feat: add process utilities for safe command execution

Author: GoodbyeNJN

README.md

@@ -12,7 +12,7 @@ GoodbyeNJN's utility library for TypeScript and JavaScript, providing a collecti
 - 📦 **Modular**: Import only what you need with tree-shakable exports
 - 🛡️ **Result Type**: Functional error handling with Result pattern
 - 📁 **File System**: Safe file system operations with Result types
-- 🧰 **Common Utils**: String, math, promise, and other utility functions
+- 🧰 **Common Utils**: String, math, promise, process, and other utility functions
 - 📊 **Remeda Extensions**: Extended utilities built on top of Remeda
 
 ## Installation
@@ -30,7 +30,7 @@ yarn add @goodbyenjn/utils
 ### Common Utilities
 
 ```typescript
-import { sleep, template, unindent, debounce } from "@goodbyenjn/utils";
+import { sleep, template, unindent, debounce, $ } from "@goodbyenjn/utils";
 
 // Promise utilities
 await sleep(1000); // Sleep for 1 second
@@ -45,6 +45,15 @@ const code = unindent`
     }
 `;
 
+// Process utilities - Execute shell commands safely
+const result = await $`ls -la`;
+if (result.isOk()) {
+    console.log("stdout:", result.value.stdout);
+    console.log("stderr:", result.value.stderr);
+} else {
+    console.error("Command failed:", result.error);
+}
+
 // Throttling and debouncing
 const debouncedFn = debounce(() => console.log("Called!"), 300);
 ```
@@ -134,7 +143,7 @@ type NumberType = YieldType<typeof numberGenerator>; // number
 
 ### Available Modules
 
-- **Main (`@goodbyenjn/utils`)** - Common utilities (string, math, promise, error handling, etc.)
+- **Main (`@goodbyenjn/utils`)** - Common utilities (string, math, promise, process, error handling, etc.)
 - **File System (`@goodbyenjn/utils/fs`)** - Safe file system operations
 - **Result (`@goodbyenjn/utils/result`)** - Functional error handling
 - **Remeda (`@goodbyenjn/utils/remeda`)** - Extended Remeda utilities
@@ -157,6 +166,10 @@ type NumberType = YieldType<typeof numberGenerator>; // number
 - `createSingleton(factory)` - Create singleton factory
 - `PromiseWithResolvers` - Promise with external resolvers
 
+#### Process Utilities
+
+- `$(command)` - Execute shell commands safely, returns ResultAsync with stdout/stderr
+
 #### Math Utilities
 
 - `linear(value, range)` - Linear interpolation

src/common/index.ts

@@ -4,6 +4,8 @@ export { linear, scale } from "./math";
 
 export { parseKeyValuePairs, parseValueToBoolean } from "./parse";
 
+export { $ } from "./process";
+
 export { PromiseWithResolvers, createLock, createSingleton, sleep } from "./promise";
 
 export {

src/common/process.ts

@@ -0,0 +1,28 @@
+import { isString } from "@/remeda";
+import { ResultAsync } from "@/result";
+
+import { errorToMessage } from "./error";
+import { PromiseWithResolvers } from "./promise";
+
+export const $ = (cmd: TemplateStringsArray | string) => {
+    const command = isString(cmd) ? cmd : cmd[0]!;
+
+    const promise = import("node:child_process").then(({ exec }) => {
+        const { promise, reject, resolve } = PromiseWithResolvers<{
+            stdout: string;
+            stderr: string;
+        }>();
+
+        exec(command, (error, stdout, stderr) => {
+            if (error) {
+                reject(error);
+            } else {
+                resolve({ stdout, stderr });
+            }
+        });
+
+        return promise;
+    });
+
+    return ResultAsync.fromPromise(promise, errorToMessage(`Failed to execute command: ${cmd}`));
+};