@monterosa/sdk-util 2.0.0-rc.3 → 2.0.0-rc.5

package/dist/sdk-util.d.ts

@@ -0,0 +1,513 @@
+/**
+ * Shared utilities including emitters, error handling, and storage helpers.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * @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
+ */
+declare type AsyncTask = () => Promise<void>;
+
+/**
+ * @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
+ */
+/**
+ * @internal
+ *
+ * The backoff strategy to use for retry attempts.
+ */
+export declare type BackoffStrategy = 'fixed' | 'incremental' | 'exponential';
+
+/**
+ * Calculate percentage of each value in the array.
+ *
+ * It uses Hamilton's method, also known as the method of largest remainder.
+ * It is a system used for distributing vote percentages among different
+ * options (like candidates or choices) based on their vote counts. It ensures
+ * that each option receives at least its lower quota of percentage points, and
+ * any remaining percentage points are allocated to those with the largest
+ * fractional remainders. This method is used in the US Electoral College.
+ *
+ * @param values - Array of number values to calculate percentage for
+ * @returns Array of percentages, where the sum of the array is 100%
+ */
+export declare const calculatePercentage: (values: number[]) => number[];
+
+/**
+ * Checks locastorage availability.
+ * Based on MDN article: https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API/Using_the_Web_Storage_API
+ * and Paul Irish gists: https://gist.github.com/paulirish/5558557
+ *
+ * @internal
+ *
+ * @returns boolean
+ */
+export declare function checkAvailability(): boolean;
+
+/**
+ * @license
+ * checksum.ts
+ * util
+ *
+ * Copyright © 2025 Monterosa. All rights reserved.
+ *
+ * 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
+ *
+ * @param str - The input string to hash
+ *
+ * @returns 8-character hexadecimal string representing the hash
+ */
+export declare function checksum(str: string): string;
+
+/**
+ * @internal
+ */
+export declare function clear(): void;
+
+/**
+ * @internal
+ */
+export declare function createError<ErrorCode extends string>(code: ErrorCode, messages: ErrorMap<ErrorCode>, ...params: any[]): MonterosaError;
+
+/**
+ * @internal
+ *
+ * Default configuration values for retry logic.
+ */
+export declare const DEFAULT_RETRY_CONFIG: Required<RetryConfig>;
+
+/**
+ * @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>;
+
+/**
+ * @internal
+ *
+ * Event emitter. Provides subscribe/unsubscribe pattern used throughout
+ * the SDK for observable state changes.
+ */
+export declare class Emitter {
+    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;
+}
+
+declare type ErrorMap<ErrorCode extends string> = {
+    readonly [K in ErrorCode]: (...rest: any[]) => string;
+};
+
+/**
+ * @license
+ * fromentries.ts
+ * util
+ *
+ * Copyright © 2023 Monterosa Productions Limited. All rights reserved.
+ *
+ * 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>;
+
+/**
+ * @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
+ */
+/**
+ * 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
+ */
+export declare function generateUUID(): string;
+
+/**
+ * @internal
+ */
+export declare function getErrorMessage(err: unknown): string;
+
+/**
+ * @license
+ * @monterosa/sdk-util
+ *
+ * Copyright © 2022 Monterosa Productions Limited. All rights reserved.
+ *
+ * More details on the license can be found at https://www.monterosa.co/sdk/license
+ */
+/**
+ * @preserve
+ * Global object polyfill.
+ * Based on MDN article: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis
+ *
+ * @internal
+ *
+ * @returns typeof globalThis
+ */
+export declare function getGlobal(): typeof globalThis;
+
+/**
+ * @internal
+ */
+export declare function getItem(key: string): string | null;
+
+/**
+ * @internal
+ */
+export declare const getKey: (name: string) => string;
+
+/**
+ * @license
+ * @monterosa/sdk-util
+ *
+ * Copyright © 2022 Monterosa Productions Limited. All rights reserved.
+ *
+ * More details on the license can be found at https://www.monterosa.co/sdk/license
+ */
+declare type Handler = (...args: any[]) => void;
+
+/**
+ * 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
+ */
+export declare function isUUID(value: string): boolean;
+
+/**
+ * Creates a function that memoizes the result of `func`.
+ *
+ * @internal
+ *
+ * @param func - A function that returns a promise. The results of its work will be memoized.
+ * @param resolver - A function that determines the cache key.
+ * @param config - A configuration object with the following optional properties:
+ *   `clearOnResolve` - Deletes memoized result upon promise resolve. Defaults to `false`.
+ *   `clearOnReject` - Deletes memoized result upon promise reject. Defaults to `true`.
+ */
+export declare const memoizePromise: <T>(func: (...args: any[]) => Promise<T>, resolver: (...args: any[]) => any, config?: {
+    clearOnResolve?: boolean;
+    clearOnReject?: boolean;
+}) => (...args: any[]) => Promise<T>;
+
+/**
+ * @license
+ * @monterosa/sdk-util
+ *
+ * Copyright © 2022 Monterosa Productions Limited. All rights reserved.
+ *
+ * More details on the license can be found at https://www.monterosa.co/sdk/license
+ */
+/**
+ * MonterosaError extends the standard JavaScript `Error` object. It has
+ * an error code so that users can identify the error. It also has its
+ * own specific `name` "MonterosaError".
+ */
+export declare class MonterosaError extends Error {
+    /**
+     * The name property represents a name for the type of error.
+     */
+    readonly name = "MonterosaError";
+    /**
+     * Error code string
+     */
+    readonly code: string;
+    /**
+     * @param code - Error code string
+     * @param message - A descriptive message for the error
+     */
+    constructor(code: string, message: string);
+}
+
+/**
+ * Returns current timestamp that is preserved by `tick()` function
+ *
+ * @returns Current timestamp in seconds
+ */
+export declare function now(): number;
+
+/**
+ * Subscribes listener to the timestamp increment
+ *
+ * @param callback - A handler that executes when the timestamp is incremented
+ *
+ * @returns A function that unsubscribes the listener
+ */
+export declare function onTick(callback: (timestamp: number) => void): Unsubscribe;
+
+/**
+ * @internal
+ */
+export declare function removeItem(key: string): void;
+
+/**
+ * @internal
+ *
+ * Configuration options for retry logic with backoff strategies.
+ */
+export declare interface RetryConfig {
+    /**
+     * The backoff strategy to use.
+     *
+     * @default 'exponential'
+     */
+    backoffStrategy?: BackoffStrategy;
+    /**
+     * The number of attempts before failing.
+     *
+     * @default 3
+     */
+    attempts?: number;
+    /**
+     * The base delay in milliseconds for retry attempts.
+     *
+     * @default 500
+     */
+    baseDelay?: number;
+    /**
+     * The maximum jitter to add to the delay in milliseconds.
+     *
+     * @default 500
+     */
+    jitter?: number;
+    /**
+     * The maximum delay in milliseconds for retry attempts.
+     *
+     * @default 10_000
+     */
+    maxDelay?: number;
+}
+
+/**
+ * @internal
+ */
+export declare function setItem(key: string, value: string): void;
+
+/**
+ * @internal
+ *
+ * Sets or updates current timestamp
+ *
+ * @param timestamp - Current timestamp in seconds
+ */
+export declare function setTimestamp(timestamp: number): void;
+
+/**
+ * @internal
+ */
+export declare interface Subscribe {
+    (emitter: Emitter, event: string, callback: (...args: any[]) => void): Unsubscribe;
+}
+
+/**
+ * @internal
+ */
+export declare const subscribe: Subscribe;
+
+/**
+ * @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.
+ */
+export declare class TaskQueue {
+    private current;
+    private queue;
+    private paused;
+    enqueue(fn: AsyncTask): void;
+    enqueueFront(fn: AsyncTask): void;
+    pause(): void;
+    resume(): void;
+    private process;
+    get length(): number;
+    isEmpty(): boolean;
+    hasActiveTask(): boolean;
+    clear(): void;
+}
+
+/**
+ * @license
+ * @monterosa/sdk-util
+ *
+ * Copyright © 2022 Monterosa Productions Limited. All rights reserved.
+ *
+ * More details on the license can be found at https://www.monterosa.co/sdk/license
+ */
+/**
+ * Creates a throttled function that only invokes `func` at most once per
+ * every `wait` milliseconds. The throttled function comes with a `cancel`
+ * method to cancel delayed `func` invocations and a `flush` method to
+ * immediately invoke them. Provide `options` to indicate whether `func`
+ * should be invoked on the leading and/or trailing edge of the `wait`
+ * timeout. The `func` is invoked with the last arguments provided to the
+ * throttled function. Subsequent calls to the throttled function return the
+ * result of the last `func` invocation.
+ *
+ * **Note:** If `leading` and `trailing` options are `true`, `func` is
+ * invoked on the trailing edge of the timeout only if the throttled function
+ * is invoked more than once during the `wait` timeout.
+ *
+ * If `wait` is `0` and `leading` is `false`, `func` invocation is deferred
+ * until to the next tick, similar to `setTimeout` with a timeout of `0`.
+ *
+ * See [David Corbacho's article](https://css-tricks.com/debouncing-throttling-explained-examples/)
+ * for details over the differences between `_.throttle` and `_.debounce`.
+ *
+ * @internal
+ *
+ * @static
+ * @memberOf _
+ * @since 0.1.0
+ * @category Function
+ * @param {Function} func The function to throttle.
+ * @param {number} [wait=0] The number of milliseconds to throttle invocations to.
+ * @param {Object} [options={}] The options object.
+ * @param {boolean} [options.leading=true]
+ *  Specify invoking on the leading edge of the timeout.
+ * @param {boolean} [options.trailing=true]
+ *  Specify invoking on the trailing edge of the timeout.
+ * @returns {Function} Returns the new throttled function.
+ * @example
+ *
+ * // Avoid excessively updating the position while scrolling.
+ * jQuery(window).on('scroll', _.throttle(updatePosition, 100));
+ *
+ * // Invoke `renewToken` when the click event is fired, but not more than once every 5 minutes.
+ * var throttled = _.throttle(renewToken, 300000, { 'trailing': false });
+ * jQuery(element).on('click', throttled);
+ *
+ * // Cancel the trailing throttled invocation.
+ * jQuery(window).on('popstate', throttled.cancel);
+ */
+export declare function throttle(func: any, wait: any, options: any): {
+    (): any;
+    cancel: () => void;
+    flush: () => any;
+};
+
+/**
+ * @internal
+ *
+ * Main function that maintains current timestamp
+ */
+export declare function tick(): void;
+
+/**
+ * The unsubscribe function. When it is called, the previously set event
+ * listener is removed. It is returned by every observer functions
+ *
+ * @example
+ * ```typescript
+ * const unsubscribe: Unsubscribe = onElementPublished((element) => {
+ *   console.log('Element published', element);
+ * });
+ *
+ * unsubscribe();
+ * ```
+ */
+export declare interface Unsubscribe {
+    (): void;
+}
+
+/**
+ * @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));
+ */
+export declare function withRetryAsync<TArgs extends any[], TResult>(fn: (...args: TArgs) => Promise<TResult>, config?: RetryConfig): (...args: TArgs) => Promise<TResult>;
+
+export { }

package/dist/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.23.0"
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monterosa/sdk-util",
-  "version": "2.0.0-rc.3",
+  "version": "2.0.0-rc.5",
   "description": "Monterosa JS SDK / Utils",
   "author": "Monterosa Productions Limited <hello@monterosa.co.uk> (https://www.monterosa.co/)",
   "main": "./dist/index.cjs",
@@ -50,5 +50,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "d692ad26af0b5ea7cd7b664168bffa069f9ab911"
+  "gitHead": "4f697a9733d36fb689a35b8e1dd6d589a9ae284c"
 }