@ibodr/utils 0.2.6 → 0.2.7

package/dist/index.d.ts

@@ -706,6 +706,12 @@ type MakeUndefinedOptional<T extends object> = Expand<{
  * function returns a Promise that resolves with the result of the original function. Includes a
  * cancel method to prevent execution if needed.
  *
+ * Calling `cancel()` while a call is pending rejects the returned promise with an `Error`
+ * whose message is `'Debounced function was cancelled'`. Callers that discard the promise
+ * are not affected — internal handling suppresses the unhandled-rejection warning — but
+ * any code that `await`s or chains `.then()` on the promise must be prepared to handle the
+ * rejection.
+ *
  * @param callback - The function to debounce (can be sync or async)
  * @param wait - The delay in milliseconds before executing the function
  * @returns A debounced function that returns a Promise and includes a cancel method
@@ -721,15 +727,19 @@ type MakeUndefinedOptional<T extends object> = Expand<{
  * debouncedSearch('react hooks') // This cancels the previous call
  * debouncedSearch('react typescript') // Only this will execute
  *
- * // Cancel pending execution
+ * // Cancel pending execution — any in-flight promise rejects
  * debouncedSearch.cancel()
  *
- * // With async/await
+ * // With async/await — wrap in try/catch if you might cancel
  * const saveData = debounce(async (data: any) => {
  *   return await api.save(data)
  * }, 1000)
  *
- * const result = await saveData({name: 'John'})
+ * try {
+ *   const result = await saveData({name: 'John'})
+ * } catch (err) {
+ *   // handle cancellation or callback error
+ * }
  * ```
  *
  * @public
@@ -1072,7 +1082,7 @@ declare function omitFromStackTrace<Args extends Array<unknown>, Return>(fn: (..
  * Does nothing, but it's really really good at it.
  * @internal
  */
-declare const noop: () => void;
+declare function noop(): void;
 
 /**
  * Hash a string using the FNV-1a algorithm.
@@ -1256,17 +1266,6 @@ declare function uniqueId(size?: number): string;
  */
 declare function getFirstFromIterable<T = unknown>(set: Set<T> | Map<any, T>): T;
 
-/** Simple LRU cache backed by a Map's insertion-order iteration. @public */
-declare class LruCache<K, V> {
-    private maxSize;
-    private map;
-    constructor(maxSize: number);
-    get(key: K): V | undefined;
-    set(key: K, value: V): void;
-    has(key: K): boolean;
-    get size(): number;
-}
-
 /**
  * A type that represents any valid JSON value. This includes primitives (boolean, null, string, number),
  * arrays of JSON values, and objects with string keys and JSON values.
@@ -1342,6 +1341,18 @@ interface JsonObject {
     [key: string]: JsonValue | undefined;
 }
 
+/** Simple LRU cache backed by a Map's insertion-order iteration. @public */
+declare class LruCache<K, V> {
+    private maxSize;
+    private map;
+    constructor(maxSize: number);
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    has(key: K): boolean;
+    delete(key: K): boolean;
+    get size(): number;
+}
+
 /**
  * Array of all supported image MIME types, combining static, vector, and animated types.
  *
@@ -1786,7 +1797,7 @@ declare function fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Re
  * @returns HTMLImageElement with referrerPolicy set to 'strict-origin-when-cross-origin'
  * @internal
  */
-declare const Image: (width?: number, height?: number) => HTMLImageElement;
+declare function Image(width?: number, height?: number): HTMLImageElement;
 
 /**
  * Linear interpolate between two values.
@@ -2596,6 +2607,32 @@ declare function deleteFromSessionStorage(key: string): void;
  */
 declare function clearSessionStorage(): void;
 
+/**
+ * Iterate over the grapheme clusters of a string — user-perceived characters such as emoji
+ * sequences, flags, and accented letters — instead of UTF-16 code units. Uses `Intl.Segmenter`
+ * where available and falls back to iterating by code point on browsers that lack it, where a
+ * multi-code-point cluster is yielded as its component code points rather than as one segment.
+ *
+ * @public
+ */
+declare function iterateGraphemes(str: string): IterableIterator<string>;
+/**
+ * Get the first character of a string, treating a multi-code-unit character such as an emoji as a
+ * single character. Unlike `str[0]` or `str.charAt(0)`, which return one UTF-16 code unit and so
+ * split an emoji into a broken half, this returns the first whole grapheme cluster. Returns an
+ * empty string when the input is empty.
+ *
+ * @example
+ * ```ts
+ * getFirstCharacter('hello') // 'h'
+ * getFirstCharacter('😀 hello') // '😀'
+ * getFirstCharacter('') // ''
+ * ```
+ *
+ * @public
+ */
+declare function getFirstCharacter(str: string): string;
+
 /**
  * Creates an enum-like object from string values where each key maps to itself.
  * Useful for creating string constant objects with type safety and autocompletion.
@@ -2817,6 +2854,47 @@ declare class Timers {
      * @public
      */
     requestAnimationFrame(contextId: string, callback: FrameRequestCallback): number;
+    /**
+     * Clears a timeout created with {@link Timers.setTimeout} and stops tracking it.
+     * Prefer this over the global `clearTimeout` for ids that came from this instance,
+     * otherwise the id stays tracked until its context is disposed.
+     * @param contextId - The context identifier the timeout was created under.
+     * @param id - The timer ID returned by `setTimeout`. Ignored when undefined.
+     * @example
+     * ```ts
+     * const timers = new Timers()
+     * const id = timers.setTimeout('autosave', () => save(), 5000)
+     * timers.clearTimeout('autosave', id)
+     * ```
+     * @public
+     */
+    clearTimeout(contextId: string, id: number | undefined): void;
+    /**
+     * Clears an interval created with {@link Timers.setInterval} and stops tracking it.
+     * @param contextId - The context identifier the interval was created under.
+     * @param id - The interval ID returned by `setInterval`. Ignored when undefined.
+     * @example
+     * ```ts
+     * const timers = new Timers()
+     * const id = timers.setInterval('refresh', () => updateData(), 1000)
+     * timers.clearInterval('refresh', id)
+     * ```
+     * @public
+     */
+    clearInterval(contextId: string, id: number | undefined): void;
+    /**
+     * Cancels an animation frame requested with {@link Timers.requestAnimationFrame} and stops tracking it.
+     * @param contextId - The context identifier the animation frame was requested under.
+     * @param id - The request ID returned by `requestAnimationFrame`. Ignored when undefined.
+     * @example
+     * ```ts
+     * const timers = new Timers()
+     * const id = timers.requestAnimationFrame('render', () => draw())
+     * timers.cancelAnimationFrame('render', id)
+     * ```
+     * @public
+     */
+    cancelAnimationFrame(contextId: string, id: number | undefined): void;
     /**
      * Disposes of all timers associated with the specified context.
      * Clears all timeouts, intervals, and animation frames for the given context ID.
@@ -2854,17 +2932,20 @@ declare class Timers {
      * Returns an object with timer methods bound to a specific context.
      * Convenient for getting context-specific timer functions without repeatedly passing the contextId.
      * @param contextId - The context identifier to bind the returned methods to.
-     * @returns An object with setTimeout, setInterval, requestAnimationFrame, and dispose methods bound to the context.
+     * @returns An object with setTimeout, setInterval, requestAnimationFrame, the matching clear methods, and dispose bound to the context.
      * @example
      * ```ts
      * const timers = new Timers()
      * const uiTimers = timers.forContext('ui')
      *
      * // These are equivalent to calling timers.setTimeout('ui', ...)
-     * uiTimers.setTimeout(() => console.log('timeout'), 1000)
+     * const id = uiTimers.setTimeout(() => console.log('timeout'), 1000)
      * uiTimers.setInterval(() => console.log('interval'), 500)
      * uiTimers.requestAnimationFrame(() => console.log('frame'))
      *
+     * // Clear a single timer
+     * uiTimers.clearTimeout(id)
+     *
      * // Dispose only this context
      * uiTimers.dispose()
      * ```
@@ -2874,6 +2955,9 @@ declare class Timers {
         setTimeout: (handler: TimerHandler, timeout?: number, ...args: any[]) => number;
         setInterval: (handler: TimerHandler, timeout?: number, ...args: any[]) => number;
         requestAnimationFrame: (callback: FrameRequestCallback) => number;
+        clearTimeout: (id: number | undefined) => void;
+        clearInterval: (id: number | undefined) => void;
+        cancelAnimationFrame: (id: number | undefined) => void;
         dispose: () => void;
     };
 }
@@ -2918,7 +3002,7 @@ declare class Timers {
  *
  * @public
  */
-declare const safeParseUrl: (url: string, baseUrl?: string | URL) => URL | undefined;
+declare function safeParseUrl(url: string, baseUrl?: string | URL): URL | undefined;
 
 /**
  * Get whether a value is not undefined.
@@ -3080,4 +3164,4 @@ declare function warnDeprecatedGetter(name: string): void;
  */
 declare function warnOnce(message: string): void;
 
-export { type Awaitable, DEFAULT_SUPPORTED_IMAGE_TYPES, DEFAULT_SUPPORTED_MEDIA_TYPES, DEFAULT_SUPPORTED_MEDIA_TYPE_LIST, DEFAULT_SUPPORT_VIDEO_TYPES, type ErrorAnnotations, type ErrorResult, ExecutionQueue, type Expand, FileHelpers, FpsScheduler, Image, type IndexKey, type JsonArray, type JsonObject, type JsonPrimitive, type JsonValue, LruCache, type MakeUndefinedOptional, MediaHelpers, type OkResult, PerformanceTracker, PngHelpers, type RecursivePartial, type Required, Result, STRUCTURED_CLONE_OBJECT_PROTOTYPE, Timers, WeakCache, ZERO_INDEX_KEY, annotateError, areArraysShallowEqual, areObjectsShallowEqual, assert, assertExists, bind, clearLocalStorage, clearSessionStorage, compact, debounce, dedupe, deleteFromLocalStorage, deleteFromSessionStorage, exhaustiveSwitchError, fetch, filterEntries, fpsThrottle, getChangedKeys, getErrorAnnotations, getFirstFromIterable, getFromLocalStorage, getFromSessionStorage, getHashForBuffer, getHashForObject, getHashForString, getIndexAbove, getIndexBelow, getIndexBetween, getIndices, getIndicesAbove, getIndicesBelow, getIndicesBetween, getOwnProperty, groupBy, hasOwnProperty, invLerp, isDefined, isEqualAllowingForFloatingPointErrors, isNativeStructuredClone, isNonNull, isNonNullish, last, lerp, lns, mapObjectMapValues, maxBy, measureAverageDuration, measureCbDuration, measureDuration, mergeArraysAndReplaceDefaults, minBy, mockUniqueId, modulate, noop, objectMapEntries, objectMapEntriesIterable, objectMapFromEntries, objectMapKeys, objectMapValues, omit, omitFromStackTrace, partition, promiseWithResolve, registerDrawLibraryVersion, restoreUniqueId, retry, rng, rotateArray, safeParseUrl, setInLocalStorage, setInSessionStorage, sleep, sortById, sortByIndex, sortByMaybeIndex, stringEnum, structuredClone, throttleToNextFrame, uniqueId, validateIndexKey, warnDeprecatedGetter, warnOnce };
+export { type Awaitable, DEFAULT_SUPPORTED_IMAGE_TYPES, DEFAULT_SUPPORTED_MEDIA_TYPES, DEFAULT_SUPPORTED_MEDIA_TYPE_LIST, DEFAULT_SUPPORT_VIDEO_TYPES, type ErrorAnnotations, type ErrorResult, ExecutionQueue, type Expand, FileHelpers, FpsScheduler, Image, type IndexKey, type JsonArray, type JsonObject, type JsonPrimitive, type JsonValue, LruCache, type MakeUndefinedOptional, MediaHelpers, type OkResult, PerformanceTracker, PngHelpers, type RecursivePartial, type Required, Result, STRUCTURED_CLONE_OBJECT_PROTOTYPE, Timers, WeakCache, ZERO_INDEX_KEY, annotateError, areArraysShallowEqual, areObjectsShallowEqual, assert, assertExists, bind, clearLocalStorage, clearSessionStorage, compact, debounce, dedupe, deleteFromLocalStorage, deleteFromSessionStorage, exhaustiveSwitchError, fetch, filterEntries, fpsThrottle, getChangedKeys, getErrorAnnotations, getFirstCharacter, getFirstFromIterable, getFromLocalStorage, getFromSessionStorage, getHashForBuffer, getHashForObject, getHashForString, getIndexAbove, getIndexBelow, getIndexBetween, getIndices, getIndicesAbove, getIndicesBelow, getIndicesBetween, getOwnProperty, groupBy, hasOwnProperty, invLerp, isDefined, isEqualAllowingForFloatingPointErrors, isNativeStructuredClone, isNonNull, isNonNullish, iterateGraphemes, last, lerp, lns, mapObjectMapValues, maxBy, measureAverageDuration, measureCbDuration, measureDuration, mergeArraysAndReplaceDefaults, minBy, mockUniqueId, modulate, noop, objectMapEntries, objectMapEntriesIterable, objectMapFromEntries, objectMapKeys, objectMapValues, omit, omitFromStackTrace, partition, promiseWithResolve, registerDrawLibraryVersion, restoreUniqueId, retry, rng, rotateArray, safeParseUrl, setInLocalStorage, setInSessionStorage, sleep, sortById, sortByIndex, sortByMaybeIndex, stringEnum, structuredClone, throttleToNextFrame, uniqueId, validateIndexKey, warnDeprecatedGetter, warnOnce };