@plyaz/types 1.23.0 → 1.23.2

package/dist/observability/types.d.ts

@@ -0,0 +1,548 @@
+/**
+ * Monitoring/Observability Types
+ *
+ * Adapter-based observability system supporting multiple providers
+ * (Datadog, Grafana, OpenTelemetry, etc.) with parallel and priority modes.
+ *
+ * All types are prefixed with "Monitoring" for this dedicated module.
+ *
+ * @module observability/types
+ */
+/**
+ * Supported observability providers
+ * Currently implemented: 'datadog', 'console', 'noop'
+ * Planned: 'grafana', 'opentelemetry', 'prometheus', 'newrelic', 'custom'
+ */
+export type MonitoringObservabilityProvider = 'datadog' | 'console' | 'noop' | 'custom';
+/**
+ * Metric types
+ */
+export type MonitoringMetricType = 'counter' | 'gauge' | 'histogram' | 'summary';
+/**
+ * Span status for tracing
+ */
+export type MonitoringSpanStatus = 'ok' | 'error' | 'unset';
+/**
+ * Log levels
+ */
+export type MonitoringLogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+/**
+ * Base metric options
+ */
+export interface MonitoringMetricOptions {
+    /** Metric name (e.g., 'http.request.duration') */
+    name: string;
+    /** Human-readable description */
+    description?: string;
+    /** Unit of measurement (e.g., 'ms', 'bytes', 'count') */
+    unit?: string;
+    /** Tags/labels for the metric */
+    tags?: Record<string, string | number | boolean>;
+}
+/**
+ * Counter metric (monotonically increasing)
+ */
+export interface MonitoringCounterMetric extends MonitoringMetricOptions {
+    type: 'counter';
+    /** Value to increment by (default: 1) */
+    value?: number;
+}
+/**
+ * Gauge metric (can go up or down)
+ */
+export interface MonitoringGaugeMetric extends MonitoringMetricOptions {
+    type: 'gauge';
+    /** Current value */
+    value: number;
+}
+/**
+ * Histogram metric (distribution of values)
+ */
+export interface MonitoringHistogramMetric extends MonitoringMetricOptions {
+    type: 'histogram';
+    /** Value to record */
+    value: number;
+    /** Bucket boundaries (optional) */
+    buckets?: number[];
+}
+/**
+ * Summary metric (percentiles)
+ */
+export interface MonitoringSummaryMetric extends MonitoringMetricOptions {
+    type: 'summary';
+    /** Value to record */
+    value: number;
+    /** Percentiles to track (e.g., [0.5, 0.9, 0.99]) */
+    percentiles?: number[];
+}
+/**
+ * Union of all metric types
+ */
+export type MonitoringMetric = MonitoringCounterMetric | MonitoringGaugeMetric | MonitoringHistogramMetric | MonitoringSummaryMetric;
+/**
+ * Span context for distributed tracing
+ */
+export interface MonitoringSpanContext {
+    /** Unique trace ID */
+    traceId: string;
+    /** Unique span ID */
+    spanId: string;
+    /** Parent span ID (if any) */
+    parentSpanId?: string;
+    /** Sampling decision */
+    sampled?: boolean;
+}
+/**
+ * Span attributes following OpenTelemetry semantic conventions.
+ * Property names use dot notation as per OTel spec (e.g., 'service.name').
+ */
+export interface MonitoringSpanAttributes {
+    /** Service name */
+    'service.name'?: string;
+    /** Operation name */
+    'operation.name'?: string;
+    /** HTTP method */
+    'http.method'?: string;
+    /** HTTP URL */
+    'http.url'?: string;
+    /** HTTP status code */
+    'http.status_code'?: number;
+    /** Database system */
+    'db.system'?: string;
+    /** Database statement */
+    'db.statement'?: string;
+    /** Error flag */
+    error?: boolean;
+    /** Error message */
+    'error.message'?: string;
+    /** Custom attributes */
+    [key: string]: string | number | boolean | undefined;
+}
+/**
+ * Span event (point-in-time occurrence within a span)
+ */
+export interface MonitoringSpanEvent {
+    /** Event name */
+    name: string;
+    /** Event timestamp */
+    timestamp?: number;
+    /** Event attributes */
+    attributes?: Record<string, string | number | boolean>;
+}
+/**
+ * Options for creating a span
+ */
+export interface MonitoringSpanOptions {
+    /** Span name (operation being traced) */
+    name: string;
+    /** Span kind */
+    kind?: 'internal' | 'server' | 'client' | 'producer' | 'consumer';
+    /** Initial attributes */
+    attributes?: MonitoringSpanAttributes;
+    /** Parent span context (for distributed tracing) */
+    parentContext?: MonitoringSpanContext;
+    /** Start time (default: now) */
+    startTime?: number;
+}
+/**
+ * Active span interface
+ */
+export interface MonitoringSpan {
+    /** Span context */
+    context: MonitoringSpanContext;
+    /** Set attribute on span */
+    setAttribute(key: string, value: string | number | boolean): void;
+    /** Set multiple attributes */
+    setAttributes(attributes: MonitoringSpanAttributes): void;
+    /** Add event to span */
+    addEvent(event: MonitoringSpanEvent): void;
+    /** Set span status */
+    setStatus(status: MonitoringSpanStatus, message?: string): void;
+    /** End the span */
+    end(endTime?: number): void;
+    /** Record exception */
+    recordException(error: Error): void;
+}
+/**
+ * Structured log entry
+ */
+export interface MonitoringLogEntry {
+    /** Log level */
+    level: MonitoringLogLevel;
+    /** Log message */
+    message: string;
+    /** Timestamp */
+    timestamp?: number;
+    /** Service/component name */
+    service?: string;
+    /** Additional context */
+    context?: Record<string, unknown>;
+    /** Associated trace ID */
+    traceId?: string;
+    /** Associated span ID */
+    spanId?: string;
+    /** Error object (if logging an error) */
+    error?: Error;
+}
+/**
+ * Custom event for observability
+ */
+export interface MonitoringObservabilityEvent {
+    /** Event name */
+    name: string;
+    /** Event timestamp */
+    timestamp?: number;
+    /** Event properties */
+    properties?: Record<string, unknown>;
+    /** Associated tags */
+    tags?: Record<string, string>;
+}
+/**
+ * Base observability adapter interface.
+ *
+ * All observability providers (Datadog, Grafana, OpenTelemetry, etc.)
+ * must implement this interface.
+ *
+ * @example
+ * ```typescript
+ * class DatadogAdapter implements ObservabilityAdapter {
+ *   readonly provider = 'datadog';
+ *   readonly name = 'DatadogAdapter';
+ *
+ *   async initialize(config: DatadogConfig): Promise<void> {
+ *     // Initialize Datadog client
+ *   }
+ *
+ *   async recordMetric(metric: Metric): Promise<void> {
+ *     // Send to Datadog
+ *   }
+ *
+ *   // ... other methods
+ * }
+ * ```
+ */
+export interface MonitoringObservabilityAdapter {
+    /** Provider type */
+    readonly provider: MonitoringObservabilityProvider;
+    /** Adapter name for logging */
+    readonly name: string;
+    /** Whether the adapter is initialized */
+    readonly isInitialized: boolean;
+    /**
+     * Initialize the adapter with provider-specific config
+     */
+    initialize(config: MonitoringObservabilityAdapterConfig): Promise<void>;
+    /**
+     * Shutdown/cleanup the adapter
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Check if adapter is healthy/connected
+     */
+    isHealthy(): Promise<boolean>;
+    /**
+     * Record a metric
+     */
+    recordMetric(metric: MonitoringMetric): Promise<void>;
+    /**
+     * Increment a counter
+     */
+    incrementCounter(name: string, value?: number, tags?: Record<string, string>): Promise<void>;
+    /**
+     * Set a gauge value
+     */
+    setGauge(name: string, value: number, tags?: Record<string, string>): Promise<void>;
+    /**
+     * Record a histogram value
+     */
+    recordHistogram(name: string, value: number, tags?: Record<string, string>): Promise<void>;
+    /**
+     * Start a new span
+     */
+    startSpan(options: MonitoringSpanOptions): MonitoringSpan;
+    /**
+     * Get current active span (if any)
+     */
+    getActiveSpan(): MonitoringSpan | null;
+    /**
+     * Run a function within a span
+     */
+    withSpan<T>(options: MonitoringSpanOptions, fn: (span: MonitoringSpan) => Promise<T>): Promise<T>;
+    /**
+     * Send a log entry
+     */
+    log(entry: MonitoringLogEntry): Promise<void>;
+    /**
+     * Send a custom event
+     */
+    sendEvent(event: MonitoringObservabilityEvent): Promise<void>;
+    /**
+     * Flush any buffered data
+     */
+    flush(): Promise<void>;
+}
+/**
+ * Base adapter configuration
+ */
+export interface MonitoringObservabilityAdapterConfig {
+    /** Enable/disable the adapter */
+    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;
+}
+/**
+ * Datadog-specific configuration
+ */
+export interface MonitoringDatadogAdapterConfig extends MonitoringObservabilityAdapterConfig {
+    /** Datadog API key */
+    apiKey: string;
+    /** Datadog site (e.g., 'datadoghq.com', 'datadoghq.eu') */
+    site?: string;
+    /** Enable APM tracing */
+    apmEnabled?: boolean;
+    /** Enable RUM (Real User Monitoring) */
+    rumEnabled?: boolean;
+    /** RUM application ID */
+    rumApplicationId?: string;
+    /** RUM client token */
+    rumClientToken?: string;
+}
+/**
+ * OpenTelemetry-specific configuration
+ */
+export interface MonitoringOpenTelemetryAdapterConfig extends MonitoringObservabilityAdapterConfig {
+    /** OTLP endpoint URL */
+    endpoint: string;
+    /** Headers for OTLP exporter */
+    headers?: Record<string, string>;
+    /** Export interval in milliseconds */
+    exportInterval?: number;
+    /** Resource attributes */
+    resourceAttributes?: Record<string, string>;
+}
+/**
+ * Grafana/Prometheus-specific configuration
+ */
+export interface MonitoringGrafanaAdapterConfig extends MonitoringObservabilityAdapterConfig {
+    /** 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;
+}
+/**
+ * Console adapter configuration (for development)
+ */
+export interface MonitoringConsoleAdapterConfig extends MonitoringObservabilityAdapterConfig {
+    /** Pretty print output */
+    prettyPrint?: boolean;
+    /** Include timestamps */
+    includeTimestamps?: boolean;
+    /** Log level filter */
+    logLevel?: MonitoringLogLevel;
+}
+/**
+ * Mode for composite adapter
+ */
+export type MonitoringCompositeMode = 'parallel' | 'priority';
+/**
+ * Configuration for composite adapter
+ */
+export interface MonitoringCompositeAdapterConfig extends MonitoringObservabilityAdapterConfig {
+    /** Execution mode */
+    mode: MonitoringCompositeMode;
+    /**
+     * Child adapters to use.
+     * For 'parallel': all adapters receive data simultaneously
+     * For 'priority': try first adapter, fallback to next on failure
+     */
+    adapters: MonitoringObservabilityAdapter[];
+    /**
+     * For 'priority' mode: continue to next adapter on these error types
+     * Default: all errors trigger fallback
+     */
+    fallbackOnErrors?: string[];
+    /**
+     * For 'parallel' mode: fail if any adapter fails (default: false)
+     * If false, logs errors but continues
+     */
+    failOnAnyError?: boolean;
+    /**
+     * Timeout for each adapter operation in ms (default: 5000)
+     */
+    adapterTimeout?: number;
+}
+/**
+ * Operation context for service hooks
+ */
+export interface MonitoringOperationContext {
+    /** Service name */
+    serviceName: string;
+    /** Operation name (e.g., 'create', 'update', 'delete') */
+    operation: string;
+    /** Entity type (e.g., 'user', 'topic') */
+    entityType?: string;
+    /** Entity ID (if applicable) */
+    entityId?: string;
+    /** Start timestamp */
+    startTime: number;
+    /** Custom attributes */
+    attributes?: Record<string, unknown>;
+    /** Parent trace context */
+    parentContext?: MonitoringSpanContext;
+}
+/**
+ * Operation result for service hooks
+ */
+export interface MonitoringOperationResult {
+    /** Whether operation succeeded */
+    success: boolean;
+    /** Duration in milliseconds */
+    duration: number;
+    /** Error (if failed) */
+    error?: Error;
+    /** Result data (optional) */
+    data?: unknown;
+}
+/**
+ * Adapter with priority and failover configuration.
+ * Higher priority = tried first in priority mode, executed first in parallel mode.
+ */
+export interface MonitoringAdapterWithPriority {
+    /** The adapter instance (should be pre-initialized) */
+    adapter: MonitoringObservabilityAdapter;
+    /**
+     * Priority level (higher = more important)
+     * - In priority mode: higher priority adapters are tried first
+     * - In parallel mode: higher priority adapters are executed first
+     * Default: 0
+     */
+    priority?: number;
+    /**
+     * Mark this adapter as a failover/fallback adapter.
+     * - In parallel mode: failover adapters only receive data if primary adapters fail
+     * - In priority mode: failover adapters are only tried after all primary adapters fail
+     * Default: false
+     */
+    failover?: boolean;
+}
+/**
+ * Internal adapter entry with resolved metadata.
+ * Used by ObservabilityService to track adapter configuration.
+ */
+export interface MonitoringAdapterEntry {
+    /** The adapter instance */
+    adapter: MonitoringObservabilityAdapter;
+    /** Resolved priority level */
+    priority: number;
+    /** Whether this is a failover adapter */
+    failover: boolean;
+}
+/**
+ * Configuration for ObservabilityService.
+ *
+ * Note: Adapter-specific configs (apiKey, endpoints, etc.) are NOT here.
+ * Each adapter is initialized separately with its own config before being passed here.
+ */
+export interface MonitoringObservabilityServiceConfig {
+    /**
+     * Execution mode
+     * - 'single': Use only one adapter (default)
+     * - 'parallel': Send to all adapters simultaneously
+     * - 'priority': Try adapters in order, use first successful
+     */
+    mode?: 'single' | 'parallel' | 'priority';
+    /**
+     * Single adapter (for 'single' mode).
+     * Should be pre-initialized.
+     */
+    adapter?: MonitoringObservabilityAdapter | MonitoringAdapterWithPriority;
+    /**
+     * Multiple adapters (for 'parallel' or 'priority' mode).
+     * Can be plain adapters or adapters with priority config.
+     * Should be pre-initialized.
+     */
+    adapters?: (MonitoringObservabilityAdapter | MonitoringAdapterWithPriority)[];
+    /** Timeout for adapter operations in ms (default: 5000) */
+    adapterTimeout?: number;
+    /** For parallel mode: fail if any adapter fails (default: false) */
+    failOnAnyError?: boolean;
+    /** For priority mode: error types that trigger fallback (default: all) */
+    fallbackOnErrors?: string[];
+}
+/**
+ * Interface for ObservabilityService (for dependency injection typing)
+ */
+export interface MonitoringObservabilityServiceInterface {
+    readonly isReady: boolean;
+    incrementCounter(name: string, value?: number, tags?: Record<string, string>): Promise<void>;
+    setGauge(name: string, value: number, tags?: Record<string, string>): Promise<void>;
+    recordHistogram(name: string, value: number, tags?: Record<string, string>): Promise<void>;
+    recordMetric(metric: MonitoringMetric): Promise<void>;
+    startSpan(options: MonitoringSpanOptions): MonitoringSpan;
+    withSpan<T>(options: MonitoringSpanOptions, fn: (span: MonitoringSpan) => Promise<T>): Promise<T>;
+    getActiveSpan(): MonitoringSpan | null;
+    log(entry: MonitoringLogEntry): Promise<void>;
+    sendEvent(event: MonitoringObservabilityEvent): Promise<void>;
+    trackOperation<T>(context: MonitoringOperationContext, operation: () => Promise<T>): Promise<{
+        result: T;
+        metrics: MonitoringOperationResult;
+    }>;
+    shutdown(): Promise<void>;
+    flush(): Promise<void>;
+    isHealthy(): Promise<boolean>;
+}
+/**
+ * Pre-defined metric names for consistency
+ */
+export declare const OBSERVABILITY_METRICS: {
+    readonly SERVICE_OPERATION_DURATION: "service.operation.duration";
+    readonly SERVICE_OPERATION_COUNT: "service.operation.count";
+    readonly SERVICE_OPERATION_ERROR: "service.operation.error";
+    readonly DB_QUERY_DURATION: "db.query.duration";
+    readonly DB_QUERY_COUNT: "db.query.count";
+    readonly DB_CONNECTION_POOL_SIZE: "db.connection.pool.size";
+    readonly DB_CONNECTION_POOL_USED: "db.connection.pool.used";
+    readonly CACHE_HIT: "cache.hit";
+    readonly CACHE_MISS: "cache.miss";
+    readonly CACHE_SET: "cache.set";
+    readonly CACHE_DELETE: "cache.delete";
+    readonly API_REQUEST_DURATION: "api.request.duration";
+    readonly API_REQUEST_COUNT: "api.request.count";
+    readonly API_REQUEST_ERROR: "api.request.error";
+    readonly TRANSACTION_DURATION: "transaction.duration";
+    readonly TRANSACTION_COUNT: "transaction.count";
+    readonly TRANSACTION_ROLLBACK: "transaction.rollback";
+};
+/**
+ * Pre-defined span names for consistency
+ */
+export declare const OBSERVABILITY_SPANS: {
+    readonly SERVICE_CREATE: "service.create";
+    readonly SERVICE_UPDATE: "service.update";
+    readonly SERVICE_DELETE: "service.delete";
+    readonly SERVICE_GET: "service.get";
+    readonly SERVICE_LIST: "service.list";
+    readonly SERVICE_BULK_CREATE: "service.bulk_create";
+    readonly SERVICE_BULK_DELETE: "service.bulk_delete";
+    readonly SERVICE_TRANSACTION: "service.transaction";
+    readonly DB_QUERY: "db.query";
+    readonly CACHE_GET: "cache.get";
+    readonly CACHE_SET: "cache.set";
+    readonly API_REQUEST: "api.request";
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plyaz/types",
-  "version": "1.23.0",
+  "version": "1.23.2",
   "author": "Redeemer Pace",
   "license": "ISC",
   "description": "Provides shared TypeScript types and schema utilities for validation and parsing in the @playz ecosystem.",
@@ -20,6 +20,11 @@
       "import": "./dist/examples/index.js",
       "require": "./dist/examples/index.cjs"
     },
+    "./observability": {
+      "types": "./dist/observability/index.d.ts",
+      "import": "./dist/observability/index.js",
+      "require": "./dist/observability/index.cjs"
+    },
     "./api": {
       "types": "./dist/api/index.d.ts",
       "import": "./dist/api/index.js",