Puppet Process

A wrapper around the native subcommand execution apis of deno (later: bun, node) to easily automate cli processes from the outside.

Provides:

• Mode 1: Interactive Command execution

  • Create a PuppetProcess object, including the command to run
  • call PuppetProcess.start to spawn the command
  • send input to the command as Uint8Array or string via PuppetProcess.std_in WritableStream
  • receive output from the command as string via PuppetProcess.std_out, PuppetProcess.std_err or PuppetProcess.std_all ReadableStreams
  • for graceful exit: wait for the command to finish via PuppetProcess.waitForExit (for example: when sending an exit command to a shell)
  • for hard exit: kill the long-running command via PuppetProcess.kill

• Mode 2: One-Shot Command execution (same as Mode 1, but no need to kill the child process):

  • Create a PuppetProcess object, including the command to run
  • call PuppetProcess.start to spawn the command
  • receive output from the command as string via PuppetProcess.std_out, PuppetProcess.std_err or PuppetProcess.std_all ReadableStreams
  • wait for the command to finish via PuppetProcess.waitForExit

Example cli: cat

Example - Run a one-shot cli (with Deno)

import {simpleCallbackTarget} from '@codemonument/rx-webstreams';
import {assertEquals, assertExists, assertRejects} from '@std/assert';
import {PuppetProcess} from '@codemonument/puppet-process/deno';
import {delay} from '@std/async';

const process = new PuppetProcess({
	command: `cat`,
});

process.std_out.pipeTo(
	simpleCallbackTarget(chunk => {
		assertEquals(chunk, 'Hello, world!');
	})
);
const writer = process.std_in.getWriter();
writer.write('Hello, world!');

process.start();

await delay(50);
// close the writer explicitly to avoid dangling stdin stream after child process has finished
await writer.close();

// CAUTION: Some cli-tools, like "cat", will exit when the writer for stdin is closed,
// since this closing sends an EOF signal to the child process!
// SO: we only need to wait for exit here, instead of killing the process.
await process.waitForExit();

Credits

• draw inspiration from deno_simple_exec

Changelog

0.1.2 - 2024-10-21

• add example for @codemonument/puppet-process/errors module

0.1.1 - 2024-10-21

• improved documentation, as suggested by jsr

0.1.0 - 2024-10-21 - initial release

Features:

• creating a puppet process with deno
• sending input to the process
• receiving output from the process
• waiting for the process to finish
• killing the process