v0.7.1 (build 925)
Koya home

Module/process

Spawn child processes and execute shell commands with streamed IO.

Spawn child processes and execute shell commands with evented stdout/stderr and exit notifications.

Import #

import * as Process from 'Module/process';

Types #

SpawnOptions
Options passed to spawn().
  • cmd string - Command to execute.
  • args string[] optional - Arguments to pass to the command.
ProcessHandle
Object returned by spawn(). Provides properties and methods to control the child process.
  • pid number - System process ID.
  • id number - Internal handle ID.
  • stdout EventEmitter - Subscribe with stdout.on('data', (chunk: string) => void) / stdout.off('data', cb).
  • stderr EventEmitter - Subscribe with stderr.on('data', (chunk: string) => void) / stderr.off('data', cb).
  • on (event: 'exit', cb: (code: number) => void) => void - Listen for exit events.
  • off (event: 'exit', cb: Function) => void - Remove exit listener.
  • write (data: string) => void - Write to the process stdin.
  • closeStdin () => void - Close the stdin pipe.
  • kill (signal?: number) => void - Send a signal to the process. Defaults to SIGTERM.
ExecResult
Object resolved by exec() on success.
  • stdout string - Standard output.
  • stderr string - Standard error.

Functions #

spawn
Launches a process. Streams stdout/stderr via event handlers.
  • Throws TypeError if options are missing or invalid.
  • Instance methods throw if the handle has been cleaned up.
spawn(options: SpawnOptions): ProcessHandle
exec
Runs a command via sh -c and resolves when it exits.
  • Rejects with { message, code, stdout, stderr } on non-zero exit.
exec(command: string): Promise<ExecResult>
writeFile
Writes data to a file. Automatically detects binary (ArrayBuffer) or text (string) data.
  • Returns true on success, false on failure.
writeFile(path: string, data: ArrayBuffer | string): boolean
writeFileText
Convenience function for writing text files.
  • Returns true on success, false on failure.
writeFileText(path: string, text: string): boolean
mkdir
Creates a directory and any necessary parent directories.
  • Returns true on success, false on failure.
mkdir(path: string): boolean
exists
Checks if a file or directory exists.
exists(path: string): boolean
getEnv
Reads process.env[name]. Returns defaultValue when provided and unset.
getEnv(name: string, defaultValue?: string): string | undefined
env
Returns a snapshot of the compositor process environment variables.
env(): Record<string, string>

Examples #

A comprehensive tour of the process module: streaming output from a long-running child process, running a one-shot shell command, writing text and binary files, creating directories, and reading environment variables.

import * as Process from 'Module/process';
import * as Log from 'Helix/Log';

// Stream lines from `date`
const p = Process.spawn({ cmd: 'sh', args: ['-c', 'while :; do date; sleep 1; done'] });
p.stdout.on('data', (chunk) => {
  for (const line of String(chunk).split('\n')) if (line.length) Log.info(line);
});
p.on('exit', (code) => Log.info('date exited: ' + code));

// One-shot command
const { stdout } = await Process.exec('uname -a');
Log.info(stdout.trim());

// Write a text file
const success = Process.writeFileText('./config.json', JSON.stringify({ theme: 'dark' }));
if (success) {
  Log.info('Config file written');
}

// Write binary data (from HTTP download)
const binaryData = new ArrayBuffer(4);
const view = new Uint8Array(binaryData);
view[0] = 0x89; view[1] = 0x50; view[2] = 0x4E; view[3] = 0x47;
const saved = Process.writeFile('./image.png', binaryData);
if (saved) {
  Log.info('Binary file saved');
}

// Create directory structure
if (!Process.exists('./downloads')) {
  Process.mkdir('./downloads');
  Log.info('Downloads directory created');
}

// Read environment variables
const path = Process.getEnv('PATH', '/usr/bin');
const env = Process.env();
Log.info(`PATH starts with: ${path.split(':')[0]}`);

Notes #

  • Paths/commands execute in the compositor process environment.
  • Use kill() and closeStdin() to control long-running processes.
  • File system operations use C++ standard library for optimal performance.
  • Binary data is handled efficiently without string conversion issues.
  • Directory creation is safe and won't overwrite existing files.
  • All file operations return boolean success indicators for error handling.
<- Module/ffmpegModule/ws ->