@beignet/core 0.0.2 → 0.0.4

package/src/jobs/index.ts

@@ -16,6 +16,48 @@ export type MaybePromise<T> = T | Promise<T>;
 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(...)`.
  */
@@ -81,12 +123,38 @@ export interface JobHandleArgs<J extends JobDef, Ctx> {
  */
 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;
 }
 
 /**
@@ -117,6 +185,96 @@ export interface DefineJobOptions<
   ): 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.
  */
@@ -148,7 +306,7 @@ export interface InlineJobDispatcher<Ctx = unknown> {
 /**
  * Context-bound job helper factory.
  */
-export interface JobHandlers<Ctx> {
+export interface Jobs<Ctx> {
   /**
    * Define a job with the bound context type.
    */
@@ -156,13 +314,6 @@ export interface JobHandlers<Ctx> {
     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>;
 }
 
 /**
@@ -207,6 +358,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,
@@ -238,14 +548,7 @@ 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<
+function defineJobImpl<
   Name extends string,
   Payload extends StandardSchema,
   Ctx = unknown,
@@ -253,12 +556,16 @@ 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"],
   };
 }
@@ -303,20 +610,24 @@ export function createInlineJobDispatcher<Ctx>(
 
 /**
  * Create job helper methods bound to an application context type.
+ *
+ * Call it once in `lib/jobs.ts`:
+ *
+ * ```ts
+ * export const { defineJob } = createJobs<AppContext>();
+ * ```
+ *
+ * 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 createJobHandlers<Ctx>(): JobHandlers<Ctx> {
+export function createJobs<Ctx>(): Jobs<Ctx> {
   return {
     defineJob<Name extends string, Payload extends StandardSchema>(
       name: Name,
       options: DefineJobOptions<Name, Payload, Ctx>,
     ): JobDef<Name, Payload, Ctx> {
-      return defineJob(name, options);
-    },
-
-    createInlineJobDispatcher(
-      options: InlineJobDispatcherOptions<Ctx> = {},
-    ): InlineJobDispatcher<Ctx> {
-      return createInlineJobDispatcher(options);
+      return defineJobImpl(name, options);
     },
   };
 }

package/src/notifications/index.ts

@@ -1,7 +1,7 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
-import type { SendMailOptions } from "../mail";
-import type { ProviderInstrumentationTarget } from "../providers";
-import { createProviderInstrumentation } from "../providers";
+import type { SendMailOptions } from "../mail/index.js";
+import type { ProviderInstrumentationTarget } from "../providers/index.js";
+import { createProviderInstrumentation } from "../providers/index.js";
 
 /**
  * Any Standard Schema compatible validator.
@@ -336,7 +336,7 @@ export type MailNotificationRenderer<
 /**
  * Context-bound notification helper factory.
  */
-export interface NotificationHandlers<Ctx> {
+export interface Notifications<Ctx> {
   /**
    * Define a notification with the bound context type.
    */
@@ -344,13 +344,6 @@ export interface NotificationHandlers<Ctx> {
     name: Name,
     options: DefineNotificationOptions<Payload, Ctx>,
   ): NotificationDef<Name, Payload, Ctx>;
-
-  /**
-   * Create an inline dispatcher with the bound context type.
-   */
-  createInlineNotificationDispatcher(
-    options?: InlineNotificationDispatcherOptions<Ctx>,
-  ): NotificationPort;
 }
 
 /**
@@ -495,14 +488,7 @@ function summarizeResults(results: readonly NotificationChannelResult[]) {
   return { sent, skipped, failed };
 }
 
-/**
- * Define a typed notification.
- *
- * Notifications represent user-facing communication intent. Channel handlers
- * decide how that intent becomes mail, SMS, push, in-app delivery, or another
- * app-owned channel.
- */
-export function defineNotification<
+function defineNotificationImpl<
   Name extends string,
   Payload extends StandardSchema,
   Ctx = unknown,
@@ -752,20 +738,24 @@ export function createMemoryNotificationPort(
 
 /**
  * Create notification helper methods bound to an application context type.
+ *
+ * Call it once in `lib/notifications.ts`:
+ *
+ * ```ts
+ * export const { defineNotification } = createNotifications<AppContext>();
+ * ```
+ *
+ * Notifications represent user-facing communication intent. Channel handlers
+ * decide how that intent becomes mail, SMS, push, in-app delivery, or another
+ * app-owned channel.
  */
-export function createNotificationHandlers<Ctx>(): NotificationHandlers<Ctx> {
+export function createNotifications<Ctx>(): Notifications<Ctx> {
   return {
     defineNotification<Name extends string, Payload extends StandardSchema>(
       name: Name,
       options: DefineNotificationOptions<Payload, Ctx>,
     ): NotificationDef<Name, Payload, Ctx> {
-      return defineNotification(name, options);
-    },
-
-    createInlineNotificationDispatcher(
-      options: InlineNotificationDispatcherOptions<Ctx> = {},
-    ): NotificationPort {
-      return createInlineNotificationDispatcher(options);
+      return defineNotificationImpl(name, options);
     },
   };
 }