@naturalcycles/nodejs-lib 13.31.1 → 13.33.0

package/src/util/exec2.ts

@@ -0,0 +1,326 @@
+import cp from 'node:child_process'
+import {
+  _since,
+  AnyObject,
+  AppError,
+  NumberOfMilliseconds,
+  UnixTimestampMillisNumber,
+} from '@naturalcycles/js-lib'
+import { dimGrey, white } from '../colors/colors'
+
+/**
+ * Set of utility functions to work with Spawn / Exec.
+ *
+ * How to decide between Spawn and Exec?
+ *
+ * Long-running job that prints output, and no need to return the output - use Spawn.
+ *
+ * Short-running job, no need to print the output, might want to return the output - use Exec.
+ *
+ * Need to both print and return the output - use SpawnAsync.
+ *
+ * ***
+ *
+ * Spawn is good for long-running large-output processes, that continuously output data.
+ * E.g running `jest`.
+ *
+ * Exec is the opposite - good for short-running processes that output small data.
+ * Exec allows to return the output as a string.
+ * Exec doesn't stream data during execution, so the output/error will only be printed
+ * at the end.
+ * Exec always uses the shell (there's no option to disable it).
+ */
+class Exec2 {
+  /**
+   * Advanced/async version of Spawn.
+   * Consider simpler `spawn` or `exec` first, which are also sync.
+   *
+   * spawnAsync features:
+   *
+   * 1. Async
+   * 2. Allows to collect the output AND print it while running.
+   * 3. Returns SpawnOutput with stdout, stderr and exitCode.
+   * 4. Allows to not throw on error, but just return SpawnOutput for further inspection.
+   *
+   * Defaults:
+   *
+   * shell: true
+   * printWhileRunning: true
+   * collectOutputWhileRunning: true
+   * throwOnNonZeroCode: true
+   * log: true
+   */
+  async spawnAsync(cmd: string, opt: SpawnAsyncOptions = {}): Promise<SpawnOutput> {
+    const started = Date.now()
+    this.logStart(cmd, opt)
+    const {
+      shell = true,
+      printWhileRunning = true,
+      collectOutputWhileRunning = true,
+      throwOnNonZeroCode = true,
+      cwd,
+      env,
+    } = opt
+    let stdout = ''
+    let stderr = ''
+
+    return await new Promise<SpawnOutput>((resolve, reject) => {
+      const p = cp.spawn(cmd, opt.args || [], {
+        shell,
+        cwd,
+        env,
+        // ...process.env, // not passing by default for security reasons
+      })
+
+      p.stdout.on('data', data => {
+        if (collectOutputWhileRunning) {
+          stdout += data.toString()
+          // console.log('stdout:', data.toString())
+        }
+        if (printWhileRunning) {
+          process.stdout.write(data)
+          // console.log('stderr:', data.toString())
+        }
+      })
+      p.stderr.on('data', data => {
+        if (collectOutputWhileRunning) {
+          stderr += data.toString()
+        }
+        if (printWhileRunning) {
+          process.stderr.write(data)
+        }
+      })
+
+      p.on('close', code => {
+        this.logFinish(cmd, opt, started)
+        const exitCode = code || 0
+        const o: SpawnOutput = {
+          exitCode,
+          stdout: stdout.trim(),
+          stderr: stderr.trim(),
+        }
+        if (throwOnNonZeroCode && code) {
+          return reject(new SpawnError(`spawnAsync exited with code ${code}: ${cmd}`, o))
+        }
+        resolve(o)
+      })
+    })
+  }
+
+  /**
+   * Reasons to use it:
+   * - Sync
+   * - Need to print output while running
+   *
+   * Limitations:
+   * - Cannot return stdout/stderr (use exec or spawnAsync for that)
+   *
+   * Defaults:
+   *
+   * shell: true
+   * log: true
+   */
+  spawn(cmd: string, opt: SpawnOptions = {}): void {
+    const started = Date.now()
+    this.logStart(cmd, opt)
+    const { shell = true, cwd, env } = opt
+
+    const r = cp.spawnSync(cmd, opt.args, {
+      encoding: 'utf8',
+      stdio: 'inherit',
+      shell,
+      cwd,
+      env,
+      // ...process.env, // not passing by default for security reasons
+    })
+
+    this.logFinish(cmd, opt, started)
+
+    if (r.error) {
+      throw r.error
+    }
+    if (r.status) {
+      throw new Error(`spawn exited with code ${r.status}: ${cmd}`)
+    }
+  }
+
+  /**
+   * Reasons to use it:
+   *
+   * - Sync
+   * - Need to return output
+   *
+   * Limitations:
+   * - Cannot print while running (use spawn or spawnAsync for that)
+   *
+   * Defaults:
+   *
+   * shell: true
+   * log: true
+   */
+  exec(cmd: string, opt: ExecOptions = {}): string {
+    const started = Date.now()
+    this.logStart(cmd, opt)
+    const { cwd, env, timeout } = opt
+
+    try {
+      return cp
+        .execSync(cmd, {
+          encoding: 'utf8',
+          // stdio: 'inherit', // no, otherwise we don't get the output returned
+          stdio: undefined,
+          // shell: undefined,
+          cwd,
+          timeout,
+          env,
+          // ...process.env, // not passing by default for security reasons
+        })
+        .trim()
+    } catch (err) {
+      // Not logging stderr, as it's printed by execSync by default (somehow)
+      // stdout is not printed by execSync though, therefor we print it here
+      // if ((err as any).stderr) {
+      //   process.stderr.write((err as any).stderr)
+      // }
+      if ((err as any).stdout) {
+        process.stdout.write((err as any).stdout)
+      }
+      throw new Error(`exec exited with code ${(err as any).status}: ${cmd}`)
+    } finally {
+      this.logFinish(cmd, opt, started)
+    }
+  }
+
+  throwOnNonZeroExitCode(o: SpawnOutput): void {
+    if (o.exitCode) {
+      throw new SpawnError(`spawn exited with code ${o.exitCode}`, o)
+    }
+  }
+
+  private logStart(cmd: string, opt: SpawnOptions | ExecOptions): void {
+    if (!opt.logStart && !opt.log) return
+
+    console.log(
+      [
+        dimGrey(...Object.entries(opt.env || {}).map(([k, v]) => [k, v].join('='))),
+        white(opt.name || cmd),
+        ...((!opt.name && (opt as SpawnOptions).args) || []),
+      ]
+        .filter(Boolean)
+        .join(' '),
+    )
+  }
+
+  private logFinish(
+    cmd: string,
+    opt: SpawnOptions | ExecOptions,
+    started: UnixTimestampMillisNumber,
+  ): void {
+    if (!opt.logFinish && !opt.log) return
+
+    console.log([white(opt.name || cmd), dimGrey('took ' + _since(started))].join(' '))
+  }
+}
+
+export const exec2 = new Exec2()
+
+export class SpawnError extends AppError<SpawnErrorData> {
+  constructor(message: string, data: SpawnErrorData) {
+    super(message, data, { name: 'SpawnError' })
+  }
+}
+
+export interface SpawnErrorData extends SpawnOutput {}
+
+export interface SpawnOutput {
+  /**
+   * Exit code of the spawned process.
+   * 0 means success, anything else means failure.
+   */
+  exitCode: number
+  stdout: string
+  stderr: string
+}
+
+export interface SpawnAsyncOptions extends SpawnOptions {
+  /**
+   * Defaults to true.
+   * If true - prints both stdout and stderr to console while running,
+   * otherwise runs "silently".
+   * Returns SpawnOutput in the same way, regardless of `printWhileRunning` setting.
+   */
+  printWhileRunning?: boolean
+
+  /**
+   * Defaults to true.
+   * If true - collects stdout and stderr while running, and return it in the end.
+   * stdout/stderr are collected and returned regardless if it returns with error or not.
+   * On success - stdout/stderr are available from `SpawnOutput`.
+   * On error - stdout/stderr are available from `SpawnError.data`.
+   */
+  collectOutputWhileRunning?: boolean
+
+  /**
+   * Defaults to true.
+   * If true - throws SpawnError if non-zero code is returned.
+   * SpawnError conveniently contains .data.stdout and .data.strerr for inspection.
+   * If false - will not throw, but return SpawnOutput with stdout, stderr and exitCode.
+   */
+  throwOnNonZeroCode?: boolean
+}
+
+export interface SpawnOptions {
+  args?: string[]
+  /**
+   * Defaults to true.
+   */
+  logStart?: boolean
+  /**
+   * Defaults to true.
+   */
+  logFinish?: boolean
+  /**
+   * Defaults to true.
+   * Controls/overrides both logStart and logFinish simultaneously.
+   */
+  log?: boolean
+  /**
+   * Defaults to true.
+   */
+  shell?: boolean
+
+  /**
+   * If specified - will be used as "command name" for logging purposes,
+   * instead of "cmd + args"
+   */
+  name?: string
+  cwd?: string
+
+  env?: AnyObject
+}
+
+export interface ExecOptions {
+  /**
+   * Defaults to false.
+   */
+  logStart?: boolean
+  /**
+   * Defaults to false.
+   */
+  logFinish?: boolean
+  /**
+   * Defaults to false.
+   * Controls/overrides both logStart and logFinish simultaneously.
+   */
+  log?: boolean
+
+  /**
+   * If specified - will be used as "command name" for logging purposes,
+   * instead of "cmd + args"
+   */
+  name?: string
+  cwd?: string
+  timeout?: NumberOfMilliseconds
+
+  env?: AnyObject
+}

package/src/util/git2.ts

@@ -0,0 +1,105 @@
+import cp from 'node:child_process'
+import path from 'node:path'
+import type { UnixTimestampNumber } from '@naturalcycles/js-lib'
+import { grey } from '../colors/colors'
+import { exec2 } from './exec2'
+
+/**
+ * Set of utility functions to work with git.
+ */
+class Git2 {
+  getLastGitCommitMsg(): string {
+    return exec2.exec('git log -1 --pretty=%B')
+  }
+
+  commitMessageToTitleMessage(msg: string): string {
+    const firstLine = msg.split('\n')[0]!
+    const [preTitle, title] = firstLine.split(': ')
+    return title || preTitle!
+  }
+
+  gitHasUncommittedChanges(): boolean {
+    // git diff-index --quiet HEAD -- || echo "untracked"
+    try {
+      cp.execSync('git diff-index --quiet HEAD --', {
+        encoding: 'utf8',
+      })
+      return false
+    } catch {
+      return true
+    }
+  }
+
+  /**
+   * Returns true if there were changes
+   */
+  gitCommitAll(msg: string): boolean {
+    // git commit -a -m "style(lint-all): $GIT_MSG" || true
+    const cmd = `git commit -a --no-verify -m "${msg}"`
+    // const cmd = `git`
+    // const args = ['commit', '-a', '--no-verify', '-m', msg]
+    console.log(grey(cmd))
+
+    try {
+      cp.execSync(cmd, {
+        stdio: 'inherit',
+      })
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * @returns true if there are not pushed commits.
+   */
+  gitIsAhead(): boolean {
+    // ahead=`git rev-list HEAD --not --remotes | wc -l | awk '{print $1}'`
+    const cmd = `git rev-list HEAD --not --remotes | wc -l | awk '{print $1}'`
+    const stdout = exec2.exec(cmd)
+    // console.log(`gitIsAhead: ${stdout}`)
+    return Number(stdout) > 0
+  }
+
+  gitPull(): void {
+    const cmd = 'git pull'
+    try {
+      cp.execSync(cmd, {
+        stdio: 'inherit',
+      })
+    } catch {}
+  }
+
+  gitPush(): void {
+    // git push --set-upstream origin $CIRCLE_BRANCH && echo "pushed, exiting" && exit 0
+    let cmd = 'git push'
+
+    const branchName = this.gitCurrentBranchName()
+
+    if (branchName) {
+      cmd += ` --set-upstream origin ${branchName}`
+    }
+
+    exec2.spawn(cmd, { logStart: true })
+  }
+
+  gitCurrentCommitSha(full = false): string {
+    const sha = exec2.exec('git rev-parse HEAD')
+    return full ? sha : sha.slice(0, 7)
+  }
+
+  gitCurrentCommitTimestamp(): UnixTimestampNumber {
+    return Number(exec2.exec('git log -1 --format=%ct'))
+  }
+
+  gitCurrentBranchName(): string {
+    return exec2.exec('git rev-parse --abbrev-ref HEAD')
+  }
+
+  gitCurrentRepoName(): string {
+    const originUrl = exec2.exec('git config --get remote.origin.url')
+    return path.basename(originUrl, '.git')
+  }
+}
+
+export const git2 = new Git2()

package/src/validation/joi/number.extensions.ts

@@ -1,4 +1,5 @@
-import Joi, { Extension, NumberSchema as JoiNumberSchema } from 'joi'
+import type Joi from 'joi'
+import { Extension, NumberSchema as JoiNumberSchema } from 'joi'
 
 export interface NumberSchema<TSchema = number> extends JoiNumberSchema<TSchema> {
   dividable: (q: number) => this

package/src/validation/joi/string.extensions.ts

@@ -1,5 +1,6 @@
 import { localTime } from '@naturalcycles/js-lib'
-import Joi, { Extension, StringSchema as JoiStringSchema } from 'joi'
+import type Joi from 'joi'
+import { Extension, StringSchema as JoiStringSchema } from 'joi'
 
 export interface StringSchema<TSchema = string> extends JoiStringSchema<TSchema> {
   dateString: (min?: string, max?: string) => this

package/dist/util/exec.util.d.ts

@@ -1,10 +0,0 @@
-import type { SpawnOptions } from 'node:child_process';
-export interface ExecOptions extends SpawnOptions {
-    /**
-     * Defaults to true.
-     * Set to false to skip logging.
-     */
-    log?: boolean;
-}
-export declare function execVoidCommand(cmd: string, args?: string[], opt?: ExecOptions): Promise<void>;
-export declare function execVoidCommandSync(cmd: string, args?: string[], opt?: ExecOptions): void;

package/dist/util/exec.util.js

@@ -1,58 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.execVoidCommand = execVoidCommand;
-exports.execVoidCommandSync = execVoidCommandSync;
-const tslib_1 = require("tslib");
-const node_child_process_1 = tslib_1.__importDefault(require("node:child_process"));
-async function execVoidCommand(cmd, args = [], opt = {}) {
-    logExec(cmd, args, opt);
-    await new Promise(resolve => {
-        const p = node_child_process_1.default.spawn(cmd, [...args], {
-            stdio: 'inherit',
-            // shell: true,
-            ...opt,
-            env: {
-                ...process.env,
-                ...opt.env,
-            },
-        });
-        p.on('close', code => {
-            if (code) {
-                console.log(`${cmd} exited with code ${code}`);
-                process.exit(code);
-            }
-            resolve();
-        });
-    });
-}
-function execVoidCommandSync(cmd, args = [], opt = {}) {
-    logExec(cmd, args, opt);
-    const r = node_child_process_1.default.spawnSync(cmd, [...args], {
-        encoding: 'utf8',
-        stdio: 'inherit',
-        // shell: true, // removing shell breaks executing `tsc`
-        ...opt,
-        env: {
-            ...process.env,
-            ...opt.env,
-        },
-    });
-    if (r.status) {
-        console.log(`${cmd} exited with code ${r.status}`);
-        process.exit(r.status);
-    }
-    if (r.error) {
-        console.log(r.error);
-        process.exit(r.error.errno || 1);
-    }
-}
-function logExec(cmd, args = [], opt = {}) {
-    if (opt.log === false)
-        return;
-    const cmdline = [
-        ...Object.entries(opt.env || {}).map(([k, v]) => [k, v].join('=')),
-        cmd,
-        ...args,
-    ].join(' ');
-    console.log(cmdline);
-}

package/dist/util/git.util.d.ts

@@ -1,18 +0,0 @@
-import type { UnixTimestampNumber } from '@naturalcycles/js-lib';
-export declare function getLastGitCommitMsg(): string;
-export declare function commitMessageToTitleMessage(msg: string): string;
-export declare function gitHasUncommittedChanges(): boolean;
-/**
- * @returns true if there were changes
- */
-export declare function gitCommitAll(msg: string): boolean;
-/**
- * @returns true if there are not pushed commits.
- */
-export declare function gitIsAhead(): boolean;
-export declare function gitPull(): void;
-export declare function gitPush(): void;
-export declare function gitCurrentCommitSha(full?: boolean): string;
-export declare function gitCurrentCommitTimestamp(): UnixTimestampNumber;
-export declare function gitCurrentBranchName(): string;
-export declare function gitCurrentRepoName(): string;

package/dist/util/git.util.js

@@ -1,109 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getLastGitCommitMsg = getLastGitCommitMsg;
-exports.commitMessageToTitleMessage = commitMessageToTitleMessage;
-exports.gitHasUncommittedChanges = gitHasUncommittedChanges;
-exports.gitCommitAll = gitCommitAll;
-exports.gitIsAhead = gitIsAhead;
-exports.gitPull = gitPull;
-exports.gitPush = gitPush;
-exports.gitCurrentCommitSha = gitCurrentCommitSha;
-exports.gitCurrentCommitTimestamp = gitCurrentCommitTimestamp;
-exports.gitCurrentBranchName = gitCurrentBranchName;
-exports.gitCurrentRepoName = gitCurrentRepoName;
-const tslib_1 = require("tslib");
-const node_child_process_1 = tslib_1.__importDefault(require("node:child_process"));
-const node_path_1 = tslib_1.__importDefault(require("node:path"));
-const colors_1 = require("../colors/colors");
-function getLastGitCommitMsg() {
-    return execSync('git log -1 --pretty=%B');
-}
-function commitMessageToTitleMessage(msg) {
-    const firstLine = msg.split('\n')[0];
-    const [preTitle, title] = firstLine.split(': ');
-    return title || preTitle;
-}
-function gitHasUncommittedChanges() {
-    // git diff-index --quiet HEAD -- || echo "untracked"
-    try {
-        node_child_process_1.default.execSync('git diff-index --quiet HEAD --', {
-            encoding: 'utf8',
-        });
-        return false;
-    }
-    catch {
-        return true;
-    }
-}
-/**
- * @returns true if there were changes
- */
-function gitCommitAll(msg) {
-    // git commit -a -m "style(lint-all): $GIT_MSG" || true
-    const cmd = `git commit -a --no-verify -m "${msg}"`;
-    // const cmd = `git`
-    // const args = ['commit', '-a', '--no-verify', '-m', msg]
-    console.log((0, colors_1.grey)(cmd));
-    try {
-        node_child_process_1.default.execSync(cmd, {
-            stdio: 'inherit',
-        });
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * @returns true if there are not pushed commits.
- */
-function gitIsAhead() {
-    // ahead=`git rev-list HEAD --not --remotes | wc -l | awk '{print $1}'`
-    const cmd = `git rev-list HEAD --not --remotes | wc -l | awk '{print $1}'`;
-    const stdout = execSync(cmd);
-    // console.log(`gitIsAhead: ${stdout}`)
-    return Number(stdout) > 0;
-}
-function gitPull() {
-    const cmd = 'git pull';
-    try {
-        node_child_process_1.default.execSync(cmd, {
-            stdio: 'inherit',
-        });
-    }
-    catch { }
-}
-function gitPush() {
-    // git push --set-upstream origin $CIRCLE_BRANCH && echo "pushed, exiting" && exit 0
-    let cmd = 'git push';
-    const branchName = gitCurrentBranchName();
-    if (branchName) {
-        cmd += ` --set-upstream origin ${branchName}`;
-    }
-    console.log((0, colors_1.grey)(cmd));
-    node_child_process_1.default.execSync(cmd, {
-        stdio: 'inherit',
-    });
-}
-function gitCurrentCommitSha(full = false) {
-    const sha = execSync('git rev-parse HEAD');
-    return full ? sha : sha.slice(0, 7);
-}
-function gitCurrentCommitTimestamp() {
-    return Number(execSync('git log -1 --format=%ct'));
-}
-function gitCurrentBranchName() {
-    return execSync('git rev-parse --abbrev-ref HEAD');
-}
-function gitCurrentRepoName() {
-    const originUrl = execSync('git config --get remote.origin.url');
-    return node_path_1.default.basename(originUrl, '.git');
-}
-function execSync(cmd) {
-    return node_child_process_1.default
-        .execSync(cmd, {
-        encoding: 'utf8',
-        // stdio: 'inherit', // no, otherwise we don't get the output returned
-    })
-        .trim();
-}