@monterosa/sdk-util 0.19.0-rc.6 → 2.0.0-rc.2

package/dist/checksum.d.ts

@@ -8,6 +8,8 @@
  * More details on the license can be found at https://www.monterosa.co/sdk/license
  */
 /**
+ * @internal
+ *
  * FNV-1a 32-bit hash function
  * Produces a fast, non-cryptographic checksum for strings
  *

package/dist/delay.d.ts

@@ -8,5 +8,11 @@
  */
 /**
  * @internal
+ *
+ * Delays the execution of the code for a given number of milliseconds.
+ *
+ * @param timeout - The timeout in milliseconds.
+ *
+ * @returns A promise that resolves after the timeout.
  */
 export declare const delay: (timeout: number) => Promise<void>;

package/dist/emitter.d.ts

@@ -7,13 +7,43 @@
  * More details on the license can be found at https://www.monterosa.co/sdk/license
  */
 type Handler = (...args: any[]) => void;
+/**
+ * @internal
+ *
+ * Event emitter. Provides subscribe/unsubscribe pattern used throughout
+ * the SDK for observable state changes.
+ */
 export declare class Emitter {
-    private readonly emitter;
-    private readonly handlers;
-    constructor();
+    private readonly listeners;
+    /**
+     * Subscribes to an event.
+     *
+     * @param event - The event name
+     * @param handler - The callback function
+     * @returns A function that unsubscribes the handler when called
+     */
     on(event: string, handler: Handler): Unsubscribe;
+    /**
+     * Unsubscribes from an event.
+     *
+     * @param event - The event name
+     * @param handler - The handler to remove. If omitted, all handlers for the event are removed.
+     */
     off(event: string, handler?: Handler): void;
+    /**
+     * Emits an event with optional arguments.
+     *
+     * @param event - The event name
+     * @param args - Arguments to pass to handlers
+     */
     emit(event: string, ...args: any[]): void;
+    /**
+     * Subscribes to an event and automatically unsubscribes after the first call.
+     *
+     * @param event - The event name
+     * @param handler - The callback function
+     * @returns A function that unsubscribes the handler when called
+     */
     once(event: string, handler: Handler): Unsubscribe;
 }
 /**

package/dist/error.d.ts

@@ -8,8 +8,8 @@
  */
 /**
  * MonterosaError extends the standard JavaScript `Error` object. It has
- * an error code so that user can identify the error. Also it has it's own
- * specific `name` "MonterosaError"
+ * an error code so that users can identify the error. It also has its
+ * own specific `name` "MonterosaError".
  */
 export declare class MonterosaError extends Error {
     /**
@@ -33,4 +33,8 @@ type ErrorMap<ErrorCode extends string> = {
  * @internal
  */
 export declare function createError<ErrorCode extends string>(code: ErrorCode, messages: ErrorMap<ErrorCode>, ...params: any[]): MonterosaError;
+/**
+ * @internal
+ */
+export declare function getErrorMessage(err: unknown): string;
 export {};

package/dist/fromentries.d.ts

@@ -7,4 +7,7 @@
  *
  * More details on the license can be found at https://www.monterosa.co/sdk/license
  */
+/**
+ * @internal
+ */
 export declare function fromEntries(entries: [string | number | symbol, any][]): Record<string | number | symbol, any>;

package/dist/index.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Shared utilities including emitters, error handling, and storage helpers.
+ *
+ * @packageDocumentation
+ */
 /**
  * @license
  * @monterosa/sdk-util
@@ -6,11 +11,6 @@
  *
  * More details on the license can be found at https://www.monterosa.co/sdk/license
  */
-/**
- * Monterosa SDK / Util
- *
- * @packageDocumentation
- */
 export * from './emitter';
 export * from './delay';
 export * from './memoize-promise';
@@ -21,4 +21,7 @@ export * from './throttle';
 export * from './time';
 export * from './fromentries';
 export * from './calculate-percentage';
+export * from './task-queue';
+export * from './with-retry-async';
 export * from './checksum';
+export * from './uuid';

package/dist/{index.esm.js → index.js}

@@ -1,5 +1,3 @@
-import mitt from 'mitt';
-
 /**
  * @license
  * @monterosa/sdk-util
@@ -8,41 +6,67 @@ import mitt from 'mitt';
  *
  * More details on the license can be found at https://www.monterosa.co/sdk/license
  */
+/**
+ * @internal
+ *
+ * Event emitter. Provides subscribe/unsubscribe pattern used throughout
+ * the SDK for observable state changes.
+ */
 class Emitter {
     constructor() {
-        this.handlers = new Map();
-        this.emitter = mitt();
+        this.listeners = new Map();
     }
+    /**
+     * Subscribes to an event.
+     *
+     * @param event - The event name
+     * @param handler - The callback function
+     * @returns A function that unsubscribes the handler when called
+     */
     on(event, handler) {
-        const mittHandler = (args) => {
-            handler(...(Array.isArray(args) ? args : [args]));
-        };
-        this.handlers.set(handler, mittHandler);
-        this.emitter.on(event, mittHandler);
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, new Set());
+        }
+        this.listeners.get(event).add(handler);
         return () => this.off(event, handler);
     }
+    /**
+     * Unsubscribes from an event.
+     *
+     * @param event - The event name
+     * @param handler - The handler to remove. If omitted, all handlers for the event are removed.
+     */
     off(event, handler) {
+        var _a;
         if (handler === undefined) {
-            this.emitter.off(event);
+            this.listeners.delete(event);
             return;
         }
-        const mittHandler = this.handlers.get(handler);
-        if (mittHandler) {
-            this.emitter.off(event, mittHandler);
-            this.handlers.delete(handler);
-        }
+        (_a = this.listeners.get(event)) === null || _a === void 0 ? void 0 : _a.delete(handler);
     }
+    /**
+     * Emits an event with optional arguments.
+     *
+     * @param event - The event name
+     * @param args - Arguments to pass to handlers
+     */
     emit(event, ...args) {
-        this.emitter.emit(event, args);
+        var _a;
+        (_a = this.listeners.get(event)) === null || _a === void 0 ? void 0 : _a.forEach((handler) => handler(...args));
     }
+    /**
+     * Subscribes to an event and automatically unsubscribes after the first call.
+     *
+     * @param event - The event name
+     * @param handler - The callback function
+     * @returns A function that unsubscribes the handler when called
+     */
     once(event, handler) {
-        const mittHandler = (args) => {
-            handler(...(Array.isArray(args) ? args : [args]));
-            this.off(event, handler);
+        const wrapper = (...args) => {
+            handler(...args);
+            this.off(event, wrapper);
         };
-        this.handlers.set(handler, mittHandler);
-        this.emitter.on(event, mittHandler);
-        return () => this.off(event, handler);
+        return this.on(event, wrapper);
     }
 }
 /**
@@ -63,6 +87,12 @@ const subscribe = (emitter, event, callback) => {
  */
 /**
  * @internal
+ *
+ * Delays the execution of the code for a given number of milliseconds.
+ *
+ * @param timeout - The timeout in milliseconds.
+ *
+ * @returns A promise that resolves after the timeout.
  */
 const delay = async (timeout) => {
     await new Promise((resolve) => setTimeout(resolve, timeout));
@@ -213,8 +243,8 @@ function checkAvailability() {
 /* eslint max-classes-per-file: ["error", 2] */
 /**
  * MonterosaError extends the standard JavaScript `Error` object. It has
- * an error code so that user can identify the error. Also it has it's own
- * specific `name` "MonterosaError"
+ * an error code so that users can identify the error. It also has its
+ * own specific `name` "MonterosaError".
  */
 class MonterosaError extends Error {
     /**
@@ -239,6 +269,23 @@ class MonterosaError extends Error {
 function createError(code, messages, ...params) {
     const message = messages[code](...params);
     return new MonterosaError(code, message);
+}
+/**
+ * @internal
+ */
+function getErrorMessage(err) {
+    if (err instanceof Error) {
+        return err.message;
+    }
+    if (typeof err === 'string') {
+        return err;
+    }
+    try {
+        return JSON.stringify(err);
+    }
+    catch (_a) {
+        return 'Unknown error';
+    }
 }
 
 /**
@@ -686,6 +733,8 @@ function calculateNextTickDelay() {
     return (expectedNextTick - serverTimestamp) * 1000;
 }
 /**
+ * @internal
+ *
  * Main function that maintains current timestamp
  */
 function tick() {
@@ -695,6 +744,14 @@ function tick() {
     serverTimestamp += timeSinceLastTick;
     lastTickTimestamp = currentTimestamp;
     tickTimeoutId = setTimeout(tick, calculateNextTickDelay());
+    // In Node.js, a pending setTimeout keeps the process alive. This causes
+    // Jest worker processes to hang after tests complete, because tick()
+    // reschedules itself indefinitely. Calling unref() tells Node.js not to
+    // keep the process alive solely for this timer. In browsers, unref()
+    // does not exist and is not needed — tabs don't have this problem.
+    if (typeof tickTimeoutId === 'object' && 'unref' in tickTimeoutId) {
+        tickTimeoutId.unref();
+    }
     emitter.emit('tick', serverTimestamp);
 }
 /**
@@ -743,6 +800,9 @@ tick();
  *
  * More details on the license can be found at https://www.monterosa.co/sdk/license
  */
+/**
+ * @internal
+ */
 function fromEntries(entries) {
     return entries.reduce((obj, [key, value]) => {
         obj[key] = value;
@@ -805,6 +865,179 @@ const calculatePercentage = (values) => {
     return results.map((item) => item.percentage);
 };
 
+/**
+ * @license
+ * @monterosa/sdk-identify-kit
+ *
+ * Copyright © 2025 Monterosa Productions Limited. All rights reserved.
+ *
+ * More details on the license can be found at https://www.monterosa.co/sdk/license
+ */
+/**
+ * @internal
+ *
+ * TaskQueue ensures that async tasks run sequentially (FIFO).
+ *
+ * Behavior:
+ * - Tasks run one at a time in the order they were enqueued.
+ * - If a task fails (throws/rejects), the queue is stopped
+ *   and all pending tasks are cleared.
+ */
+class TaskQueue {
+    constructor() {
+        this.current = null;
+        this.queue = [];
+        this.paused = false;
+    }
+    enqueue(fn) {
+        this.queue.push(fn);
+        this.process();
+    }
+    enqueueFront(fn) {
+        this.queue.unshift(fn);
+        this.process();
+    }
+    pause() {
+        this.paused = true;
+    }
+    resume() {
+        this.paused = false;
+        this.process();
+    }
+    process() {
+        if (this.current || this.paused) {
+            return;
+        }
+        const next = this.queue.shift();
+        if (!next) {
+            return;
+        }
+        this.current = next()
+            .then(() => {
+            this.current = null;
+            this.process();
+        })
+            .catch(() => {
+            this.clear();
+        });
+    }
+    get length() {
+        return this.queue.length;
+    }
+    isEmpty() {
+        return this.queue.length === 0;
+    }
+    hasActiveTask() {
+        return this.current !== null;
+    }
+    clear() {
+        this.queue = [];
+        this.current = null;
+    }
+}
+
+/**
+ * @license
+ * @monterosa/sdk-util
+ *
+ * Copyright © 2025 Monterosa Productions Limited. All rights reserved.
+ *
+ * More details on the license can be found at https://www.monterosa.co/sdk/license
+ */
+/**
+ * Calculates the delay for a retry attempt based on the backoff strategy.
+ *
+ * @param backoffStrategy - The backoff strategy.
+ * @param attemptNumber - The current attempt number (0-indexed).
+ * @param baseDelay - The base delay in milliseconds.
+ * @param jitter - The maximum jitter to add in milliseconds.
+ * @param maxDelay - The maximum delay in milliseconds.
+ *
+ * @returns The calculated delay in milliseconds.
+ */
+function calculateRetryDelay(backoffStrategy, attemptNumber, baseDelay, jitter, maxDelay) {
+    let delayMs;
+    switch (backoffStrategy) {
+        case 'fixed':
+            delayMs = baseDelay;
+            break;
+        case 'incremental':
+            delayMs = baseDelay * (attemptNumber + 1);
+            break;
+        case 'exponential':
+        default:
+            delayMs = baseDelay * 2 ** attemptNumber;
+    }
+    // Add jitter (random value between 0 and jitter)
+    delayMs += Math.floor(Math.random() * jitter);
+    // Cap at maxDelay
+    return Math.min(delayMs, maxDelay);
+}
+/**
+ * @internal
+ *
+ * Default configuration values for retry logic.
+ */
+const DEFAULT_RETRY_CONFIG = {
+    backoffStrategy: 'exponential',
+    attempts: 3,
+    baseDelay: 500,
+    jitter: 500,
+    maxDelay: 10000,
+};
+/**
+ * @internal
+ *
+ * Wraps an async function with retry logic and configurable backoff strategies.
+ *
+ * @template TArgs - The argument types of the wrapped function.
+ * @template TResult - The return type of the wrapped function.
+ *
+ * @param fn - The async function to wrap.
+ * @param config - Configuration object for retry behaviour.
+ *   - backoffStrategy: BackoffStrategy (default: 'exponential')
+ *   - attempts: number of retry attempts (default: 3)
+ *   - baseDelay: base delay in ms (default: 500)
+ *   - jitter: max jitter in ms (default: 500)
+ *   - maxDelay: max delay in ms (default: 10_000)
+ *
+ * @returns A new function that retries the given async function up to the
+ *   specified number of attempts with the configured backoff strategy.
+ *
+ * @throws The last encountered error if all retry attempts fail.
+ *
+ * @example
+ * const fetchDataWithRetry = withRetryAsync(fetchData, {
+ *   backoffStrategy: 'exponential',
+ *   attempts: 3,
+ *   baseDelay: 500
+ * });
+ *
+ * // Will retry up to 3 times with exponential backoff
+ * fetchDataWithRetry("https://api.example.com")
+ *   .then(data => console.log(data))
+ *   .catch(err => console.error("Failed after retries:", err));
+ */
+function withRetryAsync(fn, config = {}) {
+    const { backoffStrategy = DEFAULT_RETRY_CONFIG.backoffStrategy, attempts = DEFAULT_RETRY_CONFIG.attempts, baseDelay = DEFAULT_RETRY_CONFIG.baseDelay, jitter = DEFAULT_RETRY_CONFIG.jitter, maxDelay = DEFAULT_RETRY_CONFIG.maxDelay, } = config;
+    return async (...args) => {
+        let lastError;
+        for (let i = 0; i < attempts; i++) {
+            try {
+                return await fn(...args);
+            }
+            catch (error) {
+                lastError = error;
+                if (i < attempts - 1) {
+                    const delayMs = calculateRetryDelay(backoffStrategy, i, baseDelay, jitter, maxDelay);
+                    await delay(delayMs);
+                }
+            }
+        }
+        throw lastError instanceof Error ? lastError : new Error(String(lastError));
+    };
+}
+
 /**
  * @license
  * checksum.ts
@@ -846,6 +1079,8 @@ else {
     TextEncoderRef = TextEncoder;
 }
 /**
+ * @internal
+ *
  * FNV-1a 32-bit hash function
  * Produces a fast, non-cryptographic checksum for strings
  *
@@ -872,5 +1107,49 @@ function checksum(str) {
     return hash.toString(16).padStart(8, '0');
 }
 
-export { Emitter, MonterosaError, calculatePercentage, checkAvailability, checksum, clear, createError, delay, fromEntries, getGlobal, getItem, getKey, memoizePromise, now, onTick, removeItem, setItem, setTimestamp, subscribe, throttle, tick };
-//# sourceMappingURL=index.esm.js.map
+/**
+ * @license
+ * @monterosa/sdk-util
+ *
+ * Copyright © 2026 Monterosa Productions Limited. All rights reserved.
+ *
+ * More details on the license can be found at https://www.monterosa.co/sdk/license
+ */
+/* eslint-disable no-bitwise */
+const UUID_V4_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+/**
+ * Generates a RFC 4122 version 4 UUID.
+ *
+ * Uses `crypto.randomUUID()` when available, falling back to
+ * `crypto.getRandomValues()` for older browsers.
+ *
+ * @returns A UUID v4 string
+ *
+ * @internal
+ */
+function generateUUID() {
+    if (typeof crypto.randomUUID === 'function') {
+        return crypto.randomUUID();
+    }
+    const bytes = crypto.getRandomValues(new Uint8Array(16));
+    bytes[6] = (bytes[6] & 0x0f) | 0x40; // version 4
+    bytes[8] = (bytes[8] & 0x3f) | 0x80; // variant 10
+    const hex = Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+/**
+ * Validates whether a string is a valid UUID v4.
+ *
+ * @param value - The string to validate
+ * @returns `true` if the string is a valid UUID v4
+ *
+ * @internal
+ */
+function isUUID(value) {
+    return UUID_V4_REGEX.test(value);
+}
+
+export { DEFAULT_RETRY_CONFIG, Emitter, MonterosaError, TaskQueue, calculatePercentage, checkAvailability, checksum, clear, createError, delay, fromEntries, generateUUID, getErrorMessage, getGlobal, getItem, getKey, isUUID, memoizePromise, now, onTick, removeItem, setItem, setTimestamp, subscribe, throttle, tick, withRetryAsync };
+//# sourceMappingURL=index.js.map