@ix-xs/node-comfort 1.1.3 → 1.2.0

package/types/src/Time.d.ts

@@ -0,0 +1,205 @@
+declare namespace _exports {
+    export { TimeModule };
+}
+declare namespace _exports {
+    /**
+     * Sets the global default locale used by `relative`, `formatDuration` and
+     * `format` (named tokens). Chainable.
+     *
+     * @example
+     * nodeComfort.time.setLocale("fr");
+     *
+     * @param {string} locale - A BCP-47 locale tag (e.g. `"fr"`, `"en-GB"`, `"ja"`).
+     * @returns {TimeModule} The time module (for chaining).
+     */
+    function setLocale(locale: string): TimeModule;
+    /**
+     * Sets the global default time zone used by `format` and `isSameDay`.
+     * Chainable. Pass `undefined` to fall back to the system local zone.
+     *
+     * @example
+     * nodeComfort.time.setTimezone("Europe/Paris");
+     *
+     * @param {string|undefined} timeZone - An IANA time-zone name (e.g. `"America/New_York"`).
+     * @returns {TimeModule} The time module (for chaining).
+     */
+    function setTimezone(timeZone: string | undefined): TimeModule;
+    /**
+     * Returns the current global `{ locale, timeZone }` defaults.
+     *
+     * @returns {{ locale: string, timeZone: string|undefined }} A copy of the config.
+     */
+    function getConfig(): {
+        locale: string;
+        timeZone: string | undefined;
+    };
+    /**
+     * Parses a human duration string into milliseconds.
+     *
+     * Accepts things like `"1h"`, `"30m"`, `"1h30m"`, `"2 days"`, `"500ms"`.
+     * A plain number is treated as milliseconds.
+     *
+     * @example
+     * nodeComfort.time.parseDuration("1h30m"); // 5400000
+     * nodeComfort.time.parseDuration("2 days"); // 172800000
+     *
+     * @param {string|number} input - Duration string or millisecond count.
+     * @returns {number|null} Milliseconds, or null if it can't be parsed.
+     */
+    function parseDuration(input: string | number): number | null;
+    /**
+     * Formats a millisecond duration into a human string.
+     *
+     * The compact form (default) is language-neutral (`"1h 30m"`). The `long`
+     * form is fully localized through `Intl` • pass `options.locale` or set a
+     * global locale with {@link module:Time.setLocale}.
+     *
+     * @example
+     * nodeComfort.time.formatDuration(5400000);                       // "1h 30m"
+     * nodeComfort.time.formatDuration(90000, { long: true });         // "1 minute 30 seconds"
+     * nodeComfort.time.formatDuration(90000, { long: true, locale: "fr" }); // "1 minute 30 secondes"
+     *
+     * @param {number} ms - Duration in milliseconds.
+     * @param {{ long?: boolean, units?: number, locale?: string }} [options] - Formatting options (`units` caps how many parts show).
+     * @returns {string} The formatted duration.
+     */
+    function formatDuration(ms: number, options?: {
+        long?: boolean;
+        units?: number;
+        locale?: string;
+    }): string;
+    /**
+     * Returns a human-friendly, localized relative time string.
+     *
+     * Built on `Intl.RelativeTimeFormat`, so it speaks every language. Set
+     * `options.locale` (or a global locale) to translate; `options.numeric`
+     * controls wording (`"always"` → "1 day ago", `"auto"` → "yesterday").
+     *
+     * @example
+     * nodeComfort.time.relative(Date.now() - 3600e3);                 // "1 hour ago"
+     * nodeComfort.time.relative(Date.now() - 3600e3, undefined, { locale: "fr" }); // "il y a 1 heure"
+     * nodeComfort.time.relative(Date.now() - 86400e3, undefined, { numeric: "auto" }); // "yesterday"
+     *
+     * @param {Date|number|string} date - Target date.
+     * @param {Date|number|string} [from] - Reference date (defaults to now).
+     * @param {{ locale?: string, numeric?: "always"|"auto" }} [options] - Formatting options.
+     * @returns {string} The relative time string.
+     */
+    function relative(date: Date | number | string, from?: Date | number | string, options?: {
+        locale?: string;
+        numeric?: "always" | "auto";
+    }): string;
+    /**
+     * Formats a date using a small token syntax, with optional locale & time zone.
+     *
+     * **Numeric tokens:** `YYYY` `YY` `MM` `M` `DD` `D` `HH` `H` (24h) `hh` `h`
+     * (12h) `mm` `m` `ss` `s` `SSS`.
+     * **Localized tokens:** `MMMM` (month name) `MMM` (short month) `dddd` (weekday)
+     * `ddd` (short weekday) `A` (AM/PM) `a` (am/pm).
+     *
+     * Wrap literal text in square brackets to keep it verbatim: `"[Today is] dddd"`.
+     *
+     * @example
+     * nodeComfort.time.format(new Date(), "YYYY-MM-DD HH:mm:ss");
+     * nodeComfort.time.format(Date.now(), "dddd D MMMM YYYY", { locale: "fr" });
+     * nodeComfort.time.format(Date.now(), "HH:mm", { timeZone: "Asia/Tokyo" });
+     *
+     * @param {Date|number|string} date - Date to format.
+     * @param {string} [pattern="YYYY-MM-DD HH:mm:ss"] - Format pattern.
+     * @param {{ locale?: string, timeZone?: string }} [options] - Locale / time-zone overrides.
+     * @returns {string} The formatted date.
+     */
+    function format(date: Date | number | string, pattern?: string, options?: {
+        locale?: string;
+        timeZone?: string;
+    }): string;
+    /**
+     * Adds a duration to a date and returns a new Date.
+     *
+     * The duration may be a millisecond number or a string like `"1h30m"`.
+     *
+     * @example
+     * nodeComfort.time.add(new Date(), "2h");
+     * nodeComfort.time.add(new Date(), -1, "days");
+     *
+     * @param {Date|number|string} date - Base date.
+     * @param {number|string} amount - Amount (ms/string) or a number paired with `unit`.
+     * @param {"ms"|"s"|"m"|"h"|"d"|"w"} [unit] - Unit when `amount` is a plain number.
+     * @returns {Date} The resulting date.
+     */
+    function add(date: Date | number | string, amount: number | string, unit?: "ms" | "s" | "m" | "h" | "d" | "w"): Date;
+    /**
+     * Subtracts a duration from a date and returns a new Date.
+     *
+     * @param {Date|number|string} date - Base date.
+     * @param {number|string} amount - Amount (ms/string) or a number paired with `unit`.
+     * @param {"ms"|"s"|"m"|"h"|"d"|"w"} [unit] - Unit when `amount` is a plain number.
+     * @returns {Date} The resulting date.
+     */
+    function subtract(date: Date | number | string, amount: number | string, unit?: "ms" | "s" | "m" | "h" | "d" | "w"): Date;
+    /**
+     * Returns the difference between two dates in the requested unit.
+     *
+     * @example
+     * nodeComfort.time.diff("2024-01-02", "2024-01-01", "d"); // 1
+     *
+     * @param {Date|number|string} a - First date.
+     * @param {Date|number|string} b - Second date.
+     * @param {"ms"|"s"|"m"|"h"|"d"|"w"} [unit="ms"] - Result unit.
+     * @returns {number} The signed difference (`a - b`) in the given unit.
+     */
+    function diff(a: Date | number | string, b: Date | number | string, unit?: "ms" | "s" | "m" | "h" | "d" | "w"): number;
+    /**
+     * Checks whether two dates fall on the same calendar day.
+     *
+     * Uses local time by default; pass `options.timeZone` (or set a global zone)
+     * to compare calendar days in a specific zone.
+     *
+     * @param {Date|number|string} a - First date.
+     * @param {Date|number|string} b - Second date.
+     * @param {{ timeZone?: string }} [options] - Time-zone override.
+     * @returns {boolean} True if both are the same day.
+     */
+    function isSameDay(a: Date | number | string, b: Date | number | string, options?: {
+        timeZone?: string;
+    }): boolean;
+    /**
+     * Returns a new Date at the start of the given unit (day/hour/etc).
+     *
+     * @example
+     * nodeComfort.time.startOf(new Date(), "day"); // midnight today
+     *
+     * @param {Date|number|string} date - Base date.
+     * @param {"year"|"month"|"day"|"hour"|"minute"|"second"} unit - Unit to reset to.
+     * @returns {Date} The start-of-unit date.
+     */
+    function startOf(date: Date | number | string, unit: "year" | "month" | "day" | "hour" | "minute" | "second"): Date;
+    /**
+     * Returns the current Unix timestamp in seconds.
+     *
+     * @returns {number} Seconds since the Unix epoch.
+     */
+    function unix(): number;
+    /**
+     * Returns a high-resolution stopwatch you can `.stop()` to get elapsed ms.
+     *
+     * @example
+     * const timer = nodeComfort.time.stopwatch();
+     * doWork();
+     * console.log(timer.stop());          // e.g. 12.34 (ms, sub-ms precise)
+     * console.log(timer.stop(true));      // "12.34ms"
+     *
+     * @returns {{ elapsed: () => number, stop: (format?: boolean) => number|string }} A stopwatch handle.
+     */
+    function stopwatch(): {
+        elapsed: () => number;
+        stop: (format?: boolean) => number | string;
+    };
+}
+export = _exports;
+/**
+ * The time module itself • used as the return type of the chainable setters so
+ * `setLocale().setTimezone()...` stays fully typed without inlining the type.
+ */
+type TimeModule = typeof import("./Time");
+//# sourceMappingURL=Time.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Time.d.ts","sourceRoot":"","sources":["../../src/Time.js"],"names":[],"mappings":";;;;IA2HE;;;;;;;;;OASG;IACH,2BAHW,MAAM,GACJ,UAAU,CAKtB;IAED;;;;;;;;;OASG;IACH,+BAHW,MAAM,GAAC,SAAS,GACd,UAAU,CAKtB;IAED;;;;OAIG;IACH,sBAFa;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAC,SAAS,CAAA;KAAE,CAI1D;IAED;;;;;;;;;;;;OAYG;IACH,8BAHW,MAAM,GAAC,MAAM,GACX,MAAM,GAAC,IAAI,CAkBvB;IAED;;;;;;;;;;;;;;;OAeG;IACH,4BAJW,MAAM,YACN;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GACjD,MAAM,CAgClB;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,wBALW,IAAI,GAAC,MAAM,GAAC,MAAM,SAClB,IAAI,GAAC,MAAM,GAAC,MAAM,YAClB;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,QAAQ,GAAC,MAAM,CAAA;KAAE,GAC5C,MAAM,CAgClB;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,sBALW,IAAI,GAAC,MAAM,GAAC,MAAM,YAClB,MAAM,YACN;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GACpC,MAAM,CA0ClB;IAED;;;;;;;;;;;;;OAaG;IACH,mBALW,IAAI,GAAC,MAAM,GAAC,MAAM,UAClB,MAAM,GAAC,MAAM,SACb,IAAI,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GACtB,IAAI,CAWhB;IAED;;;;;;;OAOG;IACH,wBALW,IAAI,GAAC,MAAM,GAAC,MAAM,UAClB,MAAM,GAAC,MAAM,SACb,IAAI,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GACtB,IAAI,CAMhB;IAED;;;;;;;;;;OAUG;IACH,iBALW,IAAI,GAAC,MAAM,GAAC,MAAM,KAClB,IAAI,GAAC,MAAM,GAAC,MAAM,SAClB,IAAI,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GAAC,GAAG,GACtB,MAAM,CAKlB;IAED;;;;;;;;;;OAUG;IACH,sBALW,IAAI,GAAC,MAAM,GAAC,MAAM,KAClB,IAAI,GAAC,MAAM,GAAC,MAAM,YAClB;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GACnB,OAAO,CAOnB;IAED;;;;;;;;;OASG;IACH,uBAJW,IAAI,GAAC,MAAM,GAAC,MAAM,QAClB,MAAM,GAAC,OAAO,GAAC,KAAK,GAAC,MAAM,GAAC,QAAQ,GAAC,QAAQ,GAC3C,IAAI,CAkBhB;IAED;;;;OAIG;IACH,iBAFa,MAAM,CAIlB;IAED;;;;;;;;;;OAUG;IACH,sBAFa;QAAE,OAAO,EAAE,MAAM,MAAM,CAAC;QAAC,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,MAAM,GAAC,MAAM,CAAA;KAAE,CAYhF;;;;;;;kBAxcU,cAAc,QAAQ,CAAC"}

package/types/src/Utils.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Waits for a given number of milliseconds.
+ *
+ * @example
+ * await nodeComfort.wait(500); // waits 500 ms
+ *
+ * @param {number} ms - Delay in milliseconds.
+ * @returns {Promise<void>} A promise that resolves after the delay.
+ */
+export function wait(ms: number): Promise<void>;
+/**
+ * Polls a predicate at a given interval and emits events when it matches or times out.
+ *
+ * The predicate is evaluated every `options.interval` milliseconds (default: 50 ms).
+ * Be careful with the default interval: 50 ms is very frequent polling and can be
+ * unnecessarily CPU‑intensive if your predicate or trigger handlers are heavy.
+ * When `options.max` is `null`, the predicate can match indefinitely (infinite triggers),
+ * so you should choose an interval that makes sense for your use‑case.
+ *
+ * A `when(...)` task is one‑shot: once it has been stopped (manually or via `max`/`timeout`),
+ * calling `.start()` again on the same task will not restart it.
+ *
+ * @param {boolean|Promise<boolean>|(() => boolean|Promise<boolean>)} predicate
+ *        Condition to evaluate at each tick, or a function returning it.
+ * @param {*} [payload={}]
+ *        Value passed to listeners when events are emitted (e.g. an object or message).
+ * @param {object} [options]
+ * @param {number} [options.interval=50]
+ *        Polling interval in milliseconds. Increase this value if your predicate is
+ *        expensive or you expect many triggers without a `max` limit.
+ * @param {number|null} [options.timeout=null]
+ *        Maximum time in milliseconds before emitting a "timeout" event and stopping.
+ *        If `null`, no timeout is applied.
+ * @param {number|null} [options.max=null]
+ *        Maximum number of successful predicate evaluations ("trigger" events) before
+ *        automatically stopping. If `null`, triggers are infinite until `stop()` is called.
+ *
+ * @example
+ * // Basic usage: infinite triggers every 50 ms (default interval) – use with caution.
+ * const task = nodeComfort.when(() => true, { message: "Ok" });
+ *
+ * task
+ *   .on("trigger", (payload) => {
+ *     console.log(payload.message);
+ *     // task.stop(); // stop when you’re done
+ *   })
+ *   .start();
+ *
+ * @example
+ * // Safer usage: limit triggers and/or lower polling frequency.
+ * nodeComfort.when(() => true, { message: "Ok" }, { max: 1, interval: 500 })
+ *   .on("trigger", (payload) => {
+ *     console.log(payload.message);
+ *   })
+ *   .on("timeout", (payload) => {
+ *     console.log("Timed out", payload);
+ *   })
+ *   .start();
+ *
+ * @returns {{
+ *   start: () => any,
+ *   stop: () => any,
+ *   on: <E extends "error"|"trigger"|"timeout">(event: E, handler: E extends "error"
+ *       ? (error: unknown) => void|Promise<void>
+ *       : (payload: any) => void|Promise<void>) => any
+ * }} A small task controller with `start`, `stop` and `on`.
+ */
+export function when(predicate: boolean | Promise<boolean> | (() => boolean | Promise<boolean>), payload?: any, options?: {
+    interval?: number | undefined;
+    timeout?: number | null | undefined;
+    max?: number | null | undefined;
+}): {
+    start: () => any;
+    stop: () => any;
+    on: <E extends "error" | "trigger" | "timeout">(event: E, handler: E extends "error" ? (error: unknown) => void | Promise<void> : (payload: any) => void | Promise<void>) => any;
+};
+/**
+ * Installs process-level safety nets for errors, exits and signals.
+ *
+ * By default, it:
+ * - logs uncaught exceptions and unhandled rejections,
+ * - logs process exit codes,
+ * - logs SIGINT/SIGTERM/SIGQUIT and exits with code 0.
+ *
+ * You can override each handler with `.on(event, handler)`.
+ *
+ * @example
+ * // Use defaults:
+ * nodeComfort.dontCrash();
+ *
+ * @example
+ * // Custom error handler:
+ * nodeComfort.dontCrash().on("error", (err) => {
+ *   console.error("Global error:", err);
+ *   process.exit(1);
+ * });
+ *
+ * @returns {{
+ *   on: <E extends "error"|"exit"|"sig"|"beforeExit">(event: E, handler?: (
+ *     E extends "error" ? (error: Error|unknown) => void|Promise<void> :
+ *     E extends "exit" ? (code: number) => void|Promise<void> :
+ *     E extends "sig" ? (signal: "SIGINT"|"SIGTERM"|"SIGQUIT") => void|Promise<void> :
+ *     (code: number) => void|Promise<void>
+ *   )) => any
+ * }} A small controller to configure global handlers.
+ */
+export function dontCrash(): {
+    on: <E extends "error" | "exit" | "sig" | "beforeExit">(event: E, handler?: (E extends "error" ? (error: Error | unknown) => void | Promise<void> : E extends "exit" ? (code: number) => void | Promise<void> : E extends "sig" ? (signal: "SIGINT" | "SIGTERM" | "SIGQUIT") => void | Promise<void> : (code: number) => void | Promise<void>)) => any;
+};
+/**
+ * Safely stringifies a value to pretty-printed JSON (4 spaces indent).
+ *
+ * @param {*} value - Value to stringify.
+ * @returns {string} JSON string representation.
+ */
+export function JSONString(value: any): string;
+/**
+ * Parses a JSON string.
+ *
+ * @param {string} value - JSON string to parse.
+ * @returns {*} Parsed value.
+ */
+export function JSONParse(value: string): any;
+//# sourceMappingURL=Utils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Utils.d.ts","sourceRoot":"","sources":["../../src/Utils.js"],"names":[],"mappings":"AAME;;;;;;;;GAQG;AACH,yBAHW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAIzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,gCA7CW,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,GAAC,CAAC,MAAM,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,CAAC,YAEzD,GAAC,YAGT;IAAyB,QAAQ;IAGH,OAAO;IAGP,GAAG;CAIjC,GAsBU;IACR,KAAK,EAAE,MAAM,GAAG,CAAC;IACjB,IAAI,EAAE,MAAM,GAAG,CAAC;IAChB,EAAE,EAAE,CAAC,CAAC,SAAS,OAAO,GAAC,SAAS,GAAC,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,SAAS,OAAO,GAC1E,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAC,OAAO,CAAC,IAAI,CAAC,GACtC,CAAC,OAAO,EAAE,GAAG,KAAK,IAAI,GAAC,OAAO,CAAC,IAAI,CAAC,KAAK,GAAG,CAAA;CACnD,CAsIH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,6BATa;IACR,EAAE,EAAE,CAAC,CAAC,SAAS,OAAO,GAAC,MAAM,GAAC,KAAK,GAAC,YAAY,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,CACpE,CAAC,SAAS,OAAO,GAAG,CAAC,KAAK,EAAE,KAAK,GAAC,OAAO,KAAK,IAAI,GAAC,OAAO,CAAC,IAAI,CAAC,GAChE,CAAC,SAAS,MAAM,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAC,OAAO,CAAC,IAAI,CAAC,GACvD,CAAC,SAAS,KAAK,GAAG,CAAC,MAAM,EAAE,QAAQ,GAAC,SAAS,GAAC,SAAS,KAAK,IAAI,GAAC,OAAO,CAAC,IAAI,CAAC,GACpF,CAAO,IAAI,EAAE,MAAM,KAAK,IAAI,GAAC,OAAO,CAAC,IAAI,CAAC,CACrC,KAAK,GAAG,CAAA;CACV,CAiEH;AAED;;;;;GAKG;AACH,kCAHW,GAAC,GACC,MAAM,CAIlB;AAED;;;;;GAKG;AACH,iCAHW,MAAM,GACJ,GAAC,CAIb"}