@goodbyenjn/utils 26.4.0 → 26.4.2

package/README.md

@@ -11,9 +11,9 @@ A modern TypeScript/JavaScript utility library providing a comprehensive collect
 - 🔒 **Type-safe**: Full TypeScript support with comprehensive type definitions and type inference
 - 📦 **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
-- 🐚 **Shell Execution**: Powerful and flexible shell command execution with piping support
-- 🧰 **Common Utilities**: String manipulation, math operations, promise utilities, and error handling
+- 📁 **VFile & FS**: Type-safe file system operations and a powerful virtual file object
+- 🐚 **Exec**: Powerful and flexible command execution with safe and unsafe variants
+- 🧰 **Common Utilities**: String manipulation, math operations, promise utilities, and JSON handling
 - 📊 **Remeda Extensions**: Extended utilities built on top of [Remeda](https://remedajs.com/)
 
 ## Installation
@@ -33,9 +33,10 @@ yarn add @goodbyenjn/utils
 ```typescript
 // Import what you need from the main module
 import { sleep, template } from "@goodbyenjn/utils";
-import { $ } from "@goodbyenjn/utils/shell";
-import { safeReadFile } from "@goodbyenjn/utils/fs";
+import { exec, safeExec } from "@goodbyenjn/utils/exec";
+import { BaseVFile } from "@goodbyenjn/utils/fs";
 import { ok, Result } from "@goodbyenjn/utils/result";
+import { parse, safeParse } from "@goodbyenjn/utils/json";
 ```
 
 ### Common Utilities
@@ -154,34 +155,39 @@ setTimeout(() => resolve("done!"), 1000);
 const result = await promise;
 ```
 
-#### Shell Command Execution
+### Command Execution
 
 ```typescript
-import { $ } from "@goodbyenjn/utils/shell";
+import { exec, safeExec } from "@goodbyenjn/utils/exec";
 
-// Execute shell commands with template literals
-const result = await $`npm install`;
-console.log(result.stdout);
-console.log(result.stderr);
+// 1. Unsafe Execution (throws on failure)
+const output = await exec`npm install`;
+console.log(output.stdout);
 
 // String command with args
-const output = await $("ls", ["-la"]);
-console.log(output.stdout);
+const lsOutput = await exec("ls", ["-la"]);
+console.log(lsOutput.stdout);
 
-// Pipe commands
-const piped = await $`echo "hello"`.pipe`cat`;
+// 2. Safe Execution (returns Result)
+const safeOutput = await safeExec`npm install`;
+if (safeOutput.isOk()) {
+    console.log("Success:", safeOutput.unwrap().stdout);
+} else {
+    // Result contains error information (e.g., NonZeroExitError)
+    console.error("Failed:", safeOutput.unwrapErr().message);
+}
+
+// 3. Pipe Output
+const piped = await exec`echo "hello"`.pipe`cat`;
 console.log(piped.stdout);
 
-// Iterate output line by line
-for await (const line of $`cat large-file.txt`) {
+// 4. Iterate Output
+for await (const line of exec`cat large-file.txt`) {
     console.log(line);
 }
 
-// Using options
-const result2 = await $("npm", ["install"], { cwd: "/path/to/project" });
-
-// Factory function with options
-const withCwd = $({ cwd: "/path/to/project" });
+// 5. Configuration Factory
+const withCwd = exec({ cwd: "/path/to/project" });
 const result3 = await withCwd`npm install`;
 ```
 
@@ -236,6 +242,25 @@ const throttledScroll = throttle(() => {
 window.addEventListener("scroll", throttledScroll);
 ```
 
+#### JSON Handling
+
+```typescript
+import { parse, stringify, safeParse, safeStringify } from "@goodbyenjn/utils/json";
+
+// Standard JSON parsing (returns value or nil)
+const data = parse('{"a": 1}'); // { a: 1 }
+const invalid = parse("bad"); // nil
+
+// Safe JSON parsing (returns Result)
+const result = safeParse('{"a": 1}');
+if (result.isOk()) {
+    console.log(result.unwrap().a);
+}
+
+// Safe stringify
+const json = safeStringify({ a: 1 }); // Result<string, Error>
+```
+
 ### File System Operations
 
 ```typescript
@@ -248,33 +273,50 @@ import {
     safeMkdir,
     safeRm,
     safeReadFileByLine,
+    BaseVFile,
 } from "@goodbyenjn/utils/fs";
 
-// Read text file safely
-const textResult = await safeReadFile("config.txt", "utf8");
+// ... (safe operations)
+
+// BaseVFile - Unified file handling
+const vfile = new BaseVFile("example.json");
+
+// Fluid path manipulation
+vfile.filename("data").extname("ts");
+console.log(vfile.basename()); // "data.ts"
+
+// Cross-platform path handling
+const relative = vfile.pathname.relative(); // "data.ts" (relative to cwd)
+const absolute = vfile.pathname(); // "/full/path/to/data.ts"
+
+// Built-in operations (available in extended VFile implementations)
+// await vfile.read(); // Get content
+// await vfile.write(); // Write content
+```
+
 if (textResult.isOk()) {
-    console.log("File content:", textResult.unwrap());
+console.log("File content:", textResult.unwrap());
 } else {
-    console.error("Failed to read file:", textResult.unwrapErr().message);
+console.error("Failed to read file:", textResult.unwrapErr().message);
 }
 
 // Read and parse JSON safely
 const jsonResult = await safeReadJson("package.json");
 if (jsonResult.isOk()) {
-    const pkg = jsonResult.unwrap();
-    console.log("Package name:", pkg.name);
+const pkg = jsonResult.unwrap();
+console.log("Package name:", pkg.name);
 }
 
 // Write JSON file
 const writeResult = await safeWriteJson("data.json", { users: [] }, { pretty: true });
 if (writeResult.isErr()) {
-    console.error("Write failed:", writeResult.unwrapErr());
+console.error("Write failed:", writeResult.unwrapErr());
 }
 
 // Check if file exists
 const existsResult = await safeExists("path/to/file.txt");
 if (existsResult.isOk() && existsResult.unwrap()) {
-    console.log("File exists!");
+console.log("File exists!");
 }
 
 // Create directories (recursive)
@@ -286,11 +328,12 @@ const rmResult = await safeRm("build", { recursive: true, force: true });
 // Read file line by line
 const lineResult = await safeReadFileByLine("large-file.log");
 if (lineResult.isOk()) {
-    for await (const line of lineResult.unwrap()) {
-        console.log(line);
-    }
+for await (const line of lineResult.unwrap()) {
+console.log(line);
 }
-```
+}
+
+````
 
 ### Glob Patterns
 
@@ -306,7 +349,7 @@ const syncFiles = globSync("**/*.test.ts", { cwd: "tests" });
 
 // Convert file path to glob pattern
 const pattern = convertPathToPattern("/home/user/project");
-```
+````
 
 ### Result Pattern - Functional Error Handling
 

package/dist/chunks/{chunk-486f65b0.js → chunk-11b9216b.js}

@@ -1,8 +1,7 @@
-import { i as __toESM, t as __commonJSMin } from "./chunk-7ffde8d4.js";
-import { Dt as isBoolean, Et as isBigInt, Gr as isFunction, Gt as isString, It as isNonNullish, Kt as isSymbol, Nt as isError, Tt as isArray, Vt as isPlainObject, Wr as isPromiseLike, p as clamp, zt as isNumber } from "./chunk-b61db0a7.js";
-
-//#region node_modules/.pnpm/safe-stable-stringify@2.5.0/node_modules/safe-stable-stringify/index.js
-var require_safe_stable_stringify = __commonJSMin(((exports, module) => {
+import { a as __toESM, t as __commonJSMin } from "./chunk-3ce2ea14.js";
+import { add, addProp, allPass, anyPass, capitalize, ceil, chunk, clamp, clone, concat, conditional, constant, countBy, debounce as debounce$1, defaultTo, difference, differenceWith, divide, doNothing, drop, dropFirstBy, dropLast, dropLastWhile, dropWhile, endsWith, entries, evolve, filter, find, findIndex, findLast, findLastIndex, first, firstBy, flat, flatMap, floor, forEach, forEachObj, fromEntries, fromKeys, funnel, groupBy, groupByProp, hasAtLeast, hasSubObject, identity, indexBy, intersection, intersectionWith, invert, isArray, isBigInt, isBoolean, isDate, isDeepEqual, isDefined, isEmpty, isEmptyish, isError, isFunction, isIncludedIn, isNonNull, isNonNullish, isNot, isNullish, isNumber, isObjectType, isObjectType as isObjectType$1, isPlainObject, isPromise, isShallowEqual, isStrictEqual, isString as isString$1, isSymbol, isTruthy, join as join$1, keys, last, length, map, mapKeys, mapToObj, mapValues, mapWithFeedback, mean, meanBy, median, merge, mergeAll, mergeDeep, multiply, nthBy, objOf, omit, omitBy, once, only, partialBind, partialLastBind, partition, pathOr, pick, pickBy, pipe, piped, product, prop, pullObject, purry, purry as purry$1, randomBigInt, randomInteger, randomString, range, rankBy, reduce, reverse, round, sample, set, setPath, shuffle, sliceString, sort, sortBy, sortedIndex, sortedIndexBy, sortedIndexWith, sortedLastIndex, sortedLastIndexBy, splice, split as split$1, splitAt, splitWhen, startsWith, stringToPath, subtract, sum, sumBy, swapIndices, swapProps, take, takeFirstBy, takeLast, takeLastWhile, takeWhile, tap, times, toCamelCase, toKebabCase, toLowerCase, toSnakeCase, toTitleCase, toUpperCase, truncate, uncapitalize, unique, uniqueBy, uniqueWith, values, when, zip, zipWith } from "remeda";
+import { accumulateAsync as accumulateP, accumulateSync as accumulate, awaitAll, buffer, chunkAsync as chunkP, compose, concatAsync as concatP, concurrency, differenceAsync as differenceP, differenceByAsync as differenceByP, differenceBySync as differenceBy, differenceWithAsync as differenceWithP, dropAsync as dropP, everyAsync as everyP, everySync as every, executeAsync as executeP, executeSync as execute, filterAsync as filterP, findAsync as findP, flatMapAsync as flatMapP, flattenAsync as flattenP, flattenSync as flatten, forEachAsync as forEachP, intersectionAsync as intersectionP, intersectionByAsync as intersectionByP, intersectionBySync as intersectionBy, intersectionWithAsync as intersectionWithP, mapAsync as mapP, peekAsync as peekP, peekSync as peek, reduceAsync as reduceP, serializeAsync as serializeP, serializeSync as serialize, someAsync as someP, someSync as some, takeAsync as takeP, throttle as throttle$1, toArrayAsync as toArrayP, toArraySync as toArray, toIteratorAsync as toIteratorP, toIteratorSync as toIterator, uniqueAsync as uniqueP, uniqueByAsync as uniqueByP, uniqueWithAsync as uniqueWithP } from "rotery";
+const configure = __toESM(__commonJSMin(((exports, module) => {
 	const { hasOwnProperty } = Object.prototype;
 	const stringify = configure();
 	stringify.configure = configure;
@@ -410,13 +409,10 @@ var require_safe_stable_stringify = __commonJSMin(((exports, module) => {
 		}
 		return stringify;
 	}
-}));
-
+}))(), 1).configure;
 //#endregion
-//#region node_modules/.pnpm/safe-stable-stringify@2.5.0/node_modules/safe-stable-stringify/esm/wrapper.js
-var import_safe_stable_stringify = __toESM(require_safe_stable_stringify(), 1);
-const configure = import_safe_stable_stringify.configure;
-
+//#region src/json/stable.ts
+const stableStringify = configure({ bigint: true });
 //#endregion
 //#region src/result/error.ts
 const prepare = (result, msg) => {
@@ -475,7 +471,6 @@ Stack trace:`, prepared.options);
 		return this.#formatted;
 	}
 };
-
 //#endregion
 //#region src/result/result.ts
 const never = void 0;
@@ -495,7 +490,7 @@ var Result = class Result {
 		return new Result(false, error, never);
 	}
 	static try(fnOrPromise, onThrow) {
-		if (!isFunction(fnOrPromise) && !isPromiseLike(fnOrPromise)) {
+		if (!isFunction$1(fnOrPromise) && !isPromiseLike(fnOrPromise)) {
 			const error = new TypeError("Argument must be a function or a promise");
 			return this.err(transformError(error, onThrow));
 		}
@@ -629,19 +624,27 @@ var Result = class Result {
 };
 const ok = Result.ok;
 const err = Result.err;
-
+const isResult = Result.is;
 //#endregion
-//#region src/common/json.ts
-const stringify = configure({ bigint: true });
-const safeParse = (text, reviver) => {
-	return Result.wrap(JSON.parse, Error)(text, reviver).context(`Failed to parse JSON string: ${text.length > 100 ? text.slice(0, 100) + "..." : text}`);
-};
-const unsafeParse = (text, reviver) => {
-	const result = safeParse(text, reviver);
-	if (result.isErr()) return void 0;
-	return result.unwrap(null);
-};
-
+//#region src/remeda/hasOwnProperty.ts
+function hasOwnProperty(...args) {
+	return purry(hasOwnPropertyImplementation, args);
+}
+function hasOwnPropertyImplementation(data, properties) {
+	if (!isObjectType(data)) return false;
+	for (const property of properties) if (!Object.hasOwn(data, property)) return false;
+	return true;
+}
+//#endregion
+//#region src/remeda/isFunction.ts
+function isFunction$1(data) {
+	return typeof data === "function";
+}
+//#endregion
+//#region src/remeda/isPromiseLike.ts
+function isPromiseLike(data) {
+	return isObjectType(data) && isFunction(data.then) && Object.getOwnPropertyDescriptor(data, "then")?.get === void 0;
+}
 //#endregion
 //#region src/common/error.ts
 const normalizeError = (error, caller) => {
@@ -654,13 +657,12 @@ const getErrorMessage = (error, message) => {
 	if (isError(error)) return error.message;
 	if (message !== void 0) return message;
 	let msg;
-	if (isString(error) || isNumber(error) || isBigInt(error) || isBoolean(error) || isSymbol(error)) msg = error.toString();
+	if (isString$1(error) || isNumber(error) || isBigInt(error) || isBoolean(error) || isSymbol(error)) msg = error.toString();
 	else if (error === void 0) msg = "undefined";
 	else if (error === null) msg = "null";
-	else msg = stringify(error);
+	else msg = stableStringify(error);
 	return msg;
 };
-
 //#endregion
 //#region src/common/math.ts
 const linear = (value, range) => {
@@ -676,7 +678,10 @@ const scale = (value, inRange, outRange) => {
 	const [outMin, outMax] = outRange;
 	return linear((value - inMin) / (inMax - inMin), [outMin, outMax]);
 };
-
+//#endregion
+//#region src/common/nil.ts
+const nil = Symbol("nil");
+const isNil = (value) => value === nil;
 //#endregion
 //#region src/common/parse.ts
 const parseKey = (input, raw = input) => {
@@ -757,7 +762,6 @@ const parseValueToBoolean = (value, defaultValue) => {
 	if (/^(?:n|no|false|0|off)$/.test(str)) return false;
 	return defaultValue;
 };
-
 //#endregion
 //#region src/common/promise.ts
 const sleep = (ms, callback) => new Promise((resolve) => {
@@ -804,7 +808,7 @@ const createLock = () => {
 	};
 };
 const createPromiseWithResolvers = () => {
-	if (isFunction(Promise.withResolvers)) return Promise.withResolvers();
+	if (isFunction$1(Promise.withResolvers)) return Promise.withResolvers();
 	let resolve;
 	let reject;
 	return {
@@ -816,7 +820,6 @@ const createPromiseWithResolvers = () => {
 		reject
 	};
 };
-
 //#endregion
 //#region src/common/string.ts
 const REGEXP_WHITESPACE_ONLY = /^\s*$/;
@@ -864,7 +867,7 @@ function unindent(...params) {
 	let trimStart = true;
 	let trimEnd = true;
 	const unindentImpl = (...params) => {
-		const lines = splitByLineBreak(isString(params[0]) ? params[0] : concatTemplateStrings(params[0], params.slice(1)));
+		const lines = splitByLineBreak(isString$1(params[0]) ? params[0] : concatTemplateStrings(params[0], params.slice(1)));
 		let commonIndent = Number.POSITIVE_INFINITY;
 		let firstContentLine = -1;
 		for (let i = 0; i < lines.length; i++) {
@@ -887,7 +890,7 @@ function unindent(...params) {
 		trimEnd = params[1] !== false;
 		return unindentImpl;
 	}
-	if (isString(params[0]) || isArray(params[0])) return unindentImpl(...params);
+	if (isString$1(params[0]) || isArray(params[0])) return unindentImpl(...params);
 	throw new TypeError(`First parameter has an invalid type: "${typeof params[0]}"`);
 }
 function indent(...params) {
@@ -895,7 +898,7 @@ function indent(...params) {
 	let trimStart = true;
 	let trimEnd = true;
 	const indentImpl = (...params) => {
-		const lines = splitByLineBreak(isString(params[0]) ? params[0] : concatTemplateStrings(params[0], params.slice(1)));
+		const lines = splitByLineBreak(isString$1(params[0]) ? params[0] : concatTemplateStrings(params[0], params.slice(1)));
 		const whitespaceLines = lines.map((line) => REGEXP_WHITESPACE_ONLY.test(line));
 		let startIndex = 0;
 		let endIndex = lines.length;
@@ -913,7 +916,7 @@ function indent(...params) {
 		indentString = " ".repeat(params[0]);
 		return indentImpl;
 	}
-	if (isString(params[0])) {
+	if (isString$1(params[0])) {
 		indentString = params[0];
 		return indentImpl;
 	}
@@ -923,14 +926,13 @@ function template(str, ...args) {
 	const [firstArg, fallback] = args;
 	if (isPlainObject(firstArg)) {
 		const mapping = firstArg;
-		return str.replace(/\{(\w+)\}/g, (_, key) => mapping[key] || ((isFunction(fallback) ? fallback(key) : fallback) ?? key));
+		return str.replace(/\{(\w+)\}/g, (_, key) => mapping[key] || ((isFunction$1(fallback) ? fallback(key) : fallback) ?? key));
 	} else return str.replace(/\{(\d+)\}/g, (_, key) => {
 		const index = Number(key);
 		if (Number.isNaN(index)) return key;
 		return args[index];
 	});
 }
-
 //#endregion
 //#region src/common/throttle.ts
 const wrap = (fn, wait, options) => {
@@ -964,6 +966,5 @@ const throttle = (fn, wait = 0, options = {}) => {
 		trailing
 	});
 };
-
 //#endregion
-export { Result as A, linear as C, safeParse as D, normalizeError as E, ok as M, ResultError as N, stringify as O, 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 };
+export { differenceBy as $, pipe as $n, toIterator as $r, isArray as $t, accumulateP as A, mapValues as An, splice as Ar, flatMapP as At, chunkP as B, objOf as Bn, swapProps as Br, groupBy as Bt, isNil as C, isResult as Ci, keys as Cn, sort as Cr, findLast as Ct, getErrorMessage as D, mapKeys as Dn, sortedIndexWith as Dr, firstBy as Dt, scale as E, stableStringify as Ei, map as En, sortedIndexBy as Er, first as Et, awaitAll as F, merge as Fn, stringToPath as Fr, forEachObj as Ft, concatP as G, partialBind as Gn, takeP as Gr, indexBy as Gt, clone as H, omitBy as Hn, takeFirstBy as Hr, hasAtLeast as Ht, buffer as I, mergeAll as In, subtract as Ir, forEachP as It, constant as J, pathOr as Jn, throttle$1 as Jr, intersectionByP as Jt, concurrency as K, partialLastBind as Kn, takeWhile as Kr, intersection as Kt, capitalize as L, mergeDeep as Ln, sum as Lr, fromEntries as Lt, addProp as M, mean as Mn, splitAt as Mr, flattenP as Mt, allPass as N, meanBy as Nn, splitWhen as Nr, floor as Nt, normalizeError as O, mapP as On, sortedLastIndex as Or, flat as Ot, anyPass as P, median as Pn, startsWith as Pr, forEach as Pt, difference as Q, pickBy as Qn, toCamelCase as Qr, invert as Qt, ceil as R, multiply as Rn, sumBy as Rr, fromKeys as Rt, parseValueToBoolean as S, err as Si, join$1 as Sn, someP as Sr, findIndex as St, linear as T, ResultError as Ti, length as Tn, sortedIndex as Tr, findP as Tt, compose as U, once as Un, takeLast as Ur, hasSubObject as Ut, clamp as V, omit as Vn, take as Vr, groupByProp as Vt, concat as W, only as Wn, takeLastWhile as Wr, identity as Wt, debounce$1 as X, peekP as Xn, toArray as Xr, intersectionWith as Xt, countBy as Y, peek as Yn, times as Yr, intersectionP as Yt, defaultTo as Z, pick as Zn, toArrayP as Zr, intersectionWithP as Zt, createLock as _, zipWith as _i, isShallowEqual as _n, set as _r, execute as _t, concatTemplateStrings as a, toUpperCase as ai, isEmpty as an, randomBigInt as ar, doNothing as at, sleep as b, hasOwnProperty as bi, isSymbol as bn, sliceString as br, filterP as bt, joinWithSlash as c, unique as ci, isIncludedIn as cn, range as cr, dropLast as ct, split as d, uniqueP as di, isNot as dn, reduceP as dr, dropWhile as dt, toIteratorP as ei, isBigInt as en, piped as er, differenceByP as et, splitByLineBreak as f, uniqueWith as fi, isNullish as fn, reverse as fr, endsWith as ft, unindent as g, zip as gi, isPromise as gn, serializeP as gr, evolve as gt, toForwardSlash as h, when as hi, isPlainObject as hn, serialize as hr, everyP as ht, addSuffix as i, toTitleCase as ii, isDefined as in, purry$1 as ir, divide as it, add as j, mapWithFeedback as jn, split$1 as jr, flatten as jt, accumulate as k, mapToObj as kn, sortedLastIndexBy as kr, flatMap as kt, removePrefix as l, uniqueBy as li, isNonNull as ln, rankBy as lr, dropLastWhile as lt, template as m, values as mi, isObjectType$1 as mn, sample as mr, every as mt, throttle as n, toLowerCase as ni, isDate as nn, prop as nr, differenceWith as nt, indent as o, truncate as oi, isEmptyish as on, randomInteger as or, drop as ot, splitWithSlash as p, uniqueWithP as pi, isNumber as pn, round as pr, entries as pt, conditional as q, partition as qn, tap as qr, intersectionBy as qt, addPrefix as r, toSnakeCase as ri, isDeepEqual as rn, pullObject as rr, differenceWithP as rt, join as s, uncapitalize as si, isError as sn, randomString as sr, dropFirstBy as st, debounce as t, toKebabCase as ti, isBoolean as tn, product as tr, differenceP as tt, removeSuffix as u, uniqueByP as ui, isNonNullish as un, reduce as ur, dropP as ut, createPromiseWithResolvers as v, isPromiseLike as vi, isStrictEqual as vn, setPath as vr, executeP as vt, nil as w, ok as wi, last as wn, sortBy as wr, findLastIndex as wt, parseKeyValuePairs as x, Result as xi, isTruthy as xn, some as xr, find as xt, createSingleton as y, isFunction$1 as yi, isString$1 as yn, shuffle as yr, filter as yt, chunk as z, nthBy as zn, swapIndices as zr, funnel as zt };

package/dist/chunks/chunk-1b381080.js

@@ -0,0 +1,25 @@
+import { Si as err, w as nil, xi as Result } from "./chunk-11b9216b.js";
+//#region src/json/safe.ts
+const safeStringify = Result.wrap(JSON.stringify);
+const stringify$1 = (value, replacer, space) => Result.gen(function* () {
+	const text = yield* safeStringify(value, replacer, space).context(`Failed to stringify value: ${String(value)}`);
+	if (text === void 0) return err(new TypeError(`Value cannot be stringified: ${String(value)}`));
+	return text;
+});
+const safeParse = Result.wrap(JSON.parse);
+const parse$1 = (text, reviver) => safeParse(text, reviver).context(`Failed to parse JSON string: ${text.length > 100 ? text.slice(0, 100) + "..." : text}`);
+//#endregion
+//#region src/json/unsafe.ts
+function stringify(value, replacer, space) {
+	const text = JSON.stringify(value, replacer, space);
+	return text === void 0 ? nil : text;
+}
+const parse = (text, reviver) => {
+	try {
+		return JSON.parse(text, reviver);
+	} catch {
+		return nil;
+	}
+};
+//#endregion
+export { stringify$1 as i, stringify as n, parse$1 as r, parse as t };

package/dist/chunks/{chunk-7ffde8d4.js → chunk-3ce2ea14.js}

@@ -1,3 +1,4 @@
+import { createRequire } from "node:module";
 //#region \0rolldown/runtime.js
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -8,28 +9,20 @@ var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __commonJSMin = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
 var __exportAll = (all, no_symbols) => {
 	let target = {};
-	for (var name in all) {
-		__defProp(target, name, {
-			get: all[name],
-			enumerable: true
-		});
-	}
-	if (!no_symbols) {
-		__defProp(target, Symbol.toStringTag, { value: "Module" });
-	}
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
 	return target;
 };
 var __copyProps = (to, from, except, desc) => {
-	if (from && typeof from === "object" || typeof from === "function") {
-		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
-			key = keys[i];
-			if (!__hasOwnProp.call(to, key) && key !== except) {
-				__defProp(to, key, {
-					get: ((k) => from[k]).bind(null, key),
-					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-				});
-			}
-		}
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
 	}
 	return to;
 };
@@ -38,6 +31,6 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	value: mod,
 	enumerable: true
 }) : target, mod));
-
+var __require = createRequire(import.meta.url);
 //#endregion
-export { __toESM as i, __exportAll as n, __reExport as r, __commonJSMin as t };
+export { __toESM as a, __require as i, __exportAll as n, __reExport as r, __commonJSMin as t };

package/dist/chunks/chunk-71e0c144.d.ts

@@ -0,0 +1,168 @@
+import { l as Fn, p as TemplateFn, s as AsyncFn, t as index_d_exports } from "./chunk-3c6f28c7.js";
+
+//#region src/common/error.d.ts
+declare const normalizeError: (error: unknown, caller?: Function) => Error;
+declare const getErrorMessage: (error: unknown, message?: string) => string;
+//#endregion
+//#region src/common/math.d.ts
+/**
+ * @example
+ * ```
+ * const value = linear(0.5, [0, 2]) // value: 1
+ * ```
+ */
+declare const linear: (value: number, range: [min: number, max: number]) => number;
+/**
+ * @example
+ * ```
+ * const value = scale(0.5, [0, 1], [200, 400]) // value: 300
+ * ```
+ */
+declare const scale: (value: number, inRange: [min: number, max: number], outRange: [min: number, max: number]) => number;
+//#endregion
+//#region src/common/nil.d.ts
+type Nil = index_d_exports.Tagged<symbol, "nil">;
+declare const nil: Nil;
+declare const isNil: (value: unknown) => value is Nil;
+//#endregion
+//#region src/common/parse.d.ts
+declare const parseKeyValuePairs: (input: string) => Record<string, string>;
+declare const parseValueToBoolean: <T>(value: unknown, defaultValue: T | boolean) => T | boolean;
+//#endregion
+//#region src/common/promise.d.ts
+interface Singleton<T> {
+  (): Promise<T>;
+  reset: () => Promise<void>;
+}
+interface Lock {
+  run: <T = void>(fn: AsyncFn<T>) => Promise<T>;
+  wait: () => Promise<void>;
+  isWaiting: () => boolean;
+  clear: () => void;
+}
+interface PromiseWithResolvers<T> {
+  promise: Promise<T>;
+  resolve: (value: T | PromiseLike<T>) => void;
+  reject: (reason?: any) => void;
+}
+declare const sleep: (ms: number, callback?: Fn) => Promise<void>;
+declare const createSingleton: <T>(fn: AsyncFn<T>) => Singleton<T>;
+/**
+ * @example
+ * ```
+ * const lock = createLock()
+ *
+ * lock.run(async () => {
+ *   await doSomething()
+ * })
+ *
+ * // in anther context:
+ * await lock.wait() // it will wait all tasking finished
+ * ```
+ */
+declare const createLock: () => Lock;
+declare const createPromiseWithResolvers: <T>() => PromiseWithResolvers<T>;
+//#endregion
+//#region src/common/string.d.ts
+declare const addPrefix: (prefix: string, str: string) => string;
+declare const addSuffix: (suffix: string, str: string) => string;
+declare const removePrefix: (prefix: string, str: string) => string;
+declare const removeSuffix: (suffix: string, str: string) => string;
+declare const join: (separator: string, ...paths: string[]) => string;
+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;
+/**
+ * @example
+ * ```ts
+ * // Default behavior: trim both start and end
+ * const str1 = unindent`
+ *   if (a) {
+ *     b()
+ *   }
+ * `;
+ *
+ * // Factory function: custom trim behavior
+ * const str2 = unindent(false, false)`
+ *   if (a) {
+ *     b()
+ *   }
+ * `;
+ *
+ * // Only trim start, keep end
+ * const str3 = unindent(true, false)("  hello\n  world\n");
+ * ```
+ */
+declare function unindent(str: string): string;
+declare function unindent(template: TemplateStringsArray, ...values: any[]): string;
+declare function unindent(trimStart?: boolean, trimEnd?: boolean): TemplateFn<string> & ((str: string) => string);
+/**
+ * @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 function indent(indentNumber: number, trimStart?: boolean, trimEnd?: boolean): TemplateFn<string> & ((str: string) => string);
+declare function indent(indentString: string, trimStart?: boolean, trimEnd?: boolean): TemplateFn<string> & ((str: string) => string);
+/**
+ * @example
+ * ```
+ * const result = template(
+ *   'Hello {0}! My name is {1}.',
+ *   'World',
+ *   'Alice'
+ * ) // Hello World! My name is Alice.
+ * ```
+ *
+ * ```
+ * const result = template(
+ *   '{greet}! My name is {name}.',
+ *   { greet: 'Hello', name: 'Alice' }
+ * ) // Hello! My name is Alice.
+ * ```
+ *
+ * const result = template(
+ *   '{greet}! My name is {name}.',
+ *   { greet: 'Hello' }, // name isn't passed hence fallback will be used for name
+ *   'placeholder'
+ * ) // Hello! My name is placeholder.
+ * ```
+ */
+declare function template(str: string, mapping: Record<string | number, any>, fallback?: string | ((key: string) => string)): string;
+declare function template(str: string, ...args: (string | number | bigint | undefined | null)[]): string;
+//#endregion
+//#region src/common/throttle.d.ts
+interface WrappedFn<T extends Fn> {
+  (...args: Parameters<T>): void;
+  cancel: Fn<void>;
+}
+interface Options {
+  leading?: boolean;
+  trailing?: boolean;
+}
+type DebouncedFn<T extends Fn> = WrappedFn<T>;
+type ThrottledFn<T extends Fn> = WrappedFn<T>;
+type DebounceOptions = Options;
+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 { Nil as A, Singleton as C, sleep as D, createSingleton as E, getErrorMessage as F, normalizeError as I, nil as M, linear as N, parseKeyValuePairs as O, scale as P, PromiseWithResolvers as S, createPromiseWithResolvers as T, splitWithSlash as _, debounce as a, unindent as b, addSuffix as c, join as d, joinWithSlash as f, splitByLineBreak as g, split as h, ThrottledFn as i, isNil as j, parseValueToBoolean as k, concatTemplateStrings as l, removeSuffix as m, DebouncedFn as n, throttle as o, removePrefix as p, ThrottleOptions as r, addPrefix as s, DebounceOptions as t, indent as u, template as v, createLock as w, Lock as x, toForwardSlash as y };

package/dist/chunks/chunk-9fe6b612.d.ts

@@ -0,0 +1,10 @@
+import { i as Result } from "./chunk-bd9f56dd.js";
+
+//#region src/json/safe.d.ts
+declare const stringify: {
+  (value: any, replacer?: (this: any, key: string, value: any) => any, space?: string | number): Result<string, TypeError>;
+  (value: any, replacer?: (number | string)[] | null, space?: string | number): Result<string, TypeError>;
+};
+declare const parse: <T = any>(text: string, reviver?: (this: any, key: string, value: any) => any) => Result<T, SyntaxError>;
+//#endregion
+export { stringify as n, parse as t };