@sys/process@0.0.317
Built and signed on GitHub Actions
Built and signed on GitHub Actions

latest

sys-repo/sys

Works with

•JSR Score100%•

License

MIT

•

Downloads68/wk

•

Published2 weeks ago (0.0.317)

Tools for working with spawned child processes.

@sys/process

all symbols

default

Examples

Running a short lived shell command (synchronous):

import { Process } from '@sys/process';

const sh = Process.sh('./path/to/cwd');
const res = await sh.run('echo foo');     // ← res.code == 0 (success)

// OR ↓

const args = ['eval', 'console.log("👋 hello world")'];
const res = await Process.invoke({ args });

Running an interactive command with inherited terminal stdio:

import { Process } from '@sys/process';

await Process.inherit({ cmd: 'deno', args: ['task', 'help'] });

Notes:

Process.inherit does not capture stdout/stderr.
silent has no effect for inherit.
FORCE_COLOR defaults to on (override by setting env.FORCE_COLOR).

Spawning a long-running child process (asynchronous):

import { Process } from '@sys/process';

const readySignal = Process.Signal.ready;
const cmd = `
  Deno.serve({ port: 1234 }, () => new Response('👋 hello world'));
  console.info('${Process.Signal.ready}');
`;
const args = ['eval', cmd];
const proc = await Process.spawn({ args, readySignal, silent: true }).whenReady();

await proc.whenReady();

// ...

await proc.dispose();

Variables

Open: t.OpenLib

Open helpers for launching URLs and paths via the OS default handler in a detached child process.

pkg: Pkg

Package metadata.

Process: t.Process.Lib

Host and child process capabilities. https://docs.deno.com/api/deno/~/Deno.Command

process

Variables

Process: t.Process.Lib

Host and child process capabilities. https://docs.deno.com/api/deno/~/Deno.Command

Process: t.Process.Lib

Host and child process capabilities. https://docs.deno.com/api/deno/~/Deno.Command

types

Namespaces

Process

Host and child-process contracts for Process.

Process.Port

Local port inspection contracts.

Process.Terminate

Process termination contracts.

Process.Terminate.Port

Port listener termination contracts.

Type Aliases

OpenCommand = { readonly cmd: string; readonly args: readonly string[]; }

Process command for opening a URL.

args: readonly string[]
No documentation available
cmd: string
No documentation available

OpenInvokeOptions = { readonly silent?: boolean; }

Options for Open.invokeDetached.

silent: boolean
No documentation available

OpenLib = { readonly invokeDetached: (

cwd: t.StringDir,

url: t.StringUrl,

opts?: OpenInvokeOptions

) => void; readonly resolveCommand: (

target: t.StringUrl,

os?: OpenOsInput

) => OpenCommand; }

Open helpers for launching URLs and paths via the OS default handler in a detached process.

invokeDetached: (
cwd: t.StringDir,
url: t.StringUrl,
opts?: OpenInvokeOptions
) => void
Fire-and-forget open of a URL in the default handler.
resolveCommand: (
target: t.StringUrl,
os?: OpenOsInput
) => OpenCommand
Resolve the platform-specific command for opening a URL.

OpenOs = "windows" | "linux" | "darwin"

Supported OS identifiers for command resolution.

OpenOsInput = OpenOs | (string & { })

OS discriminator accepted by Open.resolveCommand.

Process.CaptureArgs = { args: string[]; cmd?: string; cwd?: string; env?: t.Process.Env; signal?: AbortSignal; timeoutMs?: t.Msecs; maxStdoutBytes: number; maxStderrBytes: number; killGraceMs?: t.Msecs; }

Arguments passed to Process.capture.

args: string[]
No documentation available
cmd: string
No documentation available
cwd: string
No documentation available
env: t.Process.Env
No documentation available
killGraceMs: t.Msecs
No documentation available
maxStderrBytes: number
No documentation available
maxStdoutBytes: number
No documentation available
signal: AbortSignal
No documentation available
timeoutMs: t.Msecs
No documentation available

Process.CaptureBaseOutput = { readonly stdout: Uint8Array; readonly stderr: Uint8Array; readonly text: { readonly stdout: string; readonly stderr: string; }; readonly stdoutTruncated: boolean; readonly stderrTruncated: boolean; toString(): string; }

Shared bounded capture output fields.

stderr: Uint8Array
No documentation available
stderrTruncated: boolean
No documentation available
stdout: Uint8Array
No documentation available
stdoutTruncated: boolean
No documentation available
text: { readonly stdout: string; readonly stderr: string; }
No documentation available
toString(): string
No documentation available

Process.CaptureCancelledOutput =

CaptureBaseOutput
& { readonly outcome: "cancelled"; readonly status: Deno.CommandStatus | null; readonly code: number | null; readonly success: false; readonly signal: Deno.Signal | null; readonly termination: CaptureTermination<"cancelled">; }

Capture result for a child process stopped by cancellation.

Process.CaptureExitedOutput =

CaptureBaseOutput
& { readonly outcome: "exited"; readonly status: Deno.CommandStatus; readonly code: number; readonly success: boolean; readonly signal: Deno.Signal | null; readonly termination: CaptureNoTermination; }

Capture result for a child process that exited before timeout/cancellation.

Process.CaptureFailedToStartOutput =

CaptureBaseOutput
& { readonly outcome: "failed-to-start"; readonly status: null; readonly code: null; readonly success: false; readonly signal: null; readonly termination: CaptureNoTermination; readonly error: unknown; }

Capture result for command construction/spawn substrate failures.

Process.CaptureNoTermination = { readonly reason: null; readonly actions: readonly t.Process.Terminate.Action[]; }

Termination metadata for naturally exited capture results.

actions: readonly t.Process.Terminate.Action[]
No documentation available
reason: null
No documentation available

Process.CaptureOutput =

CaptureExitedOutput
| CaptureTimedOutOutput
| CaptureCancelledOutput
| CaptureFailedToStartOutput

Terminal output variants returned by Process.capture.

Process.CaptureTermination<R extends "timeout" | "cancelled"> = { readonly reason: R; readonly actions: readonly t.Process.Terminate.Action[]; }

Termination metadata for timeout/cancellation capture results.

actions: readonly t.Process.Terminate.Action[]
No documentation available
reason: R
No documentation available

Process.CaptureTimedOutOutput =

CaptureBaseOutput
& { readonly outcome: "timed-out"; readonly status: Deno.CommandStatus | null; readonly code: number | null; readonly success: false; readonly signal: Deno.Signal | null; readonly termination: CaptureTermination<"timeout">; }

Capture result for a child process stopped by timeout.

Process.Env = Record<string, string> & { INIT_CWD?: t.StringDir; }

Environment values passed through to a child process.

Process.Event = { readonly source: t.Process.StdStream; readonly data: Uint8Array; toString(): string; }

Event fired when data is emitted by the process.

data: Uint8Array
No documentation available
source: t.Process.StdStream
No documentation available
toString(): string
No documentation available

Process.EventHandler = (e: t.Process.Event) => void

Handles events on a process.

Process.Handle =

t.LifecycleAsync
& { readonly pid: number; readonly $: t.Observable<t.Process.Event>; readonly is: { readonly ready: boolean; }; whenReady(fn?: ReadyHandler): Promise<t.Process.Handle>; onStdOut(fn: t.Process.EventHandler): t.Process.Handle; onStdErr(fn: t.Process.EventHandler): t.Process.Handle; }

The output from the Process.spawn command that represents a running child-process.

Process.InheritOutput = { readonly code: number; readonly success: boolean; readonly signal: Deno.Signal | null; }

Exit status from an inherited-stdio process. NB: stdout/stderr are not captured when stdio is inherited.

code: number
No documentation available
signal: Deno.Signal | null
No documentation available
success: boolean
No documentation available

Process.InvokeArgs = { args: string[]; cmd?: string; cwd?: string; env?: t.Process.Env; silent?: boolean; }

Arguments passed to the Process.invoke method.

args: string[]
No documentation available
cmd: string
No documentation available
cwd: string
No documentation available
env: t.Process.Env
No documentation available
silent: boolean
No documentation available

Process.Lib = { readonly Script: ScriptLib; readonly Signal: { readonly ready: "PROCESS_READY"; }; readonly stdout: Stdout; readonly Port: Port.Lib; readonly Terminate: Terminate.Lib; isRunning(pid: number): boolean; invoke(config: t.Process.InvokeArgs): Promise<t.Process.Output>; capture(config: t.Process.CaptureArgs): Promise<t.Process.CaptureOutput>; inherit(config: t.Process.InvokeArgs): Promise<t.Process.InheritOutput>; invokeDetached(config: t.Process.InvokeArgs): { pid: number; }; spawn(config: t.Process.SpawnArgs): t.Process.Handle; sh(options?: t.Process.ShellOptions): t.Process.Shell; sh(path: t.StringPath): t.Process.Shell; run(

script: string,

opts?: t.Process.ShellOptions

): Promise<t.Process.Output>; }

Host and child process capabilities. https://docs.deno.com/api/deno/~/Deno.Command

Port: Port.Lib
Local port inspection helpers.
Script: ScriptLib
Script helpers for preparing shell template strings.
Signal: { readonly ready: "PROCESS_READY"; }
Shared process signals.
Terminate: Terminate.Lib
Process termination helpers.
capture(config: t.Process.CaptureArgs): Promise<t.Process.CaptureOutput>
Execute a no-shell argv command with bounded stdout/stderr capture.
inherit(config: t.Process.InvokeArgs): Promise<t.Process.InheritOutput>
Execute a command with child stdio inherited from the parent terminal. Useful for interactive tools/prompts.
invoke(config: t.Process.InvokeArgs): Promise<t.Process.Output>
Execute a command on a child process and wait for response.
invokeDetached(config: t.Process.InvokeArgs): { pid: number; }
Execute a command in a fire-and-forget manner, detaching stdio and unref'ing the child so the host process is free to exit immediately.
isRunning(pid: number): boolean
Determine whether an OS process currently accepts signal delivery.
run(
script: string,
opts?: t.Process.ShellOptions
): Promise<t.Process.Output>
Runs a multiline shell script with sane defaults for strictness and output control.
sh(options?: t.Process.ShellOptions): t.Process.Shell
Run an command.
spawn(config: t.Process.SpawnArgs): t.Process.Handle
Spawn a child process to run a -like command and retrieve a streaming handle to monitor and control it.
stdout: Stdout
Canonical host-process stdout capability.

Process.Output = { readonly code: number; readonly success: boolean; readonly signal: Deno.Signal | null; readonly stdout: Uint8Array; readonly stderr: Uint8Array; readonly text: { readonly stdout: string; readonly stderr: string; }; toString(): string; }

Command output with lazy decoded text.

code: number
No documentation available
signal: Deno.Signal | null
No documentation available
stderr: Uint8Array
No documentation available
stdout: Uint8Array
No documentation available
success: boolean
No documentation available
text: { readonly stdout: string; readonly stderr: string; }
No documentation available
toString(): string
No documentation available

Process.Port.Input = number | TargetInput

Port target shorthand or structured target.

Process.Port.Lib = { listeners(input: Input): Promise<readonly Listener[]>; }

Local port inspection helper API.

listeners(input: Input): Promise<readonly Listener[]>
Discover TCP LISTEN sockets matching a local port target.

Process.Port.Listener = { readonly pid: number; readonly protocol: Protocol; readonly port: number; readonly name: string; readonly host?: string; readonly command?: string; }

TCP listener discovered for a local port target.

command: string
No documentation available
host: string
No documentation available
name: string
No documentation available
pid: number
No documentation available
port: number
No documentation available
protocol: Protocol
No documentation available

Process.Port.Protocol = "tcp"

Supported listener protocol for local port inspection.

Process.Port.Target = { readonly port: number; readonly protocol: Protocol; readonly host?: string; }

Normalized local port target.

host: string
No documentation available
port: number
No documentation available
protocol: Protocol
No documentation available

Process.Port.TargetInput = { readonly port: number; readonly host?: string; readonly protocol?: Protocol; }

Structured local port target.

host: string
No documentation available
port: number
No documentation available
protocol: Protocol
No documentation available

Process.ReadyHandler = (e: ReadyHandlerArgs) => void

Handler for the Process.whenReady method.

Process.ReadyHandlerArgs = { readonly pid: number; readonly cmd: string; toString(): string; }

Arguments passed to the Process.whenReady method.

cmd: string
No documentation available
pid: number
No documentation available
toString(): string
No documentation available

Process.ReadySignalFilter = (e: t.Process.Event) => boolean

A function that determines if a process/stdio event is a "ready" signal.

Process.ScriptLib = { t(

strings: TemplateStringsArray,

...values: unknown[]

): string; tight(

strings: TemplateStringsArray,

...values: unknown[]

): string; }

Script helpers for preparing shell template strings.

t(
strings: TemplateStringsArray,
...values: unknown[]
): string
Dedent a template literal. Matches repo-wide Str.dedent.
tight(
strings: TemplateStringsArray,
...values: unknown[]
): string
Dedent and trim all outer blank lines.

Process.Shell = { readonly path: string; run(...args: string[]): Promise<t.Process.Output>; }

A shell command ("sh").

path: string
No documentation available
run(...args: string[]): Promise<t.Process.Output>
No documentation available

Process.ShellOptions = { readonly args?: string[]; readonly silent?: boolean; readonly path?: string; readonly strict?: boolean; }

Options passed to the Process.sh method.

args: string[]
No documentation available
path: string
No documentation available
silent: boolean
No documentation available
strict: boolean
strict (default: true)

Process.SpawnArgs =

t.Process.InvokeArgs
& { until?: t.UntilInput; readySignal?: string | t.Process.ReadySignalFilter; }

Arguments passed to the Process.spawn method.

Process.Stdio = "piped" | "inherit" | "null"

Ways to handle stdin on a spawned child process.

Process.Stdout = { isTerminal(): boolean; write(text: string): void; }

Canonical host-process stdout capability.

isTerminal(): boolean
Determine whether stdout is attached to a terminal.
write(text: string): void
Write complete UTF-8 text synchronously to stdout.

Process.StdStream = "stdout" | "stderr"

Direction of a STDIO stream.

Process.Terminate.Action = { readonly signal: Deno.Signal; readonly ok: boolean; readonly error?: unknown; }

Signal attempt emitted while terminating an arbitrary process id.

error: unknown
No documentation available
ok: boolean
No documentation available
signal: Deno.Signal
No documentation available

Process.Terminate.Lib = { pid(

pid: number,

options?: Options

): Promise<Result>; port(

input: Process.Port.Input,

options?: Options

): Promise<Port.Result>; }

Process termination helper API.

pid(
pid: number,
options?: Options
): Promise<Result>
Terminate an arbitrary process id with bounded graceful escalation.
port(
input: Process.Port.Input,
options?: Options
): Promise<Port.Result>
Terminate TCP listener process ids bound to a local port target.

Process.Terminate.Options = { readonly timeout?: t.Msecs; readonly force?: boolean; }

Options for arbitrary process id termination.

force: boolean
Send SIGKILL immediately instead of attempting SIGTERM first.
timeout: t.Msecs
Grace window after SIGTERM before SIGKILL escalation. Defaults to 1000ms.

Process.Terminate.Port.Result = { readonly target: Process.Port.Target; readonly status: Status; readonly listeners: readonly Process.Port.Listener[]; readonly results: readonly Terminate.Result[]; }

Result from terminating listener process ids for a local port target.

listeners: readonly Process.Port.Listener[]
No documentation available
results: readonly Terminate.Result[]
No documentation available
status: Status
No documentation available
target: Process.Port.Target
No documentation available

Process.Terminate.Port.Status =

"not-listening"
| "terminated"
| "killed"
| "partial"
| "still-running"

Aggregate status for port listener cleanup.

Process.Terminate.Result = { readonly pid: number; readonly status: Status; readonly actions: readonly Action[]; }

Result from arbitrary process id termination.

actions: readonly Action[]
No documentation available
pid: number
No documentation available
status: Status
No documentation available

Process.Terminate.Status = "not-running" | "terminated" | "killed" | "still-running"

Result status for arbitrary process id termination.

Add Package

deno add jsr:@sys/process

Import symbol

import * as process from "@sys/process";

Import directly with a jsr specifier

import * as process from "jsr:@sys/process";

@sys/process@0.0.317Built and signed on GitHub ActionsBuilt and signed on GitHub Actions

Examples

Running a short lived shell command (synchronous):

Running an interactive command with inherited terminal stdio:

Spawning a long-running child process (asynchronous):

Variables

Variables

Namespaces

Type Aliases

Report package

@sys/process@0.0.317
Built and signed on GitHub Actions
Built and signed on GitHub Actions