@plyaz/types 1.23.0 → 1.23.2

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

@@ -94,6 +94,12 @@ export interface CoreBaseDomainServiceConfig {
     enabled?: boolean;
     /** Default values for feature flags or other defaults */
     defaults?: Record<string, FeatureFlagValue>;
+    /**
+     * Custom observability adapter to use instead of the injected global/dedicated one.
+     * Useful when a service needs a different provider or custom configuration.
+     * Takes precedence over injected observability.
+     */
+    observabilityOverride?: unknown;
 }
 /**
  * Type for mapper class constructor
@@ -126,7 +132,7 @@ export type CoreValidatorClass<T extends CoreBaseValidatorInstance = CoreBaseVal
  * interface BasicInjectedServices extends CoreInjectedServices {}
  * ```
  */
-export interface CoreInjectedServices<TCache = unknown, TDb = unknown, TApi = unknown, TStores = unknown> {
+export interface CoreInjectedServices<TCache = unknown, TDb = unknown, TApi = unknown, TStores = unknown, TObservability = unknown> {
     /** Cache manager instance */
     cache?: TCache;
     /** Database service instance */
@@ -139,6 +145,11 @@ export interface CoreInjectedServices<TCache = unknown, TDb = unknown, TApi = un
      * @example { example: ExampleStoreSlice, errors: ErrorStoreSlice }
      */
     stores?: TStores extends Record<string, unknown> ? Partial<TStores> : Record<string, TStores>;
+    /**
+     * Observability service instance for metrics, tracing, and logging.
+     * Supports adapter-based providers (Datadog, Grafana, OpenTelemetry, etc.)
+     */
+    observability?: TObservability;
 }
 /**
  * Base service configuration passed to constructor

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

@@ -2,4 +2,4 @@
  * Core Init Types
  * Service registry and initialization type definitions
  */
-export type { CoreDomainServiceInstance, CoreServiceInitConfig, CoreServiceCreateOptions, CoreInitializableDomainService, CoreServiceEntry, CoreServiceRegistryConfig, CoreExtractServiceConfig, CoreExtractServiceInstance, CoreFeatureFlagInitConfig, CoreErrorHandlerInitConfig, CoreCacheConfig, CoreInitOptionsBase, CoreServicesResultBase, } from './types';
+export type { CoreDomainServiceInstance, CoreServiceInitConfig, CoreServiceCreateOptions, CoreInitializableDomainService, CoreServiceEntry, CoreServiceRegistryConfig, CoreExtractServiceConfig, CoreExtractServiceInstance, CoreFeatureFlagInitConfig, CoreErrorHandlerInitConfig, CoreCacheConfig, CoreObservabilityConfig, CoreInitOptionsBase, CoreServicesResultBase, } from './types';

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

@@ -12,6 +12,7 @@ import type { RootStoreSlice } from '../../store';
 import type { CoreAppEnvironment, CoreAppContext, CoreRuntimeEnvironment, CoreServiceRuntime } from '../modules';
 import type { CoreDbServiceConfig } from '../services';
 import type { CoreInjectedServices } from '../domain';
+import type { MonitoringObservabilityAdapter, MonitoringAdapterWithPriority } from '../../observability';
 /**
  * Base interface that all domain service instances must implement.
  * This allows the registry to manage services generically.
@@ -213,6 +214,38 @@ export interface CoreServiceInitConfig {
         /** Default TTL in seconds for cached operations */
         defaultTtl?: number;
     };
+    /**
+     * Create a dedicated observability instance for this service.
+     *
+     * By default, services share the global observability adapter. Use this when
+     * a service needs its own isolated observability (e.g., different provider,
+     * custom tags, separate sampling).
+     *
+     * - `false` or `undefined`: Use global shared observability (default)
+     * - `true`: Create dedicated instance using global config
+     * - `ObservabilityAdapterConfig`: Create dedicated instance with custom config
+     *
+     * @example
+     * ```typescript
+     * // Use global shared observability (default)
+     * { service: UserService, config: { enabled: true } }
+     *
+     * // Create dedicated observability with global config
+     * { service: PaymentService, config: { dedicatedObservability: true } }
+     *
+     * // Create dedicated observability with custom config
+     * {
+     *   service: CriticalService,
+     *   config: {
+     *     dedicatedObservability: {
+     *       serviceName: 'critical-service',
+     *       samplingRate: 1.0, // 100% sampling for critical operations
+     *     },
+     *   },
+     * }
+     * ```
+     */
+    dedicatedObservability?: boolean | CoreObservabilityConfig;
 }
 /**
  * Options passed to the service factory method
@@ -304,6 +337,27 @@ export interface CoreServiceCreateOptions<TConfig = unknown, TMapper = unknown,
          */
         instance?: unknown;
     };
+    /**
+     * Observability configuration and mode.
+     */
+    observability?: {
+        /**
+         * Whether to use a dedicated (isolated) observability instance.
+         * - `false`: Use global shared instance (default)
+         * - `true`: Create dedicated instance
+         */
+        dedicated: boolean;
+        /**
+         * Observability config (merged global + per-service config).
+         * Used to create dedicated instance or configure global.
+         */
+        config?: CoreObservabilityConfig;
+        /**
+         * Actual ObservabilityAdapter instance to use.
+         * Injected by ServiceRegistry, not created by service.
+         */
+        instance?: unknown;
+    };
     /** Logger prefix */
     loggerPrefix?: string;
     /** Whether this is a singleton instance */
@@ -387,6 +441,8 @@ export interface CoreServiceRegistryConfig {
     db?: Partial<CoreDbServiceConfig>;
     /** Global cache config (shared by all services unless overridden) */
     cache?: CoreCacheConfig;
+    /** Global observability config (shared by all services unless overridden) */
+    observability?: CoreObservabilityConfig;
     /**
      * Store registry interface for injecting stores into services.
      * Provides type-safe store access via store keys.
@@ -519,6 +575,76 @@ export interface CoreCacheConfig {
         keyPrefix?: string;
     };
 }
+/**
+ * Observability initialization configuration
+ */
+export interface CoreObservabilityConfig {
+    /** Enable/disable observability (default: true) */
+    enabled?: boolean;
+    /** Service name for tagging */
+    serviceName?: string;
+    /** Environment (production, staging, development) */
+    environment?: string;
+    /** Default tags to add to all metrics/spans */
+    defaultTags?: Record<string, string>;
+    /** Sampling rate for traces (0.0 to 1.0) */
+    samplingRate?: number;
+    /** Flush interval in milliseconds */
+    flushInterval?: number;
+    /** Buffer size before auto-flush */
+    bufferSize?: number;
+    /**
+     * Provider type
+     * Currently supported: 'datadog', 'console', 'noop'
+     * Planned: 'grafana', 'opentelemetry', 'prometheus', 'newrelic', 'custom'
+     */
+    provider?: 'datadog' | 'console' | 'noop';
+    /** Mode for multi-provider: 'parallel' sends to all, 'priority' falls back on error */
+    mode?: 'single' | 'parallel' | 'priority';
+    /** Datadog-specific configuration */
+    datadog?: {
+        /** Datadog API key */
+        apiKey?: string;
+        /** Datadog site (e.g., 'datadoghq.com', 'datadoghq.eu') */
+        site?: string;
+        /** Enable APM tracing */
+        apmEnabled?: boolean;
+        /** Enable RUM */
+        rumEnabled?: boolean;
+        /** RUM application ID */
+        rumApplicationId?: string;
+        /** RUM client token */
+        rumClientToken?: string;
+    };
+    /** Grafana-specific configuration */
+    grafana?: {
+        /** Push gateway URL (for Prometheus) */
+        pushGatewayUrl?: string;
+        /** Grafana Cloud user */
+        grafanaCloudUser?: string;
+        /** Grafana Cloud API key */
+        grafanaCloudApiKey?: string;
+        /** Loki endpoint for logs */
+        lokiEndpoint?: string;
+        /** Tempo endpoint for traces */
+        tempoEndpoint?: string;
+    };
+    /** OpenTelemetry-specific configuration */
+    opentelemetry?: {
+        /** OTLP endpoint URL */
+        endpoint?: string;
+        /** Headers for OTLP exporter */
+        headers?: Record<string, string>;
+        /** Export interval in milliseconds */
+        exportInterval?: number;
+    };
+    /**
+     * Pre-initialized adapters for observability.
+     * Can be plain adapters or adapters with priority/failover config.
+     * LoggerAdapter is auto-added as failover if not included.
+     */
+    adapters?: (MonitoringObservabilityAdapter | MonitoringAdapterWithPriority)[];
+}
 /**
  * Base core initialization options
  * Extended by @plyaz/core's CoreInitOptions with specific types
@@ -538,12 +664,16 @@ export interface CoreInitOptionsBase<TDb = unknown, TApi = unknown> {
     api?: TApi;
     /** Cache configuration */
     cache?: CoreCacheConfig;
+    /** Observability configuration */
+    observability?: CoreObservabilityConfig;
     /** Skip database initialization */
     skipDb?: boolean;
     /** Skip API client initialization */
     skipApi?: boolean;
     /** Skip cache initialization */
     skipCache?: boolean;
+    /** Skip observability initialization */
+    skipObservability?: boolean;
     /** Enable verbose logging */
     verbose?: boolean;
     /** Error handler configuration */
@@ -556,13 +686,15 @@ export interface CoreInitOptionsBase<TDb = unknown, TApi = unknown> {
 /**
  * Core services result from initialization
  */
-export interface CoreServicesResultBase<TDb = unknown, TApi = unknown, TCache = unknown> {
+export interface CoreServicesResultBase<TDb = unknown, TApi = unknown, TCache = unknown, TObservability = 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;
+    /** Observability adapter instance (null if skipped) */
+    observability: TObservability | null;
     /** Loaded environment variables */
     env: Record<string, string | undefined>;
     /** Detected runtime environment */

package/dist/index.cjs

@@ -7306,6 +7306,46 @@ var CORRELATION_TYPE = /* @__PURE__ */ ((CORRELATION_TYPE2) => {
   return CORRELATION_TYPE2;
 })(CORRELATION_TYPE || {});
 
+// src/observability/types.ts
+var OBSERVABILITY_METRICS = {
+  // Service metrics
+  SERVICE_OPERATION_DURATION: "service.operation.duration",
+  SERVICE_OPERATION_COUNT: "service.operation.count",
+  SERVICE_OPERATION_ERROR: "service.operation.error",
+  // Database metrics
+  DB_QUERY_DURATION: "db.query.duration",
+  DB_QUERY_COUNT: "db.query.count",
+  DB_CONNECTION_POOL_SIZE: "db.connection.pool.size",
+  DB_CONNECTION_POOL_USED: "db.connection.pool.used",
+  // Cache metrics
+  CACHE_HIT: "cache.hit",
+  CACHE_MISS: "cache.miss",
+  CACHE_SET: "cache.set",
+  CACHE_DELETE: "cache.delete",
+  // API metrics
+  API_REQUEST_DURATION: "api.request.duration",
+  API_REQUEST_COUNT: "api.request.count",
+  API_REQUEST_ERROR: "api.request.error",
+  // Transaction metrics
+  TRANSACTION_DURATION: "transaction.duration",
+  TRANSACTION_COUNT: "transaction.count",
+  TRANSACTION_ROLLBACK: "transaction.rollback"
+};
+var OBSERVABILITY_SPANS = {
+  SERVICE_CREATE: "service.create",
+  SERVICE_UPDATE: "service.update",
+  SERVICE_DELETE: "service.delete",
+  SERVICE_GET: "service.get",
+  SERVICE_LIST: "service.list",
+  SERVICE_BULK_CREATE: "service.bulk_create",
+  SERVICE_BULK_DELETE: "service.bulk_delete",
+  SERVICE_TRANSACTION: "service.transaction",
+  DB_QUERY: "db.query",
+  CACHE_GET: "cache.get",
+  CACHE_SET: "cache.set",
+  API_REQUEST: "api.request"
+};
+
 // src/api/events/enum.ts
 var EVENT_NAMESPACES = {
   HEADERS: "headers",
@@ -8656,6 +8696,8 @@ exports.NOTIFICATION_ERROR_CODES = NOTIFICATION_ERROR_CODES;
 exports.NOTIFICATION_PROVIDERS = NOTIFICATION_PROVIDERS;
 exports.NetworkPresetNames = NetworkPresetNames;
 exports.NotificationCategorySchema = NotificationCategorySchema;
+exports.OBSERVABILITY_METRICS = OBSERVABILITY_METRICS;
+exports.OBSERVABILITY_SPANS = OBSERVABILITY_SPANS;
 exports.OPERATIONS = COMMON_OPERATIONS;
 exports.ORGANIZATION_TIER = ORGANIZATION_TIER;
 exports.OUTPUT_FORMAT = OUTPUT_FORMAT;