Fix IPC types for option unions

When the options are a union, IPC is now resolved for each member, with its own `buffer` and `serialization` options. `subprocess.sendMessage()`, `result.ipcOutput` and `result.stdio` used the union as a whole instead, so they were typed as if IPC was disabled.

The IPC methods are resolved per member on the subprocess type, not inside `HasIpc`, and `$`'s default stdin type no longer recomputes the `stdin` option. Otherwise, options from a generic type parameter made `$(...).stdin` fail with "Expression produces a union type that is too complex to represent".

Author: sindresorhus

test-d/ipc-options-union.test-d.ts

@@ -0,0 +1,101 @@
+import {expectTypeOf, expectError} from 'nz';
+import {
+	execa,
+	execaNode,
+	$,
+	type Message,
+	type Subprocess,
+	type Result,
+	type ExecaError,
+} from '../index.js';
+
+type EnabledSubprocess = Subprocess<{ipc: true}>;
+
+declare const options: {node: true} | {ipcInput: string};
+const subprocess = execa('unicorns', options);
+expectTypeOf(subprocess.sendMessage).toBe<Subprocess<{ipc: true}>['sendMessage']>();
+expectTypeOf(subprocess.getOneMessage).toBe<Subprocess<{ipc: true}>['getOneMessage']>();
+const result = await subprocess;
+expectTypeOf(result.ipcOutput).toBe<Array<Message<'advanced'>>>();
+expectTypeOf(subprocess.getEachMessage).toBe<EnabledSubprocess['getEachMessage']>();
+expectTypeOf(subprocess.sendMessage('hello')).toBe<Promise<void>>();
+expectTypeOf(subprocess.getOneMessage()).toBe<Promise<Message<'advanced'>>>();
+expectTypeOf<Result<typeof options>['ipcOutput']>().toBe<Array<Message<'advanced'>>>();
+expectTypeOf<ExecaError<typeof options>['ipcOutput']>().toBe<Array<Message<'advanced'>>>();
+expectTypeOf(execa(options)`unicorns`.sendMessage).toBe<EnabledSubprocess['sendMessage']>();
+expectTypeOf($(options)`unicorns`.getOneMessage).toBe<EnabledSubprocess['getOneMessage']>();
+
+const piped = execa('unicorns').pipe(subprocess);
+expectTypeOf(piped.getOneMessage).toBe<EnabledSubprocess['getOneMessage']>();
+const pipedResult = await piped;
+expectTypeOf(pipedResult.ipcOutput).toBe<Array<Message<'advanced'>>>();
+
+declare const gracefulOptions: {gracefulCancel: true; cancelSignal: AbortSignal} | {ipcInput: string};
+const gracefulSubprocess = execa('unicorns', gracefulOptions);
+expectTypeOf(gracefulSubprocess.sendMessage).toBe<EnabledSubprocess['sendMessage']>();
+const gracefulResult = await gracefulSubprocess;
+expectTypeOf(gracefulResult.ipcOutput).toBe<Array<Message<'advanced'>>>();
+
+declare const falsyInputOptions: {ipcInput: false} | {node: true};
+expectTypeOf(execa('unicorns', falsyInputOptions).sendMessage).toBe<EnabledSubprocess['sendMessage']>();
+
+declare const maybeOptions: {node: true} | {encoding: 'buffer'};
+const maybeSubprocess = execa('unicorns', maybeOptions);
+expectTypeOf(maybeSubprocess.sendMessage).toBe<EnabledSubprocess['sendMessage'] | undefined>();
+expectTypeOf(maybeSubprocess.getOneMessage).toBe<EnabledSubprocess['getOneMessage'] | undefined>();
+expectTypeOf(maybeSubprocess.getEachMessage).toBe<EnabledSubprocess['getEachMessage'] | undefined>();
+const maybeResult = await maybeSubprocess;
+expectTypeOf(maybeResult.ipcOutput).toBe<Array<Message<'advanced'>> | []>();
+expectError(maybeSubprocess.sendMessage('hello'));
+if (maybeSubprocess.sendMessage) {
+	expectTypeOf(maybeSubprocess.sendMessage('hello')).toBe<Promise<void>>();
+	expectTypeOf(maybeSubprocess.getOneMessage()).toBe<Promise<Message<'advanced'>>>();
+}
+
+declare const jsonOptions: {node: true; serialization: 'json'} | {ipcInput: string; serialization: 'json'};
+const jsonSubprocess = execa('unicorns', jsonOptions);
+expectTypeOf(jsonSubprocess.getOneMessage()).toBe<Promise<Message<'json'>>>();
+const jsonResult = await jsonSubprocess;
+expectTypeOf(jsonResult.ipcOutput).toBe<Array<Message<'json'>>>();
+expectError(jsonSubprocess.sendMessage(Symbol('message')), 'not assignable');
+
+// Explicit IPC precedence and disabled buffering are unchanged by option unions.
+declare const disabledOptions: {node: true; ipc: false} | {encoding: 'buffer'; ipc: false};
+const disabledSubprocess = execa('unicorns', disabledOptions);
+expectTypeOf(disabledSubprocess.sendMessage).toBe<undefined>();
+expectTypeOf(disabledSubprocess.getOneMessage).toBe<undefined>();
+const disabledResult = await disabledSubprocess;
+expectTypeOf(disabledResult.ipcOutput).toBe<[]>();
+expectError(disabledSubprocess.sendMessage('hello'));
+
+declare const explicitOptions: {node: false; ipc: true} | {encoding: 'buffer'; ipc: true};
+expectTypeOf(execa('unicorns', explicitOptions).sendMessage).toBe<EnabledSubprocess['sendMessage']>();
+expectTypeOf(execaNode('unicorns', options).sendMessage).toBe<EnabledSubprocess['sendMessage']>();
+const noBufferSubprocess = execa('unicorns', {...options, buffer: false});
+expectTypeOf(noBufferSubprocess.sendMessage).toBe<EnabledSubprocess['sendMessage']>();
+const noBufferResult = await noBufferSubprocess;
+expectTypeOf(noBufferResult.ipcOutput).toBe<[]>();
+
+declare const absentOptions: {node: false} | {gracefulCancel: false};
+expectTypeOf(execa('unicorns', absentOptions).getEachMessage).toBe<undefined>();
+expectTypeOf<Result<typeof absentOptions>['ipcOutput']>().toBe<[]>();
+
+declare const optionalInputOptions: {ipcInput?: string} | {node: true};
+expectTypeOf(execa('unicorns', optionalInputOptions).sendMessage).toBe<EnabledSubprocess['sendMessage'] | undefined>();
+
+// Each member's own `buffer` and `serialization` options apply to its IPC.
+declare const mixedStdioOptions: {node: true} | {encoding: 'buffer'};
+const mixedStdioResult = await execa('unicorns', mixedStdioOptions);
+expectTypeOf(mixedStdioResult.stdio).toBe<[undefined, string | Uint8Array, string | Uint8Array, undefined] | [undefined, string | Uint8Array, string | Uint8Array]>();
+
+declare const memberBufferOptions: {node: true; buffer: false} | {encoding: 'buffer'};
+const memberBufferResult = await execa('unicorns', memberBufferOptions);
+expectTypeOf(memberBufferResult.ipcOutput).toBe<[]>();
+
+declare const memberSerializationOptions: {node: true; serialization: 'json'} | {ipc: true};
+const memberSerializationSubprocess = execa('unicorns', memberSerializationOptions);
+await memberSerializationSubprocess.sendMessage({message: 'hello'});
+expectError(memberSerializationSubprocess.sendMessage(new Map()));
+expectTypeOf(memberSerializationSubprocess.getOneMessage()).toBe<Promise<Message<'advanced'>>>();
+const memberSerializationResult = await memberSerializationSubprocess;
+expectTypeOf(memberSerializationResult.ipcOutput).toBe<Array<Message<'json'>> | Array<Message<'advanced'>>>();

test-d/methods/generic-options.test-d.ts

@@ -0,0 +1,38 @@
+import {expectTypeOf} from 'nz';
+import {
+	execa,
+	execaSync,
+	execaNode,
+	$,
+	type Options,
+	type SyncOptions,
+	type ResultPromise,
+} from '../../index.js';
+
+// Options from a generic type parameter, e.g. in a wrapper function
+const runGeneric = <OptionsType extends Options>(options: OptionsType) => {
+	execa('unicorns', options).stdin?.write('input');
+	execa(options)`unicorns`.stdin?.write('input');
+	execaNode('unicorns', options).stdin?.write('input');
+	$('unicorns', options).stdin?.write('input');
+	$(options)`unicorns`.stdin?.write('input');
+	$('unicorns', [], options).stdin?.write('input');
+	$(options)`unicorns`.kill();
+	return $('unicorns', options);
+};
+
+expectTypeOf(runGeneric({})).toBeAssignableTo<ResultPromise>();
+
+const runGenericSync = <OptionsType extends SyncOptions>(options: OptionsType) => {
+	execaSync('unicorns', options).command.trim();
+	$.sync('unicorns', options).command.trim();
+};
+
+runGenericSync({});
+
+// Options inferred while the return value has an expected type, e.g. a type annotation
+const scriptSubprocess: ResultPromise = $('unicorns');
+const scriptOptionsSubprocess: ResultPromise = $('unicorns', {node: true});
+const scriptArgumentsSubprocess: ResultPromise = $('unicorns', [], {input: 'input'});
+const getScriptSubprocess = (): ResultPromise => $('unicorns', {cwd: '.'});
+expectTypeOf([scriptSubprocess, scriptOptionsSubprocess, scriptArgumentsSubprocess, getScriptSubprocess()]).toBeAssignableTo<ResultPromise[]>();

types/ipc.d.ts

@@ -142,6 +142,11 @@ export type HasIpc<OptionsType extends Options> = HasIpcOption<
 	'gracefulCancel' extends keyof OptionsType ? OptionsType['gracefulCancel'] : undefined
 >;
 
+// IPC methods of a subprocess. With an options union, each member enables IPC and sets its `serialization` separately.
+export type SubprocessIpcMethods<OptionsType extends Options> = OptionsType extends unknown
+	? IpcMethods<HasIpc<OptionsType>, OptionsType['serialization']>
+	: never;
+
 type HasIpcOption<
 	IpcOption extends Options['ipc'],
 	NodeOption extends Options['node'],

types/methods/script.d.ts

@@ -8,7 +8,7 @@ import type {SyncResult} from '../return/result.js';
 import type {ResultPromise} from '../subprocess/subprocess.js';
 import type {SubprocessStdioStream} from '../subprocess/stdout.js';
 import type {SubprocessStdioArray} from '../subprocess/stdio.js';
-import type {FdStdioOption, WithInputSources} from '../stdio/option.js';
+import type {WithInputSources} from '../stdio/option.js';
 import type {TemplateString} from './template.js';
 import type {MergeOptions} from './bind.js';
 
@@ -108,7 +108,8 @@ type ScriptStdin<
 	StdinOption,
 > = StdinOption extends undefined ? ScriptDefaultStdin<OptionsType> : StdinOption;
 
-type ScriptDefaultStdin<OptionsType extends Options> = WithInputSources<OptionsType, 'input' | 'inputFile' | 'stdio', 'inherit', FdStdioOption<'0', Omit<OptionsType, 'stdin'>>>;
+// With an input source, the `stdin` option is left `undefined`, so its usual default applies.
+type ScriptDefaultStdin<OptionsType extends Options> = WithInputSources<OptionsType, 'input' | 'inputFile' | 'stdio', 'inherit', undefined>;
 
 // 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

types/pipe.d.ts

@@ -2,7 +2,7 @@ import type {Options} from './arguments/options.js';
 import type {Result} from './return/result.js';
 import type {FromOption, ToOption} from './arguments/fd-options.js';
 import type {ResultPromise, SubprocessResultMethods} from './subprocess/subprocess.js';
-import type {IpcMethods, HasIpc} from './ipc.js';
+import type {SubprocessIpcMethods} from './ipc.js';
 import type {TemplateExpression} from './methods/template.js';
 
 // `subprocess.pipe()` options
@@ -28,7 +28,7 @@ type PipeOptions = {
 // 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']>;
+	& SubprocessIpcMethods<OptionsType>;
 
 // 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.

types/return/result-ipc.d.ts

@@ -10,11 +10,14 @@ export type ResultIpcOutput<
 	OptionsType extends CommonOptions,
 > = IsSync extends true
 	? []
-	: ResultIpcAsync<
-		FdSpecificOption<OptionsType['buffer'], 'ipc'>,
-		HasIpc<StricterOptions<OptionsType, Options>>,
-		OptionsType['serialization']
-	>;
+	// With an options union, each member enables IPC and sets its `buffer` and `serialization` options separately
+	: OptionsType extends unknown
+		? ResultIpcAsync<
+			FdSpecificOption<OptionsType['buffer'], 'ipc'>,
+			HasIpc<StricterOptions<OptionsType, Options>>,
+			OptionsType['serialization']
+		>
+		: never;
 
 type ResultIpcAsync<
 	BufferOption extends boolean | undefined,

types/return/result-stdio.d.ts

@@ -28,8 +28,11 @@ type ResultIpcStdio<
 	OptionsType extends CommonOptions,
 > = IsSync extends true
 	? []
-	: HasIpc<StricterOptions<OptionsType, Options>> extends true
-		? [undefined]
-		: [];
+	// With an options union, each member enables IPC separately
+	: OptionsType extends unknown
+		? HasIpc<StricterOptions<OptionsType, Options>> extends true
+			? [undefined]
+			: []
+		: never;
 
 export {};

types/subprocess/subprocess.d.ts

@@ -12,7 +12,7 @@ import type {
 	SubprocessAsyncIterable,
 	IsObjectIterable,
 } from '../convert.js';
-import type {IpcMethods, HasIpc} from '../ipc.js';
+import type {SubprocessIpcMethods} from '../ipc.js';
 import type {SubprocessStdioStream} from './stdout.js';
 import type {SubprocessStdioArray} from './stdio.js';
 import type {SubprocessAll} from './all.js';
@@ -52,7 +52,7 @@ export type SubprocessResultMethods<OptionsType extends Options = Options> = {
 };
 
 type ExecaCustomSubprocess<OptionsType extends Options> =
-	& IpcMethods<HasIpc<OptionsType>, OptionsType['serialization']>
+	& SubprocessIpcMethods<OptionsType>
 	& PipableSubprocess
 	& SubprocessResultMethods<OptionsType>
 	& {