@bleedingdev/modern-js-utils 3.9.0-ultramodern.9 → 3.9.3-ultramodern.10

package/dist/compiled/execa/index.d.ts

@@ -1,564 +1,2485 @@
-/// <reference types="node"/>
-import {ChildProcess} from 'child_process';
-import {Stream, Readable as ReadableStream} from 'stream';
-
-declare namespace execa {
-	type StdioOption =
-		| 'pipe'
-		| 'ipc'
-		| 'ignore'
-		| 'inherit'
-		| Stream
-		| number
-		| undefined;
-
-	interface CommonOptions<EncodingType> {
+import { Duplex, Readable, Writable } from 'node:stream';
+import { TransformStream, ReadableStream, WritableStream, ReadableWritablePair } from 'node:stream/web';
+import { SignalConstants } from 'node:os';
+import { ChildProcess } from 'node:child_process';
+
+type Not<Value extends boolean> = Value extends true ? false : true;
+
+type And<First extends boolean, Second extends boolean> = First extends true ? Second : false;
+
+type Unless<Condition extends boolean, ThenValue, ElseValue = never> = Condition extends true ? ElseValue : ThenValue;
+
+type AndUnless<Condition extends boolean, ThenValue, ElseValue = unknown> = Condition extends true ? ElseValue : ThenValue;
+
+// Whether any of T's union element is the same as one of U's union element.
+// `&` does not work here.
+type Intersects<T, U> = true extends (T extends U ? true : false) ? true : false;
+
+// `options.std*: Generator`
+// The `chunk` argument's type is based on the transform's mode:
+// - `binary: true` or binary `encoding`, with `objectMode: true` -> `unknown` for stdin, `Uint8Array` for stdout/stderr
+// - `binary: true` or binary `encoding` -> `Uint8Array`
+// - `objectMode: true` -> `unknown` for stdin, `string` for stdout/stderr
+// - otherwise -> `string`
+// The return type is kept as `unknown` since a transform can always yield either a `string` or an `Uint8Array`.
+// See https://github.com/sindresorhus/execa/issues/694
+type GeneratorTransform<IsSync extends boolean, Chunk = string> = (chunk: Chunk) =>
+	| Unless<IsSync, AsyncGenerator<unknown, void, void>>
+	| Generator<unknown, void, void>;
+type GeneratorTransformReturn<IsSync extends boolean> = ReturnType<GeneratorTransform<IsSync>>;
+type GeneratorFinal<IsSync extends boolean> = () =>
+	| Unless<IsSync, AsyncGenerator<unknown, void, void>>
+	| Generator<unknown, void, void>;
+
+type TransformCommon = {
+	/**
+	If `true`, allow `transformOptions.transform` and `transformOptions.final` to return any type, not just `string` or `Uint8Array`.
+	*/
+	readonly objectMode?: boolean;
+};
+
+// A `GeneratorTransformFull` shape whose `transform` narrows the `chunk` argument to `Chunk`.
+// The mode-independent documentation lives here.
+type GeneratorTransformBase<IsSync extends boolean, Chunk> = TransformCommon & {
+	/**
+	Map or filter the input or output of the subprocess.
+	*/
+	readonly transform: GeneratorTransform<IsSync, Chunk>;
+
+	/**
+	Create additional lines after the last one.
+	*/
+	readonly final?: GeneratorFinal<IsSync>;
+
+	/**
+	If `true`, iterate over arbitrary chunks of `Uint8Array`s instead of line `string`s.
+	*/
+	readonly binary?: boolean;
+
+	/**
+	If `true`, keep newlines in each `line` argument. Also, this allows multiple `yield`s to produce a single line.
+	*/
+	readonly preserveNewlines?: boolean;
+};
+
+// For stdout/stderr, this literal option pair accepts explicitly typed `Uint8Array` callbacks, matching runtime binary chunks, while still allowing stdin-style `unknown` object-mode callbacks.
+type GeneratorTransformBinaryObjectMode<IsSync extends boolean, ObjectModeChunk> = ObjectModeChunk extends string
+	? Omit<GeneratorTransformBase<IsSync, unknown>, 'transform' | 'objectMode' | 'binary'> & {
 		/**
-		Kill the spawned process when the parent process exits unless either:
-			- the spawned process is [`detached`](https://nodejs.org/api/child_process.html#child_process_options_detached)
-			- the parent process is terminated abruptly, for example, with `SIGKILL` as opposed to `SIGTERM` or a normal exit
+		Map or filter the input or output of the subprocess.
+		*/
+		transform(chunk: Uint8Array): GeneratorTransformReturn<IsSync>;
+		// eslint-disable-next-line @typescript-eslint/unified-signatures -- Combining these as `unknown | Uint8Array` would collapse to `unknown` and reject explicitly typed `Uint8Array` callbacks.
+		transform(chunk: unknown): GeneratorTransformReturn<IsSync>;
+
+		readonly objectMode: true;
+		readonly binary: true;
+	}
+	: GeneratorTransformBase<IsSync, unknown> & {readonly objectMode: true; readonly binary: true};
+
+/**
+A transform or an array of transforms can be passed to the `stdin`, `stdout`, `stderr` or `stdio` option.
+
+A transform is either a generator function or a plain object with the following members.
+*/
+type GeneratorTransformFull<IsSync extends boolean, ObjectModeChunk = unknown, TransformChunk = string> =
+	// Non-literal `binary` or `objectMode` values are accepted at runtime, but their mode is unknown at compile time.
+	| (GeneratorTransformBase<IsSync, unknown> & {readonly objectMode?: boolean; readonly binary?: boolean})
+	// `binary: true` without `objectMode` -> the `chunk` argument is an `Uint8Array`.
+	| (GeneratorTransformBase<IsSync, Uint8Array> & {readonly objectMode?: false; readonly binary: true})
+	// `binary: true` with `objectMode` -> the `chunk` argument is `unknown` for stdin, `Uint8Array` for stdout/stderr.
+	| GeneratorTransformBinaryObjectMode<IsSync, ObjectModeChunk>
+	// `binary: false` without `objectMode` -> the `chunk` argument depends on the subprocess encoding.
+	| (GeneratorTransformBase<IsSync, TransformChunk> & {readonly objectMode?: false; readonly binary?: false})
+	// `objectMode: true` with `binary: false` -> the `chunk` argument depends on the stdio direction.
+	| (GeneratorTransformBase<IsSync, ObjectModeChunk> & {readonly objectMode: true; readonly binary?: false});
+
+// `options.std*: Duplex`
+type DuplexTransform = TransformCommon & {
+	readonly transform: Duplex;
+};
+
+// `options.std*: TransformStream`
+type WebTransform = TransformCommon & {
+	readonly transform: TransformStream;
+};
+
+type IsStandardStream<FdNumber extends string> = FdNumber extends keyof StandardStreams ? true : false;
+
+type StandardStreams = readonly ['stdin', 'stdout', 'stderr'];
+
+// When `options.stdin|stdout|stderr|stdio` is set to one of those values, no stream is created
+type NoStreamStdioOption<FdNumber extends string> =
+	| 'ignore'
+	| 'inherit'
+	| number
+	| Readable
+	| Writable
+	| Unless<IsStandardStream<FdNumber>, undefined>
+	| readonly [NoStreamStdioOption<FdNumber>]
+	| {readonly value: 'inherit' | number; readonly input?: boolean};
+
+// `options.stdio` when it is not an array
+type SimpleStdioOption<
+	IsSync extends boolean,
+	IsExtra extends boolean,
+	IsArray extends boolean,
+> =
+	| undefined
+	| 'pipe'
+	| Unless<And<And<Not<IsSync>, IsArray>, IsExtra>, 'inherit'>
+	| Unless<IsArray, 'ignore'>
+	| Unless<IsSync, 'overlapped'>;
+
+// The `{value, input}` object form wraps a direction-ambiguous value and sets its direction explicitly.
+type AmbiguousStdioOption<
+	IsSync extends boolean,
+	IsExtra extends boolean,
+	IsArray extends boolean,
+	ObjectModeChunk = unknown,
+	TransformChunk = string,
+> = {
+	readonly value: AmbiguousStdioValue<IsSync, IsArray, ObjectModeChunk, TransformChunk>;
+	readonly input?: Unless<And<IsSync, IsExtra>, boolean> | false;
+};
+
+// Values whose direction is ambiguous on additional file descriptors, so they default to output unless `input` is set.
+// This excludes values with a fixed direction (readable/writable streams, iterables, standard file descriptors).
+type AmbiguousStdioValue<
+	IsSync extends boolean,
+	IsArray extends boolean,
+	ObjectModeChunk,
+	TransformChunk,
+> =
+	| 'pipe'
+	| 'inherit'
+	| Unless<IsSync, 'overlapped'>
+	| URL
+	| GeneratorTransform<IsSync, TransformChunk>
+	| GeneratorTransformFull<IsSync, ObjectModeChunk, TransformChunk>
+	| Unless<And<Not<IsSync>, IsArray>, 3 | 4 | 5 | 6 | 7 | 8 | 9>
+	| Unless<IsSync, DuplexTransform | WebTransform | TransformStream>
+	| {readonly file: string; readonly append?: boolean};
+
+// Values available in both `options.stdin|stdio` and `options.stdout|stderr|stdio`
+type CommonStdioOption<
+	IsSync extends boolean,
+	IsExtra extends boolean,
+	IsArray extends boolean,
+	ObjectModeChunk = unknown,
+	TransformChunk = string,
+> =
+	// TypeScript cannot contextually type inline full generator transform objects through this broad stdio union because the union also includes `{transform: Duplex | TransformStream}` wrapper objects. Users should annotate `chunk` when assigning an inline object directly to `StdinOption`, `StdoutStderrOption`, `Options['stdout']`, etc. Keep `GeneratorTransformFull` mode branches narrow, but do not add a broad full-object fallback here to try to recover contextual typing.
+	SimpleStdioOption<IsSync, IsExtra, IsArray> | URL | GeneratorTransform<IsSync, TransformChunk> | GeneratorTransformFull<IsSync, ObjectModeChunk, TransformChunk> | Unless<And<Not<IsSync>, IsArray>, 3 | 4 | 5 | 6 | 7 | 8 | 9> | Unless<IsSync, DuplexTransform | WebTransform | TransformStream> | AmbiguousStdioOption<IsSync, IsExtra, IsArray, ObjectModeChunk, TransformChunk> | {readonly file: string; readonly append?: boolean};
+
+// Synchronous iterables excluding strings, Uint8Arrays and Arrays
+type IterableObject<IsArray extends boolean> = Iterable<unknown>
+	& object
+	& AndUnless<IsArray, {readonly lastIndexOf?: never}>
+	& {readonly BYTES_PER_ELEMENT?: never};
+
+// `process.stdin|stdout|stderr` are `Duplex` with a `fd` property.
+// This ensures they can only be passed to `stdin`/`stdout`/`stderr`, based on their direction.
+type ProcessStdinFd = {readonly fd?: 0};
+type ProcessStdoutStderrFd = {readonly fd?: 1 | 2};
+
+// Values available only in `options.stdin|stdio`
+type InputStdioOption<
+	IsSync extends boolean = boolean,
+	IsExtra extends boolean = boolean,
+	IsArray extends boolean = boolean,
+> =
+	| 0
+	| Unless<And<IsSync, IsExtra>, Uint8Array | IterableObject<IsArray>>
+	| Unless<And<IsSync, IsArray>, Readable & ProcessStdinFd>
+	| Unless<IsSync, (AsyncIterable<unknown> & ProcessStdinFd) | ReadableStream>;
+
+// Values available only in `options.stdout|stderr|stdio`
+type OutputStdioOption<
+	IsSync extends boolean,
+	IsArray extends boolean,
+> =
+	| 1
+	| 2
+	| Unless<And<IsSync, IsArray>, Writable & ProcessStdoutStderrFd>
+	| Unless<IsSync, WritableStream>;
+
+// `options.stdin` array items
+type StdinSingleOption<
+	IsSync extends boolean,
+	IsExtra extends boolean,
+	IsArray extends boolean,
+	TransformChunk = string,
+> =
+	| CommonStdioOption<IsSync, IsExtra, IsArray, unknown, TransformChunk>
+	| InputStdioOption<IsSync, IsExtra, IsArray>;
+
+// `options.stdin`
+type StdinOptionCommon<
+	IsSync extends boolean = boolean,
+	IsExtra extends boolean = boolean,
+	TransformChunk = string,
+> = TransformChunk extends unknown
+	? | StdinSingleOption<IsSync, IsExtra, false, TransformChunk>
+	| ReadonlyArray<StdinSingleOption<IsSync, IsExtra, true, TransformChunk>>
+	: never;
+
+// `options.stdin`, async
+type StdinOption = StdinOptionCommon<false, false>;
+// `options.stdin`, sync
+type StdinSyncOption = StdinOptionCommon<true, false>;
+
+// `options.stdout|stderr` array items
+type StdoutStderrSingleOption<
+	IsSync extends boolean,
+	IsExtra extends boolean,
+	IsArray extends boolean,
+	TransformChunk = string,
+> =
+	| CommonStdioOption<IsSync, IsExtra, IsArray, TransformChunk, TransformChunk>
+	| OutputStdioOption<IsSync, IsArray>;
+
+// `options.stdout|stderr`
+// In `objectMode`, the `chunk` argument of every array item is typed as `string`, even though only the first transform in the pipeline receives subprocess lines. The array index cannot be used to infer the pipeline position, since non-transform items are filtered out and transforms are reordered at runtime.
+type StdoutStderrOptionCommon<
+	IsSync extends boolean = boolean,
+	IsExtra extends boolean = boolean,
+	TransformChunk = string,
+> = TransformChunk extends unknown
+	? | StdoutStderrSingleOption<IsSync, IsExtra, false, TransformChunk>
+	| ReadonlyArray<StdoutStderrSingleOption<IsSync, IsExtra, true, TransformChunk>>
+	: never;
+
+// `options.stdout|stderr`, async
+type StdoutStderrOption = StdoutStderrOptionCommon<false, false>;
+// `options.stdout|stderr`, sync
+type StdoutStderrSyncOption = StdoutStderrOptionCommon<true, false>;
+
+// `options.stdio[3+]`
+type StdioExtraOptionCommon<IsSync extends boolean, TransformChunk = string> =
+	| StdinOptionCommon<IsSync, true, TransformChunk>
+	| StdoutStderrOptionCommon<IsSync, true, TransformChunk>;
+
+// `options.stdin|stdout|stderr|stdio` array items
+type StdioSingleOption<
+	IsSync extends boolean = boolean,
+	IsExtra extends boolean = boolean,
+	IsArray extends boolean = boolean,
+	TransformChunk = string,
+> =
+	| StdinSingleOption<IsSync, IsExtra, IsArray, TransformChunk>
+	| StdoutStderrSingleOption<IsSync, IsExtra, IsArray, TransformChunk>;
+
+// Get `options.stdin|stdout|stderr|stdio` items if it is an array, else keep as is
+type StdioSingleOptionItems<StdioOptionType> = StdioOptionType extends readonly StdioSingleOption[]
+	? StdioOptionType[number]
+	: StdioOptionType;
+
+// `options.stdin|stdout|stderr|stdio`
+type StdioOptionCommon<IsSync extends boolean = boolean, TransformChunk = string> =
+	| StdinOptionCommon<IsSync, boolean, TransformChunk>
+	| StdoutStderrOptionCommon<IsSync, boolean, TransformChunk>;
+
+// `options.stdio` when it is an array
+type StdioOptionsArray<IsSync extends boolean = boolean, TransformChunk = string> = readonly [
+	StdinOptionCommon<IsSync, false, TransformChunk>,
+	StdoutStderrOptionCommon<IsSync, false, TransformChunk>,
+	StdoutStderrOptionCommon<IsSync, false, TransformChunk>,
+	...ReadonlyArray<StdioExtraOptionCommon<IsSync, TransformChunk>>,
+];
+
+// `options.stdio`
+type StdioOptionsProperty<IsSync extends boolean = boolean, TransformChunk = string> = TransformChunk extends unknown
+	? | SimpleStdioOption<IsSync, false, false>
+	| StdioOptionsArray<IsSync, TransformChunk>
+	: never;
+
+// Message when the `serialization` option is `'advanced'`
+type AdvancedMessage =
+	| string
+	| number
+	| boolean
+	| null
+	| object;
+
+// Message when the `serialization` option is `'json'`
+type JsonMessage =
+	| string
+	| number
+	| boolean
+	| null
+	| readonly JsonMessage[]
+	| {readonly [key: string | number]: JsonMessage};
+
+/**
+Type of messages exchanged between a process and its subprocess using `sendMessage()`, `getOneMessage()` and `getEachMessage()`.
+
+This requires the `ipc` option to be `true`. The type of `message` depends on the `serialization` option.
+*/
+type Message<
+	Serialization extends Options['serialization'] = Options['serialization'],
+> = Serialization extends 'json' ? JsonMessage : AdvancedMessage;
+
+/**
+Options to `sendMessage()` and `subprocess.sendMessage()`
+*/
+type SendMessageOptions = {
+	/**
+	Throw when the other process is not receiving or listening to messages.
+
+	@default false
+	*/
+	readonly strict?: boolean;
+};
+
+// IPC methods in subprocess
+/**
+Send a `message` to the parent process.
+
+This requires the `ipc` option to be `true`. The type of `message` depends on the `serialization` option.
+*/
+declare function sendMessage(message: Message, sendMessageOptions?: SendMessageOptions): Promise<void>;
+
+/**
+Options to `getOneMessage()` and `subprocess.getOneMessage()`
+*/
+type GetOneMessageOptions<
+	Serialization extends Options['serialization'],
+> = {
+	/**
+	Ignore any `message` that returns `false`.
+	*/
+	readonly filter?: (message: Message<Serialization>) => boolean;
+
+	/**
+	Keep the subprocess alive while `getOneMessage()` is waiting.
+
+	@default true
+	*/
+	readonly reference?: boolean;
+};
+
+/**
+Receive a single `message` from the parent process.
+
+This requires the `ipc` option to be `true`. The type of `message` depends on the `serialization` option.
+*/
+declare function getOneMessage(getOneMessageOptions?: GetOneMessageOptions<Options['serialization']>): Promise<Message>;
+
+/**
+Options to `getEachMessage()` and `subprocess.getEachMessage()`
+*/
+type GetEachMessageOptions = {
+	/**
+	Keep the subprocess alive while `getEachMessage()` is waiting.
+
+	@default true
+	*/
+	readonly reference?: boolean;
+};
+
+/**
+Iterate over each `message` from the parent process.
+
+This requires the `ipc` option to be `true`. The type of `message` depends on the `serialization` option.
+*/
+declare function getEachMessage(getEachMessageOptions?: GetEachMessageOptions): AsyncIterableIterator<Message>;
+
+/**
+Retrieves the [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) shared by the `cancelSignal` option.
+
+This can only be called inside a subprocess. This requires the `gracefulCancel` option to be `true`.
+*/
+declare function getCancelSignal(): Promise<AbortSignal>;
+
+// IPC methods in the subprocess
+type IpcMethods<
+	IpcEnabled extends boolean,
+	Serialization extends Options['serialization'],
+> = IpcEnabled extends true
+	? {
+		/**
+		Send a `message` to the subprocess.
+
+		This requires the `ipc` option to be `true`. The type of `message` depends on the `serialization` option.
+		*/
+		sendMessage(message: Message<Serialization>, sendMessageOptions?: SendMessageOptions): Promise<void>;
+
+		/**
+		Receive a single `message` from the subprocess.
+
+		This requires the `ipc` option to be `true`. The type of `message` depends on the `serialization` option.
+		*/
+		getOneMessage(getOneMessageOptions?: GetOneMessageOptions<Serialization>): Promise<Message<Serialization>>;
+
+		/**
+		Iterate over each `message` from the subprocess.
+
+		This requires the `ipc` option to be `true`. The type of `message` depends on the `serialization` option.
+		*/
+		getEachMessage(getEachMessageOptions?: GetEachMessageOptions): AsyncIterableIterator<Message<Serialization>>;
+	}
+	// Those methods only work if the `ipc` option is `true`.
+	// At runtime, they are actually defined, in order to provide with a nice error message.
+	// At type check time, they are typed as `undefined` to prevent calling them.
+	: {
+		sendMessage: undefined;
+		getOneMessage: undefined;
+		getEachMessage: undefined;
+	};
+
+// Whether IPC is enabled, based on the `ipc`, `node`, `ipcInput` and `gracefulCancel` options
+type HasIpc<OptionsType extends Options> = HasIpcOption<
+	OptionsType['ipc'],
+	'node' extends keyof OptionsType ? OptionsType['node'] : undefined,
+	'ipcInput' extends keyof OptionsType ? OptionsType['ipcInput'] : undefined,
+	'gracefulCancel' extends keyof OptionsType ? OptionsType['gracefulCancel'] : undefined
+>;
+
+type HasIpcOption<
+	IpcOption extends Options['ipc'],
+	NodeOption extends Options['node'],
+	IpcInputOption extends Options['ipcInput'],
+	GracefulCancelOption extends Options['gracefulCancel'],
+> = IpcOption extends true
+	? true
+	: IpcOption extends false
+		? false
+		: NodeOption extends true
+			? true
+			: IpcInputOption extends undefined
+				? GracefulCancelOption extends true
+					? true
+					: false
+				: true;
+
+type FileDescriptorOption = `fd${number}`;
+
+// `from` option of `subprocess.readable|duplex|iterable|pipe()`
+// Also used by fd-specific options
+type FromOption = 'stdout' | 'stderr' | 'all' | FileDescriptorOption;
+
+// `to` option of `subprocess.writable|duplex|pipe()`
+type ToOption = 'stdin' | FileDescriptorOption;
+
+// Options which can be fd-specific like `{verbose: {stdout: 'none', stderr: 'full'}}`
+type FdGenericOption<OptionType> = OptionType | GenericOptionObject<OptionType>;
+
+type GenericOptionObject<OptionType> = Readonly<Partial<Record<GenericFromOption, OptionType>>>;
+
+type GenericFromOption = FromOption | 'ipc';
+
+// Retrieve fd-specific option's value
+type FdSpecificOption<
+	GenericOption extends FdGenericOption<unknown>,
+	FdNumber extends string,
+> = GenericOption extends GenericOptionObject<unknown>
+	? FdSpecificObjectOption<GenericOption, FdNumber>
+	: GenericOption;
+
+type FdSpecificObjectOption<
+	GenericOption extends GenericOptionObject<unknown>,
+	FdNumber extends string,
+> = keyof GenericOption extends GenericFromOption
+	? FdNumberToFromOption<FdNumber, keyof GenericOption> extends never
+		? undefined
+		: GenericOption[FdNumberToFromOption<FdNumber, keyof GenericOption>]
+	: GenericOption;
+
+type FdNumberToFromOption<
+	FdNumber extends string,
+	GenericOptionKeys extends GenericFromOption,
+> = FdNumber extends 'ipc'
+	? 'ipc' extends GenericOptionKeys
+		? 'ipc'
+		: never
+	: FdNumber extends '1'
+		? 'stdout' extends GenericOptionKeys
+			? 'stdout'
+			: 'fd1' extends GenericOptionKeys
+				? 'fd1'
+				: 'all' extends GenericOptionKeys
+					? 'all'
+					: never
+		: FdNumber extends '2'
+			? 'stderr' extends GenericOptionKeys
+				? 'stderr'
+				: 'fd2' extends GenericOptionKeys
+					? 'fd2'
+					: 'all' extends GenericOptionKeys
+						? 'all'
+						: never
+			: `fd${FdNumber}` extends GenericOptionKeys
+				? `fd${FdNumber}`
+				: never;
+
+declare abstract class CommonError<
+	IsSync extends boolean,
+	OptionsType extends CommonOptions,
+> extends CommonResult<IsSync, OptionsType> {
+	message: CommonErrorProperty<IsSync, OptionsType, 'message'>;
+	shortMessage: CommonErrorProperty<IsSync, OptionsType, 'shortMessage'>;
+	originalMessage: CommonErrorProperty<IsSync, OptionsType, 'originalMessage'>;
+	readonly name: CommonErrorProperty<IsSync, OptionsType, 'name'>;
+	stack: CommonErrorProperty<IsSync, OptionsType, 'stack'>;
+}
+
+type CommonErrorProperty<
+	IsSync extends boolean,
+	OptionsType extends CommonOptions,
+	PropertyName extends keyof CommonResult<IsSync, OptionsType>,
+> = NonNullable<CommonResult<IsSync, OptionsType>[PropertyName]>;
+
+// `result.*` defined only on failure, i.e. on `error.*`
+type ErrorProperties =
+	| 'name'
+	| 'message'
+	| 'stack'
+	| 'cause'
+	| 'shortMessage'
+	| 'originalMessage'
+	| 'code';
+
+/**
+Result of a subprocess failed execution.
+
+This error is thrown as an exception. If the `reject` option is false, it is returned instead.
+
+This has the same shape as successful results, with a few additional properties.
+*/
+declare class ExecaError<OptionsType extends Options = Options> extends CommonError<false, OptionsType> {
+	readonly name: 'ExecaError';
+}
+
+/**
+Result of a subprocess failed execution.
+
+This error is thrown as an exception. If the `reject` option is false, it is returned instead.
+
+This has the same shape as successful results, with a few additional properties.
+*/
+declare class ExecaSyncError<OptionsType extends SyncOptions = SyncOptions> extends CommonError<true, OptionsType> {
+	readonly name: 'ExecaSyncError';
+}
+
+// `options.stdio`, normalized as an array
+type StdioOptionNormalizedArray<OptionsType extends CommonOptions> = StdioOptionNormalized<OptionsType['stdio']>;
+
+type StdioOptionNormalized<StdioOption extends CommonOptions['stdio']> = StdioOption extends StdioOptionsArray
+	? StdioOption
+	: StdioOption extends StdinOptionCommon
+		? StdioOption extends StdoutStderrOptionCommon
+			? readonly [StdioOption, StdioOption, StdioOption]
+			: DefaultStdioOption
+		: DefaultStdioOption;
+
+// `options.stdio` default value
+type DefaultStdioOption = readonly ['pipe', 'pipe', 'pipe'];
+
+// `options.stdin|stdout|stderr|stdio` for a given file descriptor
+type FdStdioOption<
+	FdNumber extends string,
+	OptionsType extends CommonOptions,
+> = FdStdioOptionProperty<FdNumber, OptionsType>;
+
+type FdStdioOptionProperty<
+	FdNumber extends string,
+	OptionsType extends CommonOptions,
+> = string extends FdNumber ? StdioOptionCommon
+	: FdNumber extends keyof StandardStreams
+		? StandardStreams[FdNumber] extends keyof OptionsType
+			? OptionsType[StandardStreams[FdNumber]] extends undefined
+				? FdStdioArrayOption<FdNumber, OptionsType>
+				: OptionsType[StandardStreams[FdNumber]]
+			: FdStdioArrayOption<FdNumber, OptionsType>
+		: FdStdioArrayOption<FdNumber, OptionsType>;
+
+// `options.stdio[FdNumber]`, excluding `options.stdin|stdout|stderr`
+type FdStdioArrayOption<
+	FdNumber extends string,
+	OptionsType extends CommonOptions,
+> = FdStdioArrayOptionProperty<FdNumber, StdioOptionNormalizedArray<OptionsType>>;
+
+type FdStdioArrayOptionProperty<
+	FdNumber extends string,
+	StdioOptionsType,
+> = string extends FdNumber
+	? StdioOptionCommon | undefined
+	: StdioOptionsType extends StdioOptionsArray
+		? FdNumber extends keyof StdioOptionsType
+			? StdioOptionsType[FdNumber]
+			: StdioOptionNormalizedArray<CommonOptions> extends StdioOptionsType
+				? StdioOptionsType[number]
+				: undefined
+		: undefined;
+
+// Whether a file descriptor is in object mode
+// I.e. whether `result.stdout|stderr|stdio|all` is an array of `unknown` due to `objectMode: true`
+type IsObjectFd<
+	FdNumber extends string,
+	OptionsType extends CommonOptions,
+> = IsObjectStdioOption<FdStdioOption<FdNumber, OptionsType>>;
+
+type IsObjectStdioOption<StdioOptionType> = IsObjectStdioSingleOption<StdioSingleOptionItems<StdioOptionType>>;
+
+type IsObjectStdioSingleOption<StdioSingleOptionType> = StdioSingleOptionType extends TransformCommon
+	? BooleanObjectMode<StdioSingleOptionType['objectMode']>
+	: StdioSingleOptionType extends DuplexTransform
+		? StdioSingleOptionType['transform']['readableObjectMode']
+		: false;
+
+type BooleanObjectMode<ObjectModeOption extends boolean | undefined> = ObjectModeOption extends true ? true : false;
+
+type AnyAmbiguousStdioOption = AmbiguousStdioOption<boolean, false, boolean>;
+
+type InputAmbiguousStdioOption = AnyAmbiguousStdioOption & {
+	readonly input: true;
+};
+
+type AmbiguousStdioInputValue<StdioOptionType> = StdioOptionType extends AnyAmbiguousStdioOption
+	? AmbiguousStdioInputProperty<StdioOptionType>
+	: never;
+
+type AmbiguousStdioInputProperty<StdioOptionType> = 'input' extends keyof StdioOptionType
+	? StdioOptionType extends {readonly input?: infer Input} ? Input : never
+	: never;
+
+// Whether `result.stdio[FdNumber]` is an input stream
+type IsInputFd<
+	FdNumber extends string,
+	OptionsType extends CommonOptions,
+> = FdNumber extends '0'
+	? true
+	: IsInputFdOption<
+		FdNumber,
+		StdioSingleOptionItems<FdStdioArrayOption<FdNumber, OptionsType>>
+	>;
+
+type IsInputFdOption<
+	FdNumber extends string,
+	StdioOptionType,
+> = Intersects<
+	StdioOptionType,
+	FdNumber extends '1' | '2' ? InputStdioOption : InputStdioOption | InputAmbiguousStdioOption
+> extends true
+	? true
+	: FdNumber extends '1' | '2'
+		? false
+		: true extends AmbiguousStdioInputValue<StdioOptionType>
+			? boolean
+			: false;
+
+// Whether `result.stdin|stdout|stderr|all|stdio[*]` is `undefined`
+type IgnoresResultOutput<
+	FdNumber extends string,
+	OptionsType extends CommonOptions,
+> = FdSpecificOption<OptionsType['buffer'], FdNumber> extends false
+	? true
+	: IgnoresResultOutputDirection<IsInputFd<FdNumber, OptionsType>, FdNumber, OptionsType>;
+
+type IgnoresResultOutputDirection<
+	IsInput extends boolean,
+	FdNumber extends string,
+	OptionsType extends CommonOptions,
+> = IsInput extends true ? true : IgnoresSubprocessOutput<FdNumber, OptionsType>;
+
+// Whether `subprocess.stdout|stderr|all` is `undefined|null`
+type IgnoresSubprocessOutput<
+	FdNumber extends string,
+	OptionsType extends CommonOptions,
+> = IgnoresOutput<FdNumber, FdStdioOption<FdNumber, OptionsType>>;
+
+type IgnoresOutput<
+	FdNumber extends string,
+	StdioOptionType,
+> = StdioOptionType extends NoStreamStdioOption<FdNumber> ? true : false;
+
+type DefaultEncodingOption = 'utf8';
+type TextEncodingOption =
+	| DefaultEncodingOption
+	| 'utf16le';
+
+type BufferEncodingOption = 'buffer';
+type BinaryEncodingOption =
+	| BufferEncodingOption
+	| 'hex'
+	| 'base64'
+	| 'base64url'
+	| 'latin1'
+	| 'ascii';
+
+// `options.encoding`
+type EncodingOption =
+	| TextEncodingOption
+	| BinaryEncodingOption
+	| undefined;
+
+// `result.stdout|stderr|stdio`
+type ResultStdioNotAll<
+	FdNumber extends string,
+	OptionsType extends CommonOptions,
+> = ResultStdio<FdNumber, FdNumber, FdNumber, OptionsType>;
+
+// `result.stdout|stderr|stdio|all`
+type ResultStdio<
+	MainFdNumber extends string,
+	ObjectFdNumber extends string,
+	LinesFdNumber extends string,
+	OptionsType extends CommonOptions,
+> = ResultStdioProperty<
+	ObjectFdNumber,
+	LinesFdNumber,
+	IgnoresResultOutput<MainFdNumber, OptionsType>,
+	OptionsType
+>;
+
+type ResultStdioProperty<
+	ObjectFdNumber extends string,
+	LinesFdNumber extends string,
+	StreamOutputIgnored,
+	OptionsType extends CommonOptions,
+> = StreamOutputIgnored extends true
+	? undefined
+	: ResultStdioItem<
+		IsObjectFd<ObjectFdNumber, OptionsType>,
+		FdSpecificOption<OptionsType['lines'], LinesFdNumber>,
+		OptionsType['encoding']
+	>;
+
+type ResultStdioItem<
+	IsObjectResult,
+	LinesOption extends boolean | undefined,
+	Encoding extends CommonOptions['encoding'],
+> = IsObjectResult extends true ? unknown[]
+	: Encoding extends BufferEncodingOption
+		? Uint8Array
+		: LinesOption extends true
+			? Encoding extends BinaryEncodingOption
+				? string
+				: string[]
+			: string;
+
+// `result.all`
+type ResultAll<OptionsType extends CommonOptions> =
+	ResultAllProperty<OptionsType['all'], OptionsType>;
+
+type ResultAllProperty<
+	AllOption extends CommonOptions['all'],
+	OptionsType extends CommonOptions,
+> = AllOption extends true
+	? ResultStdio<
+		AllMainFd<OptionsType>,
+		AllObjectFd<OptionsType>,
+		AllLinesFd<OptionsType>,
+		OptionsType
+	>
+	: undefined;
+
+type AllMainFd<OptionsType extends CommonOptions> =
+	IgnoresResultOutput<'1', OptionsType> extends true ? '2' : '1';
+
+type AllObjectFd<OptionsType extends CommonOptions> =
+	IsObjectFd<'1', OptionsType> extends true ? '1' : '2';
+
+type AllLinesFd<OptionsType extends CommonOptions> =
+	FdSpecificOption<OptionsType['lines'], '1'> extends true ? '1' : '2';
+
+// `result.stdio`
+type ResultStdioArray<
+	IsSync extends boolean,
+	OptionsType extends CommonOptions,
+> = [
+	...MapResultStdio<StdioOptionNormalizedArray<OptionsType>, OptionsType>,
+	...ResultIpcStdio<IsSync, OptionsType>,
+];
+
+type MapResultStdio<
+	StdioOptionsArrayType extends readonly unknown[],
+	OptionsType extends CommonOptions,
+> = {
+	-readonly [FdNumber in keyof StdioOptionsArrayType]: ResultStdioNotAll<
+		FdNumber extends string ? FdNumber : string,
+		OptionsType
+	>
+};
+
+// With the `ipc` option, the subprocess' IPC channel adds one last file descriptor, which has no output. Synchronous methods do not support IPC.
+type ResultIpcStdio<
+	IsSync extends boolean,
+	OptionsType extends CommonOptions,
+> = IsSync extends true
+	? []
+	: HasIpc<StricterOptions<OptionsType, Options>> extends true
+		? [undefined]
+		: [];
+
+// `result.ipcOutput`
+// This is empty unless the `ipc` option is `true`.
+// Also, this is empty if the `buffer` option is `false`.
+type ResultIpcOutput<
+	IsSync,
+	OptionsType extends CommonOptions,
+> = IsSync extends true
+	? []
+	: ResultIpcAsync<
+		FdSpecificOption<OptionsType['buffer'], 'ipc'>,
+		HasIpc<StricterOptions<OptionsType, Options>>,
+		OptionsType['serialization']
+	>;
+
+type ResultIpcAsync<
+	BufferOption extends boolean | undefined,
+	IpcEnabled extends boolean,
+	SerializationOption extends CommonOptions['serialization'],
+> = BufferOption extends false
+	? []
+	: IpcEnabled extends true
+		? Array<Message<SerializationOption>>
+		: [];
+
+declare abstract class CommonResult<
+	IsSync extends boolean,
+	OptionsType extends CommonOptions,
+> {
+	/**
+	The output of the subprocess on [`stdout`](https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout)).
+
+	This is `undefined` if the `stdout` option is set to only `'inherit'`, `'ignore'`, `Writable` or `integer`, or if the `buffer` option is `false`.
+
+	This is an array if the `lines` option is `true`, or if the `stdout` option is a transform in object mode.
+	*/
+	stdout: ResultStdioNotAll<'1', OptionsType>;
+
+	/**
+	The output of the subprocess on [`stderr`](https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr)).
+
+	This is `undefined` if the `stderr` option is set to only `'inherit'`, `'ignore'`, `Writable` or `integer`, or if the `buffer` option is `false`.
+
+	This is an array if the `lines` option is `true`, or if the `stderr` option is a transform in object mode.
+	*/
+	stderr: ResultStdioNotAll<'2', OptionsType>;
+
+	/**
+	The output of the subprocess with `result.stdout` and `result.stderr` interleaved.
+
+	This requires the `all` option to be `true`.
+
+	This is `undefined` if both `stdout` and `stderr` options are set to only `'inherit'`, `'ignore'`, `Writable` or `integer`, or if the `buffer` option is `false` for both.
+
+	This is an array if the `lines` option is `true`, or if either the `stdout` or `stderr` option is a transform in object mode.
+	*/
+	all: ResultAll<OptionsType>;
+
+	/**
+	The output of the subprocess on `stdin`, `stdout`, `stderr` and other file descriptors.
+
+	Items are `undefined` when their corresponding `stdio` option is set to only `'inherit'`, `'ignore'`, `Writable` or `integer`, or if the `buffer` option is `false`.
+
+	With the `ipc` option, the last item is the subprocess' IPC channel, which is always `undefined`.
+
+	Items are arrays when their corresponding `stdio` option is a transform in object mode.
+	*/
+	stdio: ResultStdioArray<IsSync, OptionsType>;
+
+	/**
+	All the messages sent by the subprocess to the current process.
+
+	This is empty unless the `ipc` option is `true`. Also, this is empty if the `buffer` option is `false`.
+	*/
+	ipcOutput: ResultIpcOutput<IsSync, OptionsType>;
+
+	/**
+	Results of the other subprocesses that were piped into this subprocess.
+
+	This array is initially empty and is populated each time the `subprocess.pipe()` method resolves.
+	*/
+	pipedFrom: Unless<IsSync, Array<Result | ExecaError>, []>;
+
+	/**
+	The file and arguments that were run.
+	*/
+	command: string;
+
+	/**
+	Same as `command` but escaped.
+
+	With the `shell` option, the command is not quoted, since the shell interprets it.
+	*/
+	escapedCommand: string;
+
+	/**
+	The current directory in which the command was run.
+	*/
+	cwd: string;
+
+	/**
+	Duration of the subprocess, in milliseconds.
+	*/
+	durationMs: number;
+
+	/**
+	Whether the subprocess failed to run.
+
+	When this is `true`, the result is an `ExecaError` instance with additional error-related properties.
+	*/
+	failed: boolean;
+
+	/**
+	Whether the subprocess timed out due to the `timeout` option.
+	*/
+	timedOut: boolean;
+
+	/**
+	Whether the subprocess was canceled using the `cancelSignal` option.
+	*/
+	isCanceled: boolean;
+
+	/**
+	Whether the subprocess was canceled using both the `cancelSignal` and the `gracefulCancel` options.
+	*/
+	isGracefullyCanceled: boolean;
+
+	/**
+	Whether the subprocess failed because its output was larger than the `maxBuffer` option.
+	*/
+	isMaxBuffer: boolean;
+
+	/**
+	Whether the subprocess was terminated by a signal (like `SIGTERM`) sent by either:
+	- The current process.
+	- Another process. This case is [not supported on Windows](https://nodejs.org/api/process.html#signal-events).
+	*/
+	isTerminated: boolean;
+
+	/**
+	Whether the subprocess was terminated by the `SIGKILL` signal sent by the `forceKillAfterDelay` option.
+	*/
+	isForcefullyTerminated: boolean;
+
+	/**
+	The numeric [exit code](https://en.wikipedia.org/wiki/Exit_status) of the subprocess that was run.
+
+	This is `undefined` when the subprocess could not be spawned or was terminated by a signal.
+	*/
+	exitCode?: number;
+
+	/**
+	The name of the signal (like `SIGTERM`) that terminated the subprocess, sent by either:
+	- The current process.
+	- Another process. This case is [not supported on Windows](https://nodejs.org/api/process.html#signal-events).
+
+	If a signal terminated the subprocess, this property is defined and included in the error message. Otherwise it is `undefined`.
+	*/
+	signal?: keyof SignalConstants;
+
+	/**
+	A human-friendly description of the signal that was used to terminate the subprocess.
+
+	If a signal terminated the subprocess, this property is defined and included in the error message. Otherwise it is `undefined`. It is also `undefined` when the signal is very uncommon which should seldomly happen.
+	*/
+	signalDescription?: string;
+
+	/**
+	Error message when the subprocess failed to run.
+	*/
+	message?: string;
+
+	/**
+	This is the same as `error.message` except it does not include the subprocess output.
+	*/
+	shortMessage?: string;
+
+	/**
+	Original error message. This is the same as `error.message` excluding the subprocess output and some additional information added by Execa.
+
+	This exists only in specific instances, such as during a timeout.
+	*/
+	originalMessage?: string;
+
+	/**
+	Underlying error, if there is one. For example, this is set by `subprocess.kill(error)`.
+
+	This is usually an `Error` instance.
+	*/
+	cause?: unknown;
+
+	/**
+	Node.js-specific [error code](https://nodejs.org/api/errors.html#errorcode), when available.
+	*/
+	code?: string;
+
+	// We cannot `extend Error` because `message` must be optional. So we copy its types here.
+	readonly name?: Error['name'];
+	stack?: Error['stack'];
+}
+
+type SuccessResult<
+	IsSync extends boolean = boolean,
+	OptionsType extends CommonOptions = CommonOptions,
+> = InstanceType<typeof CommonResult<IsSync, OptionsType>> & OmitErrorIfReject<OptionsType['reject']>;
+
+type OmitErrorIfReject<RejectOption extends CommonOptions['reject']> = Record<ErrorProperties, RejectOption extends false ? unknown : never>;
+
+/**
+Result of a subprocess successful execution.
+
+When the subprocess fails, it is rejected with an `ExecaError` instead.
+*/
+type Result<OptionsType extends Options = Options> = SuccessResult<false, OptionsType>;
+
+/**
+Result of a subprocess successful execution.
+
+When the subprocess fails, it is rejected with an `ExecaError` instead.
+*/
+type SyncResult<OptionsType extends SyncOptions = SyncOptions> = SuccessResult<true, OptionsType>;
+
+type VerboseOption = FdGenericOption<
+	| 'none'
+	| 'short'
+	| 'full'
+	| VerboseFunction
+>;
+
+type VerboseFunction = (verboseLine: string, verboseObject: MinimalVerboseObject) => string | void;
+
+type GenericVerboseObject = {
+	/**
+	Event type. This can be:
+	- `'command'`: subprocess start
+	- `'output'`: `stdout`/`stderr` output
+	- `'ipc'`: IPC output
+	- `'error'`: subprocess failure
+	- `'duration'`: subprocess success or failure
+	*/
+	type: 'command' | 'output' | 'ipc' | 'error' | 'duration';
+
+	/**
+	Depending on `verboseObject.type`, this is:
+	- `'command'`: the `result.escapedCommand`
+	- `'output'`: one line from `result.stdout` or `result.stderr`
+	- `'ipc'`: one IPC message from `result.ipcOutput`
+	- `'error'`: the `error.shortMessage`
+	- `'duration'`: the `result.durationMs`, formatted as `(done in 29ms)`
+	*/
+	message: string;
+
+	/**
+	The file and arguments that were run. This is the same as `result.escapedCommand`.
+	*/
+	escapedCommand: string;
+
+	/**
+	Serial number identifying the subprocess within the current process. It is incremented from `'0'`.
+
+	This is helpful when multiple subprocesses are running at the same time.
+
+	This is similar to a [PID](https://en.wikipedia.org/wiki/Process_identifier) except it has no maximum limit, which means it never repeats. Also, it is usually shorter.
+	*/
+	commandId: string;
+
+	/**
+	Event date/time.
+	*/
+	timestamp: Date;
+
+	/**
+	Whether this subprocess is the destination of another subprocess' `pipe()` method. This is `true` when it was spawned using the template string or array syntax of `pipe()`, `false` otherwise.
+	*/
+	piped: boolean;
+};
+
+type MinimalVerboseObject = GenericVerboseObject & {
+	// We cannot use the `CommonOptions` type because it would make this type recursive
+	options: object;
+	result?: never;
+};
+
+/**
+Subprocess event object, for logging purpose, using the `verbose` option and `execa()`.
+*/
+type VerboseObject = GenericVerboseObject & {
+	/**
+	The options passed to the subprocess.
+	*/
+	options: Options;
+
+	/**
+	Subprocess result.
+
+	This is `undefined` if `verboseObject.type` is `'command'`, `'output'` or `'ipc'`.
+	*/
+	result?: Result;
+};
+
+/**
+Subprocess event object, for logging purpose, using the `verbose` option and `execaSync()`.
+*/
+type SyncVerboseObject = GenericVerboseObject & {
+	/**
+	The options passed to the subprocess.
+	*/
+	options: SyncOptions;
+
+	/**
+	Subprocess result.
+
+	This is `undefined` if `verboseObject.type` is `'command'`, `'output'` or `'ipc'`.
+	*/
+	result?: SyncResult;
+};
+
+type ChunkForEncoding<Encoding extends EncodingOption> = Encoding extends BinaryEncodingOption ? Uint8Array : string;
+
+type CommonOptions<
+	IsSync extends boolean = boolean,
+	Encoding extends EncodingOption = EncodingOption,
+> = {
+	/**
+	Prefer locally installed binaries when looking for a binary to execute.
+
+	@default `true` with `$`, `false` otherwise
+	*/
+	readonly preferLocal?: boolean;
+
+	/**
+	Preferred path to find locally installed binaries, when using the `preferLocal` option.
+
+	@default `cwd` option
+	*/
+	readonly localDir?: string | URL;
+
+	/**
+	If `true`, runs with Node.js. The first argument must be a Node.js file.
+
+	The subprocess inherits the current Node.js [CLI flags](https://nodejs.org/api/cli.html#options) and version. This can be overridden using the `nodeOptions` and `nodePath` options.
+
+	@default `true` with `execaNode()`, `false` otherwise
+	*/
+	readonly node?: boolean;
+
+	/**
+	List of [CLI flags](https://nodejs.org/api/cli.html#cli_options) passed to the Node.js executable.
+
+	Requires the `node` option to be `true`.
+
+	@default [`process.execArgv`](https://nodejs.org/api/process.html#process_process_execargv) (current Node.js CLI flags)
+	*/
+	readonly nodeOptions?: readonly string[];
+
+	/**
+	Path to the Node.js executable.
+
+	Requires the `node` option to be `true`.
+
+	@default [`process.execPath`](https://nodejs.org/api/process.html#process_process_execpath) (current Node.js executable)
+	*/
+	readonly nodePath?: string | URL;
+
+	/**
+	If `true`, runs the command inside of a [shell](https://en.wikipedia.org/wiki/Shell_(computing)).
+
+	Uses [`/bin/sh`](https://en.wikipedia.org/wiki/Unix_shell) on UNIX and [`cmd.exe`](https://en.wikipedia.org/wiki/Cmd.exe) on Windows. A different shell can be specified as a string. The shell should understand the `-c` switch on UNIX or `/d /s /c` on Windows.
+
+	We recommend against using this option.
+
+	@default false
+	*/
+	readonly shell?: boolean | string | URL;
+
+	/**
+	Current [working directory](https://en.wikipedia.org/wiki/Working_directory) of the subprocess.
+
+	This is also used to resolve the `nodePath` option when it is a relative path.
+
+	@default process.cwd()
+	*/
+	readonly cwd?: string | URL;
+
+	/**
+	[Environment variables](https://en.wikipedia.org/wiki/Environment_variable).
+
+	Unless the `extendEnv` option is `false`, the subprocess also uses the current process' environment variables ([`process.env`](https://nodejs.org/api/process.html#processenv)).
+
+	@default {}
+	*/
+	readonly env?: Readonly<Partial<Record<string, string>>>;
+
+	/**
+	If `true`, the subprocess uses both the `env` option and the current process' environment variables ([`process.env`](https://nodejs.org/api/process.html#processenv)).
+	If `false`, only the `env` option is used, not `process.env`. However, when `env` has no `PATH`, the `preferLocal` and `node` options still add their directories to `process.env.PATH`.
+
+	@default true
+	*/
+	readonly extendEnv?: boolean;
+
+	/**
+	Write some input to the subprocess' [`stdin`](https://en.wikipedia.org/wiki/Standard_streams#Standard_input_(stdin)).
+
+	See also the `inputFile` and `stdin` options.
+	*/
+	readonly input?: string | Uint8Array | Readable;
+
+	/**
+	Use a file as input to the subprocess' [`stdin`](https://en.wikipedia.org/wiki/Standard_streams#Standard_input_(stdin)).
+
+	See also the `input` and `stdin` options.
+	*/
+	readonly inputFile?: string | URL;
+
+	/**
+	How to setup the subprocess' [standard input](https://en.wikipedia.org/wiki/Standard_streams#Standard_input_(stdin)). This can be `'pipe'`, `'overlapped'`, `'ignore`, `'inherit'`, a file descriptor integer, a Node.js `Readable` stream, a web `ReadableStream`, a `{ file: 'path' }` object, a file URL, an `Iterable`, an `AsyncIterable`, an `Uint8Array`, a generator function, a `Duplex` or a web `TransformStream`.
+
+	This can be an array of values such as `['inherit', 'pipe']` or `[fileUrl, 'pipe']`.
+
+	@default `'inherit'` with `$`, `'pipe'` otherwise
+	*/
+	readonly stdin?: StdinOptionCommon<IsSync, boolean, ChunkForEncoding<Encoding>>;
+
+	/**
+	How to setup the subprocess' [standard output](https://en.wikipedia.org/wiki/Standard_streams#Standard_input_(stdin)). This can be `'pipe'`, `'overlapped'`, `'ignore`, `'inherit'`, a file descriptor integer, a Node.js `Writable` stream, a web `WritableStream`, a `{ file: 'path' }` object, a file URL, a generator function, a `Duplex` or a web `TransformStream`.
+
+	This can be an array of values such as `['inherit', 'pipe']` or `[fileUrl, 'pipe']`.
+
+	@default 'pipe'
+	*/
+	readonly stdout?: StdoutStderrOptionCommon<IsSync, boolean, ChunkForEncoding<Encoding>>;
+
+	/**
+	How to setup the subprocess' [standard error](https://en.wikipedia.org/wiki/Standard_streams#Standard_input_(stdin)). This can be `'pipe'`, `'overlapped'`, `'ignore`, `'inherit'`, a file descriptor integer, a Node.js `Writable` stream, a web `WritableStream`, a `{ file: 'path' }` object, a file URL, a generator function, a `Duplex` or a web `TransformStream`.
+
+	This can be an array of values such as `['inherit', 'pipe']` or `[fileUrl, 'pipe']`.
+
+	@default 'pipe'
+	*/
+	readonly stderr?: StdoutStderrOptionCommon<IsSync, boolean, ChunkForEncoding<Encoding>>;
+
+	/**
+	Like the `stdin`, `stdout` and `stderr` options but for all [file descriptors](https://en.wikipedia.org/wiki/File_descriptor) at once. For example, `{stdio: ['ignore', 'pipe', 'pipe']}` is the same as `{stdin: 'ignore', stdout: 'pipe', stderr: 'pipe'}`.
+
+	A single string can be used as a shortcut.
+
+	The array can have more than 3 items, to create additional file descriptors beyond `stdin`/`stdout`/`stderr`.
+
+	@default 'pipe'
+	*/
+	readonly stdio?: StdioOptionsProperty<IsSync, ChunkForEncoding<Encoding>>;
+
+	/**
+	Add a `subprocess.all` stream and a `result.all` property. They contain the combined/interleaved output of the subprocess' `stdout` and `stderr`.
+
+	@default false
+	*/
+	readonly all?: boolean;
+
+	/**
+	If the subprocess outputs text, specifies its character encoding, either [`'utf8'`](https://en.wikipedia.org/wiki/UTF-8) or [`'utf16le'`](https://en.wikipedia.org/wiki/UTF-16).
+
+	If it outputs binary data instead, this should be either:
+	- `'buffer'`: returns the binary output as an `Uint8Array`.
+	- [`'hex'`](https://en.wikipedia.org/wiki/Hexadecimal), [`'base64'`](https://en.wikipedia.org/wiki/Base64), [`'base64url'`](https://en.wikipedia.org/wiki/Base64#RFC_4648), [`'latin1'`](https://nodejs.org/api/buffer.html#buffers-and-character-encodings) or [`'ascii'`](https://nodejs.org/api/buffer.html#buffers-and-character-encodings): encodes the binary output as a string.
+
+	The output is available with `result.stdout`, `result.stderr` and `result.stdio`.
+
+	String input passed with the `input` or `stdin` option is always encoded with UTF-8, whatever this option is. With a text encoding, `stdin` transforms also decode their input with UTF-8.
+
+	@default 'utf8'
+	*/
+	readonly encoding?: Encoding;
+
+	/**
+	Set `result.stdout`, `result.stderr`, `result.all` and `result.stdio` as arrays of strings, splitting the subprocess' output into lines.
+
+	This cannot be used if the `encoding` option is binary.
+
+	By default, this applies to both `stdout` and `stderr`, but different values can also be passed.
+
+	@default false
+	*/
+	readonly lines?: FdGenericOption<boolean>;
+
+	/**
+	Strip the final [newline character](https://en.wikipedia.org/wiki/Newline) from the output.
+
+	If the `lines` option is true, this applies to each output line instead.
+
+	By default, this applies to both `stdout` and `stderr`, but different values can also be passed.
+
+	@default true
+	*/
+	readonly stripFinalNewline?: FdGenericOption<boolean>;
+
+	/**
+	Largest amount of data allowed on `stdout`, `stderr` and `stdio`.
+
+	By default, this applies to both `stdout` and `stderr`, but different values can also be passed.
+
+	With synchronous methods, this cannot be enforced per file descriptor while the subprocess runs, since `spawnSync()` only accepts a single value, which limits the total output of all file descriptors. The `maxBuffer.stdout` value is used for it. The other file descriptors' own values are enforced from the output, once the subprocess ended, and cannot be higher than `maxBuffer.stdout`. Also, with synchronous methods, this is measured in bytes instead of characters or lines, for the same reason.
+
+	When reached, `error.isMaxBuffer` becomes `true`.
+
+	@default 100_000_000
+	*/
+	readonly maxBuffer?: FdGenericOption<number>;
+
+	/**
+	When `buffer` is `false`, the `result.stdout`, `result.stderr`, `result.all` and `result.stdio` properties are not set.
+
+	By default, this applies to both `stdout` and `stderr`, but different values can also be passed.
+
+	@default true
+	*/
+	readonly buffer?: FdGenericOption<boolean>;
+
+	/**
+	Enables exchanging messages with the subprocess using `subprocess.sendMessage(message)`, `subprocess.getOneMessage()` and `subprocess.getEachMessage()`.
+
+	The subprocess must be a Node.js file.
+
+	@default `true` if the `node`, `ipcInput` or `gracefulCancel` option is set, `false` otherwise
+	*/
+	readonly ipc?: Unless<IsSync, boolean>;
+
+	/**
+	Specify the kind of serialization used for sending messages between subprocesses when using the `ipc` option.
 
-		@default true
-		*/
-		readonly cleanup?: boolean;
+	@default 'advanced'
+	*/
+	readonly serialization?: Unless<IsSync, 'json' | 'advanced'>;
 
-		/**
-		Prefer locally installed binaries when looking for a binary to execute.
+	/**
+	Sends an IPC message when the subprocess starts.
 
-		If you `$ npm install foo`, you can then `execa('foo')`.
+	The subprocess must be a Node.js file. The value's type depends on the `serialization` option.
+	*/
+	readonly ipcInput?: Unless<IsSync, Message>;
 
-		@default false
-		*/
-		readonly preferLocal?: boolean;
+	/**
+	If `verbose` is `'short'`, prints the command on [`stderr`](https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr)): its file, arguments, duration and (if it failed) error message.
 
-		/**
-		Preferred path to find locally installed binaries in (use with `preferLocal`).
+	If `verbose` is `'full'` or a function, the command's [`stdout`](https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout)), `stderr` and IPC messages are also printed.
 
-		@default process.cwd()
-		*/
-		readonly localDir?: string;
+	A function can be passed to customize logging.
 
-		/**
-		Path to the Node.js executable to use in child processes.
+	By default, this applies to both `stdout` and `stderr`, but different values can also be passed.
 
-		This can be either an absolute path or a path relative to the `cwd` option.
+	@default 'none'
+	*/
+	readonly verbose?: VerboseOption;
 
-		Requires `preferLocal` to be `true`.
+	/**
+	Setting this to `false` resolves the result's promise with the error instead of rejecting it.
 
-		For example, this can be used together with [`get-node`](https://github.com/ehmicky/get-node) to run a specific Node.js version in a child process.
+	@default true
+	*/
+	readonly reject?: boolean;
 
-		@default process.execPath
-		*/
-		readonly execPath?: string;
+	/**
+	If `timeout` is greater than `0`, the subprocess will be terminated if it runs for longer than that amount of milliseconds. It must be a non-negative integer, up to `2147483647` (about 24.8 days).
 
-		/**
-		Buffer the output from the spawned process. When set to `false`, you must read the output of `stdout` and `stderr` (or `all` if the `all` option is `true`). Otherwise the returned promise will not be resolved/rejected.
+	On timeout, `error.timedOut` becomes `true`.
 
-		If the spawned process fails, `error.stdout`, `error.stderr`, and `error.all` will contain the buffered data.
+	@default 0
+	*/
+	readonly timeout?: number;
 
-		@default true
-		*/
-		readonly buffer?: boolean;
+	/**
+	When the `cancelSignal` is [aborted](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort), terminate the subprocess using a `SIGTERM` signal.
 
-		/**
-		Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio).
+	When aborted, `error.isCanceled` becomes `true`.
 
-		@default 'pipe'
-		*/
-		readonly stdin?: StdioOption;
+	@example
+	```
+	import {execaNode} from 'execa';
 
-		/**
-		Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio).
+	const controller = new AbortController();
+	const cancelSignal = controller.signal;
 
-		@default 'pipe'
-		*/
-		readonly stdout?: StdioOption;
+	setTimeout(() => {
+		controller.abort();
+	}, 5000);
 
-		/**
-		Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio).
+	try {
+		await execaNode({cancelSignal})`build.js`;
+	} catch (error) {
+		if (error.isCanceled) {
+			console.error('Canceled by cancelSignal.');
+		}
 
-		@default 'pipe'
-		*/
-		readonly stderr?: StdioOption;
+		throw error;
+	}
+	```
+	*/
+	readonly cancelSignal?: Unless<IsSync, AbortSignal>;
 
-		/**
-		Setting this to `false` resolves the promise with the error instead of rejecting it.
+	/**
+	When the `cancelSignal` option is [aborted](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort), do not send any `SIGTERM`. Instead, abort the [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) returned by `getCancelSignal()`. The subprocess should use it to terminate gracefully.
 
-		@default true
-		*/
-		readonly reject?: boolean;
+	The subprocess must be a Node.js file.
 
-		/**
-		Add an `.all` property on the promise and the resolved value. The property contains the output of the process with `stdout` and `stderr` interleaved.
+	When aborted, `error.isGracefullyCanceled` becomes `true`.
 
-		@default false
-		*/
-		readonly all?: boolean;
+	@default false
+	*/
+	readonly gracefulCancel?: Unless<IsSync, boolean>;
 
-		/**
-		Strip the final [newline character](https://en.wikipedia.org/wiki/Newline) from the output.
+	/**
+	If the subprocess is terminated but does not exit, forcefully exit it by sending [`SIGKILL`](https://en.wikipedia.org/wiki/Signal_(IPC)#SIGKILL). The delay must be a non-negative integer, up to `2147483647` milliseconds (about 24.8 days). When `true`, the default `5000` is used. When `false`, the subprocess is not forcefully exited.
 
-		@default true
-		*/
-		readonly stripFinalNewline?: boolean;
+	When this happens, `error.isForcefullyTerminated` becomes `true`.
 
-		/**
-		Set to `false` if you don't want to extend the environment variables when providing the `env` property.
+	@default 5000
+	*/
+	readonly forceKillAfterDelay?: Unless<IsSync, number | boolean>;
 
-		@default true
-		*/
-		readonly extendEnv?: boolean;
+	/**
+	Default [signal](https://en.wikipedia.org/wiki/Signal_(IPC)) used to terminate the subprocess.
 
-		/**
-		Current working directory of the child process.
+	This can be either a name (like `'SIGTERM'`) or a number (like `9`).
 
-		@default process.cwd()
-		*/
-		readonly cwd?: string;
+	@default 'SIGTERM'
+	*/
+	readonly killSignal?: keyof SignalConstants | number;
 
-		/**
-		Environment key-value pairs. Extends automatically from `process.env`. Set `extendEnv` to `false` if you don't want this.
+	/**
+	Run the subprocess independently from the current process.
 
-		@default process.env
-		*/
-		readonly env?: NodeJS.ProcessEnv;
+	@default false
+	*/
+	readonly detached?: Unless<IsSync, boolean>;
 
-		/**
-		Explicitly set the value of `argv[0]` sent to the child process. This will be set to `command` or `file` if not specified.
-		*/
-		readonly argv0?: string;
+	/**
+	Kill the subprocess when the current process exits.
 
-		/**
-		Child's [stdio](https://nodejs.org/api/child_process.html#child_process_options_stdio) configuration.
+	@default true
+	*/
+	readonly cleanup?: Unless<IsSync, boolean>;
 
-		@default 'pipe'
-		*/
-		readonly stdio?: 'pipe' | 'ignore' | 'inherit' | readonly StdioOption[];
+	/**
+	When the subprocess is terminated by Execa, also terminate all of its descendant processes, instead of only the subprocess itself.
 
-		/**
-		Specify the kind of serialization used for sending messages between processes when using the `stdio: 'ipc'` option or `execa.node()`:
-			- `json`: Uses `JSON.stringify()` and `JSON.parse()`.
-			- `advanced`: Uses [`v8.serialize()`](https://nodejs.org/api/v8.html#v8_v8_serialize_value)
+	This is useful when the subprocess spawns its own processes, such as when using the `shell` option.
 
-		Requires Node.js `13.2.0` or later.
+	On Unix, this spawns the subprocess in its own [process group](https://en.wikipedia.org/wiki/Process_group). On Windows, this uses [`taskkill`](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/taskkill).
 
-		[More info.](https://nodejs.org/api/child_process.html#child_process_advanced_serialization)
+	This is best-effort: descendant processes that create their own process group or session are not terminated. Also, on Windows, descendants are not terminated once the subprocess exited, since its PID might then belong to an unrelated process.
 
-		@default 'json'
-		*/
-		readonly serialization?: 'json' | 'advanced';
+	@default false
+	*/
+	readonly killDescendants?: Unless<IsSync, boolean>;
 
-		/**
-		Prepare child to run independently of its parent process. Specific behavior [depends on the platform](https://nodejs.org/api/child_process.html#child_process_options_detached).
+	/**
+	Sets the [user identifier](https://en.wikipedia.org/wiki/User_identifier) of the subprocess.
 
-		@default false
-		*/
-		readonly detached?: boolean;
+	@default current user identifier
+	*/
+	readonly uid?: number;
 
-		/**
-		Sets the user identity of the process.
-		*/
-		readonly uid?: number;
+	/**
+	Sets the [group identifier](https://en.wikipedia.org/wiki/Group_identifier) of the subprocess.
 
-		/**
-		Sets the group identity of the process.
-		*/
-		readonly gid?: number;
+	@default current group identifier
+	*/
+	readonly gid?: number;
 
-		/**
-		If `true`, runs `command` inside of a shell. Uses `/bin/sh` on UNIX and `cmd.exe` on Windows. A different shell can be specified as a string. The shell should understand the `-c` switch on UNIX or `/d /s /c` on Windows.
+	/**
+	Value of [`argv[0]`](https://nodejs.org/api/process.html#processargv0) sent to the subprocess.
 
-		We recommend against using this option since it is:
-		- not cross-platform, encouraging shell-specific syntax.
-		- slower, because of the additional shell interpretation.
-		- unsafe, potentially allowing command injection.
+	@default file being executed
+	*/
+	readonly argv0?: string;
 
-		@default false
-		*/
-		readonly shell?: boolean | string;
+	/**
+	On Windows, do not create a new console window.
 
-		/**
-		Specify the character encoding used to decode the `stdout` and `stderr` output. If set to `null`, then `stdout` and `stderr` will be a `Buffer` instead of a string.
+	@default true
+	*/
+	readonly windowsHide?: boolean;
 
-		@default 'utf8'
-		*/
-		readonly encoding?: EncodingType;
+	/**
+	If `false`, escapes the command arguments on Windows.
 
-		/**
-		If `timeout` is greater than `0`, the parent will send the signal identified by the `killSignal` property (the default is `SIGTERM`) if the child runs longer than `timeout` milliseconds.
+	@default `true` if the `shell` option is `true`, `false` otherwise
+	*/
+	readonly windowsVerbatimArguments?: boolean;
+};
 
-		@default 0
-		*/
-		readonly timeout?: number;
+/**
+Subprocess options.
 
-		/**
-		Largest amount of data in bytes allowed on `stdout` or `stderr`. Default: 100 MB.
+Some options are related to the subprocess output: `verbose`, `lines`, `stripFinalNewline`, `buffer`, `maxBuffer`. By default, those options apply to all file descriptors (`stdout`, `stderr`, etc.). A plain object can be passed instead to apply them to only `stdout`, `stderr`, `all` (both stdout and stderr), `ipc`, `fd3`, etc.
 
-		@default 100_000_000
-		*/
-		readonly maxBuffer?: number;
+@example
 
-		/**
-		Signal value to be used when the spawned process will be killed.
+```
+// Same value for stdout and stderr
+await execa({verbose: 'full'})`npm run build`;
 
-		@default 'SIGTERM'
-		*/
-		readonly killSignal?: string | number;
+// Different values for stdout and stderr
+await execa({verbose: {stdout: 'none', stderr: 'full'}})`npm run build`;
+```
+*/
+type TextOptions<IsSync extends boolean> = CommonOptions<IsSync, TextEncodingOption | undefined>;
+type BinaryOptions<IsSync extends boolean> = Omit<CommonOptions<IsSync, BinaryEncodingOption>, 'encoding'> & {
+	readonly encoding: BinaryEncodingOption;
+};
 
-		/**
-		If `true`, no quoting or escaping of arguments is done on Windows. Ignored on other platforms. This is set to `true` automatically when the `shell` option is `true`.
+type Options = TextOptions<false> | BinaryOptions<false>;
 
-		@default false
-		*/
-		readonly windowsVerbatimArguments?: boolean;
+/**
+Subprocess options, with synchronous methods.
 
-		/**
-		On Windows, do not create a new console window. Please note this also prevents `CTRL-C` [from working](https://github.com/nodejs/node/issues/29837) on Windows.
+Some options are related to the subprocess output: `verbose`, `lines`, `stripFinalNewline`, `buffer`, `maxBuffer`. By default, those options apply to all file descriptors (`stdout`, `stderr`, etc.). A plain object can be passed instead to apply them to only `stdout`, `stderr`, `all` (both stdout and stderr), `ipc`, `fd3`, etc.
 
-		@default true
-		*/
-		readonly windowsHide?: boolean;
-	}
+@example
 
-	interface Options<EncodingType = string> extends CommonOptions<EncodingType> {
-		/**
-		Write some input to the `stdin` of your binary.
-		*/
-		readonly input?: string | Buffer | ReadableStream;
-	}
+```
+// Same value for stdout and stderr
+execaSync({verbose: 'full'})`npm run build`;
 
-	interface SyncOptions<EncodingType = string> extends CommonOptions<EncodingType> {
-		/**
-		Write some input to the `stdin` of your binary.
-		*/
-		readonly input?: string | Buffer;
-	}
+// Different values for stdout and stderr
+execaSync({verbose: {stdout: 'none', stderr: 'full'}})`npm run build`;
+```
+*/
+type SyncOptions = TextOptions<true> | BinaryOptions<true>;
+
+type StricterOptions<
+	WideOptions extends CommonOptions,
+	StrictOptions extends CommonOptions,
+> = WideOptions extends StrictOptions ? WideOptions : StrictOptions;
+
+type TemplateExpressionItem =
+	| string
+	| number
+	| Result
+	| SyncResult;
+
+/**
+Value allowed inside `${...}` when using the template string syntax.
+*/
+type TemplateExpression = TemplateExpressionItem | readonly TemplateExpressionItem[];
+
+// `...${...}...` template syntax
+type TemplateString = readonly [TemplateStringsArray, ...readonly TemplateExpression[]];
+
+// `subprocess.pipe()` options
+type PipeOptions = {
+	/**
+	Which stream to pipe from the source subprocess. A [file descriptor](https://en.wikipedia.org/wiki/File_descriptor) like `"fd3"` can also be passed.
+
+	`"all"` pipes both `stdout` and `stderr`. This requires the `all` option to be `true`.
+	*/
+	readonly from?: FromOption;
+
+	/**
+	Which stream to pipe to the destination subprocess. A [file descriptor](https://en.wikipedia.org/wiki/File_descriptor) like `"fd3"` can also be passed.
+	*/
+	readonly to?: ToOption;
+
+	/**
+	Unpipe the subprocess when the signal aborts.
+	*/
+	readonly unpipeSignal?: AbortSignal;
+};
+
+// Methods forwarded from the destination subprocess to the return value of `subprocess.pipe()`, so its output can be iterated, converted to a stream, or used for IPC.
+type PipeResultMethods<OptionsType extends Options> =
+	& SubprocessResultMethods<OptionsType>
+	& IpcMethods<HasIpc<OptionsType>, OptionsType['serialization']>;
+
+// Same as `PipeResultMethods`, but when the destination is another `execa()` call, so its own option types are kept.
+// The base `Options` is only used to compute the property names, which do not depend on the specific options.
+type PipeResultMethodsFrom<Destination extends ResultPromise> = Pick<Destination, keyof PipeResultMethods<Options>>;
+
+// `subprocess.pipe()`
+type PipableSubprocess = {
+	/**
+	[Pipe](https://nodejs.org/api/stream.html#readablepipedestination-options) the subprocess' `stdout` to a second Execa subprocess' `stdin`. This resolves with that second subprocess' result. If either subprocess is rejected, this is rejected with that subprocess' error instead.
+
+	This follows the same syntax as `execa(file, arguments?, options?)` except both regular options and pipe-specific options can be specified.
+
+	Like a subprocess, the return value can be [iterated](https://github.com/sindresorhus/execa/blob/main/docs/lines.md#progressive-splitting), [converted to a stream](https://github.com/sindresorhus/execa/blob/main/docs/streams.md#converting-a-subprocess-to-a-stream), or used for [IPC](https://github.com/sindresorhus/execa/blob/main/docs/ipc.md) with the destination subprocess.
+	*/
+	pipe<OptionsType extends Options & PipeOptions = {}>(
+		file: string | URL,
+		arguments?: readonly string[],
+		options?: OptionsType,
+	): Promise<Result<OptionsType>> & PipableSubprocess & PipeResultMethods<OptionsType>;
+	pipe<OptionsType extends Options & PipeOptions = {}>(
+		file: string | URL,
+		options?: OptionsType,
+	): Promise<Result<OptionsType>> & PipableSubprocess & PipeResultMethods<OptionsType>;
+
+	/**
+	Like `subprocess.pipe(file, arguments?, options?)` but using a `command` template string instead. This follows the same syntax as `$`.
+	*/
+	pipe(templates: TemplateStringsArray, ...expressions: readonly TemplateExpression[]):
+	Promise<Result<{}>> & PipableSubprocess & PipeResultMethods<{}>;
+	pipe<OptionsType extends Options & PipeOptions = {}>(options: OptionsType):
+	(templates: TemplateStringsArray, ...expressions: readonly TemplateExpression[])
+	=> Promise<Result<OptionsType>> & PipableSubprocess & PipeResultMethods<OptionsType>;
+
+	/**
+	Like `subprocess.pipe(file, arguments?, options?)` but using the return value of another `execa()` call instead.
+	*/
+	pipe<Destination extends ResultPromise>(destination: Destination, options?: PipeOptions):
+	Promise<Awaited<Destination>> & PipableSubprocess & PipeResultMethodsFrom<Destination>;
+};
+
+// `subprocess.readable|duplex|iterable()` options
+type ReadableOptions = {
+	/**
+	Which stream to read from the subprocess. A [file descriptor](https://en.wikipedia.org/wiki/File_descriptor) like `"fd3"` can also be passed.
+
+	`"all"` reads both `stdout` and `stderr`. This requires the `all` option to be `true`.
+
+	@default 'stdout'
+	*/
+	readonly from?: FromOption;
+
+	/**
+	If `false`, iterates over lines. Each line is a string.
+
+	If `true`, iterates over arbitrary chunks of data. Each line is an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) (with `subprocess.iterable()`) or a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) (with `subprocess.readable()`/`subprocess.duplex()`).
+
+	This is always `true` when the `encoding` option is binary.
+
+	@default `false` with `subprocess.iterable()`, `true` otherwise
+	*/
+	readonly binary?: boolean;
+
+	/**
+	If both this option and the `binary` option is `false`, [newlines](https://en.wikipedia.org/wiki/Newline) are stripped from each line.
+
+	@default `false` with `subprocess.iterable()`, `true` otherwise
+	*/
+	readonly preserveNewlines?: boolean;
+};
+
+// `subprocess.writable|duplex()` options
+type WritableOptions = {
+	/**
+	Which stream to write to the subprocess. A [file descriptor](https://en.wikipedia.org/wiki/File_descriptor) like `"fd3"` can also be passed.
+
+	@default 'stdin'
+	*/
+	readonly to?: ToOption;
+};
+
+// `subprocess.duplex()` options
+type DuplexOptions = ReadableOptions & WritableOptions;
+
+// `subprocess.iterable()` return value
+type SubprocessAsyncIterable<
+	BinaryOption extends boolean | undefined,
+	EncodingOption extends Options['encoding'],
+> = AsyncIterableIterator<
+	EncodingOption extends BinaryEncodingOption
+		? Uint8Array
+		: BinaryOption extends true
+			? Uint8Array
+			: string
+>;
+
+// `subprocess.stdin|stdout|stderr|stdio`
+type SubprocessStdioStream<
+	FdNumber extends string,
+	OptionsType extends Options,
+> = SubprocessStream<FdNumber, IgnoresSubprocessOutput<FdNumber, OptionsType>, OptionsType>;
+
+type SubprocessStream<
+	FdNumber extends string,
+	StreamResultIgnored,
+	OptionsType extends Options,
+> = StreamResultIgnored extends true
+	? null
+	: InputOutputStream<IsInputFd<FdNumber, OptionsType>>;
+
+type InputOutputStream<IsInput extends boolean> = IsInput extends true
+	? Writable
+	: Readable;
+
+// `subprocess.stdio`
+type SubprocessStdioArray<OptionsType extends Options> = MapStdioStreams<StdioOptionNormalizedArray<OptionsType>, OptionsType>;
+
+// File descriptors beyond `stderr` are only present when the `stdio` option is an array with more items.
+// The subprocess' IPC channel, if any, is set as the last file descriptor by Node.js itself.
+// Since any `Subprocess` can be passed where the default one is expected, the list is kept open-ended.
+type MapStdioStreams<
+	StdioOptionsArrayType extends readonly unknown[],
+	OptionsType extends Options,
+> = [
+	...{
+		-readonly [FdNumber in keyof StdioOptionsArrayType]: SubprocessStdioStream<FdNumber extends string ? FdNumber : string, OptionsType>
+	},
+	...(HasIpc<OptionsType> extends true ? [null] : []),
+	...Array<Readable | Writable | null>,
+];
+
+// `subprocess.all`
+type SubprocessAll<OptionsType extends Options> = AllStream<AllIgnored<OptionsType['all'], OptionsType>>;
+
+type AllStream<IsIgnored> = IsIgnored extends true ? undefined : Readable;
+
+type AllIgnored<
+	AllOption,
+	OptionsType extends Options,
+> = AllOption extends true
+	? IgnoresSubprocessOutput<'1', OptionsType> extends true
+		? IgnoresSubprocessOutput<'2', OptionsType>
+		: false
+	: true;
+
+// Read-side iteration, stream conversion and `all` methods.
+// These are shared between a subprocess and the return value of `subprocess.pipe()`, which forwards them from its destination subprocess.
+// `writable()`, `duplex()`, `writableStream()` and `transformStream()` are not included: they write to `stdin`, which the pipe already feeds from its source.
+type SubprocessResultMethods<OptionsType extends Options = Options> = {
+	/**
+	Stream combining/interleaving `subprocess.stdout` and `subprocess.stderr`.
+
+	This requires the `all` option to be `true`.
+
+	This is `undefined` if both `stdout` and `stderr` options are set to `'inherit'`, `'ignore'`, `Writable` or `integer`.
+	*/
+	all: SubprocessAll<OptionsType>;
+
+	/**
+	Subprocesses are [async iterables](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/asyncIterator). They iterate over each output line.
+	*/
+	[Symbol.asyncIterator](): SubprocessAsyncIterable<undefined, OptionsType['encoding']>;
 
-	interface NodeOptions<EncodingType = string> extends Options<EncodingType> {
+	/**
+	Same as `subprocess[Symbol.asyncIterator]` except options can be provided.
+	*/
+	iterable<IterableOptions extends ReadableOptions = {}>(readableOptions?: IterableOptions): SubprocessAsyncIterable<IterableOptions['binary'], OptionsType['encoding']>;
+
+	/**
+	Converts the subprocess to a readable stream.
+	*/
+	readable(readableOptions?: ReadableOptions): Readable;
+
+	/**
+	Converts the subprocess to a readable [web stream](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream).
+	*/
+	readableStream(readableOptions?: ReadableOptions): ReadableStream;
+};
+
+type ExecaCustomSubprocess<OptionsType extends Options> =
+	& IpcMethods<HasIpc<OptionsType>, OptionsType['serialization']>
+	& PipableSubprocess
+	& SubprocessResultMethods<OptionsType>
+	& {
 		/**
-		The Node.js executable to use.
+		Process identifier ([PID](https://en.wikipedia.org/wiki/Process_identifier)).
 
-		@default process.execPath
+		This is `undefined` if the subprocess failed to spawn.
 		*/
-		readonly nodePath?: string;
+		pid?: number;
 
 		/**
-		List of [CLI options](https://nodejs.org/api/cli.html#cli_options) passed to the Node.js executable.
+		The subprocess [`stdin`](https://en.wikipedia.org/wiki/Standard_streams#Standard_input_(stdin)) as a stream.
 
-		@default process.execArgv
+		This is `null` if the `stdin` option is set to `'inherit'`, `'ignore'`, `Readable` or `integer`.
 		*/
-		readonly nodeOptions?: string[];
-	}
+		stdin: SubprocessStdioStream<'0', OptionsType>;
 
-	interface ExecaReturnBase<StdoutStderrType> {
 		/**
-		The file and arguments that were run, for logging purposes.
+		The subprocess [`stdout`](https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout)) as a stream.
 
-		This is not escaped and should not be executed directly as a process, including using `execa()` or `execa.command()`.
+		This is `null` if the `stdout` option is set to `'inherit'`, `'ignore'`, `Writable` or `integer`.
 		*/
-		command: string;
+		stdout: SubprocessStdioStream<'1', OptionsType>;
 
 		/**
-		Same as `command` but escaped.
+		The subprocess [`stderr`](https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr)) as a stream.
 
-		This is meant to be copy and pasted into a shell, for debugging purposes.
-		Since the escaping is fairly basic, this should not be executed directly as a process, including using `execa()` or `execa.command()`.
+		This is `null` if the `stderr` option is set to `'inherit'`, `'ignore'`, `Writable` or `integer`.
 		*/
-		escapedCommand: string;
+		stderr: SubprocessStdioStream<'2', OptionsType>;
 
 		/**
-		The numeric exit code of the process that was run.
+		The subprocess `stdin`, `stdout`, `stderr` and other files descriptors as an array of streams.
+
+		Each array item is `null` if the corresponding `stdin`, `stdout`, `stderr` or `stdio` option is set to `'inherit'`, `'ignore'`, `Stream` or `integer`.
+
+		With the `ipc` option, the last item is the subprocess' IPC channel, which is always `null`.
 		*/
-		exitCode: number;
+		stdio: SubprocessStdioArray<OptionsType>;
 
 		/**
-		The output of the process on stdout.
+		Sends a [signal](https://nodejs.org/api/os.html#signal-constants) to the subprocess. The default signal is the `killSignal` option. `killSignal` defaults to `SIGTERM`, which terminates the subprocess.
+
+		This returns `false` when the signal could not be sent, for example when the subprocess has already exited.
+
+		When an error is passed as argument, it is set to the subprocess' `error.cause`. The subprocess is then terminated with the default signal. This does not emit the [`error` event](https://nodejs.org/api/child_process.html#event-error).
+
+		[More info.](https://nodejs.org/api/child_process.html#subprocesskillsignal)
 		*/
-		stdout: StdoutStderrType;
+		kill(signal?: keyof SignalConstants | number, error?: Error): boolean;
+		kill(error?: Error): boolean;
 
 		/**
-		The output of the process on stderr.
+		Converts the subprocess to a writable stream.
 		*/
-		stderr: StdoutStderrType;
+		writable(writableOptions?: WritableOptions): Writable;
 
 		/**
-		Whether the process failed to run.
+		Converts the subprocess to a duplex stream.
 		*/
-		failed: boolean;
+		duplex(duplexOptions?: DuplexOptions): Duplex;
 
 		/**
-		Whether the process timed out.
+		Converts the subprocess to a writable [web stream](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream).
 		*/
-		timedOut: boolean;
+		writableStream(writableOptions?: WritableOptions): WritableStream;
 
 		/**
-		Whether the process was killed.
+		Converts the subprocess to a [`{readable, writable}`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) pair of web streams.
 		*/
-		killed: boolean;
+		transformStream(duplexOptions?: DuplexOptions): ReadableWritablePair;
 
 		/**
-		The name of the signal that was used to terminate the process. For example, `SIGFPE`.
+		Underlying Node.js [`ChildProcess`](https://nodejs.org/api/child_process.html#class-childprocess) instance.
 
-		If a signal terminated the process, this property is defined and included in the error message. Otherwise it is `undefined`.
+		This is an escape hatch for Node.js-specific APIs not documented by Execa, such as `.on()`, `.send()`, `.disconnect()`, `.ref()` or `.unref()`.
 		*/
-		signal?: string;
+		nodeChildProcess: ChildProcess;
+	};
 
-		/**
-		A human-friendly description of the signal that was used to terminate the process. For example, `Floating point arithmetic error`.
+/**
+Subprocess with Execa-specific methods and properties. It is also a `Promise` either resolving with its successful `result`, or rejecting with its `error`.
+*/
+type Subprocess<OptionsType extends Options = Options> =
+	& ExecaCustomSubprocess<OptionsType>
+	& Promise<Result<OptionsType>>;
 
-		If a signal terminated the process, this property is defined and included in the error message. Otherwise it is `undefined`. It is also `undefined` when the signal is very uncommon which should seldomly happen.
-		*/
-		signalDescription?: string;
-	}
+/**
+The return value of all asynchronous methods is both:
+- the subprocess with Execa-specific methods and properties.
+- a `Promise` either resolving with its successful `result`, or rejecting with its `error`.
+*/
+type ResultPromise<OptionsType extends Options = Options> =
+	Subprocess<OptionsType>;
 
-	interface ExecaSyncReturnValue<StdoutErrorType = string>
-		extends ExecaReturnBase<StdoutErrorType> {
-	}
+/**
+Executes a command using `file ...arguments`.
 
-	/**
-	Result of a child process execution. On success this is a plain object. On failure this is also an `Error` instance.
+When `command` is a template string, it includes both the `file` and its `arguments`.
 
-	The child process fails when:
-	- its exit code is not `0`
-	- it was killed with a signal
-	- timing out
-	- being canceled
-	- there's not enough memory or there are already too many child processes
-	*/
-	interface ExecaReturnValue<StdoutErrorType = string>
-		extends ExecaSyncReturnValue<StdoutErrorType> {
-		/**
-		The output of the process with `stdout` and `stderr` interleaved.
+`execa(options)` can be used to return a new instance of this method but with different default `options`. Consecutive calls are merged to previous ones.
 
-		This is `undefined` if either:
-		- the `all` option is `false` (default value)
-		- `execa.sync()` was used
-		*/
-		all?: StdoutErrorType;
+@param file - The program/script to execute, as a string or file URL
+@param arguments - Arguments to pass to `file` on execution.
+@returns A `ResultPromise` that is both:
+- the subprocess.
+- a `Promise` either resolving with its successful `result`, or rejecting with its `error`.
+@throws `ExecaError`
 
-		/**
-		Whether the process was canceled.
-		*/
-		isCanceled: boolean;
-	}
+@example <caption>Simple syntax</caption>
 
-	interface ExecaSyncError<StdoutErrorType = string>
-		extends Error,
-		ExecaReturnBase<StdoutErrorType> {
-		/**
-		Error message when the child process failed to run. In addition to the underlying error message, it also contains some information related to why the child process errored.
+```
+import {execa} from 'execa';
 
-		The child process stderr then stdout are appended to the end, separated with newlines and not interleaved.
-		*/
-		message: string;
+const {stdout} = await execa`npm run build`;
+// Print command's output
+console.log(stdout);
+```
 
-		/**
-		This is the same as the `message` property except it does not include the child process stdout/stderr.
-		*/
-		shortMessage: string;
+@example <caption>Script</caption>
 
-		/**
-		Original error message. This is the same as the `message` property except it includes neither the child process stdout/stderr nor some additional information added by Execa.
+```
+import {$} from 'execa';
 
-		This is `undefined` unless the child process exited due to an `error` event or a timeout.
-		*/
-		originalMessage?: string;
-	}
+const {stdout: name} = await $`cat package.json`.pipe`grep name`;
+console.log(name);
 
-	interface ExecaError<StdoutErrorType = string>
-		extends ExecaSyncError<StdoutErrorType> {
-		/**
-		The output of the process with `stdout` and `stderr` interleaved.
+const branch = await $`git branch --show-current`;
+await $`dep deploy --branch=${branch}`;
 
-		This is `undefined` if either:
-		- the `all` option is `false` (default value)
-		- `execa.sync()` was used
-		*/
-		all?: StdoutErrorType;
+await Promise.all([
+	$`sleep 1`,
+	$`sleep 2`,
+	$`sleep 3`,
+]);
 
-		/**
-		Whether the process was canceled.
-		*/
-		isCanceled: boolean;
-	}
+const directoryName = 'foo bar';
+await $`mkdir /tmp/${directoryName}`;
+```
 
-	interface KillOptions {
-		/**
-		Milliseconds to wait for the child process to terminate before sending `SIGKILL`.
+@example <caption>Local binaries</caption>
 
-		Can be disabled with `false`.
+```
+$ npm install -D eslint
+```
 
-		@default 5000
-		*/
-		forceKillAfterTimeout?: number | false;
-	}
+```
+await execa({preferLocal: true})`eslint`;
+```
 
-	interface ExecaChildPromise<StdoutErrorType> {
-		/**
-		Stream combining/interleaving [`stdout`](https://nodejs.org/api/child_process.html#child_process_subprocess_stdout) and [`stderr`](https://nodejs.org/api/child_process.html#child_process_subprocess_stderr).
+@example <caption>Pipe multiple subprocesses</caption>
 
-		This is `undefined` if either:
-			- the `all` option is `false` (the default value)
-			- both `stdout` and `stderr` options are set to [`'inherit'`, `'ipc'`, `Stream` or `integer`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio)
-		*/
-		all?: ReadableStream;
+```
+const {stdout, pipedFrom} = await execa`npm run build`
+	.pipe`sort`
+	.pipe`head -n 2`;
 
-		catch<ResultType = never>(
-			onRejected?: (reason: ExecaError<StdoutErrorType>) => ResultType | PromiseLike<ResultType>
-		): Promise<ExecaReturnValue<StdoutErrorType> | ResultType>;
+// Output of `npm run build | sort | head -n 2`
+console.log(stdout);
+// Output of `npm run build | sort`
+console.log(pipedFrom[0].stdout);
+// Output of `npm run build`
+console.log(pipedFrom[0].pipedFrom[0].stdout);
+```
 
-		/**
-		Same as the original [`child_process#kill()`](https://nodejs.org/api/child_process.html#child_process_subprocess_kill_signal), except if `signal` is `SIGTERM` (the default value) and the child process is not terminated after 5 seconds, force it by sending `SIGKILL`.
-		*/
-		kill(signal?: string, options?: KillOptions): void;
+@example <caption>Interleaved output</caption>
 
-		/**
-		Similar to [`childProcess.kill()`](https://nodejs.org/api/child_process.html#child_process_subprocess_kill_signal). This is preferred when cancelling the child process execution as the error is more descriptive and [`childProcessResult.isCanceled`](#iscanceled) is set to `true`.
-		*/
-		cancel(): void;
-	}
+```
+const {all} = await execa({all: true})`npm run build`;
+// stdout + stderr, interleaved
+console.log(all);
+```
+
+@example <caption>Programmatic + terminal output</caption>
+
+```
+const {stdout} = await execa({stdout: ['pipe', 'inherit']})`npm run build`;
+// stdout is also printed to the terminal
+console.log(stdout);
+```
+
+@example <caption>Simple input</caption>
+
+```
+const getInputString = () => { /* ... *\/ };
+const {stdout} = await execa({input: getInputString()})`sort`;
+console.log(stdout);
+```
+
+@example <caption>File input</caption>
+
+```
+// Similar to: npm run build < input.txt
+await execa({stdin: {file: 'input.txt'}})`npm run build`;
+```
+
+@example <caption>File output</caption>
 
-	type ExecaChildProcess<StdoutErrorType = string> = ChildProcess &
-	ExecaChildPromise<StdoutErrorType> &
-	Promise<ExecaReturnValue<StdoutErrorType>>;
+```
+// Similar to: npm run build > output.txt
+await execa({stdout: {file: 'output.txt'}})`npm run build`;
+```
+
+@example <caption>Split into text lines</caption>
+
+```
+const {stdout} = await execa({lines: true})`npm run build`;
+// Print first 10 lines
+console.log(stdout.slice(0, 10).join('\n'));
+```
+
+@example <caption>Iterate over text lines</caption>
+
+```
+for await (const line of execa`npm run build`) {
+	if (line.includes('WARN')) {
+		console.warn(line);
+	}
 }
+```
 
-declare const execa: {
-	/**
-	Execute a file.
+@example <caption>Transform/filter output</caption>
+
+```
+let count = 0;
+
+// Filter out secret lines, then prepend the line number
+const transform = function * (line) {
+	if (!line.includes('secret')) {
+		yield `[${count++}] ${line}`;
+	}
+};
 
-	Think of this as a mix of `child_process.execFile` and `child_process.spawn`.
+await execa({stdout: transform})`npm run build`;
+```
 
-	@param file - The program/script to execute.
-	@param arguments - Arguments to pass to `file` on execution.
-	@returns A [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess), which is enhanced to also be a `Promise` for a result `Object` with `stdout` and `stderr` properties.
+@example <caption>Web streams</caption>
 
-	@example
-	```
-	import execa = require('./execa');
+```
+const response = await fetch('https://example.com');
+await execa({stdin: response.body})`sort`;
+```
 
-	(async () => {
-		const {stdout} = await execa('echo', ['unicorns']);
-		console.log(stdout);
-		//=> 'unicorns'
+@example <caption>Convert to Duplex stream</caption>
 
-		// Cancelling a spawned process
+```
+import {execa} from 'execa';
+import {pipeline} from 'node:stream/promises';
+import {createReadStream, createWriteStream} from 'node:fs';
 
-		const subprocess = execa('node');
+await pipeline(
+	createReadStream('./input.txt'),
+	execa`node ./transform.js`.duplex(),
+	createWriteStream('./output.txt'),
+);
+```
 
-		setTimeout(() => {
-			subprocess.cancel()
-		}, 1000);
+@example <caption>Exchange messages</caption>
 
-		try {
-			await subprocess;
-		} catch (error) {
-			console.log(subprocess.killed); // true
-			console.log(error.isCanceled); // true
-		}
-	})();
+```
+// parent.js
+import {execaNode} from 'execa';
 
-	// Pipe the child process stdout to the current stdout
-	execa('echo', ['unicorns']).stdout.pipe(process.stdout);
-	```
-	*/
-	(
-		file: string,
-		arguments?: readonly string[],
-		options?: execa.Options
-	): execa.ExecaChildProcess;
-	(
-		file: string,
-		arguments?: readonly string[],
-		options?: execa.Options<null>
-	): execa.ExecaChildProcess<Buffer>;
-	(file: string, options?: execa.Options): execa.ExecaChildProcess;
-	(file: string, options?: execa.Options<null>): execa.ExecaChildProcess<
-	Buffer
-	>;
+const subprocess = execaNode`child.js`;
+await subprocess.sendMessage('Hello from parent');
+const message = await subprocess.getOneMessage();
+console.log(message); // 'Hello from child'
+```
 
-	/**
-	Execute a file synchronously.
+```
+// child.js
+import {getOneMessage, sendMessage} from 'execa';
 
-	This method throws an `Error` if the command fails.
+const message = await getOneMessage(); // 'Hello from parent'
+const newMessage = message.replace('parent', 'child'); // 'Hello from child'
+await sendMessage(newMessage);
+```
 
-	@param file - The program/script to execute.
-	@param arguments - Arguments to pass to `file` on execution.
-	@returns A result `Object` with `stdout` and `stderr` properties.
-	*/
-	sync(
-		file: string,
-		arguments?: readonly string[],
-		options?: execa.SyncOptions
-	): execa.ExecaSyncReturnValue;
-	sync(
-		file: string,
-		arguments?: readonly string[],
-		options?: execa.SyncOptions<null>
-	): execa.ExecaSyncReturnValue<Buffer>;
-	sync(file: string, options?: execa.SyncOptions): execa.ExecaSyncReturnValue;
-	sync(
-		file: string,
-		options?: execa.SyncOptions<null>
-	): execa.ExecaSyncReturnValue<Buffer>;
+@example <caption>Any input type</caption>
 
-	/**
-	Same as `execa()` except both file and arguments are specified in a single `command` string. For example, `execa('echo', ['unicorns'])` is the same as `execa.command('echo unicorns')`.
+```
+// main.js
+import {execaNode} from 'execa';
 
-	If the file or an argument contains spaces, they must be escaped with backslashes. This matters especially if `command` is not a constant but a variable, for example with `__dirname` or `process.cwd()`. Except for spaces, no escaping/quoting is needed.
+const ipcInput = [
+	{task: 'lint', ignore: /test\.js/},
+	{task: 'copy', files: new Set(['main.js', 'index.js']),
+}];
+await execaNode({ipcInput})`build.js`;
+```
 
-	The `shell` option must be used if the `command` uses shell-specific features (for example, `&&` or `||`), as opposed to being a simple `file` followed by its `arguments`.
+```
+// build.js
+import {getOneMessage} from 'execa';
 
-	@param command - The program/script to execute and its arguments.
-	@returns A [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess), which is enhanced to also be a `Promise` for a result `Object` with `stdout` and `stderr` properties.
+const ipcInput = await getOneMessage();
+```
 
-	@example
-	```
-	import execa = require('./execa');
+@example <caption>Any output type</caption>
 
-	(async () => {
-		const {stdout} = await execa.command('echo unicorns');
-		console.log(stdout);
-		//=> 'unicorns'
-	})();
-	```
-	*/
-	command(command: string, options?: execa.Options): execa.ExecaChildProcess;
-	command(command: string, options?: execa.Options<null>): execa.ExecaChildProcess<Buffer>;
+```
+// main.js
+import {execaNode} from 'execa';
 
-	/**
-	Same as `execa.command()` but synchronous.
+const {ipcOutput} = await execaNode`build.js`;
+console.log(ipcOutput[0]); // {kind: 'start', timestamp: date}
+console.log(ipcOutput[1]); // {kind: 'stop', timestamp: date}
+```
 
-	@param command - The program/script to execute and its arguments.
-	@returns A result `Object` with `stdout` and `stderr` properties.
-	*/
-	commandSync(command: string, options?: execa.SyncOptions): execa.ExecaSyncReturnValue;
-	commandSync(command: string, options?: execa.SyncOptions<null>): execa.ExecaSyncReturnValue<Buffer>;
+```
+// build.js
+import {sendMessage} from 'execa';
 
-	/**
-	Execute a Node.js script as a child process.
+const runBuild = () => { /* ... *\/ };
 
-	Same as `execa('node', [scriptPath, ...arguments], options)` except (like [`child_process#fork()`](https://nodejs.org/api/child_process.html#child_process_child_process_fork_modulepath_args_options)):
-		- the current Node version and options are used. This can be overridden using the `nodePath` and `nodeArguments` options.
-		- the `shell` option cannot be used
-		- an extra channel [`ipc`](https://nodejs.org/api/child_process.html#child_process_options_stdio) is passed to [`stdio`](#stdio)
+await sendMessage({kind: 'start', timestamp: new Date()});
+await runBuild();
+await sendMessage({kind: 'stop', timestamp: new Date()});
+```
 
-	@param scriptPath - Node.js script to execute.
-	@param arguments - Arguments to pass to `scriptPath` on execution.
-	@returns A [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess), which is enhanced to also be a `Promise` for a result `Object` with `stdout` and `stderr` properties.
-	*/
-	node(
-		scriptPath: string,
-		arguments?: readonly string[],
-		options?: execa.NodeOptions
-	): execa.ExecaChildProcess;
-	node(
-		scriptPath: string,
-		arguments?: readonly string[],
-		options?: execa.Options<null>
-	): execa.ExecaChildProcess<Buffer>;
-	node(scriptPath: string, options?: execa.Options): execa.ExecaChildProcess;
-	node(scriptPath: string, options?: execa.Options<null>): execa.ExecaChildProcess<Buffer>;
+@example <caption>Graceful termination</caption>
+
+```
+// main.js
+import {execaNode} from 'execa';
+
+const controller = new AbortController();
+setTimeout(() => {
+	controller.abort();
+}, 5000);
+
+await execaNode({
+	cancelSignal: controller.signal,
+	gracefulCancel: true,
+})`build.js`;
+```
+
+```
+// build.js
+import {getCancelSignal} from 'execa';
+
+const cancelSignal = await getCancelSignal();
+const url = 'https://example.com/build/info';
+const response = await fetch(url, {signal: cancelSignal});
+```
+
+@example <caption>Detailed error</caption>
+
+```
+import {execa, ExecaError} from 'execa';
+
+try {
+	await execa`unknown command`;
+} catch (error) {
+	if (error instanceof ExecaError) {
+		console.log(error);
+	}
+	/*
+	ExecaError: Command failed with ENOENT: unknown command
+	spawn unknown ENOENT
+			at ...
+			at ... {
+		shortMessage: 'Command failed with ENOENT: unknown command\nspawn unknown ENOENT',
+		originalMessage: 'spawn unknown ENOENT',
+		command: 'unknown command',
+		escapedCommand: 'unknown command',
+		cwd: '/path/to/cwd',
+		durationMs: 28.217566,
+		failed: true,
+		timedOut: false,
+		isCanceled: false,
+		isTerminated: false,
+		isMaxBuffer: false,
+		code: 'ENOENT',
+		stdout: '',
+		stderr: '',
+		stdio: [undefined, '', ''],
+		pipedFrom: []
+		[cause]: Error: spawn unknown ENOENT
+				at ...
+				at ... {
+			errno: -2,
+			code: 'ENOENT',
+			syscall: 'spawn unknown',
+			path: 'unknown',
+			spawnargs: [ 'command' ]
+		}
+	}
+	*\/
+}
+```
+
+@example <caption>Verbose mode</caption>
+
+```
+await execa`npm run build`;
+await execa`npm run test`;
+```
+
+```
+$ NODE_DEBUG=execa node build.js
+[00:57:44.581] [0] $ npm run build
+[00:57:44.653] [0]   Building application...
+[00:57:44.653] [0]   Done building.
+[00:57:44.658] [0] ✔ (done in 78ms)
+[00:57:44.658] [1] $ npm run test
+[00:57:44.740] [1]   Running tests...
+[00:57:44.740] [1]   Error: the entrypoint is invalid.
+[00:57:44.747] [1] ✘ Command failed with exit code 1: npm run test
+[00:57:44.747] [1] ✘ (done in 89ms)
+```
+
+@example <caption>Custom logging</caption>
+
+```
+import {execa as execa_} from 'execa';
+import {createLogger, transports} from 'winston';
+
+// Log to a file using Winston
+const transport = new transports.File({filename: 'logs.txt'});
+const logger = createLogger({transports: [transport]});
+const LOG_LEVELS = {
+	command: 'info',
+	output: 'verbose',
+	ipc: 'verbose',
+	error: 'error',
+	duration: 'info',
 };
 
-export = execa;
+const execa = execa_({
+	verbose(verboseLine, {message, ...verboseObject}) {
+		const level = LOG_LEVELS[verboseObject.type];
+		logger[level](message, verboseObject);
+	},
+});
+
+await execa`npm run build`;
+await execa`npm run test`;
+```
+*/
+declare const execa: ExecaMethod<{}>;
+
+/**
+`execa()` method either exported by Execa, or bound using `execa(options)`.
+*/
+type ExecaMethod<OptionsType extends Options = Options> =
+	& ExecaBind<OptionsType>
+	& ExecaTemplate<OptionsType>
+	& ExecaArrayLong<OptionsType>
+	& ExecaArrayShort<OptionsType>;
+
+// `execa(options)` binding
+type ExecaBind<OptionsType extends Options> =
+	<NewOptionsType extends Options = {}>(options: NewOptionsType)
+	=> ExecaMethod<OptionsType & NewOptionsType>;
+
+// `execa`command`` template syntax
+type ExecaTemplate<OptionsType extends Options> =
+	(...templateString: TemplateString)
+	=> ResultPromise<OptionsType>;
+
+// `execa('file', ['argument'], {})` array syntax
+type ExecaArrayLong<OptionsType extends Options> =
+	<NewOptionsType extends Options = {}>(file: string | URL, arguments?: readonly string[], options?: NewOptionsType)
+	=> ResultPromise<OptionsType & NewOptionsType>;
+
+// `execa('file', {})` array syntax
+type ExecaArrayShort<OptionsType extends Options> =
+	<NewOptionsType extends Options = {}>(file: string | URL, options?: NewOptionsType)
+	=> ResultPromise<OptionsType & NewOptionsType>;
+
+/**
+Same as `execa()` but synchronous.
+
+Returns a subprocess `result` or throws an `error`. The `subprocess` is not returned: its methods and properties are not available.
+
+When `command` is a template string, it includes both the `file` and its `arguments`.
+
+`execaSync(options)` can be used to return a new instance of this method but with different default `options`. Consecutive calls are merged to previous ones.
+
+This method is discouraged as it holds the CPU and lacks multiple features.
+
+@param file - The program/script to execute, as a string or file URL
+@param arguments - Arguments to pass to `file` on execution.
+@returns `SyncResult`
+@throws `ExecaSyncError`
+
+@example
+
+```
+import {execaSync} from 'execa';
+
+const {stdout} = execaSync`npm run build`;
+// Print command's output
+console.log(stdout);
+```
+*/
+declare const execaSync: ExecaSyncMethod<{}>;
+
+// For the moment, we purposely do not export `ExecaSyncMethod` and `ExecaScriptSyncMethod`.
+// This is because synchronous invocation is discouraged.
+type ExecaSyncMethod<OptionsType extends SyncOptions = SyncOptions> =
+	& ExecaSyncBind<OptionsType>
+	& ExecaSyncTemplate<OptionsType>
+	& ExecaSyncArrayLong<OptionsType>
+	& ExecaSyncArrayShort<OptionsType>;
+
+// `execaSync(options)` binding
+type ExecaSyncBind<OptionsType extends SyncOptions> =
+	<NewOptionsType extends SyncOptions = {}>(options: NewOptionsType)
+	=> ExecaSyncMethod<OptionsType & NewOptionsType>;
+
+// `execaSync`command`` template syntax
+type ExecaSyncTemplate<OptionsType extends SyncOptions> =
+	(...templateString: TemplateString)
+	=> SyncResult<OptionsType>;
+
+// `execaSync('file', ['argument'], {})` array syntax
+type ExecaSyncArrayLong<OptionsType extends SyncOptions> =
+	<NewOptionsType extends SyncOptions = {}>(file: string | URL, arguments?: readonly string[], options?: NewOptionsType)
+	=> SyncResult<OptionsType & NewOptionsType>;
+
+// `execaSync('file', {})` array syntax
+type ExecaSyncArrayShort<OptionsType extends SyncOptions> =
+	<NewOptionsType extends SyncOptions = {}>(file: string | URL, options?: NewOptionsType)
+	=> SyncResult<OptionsType & NewOptionsType>;
+
+/**
+Split a `command` string into an array. For example, `'npm run build'` returns `['npm', 'run', 'build']` and `'argument otherArgument'` returns `['argument', 'otherArgument']`.
+
+@param command - The file to execute and/or its arguments.
+@returns fileOrArgument[]
+
+@example
+```
+import {execa, parseCommandString} from 'execa';
+
+const commandString = 'npm run task';
+const commandArray = parseCommandString(commandString);
+await execa`${commandArray}`;
+
+const [file, ...commandArguments] = commandArray;
+await execa(file, commandArguments);
+```
+*/
+declare function parseCommandString(command: string): string[];
+
+/**
+Same as `execa()` but using script-friendly default options.
+
+When `command` is a template string, it includes both the `file` and its `arguments`.
+
+`$(options)` can be used to return a new instance of this method but with different default `options`. Consecutive calls are merged to previous ones.
+
+This is the preferred method when executing multiple commands in a script file.
+
+@returns A `ResultPromise` that is both:
+- the subprocess.
+- a `Promise` either resolving with its successful `result`, or rejecting with its `error`.
+@throws `ExecaError`
+
+@example <caption>Basic</caption>
+```
+import {$} from 'execa';
+
+const branch = await $`git branch --show-current`;
+await $`dep deploy --branch=${branch}`;
+```
+
+@example <caption>Verbose mode</caption>
+```
+$ node build.js
+Building application...
+Done building.
+Running tests...
+Error: the entrypoint is invalid.
+
+$ NODE_DEBUG=execa node build.js
+[00:57:44.581] [0] $ npm run build
+[00:57:44.653] [0]   Building application...
+[00:57:44.653] [0]   Done building.
+[00:57:44.658] [0] ✔ (done in 78ms)
+[00:57:44.658] [1] $ npm run test
+[00:57:44.740] [1]   Running tests...
+[00:57:44.740] [1]   Error: the entrypoint is invalid.
+[00:57:44.747] [1] ✘ Command failed with exit code 1: npm run test
+[00:57:44.747] [1] ✘ (done in 89ms)
+```
+*/
+declare const $: ExecaScriptMethod<{}>;
+
+/**
+`$()` method either exported by Execa, or bound using `$(options)`.
+*/
+type ExecaScriptMethod<OptionsType extends CommonOptions = CommonOptions> =
+	& ExecaScriptBind<OptionsType>
+	& ExecaScriptTemplate<OptionsType>
+	& ExecaScriptArrayLong<OptionsType>
+	& ExecaScriptArrayShort<OptionsType>
+	& {sync: ExecaScriptSyncMethod<OptionsType>}
+	& {s: ExecaScriptSyncMethod<OptionsType>};
+
+// `$(options)` binding
+type ExecaScriptBind<OptionsType extends CommonOptions> =
+	<NewOptionsType extends Options = {}>(options: NewOptionsType)
+	=> ExecaScriptMethod<OptionsType & NewOptionsType>;
+
+// `$`command`` template syntax
+type ExecaScriptTemplate<OptionsType extends CommonOptions> =
+	(...templateString: TemplateString)
+	=> ResultPromise<StricterOptions<OptionsType, Options>>;
+
+// `$('file', ['arg'], {})` array syntax
+type ExecaScriptArrayLong<OptionsType extends CommonOptions> =
+	<NewOptionsType extends Options = {}>(file: string | URL, arguments?: readonly string[], options?: NewOptionsType)
+	=> ResultPromise<StricterOptions<OptionsType & NewOptionsType, Options>>;
+
+// `$('file', {})` array syntax
+type ExecaScriptArrayShort<OptionsType extends CommonOptions> =
+	<NewOptionsType extends Options = {}>(file: string | URL, options?: NewOptionsType)
+	=> ResultPromise<StricterOptions<OptionsType & NewOptionsType, Options>>;
+
+// We must intersect the overloaded methods with & instead of using a simple object as a workaround for a TypeScript bug
+// See https://github.com/microsoft/TypeScript/issues/58765
+/**
+`$.sync()` method either exported by Execa, or bound using `$.sync(options)`.
+*/
+type ExecaScriptSyncMethod<OptionsType extends CommonOptions = CommonOptions> =
+	& ExecaScriptSyncBind<OptionsType>
+	& ExecaScriptSyncTemplate<OptionsType>
+	& ExecaScriptSyncArrayLong<OptionsType>
+	& ExecaScriptSyncArrayShort<OptionsType>;
+
+// `$.sync(options)` binding
+type ExecaScriptSyncBind<OptionsType extends CommonOptions> =
+	<NewOptionsType extends SyncOptions = {}>(options: NewOptionsType)
+	=> ExecaScriptSyncMethod<OptionsType & NewOptionsType>;
+
+// $.sync`command` template syntax
+type ExecaScriptSyncTemplate<OptionsType extends CommonOptions> =
+	(...templateString: TemplateString)
+	=> SyncResult<StricterOptions<OptionsType, SyncOptions>>;
+
+// `$.sync('file', ['arg'], {})` array syntax
+type ExecaScriptSyncArrayLong<OptionsType extends CommonOptions> =
+	<NewOptionsType extends SyncOptions = {}>(file: string | URL, arguments?: readonly string[], options?: NewOptionsType)
+	=> SyncResult<StricterOptions<OptionsType & NewOptionsType, SyncOptions>>;
+
+// `$.sync('file', {})` array syntax
+type ExecaScriptSyncArrayShort<OptionsType extends CommonOptions> =
+	<NewOptionsType extends SyncOptions = {}>(file: string | URL, options?: NewOptionsType)
+	=> SyncResult<StricterOptions<OptionsType & NewOptionsType, SyncOptions>>;
+
+/**
+Same as `execa()` but using the `node: true` option.
+Executes a Node.js file using `node scriptPath ...arguments`.
+
+When `command` is a template string, it includes both the `file` and its `arguments`.
+
+`execaNode(options)` can be used to return a new instance of this method but with different default `options`. Consecutive calls are merged to previous ones.
+
+This is the preferred method when executing Node.js files.
+
+@param scriptPath - Node.js script to execute, as a string or file URL
+@param arguments - Arguments to pass to `scriptPath` on execution.
+@returns A `ResultPromise` that is both:
+- the subprocess.
+- a `Promise` either resolving with its successful `result`, or rejecting with its `error`.
+@throws `ExecaError`
+
+@example
+```
+import {execaNode, execa} from 'execa';
+
+await execaNode`file.js argument`;
+// Is the same as:
+await execa({node: true})`file.js argument`;
+// Or:
+await execa`node file.js argument`;
+```
+*/
+declare const execaNode: ExecaNodeMethod<{}>;
+
+/**
+`execaNode()` method either exported by Execa, or bound using `execaNode(options)`.
+*/
+type ExecaNodeMethod<OptionsType extends Options = Options> =
+	& ExecaNodeBind<OptionsType>
+	& ExecaNodeTemplate<OptionsType>
+	& ExecaNodeArrayLong<OptionsType>
+	& ExecaNodeArrayShort<OptionsType>;
+
+// `execaNode(options)` binding
+type ExecaNodeBind<OptionsType extends Options> =
+	<NewOptionsType extends Options = {}>(options: NewOptionsType)
+	=> ExecaNodeMethod<OptionsType & NewOptionsType>;
+
+// `execaNode`command`` template syntax
+type ExecaNodeTemplate<OptionsType extends Options> =
+	(...templateString: TemplateString)
+	=> ResultPromise<NodeOptions<OptionsType>>;
+
+// `execaNode('script', ['argument'], {})` array syntax
+type ExecaNodeArrayLong<OptionsType extends Options> =
+	<NewOptionsType extends Options = {}>(scriptPath: string | URL, arguments?: readonly string[], options?: NewOptionsType)
+	=> ResultPromise<NodeOptions<OptionsType & NewOptionsType>>;
+
+// `execaNode('script', {})` array syntax
+type ExecaNodeArrayShort<OptionsType extends Options> =
+	<NewOptionsType extends Options = {}>(scriptPath: string | URL, options?: NewOptionsType)
+	=> ResultPromise<NodeOptions<OptionsType & NewOptionsType>>;
+
+// `execaNode()` always uses the `node` option, which also enables the `ipc` option by default
+type NodeOptions<OptionsType extends Options> = OptionsType & {readonly node: true};
+
+export { $, ExecaError, ExecaSyncError, execa, execaNode, execaSync, getCancelSignal, getEachMessage, getOneMessage, parseCommandString, sendMessage };
+export type { ExecaMethod, ExecaNodeMethod, ExecaScriptMethod, ExecaScriptSyncMethod, ExecaSyncMethod, Message, Options, Result, ResultPromise, StdinOption, StdinSyncOption, StdoutStderrOption, StdoutStderrSyncOption, Subprocess, SyncOptions, SyncResult, SyncVerboseObject, TemplateExpression, VerboseObject };