@oncely/core 0.2.0

package/dist/errors-BUehgS6t.d.cts

@@ -0,0 +1,310 @@
+/**
+ * Storage adapter interface for oncely.
+ * Implement this interface to create custom storage backends.
+ */
+interface StorageAdapter {
+    /**
+     * Attempt to acquire a lock for the given key.
+     * Returns the current state of the key.
+     */
+    acquire(key: string, hash: string | null, ttl: number): Promise<AcquireResult>;
+    /**
+     * Save a completed response for the given key.
+     */
+    save(key: string, response: StoredResponse): Promise<void>;
+    /**
+     * Release a lock without saving a response.
+     * Called when the handler fails and the request should be retryable.
+     */
+    release(key: string): Promise<void>;
+    /**
+     * Delete a key from storage.
+     * Useful for testing or manual cleanup.
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Clear all keys from storage.
+     * Useful for testing.
+     */
+    clear(): Promise<void>;
+}
+/**
+ * Result of attempting to acquire a lock.
+ */
+type AcquireResult = {
+    status: 'acquired';
+} | {
+    status: 'hit';
+    response: StoredResponse;
+} | {
+    status: 'conflict';
+    startedAt: number;
+} | {
+    status: 'mismatch';
+    existingHash: string;
+    providedHash: string;
+};
+/**
+ * A stored idempotency response.
+ */
+interface StoredResponse {
+    /** The response data returned by the handler */
+    data: unknown;
+    /** When this response was created */
+    createdAt: number;
+    /** The hash of the original request (if provided) */
+    hash: string | null;
+}
+/**
+ * Callback fired when a cached response is returned.
+ */
+type OnHitCallback = (key: string, response: StoredResponse) => void;
+/**
+ * Callback fired when a new request is processed (cache miss).
+ */
+type OnMissCallback = (key: string) => void;
+/**
+ * Callback fired when a conflict occurs (request already in progress).
+ */
+type OnConflictCallback = (key: string) => void;
+/**
+ * Callback fired when an error occurs.
+ */
+type OnErrorCallback = (key: string, error: Error) => void;
+/**
+ * Global configuration options for oncely.
+ */
+interface OncelyConfig {
+    /** Storage adapter for persisting idempotency records */
+    storage?: StorageAdapter;
+    /**
+     * Time-to-live for idempotency keys.
+     * Can be a number (milliseconds) or a string like '24h', '7d', '30m'.
+     * @default '24h'
+     */
+    ttl?: number | string;
+    /**
+     * Whether to validate request fingerprints (hash).
+     * When true, reusing a key with different payload throws MismatchError.
+     * @default true
+     */
+    fingerprint?: boolean;
+    /**
+     * Whether to log debug information.
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Callback fired when a cached response is returned.
+     */
+    onHit?: OnHitCallback;
+    /**
+     * Callback fired when a new request is processed (cache miss).
+     */
+    onMiss?: OnMissCallback;
+    /**
+     * Callback fired when a conflict occurs (request already in progress).
+     */
+    onConflict?: OnConflictCallback;
+    /**
+     * Callback fired when an error occurs.
+     */
+    onError?: OnErrorCallback;
+}
+/**
+ * Options for creating an oncely instance.
+ */
+interface OncelyOptions extends OncelyConfig {
+    /** Storage adapter for persisting idempotency records (required for instance) */
+    storage: StorageAdapter;
+}
+/**
+ * Options for running an idempotent operation.
+ */
+interface RunOptions<T> {
+    /** Unique idempotency key for this request */
+    key: string;
+    /**
+     * Hash of the request body/params for mismatch detection.
+     * If provided and a cached response exists with a different hash,
+     * a MismatchError will be thrown.
+     */
+    hash?: string;
+    /** The handler function to execute */
+    handler: () => T | Promise<T>;
+}
+/**
+ * Result of running an idempotent operation.
+ */
+interface RunResult<T> {
+    /** The data returned by the handler (or cached) */
+    data: T;
+    /** Whether this was a cache hit */
+    cached: boolean;
+    /** Status of the operation */
+    status: 'created' | 'hit';
+    /** When the response was originally created (if cached) */
+    createdAt?: number;
+}
+
+/**
+ * Oncely idempotency service.
+ * Ensures operations are executed exactly once per idempotency key.
+ */
+declare class Oncely {
+    private readonly storage;
+    private readonly ttl;
+    private readonly debug;
+    private readonly onHit?;
+    private readonly onMiss?;
+    private readonly onConflict?;
+    private readonly onError?;
+    constructor(options: OncelyOptions);
+    /**
+     * Run an operation with idempotency protection.
+     *
+     * @example
+     * ```typescript
+     * const result = await idempotency.run({
+     *   key: 'order-123',
+     *   handler: async () => {
+     *     const order = await createOrder(data);
+     *     return order;
+     *   },
+     * });
+     *
+     * if (result.cached) {
+     *   console.log('Returned cached response');
+     * }
+     * ```
+     */
+    run<T>(options: RunOptions<T>): Promise<RunResult<T>>;
+    private log;
+}
+/**
+ * Create an oncely idempotency instance.
+ *
+ * Options are optional - will use global config or sensible defaults.
+ *
+ * @example
+ * ```typescript
+ * import { createInstance } from '@oncely/core';
+ *
+ * // Zero-config (uses memory storage)
+ * const idempotency = createInstance();
+ *
+ * // With explicit storage
+ * const idempotency = createInstance({ storage: myRedis });
+ *
+ * const result = await idempotency.run({
+ *   key: 'order-123',
+ *   handler: async () => createOrder(data),
+ * });
+ * ```
+ */
+declare function createInstance(options?: Partial<OncelyOptions>): Oncely;
+
+/**
+ * In-memory storage adapter.
+ * Suitable for development, testing, and single-instance deployments.
+ *
+ * **Warning:** Data is lost on restart and not shared across instances.
+ * Use Redis for production multi-instance deployments.
+ */
+declare class MemoryStorage implements StorageAdapter {
+    private store;
+    private cleanupInterval;
+    constructor();
+    acquire(key: string, hash: string | null, ttl: number): Promise<AcquireResult>;
+    save(key: string, response: StoredResponse): Promise<void>;
+    release(key: string): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    /**
+     * Stop the cleanup interval.
+     * Call this when shutting down to prevent memory leaks in tests.
+     */
+    destroy(): void;
+    private cleanup;
+}
+
+/**
+ * RFC 7807 Problem Details response format.
+ * @see https://www.rfc-editor.org/rfc/rfc7807
+ */
+interface ProblemDetails {
+    /** URI reference identifying the problem type */
+    type: string;
+    /** Short human-readable summary */
+    title: string;
+    /** HTTP status code */
+    status: number;
+    /** Detailed human-readable explanation */
+    detail: string;
+    /** URI reference to the specific occurrence (optional) */
+    instance?: string;
+    /** Additional properties */
+    [key: string]: unknown;
+}
+/**
+ * Base class for all oncely errors.
+ * Provides RFC 7807 Problem Details format for HTTP responses.
+ */
+declare class IdempotencyError extends Error {
+    /** HTTP status code for this error */
+    readonly statusCode: number;
+    /** Error type identifier (URL) */
+    readonly type: string;
+    /** Short title for the error */
+    readonly title: string;
+    constructor(message: string, statusCode: number, type: string, title: string);
+    /**
+     * Convert to RFC 7807 Problem Details format.
+     */
+    toProblemDetails(): ProblemDetails;
+    /**
+     * Convert to JSON (RFC 7807 format).
+     */
+    toJSON(): ProblemDetails;
+}
+/**
+ * Thrown when an idempotency key is required but not provided.
+ * HTTP 400 Bad Request
+ */
+declare class MissingKeyError extends IdempotencyError {
+    constructor();
+}
+/**
+ * Thrown when a request with the same key is already being processed.
+ * HTTP 409 Conflict
+ */
+declare class ConflictError extends IdempotencyError {
+    /** When the in-progress request started */
+    readonly startedAt: number;
+    /** Suggested retry delay in seconds */
+    readonly retryAfter: number;
+    constructor(startedAt: number);
+    toProblemDetails(): ProblemDetails;
+}
+/**
+ * Thrown when the same idempotency key is used with a different request payload.
+ * HTTP 422 Unprocessable Content
+ */
+declare class MismatchError extends IdempotencyError {
+    /** Hash of the original request */
+    readonly existingHash: string;
+    /** Hash of the current request */
+    readonly providedHash: string;
+    constructor(existingHash: string, providedHash: string);
+}
+/**
+ * Thrown when the storage adapter encounters an error.
+ * HTTP 500 Internal Server Error
+ */
+declare class StorageError extends IdempotencyError {
+    /** The underlying error from the storage adapter */
+    readonly cause: Error;
+    constructor(message: string, cause: Error);
+}
+
+export { type AcquireResult as A, ConflictError as C, IdempotencyError as I, MemoryStorage as M, type OncelyConfig as O, type ProblemDetails as P, type RunOptions as R, type StorageAdapter as S, Oncely as a, MissingKeyError as b, createInstance as c, MismatchError as d, StorageError as e, type StoredResponse as f, type OncelyOptions as g, type RunResult as h, type OnHitCallback as i, type OnMissCallback as j, type OnConflictCallback as k, type OnErrorCallback as l };

package/dist/errors-BUehgS6t.d.ts

@@ -0,0 +1,310 @@
+/**
+ * Storage adapter interface for oncely.
+ * Implement this interface to create custom storage backends.
+ */
+interface StorageAdapter {
+    /**
+     * Attempt to acquire a lock for the given key.
+     * Returns the current state of the key.
+     */
+    acquire(key: string, hash: string | null, ttl: number): Promise<AcquireResult>;
+    /**
+     * Save a completed response for the given key.
+     */
+    save(key: string, response: StoredResponse): Promise<void>;
+    /**
+     * Release a lock without saving a response.
+     * Called when the handler fails and the request should be retryable.
+     */
+    release(key: string): Promise<void>;
+    /**
+     * Delete a key from storage.
+     * Useful for testing or manual cleanup.
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Clear all keys from storage.
+     * Useful for testing.
+     */
+    clear(): Promise<void>;
+}
+/**
+ * Result of attempting to acquire a lock.
+ */
+type AcquireResult = {
+    status: 'acquired';
+} | {
+    status: 'hit';
+    response: StoredResponse;
+} | {
+    status: 'conflict';
+    startedAt: number;
+} | {
+    status: 'mismatch';
+    existingHash: string;
+    providedHash: string;
+};
+/**
+ * A stored idempotency response.
+ */
+interface StoredResponse {
+    /** The response data returned by the handler */
+    data: unknown;
+    /** When this response was created */
+    createdAt: number;
+    /** The hash of the original request (if provided) */
+    hash: string | null;
+}
+/**
+ * Callback fired when a cached response is returned.
+ */
+type OnHitCallback = (key: string, response: StoredResponse) => void;
+/**
+ * Callback fired when a new request is processed (cache miss).
+ */
+type OnMissCallback = (key: string) => void;
+/**
+ * Callback fired when a conflict occurs (request already in progress).
+ */
+type OnConflictCallback = (key: string) => void;
+/**
+ * Callback fired when an error occurs.
+ */
+type OnErrorCallback = (key: string, error: Error) => void;
+/**
+ * Global configuration options for oncely.
+ */
+interface OncelyConfig {
+    /** Storage adapter for persisting idempotency records */
+    storage?: StorageAdapter;
+    /**
+     * Time-to-live for idempotency keys.
+     * Can be a number (milliseconds) or a string like '24h', '7d', '30m'.
+     * @default '24h'
+     */
+    ttl?: number | string;
+    /**
+     * Whether to validate request fingerprints (hash).
+     * When true, reusing a key with different payload throws MismatchError.
+     * @default true
+     */
+    fingerprint?: boolean;
+    /**
+     * Whether to log debug information.
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Callback fired when a cached response is returned.
+     */
+    onHit?: OnHitCallback;
+    /**
+     * Callback fired when a new request is processed (cache miss).
+     */
+    onMiss?: OnMissCallback;
+    /**
+     * Callback fired when a conflict occurs (request already in progress).
+     */
+    onConflict?: OnConflictCallback;
+    /**
+     * Callback fired when an error occurs.
+     */
+    onError?: OnErrorCallback;
+}
+/**
+ * Options for creating an oncely instance.
+ */
+interface OncelyOptions extends OncelyConfig {
+    /** Storage adapter for persisting idempotency records (required for instance) */
+    storage: StorageAdapter;
+}
+/**
+ * Options for running an idempotent operation.
+ */
+interface RunOptions<T> {
+    /** Unique idempotency key for this request */
+    key: string;
+    /**
+     * Hash of the request body/params for mismatch detection.
+     * If provided and a cached response exists with a different hash,
+     * a MismatchError will be thrown.
+     */
+    hash?: string;
+    /** The handler function to execute */
+    handler: () => T | Promise<T>;
+}
+/**
+ * Result of running an idempotent operation.
+ */
+interface RunResult<T> {
+    /** The data returned by the handler (or cached) */
+    data: T;
+    /** Whether this was a cache hit */
+    cached: boolean;
+    /** Status of the operation */
+    status: 'created' | 'hit';
+    /** When the response was originally created (if cached) */
+    createdAt?: number;
+}
+
+/**
+ * Oncely idempotency service.
+ * Ensures operations are executed exactly once per idempotency key.
+ */
+declare class Oncely {
+    private readonly storage;
+    private readonly ttl;
+    private readonly debug;
+    private readonly onHit?;
+    private readonly onMiss?;
+    private readonly onConflict?;
+    private readonly onError?;
+    constructor(options: OncelyOptions);
+    /**
+     * Run an operation with idempotency protection.
+     *
+     * @example
+     * ```typescript
+     * const result = await idempotency.run({
+     *   key: 'order-123',
+     *   handler: async () => {
+     *     const order = await createOrder(data);
+     *     return order;
+     *   },
+     * });
+     *
+     * if (result.cached) {
+     *   console.log('Returned cached response');
+     * }
+     * ```
+     */
+    run<T>(options: RunOptions<T>): Promise<RunResult<T>>;
+    private log;
+}
+/**
+ * Create an oncely idempotency instance.
+ *
+ * Options are optional - will use global config or sensible defaults.
+ *
+ * @example
+ * ```typescript
+ * import { createInstance } from '@oncely/core';
+ *
+ * // Zero-config (uses memory storage)
+ * const idempotency = createInstance();
+ *
+ * // With explicit storage
+ * const idempotency = createInstance({ storage: myRedis });
+ *
+ * const result = await idempotency.run({
+ *   key: 'order-123',
+ *   handler: async () => createOrder(data),
+ * });
+ * ```
+ */
+declare function createInstance(options?: Partial<OncelyOptions>): Oncely;
+
+/**
+ * In-memory storage adapter.
+ * Suitable for development, testing, and single-instance deployments.
+ *
+ * **Warning:** Data is lost on restart and not shared across instances.
+ * Use Redis for production multi-instance deployments.
+ */
+declare class MemoryStorage implements StorageAdapter {
+    private store;
+    private cleanupInterval;
+    constructor();
+    acquire(key: string, hash: string | null, ttl: number): Promise<AcquireResult>;
+    save(key: string, response: StoredResponse): Promise<void>;
+    release(key: string): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    /**
+     * Stop the cleanup interval.
+     * Call this when shutting down to prevent memory leaks in tests.
+     */
+    destroy(): void;
+    private cleanup;
+}
+
+/**
+ * RFC 7807 Problem Details response format.
+ * @see https://www.rfc-editor.org/rfc/rfc7807
+ */
+interface ProblemDetails {
+    /** URI reference identifying the problem type */
+    type: string;
+    /** Short human-readable summary */
+    title: string;
+    /** HTTP status code */
+    status: number;
+    /** Detailed human-readable explanation */
+    detail: string;
+    /** URI reference to the specific occurrence (optional) */
+    instance?: string;
+    /** Additional properties */
+    [key: string]: unknown;
+}
+/**
+ * Base class for all oncely errors.
+ * Provides RFC 7807 Problem Details format for HTTP responses.
+ */
+declare class IdempotencyError extends Error {
+    /** HTTP status code for this error */
+    readonly statusCode: number;
+    /** Error type identifier (URL) */
+    readonly type: string;
+    /** Short title for the error */
+    readonly title: string;
+    constructor(message: string, statusCode: number, type: string, title: string);
+    /**
+     * Convert to RFC 7807 Problem Details format.
+     */
+    toProblemDetails(): ProblemDetails;
+    /**
+     * Convert to JSON (RFC 7807 format).
+     */
+    toJSON(): ProblemDetails;
+}
+/**
+ * Thrown when an idempotency key is required but not provided.
+ * HTTP 400 Bad Request
+ */
+declare class MissingKeyError extends IdempotencyError {
+    constructor();
+}
+/**
+ * Thrown when a request with the same key is already being processed.
+ * HTTP 409 Conflict
+ */
+declare class ConflictError extends IdempotencyError {
+    /** When the in-progress request started */
+    readonly startedAt: number;
+    /** Suggested retry delay in seconds */
+    readonly retryAfter: number;
+    constructor(startedAt: number);
+    toProblemDetails(): ProblemDetails;
+}
+/**
+ * Thrown when the same idempotency key is used with a different request payload.
+ * HTTP 422 Unprocessable Content
+ */
+declare class MismatchError extends IdempotencyError {
+    /** Hash of the original request */
+    readonly existingHash: string;
+    /** Hash of the current request */
+    readonly providedHash: string;
+    constructor(existingHash: string, providedHash: string);
+}
+/**
+ * Thrown when the storage adapter encounters an error.
+ * HTTP 500 Internal Server Error
+ */
+declare class StorageError extends IdempotencyError {
+    /** The underlying error from the storage adapter */
+    readonly cause: Error;
+    constructor(message: string, cause: Error);
+}
+
+export { type AcquireResult as A, ConflictError as C, IdempotencyError as I, MemoryStorage as M, type OncelyConfig as O, type ProblemDetails as P, type RunOptions as R, type StorageAdapter as S, Oncely as a, MissingKeyError as b, createInstance as c, MismatchError as d, StorageError as e, type StoredResponse as f, type OncelyOptions as g, type RunResult as h, type OnHitCallback as i, type OnMissCallback as j, type OnConflictCallback as k, type OnErrorCallback as l };