@goodbyenjn/utils 26.3.0 → 26.4.1

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
@@ -116,6 +117,10 @@ 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"]
+
+// Parse boolean value with custom default
+const isEnabled = parseValueToBoolean("yes", false); // true
+const debugMode = parseValueToBoolean("invalid", "auto"); // "auto"
 ```
 
 #### Promise Utilities
@@ -150,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);
+
+// 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);
+}
 
-// Pipe commands
-const piped = await $`echo "hello"`.pipe`cat`;
+// 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`;
 ```
 
@@ -232,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
@@ -244,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)
@@ -282,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
 
@@ -302,12 +349,12 @@ const syncFiles = globSync("**/*.test.ts", { cwd: "tests" });
 
 // Convert file path to glob pattern
 const pattern = convertPathToPattern("/home/user/project");
-```
+````
 
 ### Result Pattern - Functional Error Handling
 
 ```typescript
-import { err, ok, Result, safeTry } from "@goodbyenjn/utils/result";
+import { err, ok, Result } from "@goodbyenjn/utils/result";
 
 // Create results explicitly
 const success = ok(42);
@@ -315,7 +362,7 @@ const failure = err("Something went wrong");
 
 // Handle results with chainable methods
 const doubled = success
-    .map(value => value * 2)
+    .map(value => value * 2) // Supports async: .map(async v => v * 2) returns Promise<Result>
     .mapErr(err => `Error: ${err}`)
     .unwrapOr(0); // 84
 
@@ -323,28 +370,36 @@ const doubled = success
 const result: Result<string, Error> = ok("value");
 const transformed = result.mapErr(() => new Error("Custom error"));
 
-// Convert throwing functions to Result
+// Convert throwing functions or promises to Result
 async function fetchUser(id: string) {
-    // If the function throws, it's caught and wrapped in Err
-    const user = await Result.fromCallable(() => JSON.parse(userJson));
+    // Result.try catches thrown errors
+    const user = await Result.try(() => JSON.parse(userJson));
+    // Or handle promise rejections
+    const user = await Result.try(fetch(`/api/users/${id}`));
 
     return user.map(u => u.name).mapErr(err => new Error(`Failed to parse user: ${err.message}`));
 }
 
+// Wrap a function to always return a Result
+const safeParse = Result.wrap(JSON.parse, Error);
+const data = safeParse('{"valid": true}'); // Result<any, Error>
+
 // Combine multiple Results
 const results = [ok(1), ok(2), err("oops"), ok(4)];
 const combined = Result.all(...results); // Err("oops")
 
-// Safe try-catch alternative
-const safeTryExample = await safeTry(async () => {
-    return await fetch("/api/data").then(r => r.json());
+// Generator-based "do" notation for flattening Results
+const finalResult = Result.gen(function* () {
+    const a = yield* ok(10);
+    const b = yield* ok(20);
+    return a + b;
+}); // ok(30)
+
+// Supports async generators
+const asyncFinal = await Result.gen(async function* () {
+    const user = yield* await fetchUser("1");
+    return user.name;
 });
-
-if (safeTryExample.isOk()) {
-    console.log("Data:", safeTryExample.unwrap());
-} else {
-    console.error("Failed:", safeTryExample.unwrapErr());
-}
 ```
 
 ### Type Utilities
@@ -356,46 +411,56 @@ import type {
     YieldType,
     OmitByKey,
     SetNullable,
+    TemplateFn,
 } from "@goodbyenjn/utils/types";
 
+// ... (other types)
+
+// Template string function type
+const myTag: TemplateFn<string> = (strings, ...values) => {
+    return strings[0] + values[0];
+};
+```
+
 // Nullable type for values that can be null or undefined
 type User = {
-    id: string;
-    name: string;
-    email: Nullable<string>; // string | null | undefined
+id: string;
+name: string;
+email: Nullable<string>; // string | null | undefined
 };
 
 // Optional type (undefined but not null)
 type Profile = {
-    bio: Optional<string>; // string | undefined
+bio: Optional<string>; // string | undefined
 };
 
 // Extract yield type from generators
-function* numberGenerator() {
-    yield 1;
-    yield 2;
-    yield 3;
+function\* numberGenerator() {
+yield 1;
+yield 2;
+yield 3;
 }
 
 type NumberType = YieldType<typeof numberGenerator>; // number
 
 // Omit properties by their value type
 type Config = {
-    name: string;
-    debug: boolean;
-    verbose: boolean;
-    timeout: number;
+name: string;
+debug: boolean;
+verbose: boolean;
+timeout: number;
 };
 type WithoutBooleans = OmitByKey<Config, boolean>; // { name: string; timeout: number }
 
 // Set specific properties to nullable
 type APIResponse = {
-    id: number;
-    name: string;
-    email: string;
+id: number;
+name: string;
+email: string;
 };
 type PartialResponse = SetNullable<APIResponse, "email" | "name">; // email and name become nullable
-```
+
+````
 
 ### Extended Remeda Utilities
 
@@ -492,7 +557,7 @@ const totalAge = sumBy(
 // Chunk array into groups
 const chunked = chunk(users, 2);
 // [[user1, user2], [user3]]
-```
+````
 
 ## API Reference