@ix-xs/node-comfort 1.1.31 → 2.0.0

package/types/src/Sys.d.ts

@@ -0,0 +1,269 @@
+/**
+ * Options for `run()` and `exec()`.
+ */
+export type RunOptions = {
+    /**
+     * Where to run the command.
+     */
+    cwd?: string | undefined;
+    /**
+     * Extra environment variables, added to `process.env`.
+     */
+    env?: Record<string, string | undefined> | undefined;
+    /**
+     * Set to `false` to pass only `env`, without `process.env`.
+     */
+    extendEnv?: boolean | undefined;
+    /**
+     * Written to the command's stdin.
+     */
+    input?: string | Buffer<ArrayBufferLike> | undefined;
+    /**
+     * Kill the command after this long, like `"30s"`.
+     */
+    timeout?: string | number | undefined;
+    /**
+     * Kills the command when aborted.
+     */
+    signal?: AbortSignal | undefined;
+    /**
+     * `"inherit"` shows the output live instead of capturing it. Defaults to `"pipe"`.
+     */
+    stdio?: "pipe" | "inherit" | undefined;
+    /**
+     * Called for each line of stdout.
+     */
+    onStdout?: ((line: string) => void) | undefined;
+    /**
+     * Called for each line of stderr.
+     */
+    onStderr?: ((line: string) => void) | undefined;
+    /**
+     * Throw when the exit code isn't 0. Defaults to `true`.
+     */
+    reject?: boolean | undefined;
+    /**
+     * Drop the final newline of the output. Defaults to `true`.
+     */
+    trim?: boolean | undefined;
+};
+/**
+ * A finished command.
+ */
+export type RunResult = {
+    /**
+     * The command line that ran.
+     */
+    command: string;
+    stdout: string;
+    stderr: string;
+    /**
+     * `null` if a signal killed it.
+     */
+    exitCode: number | null;
+    signal: string | null;
+    /**
+     * In milliseconds.
+     */
+    duration: number;
+};
+/**
+ * Options for `onShutdown()`. They apply to all handlers.
+ */
+export type ShutdownOptions = {
+    /**
+     * How long the handlers get before the exit is forced. Defaults to 10 seconds.
+     */
+    timeout?: string | number | undefined;
+    /**
+     * Exit code after a clean shutdown. Defaults to `0`.
+     */
+    exitCode?: number | undefined;
+    /**
+     * Signals that trigger it. Defaults to `SIGINT`, `SIGTERM` and `SIGHUP`.
+     */
+    signals?: NodeJS.Signals[] | undefined;
+};
+/**
+ * Returned by `info()`.
+ */
+export type SystemInfo = {
+    /**
+     * `"win32"`, `"darwin"`, `"linux"`...
+     */
+    platform: NodeJS.Platform;
+    /**
+     * `"x64"`, `"arm64"`...
+     */
+    arch: string;
+    /**
+     * OS release.
+     */
+    release: string;
+    /**
+     * Node.js version.
+     */
+    node: string;
+    /**
+     * Number of logical CPUs.
+     */
+    cpus: number;
+    cpuModel: string;
+    /**
+     * System memory, in bytes.
+     */
+    memory: {
+        total: number;
+        free: number;
+        used: number;
+    };
+    /**
+     * In seconds.
+     */
+    uptime: number;
+    hostname: string;
+    user: string;
+    pid: number;
+    /**
+     * Running in CI.
+     */
+    ci: boolean;
+    /**
+     * Running in a container.
+     */
+    docker: boolean;
+    /**
+     * Running in WSL.
+     */
+    wsl: boolean;
+};
+/**
+ * Runs a program without a shell, so arguments are passed as they are and
+ * user input can't inject anything. Resolves with the output; rejects with
+ * a `ProcessError` if the exit code isn't 0.
+ *
+ * @example
+ * const { stdout } = await sys.run("git", ["log", "-1", "--format=%s"]);
+ * await sys.run("npm", ["install"], { cwd: "./app", stdio: "inherit" });
+ * await sys.run("ffmpeg", ["-i", input, output], { timeout: "5m" });
+ *
+ * @param {string} file A name found in `PATH`, or a path.
+ * @param {string[]} [args=[]]
+ * @param {RunOptions} [options]
+ * @returns {Promise<RunResult>}
+ * @throws {ProcessError} If it can't start, fails (unless `reject: false`) or times out.
+ */
+export function run(file: string, args?: string[], options?: RunOptions): Promise<RunResult>;
+/**
+ * Runs a command line through the shell, so pipes, `&&` and variables
+ * work. Don't build it from untrusted input; use `run()` for that.
+ *
+ * @example
+ * const { stdout } = await sys.exec("git status --short | wc -l");
+ * const { exitCode } = await sys.exec("npm test", { reject: false, stdio: "inherit" });
+ *
+ * @param {string} command
+ * @param {RunOptions} [options]
+ * @returns {Promise<RunResult>}
+ * @throws {ProcessError} If it fails (unless `reject: false`) or times out.
+ */
+export function exec(command: string, options?: RunOptions): Promise<RunResult>;
+/**
+ * Finds an executable in `PATH`, like the `which` command.
+ *
+ * @example
+ * sys.which("git");  // "/usr/bin/git"
+ * sys.which("nope"); // undefined
+ *
+ * @param {string} command
+ * @returns {string | undefined}
+ */
+export function which(command: string): string | undefined;
+/**
+ * Opens a URL, file or folder with the default app.
+ *
+ * @example
+ * sys.open("http://localhost:3000");
+ *
+ * @param {string} target
+ * @returns {boolean} `true` if the opener started.
+ */
+export function open(target: string): boolean;
+/**
+ * Runs cleanup code when the process is asked to stop (Ctrl+C,
+ * `docker stop`, `kill`): close servers, flush logs, disconnect databases.
+ * Handlers run in reverse order, then the process exits. If they take
+ * longer than `timeout`, the exit is forced; a second Ctrl+C exits at once.
+ *
+ * @example
+ * const server = app.listen(3000);
+ * sys.onShutdown(() => new Promise((done) => server.close(done)));
+ * sys.onShutdown(() => db.close());
+ *
+ * @param {() => unknown} handler Can be async.
+ * @param {ShutdownOptions} [options]
+ * @returns {() => void} Removes the handler.
+ */
+export function onShutdown(handler: () => unknown, options?: ShutdownOptions): () => void;
+/**
+ * Are we on Windows?
+ * @returns {boolean}
+ */
+export function isWindows(): boolean;
+/**
+ * Are we on macOS?
+ * @returns {boolean}
+ */
+export function isMac(): boolean;
+/**
+ * Are we on Linux? WSL counts.
+ * @returns {boolean}
+ */
+export function isLinux(): boolean;
+/**
+ * Are we running in CI? Detects GitHub Actions, GitLab, CircleCI, Jenkins,
+ * Azure, Vercel, Netlify and more.
+ *
+ * @example
+ * if (sys.isCI()) nc.setLevel("warn");
+ *
+ * @returns {boolean}
+ */
+export function isCI(): boolean;
+/**
+ * Are we running inside a container?
+ *
+ * @returns {boolean}
+ */
+export function isDocker(): boolean;
+/**
+ * Are we running in WSL?
+ *
+ * @returns {boolean}
+ */
+export function isWSL(): boolean;
+/**
+ * Facts about the machine and the runtime, handy for bug reports.
+ *
+ * @example
+ * console.table(sys.info());
+ *
+ * @returns {SystemInfo}
+ */
+export function info(): SystemInfo;
+/**
+ * Memory used by this process, in bytes.
+ *
+ * @example
+ * nc.num.formatBytes(sys.memory().heapUsed); // "42.1 MB"
+ *
+ * @returns {{ rss: number, heapTotal: number, heapUsed: number, external: number, arrayBuffers: number }}
+ */
+export function memory(): {
+    rss: number;
+    heapTotal: number;
+    heapUsed: number;
+    external: number;
+    arrayBuffers: number;
+};
+//# sourceMappingURL=Sys.d.ts.map

package/types/src/Sys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Sys.d.ts","sourceRoot":"","sources":["../../src/Sys.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;uBAgCqB,MAAM,KAAK,IAAI;;;;uBACf,MAAM,KAAK,IAAI;;;;;;;;;;;;;;;;;aAQtB,MAAM;YACN,MAAM;YACN,MAAM;;;;cACN,MAAM,GAAG,IAAI;YACb,MAAM,GAAG,IAAI;;;;cACb,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;cAcN,MAAM,CAAC,QAAQ;;;;UACf,MAAM;;;;aACN,MAAM;;;;UACN,MAAM;;;;UACN,MAAM;cACN,MAAM;;;;YACN;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE;;;;YAC7C,MAAM;cACN,MAAM;UACN,MAAM;SACN,MAAM;;;;QACN,OAAO;;;;YACP,OAAO;;;;SACP,OAAO;;AA2IrB;;;;;;;;;;;;;;;GAeG;AACH,0BANW,MAAM,SACN,MAAM,EAAE,YACR,UAAU,GACR,OAAO,CAAC,SAAS,CAAC,CAM9B;AAED;;;;;;;;;;;;GAYG;AACH,8BALW,MAAM,YACN,UAAU,GACR,OAAO,CAAC,SAAS,CAAC,CAK9B;AAED;;;;;;;;;GASG;AACH,+BAHW,MAAM,GACJ,MAAM,GAAG,SAAS,CAwB9B;AAED;;;;;;;;GAQG;AACH,6BAHW,MAAM,GACJ,OAAO,CAenB;AASD;;;;;;;;;;;;;;GAcG;AACH,oCAJW,MAAM,OAAO,YACb,eAAe,GACb,MAAM,IAAI,CAyBtB;AA6BD;;;GAGG;AACH,6BAFa,OAAO,CAInB;AAED;;;GAGG;AACH,yBAFa,OAAO,CAInB;AAED;;;GAGG;AACH,2BAFa,OAAO,CAInB;AAED;;;;;;;;GAQG;AACH,wBAFa,OAAO,CAUnB;AAED;;;;GAIG;AACH,4BAFa,OAAO,CAUnB;AAED;;;;GAIG;AACH,yBAFa,OAAO,CAInB;AAED;;;;;;;GAOG;AACH,wBAFa,UAAU,CA0BtB;AAED;;;;;;;GAOG;AACH,0BAFa;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAKxG"}