@plyaz/types 1.1.2 → 1.1.4

package/dist/auth/schemas.d.ts

@@ -6,7 +6,7 @@ import { z } from 'zod';
  * ```ts
  * LoginCredentialsSchema.parse({
  *   email: "user@example.com",
- *   password: "securePassword123"
+ *   password: ""
  * });
  * ```
  */

package/dist/features/cache/index.d.ts

@@ -0,0 +1 @@
+export type * from './types';

package/dist/features/cache/types.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Cache Types and Interfaces
+ *
+ * Type definitions for the caching layer.
+ * This will be moved to @plyaz/core when the package structure is finalized.
+ *
+ * @fileoverview Cache type definitions
+ * @version 1.0.0
+ */
+/**
+ * Cache entry structure that wraps cached data with metadata.
+ */
+export interface CacheEntry<T = unknown> {
+    /** The cached data */
+    data: T;
+    /** When the entry expires (timestamp in milliseconds) */
+    expiresAt: number;
+    /** When the entry was created (timestamp in milliseconds) */
+    createdAt: number;
+    /** Optional metadata for the cache entry */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Cache statistics for monitoring and debugging.
+ */
+export interface CacheStats {
+    /** Total number of cache hits */
+    hits: number;
+    /** Total number of cache misses */
+    misses: number;
+    /** Total number of set operations */
+    sets: number;
+    /** Total number of delete operations */
+    deletes: number;
+    /** Number of entries currently in cache */
+    size: number;
+    /** Cache hit ratio (hits / (hits + misses)) */
+    hitRatio?: number;
+}
+/**
+ * Configuration for cache strategies.
+ */
+export interface CacheConfig {
+    /** Whether caching is enabled */
+    isEnabled: boolean;
+    /** Default TTL in seconds */
+    ttl: number;
+    /** Cache strategy to use */
+    strategy: 'memory' | 'redis';
+    /** Redis-specific configuration */
+    redisConfig?: RedisCacheConfig;
+    /** Memory cache specific configuration */
+    memoryConfig?: {
+        /** Maximum number of entries to store */
+        maxSize?: number;
+        /** Maximum number of entries to store (alias for maxSize) */
+        maxEntries?: number;
+        /** Check for expired entries every N milliseconds */
+        cleanupInterval?: number;
+    };
+}
+/**
+ * Configuration for memory cache strategy.
+ */
+export interface MemoryCacheConfig {
+    /** Maximum number of entries to store (default: 1000) */
+    maxSize?: number;
+    /** Maximum number of entries to store (alias for maxSize) */
+    maxEntries?: number;
+    /** Check for expired entries every N milliseconds (default: 60000) */
+    cleanupInterval?: number;
+    /** Callback when entry is evicted */
+    onEvict?: (key: string, entry: CacheEntry) => void;
+}
+/**
+ * Configuration for Redis cache strategy.
+ */
+export interface RedisCacheConfig {
+    /** Redis connection URL */
+    url: string;
+    /** Redis password for authentication */
+    password?: string;
+    /** Redis database number */
+    db?: number;
+    /** Key prefix for Redis keys */
+    keyPrefix?: string;
+    /** Connection timeout in milliseconds */
+    connectTimeout?: number;
+    /** Command timeout in milliseconds */
+    commandTimeout?: number;
+}
+/**
+ * Cache manager statistics interface.
+ */
+export interface CacheManagerStats extends CacheStats {
+}
+/**
+ * Interface that all cache strategies must implement.
+ */
+export interface CacheStrategy {
+    /**
+     * Stores a cache entry.
+     *
+     * @param key - Cache key
+     * @param entry - Cache entry to store
+     * @returns Promise that resolves when entry is stored
+     */
+    set<T>(key: string, entry: CacheEntry<T>): Promise<void>;
+    /**
+     * Retrieves a cache entry.
+     *
+     * @param key - Cache key
+     * @returns Promise that resolves to cache entry or null if not found
+     */
+    get<T>(key: string): Promise<CacheEntry<T> | null>;
+    /**
+     * Removes a cache entry.
+     *
+     * @param key - Cache key to remove
+     * @returns Promise that resolves when entry is removed
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Clears all cache entries.
+     *
+     * @returns Promise that resolves when cache is cleared
+     */
+    clear(): Promise<void>;
+    /**
+     * Gets cache statistics.
+     *
+     * @returns Promise that resolves to cache statistics
+     */
+    getStats(): Promise<CacheStats>;
+    /**
+     * Disposes of the cache strategy and cleans up resources.
+     * Optional method for cleanup.
+     *
+     * @returns Promise that resolves when cleanup is complete
+     */
+    dispose?(): Promise<void>;
+}

package/dist/features/feature-flag/index.d.ts

@@ -0,0 +1 @@
+export type * from './types';

package/dist/features/feature-flag/types.d.ts

@@ -0,0 +1,302 @@
+/**
+ * Feature Flags Domain Types
+ *
+ * Core type definitions for the feature flags domain.
+ * These types will be moved to @plyaz/types when the package structure is finalized.
+ *
+ * @fileoverview Feature flags domain type definitions
+ * @version 1.0.0
+ */
+import type * as React from 'react';
+/**
+ * Possible values that a feature flag can hold.
+ * Supports primitive types and JSON objects for complex configurations.
+ */
+export type FeatureFlagValue = boolean | string | number | Record<string, unknown>;
+/**
+ * Core feature flag definition interface.
+ * Represents a complete feature flag with all its metadata and configuration.
+ */
+export interface FeatureFlag<FeatureFlagKey> {
+    /** The unique identifier for this flag */
+    key: FeatureFlagKey;
+    /** Human-readable name for the flag */
+    name: string;
+    /** Detailed description of what this flag controls */
+    description: string;
+    /** Whether this flag is currently active */
+    isEnabled: boolean;
+    /** The value returned when this flag is evaluated */
+    value: FeatureFlagValue;
+    /** The data type of the flag value */
+    type: 'boolean' | 'string' | 'number' | 'json';
+    /** Which environment(s) this flag applies to */
+    environment: 'development' | 'staging' | 'production' | 'all';
+    /** Percentage of users who should receive this flag (0-100) */
+    rolloutPercentage?: number;
+    /** Timestamp when this flag was created */
+    createdAt: Date;
+    /** Timestamp when this flag was last updated */
+    updatedAt: Date;
+    /** Email or ID of the user who created this flag */
+    createdBy: string;
+    /** Email or ID of the user who last updated this flag */
+    updatedBy: string;
+}
+/**
+ * Feature flag rule for advanced targeting and conditional logic.
+ */
+export interface FeatureFlagRule<FeatureFlagKey> {
+    /** Unique identifier for this rule */
+    id: string;
+    /** The feature flag this rule applies to */
+    flagKey: FeatureFlagKey;
+    /** Human-readable name for this rule */
+    name: string;
+    /** Array of conditions that must all be met for this rule to apply */
+    conditions: FeatureFlagCondition[];
+    /** The value to return if this rule matches */
+    value: FeatureFlagValue;
+    /** Percentage of matching users who should receive this value (0-100) */
+    rolloutPercentage?: number;
+    /** Priority for rule evaluation (higher numbers = higher priority) */
+    priority: number;
+    /** Whether this rule is currently active */
+    isEnabled: boolean;
+}
+/**
+ * Individual condition for feature flag rule evaluation.
+ */
+export interface FeatureFlagCondition {
+    /** The context field to evaluate */
+    field: 'userId' | 'userEmail' | 'userRole' | 'country' | 'platform' | 'version' | 'environment' | 'custom';
+    /** The comparison operator to use */
+    operator: 'equals' | 'not_equals' | 'contains' | 'not_contains' | 'in' | 'not_in' | 'greater_than' | 'less_than';
+    /** The value(s) to compare against */
+    value: string | number | string[] | number[];
+}
+/**
+ * Context information used for feature flag evaluation.
+ */
+export interface FeatureFlagContext {
+    /** Unique identifier for the user */
+    userId?: string;
+    /** User's email address */
+    userEmail?: string;
+    /** User's role or permission level */
+    userRole?: string;
+    /** User's country code (ISO 3166-1 alpha-2) */
+    country?: string;
+    /** Platform the user is accessing from */
+    platform?: 'web' | 'mobile' | 'desktop';
+    /** Application version */
+    version?: string;
+    /** Custom context data for advanced targeting */
+    custom?: Record<string, unknown>;
+    /** Current environment */
+    environment: 'development' | 'staging' | 'production';
+}
+/**
+ * Result of a feature flag evaluation.
+ */
+export interface FeatureFlagEvaluation<FeatureFlagKey> {
+    /** The feature flag key that was evaluated */
+    flagKey: FeatureFlagKey;
+    /** The resolved value for this flag */
+    value: FeatureFlagValue;
+    /** Whether the flag is considered enabled (truthy value) */
+    isEnabled: boolean;
+    /** Explanation of how this value was determined */
+    reason: 'default' | 'rule_match' | 'rollout' | 'override' | 'disabled';
+    /** Source of the evaluation result */
+    source?: 'default' | 'override' | 'rule' | 'rollout';
+    /** ID of the rule that matched (if reason is 'rule_match') */
+    ruleId?: string;
+    /** Timestamp when this evaluation occurred */
+    evaluatedAt: Date;
+}
+/**
+ * Configuration options for the feature flag system.
+ */
+export interface FeatureFlagConfig<FeatureFlagKey> {
+    /** The storage provider to use for flag data */
+    provider: 'database' | 'redis' | 'memory' | 'api' | 'file';
+    /** Whether to enable caching of flag evaluations */
+    isCacheEnabled: boolean;
+    /** Cache time-to-live in seconds */
+    cacheTtl: number;
+    /** How often to refresh flag data in seconds (0 = no auto-refresh) */
+    refreshInterval: number;
+    /** Whether to fall back to default values on errors */
+    shouldFallbackToDefaults: boolean;
+    /** Whether to enable debug logging */
+    isLoggingEnabled: boolean;
+    /** API endpoint URL (required if provider is 'api') */
+    apiEndpoint?: string;
+    /** API authentication key (required if provider is 'api') */
+    apiKey?: string;
+    /** Database configuration (required if provider is 'database') */
+    databaseConfig?: {
+        connectionString: string;
+        tableName: string;
+    };
+    /** Redis configuration (required if provider is 'redis') */
+    redisConfig?: {
+        url: string;
+        keyPrefix: string;
+    };
+    /** File configuration (required if provider is 'file') */
+    fileConfig?: {
+        filePath: string;
+        format: 'json' | 'yaml';
+        shouldWatchForChanges: boolean;
+    };
+    /** Memory provider rules (optional for memory provider) */
+    memoryRules?: FeatureFlagRule<FeatureFlagKey>[];
+}
+/**
+ * React Hook Options for Feature Flags
+ */
+export interface UseFeatureFlagOptions {
+    /** Evaluation context for targeting */
+    context?: FeatureFlagContext;
+    /** Whether to automatically refresh on provider updates */
+    isAutoRefresh?: boolean;
+    /** Default value to use while loading or on error */
+    defaultValue?: FeatureFlagValue;
+    /** Whether to suspend on initial load (for Suspense) */
+    isSuspense?: boolean;
+}
+/**
+ * Internal state for feature flag evaluation in React hooks.
+ */
+export interface FeatureFlagState<FeatureFlagKey, T extends FeatureFlagValue = FeatureFlagValue> {
+    value: T;
+    isLoading: boolean;
+    error: Error | null;
+    evaluation: FeatureFlagEvaluation<FeatureFlagKey> | null;
+}
+/**
+ * Context value interface for React feature flag provider.
+ */
+export interface FeatureFlagContextValue<FeatureFlagKey> {
+    /** The feature flag provider instance */
+    provider: FeatureFlagProvider<FeatureFlagKey>;
+    /** Whether the provider is initialized */
+    isInitialized: boolean;
+    /** Whether the provider is currently loading */
+    isLoading: boolean;
+    /** Any error that occurred during initialization */
+    error: Error | null;
+    /** When the provider was last updated */
+    lastUpdated: Date | null;
+    /** Manual refresh function */
+    refresh: () => Promise<void>;
+}
+/**
+ * Props for the React FeatureFlagProvider component.
+ */
+export interface FeatureFlagProviderProps<FeatureFlagKey> {
+    /** Provider configuration */
+    config: FeatureFlagConfig<FeatureFlagKey>;
+    /** Default context for flag evaluation */
+    defaultContext?: FeatureFlagContext;
+    /** Children components */
+    children: React.ReactNode;
+    /** Callback when provider is ready */
+    onReady?: (provider: FeatureFlagProvider<FeatureFlagKey>) => void;
+    /** Callback when an error occurs */
+    onError?: (error: Error) => void;
+    /** Whether to show loading state while initializing */
+    isShowLoading?: boolean;
+    /** Custom loading component */
+    loadingComponent?: React.ComponentType;
+    /** Custom error component */
+    errorComponent?: React.ComponentType<{
+        error: Error;
+        retry: () => void;
+    }>;
+}
+/**
+ * Backend Request DTO for flag creation.
+ */
+export interface CreateFlagRequest<FeatureFlagKey> {
+    key: FeatureFlagKey;
+    name: string;
+    description?: string;
+    value: FeatureFlagValue;
+    isEnabled?: boolean;
+    environment?: 'all' | 'development' | 'staging' | 'production';
+    rolloutPercentage?: number;
+}
+/**
+ * Backend Provider health status information.
+ */
+export interface ProviderHealthStatus {
+    isInitialized: boolean;
+    provider: string;
+    isCacheEnabled: boolean;
+}
+/**
+ * Main interface for feature flag providers.
+ */
+export interface FeatureFlagProvider<FeatureFlagKey> {
+    /** Initializes the provider by loading initial data */
+    initialize(): Promise<void>;
+    /** Evaluates a feature flag and returns full evaluation details */
+    getFlag(key: FeatureFlagKey, context?: FeatureFlagContext): Promise<FeatureFlagEvaluation<FeatureFlagKey>>;
+    /** Evaluates all feature flags for the given context */
+    getAllFlags(context?: FeatureFlagContext): Promise<Record<string, FeatureFlagEvaluation<FeatureFlagKey>>>;
+    /** Checks if a feature flag is enabled */
+    isEnabled(key: FeatureFlagKey, context?: FeatureFlagContext): Promise<boolean>;
+    /** Gets the value of a feature flag with optional type casting */
+    getValue<T = FeatureFlagValue>(key: FeatureFlagKey, context?: FeatureFlagContext): Promise<T>;
+    /** Refreshes the flag data from the underlying storage */
+    refresh(): Promise<void>;
+    /** Subscribes to flag changes and updates */
+    subscribe(callback: () => void): () => void;
+    /** Sets an override for a specific flag key */
+    setOverride(key: FeatureFlagKey, value: FeatureFlagValue): void;
+    /** Removes an override for a specific flag key */
+    removeOverride(key: FeatureFlagKey): void;
+    /** Clears all overrides */
+    clearOverrides(): void;
+    /** Disposes of the provider, cleaning up resources */
+    dispose(): void;
+}
+/**
+ * Partial mapping for flag overrides.
+ */
+export type FeatureFlagOverrides<FeatureFlagKey extends string = string> = Partial<{
+    [K in FeatureFlagKey]: FeatureFlagValue;
+}>;
+/**
+ * Hook-like interface for reactive feature flag usage.
+ */
+export type FeatureFlagHook<T = boolean> = {
+    /** The current value of the flag */
+    value: T;
+    /** Whether the flag is currently being loaded */
+    isLoading: boolean;
+    /** Any error that occurred during flag evaluation */
+    error: Error | null;
+    /** Function to manually refresh the flag value */
+    refresh: () => Promise<void>;
+};
+/**
+ * Helper functions for managing feature flags.
+ */
+export interface FeatureFlagHelpers<FeatureFlagKey extends string = string> {
+    setOverride: (key: FeatureFlagKey, value: FeatureFlagValue) => void;
+    removeOverride: (key: FeatureFlagKey) => void;
+    clearOverrides: () => void;
+    refresh: () => Promise<void>;
+    getMultipleFlags: (keys: FeatureFlagKey[], context?: FeatureFlagContext) => Promise<Record<FeatureFlagKey, FeatureFlagValue>>;
+    isAnyEnabled: (keys: FeatureFlagKey[], context?: FeatureFlagContext) => Promise<boolean>;
+    isAllEnabled: (keys: FeatureFlagKey[], context?: FeatureFlagContext) => Promise<boolean>;
+    whenEnabled: <T>(key: FeatureFlagKey, callback: () => T | Promise<T>, fallback?: () => T | Promise<T>, context?: FeatureFlagContext) => Promise<T | undefined>;
+}
+export interface FetchFeatureFlagDataResponse<FeatureFlagKey> {
+    flags: FeatureFlag<FeatureFlagKey>[];
+    rules: FeatureFlagRule<FeatureFlagKey>[];
+}

package/dist/features/index.d.ts

@@ -0,0 +1,2 @@
+export type * from './cache';
+export type * from './feature-flag';

package/dist/index.d.ts

@@ -8,3 +8,4 @@ export type * from './store';
 export type * from './ui';
 export * from './web3';
 export type * from './translations';
+export type * from './features';

package/dist/translations/types.d.ts

@@ -1,4 +1,3 @@
-import type { Paths, Get } from 'type-fest';
 /**
  * Translation leaf type.
  * @description This type represents the structure of a translation leaf.
@@ -37,12 +36,56 @@ TranslationResourcesNested>>;
  * @example 'common', 'errors', etc.
  */
 export type Namespace<Resources extends TranslationResources> = keyof Resources['en'];
+/**
+ * Helper type to remove the first element from a tuple type.
+ * Used internally by LeafPaths to track recursion depth.
+ */
+type PrevTuple<T extends readonly unknown[]> = T extends [unknown, ...infer R] ? R : [];
 /**
  * Recursively extracts all nested keys from an object, creating dot-notation paths.
+ * @description This utility type traverses nested objects and creates dot-separated key paths.
+ * It uses a depth counter to prevent infinite recursion (max 25 levels, which should be sufficient
+ * for most translation structures while avoiding TypeScript compiler limits).
+ * @example
+ * type Paths = LeafPaths<{ a: { b: string, c: { d: string } } }>;
+ * // Result: 'a.b' | 'a.c.d'
+ * @template T - The object type to extract paths from
+ * @template Prev - The accumulated path string (used internally)
+ * @template Depth - Tuple type used to track recursion depth and prevent infinite loops
  */
-export type LeafPaths<T> = Paths<T> extends infer P ? P extends string ? Get<T, P> extends object ? never : P : never : never;
+export type LeafPaths<T, Prev extends string = '', Depth extends readonly unknown[] = [
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1,
+    1
+]> = Depth['length'] extends 0 ? never : T extends string ? Prev : T extends object ? {
+    [K in keyof T]: LeafPaths<T[K], Prev extends '' ? Extract<K, string> : `${Prev}.${Extract<K, string>}`, PrevTuple<Depth>>;
+}[keyof T] : never;
 /**
  * Type-safe union of all translation keys in the form 'namespace.key' or 'namespace.nested.key'.
+ * @description This type generates a union of all possible translation keys by combining
+ * namespace names with their nested key paths. It ensures type safety when accessing translations.
  * @example 'common.hello', 'common.greeting', 'common.followers.zero', etc.
  * @example use: TranslationKeys<TranslationResources, 'en'>
  */
@@ -218,6 +261,11 @@ export interface Translator {
      */
     readonly addNamespace: (namespace: string, translations: Record<string, string>) => void;
 }
+/**
+ * Command-line interface options for extracting translation keys from source code.
+ * @description These types define the configuration options for the CLI tool that
+ * automatically extracts translation keys from source files and generates translation files.
+ */
 export interface ExtractOptions {
     /**
      * File pattern to search for translation keys
@@ -240,6 +288,16 @@ export interface ExtractOptions {
      */
     readonly shouldDryRun: boolean;
 }
+/**
+ * Pluralization test cases for validating translation pluralization rules.
+ * @description These types define the structure for testing pluralization functionality
+ * across different languages, ensuring correct plural forms are used based on numeric values.
+ */
+/**
+ * Represents a single test case for pluralization validation.
+ * @description Defines a numeric value and its expected translation string
+ * to test pluralization rules in different languages.
+ */
 export interface PluralizationValueCase {
     /**
      * The numeric value to test pluralization against
@@ -250,6 +308,11 @@ export interface PluralizationValueCase {
      */
     readonly expected: string;
 }
+/**
+ * Represents a complete set of pluralization test cases for a specific language.
+ * @description Groups multiple pluralization value cases together for a single language,
+ * allowing comprehensive testing of pluralization rules across different numeric values.
+ */
 export interface PluralizationCase {
     /**
      * The language code for this pluralization case
@@ -260,6 +323,16 @@ export interface PluralizationCase {
      */
     readonly values: readonly PluralizationValueCase[];
 }
+/**
+ * Date formatting test cases for validating locale-specific date formatting.
+ * @description These types define the structure for testing date formatting functionality
+ * across different languages and locales.
+ */
+/**
+ * Represents a test case for date formatting validation.
+ * @description Defines a language and its expected formatted date string
+ * to test date formatting rules in different locales.
+ */
 export interface DateCase {
     /**
      * The language code for this date formatting case
@@ -270,6 +343,16 @@ export interface DateCase {
      */
     readonly expected: string;
 }
+/**
+ * Number formatting test cases for validating locale-specific number formatting.
+ * @description These types define the structure for testing number formatting functionality
+ * across different languages and locales.
+ */
+/**
+ * Represents a test case for number formatting validation.
+ * @description Defines a language and its expected formatted number string
+ * to test number formatting rules in different locales.
+ */
 export interface NumberCase {
     /**
      * The language code for this number formatting case
@@ -280,6 +363,16 @@ export interface NumberCase {
      */
     readonly expected: string;
 }
+/**
+ * Currency formatting test cases for validating locale-specific currency formatting.
+ * @description These types define the structure for testing currency formatting functionality
+ * across different languages and locales, including currency symbols and formatting options.
+ */
+/**
+ * Represents a test case for currency formatting validation.
+ * @description Defines a language, expected formatted currency string, and formatting options
+ * to test currency formatting rules in different locales.
+ */
 export interface CurrencyCase {
     /**
      * The language code for this currency formatting case
@@ -294,3 +387,4 @@ export interface CurrencyCase {
      */
     readonly options: Intl.NumberFormatOptions;
 }
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plyaz/types",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "author": "Redeemer Pace",
   "license": "ISC",
   "description": "Provides shared TypeScript types and schema utilities for validation and parsing in the @playz ecosystem.",