@plyaz/core 1.2.0 → 1.2.1

package/dist/domain/base/BaseDomainService.d.ts

@@ -0,0 +1,284 @@
+/**
+ * Base Domain Service
+ *
+ * Abstract base class for all domain services in @plyaz/core.
+ * Follows the same pattern as BaseAdapter in @plyaz/notifications.
+ *
+ * Provides:
+ * - API client initialization via constructor config
+ * - Automatic mapper/validator instantiation
+ * - Service enabled/disabled state management
+ * - Default values handling
+ * - Runtime context detection
+ * - Lazy logger initialization
+ *
+ * Subclasses must implement:
+ * - isAvailable() - Check if service is configured and ready
+ * - dispose() - Cleanup resources
+ *
+ * @example
+ * ```typescript
+ * interface MyServiceConfig extends BaseDomainServiceConfig {
+ *   apiBasePath?: string;
+ * }
+ *
+ * class MyDomainService extends BaseDomainService<
+ *   MyServiceConfig,
+ *   MyMapper,
+ *   MyValidator
+ * > {
+ *   constructor(config: MyServiceConfig) {
+ *     super({
+ *       serviceName: 'MyDomainService',
+ *       supportedRuntimes: ['universal'],
+ *       serviceConfig: config,
+ *       apiClientConfig: {
+ *         baseURL: config.apiBasePath ?? '/api',
+ *       },
+ *       MapperClass: MyMapperClass,
+ *       ValidatorClass: MyValidatorClass,
+ *     });
+ *   }
+ *
+ *   isAvailable(): boolean {
+ *     return this.config.enabled !== false;
+ *   }
+ *
+ *   dispose(): void {
+ *     // Cleanup
+ *   }
+ *
+ *   async create(data: unknown): Promise<MyEntity> {
+ *     this.assertReady();
+ *     const validated = this.validator.validateCreateOrThrow(data);
+ *     const dto = this.mapper.toCreateDTO(validated);
+ *     const response = await this.apiClient.post('/entities', dto);
+ *     return this.mapper.toDomain(response.data);
+ *   }
+ * }
+ *
+ * // Usage
+ * const service = new MyDomainService({ enabled: true, apiBasePath: '/api/v1' });
+ * await service.ensureApiClientInitialized();
+ * const entity = await service.create({ name: 'Test' });
+ * ```
+ */
+import { PackageLogger } from '@plyaz/logger';
+import type { CoreBaseMapperInstance, CoreBaseValidatorInstance, CoreServiceRuntime } from '@plyaz/types/core';
+import type { FeatureFlagValue } from '@plyaz/types/features';
+import { createApiClient } from '@plyaz/api';
+import type { CoreBaseDomainServiceConfig, CoreBaseServiceConfig } from '@plyaz/types/core';
+import type { DatabaseServiceInterface } from '@plyaz/types/db';
+import type { CacheManager } from '@/base/cache';
+import type { ObservabilityAdapter, Span } from '@plyaz/types/observability';
+/**
+ * API client type (from @plyaz/api)
+ */
+export type ApiClient = Awaited<ReturnType<typeof createApiClient>>;
+/**
+ * Abstract base class for domain services
+ *
+ * Uses generics for strong typing:
+ * - TConfig: Service configuration type
+ * - TMapper: Mapper instance type
+ * - TValidator: Validator instance type
+ *
+ * Subclasses use the super({...}) pattern:
+ * ```typescript
+ * class MyService extends BaseDomainService<MyConfig, MyMapper, MyValidator> {
+ *   constructor(config: MyConfig) {
+ *     super({
+ *       serviceName: 'MyService',
+ *       supportedRuntimes: ['universal'],
+ *       serviceConfig: config,
+ *       apiClientConfig: { baseURL: '/api' },
+ *       MapperClass: MyMapperClass,
+ *       ValidatorClass: MyValidatorClass,
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class BaseDomainService<TConfig extends CoreBaseDomainServiceConfig = CoreBaseDomainServiceConfig, TMapper extends CoreBaseMapperInstance<unknown, unknown> = CoreBaseMapperInstance<unknown, unknown>, TValidator extends CoreBaseValidatorInstance = CoreBaseValidatorInstance> {
+    /** Service name for logging and error messages */
+    readonly serviceName: string;
+    /** Supported runtimes for this service */
+    readonly supportedRuntimes: readonly CoreServiceRuntime[];
+    /** Service configuration */
+    protected readonly config: TConfig;
+    /** Logger instance */
+    protected readonly logger: PackageLogger;
+    /** Initialization state */
+    protected _initialized: boolean;
+    private _apiClient;
+    private _clientInitPromise;
+    private readonly _apiClientConfig?;
+    private readonly _setAsDefaultClient;
+    protected readonly cacheManager?: CacheManager;
+    protected readonly dbService?: DatabaseServiceInterface;
+    protected readonly apiService?: ApiClient;
+    protected readonly observabilityService?: ObservabilityAdapter;
+    /**
+     * Cache prefix for namespacing cache keys (e.g., 'example', 'user', 'product').
+     * Subclasses can override by defining as a property.
+     * If not overridden, defaults to serviceName.toLowerCase().
+     *
+     * @example
+     * ```typescript
+     * protected cachePrefix = 'my-service'; // Override default
+     * ```
+     */
+    protected cachePrefix: string;
+    private _mapperInstance;
+    private _validatorInstance;
+    private readonly _MapperClass?;
+    private readonly _ValidatorClass?;
+    /**
+     * Create a new domain service instance
+     *
+     * @param config - Base service configuration (passed via super({...}))
+     */
+    constructor(config: CoreBaseServiceConfig<TConfig, TMapper, TValidator>);
+    /**
+     * Check if the service is enabled
+     * Service is enabled by default unless explicitly disabled
+     */
+    get isServiceEnabled(): boolean;
+    /**
+     * Check if the service is initialized (API client ready)
+     */
+    get isInitialized(): boolean;
+    /**
+     * Check if mapper is available
+     */
+    get hasMapper(): boolean;
+    /**
+     * Check if validator is available
+     */
+    get hasValidator(): boolean;
+    /**
+     * Get the mapper instance (lazy initialization)
+     * @throws CorePackageError if MapperClass was not provided
+     */
+    get mapper(): TMapper;
+    /**
+     * Set the mapper instance
+     * Allows subclasses to override mapper initialization
+     */
+    set mapper(value: TMapper);
+    /**
+     * Get the validator instance (lazy initialization)
+     * @throws CorePackageError if ValidatorClass was not provided
+     */
+    get validator(): TValidator;
+    /**
+     * Set the validator instance
+     * Allows subclasses to override validator initialization
+     */
+    set validator(value: TValidator);
+    /**
+     * Get the API client (after initialization)
+     * @throws CorePackageError if API client was not configured or not initialized
+     */
+    get apiClient(): ApiClient;
+    /**
+     * Get the observability adapter (if injected)
+     * Returns undefined if observability is not enabled
+     */
+    get observability(): ObservabilityAdapter | undefined;
+    /**
+     * Check if observability is available
+     */
+    get hasObservability(): boolean;
+    /**
+     * Initialize API client asynchronously
+     * Called from constructor if apiClientConfig is provided
+     */
+    private initializeApiClient;
+    /**
+     * Ensure API client is initialized before use.
+     * Call this from methods that need the API client.
+     * Also called by ServiceRegistry.create() for services with async initialization.
+     */
+    ensureApiClientInitialized(): Promise<void>;
+    /**
+     * Get current configuration (immutable copy)
+     */
+    getConfig(): Readonly<TConfig>;
+    /**
+     * Get a default value
+     * @param key - The key to get the default for
+     */
+    getDefault<T = FeatureFlagValue>(key: string): T | undefined;
+    /**
+     * Set a default value (mutates config.defaults)
+     * @param key - The key to set the default for
+     * @param value - The default value
+     */
+    setDefault(key: string, value: FeatureFlagValue): void;
+    /**
+     * Set multiple default values
+     * @param defaults - Record of default values
+     */
+    setDefaults(defaults: Record<string, FeatureFlagValue>): void;
+    /**
+     * Assert that the service is available (configured and ready)
+     * @throws CorePackageError if not available
+     */
+    protected assertAvailable(): void;
+    /**
+     * Assert that the service is enabled
+     * @throws CorePackageError if disabled
+     */
+    protected assertEnabled(): void;
+    /**
+     * Assert that the service is ready (enabled AND available)
+     * @throws CorePackageError if not ready
+     */
+    protected assertReady(): void;
+    /**
+     * Check if service is available (configured and ready)
+     * Subclasses must implement this to check credentials, config, etc.
+     *
+     * @returns true if available
+     */
+    abstract isAvailable(): boolean;
+    /**
+     * Dispose/cleanup the service
+     * Subclasses must implement to release resources
+     */
+    abstract dispose(): void;
+    /**
+     * Log debug message with service context
+     */
+    protected logDebug(message: string, data?: Record<string, unknown>): void;
+    /**
+     * Log info message with service context
+     */
+    protected logInfo(message: string, data?: Record<string, unknown>): void;
+    /**
+     * Log warning message with service context
+     */
+    protected logWarn(message: string, data?: Record<string, unknown>): void;
+    /**
+     * Log error message with service context
+     */
+    protected logError(message: string, data?: Record<string, unknown>): void;
+    /**
+     * Record a metric (no-op if observability not available)
+     */
+    protected recordMetric(name: string, value: number, tags?: Record<string, string>): Promise<void>;
+    /**
+     * Increment a counter (no-op if observability not available)
+     */
+    protected incrementCounter(name: string, value?: number, tags?: Record<string, string>): Promise<void>;
+    /**
+     * Start a span for tracing (returns noop span if observability not available)
+     */
+    protected startSpan(name: string, attributes?: Record<string, string | number | boolean>): Span;
+    /**
+     * Execute a function within a traced span
+     */
+    protected withSpan<T>(name: string, fn: (span: Span) => Promise<T>, attributes?: Record<string, string | number | boolean>): Promise<T>;
+}
+//# sourceMappingURL=BaseDomainService.d.ts.map

package/dist/domain/base/BaseDomainService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseDomainService.d.ts","sourceRoot":"","sources":["../../../src/domain/base/BaseDomainService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAG9C,OAAO,KAAK,EACV,sBAAsB,EACtB,yBAAyB,EACzB,kBAAkB,EACnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,OAAO,EAAE,eAAe,EAAuB,MAAM,YAAY,CAAC;AAElE,OAAO,KAAK,EACV,2BAA2B,EAG3B,qBAAqB,EACtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,oBAAoB,EAAE,IAAI,EAAE,MAAM,4BAA4B,CAAC;AAM7E;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC;AAMpE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,8BAAsB,iBAAiB,CACrC,OAAO,SAAS,2BAA2B,GAAG,2BAA2B,EACzE,OAAO,SAAS,sBAAsB,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,sBAAsB,CAC/E,OAAO,EACP,OAAO,CACR,EACD,UAAU,SAAS,yBAAyB,GAAG,yBAAyB;IAMxE,kDAAkD;IAClD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,0CAA0C;IAC1C,QAAQ,CAAC,iBAAiB,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAE1D,4BAA4B;IAC5B,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAEnC,sBAAsB;IACtB,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAEzC,2BAA2B;IAC3B,SAAS,CAAC,YAAY,EAAE,OAAO,CAAS;IAGxC,OAAO,CAAC,UAAU,CAA0B;IAC5C,OAAO,CAAC,kBAAkB,CAA8B;IACxD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAmB;IACrD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAU;IAG9C,SAAS,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IAC/C,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,wBAAwB,CAAC;IACxD,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,CAAC;IAC1C,SAAS,CAAC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IAE/D;;;;;;;;;OASG;IACH,SAAS,CAAC,WAAW,EAAE,MAAM,CAAM;IAGnC,OAAO,CAAC,eAAe,CAAwB;IAC/C,OAAO,CAAC,kBAAkB,CAA2B;IACrD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAA2B;IACzD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAiC;IAMlE;;;;OAIG;gBAES,MAAM,EAAE,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,UAAU,CAAC;IA0DvE;;;OAGG;IACH,IAAI,gBAAgB,IAAI,OAAO,CAE9B;IAED;;OAEG;IACH,IAAI,aAAa,IAAI,OAAO,CAE3B;IAED;;OAEG;IACH,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED;;OAEG;IACH,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED;;;OAGG;IACH,IAAI,MAAM,IAAI,OAAO,CAWpB;IAED;;;OAGG;IACH,IAAI,MAAM,CAAC,KAAK,EAAE,OAAO,EAExB;IAED;;;OAGG;IACH,IAAI,SAAS,IAAI,UAAU,CAW1B;IAED;;;OAGG;IACH,IAAI,SAAS,CAAC,KAAK,EAAE,UAAU,EAE9B;IAED;;;OAGG;IACH,IAAI,SAAS,IAAI,SAAS,CAQzB;IAED;;;OAGG;IACH,IAAI,aAAa,IAAI,oBAAoB,GAAG,SAAS,CAEpD;IAED;;OAEG;IACH,IAAI,gBAAgB,IAAI,OAAO,CAE9B;IAMD;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IA8B3B;;;;OAIG;IACG,0BAA0B,IAAI,OAAO,CAAC,IAAI,CAAC;IAgBjD;;OAEG;IACH,SAAS,IAAI,QAAQ,CAAC,OAAO,CAAC;IAI9B;;;OAGG;IACH,UAAU,CAAC,CAAC,GAAG,gBAAgB,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAI5D;;;;OAIG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,IAAI;IAOtD;;;OAGG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAAG,IAAI;IAW7D;;;OAGG;IACH,SAAS,CAAC,eAAe,IAAI,IAAI;IASjC;;;OAGG;IACH,SAAS,CAAC,aAAa,IAAI,IAAI;IAS/B;;;OAGG;IACH,SAAS,CAAC,WAAW,IAAI,IAAI;IAS7B;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,IAAI,OAAO;IAE/B;;;OAGG;IACH,QAAQ,CAAC,OAAO,IAAI,IAAI;IAMxB;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAOzE;;OAEG;IACH,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAOxE;;OAEG;IACH,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAOxE;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAWzE;;OAEG;cACa,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC5B,OAAO,CAAC,IAAI,CAAC;IAQhB;;OAEG;cACa,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,KAAK,SAAI,EACT,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC5B,OAAO,CAAC,IAAI,CAAC;IAQhB;;OAEG;IACH,SAAS,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAAG,IAAI;IAsB/F;;OAEG;cACa,QAAQ,CAAC,CAAC,EACxB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,EAC9B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GACrD,OAAO,CAAC,CAAC,CAAC;CAiBd"}