command-stream 0.0.1 → 0.0.3

package/$.mjs

@@ -16,6 +16,20 @@ let globalShellSettings = {
   nounset: false     // set -u equivalent: error on undefined variables
 };
 
+// Helper function to create result objects with Bun.$ compatibility
+function createResult({ code, stdout = '', stderr = '', stdin = '' }) {
+  return {
+    code,
+    stdout,
+    stderr,
+    stdin,
+    // Bun.$ compatibility method
+    async text() {
+      return stdout;
+    }
+  };
+}
+
 // Virtual command registry - unified system for all commands
 const virtualCommands = new Map();
 
@@ -219,13 +233,21 @@ class ProcessRunner extends StreamEmitter {
     const code = await exited;
     await Promise.all([outPump, errPump, stdinPumpPromise]);
 
-    this.result = {
+    const resultData = {
       code,
       stdout: this.options.capture ? Buffer.concat(this.outChunks).toString('utf8') : undefined,
       stderr: this.options.capture ? Buffer.concat(this.errChunks).toString('utf8') : undefined,
       stdin: this.options.capture && this.inChunks ? Buffer.concat(this.inChunks).toString('utf8') : undefined,
       child: this.child
     };
+    
+    this.result = {
+      ...resultData,
+      // Bun.$ compatibility method
+      async text() {
+        return resultData.stdout || '';
+      }
+    };
 
     this.finished = true;
     this.emit('end', this.result);
@@ -481,7 +503,7 @@ class ProcessRunner extends StreamEmitter {
 
   async _runPipeline(commands) {
     if (commands.length === 0) {
-      return { code: 1, stdout: '', stderr: 'No commands in pipeline', stdin: '' };
+      return createResult({ code: 1, stdout: '', stderr: 'No commands in pipeline', stdin: '' });
     }
 
     let currentOutput = '';
@@ -565,14 +587,14 @@ class ProcessRunner extends StreamEmitter {
               this.emit('data', { type: 'stderr', data: buf });
             }
             
-            // Store final result
-            const finalResult = {
+            // Store final result using createResult helper for .text() method compatibility
+            const finalResult = createResult({
               code: result.code,
               stdout: currentOutput,
               stderr: result.stderr,
               stdin: this.options.stdin && typeof this.options.stdin === 'string' ? this.options.stdin : 
                      this.options.stdin && Buffer.isBuffer(this.options.stdin) ? this.options.stdin.toString('utf8') : ''
-            };
+            });
             
             this.result = finalResult;
             this.finished = true;
@@ -605,13 +627,13 @@ class ProcessRunner extends StreamEmitter {
           }
         } catch (error) {
           // Handle errors from virtual commands in pipeline
-          const result = {
+          const result = createResult({
             code: error.code ?? 1,
             stdout: currentOutput,
             stderr: error.stderr ?? error.message,
             stdin: this.options.stdin && typeof this.options.stdin === 'string' ? this.options.stdin : 
                    this.options.stdin && Buffer.isBuffer(this.options.stdin) ? this.options.stdin.toString('utf8') : ''
-          };
+          });
           
           this.result = result;
           this.finished = true;
@@ -637,13 +659,13 @@ class ProcessRunner extends StreamEmitter {
       } else {
         // For system commands in pipeline, we would need to spawn processes
         // For now, return an error indicating this isn't supported
-        const result = {
+        const result = createResult({
           code: 1,
           stdout: currentOutput,
           stderr: `Pipeline with system command '${cmd}' not yet supported`,
           stdin: this.options.stdin && typeof this.options.stdin === 'string' ? this.options.stdin : 
                  this.options.stdin && Buffer.isBuffer(this.options.stdin) ? this.options.stdin.toString('utf8') : ''
-        };
+        });
         
         this.result = result;
         this.finished = true;
@@ -684,21 +706,21 @@ class ProcessRunner extends StreamEmitter {
       const destResult = await destination;
       
       // Return the final result with combined information
-      return {
+      return createResult({
         code: destResult.code,
         stdout: destResult.stdout,
         stderr: sourceResult.stderr + destResult.stderr,
         stdin: sourceResult.stdin
-      };
+      });
       
     } catch (error) {
-      const result = {
+      const result = createResult({
         code: error.code ?? 1,
         stdout: '',
         stderr: error.message || 'Pipeline execution failed',
         stdin: this.options.stdin && typeof this.options.stdin === 'string' ? this.options.stdin : 
                this.options.stdin && Buffer.isBuffer(this.options.stdin) ? this.options.stdin.toString('utf8') : ''
-      };
+      });
       
       this.result = result;
       this.finished = true;
@@ -846,14 +868,14 @@ class ProcessRunner extends StreamEmitter {
         stderr: 'pipe'
       });
       
-      result = {
+      result = createResult({
         code: proc.exitCode || 0,
         stdout: proc.stdout?.toString('utf8') || '',
         stderr: proc.stderr?.toString('utf8') || '',
         stdin: typeof stdin === 'string' ? stdin : 
-               Buffer.isBuffer(stdin) ? stdin.toString('utf8') : '',
-        child: proc
-      };
+               Buffer.isBuffer(stdin) ? stdin.toString('utf8') : ''
+      });
+      result.child = proc;
     } else {
       // Use Node's synchronous spawn
       const cp = require('child_process');
@@ -866,14 +888,14 @@ class ProcessRunner extends StreamEmitter {
         stdio: ['pipe', 'pipe', 'pipe']
       });
       
-      result = {
+      result = createResult({
         code: proc.status || 0,
         stdout: proc.stdout || '',
         stderr: proc.stderr || '',
         stdin: typeof stdin === 'string' ? stdin : 
-               Buffer.isBuffer(stdin) ? stdin.toString('utf8') : '',
-        child: proc
-      };
+               Buffer.isBuffer(stdin) ? stdin.toString('utf8') : ''
+      });
+      result.child = proc;
     }
     
     // Mirror output if requested (but always capture for result)

package/README.md

@@ -1,9 +1,11 @@
-# command-$tream
+# [command-$tream](https://github.com/link-foundation/command-stream)
 
 $treamable commands executor
 
 A modern $ shell utility library with streaming, async iteration, and EventEmitter support, optimized for Bun runtime.
 
+<img width="2624" height="1320" alt="carbon" src="https://github.com/user-attachments/assets/41cccd6a-f029-4206-b3bc-a85c5dbcf2cf" />
+
 ## Features
 
 - 🐚 **Shell-like by Default**: Commands behave exactly like running in terminal (stdout→stdout, stderr→stderr, stdin→stdin)
@@ -12,10 +14,51 @@ A modern $ shell utility library with streaming, async iteration, and EventEmitt
 - 📡 **Real-time Streaming**: Process command output as it arrives, not after completion
 - 🔄 **Bun Optimized**: Designed for Bun runtime with Node.js compatibility
 - ⚡ **Performance**: Memory-efficient streaming prevents large buffer accumulation
-- 🎯 **Backward Compatible**: Existing `await $` syntax continues to work
+- 🎯 **Backward Compatible**: Existing `await $` syntax continues to work + Bun.$ `.text()` method
 - 🛡️ **Type Safe**: Full TypeScript support (coming soon)
 - 🔧 **Built-in Commands**: 18 essential commands work identically across platforms
 
+## Comparison with Other Libraries
+
+| Feature | [command-stream](https://github.com/link-foundation/command-stream) | [Bun.$](https://bun.sh/docs/runtime/shell) | [execa](https://github.com/sindresorhus/execa) | [zx](https://github.com/google/zx) |
+|---------|----------------|-------|-------|-----|
+| **Runtime Support** | ✅ Bun + Node.js | 🟡 Bun only | ✅ Node.js | ✅ Node.js |
+| **Template Literals** | ✅ `` $`cmd` `` | ✅ `` $`cmd` `` | ✅ `` $`cmd` `` | ✅ `` $`cmd` `` |
+| **Real-time Streaming** | ✅ Live output | ❌ Buffer only | 🟡 Limited | ❌ Buffer only |
+| **Synchronous Execution** | ✅ `.sync()` with events | ❌ No | ✅ `execaSync` | ❌ No |
+| **Async Iteration** | ✅ `for await (chunk of $.stream())` | ❌ No | ❌ No | ❌ No |
+| **EventEmitter Pattern** | ✅ `.on('data', ...)` | ❌ No | 🟡 Limited events | ❌ No |
+| **Mixed Patterns** | ✅ Events + await/sync | ❌ No | ❌ No | ❌ No |
+| **Bun.$ Compatibility** | ✅ `.text()` method support | ✅ Native API | ❌ No | ❌ No |
+| **Shell Injection Protection** | ✅ Auto-quoting | ✅ Built-in | ✅ Safe by default | ✅ Safe by default |
+| **Cross-platform** | ✅ macOS/Linux/Windows | ✅ Yes | ✅ Yes | ✅ Yes |
+| **Performance** | ⚡ Fast (Bun optimized) | ⚡ Very fast | 🐌 Moderate | 🐌 Slow |
+| **Memory Efficiency** | ✅ Streaming prevents buildup | 🟡 Buffers in memory | 🟡 Buffers in memory | 🟡 Buffers in memory |
+| **Error Handling** | ✅ Configurable (`set -e`/`set +e`, non-zero OK by default) | ✅ Throws on error | ✅ Throws on error | ✅ Throws on error |
+| **Shell Settings** | ✅ `set -e`/`set +e` equivalent | ❌ No | ❌ No | ❌ No |
+| **Stdout Support** | ✅ Real-time streaming + events | ✅ Shell redirection + buffered | ✅ Node.js streams + interleaved | ✅ Readable streams + `.pipe.stdout` |
+| **Stderr Support** | ✅ Real-time streaming + events | ✅ Redirection + `.quiet()` access | ✅ Streams + interleaved output | ✅ Readable streams + `.pipe.stderr` |
+| **Stdin Support** | ✅ string/Buffer/inherit/ignore | ✅ Pipe operations | ✅ Input/output streams | ✅ Basic stdin |
+| **Built-in Commands** | ✅ **18 commands**: cat, ls, mkdir, rm, mv, cp, touch, basename, dirname, seq, yes + all Bun.$ commands | ✅ echo, cd, etc. | ❌ Uses system | ❌ Uses system |
+| **Virtual Commands Engine** | ✅ **Revolutionary**: Register JavaScript functions as shell commands with full pipeline support | ❌ No extensibility | ❌ No custom commands | ❌ No custom commands |
+| **Pipeline/Piping Support** | ✅ **Advanced**: System + Built-ins + Virtual + Mixed + `.pipe()` method | ✅ Standard shell piping | ✅ Programmatic `.pipe()` + multi-destination | ✅ Shell piping + `.pipe()` method |
+| **Bundle Size** | 📦 ~15KB | 🎯 0KB (built-in) | 📦 ~25KB | 📦 ~50KB |
+| **TypeScript** | 🔄 Coming soon | ✅ Built-in | ✅ Full support | ✅ Full support |
+| **License** | ✅ **Unlicense (Public Domain)** | 🟡 MIT (+ LGPL dependencies) | 🟡 MIT | 🟡 Apache 2.0 |
+
+### Why Choose command-stream?
+
+- **🆓 Truly Free**: **Unlicense (Public Domain)** - No restrictions, no attribution required, use however you want
+- **🚀 Revolutionary Virtual Commands**: **World's first** fully customizable virtual commands engine - register JavaScript functions as shell commands!
+- **🔗 Advanced Pipeline System**: **Only library** where virtual commands work seamlessly in pipelines with built-ins and system commands
+- **🔧 Built-in Commands**: **18 essential commands** work identically across all platforms - no system dependencies!
+- **📡 Real-time Processing**: Only library with true streaming and async iteration
+- **🔄 Flexible Patterns**: Multiple usage patterns (await, events, iteration, mixed)
+- **🐚 Shell Replacement**: Dynamic error handling with `set -e`/`set +e` equivalents for .sh file replacement
+- **⚡ Bun Optimized**: Designed for Bun with Node.js fallback compatibility  
+- **💾 Memory Efficient**: Streaming prevents large buffer accumulation
+- **🛡️ Production Ready**: 266+ tests with comprehensive coverage
+
 ## Built-in Commands (🚀 NEW!)
 
 command-stream now includes **18 built-in commands** that work identically to their bash/sh counterparts, providing true cross-platform shell scripting without system dependencies:
@@ -72,46 +115,6 @@ await $`seq 1 5 | cat > numbers.txt`;
 await $`basename /path/to/file.txt .txt`; // → "file"
 ```
 
-## Comparison with Other Libraries
-
-| Feature | [command-stream](https://github.com/link-foundation/command-stream) | [Bun.$](https://bun.sh/docs/runtime/shell) | [execa](https://github.com/sindresorhus/execa) | [zx](https://github.com/google/zx) |
-|---------|----------------|-------|-------|-----|
-| **Runtime Support** | ✅ Bun + Node.js | 🟡 Bun only | ✅ Node.js | ✅ Node.js |
-| **Template Literals** | ✅ `` $`cmd` `` | ✅ `` $`cmd` `` | ✅ `` $`cmd` `` | ✅ `` $`cmd` `` |
-| **Real-time Streaming** | ✅ Live output | ❌ Buffer only | 🟡 Limited | ❌ Buffer only |
-| **Synchronous Execution** | ✅ `.sync()` with events | ❌ No | ✅ `execaSync` | ❌ No |
-| **Async Iteration** | ✅ `for await (chunk of $.stream())` | ❌ No | ❌ No | ❌ No |
-| **EventEmitter Pattern** | ✅ `.on('data', ...)` | ❌ No | 🟡 Limited events | ❌ No |
-| **Mixed Patterns** | ✅ Events + await/sync | ❌ No | ❌ No | ❌ No |
-| **Shell Injection Protection** | ✅ Auto-quoting | ✅ Built-in | ✅ Safe by default | ✅ Safe by default |
-| **Cross-platform** | ✅ macOS/Linux/Windows | ✅ Yes | ✅ Yes | ✅ Yes |
-| **Performance** | ⚡ Fast (Bun optimized) | ⚡ Very fast | 🐌 Moderate | 🐌 Slow |
-| **Memory Efficiency** | ✅ Streaming prevents buildup | 🟡 Buffers in memory | 🟡 Buffers in memory | 🟡 Buffers in memory |
-| **Error Handling** | ✅ Configurable (`set -e`/`set +e`, non-zero OK by default) | ✅ Throws on error | ✅ Throws on error | ✅ Throws on error |
-| **Shell Settings** | ✅ `set -e`/`set +e` equivalent | ❌ No | ❌ No | ❌ No |
-| **Stdout Support** | ✅ Real-time streaming + events | ✅ Shell redirection + buffered | ✅ Node.js streams + interleaved | ✅ Readable streams + `.pipe.stdout` |
-| **Stderr Support** | ✅ Real-time streaming + events | ✅ Redirection + `.quiet()` access | ✅ Streams + interleaved output | ✅ Readable streams + `.pipe.stderr` |
-| **Stdin Support** | ✅ string/Buffer/inherit/ignore | ✅ Pipe operations | ✅ Input/output streams | ✅ Basic stdin |
-| **Built-in Commands** | ✅ **18 commands**: cat, ls, mkdir, rm, mv, cp, touch, basename, dirname, seq, yes + all Bun.$ commands | ✅ echo, cd, etc. | ❌ Uses system | ❌ Uses system |
-| **Virtual Commands Engine** | ✅ **Revolutionary**: Register JavaScript functions as shell commands with full pipeline support | ❌ No extensibility | ❌ No custom commands | ❌ No custom commands |
-| **Pipeline/Piping Support** | ✅ **Advanced**: System + Built-ins + Virtual + Mixed + `.pipe()` method | ✅ Standard shell piping | ✅ Programmatic `.pipe()` + multi-destination | ✅ Shell piping + `.pipe()` method |
-| **Bundle Size** | 📦 ~15KB | 🎯 0KB (built-in) | 📦 ~25KB | 📦 ~50KB |
-| **TypeScript** | 🔄 Coming soon | ✅ Built-in | ✅ Full support | ✅ Full support |
-| **License** | ✅ **Unlicense (Public Domain)** | 🟡 MIT (+ LGPL dependencies) | 🟡 MIT | 🟡 Apache 2.0 |
-
-### Why Choose command-stream?
-
-- **🆓 Truly Free**: **Unlicense (Public Domain)** - No restrictions, no attribution required, use however you want
-- **🚀 Revolutionary Virtual Commands**: **World's first** fully customizable virtual commands engine - register JavaScript functions as shell commands!
-- **🔗 Advanced Pipeline System**: **Only library** where virtual commands work seamlessly in pipelines with built-ins and system commands
-- **🔧 Built-in Commands**: **18 essential commands** work identically across all platforms - no system dependencies!
-- **📡 Real-time Processing**: Only library with true streaming and async iteration
-- **🔄 Flexible Patterns**: Multiple usage patterns (await, events, iteration, mixed)
-- **🐚 Shell Replacement**: Dynamic error handling with `set -e`/`set +e` equivalents for .sh file replacement
-- **⚡ Bun Optimized**: Designed for Bun with Node.js fallback compatibility  
-- **💾 Memory Efficient**: Streaming prevents large buffer accumulation
-- **🛡️ Production Ready**: 266+ tests with comprehensive coverage
-
 ## Installation
 
 ```bash
@@ -693,10 +696,37 @@ All built-in commands support:
   stdout: string,      // Complete stdout output
   stderr: string,      // Complete stderr output
   stdin: string,       // Input sent to process
-  child: ChildProcess  // Original child process object
+  child: ChildProcess, // Original child process object
+  async text()         // Bun.$ compatibility method - returns stdout as string
 }
 ```
 
+#### `.text()` Method (Bun.$ Compatibility)
+
+For compatibility with Bun.$, all result objects include an async `.text()` method:
+
+```javascript
+import { $ } from 'command-stream';
+
+// Both sync and async execution support .text()
+const result1 = await $`echo "hello world"`;
+const text1 = await result1.text(); // "hello world\n"
+
+const result2 = $`echo "sync example"`.sync();  
+const text2 = await result2.text(); // "sync example\n"
+
+// .text() is equivalent to accessing .stdout
+expect(await result.text()).toBe(result.stdout);
+
+// Works with built-in commands
+const result3 = await $`seq 1 3`;
+const text3 = await result3.text(); // "1\n2\n3\n"
+
+// Works with .pipe() method
+const result4 = await $`echo "pipe test"`.pipe($`cat`);
+const text4 = await result4.text(); // "pipe test\n"
+```
+
 ## Testing
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "command-stream",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Modern $ shell utility library with streaming, async iteration, and EventEmitter support, optimized for Bun runtime",
   "type": "module",
   "main": "$.mjs",