@ix-xs/node-comfort 1.1.31 → 1.2.0

package/types/src/FS.d.ts

@@ -217,6 +217,66 @@ export function moveFile(options: {
  * @returns {string|undefined} File content, or undefined if the file cannot be read.
  */
 export function readFile(path: string): string | undefined;
+/**
+ * Reads and parses a JSON file.
+ * @template T
+ * @param {string} path - The JSON file path.
+ * @param {T} [fallback] - Value returned when the file is missing or invalid.
+ * @returns {T|any|undefined} The parsed value, or the fallback.
+ */
+export function readJSON<T>(path: string, fallback?: T): T | any | undefined;
+/**
+ * Serializes a value to JSON and writes it to a file (creating folders as needed).
+ * @param {string} path - The destination file path.
+ * @param {*} data - The value to serialize.
+ * @param {{ spaces?: number, force?: boolean }} [options] - Formatting options (`spaces` default 2).
+ * @returns {boolean} True on success, false on failure.
+ */
+export function writeJSON(path: string, data: any, options?: {
+    spaces?: number;
+    force?: boolean;
+}): boolean;
+/**
+ * Appends text to a file, creating it (and its folders) if necessary.
+ * @param {string} path - The file path.
+ * @param {string} data - The text to append.
+ * @returns {boolean} True on success, false on failure.
+ */
+export function appendFile(path: string, data: string): boolean;
+/**
+ * Checks whether a path (file or folder) exists.
+ * @param {string} path - The path to check.
+ * @returns {boolean} True if the path exists.
+ */
+export function exists(path: string): boolean;
+/**
+ * Returns filesystem stats for a path, or undefined if it does not exist.
+ * @param {string} path - The path to stat.
+ * @returns {import("node:fs").Stats|undefined} The stats object, or undefined.
+ */
+export function stat(path: string): any | undefined;
+/**
+ * Returns the size of a file in bytes.
+ * @param {string} path - The file path.
+ * @returns {number|undefined} Size in bytes, or undefined if not found.
+ */
+export function fileSize(path: string): number | undefined;
+/**
+ * Computes a hash digest of a file's contents.
+ * @param {string} path - The file path.
+ * @param {{ algorithm?: string, encoding?: "hex"|"base64"|"base64url" }} [options] - Hash options.
+ * @returns {string|undefined} The digest, or undefined if the file cannot be read.
+ */
+export function hashFile(path: string, options?: {
+    algorithm?: string;
+    encoding?: "hex" | "base64" | "base64url";
+}): string | undefined;
+/**
+ * Empties a folder's contents while keeping the folder itself.
+ * @param {string} path - The folder to empty.
+ * @returns {boolean|undefined} True on success, false on failure, undefined if not found.
+ */
+export function emptyFolder(path: string): boolean | undefined;
 /**
  * Watches a path and exposes event listeners.
  * @param {Object} [options] - Watch options.

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

@@ -1 +1 @@
-{"version":3,"file":"FS.d.ts","sourceRoot":"","sources":["../../src/FS.js"],"names":[],"mappings":"AAmKE;;;;;GAKG;AACH,8BAJW,MAAM,gBACN,MAAM,GACJ,MAAM,GAAC,SAAS,CAI5B;AAED;;;;GAIG;AACH,kCAHW,MAAM,GACJ,MAAM,CAWlB;AAED;;;;;GAKG;AACH,oCAJW,MAAM,cACN,OAAO,GACL,MAAM,EAAE,GAAC,SAAS,CAK9B;AAED;;;;GAIG;AACH,iCAHW,MAAM,GACJ,MAAM,GAAC,SAAS,CAI5B;AAED;;;;;GAKG;AACH,kCAJW,MAAM,cACN,OAAO,GACL,MAAM,EAAE,GAAC,SAAS,CAK9B;AAED;;;;GAIG;AACH,8BAHW,MAAM,GACJ,MAAM,GAAC,SAAS,CAI5B;AAED;;;;;GAKG;AACH,mCAJW,MAAM,UACN,OAAO,GACL,OAAO,GAAC,SAAS,CAoB7B;AAED;;;;;;GAMG;AACH,iCALW,MAAM,UACN,OAAO,SACP,MAAM,GAAC,MAAM,GAAC,IAAI,GAAC,SAAS,GAC1B,OAAO,GAAC,SAAS,CA+B7B;AAED;;;;;GAKG;AACH,uCAJW,MAAM,WACN,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,GACzB,MAAM,GAAC,SAAS,CAe5B;AAED;;;;GAIG;AACH,mCAHW,MAAM,GACJ,OAAO,GAAC,SAAS,CAY7B;AAED;;;;;;GAMG;AACH,qCALW,MAAM,cACN,OAAO,WACP,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GACvB,MAAM,GAAC,SAAS,CAe5B;AAED;;;;GAIG;AACH,iCAHW,MAAM,GACJ,OAAO,GAAC,SAAS,CAY7B;AAED;;;;;;;;;;GAUG;AACH,uCARG;IAAwB,IAAI,EAApB,MAAM;IACW,IAAI;IACH,SAAS;IACT,SAAS;IACT,KAAK;IACe,MAAM,aAAnC,MAAM,KAAK,OAAO;CACnC,GAAU,MAAM,GAAC,SAAS,CA0C5B;AAED;;;;;;;;;GASG;AACH,oCAPG;IAAwB,IAAI,EAApB,MAAM;IACW,IAAI;IACH,SAAS;IACT,SAAS;IACT,KAAK;CAC/B,GAAU,OAAO,GAAC,SAAS,CA0C7B;AAED;;;;;;;;;GASG;AACH,qCAPG;IAAwB,IAAI,EAApB,MAAM;IACW,IAAI;IACH,SAAS;IACT,KAAK;IACa,MAAM,WAAnC,MAAM,KAAK,OAAO;CACjC,GAAU,MAAM,GAAC,SAAS,CA+B5B;AAED;;;;;;;GAOG;AACH,kCALG;IAAwB,IAAI,EAApB,MAAM;IACU,IAAI,EAApB,MAAM;IACY,KAAK;CAC/B,GAAU,OAAO,GAAC,SAAS,CAwB7B;AAED;;;;;;;;;;GAUG;AACH,uCARG;IAAwB,IAAI,EAApB,MAAM;IACW,IAAI;IACH,SAAS;IACT,SAAS;IACT,KAAK;IACe,MAAM,aAAnC,MAAM,KAAK,OAAO;CACnC,GAAU,MAAM,GAAC,SAAS,CAkB5B;AAED;;;;;;;;;GASG;AACH,oCAPG;IAAwB,IAAI,EAApB,MAAM;IACU,IAAI,EAApB,MAAM;IACY,SAAS;IACT,SAAS;IACT,KAAK;CAC/B,GAAU,OAAO,GAAC,SAAS,CAS7B;AAED;;;;;;;;;GASG;AACH,qCAPG;IAAwB,IAAI,EAApB,MAAM;IACW,IAAI;IACH,SAAS;IACT,KAAK;IACa,MAAM,WAAnC,MAAM,KAAK,OAAO;CACjC,GAAU,MAAM,GAAC,SAAS,CAkB5B;AAED;;;;;;;GAOG;AACH,kCALG;IAAwB,IAAI,EAApB,MAAM;IACU,IAAI,EAApB,MAAM;IACY,KAAK;CAC/B,GAAU,OAAO,GAAC,SAAS,CAS7B;AAED;;;;GAIG;AACH,+BAHW,MAAM,GACJ,MAAM,GAAC,SAAS,CAW5B;AAED;;;;;;;;;;;;GAYG;AACH,gCAVG;IAAyB,IAAI;IACH,SAAS;IACmC,MAAM,YAA5D,QAAQ,GAAC,QAAQ,QAAQ,MAAM,KAAK,OAAO;CAC3D,GAAU;IACR,EAAE,EAAE,CAAC,CAAC,SAAS,QAAQ,GAAC,QAAQ,GAAC,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,SAAS,KAAK,GAAG,CAAC,KAAK,EAAE,QAAQ,GAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,GAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAC,OAAO,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC;IAC5L,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,KAAK,EAAE,MAAM,GAAG,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,CAAC;CACnB,GAAC,SAAS,CAkGb"}
+{"version":3,"file":"FS.d.ts","sourceRoot":"","sources":["../../src/FS.js"],"names":[],"mappings":"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"}

package/types/src/Func.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Creates a debounced version of a function that delays invocation until
+ * `wait` ms have elapsed since the last call.
+ *
+ * The returned function exposes `.cancel()` and `.flush()`.
+ *
+ * @example
+ * const onResize = nodeComfort.func.debounce(() => render(), 200);
+ * window.on("resize", onResize);
+ * onResize.cancel(); // drop any pending call
+ *
+ * @template {(...args: any[]) => any} F
+ * @param {F} fn - Function to debounce.
+ * @param {number} wait - Delay in milliseconds.
+ * @param {{ leading?: boolean }} [options] - Set `leading` to fire on the first call.
+ * @returns {F & { cancel: () => void, flush: () => void }} The debounced function.
+ */
+export function debounce<F extends (...args: any[]) => any>(fn: F, wait: number, options?: {
+    leading?: boolean;
+}): F & {
+    cancel: () => void;
+    flush: () => void;
+};
+/**
+ * Creates a throttled version of a function that runs at most once per
+ * `wait` ms.
+ *
+ * @example
+ * const onScroll = nodeComfort.func.throttle(() => update(), 100);
+ *
+ * @template {(...args: any[]) => any} F
+ * @param {F} fn - Function to throttle.
+ * @param {number} wait - Minimum interval in milliseconds.
+ * @param {{ trailing?: boolean }} [options] - Set `trailing` (default true) to run a final call.
+ * @returns {F & { cancel: () => void }} The throttled function.
+ */
+export function throttle<F extends (...args: any[]) => any>(fn: F, wait: number, options?: {
+    trailing?: boolean;
+}): F & {
+    cancel: () => void;
+};
+/**
+ * Wraps a function so it can only ever run once; subsequent calls return
+ * the first result.
+ *
+ * @example
+ * const init = nodeComfort.func.once(() => expensiveSetup());
+ *
+ * @template {(...args: any[]) => any} F
+ * @param {F} fn - Function to wrap.
+ * @returns {F} The single-call function.
+ */
+export function once<F extends (...args: any[]) => any>(fn: F): F;
+/**
+ * Memoizes a function, caching results by argument key.
+ *
+ * By default the cache key is a JSON serialization of the arguments; pass a
+ * `resolver` for custom keys.
+ *
+ * @example
+ * const fib = nodeComfort.func.memoize((n) => (n < 2 ? n : fib(n - 1) + fib(n - 2)));
+ *
+ * @template {(...args: any[]) => any} F
+ * @param {F} fn - Function to memoize.
+ * @param {(...args: any[]) => any} [resolver] - Cache-key resolver.
+ * @returns {F & { cache: Map<any, any> }} The memoized function.
+ */
+export function memoize<F extends (...args: any[]) => any>(fn: F, resolver?: (...args: any[]) => any): F & {
+    cache: Map<any, any>;
+};
+/**
+ * Retries an async function until it succeeds or the attempt budget runs out.
+ *
+ * Supports fixed or exponential backoff and a `shouldRetry` guard.
+ *
+ * @example
+ * const data = await nodeComfort.func.retry(() => fetch(url), {
+ *   attempts: 5,
+ *   delay: 200,
+ *   backoff: 2, // 200, 400, 800, ...
+ * });
+ *
+ * @template T
+ * @param {() => T|Promise<T>} fn - Function to run.
+ * @param {{
+ *   attempts?: number,
+ *   delay?: number,
+ *   backoff?: number,
+ *   maxDelay?: number,
+ *   shouldRetry?: (error: unknown, attempt: number) => boolean,
+ *   onRetry?: (error: unknown, attempt: number) => void
+ * }} [options] - Retry options.
+ * @returns {Promise<T>} The resolved value.
+ * @throws Re-throws the last error if all attempts fail.
+ */
+export function retry<T>(fn: () => T | Promise<T>, options?: {
+    attempts?: number;
+    delay?: number;
+    backoff?: number;
+    maxDelay?: number;
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+    onRetry?: (error: unknown, attempt: number) => void;
+}): Promise<T>;
+/**
+ * Runs a promise (or async function) with a timeout, rejecting if it takes
+ * too long.
+ *
+ * @example
+ * await nodeComfort.func.timeout(fetch(url), 5000, "fetch too slow");
+ *
+ * @template T
+ * @param {Promise<T>|(() => Promise<T>)} promise - Promise or async function.
+ * @param {number} ms - Timeout in milliseconds.
+ * @param {string} [message="Operation timed out"] - Error message on timeout.
+ * @returns {Promise<T>} The resolved value.
+ * @throws {Error} If the timeout elapses first.
+ */
+export function timeout<T>(promise: Promise<T> | (() => Promise<T>), ms: number, message?: string): Promise<T>;
+/**
+ * Composes functions left-to-right: `pipe(f, g)(x)` is `g(f(x))`.
+ *
+ * The first function may take multiple arguments; the rest take one.
+ *
+ * @example
+ * const process = nodeComfort.func.pipe(
+ *   (s) => s.trim(),
+ *   (s) => s.toUpperCase(),
+ * );
+ * process("  hi  "); // "HI"
+ *
+ * @param {...((arg: any) => any)} fns - Functions to compose.
+ * @returns {(...args: any[]) => any} The composed function.
+ */
+export function pipe(...fns: ((arg: any) => any)[]): (...args: any[]) => any;
+/**
+ * Composes functions right-to-left: `compose(f, g)(x)` is `f(g(x))`.
+ *
+ * @example
+ * const process = nodeComfort.func.compose(
+ *   (s) => s.toUpperCase(),
+ *   (s) => s.trim(),
+ * );
+ * process("  hi  "); // "HI"
+ *
+ * @param {...((arg: any) => any)} fns - Functions to compose.
+ * @returns {(...args: any[]) => any} The composed function.
+ */
+export function compose(...fns: ((arg: any) => any)[]): (...args: any[]) => any;
+/**
+ * Curries a function so it can be called with arguments one (or a few) at a time.
+ *
+ * @example
+ * const add = nodeComfort.func.curry((a, b, c) => a + b + c);
+ * add(1)(2)(3);   // 6
+ * add(1, 2)(3);   // 6
+ *
+ * @param {(...args: any[]) => any} fn - Function to curry.
+ * @param {number} [arity=fn.length] - Number of arguments to wait for.
+ * @returns {(...args: any[]) => any} The curried function.
+ */
+export function curry(fn: (...args: any[]) => any, arity?: number): (...args: any[]) => any;
+/**
+ * Returns a function that negates the result of `predicate`.
+ *
+ * @example
+ * const isOdd = nodeComfort.func.negate((n) => n % 2 === 0);
+ *
+ * @param {(...args: any[]) => boolean} predicate - Predicate to negate.
+ * @returns {(...args: any[]) => boolean} The negated predicate.
+ */
+export function negate(predicate: (...args: any[]) => boolean): (...args: any[]) => boolean;
+/**
+ * Wraps a function so that it is only actually invoked from the `n`-th call on.
+ *
+ * @example
+ * const save = nodeComfort.func.after(2, () => persist());
+ * save(); save(); // persists on the 2nd call
+ *
+ * @template {(...args: any[]) => any} F
+ * @param {number} n - Number of calls before `fn` fires.
+ * @param {F} fn - Function to wrap.
+ * @returns {F} The wrapped function.
+ */
+export function after<F extends (...args: any[]) => any>(n: number, fn: F): F;
+/**
+ * Turns a Node-style callback function (`(err, result) => ...`) into one that
+ * returns a Promise.
+ *
+ * @example
+ * const readFile = nodeComfort.func.promisify(fs.readFile);
+ * const data = await readFile("a.txt", "utf8");
+ *
+ * @param {(...args: any[]) => void} fn - Callback-style function.
+ * @returns {(...args: any[]) => Promise<any>} A promise-returning function.
+ */
+export function promisify(fn: (...args: any[]) => void): (...args: any[]) => Promise<any>;
+/**
+ * Wraps an async function so it resolves to a `[error, result]` tuple instead
+ * of throwing • Go-style error handling.
+ *
+ * @example
+ * const [err, user] = await nodeComfort.func.attempt(() => getUser(id))();
+ * if (err) return handle(err);
+ *
+ * @template T
+ * @param {(...args: any[]) => Promise<T>|T} fn - Function to wrap.
+ * @returns {(...args: any[]) => Promise<[unknown, T|undefined]>} The safe function.
+ */
+export function attempt<T>(fn: (...args: any[]) => Promise<T> | T): (...args: any[]) => Promise<[unknown, T | undefined]>;
+//# sourceMappingURL=Func.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Func.d.ts","sourceRoot":"","sources":["../../src/Func.js"],"names":[],"mappings":"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"}

package/types/src/Id.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Generates a random UUID v4.
+ *
+ * @example
+ * nodeComfort.id.uuid(); // "3f2504e0-4f89-41d3-9a0c-0305e82c3301"
+ *
+ * @returns {string} A UUID v4 string.
+ */
+export function uuid(): string;
+/**
+ * Generates a URL-safe, collision-resistant ID (nanoid-compatible alphabet).
+ *
+ * Uses secure randomness with unbiased rejection sampling.
+ *
+ * @example
+ * nodeComfort.id.nano();    // "V1StGXR8_Z5jdHi6B-myT"
+ * nodeComfort.id.nano(10);  // "IRFa-VaY2b"
+ *
+ * @param {number} [size=21] - Desired length.
+ * @param {string} [alphabet] - Custom alphabet.
+ * @returns {string} The generated ID.
+ */
+export function nano(size?: number, alphabet?: string): string;
+/**
+ * Generates a ULID • a lexicographically-sortable, timestamp-prefixed ID.
+ *
+ * ULIDs sort by creation time and are a great primary-key alternative to UUIDs.
+ *
+ * @example
+ * nodeComfort.id.ulid(); // "01ARZ3NDEKTSV4RRFFQ69G5FAV"
+ *
+ * @param {number} [time=Date.now()] - Timestamp in ms to encode.
+ * @returns {string} A 26-character ULID.
+ */
+export function ulid(time?: number): string;
+/**
+ * Generates a cryptographically-secure random token.
+ *
+ * @example
+ * nodeComfort.id.token();               // 32-byte hex string
+ * nodeComfort.id.token(16, "base64url"); // 16 bytes, URL-safe base64
+ *
+ * @param {number} [bytes=32] - Number of random bytes.
+ * @param {"hex"|"base64"|"base64url"|"base58"} [encoding="hex"] - Output encoding.
+ * @returns {string} The token.
+ */
+export function token(bytes?: number, encoding?: "hex" | "base64" | "base64url" | "base58"): string;
+/**
+ * Generates a short, human-friendly random code (uppercase + digits by default).
+ *
+ * Ambiguous characters (`0/O`, `1/I`) are excluded, making it suitable for
+ * coupons, OTP-like codes and invite links.
+ *
+ * @example
+ * nodeComfort.id.code();            // "K7QF9X"
+ * nodeComfort.id.code(4, "1234");   // "3142"
+ *
+ * @param {number} [length=6] - Number of characters.
+ * @param {string} [alphabet="ABCDEFGHJKLMNPQRSTUVWXYZ23456789"] - Characters to pick from.
+ * @returns {string} The random code.
+ */
+export function code(length?: number, alphabet?: string): string;
+/**
+ * Hashes a value with a chosen algorithm.
+ *
+ * @example
+ * nodeComfort.id.hash("hello");                  // sha256 hex
+ * nodeComfort.id.hash("hello", { algorithm: "md5" });
+ *
+ * @param {string|Buffer} value - Data to hash.
+ * @param {{ algorithm?: string, encoding?: "hex"|"base64"|"base64url" }} [options] - Hash options.
+ * @returns {string} The digest.
+ */
+export function hash(value: string | Buffer, options?: {
+    algorithm?: string;
+    encoding?: "hex" | "base64" | "base64url";
+}): string;
+/**
+ * Computes an HMAC signature for a value using a secret key.
+ *
+ * @example
+ * nodeComfort.id.hmac("payload", "secret"); // sha256 HMAC hex
+ *
+ * @param {string|Buffer} value - Data to sign.
+ * @param {string|Buffer} secret - Secret key.
+ * @param {{ algorithm?: string, encoding?: "hex"|"base64"|"base64url" }} [options] - HMAC options.
+ * @returns {string} The signature.
+ */
+export function hmac(value: string | Buffer, secret: string | Buffer, options?: {
+    algorithm?: string;
+    encoding?: "hex" | "base64" | "base64url";
+}): string;
+/**
+ * Compares two strings/buffers in constant time to prevent timing attacks.
+ *
+ * Use this when comparing secrets, tokens, or signatures.
+ *
+ * @example
+ * if (nodeComfort.id.safeEqual(provided, expected)) { ... }
+ *
+ * @param {string|Buffer} a - First value.
+ * @param {string|Buffer} b - Second value.
+ * @returns {boolean} True if equal.
+ */
+export function safeEqual(a: string | Buffer, b: string | Buffer): boolean;
+/**
+ * Returns a monotonically-increasing counter ID prefixed with an optional label.
+ *
+ * Useful for readable, unique keys within a single process run.
+ *
+ * @example
+ * nodeComfort.id.seq("user"); // "user-1"
+ * nodeComfort.id.seq("user"); // "user-2"
+ *
+ * @param {string} [prefix=""] - Optional prefix.
+ * @returns {string} The sequential ID.
+ */
+export function seq(prefix?: string): string;
+//# sourceMappingURL=Id.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Id.d.ts","sourceRoot":"","sources":["../../src/Id.js"],"names":[],"mappings":"AAyDE;;;;;;;GAOG;AACH,wBAFa,MAAM,CAIlB;AAED;;;;;;;;;;;;GAYG;AACH,4BAJW,MAAM,aACN,MAAM,GACJ,MAAM,CAgBlB;AAED;;;;;;;;;;GAUG;AACH,4BAHW,MAAM,GACJ,MAAM,CAgBlB;AAED;;;;;;;;;;GAUG;AACH,8BAJW,MAAM,aACN,KAAK,GAAC,QAAQ,GAAC,WAAW,GAAC,QAAQ,GACjC,MAAM,CAMlB;AAED;;;;;;;;;;;;;GAaG;AACH,8BAJW,MAAM,aACN,MAAM,GACJ,MAAM,CASlB;AAED;;;;;;;;;;GAUG;AACH,4BAJW,MAAM,GAAC,MAAM,YACb;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,KAAK,GAAC,QAAQ,GAAC,WAAW,CAAA;CAAE,GAC3D,MAAM,CAMlB;AAED;;;;;;;;;;GAUG;AACH,4BALW,MAAM,GAAC,MAAM,UACb,MAAM,GAAC,MAAM,YACb;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,KAAK,GAAC,QAAQ,GAAC,WAAW,CAAA;CAAE,GAC3D,MAAM,CAMlB;AAED;;;;;;;;;;;GAWG;AACH,6BAJW,MAAM,GAAC,MAAM,KACb,MAAM,GAAC,MAAM,GACX,OAAO,CAOnB;AAED;;;;;;;;;;;GAWG;AACH,6BAHW,MAAM,GACJ,MAAM,CAKlB"}

package/types/src/Logger.d.ts

@@ -21,6 +21,39 @@ export function setDelimiter(options?: {
  * @returns {Logger} The same Logger instance (for chaining)
  */
 export function log(content: any): Logger;
+/**
+ * Logs an informational message, prefixed with a cyan `ℹ INFO` label.
+ * @param {*} content - Content to print.
+ * @returns {Logger} The same Logger instance (for chaining).
+ */
+export function info(content: any): Logger;
+/**
+ * Logs a success message, prefixed with a green `✔ OK` label.
+ * @param {*} content - Content to print.
+ * @returns {Logger} The same Logger instance (for chaining).
+ */
+export function success(content: any): Logger;
+/**
+ * Logs a warning, prefixed with a yellow `⚠ WARN` label (writes to stderr).
+ * @param {*} content - Content to print.
+ * @returns {Logger} The same Logger instance (for chaining).
+ */
+export function warn(content: any): Logger;
+/**
+ * Logs an error, prefixed with a red `✖ ERROR` label.
+ *
+ * Accepts an `Error` and prints its stack when available.
+ * @param {*} content - Content or Error to print.
+ * @returns {Logger} The same Logger instance (for chaining).
+ */
+export function error(content: any): Logger;
+/**
+ * Logs a debug message (only when `DEBUG`/`NODE_DEBUG` env is set), prefixed
+ * with a gray `● DEBUG` label.
+ * @param {*} content - Content to print.
+ * @returns {Logger} The same Logger instance (for chaining).
+ */
+export function debug(content: any): Logger;
 /**
  * Start a log group (displays a label and adds indentation)
  * @param {string} label - The group name to display

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

@@ -1 +1 @@
-{"version":3,"file":"Logger.d.ts","sourceRoot":"","sources":["../../src/Logger.js"],"names":[],"mappings":"AA+NE;;;;GAIG;AACH,oCAHW,OAAO,GACL,MAAM,CAKlB;AAED;;;;;;GAMG;AACH,uCAJG;IAAyB,IAAI;IACJ,KAAK;CAC9B,GAAU,MAAM,CAQlB;AAED;;;;GAIG;AACH,6BAHW,GAAC,GACC,MAAM,CAiClB;AAED;;;;GAIG;AACH,6BAHW,MAAM,GACJ,MAAM,CAOlB;AAED;;;GAGG;AACH,4BAFa,MAAM,CAKlB"}
+{"version":3,"file":"Logger.d.ts","sourceRoot":"","sources":["../../src/Logger.js"],"names":[],"mappings":"AAiPE;;;;GAIG;AACH,oCAHW,OAAO,GACL,MAAM,CAKlB;AAED;;;;;;GAMG;AACH,uCAJG;IAAyB,IAAI;IACJ,KAAK;CAC9B,GAAU,MAAM,CAQlB;AAED;;;;GAIG;AACH,6BAHW,GAAC,GACC,MAAM,CAiClB;AAED;;;;GAIG;AACH,8BAHW,GAAC,GACC,MAAM,CAIlB;AAED;;;;GAIG;AACH,iCAHW,GAAC,GACC,MAAM,CAIlB;AAED;;;;GAIG;AACH,8BAHW,GAAC,GACC,MAAM,CAIlB;AAED;;;;;;GAMG;AACH,+BAHW,GAAC,GACC,MAAM,CAMlB;AAED;;;;;GAKG;AACH,+BAHW,GAAC,GACC,MAAM,CAOlB;AAED;;;;GAIG;AACH,6BAHW,MAAM,GACJ,MAAM,CAOlB;AAED;;;GAGG;AACH,4BAFa,MAAM,CAKlB"}