@effectionx/process 0.5.0

package/README.md

@@ -0,0 +1,12 @@
+# @effection/process
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Created by Frontside](https://img.shields.io/badge/created%20by-frontside-26abe8.svg)](https://frontside.com)
+[![Chat on Discord](https://img.shields.io/discord/700803887132704931?Label=Discord)](https://discord.gg/Ug5nWH8)
+
+[Effection][Effection] is the structured concurrency toolkit for JavaScript. You
+can find detailed information about using effection to manage system process in
+node in the
+[spawning processes guide](https://frontside.com/effection/docs/guides/processes)
+
+[Effection]: https://frontside.com/effection

package/esm/mod.d.ts

@@ -0,0 +1,3 @@
+export * from "./src/exec.js";
+export { type Daemon, daemon } from "./src/daemon.js";
+//# sourceMappingURL=mod.d.ts.map

package/esm/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC"}

package/esm/mod.js

@@ -0,0 +1,2 @@
+export * from "./src/exec.js";
+export { daemon } from "./src/daemon.js";

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/esm/src/daemon.d.ts

@@ -0,0 +1,11 @@
+import { type Operation } from "effection";
+import { type ExecOptions, type Process } from "./exec.js";
+export interface Daemon extends Operation<void>, Process {
+}
+/**
+ * Start a long-running process, like a web server that run perpetually.
+ * Daemon operations are expected to run forever, and if they exit pre-maturely
+ * before the operation containing them passes out of scope it raises an error.
+ */
+export declare function daemon(command: string, options?: ExecOptions): Operation<Daemon>;
+//# sourceMappingURL=daemon.d.ts.map

package/esm/src/daemon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon.d.ts","sourceRoot":"","sources":["../../src/src/daemon.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAY,MAAM,WAAW,CAAC;AAErD,OAAO,EAGL,KAAK,WAAW,EAEhB,KAAK,OAAO,EACb,MAAM,WAAW,CAAC;AAEnB,MAAM,WAAW,MAAO,SAAQ,SAAS,CAAC,IAAI,CAAC,EAAE,OAAO;CACvD;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CACpB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,WAAgB,GACxB,SAAS,CAAC,MAAM,CAAC,CAanB"}

package/esm/src/daemon.js

@@ -0,0 +1,20 @@
+import { resource } from "effection";
+import { DaemonExitError, exec, } from "./exec.js";
+/**
+ * Start a long-running process, like a web server that run perpetually.
+ * Daemon operations are expected to run forever, and if they exit pre-maturely
+ * before the operation containing them passes out of scope it raises an error.
+ */
+export function daemon(command, options = {}) {
+    return resource(function* (provide) {
+        // TODO: should we be able to terminate the process from here?
+        let process = yield* exec(command, options);
+        yield* provide({
+            *[Symbol.iterator]() {
+                let status = yield* process.join();
+                throw new DaemonExitError(status, command, options);
+            },
+            ...process,
+        });
+    });
+}

package/esm/src/eventemitter.d.ts

@@ -0,0 +1,22 @@
+import type { Operation, Stream } from "effection";
+import type { EventEmitter } from "node:stream";
+/**
+ * Create a {@link Stream} of events from any EventEmitter.
+ *
+ * See the guide on [Streams and Subscriptions](https://frontside.com/effection/docs/collections)
+ * for details on how to use streams.
+ *
+ * @param target - the event target whose events will be streamed
+ * @param name - the name of the event to stream. E.g. "click"
+ * @returns a stream that will see one item for each event
+ */
+export declare function on<T extends unknown[]>(target: EventEmitter | null, eventName: string): Stream<T, never>;
+/**
+ * Create an {@link Operation} that yields the next event to be emitted by an EventEmitter.
+ *
+ * @param target - the event target to be watched
+ * @param name - the name of the event to watch. E.g. "click"
+ * @returns an Operation that yields the next emitted event
+ */
+export declare function once<TArgs extends unknown[] = unknown[]>(source: EventEmitter | null, eventName: string): Operation<TArgs>;
+//# sourceMappingURL=eventemitter.d.ts.map

package/esm/src/eventemitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventemitter.d.ts","sourceRoot":"","sources":["../../src/src/eventemitter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAgB,MAAM,WAAW,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD;;;;;;;;;GASG;AACH,wBAAgB,EAAE,CAChB,CAAC,SAAS,OAAO,EAAE,EACnB,MAAM,EAAE,YAAY,GAAG,IAAI,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,CAkBlE;AAED;;;;;;GAMG;AACH,wBAAgB,IAAI,CAAC,KAAK,SAAS,OAAO,EAAE,GAAG,OAAO,EAAE,EACtD,MAAM,EAAE,YAAY,GAAG,IAAI,EAC3B,SAAS,EAAE,MAAM,GAChB,SAAS,CAAC,KAAK,CAAC,CAWlB"}

package/esm/src/eventemitter.js

@@ -0,0 +1,40 @@
+import { createSignal, resource, withResolvers } from "effection";
+/**
+ * Create a {@link Stream} of events from any EventEmitter.
+ *
+ * See the guide on [Streams and Subscriptions](https://frontside.com/effection/docs/collections)
+ * for details on how to use streams.
+ *
+ * @param target - the event target whose events will be streamed
+ * @param name - the name of the event to stream. E.g. "click"
+ * @returns a stream that will see one item for each event
+ */
+export function on(target, eventName) {
+    return resource(function* (provide) {
+        let signal = createSignal();
+        let listener = (...args) => signal.send(args);
+        target?.on(eventName, listener);
+        try {
+            yield* provide(yield* signal);
+        }
+        finally {
+            target?.off(eventName, listener);
+        }
+    });
+}
+/**
+ * Create an {@link Operation} that yields the next event to be emitted by an EventEmitter.
+ *
+ * @param target - the event target to be watched
+ * @param name - the name of the event to watch. E.g. "click"
+ * @returns an Operation that yields the next emitted event
+ */
+export function once(source, eventName) {
+    const result = withResolvers();
+    let listener = (...args) => {
+        result.resolve(args);
+        source?.off(eventName, listener);
+    };
+    source?.on(eventName, listener);
+    return result.operation;
+}

package/esm/src/exec/api.d.ts

@@ -0,0 +1,70 @@
+import type { Operation } from "effection";
+import type { OutputStream } from "../helpers.js";
+export interface Writable<T> {
+    send(message: T): void;
+}
+/**
+ * The process type is what is returned by the `exec` operation. It has all of
+ * standard io handles, and methods for synchronizing on return.
+ */
+export interface Process extends StdIO {
+    readonly pid: number;
+    /**
+     * Completes once the process has finished regardless of whether it was
+     * successful or not.
+     */
+    join(): Operation<ExitStatus>;
+    /**
+     * Completes once the process has finished successfully. If the process does
+     * not complete successfully, it will raise an ExecError.
+     */
+    expect(): Operation<ExitStatus>;
+}
+export interface ExecOptions {
+    /**
+     * When not using passing the `shell` option all arguments must be passed
+     * as an array.
+     */
+    arguments?: string[];
+    /**
+     * Map of environment variables to use for the process.
+     */
+    env?: Record<string, string>;
+    /**
+     * Create an intermediate shell process; defaults to `false`. Useful if you
+     * need to handle glob expansion or passing environment variables. A truthy value
+     * will use an intermediate shell to interpret the command using the default system shell.
+     * However, if the value is a string, that will be used as the executable path
+     * for the intermediate shell.
+     */
+    shell?: boolean | string;
+    /**
+     * Sets the working directory of the process
+     */
+    cwd?: string;
+}
+export interface StdIO {
+    stdout: OutputStream;
+    stderr: OutputStream;
+    stdin: Writable<string>;
+}
+export interface ExitStatus {
+    /**
+     * exit code
+     * //TODO: is this pertinent on Windows? Do we need an 'OK' flag
+     */
+    code?: number;
+    /**
+     * If the process exited with a signal instead of an exit code, it
+     * is recorded here.
+     */
+    signal?: string;
+}
+export interface ProcessResult extends ExitStatus {
+    stdout: string;
+    stderr: string;
+}
+export interface CreateOSProcess {
+    (command: string, options: ExecOptions): Operation<Process>;
+}
+//# sourceMappingURL=api.d.ts.map

package/esm/src/exec/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../../src/src/exec/api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAGlD,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,IAAI,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,OAAQ,SAAQ,KAAK;IACpC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,IAAI,IAAI,SAAS,CAAC,UAAU,CAAC,CAAC;IAE9B;;;OAGG;IACH,MAAM,IAAI,SAAS,CAAC,UAAU,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IAErB;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE7B;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAEzB;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,KAAK;IACpB,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAc,SAAQ,UAAU;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AACD,MAAM,WAAW,eAAe;IAC9B,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;CAC7D"}

package/esm/src/exec/api.js

@@ -0,0 +1 @@
+export {};

package/esm/src/exec/error.d.ts

@@ -0,0 +1,14 @@
+import type { ExecOptions, ExitStatus } from "./api.js";
+export declare class ExecError extends Error {
+    status: ExitStatus;
+    command: string;
+    options: ExecOptions;
+    constructor(status: ExitStatus, command: string, options: ExecOptions);
+    name: string;
+    get message(): string;
+}
+export declare class DaemonExitError extends ExecError {
+    name: string;
+    get message(): string;
+}
+//# sourceMappingURL=error.d.ts.map

package/esm/src/exec/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../../src/src/exec/error.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAExD,qBAAa,SAAU,SAAQ,KAAK;IAEzB,MAAM,EAAE,UAAU;IAClB,OAAO,EAAE,MAAM;IACf,OAAO,EAAE,WAAW;gBAFpB,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,WAAW;IAKpB,IAAI,SAAe;IAE5B,IAAa,OAAO,IAAI,MAAM,CAgB7B;CACF;AAED,qBAAa,eAAgB,SAAQ,SAAS;IACnC,IAAI,SAAqB;IAElC,IAAa,OAAO,IAAI,MAAM,CAE7B;CACF"}

package/esm/src/exec/error.js

@@ -0,0 +1,54 @@
+export class ExecError extends Error {
+    constructor(status, command, options) {
+        super();
+        Object.defineProperty(this, "status", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: status
+        });
+        Object.defineProperty(this, "command", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: command
+        });
+        Object.defineProperty(this, "options", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: options
+        });
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: "ExecError"
+        });
+    }
+    get message() {
+        let code = this.status.code ? `code: ${this.status.code}` : null;
+        let signal = this.status.signal ? `signal: ${this.status.signal}` : null;
+        let env = `env: ${JSON.stringify(this.options.env || {})}`;
+        let shell = this.options.shell ? `shell: ${this.options.shell}` : null;
+        let cwd = this.options.cwd ? `cwd: ${this.options.cwd}` : null;
+        let command = `$ ${this.command} ${this.options.arguments?.join(" ")}`
+            .trim();
+        return [code, signal, env, shell, cwd, command].filter((item) => !!item)
+            .join("\n");
+    }
+}
+export class DaemonExitError extends ExecError {
+    constructor() {
+        super(...arguments);
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: "DaemonExitError"
+        });
+    }
+    get message() {
+        return `daemon process quit unexpectedly\n${super.message}`;
+    }
+}

package/esm/src/exec/posix.d.ts

@@ -0,0 +1,3 @@
+import type { CreateOSProcess } from "./api.js";
+export declare const createPosixProcess: CreateOSProcess;
+//# sourceMappingURL=posix.d.ts.map

package/esm/src/exec/posix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"posix.d.ts","sourceRoot":"","sources":["../../../src/src/exec/posix.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,eAAe,EAAwB,MAAM,UAAU,CAAC;AAKtE,eAAO,MAAM,kBAAkB,EAAE,eAkHhC,CAAC"}

package/esm/src/exec/posix.js

@@ -0,0 +1,110 @@
+import { spawn as spawnProcess } from "node:child_process";
+import { all, createSignal, Err, Ok, spawn, withResolvers, } from "effection";
+import process from "node:process";
+import { once } from "../eventemitter.js";
+import { useReadable } from "../helpers.js";
+import { ExecError } from "./error.js";
+export const createPosixProcess = function* createPosixProcess(command, options) {
+    let processResult = withResolvers();
+    // Killing all child processes started by this command is surprisingly
+    // tricky. If a process spawns another processes and we kill the parent,
+    // then the child process is NOT automatically killed. Instead we're using
+    // the `detached` option to force the child into its own process group,
+    // which all of its children in turn will inherit. By sending the signal to
+    // `-pid` rather than `pid`, we are sending it to the entire process group
+    // instead. This will send the signal to all processes started by the child
+    // process.
+    //
+    // More information here: https://unix.stackexchange.com/questions/14815/process-descendants
+    let childProcess = spawnProcess(command, options.arguments || [], {
+        detached: true,
+        shell: options.shell,
+        env: options.env,
+        cwd: options.cwd,
+        stdio: "pipe",
+    });
+    let { pid } = childProcess;
+    let io = {
+        stdout: yield* useReadable(childProcess.stdout),
+        stderr: yield* useReadable(childProcess.stderr),
+        stdoutDone: withResolvers(),
+        stderrDone: withResolvers(),
+    };
+    let stdout = createSignal();
+    let stderr = createSignal();
+    yield* spawn(function* () {
+        let next = yield* io.stdout.next();
+        while (!next.done) {
+            stdout.send(next.value);
+            next = yield* io.stdout.next();
+        }
+        stdout.close();
+        io.stdoutDone.resolve();
+    });
+    yield* spawn(function* () {
+        let next = yield* io.stderr.next();
+        while (!next.done) {
+            stderr.send(next.value);
+            next = yield* io.stderr.next();
+        }
+        stderr.close();
+        io.stderrDone.resolve();
+    });
+    yield* spawn(function* trapError() {
+        let [error] = yield* once(childProcess, "error");
+        processResult.resolve(Err(error));
+    });
+    let stdin = {
+        send(data) {
+            childProcess.stdin.write(data);
+        },
+    };
+    yield* spawn(function* () {
+        try {
+            let value = yield* once(childProcess, "close");
+            yield* all([io.stdoutDone.operation, io.stderrDone.operation]);
+            processResult.resolve(Ok(value));
+        }
+        finally {
+            try {
+                if (typeof childProcess.pid === "undefined") {
+                    // deno-lint-ignore no-unsafe-finally
+                    throw new Error("no pid for childProcess");
+                }
+                process.kill(-childProcess.pid, "SIGTERM");
+                yield* all([io.stdoutDone.operation, io.stderrDone.operation]);
+            }
+            catch (_e) {
+                // do nothing, process is probably already dead
+            }
+        }
+    });
+    function* join() {
+        let result = yield* processResult.operation;
+        if (result.ok) {
+            let [code, signal] = result.value;
+            return { command, options, code, signal };
+        }
+        else {
+            throw result.error;
+        }
+    }
+    function* expect() {
+        let status = yield* join();
+        if (status.code != 0) {
+            throw new ExecError(status, command, options);
+        }
+        else {
+            return status;
+        }
+    }
+    // FYI: this function starts a process and returns without blocking
+    return {
+        pid: pid,
+        stdin,
+        stdout,
+        stderr,
+        join,
+        expect,
+    };
+};

package/esm/src/exec/win32.d.ts

@@ -0,0 +1,4 @@
+import type { CreateOSProcess } from "./api.js";
+export declare const createWin32Process: CreateOSProcess;
+export declare const isWin32: () => boolean;
+//# sourceMappingURL=win32.d.ts.map

package/esm/src/exec/win32.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"win32.d.ts","sourceRoot":"","sources":["../../../src/src/exec/win32.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,eAAe,EAAwB,MAAM,UAAU,CAAC;AAkBtE,eAAO,MAAM,kBAAkB,EAAE,eA8KhC,CAAC;AAEF,eAAO,MAAM,OAAO,QAAO,OAAiC,CAAC"}

package/esm/src/exec/win32.js

@@ -0,0 +1,173 @@
+import { platform } from "node:os";
+import { all, createSignal, Err, Ok, race, sleep, spawn, withResolvers, } from "effection";
+// @ts-types="npm:@types/cross-spawn@6.0.6"
+import { spawn as spawnProcess } from "cross-spawn";
+import { ctrlc } from "ctrlc-windows";
+import { once } from "../eventemitter.js";
+import { useReadable } from "../helpers.js";
+import { ExecError } from "./error.js";
+function* killTree(pid) {
+    try {
+        const killer = spawnProcess("cmd.exe", ["/c", "taskkill", "/PID", String(pid), "/T", "/F"], { windowsHide: true, stdio: "ignore" });
+        yield* once(killer, "close");
+    }
+    catch (_) {
+        // best-effort; ignore errors
+    }
+}
+export const createWin32Process = function* createWin32Process(command, options) {
+    let processResult = withResolvers();
+    // Windows-specific process spawning with different options than POSIX
+    let childProcess = spawnProcess(command, options.arguments || [], {
+        // We lose exit information and events if this is detached in windows
+        // and it opens a window in windows+powershell.
+        detached: false,
+        // The `shell` option is passed to `cross-spawn` to control whether a shell is used.
+        // On Windows, `shell: true` is necessary to run command strings, as it uses
+        // `cmd.exe` to parse the command and find executables in the PATH.
+        // Using a boolean `true` was previously disabled, causing ENOENT errors for
+        // commands that were not a direct path to an executable.
+        shell: options.shell || false,
+        // With stdio as pipe, windows gets stuck where neither the child nor the
+        // parent wants to close the stream, so we call it ourselves in the exit event.
+        stdio: "pipe",
+        // Hide the child window so that killing it will not block the parent
+        // with a Terminate Batch Process (Y/n)
+        windowsHide: true,
+        env: options.env,
+        cwd: options.cwd,
+    });
+    let { pid } = childProcess;
+    let io = {
+        stdout: yield* useReadable(childProcess.stdout),
+        stderr: yield* useReadable(childProcess.stderr),
+        stdoutDone: withResolvers(),
+        stderrDone: withResolvers(),
+    };
+    const stdout = createSignal();
+    const stderr = createSignal();
+    yield* spawn(function* () {
+        let next = yield* io.stdout.next();
+        while (!next.done) {
+            stdout.send(next.value);
+            next = yield* io.stdout.next();
+        }
+        stdout.close();
+        io.stdoutDone.resolve();
+    });
+    yield* spawn(function* () {
+        let next = yield* io.stderr.next();
+        while (!next.done) {
+            stderr.send(next.value);
+            next = yield* io.stderr.next();
+        }
+        stderr.close();
+        io.stderrDone.resolve();
+    });
+    yield* spawn(function* trapError() {
+        const [error] = yield* once(childProcess, "error");
+        processResult.resolve(Err(error));
+    });
+    let stdin = {
+        send(data) {
+            childProcess.stdin.write(data);
+        },
+    };
+    yield* spawn(function* () {
+        try {
+            let value = yield* once(childProcess, "close");
+            yield* all([io.stdoutDone.operation, io.stderrDone.operation]);
+            processResult.resolve(Ok(value));
+        }
+        finally {
+            try {
+                // Only try to kill the process if it hasn't exited yet
+                if (childProcess.exitCode === null &&
+                    childProcess.signalCode === null) {
+                    if (typeof childProcess.pid === "undefined") {
+                        // deno-lint-ignore no-unsafe-finally
+                        throw new Error("no pid for childProcess");
+                    }
+                    let stdinStream = childProcess.stdin;
+                    // Try graceful shutdown with ctrlc
+                    try {
+                        ctrlc(childProcess.pid);
+                        if (stdinStream.writable) {
+                            try {
+                                // Terminate batch process (Y/N)
+                                stdinStream.write("Y\n");
+                            }
+                            catch (_err) {
+                                // not much we can do here
+                            }
+                        }
+                    }
+                    catch (_err) {
+                        // ctrlc might fail
+                    }
+                    // Close stdin to allow process to exit cleanly
+                    try {
+                        stdinStream.end();
+                    }
+                    catch (_err) {
+                        // stdin might already be closed
+                    }
+                    // Wait for graceful exit with a timeout
+                    yield* race([processResult.operation, sleep(300)]);
+                    // If process still hasn't exited, escalate
+                    if (childProcess.exitCode === null &&
+                        childProcess.signalCode === null) {
+                        // Try regular kill first
+                        try {
+                            childProcess.kill();
+                        }
+                        catch (_err) {
+                            // process might already be dead
+                        }
+                        // If still alive after kill, force-kill entire process tree
+                        // This is necessary for bash on Windows where ctrlc doesn't work
+                        // and child.kill() only kills the shell, leaving grandchildren alive
+                        if (childProcess.exitCode === null &&
+                            childProcess.signalCode === null) {
+                            yield* killTree(childProcess.pid);
+                        }
+                    }
+                    // Wait for streams to finish
+                    yield* all([io.stdoutDone.operation, io.stderrDone.operation]);
+                }
+            }
+            catch (_e) {
+                // do nothing, process is probably already dead
+            }
+        }
+    });
+    function* join() {
+        let result = yield* processResult.operation;
+        if (result.ok) {
+            let [code, signal] = result.value;
+            return { command, options, code, signal };
+        }
+        else {
+            throw result.error;
+        }
+    }
+    function* expect() {
+        let status = yield* join();
+        if (status.code != 0) {
+            throw new ExecError(status, command, options);
+        }
+        else {
+            return status;
+        }
+    }
+    // FYI: this function starts a process and returns without blocking
+    return {
+        pid: pid,
+        stdin,
+        stdout,
+        stderr,
+        join,
+        expect,
+    };
+};
+export const isWin32 = () => platform() === "win32";

package/esm/src/exec.d.ts

@@ -0,0 +1,16 @@
+import { type Operation } from "effection";
+import type { ExecOptions, Process, ProcessResult } from "./exec/api.js";
+export * from "./exec/api.js";
+export * from "./exec/error.js";
+export interface Exec extends Operation<Process> {
+    join(): Operation<ProcessResult>;
+    expect(): Operation<ProcessResult>;
+}
+/**
+ * Execute `command` with `options`. You should use this operation for processes
+ * that have a finite lifetime and on which you may wish to synchronize on the
+ * exit status. If you want to start a process like a server that spins up and runs
+ * forever, consider using `daemon()`
+ */
+export declare function exec(command: string, options?: ExecOptions): Exec;
+//# sourceMappingURL=exec.d.ts.map

package/esm/src/exec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../../src/src/exec.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,SAAS,EAAS,MAAM,WAAW,CAAC;AAClD,OAAO,KAAK,EAEV,WAAW,EAEX,OAAO,EACP,aAAa,EACd,MAAM,eAAe,CAAC;AAIvB,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAEhC,MAAM,WAAW,IAAK,SAAQ,SAAS,CAAC,OAAO,CAAC;IAC9C,IAAI,IAAI,SAAS,CAAC,aAAa,CAAC,CAAC;IACjC,MAAM,IAAI,SAAS,CAAC,aAAa,CAAC,CAAC;CACpC;AAUD;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,IAAI,CAiErE"}