bytekit 2.2.3 → 2.4.3

package/dist/utils/core/Logger.d.ts

@@ -1,39 +1,230 @@
+/**
+ * Ordered severity levels for the logger.
+ *
+ * Levels from lowest to highest priority: `debug` < `info` < `warn` < `error`.
+ * Setting the level to `"silent"` suppresses all output.
+ */
 export type LogLevel = "silent" | "error" | "warn" | "info" | "debug";
+/**
+ * A single structured log entry passed to every {@link LogTransport}.
+ *
+ * @template TContext - Shape of the optional context object attached to the entry.
+ */
 export interface LogEntry<TContext extends Record<string, unknown> = Record<string, unknown>> {
+    /** Severity level of the log entry. */
     level: LogLevel;
+    /** Human-readable log message. */
     message: string;
+    /** Optional dot-separated namespace of the logger that emitted the entry. */
     namespace?: string;
+    /** Exact time the entry was created. */
     timestamp: Date;
+    /** Optional structured context payload for machine-readable metadata. */
     context?: TContext;
+    /** Optional `Error` object associated with the log entry. */
     error?: Error;
 }
+/**
+ * A function that receives a {@link LogEntry} and writes it to an output
+ * destination. Transports may be synchronous or asynchronous.
+ *
+ * Uncaught rejections from async transports are caught by the {@link Logger}
+ * and reported to `console.error`.
+ */
 export type LogTransport = (entry: LogEntry) => void | Promise<void>;
+/** Configuration options for the {@link Logger} constructor. */
 export interface LoggerOptions {
+    /** Dot-separated namespace prepended to every log message (e.g., `"app:db"`). */
     namespace?: string;
+    /**
+     * Minimum severity level to emit.
+     * Defaults to `"debug"` in development and `"info"` in production.
+     */
     level?: LogLevel;
+    /**
+     * Custom transport functions to use instead of the default console transport.
+     * When omitted, a console transport is selected automatically based on runtime.
+     */
     transports?: LogTransport[];
+    /**
+     * Whether to prefix log entries with an ISO 8601 timestamp in the default
+     * console transport. Defaults to `true`.
+     */
     includeTimestamp?: boolean;
 }
+/**
+ * Creates a transport that writes coloured log entries to the Node.js console
+ * using ANSI escape codes.
+ *
+ * Each severity level is rendered in a distinct colour: red (error),
+ * yellow (warn), green (info), and grey (debug).
+ *
+ * @param options - Transport configuration.
+ * @param options.includeTimestamp - Prefix each entry with an ISO 8601
+ *   timestamp. Defaults to `true`.
+ * @returns A {@link LogTransport} for use in Node.js environments.
+ *
+ * @example
+ * ```typescript
+ * const logger = new Logger({
+ *     transports: [consoleTransportNode({ includeTimestamp: false })],
+ * });
+ * logger.info('Server started');
+ * ```
+ */
 export declare const consoleTransportNode: ({ includeTimestamp, }?: {
     includeTimestamp?: boolean;
 }) => LogTransport;
+/**
+ * Creates a transport that writes styled log entries to the browser console
+ * using `%c` CSS colour formatting.
+ *
+ * Each severity level is rendered in a distinct colour: red (error),
+ * orange (warn), green (info), and grey (debug).
+ *
+ * @param options - Transport configuration.
+ * @param options.includeTimestamp - Prefix each entry with an ISO 8601
+ *   timestamp. Defaults to `true`.
+ * @returns A {@link LogTransport} for use in browser environments.
+ *
+ * @example
+ * ```typescript
+ * const logger = new Logger({
+ *     transports: [consoleTransportBrowser()],
+ * });
+ * logger.warn('Low memory');
+ * ```
+ */
 export declare const consoleTransportBrowser: ({ includeTimestamp, }?: {
     includeTimestamp?: boolean;
 }) => LogTransport;
+/**
+ * Structured, transport-based logger with namespace and level filtering.
+ *
+ * Automatically selects a console transport based on the runtime environment
+ * (Node.js or browser) when no custom transports are provided. Supports
+ * child loggers for hierarchical namespacing.
+ *
+ * @template TContext - Shape of the structured context object attached to
+ *   log entries.
+ *
+ * @example
+ * ```typescript
+ * const logger = new Logger({ namespace: 'app', level: 'info' });
+ * logger.info('Server started', { port: 3000 });
+ *
+ * const dbLogger = logger.child('db');
+ * dbLogger.debug('Query executed', { sql: 'SELECT 1' });
+ * ```
+ */
 export declare class Logger<TContext extends Record<string, unknown> = Record<string, unknown>> {
     private readonly namespace?;
     private readonly transports;
     private level;
+    /**
+     * Creates a new `Logger` instance.
+     *
+     * @param options - Logger configuration. All fields are optional.
+     */
     constructor({ namespace, level, transports, includeTimestamp, }?: LoggerOptions);
+    /**
+     * Updates the minimum log level at runtime.
+     *
+     * @param level - The new minimum severity level to emit.
+     */
     setLevel(level: LogLevel): void;
+    /**
+     * Creates a child logger that inherits this logger's level and transports.
+     *
+     * The child's namespace is formed by appending `namespace` to the parent's
+     * namespace with a colon separator (e.g., `"app"` → `"app:db"`).
+     *
+     * @param namespace - Namespace segment to append.
+     * @returns A new `Logger` instance scoped to the child namespace.
+     *
+     * @example
+     * ```typescript
+     * const child = logger.child('db');
+     * child.debug('Connected'); // emits "[app:db] Connected"
+     * ```
+     */
     child(namespace: string): Logger<TContext>;
+    /**
+     * Emits a `debug`-level log entry.
+     *
+     * @param message - Human-readable description of the event.
+     * @param context - Optional structured metadata to attach.
+     */
     debug(message: string, context?: TContext): void;
+    /**
+     * Emits an `info`-level log entry.
+     *
+     * @param message - Human-readable description of the event.
+     * @param context - Optional structured metadata to attach.
+     */
     info(message: string, context?: TContext): void;
+    /**
+     * Emits a `warn`-level log entry.
+     *
+     * @param message - Human-readable description of the event.
+     * @param context - Optional structured metadata to attach.
+     */
     warn(message: string, context?: TContext): void;
+    /**
+     * Emits an `error`-level log entry.
+     *
+     * @param message - Human-readable description of the event.
+     * @param context - Optional structured metadata to attach.
+     * @param error - Optional `Error` object to include in the entry.
+     */
     error(message: string, context?: TContext, error?: Error): void;
+    /**
+     * Low-level method to emit a log entry at any level.
+     *
+     * Skips emission when `level` is below the configured minimum.
+     * Transport failures are caught and reported to `console.error`.
+     *
+     * @param level - Severity level for the entry.
+     * @param message - Human-readable description of the event.
+     * @param context - Optional structured metadata to attach.
+     * @param error - Optional `Error` object to include in the entry.
+     *
+     * @example
+     * ```typescript
+     * logger.log('info', 'Custom event', { traceId: 'abc' });
+     * ```
+     */
     log(level: LogLevel, message: string, context?: TContext, error?: Error): void;
+    /** @internal */
     private shouldLog;
+    /**
+     * Creates a `Logger` that suppresses all output.
+     *
+     * Useful for disabling logging in test environments.
+     *
+     * @returns A new `Logger` configured with level `"silent"`.
+     *
+     * @example
+     * ```typescript
+     * const logger = Logger.silent();
+     * logger.debug('This is never printed');
+     * ```
+     */
     static silent(): Logger<Record<string, unknown>>;
 }
+/**
+ * Factory function that creates a new {@link Logger} instance.
+ *
+ * A convenience wrapper around `new Logger(options)`.
+ *
+ * @param options - Logger configuration. All fields are optional.
+ * @returns A configured `Logger` instance.
+ *
+ * @example
+ * ```typescript
+ * const logger = createLogger({ namespace: 'api', level: 'warn' });
+ * logger.warn('Rate limit approaching');
+ * ```
+ */
 export declare const createLogger: (options?: LoggerOptions) => Logger<Record<string, unknown>>;
 //# sourceMappingURL=Logger.d.ts.map

package/dist/utils/core/Logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Logger.d.ts","sourceRoot":"","sources":["../../../src/utils/core/Logger.ts"],"names":[],"mappings":"AACA,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAEtE,MAAM,WAAW,QAAQ,CACrB,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAElE,KAAK,EAAE,QAAQ,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,KAAK,CAAC,EAAE,KAAK,CAAC;CACjB;AAED,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAErE,MAAM,WAAW,aAAa;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,UAAU,CAAC,EAAE,YAAY,EAAE,CAAC;IAC5B,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAwBD,eAAO,MAAM,oBAAoB,GAAI,wBAElC;IAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAO,KAAG,YAkCxC,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAAI,wBAErC;IAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAO,KAAG,YAiCxC,CAAC;AAKF,qBAAa,MAAM,CACf,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAElE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiB;IAC5C,OAAO,CAAC,KAAK,CAAW;gBAEZ,EACR,SAAS,EACT,KAAqB,EACrB,UAAU,EACV,gBAAgB,GACnB,GAAE,aAAkB;IAerB,QAAQ,CAAC,KAAK,EAAE,QAAQ;IAIxB,KAAK,CAAC,SAAS,EAAE,MAAM;IAWvB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ;IAIzC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ;IAIxC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ;IAIxC,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,KAAK;IAIxD,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,KAAK;IAmBvE,OAAO,CAAC,SAAS;IAKjB,MAAM,CAAC,MAAM;CAGhB;AAKD,eAAO,MAAM,YAAY,GAAI,UAAU,aAAa,oCAAwB,CAAC"}
+{"version":3,"file":"Logger.d.ts","sourceRoot":"","sources":["../../../src/utils/core/Logger.ts"],"names":[],"mappings":"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"}

package/dist/utils/core/Logger.js

@@ -1,3 +1,4 @@
+/* eslint-disable no-console */
 // ------------------------------------
 // Config & Constants
 // ------------------------------------
@@ -15,6 +16,26 @@ const isBrowser = typeof window !== "undefined" && typeof document !== "undefine
 // ------------------------------------
 // Transports
 // ------------------------------------
+/**
+ * Creates a transport that writes coloured log entries to the Node.js console
+ * using ANSI escape codes.
+ *
+ * Each severity level is rendered in a distinct colour: red (error),
+ * yellow (warn), green (info), and grey (debug).
+ *
+ * @param options - Transport configuration.
+ * @param options.includeTimestamp - Prefix each entry with an ISO 8601
+ *   timestamp. Defaults to `true`.
+ * @returns A {@link LogTransport} for use in Node.js environments.
+ *
+ * @example
+ * ```typescript
+ * const logger = new Logger({
+ *     transports: [consoleTransportNode({ includeTimestamp: false })],
+ * });
+ * logger.info('Server started');
+ * ```
+ */
 export const consoleTransportNode = ({ includeTimestamp = true, } = {}) => {
     const COLORS = {
         error: "\x1b[31m", // rojo
@@ -47,6 +68,26 @@ export const consoleTransportNode = ({ includeTimestamp = true, } = {}) => {
         method(...payload);
     };
 };
+/**
+ * Creates a transport that writes styled log entries to the browser console
+ * using `%c` CSS colour formatting.
+ *
+ * Each severity level is rendered in a distinct colour: red (error),
+ * orange (warn), green (info), and grey (debug).
+ *
+ * @param options - Transport configuration.
+ * @param options.includeTimestamp - Prefix each entry with an ISO 8601
+ *   timestamp. Defaults to `true`.
+ * @returns A {@link LogTransport} for use in browser environments.
+ *
+ * @example
+ * ```typescript
+ * const logger = new Logger({
+ *     transports: [consoleTransportBrowser()],
+ * });
+ * logger.warn('Low memory');
+ * ```
+ */
 export const consoleTransportBrowser = ({ includeTimestamp = true, } = {}) => {
     const COLORS = {
         error: "color: red",
@@ -57,6 +98,7 @@ export const consoleTransportBrowser = ({ includeTimestamp = true, } = {}) => {
     };
     return (entry) => {
         const { level, message, namespace, timestamp, context, error } = entry;
+        /* v8 ignore next */
         const color = COLORS[level] ?? "";
         const prefixParts = [];
         if (includeTimestamp)
@@ -81,7 +123,31 @@ export const consoleTransportBrowser = ({ includeTimestamp = true, } = {}) => {
 // ------------------------------------
 // Logger Class
 // ------------------------------------
+/**
+ * Structured, transport-based logger with namespace and level filtering.
+ *
+ * Automatically selects a console transport based on the runtime environment
+ * (Node.js or browser) when no custom transports are provided. Supports
+ * child loggers for hierarchical namespacing.
+ *
+ * @template TContext - Shape of the structured context object attached to
+ *   log entries.
+ *
+ * @example
+ * ```typescript
+ * const logger = new Logger({ namespace: 'app', level: 'info' });
+ * logger.info('Server started', { port: 3000 });
+ *
+ * const dbLogger = logger.child('db');
+ * dbLogger.debug('Query executed', { sql: 'SELECT 1' });
+ * ```
+ */
 export class Logger {
+    /**
+     * Creates a new `Logger` instance.
+     *
+     * @param options - Logger configuration. All fields are optional.
+     */
     constructor({ namespace, level = DEFAULT_LEVEL, transports, includeTimestamp, } = {}) {
         Object.defineProperty(this, "namespace", {
             enumerable: true,
@@ -113,9 +179,29 @@ export class Logger {
                         : consoleTransportNode({ includeTimestamp }),
                 ];
     }
+    /**
+     * Updates the minimum log level at runtime.
+     *
+     * @param level - The new minimum severity level to emit.
+     */
     setLevel(level) {
         this.level = level;
     }
+    /**
+     * Creates a child logger that inherits this logger's level and transports.
+     *
+     * The child's namespace is formed by appending `namespace` to the parent's
+     * namespace with a colon separator (e.g., `"app"` → `"app:db"`).
+     *
+     * @param namespace - Namespace segment to append.
+     * @returns A new `Logger` instance scoped to the child namespace.
+     *
+     * @example
+     * ```typescript
+     * const child = logger.child('db');
+     * child.debug('Connected'); // emits "[app:db] Connected"
+     * ```
+     */
     child(namespace) {
         const childNamespace = this.namespace
             ? `${this.namespace}:${namespace}`
@@ -126,18 +212,59 @@ export class Logger {
             transports: this.transports,
         });
     }
+    /**
+     * Emits a `debug`-level log entry.
+     *
+     * @param message - Human-readable description of the event.
+     * @param context - Optional structured metadata to attach.
+     */
     debug(message, context) {
         this.log("debug", message, context);
     }
+    /**
+     * Emits an `info`-level log entry.
+     *
+     * @param message - Human-readable description of the event.
+     * @param context - Optional structured metadata to attach.
+     */
     info(message, context) {
         this.log("info", message, context);
     }
+    /**
+     * Emits a `warn`-level log entry.
+     *
+     * @param message - Human-readable description of the event.
+     * @param context - Optional structured metadata to attach.
+     */
     warn(message, context) {
         this.log("warn", message, context);
     }
+    /**
+     * Emits an `error`-level log entry.
+     *
+     * @param message - Human-readable description of the event.
+     * @param context - Optional structured metadata to attach.
+     * @param error - Optional `Error` object to include in the entry.
+     */
     error(message, context, error) {
         this.log("error", message, context, error);
     }
+    /**
+     * Low-level method to emit a log entry at any level.
+     *
+     * Skips emission when `level` is below the configured minimum.
+     * Transport failures are caught and reported to `console.error`.
+     *
+     * @param level - Severity level for the entry.
+     * @param message - Human-readable description of the event.
+     * @param context - Optional structured metadata to attach.
+     * @param error - Optional `Error` object to include in the entry.
+     *
+     * @example
+     * ```typescript
+     * logger.log('info', 'Custom event', { traceId: 'abc' });
+     * ```
+     */
     log(level, message, context, error) {
         if (!this.shouldLog(level))
             return;
@@ -153,11 +280,25 @@ export class Logger {
             Promise.resolve(transport(entry)).catch((err) => console.error("[Logger] Transport failure", err));
         }
     }
+    /** @internal */
     shouldLog(level) {
         if (this.level === "silent")
             return false;
         return LEVEL_PRIORITY[level] <= LEVEL_PRIORITY[this.level];
     }
+    /**
+     * Creates a `Logger` that suppresses all output.
+     *
+     * Useful for disabling logging in test environments.
+     *
+     * @returns A new `Logger` configured with level `"silent"`.
+     *
+     * @example
+     * ```typescript
+     * const logger = Logger.silent();
+     * logger.debug('This is never printed');
+     * ```
+     */
     static silent() {
         return new Logger({ level: "silent" });
     }
@@ -165,5 +306,19 @@ export class Logger {
 // ------------------------------------
 // Factory
 // ------------------------------------
+/**
+ * Factory function that creates a new {@link Logger} instance.
+ *
+ * A convenience wrapper around `new Logger(options)`.
+ *
+ * @param options - Logger configuration. All fields are optional.
+ * @returns A configured `Logger` instance.
+ *
+ * @example
+ * ```typescript
+ * const logger = createLogger({ namespace: 'api', level: 'warn' });
+ * logger.warn('Rate limit approaching');
+ * ```
+ */
 export const createLogger = (options) => new Logger(options);
 //# sourceMappingURL=Logger.js.map

package/dist/utils/core/Logger.js.map

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

package/dist/utils/core/Profiler.d.ts

@@ -1,9 +1,50 @@
+/**
+ * Lightweight performance profiler for measuring execution durations.
+ *
+ * Supports optional namespacing so that results from multiple profiler
+ * instances can be distinguished in a shared metrics report.
+ *
+ * @example
+ * ```typescript
+ * const profiler = new Profiler('db');
+ * profiler.start('query');
+ * await runQuery();
+ * profiler.end('query');
+ * console.log(profiler.summary()); // { db: { query: 12.34 } }
+ * ```
+ */
 export declare class Profiler {
     private stack;
     private results;
     private namespace?;
+    /**
+     * Creates a new `Profiler` instance.
+     *
+     * @param namespace - Optional label used to group results in the
+     *   {@link Profiler.summary} output. When omitted, results are flat.
+     */
     constructor(namespace?: string);
+    /**
+     * Records the start time for a named measurement.
+     *
+     * @param label - Unique name for the measurement being started.
+     */
     start(label: string): void;
+    /**
+     * Records the end time for a named measurement and stores the duration.
+     *
+     * Uses `performance.now()` for high-resolution timing. Silently ignored
+     * when no matching {@link Profiler.start} call exists for `label`.
+     *
+     * @param label - Name of the measurement to complete.
+     *
+     * @example
+     * ```typescript
+     * profiler.start('render');
+     * render();
+     * profiler.end('render');
+     * ```
+     */
     end(label: string): void;
     summary(): Record<string, number> | Record<string, Record<string, number>>;
 }

package/dist/utils/core/Profiler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Profiler.d.ts","sourceRoot":"","sources":["../../../src/utils/core/Profiler.ts"],"names":[],"mappings":"AAAA,qBAAa,QAAQ;IACjB,OAAO,CAAC,KAAK,CAA0C;IACvD,OAAO,CAAC,OAAO,CAA8C;IAC7D,OAAO,CAAC,SAAS,CAAC,CAAS;gBAEf,SAAS,CAAC,EAAE,MAAM;IAI9B,KAAK,CAAC,KAAK,EAAE,MAAM;IAInB,GAAG,CAAC,KAAK,EAAE,MAAM;IAejB,OAAO;CAOV"}
+{"version":3,"file":"Profiler.d.ts","sourceRoot":"","sources":["../../../src/utils/core/Profiler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,qBAAa,QAAQ;IACjB,OAAO,CAAC,KAAK,CAA0C;IACvD,OAAO,CAAC,OAAO,CAA8C;IAC7D,OAAO,CAAC,SAAS,CAAC,CAAS;IAE3B;;;;;OAKG;gBACS,SAAS,CAAC,EAAE,MAAM;IAsB9B;;;;OAIG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM;IAInB;;;;;;;;;;;;;;OAcG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM;IAejB,OAAO;CAOV"}

package/dist/utils/core/Profiler.js

@@ -1,4 +1,25 @@
+/**
+ * Lightweight performance profiler for measuring execution durations.
+ *
+ * Supports optional namespacing so that results from multiple profiler
+ * instances can be distinguished in a shared metrics report.
+ *
+ * @example
+ * ```typescript
+ * const profiler = new Profiler('db');
+ * profiler.start('query');
+ * await runQuery();
+ * profiler.end('query');
+ * console.log(profiler.summary()); // { db: { query: 12.34 } }
+ * ```
+ */
 export class Profiler {
+    /**
+     * Creates a new `Profiler` instance.
+     *
+     * @param namespace - Optional label used to group results in the
+     *   {@link Profiler.summary} output. When omitted, results are flat.
+     */
     constructor(namespace) {
         Object.defineProperty(this, "stack", {
             enumerable: true,
@@ -19,10 +40,48 @@ export class Profiler {
             value: void 0
         });
         this.namespace = namespace;
+        /**
+         * Returns all recorded durations.
+         *
+         * When a namespace was provided to the constructor, results are grouped
+         * under that key. Without a namespace, a flat `Record<string, number>`
+         * is returned for backwards compatibility.
+         *
+         * @returns A map of label → duration (ms), optionally nested by namespace.
+         *
+         * @example
+         * ```typescript
+         * // Without namespace:
+         * profiler.summary(); // { query: 12.34, render: 5.67 }
+         *
+         * // With namespace 'db':
+         * profiler.summary(); // { db: { query: 12.34 } }
+         * ```
+         */
     }
+    /**
+     * Records the start time for a named measurement.
+     *
+     * @param label - Unique name for the measurement being started.
+     */
     start(label) {
         this.stack.push({ label, start: performance.now() });
     }
+    /**
+     * Records the end time for a named measurement and stores the duration.
+     *
+     * Uses `performance.now()` for high-resolution timing. Silently ignored
+     * when no matching {@link Profiler.start} call exists for `label`.
+     *
+     * @param label - Name of the measurement to complete.
+     *
+     * @example
+     * ```typescript
+     * profiler.start('render');
+     * render();
+     * profiler.end('render');
+     * ```
+     */
     end(label) {
         // Compatible con ES2020: usar slice().reverse() en lugar de findLast
         const entry = this.stack

package/dist/utils/core/Profiler.js.map

@@ -1 +1 @@
-{"version":3,"file":"Profiler.js","sourceRoot":"","sources":["../../../src/utils/core/Profiler.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,QAAQ;IAKjB,YAAY,SAAkB;QAJtB;;;;mBAA4C,EAAE;WAAC;QAC/C;;;;mBAAkD,EAAE;WAAC;QACrD;;;;;WAAmB;QAGvB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC/B,CAAC;IAED,KAAK,CAAC,KAAa;QACf,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACzD,CAAC;IAED,GAAG,CAAC,KAAa;QACb,qEAAqE;QACrE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK;aACnB,KAAK,EAAE;aACP,OAAO,EAAE;aACT,IAAI,CAAC,CAAC,CAAmC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;QACtE,IAAI,CAAC,KAAK;YAAE,OAAO;QACnB,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC;QACjD,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,IAAI,UAAU,CAAC;QACzC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YACrB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC;QAC3B,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,QAAQ,CAAC;IACxC,CAAC;IAED,OAAO;QACH,mFAAmF;QACnF,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;YAC9C,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QACpC,CAAC;QACD,OAAO,IAAI,CAAC,OAAO,CAAC;IACxB,CAAC;CACJ"}
+{"version":3,"file":"Profiler.js","sourceRoot":"","sources":["../../../src/utils/core/Profiler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,QAAQ;IAKjB;;;;;OAKG;IACH,YAAY,SAAkB;QAVtB;;;;mBAA4C,EAAE;WAAC;QAC/C;;;;mBAAkD,EAAE;WAAC;QACrD;;;;;WAAmB;QASvB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B;;;;;;;;;;;;;;;;;WAiBG;IACP,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,KAAa;QACf,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACzD,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,GAAG,CAAC,KAAa;QACb,qEAAqE;QACrE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK;aACnB,KAAK,EAAE;aACP,OAAO,EAAE;aACT,IAAI,CAAC,CAAC,CAAmC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;QACtE,IAAI,CAAC,KAAK;YAAE,OAAO;QACnB,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC;QACjD,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,IAAI,UAAU,CAAC;QACzC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YACrB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC;QAC3B,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,QAAQ,CAAC;IACxC,CAAC;IAED,OAAO;QACH,mFAAmF;QACnF,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;YAC9C,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QACpC,CAAC;QACD,OAAO,IAAI,CAAC,OAAO,CAAC;IACxB,CAAC;CACJ"}

package/dist/utils/core/RateLimiter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RateLimiter.d.ts","sourceRoot":"","sources":["../../../src/utils/core/RateLimiter.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;CAC1C;AAED,MAAM,WAAW,gBAAgB;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,qBAAa,WAAW;IACpB,OAAO,CAAC,OAAO,CACD;IACd,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA0B;gBAE3C,MAAM,GAAE,iBAAsB;IAO1C;;OAEG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAwB/B;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB;IAgCvC;;OAEG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAKxB;;OAEG;IACH,QAAQ,IAAI,IAAI;IAIhB;;OAEG;IACG,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAOrD;AAED;;;GAGG;AACH,qBAAa,wBAAwB;IACjC,OAAO,CAAC,QAAQ,CAAoC;IACpD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA0B;gBAE3C,MAAM,GAAE,iBAAsB;IAO1C;;OAEG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAuB/B;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB;IAuBvC;;OAEG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAKxB;;OAEG;IACH,QAAQ,IAAI,IAAI;IAIhB;;OAEG;IACG,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAOrD"}
+{"version":3,"file":"RateLimiter.d.ts","sourceRoot":"","sources":["../../../src/utils/core/RateLimiter.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;CAC1C;AAED,MAAM,WAAW,gBAAgB;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,qBAAa,WAAW;IACpB,OAAO,CAAC,OAAO,CACD;IACd,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA0B;gBAE3C,MAAM,GAAE,iBAAsB;IAO1C;;OAEG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAwB/B;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB;IAgCvC;;OAEG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAKxB;;OAEG;IACH,QAAQ,IAAI,IAAI;IAIhB;;OAEG;IACG,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAQrD;AAED;;;GAGG;AACH,qBAAa,wBAAwB;IACjC,OAAO,CAAC,QAAQ,CAAoC;IACpD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA0B;gBAE3C,MAAM,GAAE,iBAAsB;IAO1C;;OAEG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAuB/B;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB;IAuBvC;;OAEG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAKxB;;OAEG;IACH,QAAQ,IAAI,IAAI;IAIhB;;OAEG;IACG,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAQrD"}

package/dist/utils/core/RateLimiter.js

@@ -101,6 +101,7 @@ export class RateLimiter {
     async waitForAllowance(url) {
         while (!this.isAllowed(url)) {
             const stats = this.getStats(url);
+            /* v8 ignore next */
             const waitTime = Math.min(stats.retryAfter ?? 1, 1) * 1000;
             await new Promise((resolve) => setTimeout(resolve, waitTime));
         }
@@ -202,6 +203,7 @@ export class SlidingWindowRateLimiter {
     async waitForAllowance(url) {
         while (!this.isAllowed(url)) {
             const stats = this.getStats(url);
+            /* v8 ignore next */
             const waitTime = Math.min(stats.retryAfter ?? 1, 1) * 1000;
             await new Promise((resolve) => setTimeout(resolve, waitTime));
         }