@oncely/client 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,325 @@
+/**
+ * Key generation utilities for idempotency keys.
+ */
+/**
+ * Generate a unique idempotency key.
+ *
+ * When called with no arguments, generates a random UUID v4.
+ * When called with components, generates a deterministic hash-based key.
+ *
+ * @example
+ * ```typescript
+ * // Random key (UUID v4)
+ * const key = generateKey();
+ * // => "550e8400-e29b-41d4-a716-446655440000"
+ *
+ * // Deterministic key from components
+ * const key = generateKey('user-123', 'create-order', 1234567890);
+ * // => "f7c3bc1d..." (consistent for same inputs)
+ * ```
+ */
+declare function generateKey(...components: (string | number | boolean)[]): string;
+/**
+ * Generate a prefixed idempotency key.
+ *
+ * @example
+ * ```typescript
+ * const key = generatePrefixedKey('ord');
+ * // => "ord_550e8400-e29b-41d4-a716-446655440000"
+ * ```
+ */
+declare function generatePrefixedKey(prefix: string): string;
+/**
+ * Key generator interface for the namespace.
+ */
+interface KeyGenerator {
+    /**
+     * Generate a unique key, optionally from components.
+     */
+    (...components: (string | number | boolean)[]): string;
+    /**
+     * Generate a prefixed key.
+     */
+    prefixed(prefix: string): string;
+}
+/**
+ * Create the key generator function with attached methods.
+ */
+declare function createKeyGenerator(): KeyGenerator;
+
+/**
+ * Key store for managing pending idempotency keys.
+ */
+/**
+ * Options for creating a key store.
+ */
+interface StoreOptions {
+    /**
+     * Storage backend (localStorage, sessionStorage, or custom).
+     * @default localStorage in browser, in-memory in Node.js
+     */
+    storage?: Storage | MemoryStorage;
+    /**
+     * Key prefix for namespacing.
+     * @default 'oncely:'
+     */
+    prefix?: string;
+    /**
+     * TTL for pending keys in milliseconds or string format.
+     * After this time, pending keys are considered expired.
+     * @default '5m'
+     */
+    ttl?: number | string;
+}
+/**
+ * Minimal storage interface compatible with localStorage/sessionStorage.
+ */
+interface Storage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+}
+/**
+ * Key store for managing pending idempotency keys.
+ */
+interface KeyStore {
+    /**
+     * Mark a key as pending (request in flight).
+     */
+    pending(key: string): void;
+    /**
+     * Check if a key is currently pending.
+     */
+    isPending(key: string): boolean;
+    /**
+     * Clear a pending key.
+     */
+    clear(key: string): void;
+    /**
+     * Clear all pending keys.
+     */
+    clearAll(): void;
+}
+/**
+ * In-memory storage implementation.
+ */
+declare class MemoryStorage implements Storage {
+    private data;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+}
+/**
+ * Create a key store for managing pending idempotency keys.
+ *
+ * @example
+ * ```typescript
+ * const store = createStore();
+ *
+ * // Before making request
+ * if (store.isPending('key-123')) {
+ *   throw new Error('Request already in progress');
+ * }
+ * store.pending('key-123');
+ *
+ * try {
+ *   await fetch('/api/orders', { ... });
+ * } finally {
+ *   store.clear('key-123');
+ * }
+ * ```
+ */
+declare function createStore(options?: StoreOptions): KeyStore;
+
+/**
+ * Response helper utilities for detecting idempotency-related responses.
+ */
+/**
+ * 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;
+    /** Retry-After value in seconds (for conflict errors) */
+    retryAfter?: number;
+    /** Additional properties */
+    [key: string]: unknown;
+}
+/**
+ * Response-like object for compatibility with various fetch implementations.
+ */
+interface ResponseLike {
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    json?(): Promise<unknown>;
+    clone?(): ResponseLike;
+}
+/**
+ * Check if a response is a replay (cached response).
+ *
+ * @example
+ * ```typescript
+ * const response = await fetch('/api/orders', { ... });
+ * if (isReplay(response)) {
+ *   console.log('Response was served from cache');
+ * }
+ * ```
+ */
+declare function isReplay(response: ResponseLike): boolean;
+/**
+ * Check if a response indicates a conflict (409).
+ * This means a request with the same key is already in progress.
+ *
+ * @example
+ * ```typescript
+ * if (isConflict(response)) {
+ *   const retryAfter = getRetryAfter(response);
+ *   await delay(retryAfter * 1000);
+ *   // Retry the request
+ * }
+ * ```
+ */
+declare function isConflict(response: ResponseLike): boolean;
+/**
+ * Check if a response indicates a mismatch (422).
+ * This means the idempotency key was reused with a different request payload.
+ *
+ * @example
+ * ```typescript
+ * if (isMismatch(response)) {
+ *   // Generate a new key and retry
+ *   const newKey = oncely.key();
+ *   // Retry with new key
+ * }
+ * ```
+ */
+declare function isMismatch(response: ResponseLike): boolean;
+/**
+ * Check if a response indicates a missing key error (400).
+ * This means the idempotency key header was required but not provided.
+ */
+declare function isMissingKey(response: ResponseLike): boolean;
+/**
+ * Get the Retry-After value from a response.
+ * Returns the value in seconds, or the default if not present.
+ *
+ * @param response - The response to check
+ * @param defaultValue - Default value if header is not present (default: 1)
+ * @returns Retry delay in seconds
+ */
+declare function getRetryAfter(response: ResponseLike, defaultValue?: number): number;
+/**
+ * Parse RFC 7807 Problem Details from an error response.
+ *
+ * @example
+ * ```typescript
+ * if (!response.ok) {
+ *   const problem = await getProblem(response);
+ *   console.error(`${problem.title}: ${problem.detail}`);
+ * }
+ * ```
+ */
+declare function getProblem(response: ResponseLike): Promise<ProblemDetails | null>;
+/**
+ * Check if a response is an idempotency error (400, 409, or 422).
+ */
+declare function isIdempotencyError(response: ResponseLike): boolean;
+
+/**
+ * HTTP header constants following IETF draft-ietf-httpapi-idempotency-key-header.
+ * @see https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-idempotency-key-header
+ */
+/** Standard header name for idempotency keys */
+declare const HEADER = "Idempotency-Key";
+/** Header indicating a response was replayed from cache */
+declare const HEADER_REPLAY = "Idempotency-Replay";
+
+/**
+ * Oncely client namespace.
+ * All client-side functionality is accessed through this namespace.
+ */
+declare const oncely: {
+    /**
+     * Generate a unique idempotency key.
+     *
+     * @example
+     * ```typescript
+     * // Random UUID key
+     * const key = oncely.key();
+     *
+     * // Deterministic key from components
+     * const key = oncely.key('user-123', 'action', timestamp);
+     *
+     * // Prefixed key
+     * const key = oncely.key.prefixed('ord');
+     * ```
+     */
+    readonly key: KeyGenerator;
+    /**
+     * Create a key store for managing pending requests.
+     *
+     * @example
+     * ```typescript
+     * const store = oncely.store();
+     *
+     * if (store.isPending(key)) {
+     *   throw new Error('Request in progress');
+     * }
+     * store.pending(key);
+     * ```
+     */
+    readonly store: typeof createStore;
+    /**
+     * Check if response is a replay (served from cache).
+     */
+    readonly isReplay: typeof isReplay;
+    /**
+     * Check if response is a conflict (409).
+     */
+    readonly isConflict: typeof isConflict;
+    /**
+     * Check if response is a mismatch (422).
+     */
+    readonly isMismatch: typeof isMismatch;
+    /**
+     * Check if response is a missing key error (400).
+     */
+    readonly isMissingKey: typeof isMissingKey;
+    /**
+     * Check if response is any idempotency error (400, 409, 422).
+     */
+    readonly isIdempotencyError: typeof isIdempotencyError;
+    /**
+     * Get Retry-After value from response.
+     */
+    readonly getRetryAfter: typeof getRetryAfter;
+    /**
+     * Parse RFC 7807 Problem Details from response.
+     */
+    readonly getProblem: typeof getProblem;
+    /**
+     * Standard header name for idempotency keys.
+     * @see https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-idempotency-key-header
+     */
+    readonly HEADER: "Idempotency-Key";
+    /**
+     * Header indicating a response was replayed from cache.
+     */
+    readonly HEADER_REPLAY: "Idempotency-Replay";
+};
+type OncelyClient = typeof oncely;
+
+export { HEADER, HEADER_REPLAY, type KeyGenerator, type KeyStore, MemoryStorage, type OncelyClient, type ProblemDetails, type ResponseLike, type Storage, type StoreOptions, createKeyGenerator, createStore, generateKey, generatePrefixedKey, getProblem, getRetryAfter, isConflict, isIdempotencyError, isMismatch, isMissingKey, isReplay, oncely };

package/dist/index.d.ts

@@ -0,0 +1,325 @@
+/**
+ * Key generation utilities for idempotency keys.
+ */
+/**
+ * Generate a unique idempotency key.
+ *
+ * When called with no arguments, generates a random UUID v4.
+ * When called with components, generates a deterministic hash-based key.
+ *
+ * @example
+ * ```typescript
+ * // Random key (UUID v4)
+ * const key = generateKey();
+ * // => "550e8400-e29b-41d4-a716-446655440000"
+ *
+ * // Deterministic key from components
+ * const key = generateKey('user-123', 'create-order', 1234567890);
+ * // => "f7c3bc1d..." (consistent for same inputs)
+ * ```
+ */
+declare function generateKey(...components: (string | number | boolean)[]): string;
+/**
+ * Generate a prefixed idempotency key.
+ *
+ * @example
+ * ```typescript
+ * const key = generatePrefixedKey('ord');
+ * // => "ord_550e8400-e29b-41d4-a716-446655440000"
+ * ```
+ */
+declare function generatePrefixedKey(prefix: string): string;
+/**
+ * Key generator interface for the namespace.
+ */
+interface KeyGenerator {
+    /**
+     * Generate a unique key, optionally from components.
+     */
+    (...components: (string | number | boolean)[]): string;
+    /**
+     * Generate a prefixed key.
+     */
+    prefixed(prefix: string): string;
+}
+/**
+ * Create the key generator function with attached methods.
+ */
+declare function createKeyGenerator(): KeyGenerator;
+
+/**
+ * Key store for managing pending idempotency keys.
+ */
+/**
+ * Options for creating a key store.
+ */
+interface StoreOptions {
+    /**
+     * Storage backend (localStorage, sessionStorage, or custom).
+     * @default localStorage in browser, in-memory in Node.js
+     */
+    storage?: Storage | MemoryStorage;
+    /**
+     * Key prefix for namespacing.
+     * @default 'oncely:'
+     */
+    prefix?: string;
+    /**
+     * TTL for pending keys in milliseconds or string format.
+     * After this time, pending keys are considered expired.
+     * @default '5m'
+     */
+    ttl?: number | string;
+}
+/**
+ * Minimal storage interface compatible with localStorage/sessionStorage.
+ */
+interface Storage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+}
+/**
+ * Key store for managing pending idempotency keys.
+ */
+interface KeyStore {
+    /**
+     * Mark a key as pending (request in flight).
+     */
+    pending(key: string): void;
+    /**
+     * Check if a key is currently pending.
+     */
+    isPending(key: string): boolean;
+    /**
+     * Clear a pending key.
+     */
+    clear(key: string): void;
+    /**
+     * Clear all pending keys.
+     */
+    clearAll(): void;
+}
+/**
+ * In-memory storage implementation.
+ */
+declare class MemoryStorage implements Storage {
+    private data;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+}
+/**
+ * Create a key store for managing pending idempotency keys.
+ *
+ * @example
+ * ```typescript
+ * const store = createStore();
+ *
+ * // Before making request
+ * if (store.isPending('key-123')) {
+ *   throw new Error('Request already in progress');
+ * }
+ * store.pending('key-123');
+ *
+ * try {
+ *   await fetch('/api/orders', { ... });
+ * } finally {
+ *   store.clear('key-123');
+ * }
+ * ```
+ */
+declare function createStore(options?: StoreOptions): KeyStore;
+
+/**
+ * Response helper utilities for detecting idempotency-related responses.
+ */
+/**
+ * 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;
+    /** Retry-After value in seconds (for conflict errors) */
+    retryAfter?: number;
+    /** Additional properties */
+    [key: string]: unknown;
+}
+/**
+ * Response-like object for compatibility with various fetch implementations.
+ */
+interface ResponseLike {
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    json?(): Promise<unknown>;
+    clone?(): ResponseLike;
+}
+/**
+ * Check if a response is a replay (cached response).
+ *
+ * @example
+ * ```typescript
+ * const response = await fetch('/api/orders', { ... });
+ * if (isReplay(response)) {
+ *   console.log('Response was served from cache');
+ * }
+ * ```
+ */
+declare function isReplay(response: ResponseLike): boolean;
+/**
+ * Check if a response indicates a conflict (409).
+ * This means a request with the same key is already in progress.
+ *
+ * @example
+ * ```typescript
+ * if (isConflict(response)) {
+ *   const retryAfter = getRetryAfter(response);
+ *   await delay(retryAfter * 1000);
+ *   // Retry the request
+ * }
+ * ```
+ */
+declare function isConflict(response: ResponseLike): boolean;
+/**
+ * Check if a response indicates a mismatch (422).
+ * This means the idempotency key was reused with a different request payload.
+ *
+ * @example
+ * ```typescript
+ * if (isMismatch(response)) {
+ *   // Generate a new key and retry
+ *   const newKey = oncely.key();
+ *   // Retry with new key
+ * }
+ * ```
+ */
+declare function isMismatch(response: ResponseLike): boolean;
+/**
+ * Check if a response indicates a missing key error (400).
+ * This means the idempotency key header was required but not provided.
+ */
+declare function isMissingKey(response: ResponseLike): boolean;
+/**
+ * Get the Retry-After value from a response.
+ * Returns the value in seconds, or the default if not present.
+ *
+ * @param response - The response to check
+ * @param defaultValue - Default value if header is not present (default: 1)
+ * @returns Retry delay in seconds
+ */
+declare function getRetryAfter(response: ResponseLike, defaultValue?: number): number;
+/**
+ * Parse RFC 7807 Problem Details from an error response.
+ *
+ * @example
+ * ```typescript
+ * if (!response.ok) {
+ *   const problem = await getProblem(response);
+ *   console.error(`${problem.title}: ${problem.detail}`);
+ * }
+ * ```
+ */
+declare function getProblem(response: ResponseLike): Promise<ProblemDetails | null>;
+/**
+ * Check if a response is an idempotency error (400, 409, or 422).
+ */
+declare function isIdempotencyError(response: ResponseLike): boolean;
+
+/**
+ * HTTP header constants following IETF draft-ietf-httpapi-idempotency-key-header.
+ * @see https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-idempotency-key-header
+ */
+/** Standard header name for idempotency keys */
+declare const HEADER = "Idempotency-Key";
+/** Header indicating a response was replayed from cache */
+declare const HEADER_REPLAY = "Idempotency-Replay";
+
+/**
+ * Oncely client namespace.
+ * All client-side functionality is accessed through this namespace.
+ */
+declare const oncely: {
+    /**
+     * Generate a unique idempotency key.
+     *
+     * @example
+     * ```typescript
+     * // Random UUID key
+     * const key = oncely.key();
+     *
+     * // Deterministic key from components
+     * const key = oncely.key('user-123', 'action', timestamp);
+     *
+     * // Prefixed key
+     * const key = oncely.key.prefixed('ord');
+     * ```
+     */
+    readonly key: KeyGenerator;
+    /**
+     * Create a key store for managing pending requests.
+     *
+     * @example
+     * ```typescript
+     * const store = oncely.store();
+     *
+     * if (store.isPending(key)) {
+     *   throw new Error('Request in progress');
+     * }
+     * store.pending(key);
+     * ```
+     */
+    readonly store: typeof createStore;
+    /**
+     * Check if response is a replay (served from cache).
+     */
+    readonly isReplay: typeof isReplay;
+    /**
+     * Check if response is a conflict (409).
+     */
+    readonly isConflict: typeof isConflict;
+    /**
+     * Check if response is a mismatch (422).
+     */
+    readonly isMismatch: typeof isMismatch;
+    /**
+     * Check if response is a missing key error (400).
+     */
+    readonly isMissingKey: typeof isMissingKey;
+    /**
+     * Check if response is any idempotency error (400, 409, 422).
+     */
+    readonly isIdempotencyError: typeof isIdempotencyError;
+    /**
+     * Get Retry-After value from response.
+     */
+    readonly getRetryAfter: typeof getRetryAfter;
+    /**
+     * Parse RFC 7807 Problem Details from response.
+     */
+    readonly getProblem: typeof getProblem;
+    /**
+     * Standard header name for idempotency keys.
+     * @see https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-idempotency-key-header
+     */
+    readonly HEADER: "Idempotency-Key";
+    /**
+     * Header indicating a response was replayed from cache.
+     */
+    readonly HEADER_REPLAY: "Idempotency-Replay";
+};
+type OncelyClient = typeof oncely;
+
+export { HEADER, HEADER_REPLAY, type KeyGenerator, type KeyStore, MemoryStorage, type OncelyClient, type ProblemDetails, type ResponseLike, type Storage, type StoreOptions, createKeyGenerator, createStore, generateKey, generatePrefixedKey, getProblem, getRetryAfter, isConflict, isIdempotencyError, isMismatch, isMissingKey, isReplay, oncely };