@plyaz/types 1.22.1 → 1.22.3

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

@@ -6,11 +6,12 @@
  */
 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, ErrorHandlerLogger } from '../../errors/middleware';
-import type { CoreAppEnvironment, CoreAppContext, CoreRuntimeEnvironment } from '../modules';
+import type { CoreAppEnvironment, CoreAppContext, CoreRuntimeEnvironment, CoreServiceRuntime } from '../modules';
 import type { CoreDbServiceConfig } from '../services';
+import type { CoreInjectedServices } from '../domain';
 /**
  * Base interface that all domain service instances must implement.
  * This allows the registry to manage services generically.
@@ -148,11 +149,93 @@ 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;
+    /**
+     * Service-level cache configuration.
+     * Controls caching behavior for this specific service's operations.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   service: ExampleService,
+     *   config: {
+     *     cache: {
+     *       enabled: true,
+     *       defaultTtl: 300, // 5 minutes
+     *     },
+     *   },
+     * }
+     * ```
+     */
+    cache?: {
+        /** Enable cache for this service (default: true) */
+        enabled?: boolean;
+        /** Default TTL in seconds for cached operations */
+        defaultTtl?: number;
+    };
 }
 /**
  * Options passed to the service factory method
  */
-export interface CoreServiceCreateOptions {
+export interface CoreServiceCreateOptions<TConfig = unknown, TMapper = unknown, TValidator = unknown> {
+    /**
+     * The service-specific configuration object.
+     * Optional when passed from ServiceRegistry (services build their own).
+     */
+    serviceConfig?: TConfig;
+    /**
+     * Mapper class to use for DTO transformations.
+     */
+    MapperClass?: new () => TMapper;
+    /**
+     * Validator class to use for validation.
+     */
+    ValidatorClass?: new () => TValidator;
+    /**
+     * Service name for logging and identification.
+     * Optional when passed from ServiceRegistry (services provide their own).
+     */
+    serviceName?: string;
+    /**
+     * Supported runtime environments.
+     * Optional when passed from ServiceRegistry (services provide their own).
+     */
+    supportedRuntimes?: readonly CoreServiceRuntime[];
     /**
      * API client configuration and mode.
      */
@@ -168,6 +251,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 +272,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;
@@ -194,6 +308,11 @@ export interface CoreServiceCreateOptions {
      * Passed from the service config to the create method.
      */
     storeKeys?: StoreKey[];
+    /**
+     * Injected service instances (cache, db, api).
+     * Services built by ServiceRegistry will receive these automatically.
+     */
+    injected?: CoreInjectedServices;
 }
 /**
  * Static interface that service classes must implement.
@@ -258,10 +377,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[];
 }
@@ -320,6 +445,63 @@ export interface CoreErrorHandlerInitConfig extends Omit<GlobalErrorHandlerConfi
      * Set to false to disable logging.
      */
     logger?: ErrorHandlerLogger | boolean;
+    /**
+     * Localization configuration for error messages.
+     * Configure how error messages are translated and which locales are available.
+     *
+     * @example
+     * ```typescript
+     * errorHandler: {
+     *   localization: {
+     *     defaultLocale: 'es',
+     *     fallbackLocale: 'en',
+     *     additionalCatalogs: {
+     *       es: { errors: { custom_error: 'Error personalizado' } }
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    localization?: {
+        /** Default locale to use for error messages (default: 'en') */
+        defaultLocale?: string;
+        /** Fallback locale if translation not found (default: 'en') */
+        fallbackLocale?: string;
+        /** Additional message catalogs to merge with built-in messages */
+        additionalCatalogs?: Record<string, unknown>;
+        /** Replace built-in catalogs entirely (default: false) */
+        replaceBuiltIn?: 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
@@ -338,10 +520,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 */
@@ -354,11 +540,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/modules.d.ts

@@ -311,7 +311,7 @@ export interface CoreApiInitOptions {
 /**
  * Core initialization options
  */
-export interface CoreInitOptions<TDbConfig = unknown, TApiConfig = CoreApiInitOptions> {
+export interface CoreInitOptions<TDbConfig = unknown, TApiConfig = CoreApiInitOptions, TCacheConfig = unknown> {
     /** Path to .env file */
     envPath?: string;
     /** Global application environment */
@@ -324,19 +324,24 @@ export interface CoreInitOptions<TDbConfig = unknown, TApiConfig = CoreApiInitOp
     db?: TDbConfig;
     /** API client configuration */
     api?: TApiConfig;
+    /** Cache configuration */
+    cache?: TCacheConfig;
     /** Skip database initialization */
     skipDb?: boolean;
     /** Skip API client initialization */
     skipApi?: boolean;
+    /** Skip cache initialization */
+    skipCache?: boolean;
     /** Enable verbose logging */
     verbose?: boolean;
 }
 /**
  * Core initialization result
  */
-export interface CoreServicesResult<TDb = unknown, TApi = unknown> {
+export interface CoreServicesResult<TDb = unknown, TApi = unknown, TCache = unknown> {
     db: TDb | null;
     api: TApi | null;
+    cache: TCache | null;
     env: CoreEnvVars;
     runtime: CoreRuntimeEnvironment;
     appContext: CoreAppContext;

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