@beignet/core 0.0.1 → 0.0.3

package/src/events/index.ts

@@ -1,83 +1,187 @@
 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>;
 
+/**
+ * Minimal event definition shape accepted by event bus helpers.
+ */
 export interface EventPayloadDef<
   Name extends string = string,
   Payload extends StandardSchema = StandardSchema,
 > {
+  /**
+   * Stable event name.
+   */
   readonly name: Name;
+  /**
+   * Standard Schema payload validator.
+   */
   readonly payload: Payload;
+  /**
+   * Optional human-readable description for docs and tooling.
+   */
   readonly description?: string;
 }
 
+/**
+ * Event definition created by `defineEvent(...)`.
+ */
 export interface EventDef<
   Name extends string = string,
   Payload extends StandardSchema = StandardSchema,
 > extends EventPayloadDef<Name, Payload> {
+  /**
+   * Discriminator for event definitions.
+   */
   readonly kind: "event";
 }
 
+/**
+ * Infer the parsed payload type for an event definition.
+ */
 export type InferEventPayload<E extends EventPayloadDef> =
   E["payload"] extends StandardSchemaV1<unknown, infer Output> ? Output : never;
 
+/**
+ * Options for `defineEvent(...)`.
+ */
 export interface DefineEventOptions<Payload extends StandardSchema> {
+  /**
+   * Standard Schema payload validator.
+   */
   payload: Payload;
+  /**
+   * Optional human-readable description for docs and tooling.
+   */
   description?: string;
 }
 
+/**
+ * Arguments passed to a listener handler.
+ */
 export interface ListenerHandleArgs<E extends EventDef, Ctx> {
+  /**
+   * Event definition being handled.
+   */
   event: E;
+  /**
+   * Parsed event payload.
+   */
   payload: InferEventPayload<E>;
+  /**
+   * Listener context.
+   */
   ctx: Ctx;
 }
 
+/**
+ * Listener definition created by `defineListener(...)`.
+ */
 export interface ListenerDef<
   E extends EventDef = EventDef,
   Ctx = unknown,
   Name extends string = string,
 > {
+  /**
+   * Discriminator for listener definitions.
+   */
   readonly kind: "listener";
+  /**
+   * Stable listener name.
+   */
   readonly name: Name;
+  /**
+   * Event this listener handles.
+   */
   readonly event: E;
+  /**
+   * Handle a parsed event payload.
+   */
   handle(args: ListenerHandleArgs<E, Ctx>): MaybePromise<void>;
 }
 
+/**
+ * Options for `defineListener(...)`.
+ */
 export interface DefineListenerOptions<
   E extends EventDef,
   Ctx,
   Name extends string,
 > {
+  /**
+   * Stable listener name.
+   */
   name: Name;
+  /**
+   * Handle a parsed event payload.
+   */
   handle(args: ListenerHandleArgs<E, Ctx>): MaybePromise<void>;
 }
 
+/**
+ * Event bus shape required by Beignet listener registration helpers.
+ */
 export interface EventBusLike {
+  /**
+   * Publish an event payload.
+   */
   publish<E extends EventPayloadDef>(
     event: E,
     payload: InferEventPayload<E>,
   ): MaybePromise<void>;
+  /**
+   * Subscribe to an event and return an unsubscribe function.
+   */
   subscribe<E extends EventPayloadDef>(
     event: E,
     handler: (payload: InferEventPayload<E>) => MaybePromise<void>,
   ): () => void;
 }
 
+/**
+ * Options for `registerListeners(...)`.
+ */
 export interface RegisterListenersOptions<Ctx> {
+  /**
+   * Static listener context or factory evaluated for each delivered event.
+   */
   ctx?: Ctx | (() => MaybePromise<Ctx>);
+  /**
+   * Called when a listener fails. When omitted, listener errors are rethrown to
+   * the event bus subscription callback.
+   */
   onError?: (error: unknown, listener: ListenerDef<EventDef, Ctx>) => void;
 }
 
+/**
+ * Context-bound event helper factory.
+ */
 export interface EventHandlers<Ctx> {
+  /**
+   * Define a listener with the bound context type.
+   */
   defineListener<E extends EventDef, Name extends string = string>(
     event: E,
     options: DefineListenerOptions<E, Ctx, Name>,
   ): ListenerDef<E, Ctx, Name>;
 
+  /**
+   * Register listeners with an event bus.
+   */
   registerListeners(
     eventBus: EventBusLike,
     listeners: readonly ListenerDef<EventDef, Ctx>[],
@@ -85,7 +189,13 @@ export interface EventHandlers<Ctx> {
   ): () => void;
 }
 
+/**
+ * Error thrown when event payload validation fails.
+ */
 export class EventValidationError extends Error {
+  /**
+   * Raw Standard Schema validation issues.
+   */
   readonly issues: readonly StandardSchemaV1.Issue[];
 
   constructor(args: {
@@ -152,6 +262,12 @@ async function resolveCtx<Ctx>(
   return ctx as Ctx;
 }
 
+/**
+ * Define a typed event.
+ *
+ * Event payloads are validated before publishing through `publishEvent(...)`
+ * and before registered listeners run.
+ */
 export function defineEvent<
   Name extends string,
   Payload extends StandardSchema,
@@ -164,6 +280,9 @@ export function defineEvent<
   };
 }
 
+/**
+ * Define a listener for one event.
+ */
 export function defineListener<
   E extends EventDef,
   Ctx = unknown,
@@ -180,6 +299,9 @@ export function defineListener<
   };
 }
 
+/**
+ * Validate and parse an event payload with the event's Standard Schema.
+ */
 export async function parseEventPayload<E extends EventPayloadDef>(
   event: E,
   payload: unknown,
@@ -189,6 +311,9 @@ export async function parseEventPayload<E extends EventPayloadDef>(
   })) as InferEventPayload<E>;
 }
 
+/**
+ * Validate an event payload and publish it through an event bus.
+ */
 export async function publishEvent<E extends EventPayloadDef>(
   eventBus: EventBusLike,
   event: E,
@@ -198,6 +323,12 @@ export async function publishEvent<E extends EventPayloadDef>(
   await eventBus.publish(event, parsed);
 }
 
+/**
+ * Register listeners against an event bus and return an unsubscribe function.
+ *
+ * Payloads are validated before listener handlers run. Listener context is
+ * resolved per delivery when `options.ctx` is a factory.
+ */
 export function registerListeners<Ctx>(
   eventBus: EventBusLike,
   listeners: readonly ListenerDef<EventDef, Ctx>[],
@@ -226,6 +357,9 @@ export function registerListeners<Ctx>(
   };
 }
 
+/**
+ * Create event helper methods bound to an application context type.
+ */
 export function createEventHandlers<Ctx>(): EventHandlers<Ctx> {
   return {
     defineListener<E extends EventDef, Name extends string = string>(