From 1574328fd60970ad743ea67d301499a3da2c7e28 Mon Sep 17 00:00:00 2001 From: Ani Betts Date: Wed, 27 Nov 2024 15:48:40 +0100 Subject: [PATCH] Fix up the README --- README.md | 141 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 89 insertions(+), 52 deletions(-) diff --git a/README.md b/README.md index a110756..386a70d 100644 --- a/README.md +++ b/README.md @@ -73,7 +73,8 @@ let result = await spawnPromise('uuid'); Jobber is a Windows executable that will execute a command in a process group, and if signaled via a named pipe, will terminate that process group. It's used -in the implementation of `spawnDetached`. +in the implementation of `spawnDetached`. Jobber was written by me, and its license +is the same as `spawn-rx`, it is not a third-party dependency. ## Spawn output @@ -81,25 +82,25 @@ By default spawn will merge stdout and stderr into the returned observable. You can exclude one or the other by passing `ignore` in the `stdio` option of spawn. Alternatively if you call it with `{ split: true }` option, the observable output - will be an object `{ source: 'stdout', text: '...' }` so you can distinguish - the outputs. +will be an object `{ source: 'stdout', text: '...' }` so you can distinguish +the outputs. ## Stdin support -If you provide an `observable` in `opts.stdin`, it'll be subscribed upon +If you provide an `Observable` in `opts.stdin`, it'll be subscribed upon and fed into the child process stdin. Its completion will terminate stdin stream. ## Methods -```js +```typescript /** - * Spawns a process attached as a child of the current process. - * + * Spawns a process attached as a child of the current process. + * * @param {string} exe The executable to run - * @param {Array} params The parameters to pass to the child - * @param {Object} opts Options to pass to spawn. + * @param {string[]} params The parameters to pass to the child + * @param {SpawnOptions & SpawnRxExtras} opts Options to pass to spawn. * - * @return {Observable} Returns an Observable that when subscribed + * @return {Observable} Returns an Observable that when subscribed * to, will create a child process. The * process output will be streamed to this * Observable, and if unsubscribed from, the @@ -107,20 +108,27 @@ If you provide an `observable` in `opts.stdin`, it'll be subscribed upon * process terminates with a non-zero value, * the Observable will terminate with onError. */ -function spawn(exe, params=[], opts=null) -``` +function spawn( + exe: string, + params: string[], + opts: SpawnOptions & SpawnRxExtras & { split: true } +): Observable; + +function spawn( + exe: string, + params: string[], + opts?: SpawnOptions & SpawnRxExtras & { split: false | undefined } +): Observable; -```js /** - * Spawns a process but detached from the current process. The process is put - * into its own Process Group that can be killed by unsubscribing from the - * return Observable. - * + * Spawns a process but detached from the current process. The process is put + * into its own Process Group. + * * @param {string} exe The executable to run - * @param {Array} params The parameters to pass to the child - * @param {Object} opts Options to pass to spawn. + * @param {string[]} params The parameters to pass to the child + * @param {SpawnOptions & SpawnRxExtras} opts Options to pass to spawn. * - * @return {Observable} Returns an Observable that when subscribed + * @return {Observable} Returns an Observable that when subscribed * to, will create a detached process. The * process output will be streamed to this * Observable, and if unsubscribed from, the @@ -128,60 +136,89 @@ function spawn(exe, params=[], opts=null) * process terminates with a non-zero value, * the Observable will terminate with onError. */ -function spawnDetached(exe, params, opts=null) -``` +function spawnDetached( + exe: string, + params: string[], + opts: SpawnOptions & SpawnRxExtras & { split: true } +): Observable; + +function spawnDetached( + exe: string, + params: string[], + opts?: SpawnOptions & SpawnRxExtras & { split: false | undefined } +): Observable; -```js /** * Spawns a process as a child process. - * + * * @param {string} exe The executable to run - * @param {Array} params The parameters to pass to the child - * @param {Object} opts Options to pass to spawn. + * @param {string[]} params The parameters to pass to the child + * @param {SpawnOptions & SpawnRxExtras} opts Options to pass to spawn. * - * @return {Promise} Returns an Promise that represents a child - * process. The value returned is the process - * output. If the process terminates with a - * non-zero value, the Promise will resolve with + * @return {Promise<[string, string]>} Returns a Promise that represents a child + * process. The value returned is the process + * output. If the process terminates with a + * non-zero value, the Promise will resolve with * an Error. */ -function spawnPromise(exe, params, opts=null) -``` +function spawnPromise( + exe: string, + params: string[], + opts: SpawnOptions & SpawnRxExtras & { split: true } +): Promise<[string, string]>; + +function spawnPromise( + exe: string, + params: string[], + opts?: SpawnOptions & SpawnRxExtras +): Promise; -```js /** - * Spawns a process but detached from the current process. The process is put + * Spawns a process but detached from the current process. The process is put * into its own Process Group. - * + * * @param {string} exe The executable to run - * @param {Array} params The parameters to pass to the child - * @param {Object} opts Options to pass to spawn. + * @param {string[]} params The parameters to pass to the child + * @param {SpawnOptions & SpawnRxExtras} opts Options to pass to spawn. * - * @return {Promise} Returns an Promise that represents a detached - * process. The value returned is the process - * output. If the process terminates with a - * non-zero value, the Promise will resolve with + * @return {Promise<[string, string]>} Returns a Promise that represents a detached + * process. The value returned is the process + * output. If the process terminates with a + * non-zero value, the Promise will resolve with * an Error. */ -function spawnDetachedPromise(exe, params, opts=null) -``` +function spawnDetachedPromise( + exe: string, + params: string[], + opts: SpawnOptions & SpawnRxExtras & { split: true } +): Promise<[string, string]>; + +function spawnDetachedPromise( + exe: string, + params: string[], + opts?: SpawnOptions & SpawnRxExtras +): Promise; -```js /** - * Finds the actual executable and parameters to run on Windows. This method - * mimics the POSIX behavior of being able to run scripts as executables by - * replacing the passed-in executable with the script runner, for PowerShell, + * Finds the actual executable and parameters to run on Windows. This method + * mimics the POSIX behavior of being able to run scripts as executables by + * replacing the passed-in executable with the script runner, for PowerShell, * CMD, and node scripts. * * This method also does the work of running down PATH, which spawn on Windows * also doesn't do, unlike on POSIX. - * + * * @param {string} exe The executable to run - * @param {Array} args The arguments to run + * @param {string[]} args The arguments to run * * @return {Object} The cmd and args to run * @property {string} cmd The command to pass to spawn - * @property {Array} args The arguments to pass to spawn + * @property {string[]} args The arguments to pass to spawn */ -function findActualExecutable(exe, args) -``` +function findActualExecutable( + exe: string, + args: string[] +): { + cmd: string; + args: string[]; +};