nc.utils

nc.utils.wait()

wait(duration: string | number, options?: WaitOptions): Promise<void>

Resolves after a delay, given in milliseconds or as a duration string.

Returns Promise<void>

Throws AbortError If the signal is aborted.; TypeError If the duration can't be parsed.

Example

await nc.wait(500);
await nc.wait("2s");
await nc.wait("1m", { signal: controller.signal });

nc.utils.when()

when(predicate: boolean | PromiseLike<boolean> | (() => unknown), payload?: any, options?: WhenOptions): WhenTask

Checks a condition at a regular interval and tells you when it's true. Call .start() once your listeners are in place. If you just want to await a condition, nc.async.poll() is simpler.

Returns WhenTask

Example

nc.when(() => queue.length > 0, { reason: "jobs waiting" }, { interval: 500, max: 1, timeout: 10_000 })
  .on("trigger", (payload) => nc.info(payload.reason))
  .on("timeout", () => nc.warn("Nothing happened in 10s"))
  .start();

nc.utils.dontCrash()

dontCrash(): DontCrashController

Keeps the process alive when something goes wrong. Uncaught exceptions and unhandled rejections are logged instead of crashing, and SIGINT/SIGTERM are logged before a clean exit. Customize any of it with .on().

Only its own handlers are ever removed; listeners added by your code or by other libraries are left alone.

Returns DontCrashController

Example

nc.dontCrash()
  .on("error", (error) => sentry.captureException(error))
  .on("sig", async () => {
    await server.close();
    process.exit(0);
  });

nc.utils.JSONString()

JSONString(value: unknown, spaces?: number): string

JSON.stringify that never throws. Circular references become "[Circular]", bigints become strings, Maps become objects and Sets become arrays.

Returns string: The JSON text, or "undefined" for values JSON can't represent.

Example

nc.JSONString({ a: 1 });                          // '{\n    "a": 1\n}'
nc.JSONString({ id: 10n, tags: new Set(["x"]) }, 0); // '{"id":"10","tags":["x"]}'

nc.utils.JSONParse()

JSONParse<T = any>(text: string, fallback?: T, ...args: any[]): T

JSON.parse with an optional fallback. With a fallback, invalid input returns it instead of throwing.

Returns T

Throws SyntaxError If text is invalid and there's no fallback.

Example

nc.JSONParse('{"a":1}');    // { a: 1 }
nc.JSONParse("oops", null); // null
nc.JSONParse("oops");       // throws SyntaxError