duron 0.3.0-beta.10 → 0.3.0-beta.11

package/dist/telemetry/local.d.ts

@@ -1,7 +1,28 @@
 import { type AddSpanAttributeOptions, type AddSpanEventOptions, type EndSpanOptions, type RecordMetricOptions, type Span, type StartDatabaseSpanOptions, type StartJobSpanOptions, type StartStepSpanOptions, TelemetryAdapter, type Tracer } from './adapter.js';
 export interface LocalTelemetryAdapterOptions {
+    /**
+     * Delay in milliseconds before flushing queued metrics to the database.
+     * Metrics are batched and inserted after this delay of inactivity.
+     * @default 1000
+     */
     flushDelayMs?: number;
 }
+/**
+ * Local telemetry adapter that stores metrics directly in the Duron database.
+ * Perfect for development and self-hosted deployments.
+ *
+ * This adapter automatically uses the database adapter configured in the Duron client.
+ * Metrics are batched and inserted after a configurable delay of inactivity to reduce database load.
+ *
+ * @example
+ * ```typescript
+ * const client = duron({
+ *   database: postgresAdapter({ connection: 'postgres://...' }),
+ *   telemetry: localTelemetryAdapter({ flushDelayMs: 500 }), // Custom 500ms delay
+ *   actions: { ... }
+ * })
+ * ```
+ */
 export declare class LocalTelemetryAdapter extends TelemetryAdapter {
     #private;
     constructor(options?: LocalTelemetryAdapterOptions);
@@ -18,5 +39,32 @@ export declare class LocalTelemetryAdapter extends TelemetryAdapter {
     protected _addSpanAttribute(options: AddSpanAttributeOptions): Promise<void>;
     protected _getTracer(name: string): Tracer;
 }
+/**
+ * Create a local telemetry adapter that stores metrics in the Duron database.
+ * Perfect for development and self-hosted deployments.
+ *
+ * The database adapter is automatically obtained from the Duron client.
+ * Metrics are batched and inserted after a configurable delay of inactivity to reduce database load.
+ *
+ * @param options - Configuration options
+ * @param options.flushDelayMs - Delay in milliseconds before flushing queued metrics (default: 1000)
+ * @returns LocalTelemetryAdapter instance
+ *
+ * @example
+ * ```typescript
+ * const client = duron({
+ *   database: postgresAdapter({ connection: 'postgres://...' }),
+ *   telemetry: localTelemetryAdapter(), // Uses default 1 second delay
+ *   actions: { ... }
+ * })
+ *
+ * // Or with custom flush delay
+ * const client = duron({
+ *   database: postgresAdapter({ connection: 'postgres://...' }),
+ *   telemetry: localTelemetryAdapter({ flushDelayMs: 500 }), // 500ms delay
+ *   actions: { ... }
+ * })
+ * ```
+ */
 export declare const localTelemetryAdapter: (options?: LocalTelemetryAdapterOptions) => LocalTelemetryAdapter;
 //# sourceMappingURL=local.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../src/telemetry/local.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,IAAI,EACT,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,EAExB,KAAK,oBAAoB,EACzB,gBAAgB,EAChB,KAAK,MAAM,EAEZ,MAAM,cAAc,CAAA;AAMrB,MAAM,WAAW,4BAA4B;IAM3C,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AA4BD,qBAAa,qBAAsB,SAAQ,gBAAgB;;gBAO7C,OAAO,CAAC,EAAE,4BAA4B;cAwFlC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;cAIvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;cAUtB,aAAa,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;cAyB1D,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;cAoB/D,cAAc,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;cA2B5D,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;cAqBhE,kBAAkB,CAAC,QAAQ,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;cAK5E,gBAAgB,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;cAQtE,aAAa,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;cAW1D,aAAa,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;cAc1D,iBAAiB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBlF,SAAS,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;CAqF3C;AA6BD,eAAO,MAAM,qBAAqB,GAAI,UAAU,4BAA4B,0BAAuC,CAAA"}
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../src/telemetry/local.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,IAAI,EACT,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,EAExB,KAAK,oBAAoB,EACzB,gBAAgB,EAChB,KAAK,MAAM,EAEZ,MAAM,cAAc,CAAA;AAMrB,MAAM,WAAW,4BAA4B;IAC3C;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAYD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,qBAAsB,SAAQ,gBAAgB;;gBAO7C,OAAO,CAAC,EAAE,4BAA4B;cAwFlC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;cAIvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;cAUtB,aAAa,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;cAyB1D,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;cAoB/D,cAAc,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;cA2B5D,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;cAqBhE,kBAAkB,CAAC,QAAQ,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;cAK5E,gBAAgB,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;cAQtE,aAAa,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;cAW1D,aAAa,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;cAc1D,iBAAiB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBlF,SAAS,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;CAqF3C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,qBAAqB,GAAI,UAAU,4BAA4B,0BAAuC,CAAA"}

package/dist/telemetry/local.js

@@ -1,5 +1,27 @@
 import { TelemetryAdapter, } from './adapter.js';
+// ============================================================================
+// Constants
+// ============================================================================
 const DEFAULT_FLUSH_DELAY_MS = 1000;
+// ============================================================================
+// Local Telemetry Adapter
+// ============================================================================
+/**
+ * Local telemetry adapter that stores metrics directly in the Duron database.
+ * Perfect for development and self-hosted deployments.
+ *
+ * This adapter automatically uses the database adapter configured in the Duron client.
+ * Metrics are batched and inserted after a configurable delay of inactivity to reduce database load.
+ *
+ * @example
+ * ```typescript
+ * const client = duron({
+ *   database: postgresAdapter({ connection: 'postgres://...' }),
+ *   telemetry: localTelemetryAdapter({ flushDelayMs: 500 }), // Custom 500ms delay
+ *   actions: { ... }
+ * })
+ * ```
+ */
 export class LocalTelemetryAdapter extends TelemetryAdapter {
     #spanStartTimes = new Map();
     #metricsQueue = [];
@@ -10,6 +32,10 @@ export class LocalTelemetryAdapter extends TelemetryAdapter {
         super();
         this.#flushDelayMs = options?.flushDelayMs ?? DEFAULT_FLUSH_DELAY_MS;
     }
+    /**
+     * Get the database adapter from the Duron client.
+     * @throws Error if the client is not set
+     */
     get #database() {
         const client = this.client;
         if (!client) {
@@ -17,10 +43,21 @@ export class LocalTelemetryAdapter extends TelemetryAdapter {
         }
         return client.database;
     }
+    // ============================================================================
+    // Queue Management
+    // ============================================================================
+    /**
+     * Queue a metric for batch insertion.
+     * The metric will be inserted after 1 second of inactivity.
+     */
     #queueMetric(options) {
         this.#metricsQueue.push(options);
         this.#scheduleFlush();
     }
+    /**
+     * Schedule a flush of the metrics queue.
+     * Resets the timer on each call (debounce behavior).
+     */
     #scheduleFlush() {
         if (this.#flushTimer) {
             clearTimeout(this.#flushTimer);
@@ -32,32 +69,53 @@ export class LocalTelemetryAdapter extends TelemetryAdapter {
             });
         }, this.#flushDelayMs);
     }
+    /**
+     * Flush all queued metrics to the database.
+     */
     async #flushQueue() {
         if (this.#metricsQueue.length === 0) {
             return;
         }
+        // Take all metrics from the queue
         const metrics = this.#metricsQueue.splice(0, this.#metricsQueue.length);
+        // Batch insert all metrics in a single database operation
         await this.#database.insertMetrics(metrics);
     }
+    /**
+     * Force flush the queue immediately.
+     * Used during shutdown to ensure all metrics are persisted.
+     */
     async #forceFlush() {
+        // Clear any pending timer
         if (this.#flushTimer) {
             clearTimeout(this.#flushTimer);
             this.#flushTimer = null;
         }
+        // Wait for any in-progress flush
         if (this.#flushPromise) {
             await this.#flushPromise;
         }
+        // Flush remaining metrics
         await this.#flushQueue();
     }
+    // ============================================================================
+    // Lifecycle Methods
+    // ============================================================================
     async _start() {
+        // Database adapter should already be started by the client
     }
     async _stop() {
+        // Flush any remaining metrics before stopping
         await this.#forceFlush();
         this.#spanStartTimes.clear();
     }
+    // ============================================================================
+    // Span Methods
+    // ============================================================================
     async _startJobSpan(options) {
         const spanId = `job:${options.jobId}`;
         this.#spanStartTimes.set(spanId, Date.now());
+        // Record span start as a metric
         this.#queueMetric({
             jobId: options.jobId,
             name: 'duron.job.span.start',
@@ -80,6 +138,7 @@ export class LocalTelemetryAdapter extends TelemetryAdapter {
         const startTime = this.#spanStartTimes.get(span.id);
         const duration = startTime ? Date.now() - startTime : 0;
         this.#spanStartTimes.delete(span.id);
+        // Record span end with duration
         this.#queueMetric({
             jobId: span.jobId,
             name: 'duron.job.span.end',
@@ -96,6 +155,7 @@ export class LocalTelemetryAdapter extends TelemetryAdapter {
     async _startStepSpan(options) {
         const spanId = `step:${options.stepId}`;
         this.#spanStartTimes.set(spanId, Date.now());
+        // Record span start as a metric
         this.#queueMetric({
             jobId: options.jobId,
             stepId: options.stepId,
@@ -120,6 +180,7 @@ export class LocalTelemetryAdapter extends TelemetryAdapter {
         const startTime = this.#spanStartTimes.get(span.id);
         const duration = startTime ? Date.now() - startTime : 0;
         this.#spanStartTimes.delete(span.id);
+        // Record span end with duration
         this.#queueMetric({
             jobId: span.jobId,
             stepId: span.stepId ?? undefined,
@@ -135,10 +196,15 @@ export class LocalTelemetryAdapter extends TelemetryAdapter {
         });
     }
     async _startDatabaseSpan(_options) {
+        // Local adapter doesn't trace database operations to avoid infinite loops
         return null;
     }
     async _endDatabaseSpan(_span, _options) {
+        // No-op for local adapter
     }
+    // ============================================================================
+    // Metrics Methods
+    // ============================================================================
     async _recordMetric(options) {
         this.#queueMetric({
             jobId: options.jobId,
@@ -176,6 +242,9 @@ export class LocalTelemetryAdapter extends TelemetryAdapter {
             },
         });
     }
+    // ============================================================================
+    // Tracer Methods
+    // ============================================================================
     _getTracer(name) {
         const adapter = this;
         return {
@@ -187,6 +256,10 @@ export class LocalTelemetryAdapter extends TelemetryAdapter {
                 const attributes = {
                     ...options?.attributes,
                 };
+                // Note: Local adapter tracer spans don't have a jobId context,
+                // so they can't be stored in the database. They're essentially no-ops
+                // but provide a consistent API for code that needs a tracer.
+                // For actual metrics storage, use ctx.observe within action/step handlers.
                 const tracerSpan = {
                     setAttribute(key, value) {
                         if (!ended) {
@@ -212,11 +285,13 @@ export class LocalTelemetryAdapter extends TelemetryAdapter {
                     },
                     setStatusOk() {
                         if (!ended) {
+                            // biome-ignore lint/complexity/useLiteralKeys: Index signature requires bracket notation
                             attributes['status'] = 'ok';
                         }
                     },
                     setStatusError(message) {
                         if (!ended) {
+                            // biome-ignore lint/complexity/useLiteralKeys: Index signature requires bracket notation
                             attributes['status'] = 'error';
                             if (message) {
                                 attributes['status.message'] = message;
@@ -240,4 +315,31 @@ export class LocalTelemetryAdapter extends TelemetryAdapter {
         };
     }
 }
+/**
+ * Create a local telemetry adapter that stores metrics in the Duron database.
+ * Perfect for development and self-hosted deployments.
+ *
+ * The database adapter is automatically obtained from the Duron client.
+ * Metrics are batched and inserted after a configurable delay of inactivity to reduce database load.
+ *
+ * @param options - Configuration options
+ * @param options.flushDelayMs - Delay in milliseconds before flushing queued metrics (default: 1000)
+ * @returns LocalTelemetryAdapter instance
+ *
+ * @example
+ * ```typescript
+ * const client = duron({
+ *   database: postgresAdapter({ connection: 'postgres://...' }),
+ *   telemetry: localTelemetryAdapter(), // Uses default 1 second delay
+ *   actions: { ... }
+ * })
+ *
+ * // Or with custom flush delay
+ * const client = duron({
+ *   database: postgresAdapter({ connection: 'postgres://...' }),
+ *   telemetry: localTelemetryAdapter({ flushDelayMs: 500 }), // 500ms delay
+ *   actions: { ... }
+ * })
+ * ```
+ */
 export const localTelemetryAdapter = (options) => new LocalTelemetryAdapter(options);

package/dist/telemetry/noop.d.ts

@@ -1,4 +1,8 @@
 import { type AddSpanAttributeOptions, type AddSpanEventOptions, type EndSpanOptions, type RecordMetricOptions, type Span, type StartDatabaseSpanOptions, type StartJobSpanOptions, type StartStepSpanOptions, TelemetryAdapter, type Tracer } from './adapter.js';
+/**
+ * No-operation telemetry adapter.
+ * Used when telemetry is disabled. All methods are no-ops.
+ */
 export declare class NoopTelemetryAdapter extends TelemetryAdapter {
     protected _start(): Promise<void>;
     protected _stop(): Promise<void>;
@@ -13,5 +17,11 @@ export declare class NoopTelemetryAdapter extends TelemetryAdapter {
     protected _addSpanAttribute(_options: AddSpanAttributeOptions): Promise<void>;
     protected _getTracer(name: string): Tracer;
 }
+/**
+ * Create a no-operation telemetry adapter.
+ * Use this when telemetry should be disabled.
+ *
+ * @returns NoopTelemetryAdapter instance
+ */
 export declare const noopTelemetryAdapter: () => NoopTelemetryAdapter;
 //# sourceMappingURL=noop.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"noop.d.ts","sourceRoot":"","sources":["../../src/telemetry/noop.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,IAAI,EACT,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,gBAAgB,EAChB,KAAK,MAAM,EAEZ,MAAM,cAAc,CAAA;AAyCrB,qBAAa,oBAAqB,SAAQ,gBAAgB;cAKxC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;cAIvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;cAQtB,aAAa,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;cAS1D,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;cAIjE,cAAc,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;cAS5D,YAAY,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;cAIlE,kBAAkB,CAAC,QAAQ,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;cAI5E,gBAAgB,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;cAQtE,aAAa,CAAC,QAAQ,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;cAI3D,aAAa,CAAC,QAAQ,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;cAI3D,iBAAiB,CAAC,QAAQ,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IAQnF,SAAS,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;CAQ3C;AAQD,eAAO,MAAM,oBAAoB,4BAAmC,CAAA"}
+{"version":3,"file":"noop.d.ts","sourceRoot":"","sources":["../../src/telemetry/noop.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,IAAI,EACT,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,gBAAgB,EAChB,KAAK,MAAM,EAEZ,MAAM,cAAc,CAAA;AAqCrB;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,gBAAgB;cAKxC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;cAIvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;cAQtB,aAAa,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;cAS1D,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;cAIjE,cAAc,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;cAS5D,YAAY,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;cAIlE,kBAAkB,CAAC,QAAQ,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;cAI5E,gBAAgB,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;cAQtE,aAAa,CAAC,QAAQ,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;cAI3D,aAAa,CAAC,QAAQ,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;cAI3D,iBAAiB,CAAC,QAAQ,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IAQnF,SAAS,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;CAQ3C;AAED;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,4BAAmC,CAAA"}

package/dist/telemetry/noop.js

@@ -1,28 +1,53 @@
 import { TelemetryAdapter, } from './adapter.js';
+// ============================================================================
+// Noop Tracer Span
+// ============================================================================
 const noopTracerSpan = {
     setAttribute() {
+        // No-op
     },
     setAttributes() {
+        // No-op
     },
     addEvent() {
+        // No-op
     },
     recordException() {
+        // No-op
     },
     setStatusOk() {
+        // No-op
     },
     setStatusError() {
+        // No-op
     },
     end() {
+        // No-op
     },
     isRecording() {
         return false;
     },
 };
+// ============================================================================
+// Noop Telemetry Adapter
+// ============================================================================
+/**
+ * No-operation telemetry adapter.
+ * Used when telemetry is disabled. All methods are no-ops.
+ */
 export class NoopTelemetryAdapter extends TelemetryAdapter {
+    // ============================================================================
+    // Lifecycle Methods
+    // ============================================================================
     async _start() {
+        // No-op
     }
     async _stop() {
+        // No-op
     }
+    // ============================================================================
+    // Span Methods
+    // ============================================================================
     async _startJobSpan(options) {
         return {
             id: 'noop',
@@ -32,6 +57,7 @@ export class NoopTelemetryAdapter extends TelemetryAdapter {
         };
     }
     async _endJobSpan(_span, _options) {
+        // No-op
     }
     async _startStepSpan(options) {
         return {
@@ -42,18 +68,29 @@ export class NoopTelemetryAdapter extends TelemetryAdapter {
         };
     }
     async _endStepSpan(_span, _options) {
+        // No-op
     }
     async _startDatabaseSpan(_options) {
         return null;
     }
     async _endDatabaseSpan(_span, _options) {
+        // No-op
     }
+    // ============================================================================
+    // Metrics Methods
+    // ============================================================================
     async _recordMetric(_options) {
+        // No-op
     }
     async _addSpanEvent(_options) {
+        // No-op
     }
     async _addSpanAttribute(_options) {
+        // No-op
     }
+    // ============================================================================
+    // Tracer Methods
+    // ============================================================================
     _getTracer(name) {
         return {
             name,
@@ -63,4 +100,10 @@ export class NoopTelemetryAdapter extends TelemetryAdapter {
         };
     }
 }
+/**
+ * Create a no-operation telemetry adapter.
+ * Use this when telemetry should be disabled.
+ *
+ * @returns NoopTelemetryAdapter instance
+ */
 export const noopTelemetryAdapter = () => new NoopTelemetryAdapter();

package/dist/telemetry/opentelemetry.d.ts

@@ -1,10 +1,26 @@
 import type { TracerProvider } from '@opentelemetry/api';
 import { type AddSpanAttributeOptions, type AddSpanEventOptions, type EndSpanOptions, type RecordMetricOptions, type Span, type StartDatabaseSpanOptions, type StartJobSpanOptions, type StartStepSpanOptions, TelemetryAdapter, type Tracer } from './adapter.js';
 export interface OpenTelemetryAdapterOptions {
+    /**
+     * Service name for telemetry.
+     * Used as the tracer name.
+     */
     serviceName?: string;
+    /**
+     * Optional TracerProvider to use.
+     * If not provided, uses the global tracer provider.
+     */
     tracerProvider?: TracerProvider;
+    /**
+     * Whether to trace database queries.
+     * @default false
+     */
     traceDatabaseQueries?: boolean;
 }
+/**
+ * OpenTelemetry telemetry adapter.
+ * Exports traces to external systems like Jaeger, OTLP, etc.
+ */
 export declare class OpenTelemetryAdapter extends TelemetryAdapter {
     #private;
     constructor(options?: OpenTelemetryAdapterOptions);
@@ -21,5 +37,12 @@ export declare class OpenTelemetryAdapter extends TelemetryAdapter {
     protected _addSpanAttribute(options: AddSpanAttributeOptions): Promise<void>;
     protected _getTracer(name: string): Tracer;
 }
+/**
+ * Create an OpenTelemetry telemetry adapter.
+ * Exports traces to external systems like Jaeger, OTLP, etc.
+ *
+ * @param options - Configuration options
+ * @returns OpenTelemetryAdapter instance
+ */
 export declare const openTelemetryAdapter: (options?: OpenTelemetryAdapterOptions) => OpenTelemetryAdapter;
 //# sourceMappingURL=opentelemetry.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"opentelemetry.d.ts","sourceRoot":"","sources":["../../src/telemetry/opentelemetry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA0C,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAEhG,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,IAAI,EACT,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,EAExB,KAAK,oBAAoB,EACzB,gBAAgB,EAChB,KAAK,MAAM,EAEZ,MAAM,cAAc,CAAA;AAMrB,MAAM,WAAW,2BAA2B;IAK1C,WAAW,CAAC,EAAE,MAAM,CAAA;IAMpB,cAAc,CAAC,EAAE,cAAc,CAAA;IAM/B,oBAAoB,CAAC,EAAE,OAAO,CAAA;CAC/B;AAcD,qBAAa,oBAAqB,SAAQ,gBAAgB;;gBAQ5C,OAAO,GAAE,2BAAgC;cAWrC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;cAYvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;cAStB,aAAa,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;cA8B1D,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;cA2B/D,cAAc,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;cA4C5D,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;cA2BhE,kBAAkB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;cA8B3E,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;cAyBpE,aAAa,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;cAe1D,aAAa,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;cAO1D,iBAAiB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IAWlF,SAAS,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;CAsI3C;AASD,eAAO,MAAM,oBAAoB,GAAI,UAAU,2BAA2B,yBAAsC,CAAA"}
+{"version":3,"file":"opentelemetry.d.ts","sourceRoot":"","sources":["../../src/telemetry/opentelemetry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA0C,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAEhG,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,IAAI,EACT,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,EAExB,KAAK,oBAAoB,EACzB,gBAAgB,EAChB,KAAK,MAAM,EAEZ,MAAM,cAAc,CAAA;AAMrB,MAAM,WAAW,2BAA2B;IAC1C;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IAEpB;;;OAGG;IACH,cAAc,CAAC,EAAE,cAAc,CAAA;IAE/B;;;OAGG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAA;CAC/B;AAUD;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,gBAAgB;;gBAQ5C,OAAO,GAAE,2BAAgC;cAWrC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;cAYvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;cAStB,aAAa,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;cA8B1D,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;cA2B/D,cAAc,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;cA4C5D,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;cA2BhE,kBAAkB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;cA8B3E,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;cAyBpE,aAAa,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;cAe1D,aAAa,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;cAO1D,iBAAiB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IAWlF,SAAS,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;CAsI3C;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAAI,UAAU,2BAA2B,yBAAsC,CAAA"}

package/dist/telemetry/opentelemetry.js

@@ -1,4 +1,11 @@
 import { TelemetryAdapter, } from './adapter.js';
+// ============================================================================
+// OpenTelemetry Adapter
+// ============================================================================
+/**
+ * OpenTelemetry telemetry adapter.
+ * Exports traces to external systems like Jaeger, OTLP, etc.
+ */
 export class OpenTelemetryAdapter extends TelemetryAdapter {
     #serviceName;
     #tracerProvider;
@@ -12,8 +19,13 @@ export class OpenTelemetryAdapter extends TelemetryAdapter {
         this.#tracerProvider = options.tracerProvider ?? null;
         this.#traceDatabaseQueries = options.traceDatabaseQueries ?? false;
     }
+    // ============================================================================
+    // Lifecycle Methods
+    // ============================================================================
     async _start() {
+        // Dynamically import OpenTelemetry API to make it optional
         const api = await import('@opentelemetry/api');
+        // Get tracer from provider or global
         if (this.#tracerProvider) {
             this.#tracer = this.#tracerProvider.getTracer(this.#serviceName);
         }
@@ -25,6 +37,9 @@ export class OpenTelemetryAdapter extends TelemetryAdapter {
         this.#spanMap.clear();
         this.#tracer = null;
     }
+    // ============================================================================
+    // Span Methods
+    // ============================================================================
     async _startJobSpan(options) {
         if (!this.#tracer) {
             throw new Error('OpenTelemetry tracer not initialized');
@@ -80,6 +95,7 @@ export class OpenTelemetryAdapter extends TelemetryAdapter {
             throw new Error('OpenTelemetry tracer not initialized');
         }
         const api = await import('@opentelemetry/api');
+        // Get parent span context
         let parentContext = api.context.active();
         if (options.parentSpan) {
             const parentExtSpan = options.parentSpan;
@@ -176,7 +192,12 @@ export class OpenTelemetryAdapter extends TelemetryAdapter {
         otelSpan.end();
         this.#spanMap.delete(span.id);
     }
+    // ============================================================================
+    // Metrics Methods
+    // ============================================================================
     async _recordMetric(options) {
+        // OpenTelemetry metrics would require MeterProvider
+        // For now, we record as span events on the current active span
         const api = await import('@opentelemetry/api');
         const activeSpan = api.trace.getActiveSpan();
         if (activeSpan) {
@@ -199,7 +220,11 @@ export class OpenTelemetryAdapter extends TelemetryAdapter {
             extSpan.otelSpan.setAttribute(options.key, options.value);
         }
     }
+    // ============================================================================
+    // Tracer Methods
+    // ============================================================================
     _getTracer(name) {
+        // Return cached tracer if available
         const cached = this.#tracerCache.get(name);
         if (cached) {
             return cached;
@@ -208,11 +233,15 @@ export class OpenTelemetryAdapter extends TelemetryAdapter {
         const tracer = {
             name,
             startSpan(spanName, options) {
+                // We need to dynamically get the OpenTelemetry API
+                // Since _getTracer is synchronous, we need to handle this carefully
                 let otelSpan = null;
                 let api = null;
                 let ended = false;
+                // Initialize the span asynchronously but return synchronously
                 const initPromise = (async () => {
                     api = await import('@opentelemetry/api');
+                    // Get the tracer
                     let otelTracer;
                     if (adapter.#tracerProvider) {
                         otelTracer = adapter.#tracerProvider.getTracer(name);
@@ -220,6 +249,7 @@ export class OpenTelemetryAdapter extends TelemetryAdapter {
                     else {
                         otelTracer = api.trace.getTracer(name);
                     }
+                    // Map kind
                     let spanKind = api.SpanKind.INTERNAL;
                     if (options?.kind === 'client')
                         spanKind = api.SpanKind.CLIENT;
@@ -229,6 +259,7 @@ export class OpenTelemetryAdapter extends TelemetryAdapter {
                         spanKind = api.SpanKind.PRODUCER;
                     else if (options?.kind === 'consumer')
                         spanKind = api.SpanKind.CONSUMER;
+                    // Get parent context
                     let parentContext = api.context.active();
                     if (options?.parentSpan) {
                         const parentOtelSpan = options.parentSpan._otelSpan;
@@ -296,6 +327,7 @@ export class OpenTelemetryAdapter extends TelemetryAdapter {
                         return otelSpan?.isRecording() ?? false;
                     },
                 };
+                // Store reference for parent context propagation
                 initPromise.then(() => {
                     if (otelSpan) {
                         ;
@@ -309,4 +341,11 @@ export class OpenTelemetryAdapter extends TelemetryAdapter {
         return tracer;
     }
 }
+/**
+ * Create an OpenTelemetry telemetry adapter.
+ * Exports traces to external systems like Jaeger, OTLP, etc.
+ *
+ * @param options - Configuration options
+ * @returns OpenTelemetryAdapter instance
+ */
 export const openTelemetryAdapter = (options) => new OpenTelemetryAdapter(options);

package/dist/utils/p-retry.d.ts

@@ -1,3 +1,8 @@
+/**
+ * @author github.com/sindresorhus
+ * @license MIT
+ * @description A refactor version of p-retry remove unnecessary code and add the necessary context to the retry function.
+ */
 interface RetryOptions {
     retries: number;
     factor: number;

package/dist/utils/p-retry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"p-retry.d.ts","sourceRoot":"","sources":["../../src/utils/p-retry.ts"],"names":[],"mappings":"AAMA,UAAU,YAAY;IACpB,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,SAAS,EAAE,OAAO,CAAA;IAClB,MAAM,EAAE,WAAW,CAAA;IACnB,eAAe,EAAE,CAAC,OAAO,EAAE;QACzB,KAAK,EAAE,KAAK,CAAA;QACZ,aAAa,EAAE,MAAM,CAAA;QACrB,WAAW,EAAE,MAAM,CAAA;QACnB,eAAe,EAAE,MAAM,CAAA;QACvB,UAAU,EAAE,MAAM,CAAA;KACnB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACpB;AA6HD,wBAA8B,MAAM,CAAC,OAAO,EAC1C,KAAK,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,EAClD,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,OAAO,CAAC,CA4DlB"}
+{"version":3,"file":"p-retry.d.ts","sourceRoot":"","sources":["../../src/utils/p-retry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,UAAU,YAAY;IACpB,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,SAAS,EAAE,OAAO,CAAA;IAClB,MAAM,EAAE,WAAW,CAAA;IACnB,eAAe,EAAE,CAAC,OAAO,EAAE;QACzB,KAAK,EAAE,KAAK,CAAA;QACZ,aAAa,EAAE,MAAM,CAAA;QACrB,WAAW,EAAE,MAAM,CAAA;QACnB,eAAe,EAAE,MAAM,CAAA;QACvB,UAAU,EAAE,MAAM,CAAA;KACnB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACpB;AA6HD,wBAA8B,MAAM,CAAC,OAAO,EAC1C,KAAK,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,EAClD,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,OAAO,CAAC,CA4DlB"}

package/dist/utils/p-retry.js

@@ -1,3 +1,8 @@
+/**
+ * @author github.com/sindresorhus
+ * @license MIT
+ * @description A refactor version of p-retry remove unnecessary code and add the necessary context to the retry function.
+ */
 function validateRetries(retries) {
     if (typeof retries === 'number') {
         if (retries < 0) {
@@ -95,10 +100,12 @@ export default async function pRetry(input, options) {
     options.maxTimeout ??= Number.POSITIVE_INFINITY;
     options.maxRetryTime ??= Number.POSITIVE_INFINITY;
     options.randomize ??= false;
+    // Validate numeric options and normalize edge cases
     validateNumberOption('factor', options.factor, { min: 0, allowInfinity: false });
     validateNumberOption('minTimeout', options.minTimeout, { min: 0, allowInfinity: false });
     validateNumberOption('maxTimeout', options.maxTimeout, { min: 0, allowInfinity: true });
     validateNumberOption('maxRetryTime', options.maxRetryTime, { min: 0, allowInfinity: true });
+    // Treat non-positive factor as 1 to avoid zero backoff or negative behavior
     if (!(options.factor > 0)) {
         options.factor = 1;
     }
@@ -125,5 +132,6 @@ export default async function pRetry(input, options) {
             retriesConsumed++;
         }
     }
+    // Should not reach here, but in case it does, throw an error
     throw new Error('Retry attempts exhausted without throwing an error.');
 }

package/dist/utils/wait-for-abort.d.ts

@@ -1,3 +1,4 @@
+/** biome-ignore-all lint/suspicious/noConfusingVoidType: do not care */
 export default function waitForAbort(signal: AbortSignal): {
     promise: Promise<unknown>;
     release: () => void;

package/dist/utils/wait-for-abort.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wait-for-abort.d.ts","sourceRoot":"","sources":["../../src/utils/wait-for-abort.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,OAAO,UAAU,YAAY,CAAC,MAAM,EAAE,WAAW;;;EAqCvD"}
+{"version":3,"file":"wait-for-abort.d.ts","sourceRoot":"","sources":["../../src/utils/wait-for-abort.ts"],"names":[],"mappings":"AAAA,wEAAwE;AAExE,MAAM,CAAC,OAAO,UAAU,YAAY,CAAC,MAAM,EAAE,WAAW;;;EAqCvD"}

package/dist/utils/wait-for-abort.js

@@ -1,3 +1,4 @@
+/** biome-ignore-all lint/suspicious/noConfusingVoidType: do not care */
 export default function waitForAbort(signal) {
     let done = false;
     let globalResolve = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "duron",
-  "version": "0.3.0-beta.10",
+  "version": "0.3.0-beta.11",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",