@kikiutils/shared 18.0.1 → 18.2.0

package/dist/event-awaiter.js.map

@@ -1 +1 @@
-{"version":3,"file":"event-awaiter.js","names":["#promiseResolvers"],"sources":["../src/event-awaiter.ts"],"sourcesContent":["/**\n * EventAwaiter provides a mechanism to wait for events (by key) asynchronously.\n *\n * This class allows multiple consumers to `wait` for a specific key\n * and be resolved when `trigger` is called for that key, or automatically\n * resolved with `undefined` if a timeout occurs or an AbortSignal is triggered.\n *\n * Typical use cases include long-polling, request coordination,\n * or implementing event-driven primitives in applications or services.\n *\n * @template T - The type of value that will be resolved when the event is triggered\n */\nexport class EventAwaiter<T> {\n    #promiseResolvers = new Map<string, ((value: PromiseLike<T | undefined> | T | undefined) => void)[]>();\n\n    /**\n     * Triggers all pending promises waiting for the given key.\n     * Each promise will be resolved with the provided value.\n     *\n     * @param {string} key - Identifier for the awaited event\n     * @param {T | undefined} value - The value to resolve the awaiting promises with.\n     * May be `undefined` to indicate no result or a timeout-like behavior.\n     */\n    trigger(key: string, value: T | undefined) {\n        const resolvers = this.#promiseResolvers.get(key);\n        if (resolvers) {\n            this.#promiseResolvers.delete(key);\n            resolvers?.forEach((resolve) => resolve(value));\n        }\n    }\n\n    /**\n     * Triggers and resolves all pending promises across all keys.\n     *\n     * This is typically used during shutdown or cleanup to ensure that\n     * no consumer is left waiting indefinitely.\n     *\n     * @param {T | undefined} [value] - Optional value to resolve all waiters with.\n     * Defaults to `undefined`, which usually indicates cancellation or shutdown.\n     */\n    triggerAll(value: T | undefined = undefined) {\n        for (const [_, resolvers] of this.#promiseResolvers.entries()) resolvers.forEach((resolve) => resolve(value));\n        this.#promiseResolvers.clear();\n    }\n\n    /**\n     * Waits for an event associated with the given key.\n     *\n     * The returned promise will resolve when:\n     *  - `trigger(key)` is called, in which case it resolves with the provided value.\n     *  - The optional timeout is reached, in which case it resolves with `undefined`.\n     *  - The optional `AbortSignal` is aborted, in which case it resolves with `undefined`.\n     *\n     * Behavior when multiple waiters exist for the same key:\n     *  - Default (no mode): multiple waiters are allowed, all will be resolved when triggered.\n     *  - `strict` mode: throws an error if a waiter already exists for the given key.\n     *  - `override` mode: cancels all existing waiters (resolving them with `undefined`)\n     *    and only keeps the latest one.\n     *\n     * @param {string} key - Identifier for the awaited event\n     * @param {number} [timeoutMs] - Optional timeout (in milliseconds).\n     * If reached, the promise resolves with `undefined`.\n     * @param {'override' | 'strict'} [mode] - Optional behavior mode for handling multiple waiters\n     * @param {AbortSignal} [signal] - Optional AbortSignal. If aborted, the promise resolves with `undefined`\n     *\n     * @returns {Promise<T | undefined>} A promise that resolves with the triggered value,\n     * or `undefined` if timeout or abort occurs\n     */\n    wait(key: string, timeoutMs?: number, mode?: 'override' | 'strict', signal?: AbortSignal) {\n        return new Promise<T | undefined>((resolve) => {\n            const resolvers = this.#promiseResolvers.get(key) || [];\n            if (resolvers.length) {\n                switch (mode) {\n                    case 'override':\n                        resolvers.forEach((r) => r(undefined));\n                        resolvers.length = 0;\n                        break;\n                    case 'strict':\n                        throw new Error(`Duplicate wait detected for key: ${key}`);\n                }\n            }\n\n            resolvers.push(resolve);\n            this.#promiseResolvers.set(key, resolvers);\n            if (timeoutMs != null) {\n                setTimeout(\n                    () => {\n                        const resolvers = this.#promiseResolvers.get(key);\n                        if (resolvers?.includes(resolve)) {\n                            resolve(undefined);\n                            const newResolvers = resolvers.filter((r) => r !== resolve);\n                            if (newResolvers.length) this.#promiseResolvers.set(key, newResolvers);\n                            else this.#promiseResolvers.delete(key);\n                        }\n                    },\n                    timeoutMs,\n                );\n            }\n\n            if (signal) {\n                signal.addEventListener(\n                    'abort',\n                    () => {\n                        const resolvers = this.#promiseResolvers.get(key);\n                        if (resolvers?.includes(resolve)) {\n                            resolve(undefined);\n                            const newResolvers = resolvers.filter((r) => r !== resolve);\n                            if (newResolvers.length) this.#promiseResolvers.set(key, newResolvers);\n                            else this.#promiseResolvers.delete(key);\n                        }\n                    },\n                    { once: true },\n                );\n            }\n        });\n    }\n\n    /**\n     * Waits for an event in strict mode.\n     * Only one waiter is allowed per key. If another waiter already exists,\n     * this method will throw an error.\n     *\n     * @param {string} key - Identifier for the awaited event\n     * @param {number} [timeoutMs] - Optional timeout (in milliseconds).\n     * If reached, the promise resolves with `undefined`.\n     * @param {AbortSignal} [signal] - Optional AbortSignal. If aborted, the promise resolves with `undefined`\n     */\n    waitExclusive(key: string, timeoutMs?: number, signal?: AbortSignal) {\n        return this.wait(key, timeoutMs, 'strict', signal);\n    }\n\n    /**\n     * Waits for an event in override mode.\n     * If another waiter already exists for the given key, it will be canceled\n     * (resolved with `undefined`) and replaced by the new waiter.\n     *\n     * @param {string} key - Identifier for the awaited event\n     * @param {number} [timeoutMs] - Optional timeout (in milliseconds).\n     * If reached, the promise resolves with `undefined`.\n     * @param {AbortSignal} [signal] - Optional AbortSignal. If aborted, the promise resolves with `undefined`\n     */\n    waitLatest(key: string, timeoutMs?: number, signal?: AbortSignal) {\n        return this.wait(key, timeoutMs, 'override', signal);\n    }\n}\n"],"mappings":";;;;;;;;;;;;;AAYA,IAAa,eAAb,MAA6B;CACzB,oCAAoB,IAAI,IAA6E;;;;;;;;;CAUrG,QAAQ,KAAa,OAAsB;EACvC,MAAM,YAAY,KAAKA,kBAAkB,IAAI,GAAG;EAChD,IAAI,WAAW;GACX,KAAKA,kBAAkB,OAAO,GAAG;GACjC,WAAW,SAAS,YAAY,QAAQ,KAAK,CAAC;EAClD;CACJ;;;;;;;;;;CAWA,WAAW,QAAuB,KAAA,GAAW;EACzC,KAAK,MAAM,CAAC,GAAG,cAAc,KAAKA,kBAAkB,QAAQ,GAAG,UAAU,SAAS,YAAY,QAAQ,KAAK,CAAC;EAC5G,KAAKA,kBAAkB,MAAM;CACjC;;;;;;;;;;;;;;;;;;;;;;;;CAyBA,KAAK,KAAa,WAAoB,MAA8B,QAAsB;EACtF,OAAO,IAAI,SAAwB,YAAY;GAC3C,MAAM,YAAY,KAAKA,kBAAkB,IAAI,GAAG,KAAK,CAAC;GACtD,IAAI,UAAU,QACV,QAAQ,MAAR;IACI,KAAK;KACD,UAAU,SAAS,MAAM,EAAE,KAAA,CAAS,CAAC;KACrC,UAAU,SAAS;KACnB;IACJ,KAAK,UACD,MAAM,IAAI,MAAM,oCAAoC,KAAK;GACjE;GAGJ,UAAU,KAAK,OAAO;GACtB,KAAKA,kBAAkB,IAAI,KAAK,SAAS;GACzC,IAAI,aAAa,MACb,iBACU;IACF,MAAM,YAAY,KAAKA,kBAAkB,IAAI,GAAG;IAChD,IAAI,WAAW,SAAS,OAAO,GAAG;KAC9B,QAAQ,KAAA,CAAS;KACjB,MAAM,eAAe,UAAU,QAAQ,MAAM,MAAM,OAAO;KAC1D,IAAI,aAAa,QAAQ,KAAKA,kBAAkB,IAAI,KAAK,YAAY;UAChE,KAAKA,kBAAkB,OAAO,GAAG;IAC1C;GACJ,GACA,SACJ;GAGJ,IAAI,QACA,OAAO,iBACH,eACM;IACF,MAAM,YAAY,KAAKA,kBAAkB,IAAI,GAAG;IAChD,IAAI,WAAW,SAAS,OAAO,GAAG;KAC9B,QAAQ,KAAA,CAAS;KACjB,MAAM,eAAe,UAAU,QAAQ,MAAM,MAAM,OAAO;KAC1D,IAAI,aAAa,QAAQ,KAAKA,kBAAkB,IAAI,KAAK,YAAY;UAChE,KAAKA,kBAAkB,OAAO,GAAG;IAC1C;GACJ,GACA,EAAE,MAAM,KAAK,CACjB;EAER,CAAC;CACL;;;;;;;;;;;CAYA,cAAc,KAAa,WAAoB,QAAsB;EACjE,OAAO,KAAK,KAAK,KAAK,WAAW,UAAU,MAAM;CACrD;;;;;;;;;;;CAYA,WAAW,KAAa,WAAoB,QAAsB;EAC9D,OAAO,KAAK,KAAK,KAAK,WAAW,YAAY,MAAM;CACvD;AACJ"}
+{"version":3,"file":"event-awaiter.js","names":[],"sources":["../src/event-awaiter.ts"],"sourcesContent":["/**\n * An asynchronous keyed event rendezvous for one or more waiting consumers.\n *\n * @remarks\n * Triggers resolve the currently registered waiters; values are not retained for future waits.\n * Timeouts and subsequent abort events resolve affected waiters with `undefined`.\n * Use `triggerAll` to resolve pending waits during cleanup. Timers and abort listeners are not proactively\n * removed by triggers, so they may remain until their timeout or abort event occurs.\n *\n * @typeParam T - The value delivered to waiting consumers.\n */\nexport class EventAwaiter<T> {\n    // Private instance properties\n    #promiseResolvers = new Map<string, ((value: PromiseLike<T | undefined> | T | undefined) => void)[]>();\n\n    // Public instance methods\n\n    /**\n     * Resolves all currently pending waits for a key with the supplied value.\n     *\n     * @param key - The event identifier; a key without pending waits has no effect.\n     * @param value - The delivered value; `undefined` indicates no result.\n     */\n    trigger(key: string, value: T | undefined) {\n        const resolvers = this.#promiseResolvers.get(key);\n        if (resolvers) {\n            this.#promiseResolvers.delete(key);\n            resolvers?.forEach((resolve) => resolve(value));\n        }\n    }\n\n    /**\n     * Resolves all currently pending waits and clears their registrations.\n     *\n     * @param value - The delivered value; omission resolves all pending waits with `undefined`.\n     */\n    triggerAll(value: T | undefined = undefined) {\n        for (const [_, resolvers] of this.#promiseResolvers.entries()) resolvers.forEach((resolve) => resolve(value));\n        this.#promiseResolvers.clear();\n    }\n\n    /**\n     * Waits for a trigger associated with a key.\n     *\n     * @remarks\n     * By default, multiple waiters share a key and all receive the next trigger value.\n     * `strict` mode rejects duplicate waits; `override` mode resolves existing waits with `undefined` before\n     * registering the new wait. Timeout and abort remove only the affected waiter's registration.\n     * An already aborted signal is not checked; only an abort event emitted after registration ends the wait.\n     * Without a timeout or subsequent abort, the wait remains pending until a trigger arrives.\n     *\n     * @param key - The event identifier to wait for.\n     * @param timeoutMs - The optional timeout in milliseconds, using native `setTimeout` timing rules.\n     * @param mode - The policy for existing waiters; omission allows multiple waiters.\n     * @param signal - A signal whose subsequent abort event ends this wait.\n     *\n     * @returns A promise resolving to the triggered value, or `undefined` after timeout, abort, or replacement.\n     *\n     * @throws Error through promise rejection if `strict` mode encounters an existing waiter.\n     */\n    wait(key: string, timeoutMs?: number, mode?: 'override' | 'strict', signal?: AbortSignal) {\n        return new Promise<T | undefined>((resolve) => {\n            const resolvers = this.#promiseResolvers.get(key) || [];\n            if (resolvers.length) {\n                switch (mode) {\n                    case 'override':\n                        resolvers.forEach((r) => r(undefined));\n                        resolvers.length = 0;\n                        break;\n                    case 'strict':\n                        throw new Error(`Duplicate wait detected for key: ${key}`);\n                }\n            }\n\n            resolvers.push(resolve);\n            this.#promiseResolvers.set(key, resolvers);\n            if (timeoutMs != null) {\n                setTimeout(\n                    () => {\n                        const resolvers = this.#promiseResolvers.get(key);\n                        if (resolvers?.includes(resolve)) {\n                            resolve(undefined);\n                            const newResolvers = resolvers.filter((r) => r !== resolve);\n                            if (newResolvers.length) this.#promiseResolvers.set(key, newResolvers);\n                            else this.#promiseResolvers.delete(key);\n                        }\n                    },\n                    timeoutMs,\n                );\n            }\n\n            if (signal) {\n                signal.addEventListener(\n                    'abort',\n                    () => {\n                        const resolvers = this.#promiseResolvers.get(key);\n                        if (resolvers?.includes(resolve)) {\n                            resolve(undefined);\n                            const newResolvers = resolvers.filter((r) => r !== resolve);\n                            if (newResolvers.length) this.#promiseResolvers.set(key, newResolvers);\n                            else this.#promiseResolvers.delete(key);\n                        }\n                    },\n                    { once: true },\n                );\n            }\n        });\n    }\n\n    /**\n     * Waits for a key while rejecting duplicate registrations.\n     *\n     * @param key - The event identifier to wait for.\n     * @param timeoutMs - The optional timeout in milliseconds.\n     * @param signal - A signal whose subsequent abort event ends this wait; an already aborted signal is not checked.\n     *\n     * @returns A promise resolving to the triggered value, or `undefined` on timeout or subsequent abort.\n     *\n     * @throws Error through promise rejection if the key already has a pending waiter.\n     *\n     * @see {@link EventAwaiter.wait}\n     */\n    waitExclusive(key: string, timeoutMs?: number, signal?: AbortSignal) {\n        return this.wait(key, timeoutMs, 'strict', signal);\n    }\n\n    /**\n     * Replaces existing waiters for a key and waits for its next trigger.\n     *\n     * @remarks\n     * Existing waiters resolve with `undefined` before the new waiter is registered.\n     *\n     * @param key - The event identifier to wait for.\n     * @param timeoutMs - The optional timeout in milliseconds.\n     * @param signal - A signal whose subsequent abort event ends this wait; an already aborted signal is not checked.\n     *\n     * @returns A promise resolving to the triggered value, or `undefined` on timeout, subsequent abort, or replacement.\n     *\n     * @see {@link EventAwaiter.wait}\n     */\n    waitLatest(key: string, timeoutMs?: number, signal?: AbortSignal) {\n        return this.wait(key, timeoutMs, 'override', signal);\n    }\n}\n"],"mappings":";;;;;;;;;;;;AAWA,IAAa,eAAb,MAA6B;CAEzB,oCAAoB,IAAI,IAA6E;;;;;;;CAUrG,QAAQ,KAAa,OAAsB;EACvC,MAAM,YAAY,KAAK,kBAAkB,IAAI,GAAG;EAChD,IAAI,WAAW;GACX,KAAK,kBAAkB,OAAO,GAAG;GACjC,WAAW,SAAS,YAAY,QAAQ,KAAK,CAAC;EAClD;CACJ;;;;;;CAOA,WAAW,QAAuB,KAAA,GAAW;EACzC,KAAK,MAAM,CAAC,GAAG,cAAc,KAAK,kBAAkB,QAAQ,GAAG,UAAU,SAAS,YAAY,QAAQ,KAAK,CAAC;EAC5G,KAAK,kBAAkB,MAAM;CACjC;;;;;;;;;;;;;;;;;;;;CAqBA,KAAK,KAAa,WAAoB,MAA8B,QAAsB;EACtF,OAAO,IAAI,SAAwB,YAAY;GAC3C,MAAM,YAAY,KAAK,kBAAkB,IAAI,GAAG,KAAK,CAAC;GACtD,IAAI,UAAU,QACV,QAAQ,MAAR;IACI,KAAK;KACD,UAAU,SAAS,MAAM,EAAE,KAAA,CAAS,CAAC;KACrC,UAAU,SAAS;KACnB;IACJ,KAAK,UACD,MAAM,IAAI,MAAM,oCAAoC,KAAK;GACjE;GAGJ,UAAU,KAAK,OAAO;GACtB,KAAK,kBAAkB,IAAI,KAAK,SAAS;GACzC,IAAI,aAAa,MACb,iBACU;IACF,MAAM,YAAY,KAAK,kBAAkB,IAAI,GAAG;IAChD,IAAI,WAAW,SAAS,OAAO,GAAG;KAC9B,QAAQ,KAAA,CAAS;KACjB,MAAM,eAAe,UAAU,QAAQ,MAAM,MAAM,OAAO;KAC1D,IAAI,aAAa,QAAQ,KAAK,kBAAkB,IAAI,KAAK,YAAY;UAChE,KAAK,kBAAkB,OAAO,GAAG;IAC1C;GACJ,GACA,SACJ;GAGJ,IAAI,QACA,OAAO,iBACH,eACM;IACF,MAAM,YAAY,KAAK,kBAAkB,IAAI,GAAG;IAChD,IAAI,WAAW,SAAS,OAAO,GAAG;KAC9B,QAAQ,KAAA,CAAS;KACjB,MAAM,eAAe,UAAU,QAAQ,MAAM,MAAM,OAAO;KAC1D,IAAI,aAAa,QAAQ,KAAK,kBAAkB,IAAI,KAAK,YAAY;UAChE,KAAK,kBAAkB,OAAO,GAAG;IAC1C;GACJ,GACA,EAAE,MAAM,KAAK,CACjB;EAER,CAAC;CACL;;;;;;;;;;;;;;CAeA,cAAc,KAAa,WAAoB,QAAsB;EACjE,OAAO,KAAK,KAAK,KAAK,WAAW,UAAU,MAAM;CACrD;;;;;;;;;;;;;;;CAgBA,WAAW,KAAa,WAAoB,QAAsB;EAC9D,OAAO,KAAK,KAAK,KAAK,WAAW,YAAY,MAAM;CACvD;AACJ"}

package/dist/general.d.ts

@@ -1,31 +1,36 @@
 //#region src/general.d.ts
 /**
- * Extracts the first value from an array or returns the value itself if it's not an array.
+ * Returns the first array element or the input value, with a nullish fallback.
  *
- * - If `value` is an array, returns the first element.
- * - If `value` is not an array, returns `value` directly.
- * - If the result is `null` or `undefined`, and `defaultValue` is provided, returns `defaultValue` instead.
+ * @remarks
+ * An empty array, `null`, or `undefined` selects the fallback; omission of a fallback yields `undefined`.
+ * The input and selected values are not copied or changed.
  *
- * @template T - The type of the input value(s)
- * @template D - The type of the default value (if provided)
+ * @typeParam T - The input value or array element type.
+ * @typeParam D - The fallback type when the fallback overload is used.
  *
- * @param {T | T[]} value - A single value or an array of values
- * @param {D} [defaultValue] - A fallback value if the result is `null` or `undefined`
+ * @param value - A single value or an array of values.
+ * @param defaultValue - The fallback returned when the selected value is nullish.
  *
- * @returns {T | D | undefined} The first value or the fallback
+ * @returns The selected non-nullish value, or the fallback without copying either value.
  *
  * @example
- * ```typescript
+ *
+ * ```ts
  * import { extractFirstValue } from '@kikiutils/shared/general';
  *
- * console.log(extractFirstValue([1, 2, 3])); // 1
- * console.log(extractFirstValue('hello'));  // hello
- * console.log(extractFirstValue([], 'default')); // default
- * console.log(extractFirstValue(undefined, 'fallback')); // fallback
+ * console.log(extractFirstValue([
+ *     1,
+ *     2,
+ *     3,
+ * ])); // => 1
+ *
+ * console.log(extractFirstValue('hello')); // => 'hello'
+ * console.log(extractFirstValue([], 'default')); // => 'default'
+ * console.log(extractFirstValue(undefined, 'fallback')); // => 'fallback'
  * ```
  */
-declare function extractFirstValue<T>(value: T | T[]): T | undefined;
-declare function extractFirstValue<T, D>(value: T | T[], defaultValue: D): D | NonNullable<T>;
+export declare function extractFirstValue<T>(value: T | T[]): T | undefined;
+export declare function extractFirstValue<T, D>(value: T | T[], defaultValue: D): D | NonNullable<T>;
 //#endregion
-export { extractFirstValue };
 //# sourceMappingURL=general.d.ts.map

package/dist/general.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"general.d.ts","names":[],"sources":["../src/general.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;iBA2BgB,kBAAkB,GAAG,OAAO,IAAI,MAAM;iBACtC,kBAAkB,GAAG,GAAG,OAAO,IAAI,KAAK,cAAc,IAAI,IAAI,YAAY"}
+{"version":3,"file":"general.d.ts","names":[],"sources":["../src/general.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAiCgB,kBAAkB,GAAG,OAAO,IAAI,MAAM;wBACtC,kBAAkB,GAAG,GAAG,OAAO,IAAI,KAAK,cAAc,IAAI,IAAI,YAAY"}

package/dist/general.js.map

@@ -1 +1 @@
-{"version":3,"file":"general.js","names":[],"sources":["../src/general.ts"],"sourcesContent":["/* eslint-disable jsdoc/check-param-names */\n\n/**\n * Extracts the first value from an array or returns the value itself if it's not an array.\n *\n * - If `value` is an array, returns the first element.\n * - If `value` is not an array, returns `value` directly.\n * - If the result is `null` or `undefined`, and `defaultValue` is provided, returns `defaultValue` instead.\n *\n * @template T - The type of the input value(s)\n * @template D - The type of the default value (if provided)\n *\n * @param {T | T[]} value - A single value or an array of values\n * @param {D} [defaultValue] - A fallback value if the result is `null` or `undefined`\n *\n * @returns {T | D | undefined} The first value or the fallback\n *\n * @example\n * ```typescript\n * import { extractFirstValue } from '@kikiutils/shared/general';\n *\n * console.log(extractFirstValue([1, 2, 3])); // 1\n * console.log(extractFirstValue('hello'));  // hello\n * console.log(extractFirstValue([], 'default')); // default\n * console.log(extractFirstValue(undefined, 'fallback')); // fallback\n * ```\n */\nexport function extractFirstValue<T>(value: T | T[]): T | undefined;\nexport function extractFirstValue<T, D>(value: T | T[], defaultValue: D): D | NonNullable<T>;\nexport function extractFirstValue<T, D>(value: T | T[], defaultValue?: D) {\n    return (Array.isArray(value) ? value[0] : value) ?? defaultValue;\n}\n\n/* eslint-enable jsdoc/check-param-names */\n"],"mappings":";AA6BA,SAAgB,kBAAwB,OAAgB,cAAkB;CACtE,QAAQ,MAAM,QAAQ,KAAK,IAAI,MAAM,KAAK,UAAU;AACxD"}
+{"version":3,"file":"general.js","names":[],"sources":["../src/general.ts"],"sourcesContent":["/* eslint-disable jsdoc/check-param-names */\n\n/**\n * Returns the first array element or the input value, with a nullish fallback.\n *\n * @remarks\n * An empty array, `null`, or `undefined` selects the fallback; omission of a fallback yields `undefined`.\n * The input and selected values are not copied or changed.\n *\n * @typeParam T - The input value or array element type.\n * @typeParam D - The fallback type when the fallback overload is used.\n *\n * @param value - A single value or an array of values.\n * @param defaultValue - The fallback returned when the selected value is nullish.\n *\n * @returns The selected non-nullish value, or the fallback without copying either value.\n *\n * @example\n *\n * ```ts\n * import { extractFirstValue } from '@kikiutils/shared/general';\n *\n * console.log(extractFirstValue([\n *     1,\n *     2,\n *     3,\n * ])); // => 1\n *\n * console.log(extractFirstValue('hello')); // => 'hello'\n * console.log(extractFirstValue([], 'default')); // => 'default'\n * console.log(extractFirstValue(undefined, 'fallback')); // => 'fallback'\n * ```\n */\nexport function extractFirstValue<T>(value: T | T[]): T | undefined;\nexport function extractFirstValue<T, D>(value: T | T[], defaultValue: D): D | NonNullable<T>;\nexport function extractFirstValue<T, D>(value: T | T[], defaultValue?: D) {\n    return (Array.isArray(value) ? value[0] : value) ?? defaultValue;\n}\n\n/* eslint-enable jsdoc/check-param-names */\n"],"mappings":";AAmCA,SAAgB,kBAAwB,OAAgB,cAAkB;CACtE,QAAQ,MAAM,QAAQ,KAAK,IAAI,MAAM,KAAK,UAAU;AACxD"}

package/dist/hash.d.ts

@@ -2,63 +2,66 @@
 /**
  * Computes the SHA-3 hash of the given data using the 224-bit digest.
  *
- * @param {string | Uint8Array} data - The input data to hash
+ * @param data - The UTF-8 string or raw bytes to hash.
  *
- * @returns {string} The hexadecimal hash digest
+ * @returns The hexadecimal hash digest.
  *
  * @example
- * ```typescript
+ *
+ * ```ts
  * import { sha3224 } from '@kikiutils/shared/hash';
  *
- * console.log(sha3224('test')); // 3797bf0afbbfca4a7bbba7602a2b552746876517a7f9b7ce2db0ae7b
+ * console.log(sha3224('test')); // => 3797bf0afbbfca4a7bbba7602a2b552746876517a7f9b7ce2db0ae7b
  * ```
  */
-declare function sha3224(data: string | Uint8Array): string;
+export declare function sha3224(data: string | Uint8Array): string;
 /**
  * Computes the SHA-3 hash of the given data using the 256-bit digest.
  *
- * @param {string | Uint8Array} data - The input data to hash
+ * @param data - The UTF-8 string or raw bytes to hash.
  *
- * @returns {string} The hexadecimal hash digest
+ * @returns The hexadecimal hash digest.
  *
  * @example
- * ```typescript
+ *
+ * ```ts
  * import { sha3256 } from '@kikiutils/shared/hash';
  *
- * console.log(sha3256('test')); // 36f028580bb02cc8272a9a020f4200e346e276ae664e45ee80745574e2f5ab80
+ * console.log(sha3256('test')); // => 36f028580bb02cc8272a9a020f4200e346e276ae664e45ee80745574e2f5ab80
  * ```
  */
-declare function sha3256(data: string | Uint8Array): string;
+export declare function sha3256(data: string | Uint8Array): string;
 /**
  * Computes the SHA-3 hash of the given data using the 384-bit digest.
  *
- * @param {string | Uint8Array} data - The input data to hash
+ * @param data - The UTF-8 string or raw bytes to hash.
  *
- * @returns {string} The hexadecimal hash digest
+ * @returns The hexadecimal hash digest.
  *
  * @example
- * ```typescript
+ *
+ * ```ts
  * import { sha3384 } from '@kikiutils/shared/hash';
  *
- * console.log(sha3384('test')); // e516dabb23b6e30026863543282780a3ae0dccf05551cf0295178d7f...
+ * console.log(sha3384('test')); // => e516dabb23b6e30026863543282780a3ae0dccf05551cf0295178d7f...
  * ```
  */
-declare function sha3384(data: string | Uint8Array): string;
+export declare function sha3384(data: string | Uint8Array): string;
 /**
  * Computes the SHA-3 hash of the given data using the 512-bit digest.
  *
- * @param {string | Uint8Array} data - The input data to hash
+ * @param data - The UTF-8 string or raw bytes to hash.
  *
- * @returns {string} The hexadecimal hash digest
+ * @returns The hexadecimal hash digest.
  *
  * @example
- * ```typescript
+ *
+ * ```ts
  * import { sha3512 } from '@kikiutils/shared/hash';
  *
- * console.log(sha3512('test')); // 9ece086e9bac491fac5c1d1046ca11d737b92a2b2ebd93f005d7...
+ * console.log(sha3512('test')); // => 9ece086e9bac491fac5c1d1046ca11d737b92a2b2ebd93f005d7...
  * ```
  */
-declare function sha3512(data: string | Uint8Array): string;
+export declare function sha3512(data: string | Uint8Array): string;
 //#endregion
-export { sha3224, sha3256, sha3384, sha3512 };
 //# sourceMappingURL=hash.d.ts.map

package/dist/hash.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hash.d.ts","names":[],"sources":["../src/hash.ts"],"mappings":";;;;;;;;;;;;;;;iBAyBgB,QAAQ,eAAe;;;;;;;;;;;;;;;iBAkBvB,QAAQ,eAAe;;;;;;;;;;;;;;;iBAkBvB,QAAQ,eAAe;;;;;;;;;;;;;;;iBAkBvB,QAAQ,eAAe"}
+{"version":3,"file":"hash.d.ts","names":[],"sources":["../src/hash.ts"],"mappings":";;;;;;;;;;;;;;;;wBA0BgB,QAAQ,eAAe;;;;;;;;;;;;;;;;wBAmBvB,QAAQ,eAAe;;;;;;;;;;;;;;;;wBAmBvB,QAAQ,eAAe;;;;;;;;;;;;;;;;wBAmBvB,QAAQ,eAAe"}

package/dist/hash.js

@@ -4,15 +4,16 @@ import { bytesToHex, utf8ToBytes } from "@noble/hashes/utils.js";
 /**
 * Computes the SHA-3 hash of the given data using the 224-bit digest.
 *
-* @param {string | Uint8Array} data - The input data to hash
+* @param data - The UTF-8 string or raw bytes to hash.
 *
-* @returns {string} The hexadecimal hash digest
+* @returns The hexadecimal hash digest.
 *
 * @example
-* ```typescript
+*
+* ```ts
 * import { sha3224 } from '@kikiutils/shared/hash';
 *
-* console.log(sha3224('test')); // 3797bf0afbbfca4a7bbba7602a2b552746876517a7f9b7ce2db0ae7b
+* console.log(sha3224('test')); // => 3797bf0afbbfca4a7bbba7602a2b552746876517a7f9b7ce2db0ae7b
 * ```
 */
 function sha3224(data) {
@@ -21,15 +22,16 @@ function sha3224(data) {
 /**
 * Computes the SHA-3 hash of the given data using the 256-bit digest.
 *
-* @param {string | Uint8Array} data - The input data to hash
+* @param data - The UTF-8 string or raw bytes to hash.
 *
-* @returns {string} The hexadecimal hash digest
+* @returns The hexadecimal hash digest.
 *
 * @example
-* ```typescript
+*
+* ```ts
 * import { sha3256 } from '@kikiutils/shared/hash';
 *
-* console.log(sha3256('test')); // 36f028580bb02cc8272a9a020f4200e346e276ae664e45ee80745574e2f5ab80
+* console.log(sha3256('test')); // => 36f028580bb02cc8272a9a020f4200e346e276ae664e45ee80745574e2f5ab80
 * ```
 */
 function sha3256(data) {
@@ -38,15 +40,16 @@ function sha3256(data) {
 /**
 * Computes the SHA-3 hash of the given data using the 384-bit digest.
 *
-* @param {string | Uint8Array} data - The input data to hash
+* @param data - The UTF-8 string or raw bytes to hash.
 *
-* @returns {string} The hexadecimal hash digest
+* @returns The hexadecimal hash digest.
 *
 * @example
-* ```typescript
+*
+* ```ts
 * import { sha3384 } from '@kikiutils/shared/hash';
 *
-* console.log(sha3384('test')); // e516dabb23b6e30026863543282780a3ae0dccf05551cf0295178d7f...
+* console.log(sha3384('test')); // => e516dabb23b6e30026863543282780a3ae0dccf05551cf0295178d7f...
 * ```
 */
 function sha3384(data) {
@@ -55,15 +58,16 @@ function sha3384(data) {
 /**
 * Computes the SHA-3 hash of the given data using the 512-bit digest.
 *
-* @param {string | Uint8Array} data - The input data to hash
+* @param data - The UTF-8 string or raw bytes to hash.
 *
-* @returns {string} The hexadecimal hash digest
+* @returns The hexadecimal hash digest.
 *
 * @example
-* ```typescript
+*
+* ```ts
 * import { sha3512 } from '@kikiutils/shared/hash';
 *
-* console.log(sha3512('test')); // 9ece086e9bac491fac5c1d1046ca11d737b92a2b2ebd93f005d7...
+* console.log(sha3512('test')); // => 9ece086e9bac491fac5c1d1046ca11d737b92a2b2ebd93f005d7...
 * ```
 */
 function sha3512(data) {

package/dist/hash.js.map

@@ -1 +1 @@
-{"version":3,"file":"hash.js","names":[],"sources":["../src/hash.ts"],"sourcesContent":["import {\n    sha3_224,\n    sha3_256,\n    sha3_384,\n    sha3_512,\n} from '@noble/hashes/sha3.js';\nimport {\n    bytesToHex,\n    utf8ToBytes,\n} from '@noble/hashes/utils.js';\n\n/**\n * Computes the SHA-3 hash of the given data using the 224-bit digest.\n *\n * @param {string | Uint8Array} data - The input data to hash\n *\n * @returns {string} The hexadecimal hash digest\n *\n * @example\n * ```typescript\n * import { sha3224 } from '@kikiutils/shared/hash';\n *\n * console.log(sha3224('test')); // 3797bf0afbbfca4a7bbba7602a2b552746876517a7f9b7ce2db0ae7b\n * ```\n */\nexport function sha3224(data: string | Uint8Array) {\n    return bytesToHex(sha3_224(typeof data === 'string' ? utf8ToBytes(data) : data));\n}\n\n/**\n * Computes the SHA-3 hash of the given data using the 256-bit digest.\n *\n * @param {string | Uint8Array} data - The input data to hash\n *\n * @returns {string} The hexadecimal hash digest\n *\n * @example\n * ```typescript\n * import { sha3256 } from '@kikiutils/shared/hash';\n *\n * console.log(sha3256('test')); // 36f028580bb02cc8272a9a020f4200e346e276ae664e45ee80745574e2f5ab80\n * ```\n */\nexport function sha3256(data: string | Uint8Array) {\n    return bytesToHex(sha3_256(typeof data === 'string' ? utf8ToBytes(data) : data));\n}\n\n/**\n * Computes the SHA-3 hash of the given data using the 384-bit digest.\n *\n * @param {string | Uint8Array} data - The input data to hash\n *\n * @returns {string} The hexadecimal hash digest\n *\n * @example\n * ```typescript\n * import { sha3384 } from '@kikiutils/shared/hash';\n *\n * console.log(sha3384('test')); // e516dabb23b6e30026863543282780a3ae0dccf05551cf0295178d7f...\n * ```\n */\nexport function sha3384(data: string | Uint8Array) {\n    return bytesToHex(sha3_384(typeof data === 'string' ? utf8ToBytes(data) : data));\n}\n\n/**\n * Computes the SHA-3 hash of the given data using the 512-bit digest.\n *\n * @param {string | Uint8Array} data - The input data to hash\n *\n * @returns {string} The hexadecimal hash digest\n *\n * @example\n * ```typescript\n * import { sha3512 } from '@kikiutils/shared/hash';\n *\n * console.log(sha3512('test')); // 9ece086e9bac491fac5c1d1046ca11d737b92a2b2ebd93f005d7...\n * ```\n */\nexport function sha3512(data: string | Uint8Array) {\n    return bytesToHex(sha3_512(typeof data === 'string' ? utf8ToBytes(data) : data));\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAyBA,SAAgB,QAAQ,MAA2B;CAC/C,OAAO,WAAW,SAAS,OAAO,SAAS,WAAW,YAAY,IAAI,IAAI,IAAI,CAAC;AACnF;;;;;;;;;;;;;;;AAgBA,SAAgB,QAAQ,MAA2B;CAC/C,OAAO,WAAW,SAAS,OAAO,SAAS,WAAW,YAAY,IAAI,IAAI,IAAI,CAAC;AACnF;;;;;;;;;;;;;;;AAgBA,SAAgB,QAAQ,MAA2B;CAC/C,OAAO,WAAW,SAAS,OAAO,SAAS,WAAW,YAAY,IAAI,IAAI,IAAI,CAAC;AACnF;;;;;;;;;;;;;;;AAgBA,SAAgB,QAAQ,MAA2B;CAC/C,OAAO,WAAW,SAAS,OAAO,SAAS,WAAW,YAAY,IAAI,IAAI,IAAI,CAAC;AACnF"}
+{"version":3,"file":"hash.js","names":[],"sources":["../src/hash.ts"],"sourcesContent":["import {\n    sha3_224,\n    sha3_256,\n    sha3_384,\n    sha3_512,\n} from '@noble/hashes/sha3.js';\nimport {\n    bytesToHex,\n    utf8ToBytes,\n} from '@noble/hashes/utils.js';\n\n/**\n * Computes the SHA-3 hash of the given data using the 224-bit digest.\n *\n * @param data - The UTF-8 string or raw bytes to hash.\n *\n * @returns The hexadecimal hash digest.\n *\n * @example\n *\n * ```ts\n * import { sha3224 } from '@kikiutils/shared/hash';\n *\n * console.log(sha3224('test')); // => 3797bf0afbbfca4a7bbba7602a2b552746876517a7f9b7ce2db0ae7b\n * ```\n */\nexport function sha3224(data: string | Uint8Array) {\n    return bytesToHex(sha3_224(typeof data === 'string' ? utf8ToBytes(data) : data));\n}\n\n/**\n * Computes the SHA-3 hash of the given data using the 256-bit digest.\n *\n * @param data - The UTF-8 string or raw bytes to hash.\n *\n * @returns The hexadecimal hash digest.\n *\n * @example\n *\n * ```ts\n * import { sha3256 } from '@kikiutils/shared/hash';\n *\n * console.log(sha3256('test')); // => 36f028580bb02cc8272a9a020f4200e346e276ae664e45ee80745574e2f5ab80\n * ```\n */\nexport function sha3256(data: string | Uint8Array) {\n    return bytesToHex(sha3_256(typeof data === 'string' ? utf8ToBytes(data) : data));\n}\n\n/**\n * Computes the SHA-3 hash of the given data using the 384-bit digest.\n *\n * @param data - The UTF-8 string or raw bytes to hash.\n *\n * @returns The hexadecimal hash digest.\n *\n * @example\n *\n * ```ts\n * import { sha3384 } from '@kikiutils/shared/hash';\n *\n * console.log(sha3384('test')); // => e516dabb23b6e30026863543282780a3ae0dccf05551cf0295178d7f...\n * ```\n */\nexport function sha3384(data: string | Uint8Array) {\n    return bytesToHex(sha3_384(typeof data === 'string' ? utf8ToBytes(data) : data));\n}\n\n/**\n * Computes the SHA-3 hash of the given data using the 512-bit digest.\n *\n * @param data - The UTF-8 string or raw bytes to hash.\n *\n * @returns The hexadecimal hash digest.\n *\n * @example\n *\n * ```ts\n * import { sha3512 } from '@kikiutils/shared/hash';\n *\n * console.log(sha3512('test')); // => 9ece086e9bac491fac5c1d1046ca11d737b92a2b2ebd93f005d7...\n * ```\n */\nexport function sha3512(data: string | Uint8Array) {\n    return bytesToHex(sha3_512(typeof data === 'string' ? utf8ToBytes(data) : data));\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AA0BA,SAAgB,QAAQ,MAA2B;CAC/C,OAAO,WAAW,SAAS,OAAO,SAAS,WAAW,YAAY,IAAI,IAAI,IAAI,CAAC;AACnF;;;;;;;;;;;;;;;;AAiBA,SAAgB,QAAQ,MAA2B;CAC/C,OAAO,WAAW,SAAS,OAAO,SAAS,WAAW,YAAY,IAAI,IAAI,IAAI,CAAC;AACnF;;;;;;;;;;;;;;;;AAiBA,SAAgB,QAAQ,MAA2B;CAC/C,OAAO,WAAW,SAAS,OAAO,SAAS,WAAW,YAAY,IAAI,IAAI,IAAI,CAAC;AACnF;;;;;;;;;;;;;;;;AAiBA,SAAgB,QAAQ,MAA2B;CAC/C,OAAO,WAAW,SAAS,OAAO,SAAS,WAAW,YAAY,IAAI,IAAI,IAAI,CAAC;AACnF"}

package/dist/math.d.ts

@@ -6,43 +6,44 @@ type CalculableValue = Decimal.Value | {
 /**
  * Options for configuring the output of `toPercentageString`.
  */
-interface ToPercentageStringOptions {
+export interface ToPercentageStringOptions {
   /**
-   * Number of decimal places to include in the result.
+   * The number of decimal places to include in the result.
    *
-   * @default 2
+   * @defaultValue 2
    */
   decimalPlaces?: number;
   /**
-   * Whether to include the '%' symbol in the result.
+   * Whether to include the `%` symbol in the result.
    *
-   * @default true
+   * @defaultValue true
    */
   withSymbol?: boolean;
 }
 /**
- * Converts a fraction (numerator / denominator) into a percentage string.
+ * Converts a numerator and denominator into a formatted percentage.
  *
- * - Uses `decimal.js` for precise decimal calculations.
- * - Supports custom decimal places and optional percentage symbol.
- * - Returns `'0.00%'` if result is `NaN` or division is invalid.
+ * @remarks
+ * A `NaN` or infinite quotient produces `0.00`, regardless of the configured decimal places;
+ * the percent symbol is appended according to `options.withSymbol`.
+ * Invalid decimal input and formatting options propagate decimal.js exceptions.
  *
- * @param {CalculableValue} molecular - The numerator of the fraction
- * @param {CalculableValue} denominator - The denominator of the fraction
- * @param {ToPercentageStringOptions} [options] - Optional output settings
+ * @param molecular - The numerator of the fraction.
+ * @param denominator - The denominator of the fraction.
+ * @param options - Output precision and percent-symbol settings.
  *
- * @returns {string} Formatted percentage string
+ * @returns The formatted percentage string.
  *
  * @example
- * ```typescript
+ *
+ * ```ts
  * import { toPercentageString } from '@kikiutils/shared/math';
  *
- * console.log(toPercentageString(50, 200)); // 25.00%
- * console.log(toPercentageString(50, 200, { withSymbol: false })); // 25.00
- * console.log(toPercentageString(50, 200, { decimalPlaces: 1 })); // 25.0%
+ * console.log(toPercentageString(50, 200)); // => '25.00%'
+ * console.log(toPercentageString(50, 200, { withSymbol: false })); // => '25.00'
+ * console.log(toPercentageString(50, 200, { decimalPlaces: 1 })); // => '25.0%'
  * ```
  */
-declare function toPercentageString(molecular: CalculableValue, denominator: CalculableValue, options?: ToPercentageStringOptions): string;
+export declare function toPercentageString(molecular: CalculableValue, denominator: CalculableValue, options?: ToPercentageStringOptions): string;
 //#endregion
-export { ToPercentageStringOptions, toPercentageString };
 //# sourceMappingURL=math.d.ts.map

package/dist/math.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"math.d.ts","names":[],"sources":["../src/math.ts"],"mappings":";;KAEK,kBAAkB,QAAQ;EAAU;;;;;UAKxB;;;;;;EAMb;;;;;;EAOA;;;;;;;;;;;;;;;;;;;;;;;;iBAyBY,mBACZ,WAAW,iBACX,aAAa,iBACb,UAAU"}
+{"version":3,"file":"math.d.ts","names":[],"sources":["../src/math.ts"],"mappings":";;KAEK,kBAAkB,QAAQ;EAAU;;;;;iBAKxB;;;;;;EAMb;;;;;;EAOA;;;;;;;;;;;;;;;;;;;;;;;;;;wBA2BY,mBACZ,WAAW,iBACX,aAAa,iBACb,UAAU"}

package/dist/math.js

@@ -1,25 +1,27 @@
 import { Decimal } from "decimal.js";
 //#region src/math.ts
 /**
-* Converts a fraction (numerator / denominator) into a percentage string.
+* Converts a numerator and denominator into a formatted percentage.
 *
-* - Uses `decimal.js` for precise decimal calculations.
-* - Supports custom decimal places and optional percentage symbol.
-* - Returns `'0.00%'` if result is `NaN` or division is invalid.
+* @remarks
+* A `NaN` or infinite quotient produces `0.00`, regardless of the configured decimal places;
+* the percent symbol is appended according to `options.withSymbol`.
+* Invalid decimal input and formatting options propagate decimal.js exceptions.
 *
-* @param {CalculableValue} molecular - The numerator of the fraction
-* @param {CalculableValue} denominator - The denominator of the fraction
-* @param {ToPercentageStringOptions} [options] - Optional output settings
+* @param molecular - The numerator of the fraction.
+* @param denominator - The denominator of the fraction.
+* @param options - Output precision and percent-symbol settings.
 *
-* @returns {string} Formatted percentage string
+* @returns The formatted percentage string.
 *
 * @example
-* ```typescript
+*
+* ```ts
 * import { toPercentageString } from '@kikiutils/shared/math';
 *
-* console.log(toPercentageString(50, 200)); // 25.00%
-* console.log(toPercentageString(50, 200, { withSymbol: false })); // 25.00
-* console.log(toPercentageString(50, 200, { decimalPlaces: 1 })); // 25.0%
+* console.log(toPercentageString(50, 200)); // => '25.00%'
+* console.log(toPercentageString(50, 200, { withSymbol: false })); // => '25.00'
+* console.log(toPercentageString(50, 200, { decimalPlaces: 1 })); // => '25.0%'
 * ```
 */
 function toPercentageString(molecular, denominator, options) {

package/dist/math.js.map

@@ -1 +1 @@
-{"version":3,"file":"math.js","names":[],"sources":["../src/math.ts"],"sourcesContent":["import { Decimal } from 'decimal.js';\n\ntype CalculableValue = Decimal.Value | { toString: () => string };\n\n/**\n * Options for configuring the output of `toPercentageString`.\n */\nexport interface ToPercentageStringOptions {\n    /**\n     * Number of decimal places to include in the result.\n     *\n     * @default 2\n     */\n    decimalPlaces?: number;\n\n    /**\n     * Whether to include the '%' symbol in the result.\n     *\n     * @default true\n     */\n    withSymbol?: boolean;\n}\n\n/**\n * Converts a fraction (numerator / denominator) into a percentage string.\n *\n * - Uses `decimal.js` for precise decimal calculations.\n * - Supports custom decimal places and optional percentage symbol.\n * - Returns `'0.00%'` if result is `NaN` or division is invalid.\n *\n * @param {CalculableValue} molecular - The numerator of the fraction\n * @param {CalculableValue} denominator - The denominator of the fraction\n * @param {ToPercentageStringOptions} [options] - Optional output settings\n *\n * @returns {string} Formatted percentage string\n *\n * @example\n * ```typescript\n * import { toPercentageString } from '@kikiutils/shared/math';\n *\n * console.log(toPercentageString(50, 200)); // 25.00%\n * console.log(toPercentageString(50, 200, { withSymbol: false })); // 25.00\n * console.log(toPercentageString(50, 200, { decimalPlaces: 1 })); // 25.0%\n * ```\n */\nexport function toPercentageString(\n    molecular: CalculableValue,\n    denominator: CalculableValue,\n    options?: ToPercentageStringOptions,\n) {\n    const molecularDecimal = new Decimal(molecular.toString());\n    const denominatorDecimal = new Decimal(denominator.toString());\n    const calculationResult = molecularDecimal.div(denominatorDecimal);\n\n    const result = calculationResult.isNaN() || !calculationResult.isFinite()\n        ? '0.00'\n        : calculationResult.times(100).toFixed(options?.decimalPlaces ?? 2);\n\n    return options?.withSymbol ?? true ? `${result}%` : result;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AA6CA,SAAgB,mBACZ,WACA,aACA,SACF;CACE,MAAM,mBAAmB,IAAI,QAAQ,UAAU,SAAS,CAAC;CACzD,MAAM,qBAAqB,IAAI,QAAQ,YAAY,SAAS,CAAC;CAC7D,MAAM,oBAAoB,iBAAiB,IAAI,kBAAkB;CAEjE,MAAM,SAAS,kBAAkB,MAAM,KAAK,CAAC,kBAAkB,SAAS,IAClE,SACA,kBAAkB,MAAM,GAAG,CAAC,CAAC,QAAQ,SAAS,iBAAiB,CAAC;CAEtE,OAAO,SAAS,cAAc,OAAO,GAAG,OAAO,KAAK;AACxD"}
+{"version":3,"file":"math.js","names":[],"sources":["../src/math.ts"],"sourcesContent":["import { Decimal } from 'decimal.js';\n\ntype CalculableValue = Decimal.Value | { toString: () => string };\n\n/**\n * Options for configuring the output of `toPercentageString`.\n */\nexport interface ToPercentageStringOptions {\n    /**\n     * The number of decimal places to include in the result.\n     *\n     * @defaultValue 2\n     */\n    decimalPlaces?: number;\n\n    /**\n     * Whether to include the `%` symbol in the result.\n     *\n     * @defaultValue true\n     */\n    withSymbol?: boolean;\n}\n\n/**\n * Converts a numerator and denominator into a formatted percentage.\n *\n * @remarks\n * A `NaN` or infinite quotient produces `0.00`, regardless of the configured decimal places;\n * the percent symbol is appended according to `options.withSymbol`.\n * Invalid decimal input and formatting options propagate decimal.js exceptions.\n *\n * @param molecular - The numerator of the fraction.\n * @param denominator - The denominator of the fraction.\n * @param options - Output precision and percent-symbol settings.\n *\n * @returns The formatted percentage string.\n *\n * @example\n *\n * ```ts\n * import { toPercentageString } from '@kikiutils/shared/math';\n *\n * console.log(toPercentageString(50, 200)); // => '25.00%'\n * console.log(toPercentageString(50, 200, { withSymbol: false })); // => '25.00'\n * console.log(toPercentageString(50, 200, { decimalPlaces: 1 })); // => '25.0%'\n * ```\n */\nexport function toPercentageString(\n    molecular: CalculableValue,\n    denominator: CalculableValue,\n    options?: ToPercentageStringOptions,\n) {\n    const molecularDecimal = new Decimal(molecular.toString());\n    const denominatorDecimal = new Decimal(denominator.toString());\n    const calculationResult = molecularDecimal.div(denominatorDecimal);\n\n    const result = calculationResult.isNaN() || !calculationResult.isFinite()\n        ? '0.00'\n        : calculationResult.times(100).toFixed(options?.decimalPlaces ?? 2);\n\n    return options?.withSymbol ?? true ? `${result}%` : result;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AA+CA,SAAgB,mBACZ,WACA,aACA,SACF;CACE,MAAM,mBAAmB,IAAI,QAAQ,UAAU,SAAS,CAAC;CACzD,MAAM,qBAAqB,IAAI,QAAQ,YAAY,SAAS,CAAC;CAC7D,MAAM,oBAAoB,iBAAiB,IAAI,kBAAkB;CAEjE,MAAM,SAAS,kBAAkB,MAAM,KAAK,CAAC,kBAAkB,SAAS,IAClE,SACA,kBAAkB,MAAM,GAAG,CAAC,CAAC,QAAQ,SAAS,iBAAiB,CAAC;CAEtE,OAAO,SAAS,cAAc,OAAO,GAAG,OAAO,KAAK;AACxD"}

package/dist/number.d.ts

@@ -3,22 +3,23 @@ import { millify } from "millify";
 /**
  * Converts a large number into a compact, human-readable string using `millify`.
  *
- * Applies lowercase units (e.g. 'k', 'm') and default precision of 2, unless overridden.
+ * @remarks
+ * Uses lowercase units, for example `k` and `m`, and a precision of `2` unless overridden.
  *
- * @param {number} value - The number to format
- * @param {Parameters<typeof millify>[1]} [options] - Optional configuration passed to `millify`
+ * @param value - The number to format.
+ * @param options - Optional configuration passed to `millify`.
  *
- * @returns {string} The compact number string
+ * @returns The compact number string.
  *
  * @example
- * ```typescript
+ *
+ * ```ts
  * import { toCompactNumberString } from '@kikiutils/shared/number';
  *
- * console.log(toCompactNumberString(1234567)); // 1.23m
- * console.log(toCompactNumberString(1234567, { precision: 3 })); // 1.235m
+ * console.log(toCompactNumberString(1234567)); // => 1.23m
+ * console.log(toCompactNumberString(1234567, { precision: 3 })); // => 1.235m
  * ```
  */
-declare function toCompactNumberString(value: number, options?: Parameters<typeof millify>[1]): string;
+export declare function toCompactNumberString(value: number, options?: Parameters<typeof millify>[1]): string;
 //#endregion
-export { toCompactNumberString };
 //# sourceMappingURL=number.d.ts.map

package/dist/number.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"number.d.ts","names":[],"sources":["../src/number.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;iBAoBgB,sBAAsB,eAAe,UAAU,kBAAkB"}
+{"version":3,"file":"number.d.ts","names":[],"sources":["../src/number.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;wBAsBgB,sBAAsB,eAAe,UAAU,kBAAkB"}

package/dist/number.js

@@ -3,19 +3,21 @@ import { millify } from "millify";
 /**
 * Converts a large number into a compact, human-readable string using `millify`.
 *
-* Applies lowercase units (e.g. 'k', 'm') and default precision of 2, unless overridden.
+* @remarks
+* Uses lowercase units, for example `k` and `m`, and a precision of `2` unless overridden.
 *
-* @param {number} value - The number to format
-* @param {Parameters<typeof millify>[1]} [options] - Optional configuration passed to `millify`
+* @param value - The number to format.
+* @param options - Optional configuration passed to `millify`.
 *
-* @returns {string} The compact number string
+* @returns The compact number string.
 *
 * @example
-* ```typescript
+*
+* ```ts
 * import { toCompactNumberString } from '@kikiutils/shared/number';
 *
-* console.log(toCompactNumberString(1234567)); // 1.23m
-* console.log(toCompactNumberString(1234567, { precision: 3 })); // 1.235m
+* console.log(toCompactNumberString(1234567)); // => 1.23m
+* console.log(toCompactNumberString(1234567, { precision: 3 })); // => 1.235m
 * ```
 */
 function toCompactNumberString(value, options) {

package/dist/number.js.map

@@ -1 +1 @@
-{"version":3,"file":"number.js","names":[],"sources":["../src/number.ts"],"sourcesContent":["import { millify } from 'millify';\n\n/**\n * Converts a large number into a compact, human-readable string using `millify`.\n *\n * Applies lowercase units (e.g. 'k', 'm') and default precision of 2, unless overridden.\n *\n * @param {number} value - The number to format\n * @param {Parameters<typeof millify>[1]} [options] - Optional configuration passed to `millify`\n *\n * @returns {string} The compact number string\n *\n * @example\n * ```typescript\n * import { toCompactNumberString } from '@kikiutils/shared/number';\n *\n * console.log(toCompactNumberString(1234567)); // 1.23m\n * console.log(toCompactNumberString(1234567, { precision: 3 })); // 1.235m\n * ```\n */\nexport function toCompactNumberString(value: number, options?: Parameters<typeof millify>[1]) {\n    return millify(\n        value,\n        {\n            lowercase: true,\n            precision: 2,\n            ...options,\n        },\n    );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAoBA,SAAgB,sBAAsB,OAAe,SAAyC;CAC1F,OAAO,QACH,OACA;EACI,WAAW;EACX,WAAW;EACX,GAAG;CACP,CACJ;AACJ"}
+{"version":3,"file":"number.js","names":[],"sources":["../src/number.ts"],"sourcesContent":["import { millify } from 'millify';\n\n/**\n * Converts a large number into a compact, human-readable string using `millify`.\n *\n * @remarks\n * Uses lowercase units, for example `k` and `m`, and a precision of `2` unless overridden.\n *\n * @param value - The number to format.\n * @param options - Optional configuration passed to `millify`.\n *\n * @returns The compact number string.\n *\n * @example\n *\n * ```ts\n * import { toCompactNumberString } from '@kikiutils/shared/number';\n *\n * console.log(toCompactNumberString(1234567)); // => 1.23m\n * console.log(toCompactNumberString(1234567, { precision: 3 })); // => 1.235m\n * ```\n */\nexport function toCompactNumberString(value: number, options?: Parameters<typeof millify>[1]) {\n    return millify(\n        value,\n        {\n            lowercase: true,\n            precision: 2,\n            ...options,\n        },\n    );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,sBAAsB,OAAe,SAAyC;CAC1F,OAAO,QACH,OACA;EACI,WAAW;EACX,WAAW;EACX,GAAG;CACP,CACJ;AACJ"}

package/dist/object.d.ts

@@ -2,6 +2,7 @@
 /**
  * Serializes a nested object into a deterministic, flat string format.
  *
+ * @remarks
  * This function recursively traverses the input object (including nested objects and arrays),
  * flattens it into key paths using dot notation (e.g. "a.b.0.c"), sorts all keys,
  * and joins each key-value pair into a string with customizable separators.
@@ -12,21 +13,32 @@
  * Note: Empty objects and arrays produce an empty string, which is useful for
  * generating deterministic signature payloads.
  *
- * @param {Record<string, any>} input - The object to serialize. Can contain nested objects and arrays
- * @param {string} kvSeparator - The string used to separate each key from its value (default: '=')
- * @param {string} pairSeparator - The string used to separate each key-value pair (default: '&')
- * @returns {string} A deterministic string representation of the input object
+ * @param input - The object to serialize. Can contain nested objects and arrays.
+ * @param kvSeparator - The string used to separate each key from its value (default: '=').
+ * @param pairSeparator - The string used to separate each key-value pair (default: '&').
+ *
+ * @returns A deterministic string representation of the input object.
  *
  * @example
- * ```typescript
+ *
+ * ```ts
  * import { stringifyObjectDeterministically } from '@kikiutils/shared/object';
  *
- * console.log(stringifyObjectDeterministically({ b: 2, a: { x: 1, y: [3, 4] } })); // a.x=1&a.y.0=3&a.y.1=4&b=2
- * console.log(stringifyObjectDeterministically({ foo: 'bar' }, ':', '|')); // foo:bar
- * console.log(stringifyObjectDeterministically({})); // ''
+ * console.log(stringifyObjectDeterministically({
+ *     b: 2,
+ *     a: {
+ *         x: 1,
+ *         y: [
+ *             3,
+ *             4,
+ *         ],
+ *     },
+ * })); // => a.x=1&a.y.0=3&a.y.1=4&b=2
+ *
+ * console.log(stringifyObjectDeterministically({ foo: 'bar' }, ':', '|')); // => foo:bar
+ * console.log(stringifyObjectDeterministically({})); // => ''
  * ```
  */
-declare function stringifyObjectDeterministically(input: Record<string, any>, kvSeparator?: string, pairSeparator?: string): string;
+export declare function stringifyObjectDeterministically(input: Record<string, any>, kvSeparator?: string, pairSeparator?: string): string;
 //#endregion
-export { stringifyObjectDeterministically };
 //# sourceMappingURL=object.d.ts.map

package/dist/object.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"object.d.ts","names":[],"sources":["../src/object.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2BgB,iCACZ,OAAO,qBACP,sBACA"}
+{"version":3,"file":"object.d.ts","names":[],"sources":["../src/object.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAwCgB,iCACZ,OAAO,qBACP,sBACA"}