command-stream 0.8.2 → 0.9.0

package/js/examples/test-stream-access.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+
+import { $ } from '../src/$.mjs';
+
+async function testStreamAccess() {
+  console.log('Testing event-driven stream access (no setTimeout)...\n');
+
+  // Test 1: Access streams before process starts
+  console.log('Test 1: Accessing streams before process starts');
+  const proc1 = $`echo "Hello from stdout" && echo "Error message" >&2`;
+
+  const streams = proc1.streams;
+  const stdinPromise = streams.stdin;
+  const stdoutPromise = streams.stdout;
+  const stderrPromise = streams.stderr;
+
+  console.log('Waiting for streams...');
+  const [stdin, stdout, stderr] = await Promise.all([
+    stdinPromise,
+    stdoutPromise,
+    stderrPromise,
+  ]);
+
+  console.log('  stdin:', stdin ? 'available' : 'null');
+  console.log('  stdout:', stdout ? 'available' : 'null');
+  console.log('  stderr:', stderr ? 'available' : 'null');
+
+  const result1 = await proc1;
+  console.log('  Result stdout:', result1.stdout.trim());
+  console.log('  Result stderr:', result1.stderr.trim());
+  console.log('✓ Test 1 passed\n');
+
+  // Test 2: Access streams after process starts
+  console.log('Test 2: Accessing streams after process starts');
+  const proc2 = $`sleep 0.1 && echo "Delayed output"`;
+
+  // Start the process
+  proc2.start();
+
+  // Now access streams - should resolve immediately or wait without setTimeout
+  const streams2 = proc2.streams;
+  const stdout2 = await streams2.stdout;
+  console.log('  stdout after start:', stdout2 ? 'available' : 'null');
+
+  const result2 = await proc2;
+  console.log('  Result:', result2.stdout.trim());
+  console.log('✓ Test 2 passed\n');
+
+  // Test 3: Test with finished process
+  console.log('Test 3: Accessing streams of finished process');
+  const proc3 = await $`echo "Already done"`;
+
+  const streams3 = proc3.streams;
+  const stdout3 = await streams3.stdout;
+  console.log(
+    '  stdout of finished process:',
+    stdout3 ? 'available' : 'null (expected)'
+  );
+  console.log('  Result:', proc3.stdout.trim());
+  console.log('✓ Test 3 passed\n');
+
+  // Test 4: Test parent stream closure handling (uses setImmediate now)
+  console.log('Test 4: Parent stream closure handling');
+  const proc4 = $`sleep 0.2 && echo "Should be terminated"`;
+
+  // Simulate parent stream closure scenario
+  setTimeout(() => {
+    console.log('  Simulating kill...');
+    proc4.kill();
+  }, 50);
+
+  try {
+    await proc4;
+  } catch (e) {
+    // Expected to fail
+  }
+
+  console.log('  Process killed successfully');
+  console.log('✓ Test 4 passed\n');
+
+  console.log('All tests passed! No setTimeout used for polling.');
+}
+
+testStreamAccess().catch(console.error);

package/js/examples/test-stream-cleanup.mjs

@@ -0,0 +1,27 @@
+import { $ } from '../src/$.mjs';
+
+console.log('Testing stream cleanup...');
+
+// Test that breaking from iteration kills the process
+let count = 0;
+const startTime = Date.now();
+
+for await (const chunk of $`yes "test output"`.stream()) {
+  console.log(`Chunk ${++count}: ${chunk.data.toString().trim()}`);
+  if (count >= 3) {
+    console.log('Breaking from iteration...');
+    break;
+  }
+}
+
+// Wait a bit to see if process continues outputting
+await new Promise((resolve) => setTimeout(resolve, 100));
+
+console.log(`Test completed in ${Date.now() - startTime}ms`);
+console.log('If you see this message quickly without hanging, cleanup worked!');
+
+// Test with another command to ensure no interference
+const result = await $`echo "clean test"`;
+console.log('Next command output:', result.stdout.trim());
+
+console.log('✅ Stream cleanup test passed!');

package/js/examples/test-stream-readers.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env bun
+
+// Test different ways to read from process streams in Bun
+
+console.log('=== Testing Different Stream Reading Methods ===\n');
+
+// Method 1: Using getReader() with ReadableStream API
+console.log('Method 1: ReadableStream getReader():');
+{
+  const proc = Bun.spawn(
+    ['sh', '-c', 'bun run js/examples/emulate-claude-stream.mjs | jq .'],
+    {
+      stdout: 'pipe',
+      stderr: 'pipe',
+    }
+  );
+
+  const start = Date.now();
+  const reader = proc.stdout.getReader();
+  let chunkCount = 0;
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+      chunkCount++;
+      const elapsed = Date.now() - start;
+      console.log(
+        `  [${elapsed}ms] Chunk ${chunkCount}: ${value.length} bytes`
+      );
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  await proc.exited;
+}
+
+// Method 2: Using readable() if available
+console.log('\nMethod 2: Check if readable() method exists:');
+{
+  const proc = Bun.spawn(['sh', '-c', 'echo "test"'], {
+    stdout: 'pipe',
+  });
+
+  console.log(
+    '  stdout methods:',
+    Object.getOwnPropertyNames(Object.getPrototypeOf(proc.stdout))
+  );
+  await proc.exited;
+}
+
+// Method 3: Try using Bun.file or other APIs
+console.log('\nMethod 3: Using Response API:');
+{
+  const proc = Bun.spawn(
+    ['sh', '-c', 'bun run js/examples/emulate-claude-stream.mjs | jq .'],
+    {
+      stdout: 'pipe',
+      stderr: 'pipe',
+    }
+  );
+
+  const start = Date.now();
+
+  // Try to read as a Response stream
+  const response = new Response(proc.stdout);
+  const reader = response.body.getReader();
+  let chunkCount = 0;
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+      chunkCount++;
+      const elapsed = Date.now() - start;
+      console.log(
+        `  [${elapsed}ms] Chunk ${chunkCount}: ${value.length} bytes`
+      );
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  await proc.exited;
+}
+
+// Method 4: Try smaller reads with setImmediate/setTimeout
+console.log('\nMethod 4: Polling with small timeout:');
+{
+  const proc = Bun.spawn(
+    ['sh', '-c', 'bun run js/examples/emulate-claude-stream.mjs | jq .'],
+    {
+      stdout: 'pipe',
+      stderr: 'pipe',
+    }
+  );
+
+  const start = Date.now();
+  const reader = proc.stdout.getReader();
+  let chunkCount = 0;
+
+  const readWithTimeout = async () => {
+    while (true) {
+      try {
+        // Try to read with a promise race against a timeout
+        const readPromise = reader.read();
+        const timeoutPromise = new Promise((resolve) =>
+          setTimeout(() => resolve({ done: false, timeout: true }), 10)
+        );
+
+        const result = await Promise.race([readPromise, timeoutPromise]);
+
+        if (result.timeout) {
+          // No data yet, continue
+          continue;
+        }
+
+        if (result.done) {
+          break;
+        }
+
+        chunkCount++;
+        const elapsed = Date.now() - start;
+        console.log(
+          `  [${elapsed}ms] Chunk ${chunkCount}: ${result.value.length} bytes`
+        );
+      } catch (e) {
+        break;
+      }
+    }
+  };
+
+  await readWithTimeout();
+  reader.releaseLock();
+  await proc.exited;
+}
+
+// Method 5: Direct file descriptor access (if possible)
+console.log('\nMethod 5: Check proc.stdout properties:');
+{
+  const proc = Bun.spawn(['echo', 'test'], {
+    stdout: 'pipe',
+  });
+
+  console.log('  stdout type:', proc.stdout.constructor.name);
+  console.log('  stdout properties:', Object.keys(proc.stdout));
+
+  await proc.exited;
+}

package/js/examples/test-streaming-final.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env bun
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Final Real-Time Streaming Test ===\n');
+
+console.log('Test 1: Simple command streaming (baseline):');
+{
+  const start = Date.now();
+  for await (const chunk of $`bun run js/examples/emulate-claude-stream.mjs`.stream()) {
+    if (chunk.type === 'stdout') {
+      const elapsed = Date.now() - start;
+      const lines = chunk.data.toString().trim().split('\n');
+      for (const line of lines) {
+        if (line) {
+          console.log(`  [${elapsed}ms] ${line}`);
+        }
+      }
+    }
+  }
+}
+
+console.log('\nTest 2: With jq pipeline (using PTY for real-time streaming):');
+{
+  const start = Date.now();
+  let chunkCount = 0;
+
+  // Use a real command instead of virtual echo
+  for await (const chunk of $`bun run js/examples/emulate-claude-stream.mjs | jq .`.stream()) {
+    if (chunk.type === 'stdout') {
+      chunkCount++;
+      const elapsed = Date.now() - start;
+      const text = chunk.data.toString();
+      const lines = text.split('\n').filter((l) => l.trim());
+
+      console.log(
+        `  [${elapsed}ms] Chunk ${chunkCount}: ${lines.length} lines`
+      );
+      if (lines.length > 0 && chunkCount <= 3) {
+        console.log(`    First line: ${lines[0]}`);
+      }
+    }
+  }
+  console.log(`  Total chunks: ${chunkCount}`);
+  console.log(
+    '  ✅ If you see multiple chunks at different times, streaming works!'
+  );
+}
+
+console.log('\nTest 3: Printf with jq (no virtual commands):');
+{
+  const start = Date.now();
+
+  const result = await $`printf '{"x":1}\\n{"x":2}\\n' | jq .`;
+  console.log(`  Result received at [${Date.now() - start}ms]`);
+  console.log('  Output:', result.stdout.trim());
+}

package/js/examples/test-streaming-interfaces.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+
+/**
+ * Test for Issue #33: Support stdin/stdout/stderr in different flavors
+ *
+ * This example tests the new streaming interfaces:
+ * - command.streams.stdin/stdout/stderr (immediate access)
+ * - command.buffers.stdin/stdout/stderr (binary data)
+ * - command.strings.stdin/stdout/stderr (text data)
+ *
+ * Usage:
+ *   node js/examples/test-streaming-interfaces.mjs
+ */
+
+import { $ } from '../src/$.mjs';
+
+console.log('='.repeat(60));
+console.log('TESTING NEW STREAMING INTERFACES (Issue #33)');
+console.log('='.repeat(60));
+console.log('');
+
+async function testStreamingInterfaces() {
+  try {
+    console.log('=== TEST 1: Immediate streams access ===');
+
+    // Create command but don't start it yet
+    const command1 = $`echo "Hello streams"`;
+    console.log('✓ Command created (not started)');
+
+    // Access streams - this should auto-start the process
+    const streams = command1.streams;
+    console.log('✓ Streams accessed - process should auto-start');
+
+    // The process should now be running, let's wait for completion
+    const result1 = await command1;
+    console.log('✓ Result:', JSON.stringify(result1.stdout.trim()));
+    console.log('');
+
+    console.log('=== TEST 2: Buffers interface ===');
+
+    const command2 = $`echo "Hello buffers"`;
+
+    // Access buffers before completion - should return promises
+    const buffers = command2.buffers;
+    console.log('✓ Buffers accessed - process should auto-start');
+
+    // Get stdout buffer (should be promise initially)
+    const stdoutBuffer = await buffers.stdout;
+    console.log('✓ Buffer result:', stdoutBuffer.toString().trim());
+
+    // Now that process finished, accessing again should return result immediately
+    const immediateBuffer = command2.buffers.stdout;
+    if (immediateBuffer instanceof Buffer) {
+      console.log(
+        '✓ Immediate buffer access works:',
+        immediateBuffer.toString().trim()
+      );
+    } else {
+      console.log('✓ Buffer is still promise (expected for new process)');
+    }
+    console.log('');
+
+    console.log('=== TEST 3: Strings interface ===');
+
+    const command3 = $`echo "Hello strings"`;
+
+    // Access strings before completion - should return promises
+    const strings = command3.strings;
+    console.log('✓ Strings accessed - process should auto-start');
+
+    // Get stdout string (should be promise initially)
+    const stdoutString = await strings.stdout;
+    console.log('✓ String result:', JSON.stringify(stdoutString.trim()));
+    console.log('');
+
+    console.log('=== TEST 4: Mixed usage with stderr ===');
+
+    const command4 = $`sh -c 'echo "stdout message" && echo "stderr message" >&2'`;
+
+    // Test both stdout and stderr
+    const [stdoutStr, stderrStr] = await Promise.all([
+      command4.strings.stdout,
+      command4.strings.stderr,
+    ]);
+
+    console.log('✓ Mixed stdout:', JSON.stringify(stdoutStr.trim()));
+    console.log('✓ Mixed stderr:', JSON.stringify(stderrStr.trim()));
+    console.log('');
+
+    console.log('=== TEST 5: Backward compatibility ===');
+
+    // Ensure old await syntax still works
+    const command5 = $`echo "backward compatible"`;
+    const oldResult = await command5;
+    console.log(
+      '✓ Backward compatible result:',
+      JSON.stringify(oldResult.stdout.trim())
+    );
+    console.log('');
+
+    console.log('=== TEST 6: Stream access after creation ===');
+
+    const command6 = $`ping -c 3 127.0.0.1`;
+
+    // Access stdout stream immediately for real-time monitoring
+    if (command6.streams.stdout) {
+      console.log('✓ Stream available immediately');
+
+      // Set up real-time monitoring
+      let chunks = 0;
+      command6.streams.stdout.on('data', (chunk) => {
+        chunks++;
+        console.log(
+          `  Chunk ${chunks}:`,
+          `${chunk.toString().slice(0, 50)}...`
+        );
+      });
+    } else {
+      console.log(
+        'ℹ️  Stream not immediately available (may need process start)'
+      );
+    }
+
+    // Wait for completion
+    const result6 = await command6;
+    console.log('✓ Ping completed with exit code:', result6.code);
+    console.log('');
+
+    console.log('='.repeat(60));
+    console.log('✅ ALL STREAMING INTERFACE TESTS COMPLETED');
+    console.log('='.repeat(60));
+  } catch (error) {
+    console.log('='.repeat(60));
+    console.error('❌ STREAMING INTERFACE TEST FAILED:', error.message);
+    console.error(error.stack);
+    console.log('='.repeat(60));
+    process.exit(1);
+  }
+}
+
+testStreamingInterfaces();

package/js/examples/test-streaming-timing.mjs

@@ -0,0 +1,27 @@
+import { $ } from '../src/$.mjs';
+
+async function test() {
+  console.log('Starting test...');
+  const startTime = Date.now();
+  let firstChunkTime = null;
+
+  const cmd = $`echo "immediate"; sleep 0.1; echo "delayed"`;
+  console.log('Command created');
+
+  for await (const chunk of cmd.stream()) {
+    console.log('Got chunk:', chunk.type, `${Date.now() - startTime}ms`);
+    if (chunk.type === 'stdout' && firstChunkTime === null) {
+      firstChunkTime = Date.now();
+      console.log(
+        'First chunk received after',
+        firstChunkTime - startTime,
+        'ms'
+      );
+      break;
+    }
+  }
+
+  console.log('Test done');
+}
+
+test().catch(console.error);

package/js/examples/test-streaming.mjs

@@ -0,0 +1,32 @@
+import { $ } from '../src/$.mjs';
+
+async function testStreaming() {
+  console.log('Testing basic cat with streams.stdin...');
+
+  try {
+    // Test streams.stdin with cat
+    const catCmd = $`cat`;
+    const stdin = await catCmd.streams.stdin;
+
+    console.log('stdin available:', !!stdin);
+    console.log('stdin writable:', stdin ? stdin.writable : 'N/A');
+
+    if (stdin) {
+      stdin.write('Hello from streams.stdin!\n');
+      stdin.write('Multiple lines work\n');
+      stdin.end();
+    }
+
+    const result = await catCmd;
+    console.log('Result code:', result.code);
+    console.log('Result stdout:', JSON.stringify(result.stdout));
+    console.log(
+      'Expected content present:',
+      result.stdout.includes('Hello from streams.stdin!')
+    );
+  } catch (error) {
+    console.error('Error:', error);
+  }
+}
+
+testStreaming().catch(console.error);

package/js/examples/test-streams-stdin-comprehensive.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+
+/**
+ * Test comprehensive streams.stdin functionality including:
+ * - Sending data to stdin
+ * - Using kill() method to interrupt processes
+ * - Testing with commands that actually read stdin
+ */
+
+import { $ } from '../src/$.mjs';
+
+console.log('=== Testing streams.stdin comprehensive functionality ===');
+console.log('');
+
+async function testStreamsStdinComprehensive() {
+  try {
+    console.log('TEST 1: Send data via streams.stdin to cat command');
+
+    const command1 = $`cat`;
+    console.log('✓ Cat command created');
+
+    // Access stdin stream - this should auto-start the command
+    const stdin1 = command1.streams.stdin;
+    console.log('✓ Accessed streams.stdin - command should be started');
+    console.log('  Started?', command1.started);
+
+    // Send some data and close stdin
+    if (stdin1) {
+      stdin1.write('Hello from streams.stdin!\n');
+      stdin1.write('Line 2 from stdin\n');
+      stdin1.write('Final line\n');
+      stdin1.end(); // Close stdin to let cat finish
+    }
+
+    const result1 = await command1;
+    console.log('✓ Cat command completed with exit code:', result1.code);
+    console.log('✓ Output:', JSON.stringify(result1.stdout));
+
+    console.log('');
+    console.log('TEST 2: Use kill() method to interrupt ping command');
+
+    const command2 = $`ping 8.8.8.8`;
+    console.log('✓ Ping command created');
+
+    // Access streams to start the command
+    const streams2 = command2.streams;
+    console.log('✓ Accessed streams - command should be started');
+    console.log('  Started?', command2.started);
+
+    // Wait for ping to start outputting
+    await new Promise((resolve) => setTimeout(resolve, 2000));
+
+    // Kill the command
+    console.log('✓ Killing ping command...');
+    command2.kill();
+
+    const result2 = await command2;
+    console.log('✓ Ping command terminated with exit code:', result2.code);
+    console.log('✓ Output length:', result2.stdout.length);
+
+    console.log('');
+    console.log('TEST 3: Send data to grep command via stdin');
+
+    const command3 = $`grep "hello"`;
+    console.log('✓ Grep command created');
+
+    const stdin3 = command3.streams.stdin;
+    console.log('✓ Accessed streams.stdin for grep command');
+
+    // Send data to grep
+    if (stdin3) {
+      stdin3.write('this is a test line\\n');
+      stdin3.write('hello world\\n');
+      stdin3.write('another test line\\n');
+      stdin3.write('hello again\\n');
+      stdin3.end();
+    }
+
+    const result3 = await command3;
+    console.log('✓ Grep command completed with exit code:', result3.code);
+    console.log('✓ Filtered output:', JSON.stringify(result3.stdout));
+
+    console.log('');
+    console.log('TEST 4: Test stdin with wc command');
+
+    const command4 = $`wc -l`;
+    console.log('✓ Word count command created');
+
+    const stdin4 = command4.streams.stdin;
+    if (stdin4) {
+      stdin4.write('Line 1\\n');
+      stdin4.write('Line 2\\n');
+      stdin4.write('Line 3\\n');
+      stdin4.write('Line 4\\n');
+      stdin4.end();
+    }
+
+    const result4 = await command4;
+    console.log('✓ Word count completed with exit code:', result4.code);
+    console.log('✓ Line count result:', JSON.stringify(result4.stdout.trim()));
+
+    console.log('');
+    console.log(
+      'TEST 5: Test streams.stdin availability immediately after creation'
+    );
+
+    const command5 = $`cat`;
+    console.log('✓ Command5 created');
+    console.log('  Started?', command5.started);
+
+    // Check if stdin is available before auto-start
+    const stdin5 = command5.streams.stdin;
+    console.log('✓ Stdin available?', !!stdin5);
+    console.log('  Started after accessing stdin?', command5.started);
+
+    if (stdin5) {
+      stdin5.write('Testing immediate availability\\n');
+      stdin5.end();
+    }
+
+    const result5 = await command5;
+    console.log('✓ Result:', JSON.stringify(result5.stdout));
+
+    console.log('');
+    console.log('✅ ALL STREAMS.STDIN COMPREHENSIVE TESTS COMPLETED!');
+  } catch (error) {
+    console.log('');
+    console.error('❌ STREAMS.STDIN COMPREHENSIVE TEST FAILED:', error.message);
+    console.error(error.stack);
+    process.exit(1);
+  }
+}
+
+testStreamsStdinComprehensive();