@plyaz/types 1.22.0 → 1.22.2

package/dist/core/init/types.d.ts

@@ -6,9 +6,9 @@
  */
 import type { ApiClientOptions } from '../../api';
 import type { StoreKey } from '../../store';
-import type { FeatureFlagValue, FeatureFlagPollingConfig } from '../../features';
+import type { FeatureFlagValue, FeatureFlagPollingConfig, CacheStrategyType } from '../../features';
 import type { PackageErrorLike } from '../../errors';
-import type { GlobalErrorHandlerConfig } from '../../errors/middleware';
+import type { GlobalErrorHandlerConfig, ErrorHandlerLogger } from '../../errors/middleware';
 import type { CoreAppEnvironment, CoreAppContext, CoreRuntimeEnvironment } from '../modules';
 import type { CoreDbServiceConfig } from '../services';
 /**
@@ -148,6 +148,42 @@ export interface CoreServiceInitConfig {
      * ```
      */
     dedicatedDb?: boolean | Partial<CoreDbServiceConfig>;
+    /**
+     * Create a dedicated cache instance for this service.
+     *
+     * By default, services share the global cache instance. Use this when
+     * a service needs its own isolated cache (e.g., different TTL, separate namespace).
+     *
+     * - `false` or `undefined`: Use global shared cache (default)
+     * - `true`: Create dedicated instance using global config
+     * - `CoreCacheConfig`: Create dedicated instance with custom config
+     *
+     * For Redis strategy, services using the same URL will share connections.
+     * For memory strategy, each service gets its own isolated cache.
+     *
+     * @example
+     * ```typescript
+     * // Use global shared cache (default)
+     * { service: UserService, config: { enabled: true } }
+     *
+     * // Create dedicated cache with global config
+     * { service: SessionService, config: { dedicatedCache: true } }
+     *
+     * // Create dedicated cache with custom config
+     * {
+     *   service: RateLimitService,
+     *   config: {
+     *     dedicatedCache: {
+     *       strategy: 'redis',
+     *       isEnabled: true,
+     *       ttl: 60, // 1 minute TTL for rate limits
+     *       prefix: 'ratelimit',
+     *     },
+     *   },
+     * }
+     * ```
+     */
+    dedicatedCache?: boolean | CoreCacheConfig;
 }
 /**
  * Options passed to the service factory method
@@ -168,6 +204,11 @@ export interface CoreServiceCreateOptions {
          * Used to create dedicated instance or configure global.
          */
         options?: ApiClientOptions;
+        /**
+         * Actual API client instance to use.
+         * Injected by ServiceRegistry, not created by service.
+         */
+        instance?: unknown;
     };
     /**
      * Database configuration and mode.
@@ -184,6 +225,32 @@ export interface CoreServiceCreateOptions {
          * Used to create dedicated instance or configure global.
          */
         config?: Partial<CoreDbServiceConfig>;
+        /**
+         * Actual database service instance to use.
+         * Injected by ServiceRegistry, not created by service.
+         */
+        instance?: unknown;
+    };
+    /**
+     * Cache configuration and mode.
+     */
+    cache?: {
+        /**
+         * Whether to use a dedicated (isolated) cache instance.
+         * - `false`: Use global shared instance (default)
+         * - `true`: Create dedicated instance
+         */
+        dedicated: boolean;
+        /**
+         * Cache config (merged global + per-service config).
+         * Used to create dedicated instance or configure global.
+         */
+        config?: CoreCacheConfig;
+        /**
+         * Actual CacheManager instance to use.
+         * Injected by ServiceRegistry, not created by service.
+         */
+        instance?: unknown;
     };
     /** Logger prefix */
     loggerPrefix?: string;
@@ -258,10 +325,16 @@ export interface CoreServiceEntry<TConfig extends CoreServiceInitConfig = CoreSe
  * ```
  */
 export interface CoreServiceRegistryConfig {
+    /** Global environment (production, staging, development, test) */
+    environment?: CoreAppEnvironment;
+    /** Runtime environment (node, browser, react-native, etc.) */
+    runtime?: CoreRuntimeEnvironment;
     /** Global API client options (shared by all services unless overridden) */
     apiClient?: ApiClientOptions;
     /** Global database config (shared by all services unless overridden) */
     db?: Partial<CoreDbServiceConfig>;
+    /** Global cache config (shared by all services unless overridden) */
+    cache?: CoreCacheConfig;
     /** Services to register and initialize */
     services: CoreServiceEntry[];
 }
@@ -299,6 +372,57 @@ export interface CoreErrorHandlerInitConfig extends Omit<GlobalErrorHandlerConfi
      * Set to false to use your own error handling.
      */
     enabled?: boolean;
+    /**
+     * Whether to auto-create HTTP error handler based on runtime (default: true).
+     * When enabled, Core will create the appropriate middleware for:
+     * - Express: createHttpErrorHandler
+     * - NestJS: createNestJsExceptionFilter
+     * - Next.js: withErrorHandler / createNextApiErrorHandler
+     * - Node.js: handleNodeError
+     *
+     * Access via Core.httpErrorHandler or Core.getHttpErrorHandler()
+     */
+    httpHandler?: boolean;
+    /**
+     * Include stack traces in HTTP error responses (default: false in production)
+     */
+    includeStack?: boolean;
+    /**
+     * Custom logger for error handlers.
+     * If not provided, uses default console logger.
+     * Set to false to disable logging.
+     */
+    logger?: ErrorHandlerLogger | boolean;
+}
+/**
+ * Cache initialization configuration
+ */
+export interface CoreCacheConfig {
+    /** Cache strategy to use */
+    strategy: CacheStrategyType;
+    /** Whether caching is enabled (default: true) */
+    isEnabled: boolean;
+    /** Default TTL in seconds (default: 300 - 5 minutes) */
+    ttl?: number;
+    /** Key prefix for all cache entries (default: 'app') */
+    prefix?: string;
+    /** Redis-specific configuration (required when strategy is 'redis') */
+    redis?: {
+        /** Redis connection URL (e.g., redis://localhost:6379) */
+        url?: string;
+        /** Redis host (alternative to url) */
+        host?: string;
+        /** Redis port (default: 6379) */
+        port?: number;
+        /** Redis password */
+        password?: string;
+        /** Redis database number (default: 0) */
+        db?: number;
+        /** Connection timeout in milliseconds */
+        connectTimeout?: number;
+        /** Key prefix for Redis keys */
+        keyPrefix?: string;
+    };
 }
 /**
  * Base core initialization options
@@ -317,10 +441,14 @@ export interface CoreInitOptionsBase<TDb = unknown, TApi = unknown> {
     db?: TDb;
     /** API client configuration */
     api?: TApi;
+    /** Cache configuration */
+    cache?: CoreCacheConfig;
     /** Skip database initialization */
     skipDb?: boolean;
     /** Skip API client initialization */
     skipApi?: boolean;
+    /** Skip cache initialization */
+    skipCache?: boolean;
     /** Enable verbose logging */
     verbose?: boolean;
     /** Error handler configuration */
@@ -333,11 +461,13 @@ export interface CoreInitOptionsBase<TDb = unknown, TApi = unknown> {
 /**
  * Core services result from initialization
  */
-export interface CoreServicesResultBase<TDb = unknown, TApi = unknown> {
+export interface CoreServicesResultBase<TDb = unknown, TApi = unknown, TCache = unknown> {
     /** Database service instance (null if skipped or on frontend) */
     db: TDb | null;
     /** API client service class */
     api: TApi | null;
+    /** Cache service instance (null if skipped or on frontend) */
+    cache: TCache | null;
     /** Loaded environment variables */
     env: Record<string, string | undefined>;
     /** Detected runtime environment */

package/dist/core/services/index.d.ts

@@ -3,3 +3,4 @@
  * Type definitions for @plyaz/core services
  */
 export type * from './types';
+export { SERVICE_KEYS, ALL_SERVICE_KEYS, type ServiceKey } from './keys';

package/dist/core/services/keys.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Service Keys Constants
+ *
+ * Centralized service key constants for service registry and dependency injection.
+ * Use these constants instead of string literals for type safety and consistency.
+ *
+ * @example
+ * ```typescript
+ * import { SERVICE_KEYS } from '@plyaz/types/core/services';
+ *
+ * class MyService {
+ *   static readonly serviceKey = SERVICE_KEYS.EXAMPLE;
+ * }
+ *
+ * // Use in service registry
+ * const service = ServiceRegistry.get(SERVICE_KEYS.EXAMPLE);
+ * ```
+ */
+/**
+ * Keys for all available domain services.
+ * These keys are used for service registration and lookup in the ServiceRegistry.
+ */
+export declare const SERVICE_KEYS: {
+    /** Example domain service (backend) */
+    readonly EXAMPLE: "example";
+    /** Example domain service (frontend) */
+    readonly EXAMPLE_FRONTEND: "example-frontend";
+    /** Feature flags service */
+    readonly FEATURE_FLAGS: "featureFlags";
+};
+/**
+ * Type for service keys.
+ * Ensures only valid service keys can be used.
+ */
+export type ServiceKey = (typeof SERVICE_KEYS)[keyof typeof SERVICE_KEYS];
+/**
+ * Array of all service keys for iteration.
+ * Useful for validating service configurations or iterating over all services.
+ */
+export declare const ALL_SERVICE_KEYS: ServiceKey[];

package/dist/errors/codes.d.ts

@@ -826,6 +826,17 @@ export declare const CORE_ERROR_CODES: {
     readonly CONFIGURATION_INVALID: "core.configuration_invalid";
     readonly OPERATION_FAILED: "core.operation_failed";
     readonly UNKNOWN_ERROR: "core.unknown_error";
+    readonly CLIENT_INITIALIZATION_FAILED: "CLIENT_INITIALIZATION_FAILED";
+    readonly CLIENT_INVALID_CONFIG: "CLIENT_INVALID_CONFIG";
+    readonly CONTEXT_OPERATION_FAILED: "CONTEXT_OPERATION_FAILED";
+    readonly FEATURE_NOT_SUPPORTED: "feature.not.supported";
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly RESOURCE_NOT_FOUND: "RESOURCE_NOT_FOUND";
+    readonly DB_CONNECTION_FAILED: "db.connection_failed";
+    readonly DB_DUPLICATE_ENTRY: "db.duplicate_entry";
+    readonly PROVIDER_NOT_IMPLEMENTED: "provider.not.implemented";
+    readonly STORAGE_FILE_WRITE_FAILED: "storage.file.write.failed";
 };
 /**
  * PAYMENT-specific error codes

package/dist/errors/index.cjs

@@ -1324,7 +1324,19 @@ var CORE_ERROR_CODES = {
   INITIALIZATION_FAILED: ERROR_CODES.CORE_INITIALIZATION_FAILED,
   CONFIGURATION_INVALID: ERROR_CODES.CORE_CONFIGURATION_INVALID,
   OPERATION_FAILED: ERROR_CODES.CORE_OPERATION_FAILED,
-  UNKNOWN_ERROR: ERROR_CODES.CORE_UNKNOWN_ERROR
+  UNKNOWN_ERROR: ERROR_CODES.CORE_UNKNOWN_ERROR,
+  // Common/Generic Errors (used across core package)
+  CLIENT_INITIALIZATION_FAILED: ERROR_CODES.CLIENT_INITIALIZATION_FAILED,
+  CLIENT_INVALID_CONFIG: ERROR_CODES.CLIENT_INVALID_CONFIG,
+  CONTEXT_OPERATION_FAILED: ERROR_CODES.CONTEXT_OPERATION_FAILED,
+  FEATURE_NOT_SUPPORTED: ERROR_CODES.FEATURE_NOT_SUPPORTED,
+  VALIDATION_ERROR: ERROR_CODES.VALIDATION_ERROR,
+  NETWORK_ERROR: ERROR_CODES.NETWORK_ERROR,
+  RESOURCE_NOT_FOUND: ERROR_CODES.RESOURCE_NOT_FOUND,
+  DB_CONNECTION_FAILED: ERROR_CODES.DB_CONNECTION_FAILED,
+  DB_DUPLICATE_ENTRY: ERROR_CODES.DB_DUPLICATE_ENTRY,
+  PROVIDER_NOT_IMPLEMENTED: ERROR_CODES.PROVIDER_NOT_IMPLEMENTED,
+  STORAGE_FILE_WRITE_FAILED: ERROR_CODES.STORAGE_FILE_WRITE_FAILED
 };
 var PAYMENT_ERROR_CODES = {
   // Timeout & Network