@vef-framework/shared 2.0.11 → 2.1.0

package/dist/types/src/utils/tree.d.ts

@@ -0,0 +1,216 @@
+import { AnyObject, Except, MaybeUndefined, SetRequired } from '../types';
+/**
+ * Options for flattening tree data
+ */
+export interface FlattenTreeOptions<TNode extends AnyObject = AnyObject, TTransformedNode = FlattenedNode<TNode>> {
+    /**
+     * The key name for children property
+     *
+     * @default 'children'
+     */
+    childrenKey?: keyof TNode;
+    /**
+     * Whether to include parent node reference
+     *
+     * @default false
+     */
+    includeParent?: boolean;
+    /**
+     * Whether to include level information
+     *
+     * @default false
+     */
+    includeLevel?: boolean;
+    /**
+     * Transform function to convert or filter nodes during flattening
+     */
+    transform?: (node: TNode, context: {
+        parent?: TNode;
+        level: number;
+    }) => TTransformedNode;
+    /**
+     * Filter function to skip nodes (will still traverse children)
+     */
+    filter?: (node: TNode, context: {
+        parent?: TNode;
+        level: number;
+    }) => boolean;
+}
+/**
+ * Flattened node data (used when transform is not provided)
+ */
+export interface FlattenedNode<TNode extends AnyObject = AnyObject> {
+    /**
+     * Original node data
+     */
+    data: TNode;
+    /**
+     * Parent node (only exists when includeParent is true)
+     */
+    parent?: TNode;
+    /**
+     * Level depth, starting from 0 (only exists when includeLevel is true)
+     */
+    level?: number;
+}
+/**
+ * Flatten tree data into a one-dimensional array
+ *
+ * @param tree - Tree data array
+ * @param options - Configuration options
+ * @returns Flattened array
+ */
+export declare function flattenTree<TNode extends AnyObject = AnyObject, TTransformedNode = FlattenedNode<NoInfer<TNode>>>(tree: TNode[], options: SetRequired<FlattenTreeOptions<NoInfer<TNode>, TTransformedNode>, "includeParent"> | SetRequired<FlattenTreeOptions<NoInfer<TNode>, TTransformedNode>, "includeLevel">): Array<NoInfer<TTransformedNode>>;
+/**
+ * Flatten tree data into a one-dimensional array
+ *
+ * @param tree - Tree data array
+ * @param options - Configuration options
+ * @returns Flattened array
+ */
+export declare function flattenTree<TNode extends AnyObject = AnyObject, TTransformedNode = NoInfer<TNode>>(tree: TNode[], options?: Except<FlattenTreeOptions<NoInfer<TNode>, TTransformedNode>, "includeParent" | "includeLevel">): Array<NoInfer<TTransformedNode>>;
+/**
+ * Key accessor - can be a property name or a getter function
+ */
+export type KeyAccessor<T extends AnyObject> = keyof T | ((node: T) => unknown);
+/**
+ * Options for building tree from flat array
+ */
+export interface BuildTreeOptions<TNode extends AnyObject = AnyObject, TTransformedNode extends AnyObject = TNode, TChildrenKey extends string = "children"> {
+    /**
+     * Accessor for node id
+     * Can be a property name or a getter function
+     *
+     * @default 'id'
+     */
+    idKey?: KeyAccessor<TNode>;
+    /**
+     * Accessor for parent id
+     * Can be a property name or a getter function
+     *
+     * @default 'parentId'
+     */
+    parentIdKey?: KeyAccessor<TNode>;
+    /**
+     * The key name for children property
+     *
+     * @default 'children'
+     */
+    childrenKey?: TChildrenKey;
+    /**
+     * Root node condition
+     * Can be a value to match against parentId, or a function to determine if a node is root
+     */
+    rootValue?: TNode[keyof TNode] | ((node: TNode) => boolean);
+    /**
+     * Transform function to convert nodes during building
+     */
+    transform?: (node: TNode, context: {
+        children?: TNode[];
+        level: number;
+    }) => TTransformedNode;
+}
+/**
+ * Result node type for buildTree
+ */
+export type BuildTreeResultNode<TNode extends AnyObject, TChildrenKey extends string> = TNode & {
+    [Key in TChildrenKey]?: Array<BuildTreeResultNode<TNode, TChildrenKey>>;
+};
+/**
+ * Build tree structure from flat array
+ *
+ * @param nodes - Flat array of items
+ * @param options - Configuration options
+ * @returns Tree structure array
+ */
+export declare function buildTree<TNode extends AnyObject = AnyObject, TTransformedNode extends AnyObject = NoInfer<TNode>, const TChildrenKey extends string = "children">(nodes: TNode[], options?: BuildTreeOptions<NoInfer<TNode>, TTransformedNode, TChildrenKey>): Array<BuildTreeResultNode<TTransformedNode, TChildrenKey>>;
+/**
+ * Find a node in tree data
+ *
+ * @param tree - Tree data array
+ * @param predicate - Predicate function to find the node
+ * @param childrenKey - The key name for children property
+ * @returns Found node, or undefined if not found
+ */
+export declare function findNodeInTree<TNode extends AnyObject = AnyObject>(tree: TNode[], predicate: (node: NoInfer<TNode>, context: {
+    parent?: NoInfer<TNode>;
+    level: number;
+}) => boolean, childrenKey?: keyof NoInfer<TNode>): MaybeUndefined<NoInfer<TNode>>;
+/**
+ * Options for traversing tree data
+ */
+export interface TraverseTreeOptions<TNode extends AnyObject> {
+    /**
+     * Traversal strategy
+     * - 'dfs': Depth-First Search - visit nodes depth-wise (parent -> children -> siblings)
+     * - 'bfs': Breadth-First Search - visit nodes level-wise (all nodes at level N before level N+1)
+     *
+     * @default 'dfs'
+     */
+    strategy?: "dfs" | "bfs";
+    /**
+     * The key name for children property
+     *
+     * @default 'children'
+     */
+    childrenKey?: keyof TNode;
+}
+/**
+ * Traverse tree data with depth-first or breadth-first strategy
+ *
+ * @param tree - Tree data array
+ * @param callback - Callback function for each node
+ * @param options - Traversal options or children key string (for backward compatibility)
+ */
+export declare function traverseTree<TNode extends AnyObject = AnyObject>(tree: TNode[], callback: (node: NoInfer<TNode>, context: {
+    parent?: NoInfer<TNode>;
+    level: number;
+    index: number;
+}) => void, options?: TraverseTreeOptions<NoInfer<TNode>>): void;
+/**
+ * Map tree data
+ *
+ * @param tree - Tree data array
+ * @param callback - Mapping callback function
+ * @param childrenKey - The key name for children property
+ * @returns Mapped tree data
+ */
+export declare function mapTree<TNode extends AnyObject = AnyObject, TMappedNode extends AnyObject = AnyObject>(tree: TNode[], callback: (node: NoInfer<TNode>, context: {
+    parent?: NoInfer<TNode>;
+    level: number;
+    index: number;
+}) => TMappedNode, childrenKey?: keyof NoInfer<TNode>): Array<NoInfer<TMappedNode>>;
+/**
+ * Filter tree data
+ *
+ * @param tree - Tree data array
+ * @param predicate - Filter predicate function
+ * @param childrenKey - The key name for children property
+ * @returns Filtered tree data
+ */
+export declare function filterTree<TNode extends AnyObject = AnyObject>(tree: TNode[], predicate: (node: NoInfer<TNode>, context: {
+    parent?: NoInfer<TNode>;
+    level: number;
+    index: number;
+}) => boolean, childrenKey?: keyof NoInfer<TNode>): Array<NoInfer<TNode>>;
+/**
+ * Filter tree data while preserving ancestor nodes
+ *
+ * Unlike filterTree, this function keeps all ancestor nodes of matching nodes,
+ * even if the ancestors themselves don't match the predicate.
+ * This is useful for search/filter scenarios where you want to show the full path to matching nodes.
+ *
+ * Key behavior:
+ * - Non-matching nodes are kept only if they have matching descendants
+ * - If a matching node has no matching children, its children are removed
+ *
+ * @param tree - Tree data array
+ * @param predicate - Filter predicate function
+ * @param childrenKey - The key name for children property
+ * @returns Filtered tree data with preserved ancestor paths
+ */
+export declare function filterTreeWithAncestors<TNode extends AnyObject = AnyObject>(tree: TNode[], predicate: (node: NoInfer<TNode>, context: {
+    parent?: NoInfer<TNode>;
+    level: number;
+    index: number;
+}) => boolean, childrenKey?: keyof NoInfer<TNode>): Array<NoInfer<TNode>>;

package/dist/types/src/utils/zod.d.ts

@@ -0,0 +1,2 @@
+export { z } from 'zod';
+export type { ZodError, ZodIssue, ZodSchema, ZodType } from 'zod';

package/dist/types/types/color.d.ts

@@ -1,73 +1,25 @@
-/**
- * The color entry
- */
 export type ColorEntry = [hex: string, name: string];
-/**
- * The color number
- */
 export type ColorNumber = 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950;
-/**
- * The color swatch
- */
 export interface ColorSwatch {
-    /**
-     * The color number
-     */
     number: ColorNumber;
-    /**
-     * The color hex code
-     */
     hex: string;
 }
-/**
- * The color palette
- */
 export interface ColorPalette {
-    /**
-     * The color name
-     */
     name: string;
-    /**
-     * The color swatches
-     */
     swatches: ColorSwatch[];
 }
-/**
- * The color swatch with delta
- */
 export interface ColorSwatchWithDelta extends ColorSwatch {
-    /**
-     * The color delta
-     */
     delta: number;
 }
-/**
- * The nearest color palette
- */
 export interface NearestColorPalette extends ColorPalette {
-    /**
-     * The nearest swatch
-     */
     nearestSwatch: ColorSwatchWithDelta;
-    /**
-     * The nearest lightness swatch
-     */
     nearestLightnessSwatch: ColorSwatchWithDelta;
 }
-/**
- * The matched color palette
- */
 export interface MatchedColorPalette extends ColorPalette {
-    /**
-     * The color map of the palette
-     */
     colorMap: Map<ColorNumber, string>;
     /**
-     * The main color swatch of the palette which number is 500
+     * The main color swatch with number 500
      */
     main: ColorSwatch;
-    /**
-     * The matched color swatch of the palette
-     */
     matched: ColorSwatch;
 }

package/dist/types/types/common.d.ts

@@ -6,9 +6,13 @@ export type MaybeArray<T> = T | T[];
 export type MaybeNullish<T> = T | null | undefined;
 export type MaybeUndefined<T> = T | undefined;
 export type MaybeNull<T> = T | null;
-export type Expand<T> = T extends T ? T : never;
-export type Not<A extends boolean> = A extends true ? false : A extends false ? true : never;
 export type IsString<T> = T extends string ? true : false;
+/**
+ * Inverts a boolean type.
+ *
+ * @example Not<true> = false, Not<false> = true
+ */
+export type Not<A extends boolean> = A extends true ? false : A extends false ? true : never;
 export interface EmptyObject {
 }
 export type AnyObject = Record<keyof any, any>;
@@ -22,4 +26,4 @@ export type NonFunctionGuard<T> = T extends Function ? never : T;
 export type OmitSymbol<T> = {
     [K in keyof T as K extends symbol ? never : K]: T[K];
 };
-export type { And, Except, HasOptionalKeys, HasRequiredKeys, If, IsAny, IsBooleanLiteral, IsEqual, IsFloat, IsInteger, IsLiteral, IsNever, IsNull, IsNullable, IsNumericLiteral, IsOptional, IsOptionalKeyOf, IsReadonlyKeyOf, IsRequiredKeyOf, IsStringLiteral, IsSymbolLiteral, IsTuple, IsUndefined, IsUnknown, IsWritableKeyOf, IterableElement, KebabCase, LiteralUnion, NonEmptyObject, NonEmptyString, NonEmptyTuple, OptionalKeysOf, Or, OverrideProperties, PartialDeep, Simplify as Prettify, SimplifyDeep as PrettifyDeep, Primitive, RequiredDeep, RequiredKeysOf, SetFieldType, SetOptional, SetParameterType, SetReadonly, SetRequired, SetReturnType } from 'type-fest';
+export type { And, Except, HasOptionalKeys, HasRequiredKeys, If, IsAny, IsBooleanLiteral, IsEqual, IsFloat, IsInteger, IsLiteral, IsNever, IsNull, IsNullable, IsNumericLiteral, IsOptional, IsOptionalKeyOf, IsReadonlyKeyOf, IsRequiredKeyOf, IsStringLiteral, IsSymbolLiteral, IsTuple, IsUndefined, IsUnknown, IsWritableKeyOf, IterableElement, KebabCase, LiteralUnion, NonEmptyObject, NonEmptyString, NonEmptyTuple, OptionalKeysOf, Or, OverrideProperties, PartialDeep, Primitive, RequiredDeep, RequiredKeysOf, SetFieldType, SetOptional, SetParameterType, SetReadonly, SetRequired, SetReturnType, Simplify, SimplifyDeep } from 'type-fest';

package/dist/types/types/deep-keys.d.ts

@@ -1,9 +1,37 @@
+/**
+ * Generates a range of numbers from 0 to N-1 as a tuple type.
+ * Used to create a union of valid array indices.
+ */
 type ComputeRange<N extends number, Result extends unknown[] = []> = Result["length"] extends N ? Result : ComputeRange<N, [...Result, Result["length"]]>;
+/**
+ * Union type of numbers from 0 to 39.
+ * Limits tuple index depth to prevent excessive type recursion.
+ */
 type Index40 = ComputeRange<40>[number];
+/**
+ * Checks if a type is a tuple (fixed-length array) with length <= 40.
+ * Returns the tuple type if valid, never otherwise.
+ */
 type IsTuple<T> = T extends readonly any[] & {
     length: infer Length;
 } ? Length extends Index40 ? T : never : never;
+/**
+ * Extracts all valid numeric indices from a tuple type.
+ * For [string, number, boolean], returns 0 | 1 | 2.
+ */
 type AllowedIndexes<Tuple extends readonly any[], Keys extends number = never> = Tuple extends readonly [] ? Keys : Tuple extends readonly [infer _, ...infer Tail] ? AllowedIndexes<Tail, Keys | Tail["length"]> : Keys;
+/**
+ * Creates dot-notation paths for nested properties.
+ * Converts TPrefix.NestedKey into string literal types.
+ */
 type DeepKeysPrefix<T, TPrefix, TDepth extends any[]> = TPrefix extends keyof T & (number | string) ? `${TPrefix}.${DeepKeys<T[TPrefix], [...TDepth, any]> & string}` : never;
+/**
+ * Extracts all possible deep property paths from an object type as dot-notation strings.
+ * Supports nested objects, tuples, and arrays up to 5 levels deep.
+ *
+ * @example
+ * type User = { name: string; address: { city: string; zip: number } };
+ * type Paths = DeepKeys<User>; // "name" | "address" | "address.city" | "address.zip"
+ */
 export type DeepKeys<T, TDepth extends any[] = []> = TDepth["length"] extends 5 ? never : unknown extends T ? string : T extends readonly any[] & IsTuple<T> ? AllowedIndexes<T> | DeepKeysPrefix<T, AllowedIndexes<T>, TDepth> : T extends any[] ? DeepKeys<T[number], [...TDepth, any]> : T extends Date ? never : T extends object ? (keyof T & string) | DeepKeysPrefix<T, keyof T, TDepth> : never;
 export {};

package/dist/types/utils/chrono.d.ts

@@ -13,12 +13,11 @@ export declare const DEFAULT_DATETIME_FORMAT = "YYYY-MM-DD HH:mm:ss";
 export declare const LOCALIZED_DATETIME_FORMAT = "LLLL";
 export declare const LOCALIZED_DATE_FORMAT = "LLdddd";
 /**
- * Format duration in seconds to human readable string
+ * Format duration to human readable string.
  *
- * @param seconds - Duration in seconds
+ * @param value - Duration value
  * @param unit - The unit of the duration (default: "seconds")
  * @returns Formatted duration string
- *
  * @example
  * ```ts
  * formatDuration(60) // "1分钟"
@@ -27,14 +26,13 @@ export declare const LOCALIZED_DATE_FORMAT = "LLdddd";
  * formatDuration(90061) // "1天1小时1分钟"
  * ```
  */
-export declare function formatDuration(seconds: number, unit?: DurationUnitType): string;
+export declare function formatDuration(value: number, unit?: DurationUnitType): string;
 /**
  * Parses a date string into a dayjs instance with optional format.
  *
  * @param date - The date string or Date object to parse
  * @param format - The format string to use for parsing (optional, ignored for Date objects)
  * @returns A dayjs instance
- *
  * @example
  * ```ts
  * parseDate("2025-11-10") // dayjs instance
@@ -51,7 +49,6 @@ export declare function parseDate(date: string | Date, format?: MaybeNull<string
  *
  * @param date - The date string to parse
  * @returns A dayjs instance if parsing succeeds, null otherwise
- *
  * @example
  * ```ts
  * tryParseDate("2025-11-10 16:30:45") // dayjs instance
@@ -67,7 +64,6 @@ export declare function tryParseDate(date: string): MaybeNull<Dayjs>;
  * @param date - The dayjs instance to format
  * @param format - The format string (defaults to "YYYY-MM-DD HH:mm:ss")
  * @returns The formatted date string
- *
  * @example
  * ```ts
  * formatDate(dayjs()) // "2025-11-10 16:30:45"
@@ -80,7 +76,6 @@ export declare function formatDate(date: Dayjs, format?: string): string;
  * Gets the current time as a dayjs instance.
  *
  * @returns The current time as a dayjs instance
- *
  * @example
  * ```ts
  * const now = getNow() // dayjs instance
@@ -92,7 +87,6 @@ export declare function getNow(): Dayjs;
  * Gets the current date string in "YYYY-MM-DD" format.
  *
  * @returns The current date string
- *
  * @example
  * ```ts
  * getNowDateString() // "2025-11-10"
@@ -103,7 +97,6 @@ export declare function getNowDateString(): string;
  * Gets the current time string in "HH:mm:ss" format.
  *
  * @returns The current time string
- *
  * @example
  * ```ts
  * getNowTimeString() // "16:30:45"
@@ -114,7 +107,6 @@ export declare function getNowTimeString(): string;
  * Gets the current date time string in "YYYY-MM-DD HH:mm:ss" format.
  *
  * @returns The current date time string
- *
  * @example
  * ```ts
  * getNowDateTimeString() // "2025-11-10 16:30:45"
@@ -125,7 +117,6 @@ export declare function getNowDateTimeString(): string;
  * Gets the current date time in a localized full format.
  *
  * @returns The localized date time string
- *
  * @example
  * ```ts
  * // With zh-cn locale
@@ -150,7 +141,6 @@ declare const FORMAT_MAP: {
  *
  * @param mode - The temporal picker mode
  * @returns An array of format strings for the specified mode
- *
  * @example
  * ```ts
  * getTemporalFormats("date") // ["YYYY-MM-DD", "YYYY/MM/DD", ...]

package/dist/types/utils/error.d.ts

@@ -1,38 +1,22 @@
 import * as stackTrace from "stacktrace-js";
 export type StackFrame = stackTrace.StackFrame;
 /**
- * Parse the error stack, filter the stack frames
- *
- * @param error The error to parse
- * @param filter The filter function to filter the stack frames
- * @returns The parsed stack frames
+ * Parse error stack and optionally filter frames.
  */
 export declare function parseErrorStack(error: Error, filter?: (frame: StackFrame) => boolean): Promise<StackFrame[]>;
 /**
- * Filter the user frame
- *
- * @param stackFrame The stack frame to filter
- * @returns The filtered stack frame
+ * Filter to exclude node_modules frames (user code only).
  */
 export declare function filterUserFrame(stackFrame: StackFrame): boolean;
 /**
- * Get the sanitized error stack
- *
- * @param error The error to sanitize
- * @returns The sanitized error stack
+ * Get sanitized error stack with user frames only.
  */
 export declare function getSanitizedErrorStack(error: Error): Promise<string>;
 /**
- * Get the current stack
- *
- * @param filter The filter function to filter the stack frames
- * @returns The current stack
+ * Get current call stack.
  */
 export declare function getCurrentStack(filter?: (frame: StackFrame) => boolean): Promise<StackFrame[]>;
 /**
- * Get the current stack synchronously
- *
- * @param filter The filter function to filter the stack frames
- * @returns The current stack
+ * Get current call stack synchronously.
  */
 export declare function getCurrentStackSync(filter?: (frame: StackFrame) => boolean): StackFrame[];

package/dist/types/utils/event.d.ts

@@ -1,55 +1,33 @@
 import { EventHandlerMap, EventType, Handler } from 'mitt';
 /**
- * A type-safe event emitter wrapper around mitt library.
- * Provides a clean API for event subscription, emission, and cleanup.
- *
- * @template TEvents - A record type defining the available events and their payload types
+ * Type-safe event emitter wrapper around mitt library.
  */
-export declare class EventEmitter<TEvents extends Record<EventType, unknown>> {
+export declare class EventEmitter<TEvents extends Record<EventType, any> = Record<EventType, unknown>> {
     #private;
     /**
-     * Subscribe to an event with a listener function.
-     * Returns an unsubscribe function for easy cleanup.
-     *
-     * @param eventType - The type of event to listen for
-     * @param eventListener - The function to call when the event is emitted
-     * @returns A function that removes this specific listener when called
+     * Subscribe to an event. Returns unsubscribe function.
      */
     on<const TEventType extends keyof TEvents>(eventType: TEventType, eventListener: Handler<TEvents[TEventType]>): () => void;
     /**
-     * Emit an event with the specified payload.
-     * All registered listeners for this event type will be called synchronously.
-     *
-     * @param eventType - The type of event to emit
-     * @param eventPayload - The data to pass to all listeners
+     * Emit an event with optional payload.
      */
     emit<const TEventType extends keyof TEvents>(eventType: undefined extends TEvents[TEventType] ? TEventType : never): void;
     emit<const TEventType extends keyof TEvents>(eventType: TEventType, eventPayload: TEvents[TEventType]): void;
     /**
-     * Remove a specific listener for an event type.
-     * If no listener is provided, removes all listeners for that event type.
-     *
-     * @param eventType - The type of event to remove listeners from
-     * @param eventListener - Optional specific listener to remove
+     * Remove listener(s) for an event type.
      */
     off<const TEventType extends keyof TEvents>(eventType: TEventType, eventListener?: Handler<TEvents[TEventType]>): void;
     /**
-     * Remove all event listeners from all event types.
-     * Useful for cleanup when the emitter is no longer needed.
+     * Remove all listeners from all events.
      */
     clear(): void;
     /**
-     * Get all registered listeners for debugging purposes.
-     * Returns a Map of event types to their listener arrays.
+     * Get all registered listeners (for debugging).
      */
     getAllListeners(): EventHandlerMap<TEvents>;
 }
 /**
- * Factory function to create a new EventEmitter instance.
- * Provides a more functional approach to creating event emitters.
- *
- * @template TEvents - A record type defining the available events and their payload types
- * @returns A new EventEmitter instance
+ * Create a new EventEmitter instance.
  *
  * @example
  * ```typescript
@@ -64,5 +42,5 @@ export declare class EventEmitter<TEvents extends Record<EventType, unknown>> {
  * });
  * ```
  */
-export declare function createEventEmitter<TEvents extends Record<EventType, unknown>>(): EventEmitter<TEvents>;
+export declare function createEventEmitter<TEvents extends Record<EventType, any> = Record<EventType, unknown>>(): EventEmitter<TEvents>;
 export { type Handler as EventHandler, type EventType } from 'mitt';

package/dist/types/utils/format.d.ts

@@ -4,7 +4,6 @@
  * @param bytes - Number of bytes
  * @param decimals - Number of decimal places (default: 2)
  * @returns Formatted string with unit (B, KB, MB, GB, TB, PB)
- *
  * @example
  * ```ts
  * formatBytes(1024) // "1 KB"
@@ -20,7 +19,6 @@ export declare function formatBytes(bytes: number, decimals?: number): string;
  * @param num - Number to format
  * @param decimals - Number of decimal places (default: 2)
  * @returns Formatted string with unit (K, M, B, T)
- *
  * @example
  * ```ts
  * formatNumber(1000) // "1 K"

package/dist/types/utils/function.d.ts

@@ -1,59 +1,27 @@
 import { Awaitable, MaybeUndefined } from '../types';
-/**
- * Awaitable function invocation options.
- */
 export interface AwaitableFnInvocationOptions<in TResult, in out TContext = unknown> {
-    /**
-     * The function to call before invoking the awaitable function.
-     */
     onInvoke?: () => MaybeUndefined<TContext>;
-    /**
-     * The function to call when the awaitable function succeeds.
-     */
     onSuccess?: (result: TResult, context: MaybeUndefined<TContext>) => void;
-    /**
-     * The function to call when the awaitable function fails.
-     */
     onError?: (error: unknown, context: MaybeUndefined<TContext>) => void;
-    /**
-     * The function to call after invoking the awaitable function.
-     */
     onFinally?: (context: MaybeUndefined<TContext>) => void;
 }
 /**
  * Checks if a function is an async function.
- *
- * @param fn - The function to check.
- * @returns `true` if the function is an async function, `false` otherwise.
  */
 export declare function isAsyncFunction(fn: Function): fn is (...args: any[]) => Promise<any>;
 /**
- * Invokes an awaitable function.
- *
- * @param fn - The awaitable function to invoke.
- * @param args - The arguments to pass to the awaitable function.
- * @param options - The options to pass to the awaitable function.
- * @returns The result of the awaitable function.
+ * Invokes an awaitable function with lifecycle hooks.
  */
 export declare function invokeAwaitableFn<TArgs extends any[] = any[], TResult = unknown, TContext = unknown>(fn: (...args: TArgs) => Awaitable<TResult>, args: NoInfer<TArgs>, options: AwaitableFnInvocationOptions<NoInfer<TResult>, TContext>): Promise<TResult>;
 /**
- * Returns the value itself.
- *
- * @param value - The value to return.
- * @returns The value itself.
+ * Returns the value itself (identity function).
  */
 export declare function identity<T>(value: T): T;
 /**
- * Creates a function that throws an error indicating the feature/function is not implemented.
- *
- * @param feature - The feature/function name to include in the error message.
- * @returns A function that throws an error indicating the feature/function is not implemented.
+ * Creates a function that throws a not-implemented error.
  */
 export declare function createThrowNotImplementedFn(feature?: string): () => never;
 /**
- * Throws an error indicating the feature/function is not implemented.
- *
- * @param feature - The feature/function name to include in the error message.
- * @throws Always throws an Error to indicate a missing implementation.
+ * Throws a not-implemented error.
  */
 export declare function throwNotImplemented(feature?: string): never;

package/dist/types/utils/id.d.ts

@@ -1,6 +1,6 @@
 /**
- * Generates a unique ID.
+ * Generates a unique ID based on browser fingerprint.
  *
- * @returns A unique ID.
+ * @returns A unique ID string
  */
 export declare function generateId(): string;

package/dist/types/utils/key.d.ts

@@ -1,7 +1,5 @@
 /**
- * Generate a hash key from the given value.
- *
- * @param key - The value to generate a hash key from.
- * @returns The hash key.
+ * Generate a stable hash key from any value by serializing to JSON.
+ * Objects are normalized with sorted keys for consistent hashing.
  */
 export declare function hashKey(key: unknown): string;