duron 0.3.0-beta.5 → 0.3.0-beta.7

package/dist/telemetry/opentelemetry.js

@@ -5,6 +5,7 @@ export class OpenTelemetryAdapter extends TelemetryAdapter {
     #traceDatabaseQueries;
     #tracer = null;
     #spanMap = new Map();
+    #tracerCache = new Map();
     constructor(options = {}) {
         super();
         this.#serviceName = options.serviceName ?? 'duron';
@@ -198,5 +199,114 @@ export class OpenTelemetryAdapter extends TelemetryAdapter {
             extSpan.otelSpan.setAttribute(options.key, options.value);
         }
     }
+    _getTracer(name) {
+        const cached = this.#tracerCache.get(name);
+        if (cached) {
+            return cached;
+        }
+        const adapter = this;
+        const tracer = {
+            name,
+            startSpan(spanName, options) {
+                let otelSpan = null;
+                let api = null;
+                let ended = false;
+                const initPromise = (async () => {
+                    api = await import('@opentelemetry/api');
+                    let otelTracer;
+                    if (adapter.#tracerProvider) {
+                        otelTracer = adapter.#tracerProvider.getTracer(name);
+                    }
+                    else {
+                        otelTracer = api.trace.getTracer(name);
+                    }
+                    let spanKind = api.SpanKind.INTERNAL;
+                    if (options?.kind === 'client')
+                        spanKind = api.SpanKind.CLIENT;
+                    else if (options?.kind === 'server')
+                        spanKind = api.SpanKind.SERVER;
+                    else if (options?.kind === 'producer')
+                        spanKind = api.SpanKind.PRODUCER;
+                    else if (options?.kind === 'consumer')
+                        spanKind = api.SpanKind.CONSUMER;
+                    let parentContext = api.context.active();
+                    if (options?.parentSpan) {
+                        const parentOtelSpan = options.parentSpan._otelSpan;
+                        if (parentOtelSpan) {
+                            parentContext = api.trace.setSpan(api.context.active(), parentOtelSpan);
+                        }
+                    }
+                    otelSpan = otelTracer.startSpan(spanName, {
+                        kind: spanKind,
+                        attributes: options?.attributes,
+                    }, parentContext);
+                })();
+                const tracerSpan = {
+                    setAttribute(key, value) {
+                        initPromise.then(() => {
+                            if (otelSpan && !ended) {
+                                otelSpan.setAttribute(key, value);
+                            }
+                        });
+                    },
+                    setAttributes(attributes) {
+                        initPromise.then(() => {
+                            if (otelSpan && !ended) {
+                                otelSpan.setAttributes(attributes);
+                            }
+                        });
+                    },
+                    addEvent(eventName, attributes) {
+                        initPromise.then(() => {
+                            if (otelSpan && !ended) {
+                                otelSpan.addEvent(eventName, attributes);
+                            }
+                        });
+                    },
+                    recordException(error) {
+                        initPromise.then(() => {
+                            if (otelSpan && !ended) {
+                                otelSpan.recordException(error);
+                            }
+                        });
+                    },
+                    setStatusOk() {
+                        initPromise.then(() => {
+                            if (otelSpan && api && !ended) {
+                                otelSpan.setStatus({ code: api.SpanStatusCode.OK });
+                            }
+                        });
+                    },
+                    setStatusError(message) {
+                        initPromise.then(() => {
+                            if (otelSpan && api && !ended) {
+                                otelSpan.setStatus({ code: api.SpanStatusCode.ERROR, message });
+                            }
+                        });
+                    },
+                    end() {
+                        initPromise.then(() => {
+                            if (otelSpan && !ended) {
+                                ended = true;
+                                otelSpan.end();
+                            }
+                        });
+                    },
+                    isRecording() {
+                        return otelSpan?.isRecording() ?? false;
+                    },
+                };
+                initPromise.then(() => {
+                    if (otelSpan) {
+                        ;
+                        tracerSpan._otelSpan = otelSpan;
+                    }
+                });
+                return tracerSpan;
+            },
+        };
+        this.#tracerCache.set(name, tracer);
+        return tracer;
+    }
 }
 export const openTelemetryAdapter = (options) => new OpenTelemetryAdapter(options);

package/migrations/postgres/20260119153838_flimsy_thor_girl/snapshot.json

@@ -2,9 +2,7 @@
   "version": "8",
   "dialect": "postgres",
   "id": "4e93c0bf-b135-40b4-b130-0cf0968bffe3",
-  "prevIds": [
-    "00000000-0000-0000-0000-000000000000"
-  ],
+  "prevIds": ["00000000-0000-0000-0000-000000000000"],
   "ddl": [
     {
       "name": "duron",
@@ -1268,14 +1266,10 @@
     },
     {
       "nameExplicit": false,
-      "columns": [
-        "job_id"
-      ],
+      "columns": ["job_id"],
       "schemaTo": "duron",
       "tableTo": "jobs",
-      "columnsTo": [
-        "id"
-      ],
+      "columnsTo": ["id"],
       "onUpdate": "NO ACTION",
       "onDelete": "CASCADE",
       "name": "job_steps_job_id_jobs_id_fkey",
@@ -1285,14 +1279,10 @@
     },
     {
       "nameExplicit": false,
-      "columns": [
-        "job_id"
-      ],
+      "columns": ["job_id"],
       "schemaTo": "duron",
       "tableTo": "jobs",
-      "columnsTo": [
-        "id"
-      ],
+      "columnsTo": ["id"],
       "onUpdate": "NO ACTION",
       "onDelete": "CASCADE",
       "name": "metrics_job_id_jobs_id_fkey",
@@ -1302,14 +1292,10 @@
     },
     {
       "nameExplicit": false,
-      "columns": [
-        "step_id"
-      ],
+      "columns": ["step_id"],
       "schemaTo": "duron",
       "tableTo": "job_steps",
-      "columnsTo": [
-        "id"
-      ],
+      "columnsTo": ["id"],
       "onUpdate": "NO ACTION",
       "onDelete": "CASCADE",
       "name": "metrics_step_id_job_steps_id_fkey",
@@ -1318,9 +1304,7 @@
       "table": "metrics"
     },
     {
-      "columns": [
-        "id"
-      ],
+      "columns": ["id"],
       "nameExplicit": false,
       "name": "job_steps_pkey",
       "schema": "duron",
@@ -1328,9 +1312,7 @@
       "entityType": "pks"
     },
     {
-      "columns": [
-        "id"
-      ],
+      "columns": ["id"],
       "nameExplicit": false,
       "name": "jobs_pkey",
       "schema": "duron",
@@ -1338,9 +1320,7 @@
       "entityType": "pks"
     },
     {
-      "columns": [
-        "id"
-      ],
+      "columns": ["id"],
       "nameExplicit": false,
       "name": "metrics_pkey",
       "schema": "duron",
@@ -1349,11 +1329,7 @@
     },
     {
       "nameExplicit": true,
-      "columns": [
-        "job_id",
-        "name",
-        "parent_step_id"
-      ],
+      "columns": ["job_id", "name", "parent_step_id"],
       "nullsNotDistinct": true,
       "name": "unique_job_step_name_parent",
       "entityType": "uniques",
@@ -1383,4 +1359,4 @@
     }
   ],
   "renames": []
-}
+}

package/package.json

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

package/src/action.ts

@@ -133,18 +133,13 @@ export interface StepDefinitionHandlerContext<TInput extends z.ZodObject, TVaria
    * The job ID this step belongs to.
    */
   jobId: string
-
 }
 
 /**
  * A reusable step definition created with createStep().
  * Can be executed within an action handler using ctx.run().
  */
-export interface StepDefinition<
-  TInput extends z.ZodObject,
-  TResult,
-  TVariables = Record<string, unknown>,
-> {
+export interface StepDefinition<TInput extends z.ZodObject, TResult, TVariables = Record<string, unknown>> {
   /**
    * The name of the step.
    * Can be a static string or a function that generates the name from the input.
@@ -417,11 +412,10 @@ export const defineAction = <TVariables = Record<string, unknown>>() => {
 /**
  * Input type for createStep() - the definition object before transformation.
  */
-export type StepDefinitionInput<
-  TInput extends z.ZodObject,
-  TResult,
-  TVariables = Record<string, unknown>,
-> = Omit<StepDefinition<TInput, TResult, TVariables>, '__stepDefinition'>
+export type StepDefinitionInput<TInput extends z.ZodObject, TResult, TVariables = Record<string, unknown>> = Omit<
+  StepDefinition<TInput, TResult, TVariables>,
+  '__stepDefinition'
+>
 
 /**
  * Creates a reusable step definition that can be executed within action handlers.

package/src/adapters/postgres/schema.ts

@@ -119,7 +119,9 @@ export default function createSchema(schemaName: string) {
       index('idx_job_steps_output_fts').using('gin', sql`to_tsvector('english', ${table.output}::text)`),
       // Unique constraint - step name is unique within a parent (name + parentStepId)
       // nullsNotDistinct ensures NULL parent_step_id values are treated as equal for uniqueness
-      unique('unique_job_step_name_parent').on(table.job_id, table.name, table.parent_step_id).nullsNotDistinct(),
+      unique('unique_job_step_name_parent')
+        .on(table.job_id, table.name, table.parent_step_id)
+        .nullsNotDistinct(),
       check(
         'job_steps_status_check',
         sql`${table.status} IN ${sql.raw(`(${STEP_STATUSES.map((s) => `'${s}'`).join(',')})`)}`,

package/src/client.ts

@@ -20,6 +20,38 @@ import type { JobStatusResult, JobStepStatusResult } from './adapters/schemas.js
 import { JOB_STATUS_CANCELLED, JOB_STATUS_COMPLETED, JOB_STATUS_FAILED, type JobStatus } from './constants.js'
 import { LocalTelemetryAdapter, noopTelemetryAdapter, type TelemetryAdapter } from './telemetry/index.js'
 
+/**
+ * Extracts the inferred type from an action's input/output schema.
+ * Handles the case where the schema might be undefined.
+ */
+type InferActionSchema<T> = T extends z.ZodTypeAny ? z.infer<T> : Record<string, unknown>
+
+/**
+ * Result returned from waitForJob with untyped input and output.
+ */
+export interface JobResult {
+  jobId: string
+  actionName: string
+  status: JobStatus
+  groupKey: string
+  input: unknown
+  output: unknown
+  error: Job['error']
+}
+
+/**
+ * Result returned from runActionAndWait with typed input and output based on the action's Zod schemas.
+ */
+export interface TypedJobResult<TAction extends Action<any, any, any>> {
+  jobId: string
+  actionName: string
+  status: JobStatus
+  groupKey: string
+  input: InferActionSchema<NonNullable<TAction['input']>>
+  output: InferActionSchema<NonNullable<TAction['output']>>
+  error: Job['error']
+}
+
 const BaseOptionsSchema = z.object({
   /**
    * Unique identifier for this Duron instance.
@@ -184,7 +216,7 @@ export class Client<
   #pendingJobWaits = new Map<
     string,
     Set<{
-      resolve: (job: Job | null) => void
+      resolve: (result: JobResult | null) => void
       timeoutId?: NodeJS.Timeout
       signal?: AbortSignal
       abortHandler?: () => void
@@ -335,6 +367,132 @@ export class Client<
     return jobId
   }
 
+  /**
+   * Run an action and wait for its completion.
+   * This is a convenience method that combines `runAction` and `waitForJob`.
+   *
+   * @param actionName - Name of the action to run
+   * @param input - Input data for the action (validated against action's input schema if provided)
+   * @param options - Options including abort signal and timeout
+   * @returns Promise resolving to the job result with typed input and output
+   * @throws Error if action is not found, job creation fails, job is cancelled, or operation is aborted
+   */
+  async runActionAndWait<TActionName extends keyof TActions>(
+    actionName: TActionName,
+    input?: NonNullable<TActions[TActionName]['input']> extends z.ZodObject
+      ? z.input<NonNullable<TActions[TActionName]['input']>>
+      : never,
+    options?: {
+      /**
+       * AbortSignal to cancel the operation. If aborted, the job will be cancelled and the promise will reject.
+       */
+      signal?: AbortSignal
+      /**
+       * Timeout in milliseconds. If the job doesn't complete within this time, the job will be cancelled and the promise will reject.
+       */
+      timeout?: number
+    },
+  ): Promise<TypedJobResult<TActions[TActionName]>> {
+    // Check if already aborted before starting
+    if (options?.signal?.aborted) {
+      throw new Error('Operation was aborted')
+    }
+
+    // Create the job
+    const jobId = await this.runAction(actionName, input)
+
+    // Set up abort handler to cancel the job if signal is aborted
+    let abortHandler: (() => void) | undefined
+    if (options?.signal) {
+      abortHandler = () => {
+        this.cancelJob(jobId).catch((err) => {
+          this.#logger.error({ err, jobId }, '[Duron] Error cancelling job on abort')
+        })
+      }
+      options.signal.addEventListener('abort', abortHandler, { once: true })
+    }
+
+    // Set up timeout handler to cancel the job if timeout is reached
+    let timeoutId: NodeJS.Timeout | undefined
+    let timeoutAbortController: AbortController | undefined
+    if (options?.timeout) {
+      timeoutAbortController = new AbortController()
+      timeoutId = setTimeout(() => {
+        timeoutAbortController!.abort()
+        this.cancelJob(jobId).catch((err) => {
+          this.#logger.error({ err, jobId }, '[Duron] Error cancelling job on timeout')
+        })
+      }, options.timeout)
+    }
+
+    try {
+      // Combine signals if both are provided
+      let waitSignal: AbortSignal | undefined
+      if (options?.signal && timeoutAbortController) {
+        waitSignal = AbortSignal.any([options.signal, timeoutAbortController.signal])
+      } else if (options?.signal) {
+        waitSignal = options.signal
+      } else if (timeoutAbortController) {
+        waitSignal = timeoutAbortController.signal
+      }
+
+      // Wait for the job to complete
+      const job = await this.waitForJob(jobId, { signal: waitSignal })
+
+      // Clean up
+      if (timeoutId) {
+        clearTimeout(timeoutId)
+      }
+      if (options?.signal && abortHandler) {
+        options.signal.removeEventListener('abort', abortHandler)
+      }
+
+      // Handle null result (aborted or timed out)
+      if (!job) {
+        if (options?.signal?.aborted) {
+          throw new Error('Operation was aborted')
+        }
+        if (timeoutAbortController?.signal.aborted) {
+          throw new Error('Operation timed out')
+        }
+        throw new Error('Job not found')
+      }
+
+      // Handle cancelled job
+      if (job.status === JOB_STATUS_CANCELLED) {
+        if (options?.signal?.aborted) {
+          throw new Error('Operation was aborted')
+        }
+        if (timeoutAbortController?.signal.aborted) {
+          throw new Error('Operation timed out')
+        }
+        throw new Error('Job was cancelled')
+      }
+
+      // Handle failed job
+      if (job.status === JOB_STATUS_FAILED) {
+        const errorMessage = job.error?.message ?? 'Job failed'
+        const error = new Error(errorMessage)
+        if (job.error?.stack) {
+          error.stack = job.error.stack
+        }
+        throw error
+      }
+
+      // Return the job result with typed input/output
+      return job as TypedJobResult<TActions[TActionName]>
+    } catch (err) {
+      // Clean up on error
+      if (timeoutId) {
+        clearTimeout(timeoutId)
+      }
+      if (options?.signal && abortHandler) {
+        options.signal.removeEventListener('abort', abortHandler)
+      }
+      throw err
+    }
+  }
+
   /**
    * Fetch and process jobs from the database.
    * Concurrency limits are determined from the latest job created for each groupKey.
@@ -515,11 +673,11 @@ export class Client<
 
   /**
    * Wait for a job to change status by subscribing to job-status-changed events.
-   * When the job status changes, the job is fetched and returned.
+   * When the job status changes, the job result is returned.
    *
    * @param jobId - The ID of the job to wait for
    * @param options - Optional configuration including timeout
-   * @returns Promise resolving to the job when its status changes, or `null` if timeout
+   * @returns Promise resolving to the job result when its status changes, or `null` if timeout
    */
   async waitForJob(
     jobId: string,
@@ -534,7 +692,7 @@ export class Client<
        */
       signal?: AbortSignal
     },
-  ): Promise<Job | null> {
+  ): Promise<JobResult | null> {
     await this.start()
 
     // First, check if the job already exists and is in a terminal state
@@ -546,14 +704,22 @@ export class Client<
         if (!job) {
           return null
         }
-        return job
+        return {
+          jobId: job.id,
+          actionName: job.actionName,
+          status: job.status,
+          groupKey: job.groupKey,
+          input: job.input,
+          output: job.output,
+          error: job.error,
+        }
       }
     }
 
     // Set up the shared event listener if not already set up
     this.#setupJobStatusListener()
 
-    return new Promise<Job | null>((resolve) => {
+    return new Promise<JobResult | null>((resolve) => {
       // Check if already aborted before setting up wait
       if (options?.signal?.aborted) {
         resolve(null)
@@ -796,6 +962,19 @@ export class Client<
         // Fetch the job once for all pending waits
         const job = await this.getJobById(event.jobId)
 
+        // Transform to JobResult
+        const result: JobResult | null = job
+          ? {
+              jobId: job.id,
+              actionName: job.actionName,
+              status: job.status,
+              groupKey: job.groupKey,
+              input: job.input,
+              output: job.output,
+              error: job.error,
+            }
+          : null
+
         // Resolve all pending waits for this job
         const waitsToResolve = Array.from(pendingWaits)
         this.#pendingJobWaits.delete(event.jobId)
@@ -808,7 +987,7 @@ export class Client<
           if (wait.signal && wait.abortHandler) {
             wait.signal.removeEventListener('abort', wait.abortHandler)
           }
-          wait.resolve(job)
+          wait.resolve(result)
         }
       },
     )
@@ -820,7 +999,7 @@ export class Client<
    * @param jobId - The job ID
    * @param resolve - The resolve function to remove
    */
-  #removeJobWait(jobId: string, resolve: (job: Job | null) => void) {
+  #removeJobWait(jobId: string, resolve: (result: JobResult | null) => void) {
     const pendingWaits = this.#pendingJobWaits.get(jobId)
     if (!pendingWaits) {
       return

package/src/step-manager.ts

@@ -23,7 +23,46 @@ import {
   serializeError,
   UnhandledChildStepsError,
 } from './errors.js'
-import type { ObserveContext, Span, TelemetryAdapter } from './telemetry/adapter.js'
+import type { ObserveContext, Span, TelemetryAdapter, Tracer, TracerSpan } from './telemetry/adapter.js'
+
+// ============================================================================
+// Noop Tracer (for fallback observe context)
+// ============================================================================
+
+const noopTracerSpan: TracerSpan = {
+  setAttribute() {
+    // No-op
+  },
+  setAttributes() {
+    // No-op
+  },
+  addEvent() {
+    // No-op
+  },
+  recordException() {
+    // No-op
+  },
+  setStatusOk() {
+    // No-op
+  },
+  setStatusError() {
+    // No-op
+  },
+  end() {
+    // No-op
+  },
+  isRecording() {
+    return false
+  },
+}
+
+const createNoopTracer = (name: string): Tracer => ({
+  name,
+  startSpan(): TracerSpan {
+    return noopTracerSpan
+  },
+})
+
 import pRetry from './utils/p-retry.js'
 import waitForAbort from './utils/wait-for-abort.js'
 
@@ -251,6 +290,9 @@ export class StepManager {
       addSpanEvent: () => {
         // No-op
       },
+      getTracer: (name: string) => {
+        return createNoopTracer(name)
+      },
     }
   }