duron 0.3.0-beta.8 → 0.3.0

package/src/action.ts

@@ -1,7 +1,7 @@
 import type { Logger } from 'pino'
 import * as z from 'zod'
 
-import type { ObserveContext } from './telemetry/adapter.js'
+import type { TelemetryContext } from './step-manager.js'
 import generateChecksum from './utils/checksum.js'
 
 export type RetryOptions = z.infer<typeof RetryOptionsSchema>
@@ -16,10 +16,10 @@ export interface ActionHandlerContext<TInput extends z.ZodObject, TVariables = R
   logger: Logger
 
   /**
-   * Observability context for recording metrics and span data.
-   * Allows recording custom metrics, span attributes, and events.
+   * Telemetry context for recording metrics and span data.
+   * Provides access to OpenTelemetry APIs for recording traces and metrics.
    */
-  observe: ObserveContext
+  telemetry: TelemetryContext
 
   /**
    * Execute an inline step within the action.
@@ -71,10 +71,10 @@ export interface StepHandlerContext {
   parentStepId: string | null
 
   /**
-   * Observability context for recording metrics and span data.
-   * Allows recording custom metrics, span attributes, and events.
+   * Telemetry context for recording metrics and span data.
+   * Provides access to OpenTelemetry APIs for recording traces and metrics.
    */
-  observe: ObserveContext
+  telemetry: TelemetryContext
 
   /**
    * Create a nested child step.
@@ -142,9 +142,20 @@ export interface StepDefinitionHandlerContext<TInput extends z.ZodObject, TVaria
 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.
+   * Can be a static string or a function that generates the name from the context.
+   * The function receives a context object with input, variables, jobId, and parentStepId.
+   *
+   * @example
+   * ```typescript
+   * name: (ctx) => `process-user-${ctx.input.userId}`
+   * ```
+   *
+   * @example
+   * ```typescript
+   * name: (ctx) => `step-${ctx.var.environment}-${ctx.jobId.slice(0, 8)}`
+   * ```
    */
-  name: string | ((ctx: { input: z.infer<TInput> }) => string)
+  name: string | ((ctx: StepNameContext<TInput, TVariables>) => string)
 
   /**
    * Zod schema for validating the step input.
@@ -183,95 +194,315 @@ export interface ConcurrencyHandlerContext<TInput extends z.ZodObject, TVariable
   var: TVariables
 }
 
-export type ActionDefinition<
-  TInput extends z.ZodObject,
-  TOutput extends z.ZodObject,
-  TVariables = Record<string, unknown>,
-> = z.input<ReturnType<typeof createActionDefinitionSchema<TInput, TOutput, TVariables>>>
+/**
+ * Context available when generating dynamic step names.
+ * Provides access to input, variables, job ID, and parent step ID.
+ */
+export interface StepNameContext<TInput extends z.ZodObject, TVariables = Record<string, unknown>> {
+  /**
+   * The validated input for this step.
+   */
+  input: z.infer<TInput>
 
-export type Action<
-  TInput extends z.ZodObject,
-  TOutput extends z.ZodObject,
-  TVariables = Record<string, unknown>,
-> = z.infer<ReturnType<typeof createActionDefinitionSchema<TInput, TOutput, TVariables>>>
+  /**
+   * Variables shared across the action.
+   */
+  var: TVariables
+
+  /**
+   * The job ID this step belongs to.
+   */
+  jobId: string
+
+  /**
+   * The ID of the parent step, or null if this is a root step.
+   */
+  parentStepId: string | null
+}
 
 /**
  * Retry configuration options for actions and steps.
+ * Controls how failed operations are retried with exponential backoff.
  */
-export const RetryOptionsSchema = z
-  .object({
-    /**
-     * Maximum number of retry attempts.
-     *
-     * @default 4
-     */
-    limit: z.number().default(4),
+export interface RetryOptionsInput {
+  /**
+   * Maximum number of retry attempts.
+   * Set to 0 to disable retries.
+   *
+   * @default 4
+   */
+  limit?: number
 
-    /**
-     * Exponential backoff factor.
-     * The delay between retries is calculated as: minTimeout * (factor ^ attemptNumber)
-     *
-     * @default 2
-     */
-    factor: z.number().default(2),
+  /**
+   * Exponential backoff factor.
+   * The delay between retries is calculated as: `minTimeout * (factor ^ attemptNumber)`
+   *
+   * @default 2
+   */
+  factor?: number
 
-    /**
-     * Minimum delay in milliseconds before the first retry.
-     *
-     * @default 1000
-     */
-    minTimeout: z.number().default(1000),
+  /**
+   * Minimum delay in milliseconds before the first retry.
+   * This is the base delay that gets multiplied by the factor.
+   *
+   * @default 1000
+   */
+  minTimeout?: number
 
-    /**
-     * Maximum delay in milliseconds between retries.
-     * The calculated delay will be capped at this value.
-     *
-     * @default 30000
-     */
-    maxTimeout: z.number().default(30000),
-  })
-  .default({ limit: 4, factor: 2, minTimeout: 1000, maxTimeout: 30000 })
-  .describe('The retry options')
+  /**
+   * Maximum delay in milliseconds between retries.
+   * The calculated delay will be capped at this value to prevent
+   * excessively long wait times.
+   *
+   * @default 30000
+   */
+  maxTimeout?: number
+}
 
 /**
- * Options for configuring a step within an action.
+ * Configuration options for steps within an action.
+ * Controls concurrency, retries, and timeouts for step execution.
  */
-export const StepOptionsSchema = z.object({
+export interface StepsConfigInput {
   /**
-   * Retry configuration for this step.
-   * If not provided, uses the default retry options from the action or Duron instance.
+   * Maximum number of steps that can run concurrently within this action.
+   * Higher values allow more parallelism but may increase resource usage.
+   *
+   * @default 100
    */
-  retry: RetryOptionsSchema,
+  concurrency?: number
 
   /**
-   * Timeout in milliseconds for this step.
-   * Steps that exceed this timeout will be cancelled.
+   * Retry configuration for steps.
+   * These settings apply to all steps unless overridden at the step level.
+   *
+   * @default { limit: 4, factor: 2, minTimeout: 1000, maxTimeout: 30000 }
+   */
+  retry?: RetryOptionsInput
+
+  /**
+   * Timeout in milliseconds for each step.
+   * Steps that exceed this timeout will be cancelled and may be retried.
    *
    * @default 300000 (5 minutes)
    */
-  expire: z
-    .number()
-    .default(5 * 60 * 1000)
-    .describe('The expire time for the step (milliseconds)'),
+  expire?: number
+}
 
+/**
+ * Group configuration for concurrency control.
+ * Allows grouping jobs by key and controlling concurrency per group.
+ */
+export interface GroupsConfigInput<TInput extends z.ZodObject, TVariables = Record<string, unknown>> {
   /**
-   * Whether this step runs in parallel with siblings.
-   * Parallel steps are independent from siblings during time travel.
-   * When time traveling to a step, completed parallel siblings are preserved.
+   * Function to determine the group key for a job.
+   * Jobs with the same group key will respect the group concurrency limit.
+   * Use this to limit concurrent processing of related jobs (e.g., per user, per tenant).
+   *
+   * If not provided, all jobs for this action will use the '@default' group key.
    *
-   * @default false
+   * @param ctx - Context containing the validated input and variables
+   * @returns Promise resolving to the group key string
+   *
+   * @example
+   * ```typescript
+   * groupKey: async (ctx) => `user:${ctx.input.userId}`
+   * ```
    */
-  parallel: z.boolean().default(false).describe('Whether this step runs in parallel (independent from siblings)'),
-})
+  groupKey?: (ctx: ConcurrencyHandlerContext<TInput, TVariables>) => Promise<string>
+
+  /**
+   * Function to dynamically determine the concurrency limit for a job's group.
+   * The concurrency limit is stored with each job and used during fetch operations.
+   * This allows different groups to have different concurrency limits.
+   *
+   * If not provided, uses the global `groupConcurrencyLimit` from the client options.
+   *
+   * @param ctx - Context containing the validated input and variables
+   * @returns Promise resolving to the concurrency limit number
+   *
+   * @example
+   * ```typescript
+   * concurrency: async (ctx) => ctx.input.priority === 'high' ? 10 : 2
+   * ```
+   */
+  concurrency?: (ctx: ConcurrencyHandlerContext<TInput, TVariables>) => Promise<number>
+}
 
 /**
- * Creates a Zod schema for validating action definitions.
+ * Definition for creating a Duron action.
+ * Actions are type-safe, durable job handlers with built-in retry logic,
+ * step-based execution, and concurrency control.
  *
- * @template TInput - Zod schema for the action input
- * @template TOutput - Zod schema for the action output
- * @template TVariables - Type of variables available to the action
- * @returns Zod schema for action definitions
+ * @template TInput - Zod schema type for validating the action input
+ * @template TOutput - Zod schema type for validating the action output
+ * @template TVariables - Type of variables available to the action handler
  */
+export interface ActionDefinitionInput<
+  TInput extends z.ZodObject,
+  TOutput extends z.ZodObject,
+  TVariables = Record<string, unknown>,
+> {
+  /**
+   * Unique name for this action.
+   * Used as the queue name and must be unique across all actions registered with a client.
+   * This name is used for job routing, logging, and dashboard display.
+   *
+   * @example 'send-email', 'process-payment', 'sync-user-data'
+   */
+  name: string
+
+  /**
+   * Optional version string for the action.
+   * Used to track changes to the action and included in the checksum calculation.
+   * Changing the version will cause existing jobs to be treated as having a different checksum.
+   *
+   * @example '1.0.0', '2024-01-15', 'v2'
+   */
+  version?: string
+
+  /**
+   * Zod schema for validating the action input.
+   * If provided, input will be validated before the handler is called.
+   * Invalid input will throw a validation error and the job will fail.
+   *
+   * @example
+   * ```typescript
+   * input: z.object({
+   *   email: z.string().email(),
+   *   subject: z.string().min(1),
+   * })
+   * ```
+   */
+  input?: TInput
+
+  /**
+   * Zod schema for validating the action output.
+   * If provided, output will be validated after the handler completes.
+   * Invalid output will cause the job to fail.
+   *
+   * @example
+   * ```typescript
+   * output: z.object({
+   *   success: z.boolean(),
+   *   messageId: z.string().optional(),
+   * })
+   * ```
+   */
+  output?: TOutput
+
+  /**
+   * Group configuration for concurrency control.
+   * Allows grouping jobs by a dynamic key and controlling concurrency per group.
+   * Useful for rate limiting per user, tenant, or resource.
+   */
+  groups?: GroupsConfigInput<TInput, TVariables>
+
+  /**
+   * Configuration for steps within this action.
+   * Steps are retryable units of work that can be executed within the action handler.
+   * These settings apply to all steps unless overridden at the step level.
+   *
+   * @default { concurrency: 100, retry: { limit: 4, factor: 2, minTimeout: 1000, maxTimeout: 30000 }, expire: 300000 }
+   */
+  steps?: StepsConfigInput
+
+  /**
+   * Maximum number of jobs for this action that can run concurrently across all workers.
+   * This limit is enforced per action, regardless of group.
+   *
+   * @default 100
+   */
+  concurrency?: number
+
+  /**
+   * Timeout in milliseconds for the entire action.
+   * Jobs that exceed this timeout will be cancelled.
+   * Make sure this is greater than the expected total execution time including all steps.
+   *
+   * @default 900000 (15 minutes)
+   */
+  expire?: number
+
+  /**
+   * Function to generate a dynamic description for the job.
+   * The description is calculated at job creation time and stored in the database.
+   * Use this to provide context about what the specific job instance is doing.
+   *
+   * @param ctx - Context containing the validated input and variables
+   * @returns Promise resolving to the description string
+   *
+   * @example
+   * ```typescript
+   * description: async (ctx) => `Send email to ${ctx.input.email}`
+   * ```
+   */
+  description?: (ctx: ConcurrencyHandlerContext<TInput, TVariables>) => Promise<string>
+
+  /**
+   * The handler function that executes the action logic.
+   * Receives a context object with validated input, variables, logger, and step functions.
+   * Must return a Promise that resolves to the action output (matching the output schema if provided).
+   *
+   * @param ctx - Action handler context with input, variables, and step functions
+   * @returns Promise resolving to the action output
+   *
+   * @example
+   * ```typescript
+   * handler: async (ctx) => {
+   *   const result = await ctx.step('send', async () => {
+   *     return await sendEmail(ctx.input.email, ctx.input.subject)
+   *   })
+   *   return { success: true, messageId: result.id }
+   * }
+   * ```
+   */
+  handler: (ctx: ActionHandlerContext<TInput, TVariables>) => Promise<z.infer<TOutput>>
+}
+
+// Type alias for backwards compatibility (inferred from Zod schema)
+export type ActionDefinition<
+  TInput extends z.ZodObject,
+  TOutput extends z.ZodObject,
+  TVariables = Record<string, unknown>,
+> = ActionDefinitionInput<TInput, TOutput, TVariables>
+
+// Compile-time check: ensure ActionDefinitionInput is assignable to the Zod schema's input type
+type _EnsureActionDefinitionCompatible<
+  TInput extends z.ZodObject,
+  TOutput extends z.ZodObject,
+  TVariables,
+> = ActionDefinitionInput<TInput, TOutput, TVariables> extends z.input<
+  ReturnType<typeof createActionDefinitionSchema<TInput, TOutput, TVariables>>
+>
+  ? true
+  : 'ERROR: ActionDefinitionInput does not match Zod schema input type'
+
+// This will cause a compile error if the types diverge
+declare const _actionDefCheck: _EnsureActionDefinitionCompatible<z.ZodObject<any>, z.ZodObject<any>, any>
+const _checkActionDef: _EnsureActionDefinitionCompatible<z.ZodObject<any>, z.ZodObject<any>, any> = true
+
+export type Action<
+  TInput extends z.ZodObject,
+  TOutput extends z.ZodObject,
+  TVariables = Record<string, unknown>,
+> = z.infer<ReturnType<typeof createActionDefinitionSchema<TInput, TOutput, TVariables>>>
+
+export const RetryOptionsSchema = z
+  .object({
+    limit: z.number().default(4),
+    factor: z.number().default(2),
+    minTimeout: z.number().default(1000),
+    maxTimeout: z.number().default(30000),
+  })
+  .default({ limit: 4, factor: 2, minTimeout: 1000, maxTimeout: 30000 })
+
+export const StepOptionsSchema = z.object({
+  retry: RetryOptionsSchema,
+  expire: z.number().default(5 * 60 * 1000),
+  parallel: z.boolean().default(false),
+})
+
 export function createActionDefinitionSchema<
   TInput extends z.ZodObject,
   TOutput extends z.ZodObject,
@@ -279,66 +510,25 @@ export function createActionDefinitionSchema<
 >() {
   return z
     .object({
-      /**
-       * Unique name for this action.
-       * Used as the queue name and must be unique across all actions.
-       * Required.
-       */
-      name: z.string().describe('The name of the action'),
-
-      /**
-       * Version of the action.
-       * Used to track changes to the action and generate the checksum.
-       */
-      version: z.string().describe('The version of the action').optional(),
-
-      /**
-       * Zod schema for validating the action input.
-       * If provided, input will be validated before the handler is called.
-       * If not provided, any input will be accepted.
-       */
+      name: z.string(),
+      version: z.string().optional(),
       input: z
         .custom<TInput>((val: any) => {
           return !val || ('_zod' in val && 'type' in val && val.type === 'object')
         })
         .optional(),
-
-      /**
-       * Zod schema for validating the action output.
-       * If provided, output will be validated after the handler completes.
-       * If not provided, any output will be accepted.
-       */
       output: z
         .custom<TOutput>((val: any) => {
           return !val || ('_zod' in val && 'type' in val && val.type === 'object')
         })
         .optional(),
-
       groups: z
         .object({
-          /**
-           * Function to determine the group key for a job.
-           * Jobs with the same group key will respect the group concurrency limit.
-           * If not provided, all jobs for this action will use the '@default' group key.
-           *
-           * @param ctx - Context containing the input and variables
-           * @returns Promise resolving to the group key string
-           */
           groupKey: z
             .custom<(ctx: ConcurrencyHandlerContext<TInput, TVariables>) => Promise<string>>((val) => {
               return !val || val instanceof Function
             })
             .optional(),
-
-          /**
-           * Function to determine the concurrency limit for a job.
-           * The concurrency limit is stored with each job and used during fetch operations.
-           * When fetching jobs, the latest job's concurrency limit is used for each groupKey.
-           * If not provided, defaults to 10.
-           *
-           * @param ctx - Context containing the input and variables
-           * @returns Promise resolving to the concurrency limit number
-           */
           concurrency: z
             .custom<(ctx: ConcurrencyHandlerContext<TInput, TVariables>) => Promise<number>>((val) => {
               return !val || val instanceof Function
@@ -346,49 +536,27 @@ export function createActionDefinitionSchema<
             .optional(),
         })
         .optional(),
-
       steps: z
         .object({
-          /**
-           * Function to determine the concurrency limit for a step.
-           * The concurrency limit is stored with each step and used during fetch operations.
-           * When fetching steps, the latest step's concurrency limit is used for each stepKey.
-           * If not provided, defaults to 100.
-           */
-          concurrency: z.number().default(100).describe('How many steps can run concurrently for this action'),
-          retry: RetryOptionsSchema.describe('How to retry on failure for the steps of this action'),
-          expire: z
-            .number()
-            .default(5 * 60 * 1000)
-            .describe('How long a step can run for (milliseconds)'),
+          concurrency: z.number().default(100),
+          retry: RetryOptionsSchema,
+          expire: z.number().default(5 * 60 * 1000),
         })
         .default({
           concurrency: 100,
           retry: { limit: 4, factor: 2, minTimeout: 1000, maxTimeout: 30000 },
           expire: 5 * 60 * 1000,
         }),
-
-      concurrency: z.number().default(100).describe('How many jobs can run concurrently for this action'),
-
-      expire: z
-        .number()
-        .default(15 * 60 * 1000)
-        .describe('How long a job can run for (milliseconds)'),
-
-      /**
-       * The handler function that executes the action logic.
-       * Receives a context object with input, variables, and a step function.
-       * Must return a Promise that resolves to the action output.
-       * Required.
-       *
-       * @param ctx - Action handler context
-       * @returns Promise resolving to the action output
-       */
-      handler: z
-        .custom<(ctx: ActionHandlerContext<TInput, TVariables>) => Promise<z.infer<TOutput>>>((val) => {
-          return val instanceof Function
+      concurrency: z.number().default(100),
+      expire: z.number().default(15 * 60 * 1000),
+      description: z
+        .custom<(ctx: ConcurrencyHandlerContext<TInput, TVariables>) => Promise<string>>((val) => {
+          return !val || val instanceof Function
         })
-        .describe('The handler for the action'),
+        .optional(),
+      handler: z.custom<(ctx: ActionHandlerContext<TInput, TVariables>) => Promise<z.infer<TOutput>>>((val) => {
+        return val instanceof Function
+      }),
     })
     .transform((def) => {
       const checksum = [def.name, def.version, def.handler.toString()].filter(Boolean).join(':')