@alchemy.run/node-utils 0.0.5 → 2.0.0-beta.73

package/src/adapter.ts

@@ -1,94 +0,0 @@
-import fs from "node:fs";
-
-type AnyFs = Record<string, any>;
-type AnyCallback = (err: NodeJS.ErrnoException | null, result?: any) => void;
-type AsyncMethod = (...args: any[]) => void;
-
-function createSyncFs(fs: AnyFs): AnyFs {
-  const methods = ["mkdir", "realpath", "stat", "rmdir", "utimes"] as const;
-  const newFs: AnyFs = { ...fs };
-
-  methods.forEach((method) => {
-    newFs[method] = (...args: any[]) => {
-      const callback = args.pop() as AnyCallback;
-      let ret;
-
-      try {
-        ret = fs[`${method}Sync`](...args);
-      } catch (err) {
-        return callback(err as NodeJS.ErrnoException);
-      }
-
-      callback(null, ret);
-    };
-  });
-
-  return newFs;
-}
-
-// ----------------------------------------------------------
-
-export function toPromise<T = any>(
-  method: AsyncMethod,
-): (...args: any[]) => Promise<T> {
-  return (...args: any[]) =>
-    new Promise<T>((resolve, reject) => {
-      args.push((err: NodeJS.ErrnoException | null, result: T) => {
-        if (err) {
-          reject(err);
-        } else {
-          resolve(result);
-        }
-      });
-
-      method(...args);
-    });
-}
-
-export function toSync<T = any>(method: AsyncMethod): (...args: any[]) => T {
-  return (...args: any[]) => {
-    let err: NodeJS.ErrnoException | null | undefined;
-    let result: T | undefined;
-
-    args.push((_err: NodeJS.ErrnoException | null, _result: T) => {
-      err = _err;
-      result = _result;
-    });
-
-    method(...args);
-
-    if (err) {
-      throw err;
-    }
-
-    return result as T;
-  };
-}
-
-export interface SyncOptions {
-  fs?: AnyFs;
-  retries?: number | { retries?: number };
-  [key: string]: any;
-}
-
-export function toSyncOptions(options?: SyncOptions): SyncOptions {
-  // Shallow clone options because we are going to mutate them
-  const next: SyncOptions = { ...options };
-
-  // Transform fs to use the sync methods instead
-  next.fs = createSyncFs(next.fs || fs);
-
-  // Retries are not allowed because it requires the flow to be sync
-  if (
-    (typeof next.retries === "number" && next.retries > 0) ||
-    (next.retries &&
-      typeof (next.retries as { retries?: number }).retries === "number" &&
-      ((next.retries as { retries?: number }).retries as number) > 0)
-  ) {
-    throw Object.assign(new Error("Cannot use retries with the sync api"), {
-      code: "ESYNC",
-    });
-  }
-
-  return next;
-}

package/src/exit-hook.ts

@@ -1,96 +0,0 @@
-/**
- * Lightweight replacement for the `exit-hook` npm package.
- *
- * The third-party `exit-hook` registers process listeners (`exit`, `SIGINT`,
- * `SIGTERM`, and `message`) that are never removed — even after every
- * callback has been unregistered.  Those dangling listeners are harmless in
- * long-running processes, but in short-lived child processes (e.g. those
- * spawned by `node --test`) they can prevent clean exit by holding refs on
- * handles such as the IPC channel.
- *
- * This module tracks the number of active registrations and removes **all**
- * process listeners once the last registration is unregistered, so they
- * cannot keep the event loop alive after dispose.
- */
-
-const callbacks = new Set<() => void>();
-let registered = false;
-let called = false;
-
-function runCallbacks(): void {
-  if (called) {
-    return;
-  }
-  called = true;
-  for (const callback of callbacks) {
-    callback();
-  }
-}
-
-function onExit(): void {
-  runCallbacks();
-}
-
-function onSignalInt(): void {
-  runCallbacks();
-  // eslint-disable-next-line unicorn/no-process-exit -- intentional: replicate default SIGINT behavior
-  process.exit(128 + 2);
-}
-
-function onSignalTerm(): void {
-  runCallbacks();
-  // eslint-disable-next-line unicorn/no-process-exit -- intentional: replicate default SIGTERM behavior
-  process.exit(128 + 15);
-}
-
-function onMessage(message: unknown): void {
-  if (message === "shutdown") {
-    runCallbacks();
-    // eslint-disable-next-line unicorn/no-process-exit -- intentional: PM2 graceful shutdown
-    process.exit(0);
-  }
-}
-
-function addListeners(): void {
-  registered = true;
-  called = false;
-  process.on("exit", onExit);
-  process.on("SIGINT", onSignalInt);
-  process.on("SIGTERM", onSignalTerm);
-  // Only listen for IPC "shutdown" messages (PM2 support) when the process
-  // actually has an IPC channel.  Even without this guard the listener is
-  // harmless when there is no channel, but being explicit avoids any
-  // accidental ref of a future channel.
-  if (process.send !== undefined) {
-    process.on("message", onMessage);
-  }
-}
-
-function removeListeners(): void {
-  registered = false;
-  process.removeListener("exit", onExit);
-  process.removeListener("SIGINT", onSignalInt);
-  process.removeListener("SIGTERM", onSignalTerm);
-  process.removeListener("message", onMessage);
-}
-
-/**
- * Register a callback to run when the process exits.  Returns a function
- * that unregisters the callback.  When the last callback is unregistered,
- * all underlying process listeners are removed so they cannot keep the
- * event loop alive.
- */
-export function exitHook(callback: () => void): () => void {
-  callbacks.add(callback);
-
-  if (!registered) {
-    addListeners();
-  }
-
-  return () => {
-    callbacks.delete(callback);
-    if (callbacks.size === 0 && registered) {
-      removeListeners();
-    }
-  };
-}

package/src/foreground-child.ts

@@ -1,243 +0,0 @@
-/**
- * Run a child process in the foreground: proxy signals to it, forward stdio,
- * bridge IPC, and exit with the child's code/signal. A watchdog process
- * ensures the child is killed if the parent dies unexpectedly.
- *
- * Adapted from `foreground-child@4.0.3` (© Isaac Z. Schlueter et al.):
- *   https://github.com/tapjs/foreground-child
- * Licensed under the Blue Oak Model License 1.0.0:
- *   https://blueoakcouncil.org/license/1.0.0
- *
- * The behavioral additions on top of upstream are:
- *   1. Optional `stderrFilter` — upstream hardcodes `stdio = [0, 1, 2]`,
- *      which makes intercepting child stderr impossible without forking.
- *      When `stderrFilter` is provided, the child's stderr is piped,
- *      line-buffered, and each line is passed through the filter
- *      (return `false` to drop, `true` to forward).
- *   2. Uses the in-tree {@link exitHook} instead of `signal-exit`, so this
- *      package has no external runtime dependencies.
- *
- * Everything else — signal proxying, the watchdog, IPC bridging, exit-code
- * forwarding — is preserved verbatim from upstream.
- */
-import { type ChildProcess, spawn } from "node:child_process";
-import constants from "node:constants";
-import { exitHook } from "./exit-hook.ts";
-
-type Signal = NodeJS.Signals;
-
-const allSignals = Object.keys(constants).filter(
-  (k) => k.startsWith("SIG") && k !== "SIGPROF" && k !== "SIGKILL",
-) as Signal[];
-
-function proxySignals(child: ChildProcess): () => void {
-  const listeners = new Map<Signal, () => void>();
-  for (const sig of allSignals) {
-    const listener = (): void => {
-      try {
-        child.kill(sig);
-      } catch (_) {}
-    };
-    try {
-      process.on(sig, listener);
-      listeners.set(sig, listener);
-    } catch (_) {}
-  }
-  const unproxy = (): void => {
-    for (const [sig, listener] of listeners) {
-      process.removeListener(sig, listener);
-    }
-  };
-  child.on("exit", unproxy);
-  return unproxy;
-}
-
-const watchdogCode = String.raw`
-const pid = parseInt(process.argv[1], 10)
-process.title = 'node (foreground-child watchdog pid=' + pid + ')'
-if (!isNaN(pid)) {
-  let barked = false
-  const interval = setInterval(() => {}, 60000)
-  const bark = () => {
-    clearInterval(interval)
-    if (barked) return
-    barked = true
-    process.removeListener('SIGHUP', bark)
-    setTimeout(() => {
-      try {
-        process.kill(pid, 'SIGKILL')
-        setTimeout(() => process.exit(), 200)
-      } catch (_) {}
-    }, 500)
-  }
-  process.on('SIGHUP', bark)
-}
-`;
-
-function watchdog(child: ChildProcess): ChildProcess {
-  let dogExited = false;
-  const dog = spawn(process.execPath, ["-e", watchdogCode, String(child.pid)], {
-    stdio: ["ignore", "ignore", "pipe"],
-  });
-  dog.on("exit", () => {
-    dogExited = true;
-  });
-  dog.stderr?.pipe(process.stderr, { end: false });
-  child.on("exit", () => {
-    if (!dogExited) dog.kill("SIGKILL");
-  });
-  process.on("exit", () => {
-    if (!dogExited) dog.kill("SIGKILL");
-  });
-  return dog;
-}
-
-function isPromise<T>(o: unknown): o is Promise<T> {
-  return (
-    !!o &&
-    typeof o === "object" &&
-    typeof (o as { then?: unknown }).then === "function"
-  );
-}
-
-type SyncCleanupResult =
-  | void
-  | undefined
-  | null
-  | boolean
-  | number
-  | string
-  | NodeJS.Signals;
-
-export type CleanupResult = SyncCleanupResult | Promise<SyncCleanupResult>;
-
-export interface ForegroundChildOptions {
-  /**
-   * Line-level filter for the child's stderr. Return `true` to forward the
-   * line to the parent's stderr, `false` to drop it. When omitted, the
-   * child's stderr is inherited directly (no buffering, no filtering).
-   */
-  stderrFilter?: (line: string) => boolean;
-  /**
-   * Called when the child closes. May return:
-   *   - `false` — suppress propagation of the child's exit
-   *   - `number` — override the parent's exit code
-   *   - `string` (a signal name) — kill the parent with that signal
-   *   - `void` / `undefined` — propagate the child's code/signal verbatim
-   * Async (Promise-returning) cleanup is supported.
-   */
-  cleanup?: (
-    code: number | null,
-    signal: NodeJS.Signals | null,
-    extra: { watchdogPid: number | undefined },
-  ) => CleanupResult;
-}
-
-/**
- * Run `program` with `args` as a foreground child of the current process.
- *
- * Signals received by the parent are proxied to the child, the child's stdio
- * is connected to the parent's (with optional stderr filtering via
- * {@link ForegroundChildOptions.stderrFilter}), IPC messages are bridged in
- * both directions, and the parent exits with the child's exit code or
- * signal. A watchdog subprocess ensures the child is force-killed if the
- * parent dies unexpectedly.
- */
-export function foregroundChild(
-  program: string,
-  args: ReadonlyArray<string>,
-  opts: ForegroundChildOptions = {},
-): ChildProcess {
-  const { stderrFilter, cleanup = (): void => {} } = opts;
-
-  const stdio: Array<"pipe" | "ignore" | "inherit" | number> = stderrFilter
-    ? [0, 1, "pipe"]
-    : [0, 1, 2];
-  if (process.send) stdio.push("ipc" as unknown as number);
-
-  const child = spawn(program, args as string[], { stdio });
-
-  if (stderrFilter && child.stderr) {
-    let buf = "";
-    child.stderr.on("data", (chunk: Buffer | string) => {
-      buf += chunk.toString();
-      let nl: number;
-      while ((nl = buf.search(/\r?\n/)) !== -1) {
-        const eol = buf.startsWith("\r\n", nl) ? 2 : 1;
-        const line = buf.slice(0, nl + eol);
-        buf = buf.slice(nl + eol);
-        if (stderrFilter(line)) process.stderr.write(line);
-      }
-    });
-    child.stderr.on("end", () => {
-      if (buf && stderrFilter(buf)) process.stderr.write(buf);
-    });
-  }
-
-  const childHangup = (): void => {
-    try {
-      child.kill("SIGHUP");
-    } catch (_) {
-      child.kill("SIGTERM");
-    }
-  };
-  const removeOnExit = exitHook(childHangup);
-
-  proxySignals(child);
-  const dog = watchdog(child);
-
-  let done = false;
-  dog.on("close", (code, signal) => {
-    if (done) return;
-    child.kill("SIGKILL");
-    throw new Error("foreground-child watchdog process died unexpectedly!", {
-      cause: {
-        pid: dog.pid,
-        code,
-        signal,
-        watchedProcess: { cmd: program, args, pid: child.pid },
-      },
-    });
-  });
-
-  child.on("close", async (code, signal) => {
-    if (done) return;
-    done = true;
-    const result = cleanup(code, signal, { watchdogPid: dog.pid });
-    const res = isPromise<SyncCleanupResult>(result) ? await result : result;
-    removeOnExit();
-    if (res === false) return;
-    let finalCode: number | null = code;
-    let finalSignal: NodeJS.Signals | null = signal;
-    if (typeof res === "string") {
-      finalSignal = res as NodeJS.Signals;
-      finalCode = null;
-    } else if (typeof res === "number") {
-      finalCode = res;
-      finalSignal = null;
-    }
-    if (finalSignal) {
-      setTimeout(() => {}, 2000);
-      try {
-        process.kill(process.pid, finalSignal);
-      } catch (_) {
-        process.kill(process.pid, "SIGTERM");
-      }
-    } else {
-      process.exit(finalCode ?? 0);
-    }
-  });
-
-  if (process.send) {
-    process.removeAllListeners("message");
-    child.on("message", (message, sendHandle) => {
-      process.send?.(message, sendHandle);
-    });
-    process.on("message", (message, sendHandle) => {
-      if (message === null) return;
-      child.send(message, sendHandle);
-    });
-  }
-
-  return child;
-}

package/src/index.ts

@@ -1,5 +0,0 @@
-export * from "./exit-hook.ts";
-export * from "./foreground-child.ts";
-export * from "./ignore.ts";
-export * from "./lockfile-async.ts";
-export * from "./retry.ts";

package/src/lockfile-async.ts

@@ -1,44 +0,0 @@
-import { toPromise, toSync, toSyncOptions } from "./adapter.ts";
-import type {
-  CheckOptions,
-  LockOptions,
-  ReleaseFn,
-  UnlockOptions,
-} from "./lockfile.ts";
-import * as lockfile from "./lockfile.ts";
-
-export type { CheckOptions, LockOptions, ReleaseFn, UnlockOptions };
-
-export async function lock(
-  file: string,
-  options?: LockOptions,
-): Promise<() => Promise<void>> {
-  const release = await toPromise<ReleaseFn>(lockfile.lock)(file, options);
-
-  return toPromise<void>(release);
-}
-
-export function lockSync(file: string, options?: LockOptions): () => void {
-  const release = toSync<ReleaseFn>(lockfile.lock)(
-    file,
-    toSyncOptions(options),
-  );
-
-  return toSync<void>(release);
-}
-
-export function unlock(file: string, options?: UnlockOptions): Promise<void> {
-  return toPromise<void>(lockfile.unlock)(file, options);
-}
-
-export function unlockSync(file: string, options?: UnlockOptions): void {
-  return toSync<void>(lockfile.unlock)(file, toSyncOptions(options));
-}
-
-export function check(file: string, options?: CheckOptions): Promise<boolean> {
-  return toPromise<boolean>(lockfile.check)(file, options);
-}
-
-export function checkSync(file: string, options?: CheckOptions): boolean {
-  return toSync<boolean>(lockfile.check)(file, toSyncOptions(options));
-}