@omnitron-dev/prism 0.1.3 → 0.3.0

package/dist/utils/jwt.d.ts

@@ -0,0 +1,227 @@
+/**
+ * JWT Utilities
+ *
+ * Client-side JWT decoding and validation utilities.
+ * These utilities do NOT verify signatures - they only decode and check expiration.
+ * For signature verification, use server-side libraries.
+ *
+ * @module utils
+ */
+/**
+ * Standard JWT claims.
+ * @see https://datatracker.ietf.org/doc/html/rfc7519#section-4.1
+ */
+export interface JwtStandardClaims {
+    /** Issuer */
+    iss?: string;
+    /** Subject */
+    sub?: string;
+    /** Audience */
+    aud?: string | string[];
+    /** Expiration time (Unix timestamp in seconds) */
+    exp?: number;
+    /** Not before (Unix timestamp in seconds) */
+    nbf?: number;
+    /** Issued at (Unix timestamp in seconds) */
+    iat?: number;
+    /** JWT ID */
+    jti?: string;
+}
+/**
+ * JWT payload with custom claims.
+ * Extends standard claims with any additional properties.
+ */
+export interface JwtPayload extends JwtStandardClaims {
+    /** User ID (common custom claim) */
+    userId?: string;
+    /** Email (common custom claim) */
+    email?: string;
+    /** Roles (common custom claim) */
+    roles?: string[];
+    /** Permissions (common custom claim) */
+    permissions?: string[];
+    /** Any additional custom claims */
+    [key: string]: unknown;
+}
+/**
+ * JWT validation options.
+ */
+export interface JwtValidationOptions {
+    /** Clock skew tolerance in seconds (default: 60) */
+    clockTolerance?: number;
+    /** Require expiration claim (default: true) */
+    requireExp?: boolean;
+}
+/**
+ * JWT decode result.
+ */
+export interface JwtDecodeResult<T extends JwtPayload = JwtPayload> {
+    /** Decoded header */
+    header: {
+        alg: string;
+        typ?: string;
+        [key: string]: unknown;
+    };
+    /** Decoded payload */
+    payload: T;
+    /** Original signature (base64url encoded, NOT verified) */
+    signature: string;
+}
+/**
+ * Decode a JWT token without verifying the signature.
+ *
+ * ⚠️ WARNING: This function does NOT verify the signature.
+ * Only use for client-side display purposes. Never trust decoded
+ * data for authorization decisions without server-side verification.
+ *
+ * @param token - The JWT token string
+ * @returns Decoded JWT parts (header, payload, signature)
+ * @throws Error if the token is malformed
+ *
+ * @example
+ * ```tsx
+ * const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';
+ *
+ * try {
+ *   const { header, payload } = jwtDecode(token);
+ *   console.log('Algorithm:', header.alg);
+ *   console.log('User ID:', payload.sub);
+ *   console.log('Expires:', new Date(payload.exp! * 1000));
+ * } catch (error) {
+ *   console.error('Invalid token:', error.message);
+ * }
+ * ```
+ */
+export declare function jwtDecode<T extends JwtPayload = JwtPayload>(token: string): JwtDecodeResult<T>;
+/**
+ * Decode only the payload from a JWT token.
+ * Convenience function when you only need the claims.
+ *
+ * @param token - The JWT token string
+ * @returns Decoded payload
+ * @throws Error if the token is malformed
+ *
+ * @example
+ * ```tsx
+ * const payload = jwtDecodePayload(token);
+ * console.log('User:', payload.email);
+ * ```
+ */
+export declare function jwtDecodePayload<T extends JwtPayload = JwtPayload>(token: string): T;
+/**
+ * Check if a JWT token is expired.
+ *
+ * @param token - The JWT token string
+ * @param options - Validation options
+ * @returns true if the token is expired or invalid, false if still valid
+ *
+ * @example
+ * ```tsx
+ * if (isTokenExpired(token)) {
+ *   // Redirect to login or refresh token
+ *   refreshAccessToken();
+ * }
+ * ```
+ */
+export declare function isTokenExpired(token: string, options?: JwtValidationOptions): boolean;
+/**
+ * Check if a JWT token is valid (not expired, not before nbf).
+ *
+ * @param token - The JWT token string
+ * @param options - Validation options
+ * @returns true if the token is valid, false otherwise
+ *
+ * @example
+ * ```tsx
+ * function AuthProvider({ children }) {
+ *   const [token] = useLocalStorage('accessToken');
+ *
+ *   if (!token || !isValidToken(token)) {
+ *     return <Navigate to="/login" />;
+ *   }
+ *
+ *   return children;
+ * }
+ * ```
+ */
+export declare function isValidToken(token: string, options?: JwtValidationOptions): boolean;
+/**
+ * Get time until token expires in seconds.
+ * Returns 0 if token is already expired or invalid.
+ *
+ * @param token - The JWT token string
+ * @returns Seconds until expiration, or 0 if expired/invalid
+ *
+ * @example
+ * ```tsx
+ * const secondsLeft = getTokenTimeLeft(token);
+ *
+ * if (secondsLeft < 300) {
+ *   // Less than 5 minutes left, refresh proactively
+ *   refreshToken();
+ * }
+ * ```
+ */
+export declare function getTokenTimeLeft(token: string): number;
+/**
+ * Get expiration date from token.
+ *
+ * @param token - The JWT token string
+ * @returns Date object for expiration, or null if no exp claim or invalid token
+ *
+ * @example
+ * ```tsx
+ * const expiresAt = getTokenExpirationDate(token);
+ * if (expiresAt) {
+ *   console.log('Token expires:', expiresAt.toLocaleString());
+ * }
+ * ```
+ */
+export declare function getTokenExpirationDate(token: string): Date | null;
+/**
+ * Safely get a claim from a token.
+ *
+ * @param token - The JWT token string
+ * @param claim - The claim name to extract
+ * @returns The claim value or undefined if not present/invalid
+ *
+ * @example
+ * ```tsx
+ * const userId = getTokenClaim(token, 'sub');
+ * const roles = getTokenClaim<string[]>(token, 'roles') ?? [];
+ * ```
+ */
+export declare function getTokenClaim<T>(token: string, claim: string): T | undefined;
+/**
+ * Get the subject (user identifier) from a token.
+ *
+ * @param token - The JWT token string
+ * @returns The subject claim or undefined
+ */
+export declare function getTokenSubject(token: string): string | undefined;
+/**
+ * Check if token has a specific role.
+ *
+ * @param token - The JWT token string
+ * @param role - The role to check for
+ * @param rolesKey - The key in the payload containing roles (default: 'roles')
+ * @returns true if the token contains the role
+ *
+ * @example
+ * ```tsx
+ * if (tokenHasRole(token, 'admin')) {
+ *   // Show admin features
+ * }
+ * ```
+ */
+export declare function tokenHasRole(token: string, role: string, rolesKey?: string): boolean;
+/**
+ * Check if token has a specific permission.
+ *
+ * @param token - The JWT token string
+ * @param permission - The permission to check for
+ * @param permissionsKey - The key in the payload containing permissions (default: 'permissions')
+ * @returns true if the token contains the permission
+ */
+export declare function tokenHasPermission(token: string, permission: string, permissionsKey?: string): boolean;
+//# sourceMappingURL=jwt.d.ts.map

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

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

package/dist/utils/object.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Object Utilities
+ *
+ * Type-safe object manipulation helpers.
+ *
+ * @module utils
+ */
+/**
+ * Check if an object has specific keys.
+ *
+ * Vacuously true when `keys` is empty, in line with `Array.every`
+ * — "every key in the empty set is present" matches the standard
+ * library and avoids surprising callers that pass a dynamically
+ * derived list of required keys.
+ *
+ * @template T - Object type
+ * @template K - Key type
+ * @param {T | null | undefined} obj - Object to check
+ * @param {K[]} keys - Keys to check for
+ * @returns {boolean} True if object has all specified keys
+ *
+ * @example
+ * ```ts
+ * const user = { name: 'John', email: 'john@example.com' };
+ * hasKeys(user, ['name', 'email']); // true
+ * hasKeys(user, ['name', 'age']);   // false
+ * hasKeys(null, ['name']);          // false
+ * hasKeys(user, []);                // true (vacuous)
+ * ```
+ */
+export declare function hasKeys<T extends object, K extends keyof T>(obj: T | null | undefined, keys: K[]): boolean;
+/**
+ * Omit specific keys from an object.
+ *
+ * @template T - Object type
+ * @template K - Keys to omit
+ * @param {T} obj - Source object
+ * @param {K[]} keys - Keys to omit
+ * @returns {Omit<T, K>} New object without specified keys
+ *
+ * @example
+ * ```ts
+ * const user = { name: 'John', email: 'john@example.com', password: '...' };
+ * omit(user, ['password']); // { name: 'John', email: 'john@example.com' }
+ * ```
+ */
+export declare function omit<T extends object, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>;
+/**
+ * Pick specific keys from an object.
+ *
+ * @template T - Object type
+ * @template K - Keys to pick
+ * @param {T} obj - Source object
+ * @param {K[]} keys - Keys to pick
+ * @returns {Pick<T, K>} New object with only specified keys
+ *
+ * @example
+ * ```ts
+ * const user = { name: 'John', email: 'john@example.com', password: '...' };
+ * pick(user, ['name', 'email']); // { name: 'John', email: 'john@example.com' }
+ * ```
+ */
+export declare function pick<T extends object, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>;
+/**
+ * Deep clone an object.
+ *
+ * @template T - Object type
+ * @param {T} obj - Object to clone
+ * @returns {T} Deep cloned object
+ *
+ * @example
+ * ```ts
+ * const original = { a: 1, b: { c: 2 } };
+ * const cloned = deepClone(original);
+ * cloned.b.c = 3; // original.b.c is still 2
+ * ```
+ */
+export declare function deepClone<T>(obj: T): T;
+/**
+ * Check if a value is empty (null, undefined, empty string, empty array, empty object).
+ *
+ * @param {unknown} value - Value to check
+ * @returns {boolean} True if empty
+ *
+ * @example
+ * ```ts
+ * isEmpty(null);      // true
+ * isEmpty('');        // true
+ * isEmpty([]);        // true
+ * isEmpty({});        // true
+ * isEmpty('hello');   // false
+ * isEmpty([1]);       // false
+ * ```
+ */
+export declare function isEmpty(value: unknown): boolean;
+//# sourceMappingURL=object.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"object.d.ts","sourceRoot":"","sources":["../../src/utils/object.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,OAAO,CAM1G;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAMvF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAQvF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAwBtC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAc/C"}

package/dist/utils/refs.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Ref Utilities
+ *
+ * Utilities for working with React refs.
+ *
+ * @module utils/refs
+ */
+import type { MutableRefObject, RefCallback, Ref } from 'react';
+/**
+ * Supported ref types for merging.
+ */
+export type MergeableRef<T> = Ref<T> | RefCallback<T> | MutableRefObject<T> | null | undefined;
+/**
+ * Merge multiple refs into a single callback ref.
+ * Useful when you need to pass a ref to a component that also needs
+ * to be used by a parent component or hook.
+ *
+ * @example
+ * ```tsx
+ * function Component({ ref, ...props }: ComponentProps) {
+ *   const localRef = useRef<HTMLDivElement>(null);
+ *   const mergedRef = mergeRefs(ref, localRef);
+ *   return <div ref={mergedRef} />;
+ * }
+ * ```
+ *
+ * @param refs - Array of refs to merge
+ * @returns A callback ref that updates all provided refs
+ */
+export declare function mergeRefs<T>(...refs: MergeableRef<T>[]): RefCallback<T>;
+/**
+ * Create a ref setter that can be used with useImperativeHandle.
+ * Useful for exposing a subset of methods from a ref.
+ *
+ * @example
+ * ```tsx
+ * function Component({ ref, ...props }: Props & { ref?: Ref<API> }) {
+ *   const inputRef = useRef<HTMLInputElement>(null);
+ *
+ *   useImperativeHandle(ref, () => ({
+ *     focus: () => inputRef.current?.focus(),
+ *     clear: () => { if (inputRef.current) inputRef.current.value = ''; },
+ *   }), []);
+ *
+ *   return <input ref={inputRef} />;
+ * }
+ * ```
+ *
+ * @param ref - The ref to set
+ * @param value - The value to set
+ */
+export declare function setRef<T>(ref: MergeableRef<T>, value: T | null): void;
+/**
+ * Check if a ref has a current value.
+ *
+ * @param ref - The ref to check
+ * @returns True if the ref has a current value
+ */
+export declare function hasRefValue<T>(ref: MergeableRef<T>): ref is MutableRefObject<NonNullable<T>>;
+//# sourceMappingURL=refs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"refs.d.ts","sourceRoot":"","sources":["../../src/utils/refs.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAEhE;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC;AAE/F;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,GAAG,WAAW,CAAC,CAAC,CAAC,CAUvE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,GAAG,IAAI,CAMrE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,GAAG,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,gBAAgB,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAE5F"}

package/dist/utils/rtl.d.ts

@@ -0,0 +1,75 @@
+/**
+ * RTL (Right-to-Left) Utilities
+ *
+ * Helpers for RTL layout support and CSS transformation control.
+ *
+ * @module utils
+ */
+/**
+ * Prevents automatic RTL (right-to-left) flipping of a CSS declaration.
+ *
+ * Many CSS-in-JS libraries and RTL plugins automatically flip directional
+ * CSS properties (like margin-left → margin-right) for RTL layouts.
+ * Use this function to prevent that behavior for specific declarations.
+ *
+ * Appends the `\/* @noflip *\/` comment which is recognized by:
+ * - stylis (used by Emotion/styled-components)
+ * - rtlcss
+ * - cssjanus
+ *
+ * @param cssValue - A CSS declaration string (e.g., "margin-left: 10px")
+ * @returns The same declaration with `\/* @noflip *\/` appended
+ *
+ * @example
+ * ```tsx
+ * import { noRtlFlip } from '@omnitron-dev/prism/utils';
+ *
+ * // In sx prop or styled components
+ * const styles = {
+ *   // This margin-left will stay as margin-left even in RTL
+ *   marginLeft: noRtlFlip('10px'),
+ *
+ *   // Or for full declarations
+ *   transform: noRtlFlip('translateX(100px)'),
+ * };
+ *
+ * // Common use case: icons that shouldn't flip
+ * <ChevronIcon sx={{ transform: noRtlFlip('rotate(0deg)') }} />
+ *
+ * // Progress indicators that fill from left regardless of RTL
+ * <ProgressBar sx={{ left: noRtlFlip('0'), right: 'auto' }} />
+ * ```
+ */
+export declare function noRtlFlip(cssValue: unknown): string;
+/**
+ * Check if the current document direction is RTL.
+ *
+ * @returns True if the document direction is RTL
+ *
+ * @example
+ * ```tsx
+ * const isRtl = isRtlDirection();
+ *
+ * // Conditional styling
+ * const style = {
+ *   marginLeft: isRtl ? '0' : '10px',
+ *   marginRight: isRtl ? '10px' : '0',
+ * };
+ * ```
+ */
+export declare function isRtlDirection(): boolean;
+/**
+ * Get the appropriate directional property name based on RTL state.
+ *
+ * @param property - Base property name (e.g., 'left', 'marginLeft')
+ * @param isRtl - Whether the layout is RTL
+ * @returns The appropriate property name
+ *
+ * @example
+ * ```tsx
+ * const prop = getDirectionalProperty('left', isRtl);
+ * // Returns 'right' if isRtl, 'left' otherwise
+ * ```
+ */
+export declare function getDirectionalProperty(property: 'left' | 'right' | 'marginLeft' | 'marginRight' | 'paddingLeft' | 'paddingRight', isRtl: boolean): string;
+//# sourceMappingURL=rtl.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rtl.d.ts","sourceRoot":"","sources":["../../src/utils/rtl.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAuBnD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAUxC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,GAAG,OAAO,GAAG,YAAY,GAAG,aAAa,GAAG,aAAa,GAAG,cAAc,EAC1F,KAAK,EAAE,OAAO,GACb,MAAM,CAWR"}

package/dist/utils/storage.d.ts

@@ -0,0 +1,190 @@
+/**
+ * LocalStorage Utilities
+ *
+ * SSR-safe localStorage utilities with JSON serialization support.
+ * Inspired by minimal-shared/utils/local-storage pattern.
+ *
+ * @module utils/storage
+ */
+export interface StorageOptions {
+    /** Storage to use (default: localStorage) */
+    storage?: Storage;
+    /** Serialize function (default: JSON.stringify) */
+    serialize?: (value: unknown) => string;
+    /** Deserialize function (default: JSON.parse) */
+    deserialize?: (value: string) => unknown;
+}
+/**
+ * Check if localStorage is available in the current environment.
+ * Handles SSR, private browsing, and quota exceeded scenarios.
+ *
+ * @example
+ * ```ts
+ * if (localStorageAvailable()) {
+ *   localStorage.setItem('key', 'value');
+ * }
+ * ```
+ */
+export declare function localStorageAvailable(): boolean;
+/**
+ * Check if sessionStorage is available in the current environment.
+ *
+ * @example
+ * ```ts
+ * if (sessionStorageAvailable()) {
+ *   sessionStorage.setItem('key', 'value');
+ * }
+ * ```
+ */
+export declare function sessionStorageAvailable(): boolean;
+/**
+ * Get a value from localStorage with automatic JSON parsing.
+ * Returns defaultValue if key doesn't exist, parsing fails, or storage is unavailable.
+ *
+ * @param key - Storage key
+ * @param defaultValue - Value to return if key doesn't exist or parsing fails
+ * @param options - Storage options
+ * @returns Parsed value or defaultValue
+ *
+ * @example
+ * ```ts
+ * // Simple value
+ * const count = getStorage('count', 0);
+ *
+ * // Object value
+ * const user = getStorage<User>('user', null);
+ *
+ * // With sessionStorage
+ * const session = getStorage('session', null, {
+ *   storage: sessionStorage,
+ * });
+ * ```
+ */
+export declare function getStorage<T>(key: string, defaultValue: T, options?: StorageOptions): T;
+/**
+ * Set a value in localStorage with automatic JSON serialization.
+ * Silently fails if storage is unavailable.
+ *
+ * @param key - Storage key
+ * @param value - Value to store (will be JSON serialized)
+ * @param options - Storage options
+ * @returns true if successful, false otherwise
+ *
+ * @example
+ * ```ts
+ * // Simple value
+ * setStorage('count', 42);
+ *
+ * // Object value
+ * setStorage('user', { id: 1, name: 'John' });
+ *
+ * // With sessionStorage
+ * setStorage('session', sessionData, {
+ *   storage: sessionStorage,
+ * });
+ * ```
+ */
+export declare function setStorage<T>(key: string, value: T, options?: StorageOptions): boolean;
+/**
+ * Remove a value from localStorage.
+ * Silently fails if storage is unavailable.
+ *
+ * @param key - Storage key to remove
+ * @param options - Storage options
+ * @returns true if successful, false otherwise
+ *
+ * @example
+ * ```ts
+ * removeStorage('user');
+ *
+ * // From sessionStorage
+ * removeStorage('session', { storage: sessionStorage });
+ * ```
+ */
+export declare function removeStorage(key: string, options?: Pick<StorageOptions, 'storage'>): boolean;
+/**
+ * Clear all items from localStorage.
+ * Silently fails if storage is unavailable.
+ *
+ * @param options - Storage options
+ * @returns true if successful, false otherwise
+ *
+ * @example
+ * ```ts
+ * clearStorage();
+ *
+ * // Clear sessionStorage
+ * clearStorage({ storage: sessionStorage });
+ * ```
+ */
+export declare function clearStorage(options?: Pick<StorageOptions, 'storage'>): boolean;
+/**
+ * Get all keys from localStorage.
+ *
+ * @param options - Storage options
+ * @returns Array of storage keys
+ *
+ * @example
+ * ```ts
+ * const keys = getStorageKeys();
+ * // => ['user', 'settings', 'cart']
+ * ```
+ */
+export declare function getStorageKeys(options?: Pick<StorageOptions, 'storage'>): string[];
+/**
+ * Get approximate size of localStorage in bytes.
+ *
+ * @param options - Storage options
+ * @returns Size in bytes
+ *
+ * @example
+ * ```ts
+ * const sizeBytes = getStorageSize();
+ * console.log(`Using ${sizeBytes} bytes of localStorage`);
+ * ```
+ */
+export declare function getStorageSize(options?: Pick<StorageOptions, 'storage'>): number;
+export interface StorageWithExpiryOptions extends StorageOptions {
+    /** Time to live in milliseconds */
+    ttl: number;
+}
+/**
+ * Set a value with expiration time.
+ *
+ * @param key - Storage key
+ * @param value - Value to store
+ * @param options - Options with TTL in milliseconds
+ *
+ * @example
+ * ```ts
+ * // Store for 1 hour
+ * setStorageWithExpiry('session', sessionData, {
+ *   ttl: 60 * 60 * 1000,
+ * });
+ *
+ * // Store for 24 hours
+ * setStorageWithExpiry('cache', cacheData, {
+ *   ttl: 24 * 60 * 60 * 1000,
+ * });
+ * ```
+ */
+export declare function setStorageWithExpiry<T>(key: string, value: T, options: StorageWithExpiryOptions): boolean;
+/**
+ * Get a value that was stored with expiration.
+ * Returns defaultValue if expired or not found.
+ *
+ * @param key - Storage key
+ * @param defaultValue - Value to return if expired or not found
+ * @param options - Storage options
+ *
+ * @example
+ * ```ts
+ * const session = getStorageWithExpiry<Session>('session', null);
+ * if (!session) {
+ *   // Session expired or doesn't exist
+ *   redirectToLogin();
+ * }
+ * ```
+ */
+export declare function getStorageWithExpiry<T>(key: string, defaultValue: T, options?: StorageOptions): T;
+//# sourceMappingURL=storage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/utils/storage.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,MAAM,WAAW,cAAc;IAC7B,6CAA6C;IAC7C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,mDAAmD;IACnD,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAC;IACvC,iDAAiD;IACjD,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;CAC1C;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,IAAI,OAAO,CAa/C;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,CAajD;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,EAAE,OAAO,GAAE,cAAmB,GAAG,CAAC,CAmB3F;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAe1F;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,IAAI,CAAC,cAAc,EAAE,SAAS,CAAM,GAAG,OAAO,CAajG;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,IAAI,CAAC,cAAc,EAAE,SAAS,CAAM,GAAG,OAAO,CAanF;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE,IAAI,CAAC,cAAc,EAAE,SAAS,CAAM,GAAG,MAAM,EAAE,CAmBtF;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE,IAAI,CAAC,cAAc,EAAE,SAAS,CAAM,GAAG,MAAM,CAqBpF;AAMD,MAAM,WAAW,wBAAyB,SAAQ,cAAc;IAC9D,mCAAmC;IACnC,GAAG,EAAE,MAAM,CAAC;CACb;AAOD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,wBAAwB,GAAG,OAAO,CASzG;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,EAAE,OAAO,GAAE,cAAmB,GAAG,CAAC,CAcrG"}