duron 0.3.0-beta.9 → 0.3.0

package/dist/step-manager.d.ts

@@ -1,9 +1,34 @@
+import { type Span, type Tracer } from '@opentelemetry/api';
 import type { Logger } from 'pino';
 import type { z } from 'zod';
 import { type Action, type ActionHandlerContext, type StepHandlerContext, type StepOptions } from './action.js';
 import type { Adapter } from './adapters/adapter.js';
 import { type StepStatus } from './constants.js';
-import type { ObserveContext, Span, TelemetryAdapter } from './telemetry/adapter.js';
+/**
+ * Telemetry context provided to action and step handlers.
+ * Provides access to OpenTelemetry APIs for recording traces and metrics.
+ */
+export interface TelemetryContext {
+    /**
+     * Get the active OpenTelemetry span for the current job/step.
+     */
+    getActiveSpan(): Span | undefined;
+    /**
+     * Get an OpenTelemetry tracer for creating custom spans.
+     */
+    getTracer(name: string): Tracer;
+    /**
+     * Start a new span as a child of the current job/step span.
+     * This is a convenience method that properly links the span to the trace hierarchy.
+     */
+    startSpan(name: string, options?: {
+        attributes?: Record<string, any>;
+    }): Span;
+    /**
+     * Record a custom metric as a span event.
+     */
+    recordMetric(name: string, value: number, attributes?: Record<string, any>): void;
+}
 export interface TaskStep {
     name: string;
     cb: (ctx: StepHandlerContext) => Promise<any>;
@@ -12,9 +37,30 @@ export interface TaskStep {
     parentStepId: string | null;
     parallel: boolean;
 }
+/**
+ * StepStore manages step records in the database.
+ * Provides methods to create, update, and delay steps.
+ */
 export declare class StepStore {
     #private;
+    /**
+     * Create a new StepStore instance.
+     *
+     * @param adapter - The database adapter to use for step operations
+     */
     constructor(adapter: Adapter);
+    /**
+     * Get or create a step record in the database.
+     *
+     * @param jobId - The ID of the job this step belongs to
+     * @param name - The name of the step
+     * @param timeoutMs - Timeout in milliseconds for the step
+     * @param retriesLimit - Maximum number of retries for the step
+     * @param parentStepId - The ID of the parent step (null for root steps)
+     * @param parallel - Whether this step runs in parallel (independent from siblings during time travel)
+     * @returns Promise resolving to the created step ID
+     * @throws Error if step creation fails
+     */
     getOrCreate(jobId: string, name: string, timeoutMs: number, retriesLimit: number, parentStepId?: string | null, parallel?: boolean): Promise<{
         id: string;
         status: "active" | "completed" | "failed" | "cancelled";
@@ -25,29 +71,90 @@ export declare class StepStore {
         output: any;
         isNew: boolean;
     } | null>;
+    /**
+     * Update the status of a step in the database.
+     *
+     * @param stepId - The ID of the step to update
+     * @param status - The new status (completed, failed, or cancelled)
+     * @param output - Optional output data for completed steps
+     * @param error - Optional error data for failed steps
+     * @returns Promise resolving to `true` if update succeeded, `false` otherwise
+     */
     updateStatus(stepId: string, status: StepStatus, output?: any, error?: any): Promise<boolean>;
+    /**
+     * Delay a step execution.
+     * Used when a step fails and needs to be retried after a delay.
+     *
+     * @param stepId - The ID of the step to delay
+     * @param delayMs - The delay in milliseconds before retrying
+     * @param error - The error that caused the delay
+     * @returns Promise resolving to `true` if delayed successfully, `false` otherwise
+     */
     delay(stepId: string, delayMs: number, error: any): Promise<boolean>;
 }
 export interface StepManagerOptions {
     jobId: string;
     actionName: string;
     adapter: Adapter;
-    telemetry: TelemetryAdapter;
+    tracer: Tracer;
     logger: Logger;
     concurrencyLimit: number;
 }
+/**
+ * StepManager manages steps for a single ActionJob.
+ * Each ActionJob has its own StepManager instance.
+ */
 export declare class StepManager {
     #private;
+    /**
+     * Create a new StepManager instance.
+     *
+     * @param options - Configuration options for the step manager
+     */
     constructor(options: StepManagerOptions);
+    /**
+     * Set the job span for this step manager.
+     * Called from ActionJob after the job span is created.
+     */
     setJobSpan(span: Span): void;
+    /**
+     * Set the run function factory for executing step definitions from inline steps.
+     * Called from ActionContext after it's initialized.
+     *
+     * @param factory - A function that creates run functions with the correct parent step ID and abort signal
+     */
     setRunFnFactory(factory: (parentStepId: string | null, abortSignal: AbortSignal) => StepHandlerContext['run']): void;
+    /**
+     * Create an ActionContext for the action handler.
+     * The context provides access to input, variables, logger, and the step function.
+     *
+     * @param job - The job data including ID, input, and optional group key
+     * @param action - The action definition
+     * @param variables - Variables available to the action
+     * @param abortSignal - Abort signal for cancelling the action
+     * @param logger - Pino child logger for this job
+     * @returns ActionHandlerContext instance
+     */
     createActionContext<TInput extends z.ZodObject, TOutput extends z.ZodObject, TVariables = Record<string, unknown>>(job: {
         id: string;
         input: z.infer<TInput>;
         groupKey?: string;
-    }, action: Action<TInput, TOutput, TVariables>, variables: TVariables, abortSignal: AbortSignal, logger: Logger, observeContext: ObserveContext): ActionHandlerContext<TInput, TVariables>;
-    createStepObserveContext(stepId: string): ObserveContext;
+    }, action: Action<TInput, TOutput, TVariables>, variables: TVariables, abortSignal: AbortSignal, logger: Logger): ActionHandlerContext<TInput, TVariables>;
+    /**
+     * Create a telemetry context for a step.
+     */
+    createStepTelemetryContext(stepId: string): TelemetryContext;
+    /**
+     * Queue a step task for execution.
+     *
+     * @param task - The step task to queue
+     * @returns Promise resolving to the step result
+     */
     push(task: TaskStep): Promise<any>;
+    /**
+     * Clean up step queues by waiting for them to drain.
+     * Should be called when the job completes or is cancelled.
+     */
     drain(): Promise<void>;
 }
 //# sourceMappingURL=step-manager.d.ts.map

package/dist/step-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"step-manager.d.ts","sourceRoot":"","sources":["../src/step-manager.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAA;AAClC,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAE5B,OAAO,EACL,KAAK,MAAM,EACX,KAAK,oBAAoB,EAGzB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAEjB,MAAM,aAAa,CAAA;AACpB,OAAO,KAAK,EAAE,OAAO,EAAgC,MAAM,uBAAuB,CAAA;AAClF,OAAO,EAAoE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAYlH,OAAO,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,gBAAgB,EAAsB,MAAM,wBAAwB,CAAA;AA2CxG,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,OAAO,CAAC,GAAG,CAAC,CAAA;IAC7C,OAAO,EAAE,WAAW,CAAA;IACpB,WAAW,EAAE,WAAW,CAAA;IACxB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,QAAQ,EAAE,OAAO,CAAA;CAClB;AAMD,qBAAa,SAAS;;gBAYR,OAAO,EAAE,OAAO;IAoBtB,WAAW,CACf,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,YAAY,GAAE,MAAM,GAAG,IAAW,EAClC,QAAQ,GAAE,OAAe;;;;;;;;;;IAyBrB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC;IAoB7F,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC;CAG3E;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,OAAO,CAAA;IAChB,SAAS,EAAE,gBAAgB,CAAA;IAC3B,MAAM,EAAE,MAAM,CAAA;IACd,gBAAgB,EAAE,MAAM,CAAA;CACzB;AAMD,qBAAa,WAAW;;gBAyBV,OAAO,EAAE,kBAAkB;IAqBvC,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAU5B,eAAe,CAAC,OAAO,EAAE,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,EAAE,WAAW,EAAE,WAAW,KAAK,kBAAkB,CAAC,KAAK,CAAC,GAAG,IAAI;IAoBpH,mBAAmB,CAAC,MAAM,SAAS,CAAC,CAAC,SAAS,EAAE,OAAO,SAAS,CAAC,CAAC,SAAS,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/G,GAAG,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,EAC9D,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,EAC3C,SAAS,EAAE,UAAU,EACrB,WAAW,EAAE,WAAW,EACxB,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,cAAc,GAC7B,oBAAoB,CAAC,MAAM,EAAE,UAAU,CAAC;IAO3C,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc;IAgClD,IAAI,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC;IAuBlC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CA4T7B"}
+{"version":3,"file":"step-manager.d.ts","sourceRoot":"","sources":["../src/step-manager.ts"],"names":[],"mappings":"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"}