@zokugun/exec-lite 0.2.0 → 0.3.0

package/README.md

@@ -126,6 +126,47 @@ Spawns a child process and returns a `Subprocess` instance. The process starts i
 - `exec` does not throw. Errors surface through the `fails` flag of the `Result`.
 - On Windows, batch files (`.bat`, `.cmd`) are wrapped in `cmd.exe` with verbatim argument handling.
 
+#### `createCommand`
+
+```typescript
+import { createCommand } from '@zokugun/exec-lite';
+
+const git = createCommand('git', [], { resultMode: 'merged' });
+
+await git(['status'], { cwd: repository });
+await git.withOptions({ cwd: repository })(['status']);
+await git.toCwdFirst()(repository, 'status');
+await git.toFlatArgs()('status');
+```
+
+```typescript
+type Command = {
+	(args?: readonly string[] | null, options?: Partial<Options>): Subprocess;
+	toCwdFirst(): (cwd: string, ...args: string[]) => Subprocess;
+	toFlatArgs(): (...args: string[]) => Subprocess;
+	withOptions(options: Partial<Options>): Command;
+}
+```
+
+Creates a reusable command with optional default arguments and options.
+
+### Merged Result Mode
+
+Set `resultMode: 'merged'` to make the awaited subprocess resolve directly to a string containing combined stdout and stderr, rather than the default `Result` object:
+
+```typescript
+const task = exec('git', ['status'], { resultMode: 'merged' });
+const output = await task;
+
+console.log(output);
+
+if(task.failed) {
+   console.error(`Command failed with exit code: ${task.exitCode}`);
+}
+```
+
+The subprocess does not reject on a non-zero exit. Check `.failed` and, when needed, `.exitCode` or `.error` for process status and errors.
+
 ---
 
 ### Classes
@@ -165,10 +206,13 @@ The class behind every subprocess returned by `exec`. You rarely need to constru
 
 #### `ExecResult`
 
-A discriminated union wrapping success or failure:
+A structured success or failure result by default. In merged mode, this resolves directly to a string:
 
 ```typescript
-type ExecResult = Result<ExecSuccess, ExecFailure>;
+type ResultMode = 'result' | 'merged';
+type ExecResult<M extends ResultMode = 'result'> = M extends 'merged'
+   ? string
+   : Result<ExecSuccess, ExecFailure>;
 ```
 
 ---
@@ -179,10 +223,12 @@ Returned when the process exits with code 0 and no error occurred.
 
 ```typescript
 type ExecSuccess = {
-   all: string;        // combined stdout + stderr
+   args: readonly string[];
    command: string;
+   cwd: string;
    durationMs: number;
    exitCode: number;
+   merged: string;     // combined stdout + stderr
    stdout: string;
    stderr: string;
 };
@@ -196,12 +242,14 @@ Returned when the process errors, exits non-zero, or gets killed.
 
 ```typescript
 type ExecFailure = {
-   all?: string;
+   args: readonly string[];
    canceled: boolean;  // true if aborted via signal
    command: string;
+   cwd?: string;
    durationMs: number;
    error?: Error;
    exitCode?: number;
+   merged?: string;
    signalCode?: string;
    stderr?: string;
    stdout?: string;
@@ -221,24 +269,24 @@ The shape returned by `exec()`. It is:
 ```typescript
 type Subprocess = AsyncIterable<string> & PromiseLike<ExecResult> & { ... };
 ```
-
 ---
 
 #### `Options`
 
 Extended `SpawnOptions` with extra fields:
 
-| Field               | Type                                  | Default              | Description                           |
-| ------------------- | ------------------------------------- | -------------------- | ------------------------------------- |
-| `cwd`               | `string`                              | `process.cwd()`      | Working directory                     |
-| `env`               | `Record<string, string>`              | inherited + computed | Environment variables                 |
-| `localDir`          | `string`                              | `cwd`                | Directory to resolve local paths from |
-| `preferLocal`       | `boolean`                             | `false`              | Prepends `node_modules/.bin` to PATH  |
-| `signal`            | `AbortSignal`                         | none                 | Abort signal for cancellation         |
-| `stdin`             | `string \| Subprocess \| { process }` | `pipe`               | Input source                          |
-| `stdio`             |                                       | none                 | Standard I/O configurations.          |
-| `stdout` / `stderr` | `StdioOption`                         | none                 | Stream configuration                  |
-| `timeout`           | `number`                              | none                 | Auto-abort after N milliseconds       |
+| Field               | Type                                  | Default              | Description                                          |
+| ------------------- | ------------------------------------- | -------------------- | ---------------------------------------------------- |
+| `cwd`               | `string`                              | `process.cwd()`      | Working directory                                    |
+| `env`               | `Record<string, string>`              | inherited + computed | Environment variables                                |
+| `localDir`          | `string`                              | `cwd`                | Directory to resolve local paths from                |
+| `preferLocal`       | `boolean`                             | `false`              | Prepends `node_modules/.bin` to PATH                 |
+| `resultMode`        | `'result' \| 'merged'`                | `'result'`           | Resolve to a structured result or merged output text |
+| `signal`            | `AbortSignal`                         | none                 | Abort signal for cancellation                        |
+| `stdin`             | `string \| Subprocess \| { process }` | `'pipe'`             | Input source                                         |
+| `stdio`             |                                       | none                 | Standard I/O configurations.                         |
+| `stdout` / `stderr` | `StdioOption`                         | none                 | Stream configuration                                 |
+| `timeout`           | `number`                              | none                 | Auto-abort after N milliseconds                      |
 
 Contributions
 -------------

package/lib/cjs/create-command.cjs

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCommand = createCommand;
+const exec_js_1 = require("./exec.cjs");
+function createCommand(command, args = [], options = {}) {
+    const create = (options) => {
+        const run = ((runArgs, runOptions) => {
+            return (0, exec_js_1.exec)(command, [...(args ?? []), ...(runArgs ?? [])], {
+                ...options,
+                ...runOptions,
+            });
+        });
+        run.withOptions = (overrides) => create({ ...options, ...overrides });
+        run.toCwdFirst = () => ((cwd, ...runArgs) => run(runArgs, { cwd }));
+        run.toFlatArgs = () => ((...runArgs) => run(runArgs));
+        return run;
+    };
+    return create(options);
+}

package/lib/cjs/create-command.d.cts

@@ -0,0 +1,3 @@
+import type { Command, Options, ResultMode, Subprocess } from './types.cjs';
+declare function createCommand<M extends ResultMode = 'result'>(command: string, args?: readonly string[] | null, options?: Partial<Options<M>>): Command<M>;
+export { type Command, type Options, type ResultMode, type Subprocess, createCommand, };

package/lib/cjs/exec-process.cjs

@@ -16,6 +16,7 @@ class ExecProcess {
     _aborted = false;
     _args;
     _command;
+    _cwd;
     _failed = false;
     _options;
     _process;
@@ -75,6 +76,7 @@ class ExecProcess {
         this._start = process.hrtime.bigint();
         this.reset();
         const normalizedOptions = (0, normalizeOptions_js_1.normalizeOptions)(this._options);
+        this._cwd = normalizedOptions.cwd;
         if (normalizedOptions.signal) {
             this._signal = normalizedOptions.signal;
         }
@@ -138,7 +140,12 @@ class ExecProcess {
     } // }}}
     // eslint-disable-next-line ts/promise-function-async
     then(onfulfilled, onrejected) {
-        return this.toResult().then(onfulfilled, onrejected);
+        return this.toResult().then((result) => {
+            if (onfulfilled) {
+                return onfulfilled(result);
+            }
+            return result;
+        }, onrejected);
     } // }}}
     onClose() {
         if (this._resolveClose) {
@@ -165,26 +172,31 @@ class ExecProcess {
     } // }}}
     toFailure(error) {
         this._failed = true;
+        if (this._options.resultMode === 'merged') {
+            return (0, xtry_1.stringifyError)(error);
+        }
         const result = {
-            all: '',
+            args: this._args,
             canceled: this._signal?.aborted ?? false,
             command: this._command,
+            cwd: this._cwd,
             durationMs: Number(process.hrtime.bigint() - this._start) / 1e6,
             error,
             exitCode: this.exitCode,
+            merged: '',
             signalCode: this.signalCode,
         };
-        return result;
+        return (0, xtry_1.err)(result);
     } // }}}
     async toResult() {
         if (this._thrownError) {
-            return (0, xtry_1.err)(this.toFailure(this._thrownError));
+            return this.toFailure(this._thrownError);
         }
         const task = this._process;
         if (!task) {
-            return (0, xtry_1.err)(this.toFailure(new Error('No process was started')));
+            return this.toFailure(new Error('No process was started'));
         }
-        const context = { all: '' };
+        const context = { merged: '' };
         const [stdout, stderr] = await Promise.all([
             this._streamOut ? (0, readStream_js_1.readStream)(this._streamOut, context) : '',
             this._streamErr ? (0, readStream_js_1.readStream)(this._streamErr, context) : '',
@@ -196,13 +208,21 @@ class ExecProcess {
         }
         task.removeAllListeners();
         if (this._thrownError) {
-            return (0, xtry_1.err)(this.toFailure(this._thrownError));
+            return this.toFailure(this._thrownError);
+        }
+        if (this._options.resultMode === 'merged') {
+            if ((this.exitCode !== 0 && this.exitCode !== undefined) || this.signalCode !== undefined) {
+                this._failed = true;
+            }
+            return context.merged;
         }
         const result = {
-            all: context.all,
+            args: this._args,
             command: this._command,
+            cwd: this._cwd,
             durationMs: Number(process.hrtime.bigint() - this._start) / 1e6,
             exitCode: this.exitCode,
+            merged: context.merged,
             stderr,
             stdout,
         };

package/lib/cjs/exec-process.d.cts

@@ -1,10 +1,11 @@
 import type { ChildProcess } from 'node:child_process';
 import type { Readable } from 'node:stream';
-import type { ExecFailure, ExecResult, KillSignal, Options, Subprocess } from './types.cjs';
-export declare class ExecProcess implements Subprocess {
+import type { ExecFailure, ExecResult, ExecSuccess, KillSignal, Options, ResultMode, Subprocess } from './types.cjs';
+declare class ExecProcess implements Subprocess<ResultMode> {
     protected _aborted: boolean;
     protected _args: readonly string[];
     protected _command: string;
+    protected _cwd: string | undefined;
     protected _failed: boolean;
     protected _options: Partial<Options>;
     protected _process?: ChildProcess;
@@ -25,13 +26,16 @@ export declare class ExecProcess implements Subprocess {
     get process(): ChildProcess | undefined;
     get signalCode(): string | undefined;
     kill(signal?: KillSignal): boolean;
-    pipe(command: string, args?: readonly string[], options?: Partial<Options>): Subprocess;
+    pipe<N extends ResultMode = 'result'>(command: string, args?: readonly string[], options?: Partial<Options> & {
+        resultMode?: N;
+    }): Subprocess<N>;
     spawn(): void;
     [Symbol.asyncIterator](): AsyncIterator<string>;
-    then<TResult1 = ExecResult, TResult2 = never>(onfulfilled?: ((value: ExecResult) => PromiseLike<TResult1> | TResult1) | null, onrejected?: ((reason: unknown) => PromiseLike<TResult2> | TResult2) | null): Promise<TResult1 | TResult2>;
+    then<TResult1 = ExecResult<ResultMode>, TResult2 = never>(onfulfilled?: ((value: ExecResult<ResultMode>) => PromiseLike<TResult1> | TResult1) | null, onrejected?: ((reason: unknown) => PromiseLike<TResult2> | TResult2) | null): Promise<TResult1 | TResult2>;
     protected onClose(): void;
     protected onError(error: Error): void;
     protected reset(): void;
-    protected toFailure(error: Error): ExecFailure;
-    protected toResult(): Promise<ExecResult>;
+    protected toFailure(error: Error): ExecResult<ResultMode>;
+    protected toResult(): Promise<ExecResult<ResultMode>>;
 }
+export { type ExecFailure, type ExecResult, type ExecSuccess, type KillSignal, type Options, type ResultMode, type Subprocess, ExecProcess, };

package/lib/cjs/exec.d.cts

@@ -1,2 +1,3 @@
-import type { Options, Subprocess } from './types.cjs';
-export declare function exec(command: string, args?: readonly string[] | null, options?: Partial<Options>): Subprocess;
+import type { Options, ResultMode, Subprocess } from './types.cjs';
+declare function exec<M extends ResultMode = 'result'>(command: string, args?: readonly string[] | null, options?: Partial<Options<M>>): Subprocess<M>;
+export { type Options, type ResultMode, type Subprocess, exec, };

package/lib/cjs/index.cjs

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.exec = exports.ExecProcess = void 0;
+exports.exec = exports.ExecProcess = exports.createCommand = void 0;
+var create_command_js_1 = require("./create-command.cjs");
+Object.defineProperty(exports, "createCommand", { enumerable: true, get: function () { return create_command_js_1.createCommand; } });
 var exec_process_js_1 = require("./exec-process.cjs");
 Object.defineProperty(exports, "ExecProcess", { enumerable: true, get: function () { return exec_process_js_1.ExecProcess; } });
 var exec_js_1 = require("./exec.cjs");

package/lib/cjs/index.d.cts

@@ -1,3 +1,4 @@
+export type { Command, ExecFailure, ExecResult, ExecSuccess, KillSignal, Options, ResultMode, StdinOption, StdioOption, Subprocess, } from './types.cjs';
+export { createCommand } from './create-command.cjs';
 export { ExecProcess } from './exec-process.cjs';
 export { exec } from './exec.cjs';
-export { ExecFailure, ExecResult, ExecSuccess, KillSignal, Options, StdinOption, StdioOption, Subprocess, } from './types.cjs';

package/lib/cjs/types.d.cts

@@ -1,37 +1,49 @@
 import type { ChildProcess, SpawnOptions as ProcessSpawnOptions } from 'node:child_process';
 import type { Result } from '@zokugun/xtry';
+export type Command<M extends ResultMode = 'result'> = {
+    (args?: readonly string[] | null, options?: Partial<Options<M>>): Subprocess<M>;
+    toCwdFirst(): (cwd: string, ...args: string[]) => Subprocess<M>;
+    toFlatArgs(): (...args: string[]) => Subprocess<M>;
+    withOptions(options: Partial<Options<M>>): Command<M>;
+};
 export type ExecFailure = {
-    all?: string;
+    args: readonly string[];
     canceled: boolean;
+    cwd?: string;
     command: string;
     durationMs: number;
     error?: Error;
     exitCode?: number;
+    merged?: string;
     pipedFrom?: ExecResult;
     signalCode?: string;
     stderr?: string;
     stdout?: string;
 };
-export type ExecResult = Result<ExecSuccess, ExecFailure>;
+export type ResultMode = 'merged' | 'result';
+export type ExecResult<M extends ResultMode = 'result'> = M extends 'merged' ? string : Result<ExecSuccess, ExecFailure>;
 export type ExecSuccess = {
-    all: string;
+    args: readonly string[];
     command: string;
+    cwd: string;
     durationMs: number;
     error?: undefined;
     exitCode: number;
+    merged: string;
     pipedFrom?: ExecResult;
     stderr: string;
     stdout: string;
 };
 export type KillSignal = Parameters<ChildProcess['kill']>[0];
-export type Options = Omit<ProcessSpawnOptions, 'cwd' | 'env' | 'stdio'> & Readonly<Partial<{
+export type Options<M extends ResultMode = ResultMode> = Omit<ProcessSpawnOptions, 'cwd' | 'env' | 'stdio'> & Readonly<Partial<{
     cwd?: string;
     env: Readonly<Partial<Record<string, string>>>;
     localDir: string;
     preferLocal: boolean;
+    resultMode: M;
     signal: AbortSignal;
     stderr: StdioOption;
-    stdin: ExecResult | StdinOption | Subprocess;
+    stdin: ExecResult | StdinOption | Subprocess<ResultMode>;
     stdio: readonly [StdinOption, ...readonly StdioOption[]] | SpawnOptions['stdio'];
     stdout: StdioOption;
 }>>;
@@ -42,7 +54,7 @@ export type StdinOption = StdioOption | {
     readonly string?: string;
 };
 export type StdioOption = Readonly<Exclude<SpawnOptions['stdio'], undefined>[number]>;
-export type Subprocess = AsyncIterable<string> & PromiseLike<ExecResult> & {
+export type Subprocess<M extends ResultMode = 'result'> = AsyncIterable<string> & PromiseLike<ExecResult<M>> & {
     get aborted(): boolean;
     get error(): Error | undefined;
     get exitCode(): number | undefined;
@@ -50,7 +62,9 @@ export type Subprocess = AsyncIterable<string> & PromiseLike<ExecResult> & {
     kill: (signal?: KillSignal) => boolean;
     get killed(): boolean;
     get pid(): number | undefined;
-    pipe: (command: string, args?: readonly string[], options?: Partial<Options>) => Subprocess;
+    pipe: <N extends ResultMode = 'result'>(command: string, args?: readonly string[], options?: Partial<Options> & {
+        resultMode?: N;
+    }) => Subprocess<N>;
     get process(): ChildProcess | undefined;
     get signalCode(): string | undefined;
 };

package/lib/cjs/utils/normalizeOptions.cjs

@@ -6,9 +6,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeOptions = normalizeOptions;
 const node_path_1 = __importDefault(require("node:path"));
 const computeEnv_js_1 = require("./env/computeEnv.cjs");
-const combineSignals_js_1 = require("../combineSignals.cjs");
+const combineSignals_js_1 = require("./combineSignals.cjs");
 function normalizeOptions(options) {
-    const { cwd, env, preferLocal, signal, stderr, stdin, stdio: stdioOption, stdout, ...restOptions } = options;
+    const { cwd, env, preferLocal, resultMode: _resultMode, signal, stderr, stdin, stdio: stdioOption, stdout, ...restOptions } = options;
     const spawnOptions = restOptions;
     spawnOptions.cwd = node_path_1.default.resolve(cwd ?? process.cwd());
     spawnOptions.env = (0, computeEnv_js_1.computeEnv)(env, preferLocal ?? false, options.localDir ?? spawnOptions.cwd);

package/lib/cjs/utils/stream/readStream.cjs

@@ -6,7 +6,7 @@ async function readStream(stream, context) {
     try {
         for await (const chunk of stream) {
             output += String(chunk);
-            context.all += String(chunk);
+            context.merged += String(chunk);
         }
     }
     catch {

package/lib/cjs/utils/stream/readStream.d.cts

@@ -1,5 +1,5 @@
 import type { Readable } from 'node:stream';
 export type StreamContext = {
-    all: string;
+    merged: string;
 };
 export declare function readStream(stream: Readable, context: StreamContext): Promise<string>;

package/lib/esm/create-command.d.mts

@@ -0,0 +1,3 @@
+import type { Command, Options, ResultMode, Subprocess } from './types.mjs';
+declare function createCommand<M extends ResultMode = 'result'>(command: string, args?: readonly string[] | null, options?: Partial<Options<M>>): Command<M>;
+export { type Command, type Options, type ResultMode, type Subprocess, createCommand, };

package/lib/esm/create-command.mjs

@@ -0,0 +1,17 @@
+import { exec } from './exec.mjs';
+function createCommand(command, args = [], options = {}) {
+    const create = (options) => {
+        const run = ((runArgs, runOptions) => {
+            return exec(command, [...(args ?? []), ...(runArgs ?? [])], {
+                ...options,
+                ...runOptions,
+            });
+        });
+        run.withOptions = (overrides) => create({ ...options, ...overrides });
+        run.toCwdFirst = () => ((cwd, ...runArgs) => run(runArgs, { cwd }));
+        run.toFlatArgs = () => ((...runArgs) => run(runArgs));
+        return run;
+    };
+    return create(options);
+}
+export { createCommand, };

package/lib/esm/exec-process.d.mts

@@ -1,10 +1,11 @@
 import type { ChildProcess } from 'node:child_process';
 import type { Readable } from 'node:stream';
-import type { ExecFailure, ExecResult, KillSignal, Options, Subprocess } from './types.mjs';
-export declare class ExecProcess implements Subprocess {
+import type { ExecFailure, ExecResult, ExecSuccess, KillSignal, Options, ResultMode, Subprocess } from './types.mjs';
+declare class ExecProcess implements Subprocess<ResultMode> {
     protected _aborted: boolean;
     protected _args: readonly string[];
     protected _command: string;
+    protected _cwd: string | undefined;
     protected _failed: boolean;
     protected _options: Partial<Options>;
     protected _process?: ChildProcess;
@@ -25,13 +26,16 @@ export declare class ExecProcess implements Subprocess {
     get process(): ChildProcess | undefined;
     get signalCode(): string | undefined;
     kill(signal?: KillSignal): boolean;
-    pipe(command: string, args?: readonly string[], options?: Partial<Options>): Subprocess;
+    pipe<N extends ResultMode = 'result'>(command: string, args?: readonly string[], options?: Partial<Options> & {
+        resultMode?: N;
+    }): Subprocess<N>;
     spawn(): void;
     [Symbol.asyncIterator](): AsyncIterator<string>;
-    then<TResult1 = ExecResult, TResult2 = never>(onfulfilled?: ((value: ExecResult) => PromiseLike<TResult1> | TResult1) | null, onrejected?: ((reason: unknown) => PromiseLike<TResult2> | TResult2) | null): Promise<TResult1 | TResult2>;
+    then<TResult1 = ExecResult<ResultMode>, TResult2 = never>(onfulfilled?: ((value: ExecResult<ResultMode>) => PromiseLike<TResult1> | TResult1) | null, onrejected?: ((reason: unknown) => PromiseLike<TResult2> | TResult2) | null): Promise<TResult1 | TResult2>;
     protected onClose(): void;
     protected onError(error: Error): void;
     protected reset(): void;
-    protected toFailure(error: Error): ExecFailure;
-    protected toResult(): Promise<ExecResult>;
+    protected toFailure(error: Error): ExecResult<ResultMode>;
+    protected toResult(): Promise<ExecResult<ResultMode>>;
 }
+export { type ExecFailure, type ExecResult, type ExecSuccess, type KillSignal, type Options, type ResultMode, type Subprocess, ExecProcess, };

package/lib/esm/exec-process.mjs

@@ -1,15 +1,16 @@
 import { spawn } from 'node:child_process';
 import readline from 'node:readline';
-import { err, ok } from '@zokugun/xtry';
+import { err, ok, stringifyError } from '@zokugun/xtry';
 import { exec } from './exec.mjs';
 import { normalizeCommand } from './utils/command/normalizeCommand.mjs';
 import { normalizeOptions } from './utils/normalizeOptions.mjs';
 import { combineStreams } from './utils/stream/combineStreams.mjs';
 import { readStream } from './utils/stream/readStream.mjs';
-export class ExecProcess {
+class ExecProcess {
     _aborted = false;
     _args;
     _command;
+    _cwd;
     _failed = false;
     _options;
     _process;
@@ -69,6 +70,7 @@ export class ExecProcess {
         this._start = process.hrtime.bigint();
         this.reset();
         const normalizedOptions = normalizeOptions(this._options);
+        this._cwd = normalizedOptions.cwd;
         if (normalizedOptions.signal) {
             this._signal = normalizedOptions.signal;
         }
@@ -132,7 +134,12 @@ export class ExecProcess {
     } // }}}
     // eslint-disable-next-line ts/promise-function-async
     then(onfulfilled, onrejected) {
-        return this.toResult().then(onfulfilled, onrejected);
+        return this.toResult().then((result) => {
+            if (onfulfilled) {
+                return onfulfilled(result);
+            }
+            return result;
+        }, onrejected);
     } // }}}
     onClose() {
         if (this._resolveClose) {
@@ -159,26 +166,31 @@ export class ExecProcess {
     } // }}}
     toFailure(error) {
         this._failed = true;
+        if (this._options.resultMode === 'merged') {
+            return stringifyError(error);
+        }
         const result = {
-            all: '',
+            args: this._args,
             canceled: this._signal?.aborted ?? false,
             command: this._command,
+            cwd: this._cwd,
             durationMs: Number(process.hrtime.bigint() - this._start) / 1e6,
             error,
             exitCode: this.exitCode,
+            merged: '',
             signalCode: this.signalCode,
         };
-        return result;
+        return err(result);
     } // }}}
     async toResult() {
         if (this._thrownError) {
-            return err(this.toFailure(this._thrownError));
+            return this.toFailure(this._thrownError);
         }
         const task = this._process;
         if (!task) {
-            return err(this.toFailure(new Error('No process was started')));
+            return this.toFailure(new Error('No process was started'));
         }
-        const context = { all: '' };
+        const context = { merged: '' };
         const [stdout, stderr] = await Promise.all([
             this._streamOut ? readStream(this._streamOut, context) : '',
             this._streamErr ? readStream(this._streamErr, context) : '',
@@ -190,13 +202,21 @@ export class ExecProcess {
         }
         task.removeAllListeners();
         if (this._thrownError) {
-            return err(this.toFailure(this._thrownError));
+            return this.toFailure(this._thrownError);
+        }
+        if (this._options.resultMode === 'merged') {
+            if ((this.exitCode !== 0 && this.exitCode !== undefined) || this.signalCode !== undefined) {
+                this._failed = true;
+            }
+            return context.merged;
         }
         const result = {
-            all: context.all,
+            args: this._args,
             command: this._command,
+            cwd: this._cwd,
             durationMs: Number(process.hrtime.bigint() - this._start) / 1e6,
             exitCode: this.exitCode,
+            merged: context.merged,
             stderr,
             stdout,
         };
@@ -212,3 +232,4 @@ export class ExecProcess {
         return ok(result);
     } // }}}
 }
+export { ExecProcess, };

package/lib/esm/exec.d.mts

@@ -1,2 +1,3 @@
-import type { Options, Subprocess } from './types.mjs';
-export declare function exec(command: string, args?: readonly string[] | null, options?: Partial<Options>): Subprocess;
+import type { Options, ResultMode, Subprocess } from './types.mjs';
+declare function exec<M extends ResultMode = 'result'>(command: string, args?: readonly string[] | null, options?: Partial<Options<M>>): Subprocess<M>;
+export { type Options, type ResultMode, type Subprocess, exec, };

package/lib/esm/exec.mjs

@@ -1,6 +1,7 @@
 import { ExecProcess } from './exec-process.mjs';
-export function exec(command, args, options) {
+function exec(command, args, options) {
     const subprocess = new ExecProcess(command, args, options);
     subprocess.spawn();
     return subprocess;
 }
+export { exec, };

package/lib/esm/index.d.mts

@@ -1,3 +1,4 @@
+export type { Command, ExecFailure, ExecResult, ExecSuccess, KillSignal, Options, ResultMode, StdinOption, StdioOption, Subprocess, } from './types.mjs';
+export { createCommand } from './create-command.mjs';
 export { ExecProcess } from './exec-process.mjs';
 export { exec } from './exec.mjs';
-export { ExecFailure, ExecResult, ExecSuccess, KillSignal, Options, StdinOption, StdioOption, Subprocess, } from './types.mjs';

package/lib/esm/index.mjs

@@ -1,2 +1,3 @@
+export { createCommand } from './create-command.mjs';
 export { ExecProcess } from './exec-process.mjs';
 export { exec } from './exec.mjs';

package/lib/esm/types.d.mts

@@ -1,37 +1,49 @@
 import type { ChildProcess, SpawnOptions as ProcessSpawnOptions } from 'node:child_process';
 import type { Result } from '@zokugun/xtry';
+export type Command<M extends ResultMode = 'result'> = {
+    (args?: readonly string[] | null, options?: Partial<Options<M>>): Subprocess<M>;
+    toCwdFirst(): (cwd: string, ...args: string[]) => Subprocess<M>;
+    toFlatArgs(): (...args: string[]) => Subprocess<M>;
+    withOptions(options: Partial<Options<M>>): Command<M>;
+};
 export type ExecFailure = {
-    all?: string;
+    args: readonly string[];
     canceled: boolean;
+    cwd?: string;
     command: string;
     durationMs: number;
     error?: Error;
     exitCode?: number;
+    merged?: string;
     pipedFrom?: ExecResult;
     signalCode?: string;
     stderr?: string;
     stdout?: string;
 };
-export type ExecResult = Result<ExecSuccess, ExecFailure>;
+export type ResultMode = 'merged' | 'result';
+export type ExecResult<M extends ResultMode = 'result'> = M extends 'merged' ? string : Result<ExecSuccess, ExecFailure>;
 export type ExecSuccess = {
-    all: string;
+    args: readonly string[];
     command: string;
+    cwd: string;
     durationMs: number;
     error?: undefined;
     exitCode: number;
+    merged: string;
     pipedFrom?: ExecResult;
     stderr: string;
     stdout: string;
 };
 export type KillSignal = Parameters<ChildProcess['kill']>[0];
-export type Options = Omit<ProcessSpawnOptions, 'cwd' | 'env' | 'stdio'> & Readonly<Partial<{
+export type Options<M extends ResultMode = ResultMode> = Omit<ProcessSpawnOptions, 'cwd' | 'env' | 'stdio'> & Readonly<Partial<{
     cwd?: string;
     env: Readonly<Partial<Record<string, string>>>;
     localDir: string;
     preferLocal: boolean;
+    resultMode: M;
     signal: AbortSignal;
     stderr: StdioOption;
-    stdin: ExecResult | StdinOption | Subprocess;
+    stdin: ExecResult | StdinOption | Subprocess<ResultMode>;
     stdio: readonly [StdinOption, ...readonly StdioOption[]] | SpawnOptions['stdio'];
     stdout: StdioOption;
 }>>;
@@ -42,7 +54,7 @@ export type StdinOption = StdioOption | {
     readonly string?: string;
 };
 export type StdioOption = Readonly<Exclude<SpawnOptions['stdio'], undefined>[number]>;
-export type Subprocess = AsyncIterable<string> & PromiseLike<ExecResult> & {
+export type Subprocess<M extends ResultMode = 'result'> = AsyncIterable<string> & PromiseLike<ExecResult<M>> & {
     get aborted(): boolean;
     get error(): Error | undefined;
     get exitCode(): number | undefined;
@@ -50,7 +62,9 @@ export type Subprocess = AsyncIterable<string> & PromiseLike<ExecResult> & {
     kill: (signal?: KillSignal) => boolean;
     get killed(): boolean;
     get pid(): number | undefined;
-    pipe: (command: string, args?: readonly string[], options?: Partial<Options>) => Subprocess;
+    pipe: <N extends ResultMode = 'result'>(command: string, args?: readonly string[], options?: Partial<Options> & {
+        resultMode?: N;
+    }) => Subprocess<N>;
     get process(): ChildProcess | undefined;
     get signalCode(): string | undefined;
 };

package/lib/esm/utils/normalizeOptions.mjs

@@ -1,8 +1,8 @@
 import path from 'node:path';
 import { computeEnv } from './env/computeEnv.mjs';
-import { combineSignals } from '../combineSignals.mjs';
+import { combineSignals } from './combineSignals.mjs';
 export function normalizeOptions(options) {
-    const { cwd, env, preferLocal, signal, stderr, stdin, stdio: stdioOption, stdout, ...restOptions } = options;
+    const { cwd, env, preferLocal, resultMode: _resultMode, signal, stderr, stdin, stdio: stdioOption, stdout, ...restOptions } = options;
     const spawnOptions = restOptions;
     spawnOptions.cwd = path.resolve(cwd ?? process.cwd());
     spawnOptions.env = computeEnv(env, preferLocal ?? false, options.localDir ?? spawnOptions.cwd);

package/lib/esm/utils/stream/readStream.d.mts

@@ -1,5 +1,5 @@
 import type { Readable } from 'node:stream';
 export type StreamContext = {
-    all: string;
+    merged: string;
 };
 export declare function readStream(stream: Readable, context: StreamContext): Promise<string>;

package/lib/esm/utils/stream/readStream.mjs

@@ -3,7 +3,7 @@ export async function readStream(stream, context) {
     try {
         for await (const chunk of stream) {
             output += String(chunk);
-            context.all += String(chunk);
+            context.merged += String(chunk);
         }
     }
     catch {

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@zokugun/exec-lite",
 	"description": "A lightweight tool for running shell commands and reading their output easily.",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"author": {
 		"name": "Baptiste Augrain",
 		"email": "daiyam@zokugun.org"
@@ -20,6 +20,18 @@
 		".": {
 			"import": "./lib/esm/index.mjs",
 			"require": "./lib/cjs/index.cjs"
+		},
+		"./command-line": {
+			"import": "./lib/esm/command-line.mjs",
+			"require": "./lib/cjs/command-line.cjs"
+		},
+		"./exec-process": {
+			"import": "./lib/esm/exec-process.mjs",
+			"require": "./lib/cjs/exec-process.cjs"
+		},
+		"./exec": {
+			"import": "./lib/esm/exec.mjs",
+			"require": "./lib/cjs/exec.cjs"
 		}
 	},
 	"main": "lib/cjs/index.cjs",
@@ -28,6 +40,15 @@
 		"*": {
 			".": [
 				"./lib/cjs/index.d.cts"
+			],
+			"command-line": [
+				"./lib/cjs/command-line.d.cts"
+			],
+			"exec-process": [
+				"./lib/cjs/exec-process.d.cts"
+			],
+			"exec": [
+				"./lib/cjs/exec.d.cts"
 			]
 		}
 	},
@@ -47,6 +68,7 @@
 		"lint:package": "fixpack || true",
 		"prepack": "npm run build",
 		"prepare": "husky; npm run lint:package",
+		"release": "bump-n-ship release --all --pause",
 		"test": "vitest run --reporter tree",
 		"test:coverage": "vitest run --reporter tree --coverage --coverage.reporter text",
 		"test:ui": "vitest --ui --coverage",
@@ -67,6 +89,7 @@
 		"@types/node": "20.19.43",
 		"@vitest/coverage-v8": "4.1.12",
 		"@vitest/ui": "4.1.12",
+		"@zokugun/bump-n-ship": "0.1.1",
 		"@zokugun/eslint-config": "0.2.1",
 		"@zokugun/eslint-config-data": "0.2.1",
 		"@zokugun/eslint-config-glossary": "0.2.0",
@@ -77,7 +100,7 @@
 		"@zokugun/eslint-config-test": "0.2.0",
 		"@zokugun/eslint-config-ts": "0.3.2",
 		"@zokugun/fs-extra-plus": "0.7.0",
-		"@zokugun/tsc-leda": "0.9.4",
+		"@zokugun/tsc-leda": "0.9.5",
 		"eslint": "10.13.0",
 		"fixpack": "4.0.0",
 		"get-node": "15.0.4",