@beignet/core 0.0.1 → 0.0.3

package/dist/idempotency/index.js

@@ -0,0 +1,360 @@
+/**
+ * @beignet/core/idempotency
+ *
+ * Idempotency primitives for retry-safe commands, webhooks, and jobs.
+ */
+/**
+ * Error thrown when an idempotency key is reused with a different fingerprint.
+ */
+export class IdempotencyConflictError extends Error {
+    namespace;
+    key;
+    scopeKey;
+    storedFingerprint;
+    receivedFingerprint;
+    constructor(args) {
+        super(`Idempotency key "${args.key}" conflicts with a different payload in namespace "${args.namespace}".`);
+        this.name = "IdempotencyConflictError";
+        this.namespace = args.namespace;
+        this.key = args.key;
+        this.scopeKey = args.scopeKey;
+        this.storedFingerprint = args.storedFingerprint;
+        this.receivedFingerprint = args.receivedFingerprint;
+    }
+}
+/**
+ * Error thrown when an idempotency key is already reserved by in-progress work.
+ */
+export class IdempotencyInProgressError extends Error {
+    namespace;
+    key;
+    scopeKey;
+    constructor(args) {
+        super(`Idempotency key "${args.key}" is already in progress in namespace "${args.namespace}".`);
+        this.name = "IdempotencyInProgressError";
+        this.namespace = args.namespace;
+        this.key = args.key;
+        this.scopeKey = args.scopeKey;
+    }
+}
+/**
+ * Error thrown when replay is disabled for a completed idempotency key.
+ */
+export class IdempotencyReplayError extends Error {
+    namespace;
+    key;
+    scopeKey;
+    constructor(args) {
+        super(`Idempotency key "${args.key}" already completed in namespace "${args.namespace}".`);
+        this.name = "IdempotencyReplayError";
+        this.namespace = args.namespace;
+        this.key = args.key;
+        this.scopeKey = args.scopeKey;
+    }
+}
+/**
+ * Error thrown when fingerprint input cannot be canonicalized.
+ */
+export class IdempotencyFingerprintError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "IdempotencyFingerprintError";
+    }
+}
+function assertNonEmptyString(name, value) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`${name} must be a non-empty string`);
+    }
+}
+function assertTtl(ttlSec) {
+    if (ttlSec === undefined)
+        return;
+    if (!Number.isInteger(ttlSec) || ttlSec <= 0) {
+        throw new Error("ttlSec must be a positive integer when provided");
+    }
+}
+function normalizeScopeValue(value) {
+    if (value === undefined)
+        return "";
+    if (value === null)
+        return "null";
+    return String(value);
+}
+/**
+ * Normalize an idempotency scope into a stable string.
+ */
+export function normalizeIdempotencyScope(scope) {
+    if (scope === undefined)
+        return "global";
+    if (typeof scope === "string")
+        return scope;
+    return Object.keys(scope)
+        .sort()
+        .map((key) => `${key}:${normalizeScopeValue(scope[key])}`)
+        .join("|");
+}
+/**
+ * Create the stable storage key for an idempotency operation.
+ */
+export function createIdempotencyStorageKey(input) {
+    assertNonEmptyString("namespace", input.namespace);
+    assertNonEmptyString("key", input.key);
+    return [
+        input.namespace,
+        normalizeIdempotencyScope(input.scope),
+        input.key,
+    ].join("\u0000");
+}
+function resolveExpiresAt(ttlSec, now) {
+    assertTtl(ttlSec);
+    return ttlSec === undefined ? null : new Date(now.getTime() + ttlSec * 1000);
+}
+function isExpired(entry, now) {
+    return entry.expiresAt !== null && entry.expiresAt.getTime() <= now.getTime();
+}
+function reservationFromRecord(record, receivedFingerprint) {
+    if (record.fingerprint !== receivedFingerprint) {
+        return {
+            status: "conflict",
+            namespace: record.namespace,
+            key: record.key,
+            scopeKey: record.scopeKey,
+            storedFingerprint: record.fingerprint,
+            receivedFingerprint,
+            reservedAt: record.reservedAt,
+            completedAt: record.completedAt,
+            expiresAt: record.expiresAt,
+        };
+    }
+    if (record.status === "completed" && record.completedAt) {
+        return {
+            status: "replay",
+            namespace: record.namespace,
+            key: record.key,
+            scopeKey: record.scopeKey,
+            fingerprint: record.fingerprint,
+            result: record.result,
+            reservedAt: record.reservedAt,
+            completedAt: record.completedAt,
+            expiresAt: record.expiresAt,
+        };
+    }
+    return {
+        status: "inProgress",
+        namespace: record.namespace,
+        key: record.key,
+        scopeKey: record.scopeKey,
+        fingerprint: record.fingerprint,
+        reservedAt: record.reservedAt,
+        expiresAt: record.expiresAt,
+    };
+}
+/**
+ * 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 function createMemoryIdempotencyStore() {
+    const records = new Map();
+    return {
+        get entries() {
+            return [...records.values()];
+        },
+        async reserve(input) {
+            assertNonEmptyString("namespace", input.namespace);
+            assertNonEmptyString("key", input.key);
+            assertNonEmptyString("fingerprint", input.fingerprint);
+            assertTtl(input.ttlSec);
+            const now = new Date();
+            const storageKey = createIdempotencyStorageKey(input);
+            const existing = records.get(storageKey);
+            if (existing && !isExpired(existing, now)) {
+                return reservationFromRecord(existing, input.fingerprint);
+            }
+            if (existing) {
+                records.delete(storageKey);
+            }
+            const record = {
+                namespace: input.namespace,
+                key: input.key,
+                scopeKey: normalizeIdempotencyScope(input.scope),
+                fingerprint: input.fingerprint,
+                status: "in-progress",
+                reservedAt: now,
+                expiresAt: resolveExpiresAt(input.ttlSec, now),
+            };
+            records.set(storageKey, record);
+            return {
+                status: "reserved",
+                namespace: record.namespace,
+                key: record.key,
+                scopeKey: record.scopeKey,
+                fingerprint: record.fingerprint,
+                reservedAt: record.reservedAt,
+                expiresAt: record.expiresAt,
+            };
+        },
+        async complete(input) {
+            assertNonEmptyString("namespace", input.namespace);
+            assertNonEmptyString("key", input.key);
+            assertNonEmptyString("fingerprint", input.fingerprint);
+            const storageKey = createIdempotencyStorageKey(input);
+            const existing = records.get(storageKey);
+            if (!existing || existing.fingerprint !== input.fingerprint)
+                return;
+            existing.status = "completed";
+            existing.result = input.result;
+            existing.completedAt = new Date();
+        },
+        async fail(input) {
+            assertNonEmptyString("namespace", input.namespace);
+            assertNonEmptyString("key", input.key);
+            assertNonEmptyString("fingerprint", input.fingerprint);
+            const storageKey = createIdempotencyStorageKey(input);
+            const existing = records.get(storageKey);
+            if (!existing || existing.fingerprint !== input.fingerprint)
+                return;
+            if (existing.status === "completed")
+                return;
+            records.delete(storageKey);
+        },
+        clear() {
+            records.clear();
+        },
+    };
+}
+/**
+ * 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 async function runIdempotently(idempotency, options) {
+    const operation = {
+        namespace: options.namespace,
+        key: options.key,
+        scope: options.scope,
+        fingerprint: options.fingerprint,
+        ttlSec: options.ttlSec,
+    };
+    const reservation = await idempotency.reserve(operation);
+    switch (reservation.status) {
+        case "replay": {
+            if (options.replay === "error") {
+                throw new IdempotencyReplayError(reservation);
+            }
+            return reservation.result;
+        }
+        case "inProgress": {
+            throw new IdempotencyInProgressError(reservation);
+        }
+        case "conflict": {
+            throw new IdempotencyConflictError(reservation);
+        }
+        case "reserved": {
+            try {
+                const result = await options.run();
+                await idempotency.complete({
+                    namespace: operation.namespace,
+                    key: operation.key,
+                    scope: operation.scope,
+                    fingerprint: operation.fingerprint,
+                    result,
+                });
+                return result;
+            }
+            catch (error) {
+                await idempotency.fail({
+                    namespace: operation.namespace,
+                    key: operation.key,
+                    scope: operation.scope,
+                    fingerprint: operation.fingerprint,
+                    error,
+                });
+                throw error;
+            }
+        }
+    }
+}
+function normalizeOmitPath(path) {
+    if (typeof path === "string")
+        return path.split(".").filter(Boolean);
+    return path.map(String);
+}
+function shouldOmitPath(path, omit) {
+    return omit.some((entry) => {
+        const omitPath = normalizeOmitPath(entry);
+        if (omitPath.length !== path.length)
+            return false;
+        return omitPath.every((segment, index) => segment === path[index]);
+    });
+}
+function canonicalize(value, options, path, seen) {
+    if (shouldOmitPath(path, options.omit ?? [])) {
+        return undefined;
+    }
+    if (value === undefined || typeof value === "function") {
+        return undefined;
+    }
+    if (value === null ||
+        typeof value === "string" ||
+        typeof value === "boolean") {
+        return value;
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new IdempotencyFingerprintError("Cannot fingerprint non-finite numeric values.");
+        }
+        return value;
+    }
+    if (typeof value === "bigint") {
+        return value.toString();
+    }
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    if (Array.isArray(value)) {
+        return value.map((item, index) => canonicalize(item, options, [...path, String(index)], seen) ?? null);
+    }
+    if (typeof value === "object") {
+        if (seen.has(value)) {
+            throw new IdempotencyFingerprintError("Cannot fingerprint circular values.");
+        }
+        seen.add(value);
+        const result = {};
+        for (const key of Object.keys(value).sort()) {
+            const nestedValue = canonicalize(value[key], options, [...path, key], seen);
+            if (nestedValue !== undefined) {
+                result[key] = nestedValue;
+            }
+        }
+        seen.delete(value);
+        return result;
+    }
+    throw new IdempotencyFingerprintError(`Cannot fingerprint value of type "${typeof value}".`);
+}
+function bytesToHex(bytes) {
+    return [...new Uint8Array(bytes)]
+        .map((byte) => byte.toString(16).padStart(2, "0"))
+        .join("");
+}
+/**
+ * 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 async function createIdempotencyFingerprint(value, options = {}) {
+    if (!globalThis.crypto?.subtle) {
+        throw new IdempotencyFingerprintError("Cannot create an idempotency fingerprint because Web Crypto is unavailable.");
+    }
+    const canonical = canonicalize(value, options, [], new WeakSet());
+    const json = JSON.stringify(canonical ?? null);
+    const digest = await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(json));
+    return `sha256:${bytesToHex(digest)}`;
+}
+//# sourceMappingURL=index.js.map

package/dist/idempotency/index.js.map

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

package/dist/jobs/index.d.ts

@@ -1,56 +1,300 @@
 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>;
+/**
+ * Duration accepted by retry helpers. Numbers are milliseconds.
+ */
+export type JobRetryDuration = number | `${number}ms` | `${number}s` | `${number}m` | `${number}h`;
+/**
+ * Retry strategy understood by Beignet job adapters.
+ */
+export type JobRetryStrategy = "none" | "fixed" | "exponential";
+/**
+ * Arguments passed to a retry predicate.
+ */
+export interface JobRetryPredicateArgs {
+    /**
+     * Error thrown by the previous attempt.
+     */
+    error: unknown;
+    /**
+     * One-based attempt number that just failed.
+     */
+    attempt: number;
+    /**
+     * Maximum attempts allowed for this delivery.
+     */
+    maxAttempts: number;
+    /**
+     * Job name when the retry decision is for a job.
+     */
+    jobName?: string;
+}
+/**
+ * Return whether a failed attempt should be retried.
+ */
+export type JobRetryPredicate = (args: JobRetryPredicateArgs) => boolean;
+/**
+ * Job definition created by `defineJob(...)`.
+ */
 export interface JobDef<Name extends string = string, Payload extends StandardSchema = StandardSchema, Ctx = unknown> {
+    /**
+     * Discriminator for job definitions.
+     */
     readonly kind: "job";
+    /**
+     * Stable job name used by dispatchers and provider adapters.
+     */
     readonly name: Name;
+    /**
+     * Standard Schema payload validator.
+     */
     readonly payload: Payload;
+    /**
+     * Optional human-readable description for docs and tooling.
+     */
     readonly description?: string;
+    /**
+     * Retry metadata for durable job providers.
+     */
     readonly retry?: JobRetryOptions;
+    /**
+     * Handle a parsed job payload.
+     */
     handle(args: JobHandleArgs<JobDef<Name, Payload, Ctx>, Ctx>): MaybePromise<void>;
 }
+/**
+ * Infer the parsed payload type for a job definition.
+ */
 export type InferJobPayload<J extends JobDef> = J["payload"] extends StandardSchemaV1<unknown, infer Output> ? Output : never;
+/**
+ * Arguments passed to a job handler.
+ */
 export interface JobHandleArgs<J extends JobDef, Ctx> {
+    /**
+     * Job definition being handled.
+     */
     job: J;
+    /**
+     * Parsed job payload.
+     */
     payload: InferJobPayload<J>;
+    /**
+     * Handler context.
+     */
     ctx: Ctx;
 }
+/**
+ * Retry metadata that durable job providers can map to their own retry model.
+ */
 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.
+     * Retry strategy. Raw objects without a strategy default to exponential
+     * backoff so existing `{ attempts }` style definitions stay meaningful.
+     */
+    strategy?: JobRetryStrategy;
+    /**
+     * Maximum total attempts, including the first attempt.
      */
     attempts?: number;
+    /**
+     * Delay between attempts for fixed retry policies.
+     */
+    delay?: JobRetryDuration;
+    /**
+     * Initial delay for exponential retry policies.
+     */
+    initialDelay?: JobRetryDuration;
+    /**
+     * Maximum delay for exponential retry policies.
+     */
+    maxDelay?: JobRetryDuration;
+    /**
+     * Exponential multiplier. Defaults to `2`.
+     */
+    factor?: number;
+    /**
+     * Whether adapters that compute delays should add jitter.
+     */
+    jitter?: boolean;
+    /**
+     * Optional app-owned retry classifier.
+     */
+    retryIf?: JobRetryPredicate;
 }
+/**
+ * Options for declaring a typed job.
+ */
 export interface DefineJobOptions<Name extends string, Payload extends StandardSchema, Ctx> {
+    /**
+     * Standard Schema payload validator.
+     */
     payload: Payload;
+    /**
+     * Optional human-readable description for docs and tooling.
+     */
     description?: string;
+    /**
+     * Retry metadata for durable job providers.
+     */
     retry?: JobRetryOptions;
+    /**
+     * Handle a parsed job payload.
+     */
     handle(args: JobHandleArgs<JobDef<Name, Payload, Ctx>, Ctx>): MaybePromise<void>;
 }
+/**
+ * Options for a fixed job retry policy.
+ */
+export interface FixedJobRetryOptions {
+    /**
+     * Maximum total attempts, including the first attempt.
+     */
+    attempts: number;
+    /**
+     * Delay between attempts.
+     */
+    delay: JobRetryDuration;
+    /**
+     * Optional app-owned retry classifier.
+     */
+    retryIf?: JobRetryPredicate;
+}
+/**
+ * Options for an exponential job retry policy.
+ */
+export interface ExponentialJobRetryOptions {
+    /**
+     * Maximum total attempts, including the first attempt.
+     */
+    attempts: number;
+    /**
+     * Initial delay. Defaults to `1s`.
+     */
+    initialDelay?: JobRetryDuration;
+    /**
+     * Maximum delay. Defaults to `1m`.
+     */
+    maxDelay?: JobRetryDuration;
+    /**
+     * Exponential multiplier. Defaults to `2`.
+     */
+    factor?: number;
+    /**
+     * Whether computed delays should include jitter.
+     */
+    jitter?: boolean;
+    /**
+     * Optional app-owned retry classifier.
+     */
+    retryIf?: JobRetryPredicate;
+}
+/**
+ * Retry helper namespace for job definitions.
+ */
+export declare const retry: {
+    /**
+     * Disable retries. The first failure is terminal.
+     */
+    readonly none: () => JobRetryOptions;
+    /**
+     * Retry with the same delay between attempts.
+     */
+    readonly fixed: (options: FixedJobRetryOptions) => JobRetryOptions;
+    /**
+     * Retry with exponential backoff.
+     */
+    readonly exponential: (options: ExponentialJobRetryOptions) => JobRetryOptions;
+};
+/**
+ * Options for the inline job dispatcher.
+ */
 export interface InlineJobDispatcherOptions<Ctx> {
+    /**
+     * Static job context or factory evaluated for each dispatched job.
+     */
     ctx?: Ctx | (() => MaybePromise<Ctx>);
+    /**
+     * Called when a dispatched inline job fails. When omitted, errors are
+     * rethrown to the caller.
+     */
     onError?: (error: unknown, job: JobDef<string, StandardSchema, Ctx>) => void;
 }
+/**
+ * Local/test job dispatcher that executes job handlers inline.
+ */
 export interface InlineJobDispatcher<Ctx = unknown> {
+    /**
+     * Validate a payload and run the job handler immediately.
+     */
     dispatch<J extends JobDef<string, StandardSchema, Ctx>>(job: J, payload: InferJobPayload<J>): Promise<void>;
 }
+/**
+ * Context-bound job helper factory.
+ */
 export interface JobHandlers<Ctx> {
+    /**
+     * Define a job with the bound context type.
+     */
     defineJob<Name extends string, Payload extends StandardSchema>(name: Name, options: DefineJobOptions<Name, Payload, Ctx>): JobDef<Name, Payload, Ctx>;
+    /**
+     * Create an inline dispatcher with the bound context type.
+     */
     createInlineJobDispatcher(options?: InlineJobDispatcherOptions<Ctx>): InlineJobDispatcher<Ctx>;
 }
+/**
+ * Error thrown when job payload validation fails.
+ */
 export declare class JobValidationError extends Error {
+    /**
+     * Raw Standard Schema validation issues.
+     */
     readonly issues: readonly StandardSchemaV1.Issue[];
     constructor(args: {
         name: string;
         issues: readonly StandardSchemaV1.Issue[];
     });
 }
+/**
+ * Return the maximum total attempts configured by a retry policy.
+ */
+export declare function getJobRetryMaxAttempts(options: JobRetryOptions | undefined): number | undefined;
+/**
+ * Return whether a failed job attempt should be retried.
+ */
+export declare function shouldRetryJob(options: JobRetryOptions | undefined, args: JobRetryPredicateArgs): boolean;
+/**
+ * Compute the next retry delay in milliseconds for a failed job attempt.
+ */
+export declare function getJobRetryDelayMs(options: JobRetryOptions | undefined, args: Pick<JobRetryPredicateArgs, "attempt" | "error" | "jobName">): number;
+/**
+ * Define a typed job.
+ *
+ * Retry options are provider hints. Inline dispatchers validate payloads and
+ * call `handle(...)` immediately; durable providers may enqueue or schedule the
+ * job according to their own runtime.
+ */
 export declare function defineJob<Name extends string, Payload extends StandardSchema, Ctx = unknown>(name: Name, options: DefineJobOptions<Name, Payload, Ctx>): JobDef<Name, Payload, Ctx>;
+/**
+ * Validate and parse a job payload with the job's Standard Schema.
+ */
 export declare function parseJobPayload<J extends JobDef>(job: J, payload: unknown): Promise<InferJobPayload<J>>;
+/**
+ * Create a local/test dispatcher that runs job handlers inline.
+ */
 export declare function createInlineJobDispatcher<Ctx>(options?: InlineJobDispatcherOptions<Ctx>): InlineJobDispatcher<Ctx>;
+/**
+ * Create job helper methods bound to an application context type.
+ */
 export declare function createJobHandlers<Ctx>(): JobHandlers<Ctx>;
 //# sourceMappingURL=index.d.ts.map