@plyaz/core 1.1.1 → 1.2.1

package/dist/init/ServiceRegistry.d.ts

@@ -0,0 +1,256 @@
+/**
+ * Service Registry - Frontend Service Auto-Initialization
+ *
+ * Provides a generic, scalable pattern for initializing domain services.
+ * Services implement the InitializableDomainService interface and are
+ * initialized automatically without hardcoded switch statements.
+ *
+ * @example
+ * ```typescript
+ * import { ServiceRegistry } from '@plyaz/core';
+ * import { FeatureFlagDomainService } from '@plyaz/core/frontend';
+ * import { ExampleDomainService } from '@plyaz/core/domain';
+ *
+ * // Initialize services
+ * await ServiceRegistry.initialize({
+ *   apiClient: { baseURL: '/api' },
+ *   services: [
+ *     { service: FeatureFlagDomainService, config: { enabled: true } },
+ *     { service: ExampleDomainService, config: { enabled: true, useRealApi: false } },
+ *   ],
+ * });
+ *
+ * // Access services by key
+ * const flags = ServiceRegistry.get('featureFlags');
+ * const isEnabled = await flags.isEnabled('my-flag');
+ *
+ * // Or get with type safety
+ * const example = ServiceRegistry.get<ExampleDomainService>('example');
+ * ```
+ */
+import type { CoreDomainServiceInstance, CoreServiceEntry, CoreServiceInitConfig, CoreServiceRegistryConfig } from '@plyaz/types/core';
+import type { ObservabilityAdapter } from '@plyaz/types/observability';
+/**
+ * Service Registry
+ *
+ * Manages frontend domain service instances with auto-initialization.
+ * Supports immediate, lazy, and conditional initialization.
+ *
+ * Key features:
+ * - Generic: No switch statements, services implement common interface
+ * - Scalable: Add new services without modifying registry code
+ * - Flexible: Immediate, lazy, or conditional initialization
+ * - Type-safe: Get services with proper typing
+ */
+export declare class ServiceRegistry {
+    private static readonly logger;
+    /** Initialized singleton service instances by key */
+    private static _services;
+    /** Pending services for lazy initialization */
+    private static _pending;
+    /** Service metadata (config, singleton flag) by key */
+    private static _metadata;
+    /** Global environment */
+    private static _environment;
+    /** Runtime environment (node, browser, bun, etc.) */
+    private static _runtime;
+    /** Global API client options */
+    private static _apiClientOptions;
+    /** Global database config */
+    private static _dbConfig;
+    /** Global cache config */
+    private static _cacheConfig;
+    /** Global observability config */
+    private static _observabilityConfig;
+    /** Global observability adapter instance */
+    private static _observabilityInstance;
+    /** Global storage config */
+    private static _storageConfig;
+    /** Global notifications config */
+    private static _notificationsConfig;
+    /** Store registry interface from Core (type-safe) */
+    private static _storeRegistry;
+    /** Initialization promises (for concurrent access during lazy init) */
+    private static _initPromises;
+    /**
+     * Initialize the service registry with the provided configuration.
+     *
+     * @param config - Registry configuration with services to initialize
+     *
+     * @example
+     * ```typescript
+     * await ServiceRegistry.initialize({
+     *   apiClient: { baseURL: '/api' },
+     *   services: [
+     *     { service: FeatureFlagDomainService, config: { enabled: true } },
+     *     { service: ExampleDomainService, config: { enabled: true, initWhen: 'lazy' } },
+     *   ],
+     * });
+     * ```
+     */
+    static initialize(config: CoreServiceRegistryConfig): Promise<void>;
+    /**
+     * Get a singleton service instance by key (synchronous).
+     * Throws if the service is not initialized or is non-singleton.
+     *
+     * @param key - Service key (e.g., 'featureFlags', 'example')
+     * @returns The service instance
+     * @throws CorePackageError if service not found, not initialized, or non-singleton
+     *
+     * @example
+     * ```typescript
+     * const flags = ServiceRegistry.get<FeatureFlagDomainService>('featureFlags');
+     * const isEnabled = await flags.isEnabled('my-flag');
+     * ```
+     */
+    static get<T extends CoreDomainServiceInstance = CoreDomainServiceInstance>(key: string): T;
+    /**
+     * Create a new instance of a service.
+     * Use this for non-singleton services or when you need a fresh instance.
+     *
+     * Note: The caller is responsible for disposing the returned instance.
+     *
+     * @param key - Service key
+     * @param configOverrides - Optional config overrides for this instance
+     * @returns Promise resolving to a new service instance
+     *
+     * @example
+     * ```typescript
+     * // Non-singleton service - always creates new instance
+     * const instance1 = await ServiceRegistry.create<WorkerService>('worker');
+     * const instance2 = await ServiceRegistry.create<WorkerService>('worker');
+     * instance1 !== instance2; // true
+     *
+     * // With config overrides
+     * const customWorker = await ServiceRegistry.create<WorkerService>('worker', {
+     *   apiClient: { baseURL: 'https://custom-api.com' },
+     * });
+     *
+     * // Don't forget to dispose when done!
+     * instance1.dispose();
+     * instance2.dispose();
+     * ```
+     */
+    static create<T extends CoreDomainServiceInstance = CoreDomainServiceInstance>(key: string, configOverrides?: Partial<CoreServiceInitConfig>): Promise<T>;
+    /**
+     * Get a service instance by key with async initialization if needed.
+     * Use this for lazy-initialized services.
+     *
+     * @param key - Service key
+     * @returns Promise resolving to the service instance
+     *
+     * @example
+     * ```typescript
+     * const example = await ServiceRegistry.getAsync<ExampleDomainService>('example');
+     * const entities = await example.getAll();
+     * ```
+     */
+    static getAsync<T extends CoreDomainServiceInstance = CoreDomainServiceInstance>(key: string): Promise<T>;
+    /**
+     * Check if a service is registered (either initialized or pending).
+     *
+     * @param key - Service key
+     */
+    static has(key: string): boolean;
+    /**
+     * Check if a service is initialized and ready.
+     *
+     * @param key - Service key
+     */
+    static isInitialized(key: string): boolean;
+    /**
+     * Get all initialized service keys.
+     */
+    static getInitializedKeys(): string[];
+    /**
+     * Get all pending (lazy) service keys.
+     */
+    static getPendingKeys(): string[];
+    /** Build API client options and instance for service */
+    private static buildApiClientOptions;
+    /** Build DB config and instance for service with runtime validation */
+    private static buildDbConfig;
+    /** Build cache config and instance for service with runtime validation */
+    private static buildCacheConfig;
+    /** Build observability config and instance for service */
+    private static buildObservabilityConfig;
+    /** Build storage config and instance for service with runtime validation (backend-only) */
+    private static buildStorageConfig;
+    /** Build notifications config and instance for service with runtime validation (backend-only) */
+    private static buildNotificationsConfig;
+    /**
+     * Create a dedicated ObservabilityService instance for a service.
+     * Uses the same adapter pattern as global observability but with service-specific config.
+     */
+    private static createDedicatedObservability;
+    /**
+     * Set the global observability adapter instance.
+     * Called by Core.initialize() after creating the adapter.
+     */
+    static setObservabilityInstance(instance: ObservabilityAdapter): void;
+    /**
+     * Get the global observability adapter instance.
+     */
+    static getObservabilityInstance(): ObservabilityAdapter | null;
+    /**
+     * Initialize a single service from an entry.
+     * Uses the service class's static create() method.
+     * Merges per-service config with global config.
+     */
+    private static initializeService;
+    /** Build stores for service injection */
+    private static buildStoresForService;
+    /** Perform the actual service initialization */
+    private static doInitializeService;
+    /**
+     * Dispose a specific service by key.
+     *
+     * @param key - Service key to dispose
+     */
+    static dispose(key: string): void;
+    /**
+     * Dispose all services and clear the registry.
+     */
+    static disposeAll(): void;
+    /**
+     * Check if a service is configured as singleton.
+     *
+     * @param key - Service key
+     * @returns true if singleton (default), false if non-singleton
+     */
+    static isSingleton(key: string): boolean;
+    /**
+     * Get all non-singleton service keys.
+     * These services must be created via `create()` method.
+     */
+    static getNonSingletonKeys(): string[];
+    /**
+     * Register a new service dynamically after initialization.
+     *
+     * @param entry - Service entry to register
+     * @param initNow - Whether to initialize immediately (default: true)
+     *
+     * @example
+     * ```typescript
+     * // Register and initialize immediately
+     * await ServiceRegistry.register({
+     *   service: NewDomainService,
+     *   config: { enabled: true },
+     * });
+     *
+     * // Register for lazy initialization
+     * ServiceRegistry.register({
+     *   service: LazyService,
+     *   config: { enabled: true, initWhen: 'lazy' },
+     * }, false);
+     * ```
+     */
+    static register(entry: CoreServiceEntry, initNow?: boolean): Promise<void>;
+    /**
+     * Unregister a service (dispose if initialized).
+     *
+     * @param key - Service key to unregister
+     */
+    static unregister(key: string): void;
+}
+//# sourceMappingURL=ServiceRegistry.d.ts.map

package/dist/init/ServiceRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ServiceRegistry.d.ts","sourceRoot":"","sources":["../../src/init/ServiceRegistry.ts"],"names":[],"mappings":"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"}

package/dist/init/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Core initialization exports
+ *
+ * Import runtime types directly from '@plyaz/types/core':
+ * - CoreRuntimeEnvironment, CoreRuntimeContext
+ * - BACKEND_RUNTIMES, FRONTEND_RUNTIMES, UNIVERSAL_RUNTIMES
+ */
+export { Core, DEFAULT_ENCRYPTION_FIELDS } from './CoreInitializer';
+export type { CoreInitOptions, CoreServicesResult } from './CoreInitializer';
+export type { CoreEnvVars, CoreFeatureFlagInitConfig, CoreErrorHandlerInitConfig, } from '@plyaz/types/core';
+export { ServiceRegistry } from './ServiceRegistry';
+export { DbService } from '../services/DbService';
+export { ApiClientService } from '../services/ApiClientService';
+//# sourceMappingURL=index.d.ts.map

package/dist/init/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/init/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,IAAI,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAC;AAEpE,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAG7E,YAAY,EACV,WAAW,EACX,yBAAyB,EACzB,0BAA0B,GAC3B,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGpD,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/init/nestjs/CoreModule.d.ts

@@ -0,0 +1,63 @@
+/**
+ * NestJS Module for @plyaz/core
+ *
+ * Provides dependency injection integration for NestJS applications.
+ *
+ * @example
+ * ```typescript
+ * // app.module.ts
+ * import { CoreModule } from '@plyaz/core/nestjs';
+ *
+ * @Module({
+ *   imports: [
+ *     CoreModule.forRoot({
+ *       envPath: '.env',
+ *       db: { adapter: 'sql' },
+ *     }),
+ *   ],
+ * })
+ * export class AppModule {}
+ * ```
+ *
+ * @example Async configuration
+ * ```typescript
+ * CoreModule.forRootAsync({
+ *   imports: [ConfigModule],
+ *   useFactory: (config: ConfigService) => ({
+ *     db: {
+ *       adapter: 'sql',
+ *       sql: { connectionString: config.get('DATABASE_URL') },
+ *     },
+ *   }),
+ *   inject: [ConfigService],
+ * })
+ * ```
+ */
+import type { DynamicModule } from '@nestjs/common';
+import { type CoreInitOptions } from '../CoreInitializer';
+import type { CoreNestJsCoreModuleAsyncOptions } from '@plyaz/types/core';
+/**
+ * Injection tokens for Core services
+ */
+export declare const CORE_OPTIONS: unique symbol;
+export declare const DB_SERVICE: unique symbol;
+/**
+ * Async configuration options for CoreModule
+ * Uses CoreInitOptions for type safety with Core.initialize()
+ */
+type CoreModuleAsyncOptions = CoreNestJsCoreModuleAsyncOptions;
+/**
+ * CoreModule - NestJS DI module for @plyaz/core
+ */
+export declare class CoreModule {
+    /**
+     * Register CoreModule with static configuration
+     */
+    static forRoot(options?: CoreInitOptions): DynamicModule;
+    /**
+     * Register CoreModule with async configuration
+     */
+    static forRootAsync(options: CoreModuleAsyncOptions): DynamicModule;
+}
+export {};
+//# sourceMappingURL=CoreModule.d.ts.map

package/dist/init/nestjs/CoreModule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CoreModule.d.ts","sourceRoot":"","sources":["../../../src/init/nestjs/CoreModule.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,gBAAgB,CAAC;AAC9D,OAAO,EAAQ,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAEhE,OAAO,KAAK,EAAE,gCAAgC,EAAE,MAAM,mBAAmB,CAAC;AAE1E;;GAEG;AACH,eAAO,MAAM,YAAY,eAAyB,CAAC;AACnD,eAAO,MAAM,UAAU,eAAuB,CAAC;AAE/C;;;GAGG;AACH,KAAK,sBAAsB,GAAG,gCAAgC,CAAC;AAE/D;;GAEG;AACH,qBAAa,UAAU;IACrB;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,eAAoB,GAAG,aAAa;IA8B5D;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,sBAAsB,GAAG,aAAa;CAiCpE"}

package/dist/init/nestjs/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * NestJS integration exports
+ */
+export { CoreModule, CORE_OPTIONS, DB_SERVICE } from './CoreModule';
+//# sourceMappingURL=index.d.ts.map

package/dist/init/nestjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/init/nestjs/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC"}