tauri-apps/tauri
1
1
Fork 0
mirror of https://github.com/tauri-apps/tauri.git synced 2024-12-01 03:02:28 +03:00
Code Issues Packages Projects Releases Wiki Activity

refactor: more consistent js-api docs (#1463)

Browse Source
This commit is contained in:
Amr Bashir 2021-04-13 03:44:50 +02:00 committed by GitHub
parent 0a5233a316
commit 186deb43d5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
14 changed files with 378 additions and 342 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
tooling/api/src/app.ts
View File

@ -5,9 +5,9 @@
import { invokeTauriCommand } from './helpers/tauri'
/**
* @name getVersion
* @description Get application version
* @returns {Promise<string>} Promise resolving to application version
* Gets the application version.
*
* @returns A promise resolving to application version.
*/
async function getVersion(): Promise<string> {
return invokeTauriCommand<string>({
@ -20,9 +20,9 @@ async function getVersion(): Promise<string> {
}
/**
* @name getName
* @description Get application name
* @returns {Promise<string>} Promise resolving to application name
* Gets the application name.
*
* @returns A promise resolving to application name.
*/
async function getName(): Promise<string> {
return invokeTauriCommand<string>({
@ -35,9 +35,9 @@ async function getName(): Promise<string> {
}
/**
* @name getTauriVersion
* @description Get tauri version
* @returns {Promise<string>} Promise resolving to tauri version
* Gets the tauri version.
*
* @returns A promise resolving to tauri version.
*/
async function getTauriVersion(): Promise<string> {
return invokeTauriCommand<string>({
@ -50,10 +50,10 @@ async function getTauriVersion(): Promise<string> {
}
/**
* @name exit
* @description Exits immediately with exitCode.
* @param [exitCode] defaults to 0.
* @returns {Promise<void>} Application is closing, nothing is returned
* Exits immediately with the given `exitCode`.
*
* @param exitCode The exit code to use
* @returns
*/
async function exit(exitCode: number = 0): Promise<void> {
return invokeTauriCommand({
@ -67,9 +67,9 @@ async function exit(exitCode: number = 0): Promise<void> {
}
/**
* @name relaunch
* @description Relaunches the app when current instance exits.
* @returns {Promise<void>} Application is restarting, nothing is returned
* Exits the current instance of the app then relaunches it.
*
* @returns
*/
async function relaunch(): Promise<void> {
return invokeTauriCommand({

6
tooling/api/src/cli.ts
View File

@ -12,7 +12,7 @@ export interface ArgMatch {
*/
value: string | boolean | string[] | null
/**
* number of occurrences
* Number of occurrences
*/
occurrences: number
}
@ -28,7 +28,9 @@ export interface CliMatches {
}
/**
* gets the CLI matches
* Gets the CLI matches.
*
* @returns A promise resolving to cli matches.
*/
async function getMatches(): Promise<CliMatches> {
return invokeTauriCommand<CliMatches>({

20
tooling/api/src/dialog.ts
View File

@ -22,14 +22,9 @@ export interface SaveDialogOptions {
}
/**
* @name openDialog
* @description Open a file/directory selection dialog
* @param {Object} [options]
* @param {string} [options.filter]
* @param {string} [options.defaultPath]
* @param {boolean} [options.multiple=false]
* @param {boolean} [options.directory=false]
* @returns {Promise<string | string[]>} Promise resolving to the select path(s)
* Open a file/directory selection dialog
*
* @returns A promise resolving to the selected path(s)
*/
async function open(
options: OpenDialogOptions = {}
@ -49,12 +44,9 @@ async function open(
}
/**
* @name save
* @description Open a file/directory save dialog
* @param {Object} [options]
* @param {string} [options.filter]
* @param {string} [options.defaultPath]
* @returns {Promise<string>} Promise resolving to the select path
* Open a file/directory save dialog.
*
* @returns A promise resolving to the selected path.
*/
async function save(options: SaveDialogOptions = {}): Promise<string> {
if (typeof options === 'object') {

82
tooling/api/src/event.ts
View File

@ -2,11 +2,89 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-License-Identifier: MIT
import { invokeTauriCommand } from './helpers/tauri'
import { emit as emitEvent } from './helpers/event'
import { transformCallback } from './tauri'
export interface Event<T> {
/** Event name */
event: string
/** Event identifier used to unlisten */
id: number
/** Event payload */
payload: T
}
export type EventCallback<T> = (event: Event<T>) => void
export type UnlistenFn = () => void
/**
* Unregister the event listener associated with the given id.
*
* @ignore
* @param eventId Event identifier
* @returns
*/
async function _unlisten(eventId: number): Promise<void> {
return invokeTauriCommand({
__tauriModule: 'Event',
message: {
cmd: 'unlisten',
eventId
}
})
}
/**
* Listen to an event from the backend.
*
* @param event Event name
* @param handler Event handler callback
* @return A promise resolving to a function to unlisten to the event.
*/
async function listen<T>(
event: string,
handler: EventCallback<T>
): Promise<UnlistenFn> {
return invokeTauriCommand<number>({
__tauriModule: 'Event',
message: {
cmd: 'listen',
event,
handler: transformCallback(handler)
}
}).then((eventId) => {
return async () => _unlisten(eventId)
})
}
/**
* Listen to an one-off event from the backend.
*
* @param event Event name
* @param handler Event handler callback
* @returns A promise resolving to a function to unlisten to the event.
*/
async function once<T>(
event: string,
handler: EventCallback<T>
): Promise<UnlistenFn> {
return listen<T>(event, (eventData) => {
handler(eventData)
_unlisten(eventData.id).catch(() => {})
})
}
/**
* Emits an event to the backend.
*
* @param event Event name
* @param [payload] Event payload
* @returns
*/
async function emit(event: string, payload?: string): Promise<void> {
return emitEvent(event, undefined, payload)
}
export { listen, once } from './helpers/event'
export { emit }
export { listen, once, emit }

123
tooling/api/src/fs.ts
View File

@ -47,20 +47,21 @@ export interface FsBinaryFileOption {
export interface FileEntry {
path: string
// name of the directory/file
// can be null if the path terminates with `..`
/**
* Name of the directory/file
* can be null if the path terminates with `..`
*/
name?: string
// children of this entry if it's a directory; null otherwise
/** Children of this entry if it's a directory; null otherwise */
children?: FileEntry[]
}
/**
* @name readTextFile
* @description Reads a file as text
* @param {string} filePath path to the file
* @param {FsOptions} [options] configuration object
* @param {BaseDirectory} [options.dir] base directory
* @return {Promise<string>}
* Reads a file as text.
*
* @param filePath Path to the file
* @param [options]
* @returns A promise resolving to a string of the file content.
*/
async function readTextFile(
filePath: string,
@ -77,12 +78,11 @@ async function readTextFile(
}
/**
* @name readBinaryFile
* @description Reads a file as binary
* @param {string} filePath path to the file
* @param {FsOptions} [options] configuration object
* @param {BaseDirectory} [options.dir] base directory
* @return {Promise<number[]>}
* Reads a file as binary.
*
* @param filePath Path to the file
* @param [options]
* @returns A promise resolving to an array of the file bytes.
*/
async function readBinaryFile(
filePath: string,
@ -99,14 +99,11 @@ async function readBinaryFile(
}
/**
* writes a text file
* Writes a text file.
*
* @param file
* @param file.path path of the file
* @param file.contents contents of the file
* @param [options] configuration object
* @param [options.dir] base directory
* @return
* @param file File configuration object
* @param [options]
* @returns
*/
async function writeFile(
file: FsTextFileOption,
@ -133,10 +130,10 @@ async function writeFile(
const CHUNK_SIZE = 65536
/**
* convert an Uint8Array to ascii string
* Convert an Uint8Array to ascii string.
*
* @param arr
* @return ASCII string
* @returns An ASCII string.
*/
function uint8ArrayToString(arr: Uint8Array): string {
if (arr.length < CHUNK_SIZE) {
@ -153,10 +150,10 @@ function uint8ArrayToString(arr: Uint8Array): string {
}
/**
* convert an ArrayBuffer to base64 encoded string
* Convert an ArrayBuffer to base64 encoded string.
*
* @param buffer
* @return base64 encoded string
* @returns A base64 encoded string.
*/
function arrayBufferToBase64(buffer: ArrayBuffer): string {
const str = uint8ArrayToString(new Uint8Array(buffer))
@ -164,14 +161,11 @@ function arrayBufferToBase64(buffer: ArrayBuffer): string {
}
/**
* writes a binary file
* Writes a binary file
*
* @param file
* @param file.path path of the file
* @param file.contents contents of the file
* @param [options] configuration object
* @param [options.dir] base directory
* @return
* @param file File configuration object
* @param [options]
* @returns
*/
async function writeBinaryFile(
file: FsBinaryFileOption,
@ -196,13 +190,11 @@ async function writeBinaryFile(
}
/**
* list directory files
* List directory files.
*
* @param dir path to the directory to read
* @param [options] configuration object
* @param [options.recursive] whether to list dirs recursively or not
* @param [options.dir] base directory
* @return
* @param dir Path to the directory to read
* @param [options] Configuration object
* @returns
*/
async function readDir(
dir: string,
@ -219,15 +211,13 @@ async function readDir(
}
/**
* Creates a directory
* Creates a directory.
* If one of the path's parent components doesn't exist
* and the `recursive` option isn't set to true, it will be rejected
* and the `recursive` option isn't set to true, it will be rejected.
*
* @param dir path to the directory to create
* @param [options] configuration object
* @param [options.recursive] whether to create the directory's parent components or not
* @param [options.dir] base directory
* @return
* @param dir Path to the directory to create
* @param [options] Configuration object
* @returns
*/
async function createDir(
dir: string,
@ -244,14 +234,12 @@ async function createDir(
}
/**
* Removes a directory
* If the directory is not empty and the `recursive` option isn't set to true, it will be rejected
* Removes a directory.
* If the directory is not empty and the `recursive` option isn't set to true, it will be rejected.
*
* @param dir path to the directory to remove
* @param [options] configuration object
* @param [options.recursive] whether to remove all of the directory's content or not
* @param [options.dir] base directory
* @return
* @param dir Path to the directory to remove
* @param [options] Configuration object
* @returns
*/
async function removeDir(
dir: string,
@ -268,13 +256,12 @@ async function removeDir(
}
/**
* Copy file
* Copys a file to a destination.
*
* @param source
* @param destination
* @param [options] configuration object
* @param [options.dir] base directory
* @return
* @param source A path of the file to copy
* @param destination A path for the destination file
* @param [options] Configuration object
* @returns
*/
async function copyFile(
source: string,
@ -293,12 +280,11 @@ async function copyFile(
}
/**
* Removes a file
* Removes a file.
*
* @param file path to the file to remove
* @param [options] configuration object
* @param [options.dir] base directory
* @return
* @param file Path to the file to remove
* @param [options] Configuration object
* @returns
*/
async function removeFile(
file: string,
@ -317,11 +303,10 @@ async function removeFile(
/**
* Renames a file
*
* @param oldPath
* @param newPath
* @param [options] configuration object
* @param [options.dir] base directory
* @return
* @param oldPath A path of the file to rename
* @param newPath A path of the new file name
* @param [options] Configuration object
* @returns
*/
async function renameFile(
oldPath: string,

32
tooling/api/src/globalShortcut.ts
View File

@ -5,14 +5,18 @@
import { invokeTauriCommand } from './helpers/tauri'
import { transformCallback } from './tauri'
export type ShortcutHandler = (shortcut: string) => void
/**
* Register a global shortcut
* @param shortcut shortcut definition, modifiers and key separated by "+" e.g. CmdOrControl+Q
* @param handler shortcut handler callback - takes the triggered shortcut as argument
* Register a global shortcut.
*
* @param shortcut Shortcut definition, modifiers and key separated by "+" e.g. CmdOrControl+Q
* @param handler Shortcut handler callback - takes the triggered shortcut as argument
* @returns
*/
async function register(
shortcut: string,
handler: (shortcut: string) => void
handler: ShortcutHandler
): Promise<void> {
return invokeTauriCommand({
__tauriModule: 'GlobalShortcut',
@ -25,13 +29,15 @@ async function register(
}
/**
* Register a collection of global shortcuts
* @param shortcuts array of shortcut definitions, modifiers and key separated by "+" e.g. CmdOrControl+Q
* @param handler shortcut handler callback - takes the triggered shortcut as argument
* Register a collection of global shortcuts.
*
* @param shortcuts Array of shortcut definitions, modifiers and key separated by "+" e.g. CmdOrControl+Q
* @param handler Shortcut handler callback - takes the triggered shortcut as argument
* @returns
*/
async function registerAll(
shortcuts: string[],
handler: (shortcut: string) => void
handler: ShortcutHandler
): Promise<void> {
return invokeTauriCommand({
__tauriModule: 'GlobalShortcut',
@ -46,8 +52,8 @@ async function registerAll(
/**
* Determines whether the given shortcut is registered by this application or not.
*
* @param shortcuts array of shortcut definitions, modifiers and key separated by "+" e.g. CmdOrControl+Q
* @return {Promise<boolean>} promise resolving to the state
* @param shortcut Array of shortcut definitions, modifiers and key separated by "+" e.g. CmdOrControl+Q
* @returns A promise resolving to the state.
*/
async function isRegistered(shortcut: string): Promise<boolean> {
return invokeTauriCommand({
@ -60,8 +66,10 @@ async function isRegistered(shortcut: string): Promise<boolean> {
}
/**
* Unregister a global shortcut
* Unregister a global shortcut.
*
* @param shortcut shortcut definition, modifiers and key separated by "+" e.g. CmdOrControl+Q
* @returns
*/
async function unregister(shortcut: string): Promise<void> {
return invokeTauriCommand({
@ -75,6 +83,8 @@ async function unregister(shortcut: string): Promise<void> {
/**
* Unregisters all shortcuts registered by the application.
*
* @returns
*/
async function unregisterAll(): Promise<void> {
return invokeTauriCommand({

89
tooling/api/src/helpers/event.ts
View File

@ -1,89 +1,12 @@
// Copyright 2019-2021 Tauri Programme within The Commons Conservancy
// SPDX-License-Identifier: Apache-2.0
// SPDX-License-Identifier: MIT
import { invokeTauriCommand } from './tauri'
import { transformCallback } from '../tauri'
export interface Event<T> {
/// event name.
event: string
/// event identifier used to unlisten.
id: number
/// event payload.
payload: T
}
export type EventCallback<T> = (event: Event<T>) => void
export type UnlistenFn = () => void
async function _listen<T>(
event: string,
handler: EventCallback<T>
): Promise<UnlistenFn> {
return invokeTauriCommand<number>({
__tauriModule: 'Event',
message: {
cmd: 'listen',
event,
handler: transformCallback(handler)
}
}).then((eventId) => {
return async () => _unlisten(eventId)
})
}
/**
* Unregister the event listener associated with the given id.
* Emits an event to the backend.
*
* @param {number} eventId the event identifier
*/
async function _unlisten(eventId: number): Promise<void> {
return invokeTauriCommand({
__tauriModule: 'Event',
message: {
cmd: 'unlisten',
eventId
}
})
}
/**
* listen to an event from the backend
*
* @param event the event name
* @param handler the event handler callback
* @return {Promise<UnlistenFn>} a promise resolving to a function to unlisten to the event.
*/
async function listen<T>(
event: string,
handler: EventCallback<T>
): Promise<UnlistenFn> {
return _listen(event, handler)
}
/**
* listen to an one-off event from the backend
*
* @param event the event name
* @param handler the event handler callback
*/
async function once<T>(
event: string,
handler: EventCallback<T>
): Promise<UnlistenFn> {
return _listen<T>(event, (eventData) => {
handler(eventData)
_unlisten(eventData.id).catch(() => {})
})
}
/**
* emits an event to the backend
*
* @param event the event name
* @param [payload] the event payload
* @param event Event name
* @param [windowLabel] The label of the window to which the event is sent, if null/undefined the event will be sent to all windows
* @param [payload] Event payload
* @returns
*/
async function emit(
event: string,
@ -101,4 +24,4 @@ async function emit(
})
}
export { listen, once, emit }
export { emit }

60
tooling/api/src/http.ts
View File

@ -81,7 +81,9 @@ export class Client {
}
/**
* drops the client instance
* Drops the client instance.
*
* @returns
*/
async drop(): Promise<void> {
return invokeTauriCommand({
@ -94,11 +96,10 @@ export class Client {
}
/**
* makes a HTTP request
* Makes a HTTP request.
*
* @param options request options
*
* @return promise resolving to the response
* @param options Request options
* @returns A promise resolving to the response.
*/
async request<T>(options: HttpOptions): Promise<Response<T>> {
return invokeTauriCommand({
@ -112,12 +113,11 @@ export class Client {
}
/**
* makes a GET request
* Makes a GET request.
*
* @param url request URL
* @param options request options
*
* @return promise resolving to the response
* @param url Request URL
* @param [options] Request options
* @returns A promise resolving to the response.
*/
async get<T>(url: string, options?: RequestOptions): Promise<Response<T>> {
return this.request({
@ -128,13 +128,12 @@ export class Client {
}
/**
* makes a POST request
* Makes a POST request.
*
* @param url request URL
* @param body request body
* @param options request options
*
* @return promise resolving to the response
* @param url Request URL
* @param [body] Request body
* @param [options] Request options
* @returns A promise resolving to the response.
*/
async post<T>(
url: string,
@ -150,13 +149,12 @@ export class Client {
}
/**
* makes a PUT request
* Makes a PUT request.
*
* @param url request URL
* @param body request body
* @param options request options
*
* @return promise resolving to the response
* @param url Request URL
* @param [body] Request body
* @param [options] Request options
* @returns A promise resolving to the response.
*/
async put<T>(
url: string,
@ -172,12 +170,11 @@ export class Client {
}
/**
* makes a PATCH request
* Makes a PATCH request.
*
* @param url request URL
* @param options request options
*
* @return promise resolving to the response
* @param url Request URL
* @param options Request options
* @returns A promise resolving to the response.
*/
async patch<T>(url: string, options?: RequestOptions): Promise<Response<T>> {
return this.request({
@ -188,12 +185,11 @@ export class Client {
}
/**
* makes a DELETE request
* Makes a DELETE request.
*
* @param url request URL
* @param options request options
*
* @return promise resolving to the response
* @param url Request URL
* @param options Request options
* @returns A promise resolving to the response.
*/
async delete<T>(url: string, options?: RequestOptions): Promise<Response<T>> {
return this.request({

16
tooling/api/src/notification.ts
View File

@ -13,6 +13,11 @@ export interface Options {
export type PartialOptions = Omit<Options, 'title'>
export type Permission = 'granted' | 'denied' | 'default'
/**
* Checks if the permission to send notifications is granted.
*
* @returns
*/
async function isPermissionGranted(): Promise<boolean | null> {
if (window.Notification.permission !== 'default') {
return Promise.resolve(window.Notification.permission === 'granted')
@ -25,10 +30,21 @@ async function isPermissionGranted(): Promise<boolean | null> {
})
}
/**
* Requests the permission to send notifications.
*
* @returns A promise resolving to whether the user granted the permission or not.
*/
async function requestPermission(): Promise<Permission> {
return window.Notification.requestPermission()
}
/**
* Sends a notification to the user.
*
* @param options Notification options
* @returns
*/
function sendNotification(options: Options | string): void {
if (typeof options === 'string') {
// eslint-disable-next-line no-new

126
tooling/api/src/path.ts
View File

@ -6,9 +6,9 @@ import { invokeTauriCommand } from './helpers/tauri'
import { BaseDirectory } from './fs'
/**
* @name appDir
* @description Returns the path to the suggested directory for your app config files.
* @return {Promise<string>}
* Returns the path to the suggested directory for your app config files.
*
* @returns
*/
async function appDir(): Promise<string> {
return invokeTauriCommand<string>({
@ -22,9 +22,9 @@ async function appDir(): Promise<string> {
}
/**
* @name audioDir
* @description Returns the path to the user's audio directory.
* @return {Promise<string>}
* Returns the path to the user's audio directory.
*
* @returns
*/
async function audioDir(): Promise<string> {
return invokeTauriCommand<string>({
@ -38,9 +38,9 @@ async function audioDir(): Promise<string> {
}
/**
* @name cacheDir
* @description Returns the path to the user's cache directory.
* @return {Promise<string>}
* Returns the path to the user's cache directory.
*
* @returns
*/
async function cacheDir(): Promise<string> {
return invokeTauriCommand<string>({
@ -54,9 +54,9 @@ async function cacheDir(): Promise<string> {
}
/**
* @name configDir
* @description Returns the path to the user's config directory.
* @return {Promise<string>}
* Returns the path to the user's config directory.
*
* @returns
*/
async function configDir(): Promise<string> {
return invokeTauriCommand<string>({
@ -70,9 +70,9 @@ async function configDir(): Promise<string> {
}
/**
* @name dataDir
* @description Returns the path to the user's data directory.
* @return {Promise<string>}
* Returns the path to the user's data directory.
*
* @returns
*/
async function dataDir(): Promise<string> {
return invokeTauriCommand<string>({
@ -86,9 +86,9 @@ async function dataDir(): Promise<string> {
}
/**
* @name desktopDir
* @description Returns the path to the user's desktop directory.
* @return {Promise<string>}
* Returns the path to the user's desktop directory.
* @returns
*/
async function desktopDir(): Promise<string> {
return invokeTauriCommand<string>({
@ -102,9 +102,9 @@ async function desktopDir(): Promise<string> {
}
/**
* @name documentDir
* @description Returns the path to the user's document directory.
* @return {Promise<string>}
* Returns the path to the user's document directory.
*
* @returns
*/
async function documentDir(): Promise<string> {
return invokeTauriCommand<string>({
@ -118,9 +118,9 @@ async function documentDir(): Promise<string> {
}
/**
* @name downloadDir
* @description Returns the path to the user's download directory.
* @return {Promise<string>}
* Returns the path to the user's download directory.
*
* @returns
*/
async function downloadDir(): Promise<string> {
return invokeTauriCommand<string>({
@ -134,9 +134,9 @@ async function downloadDir(): Promise<string> {
}
/**
* @name executableDir
* @description Returns the path to the user's executable directory.
* @return {Promise<string>}
* Returns the path to the user's executable directory.
*
* @returns
*/
async function executableDir(): Promise<string> {
return invokeTauriCommand<string>({
@ -150,9 +150,9 @@ async function executableDir(): Promise<string> {
}
/**
* @name fontDir
* @description Returns the path to the user's font directory.
* @return {Promise<string>}
* Returns the path to the user's font directory.
*
* @returns
*/
async function fontDir(): Promise<string> {
return invokeTauriCommand<string>({
@ -166,9 +166,9 @@ async function fontDir(): Promise<string> {
}
/**
* @name homeDir
* @description Returns the path to the user's home directory.
* @return {Promise<string>}
* Returns the path to the user's home directory.
*
* @returns
*/
async function homeDir(): Promise<string> {
return invokeTauriCommand<string>({
@ -182,9 +182,9 @@ async function homeDir(): Promise<string> {
}
/**
* @name localDataDir
* @description Returns the path to the user's local data directory.
* @return {Promise<string>}
* Returns the path to the user's local data directory.
*
* @returns
*/
async function localDataDir(): Promise<string> {
return invokeTauriCommand<string>({
@ -198,9 +198,9 @@ async function localDataDir(): Promise<string> {
}
/**
* @name pictureDir
* @description Returns the path to the user's picture directory.
* @return {Promise<string>}
* Returns the path to the user's picture directory.
*
* @returns
*/
async function pictureDir(): Promise<string> {
return invokeTauriCommand<string>({
@ -214,9 +214,9 @@ async function pictureDir(): Promise<string> {
}
/**
* @name publicDir
* @description Returns the path to the user's public directory.
* @return {Promise<string>}
* Returns the path to the user's public directory.
*
* @returns
*/
async function publicDir(): Promise<string> {
return invokeTauriCommand<string>({
@ -230,9 +230,9 @@ async function publicDir(): Promise<string> {
}
/**
* @name resourceDir
* @description Returns the path to the user's resource directory.
* @return {Promise<string>}
* Returns the path to the user's resource directory.
*
* @returns
*/
async function resourceDir(): Promise<string> {
return invokeTauriCommand<string>({
@ -246,9 +246,9 @@ async function resourceDir(): Promise<string> {
}
/**
* @name runtimeDir
* @descriptionReturns Returns the path to the user's runtime directory.
* @return {Promise<string>}
* Returns the path to the user's runtime directory.
*
* @returns
*/
async function runtimeDir(): Promise<string> {
return invokeTauriCommand<string>({
@ -262,9 +262,9 @@ async function runtimeDir(): Promise<string> {
}
/**
* @name templateDir
* @descriptionReturns Returns the path to the user's template directory.
* @return {Promise<string>}
* Returns the path to the user's template directory.
*
* @returns
*/
async function templateDir(): Promise<string> {
return invokeTauriCommand<string>({
@ -278,9 +278,9 @@ async function templateDir(): Promise<string> {
}
/**
* @name videoDir
* @descriptionReturns Returns the path to the user's video dir.
* @return {Promise<string>}
* Returns the path to the user's video directory.
*
* @returns
*/
async function videoDir(): Promise<string> {
return invokeTauriCommand<string>({
@ -294,9 +294,9 @@ async function videoDir(): Promise<string> {
}
/**
* @name currentDir
* @descriptionReturns Returns the path to the current working dir.
* @return {Promise<string>}
* Returns the path to the current working directory.
*
* @returns
*/
async function currentDir(): Promise<string> {
return invokeTauriCommand<string>({
@ -310,11 +310,13 @@ async function currentDir(): Promise<string> {
}
/**
* @name resolvePath
* @descriptionReturns Resolves the path with the optional base directory.
* @return {Promise<string>}
* Resolves the path with the optional base directory.
*
* @param path A path to resolve
* @param directory A base directory to use when resolving the given path
* @returns A path resolved to the given base directory.
*/
async function resolvePath(
async function resolve(
path: string,
directory: BaseDirectory
): Promise<string> {
@ -348,5 +350,5 @@ export {
templateDir,
videoDir,
currentDir,
resolvePath
resolve as resolvePath
}

25
tooling/api/src/shell.ts
View File

@ -6,12 +6,13 @@ import { invokeTauriCommand } from './helpers/tauri'
import { transformCallback } from './tauri'
/**
* spawns a process
* Spawns a process.
*
* @param program the name of the program to execute e.g. 'mkdir' or 'node'
* @param sidecar whether the program is a sidecar or a system program
* @param [args] command args
* @return promise resolving to the stdout text
* @param program The name of the program to execute e.g. 'mkdir' or 'node'
* @param sidecar Whether the program is a sidecar or a system program
* @param onEvent
* @param [args] Command args
* @returns A promise resolving to the process id.
*/
async function execute(
program: string,
@ -118,11 +119,10 @@ class Command extends EventEmitter<'close' | 'error'> {
}
/**
* Creates a command to execute the given sidecar binary
* Creates a command to execute the given sidecar binary.
*
* @param {string} program Binary name
*
* @return {Command}
* @param program Binary name
* @returns
*/
static sidecar(program: string, args: string | string[] = []): Command {
const instance = new Command(program, args)
@ -195,11 +195,12 @@ type CommandEvent =
| Event<'Error', string>
/**
* opens a path or URL with the system's default app,
* or the one specified with `openWith`
* Opens a path or URL with the system's default app,
* or the one specified with `openWith`.
*
* @param path the path or URL to open
* @param openWith the app to open the file or URL with
* @param [openWith] the app to open the file or URL with
* @returns
*/
async function open(path: string, openWith?: string): Promise<void> {
return invokeTauriCommand({

8
tooling/api/src/tauri.ts
View File

@ -46,11 +46,11 @@ export interface InvokeArgs {
}
/**
* sends a message to the backend
* Sends a message to the backend.
*
* @param args
*
* @return {Promise<T>} Promise resolving or rejecting to the backend response
* @param cmd
* @param [args]
* @return A promise resolving or rejecting to the backend response.
*/
async function invoke<T>(cmd: string, args: InvokeArgs = {}): Promise<T> {
return new Promise((resolve, reject) => {

2
tooling/api/src/updater.ts
View File

@ -2,7 +2,7 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-License-Identifier: MIT
import { once, listen, emit, UnlistenFn } from './helpers/event'
import { once, listen, emit, UnlistenFn } from './event'
export type UpdateStatus = 'PENDING' | 'ERROR' | 'DONE' | 'UPTODATE'

99
tooling/api/src/window.ts
View File

@ -3,7 +3,8 @@
// SPDX-License-Identifier: MIT
import { invokeTauriCommand } from './helpers/tauri'
import { EventCallback, UnlistenFn, emit, listen, once } from './helpers/event'
import { EventCallback, UnlistenFn, listen, once } from './event'
import { emit } from './helpers/event'
interface WindowDef {
label: string
@ -40,11 +41,11 @@ class WebviewWindowHandle {
}
/**
* Listen to an event emitted by the webview
* Listen to an event emitted by the webview.
*
* @param event the event name
* @param handler the event handler callback
* @return {Promise<UnlistenFn>} a promise resolving to a function to unlisten to the event.
* @param event Event name
* @param handler Event handler callback
* @returns A promise resolving to a function to unlisten to the event.
*/
async listen<T>(
event: string,
@ -61,10 +62,11 @@ class WebviewWindowHandle {
}
/**
* Listen to an one-off event emitted by the webview
* Listen to an one-off event emitted by the webview.
*
* @param event the event name
* @param handler the event handler callback
* @param event Event name
* @param handler Event handler callback
* @returns A promise resolving to a function to unlisten to the event.
*/
async once<T>(event: string, handler: EventCallback<T>): Promise<UnlistenFn> {
if (this._handleTauriEvent(event, handler)) {
@ -78,10 +80,10 @@ class WebviewWindowHandle {
}
/**
* emits an event to the webview
* Emits an event to the webview.
*
* @param event the event name
* @param [payload] the event payload
* @param event Event name
* @param [payload] Event payload
*/
async emit(event: string, payload?: string): Promise<void> {
if (localTauriEvents.includes(event)) {
@ -129,9 +131,8 @@ class WebviewWindow extends WebviewWindowHandle {
/**
* Gets the WebviewWindow handle for the webview associated with the given label.
*
* @param {string} label the webview window label.
*
* @return {WebviewWindowHandle} the handle to communicate with the webview or null if the webview doesn't exist
* @param label The webview window label.
* @returns The handle to communicate with the webview or null if the webview doesn't exist.
*/
static getByLabel(label: string): WebviewWindowHandle | null {
if (getAll().some((w) => w.label === label)) {
@ -141,9 +142,12 @@ class WebviewWindow extends WebviewWindowHandle {
}
}
class WindowManager {
export class WindowManager {
/**
* Updates the window resizable flag.
*
* @param resizable
* @returns
*/
async setResizable(resizable: boolean): Promise<void> {
return invokeTauriCommand({
@ -156,9 +160,10 @@ class WindowManager {
}
/**
* sets the window title
* Sets the window title.
*
* @param title the new title
* @param title The new title
* @returns
*/
async setTitle(title: string): Promise<void> {
return invokeTauriCommand({
@ -172,6 +177,8 @@ class WindowManager {
/**
* Maximizes the window.
*
* @returns
*/
async maximize(): Promise<void> {
return invokeTauriCommand({
@ -184,6 +191,8 @@ class WindowManager {
/**
* Unmaximizes the window.
*
* @returns
*/
async unmaximize(): Promise<void> {
return invokeTauriCommand({
@ -196,6 +205,8 @@ class WindowManager {
/**
* Minimizes the window.
*
* @returns
*/
async minimize(): Promise<void> {
return invokeTauriCommand({
@ -208,6 +219,8 @@ class WindowManager {
/**
* Unminimizes the window.
*
* @returns
*/
async unminimize(): Promise<void> {
return invokeTauriCommand({
@ -220,6 +233,8 @@ class WindowManager {
/**
* Sets the window visibility to true.
*
* @returns
*/
async show(): Promise<void> {
return invokeTauriCommand({
@ -232,6 +247,8 @@ class WindowManager {
/**
* Sets the window visibility to false.
*
* @returns
*/
async hide(): Promise<void> {
return invokeTauriCommand({
@ -244,6 +261,8 @@ class WindowManager {
/**
* Closes the window.
*
* @returns
*/
async close(): Promise<void> {
return invokeTauriCommand({
@ -257,7 +276,8 @@ class WindowManager {
/**
* Whether the window should have borders and bars.
*
* @param {boolean} decorations whether the window should have borders and bars
* @param decorations Whether the window should have borders and bars
* @returns
*/
async setDecorations(decorations: boolean): Promise<void> {
return invokeTauriCommand({
@ -272,7 +292,8 @@ class WindowManager {
/**
* Whether the window should always be on top of other windows.
*
* @param {boolean} alwaysOnTop whether the window should always be on top of other windows or not
* @param alwaysOnTop Whether the window should always be on top of other windows or not
* @returns
*/
async setAlwaysOnTop(alwaysOnTop: boolean): Promise<void> {
return invokeTauriCommand({
@ -287,7 +308,8 @@ class WindowManager {
/**
* Sets the window width.
*
* @param {number} width the new window width
* @param width The new window width
* @returns
*/
async setWidth(width: number): Promise<void> {
return invokeTauriCommand({
@ -302,7 +324,8 @@ class WindowManager {
/**
* Sets the window height.
*
* @param {number} height the new window height
* @param height The new window height
* @returns
*/
async setHeight(height: number): Promise<void> {
return invokeTauriCommand({
@ -317,8 +340,9 @@ class WindowManager {
/**
* Resizes the window.
*
* @param {number} width the new window width
* @param {number} height the new window height
* @param width The new window width
* @param height The new window height
* @returns
*/
async resize(width: number, height: number): Promise<void> {
return invokeTauriCommand({
@ -334,8 +358,9 @@ class WindowManager {
/**
* Sets the window min size.
*
* @param {number} minWidth the new window min width
* @param {number} minHeight the new window min height
* @param minWidth The new window min width
* @param minHeight The new window min height
* @returns
*/
async setMinSize(minWidth: number, minHeight: number): Promise<void> {
return invokeTauriCommand({
@ -351,8 +376,9 @@ class WindowManager {
/**
* Sets the window max size.
*
* @param {number} maxWidth the new window max width
* @param {number} maxHeight the new window max height
* @param maxWidth The new window max width
* @param maxHeight The new window max height
* @returns
*/
async setMaxSize(maxWidth: number, maxHeight: number): Promise<void> {
return invokeTauriCommand({
@ -368,7 +394,8 @@ class WindowManager {
/**
* Sets the window x position.
*
* @param {number} x the new window x position
* @param x The new window x position
* @returns
*/
async setX(x: number): Promise<void> {
return invokeTauriCommand({
@ -383,7 +410,8 @@ class WindowManager {
/**
* Sets the window y position.
*
* @param {number} y the new window y position
* @param y The new window y position
* @returns
*/
async setY(y: number): Promise<void> {
return invokeTauriCommand({
@ -398,8 +426,9 @@ class WindowManager {
/**
* Sets the window position.
*
* @param {number} x the new window x position
* @param {number} y the new window y position
* @param x The new window x position
* @param y The new window y position
* @returns
*/
async setPosition(x: number, y: number): Promise<void> {
return invokeTauriCommand({
@ -415,7 +444,8 @@ class WindowManager {
/**
* Sets the window fullscreen state.
*
* @param {boolean} fullscreen whether the window should go to fullscreen or not
* @param fullscreen Whether the window should go to fullscreen or not
* @returns
*/
async setFullscreen(fullscreen: boolean): Promise<void> {
return invokeTauriCommand({
@ -428,9 +458,10 @@ class WindowManager {
}
/**
* Sets the window icon
* Sets the window icon.
*
* @param {string | number[]} icon icon bytes or path to the icon file
* @param icon Icon bytes or path to the icon file
* @returns
*/
async setIcon(icon: 'string' | number[]): Promise<void> {
return invokeTauriCommand({