@beignet/core 0.0.1 → 0.0.3

package/src/jobs/index.ts

@@ -1,82 +1,335 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 
+/**
+ * Any Standard Schema compatible validator.
+ */
 export type StandardSchema = StandardSchemaV1<unknown, unknown>;
+
+/**
+ * Value or promise of that value.
+ */
 export type MaybePromise<T> = T | Promise<T>;
 
+/**
+ * Infer the parsed output type from a Standard Schema.
+ */
 export type InferSchemaOutput<T extends StandardSchemaV1> =
   StandardSchemaV1.InferOutput<T>;
 
+/**
+ * Duration accepted by retry helpers. Numbers are milliseconds.
+ */
+export type JobRetryDuration =
+  | number
+  | `${number}ms`
+  | `${number}s`
+  | `${number}m`
+  | `${number}h`;
+
+/**
+ * Retry strategy understood by Beignet job adapters.
+ */
+export type JobRetryStrategy = "none" | "fixed" | "exponential";
+
+/**
+ * Arguments passed to a retry predicate.
+ */
+export interface JobRetryPredicateArgs {
+  /**
+   * Error thrown by the previous attempt.
+   */
+  error: unknown;
+  /**
+   * One-based attempt number that just failed.
+   */
+  attempt: number;
+  /**
+   * Maximum attempts allowed for this delivery.
+   */
+  maxAttempts: number;
+  /**
+   * Job name when the retry decision is for a job.
+   */
+  jobName?: string;
+}
+
+/**
+ * Return whether a failed attempt should be retried.
+ */
+export type JobRetryPredicate = (args: JobRetryPredicateArgs) => boolean;
+
+/**
+ * Job definition created by `defineJob(...)`.
+ */
 export interface JobDef<
   Name extends string = string,
   Payload extends StandardSchema = StandardSchema,
   Ctx = unknown,
 > {
+  /**
+   * Discriminator for job definitions.
+   */
   readonly kind: "job";
+  /**
+   * Stable job name used by dispatchers and provider adapters.
+   */
   readonly name: Name;
+  /**
+   * Standard Schema payload validator.
+   */
   readonly payload: Payload;
+  /**
+   * Optional human-readable description for docs and tooling.
+   */
   readonly description?: string;
+  /**
+   * Retry metadata for durable job providers.
+   */
   readonly retry?: JobRetryOptions;
+  /**
+   * Handle a parsed job payload.
+   */
   handle(
     args: JobHandleArgs<JobDef<Name, Payload, Ctx>, Ctx>,
   ): MaybePromise<void>;
 }
 
+/**
+ * Infer the parsed payload type for a job definition.
+ */
 export type InferJobPayload<J extends JobDef> =
   J["payload"] extends StandardSchemaV1<unknown, infer Output> ? Output : never;
 
+/**
+ * Arguments passed to a job handler.
+ */
 export interface JobHandleArgs<J extends JobDef, Ctx> {
+  /**
+   * Job definition being handled.
+   */
   job: J;
+  /**
+   * Parsed job payload.
+   */
   payload: InferJobPayload<J>;
+  /**
+   * Handler context.
+   */
   ctx: Ctx;
 }
 
+/**
+ * Retry metadata that durable job providers can map to their own retry model.
+ */
 export interface JobRetryOptions {
   /**
-   * Maximum number of retry attempts a durable job adapter should request.
-   *
-   * Providers may impose their own range limits. For example, the Inngest
-   * adapter validates this as a function-level `retries` value.
+   * Retry strategy. Raw objects without a strategy default to exponential
+   * backoff so existing `{ attempts }` style definitions stay meaningful.
+   */
+  strategy?: JobRetryStrategy;
+  /**
+   * Maximum total attempts, including the first attempt.
    */
   attempts?: number;
+  /**
+   * Delay between attempts for fixed retry policies.
+   */
+  delay?: JobRetryDuration;
+  /**
+   * Initial delay for exponential retry policies.
+   */
+  initialDelay?: JobRetryDuration;
+  /**
+   * Maximum delay for exponential retry policies.
+   */
+  maxDelay?: JobRetryDuration;
+  /**
+   * Exponential multiplier. Defaults to `2`.
+   */
+  factor?: number;
+  /**
+   * Whether adapters that compute delays should add jitter.
+   */
+  jitter?: boolean;
+  /**
+   * Optional app-owned retry classifier.
+   */
+  retryIf?: JobRetryPredicate;
 }
 
+/**
+ * Options for declaring a typed job.
+ */
 export interface DefineJobOptions<
   Name extends string,
   Payload extends StandardSchema,
   Ctx,
 > {
+  /**
+   * Standard Schema payload validator.
+   */
   payload: Payload;
+  /**
+   * Optional human-readable description for docs and tooling.
+   */
   description?: string;
+  /**
+   * Retry metadata for durable job providers.
+   */
   retry?: JobRetryOptions;
+  /**
+   * Handle a parsed job payload.
+   */
   handle(
     args: JobHandleArgs<JobDef<Name, Payload, Ctx>, Ctx>,
   ): MaybePromise<void>;
 }
 
+/**
+ * Options for a fixed job retry policy.
+ */
+export interface FixedJobRetryOptions {
+  /**
+   * Maximum total attempts, including the first attempt.
+   */
+  attempts: number;
+  /**
+   * Delay between attempts.
+   */
+  delay: JobRetryDuration;
+  /**
+   * Optional app-owned retry classifier.
+   */
+  retryIf?: JobRetryPredicate;
+}
+
+/**
+ * Options for an exponential job retry policy.
+ */
+export interface ExponentialJobRetryOptions {
+  /**
+   * Maximum total attempts, including the first attempt.
+   */
+  attempts: number;
+  /**
+   * Initial delay. Defaults to `1s`.
+   */
+  initialDelay?: JobRetryDuration;
+  /**
+   * Maximum delay. Defaults to `1m`.
+   */
+  maxDelay?: JobRetryDuration;
+  /**
+   * Exponential multiplier. Defaults to `2`.
+   */
+  factor?: number;
+  /**
+   * Whether computed delays should include jitter.
+   */
+  jitter?: boolean;
+  /**
+   * Optional app-owned retry classifier.
+   */
+  retryIf?: JobRetryPredicate;
+}
+
+/**
+ * Retry helper namespace for job definitions.
+ */
+export const retry = {
+  /**
+   * Disable retries. The first failure is terminal.
+   */
+  none(): JobRetryOptions {
+    return {
+      strategy: "none",
+      attempts: 1,
+    };
+  },
+
+  /**
+   * Retry with the same delay between attempts.
+   */
+  fixed(options: FixedJobRetryOptions): JobRetryOptions {
+    return validateJobRetryOptions({
+      strategy: "fixed",
+      attempts: options.attempts,
+      delay: options.delay,
+      retryIf: options.retryIf,
+    });
+  },
+
+  /**
+   * Retry with exponential backoff.
+   */
+  exponential(options: ExponentialJobRetryOptions): JobRetryOptions {
+    return validateJobRetryOptions({
+      strategy: "exponential",
+      attempts: options.attempts,
+      initialDelay: options.initialDelay,
+      maxDelay: options.maxDelay,
+      factor: options.factor,
+      jitter: options.jitter,
+      retryIf: options.retryIf,
+    });
+  },
+} as const;
+
+/**
+ * Options for the inline job dispatcher.
+ */
 export interface InlineJobDispatcherOptions<Ctx> {
+  /**
+   * Static job context or factory evaluated for each dispatched job.
+   */
   ctx?: Ctx | (() => MaybePromise<Ctx>);
+  /**
+   * Called when a dispatched inline job fails. When omitted, errors are
+   * rethrown to the caller.
+   */
   onError?: (error: unknown, job: JobDef<string, StandardSchema, Ctx>) => void;
 }
 
+/**
+ * Local/test job dispatcher that executes job handlers inline.
+ */
 export interface InlineJobDispatcher<Ctx = unknown> {
+  /**
+   * Validate a payload and run the job handler immediately.
+   */
   dispatch<J extends JobDef<string, StandardSchema, Ctx>>(
     job: J,
     payload: InferJobPayload<J>,
   ): Promise<void>;
 }
 
+/**
+ * Context-bound job helper factory.
+ */
 export interface JobHandlers<Ctx> {
+  /**
+   * Define a job with the bound context type.
+   */
   defineJob<Name extends string, Payload extends StandardSchema>(
     name: Name,
     options: DefineJobOptions<Name, Payload, Ctx>,
   ): JobDef<Name, Payload, Ctx>;
 
+  /**
+   * Create an inline dispatcher with the bound context type.
+   */
   createInlineJobDispatcher(
     options?: InlineJobDispatcherOptions<Ctx>,
   ): InlineJobDispatcher<Ctx>;
 }
 
+/**
+ * Error thrown when job payload validation fails.
+ */
 export class JobValidationError extends Error {
+  /**
+   * Raw Standard Schema validation issues.
+   */
   readonly issues: readonly StandardSchemaV1.Issue[];
 
   constructor(args: {
@@ -112,6 +365,165 @@ function formatIssues(issues: readonly StandardSchemaV1.Issue[]): string {
     .join("; ");
 }
 
+function assertPositiveInteger(name: string, value: number): void {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`${name} must be a positive integer`);
+  }
+}
+
+function assertPositiveNumber(name: string, value: number): void {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`${name} must be a positive number`);
+  }
+}
+
+function durationToMs(name: string, value: JobRetryDuration): number {
+  if (typeof value === "number") {
+    assertPositiveInteger(name, value);
+    return value;
+  }
+
+  const match = /^(\d+)(ms|s|m|h)$/.exec(value);
+  if (!match) {
+    throw new Error(
+      `${name} must be a positive millisecond value or duration string like "500ms", "30s", "5m", or "1h".`,
+    );
+  }
+
+  const amount = Number(match[1]);
+  assertPositiveInteger(name, amount);
+
+  switch (match[2]) {
+    case "ms":
+      return amount;
+    case "s":
+      return amount * 1000;
+    case "m":
+      return amount * 60_000;
+    case "h":
+      return amount * 3_600_000;
+    default:
+      throw new Error(`${name} has an unsupported duration unit.`);
+  }
+}
+
+function validateJobRetryOptions(options: JobRetryOptions): JobRetryOptions {
+  const strategy = options.strategy ?? "exponential";
+
+  if (!["none", "fixed", "exponential"].includes(strategy)) {
+    throw new Error("retry.strategy must be none, fixed, or exponential");
+  }
+
+  const attempts = options.attempts ?? (strategy === "none" ? 1 : undefined);
+  if (attempts === undefined) {
+    throw new Error("retry.attempts is required");
+  }
+  assertPositiveInteger("retry.attempts", attempts);
+
+  if (strategy === "none" && attempts !== 1) {
+    throw new Error("retry.none() must use exactly one attempt");
+  }
+
+  if (strategy === "fixed") {
+    if (options.delay === undefined) {
+      throw new Error("retry.delay is required for fixed retry policies");
+    }
+    durationToMs("retry.delay", options.delay);
+  }
+
+  if (strategy === "exponential") {
+    if (options.initialDelay !== undefined) {
+      durationToMs("retry.initialDelay", options.initialDelay);
+    }
+    if (options.maxDelay !== undefined) {
+      durationToMs("retry.maxDelay", options.maxDelay);
+    }
+    if (options.factor !== undefined) {
+      assertPositiveNumber("retry.factor", options.factor);
+    }
+  }
+
+  return {
+    ...options,
+    strategy,
+    attempts,
+  };
+}
+
+/**
+ * Return the maximum total attempts configured by a retry policy.
+ */
+export function getJobRetryMaxAttempts(
+  options: JobRetryOptions | undefined,
+): number | undefined {
+  return options ? validateJobRetryOptions(options).attempts : undefined;
+}
+
+/**
+ * Return whether a failed job attempt should be retried.
+ */
+export function shouldRetryJob(
+  options: JobRetryOptions | undefined,
+  args: JobRetryPredicateArgs,
+): boolean {
+  if (!options) return args.attempt < args.maxAttempts;
+
+  const retryOptions = validateJobRetryOptions(options);
+  const maxAttempts = Math.min(
+    args.maxAttempts,
+    retryOptions.attempts ?? args.maxAttempts,
+  );
+  if (retryOptions.strategy === "none") return false;
+  if (args.attempt >= maxAttempts) return false;
+
+  return retryOptions.retryIf?.({ ...args, maxAttempts }) ?? true;
+}
+
+/**
+ * Compute the next retry delay in milliseconds for a failed job attempt.
+ */
+export function getJobRetryDelayMs(
+  options: JobRetryOptions | undefined,
+  args: Pick<JobRetryPredicateArgs, "attempt" | "error" | "jobName">,
+): number {
+  const retryOptions = options
+    ? validateJobRetryOptions(options)
+    : retry.exponential({ attempts: 3 });
+
+  let delayMs: number;
+  if (retryOptions.strategy === "fixed") {
+    delayMs = durationToMs("retry.delay", retryOptions.delay ?? "1s");
+  } else if (retryOptions.strategy === "none") {
+    delayMs = 0;
+  } else {
+    const initialDelayMs = durationToMs(
+      "retry.initialDelay",
+      retryOptions.initialDelay ?? "1s",
+    );
+    const maxDelayMs = durationToMs(
+      "retry.maxDelay",
+      retryOptions.maxDelay ?? "1m",
+    );
+    const factor = retryOptions.factor ?? 2;
+    delayMs = Math.min(
+      maxDelayMs,
+      initialDelayMs * factor ** Math.max(0, args.attempt - 1),
+    );
+  }
+
+  if (retryOptions.jitter && delayMs > 0) {
+    delayMs = Math.ceil(delayMs * (0.5 + Math.random()));
+    if (retryOptions.strategy === "exponential") {
+      delayMs = Math.min(
+        delayMs,
+        durationToMs("retry.maxDelay", retryOptions.maxDelay ?? "1m"),
+      );
+    }
+  }
+
+  return delayMs;
+}
+
 async function parsePayload<Schema extends StandardSchemaV1>(
   schema: Schema,
   input: unknown,
@@ -143,6 +555,13 @@ async function resolveCtx<Ctx>(
   return ctx as Ctx;
 }
 
+/**
+ * Define a typed job.
+ *
+ * Retry options are provider hints. Inline dispatchers validate payloads and
+ * call `handle(...)` immediately; durable providers may enqueue or schedule the
+ * job according to their own runtime.
+ */
 export function defineJob<
   Name extends string,
   Payload extends StandardSchema,
@@ -151,16 +570,23 @@ export function defineJob<
   name: Name,
   options: DefineJobOptions<Name, Payload, Ctx>,
 ): JobDef<Name, Payload, Ctx> {
+  const retryOptions = options.retry
+    ? validateJobRetryOptions(options.retry)
+    : undefined;
+
   return {
     kind: "job",
     name,
     payload: options.payload,
     description: options.description,
-    retry: options.retry,
+    retry: retryOptions,
     handle: options.handle as JobDef<Name, Payload, Ctx>["handle"],
   };
 }
 
+/**
+ * Validate and parse a job payload with the job's Standard Schema.
+ */
 export async function parseJobPayload<J extends JobDef>(
   job: J,
   payload: unknown,
@@ -170,6 +596,9 @@ export async function parseJobPayload<J extends JobDef>(
   })) as InferJobPayload<J>;
 }
 
+/**
+ * Create a local/test dispatcher that runs job handlers inline.
+ */
 export function createInlineJobDispatcher<Ctx>(
   options: InlineJobDispatcherOptions<Ctx> = {},
 ): InlineJobDispatcher<Ctx> {
@@ -193,6 +622,9 @@ export function createInlineJobDispatcher<Ctx>(
   };
 }
 
+/**
+ * Create job helper methods bound to an application context type.
+ */
 export function createJobHandlers<Ctx>(): JobHandlers<Ctx> {
   return {
     defineJob<Name extends string, Payload extends StandardSchema>(