mirror of
https://github.com/tauri-apps/plugins-workspace.git
synced 2026-09-22 21:30:44 +02:00
chore: update documentation
This commit is contained in:
Lucas Nogueira
+336
-24
@@ -66,6 +66,8 @@
|
||||
import { invoke, Channel } from '@tauri-apps/api/core'
|
||||
|
||||
/**
|
||||
* Options that configure how a child process is spawned.
|
||||
*
|
||||
* @since 2.0.0
|
||||
*/
|
||||
interface SpawnOptions {
|
||||
@@ -87,6 +89,8 @@ interface InternalSpawnOptions extends SpawnOptions {
|
||||
}
|
||||
|
||||
/**
|
||||
* The output collected from a child process that ran to completion.
|
||||
*
|
||||
* @since 2.0.0
|
||||
*/
|
||||
interface ChildProcess<O extends IOPayload> {
|
||||
@@ -101,6 +105,9 @@ interface ChildProcess<O extends IOPayload> {
|
||||
}
|
||||
|
||||
/**
|
||||
* A minimal event emitter modeled after Node.js' `EventEmitter`, used by
|
||||
* {@link Command} and by its `stdout` and `stderr` streams.
|
||||
*
|
||||
* @since 2.0.0
|
||||
*/
|
||||
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||
@@ -113,6 +120,18 @@ class EventEmitter<E extends Record<string, any>> {
|
||||
/**
|
||||
* Alias for `emitter.on(eventName, listener)`.
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* import { Command } from '@tauri-apps/plugin-shell';
|
||||
* const command = Command.create('node');
|
||||
* command.addListener('error', (error) => console.error(error));
|
||||
* ```
|
||||
*
|
||||
* @param eventName The name of the event to listen to.
|
||||
* @param listener The callback invoked with the event payload.
|
||||
*
|
||||
* @returns A reference to the `EventEmitter`, so that calls can be chained.
|
||||
*
|
||||
* @since 2.0.0
|
||||
*/
|
||||
addListener<N extends keyof E>(
|
||||
@@ -125,6 +144,20 @@ class EventEmitter<E extends Record<string, any>> {
|
||||
/**
|
||||
* Alias for `emitter.off(eventName, listener)`.
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* import { Command } from '@tauri-apps/plugin-shell';
|
||||
* const command = Command.create('node');
|
||||
* const listener = (error: string) => console.error(error);
|
||||
* command.addListener('error', listener);
|
||||
* command.removeListener('error', listener);
|
||||
* ```
|
||||
*
|
||||
* @param eventName The name of the event to stop listening to.
|
||||
* @param listener The exact callback that was registered before.
|
||||
*
|
||||
* @returns A reference to the `EventEmitter`, so that calls can be chained.
|
||||
*
|
||||
* @since 2.0.0
|
||||
*/
|
||||
removeListener<N extends keyof E>(
|
||||
@@ -142,6 +175,20 @@ class EventEmitter<E extends Record<string, any>> {
|
||||
*
|
||||
* Returns a reference to the `EventEmitter`, so that calls can be chained.
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* import { Command } from '@tauri-apps/plugin-shell';
|
||||
* const command = Command.create('node');
|
||||
* command.on('close', (data) => {
|
||||
* console.log(`command finished with code ${data.code}`);
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* @param eventName The name of the event to listen to.
|
||||
* @param listener The callback invoked with the event payload.
|
||||
*
|
||||
* @returns A reference to the `EventEmitter`, so that calls can be chained.
|
||||
*
|
||||
* @since 2.0.0
|
||||
*/
|
||||
on<N extends keyof E>(
|
||||
@@ -164,6 +211,20 @@ class EventEmitter<E extends Record<string, any>> {
|
||||
*
|
||||
* Returns a reference to the `EventEmitter`, so that calls can be chained.
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* import { Command } from '@tauri-apps/plugin-shell';
|
||||
* const command = Command.create('node');
|
||||
* command.once('close', (data) => {
|
||||
* console.log(`command finished with code ${data.code}`);
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* @param eventName The name of the event to listen to once.
|
||||
* @param listener The callback invoked with the event payload.
|
||||
*
|
||||
* @returns A reference to the `EventEmitter`, so that calls can be chained.
|
||||
*
|
||||
* @since 2.0.0
|
||||
*/
|
||||
once<N extends keyof E>(
|
||||
@@ -181,6 +242,20 @@ class EventEmitter<E extends Record<string, any>> {
|
||||
* Removes the all specified listener from the listener array for the event eventName
|
||||
* Returns a reference to the `EventEmitter`, so that calls can be chained.
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* import { Command } from '@tauri-apps/plugin-shell';
|
||||
* const command = Command.create('node');
|
||||
* const listener = (error: string) => console.error(error);
|
||||
* command.on('error', listener);
|
||||
* command.off('error', listener);
|
||||
* ```
|
||||
*
|
||||
* @param eventName The name of the event to stop listening to.
|
||||
* @param listener The exact callback that was registered before.
|
||||
*
|
||||
* @returns A reference to the `EventEmitter`, so that calls can be chained.
|
||||
*
|
||||
* @since 2.0.0
|
||||
*/
|
||||
off<N extends keyof E>(
|
||||
@@ -201,6 +276,19 @@ class EventEmitter<E extends Record<string, any>> {
|
||||
*
|
||||
* Returns a reference to the `EventEmitter`, so that calls can be chained.
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* import { Command } from '@tauri-apps/plugin-shell';
|
||||
* const command = Command.create('node');
|
||||
* command.on('error', (error) => console.error(error));
|
||||
* command.removeAllListeners('error');
|
||||
* ```
|
||||
*
|
||||
* @param event The name of the event to remove the listeners of.
|
||||
* When omitted, the listeners of every event are removed.
|
||||
*
|
||||
* @returns A reference to the `EventEmitter`, so that calls can be chained.
|
||||
*
|
||||
* @since 2.0.0
|
||||
*/
|
||||
removeAllListeners<N extends keyof E>(event?: N): this {
|
||||
@@ -215,10 +303,23 @@ class EventEmitter<E extends Record<string, any>> {
|
||||
}
|
||||
|
||||
/**
|
||||
* @ignore
|
||||
* Synchronously calls each of the listeners registered for the event named`eventName`, in the order they were registered, passing the supplied arguments
|
||||
* Synchronously calls each of the listeners registered for the event named
|
||||
* `eventName`, in the order they were registered, passing the supplied arguments
|
||||
* to each.
|
||||
*
|
||||
* @ignore
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* import { EventEmitter } from '@tauri-apps/plugin-shell';
|
||||
* const emitter = new EventEmitter<{ data: string }>();
|
||||
* emitter.on('data', (line) => console.log(line));
|
||||
* emitter.emit('data', 'hello');
|
||||
* ```
|
||||
*
|
||||
* @param eventName The name of the event to emit.
|
||||
* @param arg The payload passed to every registered listener.
|
||||
*
|
||||
* @returns `true` if the event had listeners, `false` otherwise.
|
||||
*
|
||||
* @since 2.0.0
|
||||
@@ -236,6 +337,18 @@ class EventEmitter<E extends Record<string, any>> {
|
||||
/**
|
||||
* Returns the number of listeners listening to the event named `eventName`.
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* import { Command } from '@tauri-apps/plugin-shell';
|
||||
* const command = Command.create('node');
|
||||
* command.on('close', () => {});
|
||||
* console.log(command.listenerCount('close')); // 1
|
||||
* ```
|
||||
*
|
||||
* @param eventName The name of the event to count the listeners of.
|
||||
*
|
||||
* @returns The number of listeners registered for the given event.
|
||||
*
|
||||
* @since 2.0.0
|
||||
*/
|
||||
listenerCount<N extends keyof E>(eventName: N): number {
|
||||
@@ -253,6 +366,18 @@ class EventEmitter<E extends Record<string, any>> {
|
||||
*
|
||||
* Returns a reference to the `EventEmitter`, so that calls can be chained.
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* import { Command } from '@tauri-apps/plugin-shell';
|
||||
* const command = Command.create('node');
|
||||
* command.prependListener('error', (error) => console.error(error));
|
||||
* ```
|
||||
*
|
||||
* @param eventName The name of the event to listen to.
|
||||
* @param listener The callback invoked with the event payload.
|
||||
*
|
||||
* @returns A reference to the `EventEmitter`, so that calls can be chained.
|
||||
*
|
||||
* @since 2.0.0
|
||||
*/
|
||||
prependListener<N extends keyof E>(
|
||||
@@ -275,6 +400,18 @@ class EventEmitter<E extends Record<string, any>> {
|
||||
*
|
||||
* Returns a reference to the `EventEmitter`, so that calls can be chained.
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* import { Command } from '@tauri-apps/plugin-shell';
|
||||
* const command = Command.create('node');
|
||||
* command.prependOnceListener('error', (error) => console.error(error));
|
||||
* ```
|
||||
*
|
||||
* @param eventName The name of the event to listen to once.
|
||||
* @param listener The callback invoked with the event payload.
|
||||
*
|
||||
* @returns A reference to the `EventEmitter`, so that calls can be chained.
|
||||
*
|
||||
* @since 2.0.0
|
||||
*/
|
||||
prependOnceListener<N extends keyof E>(
|
||||
@@ -292,12 +429,30 @@ class EventEmitter<E extends Record<string, any>> {
|
||||
}
|
||||
|
||||
/**
|
||||
* A handle to a child process spawned with {@link Command.spawn},
|
||||
* which can be used to write to its `stdin` or to kill it.
|
||||
*
|
||||
* @since 2.0.0
|
||||
*/
|
||||
class Child {
|
||||
/** The child process `pid`. */
|
||||
pid: number
|
||||
|
||||
/**
|
||||
* Creates a handle to the child process with the given process id.
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* import { Command } from '@tauri-apps/plugin-shell';
|
||||
* // a `Child` is usually obtained by spawning a command:
|
||||
* const child = await Command.create('node').spawn();
|
||||
* console.log(child.pid);
|
||||
* ```
|
||||
*
|
||||
* @param pid The process id of the child process.
|
||||
*
|
||||
* @since 2.0.0
|
||||
*/
|
||||
constructor(pid: number) {
|
||||
this.pid = pid
|
||||
}
|
||||
@@ -329,6 +484,14 @@ class Child {
|
||||
/**
|
||||
* Kills the child process.
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* import { Command } from '@tauri-apps/plugin-shell';
|
||||
* const command = Command.create('node');
|
||||
* const child = await command.spawn();
|
||||
* await child.kill();
|
||||
* ```
|
||||
*
|
||||
* @returns A promise indicating the success or failure of the operation.
|
||||
*
|
||||
* @since 2.0.0
|
||||
@@ -341,12 +504,25 @@ class Child {
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* The events emitted by a {@link Command} instance.
|
||||
*
|
||||
* @since 2.0.0
|
||||
*/
|
||||
interface CommandEvents {
|
||||
/** Emitted when the child process terminated, carrying its exit code and signal. */
|
||||
close: TerminatedPayload
|
||||
/** Emitted when the child process could not be spawned or failed unexpectedly, carrying the error message. */
|
||||
error: string
|
||||
}
|
||||
|
||||
/**
|
||||
* The events emitted by the `stdout` and `stderr` streams of a {@link Command}.
|
||||
*
|
||||
* @since 2.0.0
|
||||
*/
|
||||
interface OutputEvents<O extends IOPayload> {
|
||||
/** Emitted for each line the process wrote to the stream, or for each raw chunk when the `raw` encoding is used. */
|
||||
data: O
|
||||
}
|
||||
|
||||
@@ -403,20 +579,9 @@ class Command<O extends IOPayload> extends EventEmitter<CommandEvents> {
|
||||
this.options = options ?? {}
|
||||
}
|
||||
|
||||
static create(program: string, args?: string | string[]): Command<string>
|
||||
static create(
|
||||
program: string,
|
||||
args?: string | string[],
|
||||
options?: SpawnOptions & { encoding: 'raw' }
|
||||
): Command<Uint8Array>
|
||||
static create(
|
||||
program: string,
|
||||
args?: string | string[],
|
||||
options?: SpawnOptions
|
||||
): Command<string>
|
||||
|
||||
/**
|
||||
* Creates a command to execute the given program.
|
||||
* Creates a command to execute the given program, decoding its output as text.
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* import { Command } from '@tauri-apps/plugin-shell';
|
||||
@@ -426,6 +591,77 @@ class Command<O extends IOPayload> extends EventEmitter<CommandEvents> {
|
||||
*
|
||||
* @param program The program to execute.
|
||||
* It must be configured in your project's capabilities.
|
||||
* @param args The arguments to pass to the program. Defaults to no arguments.
|
||||
*
|
||||
* @returns The command instance, ready to be spawned or executed.
|
||||
*
|
||||
* @since 2.0.0
|
||||
*/
|
||||
static create(program: string, args?: string | string[]): Command<string>
|
||||
/**
|
||||
* Creates a command to execute the given program, keeping its output as raw bytes.
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* import { Command } from '@tauri-apps/plugin-shell';
|
||||
* const command = Command.create('my-app', ['run', 'tauri'], { encoding: 'raw' });
|
||||
* const output = await command.execute();
|
||||
* console.log(output.stdout); // a Uint8Array
|
||||
* ```
|
||||
*
|
||||
* @param program The program to execute.
|
||||
* It must be configured in your project's capabilities.
|
||||
* @param args The arguments to pass to the program. Defaults to no arguments.
|
||||
* @param options Spawn options using the `raw` encoding, which makes the process
|
||||
* output be delivered as `Uint8Array` instead of `string`.
|
||||
*
|
||||
* @returns The command instance, ready to be spawned or executed.
|
||||
*
|
||||
* @since 2.0.0
|
||||
*/
|
||||
static create(
|
||||
program: string,
|
||||
args?: string | string[],
|
||||
options?: SpawnOptions & { encoding: 'raw' }
|
||||
): Command<Uint8Array>
|
||||
/**
|
||||
* Creates a command to execute the given program with the given spawn options.
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* import { Command } from '@tauri-apps/plugin-shell';
|
||||
* const command = Command.create('my-app', ['run', 'tauri'], { cwd: '/path/to/project' });
|
||||
* const output = await command.execute();
|
||||
* ```
|
||||
*
|
||||
* @param program The program to execute.
|
||||
* It must be configured in your project's capabilities.
|
||||
* @param args The arguments to pass to the program. Defaults to no arguments.
|
||||
* @param options Spawn options such as the working directory, the environment
|
||||
* variables and the character encoding of the process output.
|
||||
*
|
||||
* @returns The command instance, ready to be spawned or executed.
|
||||
*
|
||||
* @since 2.0.0
|
||||
*/
|
||||
static create(
|
||||
program: string,
|
||||
args?: string | string[],
|
||||
options?: SpawnOptions
|
||||
): Command<string>
|
||||
|
||||
/**
|
||||
* Creates a command to execute the given program.
|
||||
*
|
||||
* @param program The program to execute.
|
||||
* It must be configured in your project's capabilities.
|
||||
* @param args The arguments to pass to the program. Defaults to no arguments.
|
||||
* @param options Spawn options such as the working directory, the environment
|
||||
* variables and the character encoding of the process output.
|
||||
*
|
||||
* @returns The command instance, ready to be spawned or executed.
|
||||
*
|
||||
* @since 2.0.0
|
||||
*/
|
||||
static create<O extends IOPayload>(
|
||||
program: string,
|
||||
@@ -435,12 +671,74 @@ class Command<O extends IOPayload> extends EventEmitter<CommandEvents> {
|
||||
return new Command(program, args, options)
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates a command to execute the given sidecar program, decoding its output as text.
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* import { Command } from '@tauri-apps/plugin-shell';
|
||||
* const command = Command.sidecar('my-sidecar');
|
||||
* const output = await command.execute();
|
||||
* ```
|
||||
*
|
||||
* @param program The sidecar program to execute.
|
||||
* It must be configured in your project's capabilities
|
||||
* and defined on `tauri.conf.json > bundle > externalBin`.
|
||||
* @param args The arguments to pass to the program. Defaults to no arguments.
|
||||
*
|
||||
* @returns The command instance, ready to be spawned or executed.
|
||||
*
|
||||
* @since 2.0.0
|
||||
*/
|
||||
static sidecar(program: string, args?: string | string[]): Command<string>
|
||||
/**
|
||||
* Creates a command to execute the given sidecar program, keeping its output as raw bytes.
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* import { Command } from '@tauri-apps/plugin-shell';
|
||||
* const command = Command.sidecar('my-sidecar', [], { encoding: 'raw' });
|
||||
* const output = await command.execute();
|
||||
* console.log(output.stdout); // a Uint8Array
|
||||
* ```
|
||||
*
|
||||
* @param program The sidecar program to execute.
|
||||
* It must be configured in your project's capabilities
|
||||
* and defined on `tauri.conf.json > bundle > externalBin`.
|
||||
* @param args The arguments to pass to the program. Defaults to no arguments.
|
||||
* @param options Spawn options using the `raw` encoding, which makes the process
|
||||
* output be delivered as `Uint8Array` instead of `string`.
|
||||
*
|
||||
* @returns The command instance, ready to be spawned or executed.
|
||||
*
|
||||
* @since 2.0.0
|
||||
*/
|
||||
static sidecar(
|
||||
program: string,
|
||||
args?: string | string[],
|
||||
options?: SpawnOptions & { encoding: 'raw' }
|
||||
): Command<Uint8Array>
|
||||
/**
|
||||
* Creates a command to execute the given sidecar program with the given spawn options.
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* import { Command } from '@tauri-apps/plugin-shell';
|
||||
* const command = Command.sidecar('my-sidecar', [], { cwd: '/path/to/project' });
|
||||
* const output = await command.execute();
|
||||
* ```
|
||||
*
|
||||
* @param program The sidecar program to execute.
|
||||
* It must be configured in your project's capabilities
|
||||
* and defined on `tauri.conf.json > bundle > externalBin`.
|
||||
* @param args The arguments to pass to the program. Defaults to no arguments.
|
||||
* @param options Spawn options such as the working directory, the environment
|
||||
* variables and the character encoding of the process output.
|
||||
*
|
||||
* @returns The command instance, ready to be spawned or executed.
|
||||
*
|
||||
* @since 2.0.0
|
||||
*/
|
||||
static sidecar(
|
||||
program: string,
|
||||
args?: string | string[],
|
||||
@@ -449,15 +747,17 @@ class Command<O extends IOPayload> extends EventEmitter<CommandEvents> {
|
||||
|
||||
/**
|
||||
* Creates a command to execute the given sidecar program.
|
||||
* @example
|
||||
* ```typescript
|
||||
* import { Command } from '@tauri-apps/plugin-shell';
|
||||
* const command = Command.sidecar('my-sidecar');
|
||||
* const output = await command.execute();
|
||||
* ```
|
||||
*
|
||||
* @param program The program to execute.
|
||||
* It must be configured in your project's capabilities.
|
||||
* @param program The sidecar program to execute.
|
||||
* It must be configured in your project's capabilities
|
||||
* and defined on `tauri.conf.json > bundle > externalBin`.
|
||||
* @param args The arguments to pass to the program. Defaults to no arguments.
|
||||
* @param options Spawn options such as the working directory, the environment
|
||||
* variables and the character encoding of the process output.
|
||||
*
|
||||
* @returns The command instance, ready to be spawned or executed.
|
||||
*
|
||||
* @since 2.0.0
|
||||
*/
|
||||
static sidecar<O extends IOPayload>(
|
||||
program: string,
|
||||
@@ -472,6 +772,15 @@ class Command<O extends IOPayload> extends EventEmitter<CommandEvents> {
|
||||
/**
|
||||
* Executes the command as a child process, returning a handle to it.
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* import { Command } from '@tauri-apps/plugin-shell';
|
||||
* const command = Command.create('node');
|
||||
* command.stdout.on('data', (line) => console.log(line));
|
||||
* const child = await command.spawn();
|
||||
* console.log('pid:', child.pid);
|
||||
* ```
|
||||
*
|
||||
* @returns A promise resolving to the child process handle.
|
||||
*
|
||||
* @since 2.0.0
|
||||
@@ -562,7 +871,10 @@ interface TerminatedPayload {
|
||||
signal: number | null
|
||||
}
|
||||
|
||||
/** Event payload type */
|
||||
/**
|
||||
* The type of the data a child process writes to `stdout` and `stderr`:
|
||||
* a `string`, or a `Uint8Array` when the `raw` encoding is configured.
|
||||
*/
|
||||
type IOPayload = string | Uint8Array
|
||||
|
||||
/** Events emitted by the child process. */
|
||||
|
||||
Reference in New Issue
Block a user