duron 0.3.0-beta.9 → 0.3.0

package/dist/constants.js

@@ -1,3 +1,6 @@
+// ============================================================================
+// Job Status Constants
+// ============================================================================
 export const JOB_STATUS_CREATED = 'created';
 export const JOB_STATUS_ACTIVE = 'active';
 export const JOB_STATUS_COMPLETED = 'completed';
@@ -10,6 +13,9 @@ export const JOB_STATUSES = [
     JOB_STATUS_FAILED,
     JOB_STATUS_CANCELLED,
 ];
+// ============================================================================
+// Step Status Constants
+// ============================================================================
 export const STEP_STATUS_ACTIVE = 'active';
 export const STEP_STATUS_COMPLETED = 'completed';
 export const STEP_STATUS_FAILED = 'failed';

package/dist/errors.d.ts

@@ -8,62 +8,199 @@ export declare const ERROR_CODES: {
     readonly UNHANDLED_CHILD_STEPS: "UNHANDLED_CHILD_STEPS";
 };
 export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+/**
+ * Metadata about the context where an error occurred.
+ */
+export interface ErrorMetadata {
+    jobId?: string;
+    stepId?: string;
+    parentStepId?: string | null;
+    actionName?: string;
+    stepName?: string;
+}
+/**
+ * Base class for all built-in errors in Duron.
+ * All errors include a cause property that can be serialized.
+ */
 export declare abstract class DuronError extends Error {
+    /**
+     * Error code for type checking without instanceof.
+     */
     readonly code: ErrorCode;
+    /**
+     * Whether this error should prevent retries.
+     */
     readonly nonRetriable: boolean;
+    /**
+     * The underlying cause of the error, if any.
+     *
+     * This will be serialized and stored in the database.
+     */
     readonly cause?: unknown;
+    /**
+     * Metadata about the context where the error occurred.
+     */
+    metadata: ErrorMetadata;
     constructor(message: string, options?: {
+        /**
+         * The underlying cause of the error, if any.
+         *
+         * This will be serialized and stored in the database.
+         */
         cause?: unknown;
+        /**
+         * Metadata about the context where the error occurred.
+         */
+        metadata?: ErrorMetadata;
     });
+    /**
+     * Set or update metadata about the context where the error occurred.
+     * Merges with existing metadata (new values override existing ones).
+     *
+     * @param metadata - The metadata to set or merge
+     * @returns this - Returns the error instance for chaining
+     */
+    setMetadata(metadata: ErrorMetadata): this;
 }
+/**
+ * Error thrown when attempting to execute a step that has already been executed.
+ */
 export declare class StepAlreadyExecutedError extends DuronError {
     readonly code: "STEP_ALREADY_EXECUTED";
     readonly nonRetriable = true;
+    /**
+     * Create a new StepAlreadyExecutedError.
+     *
+     * @param stepName - The name of the step that was already executed
+     * @param jobId - The ID of the job containing the step
+     * @param actionName - The name of the action containing the step
+     */
     constructor(stepName: string, jobId: string, actionName: string);
 }
+/**
+ * NonRetriableError indicates that a step should not be retried.
+ *
+ * If a step handler throws this error, the step will fail immediately
+ * without retrying, even if retry options are configured.
+ */
 export declare class NonRetriableError extends DuronError {
     readonly code: ErrorCode;
     readonly nonRetriable = true;
 }
+/**
+ * Error thrown when an action exceeds its timeout.
+ */
 export declare class ActionTimeoutError extends DuronError {
     readonly code: "ACTION_TIMEOUT";
     readonly nonRetriable = true;
-    constructor(actionName: string, timeoutMs: number, options?: {
+    /**
+     * Create a new ActionTimeoutError.
+     *
+     * @param actionName - The name of the action that timed out
+     * @param jobId - The ID of the job containing the action
+     * @param timeoutMs - The timeout value in milliseconds
+     * @param options - Optional error options including cause
+     */
+    constructor(actionName: string, jobId: string, timeoutMs: number, options?: {
         cause?: unknown;
     });
 }
+/**
+ * Error thrown when a step exceeds its timeout.
+ */
 export declare class StepTimeoutError extends DuronError {
     readonly code: "STEP_TIMEOUT";
     readonly nonRetriable = false;
+    /**
+     * Create a new StepTimeoutError.
+     *
+     * @param stepName - The name of the step that timed out
+     * @param jobId - The ID of the job containing the step
+     * @param timeoutMs - The timeout value in milliseconds
+     * @param options - Optional error options including cause and additional metadata
+     */
     constructor(stepName: string, jobId: string, timeoutMs: number, options?: {
         cause?: unknown;
+        stepId?: string;
+        parentStepId?: string | null;
+        actionName?: string;
     });
 }
+/**
+ * Error thrown when an action is cancelled.
+ */
 export declare class ActionCancelError extends DuronError {
     readonly code: "ACTION_CANCEL";
     readonly nonRetriable = true;
+    /**
+     * Create a new ActionCancelError.
+     *
+     * @param actionName - The name of the action that was cancelled
+     * @param jobId - The ID of the job containing the action
+     * @param options - Optional error options including cause
+     */
     constructor(actionName: string, jobId: string, options?: {
         cause?: unknown;
     });
 }
+/**
+ * Error thrown when a parent step completes with unhandled (non-awaited) child steps.
+ *
+ * This error indicates a bug in the action handler where child steps were started
+ * but not properly awaited. All child steps must be awaited before the parent returns.
+ */
 export declare class UnhandledChildStepsError extends NonRetriableError {
     readonly code: "UNHANDLED_CHILD_STEPS";
-    readonly stepName: string;
+    /**
+     * The number of unhandled child steps.
+     */
     readonly pendingCount: number;
-    constructor(stepName: string, pendingCount: number);
+    /**
+     * Create a new UnhandledChildStepsError.
+     *
+     * @param stepName - The name of the parent step
+     * @param pendingCount - The number of unhandled child steps
+     * @param options - Optional metadata
+     */
+    constructor(stepName: string, pendingCount: number, options?: {
+        stepId?: string;
+        parentStepId?: string | null;
+        jobId?: string;
+        actionName?: string;
+    });
 }
+/**
+ * Checks if an error is a DuronError instance.
+ */
 export declare function isDuronError(error: unknown): error is DuronError;
+/**
+ * Checks if an error is a NonRetriableError instance.
+ */
 export declare function isNonRetriableError(error: unknown): error is NonRetriableError;
+/**
+ * Checks if an error is an UnhandledChildStepsError instance.
+ */
 export declare function isUnhandledChildStepsError(error: unknown): error is UnhandledChildStepsError;
+/**
+ * Checks if an error is a timeout error (ActionTimeoutError or StepTimeoutError).
+ */
 export declare function isTimeoutError(error: unknown): error is ActionTimeoutError | StepTimeoutError;
+/**
+ * Checks if an error is a cancel error (ActionCancelError or StepCancelError).
+ */
 export declare function isCancelError(error: unknown): error is ActionCancelError;
 export type SerializableError = {
     name: string;
     message: string;
     code?: ErrorCode;
     nonRetriable?: boolean;
+    metadata?: ErrorMetadata;
     cause?: unknown;
     stack?: string;
 };
+/**
+ * Serializes an error for storage in the database.
+ * Handles DuronError instances specially to preserve their type information.
+ */
 export declare function serializeError(error: unknown): SerializableError;
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,WAAW;;;;;;;;CAQd,CAAA;AAEV,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAA;AAMtE,8BAAsB,UAAW,SAAQ,KAAK;IAI5C,SAAgB,IAAI,EAAE,SAAS,CAA0B;IAKzD,SAAgB,YAAY,EAAE,OAAO,CAAQ;IAO7C,SAAyB,KAAK,CAAC,EAAE,OAAO,CAAA;gBAGtC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAMR,KAAK,CAAC,EAAE,OAAO,CAAA;KAChB;CAWJ;AAKD,qBAAa,wBAAyB,SAAQ,UAAU;IACtD,SAAyB,IAAI,0BAAoC;IACjE,SAAyB,YAAY,QAAO;gBAShC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;CAGhE;AAQD,qBAAa,iBAAkB,SAAQ,UAAU;IAC/C,SAAyB,IAAI,EAAE,SAAS,CAA4B;IACpE,SAAyB,YAAY,QAAO;CAC7C;AAKD,qBAAa,kBAAmB,SAAQ,UAAU;IAChD,SAAyB,IAAI,mBAA6B;IAC1D,SAAyB,YAAY,QAAO;gBAU1C,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,OAAO,CAAA;KAChB;CAIJ;AAKD,qBAAa,gBAAiB,SAAQ,UAAU;IAC9C,SAAyB,IAAI,iBAA2B;IACxD,SAAyB,YAAY,SAAQ;gBAW3C,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,OAAO,CAAA;KAChB;CAIJ;AAKD,qBAAa,iBAAkB,SAAQ,UAAU;IAC/C,SAAyB,IAAI,kBAA4B;IACzD,SAAyB,YAAY,QAAO;gBAU1C,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,OAAO,CAAA;KAChB;CAIJ;AAQD,qBAAa,wBAAyB,SAAQ,iBAAiB;IAC7D,SAAyB,IAAI,0BAAoC;IAKjE,SAAgB,QAAQ,EAAE,MAAM,CAAA;IAKhC,SAAgB,YAAY,EAAE,MAAM,CAAA;gBAQxB,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM;CAOnD;AAKD,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAGhE;AAKD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAE9E;AAKD,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,wBAAwB,CAE5F;AAKD,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,kBAAkB,GAAG,gBAAgB,CAG7F;AAKD,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAExE;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAMD,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,CAuChE"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/errors.js

@@ -1,3 +1,4 @@
+// Error codes for type checking without instanceof
 export const ERROR_CODES = {
     DURON_ERROR: 'DURON_ERROR',
     STEP_ALREADY_EXECUTED: 'STEP_ALREADY_EXECUTED',
@@ -7,87 +8,228 @@ export const ERROR_CODES = {
     ACTION_CANCEL: 'ACTION_CANCEL',
     UNHANDLED_CHILD_STEPS: 'UNHANDLED_CHILD_STEPS',
 };
+/**
+ * Base class for all built-in errors in Duron.
+ * All errors include a cause property that can be serialized.
+ */
 export class DuronError extends Error {
+    /**
+     * Error code for type checking without instanceof.
+     */
     code = ERROR_CODES.DURON_ERROR;
+    /**
+     * Whether this error should prevent retries.
+     */
     nonRetriable = false;
+    /**
+     * The underlying cause of the error, if any.
+     *
+     * This will be serialized and stored in the database.
+     */
     cause;
+    /**
+     * Metadata about the context where the error occurred.
+     */
+    metadata;
     constructor(message, options) {
         super(message);
         this.cause = options?.cause;
+        this.metadata = options?.metadata ?? {};
+        // Set the name to the class name
         this.name = this.constructor.name;
+        // Ensure stack trace points to the error location
         if (Error.captureStackTrace) {
             Error.captureStackTrace(this, this.constructor);
         }
     }
+    /**
+     * Set or update metadata about the context where the error occurred.
+     * Merges with existing metadata (new values override existing ones).
+     *
+     * @param metadata - The metadata to set or merge
+     * @returns this - Returns the error instance for chaining
+     */
+    setMetadata(metadata) {
+        this.metadata = { ...this.metadata, ...metadata };
+        return this;
+    }
 }
+/**
+ * Error thrown when attempting to execute a step that has already been executed.
+ */
 export class StepAlreadyExecutedError extends DuronError {
     code = ERROR_CODES.STEP_ALREADY_EXECUTED;
     nonRetriable = true;
+    /**
+     * Create a new StepAlreadyExecutedError.
+     *
+     * @param stepName - The name of the step that was already executed
+     * @param jobId - The ID of the job containing the step
+     * @param actionName - The name of the action containing the step
+     */
     constructor(stepName, jobId, actionName) {
-        super(`Step "${stepName}" has already been executed for job "${jobId}" and action "${actionName}"`);
+        super(`Step "${stepName}" has already been executed for job "${jobId}" and action "${actionName}"`, {
+            metadata: { stepName, jobId, actionName },
+        });
     }
 }
+/**
+ * NonRetriableError indicates that a step should not be retried.
+ *
+ * If a step handler throws this error, the step will fail immediately
+ * without retrying, even if retry options are configured.
+ */
 export class NonRetriableError extends DuronError {
     code = ERROR_CODES.NON_RETRIABLE;
     nonRetriable = true;
 }
+/**
+ * Error thrown when an action exceeds its timeout.
+ */
 export class ActionTimeoutError extends DuronError {
     code = ERROR_CODES.ACTION_TIMEOUT;
     nonRetriable = true;
-    constructor(actionName, timeoutMs, options) {
-        super(`Action "${actionName}" timed out after ${timeoutMs}ms`, options);
+    /**
+     * Create a new ActionTimeoutError.
+     *
+     * @param actionName - The name of the action that timed out
+     * @param jobId - The ID of the job containing the action
+     * @param timeoutMs - The timeout value in milliseconds
+     * @param options - Optional error options including cause
+     */
+    constructor(actionName, jobId, timeoutMs, options) {
+        super(`Action "${actionName}" in job "${jobId}" timed out after ${timeoutMs}ms`, {
+            cause: options?.cause,
+            metadata: { actionName, jobId },
+        });
     }
 }
+/**
+ * Error thrown when a step exceeds its timeout.
+ */
 export class StepTimeoutError extends DuronError {
     code = ERROR_CODES.STEP_TIMEOUT;
     nonRetriable = false;
+    /**
+     * Create a new StepTimeoutError.
+     *
+     * @param stepName - The name of the step that timed out
+     * @param jobId - The ID of the job containing the step
+     * @param timeoutMs - The timeout value in milliseconds
+     * @param options - Optional error options including cause and additional metadata
+     */
     constructor(stepName, jobId, timeoutMs, options) {
-        super(`Step "${stepName}" in job "${jobId}" timed out after ${timeoutMs}ms`, options);
+        super(`Step "${stepName}" in job "${jobId}" timed out after ${timeoutMs}ms`, {
+            cause: options?.cause,
+            metadata: {
+                stepName,
+                jobId,
+                stepId: options?.stepId,
+                parentStepId: options?.parentStepId,
+                actionName: options?.actionName,
+            },
+        });
     }
 }
+/**
+ * Error thrown when an action is cancelled.
+ */
 export class ActionCancelError extends DuronError {
     code = ERROR_CODES.ACTION_CANCEL;
     nonRetriable = true;
+    /**
+     * Create a new ActionCancelError.
+     *
+     * @param actionName - The name of the action that was cancelled
+     * @param jobId - The ID of the job containing the action
+     * @param options - Optional error options including cause
+     */
     constructor(actionName, jobId, options) {
-        super(`Action "${actionName}" in job "${jobId}" was cancelled`, options);
+        super(`Action "${actionName}" in job "${jobId}" was cancelled`, {
+            cause: options?.cause,
+            metadata: { actionName, jobId },
+        });
     }
 }
+/**
+ * Error thrown when a parent step completes with unhandled (non-awaited) child steps.
+ *
+ * This error indicates a bug in the action handler where child steps were started
+ * but not properly awaited. All child steps must be awaited before the parent returns.
+ */
 export class UnhandledChildStepsError extends NonRetriableError {
     code = ERROR_CODES.UNHANDLED_CHILD_STEPS;
-    stepName;
+    /**
+     * The number of unhandled child steps.
+     */
     pendingCount;
-    constructor(stepName, pendingCount) {
-        super(`Parent step "${stepName}" completed with ${pendingCount} unhandled child step(s). All child steps must be awaited before the parent returns.`);
-        this.stepName = stepName;
+    /**
+     * Create a new UnhandledChildStepsError.
+     *
+     * @param stepName - The name of the parent step
+     * @param pendingCount - The number of unhandled child steps
+     * @param options - Optional metadata
+     */
+    constructor(stepName, pendingCount, options) {
+        super(`Parent step "${stepName}" completed with ${pendingCount} unhandled child step(s). All child steps must be awaited before the parent returns.`, {
+            metadata: {
+                stepName,
+                stepId: options?.stepId,
+                parentStepId: options?.parentStepId,
+                jobId: options?.jobId,
+                actionName: options?.actionName,
+            },
+        });
         this.pendingCount = pendingCount;
     }
 }
+/**
+ * Checks if an error is a DuronError instance.
+ */
 export function isDuronError(error) {
     const code = error?.code;
     return code !== undefined && Object.values(ERROR_CODES).includes(code);
 }
+/**
+ * Checks if an error is a NonRetriableError instance.
+ */
 export function isNonRetriableError(error) {
     return error?.nonRetriable === true;
 }
+/**
+ * Checks if an error is an UnhandledChildStepsError instance.
+ */
 export function isUnhandledChildStepsError(error) {
     return error?.code === ERROR_CODES.UNHANDLED_CHILD_STEPS;
 }
+/**
+ * Checks if an error is a timeout error (ActionTimeoutError or StepTimeoutError).
+ */
 export function isTimeoutError(error) {
     const code = error?.code;
     return code === ERROR_CODES.ACTION_TIMEOUT || code === ERROR_CODES.STEP_TIMEOUT;
 }
+/**
+ * Checks if an error is a cancel error (ActionCancelError or StepCancelError).
+ */
 export function isCancelError(error) {
     return error?.code === ERROR_CODES.ACTION_CANCEL;
 }
+/**
+ * Serializes an error for storage in the database.
+ * Handles DuronError instances specially to preserve their type information.
+ */
 export function serializeError(error) {
     const code = error?.code;
     const nonRetriable = error?.nonRetriable;
+    const metadata = error?.metadata;
     if (isTimeoutError(error)) {
         return {
             name: error.name,
             message: error.message,
             code,
             nonRetriable,
+            metadata,
             cause: error.cause,
             stack: undefined,
         };
@@ -98,6 +240,7 @@ export function serializeError(error) {
             message: error.message,
             code,
             nonRetriable,
+            metadata,
             cause: error.cause,
             stack: error.stack,
         };

package/dist/index.d.ts

@@ -1,10 +1,11 @@
 import type { Action } from './action.js';
 import { Client, type ClientOptions } from './client.js';
-export { createStep, defineAction, type StepDefinition, type StepDefinitionHandlerContext, type StepDefinitionInput, } from './action.js';
+export { createStep, defineAction, type StepDefinition, type StepDefinitionHandlerContext, type StepDefinitionInput, type StepNameContext, } from './action.js';
 export * from './client.js';
 export * from './constants.js';
 export { NonRetriableError, UnhandledChildStepsError } from './errors.js';
 export * from './server.js';
+export type { TelemetryContext } from './step-manager.js';
 export * from './telemetry/index.js';
 export declare const duron: <TActions extends Record<string, Action<any, any, TVariables>>, TVariables = Record<string, unknown>>(options: ClientOptions<TActions, TVariables>) => Client<TActions, TVariables>;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAA;AAExD,OAAO,EACL,UAAU,EACV,YAAY,EACZ,KAAK,cAAc,EACnB,KAAK,4BAA4B,EACjC,KAAK,mBAAmB,GACzB,MAAM,aAAa,CAAA;AACpB,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,OAAO,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAA;AACzE,cAAc,aAAa,CAAA;AAC3B,cAAc,sBAAsB,CAAA;AAEpC,eAAO,MAAM,KAAK,GAChB,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,EAC7D,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAEpC,SAAS,aAAa,CAAC,QAAQ,EAAE,UAAU,CAAC,iCACA,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAA;AAExD,OAAO,EACL,UAAU,EACV,YAAY,EACZ,KAAK,cAAc,EACnB,KAAK,4BAA4B,EACjC,KAAK,mBAAmB,EACxB,KAAK,eAAe,GACrB,MAAM,aAAa,CAAA;AACpB,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,OAAO,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAA;AACzE,cAAc,aAAa,CAAA;AAC3B,YAAY,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AACzD,cAAc,sBAAsB,CAAA;AAEpC,eAAO,MAAM,KAAK,GAChB,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,UAAU,CAAC,CAAC,EAC7D,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAEpC,SAAS,aAAa,CAAC,QAAQ,EAAE,UAAU,CAAC,iCACA,CAAA"}