duron 0.3.0-beta.10 → 0.3.0-beta.12

package/dist/telemetry/adapter.d.ts

@@ -1,20 +1,48 @@
 import type { Logger } from 'pino';
 import type { Adapter } from '../adapters/adapter.js';
+/**
+ * Interface representing the minimal Duron client required by telemetry adapters.
+ * This avoids circular dependencies by using a minimal interface.
+ */
 export interface TelemetryClient {
+    /**
+     * The database adapter instance.
+     */
     database: Adapter;
 }
+/**
+ * Span represents a trace span for job or step execution.
+ */
 export interface Span {
+    /**
+     * Unique identifier for this span.
+     */
     id: string;
+    /**
+     * The job ID this span belongs to.
+     */
     jobId: string;
+    /**
+     * The step ID this span belongs to (null for job spans).
+     */
     stepId: string | null;
+    /**
+     * Parent span ID for nested spans.
+     */
     parentSpanId: string | null;
 }
+/**
+ * Options for starting a job span.
+ */
 export interface StartJobSpanOptions {
     jobId: string;
     actionName: string;
     groupKey: string;
     input?: any;
 }
+/**
+ * Options for starting a step span.
+ */
 export interface StartStepSpanOptions {
     jobId: string;
     stepId: string;
@@ -22,14 +50,23 @@ export interface StartStepSpanOptions {
     parentSpan?: Span;
     parentStepId: string | null;
 }
+/**
+ * Options for ending a span.
+ */
 export interface EndSpanOptions {
     status: 'ok' | 'error' | 'cancelled';
     error?: any;
 }
+/**
+ * Options for starting a database span.
+ */
 export interface StartDatabaseSpanOptions {
     operation: string;
     query?: string;
 }
+/**
+ * Options for recording a metric.
+ */
 export interface RecordMetricOptions {
     jobId: string;
     stepId?: string;
@@ -37,71 +74,356 @@ export interface RecordMetricOptions {
     value: number;
     attributes?: Record<string, any>;
 }
+/**
+ * Options for adding a span event.
+ */
 export interface AddSpanEventOptions {
     span: Span;
     name: string;
     attributes?: Record<string, any>;
 }
+/**
+ * Options for adding a span attribute.
+ */
 export interface AddSpanAttributeOptions {
     span: Span;
     key: string;
     value: string | number | boolean;
 }
+/**
+ * Options for starting a custom span with the tracer.
+ */
 export interface StartSpanOptions {
+    /**
+     * Span kind (internal, client, server, producer, consumer).
+     * @default 'internal'
+     */
     kind?: 'internal' | 'client' | 'server' | 'producer' | 'consumer';
+    /**
+     * Initial attributes for the span.
+     */
     attributes?: Record<string, string | number | boolean>;
+    /**
+     * Parent span to use for context propagation.
+     * If not provided, uses the current active context.
+     */
     parentSpan?: TracerSpan;
 }
+/**
+ * A span created by the Tracer for manual instrumentation.
+ */
 export interface TracerSpan {
+    /**
+     * Set an attribute on the span.
+     *
+     * @param key - The attribute key
+     * @param value - The attribute value
+     */
     setAttribute(key: string, value: string | number | boolean): void;
+    /**
+     * Set multiple attributes on the span.
+     *
+     * @param attributes - The attributes to set
+     */
     setAttributes(attributes: Record<string, string | number | boolean>): void;
+    /**
+     * Add an event to the span.
+     *
+     * @param name - The event name
+     * @param attributes - Optional event attributes
+     */
     addEvent(name: string, attributes?: Record<string, string | number | boolean>): void;
+    /**
+     * Record an exception on the span.
+     *
+     * @param error - The error to record
+     */
     recordException(error: Error): void;
+    /**
+     * Set the span status to OK.
+     */
     setStatusOk(): void;
+    /**
+     * Set the span status to error.
+     *
+     * @param message - Optional error message
+     */
     setStatusError(message?: string): void;
+    /**
+     * End the span.
+     * After calling this, no more operations can be performed on the span.
+     */
     end(): void;
+    /**
+     * Check if this span is recording.
+     */
     isRecording(): boolean;
 }
+/**
+ * A Tracer provides methods for creating spans.
+ * Similar to OpenTelemetry's Tracer interface.
+ */
 export interface Tracer {
+    /**
+     * The name of this tracer.
+     */
     readonly name: string;
+    /**
+     * Start a new span.
+     *
+     * @param name - The name of the span
+     * @param options - Optional span configuration
+     * @returns A TracerSpan for manual instrumentation
+     */
     startSpan(name: string, options?: StartSpanOptions): TracerSpan;
 }
+/**
+ * Observe context provided to action and step handlers.
+ */
 export interface ObserveContext {
+    /**
+     * Record a custom metric.
+     *
+     * @param name - The metric name (e.g., 'ai.tokens.total', 'processing.duration_ms')
+     * @param value - The metric value
+     * @param attributes - Optional attributes for the metric
+     */
     recordMetric(name: string, value: number, attributes?: Record<string, any>): void;
+    /**
+     * Add an attribute to the current span.
+     *
+     * @param key - The attribute key
+     * @param value - The attribute value
+     */
     addSpanAttribute(key: string, value: string | number | boolean): void;
+    /**
+     * Add an event to the current span.
+     *
+     * @param name - The event name
+     * @param attributes - Optional event attributes
+     */
     addSpanEvent(name: string, attributes?: Record<string, any>): void;
+    /**
+     * Get a tracer for manual instrumentation.
+     * Similar to OpenTelemetry's `trace.getTracer()` method.
+     *
+     * @param name - The name of the tracer (typically your service or library name)
+     * @returns A Tracer for creating custom spans
+     *
+     * @example
+     * ```typescript
+     * const tracer = ctx.observe.getTracer('my-service')
+     *
+     * const span = tracer.startSpan('external-api-call', {
+     *   kind: 'client',
+     *   attributes: { 'api.endpoint': '/users' }
+     * })
+     *
+     * try {
+     *   const result = await fetch('https://api.example.com/users')
+     *   span.setStatusOk()
+     *   return result
+     * } catch (error) {
+     *   span.recordException(error)
+     *   span.setStatusError(error.message)
+     *   throw error
+     * } finally {
+     *   span.end()
+     * }
+     * ```
+     */
     getTracer(name: string): Tracer;
 }
+/**
+ * Abstract base class for telemetry adapters.
+ * All telemetry adapters must extend this class and implement its abstract methods.
+ */
 export declare abstract class TelemetryAdapter {
     #private;
+    /**
+     * Start the telemetry adapter.
+     * Performs any necessary initialization.
+     *
+     * @returns Promise resolving to `true` if started successfully, `false` otherwise
+     */
     start(): Promise<boolean>;
+    /**
+     * Stop the telemetry adapter.
+     * Performs cleanup.
+     *
+     * @returns Promise resolving to `true` if stopped successfully, `false` otherwise
+     */
     stop(): Promise<boolean>;
+    /**
+     * Set the logger instance for this adapter.
+     *
+     * @param logger - The logger instance to use for logging
+     */
     setLogger(logger: Logger): void;
+    /**
+     * Get the logger instance for this adapter.
+     *
+     * @returns The logger instance, or `null` if not set
+     */
     get logger(): Logger | null;
+    /**
+     * Set the Duron client instance for this adapter.
+     * This is called automatically by the Duron client during initialization.
+     *
+     * @param client - The Duron client instance
+     */
     setClient(client: TelemetryClient): void;
+    /**
+     * Get the Duron client instance.
+     * Available to subclasses for accessing the database adapter.
+     *
+     * @returns The Duron client instance, or `null` if not set
+     */
     protected get client(): TelemetryClient | null;
+    /**
+     * Start a span for job execution.
+     *
+     * @param options - Options for the job span
+     * @returns The created span
+     */
     startJobSpan(options: StartJobSpanOptions): Promise<Span>;
+    /**
+     * End a job span.
+     *
+     * @param span - The span to end
+     * @param options - End options including status and error
+     */
     endJobSpan(span: Span, options: EndSpanOptions): Promise<void>;
+    /**
+     * Start a span for step execution.
+     *
+     * @param options - Options for the step span
+     * @returns The created span
+     */
     startStepSpan(options: StartStepSpanOptions): Promise<Span>;
+    /**
+     * End a step span.
+     *
+     * @param span - The span to end
+     * @param options - End options including status and error
+     */
     endStepSpan(span: Span, options: EndSpanOptions): Promise<void>;
+    /**
+     * Start a span for database operation (optional tracing).
+     *
+     * @param options - Options for the database span
+     * @returns The created span, or null if database tracing is disabled
+     */
     startDatabaseSpan(options: StartDatabaseSpanOptions): Promise<Span | null>;
+    /**
+     * End a database span.
+     *
+     * @param span - The span to end
+     * @param options - End options including status and error
+     */
     endDatabaseSpan(span: Span | null, options: EndSpanOptions): Promise<void>;
+    /**
+     * Record a metric.
+     *
+     * @param options - Options for recording the metric
+     */
     recordMetric(options: RecordMetricOptions): Promise<void>;
+    /**
+     * Add an event to a span.
+     *
+     * @param options - Options for the span event
+     */
     addSpanEvent(options: AddSpanEventOptions): Promise<void>;
+    /**
+     * Add an attribute to a span.
+     *
+     * @param options - Options for the span attribute
+     */
     addSpanAttribute(options: AddSpanAttributeOptions): Promise<void>;
+    /**
+     * Get a tracer for manual instrumentation.
+     * Similar to OpenTelemetry's `trace.getTracer()` method.
+     *
+     * @param name - The name of the tracer (typically your service or library name)
+     * @returns A Tracer for creating custom spans
+     *
+     * @example
+     * ```typescript
+     * const tracer = telemetry.getTracer('my-service')
+     *
+     * const span = tracer.startSpan('process-order', {
+     *   attributes: { 'order.id': orderId }
+     * })
+     *
+     * try {
+     *   // Do some work
+     *   span.addEvent('order.validated')
+     *   span.setStatusOk()
+     * } catch (error) {
+     *   span.recordException(error)
+     *   span.setStatusError(error.message)
+     * } finally {
+     *   span.end()
+     * }
+     * ```
+     */
     getTracer(name: string): Tracer;
+    /**
+     * Create an observe context for action/step handlers.
+     *
+     * @param jobId - The job ID
+     * @param stepId - The step ID (optional)
+     * @param span - The current span
+     * @returns ObserveContext for use in handlers
+     */
     createObserveContext(jobId: string, stepId: string | null, span: Span): ObserveContext;
+    /**
+     * Start the adapter.
+     */
     protected abstract _start(): Promise<void>;
+    /**
+     * Stop the adapter.
+     */
     protected abstract _stop(): Promise<void>;
+    /**
+     * Internal method to start a job span.
+     */
     protected abstract _startJobSpan(options: StartJobSpanOptions): Promise<Span>;
+    /**
+     * Internal method to end a job span.
+     */
     protected abstract _endJobSpan(span: Span, options: EndSpanOptions): Promise<void>;
+    /**
+     * Internal method to start a step span.
+     */
     protected abstract _startStepSpan(options: StartStepSpanOptions): Promise<Span>;
+    /**
+     * Internal method to end a step span.
+     */
     protected abstract _endStepSpan(span: Span, options: EndSpanOptions): Promise<void>;
+    /**
+     * Internal method to start a database span.
+     */
     protected abstract _startDatabaseSpan(options: StartDatabaseSpanOptions): Promise<Span | null>;
+    /**
+     * Internal method to end a database span.
+     */
     protected abstract _endDatabaseSpan(span: Span, options: EndSpanOptions): Promise<void>;
+    /**
+     * Internal method to record a metric.
+     */
     protected abstract _recordMetric(options: RecordMetricOptions): Promise<void>;
+    /**
+     * Internal method to add a span event.
+     */
     protected abstract _addSpanEvent(options: AddSpanEventOptions): Promise<void>;
+    /**
+     * Internal method to add a span attribute.
+     */
     protected abstract _addSpanAttribute(options: AddSpanAttributeOptions): Promise<void>;
+    /**
+     * Internal method to get a tracer for manual instrumentation.
+     */
     protected abstract _getTracer(name: string): Tracer;
 }
 //# sourceMappingURL=adapter.d.ts.map

package/dist/telemetry/adapter.d.ts.map

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

package/dist/telemetry/adapter.js

@@ -1,3 +1,10 @@
+// ============================================================================
+// Abstract Telemetry Adapter
+// ============================================================================
+/**
+ * Abstract base class for telemetry adapters.
+ * All telemetry adapters must extend this class and implement its abstract methods.
+ */
 export class TelemetryAdapter {
     #logger = null;
     #client = null;
@@ -5,6 +12,15 @@ export class TelemetryAdapter {
     #stopped = false;
     #starting = null;
     #stopping = null;
+    // ============================================================================
+    // Lifecycle Methods
+    // ============================================================================
+    /**
+     * Start the telemetry adapter.
+     * Performs any necessary initialization.
+     *
+     * @returns Promise resolving to `true` if started successfully, `false` otherwise
+     */
     async start() {
         try {
             if (this.#stopping || this.#stopped) {
@@ -29,6 +45,12 @@ export class TelemetryAdapter {
             throw error;
         }
     }
+    /**
+     * Stop the telemetry adapter.
+     * Performs cleanup.
+     *
+     * @returns Promise resolving to `true` if stopped successfully, `false` otherwise
+     */
     async stop() {
         try {
             if (this.#stopped) {
@@ -50,59 +72,182 @@ export class TelemetryAdapter {
             throw error;
         }
     }
+    // ============================================================================
+    // Configuration Methods
+    // ============================================================================
+    /**
+     * Set the logger instance for this adapter.
+     *
+     * @param logger - The logger instance to use for logging
+     */
     setLogger(logger) {
         this.#logger = logger;
     }
+    /**
+     * Get the logger instance for this adapter.
+     *
+     * @returns The logger instance, or `null` if not set
+     */
     get logger() {
         return this.#logger;
     }
+    /**
+     * Set the Duron client instance for this adapter.
+     * This is called automatically by the Duron client during initialization.
+     *
+     * @param client - The Duron client instance
+     */
     setClient(client) {
         this.#client = client;
     }
+    /**
+     * Get the Duron client instance.
+     * Available to subclasses for accessing the database adapter.
+     *
+     * @returns The Duron client instance, or `null` if not set
+     */
     get client() {
         return this.#client;
     }
+    // ============================================================================
+    // Span Methods
+    // ============================================================================
+    /**
+     * Start a span for job execution.
+     *
+     * @param options - Options for the job span
+     * @returns The created span
+     */
     async startJobSpan(options) {
         await this.start();
         return this._startJobSpan(options);
     }
+    /**
+     * End a job span.
+     *
+     * @param span - The span to end
+     * @param options - End options including status and error
+     */
     async endJobSpan(span, options) {
         await this.start();
         return this._endJobSpan(span, options);
     }
+    /**
+     * Start a span for step execution.
+     *
+     * @param options - Options for the step span
+     * @returns The created span
+     */
     async startStepSpan(options) {
         await this.start();
         return this._startStepSpan(options);
     }
+    /**
+     * End a step span.
+     *
+     * @param span - The span to end
+     * @param options - End options including status and error
+     */
     async endStepSpan(span, options) {
         await this.start();
         return this._endStepSpan(span, options);
     }
+    /**
+     * Start a span for database operation (optional tracing).
+     *
+     * @param options - Options for the database span
+     * @returns The created span, or null if database tracing is disabled
+     */
     async startDatabaseSpan(options) {
         await this.start();
         return this._startDatabaseSpan(options);
     }
+    /**
+     * End a database span.
+     *
+     * @param span - The span to end
+     * @param options - End options including status and error
+     */
     async endDatabaseSpan(span, options) {
         if (!span)
             return;
         await this.start();
         return this._endDatabaseSpan(span, options);
     }
+    // ============================================================================
+    // Metrics Methods
+    // ============================================================================
+    /**
+     * Record a metric.
+     *
+     * @param options - Options for recording the metric
+     */
     async recordMetric(options) {
         await this.start();
         return this._recordMetric(options);
     }
+    /**
+     * Add an event to a span.
+     *
+     * @param options - Options for the span event
+     */
     async addSpanEvent(options) {
         await this.start();
         return this._addSpanEvent(options);
     }
+    /**
+     * Add an attribute to a span.
+     *
+     * @param options - Options for the span attribute
+     */
     async addSpanAttribute(options) {
         await this.start();
         return this._addSpanAttribute(options);
     }
+    // ============================================================================
+    // Tracer Methods
+    // ============================================================================
+    /**
+     * Get a tracer for manual instrumentation.
+     * Similar to OpenTelemetry's `trace.getTracer()` method.
+     *
+     * @param name - The name of the tracer (typically your service or library name)
+     * @returns A Tracer for creating custom spans
+     *
+     * @example
+     * ```typescript
+     * const tracer = telemetry.getTracer('my-service')
+     *
+     * const span = tracer.startSpan('process-order', {
+     *   attributes: { 'order.id': orderId }
+     * })
+     *
+     * try {
+     *   // Do some work
+     *   span.addEvent('order.validated')
+     *   span.setStatusOk()
+     * } catch (error) {
+     *   span.recordException(error)
+     *   span.setStatusError(error.message)
+     * } finally {
+     *   span.end()
+     * }
+     * ```
+     */
     getTracer(name) {
         return this._getTracer(name);
     }
+    // ============================================================================
+    // Context Methods
+    // ============================================================================
+    /**
+     * Create an observe context for action/step handlers.
+     *
+     * @param jobId - The job ID
+     * @param stepId - The step ID (optional)
+     * @param span - The current span
+     * @returns ObserveContext for use in handlers
+     */
     createObserveContext(jobId, stepId, span) {
         return {
             recordMetric: (name, value, attributes) => {

package/dist/telemetry/index.d.ts

@@ -1,5 +1,2 @@
-export { type AddSpanAttributeOptions, type AddSpanEventOptions, type EndSpanOptions, type ObserveContext, type RecordMetricOptions, type Span, type StartDatabaseSpanOptions, type StartJobSpanOptions, type StartSpanOptions, type StartStepSpanOptions, TelemetryAdapter, type Tracer, type TracerSpan, } from './adapter.js';
-export { LocalTelemetryAdapter, type LocalTelemetryAdapterOptions, localTelemetryAdapter } from './local.js';
-export { NoopTelemetryAdapter, noopTelemetryAdapter } from './noop.js';
-export { OpenTelemetryAdapter, type OpenTelemetryAdapterOptions, openTelemetryAdapter } from './opentelemetry.js';
+export { LocalSpanExporter, type LocalSpanExporterOptions } from './local-span-exporter.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/telemetry/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,IAAI,EACT,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,gBAAgB,EAChB,KAAK,MAAM,EACX,KAAK,UAAU,GAChB,MAAM,cAAc,CAAA;AACrB,OAAO,EAAE,qBAAqB,EAAE,KAAK,4BAA4B,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AAC5G,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAA;AACtE,OAAO,EAAE,oBAAoB,EAAE,KAAK,2BAA2B,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/telemetry/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,MAAM,0BAA0B,CAAA"}

package/dist/telemetry/index.js

@@ -1,4 +1,2 @@
-export { TelemetryAdapter, } from './adapter.js';
-export { LocalTelemetryAdapter, localTelemetryAdapter } from './local.js';
-export { NoopTelemetryAdapter, noopTelemetryAdapter } from './noop.js';
-export { OpenTelemetryAdapter, openTelemetryAdapter } from './opentelemetry.js';
+// OpenTelemetry-based span exporter for local database persistence
+export { LocalSpanExporter } from './local-span-exporter.js';