@plyaz/types 1.19.4 → 1.19.5

package/dist/errors/middleware.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Middleware Types
+ *
+ * Type definitions for error middleware across frontend and backend.
+ * Used by @plyaz/errors middleware implementations.
+ */
+import type { Request, Response } from 'express';
+import type { SerializedError, ErrorStoreActions } from './store';
+import type { ErrorEventFactory, ErrorResponse } from './types';
+/**
+ * Configuration for HTTP error handler middleware.
+ * Used by Express and NestJS error handlers.
+ */
+export interface HttpErrorHandlerConfig {
+    /** Global error handler instance (optional - for tracking) */
+    errorHandler?: GlobalErrorHandler;
+    /** Include stack traces in response (default: false) */
+    includeStack?: boolean;
+    /** Custom error formatter */
+    formatError?: (error: SerializedError, req: Request) => ErrorResponse;
+    /** Callback when error is handled */
+    onError?: (error: SerializedError, req: Request, res: Response) => void;
+    /** Log errors to console (default: true) */
+    logErrors?: boolean;
+}
+/**
+ * Configuration for the global error handler.
+ * Used to initialize error capturing for uncaught errors and rejections.
+ */
+export interface GlobalErrorHandlerConfig {
+    /** Source identifier for errors (default: 'global') */
+    source?: string;
+    /** Maximum errors to keep (default: 100) */
+    maxErrors?: number;
+    /** Filter function - return false to ignore error */
+    filter?: (error: unknown) => boolean;
+    /** Custom serializer */
+    serialize?: (error: unknown, source?: string) => SerializedError;
+    /** Callback after error is added to store */
+    onError?: (error: SerializedError) => void;
+    /** Also log to console (default: true in dev) */
+    logToConsole?: boolean;
+}
+/**
+ * Global error handler instance interface.
+ * Provides methods to capture errors and manage the error store.
+ */
+export interface GlobalErrorHandler {
+    /** Manually capture an error */
+    captureError: (error: unknown, source?: string) => void;
+    /** Manually capture an exception (alias) */
+    captureException: (error: unknown, source?: string) => void;
+    /** Get the error store */
+    getStore: () => ErrorStoreActions;
+    /** Cleanup and remove listeners */
+    destroy: () => void;
+}
+/**
+ * Configuration for backend error store.
+ * Used to create in-memory error stores for server environments.
+ */
+export interface BackendErrorStoreConfig {
+    /** Maximum errors to keep in memory (default: 100) */
+    maxErrors?: number;
+    /** Callback when an error is added */
+    onErrorAdded?: (error: SerializedError) => void;
+    /** Callback when errors are cleared */
+    onErrorsCleared?: () => void;
+}
+/**
+ * Backend error store interface.
+ * Extends ErrorStoreActions with backend-specific getters.
+ */
+export interface BackendErrorStore extends ErrorStoreActions {
+    /** Get all errors (backend-specific method) */
+    getErrors(): SerializedError[];
+    /** Get last error (backend-specific method) */
+    getLastError(): SerializedError | null;
+    /** Get error count (backend-specific method) */
+    getErrorCount(): number;
+    /** Get active error count (backend-specific method) */
+    getActiveErrorCount(): number;
+    /** Check if connected (backend-specific method) */
+    getIsConnected(): boolean;
+}
+/**
+ * Keys for backend error store action methods.
+ */
+export type BackendErrorStoreActionKeys = 'addError' | 'removeError' | 'clearErrors' | 'clearErrorsByCategory' | 'clearErrorsBySource' | 'dismissError' | 'dismissAllErrors' | 'setConnected' | 'reset';
+/**
+ * Keys for backend error store getter methods.
+ */
+export type BackendErrorStoreGetterKeys = 'getErrors' | 'getLastError' | 'getErrorCount' | 'getActiveErrorCount' | 'getIsConnected';
+/**
+ * Event integration interface for error event emission.
+ * Allows errors to be listened to via scoped-error-events.
+ */
+export interface ErrorEventIntegration {
+    /** Emit an error event that can be listened to */
+    emitError(error: SerializedError): void;
+    /** Emit an error event with custom event name */
+    emitErrorEvent(eventName: string, error: SerializedError): void;
+    /** Get the event factory for custom integration */
+    getEventFactory(): ErrorEventFactory;
+}

package/dist/errors/store.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Error Store Types
+ *
+ * Type definitions for the unified error store slice.
+ * Used by @plyaz/store and error middleware.
+ */
+import type { ERROR_CATEGORY, ERROR_SEVERITY } from './enums';
+import type { ERROR_CODES } from './codes';
+/**
+ * Serialized error for store state.
+ * JSON-serializable version of PackageErrorLike.
+ */
+export interface SerializedError {
+    /** Unique ID for this error instance */
+    id: string;
+    /** Error code (from ERROR_CODES) */
+    code: (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+    /** Human-readable error message */
+    message: string;
+    /** HTTP status code */
+    status?: number;
+    /** Error category */
+    category: (typeof ERROR_CATEGORY)[keyof typeof ERROR_CATEGORY];
+    /** Error severity */
+    severity?: (typeof ERROR_SEVERITY)[keyof typeof ERROR_SEVERITY];
+    /** Correlation ID for tracing */
+    correlationId?: string;
+    /** ISO timestamp when error occurred */
+    timestamp: string;
+    /** Whether error is retryable */
+    isRetryable: boolean;
+    /** Additional context (JSON-serializable) */
+    context?: Record<string, unknown>;
+    /** User-friendly message */
+    userMessage?: string;
+    /** Source/namespace of the error */
+    source?: string;
+    /** Whether error has been dismissed by user */
+    dismissed?: boolean;
+}
+/**
+ * Error store state shape.
+ */
+export interface ErrorStoreState {
+    /** Array of all errors (newest first) */
+    errors: SerializedError[];
+    /** Most recent error */
+    lastError: SerializedError | null;
+    /** Total error count (including dismissed) */
+    errorCount: number;
+    /** Count of undismissed errors */
+    activeErrorCount: number;
+    /** Whether error middleware is connected */
+    isConnected: boolean;
+}
+/**
+ * Error store actions.
+ */
+export interface ErrorStoreActions {
+    /** Add an error to the store */
+    addError: (error: SerializedError) => void;
+    /** Remove an error by ID */
+    removeError: (id: string) => void;
+    /** Clear all errors */
+    clearErrors: () => void;
+    /** Clear errors by category */
+    clearErrorsByCategory: (category: string) => void;
+    /** Clear errors by source */
+    clearErrorsBySource: (source: string) => void;
+    /** Dismiss an error (mark as read) */
+    dismissError: (id: string) => void;
+    /** Dismiss all errors */
+    dismissAllErrors: () => void;
+    /** Set connection status */
+    setConnected: (connected: boolean) => void;
+    /** Reset store to initial state */
+    reset: () => void;
+}
+/**
+ * Complete error store slice (state + actions).
+ */
+export interface ErrorStoreSlice extends ErrorStoreState, ErrorStoreActions {
+}
+/**
+ * Error store selectors interface.
+ */
+export interface ErrorStoreSelectors {
+    /** Select all errors */
+    selectErrors: (state: ErrorStoreState) => SerializedError[];
+    /** Select active (undismissed) errors */
+    selectActiveErrors: (state: ErrorStoreState) => SerializedError[];
+    /** Select errors by category */
+    selectErrorsByCategory: (state: ErrorStoreState, category: string) => SerializedError[];
+    /** Select errors by source */
+    selectErrorsBySource: (state: ErrorStoreState, source: string) => SerializedError[];
+    /** Select errors by severity */
+    selectErrorsBySeverity: (state: ErrorStoreState, severity: string) => SerializedError[];
+    /** Select retryable errors */
+    selectRetryableErrors: (state: ErrorStoreState) => SerializedError[];
+    /** Select last error */
+    selectLastError: (state: ErrorStoreState) => SerializedError | null;
+    /** Select error count */
+    selectErrorCount: (state: ErrorStoreState) => number;
+    /** Select active error count */
+    selectActiveErrorCount: (state: ErrorStoreState) => number;
+    /** Check if has errors */
+    selectHasErrors: (state: ErrorStoreState) => boolean;
+    /** Check if has active errors */
+    selectHasActiveErrors: (state: ErrorStoreState) => boolean;
+}
+/**
+ * Error middleware configuration.
+ */
+export interface ErrorMiddlewareConfig {
+    /** Maximum errors to keep in store (default: 100) */
+    maxErrors?: number;
+    /** Error namespaces to subscribe to (default: ['global']) */
+    namespaces?: string[];
+    /** Error scopes to listen on (default: ['GLOBAL']) */
+    scopes?: ('GLOBAL' | 'CONFIG' | 'CLIENT' | 'REQUEST')[];
+    /** Filter function to decide which errors to store */
+    filter?: (error: unknown) => boolean;
+    /** Source identifier for errors from this middleware */
+    source?: string;
+    /** Auto-connect on creation (default: true) */
+    autoConnect?: boolean;
+}
+/**
+ * Error middleware instance interface.
+ */
+export interface ErrorMiddleware {
+    /** Connect and start listening to errors */
+    connect: () => void;
+    /** Disconnect and stop listening */
+    disconnect: () => void;
+    /** Whether middleware is connected */
+    readonly isConnected: boolean;
+    /** Get current configuration */
+    readonly config: ErrorMiddlewareConfig;
+}

package/dist/examples/index.d.ts

@@ -14,4 +14,4 @@
  * ```
  */
 export { CreateExampleSchema, UpdateExampleSchema, PatchExampleSchema, QueryExampleSchema, DeleteExampleSchema, ExampleResponseSchema, ExampleListResponseSchema, } from './schemas';
-export type { CreateExampleDTO, UpdateExampleDTO, PatchExampleDTO, QueryExampleDTO, DeleteExampleDTO, ExampleResponseDTO, ExampleListResponseDTO, ExampleEntity, ExampleStoreItem, ExampleStoreState, ExampleCreatedPayload, ExampleUpdatedPayload, ExampleDeletedPayload, ExampleValidationFailedPayload, } from './types';
+export type { CreateExampleDTO, UpdateExampleDTO, PatchExampleDTO, QueryExampleDTO, DeleteExampleDTO, ExampleResponseDTO, ExampleListResponseDTO, ExampleEntity, ExampleStoreItem, ExampleStoreState, ExampleCreatedPayload, ExampleUpdatedPayload, ExampleDeletedPayload, ExampleValidationFailedPayload, ExampleFrontendStoreData, ExampleFrontendStore, ExampleFrontendServiceConfig, ExampleFrontendEventType, ExampleUser, ExampleDomainServiceConfig, } from './types';

package/dist/examples/types.d.ts

@@ -7,6 +7,9 @@
 import type { z } from 'zod';
 import type { CreateExampleSchema, UpdateExampleSchema, PatchExampleSchema, QueryExampleSchema, DeleteExampleSchema, ExampleResponseSchema, ExampleListResponseSchema } from './schemas';
 import type { CoreEntityCreatedPayload, CoreEntityUpdatedPayload, CoreEntityDeletedPayload, CoreValidationFailedPayload } from '../core/events';
+import type { CoreBaseFrontendStore, CoreBaseFrontendServiceConfig } from '../core/frontend';
+import type { CoreServiceInitConfig } from '../core/init';
+import type { CoreBaseDomainServiceConfig } from '../core/domain';
 /**
  * Create request DTO (POST body)
  */
@@ -101,3 +104,64 @@ export type ExampleDeletedPayload = CoreEntityDeletedPayload;
  * Event payload for example:validation:failed
  */
 export type ExampleValidationFailedPayload = CoreValidationFailedPayload;
+/**
+ * Example frontend store data type
+ */
+export interface ExampleFrontendStoreData {
+    items: ExampleEntity[];
+    selectedId: string | null;
+}
+/**
+ * Example frontend store interface (Zustand-compatible)
+ */
+export interface ExampleFrontendStore extends CoreBaseFrontendStore<ExampleFrontendStoreData> {
+    items: ExampleEntity[];
+    selectedId: string | null;
+    isLoading: boolean;
+    error: Error | null;
+    setData(data: ExampleFrontendStoreData): void;
+    updateData?(data: Partial<ExampleFrontendStoreData>): void;
+    setLoading(isLoading: boolean): void;
+    setError(error: unknown): void;
+    setItems(items: ExampleEntity[]): void;
+    addItem(item: ExampleEntity): void;
+    updateItem(id: string, updates: Partial<ExampleEntity>): void;
+    removeItem(id: string): void;
+    selectItem(id: string | null): void;
+    clearError(): void;
+}
+/**
+ * Example Frontend Service Configuration
+ */
+export interface ExampleFrontendServiceConfig extends CoreBaseFrontendServiceConfig<ExampleFrontendStoreData, ExampleFrontendStore>, CoreServiceInitConfig {
+    /** API base path for example endpoints */
+    apiBasePath?: string;
+    /** Auto-fetch on initialization */
+    autoFetch?: boolean;
+    /** Polling interval in ms (0 = disabled) */
+    pollingInterval?: number;
+}
+/**
+ * Example frontend event types
+ */
+export type ExampleFrontendEventType = 'example:fetching' | 'example:fetched' | 'example:fetch:error' | 'example:creating' | 'example:created' | 'example:create:error' | 'example:updating' | 'example:updated' | 'example:update:error' | 'example:deleting' | 'example:deleted' | 'example:delete:error' | 'example:store:synced';
+/**
+ * Example User entity for backend repository
+ */
+export interface ExampleUser extends Record<string, unknown> {
+    id: string;
+    email: string;
+    name: string;
+    created_at?: string;
+    updated_at?: string;
+    deleted_at?: string | null;
+}
+/**
+ * Example Domain Service Configuration
+ */
+export interface ExampleDomainServiceConfig extends CoreBaseDomainServiceConfig, CoreServiceInitConfig {
+    /** Use real API client instead of mocks */
+    useRealApi?: boolean;
+    /** API base path for example endpoints */
+    apiBasePath?: string;
+}

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

@@ -0,0 +1,67 @@
+/**
+ * Feature Flag DTO Types
+ *
+ * Data Transfer Object types for API communication.
+ * These represent the wire format (snake_case) that the API uses.
+ *
+ * @fileoverview Feature flag API DTO type definitions
+ * @version 1.0.0
+ */
+import type { FeatureFlagValue } from './types';
+/**
+ * API Response DTO for a single feature flag
+ */
+export interface FeatureFlagResponseDTO {
+    key: string;
+    value: FeatureFlagValue;
+    name: string;
+    description?: string;
+    is_enabled: boolean;
+    type: 'boolean' | 'string' | 'number' | 'json';
+    environment: string;
+    rollout_percentage?: number;
+    rules?: FeatureFlagRuleDTO[];
+    metadata?: Record<string, unknown>;
+    tags?: string[];
+    created_at: string;
+    updated_at: string;
+    created_by: string;
+    updated_by: string;
+}
+/**
+ * API Response DTO for a feature flag rule
+ */
+export interface FeatureFlagRuleDTO {
+    id: string;
+    name: string;
+    flag_key: string;
+    conditions: Array<{
+        field: string;
+        operator: string;
+        value: string | number | string[] | number[];
+    }>;
+    value: FeatureFlagValue;
+    priority: number;
+    is_enabled: boolean;
+    rollout_percentage?: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * API Response DTO for evaluation result
+ */
+export interface FeatureFlagEvaluationDTO {
+    key: string;
+    value: FeatureFlagValue;
+    is_enabled: boolean;
+    reason: 'default' | 'rule_match' | 'rollout' | 'override' | 'disabled';
+    source?: 'default' | 'override' | 'rule' | 'rollout';
+    matched_rule_id?: string;
+    evaluated_at: string;
+}
+/**
+ * API Response for fetching all flags
+ */
+export interface FetchAllFlagsResponseDTO {
+    flags: FeatureFlagResponseDTO[];
+    rules?: FeatureFlagRuleDTO[];
+}

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

@@ -1 +1,4 @@
 export type * from './types';
+export type * from './store.types';
+export type * from './service.types';
+export type * from './dto.types';

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

@@ -0,0 +1,184 @@
+/**
+ * Service Flag Requirement Types
+ *
+ * Type definitions for services that depend on feature flags.
+ * Enables declarative flag dependencies per service.
+ *
+ * @fileoverview Service flag requirement type definitions
+ * @version 1.0.0
+ */
+import type { FeatureFlagContext, FeatureFlagProvider, FeatureFlagConfig, FeatureFlagValue } from './types';
+import type { CoreBaseDomainServiceConfig } from '../../core/domain';
+import type { ServiceOptions } from '../../api';
+/**
+ * Requirement specification for a single feature flag
+ */
+export interface ServiceFlagRequirement {
+    /** The feature flag key */
+    key: string;
+    /** Expected value (if undefined, just checks if enabled) */
+    expectedValue?: FeatureFlagValue;
+    /** Whether this flag is required for the service to operate */
+    required: boolean;
+    /** Default value to use if flag is not found */
+    default?: FeatureFlagValue;
+    /** Human-readable description of what this flag controls */
+    description?: string;
+}
+/**
+ * Result of validating flag requirements
+ */
+export interface FlagRequirementValidationResult {
+    /** Whether all required flags are satisfied */
+    isValid: boolean;
+    /** Array of validation errors */
+    errors: FlagRequirementError[];
+    /** Array of validation warnings */
+    warnings: FlagRequirementWarning[];
+    /** Flags that were not found but had defaults applied */
+    defaultsApplied: string[];
+}
+/**
+ * Error when a required flag is missing or has wrong value
+ */
+export interface FlagRequirementError {
+    /** The flag key that failed validation */
+    key: string;
+    /** The expected value (if any) */
+    expectedValue?: FeatureFlagValue;
+    /** The actual value found */
+    actualValue?: FeatureFlagValue;
+    /** Error message */
+    message: string;
+    /** Whether the flag was not found at all */
+    notFound: boolean;
+}
+/**
+ * Warning for non-required flag issues
+ */
+export interface FlagRequirementWarning {
+    /** The flag key */
+    key: string;
+    /** Warning message */
+    message: string;
+    /** The default value that was applied */
+    defaultApplied?: FeatureFlagValue;
+}
+/**
+ * Error thrown when flag requirements are not met
+ */
+export interface ServiceFlagRequirementsErrorDetails {
+    /** Service name that has unmet requirements */
+    serviceName: string;
+    /** Array of requirement errors */
+    errors: FlagRequirementError[];
+}
+/**
+ * Error thrown when a feature is disabled
+ */
+export interface FeatureDisabledErrorDetails {
+    /** The flag key that is disabled */
+    flagKey: string;
+    /** Optional message */
+    message?: string;
+}
+/**
+ * Error thrown when a flag value doesn't match expected
+ */
+export interface FeatureFlagMismatchErrorDetails {
+    /** The flag key */
+    flagKey: string;
+    /** The expected value */
+    expectedValue: FeatureFlagValue;
+    /** The actual value */
+    actualValue: FeatureFlagValue | undefined;
+}
+/**
+ * Interface for services that depend on feature flags
+ */
+export interface FlagDependentServiceInterface {
+    /**
+     * Validate that all flag requirements are met
+     * Called during service initialization
+     */
+    validateFlagRequirements(): Promise<FlagRequirementValidationResult>;
+    /**
+     * Get the flag requirements for this service
+     */
+    getFlagRequirements(): ServiceFlagRequirement[];
+}
+/**
+ * Configuration for flag-dependent service base class
+ */
+export interface FlagDependentServiceConfig {
+    /** Service name (for error messages) */
+    serviceName: string;
+    /** Flag requirements */
+    requirements: ServiceFlagRequirement[];
+    /** Whether to throw on validation failure */
+    throwOnValidationFailure?: boolean;
+    /** Whether to log warnings */
+    logWarnings?: boolean;
+}
+/**
+ * Utility type to extract flag keys from requirements array
+ */
+export type ExtractFlagKeys<T extends readonly ServiceFlagRequirement[]> = T[number]['key'];
+/**
+ * Utility type to create a typed flag map from requirements
+ */
+export type FlagMapFromRequirements<T extends readonly ServiceFlagRequirement[]> = {
+    [K in T[number]['key']]: FeatureFlagValue;
+};
+/**
+ * Feature flag event types (backend domain service)
+ */
+export type FeatureFlagDomainEventType = 'featureFlag:backend:evaluating' | 'featureFlag:backend:evaluated' | 'featureFlag:backend:evaluate:error' | 'featureFlag:backend:creating' | 'featureFlag:backend:created' | 'featureFlag:backend:create:error' | 'featureFlag:backend:updating' | 'featureFlag:backend:updated' | 'featureFlag:backend:update:error' | 'featureFlag:backend:deleting' | 'featureFlag:backend:deleted' | 'featureFlag:backend:delete:error' | 'featureFlag:backend:override:setting' | 'featureFlag:backend:override:set' | 'featureFlag:backend:override:removing' | 'featureFlag:backend:override:removed' | 'featureFlag:backend:provider:initialized' | 'featureFlag:backend:provider:refreshed' | 'featureFlag:backend:provider:disposed';
+/**
+ * Backend Feature Flag Domain Service configuration
+ */
+export interface FeatureFlagDomainServiceConfig extends CoreBaseDomainServiceConfig {
+    /** Default context for evaluations */
+    defaultContext?: FeatureFlagContext;
+    /** Feature flag provider (database, redis, memory, etc.) */
+    provider: FeatureFlagProvider<string>;
+}
+/**
+ * API client type for service options
+ */
+type ApiClientType = NonNullable<ServiceOptions['apiClient']>;
+/**
+ * API Feature Flag Provider Configuration (extends base config)
+ */
+export interface ApiFeatureFlagConfig<TKey extends string> extends FeatureFlagConfig<TKey> {
+    /** API client instance to use for requests */
+    apiClient: ApiClientType;
+    /** Optional context for evaluations */
+    context?: FeatureFlagContext;
+}
+/**
+ * Options for creating feature flag config
+ *
+ * Note: Database connection is handled by DbService (via Core.initialize()),
+ * so no connection string is needed here. The database provider will use
+ * the already-configured DbService.
+ *
+ * Environment is read from Core.env.NODE_ENV - no need to pass it.
+ */
+export interface FeatureFlagConfigOptions {
+    /** Provider type - 'database' uses DbService which must be initialized via Core.initialize() */
+    provider?: 'memory' | 'database' | 'redis' | 'api' | 'file';
+    /** Enable caching */
+    cacheEnabled?: boolean;
+    /** Cache TTL in seconds */
+    cacheTtl?: number;
+    /** Refresh interval in seconds */
+    refreshInterval?: number;
+    /** Enable logging (defaults to true in development based on Core.env.NODE_ENV) */
+    loggingEnabled?: boolean;
+    /** Fallback to defaults when flag not found */
+    fallbackToDefaults?: boolean;
+    /** Table name for database provider (defaults to 'feature_flags') */
+    tableName?: string;
+}
+export {};