@goodbyenjn/utils 26.1.2 → 26.1.3

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://badge.fury.io/js/@goodbyenjn%2Futils.svg)](https://badge.fury.io/js/@goodbyenjn%2Futils)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A modern TypeScript/JavaScript utility library providing a comprehensive collection of type-safe utility functions, functional error handling with the Result pattern, and filesystem operations.
+A modern TypeScript/JavaScript utility library providing a comprehensive collection of type-safe utility functions, functional error handling with the Result pattern, filesystem operations, and shell command execution.
 
 ## Features
 
@@ -12,7 +12,8 @@ A modern TypeScript/JavaScript utility library providing a comprehensive collect
 - 📦 **Modular**: Import only what you need with tree-shakable exports and multiple entry points
 - 🛡️ **Result Pattern**: Functional error handling without exceptions, based on Rust-style Result types
 - 📁 **Safe File System**: Type-safe file system operations with Result-based error handling
-- 🧰 **Common Utilities**: String manipulation, math operations, promise utilities, shell commands, and error handling
+- 🐚 **Shell Execution**: Powerful and flexible shell command execution with piping support
+- 🧰 **Common Utilities**: String manipulation, math operations, promise utilities, and error handling
 - 📊 **Remeda Extensions**: Extended utilities built on top of [Remeda](https://remedajs.com/)
 
 ## Installation
@@ -31,7 +32,8 @@ yarn add @goodbyenjn/utils
 
 ```typescript
 // Import what you need from the main module
-import { sleep, template, $ } from "@goodbyenjn/utils";
+import { sleep, template } from "@goodbyenjn/utils";
+import { $ } from "@goodbyenjn/utils/shell";
 import { safeReadFile } from "@goodbyenjn/utils/fs";
 import { ok, Result } from "@goodbyenjn/utils/result";
 ```
@@ -151,30 +153,32 @@ const result = await promise;
 #### Shell Command Execution
 
 ```typescript
-import { $ } from "@goodbyenjn/utils";
-
-// Execute shell commands safely using template literals
-const result = await $`ls -la`;
-if (result.isOk()) {
-    console.log("Command succeeded:");
-    console.log("stdout:", result.unwrap().stdout);
-    console.log("stderr:", result.unwrap().stderr);
-} else if (result.isErr()) {
-    console.error("Command failed:", result.unwrapErr().message);
-}
+import { $ } from "@goodbyenjn/utils/shell";
+
+// Execute shell commands with template literals
+const result = await $`npm install`;
+console.log(result.stdout);
+console.log(result.stderr);
+
+// String command with args
+const output = await $("ls", ["-la"]);
+console.log(output.stdout);
 
-// Complex command with options
-const { $ } = await import("@goodbyenjn/utils");
-const deployResult = await $`docker build -t myapp .`;
-if (deployResult.isOk()) {
-    const { stdout, stderr } = deployResult.unwrap();
-    console.log("Build output:", stdout);
+// Pipe commands
+const piped = await $`echo "hello"`.pipe`cat`;
+console.log(piped.stdout);
+
+// Iterate output line by line
+for await (const line of $`cat large-file.txt`) {
+    console.log(line);
 }
 
-// Using quoteShellArg for safe argument escaping
-import { quoteShellArg } from "@goodbyenjn/utils";
-const userInput = "'; rm -rf /;";
-const safeArg = quoteShellArg(userInput); // Properly escaped for shell
+// Using options
+const result2 = await $("npm", ["install"], { cwd: "/path/to/project" });
+
+// Factory function with options
+const withCwd = $({ cwd: "/path/to/project" });
+const result3 = await withCwd`npm install`;
 ```
 
 #### Math Utilities

package/dist/chunks/{chunk-f4c5d38b.js → chunk-fda806f4.js}

@@ -1001,7 +1001,7 @@ const unindent = (...params) => {
 		return unindentImpl;
 	}
 	if (e$1(params[0]) || e$6(params[0])) return unindentImpl(...params);
-	throw new TypeError("Invalid arguments.");
+	throw new TypeError(`First parameter has an invalid type: "${typeof params[0]}"`);
 };
 /**
 * @example
@@ -1051,7 +1051,7 @@ const indent = (...params) => {
 		indentString = params[0];
 		return indentImpl;
 	}
-	throw new TypeError("Invalid arguments.");
+	throw new TypeError(`First parameter has an invalid type: "${typeof params[0]}"`);
 };
 function template(str, ...args) {
 	const [firstArg, fallback] = args;
@@ -1065,74 +1065,6 @@ function template(str, ...args) {
 	});
 }
 
-//#endregion
-//#region src/common/shell.ts
-const REGEXP_NULL_CHAR = /\x00+/g;
-const REGEXP_SAFE_CHARS = /^[A-Za-z0-9,:=_./-]+$/;
-const REGEXP_SINGLE_QUOTES = /'+/g;
-const noop = () => {};
-const pipeToStdout = (chunk) => process.stdout.write(chunk);
-const pipeToStderr = (chunk) => process.stderr.write(chunk);
-async function $(cmd, ...values) {
-	const { spawn } = await import("node:child_process");
-	const [command, options] = e$1(cmd) ? [cmd, values[0] || {}] : [concatTemplateStrings(cmd, values), {}];
-	const stdio = [
-		"inherit",
-		"pipe",
-		"pipe"
-	];
-	let onStdin = noop;
-	if (options.onStdin !== void 0) {
-		stdio[0] = "pipe";
-		if (isFunction(options.onStdin)) onStdin = options.onStdin;
-		else {
-			const chunk = options.onStdin;
-			onStdin = (stdin) => stdin.write(chunk);
-		}
-	}
-	const onStdout = options.onStdout === "ignore" ? noop : options.onStdout === "print" ? pipeToStdout : options.onStdout || noop;
-	const onStderr = options.onStderr === "ignore" ? noop : options.onStderr === "print" ? pipeToStderr : options.onStderr || noop;
-	const fn = async () => {
-		const { promise, reject, resolve } = createPromiseWithResolvers();
-		const child = spawn(command, {
-			shell: true,
-			stdio
-		});
-		if (stdio[0] === "pipe" && child.stdin) {
-			await onStdin(child.stdin);
-			child.stdin?.end();
-		}
-		let stdout = "";
-		let stderr = "";
-		child.stdout?.on("data", (data) => {
-			const chunk = data.toString();
-			stdout += chunk;
-			onStdout(chunk);
-		});
-		child.stderr?.on("data", (data) => {
-			const chunk = data.toString();
-			stderr += chunk;
-			onStderr(chunk);
-		});
-		child.on("error", reject);
-		child.on("close", (code) => {
-			if (code === 0) resolve({
-				stdout: stdout.trim(),
-				stderr: stderr.trim()
-			});
-			else reject(/* @__PURE__ */ new Error(`Command exited with code ${code}`));
-		});
-		return await promise;
-	};
-	return (await Result.fromCallable(fn, Error)).context(`Failed to execute command: ${cmd}`);
-}
-const quoteShellArg = (arg) => {
-	if (!arg) return "''";
-	const cleaned = String(arg).replace(REGEXP_NULL_CHAR, "");
-	if (REGEXP_SAFE_CHARS.exec(cleaned)?.[0].length === cleaned.length) return cleaned;
-	return `'${cleaned.replace(REGEXP_SINGLE_QUOTES, (matched) => matched.length === 1 ? `'\\''` : `'"${matched}"'`)}'`.replace(/^''/, "").replace(/''$/, "");
-};
-
 //#endregion
 //#region src/common/throttle.ts
 const wrap = (fn, wait, options) => {
@@ -1168,4 +1100,4 @@ const throttle = (fn, wait = 0, options = {}) => {
 };
 
 //#endregion
-export { stringify as A, parseKeyValuePairs as C, getErrorMessage as D, scale as E, safeTry as F, ResultError as I, __commonJSMin as L, Result as M, err as N, normalizeError as O, ok as P, __toESM as R, sleep as S, linear as T, toForwardSlash as _, addPrefix as a, createPromiseWithResolvers as b, indent as c, removePrefix as d, removeSuffix as f, template as g, splitWithSlash as h, quoteShellArg as i, unsafeParse as j, safeParse as k, join as l, splitByLineBreak as m, throttle as n, addSuffix as o, split as p, $ as r, concatTemplateStrings as s, debounce as t, joinWithSlash as u, unindent as v, parseValueToBoolean as w, createSingleton as x, createLock as y };
+export { Result as A, linear as C, safeParse as D, normalizeError as E, __commonJSMin as F, __toESM as I, ok as M, safeTry as N, stringify as O, ResultError as P, parseValueToBoolean as S, getErrorMessage as T, createLock as _, concatTemplateStrings as a, sleep as b, joinWithSlash as c, split as d, splitByLineBreak as f, unindent as g, toForwardSlash as h, addSuffix as i, err as j, unsafeParse as k, removePrefix as l, template as m, throttle as n, indent as o, splitWithSlash as p, addPrefix as r, join as s, debounce as t, removeSuffix as u, createPromiseWithResolvers as v, scale as w, parseKeyValuePairs as x, createSingleton as y };

package/dist/common.d.ts

@@ -1,5 +1,5 @@
 import { i as Result } from "./chunks/chunk-4b76d1c4.js";
-import { ai as Fn, on as Promisable, ri as AsyncFn } from "./chunks/chunk-a07ed28f.js";
+import { ai as Fn, ri as AsyncFn } from "./chunks/chunk-a07ed28f.js";
 
 //#region src/common/error.d.ts
 declare const normalizeError: (error: unknown, caller?: Function) => Error;
@@ -82,20 +82,6 @@ declare const createSingleton: <T>(fn: AsyncFn<T>) => Singleton<T>;
 declare const createLock: () => Lock;
 declare const createPromiseWithResolvers: <T>() => PromiseWithResolvers<T>;
 //#endregion
-//#region src/common/shell.d.ts
-interface ShellExecOptions {
-  onStdin?: string | Buffer | ((stdin: NodeJS.WritableStream) => Promisable<any>);
-  onStdout?: "ignore" | "print" | ((chunk: string) => Promisable<any>);
-  onStderr?: "ignore" | "print" | ((chunk: string) => Promisable<any>);
-}
-interface ShellExecResult {
-  stdout: string;
-  stderr: string;
-}
-declare function $(cmd: string, options?: ShellExecOptions): Promise<Result<ShellExecResult, Error>>;
-declare function $(cmd: TemplateStringsArray, ...values: any[]): Promise<Result<ShellExecResult, Error>>;
-declare const quoteShellArg: (arg: string) => string;
-//#endregion
 //#region src/common/string.d.ts
 declare const addPrefix: (prefix: string, str: string) => string;
 declare const addSuffix: (suffix: string, str: string) => string;
@@ -206,4 +192,4 @@ type ThrottleOptions = Options;
 declare const debounce: <T extends Fn>(fn: T, wait?: number, options?: DebounceOptions) => DebouncedFn<T>;
 declare const throttle: <T extends Fn>(fn: T, wait?: number, options?: ThrottleOptions) => ThrottledFn<T>;
 //#endregion
-export { $, type DebounceOptions, type DebouncedFn, type Lock, type PromiseWithResolvers, type ShellExecOptions, type ShellExecResult, type Singleton, type Stringify, type ThrottleOptions, type ThrottledFn, addPrefix, addSuffix, concatTemplateStrings, createLock, createPromiseWithResolvers, createSingleton, debounce, getErrorMessage, indent, join, joinWithSlash, linear, normalizeError, unsafeParse as parse, parseKeyValuePairs, parseValueToBoolean, quoteShellArg, removePrefix, removeSuffix, safeParse, scale, sleep, split, splitByLineBreak, splitWithSlash, stringify, template, throttle, toForwardSlash, unindent };
+export { type DebounceOptions, type DebouncedFn, type Lock, type PromiseWithResolvers, type Singleton, type Stringify, type ThrottleOptions, type ThrottledFn, addPrefix, addSuffix, concatTemplateStrings, createLock, createPromiseWithResolvers, createSingleton, debounce, getErrorMessage, indent, join, joinWithSlash, linear, normalizeError, unsafeParse as parse, parseKeyValuePairs, parseValueToBoolean, removePrefix, removeSuffix, safeParse, scale, sleep, split, splitByLineBreak, splitWithSlash, stringify, template, throttle, toForwardSlash, unindent };

package/dist/common.js

@@ -1,3 +1,3 @@
-import { A as stringify, C as parseKeyValuePairs, D as getErrorMessage, E as scale, O as normalizeError, S as sleep, T as linear, _ as toForwardSlash, a as addPrefix, b as createPromiseWithResolvers, c as indent, d as removePrefix, f as removeSuffix, g as template, h as splitWithSlash, i as quoteShellArg, j as unsafeParse, k as safeParse, l as join, m as splitByLineBreak, n as throttle, o as addSuffix, p as split, r as $, s as concatTemplateStrings, t as debounce, u as joinWithSlash, v as unindent, w as parseValueToBoolean, x as createSingleton, y as createLock } from "./chunks/chunk-f4c5d38b.js";
+import { C as linear, D as safeParse, E as normalizeError, O as stringify, S as parseValueToBoolean, T as getErrorMessage, _ as createLock, a as concatTemplateStrings, b as sleep, c as joinWithSlash, d as split, f as splitByLineBreak, g as unindent, h as toForwardSlash, i as addSuffix, k as unsafeParse, l as removePrefix, m as template, n as throttle, o as indent, p as splitWithSlash, r as addPrefix, s as join, t as debounce, u as removeSuffix, v as createPromiseWithResolvers, w as scale, x as parseKeyValuePairs, y as createSingleton } from "./chunks/chunk-fda806f4.js";
 
-export { $, addPrefix, addSuffix, concatTemplateStrings, createLock, createPromiseWithResolvers, createSingleton, debounce, getErrorMessage, indent, join, joinWithSlash, linear, normalizeError, unsafeParse as parse, parseKeyValuePairs, parseValueToBoolean, quoteShellArg, removePrefix, removeSuffix, safeParse, scale, sleep, split, splitByLineBreak, splitWithSlash, stringify, template, throttle, toForwardSlash, unindent };
+export { addPrefix, addSuffix, concatTemplateStrings, createLock, createPromiseWithResolvers, createSingleton, debounce, getErrorMessage, indent, join, joinWithSlash, linear, normalizeError, unsafeParse as parse, parseKeyValuePairs, parseValueToBoolean, removePrefix, removeSuffix, safeParse, scale, sleep, split, splitByLineBreak, splitWithSlash, stringify, template, throttle, toForwardSlash, unindent };

package/dist/fs.js

@@ -1,4 +1,4 @@
-import { A as stringify, F as safeTry, L as __commonJSMin, M as Result, N as err, P as ok, R as __toESM, d as removePrefix, k as safeParse } from "./chunks/chunk-f4c5d38b.js";
+import { A as Result, D as safeParse, F as __commonJSMin, I as __toESM, M as ok, N as safeTry, O as stringify, j as err, l as removePrefix } from "./chunks/chunk-fda806f4.js";
 import { Fn as e$1, Jt as n, Sn as e$2, gn as e } from "./chunks/chunk-267b337b.js";
 import * as nativeFs$1 from "fs";
 import nativeFs from "fs";

package/dist/result.js

@@ -1,3 +1,3 @@
-import { F as safeTry, I as ResultError, M as Result, N as err, P as ok } from "./chunks/chunk-f4c5d38b.js";
+import { A as Result, M as ok, N as safeTry, P as ResultError, j as err } from "./chunks/chunk-fda806f4.js";
 
 export { Result, ResultError, err, ok, safeTry };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@goodbyenjn/utils",
-    "version": "26.1.2",
+    "version": "26.1.3",
     "description": "GoodbyeNJN's utils for typescript and javascript",
     "keywords": [
         "utils",
@@ -60,6 +60,7 @@
         "@goodbyenjn/configs": "^6.1.4",
         "@goodbyenjn/utils": "file:",
         "@types/node": "^25.0.3",
+        "args-tokenizer": "^0.3.0",
         "eslint": "^9.39.2",
         "prettier": "^3.7.4",
         "remeda": "^2.33.1",
@@ -67,6 +68,7 @@
         "rolldown-plugin-dts": "^0.20.0",
         "rotery": "^0.7.0",
         "safe-stable-stringify": "^2.5.0",
+        "tinyexec": "^1.0.2",
         "tinyglobby": "^0.2.15",
         "type-fest": "^5.3.1",
         "typescript": "^5.9.3",