@oncely/core 0.2.0

package/dist/testing.d.cts

@@ -0,0 +1,119 @@
+import { M as MemoryStorage, A as AcquireResult, f as StoredResponse, g as OncelyOptions, a as Oncely, O as OncelyConfig } from './errors-BUehgS6t.cjs';
+export { C as ConflictError, I as IdempotencyError, d as MismatchError, b as MissingKeyError, R as RunOptions, h as RunResult, S as StorageAdapter, e as StorageError } from './errors-BUehgS6t.cjs';
+
+/**
+ * Mock storage for testing.
+ * Same as MemoryStorage but with additional test utilities.
+ */
+declare class MockStorage extends MemoryStorage {
+    /** Track all operations for assertions */
+    readonly operations: Array<{
+        type: string;
+        key: string;
+        timestamp: number;
+    }>;
+    /** Simulated conflict keys */
+    private simulatedConflicts;
+    /** Simulated mismatch keys */
+    private simulatedMismatches;
+    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>;
+    /**
+     * Get operations for a specific key.
+     */
+    getOperationsForKey(key: string): {
+        type: string;
+        key: string;
+        timestamp: number;
+    }[];
+    /**
+     * Assert that a key was acquired.
+     */
+    assertAcquired(key: string): void;
+    /**
+     * Assert that a key was saved (cached).
+     */
+    assertCached(key: string): void;
+    /**
+     * Assert that a key was NOT saved (not cached).
+     */
+    assertNotCached(key: string): void;
+    /**
+     * Assert that a key was released.
+     */
+    assertReleased(key: string): void;
+    /**
+     * Simulate a conflict error for a specific key.
+     * The next acquire for this key will return conflict status.
+     */
+    simulateConflict(key: string): void;
+    /**
+     * Simulate a mismatch error for a specific key.
+     * The next acquire for this key will return mismatch status.
+     */
+    simulateMismatch(key: string, existingHash?: string, providedHash?: string): void;
+    /**
+     * Clear all simulations.
+     */
+    clearSimulations(): void;
+}
+/**
+ * Create an oncely instance configured for testing.
+ *
+ * @example
+ * ```typescript
+ * import { createTestInstance, MockStorage } from '@oncely/core/testing';
+ *
+ * describe('my api', () => {
+ *   const storage = new MockStorage();
+ *   const idempotency = createTestInstance({ storage });
+ *
+ *   beforeEach(() => storage.clear());
+ *
+ *   it('handles duplicate requests', async () => {
+ *     const handler = vi.fn().mockResolvedValue({ id: 1 });
+ *
+ *     await idempotency.run({ key: 'test', handler });
+ *     await idempotency.run({ key: 'test', handler });
+ *
+ *     expect(handler).toHaveBeenCalledTimes(1);
+ *     storage.assertCached('test');
+ *   });
+ * });
+ * ```
+ */
+declare function createTestInstance(options?: Partial<OncelyOptions>): Oncely;
+/**
+ * @deprecated Use createTestInstance instead.
+ */
+declare const createTestOncely: typeof createTestInstance;
+/**
+ * Set up oncely for testing with auto-reset between tests.
+ * Returns utilities for testing assertions.
+ *
+ * @example
+ * ```typescript
+ * import { setupTest } from '@oncely/core/testing';
+ *
+ * describe('my api', () => {
+ *   const { storage, instance, reset } = setupTest();
+ *
+ *   beforeEach(() => reset());
+ *
+ *   it('caches responses', async () => {
+ *     await instance.run({ key: 'test', handler: () => ({ ok: true }) });
+ *     storage.assertCached('test');
+ *   });
+ * });
+ * ```
+ */
+declare function setupTest(config?: OncelyConfig): {
+    storage: MockStorage;
+    instance: Oncely;
+    reset: () => void;
+};
+
+export { AcquireResult, MockStorage, OncelyConfig, OncelyOptions, StoredResponse, createTestInstance, createTestOncely, setupTest };

package/dist/testing.d.ts

@@ -0,0 +1,119 @@
+import { M as MemoryStorage, A as AcquireResult, f as StoredResponse, g as OncelyOptions, a as Oncely, O as OncelyConfig } from './errors-BUehgS6t.js';
+export { C as ConflictError, I as IdempotencyError, d as MismatchError, b as MissingKeyError, R as RunOptions, h as RunResult, S as StorageAdapter, e as StorageError } from './errors-BUehgS6t.js';
+
+/**
+ * Mock storage for testing.
+ * Same as MemoryStorage but with additional test utilities.
+ */
+declare class MockStorage extends MemoryStorage {
+    /** Track all operations for assertions */
+    readonly operations: Array<{
+        type: string;
+        key: string;
+        timestamp: number;
+    }>;
+    /** Simulated conflict keys */
+    private simulatedConflicts;
+    /** Simulated mismatch keys */
+    private simulatedMismatches;
+    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>;
+    /**
+     * Get operations for a specific key.
+     */
+    getOperationsForKey(key: string): {
+        type: string;
+        key: string;
+        timestamp: number;
+    }[];
+    /**
+     * Assert that a key was acquired.
+     */
+    assertAcquired(key: string): void;
+    /**
+     * Assert that a key was saved (cached).
+     */
+    assertCached(key: string): void;
+    /**
+     * Assert that a key was NOT saved (not cached).
+     */
+    assertNotCached(key: string): void;
+    /**
+     * Assert that a key was released.
+     */
+    assertReleased(key: string): void;
+    /**
+     * Simulate a conflict error for a specific key.
+     * The next acquire for this key will return conflict status.
+     */
+    simulateConflict(key: string): void;
+    /**
+     * Simulate a mismatch error for a specific key.
+     * The next acquire for this key will return mismatch status.
+     */
+    simulateMismatch(key: string, existingHash?: string, providedHash?: string): void;
+    /**
+     * Clear all simulations.
+     */
+    clearSimulations(): void;
+}
+/**
+ * Create an oncely instance configured for testing.
+ *
+ * @example
+ * ```typescript
+ * import { createTestInstance, MockStorage } from '@oncely/core/testing';
+ *
+ * describe('my api', () => {
+ *   const storage = new MockStorage();
+ *   const idempotency = createTestInstance({ storage });
+ *
+ *   beforeEach(() => storage.clear());
+ *
+ *   it('handles duplicate requests', async () => {
+ *     const handler = vi.fn().mockResolvedValue({ id: 1 });
+ *
+ *     await idempotency.run({ key: 'test', handler });
+ *     await idempotency.run({ key: 'test', handler });
+ *
+ *     expect(handler).toHaveBeenCalledTimes(1);
+ *     storage.assertCached('test');
+ *   });
+ * });
+ * ```
+ */
+declare function createTestInstance(options?: Partial<OncelyOptions>): Oncely;
+/**
+ * @deprecated Use createTestInstance instead.
+ */
+declare const createTestOncely: typeof createTestInstance;
+/**
+ * Set up oncely for testing with auto-reset between tests.
+ * Returns utilities for testing assertions.
+ *
+ * @example
+ * ```typescript
+ * import { setupTest } from '@oncely/core/testing';
+ *
+ * describe('my api', () => {
+ *   const { storage, instance, reset } = setupTest();
+ *
+ *   beforeEach(() => reset());
+ *
+ *   it('caches responses', async () => {
+ *     await instance.run({ key: 'test', handler: () => ({ ok: true }) });
+ *     storage.assertCached('test');
+ *   });
+ * });
+ * ```
+ */
+declare function setupTest(config?: OncelyConfig): {
+    storage: MockStorage;
+    instance: Oncely;
+    reset: () => void;
+};
+
+export { AcquireResult, MockStorage, OncelyConfig, OncelyOptions, StoredResponse, createTestInstance, createTestOncely, setupTest };