@beignet/core 0.0.1 → 0.0.3

package/src/ports/testing.ts

@@ -55,6 +55,9 @@ export function createRecordingEventBus(): {
   return { bus, events };
 }
 
+/**
+ * Expected outcome for one policy matrix case.
+ */
 export type PolicyMatrixExpectation = "allow" | "deny";
 
 type PolicyMatrixSubject<TResolver> =
@@ -62,6 +65,9 @@ type PolicyMatrixSubject<TResolver> =
     ? { subject: Subject }
     : { subject?: never };
 
+/**
+ * One typed authorization matrix case for a policy ability.
+ */
 export type PolicyMatrixCase<
   TContext,
   TPolicies extends readonly PolicyDefinition[] = readonly PolicyDefinition[],
@@ -76,6 +82,9 @@ export type PolicyMatrixCase<
   } & PolicyMatrixSubject<PolicyMapFromDefinitions<TPolicies>[TAbility]>;
 }[keyof PolicyMapFromDefinitions<TPolicies> & string];
 
+/**
+ * Untyped policy matrix case used internally for failure reporting.
+ */
 export type UntypedPolicyMatrixCase<TContext> = {
   name: string;
   ctx: TContext;
@@ -86,6 +95,9 @@ export type UntypedPolicyMatrixCase<TContext> = {
   code?: string;
 };
 
+/**
+ * Result for one evaluated policy matrix case.
+ */
 export type PolicyMatrixResult<
   TContext,
   TPolicies extends readonly PolicyDefinition[] = readonly PolicyDefinition[],
@@ -96,19 +108,40 @@ export type PolicyMatrixResult<
   message?: string;
 };
 
+/**
+ * Test helper for evaluating authorization policies.
+ */
 export type PolicyTester<
   TContext,
   TPolicies extends readonly PolicyDefinition[],
 > = {
+  /**
+   * Gate created from the same policies, useful for direct assertions.
+   */
   gate: GatePort<TContext, TPolicies>;
+  /**
+   * Evaluate cases and return structured pass/fail results.
+   */
   evaluateMatrix(
     cases: readonly PolicyMatrixCase<TContext, TPolicies>[],
   ): Promise<PolicyMatrixResult<TContext, TPolicies>[]>;
+  /**
+   * Evaluate cases and throw a combined assertion error when any fail.
+   */
   assertMatrix(
     cases: readonly PolicyMatrixCase<TContext, TPolicies>[],
   ): Promise<void>;
 };
 
+/**
+ * Create a policy tester from the same options used by `createGate(...)`.
+ *
+ * Use this for table-driven authorization tests that document who can perform
+ * each ability against which subject.
+ *
+ * @param options - Policy definitions and optional denial mapper.
+ * @returns A policy tester with a gate plus matrix helpers.
+ */
 export function createPolicyTester<
   const TPolicies extends readonly PolicyDefinition[],
 >(
@@ -126,6 +159,13 @@ export function createPolicyTester<
   };
 }
 
+/**
+ * Evaluate a table of policy cases without throwing.
+ *
+ * @param gate - Gate under test.
+ * @param cases - Matrix cases to evaluate.
+ * @returns Structured result for each case.
+ */
 export async function evaluatePolicyMatrix<
   TContext,
   TPolicies extends readonly PolicyDefinition[],
@@ -152,6 +192,13 @@ export async function evaluatePolicyMatrix<
   return results;
 }
 
+/**
+ * Assert that all policy matrix cases pass.
+ *
+ * @param gate - Gate under test.
+ * @param cases - Matrix cases to evaluate.
+ * @throws Combined error listing every failed case.
+ */
 export async function assertPolicyMatrix<
   TContext,
   TPolicies extends readonly PolicyDefinition[],

package/src/ports/unit-of-work.ts

@@ -3,6 +3,12 @@ import type { DomainEventDef, EventBusPort, InferEventPayload } from "./events";
 
 type MaybePromise<T> = T | Promise<T>;
 
+/**
+ * Work function executed inside a Unit of Work.
+ *
+ * `tx` contains transaction-scoped app ports, usually repositories plus
+ * side-effect recorders such as `events`, `jobs`, or `audit`.
+ */
 export type UnitOfWorkCallback<TxPorts, Result> = (
   tx: TxPorts,
 ) => MaybePromise<Result>;
@@ -15,11 +21,19 @@ export type UnitOfWorkCallback<TxPorts, Result> = (
  * `createNoopUnitOfWork`.
  */
 export interface UnitOfWorkPort<TxPorts> {
+  /**
+   * Run application work with transaction-scoped ports.
+   *
+   * Durable implementations should commit only if this callback resolves.
+   */
   transaction<Result>(
     work: UnitOfWorkCallback<TxPorts, Result>,
   ): Promise<Result>;
 }
 
+/**
+ * Hooks for `createNoopUnitOfWork(...)`.
+ */
 export interface NoopUnitOfWorkOptions<TxPorts> {
   /**
    * Runs after the callback completes successfully.
@@ -37,22 +51,56 @@ export interface NoopUnitOfWorkOptions<TxPorts> {
   afterRollback?: (error: unknown, tx: TxPorts) => MaybePromise<void>;
 }
 
+/**
+ * Domain event captured by a buffered event recorder.
+ */
 export interface RecordedDomainEvent {
+  /**
+   * Event definition used to validate the payload before publishing.
+   */
   event: DomainEventDef;
+  /**
+   * Stable event name.
+   */
   eventName: string;
+  /**
+   * Unparsed payload recorded during the transaction.
+   */
   payload: unknown;
 }
 
+/**
+ * Transaction-scoped port used to record domain events.
+ *
+ * Use cases record events here during the Unit of Work. The adapter decides
+ * whether to publish after commit, enqueue through an outbox, or buffer for a
+ * test assertion.
+ */
 export interface DomainEventRecorderPort {
+  /**
+   * Record a domain event payload.
+   */
   record<E extends DomainEventDef>(
     event: E,
     payload: InferEventPayload<E>,
-  ): void;
+  ): Promise<void> | void;
 }
 
+/**
+ * In-memory event recorder that can be inspected, cleared, or flushed.
+ */
 export interface BufferedDomainEventRecorder extends DomainEventRecorderPort {
+  /**
+   * Return recorded events without clearing them.
+   */
   entries(): readonly RecordedDomainEvent[];
+  /**
+   * Remove all recorded events.
+   */
   clear(): void;
+  /**
+   * Validate and publish all recorded events to an event bus in FIFO order.
+   */
   flush(eventBus: EventBusPort): Promise<void>;
 }
 
@@ -62,6 +110,11 @@ export interface BufferedDomainEventRecorder extends DomainEventRecorderPort {
  *
  * This helper does not create database transactions. It gives applications the
  * same UOW shape everywhere and runs commit/rollback hooks around the callback.
+ *
+ * @param txPortsOrFactory - Transaction-scoped ports or a factory that creates
+ * them per transaction call.
+ * @param options - Optional commit and rollback hooks.
+ * @returns A Unit of Work port with no durable transaction semantics.
  */
 export function createNoopUnitOfWork<TxPorts>(
   txPortsOrFactory: TxPorts | (() => TxPorts),
@@ -99,8 +152,12 @@ export function createNoopUnitOfWork<TxPorts>(
 }
 
 /**
- * Buffer domain events during a transaction and publish them only after the
- * owning Unit of Work commits.
+ * Create a recorder that buffers domain events until the caller flushes them.
+ *
+ * Unit of Work adapters commonly flush this recorder from an `afterCommit`
+ * hook so events are not published when the work rolls back.
+ *
+ * @returns A buffered domain event recorder for tests or Unit of Work adapters.
  */
 export function createDomainEventRecorder(): BufferedDomainEventRecorder {
   const records: RecordedDomainEvent[] = [];

package/src/providers/instrumentation.ts

@@ -1,86 +1,236 @@
 import { type Redactor, redactValue } from "../ports/redaction";
 
+/**
+ * Logical provider watcher name used to toggle groups of instrumentation
+ * events.
+ */
 export type ProviderInstrumentationWatcherName = string;
 
+/**
+ * Common metadata attached to every provider instrumentation event.
+ */
 export interface BaseProviderInstrumentationEvent {
+  /**
+   * Optional event identifier supplied by the caller.
+   */
   id?: string;
+  /**
+   * ISO timestamp supplied by the caller. Devtools can also assign a timestamp
+   * when one is omitted.
+   */
   timestamp?: string;
+  /**
+   * Request correlation ID for events emitted during request handling.
+   */
   requestId?: string;
+  /**
+   * Trace identifier for distributed tracing integrations.
+   */
   traceId?: string;
+  /**
+   * Span identifier for the current operation.
+   */
   spanId?: string;
+  /**
+   * Parent span identifier for nested operations.
+   */
   parentSpanId?: string;
+  /**
+   * W3C traceparent header value, when available.
+   */
   traceparent?: string;
+  /**
+   * Watcher category used by devtools and instrumentation sinks.
+   */
   watcher?: ProviderInstrumentationWatcherName;
+  /**
+   * Provider-specific structured details. Values are redacted before being
+   * recorded by `createProviderInstrumentation(...)`.
+   */
   details?: unknown;
 }
 
+/**
+ * HTTP request instrumentation emitted by server adapters.
+ */
 export interface RequestProviderInstrumentationEvent
   extends BaseProviderInstrumentationEvent {
   type: "request";
+  /**
+   * HTTP method.
+   */
   method: string;
+  /**
+   * Request path.
+   */
   path: string;
+  /**
+   * Matched contract name, when known.
+   */
   contractName?: string;
+  /**
+   * Response status code.
+   */
   status?: number;
+  /**
+   * Request duration in milliseconds.
+   */
   durationMs?: number;
+  /**
+   * Human-readable summary for devtools lists.
+   */
   summary?: string;
 }
 
+/**
+ * Error instrumentation emitted by framework hooks, use cases, or providers.
+ */
 export interface ErrorProviderInstrumentationEvent
   extends BaseProviderInstrumentationEvent {
   type: "error";
+  /**
+   * Error message.
+   */
   message: string;
+  /**
+   * Error stack trace, when available.
+   */
   stack?: string;
+  /**
+   * Contract associated with the error.
+   */
   contractName?: string;
+  /**
+   * Use case associated with the error.
+   */
   useCaseName?: string;
 }
 
+/**
+ * Use-case lifecycle instrumentation.
+ */
 export interface UseCaseProviderInstrumentationEvent
   extends BaseProviderInstrumentationEvent {
   type: "usecase";
+  /**
+   * Use-case name.
+   */
   name: string;
+  /**
+   * Optional classification used by devtools.
+   */
   kind?: "command" | "query";
+  /**
+   * Lifecycle phase.
+   */
   phase: "start" | "end" | "error";
+  /**
+   * Duration in milliseconds for completed phases.
+   */
   durationMs?: number;
+  /**
+   * Error summary for failed phases.
+   */
   error?: string;
 }
 
+/**
+ * Event bus instrumentation.
+ */
 export interface EventBusProviderInstrumentationEvent
   extends BaseProviderInstrumentationEvent {
   type: "eventBus";
+  /**
+   * Domain or integration event name.
+   */
   eventName: string;
 }
 
+/**
+ * Background job instrumentation.
+ */
 export interface JobProviderInstrumentationEvent
   extends BaseProviderInstrumentationEvent {
   type: "job";
+  /**
+   * Job name.
+   */
   jobName: string;
-  status: "scheduled" | "started" | "completed" | "failed";
+  /**
+   * Job lifecycle status.
+   */
+  status:
+    | "scheduled"
+    | "started"
+    | "completed"
+    | "failed"
+    | "retryScheduled"
+    | "deadLettered";
 }
 
+/**
+ * Scheduled task instrumentation.
+ */
 export interface ScheduleProviderInstrumentationEvent
   extends BaseProviderInstrumentationEvent {
   type: "schedule";
+  /**
+   * Schedule name.
+   */
   scheduleName: string;
+  /**
+   * Schedule run lifecycle status.
+   */
   status: "started" | "completed" | "failed";
+  /**
+   * Cron expression for the schedule, when known.
+   */
   cron?: string;
+  /**
+   * Time zone used by the schedule, when known.
+   */
   timezone?: string;
 }
 
+/**
+ * Provider lifecycle instrumentation emitted during setup, start, and stop.
+ */
 export interface ProviderLifecycleInstrumentationEvent
   extends BaseProviderInstrumentationEvent {
   type: "provider";
+  /**
+   * Provider name.
+   */
   providerName: string;
+  /**
+   * Lifecycle action.
+   */
   action: "setup" | "start" | "stop";
 }
 
+/**
+ * Custom provider instrumentation event for provider-owned operations.
+ */
 export interface CustomProviderInstrumentationEvent
   extends BaseProviderInstrumentationEvent {
   type: "custom";
+  /**
+   * Stable event name.
+   */
   name: string;
+  /**
+   * Short display label for devtools.
+   */
   label?: string;
+  /**
+   * Human-readable summary for devtools lists.
+   */
   summary?: string;
 }
 
+/**
+ * Union of instrumentation events that provider sinks can receive.
+ */
 export type ProviderInstrumentationEvent =
   | RequestProviderInstrumentationEvent
   | ErrorProviderInstrumentationEvent
@@ -91,36 +241,82 @@ export type ProviderInstrumentationEvent =
   | ProviderLifecycleInstrumentationEvent
   | CustomProviderInstrumentationEvent;
 
+/**
+ * Input accepted by provider instrumentation recorders.
+ */
 export type ProviderInstrumentationEventInput = ProviderInstrumentationEvent;
 
+/**
+ * Custom instrumentation input. `type: "custom"` is added by the helper.
+ */
 export type ProviderCustomInstrumentationEventInput = Omit<
   CustomProviderInstrumentationEvent,
   "type"
 >;
 
+/**
+ * Sink for provider instrumentation events.
+ */
 export interface ProviderInstrumentationPort<
   EventInput extends
     ProviderInstrumentationEventInput = ProviderInstrumentationEventInput,
   WatcherName extends string = ProviderInstrumentationWatcherName,
   RecordResult = unknown,
 > {
+  /**
+   * Record an instrumentation event.
+   */
   record(event: EventInput): RecordResult;
+  /**
+   * Return whether a watcher is enabled. Missing methods are treated as
+   * enabled so simple sinks only need to implement `record`.
+   */
   isWatcherEnabled?(name: WatcherName): boolean;
 }
 
+/**
+ * Options for creating a provider instrumentation helper.
+ */
 export interface ProviderInstrumentationOptions {
+  /**
+   * Provider name to attach to custom event details.
+   */
   providerName: string;
+  /**
+   * Default watcher name for events emitted by the helper.
+   */
   watcher?: ProviderInstrumentationWatcherName;
+  /**
+   * Optional redactor applied after Beignet's default redaction pass.
+   */
   redact?: Redactor<ProviderInstrumentationEventInput>;
 }
 
+/**
+ * Convenience wrapper used by providers to emit safe, watcher-aware events.
+ */
 export interface ProviderInstrumentation {
+  /**
+   * Resolved instrumentation port, when one is available.
+   */
   port: ProviderInstrumentationPort | undefined;
+  /**
+   * Return whether the given watcher is enabled.
+   */
   isEnabled(watcher?: ProviderInstrumentationWatcherName): boolean;
+  /**
+   * Record a fully formed provider instrumentation event.
+   */
   record(event: ProviderInstrumentationEventInput): unknown;
+  /**
+   * Record a provider-owned custom event.
+   */
   custom(event: ProviderCustomInstrumentationEventInput): unknown;
 }
 
+/**
+ * Values accepted by `createProviderInstrumentation(...)`.
+ */
 export type ProviderInstrumentationTarget =
   | ProviderInstrumentationPort
   | ProviderInstrumentation
@@ -134,6 +330,9 @@ function isObject(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null;
 }
 
+/**
+ * Return whether a value is a provider instrumentation helper.
+ */
 export function isProviderInstrumentation(
   value: unknown,
 ): value is ProviderInstrumentation {
@@ -145,6 +344,9 @@ export function isProviderInstrumentation(
   );
 }
 
+/**
+ * Return whether a value is a provider instrumentation port.
+ */
 export function isProviderInstrumentationPort(
   value: unknown,
 ): value is ProviderInstrumentationPort {
@@ -159,6 +361,10 @@ function resolveProviderInstrumentationValue(
   return undefined;
 }
 
+/**
+ * Resolve an instrumentation port from a direct port, helper, or context-like
+ * object.
+ */
 export function resolveProviderInstrumentationPort(
   target: ProviderInstrumentationTarget,
 ): ProviderInstrumentationPort | undefined {
@@ -187,6 +393,10 @@ function withProviderDetails(providerName: string, details: unknown): unknown {
   return { providerName, value: details };
 }
 
+/**
+ * Create a provider instrumentation helper that handles watcher checks,
+ * default watcher assignment, redaction, and sink failures.
+ */
 export function createProviderInstrumentation(
   target: ProviderInstrumentationTarget,
   options: ProviderInstrumentationOptions,

package/src/providers/provider.ts

@@ -38,12 +38,24 @@ export interface ProviderConfigDef<CfgSchema extends StandardSchemaV1> {
   envPrefix?: string;
 }
 
+/**
+ * Value or promise of that value.
+ */
 export type MaybePromise<T> = T | Promise<T>;
 
+/**
+ * Context passed to provider lifecycle hooks.
+ */
 export type ProviderLifecycleContext = {
+  /**
+   * Final app ports after provider setup.
+   */
   ports: Readonly<ProviderPorts>;
 };
 
+/**
+ * Result returned from provider setup.
+ */
 export type ProviderSetupResult<ProvidedPorts extends ProviderPorts> = {
   /**
    * Ports contributed by this provider.
@@ -113,7 +125,8 @@ export interface ServiceProvider<
 
   /**
    * Setup phase: create the ports this provider contributes.
-   * Called during app initialization, before routes are registered.
+   * Called during server initialization before provider `start` hooks and
+   * before the server handles requests.
    *
    * @param ctx.ports - Ports contributed by previous providers
    * @param ctx.config - Validated config (if config was defined), or undefined