command-stream 0.8.2 → 0.9.0

package/js/examples/methods-run-basic.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+// Using .run() method (identical functionality to .start())
+
+import { $ } from '../src/$.mjs';
+
+console.log('Using .run() method (identical functionality):');
+const result = await $`echo "Using .run() method"`.run({ mirror: false });
+console.log(`Result: ${JSON.stringify(result.stdout)}`);
+console.log(`Code: ${result.code}`);

package/js/examples/methods-start-basic.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+// Using .start() method
+
+import { $ } from '../src/$.mjs';
+
+console.log('Using .start() method:');
+const result = await $`echo "Using .start() method"`.start({ mirror: false });
+console.log(`Result: ${JSON.stringify(result.stdout)}`);
+console.log(`Code: ${result.code}`);

package/js/examples/node-compat-data-events.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env bun
+
+// Node.js spawn with on("data") events
+
+import { spawn } from 'child_process';
+
+console.log('Node.js spawn with on("data") events:');
+
+const start = Date.now();
+let chunkCount = 0;
+
+const proc1 = spawn('bun', ['run', 'js/examples/emulate-claude-stream.mjs']);
+const proc2 = spawn('jq', ['.'], {
+  stdio: ['pipe', 'pipe', 'pipe'],
+});
+
+// Pipe proc1 to proc2
+proc1.stdout.pipe(proc2.stdin);
+
+// Listen for data events
+proc2.stdout.on('data', (chunk) => {
+  chunkCount++;
+  const elapsed = Date.now() - start;
+  const text = chunk.toString();
+  const lines = text
+    .split('\n')
+    .filter((l) => l.trim())
+    .slice(0, 2);
+  console.log(
+    `[${elapsed}ms] Chunk ${chunkCount}: ${chunk.length} bytes, first lines:`,
+    lines
+  );
+});
+
+await new Promise((resolve) => proc2.on('exit', resolve));
+console.log(`Total chunks: ${chunkCount}`);

package/js/examples/node-compat-readable-event.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env bun
+
+// Using readable event
+
+import { spawn } from 'child_process';
+
+console.log('Using readable event:');
+
+const start = Date.now();
+let chunkCount = 0;
+
+const proc1 = spawn('bun', ['run', 'js/examples/emulate-claude-stream.mjs']);
+const proc2 = spawn('jq', ['.'], {
+  stdio: ['pipe', 'pipe', 'pipe'],
+});
+
+proc1.stdout.pipe(proc2.stdin);
+
+proc2.stdout.on('readable', () => {
+  let chunk;
+  while (null !== (chunk = proc2.stdout.read())) {
+    chunkCount++;
+    const elapsed = Date.now() - start;
+    console.log(`[${elapsed}ms] Chunk ${chunkCount}: ${chunk.length} bytes`);
+  }
+});
+
+await new Promise((resolve) => proc2.on('exit', resolve));
+console.log(`Total chunks: ${chunkCount}`);

package/js/examples/node-compat-small-buffer.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env bun
+
+// Reading with small buffer size
+
+import { spawn } from 'child_process';
+
+console.log('Reading with small buffer size:');
+
+const start = Date.now();
+let chunkCount = 0;
+
+const proc1 = spawn('bun', ['run', 'js/examples/emulate-claude-stream.mjs']);
+const proc2 = spawn('jq', ['.'], {
+  stdio: ['pipe', 'pipe', 'pipe'],
+});
+
+proc1.stdout.pipe(proc2.stdin);
+
+// Try to read in smaller chunks
+proc2.stdout.on('readable', () => {
+  let chunk;
+  while (null !== (chunk = proc2.stdout.read(1))) {
+    // Read 1 byte at a time
+    chunkCount++;
+    const elapsed = Date.now() - start;
+    if (chunkCount === 1 || chunkCount % 100 === 0) {
+      console.log(`[${elapsed}ms] Byte ${chunkCount}: ${chunk.toString()}`);
+    }
+  }
+});
+
+await new Promise((resolve) => proc2.on('exit', resolve));
+console.log(`Total bytes read: ${chunkCount}`);

package/js/examples/options-capture-false.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+// Using .start() with capture: false
+
+import { $ } from '../src/$.mjs';
+
+console.log('Testing $`echo test`.start({ capture: false }):');
+const result = await $`echo "test with capture false"`.start({
+  capture: false,
+});
+console.log('Result stdout:', JSON.stringify(result.stdout)); // Should be undefined
+console.log('Result code:', result.code);

package/js/examples/options-combined-settings.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+// Using .run() alias with both mirror and capture options
+
+import { $ } from '../src/$.mjs';
+
+console.log('Testing $`echo test`.run({ mirror: false, capture: true }):');
+const result = await $`echo "test with both options"`.run({
+  mirror: false,
+  capture: true,
+});
+console.log('Result stdout:', JSON.stringify(result.stdout)); // Should have content
+console.log('Result code:', result.code);

package/js/examples/options-custom-input.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+// Custom input with options
+
+import { $ } from '../src/$.mjs';
+
+console.log('Custom input with options:');
+console.log('await $`cat`.start({ stdin: "custom", mirror: false })');
+const result = await $`cat`.start({
+  stdin: 'This is custom input data',
+  mirror: false,
+  capture: true,
+});
+console.log(
+  `Exit code: ${result.code}, Output: ${JSON.stringify(result.stdout)}`
+);

package/js/examples/options-default-behavior.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+// Default behavior comparison (direct await)
+
+import { $ } from '../src/$.mjs';
+
+console.log('Testing default await $`echo test` (for comparison):');
+const result = await $`echo "test default behavior"`;
+console.log('Result stdout:', JSON.stringify(result.stdout)); // Should have content
+console.log('Result code:', result.code);

package/js/examples/options-maximum-performance.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+// Maximum performance - no capture, no mirror
+
+import { $ } from '../src/$.mjs';
+
+console.log('Maximum performance - no capture, no mirror:');
+console.log('await $`echo "blazing"`.start({ capture: false, mirror: false })');
+const result = await $`echo "This is blazing fast!"`.start({
+  capture: false,
+  mirror: false,
+});
+console.log(
+  `Exit code: ${result.code}, Stdout: ${JSON.stringify(result.stdout)}`
+);

package/js/examples/options-mirror-false.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+// Using .start() with mirror: false
+
+import { $ } from '../src/$.mjs';
+
+console.log('Testing $`echo test`.start({ mirror: false }):');
+const result = await $`echo "test with mirror false"`.start({ mirror: false });
+console.log('Result stdout:', JSON.stringify(result.stdout)); // Should have content
+console.log('Result code:', result.code);

package/js/examples/options-performance-mode.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+// capture: false and mirror: false together (maximum performance)
+
+import { $ } from '../src/$.mjs';
+
+console.log('Testing $`echo test`.start({ capture: false, mirror: false }):');
+const result = await $`echo "no capture, no mirror"`.start({
+  capture: false,
+  mirror: false,
+});
+console.log('Result stdout:', JSON.stringify(result.stdout)); // Should be undefined
+console.log('Result code:', result.code);

package/js/examples/options-performance-optimization.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+// Performance optimization - disable capture
+
+import { $ } from '../src/$.mjs';
+
+console.log('Performance optimization - disable capture:');
+console.log('await $`echo "fast"`.start({ capture: false })');
+const result = await $`echo "This runs fast without memory capture"`.start({
+  capture: false,
+});
+console.log(
+  `Exit code: ${result.code}, Stdout: ${JSON.stringify(result.stdout)}`
+);

package/js/examples/options-run-alias-demo.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+// Using .run() alias
+
+import { $ } from '../src/$.mjs';
+
+console.log('Using .run() alias:');
+console.log('await $`echo "alias"`.run({ capture: true, mirror: false })');
+const result = await $`echo "Using .run() instead of .start()"`.run({
+  capture: true,
+  mirror: false,
+});
+console.log(
+  `Exit code: ${result.code}, Captured: ${JSON.stringify(result.stdout)}`
+);

package/js/examples/options-run-alias.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+// Using .run() alias with capture: false
+
+import { $ } from '../src/$.mjs';
+
+console.log('Testing $`echo test`.run({ capture: false }):');
+const result = await $`echo "test with run alias"`.run({ capture: false });
+console.log('Result stdout:', JSON.stringify(result.stdout)); // Should be undefined
+console.log('Result code:', result.code);

package/js/examples/options-silent-execution.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+// Silent execution - disable mirroring
+
+import { $ } from '../src/$.mjs';
+
+console.log('Silent execution - disable mirroring:');
+console.log('await $`echo "silent"`.start({ mirror: false })');
+const result = await $`echo "This won't show on console but is captured"`.start(
+  { mirror: false }
+);
+console.log(
+  `Exit code: ${result.code}, Captured: ${JSON.stringify(result.stdout)}`
+);

package/js/examples/options-streaming-capture.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+
+// Capture enabled with streaming using $({ capture: true })
+
+import { $ } from '../src/$.mjs';
+
+console.log('Capture enabled with streaming:');
+const $capture = $({ capture: true, mirror: false });
+
+try {
+  const runner = $capture`echo -e "Line 1\nLine 2\nLine 3"`;
+
+  for await (const chunk of runner.stream()) {
+    if (chunk.type === 'stdout') {
+      const output = chunk.data.toString();
+      console.log(`📦 Streaming: ${output.trim()}`);
+    }
+  }
+
+  const result = await runner;
+  console.log(`💾 Final captured: "${result.stdout.trim()}"`);
+} catch (error) {
+  console.log(`Error: ${error.message}`);
+}

package/js/examples/options-streaming-multiple.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+
+// Multiple configured instances with different options
+
+import { $ } from '../src/$.mjs';
+
+console.log('Multiple configured instances:');
+const $quiet = $({ mirror: false });
+const $verbose = $({ mirror: true });
+
+try {
+  console.log('Running quiet ping...');
+  for await (const chunk of $quiet`ping -c 2 127.0.0.1`.stream()) {
+    if (
+      chunk.type === 'stdout' &&
+      chunk.data.toString().includes('bytes from')
+    ) {
+      console.log(`🤫 Quiet result: ping successful`);
+    }
+  }
+
+  console.log('\nRunning verbose ping...');
+  let count = 0;
+  for await (const chunk of $verbose`ping -c 2 127.0.0.1`.stream()) {
+    if (
+      chunk.type === 'stdout' &&
+      chunk.data.toString().includes('bytes from')
+    ) {
+      count++;
+      console.log(`📢 Verbose: packet #${count} received`);
+    }
+  }
+} catch (error) {
+  console.log(`Error: ${error.message}`);
+}

package/js/examples/options-streaming-silent.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+
+// Silent streaming using $({ mirror: false }) syntax
+
+import { $ } from '../src/$.mjs';
+
+console.log('Silent streaming (mirror: false):');
+const $silent = $({ mirror: false });
+
+try {
+  for await (const chunk of $silent`ping -c 3 8.8.8.8`.stream()) {
+    if (chunk.type === 'stdout') {
+      const output = chunk.data.toString().trim();
+      if (output) {
+        console.log(`🔇 Silent: ${output}`);
+      }
+    }
+  }
+} catch (error) {
+  console.log(`Error: ${error.message}`);
+}

package/js/examples/options-streaming-stdin.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+
+// Streaming with custom stdin using $({ stdin }) syntax
+
+import { $ } from '../src/$.mjs';
+
+console.log('Streaming with custom stdin:');
+const $withStdin = $({ stdin: 'Hello\nWorld\n', mirror: false });
+
+try {
+  for await (const chunk of $withStdin`cat -n`.stream()) {
+    if (chunk.type === 'stdout') {
+      const output = chunk.data.toString().trim();
+      if (output) {
+        console.log(`📝 Input: ${output}`);
+      }
+    }
+  }
+} catch (error) {
+  console.log(`Error: ${error.message}`);
+}

package/js/examples/ping-streaming-filtered.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+// Filtering only ping replies (no summary)
+
+import { $ } from '../src/$.mjs';
+
+console.log('Filtering only ping replies (no summary):');
+console.log('Running ping -c 3 1.1.1.1...\n');
+
+try {
+  for await (const chunk of $`ping -c 3 1.1.1.1`.stream()) {
+    if (chunk.type === 'stdout') {
+      const output = chunk.data.toString().trim();
+      // Only show lines with ping replies (contain "bytes from")
+      if (output.includes('bytes from')) {
+        console.log(`📡 ${output}`);
+      }
+    }
+  }
+} catch (error) {
+  console.log(`Error: ${error.message}`);
+}

package/js/examples/ping-streaming-interruptible.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+
+// Interruptible ping streaming - shows how to handle CTRL+C gracefully
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Interruptible Ping Streaming ===');
+console.log('Streaming continuous ping - press CTRL+C to stop gracefully...\n');
+
+let packetCount = 0;
+const startTime = Date.now();
+
+try {
+  // Stream continuous ping (no -c limit)
+  for await (const chunk of $`ping 8.8.8.8`.stream()) {
+    if (chunk.type === 'stdout') {
+      const output = chunk.data.toString().trim();
+
+      if (output.includes('bytes from')) {
+        packetCount++;
+        const timeMatch = output.match(/time=([0-9.]+)/);
+        const responseTime = timeMatch ? timeMatch[1] : 'unknown';
+
+        console.log(`Packet #${packetCount}: ${responseTime}ms`);
+
+        // Show periodic statistics
+        if (packetCount % 5 === 0) {
+          const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+          console.log(`  └─ ${packetCount} packets in ${elapsed}s`);
+        }
+      }
+    }
+  }
+} catch (error) {
+  const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+
+  if (error.code === 130 || error.code === -2) {
+    console.log(`\n✅ Ping stopped by CTRL+C after ${elapsed}s`);
+    console.log(`📊 Total packets received: ${packetCount}`);
+    console.log('🎯 Stream handling completed gracefully!');
+  } else {
+    console.error(`\n❌ Ping failed: ${error.message}`);
+    console.log(`📊 Packets received before failure: ${packetCount}`);
+  }
+}
+
+console.log('\n=== Streaming session ended ===');

package/js/examples/ping-streaming-silent.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+
+// Silent streaming (no mirror to terminal)
+
+import { $ } from '../src/$.mjs';
+
+console.log('Silent streaming (no mirror to terminal):');
+console.log('Running ping -c 3 127.0.0.1 with mirror: false...\n');
+
+try {
+  const $silent = $({ mirror: false });
+
+  for await (const chunk of $silent`ping -c 3 127.0.0.1`.stream()) {
+    if (chunk.type === 'stdout') {
+      const output = chunk.data.toString().trim();
+      if (output) {
+        // Custom formatting since we're not mirroring
+        console.log(`🔇 Silent: ${output}`);
+      }
+    }
+  }
+} catch (error) {
+  console.log(`Error: ${error.message}`);
+}

package/js/examples/ping-streaming-simple.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+// Simple ping streaming example - minimal code, maximum clarity
+
+import { $ } from '../src/$.mjs';
+
+console.log('Streaming ping output in real-time...\n');
+
+for await (const chunk of $`ping -c 5 8.8.8.8`.stream()) {
+  if (chunk.type === 'stdout') {
+    console.log('Real-time output:', chunk.data.toString().trim());
+  }
+}

package/js/examples/ping-streaming-statistics.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+// Counting responses with statistics
+
+import { $ } from '../src/$.mjs';
+
+console.log('Counting responses with statistics:');
+console.log('Running ping -c 4 8.8.8.8...\n');
+
+let responseCount = 0;
+let totalTime = 0;
+const responses = [];
+
+try {
+  for await (const chunk of $`ping -c 4 8.8.8.8`.stream()) {
+    if (chunk.type === 'stdout') {
+      const output = chunk.data.toString().trim();
+
+      if (output.includes('bytes from')) {
+        responseCount++;
+
+        // Extract response time
+        const timeMatch = output.match(/time=([0-9.]+)/);
+        if (timeMatch) {
+          const responseTime = parseFloat(timeMatch[1]);
+          responses.push(responseTime);
+          totalTime += responseTime;
+
+          console.log(`Response #${responseCount}: ${responseTime}ms`);
+        }
+      }
+
+      // Show final statistics
+      if (output.includes('packets transmitted')) {
+        console.log('\n📊 Final Statistics:');
+        console.log(`• Total responses: ${responseCount}`);
+        if (responses.length > 0) {
+          console.log(
+            `• Average time: ${(totalTime / responses.length).toFixed(2)}ms`
+          );
+          console.log(`• Min time: ${Math.min(...responses).toFixed(2)}ms`);
+          console.log(`• Max time: ${Math.max(...responses).toFixed(2)}ms`);
+        }
+      }
+    }
+  }
+} catch (error) {
+  console.log(`Error: ${error.message}`);
+}

package/js/examples/ping-streaming-timestamps.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+// Basic ping streaming with timestamps
+
+import { $ } from '../src/$.mjs';
+
+console.log('Basic streaming with timestamps:');
+console.log('Running ping -c 5 google.com...\n');
+
+try {
+  for await (const chunk of $`ping -c 5 google.com`.stream()) {
+    if (chunk.type === 'stdout') {
+      const output = chunk.data.toString().trim();
+      if (output) {
+        const time = new Date().toLocaleTimeString();
+        console.log(`[${time}] ${output}`);
+      }
+    }
+  }
+} catch (error) {
+  console.log(`Error: ${error.message}`);
+}

package/js/examples/ping-streaming.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+
+// Streaming ping example - shows real-time output as it arrives
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Real-time Ping Streaming Example ===');
+console.log('Press CTRL+C to stop the ping...\n');
+
+try {
+  // Stream ping output in real-time
+  for await (const chunk of $`ping -c 10 8.8.8.8`.stream()) {
+    if (chunk.type === 'stdout') {
+      // Process each line of ping output as it arrives
+      const output = chunk.data.toString().trim();
+      if (output) {
+        const timestamp = new Date().toISOString().substring(11, 23);
+        console.log(`[${timestamp}] ${output}`);
+
+        // Parse ping statistics if available
+        if (output.includes('time=')) {
+          const timeMatch = output.match(/time=([0-9.]+)/);
+          if (timeMatch) {
+            const responseTime = parseFloat(timeMatch[1]);
+            const status =
+              responseTime < 50
+                ? '🟢 Fast'
+                : responseTime < 100
+                  ? '🟡 Normal'
+                  : '🔴 Slow';
+            console.log(`    └─ Response time: ${responseTime}ms ${status}`);
+          }
+        }
+      }
+    } else if (chunk.type === 'stderr') {
+      // Handle any error output
+      console.error('Error:', chunk.data.toString().trim());
+    }
+  }
+} catch (error) {
+  if (error.code === 130) {
+    console.log('\n✓ Ping interrupted by user (CTRL+C)');
+  } else {
+    console.error('\n✗ Ping failed:', error.message);
+  }
+}
+
+console.log('\n=== Ping streaming completed ===');