feat: enhance parameter handling and type definitions in exec module

GoodbyeNJN · GoodbyeNJN · commit f6a3f9cd0237 · 2026-04-18T03:53:55.000+08:00
diff --git a/src/exec/params.ts b/src/exec/params.ts
@@ -1,9 +1,18 @@
 import { tokenizeArgs } from "args-tokenizer";
 
-import { concatTemplateStrings, getErrorMessage } from "@/common";
+import { getErrorMessage } from "@/common";
 import { isArray, isPlainObject, isString } from "@/remeda";
 
-import type { BaseProcessOptions, ExecParams, SpawnCommand, SpawnOptions } from "./types";
+import type {
+    BaseProcessOptions,
+    ExecCommandStringParams,
+    ExecCommandTemplateParams,
+    ExecFactoryParams,
+    ExecParams,
+    ExecSpawnParams,
+    SpawnCommand,
+    SpawnOptions,
+} from "./types";
 
 export const defaultOptions: Partial<BaseProcessOptions> = {
     timeout: undefined,
@@ -14,7 +23,7 @@ export const defaultSpawnOptions: SpawnOptions = {
     windowsHide: true,
 };
 
-const parseCommandString = (input: string): SpawnCommand => {
+export const parseCommandString = (input: string): SpawnCommand => {
     let tokens;
     try {
         tokens = tokenizeArgs(input);
@@ -29,32 +38,28 @@ const parseCommandString = (input: string): SpawnCommand => {
     return { command: tokens[0], args: tokens.slice(1) };
 };
 
-export const getSpawnCommand = (params: ExecParams): SpawnCommand => {
-    const [templateOrString, ...rest] = params;
-
-    let cmd;
-
-    if (isArray(templateOrString)) {
-        // Template string case, should parse input string into command and args
-        const input = concatTemplateStrings(templateOrString, rest);
-        cmd = parseCommandString(input);
-    } else if (isString(templateOrString)) {
-        // Simple command string case
-        cmd = isArray(rest[0])
-            ? { command: templateOrString, args: rest[0] as string[] } // Args array provided
-            : parseCommandString(templateOrString); // No args provided, should parse string into command and args
-    } else {
-        throw new Error(
-            `Invalid first parameter for exec: expected string or template string, got ${typeof templateOrString}.`,
-        );
-    }
+export const isSpawnParams = (params: ExecParams): params is ExecSpawnParams => {
+    const [a, b, c] = params;
+
+    return isString(a) && (b === undefined || isArray(b)) && (c === undefined || isPlainObject(c));
+};
+
+export const isCommandTemplateParams = (
+    params: ExecParams,
+): params is ExecCommandTemplateParams => {
+    const [a] = params;
+
+    return isArray(a);
+};
+
+export const isCommandStringParams = (params: ExecParams): params is ExecCommandStringParams => {
+    const [a, b, c] = params;
 
-    return cmd;
+    return isString(a) && b === undefined && c === undefined;
 };
 
-export const getProcessOptions = (params: ExecParams): Partial<BaseProcessOptions> | undefined => {
-    const [maybeOptions] = params;
-    if (isPlainObject(maybeOptions)) return maybeOptions;
+export const isFactoryParams = (params: ExecParams): params is ExecFactoryParams => {
+    const [a, b, c] = params;
 
-    return undefined;
+    return isPlainObject(a) && b === undefined && c === undefined;
 };
diff --git a/src/exec/process.ts b/src/exec/process.ts
@@ -1,28 +1,43 @@
 import { isString } from "remeda";
 
-import { createPromiseWithResolvers } from "@/common";
+import { concatTemplateStrings, createPromiseWithResolvers } from "@/common";
 
 import { isAbortError } from "./error";
-import { defaultOptions, getProcessOptions, getSpawnCommand } from "./params";
+import {
+    defaultOptions,
+    isCommandStringParams,
+    isCommandTemplateParams,
+    isFactoryParams,
+    isSpawnParams,
+    parseCommandString,
+} from "./params";
 import { spawnProcess } from "./spawn";
 
 import type {
     BaseExec,
     BaseProcessInstance,
     BaseProcessOptions,
+    ExecCommandStringParams,
+    ExecCommandTemplateParams,
     ExecParams,
     KillSignal,
 } from "./types";
 import type { Nullable } from "@/types";
 import type { ChildProcess } from "node:child_process";
 import type { Readable } from "node:stream";
 
-export abstract class BaseProcess implements BaseProcessInstance {
-    protected static execImpl(self: BaseProcess, params: ExecParams): BaseExec {
-        const exec = (...params: ExecParams): any => {
+export abstract class BaseProcess<P, I> implements BaseProcessInstance<P, I> {
+    protected static execImpl<P, I>(self: BaseProcess<P, I>, params: ExecParams) {
+        const execCommandTemplateOrString = (
+            ...params: ExecCommandTemplateParams | ExecCommandStringParams
+        ) => {
+            const input = isCommandTemplateParams(params)
+                ? concatTemplateStrings(params[0], params.slice(1))
+                : params[0];
+
             let cmd;
             try {
-                cmd = getSpawnCommand(params);
+                cmd = parseCommandString(input);
             } catch (error) {
                 self.thrownError = error as Error;
             }
@@ -31,16 +46,23 @@ export abstract class BaseProcess implements BaseProcessInstance {
             return cmd ? self.spawn(cmd.command, cmd.args) : self;
         };
 
-        // Factory case
-        const options = getProcessOptions(params);
-        if (options) {
-            self.options = { ...self.options, ...options };
+        if (isCommandTemplateParams(params) || isCommandStringParams(params)) {
+            return execCommandTemplateOrString(...params);
+        } else if (isSpawnParams(params)) {
+            self.options = { ...self.options, ...params[2] };
 
-            return exec;
-        }
+            return self.spawn(params[0], params[1] || []);
+        } else if (isFactoryParams(params)) {
+            self.options = { ...self.options, ...params[0] };
 
-        // Command string or template case
-        return exec(...params);
+            return execCommandTemplateOrString;
+        } else {
+            self.thrownError = new Error(
+                `Invalid parameters passed to exec: ${JSON.stringify(params)}`,
+            );
+
+            return self;
+        }
     }
 
     protected _process: ChildProcess | undefined;
@@ -82,12 +104,12 @@ export abstract class BaseProcess implements BaseProcessInstance {
             createPromiseWithResolvers<void>());
     }
 
-    exec: any = (...params: ExecParams) => {
+    exec: BaseExec<BaseProcessInstance<P, I>> = (...params: ExecParams): any => {
         return BaseProcess.execImpl(this, params);
     };
 
-    pipe: any = (...params: ExecParams) => {
-        const self = this.construct();
+    pipe: BaseExec<BaseProcessInstance<P, I>> = (...params: ExecParams): any => {
+        const self = this.child();
 
         return BaseProcess.execImpl(self, params);
     };
@@ -96,8 +118,8 @@ export abstract class BaseProcess implements BaseProcessInstance {
         return this.process?.kill(signal) === true;
     }
 
-    then<TResult1 = any, TResult2 = never>(
-        onfulfilled?: ((value: any) => TResult1 | PromiseLike<TResult1>) | null,
+    then<TResult1 = P, TResult2 = never>(
+        onfulfilled?: ((value: P) => TResult1 | PromiseLike<TResult1>) | null,
         onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null,
     ): Promise<TResult1 | TResult2> {
         return this.thenImpl().then(onfulfilled, onrejected);
@@ -148,9 +170,9 @@ export abstract class BaseProcess implements BaseProcessInstance {
         this.process?.removeAllListeners();
     }
 
-    abstract [Symbol.asyncIterator](): AsyncIterator<any>;
+    abstract [Symbol.asyncIterator](): AsyncIterator<I>;
 
-    protected abstract thenImpl(): Promise<any>;
+    protected abstract thenImpl(): Promise<P>;
 
-    protected abstract construct(): BaseProcess;
+    protected abstract child(): BaseProcess<P, I>;
 }
diff --git a/src/exec/safe/index.ts b/src/exec/safe/index.ts
@@ -5,10 +5,13 @@ import { BaseProcess } from "../process";
 import { readStreamLines, readStreams } from "../stream";
 
 import type { Exec, ProcessInstance, ProcessOptions } from "./types";
-import type { Output } from "../types";
+import type { ExecParams, Output } from "../types";
 import type { Result } from "@/result";
 
-export class Process extends BaseProcess implements ProcessInstance {
+export class Process
+    extends BaseProcess<Result<Output, Error>, Result<string, Error>>
+    implements ProcessInstance
+{
     declare exec: Exec;
     declare pipe: Exec;
 
@@ -62,12 +65,12 @@ export class Process extends BaseProcess implements ProcessInstance {
         return err(new NonZeroExitError(this, output));
     }
 
-    protected override construct(): Process {
+    protected override child() {
         return new Process({ stdin: this });
     }
 }
 
-export const exec: Exec = (...params: [any, ...any[]]): any => {
+export const exec: Exec = (...params: ExecParams): any => {
     const self = new Process();
 
     return BaseProcess["execImpl"](self, params);
diff --git a/src/exec/safe/types.ts b/src/exec/safe/types.ts
@@ -8,27 +8,12 @@ import type {
     Output,
 } from "../types";
 import type { Result } from "@/result";
-import type { SetReturnType } from "@/types";
 
-export type ProcessOptions = BaseProcessOptions & ExtendProcessOptions;
+export type ProcessOptions = BaseProcessOptions<ProcessInstance>;
 
-export interface ExtendProcessOptions {
-    stdin: ProcessInstance | string;
-}
+export type ProcessInstance = BaseProcessInstance<Result<Output, Error>, Result<string, Error>>;
 
-export type ProcessInstance = BaseProcessInstance & ExtendProcessInstance;
-
-export interface ExtendProcessInstance
-    extends PromiseLike<Result<Output, Error>>, AsyncIterable<Result<string, Error>> {
-    exec: Exec;
-    pipe: Exec;
-}
-
-export type Exec = SetReturnType<BaseExecSpawn, ProcessInstance> &
-    SetReturnType<BaseExecCommandTemplate, ProcessInstance> &
-    SetReturnType<BaseExecCommandString, ProcessInstance> &
-    SetReturnType<
-        BaseExecFactory,
-        SetReturnType<BaseExecCommandTemplate, ProcessInstance> &
-            SetReturnType<BaseExecCommandString, ProcessInstance>
-    >;
+export type Exec = BaseExecSpawn<ProcessInstance> &
+    BaseExecCommandTemplate<ProcessInstance> &
+    BaseExecCommandString<ProcessInstance> &
+    BaseExecFactory<ProcessInstance>;
diff --git a/src/exec/types.ts b/src/exec/types.ts
@@ -15,24 +15,24 @@ export interface SpawnCommand {
 }
 export type { SpawnOptions } from "node:child_process";
 
-export interface BaseProcessOptions {
-    stdin: BaseProcessInstance | string;
+export interface BaseProcessOptions<T extends BaseProcessInstance = BaseProcessInstance> {
+    stdin: T | string;
     signal: AbortSignal;
     spawnOptions: SpawnOptions;
     timeout: number;
     persist: boolean;
     throwOnError: boolean;
 }
 
-export interface BaseProcessInstance extends PromiseLike<any>, AsyncIterable<any> {
+export interface BaseProcessInstance<P = any, I = any> extends PromiseLike<P>, AsyncIterable<I> {
     get process(): ChildProcess | undefined;
     get aborted(): boolean;
     get killed(): boolean;
     get pid(): number | undefined;
     get exitCode(): number | undefined;
 
-    exec: (...params: any[]) => any;
-    pipe: (...params: any[]) => any;
+    exec: BaseExec<BaseProcessInstance<P, I>>;
+    pipe: BaseExec<BaseProcessInstance<P, I>>;
     kill: (signal?: KillSignal) => boolean;
 }
 
@@ -41,25 +41,24 @@ export type ExecParams =
     | ExecCommandTemplateParams
     | ExecCommandStringParams
     | ExecFactoryParams;
-export type BaseExec = BaseExecSpawn &
-    BaseExecCommandTemplate &
-    BaseExecCommandString &
-    BaseExecFactory;
 
 export type ExecSpawnParams = [
     command: string,
     args?: string[],
     options?: Partial<BaseProcessOptions>,
 ];
-export type BaseExecSpawn = (...params: ExecSpawnParams) => unknown;
-
 export type ExecCommandTemplateParams = Parameters<TemplateFn>;
-export type BaseExecCommandTemplate = (...params: ExecCommandTemplateParams) => unknown;
-
 export type ExecCommandStringParams = [command: string];
-export type BaseExecCommandString = (...params: ExecCommandStringParams) => unknown;
-
 export type ExecFactoryParams = [options: Partial<BaseProcessOptions>];
-export type BaseExecFactory = (
+
+export type BaseExec<T> = BaseExecSpawn<T> &
+    BaseExecCommandTemplate<T> &
+    BaseExecCommandString<T> &
+    BaseExecFactory<T>;
+
+export type BaseExecSpawn<T> = (...params: ExecSpawnParams) => T;
+export type BaseExecCommandTemplate<T> = (...params: ExecCommandTemplateParams) => T;
+export type BaseExecCommandString<T> = (...params: ExecCommandStringParams) => T;
+export type BaseExecFactory<T> = (
     ...params: ExecFactoryParams
-) => BaseExecCommandTemplate & BaseExecCommandString;
+) => BaseExecCommandTemplate<T> & BaseExecCommandString<T>;
diff --git a/src/exec/unsafe/index.ts b/src/exec/unsafe/index.ts
@@ -3,9 +3,9 @@ import { BaseProcess } from "../process";
 import { readStreamLines, readStreams } from "../stream";
 
 import type { Exec, ProcessInstance, ProcessOptions } from "./types";
-import type { Output } from "../types";
+import type { ExecParams, Output } from "../types";
 
-export class Process extends BaseProcess implements ProcessInstance {
+export class Process extends BaseProcess<Output, string> implements ProcessInstance {
     declare exec: Exec;
     declare pipe: Exec;
 
@@ -56,12 +56,12 @@ export class Process extends BaseProcess implements ProcessInstance {
         throw new NonZeroExitError(this, output);
     }
 
-    protected override construct(): Process {
+    protected override child() {
         return new Process({ stdin: this });
     }
 }
 
-export const exec: Exec = (...params: [any, ...any[]]): any => {
+export const exec: Exec = (...params: ExecParams): any => {
     const self = new Process();
 
     return BaseProcess["execImpl"](self, params);
diff --git a/src/exec/unsafe/types.ts b/src/exec/unsafe/types.ts
@@ -7,26 +7,12 @@ import type {
     BaseProcessOptions,
     Output,
 } from "../types";
-import type { SetReturnType } from "@/types";
 
-export type ProcessOptions = BaseProcessOptions & ExtendProcessOptions;
+export type ProcessOptions = BaseProcessOptions<ProcessInstance>;
 
-export interface ExtendProcessOptions {
-    stdin: ProcessInstance;
-}
+export type ProcessInstance = BaseProcessInstance<Output, string>;
 
-export type ProcessInstance = BaseProcessInstance & ExtendProcessInstance;
-
-export interface ExtendProcessInstance extends PromiseLike<Output>, AsyncIterable<string> {
-    exec: Exec;
-    pipe: Exec;
-}
-
-export type Exec = SetReturnType<BaseExecSpawn, ProcessInstance> &
-    SetReturnType<BaseExecCommandTemplate, ProcessInstance> &
-    SetReturnType<BaseExecCommandString, ProcessInstance> &
-    SetReturnType<
-        BaseExecFactory,
-        SetReturnType<BaseExecCommandTemplate, ProcessInstance> &
-            SetReturnType<BaseExecCommandString, ProcessInstance>
-    >;
+export type Exec = BaseExecSpawn<ProcessInstance> &
+    BaseExecCommandTemplate<ProcessInstance> &
+    BaseExecCommandString<ProcessInstance> &
+    BaseExecFactory<ProcessInstance>;
