storybook 10.2.0-alpha.8 → 10.2.0-beta.0

package/dist/common/index.d.ts

@@ -2,9 +2,10 @@ import * as storybook_internal_types from 'storybook/internal/types';
 import { CLIOptions, LoadOptions, BuilderOptions, StorybookConfigRaw, PresetConfig, CoreCommon_ResolvedAddonPreset, CoreCommon_ResolvedAddonVirtual, LoadedPreset, Presets, CoreCommon_AddonInfo, SupportedFramework, SupportedRenderer, SupportedBuilder, Options as Options$2, CoreWebpackCompiler, CoreCommon_StorybookInfo, Ref, StorybookConfig, StoriesEntry, NormalizedStoriesSpecifier, PackageJson } from 'storybook/internal/types';
 export { PackageJson } from 'storybook/internal/types';
 import { WriteStream } from 'node:fs';
-import { Buffer } from 'node:buffer';
 import { ChildProcess } from 'node:child_process';
-import { Readable, Writable, Stream } from 'node:stream';
+import { SignalConstants } from 'node:os';
+import { Duplex, Readable, Writable } from 'node:stream';
+import { TransformStream, ReadableStream, WritableStream } from 'node:stream/web';
 import { ConfigFile } from 'storybook/internal/csf-tools';
 import { types } from 'storybook/internal/babel';
 
@@ -581,527 +582,1570 @@ declare function normalizeStoryPath(filename: string): string;
 
 declare function readTemplate(filename: string): Promise<string>;
 
-type StdioOption =
-	| 'pipe'
-	| 'overlapped'
-	| 'ipc'
+type Not<Value extends boolean> = Value extends true ? false : true;
+
+type And<First extends boolean, Second extends boolean> = First extends true ? Second : false;
+
+type Or<First extends boolean, Second extends boolean> = First extends true ? true : Second;
+
+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`
+// @todo Use `string`, `Uint8Array` or `unknown` for both the argument and the return type, based on whether `encoding: 'buffer'` and `objectMode: true` are used.
+// See https://github.com/sindresorhus/execa/issues/694
+type GeneratorTransform<IsSync extends boolean> = (chunk: unknown) =>
+| Unless<IsSync, AsyncGenerator<unknown, void, void>>
+| Generator<unknown, void, void>;
+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 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> = {
+	/**
+	Map or filter the input or output of the subprocess.
+	*/
+	readonly transform: GeneratorTransform<IsSync>;
+
+	/**
+	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 produces a single line.
+	*/
+	readonly preserveNewlines?: boolean;
+} & TransformCommon;
+
+// `options.std*: Duplex`
+type DuplexTransform = {
+	readonly transform: Duplex;
+} & TransformCommon;
+
+// `options.std*: TransformStream`
+type WebTransform = {
+	readonly transform: TransformStream;
+} & TransformCommon;
+
+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'
-	| Stream
+	| 'ipc'
 	| number
-	| undefined;
+	| Readable
+	| Writable
+	| Unless<IsStandardStream<FdNumber>, undefined>
+	| readonly [NoStreamStdioOption<FdNumber>];
+
+// `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'>;
+
+// Values available in both `options.stdin|stdio` and `options.stdout|stderr|stdio`
+type CommonStdioOption<
+	IsSync extends boolean,
+	IsExtra extends boolean,
+	IsArray extends boolean,
+> =
+	| SimpleStdioOption<IsSync, IsExtra, IsArray>
+	| URL
+	| {readonly file: string; readonly append?: boolean}
+	| GeneratorTransform<IsSync>
+	| GeneratorTransformFull<IsSync>
+	| Unless<And<Not<IsSync>, IsArray>, 3 | 4 | 5 | 6 | 7 | 8 | 9>
+	| Unless<Or<IsSync, IsArray>, 'ipc'>
+	| Unless<IsSync, DuplexTransform | WebTransform | TransformStream>;
+
+// Synchronous iterables excluding strings, Uint8Arrays and Arrays
+type IterableObject<IsArray extends boolean> = Iterable<unknown>
+& object
+& {readonly BYTES_PER_ELEMENT?: never}
+& AndUnless<IsArray, {readonly lastIndexOf?: 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,
+> =
+	| CommonStdioOption<IsSync, IsExtra, IsArray>
+	| InputStdioOption<IsSync, IsExtra, IsArray>;
+
+// `options.stdin`
+type StdinOptionCommon<
+	IsSync extends boolean = boolean,
+	IsExtra extends boolean = boolean,
+> =
+	| StdinSingleOption<IsSync, IsExtra, false>
+	| ReadonlyArray<StdinSingleOption<IsSync, IsExtra, true>>;
+
+// `options.stdout|stderr` array items
+type StdoutStderrSingleOption<
+	IsSync extends boolean,
+	IsExtra extends boolean,
+	IsArray extends boolean,
+> =
+  | CommonStdioOption<IsSync, IsExtra, IsArray>
+  | OutputStdioOption<IsSync, IsArray>;
+
+// `options.stdout|stderr`
+type StdoutStderrOptionCommon<
+	IsSync extends boolean = boolean,
+	IsExtra extends boolean = boolean,
+> =
+	| StdoutStderrSingleOption<IsSync, IsExtra, false>
+	| ReadonlyArray<StdoutStderrSingleOption<IsSync, IsExtra, true>>;
+
+// `options.stdio[3+]`
+type StdioExtraOptionCommon<IsSync extends boolean> =
+	| StdinOptionCommon<IsSync, true>
+	| StdoutStderrOptionCommon<IsSync, true>;
+
+// `options.stdin|stdout|stderr|stdio` array items
+type StdioSingleOption<
+	IsSync extends boolean = boolean,
+	IsExtra extends boolean = boolean,
+	IsArray extends boolean = boolean,
+> =
+	| StdinSingleOption<IsSync, IsExtra, IsArray>
+	| StdoutStderrSingleOption<IsSync, IsExtra, IsArray>;
+
+// 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> =
+	| StdinOptionCommon<IsSync>
+	| StdoutStderrOptionCommon<IsSync>;
+
+// `options.stdio` when it is an array
+type StdioOptionsArray<IsSync extends boolean = boolean> = readonly [
+	StdinOptionCommon<IsSync, false>,
+	StdoutStderrOptionCommon<IsSync, false>,
+	StdoutStderrOptionCommon<IsSync, false>,
+	...ReadonlyArray<StdioExtraOptionCommon<IsSync>>,
+];
+
+// `options.stdio`
+type StdioOptionsProperty<IsSync extends boolean = boolean> =
+	| SimpleStdioOption<IsSync, false, false>
+	| StdioOptionsArray<IsSync>;
+
+// Message when the `serialization` option is `'advanced'`
+type AdvancedMessage =
+	| string
+	| number
+	| boolean
+	| null
+	| object;
 
-type EncodingOption =
-  | 'utf8'
-  // eslint-disable-next-line unicorn/text-encoding-identifier-case
-  | 'utf-8'
-  | 'utf16le'
-  | 'utf-16le'
-  | 'ucs2'
-  | 'ucs-2'
-  | 'latin1'
-  | 'binary'
-  | 'ascii'
+// 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;
+};
+
+/**
+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;
+};
+
+/**
+Options to `getEachMessage()` and `subprocess.getEachMessage()`
+*/
+type GetEachMessageOptions = {
+	/**
+	Keep the subprocess alive while `getEachMessage()` is waiting.
+
+	@default true
+	*/
+	readonly reference?: boolean;
+};
+
+// 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`, `ipcInput` and `gracefulCancel` options
+type HasIpc<OptionsType extends Options> = HasIpcOption<
+OptionsType['ipc'],
+'ipcInput' extends keyof OptionsType ? OptionsType['ipcInput'] : undefined,
+'gracefulCancel' extends keyof OptionsType ? OptionsType['gracefulCancel'] : undefined
+>;
+
+type HasIpcOption<
+	IpcOption extends Options['ipc'],
+	IpcInputOption extends Options['ipcInput'],
+	GracefulCancelOption extends Options['gracefulCancel'],
+> = IpcOption extends true
+	? true
+	: IpcOption extends false
+		? false
+		: 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 [FdName in 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 '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}`
+			: 'ipc' extends GenericOptionKeys
+				? 'ipc'
+				: never;
+
+// `result.*` defined only on failure, i.e. on `error.*`
+type ErrorProperties =
+  | 'name'
+  | 'message'
+  | 'stack'
+  | 'cause'
+  | 'shortMessage'
+  | 'originalMessage'
+  | 'code';
+
+// `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;
+
+// Whether `result.stdio[FdNumber]` is an input stream
+type IsInputFd<
+	FdNumber extends string,
+	OptionsType extends CommonOptions,
+> = FdNumber extends '0'
+	? true
+	: Intersects<StdioSingleOptionItems<FdStdioArrayOption<FdNumber, OptionsType>>, InputStdioOption>;
+
+// Whether `result.stdin|stdout|stderr|all|stdio[*]` is `undefined`
+type IgnoresResultOutput<
+	FdNumber extends string,
+	OptionsType extends CommonOptions,
+> = FdSpecificOption<OptionsType['buffer'], FdNumber> extends false
+	? true
+	: IsInputFd<FdNumber, OptionsType> 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'
-  | 'buffer'
-  | null
-  | undefined;
-type DefaultEncodingOption = 'utf8';
+  | 'latin1'
+  | 'ascii';
+
+// `options.encoding`
+type EncodingOption =
+	| TextEncodingOption
+	| BinaryEncodingOption
+	| undefined;
 
-type CommonOptions<EncodingType extends EncodingOption = DefaultEncodingOption> = {
+// `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<OptionsType extends CommonOptions> =
+	MapResultStdio<StdioOptionNormalizedArray<OptionsType>, OptionsType>;
+
+type MapResultStdio<
+	StdioOptionsArrayType,
+	OptionsType extends CommonOptions,
+> = {
+	-readonly [FdNumber in keyof StdioOptionsArrayType]: ResultStdioNotAll<
+	FdNumber extends string ? FdNumber : string,
+	OptionsType
+	>
+};
+
+// `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,
+> {
 	/**
-	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
+	The output of the subprocess on [`stdout`](https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout)).
 
-	@default true
+	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.
 	*/
-	readonly cleanup?: boolean;
+	stdout: ResultStdioNotAll<'1', OptionsType>;
 
 	/**
-	Prefer locally installed binaries when looking for a binary to execute.
+	The output of the subprocess on [`stderr`](https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr)).
 
-	If you `$ npm install foo`, you can then `execa('foo')`.
+	This is `undefined` if the `stderr` option is set to only `'inherit'`, `'ignore'`, `Writable` or `integer`, or if the `buffer` option is `false`.
 
-	@default `true` with `$`, `false` otherwise
+	This is an array if the `lines` option is `true`, or if the `stderr` option is a transform in object mode.
 	*/
-	readonly preferLocal?: boolean;
+	stderr: ResultStdioNotAll<'2', OptionsType>;
 
 	/**
-	Preferred path to find locally installed binaries in (use with `preferLocal`).
+	The output of the subprocess with `result.stdout` and `result.stderr` interleaved.
 
-	@default process.cwd()
+	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`.
+
+	This is an array if the `lines` option is `true`, or if either the `stdout` or `stderr` option is a transform in object mode.
 	*/
-	readonly localDir?: string | URL;
+	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`.
+
+	Items are arrays when their corresponding `stdio` option is a transform in object mode.
+	*/
+	stdio: ResultStdioArray<OptionsType>;
 
 	/**
-	Path to the Node.js executable to use in child processes.
+	All the messages sent by the subprocess to the current process.
 
-	This can be either an absolute path or a path relative to the `cwd` option.
+	This is empty unless the `ipc` option is `true`. Also, this is empty if the `buffer` option is `false`.
+	*/
+	ipcOutput: ResultIpcOutput<IsSync, OptionsType>;
 
-	Requires `preferLocal` to be `true`.
+	/**
+	Results of the other subprocesses that were piped into this subprocess.
 
-	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.
+	This array is initially empty and is populated each time the `subprocess.pipe()` method resolves.
+	*/
+	pipedFrom: Unless<IsSync, Result[], []>;
 
-	@default process.execPath
+	/**
+	The file and arguments that were run.
 	*/
-	readonly execPath?: string;
+	command: string;
 
 	/**
-	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.
+	Same as `command` but escaped.
+	*/
+	escapedCommand: string;
 
-	If the spawned process fails, `error.stdout`, `error.stderr`, and `error.all` will contain the buffered data.
+	/**
+	The current directory in which the command was run.
+	*/
+	cwd: string;
 
-	@default true
+	/**
+	Duration of the subprocess, in milliseconds.
 	*/
-	readonly buffer?: boolean;
+	durationMs: number;
 
 	/**
-	Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio).
+	Whether the subprocess failed to run.
 
-	@default `inherit` with `$`, `pipe` otherwise
+	When this is `true`, the result is an `ExecaError` instance with additional error-related properties.
 	*/
-	readonly stdin?: StdioOption;
+	failed: boolean;
 
 	/**
-	Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio).
+	Whether the subprocess timed out due to the `timeout` option.
+	*/
+	timedOut: boolean;
 
-	@default 'pipe'
+	/**
+	Whether the subprocess was canceled using the `cancelSignal` option.
 	*/
-	readonly stdout?: StdioOption;
+	isCanceled: boolean;
 
 	/**
-	Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio).
+	Whether the subprocess was canceled using both the `cancelSignal` and the `gracefulCancel` options.
+	*/
+	isGracefullyCanceled: boolean;
 
-	@default 'pipe'
+	/**
+	Whether the subprocess failed because its output was larger than the `maxBuffer` option.
 	*/
-	readonly stderr?: StdioOption;
+	isMaxBuffer: boolean;
 
 	/**
-	Setting this to `false` resolves the promise with the error instead of rejecting it.
+	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;
 
-	@default true
+	/**
+	Whether the subprocess was terminated by the `SIGKILL` signal sent by the `forceKillAfterDelay` option.
 	*/
-	readonly reject?: boolean;
+	isForcefullyTerminated: boolean;
 
 	/**
-	Add an `.all` property on the promise and the resolved value. The property contains the output of the process with `stdout` and `stderr` interleaved.
+	The numeric [exit code](https://en.wikipedia.org/wiki/Exit_status) of the subprocess that was run.
 
-	@default false
+	This is `undefined` when the subprocess could not be spawned or was terminated by a signal.
 	*/
-	readonly all?: boolean;
+	exitCode?: number;
 
 	/**
-	Strip the final [newline character](https://en.wikipedia.org/wiki/Newline) from the output.
+	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).
 
-	@default true
+	If a signal terminated the subprocess, this property is defined and included in the error message. Otherwise it is `undefined`.
 	*/
-	readonly stripFinalNewline?: boolean;
+	signal?: keyof SignalConstants;
 
 	/**
-	Set to `false` if you don't want to extend the environment variables when providing the `env` property.
+	A human-friendly description of the signal that was used to terminate the subprocess.
 
-	@default true
+	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.
 	*/
-	readonly extendEnv?: boolean;
+	signalDescription?: string;
 
 	/**
-	Current working directory of the child process.
+	Error message when the subprocess failed to run.
+	*/
+	message?: string;
 
-	@default process.cwd()
+	/**
+	This is the same as `error.message` except it does not include the subprocess output.
 	*/
-	readonly cwd?: string | URL;
+	shortMessage?: string;
 
 	/**
-	Environment key-value pairs. Extends automatically from `process.env`. Set `extendEnv` to `false` if you don't want this.
+	Original error message. This is the same as `error.message` excluding the subprocess output and some additional information added by Execa.
 
-	@default process.env
+	This exists only in specific instances, such as during a timeout.
 	*/
-	readonly env?: NodeJS.ProcessEnv;
+	originalMessage?: string;
 
 	/**
-	Explicitly set the value of `argv[0]` sent to the child process. This will be set to `command` or `file` if not specified.
+	Underlying error, if there is one. For example, this is set by `subprocess.kill(error)`.
+
+	This is usually an `Error` instance.
 	*/
-	readonly argv0?: string;
+	cause?: unknown;
 
 	/**
-	Child's [stdio](https://nodejs.org/api/child_process.html#child_process_options_stdio) configuration.
+	Node.js-specific [error code](https://nodejs.org/api/errors.html#errorcode), when available.
+	*/
+	code?: string;
 
-	@default 'pipe'
+	// 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']> = {
+	[ErrorProperty in 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
 	*/
-	readonly stdio?: 'pipe' | 'overlapped' | 'ignore' | 'inherit' | readonly StdioOption[];
+	type: 'command' | 'output' | 'ipc' | 'error' | 'duration';
 
 	/**
-	Specify the kind of serialization used for sending messages between processes when using the `stdio: 'ipc'` option or `execaNode()`:
-		- `json`: Uses `JSON.stringify()` and `JSON.parse()`.
-		- `advanced`: Uses [`v8.serialize()`](https://nodejs.org/api/v8.html#v8_v8_serialize_value)
+	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`
+	*/
+	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'`.
 
-	[More info.](https://nodejs.org/api/child_process.html#child_process_advanced_serialization)
+	This is helpful when multiple subprocesses are running at the same time.
 
-	@default 'json'
+	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.
 	*/
-	readonly serialization?: 'json' | 'advanced';
+	commandId: string;
 
 	/**
-	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).
+	Event date/time.
+	*/
+	timestamp: Date;
 
-	@default false
+	/**
+	Whether another subprocess is piped into this subprocess. This is `false` when `result.pipedFrom` is empty.
 	*/
-	readonly detached?: boolean;
+	piped: boolean;
+};
 
+type MinimalVerboseObject = GenericVerboseObject & {
+	// We cannot use the `CommonOptions` type because it would make this type recursive
+	options: object;
+	result?: never;
+};
+
+type CommonOptions<IsSync extends boolean = boolean> = {
 	/**
-	Sets the user identity of the process.
+	Prefer locally installed binaries when looking for a binary to execute.
+
+	@default `true` with `$`, `false` otherwise
 	*/
-	readonly uid?: number;
+	readonly preferLocal?: boolean;
 
 	/**
-	Sets the group identity of the process.
+	Preferred path to find locally installed binaries, when using the `preferLocal` option.
+
+	@default `cwd` option
 	*/
-	readonly gid?: number;
+	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 `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.
+	If `true`, runs the command inside of a [shell](https://en.wikipedia.org/wiki/Shell_(computing)).
 
-	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.
+	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;
+	readonly shell?: boolean | string | URL;
 
 	/**
-	Specify the character encoding used to decode the `stdout` and `stderr` output. If set to `'buffer'` or `null`, then `stdout` and `stderr` will be a `Buffer` instead of a string.
+	Current [working directory](https://en.wikipedia.org/wiki/Working_directory) of the subprocess.
 
-	@default 'utf8'
+	This is also used to resolve the `nodePath` option when it is a relative path.
+
+	@default process.cwd()
 	*/
-	readonly encoding?: EncodingType;
+	readonly cwd?: string | URL;
 
 	/**
-	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.
+	[Environment variables](https://en.wikipedia.org/wiki/Environment_variable).
 
-	@default 0
+	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 [process.env](https://nodejs.org/api/process.html#processenv)
 	*/
-	readonly timeout?: number;
+	readonly env?: Readonly<Partial<Record<string, string>>>;
 
 	/**
-	Largest amount of data in bytes allowed on `stdout` or `stderr`. Default: 100 MB.
+	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`.
 
-	@default 100_000_000
+	@default true
 	*/
-	readonly maxBuffer?: number;
+	readonly extendEnv?: boolean;
 
 	/**
-	Signal value to be used when the spawned process will be killed.
+	Write some input to the subprocess' [`stdin`](https://en.wikipedia.org/wiki/Standard_streams#Standard_input_(stdin)).
 
-	@default 'SIGTERM'
+	See also the `inputFile` and `stdin` options.
 	*/
-	readonly killSignal?: string | number;
+	readonly input?: string | Uint8Array | Readable;
 
 	/**
-	You can abort the spawned process using [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController).
+	Use a file as input to the subprocess' [`stdin`](https://en.wikipedia.org/wiki/Standard_streams#Standard_input_(stdin)).
 
-	When `AbortController.abort()` is called, [`.isCanceled`](https://github.com/sindresorhus/execa#iscanceled) becomes `true`.
+	See also the `input` and `stdin` options.
+	*/
+	readonly inputFile?: string | URL;
 
-	@example
-	```
-	import {execa} from 'execa';
+	/**
+	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`.
 
-	const abortController = new AbortController();
-	const subprocess = execa('node', [], {signal: abortController.signal});
+	This can be an array of values such as `['inherit', 'pipe']` or `[fileUrl, 'pipe']`.
 
-	setTimeout(() => {
-		abortController.abort();
-	}, 1000);
+	@default `'inherit'` with `$`, `'pipe'` otherwise
+	*/
+	readonly stdin?: StdinOptionCommon<IsSync>;
 
-	try {
-		await subprocess;
-	} catch (error) {
-		console.log(subprocess.killed); // true
-		console.log(error.isCanceled); // true
-	}
-	```
+	/**
+	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>;
+
+	/**
+	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 signal?: AbortSignal;
+	readonly stderr?: StdoutStderrOptionCommon<IsSync>;
 
 	/**
-	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`.
+	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>;
+
+	/**
+	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 windowsVerbatimArguments?: boolean;
+	readonly all?: boolean;
 
 	/**
-	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.
+	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).
 
-	@default true
+	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#URL_applications), [`'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`.
+
+	@default 'utf8'
 	*/
-	readonly windowsHide?: boolean;
+	readonly encoding?: EncodingOption;
 
 	/**
-	Print each command on `stderr` before executing it.
+	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.
 
-	This can also be enabled by setting the `NODE_DEBUG=execa` environment variable in the current process.
+	By default, this applies to both `stdout` and `stderr`, but different values can also be passed.
 
 	@default false
 	*/
-	readonly verbose?: boolean;
-};
+	readonly lines?: FdGenericOption<boolean>;
 
-type Options<EncodingType extends EncodingOption = DefaultEncodingOption> = {
 	/**
-	Write some input to the `stdin` of your binary.
+	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.
 
-	If the input is a file, use the `inputFile` option instead.
+	By default, this applies to both `stdout` and `stderr`, but different values can also be passed.
+
+	@default true
 	*/
-	readonly input?: string | Buffer | Readable;
+	readonly stripFinalNewline?: FdGenericOption<boolean>;
 
 	/**
-	Use a file as input to the the `stdin` of your binary.
+	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.
+
+	When reached, `error.isMaxBuffer` becomes `true`.
 
-	If the input is not a file, use the `input` option instead.
+	@default 100_000_000
 	*/
-	readonly inputFile?: string;
-} & CommonOptions<EncodingType>;
+	readonly maxBuffer?: FdGenericOption<number>;
 
-type NodeOptions<EncodingType extends EncodingOption = DefaultEncodingOption> = {
 	/**
-	The Node.js executable to use.
+	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 process.execPath
+	@default true
 	*/
-	readonly nodePath?: string;
+	readonly buffer?: FdGenericOption<boolean>;
 
 	/**
-	List of [CLI options](https://nodejs.org/api/cli.html#cli_options) passed to the Node.js executable.
+	Enables exchanging messages with the subprocess using `subprocess.sendMessage(message)`, `subprocess.getOneMessage()` and `subprocess.getEachMessage()`.
 
-	@default process.execArgv
+	The subprocess must be a Node.js file.
+
+	@default `true` if the `node`, `ipcInput` or `gracefulCancel` option is set, `false` otherwise
 	*/
-	readonly nodeOptions?: string[];
-} & Options<EncodingType>;
+	readonly ipc?: Unless<IsSync, boolean>;
+
+	/**
+	Specify the kind of serialization used for sending messages between subprocesses when using the `ipc` option.
 
-type StdoutStderrAll = string | Buffer | undefined;
+	@default 'advanced'
+	*/
+	readonly serialization?: Unless<IsSync, 'json' | 'advanced'>;
 
-type ExecaReturnBase<StdoutStderrType extends StdoutStderrAll> = {
 	/**
-	The file and arguments that were run, for logging purposes.
+	Sends an IPC message when the subprocess starts.
 
-	This is not escaped and should not be executed directly as a process, including using `execa()` or `execaCommand()`.
+	The subprocess must be a Node.js file. The value's type depends on the `serialization` option.
 	*/
-	command: string;
+	readonly ipcInput?: Unless<IsSync, Message>;
 
 	/**
-	Same as `command` but escaped.
+	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.
 
-	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 `execaCommand()`.
+	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.
+
+	A function can be passed to customize logging.
+
+	By default, this applies to both `stdout` and `stderr`, but different values can also be passed.
+
+	@default 'none'
 	*/
-	escapedCommand: string;
+	readonly verbose?: VerboseOption;
 
 	/**
-	The numeric exit code of the process that was run.
+	Setting this to `false` resolves the result's promise with the error instead of rejecting it.
+
+	@default true
 	*/
-	exitCode: number;
+	readonly reject?: boolean;
 
 	/**
-	The output of the process on stdout.
+	If `timeout` is greater than `0`, the subprocess will be terminated if it runs for longer than that amount of milliseconds.
+
+	On timeout, `error.timedOut` becomes `true`.
+
+	@default 0
 	*/
-	stdout: StdoutStderrType;
+	readonly timeout?: number;
 
 	/**
-	The output of the process on stderr.
+	When the `cancelSignal` is [aborted](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort), terminate the subprocess using a `SIGTERM` signal.
+
+	When aborted, `error.isCanceled` becomes `true`.
+
+	@example
+	```
+	import {execaNode} from 'execa';
+
+	const controller = new AbortController();
+	const cancelSignal = controller.signal;
+
+	setTimeout(() => {
+		controller.abort();
+	}, 5000);
+
+	try {
+		await execaNode({cancelSignal})`build.js`;
+	} catch (error) {
+		if (error.isCanceled) {
+			console.error('Canceled by cancelSignal.');
+		}
+
+		throw error;
+	}
+	```
 	*/
-	stderr: StdoutStderrType;
+	readonly cancelSignal?: Unless<IsSync, AbortSignal>;
 
 	/**
-	Whether the process failed to run.
+	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.
+
+	The subprocess must be a Node.js file.
+
+	When aborted, `error.isGracefullyCanceled` becomes `true`.
+
+	@default false
 	*/
-	failed: boolean;
+	readonly gracefulCancel?: Unless<IsSync, boolean>;
 
 	/**
-	Whether the process timed out.
+	If the subprocess is terminated but does not exit, forcefully exit it by sending [`SIGKILL`](https://en.wikipedia.org/wiki/Signal_(IPC)#SIGKILL).
+
+	When this happens, `error.isForcefullyTerminated` becomes `true`.
+
+	@default 5000
 	*/
-	timedOut: boolean;
+	readonly forceKillAfterDelay?: Unless<IsSync, number | boolean>;
 
 	/**
-	Whether the process was killed.
+	Default [signal](https://en.wikipedia.org/wiki/Signal_(IPC)) used to terminate the subprocess.
+
+	This can be either a name (like `'SIGTERM'`) or a number (like `9`).
+
+	@default 'SIGTERM'
 	*/
-	killed: boolean;
+	readonly killSignal?: keyof SignalConstants | number;
 
 	/**
-	The name of the signal that was used to terminate the process. For example, `SIGFPE`.
+	Run the subprocess independently from the current process.
 
-	If a signal terminated the process, this property is defined and included in the error message. Otherwise it is `undefined`.
+	@default false
 	*/
-	signal?: string;
+	readonly detached?: Unless<IsSync, boolean>;
 
 	/**
-	A human-friendly description of the signal that was used to terminate the process. For example, `Floating point arithmetic error`.
+	Kill the subprocess when the current process exits.
 
-	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.
+	@default true
 	*/
-	signalDescription?: string;
+	readonly cleanup?: Unless<IsSync, boolean>;
 
 	/**
-	The `cwd` of the command if provided in the command options. Otherwise it is `process.cwd()`.
+	Sets the [user identifier](https://en.wikipedia.org/wiki/User_identifier) of the subprocess.
+
+	@default current user identifier
 	*/
-	cwd: string;
+	readonly uid?: number;
+
+	/**
+	Sets the [group identifier](https://en.wikipedia.org/wiki/Group_identifier) of the subprocess.
+
+	@default current group identifier
+	*/
+	readonly gid?: number;
+
+	/**
+	Value of [`argv[0]`](https://nodejs.org/api/process.html#processargv0) sent to the subprocess.
+
+	@default file being executed
+	*/
+	readonly argv0?: string;
+
+	/**
+	On Windows, do not create a new console window.
+
+	@default true
+	*/
+	readonly windowsHide?: boolean;
+
+	/**
+	If `false`, escapes the command arguments on Windows.
+
+	@default `true` if the `shell` option is `true`, `false` otherwise
+	*/
+	readonly windowsVerbatimArguments?: boolean;
 };
 
-type ExecaSyncReturnValue<StdoutStderrType extends StdoutStderrAll = string> = {
-} & ExecaReturnBase<StdoutStderrType>;
+/**
+Subprocess options.
+
+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.
+
+@example
+
+```
+// Same value for stdout and stderr
+await execa({verbose: 'full'})`npm run build`;
+
+// Different values for stdout and stderr
+await execa({verbose: {stdout: 'none', stderr: 'full'}})`npm run build`;
+```
+*/
+type Options = CommonOptions<false>;
+
+/**
+Subprocess options, with synchronous methods.
+
+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.
+
+@example
+
+```
+// Same value for stdout and stderr
+execaSync({verbose: 'full'})`npm run build`;
+
+// Different values for stdout and stderr
+execaSync({verbose: {stdout: 'none', stderr: 'full'}})`npm run build`;
+```
+*/
+type SyncOptions = CommonOptions<true>;
+
+type StricterOptions<
+	WideOptions extends CommonOptions,
+	StrictOptions extends CommonOptions,
+> = WideOptions extends StrictOptions ? WideOptions : StrictOptions;
+
+type TemplateExpressionItem =
+	| string
+	| number
+	| Result
+	| SyncResult;
 
 /**
-Result of a child process execution. On success this is a plain object. On failure this is also an `Error` instance.
-
-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
+Value allowed inside `${...}` when using the template string syntax.
 */
-type ExecaReturnValue<StdoutStderrType extends StdoutStderrAll = string> = {
+type TemplateExpression = TemplateExpressionItem | readonly TemplateExpressionItem[];
+
+// `subprocess.pipe()` options
+type PipeOptions = {
 	/**
-	The output of the process with `stdout` and `stderr` interleaved.
+	Which stream to pipe from the source subprocess. A [file descriptor](https://en.wikipedia.org/wiki/File_descriptor) like `"fd3"` can also be passed.
 
-	This is `undefined` if either:
-	- the `all` option is `false` (default value)
-	- `execaSync()` was used
+	`"all"` pipes both `stdout` and `stderr`. This requires the `all` option to be `true`.
 	*/
-	all?: StdoutStderrType;
+	readonly from?: FromOption;
 
 	/**
-	Whether the process was canceled.
+	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;
 
-	You can cancel the spawned process using the [`signal`](https://github.com/sindresorhus/execa#signal-1) option.
+	/**
+	Unpipe the subprocess when the signal aborts.
 	*/
-	isCanceled: boolean;
-} & ExecaSyncReturnValue<StdoutStderrType>;
+	readonly unpipeSignal?: AbortSignal;
+};
 
-type ExecaSyncError<StdoutStderrType extends StdoutStderrAll = string> = {
+// `subprocess.pipe()`
+type PipableSubprocess = {
 	/**
-	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.
+	[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.
 
-	The child process stderr then stdout are appended to the end, separated with newlines and not interleaved.
+	This follows the same syntax as `execa(file, arguments?, options?)` except both regular options and pipe-specific options can be specified.
 	*/
-	message: string;
+	pipe<OptionsType extends Options & PipeOptions = {}>(
+		file: string | URL,
+		arguments?: readonly string[],
+		options?: OptionsType,
+	): Promise<Result<OptionsType>> & PipableSubprocess;
+	pipe<OptionsType extends Options & PipeOptions = {}>(
+		file: string | URL,
+		options?: OptionsType,
+	): Promise<Result<OptionsType>> & PipableSubprocess;
 
 	/**
-	This is the same as the `message` property except it does not include the child process stdout/stderr.
+	Like `subprocess.pipe(file, arguments?, options?)` but using a `command` template string instead. This follows the same syntax as `$`.
 	*/
-	shortMessage: string;
+	pipe(templates: TemplateStringsArray, ...expressions: readonly TemplateExpression[]):
+	Promise<Result<{}>> & PipableSubprocess;
+	pipe<OptionsType extends Options & PipeOptions = {}>(options: OptionsType):
+	(templates: TemplateStringsArray, ...expressions: readonly TemplateExpression[])
+	=> Promise<Result<OptionsType>> & PipableSubprocess;
 
 	/**
-	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.
-
-	This is `undefined` unless the child process exited due to an `error` event or a timeout.
+	Like `subprocess.pipe(file, arguments?, options?)` but using the return value of another `execa()` call instead.
 	*/
-	originalMessage?: string;
-} & Error & ExecaReturnBase<StdoutStderrType>;
+	pipe<Destination extends ResultPromise>(destination: Destination, options?: PipeOptions):
+	Promise<Awaited<Destination>> & PipableSubprocess;
+};
 
-type ExecaError<StdoutStderrType extends StdoutStderrAll = string> = {
+// `subprocess.readable|duplex|iterable()` options
+type ReadableOptions = {
 	/**
-	The output of the process with `stdout` and `stderr` interleaved.
+	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`.
 
-	This is `undefined` if either:
-	- the `all` option is `false` (default value)
-	- `execaSync()` was used
+	@default 'stdout'
 	*/
-	all?: StdoutStderrType;
+	readonly from?: FromOption;
 
 	/**
-	Whether the process was canceled.
+	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
 	*/
-	isCanceled: boolean;
-} & ExecaSyncError<StdoutStderrType>;
+	readonly binary?: boolean;
 
-type KillOptions = {
 	/**
-	Milliseconds to wait for the child process to terminate before sending `SIGKILL`.
+	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;
+};
 
-	Can be disabled with `false`.
+// `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 5000
+	@default 'stdin'
 	*/
-	forceKillAfterTimeout?: number | false;
+	readonly to?: ToOption;
 };
 
-type ExecaChildPromise<StdoutStderrType extends StdoutStderrAll> = {
+// `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>;
+
+// We cannot use mapped types because it must be compatible with Node.js `ChildProcess["stdio"]` which uses a tuple with exactly 5 items
+type MapStdioStreams<
+	StdioOptionsArrayType,
+	OptionsType extends Options,
+> = [
+	SubprocessStdioStream<'0', OptionsType>,
+	SubprocessStdioStream<'1', OptionsType>,
+	SubprocessStdioStream<'2', OptionsType>,
+	'3' extends keyof StdioOptionsArrayType ? SubprocessStdioStream<'3', OptionsType> : never,
+	'4' extends keyof StdioOptionsArrayType ? SubprocessStdioStream<'4', OptionsType> : never,
+];
+
+// `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;
+
+type ExecaCustomSubprocess<OptionsType extends Options> = {
 	/**
-	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).
+	Process identifier ([PID](https://en.wikipedia.org/wiki/Process_identifier)).
 
-	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)
+	This is `undefined` if the subprocess failed to spawn.
 	*/
-	all?: Readable;
+	pid?: number;
 
-	catch<ResultType = never>(
-		onRejected?: (reason: ExecaError<StdoutStderrType>) => ResultType | PromiseLike<ResultType>
-	): Promise<ExecaReturnValue<StdoutStderrType> | ResultType>;
+	/**
+	The subprocess [`stdin`](https://en.wikipedia.org/wiki/Standard_streams#Standard_input_(stdin)) as a stream.
+
+	This is `null` if the `stdin` option is set to `'inherit'`, `'ignore'`, `Readable` or `integer`.
+	*/
+	stdin: SubprocessStdioStream<'0', OptionsType>;
 
 	/**
-	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`. Note that this graceful termination does not work on Windows, because Windows [doesn't support signals](https://nodejs.org/api/process.html#process_signal_events) (`SIGKILL` and `SIGTERM` has the same effect of force-killing the process immediately.) If you want to achieve graceful termination on Windows, you have to use other means, such as [`taskkill`](https://github.com/sindresorhus/taskkill).
+	The subprocess [`stdout`](https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout)) as a stream.
+
+	This is `null` if the `stdout` option is set to `'inherit'`, `'ignore'`, `Writable` or `integer`, or if the `buffer` option is `false`.
 	*/
-	kill(signal?: string, options?: KillOptions): void;
+	stdout: SubprocessStdioStream<'1', OptionsType>;
 
 	/**
-	Similar to [`childProcess.kill()`](https://nodejs.org/api/child_process.html#child_process_subprocess_kill_signal). This used to be preferred when cancelling the child process execution as the error is more descriptive and [`childProcessResult.isCanceled`](#iscanceled) is set to `true`. But now this is deprecated and you should either use `.kill()` or the `signal` option when creating the child process.
+	The subprocess [`stderr`](https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr)) as a stream.
+
+	This is `null` if the `stderr` option is set to `'inherit'`, `'ignore'`, `Writable` or `integer`, or if the `buffer` option is `false`.
 	*/
-	cancel(): void;
+	stderr: SubprocessStdioStream<'2', OptionsType>;
 
 	/**
-	[Pipe](https://nodejs.org/api/stream.html#readablepipedestination-options) the child process's `stdout` to `target`, which can be:
-	- Another `execa()` return value
-	- A writable stream
-	- A file path string
+	Stream combining/interleaving `subprocess.stdout` and `subprocess.stderr`.
 
-	If the `target` is another `execa()` return value, it is returned. Otherwise, the original `execa()` return value is returned. This allows chaining `pipeStdout()` then `await`ing the final result.
+	This requires the `all` option to be `true`.
 
-	The `stdout` option] must be kept as `pipe`, its default value.
+	This is `undefined` if `stdout` and `stderr` options are set to `'inherit'`, `'ignore'`, `Writable` or `integer`, or if the `buffer` option is `false`.
 	*/
-	pipeStdout?<Target extends ExecaChildPromise<StdoutStderrAll>>(target: Target): Target;
-	pipeStdout?(target: Writable | string): ExecaChildProcess<StdoutStderrType>;
+	all: SubprocessAll<OptionsType>;
 
 	/**
-	Like `pipeStdout()` but piping the child process's `stderr` instead.
+	The subprocess `stdin`, `stdout`, `stderr` and other files descriptors as an array of streams.
 
-	The `stderr` option must be kept as `pipe`, its default value.
+	Each array item is `null` if the corresponding `stdin`, `stdout`, `stderr` or `stdio` option is set to `'inherit'`, `'ignore'`, `Stream` or `integer`, or if the `buffer` option is `false`.
 	*/
-	pipeStderr?<Target extends ExecaChildPromise<StdoutStderrAll>>(target: Target): Target;
-	pipeStderr?(target: Writable | string): ExecaChildProcess<StdoutStderrType>;
+	stdio: SubprocessStdioArray<OptionsType>;
 
 	/**
-	Combines both `pipeStdout()` and `pipeStderr()`.
+	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.
 
-	Either the `stdout` option or the `stderr` option must be kept as `pipe`, their default value. Also, the `all` option must be set to `true`.
+	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)
 	*/
-	pipeAll?<Target extends ExecaChildPromise<StdoutStderrAll>>(target: Target): Target;
-	pipeAll?(target: Writable | string): ExecaChildProcess<StdoutStderrType>;
-};
+	kill(signal?: keyof SignalConstants | number, error?: Error): boolean;
+	kill(error?: Error): boolean;
+
+	/**
+	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']>;
+
+	/**
+	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 writable stream.
+	*/
+	writable(writableOptions?: WritableOptions): Writable;
+
+	/**
+	Converts the subprocess to a duplex stream.
+	*/
+	duplex(duplexOptions?: DuplexOptions): Duplex;
+}
+& IpcMethods<HasIpc<OptionsType>, OptionsType['serialization']>
+& PipableSubprocess;
 
-type ExecaChildProcess<StdoutStderrType extends StdoutStderrAll = string> = ChildProcess &
-ExecaChildPromise<StdoutStderrType> &
-Promise<ExecaReturnValue<StdoutStderrType>>;
+/**
+[`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess) with additional methods and properties.
+*/
+type Subprocess<OptionsType extends Options = Options> =
+	& Omit<ChildProcess, keyof ExecaCustomSubprocess<OptionsType>>
+	& ExecaCustomSubprocess<OptionsType>;
+
+/**
+The return value of all asynchronous methods is both:
+- the subprocess.
+- a `Promise` either resolving with its successful `result`, or rejecting with its `error`.
+*/
+type ResultPromise<OptionsType extends Options = Options> =
+	& Subprocess<OptionsType>
+	& Promise<Result<OptionsType>>;
 
-type ExecuteCommandOptions = CommonOptions<'utf8'> & {
+type ExecuteCommandOptions = Omit<Options, 'cancelSignal'> & {
     command: string;
     args?: string[];
     cwd?: string;
     ignoreError?: boolean;
-    env?: Record<string, any>;
+    env?: Record<string, string>;
+    signal?: AbortSignal;
 };
-declare function executeCommand(options: ExecuteCommandOptions): ExecaChildProcess;
+declare function executeCommand(options: ExecuteCommandOptions): ResultPromise;
 declare function executeCommandSync(options: ExecuteCommandOptions): string;
 declare function executeNodeCommand({ scriptPath, args, options, }: {
     scriptPath: string;
     args?: string[];
-    options?: NodeOptions;
-}): ExecaChildProcess;
+    options?: Options;
+}): ResultPromise;
 
 type PackageJsonWithDepsAndDevDeps = PackageJson & Required<Pick<PackageJson, 'dependencies' | 'devDependencies'>>;
 type PackageJsonWithMaybeDeps = Partial<Pick<PackageJson, 'dependencies' | 'devDependencies' | 'peerDependencies' | 'files'>>;
@@ -1125,6 +2169,10 @@ declare enum PackageManagerName {
     PNPM = "pnpm",
     BUN = "bun"
 }
+declare const indentSymbol: unique symbol;
+type PackageJsonWithIndent = PackageJsonWithDepsAndDevDeps & {
+    [indentSymbol]?: any;
+};
 /**
  * Extract package name and version from input
  *
@@ -1161,7 +2209,7 @@ declare abstract class JsPackageManager {
     /** Cache for installed version results to avoid repeated file system calls. */
     static readonly installedVersionCache: Map<string, string | null>;
     /** Cache for package.json files to avoid repeated file system calls. */
-    static readonly packageJsonCache: Map<string, PackageJsonWithDepsAndDevDeps>;
+    static readonly packageJsonCache: Map<string, PackageJsonWithIndent>;
     constructor(options?: JsPackageManagerOptions);
     /** Runs arbitrary package scripts (as a string for display). */
     abstract getRunCommand(command: string): string;
@@ -1177,7 +2225,7 @@ declare abstract class JsPackageManager {
         force?: boolean;
     }): Promise<void>;
     /** Read the `package.json` file available in the provided directory */
-    static getPackageJson(packageJsonPath: string): PackageJsonWithDepsAndDevDeps;
+    static getPackageJson(packageJsonPath: string): PackageJsonWithIndent;
     writePackageJson(packageJson: PackageJson, directory?: string): void;
     getAllDependencies(): Record<string, string>;
     isDependencyInstalled(dependency: string): boolean;
@@ -1207,7 +2255,7 @@ declare abstract class JsPackageManager {
         type: 'dependencies' | 'devDependencies';
         writeOutputToFile?: boolean;
         packageJsonInfo?: PackageJsonInfo;
-    }, dependencies: string[]): Promise<void | ExecaChildProcess>;
+    }, dependencies: string[]): Promise<void | ResultPromise>;
     /**
      * Removing dependencies from the package.json file, which is found first starting from the
      * instance root. The method does not run a package manager install like `npm install`.
@@ -1286,8 +2334,8 @@ declare abstract class JsPackageManager {
     addPackageResolutions(versions: Record<string, string>): void;
     protected abstract runInstall(options?: {
         force?: boolean;
-    }): ExecaChildProcess;
-    protected abstract runAddDeps(dependencies: string[], installAsDevDependencies: boolean, writeOutputToFile?: boolean): ExecaChildProcess;
+    }): ResultPromise;
+    protected abstract runAddDeps(dependencies: string[], installAsDevDependencies: boolean, writeOutputToFile?: boolean): ResultPromise;
     protected abstract getResolutions(packageJson: PackageJson, versions: Record<string, string>): Record<string, any>;
     /**
      * Get the latest or all versions of the input package available on npmjs.com
@@ -1297,10 +2345,10 @@ declare abstract class JsPackageManager {
      */
     protected abstract runGetVersions<T extends boolean>(packageName: string, fetchAllVersions: T): Promise<T extends true ? string[] : string>;
     abstract getRegistryURL(): Promise<string | undefined>;
-    abstract runInternalCommand(command: string, args: string[], cwd?: string, stdio?: 'inherit' | 'pipe' | 'ignore'): ExecaChildProcess;
+    abstract runInternalCommand(command: string, args: string[], cwd?: string, stdio?: 'inherit' | 'pipe' | 'ignore'): ResultPromise;
     abstract runPackageCommand(options: Omit<ExecuteCommandOptions, 'command'> & {
         args: string[];
-    }): ExecaChildProcess;
+    }): ResultPromise;
     abstract findInstallations(pattern?: string[]): Promise<InstallationMetadata | undefined>;
     abstract findInstallations(pattern?: string[], options?: {
         depth: number;