@plyaz/types 1.19.4 → 1.20.0

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

@@ -0,0 +1,166 @@
+/**
+ * Feature Flag Store Types
+ *
+ * Type definitions for the feature flag store slice.
+ * Used by @plyaz/store for state management.
+ *
+ * @fileoverview Feature flag store type definitions
+ * @version 1.0.0
+ */
+import type { FeatureFlagValue, FeatureFlagRule } from './types';
+import type { PackageErrorLike } from '../../errors';
+/**
+ * Metadata associated with a feature flag in the store
+ */
+export interface FeatureFlagStoreMetadata {
+    /** Associated rules for the flag */
+    rules?: FeatureFlagRule<string>[];
+    /** Last time this flag was updated */
+    updatedAt?: Date;
+    /** Source of the flag value */
+    source?: 'api' | 'database' | 'redis' | 'memory' | 'file' | 'default';
+}
+/**
+ * Polling configuration for feature flags
+ */
+export interface FeatureFlagPollingConfig {
+    /** Whether polling is enabled */
+    enabled: boolean;
+    /** Polling interval in milliseconds */
+    interval: number;
+}
+/**
+ * Feature flag store state
+ */
+export interface FeatureFlagStoreState {
+    /** Map of flag keys to their values */
+    flags: Record<string, FeatureFlagValue>;
+    /** Default values to use when flag is not found */
+    defaults: Record<string, FeatureFlagValue>;
+    /** Metadata for each flag */
+    metadata: Record<string, FeatureFlagStoreMetadata>;
+    /** Timestamp of last fetch */
+    lastFetched: number | null;
+    /** Whether flags are currently being loaded */
+    isLoading: boolean;
+    /** Whether the store has been initialized */
+    isInitialized: boolean;
+    /** Current error state */
+    error: PackageErrorLike | null;
+    /** Polling configuration */
+    pollingConfig: FeatureFlagPollingConfig | null;
+    /** Active polling interval ID (for cleanup) */
+    pollingIntervalId: ReturnType<typeof globalThis.setInterval> | null;
+}
+/**
+ * Feature flag store actions
+ */
+export interface FeatureFlagStoreActions {
+    /**
+     * Initialize the store with optional configuration
+     */
+    initialize(config?: FeatureFlagStoreInitConfig): Promise<void>;
+    /**
+     * Fetch all flags from the configured source
+     */
+    fetchAll(): Promise<void>;
+    /**
+     * Refresh flags (re-fetch from source)
+     */
+    refresh(): Promise<void>;
+    /**
+     * Set flags in the store
+     */
+    setFlags(flags: Record<string, FeatureFlagValue>): void;
+    /**
+     * Update flags (merge with existing)
+     */
+    updateFlags(flags: Record<string, FeatureFlagValue>): void;
+    /**
+     * Check if a flag is enabled
+     * Returns synchronously from store (with warning if flag not found)
+     */
+    isEnabled(key: string): boolean;
+    /**
+     * Get the value of a flag
+     */
+    getValue<T = FeatureFlagValue>(key: string): T | undefined;
+    /**
+     * Get value with a default fallback
+     */
+    getValueOrDefault<T = FeatureFlagValue>(key: string, fallback: T): T;
+    /**
+     * Set a single default value
+     */
+    setDefault(key: string, value: FeatureFlagValue): void;
+    /**
+     * Set multiple default values
+     */
+    setDefaults(defaults: Record<string, FeatureFlagValue>): void;
+    /**
+     * Configure polling
+     */
+    setPollingConfig(config: FeatureFlagPollingConfig | null): void;
+    /**
+     * Start polling for flag updates
+     */
+    startPolling(): void;
+    /**
+     * Stop polling
+     */
+    stopPolling(): void;
+    /**
+     * Set loading state
+     */
+    setLoading(isLoading: boolean): void;
+    /**
+     * Set error state
+     */
+    setError(error: PackageErrorLike | null): void;
+    /**
+     * Clear all flags and reset store
+     */
+    reset(): void;
+    /**
+     * Dispose of the store (cleanup)
+     */
+    dispose(): void;
+}
+/**
+ * Combined store slice type
+ */
+export type FeatureFlagStoreSlice = FeatureFlagStoreState & FeatureFlagStoreActions;
+/**
+ * Configuration for store initialization
+ */
+export interface FeatureFlagStoreInitConfig {
+    /** Default flag values */
+    defaults?: Record<string, FeatureFlagValue>;
+    /** Polling configuration */
+    polling?: FeatureFlagPollingConfig;
+    /** Fetch function to get flags from source */
+    fetchFn?: () => Promise<Record<string, FeatureFlagValue>>;
+    /** Callback when flags change */
+    onFlagChange?: (key: string, prevValue: FeatureFlagValue | undefined, newValue: FeatureFlagValue) => void;
+    /** Callback when an error occurs */
+    onError?: (error: PackageErrorLike) => void;
+}
+/**
+ * Selector functions for the feature flag store
+ */
+export interface FeatureFlagStoreSelectors {
+    /** Select all flags */
+    selectFlags: (state: FeatureFlagStoreState) => Record<string, FeatureFlagValue>;
+    /** Select a specific flag value */
+    selectFlag: (state: FeatureFlagStoreState, key: string) => FeatureFlagValue | undefined;
+    /** Select whether a flag is enabled */
+    selectIsEnabled: (state: FeatureFlagStoreState, key: string) => boolean;
+    /** Select loading state */
+    selectIsLoading: (state: FeatureFlagStoreState) => boolean;
+    /** Select initialization state */
+    selectIsInitialized: (state: FeatureFlagStoreState) => boolean;
+    /** Select error state */
+    selectError: (state: FeatureFlagStoreState) => PackageErrorLike | null;
+    /** Select last fetched timestamp */
+    selectLastFetched: (state: FeatureFlagStoreState) => number | null;
+}

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

@@ -9,6 +9,7 @@
 import type { UnknownArray, Arrayable, SetOptional } from 'type-fest';
 import type * as React from 'react';
 import type { Describable, Timestamped, WithMetadata, Loadable, Authored, WithTags, WithEnvironment, Identifiable, Named, WithLogging, WithApiKey, Initializable, Refreshable, WithOperation, Enabled, WithError, KeyValuePair, WithUserId, WithCountry, Versioned, WithPlatform, WithPriority, ValidationResult } from '../../common/types';
+import type { PackageErrorLike } from '../../errors';
 /**
  * Possible values that a feature flag can hold.
  * Supports primitive types and JSON objects for complex configurations.
@@ -76,12 +77,23 @@ export interface FeatureFlagEvaluation<FeatureFlagKey extends string> extends En
     /** Timestamp when this evaluation occurred */
     evaluatedAt: Date;
 }
+/**
+ * Available feature flag provider types.
+ * This is the single source of truth for provider types across all packages.
+ *
+ * - `memory`: In-memory provider using FEATURES constant (ephemeral)
+ * - `file`: File-based provider supporting JSON and YAML formats
+ * - `redis`: Redis-based provider for distributed caching
+ * - `api`: Remote API provider for centralized flag management
+ * - `database`: Database provider for persistent flag storage
+ */
+export type FeatureFlagProviderType = 'database' | 'redis' | 'memory' | 'api' | 'file';
 /**
  * Configuration options for the feature flag system.
  */
 export interface FeatureFlagConfig<FeatureFlagKey extends string> extends SetOptional<WithLogging, 'isLoggingEnabled'>, SetOptional<WithApiKey, 'apiKey'> {
     /** The storage provider to use for flag data */
-    provider: 'database' | 'redis' | 'memory' | 'api' | 'file';
+    provider: FeatureFlagProviderType;
     /** Whether to enable caching of flag evaluations */
     isCacheEnabled: boolean;
     /** Cache time-to-live in seconds */
@@ -167,14 +179,14 @@ export interface FeatureFlagProviderProps<FeatureFlagKey extends string, Feature
     /** Callback when provider is ready */
     onReady?: (provider: FeatureFlagProvider<FeatureFlagKey>) => void;
     /** Callback when an error occurs */
-    onError?: (error: Error) => void;
+    onError?: (error: PackageErrorLike) => void;
     /** Whether to show loading state while initializing */
     isShowLoading?: boolean;
     /** Custom loading component */
     loadingComponent?: React.ComponentType;
     /** Custom error component */
     errorComponent?: React.ComponentType<{
-        error: Error;
+        error: PackageErrorLike;
         retry: () => void;
     }>;
 }
@@ -386,7 +398,7 @@ export interface FlagOperationErrorTestInput<FeatureFlagKey extends string> {
     /** Flag key involved in the operation */
     flagKey: FeatureFlagKey;
     /** Error that occurred */
-    error: Error;
+    error: PackageErrorLike;
     /** Expected log message */
     expectedLogMessage: string;
 }

package/dist/globals.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Global Type Declarations
+ *
+ * Extends globalThis with runtime-specific globals for cross-runtime compatibility.
+ * These declarations allow TypeScript to recognize runtime-specific globals
+ * without errors when checking for their existence.
+ */
+
+declare global {
+  // Runtime-specific globals
+  // eslint-disable-next-line no-unused-vars
+  var Deno: unknown;
+  // eslint-disable-next-line no-unused-vars
+  var Bun: unknown;
+  // eslint-disable-next-line no-unused-vars
+  var EdgeRuntime: unknown;
+
+  // Node.js require with resolve
+  // eslint-disable-next-line no-unused-vars
+  var require: (((id: string) => unknown) & { resolve?: (id: string) => string }) | undefined;
+}
+
+export {};

package/dist/index.cjs

@@ -190,6 +190,7 @@ var CoreEventScope = {
   API: "api",
   CACHE: "cache",
   AUTH: "auth",
+  DATABASE: "database",
   FEATURE_FLAG: "featureFlag",
   STORE: "store"
 };
@@ -250,6 +251,15 @@ var AuthEventAction = {
   SESSION_EXPIRED: "sessionExpired",
   UNAUTHORIZED: "unauthorized"
 };
+var DatabaseEventAction = {
+  CONNECTED: "connected",
+  DISCONNECTED: "disconnected",
+  QUERY: "query",
+  ERROR: "error",
+  TRANSACTION_START: "transactionStart",
+  TRANSACTION_COMMIT: "transactionCommit",
+  TRANSACTION_ROLLBACK: "transactionRollback"
+};
 var FeatureFlagEventAction = {
   CHANGED: "changed",
   EVALUATED: "evaluated",
@@ -314,6 +324,15 @@ var CORE_EVENTS = {
     SESSION_EXPIRED: `${CoreEventScope.AUTH}:${AuthEventAction.SESSION_EXPIRED}`,
     UNAUTHORIZED: `${CoreEventScope.AUTH}:${AuthEventAction.UNAUTHORIZED}`
   },
+  DATABASE: {
+    CONNECTED: `${CoreEventScope.DATABASE}:${DatabaseEventAction.CONNECTED}`,
+    DISCONNECTED: `${CoreEventScope.DATABASE}:${DatabaseEventAction.DISCONNECTED}`,
+    QUERY: `${CoreEventScope.DATABASE}:${DatabaseEventAction.QUERY}`,
+    ERROR: `${CoreEventScope.DATABASE}:${DatabaseEventAction.ERROR}`,
+    TRANSACTION_START: `${CoreEventScope.DATABASE}:${DatabaseEventAction.TRANSACTION_START}`,
+    TRANSACTION_COMMIT: `${CoreEventScope.DATABASE}:${DatabaseEventAction.TRANSACTION_COMMIT}`,
+    TRANSACTION_ROLLBACK: `${CoreEventScope.DATABASE}:${DatabaseEventAction.TRANSACTION_ROLLBACK}`
+  },
   FEATURE_FLAG: {
     CHANGED: `${CoreEventScope.FEATURE_FLAG}:${FeatureFlagEventAction.CHANGED}`,
     EVALUATED: `${CoreEventScope.FEATURE_FLAG}:${FeatureFlagEventAction.EVALUATED}`,
@@ -1223,6 +1242,10 @@ var ERROR_CODES = {
   ERROR_SYSTEM_NOT_INITIALIZED: "error.system.not.initialized",
   EVENT_FACTORY_NOT_REGISTERED: "error.event.factory.not.registered",
   DATABASE_ERROR: "error.database",
+  // Global Error Handler
+  UNCAUGHT_EXCEPTION: "error.uncaught.exception",
+  UNHANDLED_REJECTION: "error.unhandled.rejection",
+  RUNTIME_ERROR: "error.runtime",
   // ===== Database Errors =====
   // Connection & Configuration
   DB_ACCESS_DENIED: "db.access_denied",
@@ -4363,6 +4386,31 @@ var ERROR_DEFINITIONS = {
     retryable: false,
     userMessage: "errors.database"
   },
+  // Global Error Handler
+  [ERROR_CODES.UNCAUGHT_EXCEPTION]: {
+    code: ERROR_CODES.UNCAUGHT_EXCEPTION,
+    status: HTTP_STATUS.INTERNAL_SERVER_ERROR,
+    category: ERROR_CATEGORY.System,
+    severity: ERROR_SEVERITY.Critical,
+    retryable: false,
+    userMessage: "errors.uncaught.exception"
+  },
+  [ERROR_CODES.UNHANDLED_REJECTION]: {
+    code: ERROR_CODES.UNHANDLED_REJECTION,
+    status: HTTP_STATUS.INTERNAL_SERVER_ERROR,
+    category: ERROR_CATEGORY.System,
+    severity: ERROR_SEVERITY.Critical,
+    retryable: false,
+    userMessage: "errors.unhandled.rejection"
+  },
+  [ERROR_CODES.RUNTIME_ERROR]: {
+    code: ERROR_CODES.RUNTIME_ERROR,
+    status: HTTP_STATUS.INTERNAL_SERVER_ERROR,
+    category: ERROR_CATEGORY.System,
+    severity: ERROR_SEVERITY.High,
+    retryable: false,
+    userMessage: "errors.runtime"
+  },
   // ===== Database Error Definitions =====
   // Connection & Configuration
   [ERROR_CODES.DB_ACCESS_DENIED]: {
@@ -8501,6 +8549,7 @@ exports.DEBUGGER_CONFIG_SOURCES = DEBUGGER_CONFIG_SOURCES;
 exports.DEBUG_EVENTS = DEBUG_EVENTS;
 exports.DEFAULT_THRESHOLDS = DEFAULT_THRESHOLDS;
 exports.DOCUMENT_TYPE = DOCUMENT_TYPE;
+exports.DatabaseEventAction = DatabaseEventAction;
 exports.DeviceTokenSchema = DeviceTokenSchema;
 exports.ENCRYPTION_DEFAULTS = ENCRYPTION_DEFAULTS;
 exports.ENTITY_TYPE = ENTITY_TYPE;