@goodbyenjn/utils 26.1.1 → 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";
 ```
@@ -110,6 +112,10 @@ const cleaned = removeSuffix(".js", "script.js"); // "script"
 // String joining and splitting
 const path = join("/", "home", "user", "docs"); // "/home/user/docs"
 const parts = split("-", "hello-world-js"); // ["hello", "world", "js"]
+
+// Split string by line breaks (handles both \n and \r\n)
+const lines = splitByLineBreak("line1\nline2\r\nline3");
+console.log(lines); // ["line1", "line2", "line3"]
 ```
 
 #### Promise Utilities
@@ -147,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);
 
-// 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);
+// String command with args
+const output = await $("ls", ["-la"]);
+console.log(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
@@ -499,6 +507,7 @@ Common utilities for everyday programming tasks:
 export {
     template,
     unindent,
+    indent,
     addPrefix,
     addSuffix,
     removePrefix,
@@ -508,6 +517,7 @@ export {
     splitWithSlash,
     joinWithSlash,
     toForwardSlash,
+    splitByLineBreak,
     concatTemplateStrings,
 };
 

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

@@ -984,8 +984,8 @@ const unindent = (...params) => {
 			const line = lines[i];
 			if (REGEXP_WHITESPACE_ONLY.test(line)) continue;
 			if (firstContentLine === -1) firstContentLine = i;
-			const indent = line.match(REGEXP_WHITESPACE_PREFIX)?.[0].length ?? 0;
-			commonIndent = Math.min(commonIndent, indent);
+			const indent$1 = line.match(REGEXP_WHITESPACE_PREFIX)?.[0].length ?? 0;
+			commonIndent = Math.min(commonIndent, indent$1);
 		}
 		if (firstContentLine === -1) commonIndent = 0;
 		if (!Number.isFinite(commonIndent)) commonIndent = 0;
@@ -1001,7 +1001,57 @@ 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
+* ```ts
+* // Using indent count with default space character
+* const str1 = indent(2)`
+*   if (a) {
+*     b()
+*   }
+* `;
+*
+* // Using custom indent string directly
+* const str2 = indent(">>")`
+*   if (a) {
+*     b()
+*   }
+* `;
+*
+* // Only trim start, keep end
+* const str3 = indent(2, true, false)("hello\nworld\n");
+* ```
+*/
+const indent = (...params) => {
+	let indentString;
+	let trimStart = true;
+	let trimEnd = true;
+	const indentImpl = (...params$1) => {
+		const lines = splitByLineBreak(e$1(params$1[0]) ? params$1[0] : concatTemplateStrings(params$1[0], params$1.slice(1)));
+		const whitespaceLines = lines.map((line) => REGEXP_WHITESPACE_ONLY.test(line));
+		let startIndex = 0;
+		let endIndex = lines.length;
+		if (trimStart) while (startIndex < lines.length && whitespaceLines[startIndex]) startIndex++;
+		if (trimEnd) while (endIndex > startIndex && whitespaceLines[endIndex - 1]) endIndex--;
+		return lines.slice(startIndex, endIndex).map((line, index) => {
+			return whitespaceLines[index + startIndex] ? line : indentString + line;
+		}).join("\n");
+	};
+	if ((e$4(params[1]) || params[1] === void 0) && (e$4(params[2]) || params[2] === void 0)) {
+		trimStart = params[1] !== false;
+		trimEnd = params[2] !== false;
+	}
+	if (e$2(params[0])) {
+		indentString = " ".repeat(params[0]);
+		return indentImpl;
+	}
+	if (e$1(params[0])) {
+		indentString = params[0];
+		return indentImpl;
+	}
+	throw new TypeError(`First parameter has an invalid type: "${typeof params[0]}"`);
 };
 function template(str, ...args) {
 	const [firstArg, fallback] = args;
@@ -1015,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) => {
@@ -1118,4 +1100,4 @@ const throttle = (fn, wait = 0, options = {}) => {
 };
 
 //#endregion
-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 _, addPrefix as a, sleep as b, join as c, removeSuffix as d, split as f, unindent as g, toForwardSlash as h, quoteShellArg as i, err as j, unsafeParse as k, joinWithSlash as l, template as m, throttle as n, addSuffix as o, splitWithSlash as p, $ as r, concatTemplateStrings as s, debounce as t, removePrefix as u, createPromiseWithResolvers as v, scale as w, parseKeyValuePairs as x, createSingleton 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;
@@ -106,6 +92,7 @@ declare const split: (separator: string, path: string) => string[];
 declare const toForwardSlash: (str: string) => string;
 declare const joinWithSlash: (...paths: string[]) => string;
 declare const splitWithSlash: (path: string) => string[];
+declare const splitByLineBreak: (str: string) => string[];
 declare const concatTemplateStrings: (template: TemplateStringsArray, values: any[]) => string;
 interface StringOrTemplateFunction {
   (str: string): string;
@@ -136,6 +123,32 @@ interface UnindentFunction extends StringOrTemplateFunction {
  * ```
  */
 declare const unindent: UnindentFunction;
+interface IndentFunction {
+  (indentNumber: number, trimStart?: boolean, trimEnd?: boolean): StringOrTemplateFunction;
+  (indentString: string, trimStart?: boolean, trimEnd?: boolean): StringOrTemplateFunction;
+}
+/**
+ * @example
+ * ```ts
+ * // Using indent count with default space character
+ * const str1 = indent(2)`
+ *   if (a) {
+ *     b()
+ *   }
+ * `;
+ *
+ * // Using custom indent string directly
+ * const str2 = indent(">>")`
+ *   if (a) {
+ *     b()
+ *   }
+ * `;
+ *
+ * // Only trim start, keep end
+ * const str3 = indent(2, true, false)("hello\nworld\n");
+ * ```
+ */
+declare const indent: IndentFunction;
 /**
  * @example
  * ```
@@ -179,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, join, joinWithSlash, linear, normalizeError, unsafeParse as parse, parseKeyValuePairs, parseValueToBoolean, quoteShellArg, removePrefix, removeSuffix, safeParse, scale, sleep, split, 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 { C as linear, D as safeParse, E as normalizeError, O as stringify, S as parseValueToBoolean, T as getErrorMessage, _ as createLock, a as addPrefix, b as sleep, c as join, d as removeSuffix, f as split, g as unindent, h as toForwardSlash, i as quoteShellArg, k as unsafeParse, l as joinWithSlash, m as template, n as throttle, o as addSuffix, p as splitWithSlash, r as $, s as concatTemplateStrings, t as debounce, u as removePrefix, v as createPromiseWithResolvers, w as scale, x as parseKeyValuePairs, y as createSingleton } from "./chunks/chunk-7a37e668.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, join, joinWithSlash, linear, normalizeError, unsafeParse as parse, parseKeyValuePairs, parseValueToBoolean, quoteShellArg, removePrefix, removeSuffix, safeParse, scale, sleep, split, 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 Result, D as safeParse, F as __commonJSMin, I as __toESM, M as ok, N as safeTry, O as stringify, j as err, u as removePrefix } from "./chunks/chunk-7a37e668.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 { A as Result, M as ok, N as safeTry, P as ResultError, j as err } from "./chunks/chunk-7a37e668.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.1",
+    "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",