@beignet/core 0.0.1

package/src/events/index.ts

@@ -0,0 +1,246 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+
+export type StandardSchema = StandardSchemaV1<unknown, unknown>;
+export type MaybePromise<T> = T | Promise<T>;
+
+export type InferSchemaOutput<T extends StandardSchemaV1> =
+  StandardSchemaV1.InferOutput<T>;
+
+export interface EventPayloadDef<
+  Name extends string = string,
+  Payload extends StandardSchema = StandardSchema,
+> {
+  readonly name: Name;
+  readonly payload: Payload;
+  readonly description?: string;
+}
+
+export interface EventDef<
+  Name extends string = string,
+  Payload extends StandardSchema = StandardSchema,
+> extends EventPayloadDef<Name, Payload> {
+  readonly kind: "event";
+}
+
+export type InferEventPayload<E extends EventPayloadDef> =
+  E["payload"] extends StandardSchemaV1<unknown, infer Output> ? Output : never;
+
+export interface DefineEventOptions<Payload extends StandardSchema> {
+  payload: Payload;
+  description?: string;
+}
+
+export interface ListenerHandleArgs<E extends EventDef, Ctx> {
+  event: E;
+  payload: InferEventPayload<E>;
+  ctx: Ctx;
+}
+
+export interface ListenerDef<
+  E extends EventDef = EventDef,
+  Ctx = unknown,
+  Name extends string = string,
+> {
+  readonly kind: "listener";
+  readonly name: Name;
+  readonly event: E;
+  handle(args: ListenerHandleArgs<E, Ctx>): MaybePromise<void>;
+}
+
+export interface DefineListenerOptions<
+  E extends EventDef,
+  Ctx,
+  Name extends string,
+> {
+  name: Name;
+  handle(args: ListenerHandleArgs<E, Ctx>): MaybePromise<void>;
+}
+
+export interface EventBusLike {
+  publish<E extends EventPayloadDef>(
+    event: E,
+    payload: InferEventPayload<E>,
+  ): MaybePromise<void>;
+  subscribe<E extends EventPayloadDef>(
+    event: E,
+    handler: (payload: InferEventPayload<E>) => MaybePromise<void>,
+  ): () => void;
+}
+
+export interface RegisterListenersOptions<Ctx> {
+  ctx?: Ctx | (() => MaybePromise<Ctx>);
+  onError?: (error: unknown, listener: ListenerDef<EventDef, Ctx>) => void;
+}
+
+export interface EventHandlers<Ctx> {
+  defineListener<E extends EventDef, Name extends string = string>(
+    event: E,
+    options: DefineListenerOptions<E, Ctx, Name>,
+  ): ListenerDef<E, Ctx, Name>;
+
+  registerListeners(
+    eventBus: EventBusLike,
+    listeners: readonly ListenerDef<EventDef, Ctx>[],
+    options?: RegisterListenersOptions<Ctx>,
+  ): () => void;
+}
+
+export class EventValidationError extends Error {
+  readonly issues: readonly StandardSchemaV1.Issue[];
+
+  constructor(args: {
+    name: string;
+    issues: readonly StandardSchemaV1.Issue[];
+  }) {
+    super(
+      `Event "${args.name}" payload validation failed: ${formatIssues(args.issues)}`,
+    );
+    this.name = "EventValidationError";
+    this.issues = args.issues;
+  }
+}
+
+function formatPath(path: StandardSchemaV1.Issue["path"]): string {
+  if (!path?.length) return "";
+
+  return path
+    .map((segment) =>
+      typeof segment === "object" && segment !== null && "key" in segment
+        ? String(segment.key)
+        : String(segment),
+    )
+    .join(".");
+}
+
+function formatIssues(issues: readonly StandardSchemaV1.Issue[]): string {
+  return issues
+    .map((issue) => {
+      const path = formatPath(issue.path);
+      return path ? `${path}: ${issue.message}` : issue.message;
+    })
+    .join("; ");
+}
+
+async function parsePayload<Schema extends StandardSchemaV1>(
+  schema: Schema,
+  input: unknown,
+  args: { name: string },
+): Promise<InferSchemaOutput<Schema>> {
+  const result = await schema["~standard"].validate(input);
+
+  if (result.issues?.length) {
+    throw new EventValidationError({
+      name: args.name,
+      issues: result.issues,
+    });
+  }
+
+  if ("value" in result) {
+    return result.value as InferSchemaOutput<Schema>;
+  }
+
+  throw new Error("Invalid Standard Schema result: missing value");
+}
+
+async function resolveCtx<Ctx>(
+  ctx: Ctx | (() => MaybePromise<Ctx>) | undefined,
+): Promise<Ctx> {
+  if (typeof ctx === "function") {
+    return (ctx as () => MaybePromise<Ctx>)();
+  }
+
+  return ctx as Ctx;
+}
+
+export function defineEvent<
+  Name extends string,
+  Payload extends StandardSchema,
+>(name: Name, options: DefineEventOptions<Payload>): EventDef<Name, Payload> {
+  return {
+    kind: "event",
+    name,
+    payload: options.payload,
+    description: options.description,
+  };
+}
+
+export function defineListener<
+  E extends EventDef,
+  Ctx = unknown,
+  Name extends string = string,
+>(
+  event: E,
+  options: DefineListenerOptions<E, Ctx, Name>,
+): ListenerDef<E, Ctx, Name> {
+  return {
+    kind: "listener",
+    name: options.name,
+    event,
+    handle: options.handle,
+  };
+}
+
+export async function parseEventPayload<E extends EventPayloadDef>(
+  event: E,
+  payload: unknown,
+): Promise<InferEventPayload<E>> {
+  return (await parsePayload(event.payload, payload, {
+    name: event.name,
+  })) as InferEventPayload<E>;
+}
+
+export async function publishEvent<E extends EventPayloadDef>(
+  eventBus: EventBusLike,
+  event: E,
+  payload: InferEventPayload<E>,
+): Promise<void> {
+  const parsed = await parseEventPayload(event, payload);
+  await eventBus.publish(event, parsed);
+}
+
+export function registerListeners<Ctx>(
+  eventBus: EventBusLike,
+  listeners: readonly ListenerDef<EventDef, Ctx>[],
+  options: RegisterListenersOptions<Ctx> = {},
+): () => void {
+  const unsubscribes = listeners.map((listener) =>
+    eventBus.subscribe(listener.event, async (rawPayload) => {
+      try {
+        const payload = await parseEventPayload(listener.event, rawPayload);
+        await listener.handle({
+          event: listener.event,
+          payload,
+          ctx: await resolveCtx(options.ctx),
+        });
+      } catch (error) {
+        options.onError?.(error, listener);
+        if (!options.onError) throw error;
+      }
+    }),
+  );
+
+  return () => {
+    for (const unsubscribe of [...unsubscribes].reverse()) {
+      unsubscribe();
+    }
+  };
+}
+
+export function createEventHandlers<Ctx>(): EventHandlers<Ctx> {
+  return {
+    defineListener<E extends EventDef, Name extends string = string>(
+      event: E,
+      options: DefineListenerOptions<E, Ctx, Name>,
+    ): ListenerDef<E, Ctx, Name> {
+      return defineListener(event, options);
+    },
+
+    registerListeners(
+      eventBus: EventBusLike,
+      listeners: readonly ListenerDef<EventDef, Ctx>[],
+      options: RegisterListenersOptions<Ctx> = {},
+    ): () => void {
+      return registerListeners(eventBus, listeners, options);
+    },
+  };
+}

package/src/jobs/index.ts

@@ -0,0 +1,211 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+
+export type StandardSchema = StandardSchemaV1<unknown, unknown>;
+export type MaybePromise<T> = T | Promise<T>;
+
+export type InferSchemaOutput<T extends StandardSchemaV1> =
+  StandardSchemaV1.InferOutput<T>;
+
+export interface JobDef<
+  Name extends string = string,
+  Payload extends StandardSchema = StandardSchema,
+  Ctx = unknown,
+> {
+  readonly kind: "job";
+  readonly name: Name;
+  readonly payload: Payload;
+  readonly description?: string;
+  readonly retry?: JobRetryOptions;
+  handle(
+    args: JobHandleArgs<JobDef<Name, Payload, Ctx>, Ctx>,
+  ): MaybePromise<void>;
+}
+
+export type InferJobPayload<J extends JobDef> =
+  J["payload"] extends StandardSchemaV1<unknown, infer Output> ? Output : never;
+
+export interface JobHandleArgs<J extends JobDef, Ctx> {
+  job: J;
+  payload: InferJobPayload<J>;
+  ctx: 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.
+   */
+  attempts?: number;
+}
+
+export interface DefineJobOptions<
+  Name extends string,
+  Payload extends StandardSchema,
+  Ctx,
+> {
+  payload: Payload;
+  description?: string;
+  retry?: JobRetryOptions;
+  handle(
+    args: JobHandleArgs<JobDef<Name, Payload, Ctx>, Ctx>,
+  ): MaybePromise<void>;
+}
+
+export interface InlineJobDispatcherOptions<Ctx> {
+  ctx?: Ctx | (() => MaybePromise<Ctx>);
+  onError?: (error: unknown, job: JobDef<string, StandardSchema, Ctx>) => void;
+}
+
+export interface InlineJobDispatcher<Ctx = unknown> {
+  dispatch<J extends JobDef<string, StandardSchema, Ctx>>(
+    job: J,
+    payload: InferJobPayload<J>,
+  ): Promise<void>;
+}
+
+export interface JobHandlers<Ctx> {
+  defineJob<Name extends string, Payload extends StandardSchema>(
+    name: Name,
+    options: DefineJobOptions<Name, Payload, Ctx>,
+  ): JobDef<Name, Payload, Ctx>;
+
+  createInlineJobDispatcher(
+    options?: InlineJobDispatcherOptions<Ctx>,
+  ): InlineJobDispatcher<Ctx>;
+}
+
+export class JobValidationError extends Error {
+  readonly issues: readonly StandardSchemaV1.Issue[];
+
+  constructor(args: {
+    name: string;
+    issues: readonly StandardSchemaV1.Issue[];
+  }) {
+    super(
+      `Job "${args.name}" payload validation failed: ${formatIssues(args.issues)}`,
+    );
+    this.name = "JobValidationError";
+    this.issues = args.issues;
+  }
+}
+
+function formatPath(path: StandardSchemaV1.Issue["path"]): string {
+  if (!path?.length) return "";
+
+  return path
+    .map((segment) =>
+      typeof segment === "object" && segment !== null && "key" in segment
+        ? String(segment.key)
+        : String(segment),
+    )
+    .join(".");
+}
+
+function formatIssues(issues: readonly StandardSchemaV1.Issue[]): string {
+  return issues
+    .map((issue) => {
+      const path = formatPath(issue.path);
+      return path ? `${path}: ${issue.message}` : issue.message;
+    })
+    .join("; ");
+}
+
+async function parsePayload<Schema extends StandardSchemaV1>(
+  schema: Schema,
+  input: unknown,
+  args: { name: string },
+): Promise<InferSchemaOutput<Schema>> {
+  const result = await schema["~standard"].validate(input);
+
+  if (result.issues?.length) {
+    throw new JobValidationError({
+      name: args.name,
+      issues: result.issues,
+    });
+  }
+
+  if ("value" in result) {
+    return result.value as InferSchemaOutput<Schema>;
+  }
+
+  throw new Error("Invalid Standard Schema result: missing value");
+}
+
+async function resolveCtx<Ctx>(
+  ctx: Ctx | (() => MaybePromise<Ctx>) | undefined,
+): Promise<Ctx> {
+  if (typeof ctx === "function") {
+    return (ctx as () => MaybePromise<Ctx>)();
+  }
+
+  return ctx as Ctx;
+}
+
+export function defineJob<
+  Name extends string,
+  Payload extends StandardSchema,
+  Ctx = unknown,
+>(
+  name: Name,
+  options: DefineJobOptions<Name, Payload, Ctx>,
+): JobDef<Name, Payload, Ctx> {
+  return {
+    kind: "job",
+    name,
+    payload: options.payload,
+    description: options.description,
+    retry: options.retry,
+    handle: options.handle as JobDef<Name, Payload, Ctx>["handle"],
+  };
+}
+
+export async function parseJobPayload<J extends JobDef>(
+  job: J,
+  payload: unknown,
+): Promise<InferJobPayload<J>> {
+  return (await parsePayload(job.payload, payload, {
+    name: job.name,
+  })) as InferJobPayload<J>;
+}
+
+export function createInlineJobDispatcher<Ctx>(
+  options: InlineJobDispatcherOptions<Ctx> = {},
+): InlineJobDispatcher<Ctx> {
+  return {
+    async dispatch<J extends JobDef<string, StandardSchema, Ctx>>(
+      job: J,
+      payload: InferJobPayload<J>,
+    ) {
+      try {
+        const parsed = await parseJobPayload(job, payload);
+        await job.handle({
+          job,
+          payload: parsed,
+          ctx: await resolveCtx(options.ctx),
+        });
+      } catch (error) {
+        options.onError?.(error, job);
+        if (!options.onError) throw error;
+      }
+    },
+  };
+}
+
+export function createJobHandlers<Ctx>(): JobHandlers<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);
+    },
+  };
+}

package/src/mail/index.ts

@@ -0,0 +1,177 @@
+/**
+ * @beignet/core/mail
+ *
+ * Shared mail port and test adapters for Beignet applications.
+ */
+
+export type MaybePromise<T> = T | Promise<T>;
+
+export type MailAddress =
+  | string
+  | {
+      email: string;
+      name?: string;
+    };
+
+export type MailAddressList = MailAddress | readonly MailAddress[];
+
+export interface MailBaseMessage {
+  to: MailAddressList;
+  subject: string;
+  from?: MailAddress;
+  cc?: MailAddressList;
+  bcc?: MailAddressList;
+  replyTo?: MailAddressList;
+  headers?: Record<string, string>;
+}
+
+export type SendMailOptions = MailBaseMessage &
+  (
+    | {
+        text: string;
+        html?: string;
+      }
+    | {
+        html: string;
+        text?: string;
+      }
+  );
+
+export interface NormalizedMailMessage extends MailBaseMessage {
+  to: readonly MailAddress[];
+  from?: MailAddress;
+  cc?: readonly MailAddress[];
+  bcc?: readonly MailAddress[];
+  replyTo?: readonly MailAddress[];
+  text?: string;
+  html?: string;
+}
+
+export interface SendMailResult {
+  id?: string;
+  provider?: string;
+}
+
+export interface MailerPort {
+  send(message: SendMailOptions): Promise<SendMailResult>;
+}
+
+export interface MemoryMailDelivery {
+  id: string;
+  message: NormalizedMailMessage;
+  sentAt: Date;
+}
+
+export interface MemoryMailerPort extends MailerPort {
+  readonly deliveries: readonly MemoryMailDelivery[];
+  clear(): void;
+}
+
+export interface CreateMemoryMailerOptions {
+  defaultFrom?: MailAddress;
+  now?: () => Date;
+  id?: () => string;
+  onSend?: (delivery: MemoryMailDelivery) => MaybePromise<void>;
+}
+
+export class MailDeliveryError extends Error {
+  readonly provider?: string;
+  readonly cause?: unknown;
+
+  constructor(args: { provider?: string; message: string; cause?: unknown }) {
+    super(args.message);
+    this.name = "MailDeliveryError";
+    this.provider = args.provider;
+    this.cause = args.cause;
+  }
+}
+
+export function normalizeMailAddressList(
+  addresses: MailAddressList | undefined,
+): readonly MailAddress[] | undefined {
+  if (addresses === undefined) return undefined;
+  return Array.isArray(addresses) ? [...addresses] : [addresses as MailAddress];
+}
+
+function normalizeOptionalMailAddressList(
+  addresses: MailAddressList | undefined,
+): readonly MailAddress[] | undefined {
+  const normalized = normalizeMailAddressList(addresses);
+  return normalized && normalized.length > 0 ? normalized : undefined;
+}
+
+export function formatMailAddress(address: MailAddress): string {
+  if (typeof address === "string") return address;
+  if (!address.name) return address.email;
+
+  const escapedName = address.name.replace(/"/g, '\\"');
+  return `"${escapedName}" <${address.email}>`;
+}
+
+export function formatMailAddressList(
+  addresses: MailAddressList,
+): string | string[] {
+  const normalized = normalizeMailAddressList(addresses) ?? [];
+  const formatted = normalized.map(formatMailAddress);
+  return formatted.length === 1 ? formatted[0] : formatted;
+}
+
+export function normalizeMailMessage(
+  message: SendMailOptions,
+  options: { defaultFrom?: MailAddress } = {},
+): NormalizedMailMessage {
+  const to = normalizeMailAddressList(message.to) ?? [];
+
+  if (to.length === 0) {
+    throw new MailDeliveryError({
+      message: "Cannot send email without at least one recipient.",
+    });
+  }
+
+  return {
+    ...message,
+    to,
+    from: message.from ?? options.defaultFrom,
+    cc: normalizeOptionalMailAddressList(message.cc),
+    bcc: normalizeOptionalMailAddressList(message.bcc),
+    replyTo: normalizeOptionalMailAddressList(message.replyTo),
+    text: "text" in message ? message.text : undefined,
+    html: "html" in message ? message.html : undefined,
+  };
+}
+
+export function createMemoryMailer(
+  options: CreateMemoryMailerOptions = {},
+): MemoryMailerPort {
+  const deliveries: MemoryMailDelivery[] = [];
+  const now = options.now ?? (() => new Date());
+  const id = options.id ?? (() => crypto.randomUUID());
+
+  return {
+    get deliveries() {
+      return deliveries;
+    },
+
+    async send(message) {
+      const delivery: MemoryMailDelivery = {
+        id: id(),
+        message: normalizeMailMessage(message, {
+          defaultFrom: options.defaultFrom,
+        }),
+        sentAt: now(),
+      };
+
+      deliveries.push(delivery);
+      await options.onSend?.(delivery);
+
+      return {
+        id: delivery.id,
+        provider: "memory",
+      };
+    },
+
+    clear() {
+      deliveries.length = 0;
+    },
+  };
+}