duron 0.3.0-beta.9 → 0.3.0

package/dist/adapters/adapter.js

@@ -1,7 +1,14 @@
 import { EventEmitter } from 'node:events';
 import { z } from 'zod';
 import { JOB_STATUS_CANCELLED, JOB_STATUS_COMPLETED, JOB_STATUS_FAILED, STEP_STATUS_CANCELLED, STEP_STATUS_COMPLETED, STEP_STATUS_FAILED, } from '../constants.js';
-import { BooleanResultSchema, CancelJobOptionsSchema, CancelJobStepOptionsSchema, CompleteJobOptionsSchema, CompleteJobStepOptionsSchema, CreateJobOptionsSchema, CreateOrRecoverJobStepOptionsSchema, CreateOrRecoverJobStepResultNullableSchema, DelayJobStepOptionsSchema, DeleteJobOptionsSchema, DeleteJobsOptionsSchema, DeleteMetricsOptionsSchema, FailJobOptionsSchema, FailJobStepOptionsSchema, FetchOptionsSchema, GetActionsResultSchema, GetJobStepsOptionsSchema, GetJobStepsResultSchema, GetJobsOptionsSchema, GetJobsResultSchema, GetMetricsOptionsSchema, GetMetricsResultSchema, InsertMetricOptionsSchema, JobIdResultSchema, JobSchema, JobStatusResultSchema, JobStepSchema, JobStepStatusResultSchema, JobsArrayResultSchema, NumberResultSchema, RecoverJobsOptionsSchema, RetryJobOptionsSchema, TimeTravelJobOptionsSchema, } from './schemas.js';
+import { BooleanResultSchema, CancelJobOptionsSchema, CancelJobStepOptionsSchema, CompleteJobOptionsSchema, CompleteJobStepOptionsSchema, CreateJobOptionsSchema, CreateOrRecoverJobStepOptionsSchema, CreateOrRecoverJobStepResultNullableSchema, DelayJobStepOptionsSchema, DeleteJobOptionsSchema, DeleteJobsOptionsSchema, DeleteSpansOptionsSchema, FailJobOptionsSchema, FailJobStepOptionsSchema, FetchOptionsSchema, GetActionsResultSchema, GetJobStepsOptionsSchema, GetJobStepsResultSchema, GetJobsOptionsSchema, GetJobsResultSchema, GetSpansOptionsSchema, GetSpansResultSchema, InsertSpanOptionsSchema, JobIdResultSchema, JobSchema, JobStatusResultSchema, JobStepSchema, JobStepStatusResultSchema, JobsArrayResultSchema, NumberResultSchema, RecoverJobsOptionsSchema, RetryJobOptionsSchema, TimeTravelJobOptionsSchema, } from './schemas.js';
+// ============================================================================
+// Abstract Adapter Class
+// ============================================================================
+/**
+ * Abstract base class for database adapters.
+ * All adapters must extend this class and implement its abstract methods.
+ */
 export class Adapter extends EventEmitter {
     #id;
     #started = false;
@@ -9,6 +16,15 @@ export class Adapter extends EventEmitter {
     #starting = null;
     #stopping = null;
     #logger = null;
+    // ============================================================================
+    // Lifecycle Methods
+    // ============================================================================
+    /**
+     * Start the adapter.
+     * Performs any necessary initialization, such as running migrations or setting up listeners.
+     *
+     * @returns Promise resolving to `true` if started successfully, `false` otherwise
+     */
     async start() {
         try {
             if (!this.#id) {
@@ -36,6 +52,12 @@ export class Adapter extends EventEmitter {
             throw error;
         }
     }
+    /**
+     * Stop the adapter.
+     * Performs cleanup, such as closing database connections.
+     *
+     * @returns Promise resolving to `true` if stopped successfully, `false` otherwise
+     */
     async stop() {
         try {
             if (this.#stopped) {
@@ -57,6 +79,15 @@ export class Adapter extends EventEmitter {
             throw error;
         }
     }
+    // ============================================================================
+    // Configuration Methods
+    // ============================================================================
+    /**
+     * Set the unique identifier for this adapter instance.
+     * Used for multi-process coordination and job ownership.
+     *
+     * @param id - The unique identifier for this adapter instance
+     */
     setId(id) {
         try {
             this.#id = id;
@@ -66,6 +97,11 @@ export class Adapter extends EventEmitter {
             throw error;
         }
     }
+    /**
+     * Set the logger instance for this adapter.
+     *
+     * @param logger - The logger instance to use for logging
+     */
     setLogger(logger) {
         try {
             this.#logger = logger;
@@ -75,12 +111,30 @@ export class Adapter extends EventEmitter {
             throw error;
         }
     }
+    /**
+     * Get the unique identifier for this adapter instance.
+     *
+     * @returns The unique identifier for this adapter instance
+     */
     get id() {
         return this.#id;
     }
+    /**
+     * Get the logger instance for this adapter.
+     *
+     * @returns The logger instance, or `null` if not set
+     */
     get logger() {
         return this.#logger;
     }
+    // ============================================================================
+    // Job Methods
+    // ============================================================================
+    /**
+     * Create a new job in the database.
+     *
+     * @returns Promise resolving to the job ID, or `null` if creation failed
+     */
     async createJob(options) {
         try {
             await this.start();
@@ -97,6 +151,11 @@ export class Adapter extends EventEmitter {
             throw error;
         }
     }
+    /**
+     * Mark a job as completed.
+     *
+     * @returns Promise resolving to `true` if completed, `false` otherwise
+     */
     async completeJob(options) {
         try {
             await this.start();
@@ -117,6 +176,11 @@ export class Adapter extends EventEmitter {
             throw error;
         }
     }
+    /**
+     * Mark a job as failed.
+     *
+     * @returns Promise resolving to `true` if failed, `false` otherwise
+     */
     async failJob(options) {
         try {
             await this.start();
@@ -137,6 +201,11 @@ export class Adapter extends EventEmitter {
             throw error;
         }
     }
+    /**
+     * Cancel a job.
+     *
+     * @returns Promise resolving to `true` if cancelled, `false` otherwise
+     */
     async cancelJob(options) {
         try {
             await this.start();
@@ -157,6 +226,11 @@ export class Adapter extends EventEmitter {
             throw error;
         }
     }
+    /**
+     * Retry a failed job by creating a copy of it with status 'created' and cleared output/error.
+     *
+     * @returns Promise resolving to the job ID, or `null` if creation failed
+     */
     async retryJob(options) {
         try {
             await this.start();
@@ -173,6 +247,14 @@ export class Adapter extends EventEmitter {
             throw error;
         }
     }
+    /**
+     * Time travel a job to restart from a specific step.
+     * The job must be in completed, failed, or cancelled status.
+     * Resets the job and ancestor steps to active status, deletes subsequent steps,
+     * and preserves completed parallel siblings.
+     *
+     * @returns Promise resolving to `true` if time travel succeeded, `false` otherwise
+     */
     async timeTravelJob(options) {
         try {
             await this.start();
@@ -189,6 +271,12 @@ export class Adapter extends EventEmitter {
             throw error;
         }
     }
+    /**
+     * Delete a job by its ID.
+     * Active jobs cannot be deleted.
+     *
+     * @returns Promise resolving to `true` if deleted, `false` otherwise
+     */
     async deleteJob(options) {
         try {
             await this.start();
@@ -201,6 +289,12 @@ export class Adapter extends EventEmitter {
             throw error;
         }
     }
+    /**
+     * Delete multiple jobs using the same filters as getJobs.
+     * Active jobs cannot be deleted and will be excluded from deletion.
+     *
+     * @returns Promise resolving to the number of jobs deleted
+     */
     async deleteJobs(options) {
         try {
             await this.start();
@@ -213,6 +307,11 @@ export class Adapter extends EventEmitter {
             throw error;
         }
     }
+    /**
+     * Fetch jobs from the database respecting concurrency limits per group.
+     *
+     * @returns Promise resolving to an array of fetched jobs
+     */
     async fetch(options) {
         try {
             await this.start();
@@ -225,6 +324,11 @@ export class Adapter extends EventEmitter {
             throw error;
         }
     }
+    /**
+     * Recover stuck jobs (jobs that were active but the process that owned them is no longer running).
+     *
+     * @returns Promise resolving to the number of jobs recovered
+     */
     async recoverJobs(options) {
         try {
             await this.start();
@@ -237,6 +341,14 @@ export class Adapter extends EventEmitter {
             throw error;
         }
     }
+    // ============================================================================
+    // Step Methods
+    // ============================================================================
+    /**
+     * Create or recover a job step by creating or resetting a step record in the database.
+     *
+     * @returns Promise resolving to the step, or `null` if creation failed
+     */
     async createOrRecoverJobStep(options) {
         try {
             await this.start();
@@ -249,6 +361,11 @@ export class Adapter extends EventEmitter {
             throw error;
         }
     }
+    /**
+     * Mark a job step as completed.
+     *
+     * @returns Promise resolving to `true` if completed, `false` otherwise
+     */
     async completeJobStep(options) {
         try {
             await this.start();
@@ -256,6 +373,7 @@ export class Adapter extends EventEmitter {
             const result = await this._completeJobStep(parsedOptions);
             const success = BooleanResultSchema.parse(result);
             if (success) {
+                // Fetch jobId for notification
                 const step = await this._getJobStepById(parsedOptions.stepId);
                 if (step) {
                     await this._notify('step-status-changed', {
@@ -274,6 +392,11 @@ export class Adapter extends EventEmitter {
             throw error;
         }
     }
+    /**
+     * Mark a job step as failed.
+     *
+     * @returns Promise resolving to `true` if failed, `false` otherwise
+     */
     async failJobStep(options) {
         try {
             await this.start();
@@ -281,6 +404,7 @@ export class Adapter extends EventEmitter {
             const result = await this._failJobStep(parsedOptions);
             const success = BooleanResultSchema.parse(result);
             if (success) {
+                // Fetch jobId for notification
                 const step = await this._getJobStepById(parsedOptions.stepId);
                 if (step) {
                     await this._notify('step-status-changed', {
@@ -299,6 +423,11 @@ export class Adapter extends EventEmitter {
             throw error;
         }
     }
+    /**
+     * Delay a job step.
+     *
+     * @returns Promise resolving to `true` if delayed, `false` otherwise
+     */
     async delayJobStep(options) {
         try {
             await this.start();
@@ -306,6 +435,7 @@ export class Adapter extends EventEmitter {
             const result = await this._delayJobStep(parsedOptions);
             const success = BooleanResultSchema.parse(result);
             if (success) {
+                // Fetch jobId for notification
                 const step = await this._getJobStepById(parsedOptions.stepId);
                 if (step) {
                     await this._notify('step-delayed', {
@@ -324,6 +454,11 @@ export class Adapter extends EventEmitter {
             throw error;
         }
     }
+    /**
+     * Cancel a job step.
+     *
+     * @returns Promise resolving to `true` if cancelled, `false` otherwise
+     */
     async cancelJobStep(options) {
         try {
             await this.start();
@@ -331,6 +466,7 @@ export class Adapter extends EventEmitter {
             const result = await this._cancelJobStep(parsedOptions);
             const success = BooleanResultSchema.parse(result);
             if (success) {
+                // Fetch jobId for notification
                 const step = await this._getJobStepById(parsedOptions.stepId);
                 if (step) {
                     await this._notify('step-status-changed', {
@@ -349,6 +485,15 @@ export class Adapter extends EventEmitter {
             throw error;
         }
     }
+    // ============================================================================
+    // Query Methods
+    // ============================================================================
+    /**
+     * Get a job by its ID. Does not include step information.
+     *
+     * @param jobId - The ID of the job to retrieve
+     * @returns Promise resolving to the job, or `null` if not found
+     */
     async getJobById(jobId) {
         try {
             const parsedJobId = z.string().parse(jobId);
@@ -363,6 +508,14 @@ export class Adapter extends EventEmitter {
             throw error;
         }
     }
+    /**
+     * Get steps for a job with pagination and fuzzy search.
+     * Steps are always ordered by created_at ASC.
+     * Steps do not include output data.
+     *
+     * @param options - Query options including jobId, pagination, and search
+     * @returns Promise resolving to steps result with pagination info
+     */
     async getJobSteps(options) {
         try {
             const parsedOptions = GetJobStepsOptionsSchema.parse(options);
@@ -374,6 +527,13 @@ export class Adapter extends EventEmitter {
             throw error;
         }
     }
+    /**
+     * Get jobs with pagination, filtering, and sorting.
+     * Does not include step information or job output.
+     *
+     * @param options - Query options including pagination, filters, and sort
+     * @returns Promise resolving to jobs result with pagination info
+     */
     async getJobs(options) {
         try {
             const parsedOptions = options ? GetJobsOptionsSchema.parse(options) : undefined;
@@ -385,6 +545,12 @@ export class Adapter extends EventEmitter {
             throw error;
         }
     }
+    /**
+     * Get a step by its ID with all information.
+     *
+     * @param stepId - The ID of the step to retrieve
+     * @returns Promise resolving to the step, or `null` if not found
+     */
     async getJobStepById(stepId) {
         try {
             const parsedStepId = z.string().parse(stepId);
@@ -399,6 +565,12 @@ export class Adapter extends EventEmitter {
             throw error;
         }
     }
+    /**
+     * Get job status and updatedAt timestamp.
+     *
+     * @param jobId - The ID of the job
+     * @returns Promise resolving to job status result, or `null` if not found
+     */
     async getJobStatus(jobId) {
         try {
             const parsedJobId = z.string().parse(jobId);
@@ -413,6 +585,12 @@ export class Adapter extends EventEmitter {
             throw error;
         }
     }
+    /**
+     * Get job step status and updatedAt timestamp.
+     *
+     * @param stepId - The ID of the step
+     * @returns Promise resolving to step status result, or `null` if not found
+     */
     async getJobStepStatus(stepId) {
         try {
             const parsedStepId = z.string().parse(stepId);
@@ -427,6 +605,11 @@ export class Adapter extends EventEmitter {
             throw error;
         }
     }
+    /**
+     * Get action statistics including counts and last job created date.
+     *
+     * @returns Promise resolving to action statistics
+     */
     async getActions() {
         try {
             const result = await this._getActions();
@@ -437,45 +620,68 @@ export class Adapter extends EventEmitter {
             throw error;
         }
     }
-    async insertMetrics(metrics) {
+    // ============================================================================
+    // Span Methods (OpenTelemetry)
+    // ============================================================================
+    /**
+     * Insert multiple span records in a single batch operation.
+     * Used by LocalSpanExporter to store spans from the OpenTelemetry SDK.
+     *
+     * @param spans - Array of span data to insert
+     * @returns Promise resolving to the number of spans inserted
+     */
+    async insertSpans(spans) {
         try {
-            if (metrics.length === 0) {
+            if (spans.length === 0) {
                 return 0;
             }
             await this.start();
-            const parsedMetrics = metrics.map((m) => InsertMetricOptionsSchema.parse(m));
-            const result = await this._insertMetrics(parsedMetrics);
+            const parsedSpans = spans.map((s) => InsertSpanOptionsSchema.parse(s));
+            const result = await this._insertSpans(parsedSpans);
             return NumberResultSchema.parse(result);
         }
         catch (error) {
-            this.#logger?.error(error, 'Error in Adapter.insertMetrics()');
+            this.#logger?.error(error, 'Error in Adapter.insertSpans()');
             throw error;
         }
     }
-    async getMetrics(options) {
+    /**
+     * Get spans for a job or step.
+     *
+     * @param options - Query options including jobId/stepId, filters, and sort
+     * @returns Promise resolving to spans result
+     */
+    async getSpans(options) {
         try {
             await this.start();
-            const parsedOptions = GetMetricsOptionsSchema.parse(options);
+            const parsedOptions = GetSpansOptionsSchema.parse(options);
+            // Validate that at least one of jobId or stepId is provided
             if (!parsedOptions.jobId && !parsedOptions.stepId) {
                 throw new Error('At least one of jobId or stepId must be provided');
             }
-            const result = await this._getMetrics(parsedOptions);
-            return GetMetricsResultSchema.parse(result);
+            const result = await this._getSpans(parsedOptions);
+            return GetSpansResultSchema.parse(result);
         }
         catch (error) {
-            this.#logger?.error(error, 'Error in Adapter.getMetrics()');
+            this.#logger?.error(error, 'Error in Adapter.getSpans()');
             throw error;
         }
     }
-    async deleteMetrics(options) {
+    /**
+     * Delete all spans for a job.
+     *
+     * @param options - Options containing the jobId
+     * @returns Promise resolving to the number of spans deleted
+     */
+    async deleteSpans(options) {
         try {
             await this.start();
-            const parsedOptions = DeleteMetricsOptionsSchema.parse(options);
-            const result = await this._deleteMetrics(parsedOptions);
+            const parsedOptions = DeleteSpansOptionsSchema.parse(options);
+            const result = await this._deleteSpans(parsedOptions);
             return NumberResultSchema.parse(result);
         }
         catch (error) {
-            this.#logger?.error(error, 'Error in Adapter.deleteMetrics()');
+            this.#logger?.error(error, 'Error in Adapter.deleteSpans()');
             throw error;
         }
     }