@oncely/core 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,183 @@
+import { O as OncelyConfig, S as StorageAdapter, c as createInstance } from './errors-BUehgS6t.cjs';
+export { A as AcquireResult, C as ConflictError, I as IdempotencyError, M as MemoryStorage, d as MismatchError, b as MissingKeyError, k as OnConflictCallback, l as OnErrorCallback, i as OnHitCallback, j as OnMissCallback, a as Oncely, g as OncelyOptions, P as ProblemDetails, R as RunOptions, h as RunResult, e as StorageError, f as StoredResponse } from './errors-BUehgS6t.cjs';
+
+type GlobalConfig = OncelyConfig;
+/**
+ * Configure global defaults for oncely.
+ * Call this once at application startup to set defaults for all oncely operations.
+ *
+ * @example
+ * ```typescript
+ * import { oncely } from '@oncely/core';
+ * import { redis } from '@oncely/redis';
+ *
+ * // Set up once at app startup
+ * oncely.configure({
+ *   storage: redis(),
+ *   ttl: '1h',
+ *   onHit: (key) => console.log(`Cache hit: ${key}`),
+ * });
+ * ```
+ */
+declare function configure(config: OncelyConfig): void;
+/**
+ * Get the current global configuration.
+ */
+declare function getConfig(): OncelyConfig;
+/**
+ * Reset global configuration to defaults.
+ * Useful for testing.
+ */
+declare function resetConfig(): void;
+/**
+ * Get the default storage adapter.
+ * Returns the configured global storage, or a shared memory instance.
+ */
+declare function getDefaultStorage(): StorageAdapter;
+
+/**
+ * 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";
+
+/**
+ * Parse a TTL string into milliseconds.
+ * Supports: '30s', '5m', '24h', '7d'
+ */
+declare function parseTtl(ttl: number | string): number;
+/**
+ * Generate a simple hash from a string using DJB2 algorithm.
+ *
+ * **Note:** This is a fast, non-cryptographic hash suitable for request
+ * fingerprinting. It has a 32-bit output space (~4 billion unique values).
+ *
+ * **Collision Risk:** At ~77,000 unique payloads, there's a 50% probability
+ * of collision (birthday problem). For high-volume payment systems or
+ * security-sensitive applications, use {@link hashObjectSecure} instead.
+ *
+ * For typical API use cases with moderate volume, DJB2 provides excellent
+ * performance (~2.4M ops/sec vs ~600K ops/sec for SHA-256).
+ */
+declare function simpleHash(str: string): string;
+/**
+ * Generate a SHA-256 hash from a string.
+ *
+ * Use this for security-sensitive applications where collision resistance
+ * is important. Slower than {@link simpleHash} but cryptographically secure.
+ */
+declare function secureHash(str: string): string;
+/**
+ * Hash an object by JSON stringifying it.
+ *
+ * Uses the fast DJB2 algorithm (~2.4M ops/sec). For high-volume payment
+ * systems or security-sensitive applications where collision resistance
+ * is critical, use {@link hashObjectSecure} instead.
+ *
+ * **Collision Risk:** At ~77,000 unique payloads, there's a 50% probability
+ * of collision. A collision could cause:
+ * - False mismatch errors (if hashes differ)
+ * - Or incorrectly matching different payloads (if hashes collide)
+ *
+ * **Note:** Object key order affects the hash. If you need order-independent
+ * hashing, sort the keys before passing to this function.
+ */
+declare function hashObject(obj: unknown): string;
+/**
+ * Hash an object using SHA-256.
+ *
+ * Use this for security-sensitive applications where collision resistance
+ * is important. Slower than {@link hashObject} but cryptographically secure.
+ */
+declare function hashObjectSecure(obj: unknown): string;
+/**
+ * Generate a cryptographically secure unique key (UUID v4).
+ *
+ * Uses Node.js crypto.randomUUID() for secure random generation.
+ */
+declare function generateKey(): string;
+/**
+ * Compose a deterministic key from multiple parts.
+ */
+declare function composeKey(...parts: (string | number)[]): string;
+
+/**
+ * Oncely namespace object.
+ * All oncely functionality is accessed through this namespace.
+ *
+ * @example
+ * ```typescript
+ * import { oncely } from '@oncely/core';
+ *
+ * // Configure globally
+ * oncely.configure({
+ *   storage: redis(),
+ *   ttl: '1h',
+ * });
+ *
+ * // Create an instance
+ * const instance = oncely.createInstance();
+ * const result = await instance.run({
+ *   key: 'order-123',
+ *   handler: () => createOrder(data),
+ * });
+ * ```
+ */
+declare const oncely: {
+    /**
+     * Configure global defaults for oncely.
+     * Call this once at application startup.
+     */
+    readonly configure: typeof configure;
+    /**
+     * Get the current global configuration.
+     */
+    readonly getConfig: typeof getConfig;
+    /**
+     * Reset global configuration to defaults.
+     * Useful for testing.
+     */
+    readonly resetConfig: typeof resetConfig;
+    /**
+     * Get the default storage adapter.
+     */
+    readonly getDefaultStorage: typeof getDefaultStorage;
+    /**
+     * Create an oncely instance with optional configuration.
+     * Uses global config merged with provided options.
+     */
+    readonly createInstance: typeof createInstance;
+    /**
+     * 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";
+};
+/**
+ * Interface for oncely namespace - can be extended via module augmentation.
+ */
+interface OncelyNamespace {
+    readonly configure: typeof configure;
+    readonly getConfig: typeof getConfig;
+    readonly resetConfig: typeof resetConfig;
+    readonly getDefaultStorage: typeof getDefaultStorage;
+    readonly createInstance: typeof createInstance;
+    readonly HEADER: typeof HEADER;
+    readonly HEADER_REPLAY: typeof HEADER_REPLAY;
+    [key: string]: unknown;
+}
+
+/**
+ * Pre-configured memory storage instance.
+ * Use this for quick setup in development.
+ */
+declare const memory: StorageAdapter;
+
+export { type GlobalConfig, HEADER, HEADER_REPLAY, OncelyConfig, type OncelyNamespace, StorageAdapter, composeKey, configure, generateKey, getConfig, getDefaultStorage, hashObject, hashObjectSecure, memory, oncely, parseTtl, resetConfig, secureHash, simpleHash };

package/dist/index.d.ts

@@ -0,0 +1,183 @@
+import { O as OncelyConfig, S as StorageAdapter, c as createInstance } from './errors-BUehgS6t.js';
+export { A as AcquireResult, C as ConflictError, I as IdempotencyError, M as MemoryStorage, d as MismatchError, b as MissingKeyError, k as OnConflictCallback, l as OnErrorCallback, i as OnHitCallback, j as OnMissCallback, a as Oncely, g as OncelyOptions, P as ProblemDetails, R as RunOptions, h as RunResult, e as StorageError, f as StoredResponse } from './errors-BUehgS6t.js';
+
+type GlobalConfig = OncelyConfig;
+/**
+ * Configure global defaults for oncely.
+ * Call this once at application startup to set defaults for all oncely operations.
+ *
+ * @example
+ * ```typescript
+ * import { oncely } from '@oncely/core';
+ * import { redis } from '@oncely/redis';
+ *
+ * // Set up once at app startup
+ * oncely.configure({
+ *   storage: redis(),
+ *   ttl: '1h',
+ *   onHit: (key) => console.log(`Cache hit: ${key}`),
+ * });
+ * ```
+ */
+declare function configure(config: OncelyConfig): void;
+/**
+ * Get the current global configuration.
+ */
+declare function getConfig(): OncelyConfig;
+/**
+ * Reset global configuration to defaults.
+ * Useful for testing.
+ */
+declare function resetConfig(): void;
+/**
+ * Get the default storage adapter.
+ * Returns the configured global storage, or a shared memory instance.
+ */
+declare function getDefaultStorage(): StorageAdapter;
+
+/**
+ * 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";
+
+/**
+ * Parse a TTL string into milliseconds.
+ * Supports: '30s', '5m', '24h', '7d'
+ */
+declare function parseTtl(ttl: number | string): number;
+/**
+ * Generate a simple hash from a string using DJB2 algorithm.
+ *
+ * **Note:** This is a fast, non-cryptographic hash suitable for request
+ * fingerprinting. It has a 32-bit output space (~4 billion unique values).
+ *
+ * **Collision Risk:** At ~77,000 unique payloads, there's a 50% probability
+ * of collision (birthday problem). For high-volume payment systems or
+ * security-sensitive applications, use {@link hashObjectSecure} instead.
+ *
+ * For typical API use cases with moderate volume, DJB2 provides excellent
+ * performance (~2.4M ops/sec vs ~600K ops/sec for SHA-256).
+ */
+declare function simpleHash(str: string): string;
+/**
+ * Generate a SHA-256 hash from a string.
+ *
+ * Use this for security-sensitive applications where collision resistance
+ * is important. Slower than {@link simpleHash} but cryptographically secure.
+ */
+declare function secureHash(str: string): string;
+/**
+ * Hash an object by JSON stringifying it.
+ *
+ * Uses the fast DJB2 algorithm (~2.4M ops/sec). For high-volume payment
+ * systems or security-sensitive applications where collision resistance
+ * is critical, use {@link hashObjectSecure} instead.
+ *
+ * **Collision Risk:** At ~77,000 unique payloads, there's a 50% probability
+ * of collision. A collision could cause:
+ * - False mismatch errors (if hashes differ)
+ * - Or incorrectly matching different payloads (if hashes collide)
+ *
+ * **Note:** Object key order affects the hash. If you need order-independent
+ * hashing, sort the keys before passing to this function.
+ */
+declare function hashObject(obj: unknown): string;
+/**
+ * Hash an object using SHA-256.
+ *
+ * Use this for security-sensitive applications where collision resistance
+ * is important. Slower than {@link hashObject} but cryptographically secure.
+ */
+declare function hashObjectSecure(obj: unknown): string;
+/**
+ * Generate a cryptographically secure unique key (UUID v4).
+ *
+ * Uses Node.js crypto.randomUUID() for secure random generation.
+ */
+declare function generateKey(): string;
+/**
+ * Compose a deterministic key from multiple parts.
+ */
+declare function composeKey(...parts: (string | number)[]): string;
+
+/**
+ * Oncely namespace object.
+ * All oncely functionality is accessed through this namespace.
+ *
+ * @example
+ * ```typescript
+ * import { oncely } from '@oncely/core';
+ *
+ * // Configure globally
+ * oncely.configure({
+ *   storage: redis(),
+ *   ttl: '1h',
+ * });
+ *
+ * // Create an instance
+ * const instance = oncely.createInstance();
+ * const result = await instance.run({
+ *   key: 'order-123',
+ *   handler: () => createOrder(data),
+ * });
+ * ```
+ */
+declare const oncely: {
+    /**
+     * Configure global defaults for oncely.
+     * Call this once at application startup.
+     */
+    readonly configure: typeof configure;
+    /**
+     * Get the current global configuration.
+     */
+    readonly getConfig: typeof getConfig;
+    /**
+     * Reset global configuration to defaults.
+     * Useful for testing.
+     */
+    readonly resetConfig: typeof resetConfig;
+    /**
+     * Get the default storage adapter.
+     */
+    readonly getDefaultStorage: typeof getDefaultStorage;
+    /**
+     * Create an oncely instance with optional configuration.
+     * Uses global config merged with provided options.
+     */
+    readonly createInstance: typeof createInstance;
+    /**
+     * 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";
+};
+/**
+ * Interface for oncely namespace - can be extended via module augmentation.
+ */
+interface OncelyNamespace {
+    readonly configure: typeof configure;
+    readonly getConfig: typeof getConfig;
+    readonly resetConfig: typeof resetConfig;
+    readonly getDefaultStorage: typeof getDefaultStorage;
+    readonly createInstance: typeof createInstance;
+    readonly HEADER: typeof HEADER;
+    readonly HEADER_REPLAY: typeof HEADER_REPLAY;
+    [key: string]: unknown;
+}
+
+/**
+ * Pre-configured memory storage instance.
+ * Use this for quick setup in development.
+ */
+declare const memory: StorageAdapter;
+
+export { type GlobalConfig, HEADER, HEADER_REPLAY, OncelyConfig, type OncelyNamespace, StorageAdapter, composeKey, configure, generateKey, getConfig, getDefaultStorage, hashObject, hashObjectSecure, memory, oncely, parseTtl, resetConfig, secureHash, simpleHash };