ts-repo-utils 5.2.0 → 5.3.0

package/dist/functions/exec-async.d.mts

@@ -1,17 +1,26 @@
-import { type ExecException } from 'node:child_process';
+import { type ExecException, type ExecOptions as ExecOptions_ } from 'node:child_process';
 import { Result } from 'ts-data-forge';
+type ExecOptionsCustom = Readonly<{
+    silent?: boolean;
+}>;
+type ExecOptions = DeepReadonly<ExecOptions_ & ExecOptionsCustom>;
+type ExecResult<T extends string | Buffer> = Result<Readonly<{
+    stdout: T;
+    stderr: T;
+}>, ExecException>;
 /**
  * Executes a shell command asynchronously.
  *
- * @param cmd - The command to execute.
+ * @param command - The command to execute.
  * @param options - Optional configuration for command execution.
  * @returns A promise that resolves with the command result.
  */
-export declare const $: (cmd: string, options?: Readonly<{
-    silent?: boolean;
-    timeout?: number;
-}>) => Promise<Result<Readonly<{
-    stdout: string;
-    stderr: string;
-}>, ExecException>>;
+export declare function $(command: string, options?: ExecOptionsCustom): Promise<ExecResult<string>>;
+export declare function $(command: string, options: Readonly<{
+    encoding: 'buffer' | null;
+} & ExecOptions>): Promise<ExecResult<Buffer>>;
+export declare function $(command: string, options: Readonly<{
+    encoding: BufferEncoding;
+} & ExecOptions>): Promise<ExecResult<string>>;
+export {};
 //# sourceMappingURL=exec-async.d.mts.map

package/dist/functions/exec-async.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"exec-async.d.mts","sourceRoot":"","sources":["../../src/functions/exec-async.mts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAEvC;;;;;;GAMG;AACH,eAAO,MAAM,CAAC,GACZ,KAAK,MAAM,EACX,UAAS,QAAQ,CAAC;IAAE,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAM,KAC7D,OAAO,CACR,MAAM,CAAC,QAAQ,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,EAAE,aAAa,CAAC,CA6BpE,CAAC"}
+{"version":3,"file":"exec-async.d.mts","sourceRoot":"","sources":["../../src/functions/exec-async.mts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,WAAW,IAAI,YAAY,EACjC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAEvC,KAAK,iBAAiB,GAAG,QAAQ,CAAC;IAChC,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC,CAAC;AAEH,KAAK,WAAW,GAAG,YAAY,CAAC,YAAY,GAAG,iBAAiB,CAAC,CAAC;AAElE,KAAK,UAAU,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI,MAAM,CACjD,QAAQ,CAAC;IAAE,MAAM,EAAE,CAAC,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,CAAC,EAClC,aAAa,CACd,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,CAAC,CACf,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;AAE/B,wBAAgB,CAAC,CACf,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,QAAQ,CAAC;IAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAA;CAAE,GAAG,WAAW,CAAC,GAC7D,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;AAE/B,wBAAgB,CAAC,CACf,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,QAAQ,CAAC;IAAE,QAAQ,EAAE,cAAc,CAAA;CAAE,GAAG,WAAW,CAAC,GAC5D,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC"}

package/dist/functions/exec-async.mjs

@@ -1,22 +1,16 @@
 import { exec } from 'node:child_process';
 import { Result } from 'ts-data-forge';
 
-/**
- * Executes a shell command asynchronously.
- *
- * @param cmd - The command to execute.
- * @param options - Optional configuration for command execution.
- * @returns A promise that resolves with the command result.
- */
-const $ = (cmd, options = {}) => {
-    const { silent = false, timeout = 30000 } = options;
+function $(command, options) {
+    const { silent = false, ...restOptions } = options ?? {};
     if (!silent) {
-        echo(`$ ${cmd}`);
+        echo(`$ ${command}`);
     }
     return new Promise((resolve) => {
-        const execOptions = { timeout };
         // eslint-disable-next-line security/detect-child-process
-        exec(cmd, execOptions, (error, stdout, stderr) => {
+        exec(command, 
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+        restOptions, (error, stdout, stderr) => {
             if (!silent) {
                 if (stdout !== '') {
                     echo(stdout);
@@ -33,7 +27,7 @@ const $ = (cmd, options = {}) => {
             }
         });
     });
-};
+}
 
 export { $ };
 //# sourceMappingURL=exec-async.mjs.map

package/dist/functions/exec-async.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"exec-async.mjs","sources":["../../src/functions/exec-async.mts"],"sourcesContent":[null],"names":[],"mappings":";;;AAGA;;;;;;AAMG;AACI,MAAM,CAAC,GAAG,CACf,GAAW,EACX,OAAA,GAA4D,EAAE,KAG5D;IACF,MAAM,EAAE,MAAM,GAAG,KAAK,EAAE,OAAO,GAAG,KAAK,EAAE,GAAG,OAAO;IAEnD,IAAI,CAAC,MAAM,EAAE;AACX,QAAA,IAAI,CAAC,CAAA,EAAA,EAAK,GAAG,CAAA,CAAE,CAAC;IAClB;AAEA,IAAA,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,KAAI;AAC7B,QAAA,MAAM,WAAW,GAAG,EAAE,OAAO,EAAE;;AAG/B,QAAA,IAAI,CAAC,GAAG,EAAE,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,KAAI;YAC/C,IAAI,CAAC,MAAM,EAAE;AACX,gBAAA,IAAI,MAAM,KAAK,EAAE,EAAE;oBACjB,IAAI,CAAC,MAAM,CAAC;gBACd;AACA,gBAAA,IAAI,MAAM,KAAK,EAAE,EAAE;AACjB,oBAAA,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC;gBACvB;YACF;AAEA,YAAA,IAAI,KAAK,KAAK,IAAI,EAAE;gBAClB,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YAC5B;iBAAO;AACL,gBAAA,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;YACxC;AACF,QAAA,CAAC,CAAC;AACJ,IAAA,CAAC,CAAC;AACJ;;;;"}
+{"version":3,"file":"exec-async.mjs","sources":["../../src/functions/exec-async.mts"],"sourcesContent":[null],"names":[],"mappings":";;;AAwCM,SAAU,CAAC,CACf,OAAe,EACf,OAEC,EAAA;AAED,IAAA,MAAM,EAAE,MAAM,GAAG,KAAK,EAAE,GAAG,WAAW,EAAE,GAAG,OAAO,IAAI,EAAE;IAExD,IAAI,CAAC,MAAM,EAAE;AACX,QAAA,IAAI,CAAC,CAAA,EAAA,EAAK,OAAO,CAAA,CAAE,CAAC;IACtB;AAEA,IAAA,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,KAAI;;AAE7B,QAAA,IAAI,CACF,OAAO;;QAEP,WAEgB,EAChB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,KAAI;YACxB,IAAI,CAAC,MAAM,EAAE;AACX,gBAAA,IAAI,MAAM,KAAK,EAAE,EAAE;oBACjB,IAAI,CAAC,MAAM,CAAC;gBACd;AACA,gBAAA,IAAI,MAAM,KAAK,EAAE,EAAE;AACjB,oBAAA,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC;gBACvB;YACF;AAEA,YAAA,IAAI,KAAK,KAAK,IAAI,EAAE;gBAClB,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YAC5B;iBAAO;AACL,gBAAA,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;YACxC;AACF,QAAA,CAAC,CACF;AACH,IAAA,CAAC,CAAC;AACJ;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-repo-utils",
-  "version": "5.2.0",
+  "version": "5.3.0",
   "private": false,
   "keywords": [
     "typescript"
@@ -57,7 +57,7 @@
     "fast-glob": "^3.3.3",
     "micromatch": "^4.0.8",
     "prettier": "^3.6.2",
-    "ts-data-forge": "^3.0.4"
+    "ts-data-forge": "^3.0.5"
   },
   "devDependencies": {
     "@eslint/js": "^9.31.0",
@@ -91,13 +91,13 @@
     "prettier-plugin-jsdoc": "^1.3.3",
     "prettier-plugin-organize-imports": "^4.2.0",
     "prettier-plugin-packagejson": "^2.5.19",
-    "rollup": "^4.45.1",
+    "rollup": "^4.46.2",
     "semantic-release": "^24.2.7",
     "ts-type-forge": "^2.1.1",
     "tslib": "^2.8.1",
     "tsx": "^4.20.3",
     "typedoc": "^0.28.7",
-    "typedoc-plugin-markdown": "^4.7.1",
+    "typedoc-plugin-markdown": "^4.8.0",
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.38.0",
     "vitest": "^3.2.4"

package/src/functions/exec-async.mts

@@ -1,44 +1,79 @@
-import { exec, type ExecException } from 'node:child_process';
+import {
+  exec,
+  type ExecException,
+  type ExecOptions as ExecOptions_,
+} from 'node:child_process';
 import { Result } from 'ts-data-forge';
 
+type ExecOptionsCustom = Readonly<{
+  silent?: boolean;
+}>;
+
+type ExecOptions = DeepReadonly<ExecOptions_ & ExecOptionsCustom>;
+
+type ExecResult<T extends string | Buffer> = Result<
+  Readonly<{ stdout: T; stderr: T }>,
+  ExecException
+>;
+
 /**
  * Executes a shell command asynchronously.
  *
- * @param cmd - The command to execute.
+ * @param command - The command to execute.
  * @param options - Optional configuration for command execution.
  * @returns A promise that resolves with the command result.
  */
-export const $ = (
-  cmd: string,
-  options: Readonly<{ silent?: boolean; timeout?: number }> = {},
-): Promise<
-  Result<Readonly<{ stdout: string; stderr: string }>, ExecException>
-> => {
-  const { silent = false, timeout = 30000 } = options;
+export function $(
+  command: string,
+  options?: ExecOptionsCustom,
+): Promise<ExecResult<string>>;
+
+export function $(
+  command: string,
+  options: Readonly<{ encoding: 'buffer' | null } & ExecOptions>,
+): Promise<ExecResult<Buffer>>;
+
+export function $(
+  command: string,
+  options: Readonly<{ encoding: BufferEncoding } & ExecOptions>,
+): Promise<ExecResult<string>>;
+
+export function $(
+  command: string,
+  options?: Readonly<
+    { encoding?: BufferEncoding | 'buffer' | null } & ExecOptions
+  >,
+): Promise<ExecResult<string | Buffer>> {
+  const { silent = false, ...restOptions } = options ?? {};
 
   if (!silent) {
-    echo(`$ ${cmd}`);
+    echo(`$ ${command}`);
   }
 
   return new Promise((resolve) => {
-    const execOptions = { timeout };
-
     // eslint-disable-next-line security/detect-child-process
-    exec(cmd, execOptions, (error, stdout, stderr) => {
-      if (!silent) {
-        if (stdout !== '') {
-          echo(stdout);
+    exec(
+      command,
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+      restOptions as {
+        encoding?: 'buffer' | null | BufferEncoding;
+      } & ExecOptions_,
+      (error, stdout, stderr) => {
+        if (!silent) {
+          if (stdout !== '') {
+            echo(stdout);
+          }
+          if (stderr !== '') {
+            console.error(stderr);
+          }
         }
-        if (stderr !== '') {
-          console.error(stderr);
+
+        if (error !== null) {
+          resolve(Result.err(error));
+        } else {
+          resolve(Result.ok({ stdout, stderr }));
         }
-      }
-
-      if (error !== null) {
-        resolve(Result.err(error));
-      } else {
-        resolve(Result.ok({ stdout, stderr }));
-      }
-    });
+      },
+    );
   });
-};
+}

package/src/functions/exec-async.test.mts

@@ -0,0 +1,501 @@
+import { exec, type ExecException } from 'node:child_process';
+import { expectType, Result } from 'ts-data-forge';
+import '../node-global.mjs';
+import { $ } from './exec-async.mjs';
+
+describe('exec-async', () => {
+  // Helper to suppress echo output during tests
+  const withSilentEcho = async <T,>(fn: () => Promise<T>): Promise<T> => {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-type-assertion, @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
+    const originalEcho = (globalThis as any).echo;
+    // eslint-disable-next-line functional/immutable-data, @typescript-eslint/no-unsafe-type-assertion, @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
+    (globalThis as any).echo = () => {
+      // Silent implementation - no output
+    };
+    try {
+      return await fn();
+    } finally {
+      // eslint-disable-next-line functional/immutable-data, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-type-assertion, @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
+      (globalThis as any).echo = originalEcho;
+    }
+  };
+  describe('basic command execution', () => {
+    test('should execute simple command successfully', async () => {
+      const result = await $('echo "hello world"', { silent: true });
+
+      expect(Result.isOk(result)).toBe(true);
+      if (Result.isOk(result)) {
+        expect(result.value.stdout.trim()).toBe('hello world');
+        expect(result.value.stderr).toBe('');
+      }
+    });
+
+    test('should execute command with multiple lines of output', async () => {
+      const result = await $('echo "line1\nline2\nline3"', { silent: true });
+
+      expect(Result.isOk(result)).toBe(true);
+      if (Result.isOk(result)) {
+        expect(result.value.stdout.trim()).toBe('line1\nline2\nline3');
+        expect(result.value.stderr).toBe('');
+      }
+    });
+
+    test('should handle empty output', async () => {
+      const result = await $('true', { silent: true });
+
+      expect(Result.isOk(result)).toBe(true);
+      if (Result.isOk(result)) {
+        expect(result.value.stdout).toBe('');
+        expect(result.value.stderr).toBe('');
+      }
+    });
+  });
+
+  describe('error handling', () => {
+    test('should handle command not found error', async () => {
+      const result = await $('nonexistent_command_xyz', { silent: true });
+
+      expect(Result.isErr(result)).toBe(true);
+      if (Result.isErr(result)) {
+        expect(result.value).toBeDefined();
+        expect(result.value.code).toBeDefined();
+      }
+    });
+
+    test('should handle exit code error', async () => {
+      const result = await $('exit 1', { silent: true });
+
+      expect(Result.isErr(result)).toBe(true);
+      if (Result.isErr(result)) {
+        expect(result.value).toBeDefined();
+        expect(result.value.code).toBe(1);
+      }
+    });
+
+    test('should capture stderr on error', async () => {
+      const result = await $('>&2 echo "error message" && exit 1', {
+        silent: true,
+      });
+
+      expect(Result.isErr(result)).toBe(true);
+      if (Result.isErr(result)) {
+        expect(result.value).toBeDefined();
+      }
+    });
+  });
+
+  describe('silent option', () => {
+    test('should not output when silent is true', async () => {
+      // Silent mode should not produce any output
+      await $('echo "test"', { silent: true });
+      // If no error is thrown, the test passes
+    });
+
+    test('should output when silent is false', async () => {
+      // Non-silent mode should produce output (suppressed for clean test output)
+      await withSilentEcho(async () => {
+        await $('echo "test"', { silent: false });
+      });
+      // If no error is thrown, the test passes
+    });
+
+    test('should default to not silent', async () => {
+      // Default behavior should produce output (suppressed for clean test output)
+      await withSilentEcho(async () => {
+        await $('echo "test"');
+      });
+      // If no error is thrown, the test passes
+    });
+  });
+
+  describe('encoding options', () => {
+    test('should return string with default encoding', async () => {
+      const result = await $('echo "test"', { silent: true });
+
+      expect(Result.isOk(result)).toBe(true);
+      if (Result.isOk(result)) {
+        expect(typeof result.value.stdout).toBe('string');
+      }
+    });
+
+    test('should return Buffer with buffer encoding', async () => {
+      const result = await $('echo "test"', {
+        silent: true,
+        encoding: 'buffer',
+      });
+
+      expect(Result.isOk(result)).toBe(true);
+      if (Result.isOk(result)) {
+        expect(Buffer.isBuffer(result.value.stdout)).toBe(true);
+        expect(Buffer.isBuffer(result.value.stderr)).toBe(true);
+      }
+    });
+
+    test('should return Buffer with null encoding', async () => {
+      const result = await $('echo "test"', { silent: true, encoding: null });
+
+      expect(Result.isOk(result)).toBe(true);
+      if (Result.isOk(result)) {
+        expect(Buffer.isBuffer(result.value.stdout)).toBe(true);
+        expect(Buffer.isBuffer(result.value.stderr)).toBe(true);
+      }
+    });
+
+    test('should handle utf8 encoding', async () => {
+      const result = await $('echo "test 日本語"', {
+        silent: true,
+        encoding: 'utf8',
+      });
+
+      expect(Result.isOk(result)).toBe(true);
+      if (Result.isOk(result)) {
+        expect(typeof result.value.stdout).toBe('string');
+        expect(result.value.stdout.trim()).toBe('test 日本語');
+      }
+    });
+  });
+
+  describe('complex commands', () => {
+    test('should handle pipes', async () => {
+      const result = await $('echo "hello world" | grep "world"', {
+        silent: true,
+      });
+
+      expect(Result.isOk(result)).toBe(true);
+      if (Result.isOk(result)) {
+        expect(result.value.stdout.trim()).toBe('hello world');
+      }
+    });
+
+    test('should handle command chaining with &&', async () => {
+      const result = await $('echo "first" && echo "second"', { silent: true });
+
+      expect(Result.isOk(result)).toBe(true);
+      if (Result.isOk(result)) {
+        expect(result.value.stdout.trim()).toBe('first\nsecond');
+      }
+    });
+
+    test('should handle command chaining with ;', async () => {
+      const result = await $('echo "first"; echo "second"', { silent: true });
+
+      expect(Result.isOk(result)).toBe(true);
+      if (Result.isOk(result)) {
+        expect(result.value.stdout.trim()).toBe('first\nsecond');
+      }
+    });
+
+    test('should stop on first error with &&', async () => {
+      const result = await $('false && echo "should not print"', {
+        silent: true,
+      });
+
+      expect(Result.isErr(result)).toBe(true);
+    });
+  });
+
+  describe('type inference (compile-time checks)', () => {
+    test('should infer string result type with no encoding option', async () => {
+      const result = await $('echo "test"', { silent: true });
+
+      // Type assertion: result should be string type
+      assertType<
+        Result<Readonly<{ stdout: string; stderr: string }>, ExecException>
+      >(result);
+
+      if (Result.isOk(result)) {
+        // These assignments will fail at compile time if types don't match
+        assertType<string>(result.value.stdout);
+        assertType<string>(result.value.stderr);
+      }
+    });
+
+    test('should infer string result type with default options', async () => {
+      const _result = await withSilentEcho(async () => $('echo "test"'));
+
+      expectType<
+        typeof _result,
+        Result<Readonly<{ stdout: string; stderr: string }>, ExecException>
+      >('=');
+    });
+
+    test('should infer Buffer result type with buffer encoding', async () => {
+      const result = await $('echo "test"', {
+        encoding: 'buffer',
+        silent: true,
+      });
+
+      expectType<
+        typeof result,
+        Result<Readonly<{ stdout: Buffer; stderr: Buffer }>, ExecException>
+      >('=');
+
+      if (Result.isOk(result)) {
+        assertType<Buffer>(result.value.stdout);
+        assertType<Buffer>(result.value.stderr);
+      }
+    });
+
+    test('should infer Buffer result type with null encoding', async () => {
+      const result = await $('echo "test"', { encoding: null, silent: true });
+
+      expectType<
+        typeof result,
+        Result<Readonly<{ stdout: Buffer; stderr: Buffer }>, ExecException>
+      >('=');
+
+      if (Result.isOk(result)) {
+        assertType<Buffer>(result.value.stdout);
+        assertType<Buffer>(result.value.stderr);
+      }
+    });
+
+    test('should infer string result type with specific BufferEncoding', async () => {
+      const _resultUtf8 = await $('echo "test"', {
+        encoding: 'utf8',
+        silent: true,
+      });
+      const _resultAscii = await $('echo "test"', {
+        encoding: 'ascii',
+        silent: true,
+      });
+      const _resultBase64 = await $('echo "test"', {
+        encoding: 'base64',
+        silent: true,
+      });
+
+      expectType<
+        typeof _resultUtf8,
+        Result<Readonly<{ stdout: string; stderr: string }>, ExecException>
+      >('=');
+
+      expectType<
+        typeof _resultAscii,
+        Result<Readonly<{ stdout: string; stderr: string }>, ExecException>
+      >('=');
+
+      expectType<
+        typeof _resultBase64,
+        Result<Readonly<{ stdout: string; stderr: string }>, ExecException>
+      >('=');
+    });
+
+    test('should maintain type safety with const encoding values', async () => {
+      const bufferEncoding = 'buffer';
+      const nullEncoding = null;
+      const utf8Encoding = 'utf8';
+
+      const _resultBuffer = await $('echo "test"', {
+        encoding: bufferEncoding,
+        silent: true,
+      });
+      const _resultNull = await $('echo "test"', {
+        encoding: nullEncoding,
+        silent: true,
+      });
+      const _resultUtf8 = await $('echo "test"', {
+        encoding: utf8Encoding,
+        silent: true,
+      });
+
+      expectType<
+        typeof _resultBuffer,
+        Result<Readonly<{ stdout: Buffer; stderr: Buffer }>, ExecException>
+      >('=');
+
+      expectType<
+        typeof _resultNull,
+        Result<Readonly<{ stdout: Buffer; stderr: Buffer }>, ExecException>
+      >('=');
+
+      expectType<
+        typeof _resultUtf8,
+        Result<Readonly<{ stdout: string; stderr: string }>, ExecException>
+      >('=');
+    });
+
+    test('should handle union types when encoding is not const', async () => {
+      // Test that when we don't know the encoding at compile time,
+      // we need to check the type at runtime
+      const randomEncoding = Math.random() > 0.5 ? 'utf8' : 'buffer';
+
+      if (randomEncoding === 'buffer') {
+        const _result = await $('echo "test"', {
+          encoding: randomEncoding,
+          silent: true,
+        });
+
+        expectType<
+          typeof _result,
+          Result<Readonly<{ stdout: Buffer; stderr: Buffer }>, ExecException>
+        >('=');
+      } else {
+        const _result = await $('echo "test"', {
+          encoding: randomEncoding,
+          silent: true,
+        });
+
+        expectType<
+          typeof _result,
+          Result<Readonly<{ stdout: string; stderr: string }>, ExecException>
+        >('=');
+      }
+    });
+  });
+
+  describe('type correspondence with native exec', () => {
+    test('should match exec callback types for default encoding', () => {
+      // Type check for native exec with default options
+      exec('echo "test"', (error, stdout, stderr) => {
+        expectType<ExecException | null, typeof error>('=');
+        expectType<string, typeof stdout>('=');
+        expectType<string, typeof stderr>('=');
+      });
+
+      // The $ function should produce the same types wrapped in Result (suppressed for clean output)
+      const _resultPromise = withSilentEcho(async () => $('echo "test"'));
+      expectType<
+        typeof _resultPromise,
+        Promise<
+          Result<Readonly<{ stdout: string; stderr: string }>, ExecException>
+        >
+      >('=');
+    });
+
+    test('should match exec callback types for buffer encoding', () => {
+      // Type check for native exec with buffer encoding
+      exec('echo "test"', { encoding: 'buffer' }, (error, stdout, stderr) => {
+        expectType<ExecException | null, typeof error>('=');
+        expectType<Buffer, typeof stdout>('=');
+        expectType<Buffer, typeof stderr>('=');
+      });
+
+      // The $ function should produce the same types wrapped in Result (suppressed for clean output)
+      const _resultPromise = withSilentEcho(async () =>
+        $('echo "test"', { encoding: 'buffer' }),
+      );
+      expectType<
+        typeof _resultPromise,
+        Promise<
+          Result<Readonly<{ stdout: Buffer; stderr: Buffer }>, ExecException>
+        >
+      >('=');
+    });
+
+    test('should match exec callback types for null encoding', () => {
+      // Type check for native exec with null encoding
+      exec('echo "test"', { encoding: null }, (error, stdout, stderr) => {
+        expectType<ExecException | null, typeof error>('=');
+        expectType<Buffer, typeof stdout>('=');
+        expectType<Buffer, typeof stderr>('=');
+      });
+
+      // The $ function should produce the same types wrapped in Result (suppressed for clean output)
+      const _resultPromise = withSilentEcho(async () =>
+        $('echo "test"', { encoding: null }),
+      );
+      expectType<
+        typeof _resultPromise,
+        Promise<
+          Result<Readonly<{ stdout: Buffer; stderr: Buffer }>, ExecException>
+        >
+      >('=');
+    });
+
+    test('should match exec callback types for specific BufferEncoding', () => {
+      // Type check for native exec with utf8 encoding
+      exec('echo "test"', { encoding: 'utf8' }, (error, stdout, stderr) => {
+        expectType<ExecException | null, typeof error>('=');
+        expectType<string, typeof stdout>('=');
+        expectType<string, typeof stderr>('=');
+      });
+
+      // The $ function should produce the same types wrapped in Result (suppressed for clean output)
+      const _resultPromise = withSilentEcho(async () =>
+        $('echo "test"', { encoding: 'utf8' }),
+      );
+      expectType<
+        typeof _resultPromise,
+        Promise<
+          Result<Readonly<{ stdout: string; stderr: string }>, ExecException>
+        >
+      >('=');
+    });
+
+    test('should match exec callback types with custom options', () => {
+      // Type check for native exec with custom options
+      exec(
+        'echo "test"',
+        { encoding: 'utf8', timeout: 5000 },
+        (error, stdout, stderr) => {
+          expectType<ExecException | null, typeof error>('=');
+          expectType<string, typeof stdout>('=');
+          expectType<string, typeof stderr>('=');
+        },
+      );
+
+      // The $ function with silent option should produce the same stdout/stderr types
+      const _resultPromise = $('echo "test"', {
+        encoding: 'utf8',
+        silent: true,
+      });
+      expectType<
+        typeof _resultPromise,
+        Promise<
+          Result<Readonly<{ stdout: string; stderr: string }>, ExecException>
+        >
+      >('=');
+    });
+
+    test('should demonstrate type equivalence with runtime comparison', async () => {
+      // Create a type that represents what exec callback receives
+      type ExecCallbackParams<T extends string | Buffer> = {
+        error: ExecException | null;
+        stdout: T;
+        stderr: T;
+      };
+
+      // Helper to capture exec callback types
+      const captureExecTypes = <T extends string | Buffer>(
+        _encoding?: BufferEncoding | 'buffer' | null,
+      ): ExecCallbackParams<T> => {
+        const emptyParams: ExecCallbackParams<T> = {
+          error: null,
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+          stdout: undefined as unknown as T,
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+          stderr: undefined as unknown as T,
+        };
+        return emptyParams;
+      };
+
+      // Default encoding comparison
+      const _execDefault = captureExecTypes<string>();
+      const $Default = await $('echo "test"', { silent: true });
+      if (Result.isOk($Default)) {
+        expectType<typeof _execDefault.stdout, typeof $Default.value.stdout>(
+          '=',
+        );
+        expectType<typeof _execDefault.stderr, typeof $Default.value.stderr>(
+          '=',
+        );
+      }
+
+      // Buffer encoding comparison
+      const _execBuffer = captureExecTypes<Buffer>('buffer');
+      const $Buffer = await $('echo "test"', {
+        encoding: 'buffer',
+        silent: true,
+      });
+      if (Result.isOk($Buffer)) {
+        expectType<typeof _execBuffer.stdout, typeof $Buffer.value.stdout>('=');
+        expectType<typeof _execBuffer.stderr, typeof $Buffer.value.stderr>('=');
+      }
+
+      // Error type comparison
+      if (Result.isErr($Default)) {
+        expectType<ExecException, typeof $Default.value>('=');
+      }
+    });
+  });
+});