@augment-vir/node
Version:
A collection of augments, helpers types, functions, and classes only for Node.js (backend) JavaScript environments.
191 lines (190 loc) • 8 kB
TypeScript
import { type Logger } from '@augment-vir/common';
import { type MaybePromise, type PartialWithUndefined } from '@augment-vir/core';
import { type ChildProcess } from 'node:child_process';
import { ListenTarget } from 'typed-event-target';
/**
* All output from {@link runShellCommand}.
*
* @category Node : Terminal : Util
* @category Package : @augment-vir/node
* @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
*/
export type ShellOutput = {
error: undefined | Error;
stderr: string;
stdout: string;
exitCode: number | undefined;
exitSignal: NodeJS.Signals | undefined;
};
declare const ShellStdoutEvent_base: (new (eventInitDict: {
bubbles?: boolean;
cancelable?: boolean;
composed?: boolean;
detail: string | Buffer<ArrayBufferLike>;
}) => import("typed-event-target").TypedCustomEvent<string | Buffer<ArrayBufferLike>, "shell-stdout">) & Pick<{
new (type: string, eventInitDict?: EventInit): Event;
prototype: Event;
readonly NONE: 0;
readonly CAPTURING_PHASE: 1;
readonly AT_TARGET: 2;
readonly BUBBLING_PHASE: 3;
}, "prototype" | "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE"> & Pick<import("typed-event-target").TypedCustomEvent<string | Buffer<ArrayBufferLike>, "shell-stdout">, "type">;
/**
* An event that indicates that the shell command just wrote to stdout.
*
* @category Node : Terminal : Util
* @category Package : @augment-vir/node
* @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
*/
export declare class ShellStdoutEvent extends ShellStdoutEvent_base {
}
declare const ShellStderrEvent_base: (new (eventInitDict: {
bubbles?: boolean;
cancelable?: boolean;
composed?: boolean;
detail: string | Buffer<ArrayBufferLike>;
}) => import("typed-event-target").TypedCustomEvent<string | Buffer<ArrayBufferLike>, "shell-stderr">) & Pick<{
new (type: string, eventInitDict?: EventInit): Event;
prototype: Event;
readonly NONE: 0;
readonly CAPTURING_PHASE: 1;
readonly AT_TARGET: 2;
readonly BUBBLING_PHASE: 3;
}, "prototype" | "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE"> & Pick<import("typed-event-target").TypedCustomEvent<string | Buffer<ArrayBufferLike>, "shell-stderr">, "type">;
/**
* An event that indicates that the shell command just wrote to stderr.
*
* @category Node : Terminal : Util
* @category Package : @augment-vir/node
* @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
*/
export declare class ShellStderrEvent extends ShellStderrEvent_base {
}
declare const ShellDoneEvent_base: (new (eventInitDict: {
bubbles?: boolean;
cancelable?: boolean;
composed?: boolean;
detail: {
exitCode: number | undefined;
exitSignal: NodeJS.Signals | undefined;
};
}) => import("typed-event-target").TypedCustomEvent<{
exitCode: number | undefined;
exitSignal: NodeJS.Signals | undefined;
}, "shell-done">) & Pick<{
new (type: string, eventInitDict?: EventInit): Event;
prototype: Event;
readonly NONE: 0;
readonly CAPTURING_PHASE: 1;
readonly AT_TARGET: 2;
readonly BUBBLING_PHASE: 3;
}, "prototype" | "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE"> & Pick<import("typed-event-target").TypedCustomEvent<{
exitCode: number | undefined;
exitSignal: NodeJS.Signals | undefined;
}, "shell-done">, "type">;
/**
* An event that indicates that the shell command is finished. This contains an exit code or an exit
* signal. Based on the Node.js documentation, either one or the other is defined, never both at the
* same time.
*
* @category Node : Terminal : Util
* @category Package : @augment-vir/node
* @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
*/
export declare class ShellDoneEvent extends ShellDoneEvent_base {
}
declare const ShellErrorEvent_base: (new (eventInitDict: {
bubbles?: boolean;
cancelable?: boolean;
composed?: boolean;
detail: Error;
}) => import("typed-event-target").TypedCustomEvent<Error, "shell-error">) & Pick<{
new (type: string, eventInitDict?: EventInit): Event;
prototype: Event;
readonly NONE: 0;
readonly CAPTURING_PHASE: 1;
readonly AT_TARGET: 2;
readonly BUBBLING_PHASE: 3;
}, "prototype" | "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE"> & Pick<import("typed-event-target").TypedCustomEvent<Error, "shell-error">, "type">;
/**
* An event that indicates that the shell command errored.
*
* @category Node : Terminal : Util
* @category Package : @augment-vir/node
* @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
*/
export declare class ShellErrorEvent extends ShellErrorEvent_base {
}
/**
* A shell command listen target that emits events.
*
* @category Node : Terminal : Util
* @category Package : @augment-vir/node
* @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
*/
export declare class ShellTarget extends ListenTarget<ShellStdoutEvent | ShellStderrEvent | ShellDoneEvent | ShellErrorEvent> {
readonly childProcess: ChildProcess;
constructor(childProcess: ChildProcess);
}
/**
* Runs a shell command and returns a {@link ShellTarget} instance for directly hooking into shell
* events. This allows instant reactions to shell events but in a less convenient API compared to
* {@link runShellCommand}.
*
* @category Node : Terminal
* @category Package : @augment-vir/node
* @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
* @see
* - {@link runShellCommand}: a higher level and more succinct way of running a shell command.
*/
export declare function streamShellCommand(command: string, cwd?: string, shell?: string, env?: NodeJS.ProcessEnv, hookUpToConsole?: boolean): ShellTarget;
/**
* Options for {@link runShellCommand}.
*
* @category Node : Terminal : Util
* @category Package : @augment-vir/node
* @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
*/
export type RunShellCommandOptions = {
cwd?: string | undefined;
env?: NodeJS.ProcessEnv | undefined;
shell?: string | undefined;
/** Automatically hook up stdout and stderr printing to the caller's console methods. */
hookUpToConsole?: boolean | undefined;
rejectOnError?: boolean | undefined;
/** Callback to call whenever the shell logs to stdout. */
stdoutCallback?: (stdout: string, childProcess: ChildProcess) => MaybePromise<void> | undefined;
/** Callback to call whenever the shell logs to stderr. */
stderrCallback?: (stderr: string, childProcess: ChildProcess) => MaybePromise<void> | undefined;
};
/**
* Runs a shell command and returns its output.
*
* @category Node : Terminal
* @category Package : @augment-vir/node
* @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
* @see
* - {@link streamShellCommand}: a lower level way of running a shell command that allows instant reactions to shell events.
*/
export declare function runShellCommand(command: string, options?: RunShellCommandOptions): Promise<ShellOutput>;
/**
* Options for {@link logShellOutput}.
*
* @category Node : Terminal : Util
* @category Package : @augment-vir/node
* @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
*/
export type LogShellOutputOptions = PartialWithUndefined<{
logger: Logger;
withLabels: boolean;
ignoreError: boolean;
}>;
/**
* Log the output of running a shell command. This is useful for quick debugging of shell commands.
*
* @category Node : Terminal : Util
* @category Package : @augment-vir/node
* @package [`@augment-vir/node`](https://www.npmjs.com/package/@augment-vir/node)
*/
export declare function logShellOutput(shellOutput: PartialWithUndefined<Omit<ShellOutput, 'exitSignal'>>, { ignoreError, logger, withLabels, }?: LogShellOutputOptions): void;
export {};