@omnitron-dev/prism 0.2.0 → 0.3.0

package/dist/utils/format-number.d.ts

@@ -0,0 +1,245 @@
+/**
+ * Number Formatting Utilities
+ *
+ * Locale-aware number formatting utilities.
+ *
+ * @module utils/format-number
+ */
+export interface FormatNumberOptions extends Intl.NumberFormatOptions {
+    /** Locale for formatting (default: 'en-US') */
+    locale?: string;
+}
+export interface FormatCurrencyOptions extends FormatNumberOptions {
+    /** Currency code (default: 'USD') */
+    currency?: string;
+}
+/**
+ * Format a number with locale-aware formatting.
+ *
+ * @example
+ * ```ts
+ * fNumber(1234567.89)
+ * // => "1,234,567.89"
+ *
+ * fNumber(1234567.89, { locale: 'de-DE' })
+ * // => "1.234.567,89"
+ *
+ * fNumber(0.1234, { style: 'percent' })
+ * // => "12%"
+ * ```
+ */
+export declare function fNumber(value: number | string | null | undefined, options?: FormatNumberOptions): string;
+/**
+ * Format a number as currency.
+ *
+ * @example
+ * ```ts
+ * fCurrency(1234.56)
+ * // => "$1,234.56"
+ *
+ * fCurrency(1234.56, { currency: 'EUR', locale: 'de-DE' })
+ * // => "1.234,56 €"
+ *
+ * fCurrency(1234.56, { currency: 'JPY' })
+ * // => "¥1,235" (JPY has no decimal places)
+ * ```
+ */
+export declare function fCurrency(value: number | string | null | undefined, options?: FormatCurrencyOptions): string;
+/**
+ * Format a number as a percentage.
+ *
+ * @example
+ * ```ts
+ * fPercent(0.1234)
+ * // => "12.34%"
+ *
+ * fPercent(0.1234, { maximumFractionDigits: 0 })
+ * // => "12%"
+ *
+ * fPercent(1.5)
+ * // => "150%"
+ * ```
+ */
+export declare function fPercent(value: number | string | null | undefined, options?: FormatNumberOptions): string;
+/**
+ * Shorten a large number with K, M, B suffixes.
+ *
+ * @example
+ * ```ts
+ * fShortenNumber(1234)
+ * // => "1.23K"
+ *
+ * fShortenNumber(1234567)
+ * // => "1.23M"
+ *
+ * fShortenNumber(1234567890)
+ * // => "1.23B"
+ *
+ * fShortenNumber(1234567890000)
+ * // => "1.23T"
+ * ```
+ */
+export declare function fShortenNumber(value: number | string | null | undefined, decimals?: number): string;
+/**
+ * Format bytes to human-readable size.
+ *
+ * @example
+ * ```ts
+ * fBytes(1024)
+ * // => "1 KB"
+ *
+ * fBytes(1048576)
+ * // => "1 MB"
+ *
+ * fBytes(1073741824)
+ * // => "1 GB"
+ * ```
+ */
+export declare function fBytes(bytes: number | string | null | undefined, decimals?: number): string;
+/**
+ * Format number with ordinal suffix (1st, 2nd, 3rd, etc.)
+ *
+ * @example
+ * ```ts
+ * fOrdinal(1)
+ * // => "1st"
+ *
+ * fOrdinal(22)
+ * // => "22nd"
+ *
+ * fOrdinal(33)
+ * // => "33rd"
+ *
+ * fOrdinal(44)
+ * // => "44th"
+ * ```
+ */
+export declare function fOrdinal(value: number | null | undefined): string;
+/**
+ * Format a number with decimal places.
+ *
+ * @example
+ * ```ts
+ * fDecimal(1234.5678)
+ * // => "1234.57"
+ *
+ * fDecimal(1234.5678, 4)
+ * // => "1234.5678"
+ *
+ * fDecimal(1234)
+ * // => "1234.00"
+ * ```
+ */
+export declare function fDecimal(value: number | string | null | undefined, decimals?: number): string;
+/**
+ * Calculate percentage of a value relative to a total.
+ *
+ * @param value - The part value
+ * @param total - The total value
+ * @param decimals - Decimal places (default: 0)
+ * @returns Percentage number (0-100)
+ *
+ * @example
+ * ```ts
+ * getPercentage(25, 100)
+ * // => 25
+ *
+ * getPercentage(1, 3)
+ * // => 33
+ *
+ * getPercentage(1, 3, 2)
+ * // => 33.33
+ *
+ * getPercentage(50, 200)
+ * // => 25
+ * ```
+ */
+export declare function getPercentage(value: number, total: number, decimals?: number): number;
+/**
+ * Calculate percentage change between two values.
+ *
+ * @param current - Current value
+ * @param previous - Previous value
+ * @param decimals - Decimal places (default: 0)
+ * @returns Percentage change (positive = increase, negative = decrease)
+ *
+ * @example
+ * ```ts
+ * calculatePercentageChange(150, 100)
+ * // => 50 (50% increase)
+ *
+ * calculatePercentageChange(50, 100)
+ * // => -50 (50% decrease)
+ *
+ * calculatePercentageChange(100, 100)
+ * // => 0 (no change)
+ *
+ * calculatePercentageChange(120, 100, 1)
+ * // => 20.0
+ * ```
+ */
+export declare function calculatePercentageChange(current: number, previous: number, decimals?: number): number;
+/**
+ * Get currency symbol for a currency code.
+ *
+ * @param currencyCode - ISO 4217 currency code (e.g., 'USD', 'EUR')
+ * @param locale - Locale for formatting (default: 'en-US')
+ * @returns Currency symbol (e.g., '$', '€', '¥')
+ *
+ * @example
+ * ```ts
+ * getCurrencySymbol('USD')
+ * // => "$"
+ *
+ * getCurrencySymbol('EUR')
+ * // => "€"
+ *
+ * getCurrencySymbol('JPY')
+ * // => "¥"
+ *
+ * getCurrencySymbol('GBP')
+ * // => "£"
+ * ```
+ */
+export declare function getCurrencySymbol(currencyCode: string, locale?: string): string;
+/**
+ * Format a number with +/- sign prefix.
+ *
+ * @param value - Number to format
+ * @param options - Formatting options
+ * @returns Formatted string with sign
+ *
+ * @example
+ * ```ts
+ * fNumberWithSign(25)
+ * // => "+25"
+ *
+ * fNumberWithSign(-25)
+ * // => "-25"
+ *
+ * fNumberWithSign(0)
+ * // => "0"
+ *
+ * fNumberWithSign(25.5, { maximumFractionDigits: 1 })
+ * // => "+25.5"
+ * ```
+ */
+export declare function fNumberWithSign(value: number | string | null | undefined, options?: FormatNumberOptions): string;
+/**
+ * Format a number as compact notation (1K, 1M, 1B).
+ * Uses Intl.NumberFormat with compact notation.
+ *
+ * @example
+ * ```ts
+ * fCompact(1234)
+ * // => "1.2K"
+ *
+ * fCompact(1234567)
+ * // => "1.2M"
+ *
+ * fCompact(1234567890)
+ * // => "1.2B"
+ * ```
+ */
+export declare function fCompact(value: number | string | null | undefined, options?: FormatNumberOptions): string;
+//# sourceMappingURL=format-number.d.ts.map

package/dist/utils/format-number.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-number.d.ts","sourceRoot":"","sources":["../../src/utils/format-number.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,MAAM,WAAW,mBAAoB,SAAQ,IAAI,CAAC,mBAAmB;IACnE,+CAA+C;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,qBAAsB,SAAQ,mBAAmB;IAChE,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,OAAO,GAAE,mBAAwB,GAAG,MAAM,CAc5G;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,OAAO,GAAE,qBAA0B,GAAG,MAAM,CAkBhH;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,OAAO,GAAE,mBAAwB,GAAG,MAAM,CAmB7G;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,QAAQ,GAAE,MAAU,GAAG,MAAM,CA2BtG;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,QAAQ,GAAE,MAAU,GAAG,MAAM,CAgB9F;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAYjE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,QAAQ,GAAE,MAAU,GAAG,MAAM,CAYhG;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAU,GAAG,MAAM,CAIxF;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAU,GAAG,MAAM,CAIzG;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,GAAE,MAAgB,GAAG,MAAM,CASxF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,OAAO,GAAE,mBAAwB,GAAG,MAAM,CAepH;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,OAAO,GAAE,mBAAwB,GAAG,MAAM,CAmB7G"}

package/dist/utils/i18n-text.d.ts

@@ -0,0 +1,68 @@
+/**
+ * i18n-text — generic locale resolution for bilingual / multilingual
+ * JSONB payloads stored on backend DTOs.
+ *
+ * Design goals:
+ *
+ *  - Zero hard-coded locale strings. Caller passes the viewer locale
+ *    and (optionally) a fallback order; the helper does the rest.
+ *    Adding a new locale to the platform is just config, not a code
+ *    edit in every consumer.
+ *  - Locale-agnostic API so it can serve marketplace categories,
+ *    achievement titles, payments coin names, future post translations
+ *    — anywhere a `{ [lang]: string }` bag is stored.
+ *  - O(1) in the happy path (direct map access) with a deterministic
+ *    fallback walk.
+ *
+ * @module utils/i18n-text
+ */
+/** A bag of language-keyed strings. Keys are RFC 5646 language codes
+ * (or just `'en'`, `'ru'` for simple two-locale platforms). */
+export type I18nText = Record<string, string | undefined>;
+/** Object shape that carries both a localised bag and a legacy
+ * scalar field as final fallback — the canonical wire format for
+ * categories, achievements etc. */
+export interface I18nResolvable {
+    /** Bilingual / multilingual bag. */
+    nameI18n?: I18nText | null;
+    /** Last-resort legacy fallback. The backend keeps this populated
+     * even after migrating to JSONB so single-locale consumers keep
+     * working without an immediate refactor. */
+    name?: string | null;
+}
+/**
+ * Resolve a `{ nameI18n, name }` object to the viewer-preferred
+ * locale, walking through optional fallbacks before bottoming out
+ * on the legacy scalar.
+ *
+ * @example
+ * ```ts
+ * const label = resolveI18n(category, 'ru', ['en']);
+ * // → category.nameI18n.ru
+ * //   ?? category.nameI18n.en
+ * //   ?? category.name
+ * //   ?? ''
+ * ```
+ *
+ * @param obj      The resolvable record (e.g. a category DTO).
+ * @param lang     Viewer's preferred language code.
+ * @param fallback Ordered list of secondary languages to try before
+ *                 the legacy scalar. Defaults to `['en']`.
+ * @param field    Override the I18nText key (defaults to `nameI18n`)
+ *                 + the legacy scalar key (defaults to `name`).
+ *                 Useful for `descriptionI18n` / `description`.
+ */
+export declare function resolveI18n(obj: object | null | undefined, lang: string, fallback?: readonly string[], field?: {
+    bag?: string;
+    scalar?: string;
+}): string;
+/**
+ * Build a stable searchable haystack from an i18n object — all
+ * known translations concatenated lower-case so a single `.includes`
+ * check matches against any locale.
+ *
+ * Useful inside `Autocomplete.filterOptions` to make EN-only users
+ * find RU-only entries.
+ */
+export declare function i18nHaystack(bag: object | null | undefined, extra?: readonly string[]): string;
+//# sourceMappingURL=i18n-text.d.ts.map

package/dist/utils/i18n-text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i18n-text.d.ts","sourceRoot":"","sources":["../../src/utils/i18n-text.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;+DAC+D;AAC/D,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAE1D;;mCAEmC;AACnC,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,QAAQ,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC3B;;gDAE4C;IAC5C,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC9B,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,SAAS,MAAM,EAAW,EACpC,KAAK,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAC5C,MAAM,CAoBR;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC9B,KAAK,GAAE,SAAS,MAAM,EAAO,GAC5B,MAAM,CAKR"}

package/dist/utils/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Prism Utilities
+ *
+ * Common utility functions for formatting, string manipulation,
+ * class name handling, refs, URLs, and number input handling.
+ *
+ * @module utils
+ */
+export { cn, mergeClasses, type ClassValue, type StateProps } from './cn.js';
+export { createClasses, createClassesObject, createComponentClasses, setClassPrefix, getClassPrefix, DEFAULT_CLASS_PREFIX, } from './create-classes.js';
+export { mergeRefs, setRef, hasRefValue, type MergeableRef } from './refs.js';
+export { fNumber, fCurrency, fPercent, fShortenNumber, fBytes, fOrdinal, fDecimal, fNumberWithSign, fCompact, getPercentage, calculatePercentageChange, getCurrencySymbol, type FormatNumberOptions, type FormatCurrencyOptions, } from './format-number.js';
+export { parseNumber, clampNumber, roundToDecimals, transformOnChange, transformOnBlur, transformForDisplay, createNumberInputHandlers, type TransformNumberOptions, } from './transform-number.js';
+export { fDate, fDateTime, fTime, fDateISO, fRelativeTime, fDuration, isToday, isYesterday, isThisWeek, isPast, isFuture, diffInDays, getDates, getPastDates, getFutureDates, startOfDay, endOfDay, addDays, addMonths, type DateInput, type FormatDateOptions, type DateDurationPreset, } from './format-date.js';
+export { truncate, getInitials, capitalize, titleCase, kebabCase, camelCase, snakeCase, highlightText, escapeRegExp, containsIgnoreCase, isBlank, isEmail, isUrl, randomString, uuid, slugify, } from './string.js';
+export { safeReturnUrl, isActiveLink, isExternalUrl, isExternalLink, isEqualPath, buildUrl, parseQueryParams, getQueryParam, hasParams, removeParams, removeLastSlash, type SafeReturnUrlOptions, } from './url.js';
+export { getCookie, setCookie, removeCookie, cookiesAvailable, type CookieOptions } from './cookies.js';
+export { localStorageAvailable, sessionStorageAvailable, getStorage, setStorage, removeStorage, clearStorage, getStorageKeys, getStorageSize, setStorageWithExpiry, getStorageWithExpiry, type StorageOptions, type StorageWithExpiryOptions, } from './storage.js';
+export { setFont, remToPx, pxToRem, responsiveFontSize } from './font.js';
+export { hasKeys, omit, pick, deepClone, isEmpty } from './object.js';
+export { noRtlFlip, isRtlDirection, getDirectionalProperty } from './rtl.js';
+export { AsyncLock, AsyncLockTimeoutError, createAsyncLock, createTokenRefreshLock, withLock, locked, type AsyncLockOptions, type AsyncLockResult, type AsyncLockState, } from './async-lock.js';
+export { classifyHttpError, isNetworkError, isRetryableError, getErrorSeverity, createErrorTranslator, DEFAULT_ERROR_MESSAGES, extractErrorContext, withRetry, isChunkLoadError, isSessionExpiredError, createErrorRecoveryHandler, type ErrorCode, type ErrorSeverity, type ErrorContext, type TranslatedError, type TranslateFn, type ErrorMessages, type RetryConfig, } from './errors.js';
+export { createFetchClient, createTokenRefreshInterceptor, createJsonApiClient, type FetchRequestInit, type RequestContext, type ResponseContext, type ErrorContext as FetchErrorContext, type RequestInterceptor, type ResponseInterceptor, type ErrorInterceptor, type FetchInterceptorConfig, type TokenRefreshConfig, type FetchClient, } from './fetch-interceptor.js';
+export { jwtDecode, jwtDecodePayload, isTokenExpired, isValidToken, getTokenTimeLeft, getTokenExpirationDate, getTokenClaim, getTokenSubject, tokenHasRole, tokenHasPermission, type JwtStandardClaims, type JwtPayload, type JwtValidationOptions, type JwtDecodeResult, } from './jwt.js';
+export { resolveTemplateVariables } from './template-resolver.js';
+export { resolveI18n, i18nHaystack, type I18nText, type I18nResolvable, } from './i18n-text.js';
+export { toast } from './toast.js';
+export { formatCoinAmount, formatCoinAmountList, getCoinDecimals, getCoinWireDecimals, COIN_DISPLAY_DECIMALS, COIN_WIRE_DECIMALS, type FormatCoinAmountOptions, type DecimalRounding, formatDecimalString, sumDecimalStrings, subtractDecimalStrings, toScaledInteger, fromScaledInteger, } from './format-crypto.js';
+//# sourceMappingURL=index.d.ts.map

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

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

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