@beignet/core 0.0.1 → 0.0.3

package/dist/events/index.js

@@ -1,4 +1,10 @@
+/**
+ * Error thrown when event payload validation fails.
+ */
 export class EventValidationError extends Error {
+    /**
+     * Raw Standard Schema validation issues.
+     */
     issues;
     constructor(args) {
         super(`Event "${args.name}" payload validation failed: ${formatIssues(args.issues)}`);
@@ -42,6 +48,12 @@ async function resolveCtx(ctx) {
     }
     return ctx;
 }
+/**
+ * Define a typed event.
+ *
+ * Event payloads are validated before publishing through `publishEvent(...)`
+ * and before registered listeners run.
+ */
 export function defineEvent(name, options) {
     return {
         kind: "event",
@@ -50,6 +62,9 @@ export function defineEvent(name, options) {
         description: options.description,
     };
 }
+/**
+ * Define a listener for one event.
+ */
 export function defineListener(event, options) {
     return {
         kind: "listener",
@@ -58,15 +73,27 @@ export function defineListener(event, options) {
         handle: options.handle,
     };
 }
+/**
+ * Validate and parse an event payload with the event's Standard Schema.
+ */
 export async function parseEventPayload(event, payload) {
     return (await parsePayload(event.payload, payload, {
         name: event.name,
     }));
 }
+/**
+ * Validate an event payload and publish it through an event bus.
+ */
 export async function publishEvent(eventBus, event, payload) {
     const parsed = await parseEventPayload(event, payload);
     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(eventBus, listeners, options = {}) {
     const unsubscribes = listeners.map((listener) => eventBus.subscribe(listener.event, async (rawPayload) => {
         try {
@@ -89,6 +116,9 @@ export function registerListeners(eventBus, listeners, options = {}) {
         }
     };
 }
+/**
+ * Create event helper methods bound to an application context type.
+ */
 export function createEventHandlers() {
     return {
         defineListener(event, options) {

package/dist/events/index.js.map

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

package/dist/idempotency/index.d.ts

@@ -0,0 +1,355 @@
+/**
+ * @beignet/core/idempotency
+ *
+ * Idempotency primitives for retry-safe commands, webhooks, and jobs.
+ */
+/**
+ * Value or promise of that value.
+ */
+export type MaybePromise<T> = T | Promise<T>;
+/**
+ * Primitive value accepted inside an idempotency scope object.
+ */
+export type IdempotencyScopeValue = string | number | boolean | null | undefined;
+/**
+ * Logical scope for idempotency keys.
+ *
+ * String scopes are used as-is. Object scopes are normalized by sorting keys and
+ * joining key/value pairs so adapters can build stable storage keys.
+ */
+export type IdempotencyScope = string | Record<string, IdempotencyScopeValue>;
+/**
+ * Scope mode that HTTP hooks can use when deriving an idempotency scope.
+ */
+export type IdempotencyScopeMode = "global" | "actor" | "tenant" | "actor-tenant";
+/**
+ * Contract metadata for idempotency-aware routes.
+ */
+export interface IdempotencyMeta {
+    /**
+     * Whether this operation requires an idempotency key at the HTTP boundary.
+     *
+     * This is metadata for hooks, docs, and generated OpenAPI. Use cases should
+     * still call `runIdempotently(...)` for workflows that must be retry-safe.
+     */
+    required?: boolean;
+    /**
+     * Header that carries the idempotency key.
+     *
+     * Default: "idempotency-key".
+     */
+    header?: string;
+    /**
+     * How to scope idempotency keys when an HTTP hook derives the scope.
+     *
+     * Default: "global".
+     */
+    scope?: IdempotencyScopeMode;
+    /**
+     * Time-to-live for reserved and completed keys.
+     */
+    ttlSec?: number;
+}
+/**
+ * Input for reserving an idempotency key.
+ */
+export interface IdempotencyReserveInput {
+    /**
+     * Operation namespace, usually a use-case or route name.
+     */
+    namespace: string;
+    /**
+     * Client-provided idempotency key.
+     */
+    key: string;
+    /**
+     * Logical scope for this key.
+     */
+    scope?: IdempotencyScope;
+    /**
+     * Fingerprint of the logical command payload.
+     */
+    fingerprint: string;
+    /**
+     * Optional key time-to-live in seconds.
+     */
+    ttlSec?: number;
+}
+/**
+ * Result of reserving an idempotency key.
+ */
+export type IdempotencyReservation = {
+    status: "reserved";
+    namespace: string;
+    key: string;
+    scopeKey: string;
+    fingerprint: string;
+    reservedAt: Date;
+    expiresAt: Date | null;
+} | {
+    status: "replay";
+    namespace: string;
+    key: string;
+    scopeKey: string;
+    fingerprint: string;
+    result: unknown;
+    reservedAt: Date;
+    completedAt: Date;
+    expiresAt: Date | null;
+} | {
+    status: "inProgress";
+    namespace: string;
+    key: string;
+    scopeKey: string;
+    fingerprint: string;
+    reservedAt: Date;
+    expiresAt: Date | null;
+} | {
+    status: "conflict";
+    namespace: string;
+    key: string;
+    scopeKey: string;
+    storedFingerprint: string;
+    receivedFingerprint: string;
+    reservedAt: Date;
+    completedAt?: Date;
+    expiresAt: Date | null;
+};
+/**
+ * Input for marking an idempotency key complete.
+ */
+export interface IdempotencyCompleteInput {
+    /**
+     * Operation namespace.
+     */
+    namespace: string;
+    /**
+     * Client-provided idempotency key.
+     */
+    key: string;
+    /**
+     * Logical scope for this key.
+     */
+    scope?: IdempotencyScope;
+    /**
+     * Fingerprint that must match the reserved operation.
+     */
+    fingerprint: string;
+    /**
+     * Result to replay for future matching requests.
+     */
+    result?: unknown;
+}
+/**
+ * Input for releasing or marking a failed idempotency reservation.
+ */
+export interface IdempotencyFailInput {
+    /**
+     * Operation namespace.
+     */
+    namespace: string;
+    /**
+     * Client-provided idempotency key.
+     */
+    key: string;
+    /**
+     * Logical scope for this key.
+     */
+    scope?: IdempotencyScope;
+    /**
+     * Fingerprint that must match the reserved operation.
+     */
+    fingerprint: string;
+    /**
+     * Error that caused the protected operation to fail.
+     */
+    error?: unknown;
+}
+/**
+ * App-facing idempotency port.
+ */
+export interface IdempotencyPort {
+    /**
+     * Atomically reserve a key for work, replay an already completed result, or
+     * report that the key is in progress/conflicting.
+     */
+    reserve(input: IdempotencyReserveInput): Promise<IdempotencyReservation>;
+    /**
+     * Mark a reserved key as complete and store the result that may be replayed.
+     */
+    complete(input: IdempotencyCompleteInput): Promise<void>;
+    /**
+     * Release or mark a reserved key after the protected work fails.
+     */
+    fail(input: IdempotencyFailInput): Promise<void>;
+}
+/**
+ * Options for reserving an idempotency key around a protected operation.
+ */
+export interface RunIdempotentlyOptions<Result> extends IdempotencyReserveInput {
+    /**
+     * Protected operation to run after the key is reserved.
+     */
+    run: () => MaybePromise<Result>;
+    /**
+     * Replay behavior for completed matching reservations.
+     *
+     * Defaults to returning the stored result. Use `"error"` when callers need to
+     * distinguish replay from first execution.
+     */
+    replay?: "return" | "error";
+}
+/**
+ * Options for `createIdempotencyFingerprint(...)`.
+ */
+export interface CreateIdempotencyFingerprintOptions {
+    /**
+     * Omit values from the fingerprint input. Use this for the idempotency key
+     * itself or other request metadata that does not define the logical command.
+     *
+     * String paths can be top-level keys (`"idempotencyKey"`) or dotted paths
+     * (`"metadata.requestId"`). Array paths avoid ambiguity when keys contain
+     * dots.
+     */
+    omit?: readonly (string | readonly string[])[];
+}
+/**
+ * In-memory idempotency store for tests and local examples.
+ */
+export interface MemoryIdempotencyStore extends IdempotencyPort {
+    /**
+     * Current store entries.
+     */
+    readonly entries: readonly MemoryIdempotencyEntry[];
+    /**
+     * Remove all entries.
+     */
+    clear(): void;
+}
+/**
+ * Snapshot entry from the memory idempotency store.
+ */
+export interface MemoryIdempotencyEntry {
+    /**
+     * Operation namespace.
+     */
+    namespace: string;
+    /**
+     * Client-provided idempotency key.
+     */
+    key: string;
+    /**
+     * Normalized scope key.
+     */
+    scopeKey: string;
+    /**
+     * Fingerprint of the logical command payload.
+     */
+    fingerprint: string;
+    /**
+     * Memory store status.
+     */
+    status: "in-progress" | "completed";
+    /**
+     * Stored result for completed entries.
+     */
+    result?: unknown;
+    /**
+     * Reservation timestamp.
+     */
+    reservedAt: Date;
+    /**
+     * Completion timestamp.
+     */
+    completedAt?: Date;
+    /**
+     * Expiration timestamp, or null for no expiration.
+     */
+    expiresAt: Date | null;
+}
+/**
+ * Error thrown when an idempotency key is reused with a different fingerprint.
+ */
+export declare class IdempotencyConflictError extends Error {
+    readonly namespace: string;
+    readonly key: string;
+    readonly scopeKey: string;
+    readonly storedFingerprint: string;
+    readonly receivedFingerprint: string;
+    constructor(args: {
+        namespace: string;
+        key: string;
+        scopeKey: string;
+        storedFingerprint: string;
+        receivedFingerprint: string;
+    });
+}
+/**
+ * Error thrown when an idempotency key is already reserved by in-progress work.
+ */
+export declare class IdempotencyInProgressError extends Error {
+    readonly namespace: string;
+    readonly key: string;
+    readonly scopeKey: string;
+    constructor(args: {
+        namespace: string;
+        key: string;
+        scopeKey: string;
+    });
+}
+/**
+ * Error thrown when replay is disabled for a completed idempotency key.
+ */
+export declare class IdempotencyReplayError extends Error {
+    readonly namespace: string;
+    readonly key: string;
+    readonly scopeKey: string;
+    constructor(args: {
+        namespace: string;
+        key: string;
+        scopeKey: string;
+    });
+}
+/**
+ * Error thrown when fingerprint input cannot be canonicalized.
+ */
+export declare class IdempotencyFingerprintError extends Error {
+    constructor(message: string);
+}
+/**
+ * Normalize an idempotency scope into a stable string.
+ */
+export declare function normalizeIdempotencyScope(scope: IdempotencyScope | undefined): string;
+/**
+ * Create the stable storage key for an idempotency operation.
+ */
+export declare function createIdempotencyStorageKey(input: {
+    namespace: string;
+    key: string;
+    scope?: IdempotencyScope;
+}): string;
+/**
+ * Create an in-memory idempotency store for tests and local examples.
+ *
+ * The memory store is process-local and not suitable for multi-process
+ * production deployments.
+ */
+export declare function createMemoryIdempotencyStore(): MemoryIdempotencyStore;
+/**
+ * Run an operation behind an idempotency reservation.
+ *
+ * The flow is: reserve the key, replay completed matching results, reject
+ * in-progress/conflicting keys, run the operation for new reservations, then
+ * complete or fail the reservation. Callers are responsible for choosing a
+ * namespace, scope, key, and fingerprint that match their business operation.
+ */
+export declare function runIdempotently<Result>(idempotency: IdempotencyPort, options: RunIdempotentlyOptions<Result>): Promise<Result>;
+/**
+ * Create a SHA-256 fingerprint from a canonicalized value.
+ *
+ * Object keys are sorted, `undefined` and functions are omitted, `Date` values
+ * become ISO strings, BigInts become strings, and circular or non-finite values
+ * throw. Exact omit paths may be supplied as dotted strings or string arrays.
+ */
+export declare function createIdempotencyFingerprint(value: unknown, options?: CreateIdempotencyFingerprintOptions): Promise<string>;
+//# sourceMappingURL=index.d.ts.map

package/dist/idempotency/index.d.ts.map

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