@beignet/core 0.0.1 → 0.0.2

package/dist/ports/redaction.js

@@ -1,6 +1,18 @@
+/**
+ * Default replacement used when a sensitive field is redacted.
+ */
 export const DEFAULT_REDACTED_VALUE = "[redacted]";
+/**
+ * Default replacement used when recursive redaction exceeds `maxDepth`.
+ */
 export const DEFAULT_TRUNCATED_VALUE = "[truncated]";
+/**
+ * Default replacement used when recursive redaction finds a circular object.
+ */
 export const DEFAULT_CIRCULAR_VALUE = "[circular]";
+/**
+ * Exact header/object keys redacted by default.
+ */
 export const DEFAULT_SENSITIVE_KEYS = [
     "authorization",
     "cookie",
@@ -12,6 +24,11 @@ export const DEFAULT_SENSITIVE_KEYS = [
     "refresh-token",
     "credentials",
 ];
+/**
+ * Key substrings redacted by default.
+ *
+ * Matching is case-insensitive.
+ */
 export const DEFAULT_SENSITIVE_KEY_TERMS = [
     "token",
     "password",
@@ -23,6 +40,17 @@ export const DEFAULT_SENSITIVE_KEY_TERMS = [
 function normalizeKey(key) {
     return key.toLowerCase();
 }
+/**
+ * Return whether a key should be redacted.
+ *
+ * Checks default exact keys, default key terms, user-provided exact keys,
+ * user-provided key terms, and finally `shouldRedactKey`.
+ *
+ * @param key - Object or header key to evaluate.
+ * @param options - Optional redaction behavior.
+ * @param context - Optional path/value context for custom decisions.
+ * @returns `true` when the key should be replaced.
+ */
 export function isSensitiveKey(key, options = {}, context) {
     const normalized = normalizeKey(key);
     const exactKeys = new Set([...DEFAULT_SENSITIVE_KEYS, ...(options.sensitiveKeys ?? [])].map(normalizeKey));
@@ -91,6 +119,20 @@ function redactUnknown(value, options, path, seen) {
     seen.delete(objectValue);
     return output;
 }
+/**
+ * Recursively redact a value using Beignet's default sensitive-key rules plus
+ * any custom rules in `options`.
+ *
+ * This returns a copy for objects and arrays. Primitive values are returned as
+ * is unless they are under a sensitive key. Some runtime shapes are normalized:
+ * `bigint` becomes a string, `Error` becomes a plain object with `name`,
+ * `message`, and `stack`, and class instances are copied from enumerable
+ * entries.
+ *
+ * @param value - Value to redact.
+ * @param options - Optional redaction behavior.
+ * @returns A redacted value typed as the input type for caller convenience.
+ */
 export function redactValue(value, options = {}) {
     return redactUnknown(value, options, [], new WeakSet());
 }
@@ -108,6 +150,17 @@ function headerEntries(headers) {
     }
     return Object.entries(headers);
 }
+/**
+ * Redact headers into a plain object.
+ *
+ * Sensitive header names such as `authorization`, `cookie`, and token-like keys
+ * are replaced. Non-sensitive values are passed through `redactValue(...)` so
+ * nested object values are still sanitized.
+ *
+ * @param headers - Headers object, iterable entries, or plain object.
+ * @param options - Optional redaction behavior.
+ * @returns A plain object with redacted header values.
+ */
 export function redactHeaders(headers, options = {}) {
     const output = {};
     for (const [key, value] of headerEntries(headers)) {
@@ -120,6 +173,12 @@ export function redactHeaders(headers, options = {}) {
     }
     return output;
 }
+/**
+ * Create a reusable redactor function from options.
+ *
+ * @param options - Redaction behavior to apply on each call.
+ * @returns A function that redacts values with the provided options.
+ */
 export function createRedactor(options = {}) {
     return (value) => redactValue(value, options);
 }

package/dist/ports/redaction.js.map

@@ -1 +1 @@
-{"version":3,"file":"redaction.js","sourceRoot":"","sources":["../../src/ports/redaction.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"redaction.js","sourceRoot":"","sources":["../../src/ports/redaction.ts"],"names":[],"mappings":"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"}

package/dist/ports/storage.d.ts

@@ -1,21 +1,70 @@
+/**
+ * Object visibility understood by storage ports.
+ */
 export type StorageVisibility = "private" | "public";
+/**
+ * String metadata stored alongside an object.
+ */
 export type StorageMetadata = Record<string, string>;
+/**
+ * Body types accepted by `StoragePort.put(...)`.
+ */
 export type StorageBody = string | ArrayBuffer | Uint8Array | Blob | ReadableStream<Uint8Array>;
+/**
+ * Options for writing an object to storage.
+ */
 export interface StoragePutOptions {
+    /**
+     * MIME content type stored with the object.
+     */
     contentType?: string;
+    /**
+     * Cache-Control value stored with the object.
+     */
     cacheControl?: string;
+    /**
+     * Provider metadata stored with the object.
+     */
     metadata?: StorageMetadata;
+    /**
+     * Whether the object may receive a public URL.
+     */
     visibility?: StorageVisibility;
 }
+/**
+ * Metadata for an object in storage.
+ */
 export interface StorageObject {
+    /**
+     * Object key. Keys are relative object-store paths, not filesystem paths or
+     * public URLs.
+     */
     key: string;
+    /**
+     * Object size in bytes.
+     */
     size: number;
     contentType?: string;
     cacheControl?: string;
+    /**
+     * Provider metadata stored with the object.
+     */
     metadata: StorageMetadata;
+    /**
+     * Object visibility.
+     */
     visibility: StorageVisibility;
+    /**
+     * Last modification timestamp.
+     */
     lastModified: Date;
 }
+/**
+ * Object metadata plus a one-shot readable body.
+ *
+ * Like Fetch response bodies, storage bodies can be consumed once. Call `get`
+ * again if you need another reader.
+ */
 export interface StorageObjectBody extends StorageObject {
     /**
      * Whether this object body has already been consumed. Like Fetch response
@@ -23,19 +72,60 @@ export interface StorageObjectBody extends StorageObject {
      * buffering them.
      */
     readonly bodyUsed: boolean;
+    /**
+     * Consume the object as a readable byte stream.
+     */
     stream(): ReadableStream<Uint8Array>;
+    /**
+     * Consume the object as bytes.
+     */
     bytes(): Promise<Uint8Array>;
+    /**
+     * Consume the object as an ArrayBuffer.
+     */
     arrayBuffer(): Promise<ArrayBuffer>;
+    /**
+     * Consume the object as UTF-8 text.
+     */
     text(): Promise<string>;
 }
+/**
+ * App-facing object storage port.
+ *
+ * Implement this with S3, R2, local disk, or a test adapter. Application code
+ * should depend on this interface instead of provider-specific SDKs.
+ */
 export interface StoragePort {
+    /**
+     * Store an object and return its metadata.
+     */
     put(key: string, body: StorageBody, options?: StoragePutOptions): Promise<StorageObject>;
+    /**
+     * Return object metadata and body, or `null` when missing.
+     */
     get(key: string): Promise<StorageObjectBody | null>;
+    /**
+     * Return object metadata without its body, or `null` when missing.
+     */
     stat(key: string): Promise<StorageObject | null>;
+    /**
+     * Delete an object.
+     *
+     * @returns `true` when the object existed.
+     */
     delete(key: string): Promise<boolean>;
+    /**
+     * Return whether an object exists.
+     */
     exists(key: string): Promise<boolean>;
+    /**
+     * Return a public URL when the object is public and the adapter can build one.
+     */
     publicUrl(key: string): Promise<string | null>;
 }
+/**
+ * Options for `createMemoryStorage(...)`.
+ */
 export interface MemoryStorageOptions {
     /**
      * Base URL used by `publicUrl(...)` for objects written with
@@ -43,5 +133,15 @@ export interface MemoryStorageOptions {
      */
     publicBaseUrl?: string;
 }
+/**
+ * Create an in-memory object storage adapter for tests, examples, and
+ * single-process development.
+ *
+ * This adapter validates object keys using Beignet's storage key rules. It is
+ * not durable and does not share objects across processes.
+ *
+ * @param options - Optional public URL base for public objects.
+ * @returns A storage port backed by a local `Map`.
+ */
 export declare function createMemoryStorage(options?: MemoryStorageOptions): StoragePort;
 //# sourceMappingURL=storage.d.ts.map

package/dist/ports/storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/ports/storage.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,QAAQ,CAAC;AAErD,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAErD,MAAM,MAAM,WAAW,GACnB,MAAM,GACN,WAAW,GACX,UAAU,GACV,IAAI,GACJ,cAAc,CAAC,UAAU,CAAC,CAAC;AAE/B,MAAM,WAAW,iBAAiB;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,eAAe,CAAC;IAC1B,UAAU,EAAE,iBAAiB,CAAC;IAC9B,YAAY,EAAE,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,iBAAkB,SAAQ,aAAa;IACtD;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,MAAM,IAAI,cAAc,CAAC,UAAU,CAAC,CAAC;IACrC,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;IAC7B,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC;IACpC,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,CACD,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,aAAa,CAAC,CAAC;IAC1B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IACpD,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IACjD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtC,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAiKD,wBAAgB,mBAAmB,CACjC,OAAO,GAAE,oBAAyB,GACjC,WAAW,CA0Db"}
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/ports/storage.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,QAAQ,CAAC;AAErD;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAErD;;GAEG;AACH,MAAM,MAAM,WAAW,GACnB,MAAM,GACN,WAAW,GACX,UAAU,GACV,IAAI,GACJ,cAAc,CAAC,UAAU,CAAC,CAAC;AAE/B;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;OAEG;IACH,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B;;OAEG;IACH,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;OAEG;IACH,QAAQ,EAAE,eAAe,CAAC;IAC1B;;OAEG;IACH,UAAU,EAAE,iBAAiB,CAAC;IAC9B;;OAEG;IACH,YAAY,EAAE,IAAI,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAkB,SAAQ,aAAa;IACtD;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B;;OAEG;IACH,MAAM,IAAI,cAAc,CAAC,UAAU,CAAC,CAAC;IACrC;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;IAC7B;;OAEG;IACH,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC;IACpC;;OAEG;IACH,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,GAAG,CACD,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,aAAa,CAAC,CAAC;IAC1B;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IACpD;;OAEG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IACjD;;;;OAIG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtC;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtC;;OAEG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAChD;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAiKD;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,GAAE,oBAAyB,GACjC,WAAW,CA0Db"}

package/dist/ports/storage.js

@@ -127,6 +127,16 @@ function joinPublicUrl(baseUrl, key) {
         .join("/");
     return `${base}/${encodedKey}`;
 }
+/**
+ * Create an in-memory object storage adapter for tests, examples, and
+ * single-process development.
+ *
+ * This adapter validates object keys using Beignet's storage key rules. It is
+ * not durable and does not share objects across processes.
+ *
+ * @param options - Optional public URL base for public objects.
+ * @returns A storage port backed by a local `Map`.
+ */
 export function createMemoryStorage(options = {}) {
     const objects = new Map();
     return {

package/dist/ports/storage.js.map

@@ -1 +1 @@
-{"version":3,"file":"storage.js","sourceRoot":"","sources":["../../src/ports/storage.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../../src/ports/storage.ts"],"names":[],"mappings":"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"}

package/dist/ports/testing.d.ts

@@ -30,12 +30,18 @@ export declare function createRecordingEventBus(): {
     bus: EventBusPort;
     events: RecordedEvent[];
 };
+/**
+ * Expected outcome for one policy matrix case.
+ */
 export type PolicyMatrixExpectation = "allow" | "deny";
 type PolicyMatrixSubject<TResolver> = PolicySubjectArgs<TResolver> extends [subject: infer Subject] ? {
     subject: Subject;
 } : {
     subject?: never;
 };
+/**
+ * One typed authorization matrix case for a policy ability.
+ */
 export type PolicyMatrixCase<TContext, TPolicies extends readonly PolicyDefinition[] = readonly PolicyDefinition[]> = {
     [TAbility in keyof PolicyMapFromDefinitions<TPolicies> & string]: {
         name: string;
@@ -46,6 +52,9 @@ export type PolicyMatrixCase<TContext, TPolicies extends readonly PolicyDefiniti
         code?: string;
     } & 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;
@@ -55,19 +64,57 @@ export type UntypedPolicyMatrixCase<TContext> = {
     reason?: string;
     code?: string;
 };
+/**
+ * Result for one evaluated policy matrix case.
+ */
 export type PolicyMatrixResult<TContext, TPolicies extends readonly PolicyDefinition[] = readonly PolicyDefinition[]> = {
     case: PolicyMatrixCase<TContext, TPolicies>;
     decision: GateDecision;
     passed: boolean;
     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 declare function createPolicyTester<const TPolicies extends readonly PolicyDefinition[]>(options: CreateGateOptions<PolicyContextFromDefinitions<TPolicies>, TPolicies>): PolicyTester<PolicyContextFromDefinitions<TPolicies>, TPolicies>;
+/**
+ * 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 declare function evaluatePolicyMatrix<TContext, TPolicies extends readonly PolicyDefinition[]>(gate: GatePort<TContext, TPolicies>, cases: readonly PolicyMatrixCase<TContext, TPolicies>[]): Promise<PolicyMatrixResult<TContext, TPolicies>[]>;
+/**
+ * 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 declare function assertPolicyMatrix<TContext, TPolicies extends readonly PolicyDefinition[]>(gate: GatePort<TContext, TPolicies>, cases: readonly PolicyMatrixCase<TContext, TPolicies>[]): Promise<void>;
 export {};
 //# sourceMappingURL=testing.d.ts.map

package/dist/ports/testing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../../src/ports/testing.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../../src/ports/testing.ts"],"names":[],"mappings":"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"}

package/dist/ports/testing.js

@@ -30,6 +30,15 @@ export function createRecordingEventBus() {
     };
     return { bus, events };
 }
+/**
+ * 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(options) {
     const gate = createGate(options);
     return {
@@ -38,6 +47,13 @@ export function createPolicyTester(options) {
         assertMatrix: (cases) => assertPolicyMatrix(gate, cases),
     };
 }
+/**
+ * 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(gate, cases) {
     const results = [];
     for (const matrixCase of cases) {
@@ -54,6 +70,13 @@ export async function evaluatePolicyMatrix(gate, cases) {
     }
     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(gate, cases) {
     const results = await evaluatePolicyMatrix(gate, cases);
     const failures = results.filter((result) => !result.passed);

package/dist/ports/testing.js.map

@@ -1 +1 @@
-{"version":3,"file":"testing.js","sourceRoot":"","sources":["../../src/ports/testing.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../../src/ports/testing.ts"],"names":[],"mappings":"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"}

package/dist/ports/unit-of-work.d.ts

@@ -1,5 +1,11 @@
 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>;
 /**
  * A transaction boundary for application workflows.
@@ -9,8 +15,16 @@ export type UnitOfWorkCallback<TxPorts, Result> = (tx: TxPorts) => MaybePromise<
  * `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.
@@ -26,17 +40,51 @@ 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<E extends DomainEventDef>(event: E, payload: InferEventPayload<E>): void;
+    /**
+     * Record a domain event payload.
+     */
+    record<E extends DomainEventDef>(event: E, payload: InferEventPayload<E>): 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>;
 }
 /**
@@ -45,11 +93,20 @@ 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 declare function createNoopUnitOfWork<TxPorts>(txPortsOrFactory: TxPorts | (() => TxPorts), options?: NoopUnitOfWorkOptions<TxPorts>): UnitOfWorkPort<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 declare function createDomainEventRecorder(): BufferedDomainEventRecorder;
 export {};

package/dist/ports/unit-of-work.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"unit-of-work.d.ts","sourceRoot":"","sources":["../../src/ports/unit-of-work.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAEhF,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAEtC,MAAM,MAAM,kBAAkB,CAAC,OAAO,EAAE,MAAM,IAAI,CAChD,EAAE,EAAE,OAAO,KACR,YAAY,CAAC,MAAM,CAAC,CAAC;AAE1B;;;;;;GAMG;AACH,MAAM,WAAW,cAAc,CAAC,OAAO;IACrC,WAAW,CAAC,MAAM,EAChB,IAAI,EAAE,kBAAkB,CAAC,OAAO,EAAE,MAAM,CAAC,GACxC,OAAO,CAAC,MAAM,CAAC,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB,CAAC,OAAO;IAC5C;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,OAAO,KAAK,YAAY,CAAC,IAAI,CAAC,CAAC;IAElD;;;;;OAKG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,KAAK,YAAY,CAAC,IAAI,CAAC,CAAC;CACrE;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,cAAc,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,CAAC,SAAS,cAAc,EAC7B,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC5B,IAAI,CAAC;CACT;AAED,MAAM,WAAW,2BAA4B,SAAQ,uBAAuB;IAC1E,OAAO,IAAI,SAAS,mBAAmB,EAAE,CAAC;IAC1C,KAAK,IAAI,IAAI,CAAC;IACd,KAAK,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9C;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAC1C,gBAAgB,EAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,EAC3C,OAAO,GAAE,qBAAqB,CAAC,OAAO,CAAM,GAC3C,cAAc,CAAC,OAAO,CAAC,CA8BzB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,IAAI,2BAA2B,CA6BvE"}
+{"version":3,"file":"unit-of-work.d.ts","sourceRoot":"","sources":["../../src/ports/unit-of-work.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAEhF,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAEtC;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,CAAC,OAAO,EAAE,MAAM,IAAI,CAChD,EAAE,EAAE,OAAO,KACR,YAAY,CAAC,MAAM,CAAC,CAAC;AAE1B;;;;;;GAMG;AACH,MAAM,WAAW,cAAc,CAAC,OAAO;IACrC;;;;OAIG;IACH,WAAW,CAAC,MAAM,EAChB,IAAI,EAAE,kBAAkB,CAAC,OAAO,EAAE,MAAM,CAAC,GACxC,OAAO,CAAC,MAAM,CAAC,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB,CAAC,OAAO;IAC5C;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,OAAO,KAAK,YAAY,CAAC,IAAI,CAAC,CAAC;IAElD;;;;;OAKG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,KAAK,YAAY,CAAC,IAAI,CAAC,CAAC;CACrE;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,KAAK,EAAE,cAAc,CAAC;IACtB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,MAAM,CAAC,CAAC,SAAS,cAAc,EAC7B,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC5B,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,2BAA4B,SAAQ,uBAAuB;IAC1E;;OAEG;IACH,OAAO,IAAI,SAAS,mBAAmB,EAAE,CAAC;IAC1C;;OAEG;IACH,KAAK,IAAI,IAAI,CAAC;IACd;;OAEG;IACH,KAAK,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAC1C,gBAAgB,EAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,EAC3C,OAAO,GAAE,qBAAqB,CAAC,OAAO,CAAM,GAC3C,cAAc,CAAC,OAAO,CAAC,CA8BzB;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,IAAI,2BAA2B,CA6BvE"}

package/dist/ports/unit-of-work.js

@@ -5,6 +5,11 @@ import { parseEventPayload } from "../events";
  *
  * 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(txPortsOrFactory, options = {}) {
     const createTxPorts = typeof txPortsOrFactory === "function"
@@ -32,8 +37,12 @@ export function createNoopUnitOfWork(txPortsOrFactory, options = {}) {
     };
 }
 /**
- * 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() {
     const records = [];

package/dist/ports/unit-of-work.js.map

@@ -1 +1 @@
-{"version":3,"file":"unit-of-work.js","sourceRoot":"","sources":["../../src/ports/unit-of-work.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AA0D9C;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAClC,gBAA2C,EAC3C,UAA0C,EAAE;IAE5C,MAAM,aAAa,GACjB,OAAO,gBAAgB,KAAK,UAAU;QACpC,CAAC,CAAE,gBAAkC;QACrC,CAAC,CAAC,GAAG,EAAE,CAAC,gBAAgB,CAAC;IAE7B,OAAO;QACL,KAAK,CAAC,WAAW,CACf,IAAyC;YAEzC,MAAM,EAAE,GAAG,aAAa,EAAE,CAAC;YAE3B,IAAI,MAAc,CAAC;YAEnB,IAAI,CAAC;gBACH,MAAM,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,CAAC;YAC1B,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,CAAC;oBACH,MAAM,OAAO,CAAC,aAAa,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;gBAC3C,CAAC;gBAAC,MAAM,CAAC;oBACP,gEAAgE;gBAClE,CAAC;gBAED,MAAM,KAAK,CAAC;YACd,CAAC;YAED,MAAM,OAAO,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC,CAAC;YAChC,OAAO,MAAM,CAAC;QAChB,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,yBAAyB;IACvC,MAAM,OAAO,GAA0B,EAAE,CAAC;IAE1C,OAAO;QACL,MAAM,CAAC,KAAK,EAAE,OAAO;YACnB,OAAO,CAAC,IAAI,CAAC;gBACX,KAAK;gBACL,SAAS,EAAE,KAAK,CAAC,IAAI;gBACrB,OAAO;aACR,CAAC,CAAC;QACL,CAAC;QAED,OAAO;YACL,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,KAAK;YACH,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;QACrB,CAAC;QAED,KAAK,CAAC,KAAK,CAAC,QAAQ;YAClB,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC1B,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;gBAC1B,MAAM,OAAO,GAAG,MAAM,iBAAiB,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;gBACtE,MAAM,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;gBAC9C,OAAO,CAAC,KAAK,EAAE,CAAC;YAClB,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"unit-of-work.js","sourceRoot":"","sources":["../../src/ports/unit-of-work.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AA0G9C;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,oBAAoB,CAClC,gBAA2C,EAC3C,UAA0C,EAAE;IAE5C,MAAM,aAAa,GACjB,OAAO,gBAAgB,KAAK,UAAU;QACpC,CAAC,CAAE,gBAAkC;QACrC,CAAC,CAAC,GAAG,EAAE,CAAC,gBAAgB,CAAC;IAE7B,OAAO;QACL,KAAK,CAAC,WAAW,CACf,IAAyC;YAEzC,MAAM,EAAE,GAAG,aAAa,EAAE,CAAC;YAE3B,IAAI,MAAc,CAAC;YAEnB,IAAI,CAAC;gBACH,MAAM,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,CAAC;YAC1B,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,CAAC;oBACH,MAAM,OAAO,CAAC,aAAa,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;gBAC3C,CAAC;gBAAC,MAAM,CAAC;oBACP,gEAAgE;gBAClE,CAAC;gBAED,MAAM,KAAK,CAAC;YACd,CAAC;YAED,MAAM,OAAO,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC,CAAC;YAChC,OAAO,MAAM,CAAC;QAChB,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,yBAAyB;IACvC,MAAM,OAAO,GAA0B,EAAE,CAAC;IAE1C,OAAO;QACL,MAAM,CAAC,KAAK,EAAE,OAAO;YACnB,OAAO,CAAC,IAAI,CAAC;gBACX,KAAK;gBACL,SAAS,EAAE,KAAK,CAAC,IAAI;gBACrB,OAAO;aACR,CAAC,CAAC;QACL,CAAC;QAED,OAAO;YACL,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,KAAK;YACH,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;QACrB,CAAC;QAED,KAAK,CAAC,KAAK,CAAC,QAAQ;YAClB,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC1B,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;gBAC1B,MAAM,OAAO,GAAG,MAAM,iBAAiB,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;gBACtE,MAAM,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;gBAC9C,OAAO,CAAC,KAAK,EAAE,CAAC;YAClB,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}