https://github.com/codemonument/deno_puppet_process
A wrapper around the native subcommand execution apis of deno (later: bun, node) to easily automate cli processes from the outside
https://github.com/codemonument/deno_puppet_process
Last synced: about 1 month ago
JSON representation
A wrapper around the native subcommand execution apis of deno (later: bun, node) to easily automate cli processes from the outside
- Host: GitHub
- URL: https://github.com/codemonument/deno_puppet_process
- Owner: codemonument
- License: mit
- Created: 2024-10-18T16:31:33.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-10-22T14:49:48.000Z (over 1 year ago)
- Last Synced: 2025-08-10T00:57:35.515Z (11 months ago)
- Language: TypeScript
- Size: 58.6 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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 {@link PuppetProcess} object, including the command to run
- call {@link PuppetProcess.start} to spawn the command
- send input to the command as Uint8Array or string via {@link PuppetProcess.std_in} WritableStream
- receive output from the command as string via {@link PuppetProcess.std_out}, {@link PuppetProcess.std_err} or {@link PuppetProcess.std_all} ReadableStreams
- for graceful exit: wait for the command to finish via {@link PuppetProcess.waitForExit}
(for example: when sending an `exit` command to a shell)
- for hard exit: kill the long-running command via {@link PuppetProcess.kill}
- Mode 2: One-Shot Command execution (same as Mode 1, but no need to kill the child process):
- Create a {@link PuppetProcess} object, including the command to run
- call {@link PuppetProcess.start} to spawn the command
- receive output from the command as string via {@link PuppetProcess.std_out}, {@link PuppetProcess.std_err} or {@link PuppetProcess.std_all} ReadableStreams
- wait for the command to finish via {@link PuppetProcess.waitForExit}
Example cli: `cat`
## Example - Run a one-shot cli (with Deno)
```typescript
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](https://github.com/codemonument/deno_simple_exec)
---
# Changelog
## 1.0.1 - 2024-10-22
- remove annoying debug log in `PuppetProcess` constructor
## 1.0.0 - 2024-10-22
- first stable release
- add optional `cwd` option to `PuppetProcess` constructor - changes the current working directory of the spawned process
## 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