From a2e4dbea9420720c06144832e905c0ee88680b0b Mon Sep 17 00:00:00 2001 From: ehmicky Date: Wed, 5 Jun 2024 11:50:23 +0100 Subject: [PATCH] Export TypeScript types for the `execa` method (#1066) --- docs/typescript.md | 18 +++++++--- index.d.ts | 8 ++--- test-d/methods/list.test-d.ts | 63 +++++++++++++++++++++++++++++++++++ types/methods/main-async.d.ts | 2 +- types/methods/main-sync.d.ts | 2 +- types/methods/node.d.ts | 2 +- types/methods/script.d.ts | 4 +-- 7 files changed, 85 insertions(+), 14 deletions(-) create mode 100644 test-d/methods/list.test-d.ts diff --git a/docs/typescript.md b/docs/typescript.md index 49a231a08f..e767e22fbb 100644 --- a/docs/typescript.md +++ b/docs/typescript.md @@ -8,11 +8,11 @@ ## Available types -The following types can be imported: [`ResultPromise`](api.md#return-value), [`Subprocess`](api.md#subprocess), [`Result`](api.md#result), [`ExecaError`](api.md#execaerror), [`Options`](api.md#options-1), [`StdinOption`](api.md#optionsstdin), [`StdoutStderrOption`](api.md#optionsstdout), [`TemplateExpression`](api.md#execacommand) and [`Message`](api.md#subprocesssendmessagemessage-sendmessageoptions). +The following types can be imported: [`ResultPromise`](api.md#return-value), [`Subprocess`](api.md#subprocess), [`Result`](api.md#result), [`ExecaError`](api.md#execaerror), [`Options`](api.md#options-1), [`StdinOption`](api.md#optionsstdin), [`StdoutStderrOption`](api.md#optionsstdout), [`TemplateExpression`](api.md#execacommand), [`Message`](api.md#subprocesssendmessagemessage-sendmessageoptions), [`ExecaMethod`](api.md#execaoptions), [`ExecaNodeMethod`](api.md#execanodeoptions) and [`ExecaScriptMethod`](api.md#options). ```ts import { - execa, + execa as execa_, ExecaError, type ResultPromise, type Result, @@ -21,8 +21,11 @@ import { type StdoutStderrOption, type TemplateExpression, type Message, + type ExecaMethod, } from 'execa'; +const execa: ExecaMethod = execa_({preferLocal: true}); + const options: Options = { stdin: 'inherit' satisfies StdinOption, stdout: 'pipe' satisfies StdoutStderrOption, @@ -47,19 +50,22 @@ try { ## Synchronous execution -Their [synchronous](#synchronous-execution) counterparts are [`SyncResult`](api.md#result), [`ExecaSyncError`](api.md#execasyncerror), [`SyncOptions`](api.md#options-1), [`StdinSyncOption`](api.md#optionsstdin), [`StdoutStderrSyncOption`](api.md#optionsstdout) and [`TemplateExpression`](api.md#execacommand). +Their [synchronous](#synchronous-execution) counterparts are [`SyncResult`](api.md#result), [`ExecaSyncError`](api.md#execasyncerror), [`SyncOptions`](api.md#options-1), [`StdinSyncOption`](api.md#optionsstdin), [`StdoutStderrSyncOption`](api.md#optionsstdout), [`TemplateExpression`](api.md#execacommand), [`ExecaSyncMethod`](api.md#execasyncoptions) and [`ExecaScriptSyncMethod`](api.md#syncoptions). ```ts import { - execaSync, + execaSync as execaSync_, ExecaSyncError, type SyncResult, type SyncOptions, type StdinSyncOption, type StdoutStderrSyncOption, type TemplateExpression, + type ExecaSyncMethod, } from 'execa'; +const execaSync: ExecaSyncMethod = execaSync_({preferLocal: true}); + const options: SyncOptions = { stdin: 'inherit' satisfies StdinSyncOption, stdout: 'pipe' satisfies StdoutStderrSyncOption, @@ -84,11 +90,13 @@ The above examples demonstrate those types. However, types are automatically inf ```ts import { - execa, + execa as execa_, ExecaError, type Result, } from 'execa'; +const execa = execa_({preferLocal: true}); + const printResultStdout = (result: Result) => { console.log('Stdout', result.stdout); }; diff --git a/index.d.ts b/index.d.ts index 3e77c6b175..723d3e2891 100644 --- a/index.d.ts +++ b/index.d.ts @@ -11,11 +11,11 @@ export type {Result, SyncResult} from './types/return/result.js'; export type {ResultPromise, Subprocess} from './types/subprocess/subprocess.js'; export {ExecaError, ExecaSyncError} from './types/return/final-error.js'; -export {execa} from './types/methods/main-async.js'; -export {execaSync} from './types/methods/main-sync.js'; +export {execa, type ExecaMethod} from './types/methods/main-async.js'; +export {execaSync, type ExecaSyncMethod} from './types/methods/main-sync.js'; export {execaCommand, execaCommandSync, parseCommandString} from './types/methods/command.js'; -export {$} from './types/methods/script.js'; -export {execaNode} from './types/methods/node.js'; +export {$, type ExecaScriptMethod, type ExecaScriptSyncMethod} from './types/methods/script.js'; +export {execaNode, type ExecaNodeMethod} from './types/methods/node.js'; export { sendMessage, diff --git a/test-d/methods/list.test-d.ts b/test-d/methods/list.test-d.ts new file mode 100644 index 0000000000..2ba07fb927 --- /dev/null +++ b/test-d/methods/list.test-d.ts @@ -0,0 +1,63 @@ +import {expectAssignable} from 'tsd'; +import { + type ExecaMethod, + type ExecaSyncMethod, + type ExecaNodeMethod, + type ExecaScriptMethod, + type ExecaScriptSyncMethod, + execa, + execaSync, + execaNode, + $, +} from '../../index.js'; + +const options = {preferLocal: true} as const; +const secondOptions = {node: true} as const; + +expectAssignable(execa); +expectAssignable(execa({})); +expectAssignable(execa({})({})); +expectAssignable(execa(options)); +expectAssignable(execa(options)(secondOptions)); +expectAssignable(execa(options)({})); +expectAssignable(execa({})(options)); + +expectAssignable(execaSync); +expectAssignable(execaSync({})); +expectAssignable(execaSync({})({})); +expectAssignable(execaSync(options)); +expectAssignable(execaSync(options)(secondOptions)); +expectAssignable(execaSync(options)({})); +expectAssignable(execaSync({})(options)); + +expectAssignable(execaNode); +expectAssignable(execaNode({})); +expectAssignable(execaNode({})({})); +expectAssignable(execaNode(options)); +expectAssignable(execaNode(options)(secondOptions)); +expectAssignable(execaNode(options)({})); +expectAssignable(execaNode({})(options)); + +expectAssignable($); +expectAssignable($({})); +expectAssignable($({})({})); +expectAssignable($(options)); +expectAssignable($(options)(secondOptions)); +expectAssignable($(options)({})); +expectAssignable($({})(options)); + +expectAssignable($.sync); +expectAssignable($.sync({})); +expectAssignable($.sync({})({})); +expectAssignable($.sync(options)); +expectAssignable($.sync(options)(secondOptions)); +expectAssignable($.sync(options)({})); +expectAssignable($.sync({})(options)); + +expectAssignable($.s); +expectAssignable($.s({})); +expectAssignable($.s({})({})); +expectAssignable($.s(options)); +expectAssignable($.s(options)(secondOptions)); +expectAssignable($.s(options)({})); +expectAssignable($.s({})(options)); diff --git a/types/methods/main-async.d.ts b/types/methods/main-async.d.ts index 096ffab55f..983a7f57a9 100644 --- a/types/methods/main-async.d.ts +++ b/types/methods/main-async.d.ts @@ -324,7 +324,7 @@ export declare const execa: ExecaMethod<{}>; /** `execa()` method either exported by Execa, or bound using `execa(options)`. */ -type ExecaMethod = +export type ExecaMethod = & ExecaBind & ExecaTemplate & ExecaArrayLong diff --git a/types/methods/main-sync.d.ts b/types/methods/main-sync.d.ts index d8a5bbf99b..45fc35a8d6 100644 --- a/types/methods/main-sync.d.ts +++ b/types/methods/main-sync.d.ts @@ -32,7 +32,7 @@ export declare const execaSync: ExecaSyncMethod<{}>; // For the moment, we purposely do not export `ExecaSyncMethod` and `ExecaScriptSyncMethod`. // This is because synchronous invocation is discouraged. -type ExecaSyncMethod = +export type ExecaSyncMethod = & ExecaSyncBind & ExecaSyncTemplate & ExecaSyncArrayLong diff --git a/types/methods/node.d.ts b/types/methods/node.d.ts index 59f9e3d32b..910109b0bf 100644 --- a/types/methods/node.d.ts +++ b/types/methods/node.d.ts @@ -35,7 +35,7 @@ export declare const execaNode: ExecaNodeMethod<{}>; /** `execaNode()` method either exported by Execa, or bound using `execaNode(options)`. */ -type ExecaNodeMethod = +export type ExecaNodeMethod = & ExecaNodeBind & ExecaNodeTemplate & ExecaNodeArrayLong diff --git a/types/methods/script.d.ts b/types/methods/script.d.ts index 29fcf0e977..30cb8afa13 100644 --- a/types/methods/script.d.ts +++ b/types/methods/script.d.ts @@ -55,7 +55,7 @@ export const $: ExecaScriptMethod<{}>; /** `$()` method either exported by Execa, or bound using `$(options)`. */ -type ExecaScriptMethod = +export type ExecaScriptMethod = & ExecaScriptBind & ExecaScriptTemplate & ExecaScriptArrayLong @@ -88,7 +88,7 @@ type ExecaScriptArrayShort = /** `$.sync()` method either exported by Execa, or bound using `$.sync(options)`. */ -type ExecaScriptSyncMethod = +export type ExecaScriptSyncMethod = & ExecaScriptSyncBind & ExecaScriptSyncTemplate & ExecaScriptSyncArrayLong