@plyaz/types 1.22.9 → 1.23.1

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

@@ -126,7 +126,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 +139,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
@@ -180,3 +185,188 @@ export interface CoreBaseBackendServiceConfig extends CoreBaseDomainServiceConfi
         defaultTtl?: number;
     };
 }
+/**
+ * Base interface for service type bundles.
+ * Define your concrete types by implementing this interface.
+ *
+ * This reduces the number of generic parameters from 13 to 5:
+ * - TConfig (service config)
+ * - TTypes (this bundle)
+ * - TRepository
+ * - TMapper
+ * - TValidator
+ *
+ * @example
+ * ```typescript
+ * // Define your service types bundle (no extends needed!)
+ * interface UserServiceTypes {
+ *   Entity: User;
+ *   ResponseDTO: UserResponseDTO;
+ *   CreateDTO: CreateUserDTO;
+ *   UpdateDTO: UpdateUserDTO;
+ *   PatchDTO: PatchUserDTO;
+ *   QueryDTO: QueryUserDTO;
+ *   DeleteOptions: { soft: boolean };
+ *   DatabaseRow: UserDatabaseRow;
+ *   StoreState: UserStoreItem;
+ * }
+ *
+ * // Use in service (5 generics instead of 13!)
+ * class UserService extends BaseBackendDomainServiceV2<
+ *   UserServiceConfig,
+ *   UserServiceTypes,
+ *   UserRepository,
+ *   UserMapper,
+ *   UserValidator
+ * > {}
+ * ```
+ */
+export interface BackendServiceTypesShape {
+    /** Domain entity type */
+    Entity: unknown;
+    /** API response DTO type */
+    ResponseDTO: unknown;
+    /** Create input DTO type (POST body) - must be Record<string, unknown> */
+    CreateDTO: Record<string, unknown>;
+    /** Update input DTO type (PUT body) - must be Record<string, unknown> */
+    UpdateDTO: Record<string, unknown>;
+    /** Patch input DTO type (PATCH body) */
+    PatchDTO: Partial<Record<string, unknown>>;
+    /** Query params DTO type */
+    QueryDTO: Record<string, unknown>;
+    /** Delete options type */
+    DeleteOptions: unknown;
+    /** Database row type - must be Record<string, unknown> */
+    DatabaseRow: Record<string, unknown>;
+    /** Store state type (serializable) */
+    StoreState: unknown;
+}
+/**
+ * Frontend service types shape (without database-specific types)
+ */
+export interface FrontendServiceTypesShape {
+    /** Domain entity type */
+    Entity: unknown;
+    /** API response DTO type */
+    ResponseDTO: unknown;
+    /** Create input DTO type */
+    CreateDTO: unknown;
+    /** Update input DTO type */
+    UpdateDTO: unknown;
+    /** Patch input DTO type */
+    PatchDTO: unknown;
+    /** Query params DTO type */
+    QueryDTO: unknown;
+    /** Store state type */
+    StoreState: unknown;
+}
+/**
+ * Helper to create a backend service types bundle with defaults.
+ * Use this when you want type inference with sensible defaults.
+ *
+ * @example
+ * ```typescript
+ * type UserTypes = DefineBackendServiceTypes<{
+ *   Entity: User;
+ *   ResponseDTO: UserResponseDTO;
+ *   CreateDTO: CreateUserDTO;
+ *   // UpdateDTO defaults to CreateDTO
+ *   // PatchDTO defaults to Partial<CreateDTO>
+ *   QueryDTO: QueryUserDTO;
+ *   DatabaseRow: UserDatabaseRow;
+ * }>;
+ * ```
+ */
+export type DefineBackendServiceTypes<T extends Partial<BackendServiceTypesShape> & {
+    Entity: unknown;
+    CreateDTO: Record<string, unknown>;
+}> = {
+    Entity: T['Entity'];
+    ResponseDTO: T extends {
+        ResponseDTO: infer R;
+    } ? R : T['Entity'];
+    CreateDTO: T['CreateDTO'];
+    UpdateDTO: T extends {
+        UpdateDTO: infer U;
+    } ? U : T['CreateDTO'];
+    PatchDTO: T extends {
+        PatchDTO: infer P;
+    } ? P : Partial<T['CreateDTO']>;
+    QueryDTO: T extends {
+        QueryDTO: infer Q;
+    } ? Q : Record<string, unknown>;
+    DeleteOptions: T extends {
+        DeleteOptions: infer D;
+    } ? D : {
+        soft: boolean;
+    };
+    DatabaseRow: T extends {
+        DatabaseRow: infer DB;
+    } ? DB : T['CreateDTO'] & {
+        id: string;
+    };
+    StoreState: T extends {
+        StoreState: infer S;
+    } ? S : T['Entity'];
+};
+/**
+ * Helper to create a frontend service types bundle with defaults.
+ */
+export type DefineFrontendServiceTypes<T extends Partial<FrontendServiceTypesShape> & {
+    Entity: unknown;
+}> = {
+    Entity: T['Entity'];
+    ResponseDTO: T extends {
+        ResponseDTO: infer R;
+    } ? R : T['Entity'];
+    CreateDTO: T extends {
+        CreateDTO: infer C;
+    } ? C : Record<string, unknown>;
+    UpdateDTO: T extends {
+        UpdateDTO: infer U;
+    } ? U : T extends {
+        CreateDTO: infer C;
+    } ? C : Record<string, unknown>;
+    PatchDTO: T extends {
+        PatchDTO: infer P;
+    } ? P : Partial<T extends {
+        CreateDTO: infer C;
+    } ? C : Record<string, unknown>>;
+    QueryDTO: T extends {
+        QueryDTO: infer Q;
+    } ? Q : Record<string, unknown>;
+    StoreState: T extends {
+        StoreState: infer S;
+    } ? S : T['Entity'];
+};
+/**
+ * Type-safe extraction helpers for service type bundles.
+ * These work with any object that has the expected shape.
+ */
+export type ExtractEntity<T extends {
+    Entity: unknown;
+}> = T['Entity'];
+export type ExtractResponseDTO<T extends {
+    ResponseDTO: unknown;
+}> = T['ResponseDTO'];
+export type ExtractCreateDTO<T extends {
+    CreateDTO: unknown;
+}> = T['CreateDTO'];
+export type ExtractUpdateDTO<T extends {
+    UpdateDTO: unknown;
+}> = T['UpdateDTO'];
+export type ExtractPatchDTO<T extends {
+    PatchDTO: unknown;
+}> = T['PatchDTO'];
+export type ExtractQueryDTO<T extends {
+    QueryDTO: unknown;
+}> = T['QueryDTO'];
+export type ExtractDeleteOptions<T extends {
+    DeleteOptions: unknown;
+}> = T['DeleteOptions'];
+export type ExtractDatabaseRow<T extends {
+    DatabaseRow: unknown;
+}> = T['DatabaseRow'];
+export type ExtractStoreState<T extends {
+    StoreState: unknown;
+}> = T['StoreState'];

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

@@ -2,5 +2,5 @@
  * Core Frontend Types
  * Type definitions for @plyaz/core frontend services
  */
-export type { CoreBaseFrontendStore, CoreBaseFrontendServiceConfig, CoreBaseFrontendServiceInterface, CoreStoreHandlers, CoreFetcherFunction, CoreServiceFetchers, CorePlyazApiConfig, FrontendFeatureFlagProvider, CorePlyazFeatureFlagConfig, CorePlyazStoreConfig, CorePlyazConfig, CoreFeatureFlagServiceLike, CoreFeatureFlagFetcherOptions, CoreFeatureFlagStoreInitConfig, CoreBaseFrontendServiceConstructorConfig, CoreInitializationErrorProps, CoreInitializationLoadingProps, CorePlyazServices, CorePlyazContextValue, CorePlyazProviderProps, } from './types';
+export type { CoreBaseFrontendStore, CoreBaseFrontendServiceConfig, CoreBaseFrontendServiceInterface, CoreStoreHandlers, CoreOptimisticUpdateConfig, OptimisticConflictResolution, CoreFetcherFunction, CoreServiceFetchers, CorePlyazApiConfig, FrontendFeatureFlagProvider, CorePlyazFeatureFlagConfig, CorePlyazStoreConfig, CorePlyazConfig, CoreFeatureFlagServiceLike, CoreFeatureFlagFetcherOptions, CoreFeatureFlagStoreInitConfig, CoreBaseFrontendServiceConstructorConfig, CoreInitializationErrorProps, CoreInitializationLoadingProps, CorePlyazServices, CorePlyazContextValue, CorePlyazProviderProps, } from './types';
 export type { CoreFrontendFeatureFlagEventType, CoreFeatureFlagStore, CoreFeatureFlagServiceConfig, CoreFeatureFlagServiceInitConfig, CoreFeatureFlagServiceInterface, } from './featureFlags';

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

@@ -638,6 +638,68 @@ export interface CoreStoreHandlers<TData = Record<string, unknown>, TStore exten
      */
     removeData?: (store: TStore, id: string) => void;
 }
+/**
+ * Conflict resolution strategy for optimistic updates
+ */
+export type OptimisticConflictResolution = 'server-wins' | 'client-wins' | 'merge' | 'manual';
+/**
+ * Optimistic update configuration
+ *
+ * When enabled, store updates happen immediately before API call completes.
+ * If the API call fails, changes are rolled back automatically.
+ *
+ * @example
+ * ```typescript
+ * optimisticUpdates: {
+ *   enabled: true,
+ *   rollbackOnError: true,
+ *   conflictResolution: 'server-wins',
+ * }
+ * ```
+ */
+export interface CoreOptimisticUpdateConfig {
+    /**
+     * Enable optimistic updates for CRUD operations.
+     * When true, store is updated before API response.
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Automatically rollback on API error.
+     * When true, reverts store to previous state if API fails.
+     * @default true
+     */
+    rollbackOnError?: boolean;
+    /**
+     * How to resolve conflicts when server response differs from optimistic state.
+     * - 'server-wins': Always use server response (default, safest)
+     * - 'client-wins': Keep client changes, ignore server differences
+     * - 'merge': Deep merge server and client data
+     * - 'manual': Call onConflict handler for resolution
+     * @default 'server-wins'
+     */
+    conflictResolution?: OptimisticConflictResolution;
+    /**
+     * Delay before applying optimistic update (ms).
+     * Useful for debouncing rapid updates.
+     * @default 0
+     */
+    debounceMs?: number;
+    /**
+     * Operations to enable optimistic updates for.
+     * @default ['create', 'update', 'delete']
+     */
+    operations?: ('create' | 'update' | 'delete')[];
+    /**
+     * Called when conflict detected (only when conflictResolution is 'manual').
+     * Return the resolved data to use.
+     */
+    onConflict?: <T>(optimistic: T, server: T) => T;
+    /**
+     * Called when rollback occurs due to error.
+     */
+    onRollback?: (operation: string, error: Error, previousState: unknown) => void;
+}
 /**
  * Configuration for frontend domain services
  */
@@ -684,6 +746,24 @@ export interface CoreBaseFrontendServiceConfig<TData = Record<string, unknown>,
      * ```
      */
     storeHandlers?: CoreStoreHandlers<TData, TStore>;
+    /**
+     * Optimistic update configuration.
+     *
+     * When enabled, store updates happen immediately before API completes.
+     * If API fails, changes are automatically rolled back.
+     *
+     * @see {@link CoreOptimisticUpdateConfig} for options
+     *
+     * @example
+     * ```typescript
+     * optimisticUpdates: {
+     *   enabled: true,
+     *   rollbackOnError: true,
+     *   conflictResolution: 'server-wins',
+     * }
+     * ```
+     */
+    optimisticUpdates?: CoreOptimisticUpdateConfig;
 }
 /**
  * Base interface for frontend domain services with store integration.

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

@@ -213,6 +213,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 +336,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 +440,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 +574,70 @@ 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;
+    };
+}
 /**
  * Base core initialization options
  * Extended by @plyaz/core's CoreInitOptions with specific types
@@ -538,12 +657,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 +679,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;