@beignet/core 0.0.1 → 0.0.2

package/src/jobs/index.ts

@@ -1,35 +1,84 @@
 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>;
 
+/**
+ * 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.
@@ -40,43 +89,89 @@ export interface JobRetryOptions {
   attempts?: number;
 }
 
+/**
+ * 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 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: {
@@ -143,6 +238,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,
@@ -161,6 +263,9 @@ export function defineJob<
   };
 }
 
+/**
+ * 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 +275,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 +301,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>(

package/src/mail/index.ts

@@ -4,27 +4,71 @@
  * Shared mail port and test adapters for Beignet applications.
  */
 
+/**
+ * Value or promise of that value.
+ */
 export type MaybePromise<T> = T | Promise<T>;
 
+/**
+ * Email address accepted by Beignet mail helpers.
+ */
 export type MailAddress =
   | string
   | {
+      /**
+       * Email address.
+       */
       email: string;
+      /**
+       * Optional display name.
+       */
       name?: string;
     };
 
+/**
+ * Single address or address list.
+ */
 export type MailAddressList = MailAddress | readonly MailAddress[];
 
+/**
+ * Common mail message fields shared by all send options.
+ */
 export interface MailBaseMessage {
+  /**
+   * Required recipients.
+   */
   to: MailAddressList;
+  /**
+   * Message subject.
+   */
   subject: string;
+  /**
+   * Sender address. Providers or adapters may supply a default.
+   */
   from?: MailAddress;
+  /**
+   * Carbon-copy recipients.
+   */
   cc?: MailAddressList;
+  /**
+   * Blind-carbon-copy recipients.
+   */
   bcc?: MailAddressList;
+  /**
+   * Reply-to recipients.
+   */
   replyTo?: MailAddressList;
+  /**
+   * Provider-specific message headers.
+   */
   headers?: Record<string, string>;
 }
 
+/**
+ * Mail send options.
+ *
+ * A message must include at least one body format: `text` or `html`.
+ */
 export type SendMailOptions = MailBaseMessage &
   (
     | {
@@ -37,45 +81,129 @@ export type SendMailOptions = MailBaseMessage &
       }
   );
 
+/**
+ * Normalized mail message with address fields converted to arrays.
+ */
 export interface NormalizedMailMessage extends MailBaseMessage {
+  /**
+   * Normalized recipients.
+   */
   to: readonly MailAddress[];
+  /**
+   * Sender address after applying any default.
+   */
   from?: MailAddress;
+  /**
+   * Normalized carbon-copy recipients.
+   */
   cc?: readonly MailAddress[];
+  /**
+   * Normalized blind-carbon-copy recipients.
+   */
   bcc?: readonly MailAddress[];
+  /**
+   * Normalized reply-to recipients.
+   */
   replyTo?: readonly MailAddress[];
+  /**
+   * Plain text body.
+   */
   text?: string;
+  /**
+   * HTML body.
+   */
   html?: string;
 }
 
+/**
+ * Result returned by a mail provider.
+ */
 export interface SendMailResult {
+  /**
+   * Provider message ID when available.
+   */
   id?: string;
+  /**
+   * Provider name.
+   */
   provider?: string;
 }
 
+/**
+ * App-facing mailer port.
+ */
 export interface MailerPort {
+  /**
+   * Send one mail message.
+   */
   send(message: SendMailOptions): Promise<SendMailResult>;
 }
 
+/**
+ * Delivery captured by the memory mailer.
+ */
 export interface MemoryMailDelivery {
+  /**
+   * Generated delivery ID.
+   */
   id: string;
+  /**
+   * Normalized message that would have been sent.
+   */
   message: NormalizedMailMessage;
+  /**
+   * Timestamp assigned by the memory mailer.
+   */
   sentAt: Date;
 }
 
+/**
+ * In-memory mailer port for tests and local examples.
+ */
 export interface MemoryMailerPort extends MailerPort {
+  /**
+   * Captured deliveries.
+   */
   readonly deliveries: readonly MemoryMailDelivery[];
+  /**
+   * Clear captured deliveries.
+   */
   clear(): void;
 }
 
+/**
+ * Options for `createMemoryMailer(...)`.
+ */
 export interface CreateMemoryMailerOptions {
+  /**
+   * Sender used when a message does not specify `from`.
+   */
   defaultFrom?: MailAddress;
+  /**
+   * Clock used for captured deliveries.
+   */
   now?: () => Date;
+  /**
+   * ID factory used for captured deliveries.
+   */
   id?: () => string;
+  /**
+   * Observer called after a delivery is captured.
+   */
   onSend?: (delivery: MemoryMailDelivery) => MaybePromise<void>;
 }
 
+/**
+ * Error thrown by mail helpers and provider adapters.
+ */
 export class MailDeliveryError extends Error {
+  /**
+   * Provider name when known.
+   */
   readonly provider?: string;
+  /**
+   * Original provider error when available.
+   */
   readonly cause?: unknown;
 
   constructor(args: { provider?: string; message: string; cause?: unknown }) {
@@ -86,6 +214,11 @@ export class MailDeliveryError extends Error {
   }
 }
 
+/**
+ * Normalize a single address or address list into an array.
+ *
+ * This helper does not validate email syntax.
+ */
 export function normalizeMailAddressList(
   addresses: MailAddressList | undefined,
 ): readonly MailAddress[] | undefined {
@@ -100,6 +233,9 @@ function normalizeOptionalMailAddressList(
   return normalized && normalized.length > 0 ? normalized : undefined;
 }
 
+/**
+ * Format one address for providers that accept RFC-like address strings.
+ */
 export function formatMailAddress(address: MailAddress): string {
   if (typeof address === "string") return address;
   if (!address.name) return address.email;
@@ -108,6 +244,9 @@ export function formatMailAddress(address: MailAddress): string {
   return `"${escapedName}" <${address.email}>`;
 }
 
+/**
+ * Format one or more addresses for providers that accept string address fields.
+ */
 export function formatMailAddressList(
   addresses: MailAddressList,
 ): string | string[] {
@@ -116,6 +255,11 @@ export function formatMailAddressList(
   return formatted.length === 1 ? formatted[0] : formatted;
 }
 
+/**
+ * Normalize a mail message and apply a default sender.
+ *
+ * Throws when the message has no recipients.
+ */
 export function normalizeMailMessage(
   message: SendMailOptions,
   options: { defaultFrom?: MailAddress } = {},
@@ -140,6 +284,11 @@ export function normalizeMailMessage(
   };
 }
 
+/**
+ * Create an in-memory mailer for tests, local development, and examples.
+ *
+ * The memory mailer does not send real email or validate address syntax.
+ */
 export function createMemoryMailer(
   options: CreateMemoryMailerOptions = {},
 ): MemoryMailerPort {