@omnitron-dev/prism 0.1.3 → 0.3.0

package/dist/utils/async-lock.d.ts

@@ -0,0 +1,169 @@
+/**
+ * AsyncLock Utility
+ *
+ * Prevents race conditions in async operations like token refresh.
+ * Ensures only one operation runs at a time, with subsequent calls
+ * waiting for and sharing the result of the in-flight operation.
+ *
+ * @module utils
+ */
+/**
+ * Options for AsyncLock.
+ */
+export interface AsyncLockOptions {
+    /** Timeout in milliseconds for the lock acquisition (default: 30000) */
+    timeout?: number;
+    /** Custom error message for timeout */
+    timeoutMessage?: string;
+}
+/**
+ * Result from a locked operation.
+ */
+export interface AsyncLockResult<T> {
+    /** The result value */
+    value: T;
+    /** Whether this call executed the operation (vs waiting for another) */
+    wasExecutor: boolean;
+}
+/**
+ * State of the lock.
+ */
+export type AsyncLockState = 'idle' | 'locked' | 'releasing';
+/**
+ * AsyncLock prevents race conditions in concurrent async operations.
+ *
+ * Use cases:
+ * - Token refresh: Multiple API calls fail simultaneously, only one should refresh
+ * - Resource initialization: Expensive setup should happen once
+ * - Cache population: Prevent thundering herd problem
+ *
+ * @example
+ * ```tsx
+ * import { AsyncLock } from '@omnitron-dev/prism/utils';
+ *
+ * const tokenRefreshLock = new AsyncLock({ timeout: 10000 });
+ *
+ * async function refreshToken(): Promise<string> {
+ *   const { value: newToken } = await tokenRefreshLock.acquire(
+ *     'refresh-token',
+ *     async () => {
+ *       // This only runs once even if called concurrently
+ *       const response = await fetch('/auth/refresh', { method: 'POST' });
+ *       const data = await response.json();
+ *       return data.accessToken;
+ *     }
+ *   );
+ *   return newToken;
+ * }
+ *
+ * // Multiple concurrent calls share the same result
+ * const [token1, token2, token3] = await Promise.all([
+ *   refreshToken(), // Executes the actual refresh
+ *   refreshToken(), // Waits for first to complete
+ *   refreshToken(), // Waits for first to complete
+ * ]);
+ * // token1 === token2 === token3
+ * ```
+ */
+export declare class AsyncLock {
+    private locks;
+    private resolvers;
+    private rejecters;
+    private options;
+    constructor(options?: AsyncLockOptions);
+    /**
+     * Current state of a specific lock.
+     */
+    getState(key: string): AsyncLockState;
+    /**
+     * Check if a specific lock is currently held.
+     */
+    isLocked(key: string): boolean;
+    /**
+     * Get all currently active lock keys.
+     */
+    getActiveLocks(): string[];
+    /**
+     * Acquire the lock and execute the operation.
+     * If the lock is already held, waits for the existing operation.
+     *
+     * @param key - Unique identifier for this lock
+     * @param operation - Async operation to execute
+     * @returns Result with the value and whether this call was the executor
+     */
+    acquire<T>(key: string, operation: () => Promise<T>): Promise<AsyncLockResult<T>>;
+    /**
+     * Try to acquire the lock without waiting.
+     * Returns immediately if lock is held.
+     *
+     * @param key - Unique identifier for this lock
+     * @param operation - Async operation to execute
+     * @returns Result or null if lock was already held
+     */
+    tryAcquire<T>(key: string, operation: () => Promise<T>): Promise<AsyncLockResult<T> | null>;
+    /**
+     * Force release a lock (use with caution).
+     * This will reject all waiters with the provided error.
+     */
+    forceRelease(key: string, error?: Error): void;
+    /**
+     * Clear all locks (use with caution, e.g., on logout).
+     */
+    clearAll(error?: Error): void;
+    /**
+     * Wait for a promise with timeout.
+     */
+    private waitWithTimeout;
+}
+/**
+ * Error thrown when lock acquisition times out.
+ */
+export declare class AsyncLockTimeoutError extends Error {
+    readonly name = "AsyncLockTimeoutError";
+    constructor(message: string);
+}
+/**
+ * Create a singleton AsyncLock instance for a specific use case.
+ *
+ * @example
+ * ```tsx
+ * import { createAsyncLock } from '@omnitron-dev/prism/utils';
+ *
+ * // Create a singleton lock for token refresh
+ * const tokenLock = createAsyncLock({ timeout: 10000 });
+ *
+ * // Use in multiple places - same lock instance
+ * async function apiCall() {
+ *   if (isTokenExpired()) {
+ *     await tokenLock.acquire('token', refreshToken);
+ *   }
+ *   // Make API call...
+ * }
+ * ```
+ */
+export declare function createAsyncLock(options?: AsyncLockOptions): AsyncLock;
+/**
+ * Create a pre-configured lock for token refresh operations.
+ * Uses sensible defaults for auth token refresh scenarios.
+ */
+export declare function createTokenRefreshLock(): AsyncLock;
+export declare function withLock<T>(key: string, operation: () => Promise<T>, options?: AsyncLockOptions): Promise<T>;
+/**
+ * Decorator factory for methods that should be locked.
+ * Use with class methods to ensure single execution.
+ *
+ * @example
+ * ```tsx
+ * import { locked } from '@omnitron-dev/prism/utils';
+ *
+ * class AuthService {
+ *   @locked('refresh')
+ *   async refreshToken(): Promise<string> {
+ *     // Only one instance runs at a time
+ *     return await this.doRefresh();
+ *   }
+ * }
+ * ```
+ */
+export declare function locked(key: string, options?: AsyncLockOptions): <T extends (...args: unknown[]) => Promise<unknown>>(_target: object, _propertyKey: string, descriptor: TypedPropertyDescriptor<T>) => TypedPropertyDescriptor<T>;
+//# sourceMappingURL=async-lock.d.ts.map

package/dist/utils/async-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-lock.d.ts","sourceRoot":"","sources":["../../src/utils/async-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,uBAAuB;IACvB,KAAK,EAAE,CAAC,CAAC;IACT,wEAAwE;IACxE,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,QAAQ,GAAG,WAAW,CAAC;AAM7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,KAAK,CAA4C;IACzD,OAAO,CAAC,SAAS,CAAoD;IACrE,OAAO,CAAC,SAAS,CAAoD;IACrE,OAAO,CAAC,OAAO,CAA6B;IAE5C,YAAY,OAAO,GAAE,gBAAqB,EAKzC;IAED;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAEpC;IAED;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE7B;IAED;;OAEG;IACH,cAAc,IAAI,MAAM,EAAE,CAEzB;IAED;;;;;;;OAOG;IACG,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CA6CtF;IAED;;;;;;;OAOG;IACG,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAKhG;IAED;;;OAGG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAQ7C;IAED;;OAEG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAI5B;IAED;;OAEG;YACW,eAAe;CAgB9B;AAMD;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,2BAA2B;IAExC,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAErE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,SAAS,CAKlD;AAuBD,wBAAsB,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,CAAC,CAAC,CAIlH;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,IAG3C,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,WACxD,MAAM,gBACD,MAAM,cACR,uBAAuB,CAAC,CAAC,CAAC,KACrC,uBAAuB,CAAC,CAAC,CAAC,CAc9B"}

package/dist/utils/cn.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Class Name Utility
+ *
+ * Combines clsx for conditional classes with optional Tailwind merge.
+ * Inspired by shadcn/ui's cn() utility and minimal-shared's mergeClasses.
+ *
+ * @module utils/cn
+ */
+import { type ClassValue } from 'clsx';
+/**
+ * Combines class names using clsx.
+ *
+ * This is a simplified version without tailwind-merge since Prism
+ * primarily uses MUI's sx prop for styling. For Tailwind projects,
+ * consider adding tailwind-merge.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * cn('px-4 py-2', 'bg-blue-500')
+ *
+ * // Conditional classes
+ * cn('base-class', isActive && 'active', isDisabled && 'disabled')
+ *
+ * // With objects
+ * cn('base', { active: isActive, disabled: isDisabled })
+ *
+ * // With arrays
+ * cn(['class1', 'class2'], condition && 'class3')
+ * ```
+ */
+export declare function cn(...inputs: ClassValue[]): string;
+/**
+ * Type for class value inputs.
+ * Re-exported for convenience.
+ */
+export type { ClassValue };
+/**
+ * State props for mergeClasses.
+ * Values can be:
+ * - boolean: includes key as class name if true
+ * - undefined: excluded
+ * - [boolean, string]: includes string as class name if boolean is true
+ */
+export type StateProps = {
+    [key: string]: boolean | undefined | [boolean, string];
+};
+/**
+ * Merges class names with state-based class names.
+ *
+ * This utility provides an alternative API for state-based class toggling,
+ * particularly useful when class names differ from state keys.
+ *
+ * @param className - Base class name(s)
+ * @param state - State object with boolean or [boolean, className] values
+ * @returns Merged class names string
+ *
+ * @example
+ * ```tsx
+ * // Basic state-based merging
+ * mergeClasses('item', {
+ *   'item--active': isActive,
+ *   'item--disabled': isDisabled,
+ * });
+ * // Output: 'item item--active' (if isActive is true)
+ *
+ * // With tuple format for different class names
+ * mergeClasses('btn', {
+ *   primary: [isPrimary, 'btn-primary'],
+ *   secondary: [isSecondary, 'btn-secondary'],
+ * });
+ *
+ * // With array of base classes
+ * mergeClasses(['nav', 'nav--main'], {
+ *   'nav--open': isOpen,
+ * });
+ * ```
+ */
+export declare function mergeClasses(className?: string | (string | undefined)[] | null, state?: StateProps): string;
+//# sourceMappingURL=cn.d.ts.map

package/dist/utils/cn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cn.d.ts","sourceRoot":"","sources":["../../src/utils/cn.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAQ,KAAK,UAAU,EAAE,MAAM,MAAM,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,EAAE,CAAC,GAAG,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,CAElD;AAED;;;GAGG;AACH,YAAY,EAAE,UAAU,EAAE,CAAC;AAM3B;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;CACxD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,YAAY,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,EAAE,UAAU,GAAG,MAAM,CAkB3G"}

package/dist/utils/cookies.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Cookie Utilities
+ *
+ * Type-safe cookie management with JSON serialization.
+ *
+ * @module utils
+ */
+/**
+ * Cookie options for setting cookies.
+ */
+export interface CookieOptions {
+    /** Enable secure flag (HTTPS only) */
+    secure?: boolean;
+    /** Days until expiration */
+    daysUntilExpiration?: number;
+    /** SameSite policy */
+    sameSite?: 'strict' | 'lax' | 'none';
+    /** Cookie domain */
+    domain?: string;
+    /** Cookie path */
+    path?: string;
+}
+/**
+ * Check if cookies are available.
+ *
+ * @returns {boolean} True if cookies are available
+ */
+export declare function cookiesAvailable(): boolean;
+/**
+ * Get a cookie value with JSON parsing.
+ *
+ * @template T - Type of the stored value
+ * @param {string} key - Cookie name
+ * @returns {T | null} Parsed value or null
+ *
+ * @example
+ * ```ts
+ * const user = getCookie<User>('user');
+ * ```
+ */
+export declare function getCookie<T>(key: string): T | null;
+/**
+ * Set a cookie with JSON serialization.
+ *
+ * @template T - Type of the value
+ * @param {string} key - Cookie name
+ * @param {T} value - Value to store
+ * @param {CookieOptions} [options] - Cookie options
+ *
+ * @example
+ * ```ts
+ * setCookie('user', { name: 'John' }, { daysUntilExpiration: 7 });
+ * ```
+ */
+export declare function setCookie<T>(key: string, value: T, options?: CookieOptions): void;
+/**
+ * Remove a cookie.
+ *
+ * @param {string} key - Cookie name
+ * @param {Pick<CookieOptions, 'domain' | 'path'>} [options] - Cookie options
+ *
+ * @example
+ * ```ts
+ * removeCookie('user');
+ * ```
+ */
+export declare function removeCookie(key: string, options?: Pick<CookieOptions, 'domain' | 'path'>): void;
+//# sourceMappingURL=cookies.d.ts.map

package/dist/utils/cookies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookies.d.ts","sourceRoot":"","sources":["../../src/utils/cookies.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,sCAAsC;IACtC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,4BAA4B;IAC5B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,sBAAsB;IACtB,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IACrC,oBAAoB;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kBAAkB;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAa1C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAqBlD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,GAAE,aAAkB,GAAG,IAAI,CAgCrF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,MAAM,CAAM,GAAG,IAAI,CAcpG"}

package/dist/utils/create-classes.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Class Name Factory
+ *
+ * Creates prefixed CSS class names for consistent component styling.
+ * Uses a configurable prefix to avoid collisions with other libraries.
+ *
+ * @module utils/create-classes
+ */
+/**
+ * Default class prefix for Prism components.
+ * Can be overridden via PRISM_CLASS_PREFIX environment variable.
+ */
+export declare const DEFAULT_CLASS_PREFIX = "prism";
+/**
+ * Set the global class prefix for all Prism components.
+ *
+ * @param prefix - New class prefix to use
+ *
+ * @example
+ * ```ts
+ * setClassPrefix('my-app');
+ * createClasses('button__root'); // => "my-app__button__root"
+ * ```
+ */
+export declare function setClassPrefix(prefix: string): void;
+/**
+ * Get the current class prefix.
+ *
+ * @returns Current class prefix
+ */
+export declare function getClassPrefix(): string;
+/**
+ * Create a prefixed CSS class name.
+ *
+ * @param className - Class name suffix (e.g., "button__root")
+ * @returns Prefixed class name (e.g., "prism__button__root")
+ *
+ * @example
+ * ```ts
+ * createClasses('chart__root')
+ * // => "prism__chart__root"
+ *
+ * createClasses('chart__loading')
+ * // => "prism__chart__loading"
+ * ```
+ */
+export declare function createClasses(className: string): string;
+/**
+ * Create multiple prefixed CSS class names.
+ *
+ * @param classNames - Array of class name suffixes
+ * @returns Object mapping original names to prefixed names
+ *
+ * @example
+ * ```ts
+ * const classes = createClassesObject(['root', 'loading', 'label']);
+ * // => { root: "prism__root", loading: "prism__loading", label: "prism__label" }
+ * ```
+ */
+export declare function createClassesObject<T extends string>(classNames: readonly T[]): Record<T, string>;
+/**
+ * Create a class name factory for a specific component.
+ *
+ * @param componentName - Component name (e.g., "chart", "button")
+ * @returns Function that creates prefixed class names for that component
+ *
+ * @example
+ * ```ts
+ * const chartClass = createComponentClasses('chart');
+ * chartClass('root');    // => "prism__chart__root"
+ * chartClass('loading'); // => "prism__chart__loading"
+ * ```
+ */
+export declare function createComponentClasses(componentName: string): (suffix: string) => string;
+/**
+ * Create a class name object for a specific component with predefined suffixes.
+ *
+ * @param componentName - Component name (e.g., "chart", "button")
+ * @param suffixes - Array of class name suffixes
+ * @returns Object mapping suffix names to prefixed class names
+ *
+ * @example
+ * ```ts
+ * const chartClasses = createComponentClasses('chart', ['root', 'loading', 'label'] as const);
+ * chartClasses.root;    // => "prism__chart__root"
+ * chartClasses.loading; // => "prism__chart__loading"
+ * ```
+ */
+export declare function createComponentClasses<T extends string>(componentName: string, suffixes: readonly T[]): Record<T, string>;
+//# sourceMappingURL=create-classes.d.ts.map

package/dist/utils/create-classes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-classes.d.ts","sourceRoot":"","sources":["../../src/utils/create-classes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH;;;GAGG;AACH,eAAO,MAAM,oBAAoB,UAAU,CAAC;AAI5C;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAEnD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,EAAE,UAAU,EAAE,SAAS,CAAC,EAAE,GAAG,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CAQjG;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;AAE1F;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,MAAM,EACrD,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,SAAS,CAAC,EAAE,GACrB,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC"}

package/dist/utils/errors.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Error Handling Utilities
+ *
+ * Comprehensive error handling with i18n support, error classification,
+ * and retry logic for robust frontend applications.
+ *
+ * @module utils
+ */
+/**
+ * Error codes for classification.
+ */
+export type ErrorCode = 'AUTH_REQUIRED' | 'AUTH_EXPIRED' | 'AUTH_INVALID' | 'AUTH_FORBIDDEN' | 'AUTH_MFA_REQUIRED' | 'AUTH_DEVICE_BLOCKED' | 'NETWORK_ERROR' | 'NETWORK_TIMEOUT' | 'NETWORK_OFFLINE' | 'VALIDATION_ERROR' | 'VALIDATION_REQUIRED' | 'VALIDATION_FORMAT' | 'VALIDATION_RANGE' | 'SERVER_ERROR' | 'SERVER_UNAVAILABLE' | 'SERVER_MAINTENANCE' | 'NOT_FOUND' | 'CONFLICT' | 'RATE_LIMITED' | 'QUOTA_EXCEEDED' | 'UNKNOWN_ERROR' | string;
+/**
+ * Severity levels for errors.
+ */
+export type ErrorSeverity = 'error' | 'warning' | 'info';
+/**
+ * Error context for i18n.
+ */
+export interface ErrorContext {
+    /** Error code for lookup */
+    code: ErrorCode;
+    /** HTTP status code if applicable */
+    status?: number;
+    /** Field name for validation errors */
+    field?: string;
+    /** Additional interpolation values */
+    values?: Record<string, string | number>;
+    /** Original error message (fallback) */
+    message?: string;
+    /** Retry information */
+    retryAfter?: number;
+    /** Severity level */
+    severity?: ErrorSeverity;
+}
+/**
+ * Translated error result.
+ */
+export interface TranslatedError {
+    /** Translated title */
+    title: string;
+    /** Translated message */
+    message: string;
+    /** Error code */
+    code: ErrorCode;
+    /** Severity */
+    severity: ErrorSeverity;
+    /** Action hint (e.g., "Please log in again") */
+    action?: string;
+    /** Retry after seconds */
+    retryAfter?: number;
+    /** Is this a retryable error */
+    canRetry: boolean;
+}
+/**
+ * Translation function type.
+ */
+export type TranslateFn = (key: string, values?: Record<string, string | number>) => string;
+/**
+ * Error messages dictionary type.
+ */
+export interface ErrorMessages {
+    [code: string]: {
+        title: string;
+        message: string;
+        action?: string;
+    };
+}
+/**
+ * Default error messages in English.
+ * Can be replaced with i18n translations.
+ */
+export declare const DEFAULT_ERROR_MESSAGES: ErrorMessages;
+/**
+ * Classify an error by HTTP status code.
+ */
+export declare function classifyHttpError(status: number): ErrorCode;
+/**
+ * Check if an error is a network error.
+ *
+ * Deciding by the words a message happens to contain cuts the wrong way in
+ * both directions. Matching "network", "connection" or "offline" anywhere in
+ * any message classified "Connection to the payment provider was declined"
+ * and "This network is not supported in your region" — ordinary server
+ * answers — as the user's connection failing, which sends them to check a
+ * router instead of reading what the server said. Against a corpus of the
+ * eight shapes a real network failure takes and five that only mention one,
+ * the old predicate was right 7 times out of 13.
+ *
+ * So: an errno if the error carries one, the engine's own wording if `fetch`
+ * rejected (it rejects with a TypeError and nothing else for a network-level
+ * failure), and axios's exact `Network Error` — which is its whole message,
+ * not a fragment of a sentence.
+ */
+export declare function isNetworkError(error: unknown): boolean;
+/**
+ * Check if an error is retryable.
+ */
+export declare function isRetryableError(code: ErrorCode): boolean;
+/**
+ * Get severity for an error code.
+ */
+export declare function getErrorSeverity(code: ErrorCode): ErrorSeverity;
+/**
+ * Create an error translator with custom messages or i18n function.
+ *
+ * @example
+ * ```tsx
+ * // With custom messages
+ * const translate = createErrorTranslator({
+ *   messages: {
+ *     AUTH_REQUIRED: {
+ *       title: 'Необходима авторизация',
+ *       message: 'Пожалуйста, войдите в систему.',
+ *     },
+ *   },
+ * });
+ *
+ * // With i18n library
+ * const translate = createErrorTranslator({
+ *   t: (key, values) => i18n.t(key, values),
+ * });
+ *
+ * const error = translate({ code: 'AUTH_REQUIRED', status: 401 });
+ * // { title: 'Необходима авторизация', message: '...', ... }
+ * ```
+ */
+export declare function createErrorTranslator(options: {
+    messages?: ErrorMessages;
+    t?: TranslateFn;
+    fallbackMessages?: ErrorMessages;
+}): (context: ErrorContext) => TranslatedError;
+/**
+ * Extract error context from various error types.
+ *
+ * @example
+ * ```tsx
+ * try {
+ *   await api.call();
+ * } catch (error) {
+ *   const context = extractErrorContext(error);
+ *   const translated = translateError(context);
+ *   showNotification(translated);
+ * }
+ * ```
+ */
+export declare function extractErrorContext(error: unknown): ErrorContext;
+/**
+ * Retry configuration.
+ */
+export interface RetryConfig {
+    /** Maximum number of retries */
+    maxRetries?: number;
+    /** Initial delay in ms */
+    initialDelay?: number;
+    /** Maximum delay in ms */
+    maxDelay?: number;
+    /** Exponential backoff factor */
+    backoffFactor?: number;
+    /** Add jitter to delays */
+    jitter?: boolean;
+    /** Custom retry condition */
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+    /** Called before each retry */
+    onRetry?: (error: unknown, attempt: number, delay: number) => void;
+}
+/**
+ * Execute an async operation with automatic retry.
+ *
+ * @example
+ * ```tsx
+ * const result = await withRetry(
+ *   () => fetch('/api/data'),
+ *   {
+ *     maxRetries: 3,
+ *     onRetry: (error, attempt, delay) => {
+ *       console.log(`Retry ${attempt} after ${delay}ms`);
+ *     },
+ *   }
+ * );
+ * ```
+ */
+export declare function withRetry<T>(operation: () => Promise<T>, config?: RetryConfig): Promise<T>;
+/**
+ * Check if error is a chunk load error (code splitting failure).
+ */
+export declare function isChunkLoadError(error: unknown): boolean;
+/**
+ * Check if error is a session expiry error.
+ */
+export declare function isSessionExpiredError(error: unknown): boolean;
+/**
+ * Create a handler for error boundary recovery.
+ */
+export declare function createErrorRecoveryHandler(options: {
+    onChunkError?: () => void;
+    onSessionExpired?: () => void;
+    onNetworkError?: () => void;
+    onGenericError?: (error: unknown) => void;
+}): (error: unknown) => void;
+//# sourceMappingURL=errors.d.ts.map

package/dist/utils/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"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"}