command-stream 0.8.2 → 0.9.0

package/js/tests/jq.test.mjs

@@ -0,0 +1,318 @@
+import { $ } from '../src/$.mjs';
+import { trace } from '../src/$.utils.mjs';
+import { describe, test, expect } from 'bun:test';
+import './test-helper.mjs'; // Automatically sets up beforeEach/afterEach cleanup
+
+// Platform detection - These tests use Unix shell commands (sh, printf)
+const isWindows = process.platform === 'win32';
+
+// Skip on Windows - uses printf and jq (Unix utilities)
+describe.skipIf(isWindows)('jq streaming tests', () => {
+  test('stream of JSON objects through jq -c', async () => {
+    // Generate a stream of JSON objects using printf
+    const result =
+      await $`printf '{"id":1,"name":"Alice"}\n{"id":2,"name":"Bob"}\n{"id":3,"name":"Charlie"}\n'`.pipe(
+        $`jq -c .`
+      );
+
+    // Each object should be on its own line in compact format
+    const lines = result.stdout.trim().split('\n');
+    expect(lines).toHaveLength(3);
+    expect(lines[0]).toBe('{"id":1,"name":"Alice"}');
+    expect(lines[1]).toBe('{"id":2,"name":"Bob"}');
+    expect(lines[2]).toBe('{"id":3,"name":"Charlie"}');
+  });
+
+  test('stream JSON objects with filtering through jq', async () => {
+    // Generate stream and filter for id > 1
+    const result =
+      await $`printf '{"id":1,"value":10}\n{"id":2,"value":20}\n{"id":3,"value":30}\n'`.pipe(
+        $`jq -c 'select(.id > 1)'`
+      );
+
+    const lines = result.stdout.trim().split('\n');
+    expect(lines).toHaveLength(2);
+    expect(JSON.parse(lines[0])).toEqual({ id: 2, value: 20 });
+    expect(JSON.parse(lines[1])).toEqual({ id: 3, value: 30 });
+  });
+
+  test('generate JSON stream using echo in loop', async () => {
+    // Generate JSON objects using a loop
+    const result =
+      await $`sh -c 'for i in 1 2 3; do echo "{\\"index\\":$i,\\"squared\\":$((i*i))}"; done'`.pipe(
+        $`jq -c .`
+      );
+
+    const lines = result.stdout.trim().split('\n');
+    expect(lines).toHaveLength(3);
+    expect(JSON.parse(lines[0])).toEqual({ index: 1, squared: 1 });
+    expect(JSON.parse(lines[1])).toEqual({ index: 2, squared: 4 });
+    expect(JSON.parse(lines[2])).toEqual({ index: 3, squared: 9 });
+  });
+
+  test('transform JSON stream with jq', async () => {
+    // Generate stream and transform each object
+    const result =
+      await $`printf '{"name":"Alice","age":30}\n{"name":"Bob","age":25}\n'`.pipe(
+        $`jq -c '{user: .name, years: .age}'`
+      );
+
+    const lines = result.stdout.trim().split('\n');
+    expect(lines).toHaveLength(2);
+    expect(JSON.parse(lines[0])).toEqual({ user: 'Alice', years: 30 });
+    expect(JSON.parse(lines[1])).toEqual({ user: 'Bob', years: 25 });
+  });
+
+  test('generate and process array elements as stream', async () => {
+    // Generate an array and convert to stream of objects
+    const result = await $`echo '[{"x":1},{"x":2},{"x":3}]'`.pipe(
+      $`jq -c '.[]'`
+    );
+
+    const lines = result.stdout.trim().split('\n');
+    expect(lines).toHaveLength(3);
+    expect(lines[0]).toBe('{"x":1}');
+    expect(lines[1]).toBe('{"x":2}');
+    expect(lines[2]).toBe('{"x":3}');
+  });
+
+  test('combine multiple JSON sources into stream', async () => {
+    // Combine multiple echo commands into a single stream
+    const result =
+      await $`sh -c 'echo "{\\"source\\":\\"A\\",\\"data\\":100}"; echo "{\\"source\\":\\"B\\",\\"data\\":200}"'`.pipe(
+        $`jq -c .`
+      );
+
+    const lines = result.stdout.trim().split('\n');
+    expect(lines).toHaveLength(2);
+    expect(JSON.parse(lines[0])).toEqual({ source: 'A', data: 100 });
+    expect(JSON.parse(lines[1])).toEqual({ source: 'B', data: 200 });
+  });
+});
+
+// Skip on Windows - uses printf and jq (Unix utilities)
+describe.skipIf(isWindows)('jq streaming with pipe | syntax', () => {
+  test('stream of JSON objects through jq -c using pipe syntax', async () => {
+    // Generate a stream of JSON objects using printf with pipe syntax
+    const result =
+      await $`printf '{"id":1,"name":"Alice"}\n{"id":2,"name":"Bob"}\n{"id":3,"name":"Charlie"}\n' | jq -c .`;
+
+    // Each object should be on its own line in compact format
+    const lines = result.stdout.trim().split('\n');
+    expect(lines).toHaveLength(3);
+    expect(lines[0]).toBe('{"id":1,"name":"Alice"}');
+    expect(lines[1]).toBe('{"id":2,"name":"Bob"}');
+    expect(lines[2]).toBe('{"id":3,"name":"Charlie"}');
+  });
+
+  test('stream JSON with filtering using pipe syntax', async () => {
+    // Generate stream and filter for value > 15
+    const result =
+      await $`printf '{"id":1,"value":10}\n{"id":2,"value":20}\n{"id":3,"value":30}\n' | jq -c 'select(.value > 15)'`;
+
+    const lines = result.stdout.trim().split('\n');
+    expect(lines).toHaveLength(2);
+    expect(JSON.parse(lines[0])).toEqual({ id: 2, value: 20 });
+    expect(JSON.parse(lines[1])).toEqual({ id: 3, value: 30 });
+  });
+
+  test('transform JSON stream with jq using pipe syntax', async () => {
+    // Generate stream and transform each object
+    const result =
+      await $`printf '{"name":"Alice","age":30}\n{"name":"Bob","age":25}\n' | jq -c '{user: .name, years: .age}'`;
+
+    const lines = result.stdout.trim().split('\n');
+    expect(lines).toHaveLength(2);
+    expect(JSON.parse(lines[0])).toEqual({ user: 'Alice', years: 30 });
+    expect(JSON.parse(lines[1])).toEqual({ user: 'Bob', years: 25 });
+  });
+
+  test('process array elements as stream using pipe syntax', async () => {
+    // Generate an array and convert to stream of objects
+    const result = await $`echo '[{"x":1},{"x":2},{"x":3}]' | jq -c '.[]'`;
+
+    const lines = result.stdout.trim().split('\n');
+    expect(lines).toHaveLength(3);
+    expect(lines[0]).toBe('{"x":1}');
+    expect(lines[1]).toBe('{"x":2}');
+    expect(lines[2]).toBe('{"x":3}');
+  });
+
+  test('multi-pipe JSON processing', async () => {
+    // Use multiple pipes to process JSON
+    const result =
+      await $`echo '[{"name":"alice","score":95},{"name":"bob","score":87},{"name":"charlie","score":92}]' | jq -c '.[]' | jq -c 'select(.score > 90)'`;
+
+    const lines = result.stdout.trim().split('\n');
+    expect(lines).toHaveLength(2);
+    expect(JSON.parse(lines[0])).toEqual({ name: 'alice', score: 95 });
+    expect(JSON.parse(lines[1])).toEqual({ name: 'charlie', score: 92 });
+  });
+
+  test('complex JSON stream manipulation with pipes', async () => {
+    // Multiple transformations in a pipeline
+    const result =
+      await $`printf '{"user":"alice","points":100}\n{"user":"bob","points":150}\n{"user":"charlie","points":75}\n' | jq -c 'select(.points >= 100)' | jq -c '{name: .user, level: (if .points >= 150 then "gold" else "silver" end)}'`;
+
+    const lines = result.stdout.trim().split('\n');
+    expect(lines).toHaveLength(2);
+    expect(JSON.parse(lines[0])).toEqual({ name: 'alice', level: 'silver' });
+    expect(JSON.parse(lines[1])).toEqual({ name: 'bob', level: 'gold' });
+  });
+});
+
+// Skip on Windows - uses sh -c and Unix utilities
+describe.skipIf(isWindows)('realtime JSON streaming with delays', () => {
+  test('stream JSON with random delays between outputs', async () => {
+    // Simulate realtime stream with random delays between 0.01 and 0.05 seconds
+    const result =
+      await $`sh -c 'for i in 1 2 3 4 5; do echo "{\\"timestamp\\":$(date +%s),\\"event\\":\\"event$i\\",\\"value\\":$((i * 10))}"; sleep 0.0$((RANDOM % 5 + 1)); done' | jq -c .`;
+
+    const lines = result.stdout.trim().split('\n');
+    expect(lines).toHaveLength(5);
+
+    // Verify each JSON object is valid and has expected structure
+    for (let i = 0; i < 5; i++) {
+      const obj = JSON.parse(lines[i]);
+      expect(obj).toHaveProperty('timestamp');
+      expect(obj).toHaveProperty('event');
+      expect(obj).toHaveProperty('value');
+      expect(obj.event).toBe(`event${i + 1}`);
+      expect(obj.value).toBe((i + 1) * 10);
+    }
+  });
+
+  test('stream JSON with fixed delays using printf and sleep', async () => {
+    // Use printf and sleep to simulate delayed streaming
+    const result =
+      await $`sh -c 'for i in 1 2 3; do printf "{\\"id\\":%d,\\"time\\":\\"now\\"}\\n" $i; sleep 0.01; done' | jq -c .`;
+
+    const lines = result.stdout.trim().split('\n');
+    expect(lines).toHaveLength(3);
+    expect(JSON.parse(lines[0])).toEqual({ id: 1, time: 'now' });
+    expect(JSON.parse(lines[1])).toEqual({ id: 2, time: 'now' });
+    expect(JSON.parse(lines[2])).toEqual({ id: 3, time: 'now' });
+  });
+
+  test('simulate server logs with delayed JSON output', async () => {
+    // Simulate server logs that arrive at different intervals
+    const result =
+      await $`sh -c 'echo "{\\"level\\":\\"info\\",\\"msg\\":\\"Server starting\\",\\"port\\":3000}"; sleep 0.02; echo "{\\"level\\":\\"debug\\",\\"msg\\":\\"Database connected\\",\\"host\\":\\"localhost\\"}"; sleep 0.03; echo "{\\"level\\":\\"info\\",\\"msg\\":\\"Server ready\\",\\"status\\":\\"listening\\"}"; sleep 0.01; echo "{\\"level\\":\\"warn\\",\\"msg\\":\\"High memory usage\\",\\"usage\\":85}"' | jq -c 'select(.level != "debug")'`;
+
+    const lines = result.stdout.trim().split('\n');
+    expect(lines).toHaveLength(3); // Should filter out debug message
+
+    const logs = lines.map((line) => JSON.parse(line));
+    expect(logs[0]).toMatchObject({ level: 'info', msg: 'Server starting' });
+    expect(logs[1]).toMatchObject({ level: 'info', msg: 'Server ready' });
+    expect(logs[2]).toMatchObject({ level: 'warn', msg: 'High memory usage' });
+  });
+
+  test('process streaming metrics with delays and aggregation', async () => {
+    // Simulate streaming metrics that arrive over time
+    const result =
+      await $`sh -c 'for i in 1 2 3 4 5; do echo "{\\"metric\\":\\"cpu\\",\\"value\\":$((50 + i * 5)),\\"host\\":\\"server$i\\"}"; sleep 0.015; done' | jq -c 'select(.value > 60)'`;
+
+    const lines = result.stdout.trim().split('\n');
+    expect(lines).toHaveLength(3); // Only values > 60 (65, 70, 75)
+
+    const metrics = lines.map((line) => JSON.parse(line));
+    expect(metrics[0].value).toBe(65);
+    expect(metrics[1].value).toBe(70);
+    expect(metrics[2].value).toBe(75);
+  });
+
+  test('handle burst then delay pattern', async () => {
+    // Simulate burst of messages followed by delays
+    const result =
+      await $`sh -c 'echo "{\\"batch\\":1,\\"msg\\":\\"burst1\\"}"; echo "{\\"batch\\":1,\\"msg\\":\\"burst2\\"}"; echo "{\\"batch\\":1,\\"msg\\":\\"burst3\\"}"; sleep 0.05; echo "{\\"batch\\":2,\\"msg\\":\\"burst4\\"}"; echo "{\\"batch\\":2,\\"msg\\":\\"burst5\\"}"' | jq -c .`;
+
+    const lines = result.stdout.trim().split('\n');
+    expect(lines).toHaveLength(5);
+
+    const messages = lines.map((line) => JSON.parse(line));
+    expect(messages.filter((m) => m.batch === 1)).toHaveLength(3);
+    expect(messages.filter((m) => m.batch === 2)).toHaveLength(2);
+  });
+
+  test('stream with varying delay intervals', async () => {
+    // Different delay patterns to test buffering
+    const result =
+      await $`sh -c 'echo "{\\"seq\\":1,\\"delay\\":\\"none\\"}"; sleep 0.001; echo "{\\"seq\\":2,\\"delay\\":\\"1ms\\"}"; sleep 0.01; echo "{\\"seq\\":3,\\"delay\\":\\"10ms\\"}"; sleep 0.02; echo "{\\"seq\\":4,\\"delay\\":\\"20ms\\"}"; sleep 0.005; echo "{\\"seq\\":5,\\"delay\\":\\"5ms\\"}"' | jq -c '{id: .seq, type: .delay}'`;
+
+    const lines = result.stdout.trim().split('\n');
+    expect(lines).toHaveLength(5);
+
+    // Verify transformation was applied correctly despite delays
+    for (let i = 0; i < 5; i++) {
+      const obj = JSON.parse(lines[i]);
+      expect(obj).toHaveProperty('id');
+      expect(obj).toHaveProperty('type');
+      expect(obj.id).toBe(i + 1);
+    }
+  });
+
+  test('verify immediate streaming output from jq', async () => {
+    // Test that jq outputs each object immediately as it arrives
+    const startTime = Date.now();
+    const timestamps = [];
+
+    // Create a command that outputs JSON with significant delays
+    const cmd = $`sh -c 'echo "{\\"id\\":1}"; sleep 0.2; echo "{\\"id\\":2}"; sleep 0.2; echo "{\\"id\\":3}"' | jq -c .`;
+
+    // Use streaming to capture output as it arrives
+    const chunks = [];
+    let iterations = 0;
+    const maxIterations = 10; // Prevent infinite loop
+
+    try {
+      for await (const chunk of cmd.stream()) {
+        iterations++;
+        if (iterations > maxIterations) {
+          cmd.kill();
+          break;
+        }
+
+        if (chunk.type === 'stdout') {
+          const now = Date.now();
+          timestamps.push(now - startTime);
+          chunks.push(chunk.data.toString());
+        }
+      }
+    } catch (error) {
+      // If streaming fails, just skip the test
+      trace(
+        'JqTest',
+        () => `Streaming test failed, skipping: ${error.message}`
+      );
+      return;
+    }
+
+    // We should have received chunks at different times, not all at once
+    expect(chunks.length).toBeGreaterThan(0);
+
+    // Check if we got output in realtime (with some delays between)
+    // The timestamps should show delays if streaming is working properly
+    if (timestamps.length >= 3) {
+      // Allow for some variance but expect delays
+      const delay1 = timestamps[1] - timestamps[0];
+      const delay2 = timestamps[2] - timestamps[1];
+
+      // At least one of the delays should be significant (>100ms)
+      // showing that output came as it was produced
+      expect(Math.max(delay1, delay2)).toBeGreaterThan(100);
+    }
+
+    // Verify we got all the JSON objects
+    const output = chunks.join('');
+    const lines = output
+      .trim()
+      .split('\n')
+      .filter((l) => l.trim());
+    if (lines.length === 3) {
+      expect(JSON.parse(lines[0])).toEqual({ id: 1 });
+      expect(JSON.parse(lines[1])).toEqual({ id: 2 });
+      expect(JSON.parse(lines[2])).toEqual({ id: 3 });
+    }
+  }, 4000); // Set a shorter timeout for this test
+});

package/js/tests/options-examples.test.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+
+import { test, expect, describe } from 'bun:test';
+import { isWindows } from './test-helper.mjs'; // Automatically sets up beforeEach/afterEach cleanup
+import { $ } from '../src/$.mjs';
+
+describe('Options Examples (Feature Demo)', () => {
+  test('example: disable capture for performance', async () => {
+    // When you don't need the output stored in memory
+    const result = await $`echo "performance optimization"`.start({
+      capture: false,
+    });
+
+    // Output goes to console but not stored in result
+    expect(result.stdout).toBeUndefined();
+    expect(result.code).toBe(0);
+  });
+
+  test('example: disable mirroring for silent execution', async () => {
+    // When you want to capture output but not show it on console
+    const result = await $`echo "silent execution"`.start({ mirror: false });
+
+    // Output is captured but not shown on console
+    expect(result.stdout).toBe('silent execution\n');
+    expect(result.code).toBe(0);
+  });
+
+  test('example: both disabled for maximum performance', async () => {
+    // When you just want to run a command and check exit code
+    const result = await $`echo "max performance"`.start({
+      capture: false,
+      mirror: false,
+    });
+
+    expect(result.stdout).toBeUndefined();
+    expect(result.code).toBe(0);
+  });
+
+  test('example: custom stdin with options', async () => {
+    // Pass custom input and configure output behavior
+    const result = await $`cat`.start({
+      stdin: 'Hello from stdin!',
+      mirror: false, // Don't show on console
+      capture: true, // But do capture the result
+    });
+
+    expect(result.stdout).toBe('Hello from stdin!');
+    expect(result.code).toBe(0);
+  });
+
+  test('example: using .run() alias', async () => {
+    // .run() works exactly like .start()
+    const result1 = await $`echo "using run method"`.run({ capture: false });
+    const result2 = await $`echo "using start method"`.start({
+      capture: false,
+    });
+
+    expect(result1.stdout).toBeUndefined();
+    expect(result2.stdout).toBeUndefined();
+    expect(result1.code).toBe(0);
+    expect(result2.code).toBe(0);
+  });
+
+  test('example: comparison with sh() function', async () => {
+    // Before: had to use sh() function for options
+    // const result = await sh('echo "with sh function"', { mirror: false });
+
+    // Now: can use template literal syntax with options
+    const result = await $`echo "with template literal"`.start({
+      mirror: false,
+    });
+
+    expect(result.stdout).toBe('with template literal\n');
+    expect(result.code).toBe(0);
+  });
+
+  // Skip on Windows - uses 'ls /tmp' which is Unix-specific
+  test.skipIf(isWindows)(
+    'example: real shell command vs virtual command',
+    async () => {
+      // Both work the same way
+      const virtualResult = await $`echo "virtual command"`.start({
+        capture: false,
+      });
+      const realResult = await $`ls /tmp`.start({ capture: false });
+
+      expect(virtualResult.stdout).toBeUndefined();
+      expect(realResult.stdout).toBeUndefined();
+      expect(virtualResult.code).toBe(0);
+      expect(realResult.code).toBe(0);
+    }
+  );
+
+  test('example: chaining still works', async () => {
+    // You can still use all other methods after .start() or .run()
+    const runner = $`echo "chainable"`;
+    const result = await runner.start({ mirror: false });
+
+    expect(result.stdout).toBe('chainable\n');
+    expect(result.code).toBe(0);
+
+    // The result object has the standard properties
+    expect(result).toHaveProperty('stderr');
+    expect(result).toHaveProperty('stdin');
+  });
+});

package/js/tests/options-syntax.test.mjs

@@ -0,0 +1,112 @@
+import { describe, it, expect } from 'bun:test';
+import './test-helper.mjs'; // Automatically sets up beforeEach/afterEach cleanup
+import { $ } from '../src/$.mjs';
+
+describe('$({ options }) syntax', () => {
+  it('should support $({ options }) syntax for custom options', async () => {
+    // Test with stdin option
+    const $withStdin = $({ stdin: 'test input\n' });
+    const result1 = await $withStdin`cat`;
+    expect(result1.stdout).toBe('test input\n');
+    expect(result1.code).toBe(0);
+  });
+
+  it('should support capture and mirror options', async () => {
+    // Test with capture: false
+    const $noCapture = $({ capture: false });
+    const result = await $noCapture`echo "test"`;
+    expect(result.stdout).toBeUndefined();
+    expect(result.code).toBe(0);
+  });
+
+  it('should support multiple options at once', async () => {
+    // Test with multiple options
+    const $custom = $({
+      stdin: 'hello world',
+      capture: true,
+      mirror: false,
+    });
+    const result = await $custom`cat`;
+    expect(result.stdout).toBe('hello world');
+    expect(result.code).toBe(0);
+  });
+
+  it('should work with environment variables', async () => {
+    // Test with custom environment
+    const $withEnv = $({
+      env: { ...process.env, TEST_VAR: 'custom_value' },
+    });
+    const result = await $withEnv`printenv TEST_VAR`;
+    expect(result.stdout.trim()).toBe('custom_value');
+  });
+
+  it('should work with custom working directory', async () => {
+    // Test with custom cwd
+    const $withCwd = $({ cwd: '/tmp' });
+    const result = await $withCwd`pwd`;
+    expect(result.stdout.trim()).toBe('/tmp');
+  });
+
+  it('should be reusable for multiple commands', async () => {
+    // Create a reusable $ with options
+    const $silent = $({ mirror: false, capture: true });
+
+    const result1 = await $silent`echo "first"`;
+    expect(result1.stdout.trim()).toBe('first');
+
+    const result2 = await $silent`echo "second"`;
+    expect(result2.stdout.trim()).toBe('second');
+
+    const result3 = await $silent`echo "third"`;
+    expect(result3.stdout.trim()).toBe('third');
+  });
+
+  it('should work alongside regular $ usage', async () => {
+    // Mix regular and options syntax
+    const regular = await $`echo "regular"`;
+    expect(regular.stdout.trim()).toBe('regular');
+
+    const withOptions = await $({ mirror: false })`echo "with options"`;
+    expect(withOptions.stdout.trim()).toBe('with options');
+
+    const regular2 = await $`echo "regular again"`;
+    expect(regular2.stdout.trim()).toBe('regular again');
+  });
+
+  it('should handle stdin as ignore', async () => {
+    const $noStdin = $({ stdin: 'ignore' });
+    const result = await $noStdin`echo "test"`;
+    expect(result.stdout.trim()).toBe('test');
+    expect(result.code).toBe(0);
+  });
+
+  it('should handle stdin as inherit (default)', async () => {
+    const $inheritStdin = $({ stdin: 'inherit' });
+    const result = await $inheritStdin`echo "test"`;
+    expect(result.stdout.trim()).toBe('test');
+    expect(result.code).toBe(0);
+  });
+
+  it('should work with interpolation', async () => {
+    const name = 'World';
+    const $custom = $({ capture: true, mirror: false });
+    const result = await $custom`echo Hello, ${name}!`;
+    // Interpolation should apply quoting, but the final output depends on whether
+    // virtual or real echo is used. Both behaviors are acceptable.
+    const expected = ["Hello, 'World'!", 'Hello, World!'];
+    expect(expected).toContain(result.stdout.trim());
+  });
+
+  it('should work with command chaining', async () => {
+    const $silent = $({ mirror: false });
+    const result = await $silent`echo "test" | tr 'a-z' 'A-Z'`;
+    expect(result.stdout.trim()).toBe('TEST');
+  });
+
+  it('should handle errors with custom options', async () => {
+    const $custom = $({ capture: true, mirror: false });
+    const result = await $custom`ls /nonexistent-path-${Date.now()}`;
+    expect(result.code).toBeGreaterThan(0);
+    expect(result.stderr).toContain('No such file or directory');
+  });
+});