@oncely/core 0.2.1 → 0.2.2

package/README.md

@@ -1,6 +1,8 @@
 # @oncely/core
 
-Core idempotency library with memory storage adapter. Provides the lean kernel with full TypeScript support.
+Core idempotency library with memory storage. The foundation for all oncely packages.
+
+[![npm version](https://img.shields.io/npm/v/@oncely/core.svg)](https://www.npmjs.com/package/@oncely/core)
 
 ## Installation
 
@@ -11,650 +13,133 @@ npm install @oncely/core
 ## Quick Start
 
 ```typescript
-import { oncely, MemoryStorage } from '@oncely/core';
-
-// Configure globally
-oncely.configure({ ttl: '1h' });
-
-// Create an instance
-const idempotency = oncely.createInstance({
-  storage: new MemoryStorage(),
-});
-
-// Run with idempotency
-const result = await idempotency.run({
-  key: 'unique-request-id',
-  handler: async () => {
-    return await createOrder({ amount: 100 });
-  },
-});
+import { MemoryStorage, hashObject, parseTtl } from '@oncely/core';
 
-console.log(result.data); // { id: 'ord_123' }
-console.log(result.cached); // false (first request)
-console.log(result.createdAt); // 1704888000000
-```
-
-## API Reference
-
-### `oncely` Namespace
-
-Global namespace for configuration and instance creation.
-
-```typescript
-// Configure global defaults
-oncely.configure({
-  storage: new MemoryStorage(),
-  ttl: '24h',
-  debug: false,
-});
-
-// Get current configuration
-const config = oncely.getConfig();
-
-// Reset configuration
-oncely.resetConfig();
-
-// Get default storage
-const storage = oncely.getDefaultStorage();
-
-// Create instance with merged config
-const instance = oncely.createInstance({
-  ttl: '1h', // Override global ttl
-});
-
-// Constants
-oncely.HEADER; // 'Idempotency-Key'
-oncely.HEADER_REPLAY; // 'Idempotency-Replay'
-```
+const storage = new MemoryStorage();
 
-### `idempotency.run(options)`
+// Acquire a lock for a request
+const result = await storage.acquire('request-key', hashObject(body), parseTtl('1h'));
 
-Execute a handler with idempotency protection.
+if (result.status === 'acquired') {
+  // Execute the operation
+  const response = await processRequest(body);
 
-```typescript
-interface RunOptions<T = any> {
-  key: string; // Idempotency key (required)
-  hash?: string; // Request hash for mismatch detection
-  handler: () => Promise<T>; // Async function to execute
-  ttl?: number | string; // Override global TTL
+  // Save the response
+  await storage.save('request-key', {
+    data: response,
+    createdAt: Date.now(),
+    hash: hashObject(body),
+  });
 }
 
-interface RunResult<T = any> {
-  data: T; // Handler return value
-  cached: boolean; // Was this a cache hit?
-  status: 'created' | 'hit'; // Result status
-  createdAt: number; // Timestamp of original request
+if (result.status === 'hit') {
+  // Return cached response
+  return result.response.data;
 }
-
-const result = await idempotency.run({
-  key: 'order-123',
-  hash: hashObject(req.body),
-  handler: async () => {
-    const order = await createOrder(req.body);
-    return order;
-  },
-  ttl: '2h',
-});
 ```
 
-## Configuration
-
-### Global Configuration
+## Storage Adapter
 
-```typescript
-oncely.configure({
-  // Storage adapter (required)
-  storage: new MemoryStorage(),
-
-  // Time-to-live for cached responses
-  // Accepts: milliseconds (number) or string ('1h', '30m', '5s')
-  ttl: '24h',
-
-  // Enable debug logging
-  debug: false,
-
-  // Callbacks
-  onHit: (key, response) => {
-    console.log(`Cache hit for key: ${key}`);
-  },
-  onMiss: (key) => {
-    console.log(`Cache miss for key: ${key}`);
-  },
-  onConflict: (key, error) => {
-    console.log(`Conflict for key: ${key}`);
-  },
-});
-```
+`MemoryStorage` is the default adapter, ideal for:
 
-### Per-Instance Configuration
+- Development and testing
+- Single-instance deployments
+- Prototyping
 
-```typescript
-const instance = oncely.createInstance({
-  storage: redis(),
-  ttl: '1h',
-  onHit: (key) => analytics.track('cache_hit', { key }),
-});
-```
+For production multi-instance deployments, use:
 
-## Error Handling
+- [@oncely/redis](https://www.npmjs.com/package/@oncely/redis) - Standard Redis
+- [@oncely/upstash](https://www.npmjs.com/package/@oncely/upstash) - Serverless Redis
 
-All errors are instances of `IdempotencyError` and include a `statusCode`.
+### StorageAdapter Interface
 
 ```typescript
-import {
-  IdempotencyError,
-  MissingKeyError,
-  ConflictError,
-  MismatchError,
-  StorageError,
-} from '@oncely/core';
-
-try {
-  const result = await idempotency.run({ key, handler });
-} catch (error) {
-  if (error instanceof MissingKeyError) {
-    // status: 400
-    // Idempotency key is required but not provided
-    return new Response('Idempotency-Key header required', { status: 400 });
-  }
-
-  if (error instanceof ConflictError) {
-    // status: 409
-    // Request with this key is already in progress
-    return new Response('Request in progress', {
-      status: 409,
-      headers: { 'Retry-After': String(error.retryAfter ?? 30) },
-    });
-  }
-
-  if (error instanceof MismatchError) {
-    // status: 422
-    // Same key used with different request body
-    return new Response('Idempotency key mismatch', {
-      status: 422,
-      headers: {
-        'Content-Type': 'application/problem+json',
-      },
-      body: JSON.stringify({
-        type: 'https://oncely.dev/errors/mismatch',
-        title: 'Idempotency Key Mismatch',
-        detail: `Key was previously used with different request body`,
-        existingHash: error.existingHash,
-        providedHash: error.providedHash,
-      }),
-    });
-  }
-
-  if (error instanceof StorageError) {
-    // status: 500
-    // Storage adapter failed
-    console.error('Storage error:', error);
-    return new Response('Storage error', { status: 500 });
-  }
-
-  // Other errors
-  throw error;
+interface StorageAdapter {
+  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>;
 }
+
+type AcquireResult =
+  | { status: 'acquired' }
+  | { status: 'hit'; response: StoredResponse }
+  | { status: 'conflict'; startedAt: number }
+  | { status: 'mismatch'; existingHash: string; providedHash: string };
 ```
 
 ## Utilities
 
-### Key Generation
-
-```typescript
-import { generateKey, composeKey } from '@oncely/core';
-
-// Generate UUID-based key
-const key = generateKey();
-// => '550e8400-e29b-41d4-a716-446655440000'
-
-// Compose keys from parts
-const key = composeKey('order', orderId, 'attempt', attemptNumber);
-// => 'order:123:attempt:1'
-```
-
-### Hashing
+### Hash Objects
 
 ```typescript
 import { hashObject } from '@oncely/core';
 
-// Hash request body for mismatch detection
-const hash = hashObject(req.body);
-// => 'f8e9b4a2c1d5e3f6...'
-
-// Works with any serializable object
-const hash = hashObject({
-  amount: 100,
-  currency: 'USD',
-  items: [{ id: 1, qty: 2 }],
-});
+const hash = hashObject({ amount: 100, currency: 'USD' });
+// => 'a1b2c3d4...'
 ```
 
-### TTL Parsing
+### Parse TTL
 
 ```typescript
 import { parseTtl } from '@oncely/core';
 
-parseTtl(3600000); // 3600000 (milliseconds)
 parseTtl('1h'); // 3600000
 parseTtl('30m'); // 1800000
 parseTtl('5s'); // 5000
 parseTtl('1d'); // 86400000
-
-// Invalid values throw Error
-parseTtl('invalid'); // throws
+parseTtl(60000); // 60000
 ```
 
-## Storage Adapters
-
-### Memory (Built-in, Default)
-
-In-memory storage for development and testing.
+## Error Classes
 
 ```typescript
-import { oncely, MemoryStorage } from '@oncely/core';
-
-// Implicit (default)
-const idempotency = oncely.createInstance();
-
-// Explicit
-const storage = new MemoryStorage();
-const idempotency = oncely.createInstance({ storage });
-
-// Shared singleton
-import { memory } from '@oncely/core';
-const idempotency = oncely.createInstance({ storage: memory });
-```
-
-**Pros:**
-
-- Zero configuration
-- Fast (no I/O)
-- Easy to test
-
-**Cons:**
-
-- Data lost on restart
-- Not shared between processes
-- Only suitable for single-instance apps
-
-### Redis (Production)
-
-For production deployments with ioredis.
-
-```bash
-npm install @oncely/redis ioredis
-```
-
-```typescript
-import { redis } from '@oncely/redis';
-
-// From environment variable (ONCELY_REDIS_URL)
-const storage = redis();
-
-// From explicit URL
-const storage = redis('redis://localhost:6379');
-
-// With options
-const storage = redis('redis://localhost:6379', {
-  keyPrefix: 'oncely:',
-});
-
-// From existing client
-import Redis from 'ioredis';
-const client = new Redis(process.env.REDIS_URL);
-const storage = new RedisStorage(client, { keyPrefix: 'oncely:' });
-```
-
-See [@oncely/redis](../redis) for full documentation.
-
-### Upstash (Serverless)
-
-For serverless and edge deployments.
-
-```bash
-npm install @oncely/upstash
-```
-
-```typescript
-import { upstash } from '@oncely/upstash';
-
-// From environment variables
-const storage = upstash();
-
-// With explicit config
-const storage = upstash({
-  url: process.env.UPSTASH_REDIS_REST_URL,
-  token: process.env.UPSTASH_REDIS_REST_TOKEN,
-});
-```
-
-See [@oncely/upstash](../upstash) for full documentation.
-
-### Custom Adapters
-
-Implement the `StorageAdapter` interface for custom backends.
-
-```typescript
-import type { StorageAdapter, AcquireResult, StoredResponse } from '@oncely/core';
-
-export class DatabaseStorage implements StorageAdapter {
-  async acquire(key: string, hash: string | null, ttl: number): Promise<AcquireResult> {
-    // Acquire lock and check for existing response
-    // Return { status: 'acquired', startedAt: Date.now() }
-    // Or { status: 'conflict', startedAt, retryAfter }
-    // Or { status: 'mismatch', existingHash, providedHash }
-  }
-
-  async save(key: string, response: StoredResponse): Promise<void> {
-    // Save response and release lock
-  }
-
-  async release(key: string): Promise<void> {
-    // Release lock without saving
-  }
-
-  async delete(key: string): Promise<void> {
-    // Optional: delete stored response
-  }
-
-  async clear(): Promise<void> {
-    // Optional: clear all stored responses
-  }
-}
-
-// Usage
-const storage = new DatabaseStorage();
-const idempotency = oncely.createInstance({ storage });
-```
-
-## Testing
-
-The library includes testing utilities via `@oncely/core/testing`.
-
-```typescript
-import { MockStorage, createTestInstance } from '@oncely/core/testing';
-
-// Use MockStorage to track operations
-const storage = new MockStorage();
-const idempotency = createTestInstance({ storage });
-
-// Run handler
-await idempotency.run({
-  key: 'test-key',
-  handler: async () => ({ id: 1 }),
-});
-
-// Verify operations
-const operations = storage.operations;
-// [
-//   { type: 'acquire', key: 'test-key', timestamp: ... },
-//   { type: 'save', key: 'test-key', timestamp: ... },
-// ]
-
-const saveOps = storage.getOperationsForKey('test-key', 'save');
-expect(saveOps).toHaveLength(1);
-```
-
-## Callbacks
-
-Hooks for monitoring and logging.
-
-```typescript
-oncely.configure({
-  onHit: (key, response) => {
-    console.log(`Cache hit: ${key}`);
-    analytics.track('idempotency_hit', { key });
-  },
-
-  onMiss: (key) => {
-    console.log(`Cache miss: ${key}`);
-    analytics.track('idempotency_miss', { key });
-  },
-
-  onConflict: (key, error) => {
-    console.log(`Conflict: ${key}`);
-    metrics.increment('idempotency_conflicts');
-  },
-});
-```
-
-## Type Definitions
-
-Full TypeScript support with strict typing.
-
-```typescript
-interface Oncely {
-  configure(options: OncelyConfig): void;
-  getConfig(): OncelyConfig;
-  resetConfig(): void;
-  getDefaultStorage(): StorageAdapter;
-  createInstance(options?: Partial<OncelyOptions>): OncelyInstance;
-  HEADER: string;
-  HEADER_REPLAY: string;
-}
-
-interface OncelyOptions {
-  storage: StorageAdapter;
-  ttl: number | string;
-  debug: boolean;
-  onHit?: (key: string, response: StoredResponse) => void;
-  onMiss?: (key: string) => void;
-  onConflict?: (key: string, error: ConflictError) => void;
-}
-
-interface OncelyInstance {
-  run<T>(options: RunOptions<T>): Promise<RunResult<T>>;
-}
-```
-
-## Performance
-
-- Small bundle: ~11 KB (ESM)
-- No external dependencies
-- Tree-shakeable exports
-- Efficient hashing (SHA256)
-- Minimal memory overhead
-
-## FAQ
-
-**Q: Should I use memory storage in production?**  
-A: Only for single-instance deployments. Use Redis or Upstash for distributed systems.
-
-**Q: How do I generate idempotency keys on the client?**  
-A: See [@oncely/client](../client) package.
-
-**Q: Can I customize error responses?**  
-A: Yes, catch errors and format responses as needed. Framework packages (Express, Next.js) handle this automatically.
-
-**Q: How do I migrate from another idempotency library?**  
-A: See [migration guide](../../README.md#migration-guide) in root README.
-
-## License
-
-MIT © stacks0x
-
-```typescript
-import { fromEnv } from 'oncely';
-
-// Read REDIS_URL or UPSTASH_REDIS_REST_URL + TOKEN
-const storage = fromEnv();
-
-// With options
-const storage = fromEnv({
-  preferUpstash: true, // Prefer Upstash when both configured
-  env: {
-    redisUrl: 'MY_REDIS_URL', // Custom env var names
-    upstashUrl: 'MY_UPSTASH_URL',
-    upstashToken: 'MY_UPSTASH_TOKEN',
-  },
-});
-```
-
-### `redis(url, options?)`
-
-Quick helper to create Redis storage from a URL.
-
-```typescript
-import { redis } from 'oncely';
-
-const storage = redis('redis://localhost:6379');
-const storage = redis(process.env.REDIS_URL!, { keyPrefix: 'myapp:' });
-```
-
-### `idempotency.run(options)`
-
-Run an operation with idempotency protection.
-
-```typescript
-const result = await idempotency.run({
-  key: 'unique-key', // Required: idempotency key
-  hash: 'request-hash', // Optional: for mismatch detection
-  handler: async () => {
-    // Required: your operation
-    return { id: 1 };
-  },
-});
-
-// result.data     - your handler's return value
-// result.cached   - boolean, was this a cache hit?
-// result.status   - 'created' | 'hit'
-// result.createdAt - when the response was created
-```
-
-## Errors
-
-All errors extend `IdempotencyError` and include a `statusCode` property.
-
-| Error             | Status | When                         |
-| ----------------- | ------ | ---------------------------- |
-| `MissingKeyError` | 400    | Key is undefined/null        |
-| `ConflictError`   | 409    | Same key already in progress |
-| `MismatchError`   | 422    | Same key, different hash     |
-| `StorageError`    | 500    | Storage adapter failed       |
-
-```typescript
-import { IdempotencyError, ConflictError } from 'oncely';
-
-try {
-  await idempotency.run({ key, handler });
-} catch (err) {
-  if (err instanceof ConflictError) {
-    // Return 409 with Retry-After header
-    return new Response('Request in progress', {
-      status: 409,
-      headers: { 'Retry-After': String(err.retryAfter) },
-    });
-  }
-}
-```
-
-## Utilities
-
-```typescript
-import { generateKey, composeKey, hashObject } from 'oncely';
-
-// Generate a UUID-like key
-const key = generateKey(); // "f47ac10b-58cc-4372-a567-0e02b2c3d479"
-
-// Compose a deterministic key
-const key = composeKey('user', userId, 'order', orderId); // "user:123:order:456"
-
-// Hash an object for fingerprinting
-const hash = hashObject({ amount: 100, currency: 'usd' });
-```
-
-## Storage Adapters
-
-### Memory (Built-in, Default)
-
-For development and testing. Used automatically when no storage is configured:
-
-```typescript
-import { oncely, memory, MemoryStorage } from 'oncely';
-
-// Zero-config — uses shared memory
-const idempotency = oncely();
-
-// Explicit memory storage
-const idempotency = oncely({ storage: memory });
-
-// Custom instance
-const myStorage = new MemoryStorage();
-const idempotency = oncely({ storage: myStorage });
+import {
+  IdempotencyError,
+  MissingKeyError, // 400 - Key required but missing
+  ConflictError, // 409 - Request in progress
+  MismatchError, // 422 - Key reused with different body
+} from '@oncely/core';
 ```
 
-### Redis with ioredis
+All errors extend `IdempotencyError` and include:
 
-For production with self-hosted Redis or managed services:
+- `statusCode` - HTTP status code
+- `toProblemDetails()` - RFC 7807 Problem Details
 
-```bash
-npm install ioredis
-```
+## Constants
 
 ```typescript
-import { oncely, redis, ioredis } from 'oncely';
-import Redis from 'ioredis';
+import { IDEMPOTENCY_KEY_HEADER, IDEMPOTENCY_REPLAY_HEADER } from '@oncely/core';
 
-// Quick setup from URL
-const idempotency = oncely({
-  storage: redis('redis://localhost:6379'),
-});
-
-// With existing client
-const client = new Redis(process.env.REDIS_URL);
-const idempotency = oncely({
-  storage: ioredis(client, { keyPrefix: 'idempotent:' }),
-});
+IDEMPOTENCY_KEY_HEADER; // 'Idempotency-Key'
+IDEMPOTENCY_REPLAY_HEADER; // 'Idempotency-Replay'
 ```
 
-### Upstash / Vercel KV
-
-For serverless environments:
-
-```bash
-npm install @upstash/redis
-```
+## Testing Utilities
 
 ```typescript
-import { oncely, upstash } from 'oncely';
-import { Redis } from '@upstash/redis';
+import { createTestStorage, MockStorage } from '@oncely/core/testing';
 
-const redis = new Redis({
-  url: process.env.UPSTASH_REDIS_REST_URL!,
-  token: process.env.UPSTASH_REDIS_REST_TOKEN!,
+// Create a test storage with optional pre-seeded data
+const storage = createTestStorage({
+  'existing-key': { data: { id: 1 }, createdAt: Date.now(), hash: null },
 });
 
-const idempotency = oncely({
-  storage: upstash(redis, { keyPrefix: 'idempotent:' }),
-});
+// Or use MockStorage for fine-grained control
+const mock = new MockStorage();
+mock.simulateConflict('key');
+mock.simulateError(new Error('Connection failed'));
 ```
 
-### Custom Adapters
-
-Implement the `StorageAdapter` interface:
+## Related Packages
 
-```typescript
-import type { StorageAdapter } from 'oncely';
-
-const myAdapter: StorageAdapter = {
-  async acquire(key, hash, ttl) {
-    // Try to acquire lock, return { acquired: true/false, response?: cached }
-  },
-  async save(key, response) {
-    // Save response, release lock
-  },
-  async release(key) {
-    // Release lock without saving
-  },
-  async delete(key) {
-    // Delete stored response (optional)
-  },
-  async clear() {
-    // Clear all stored responses (optional)
-  },
-};
-```
+- [@oncely/express](https://www.npmjs.com/package/@oncely/express) - Express middleware
+- [@oncely/next](https://www.npmjs.com/package/@oncely/next) - Next.js integration
+- [@oncely/client](https://www.npmjs.com/package/@oncely/client) - Client utilities
+- [@oncely/redis](https://www.npmjs.com/package/@oncely/redis) - Redis adapter
+- [@oncely/upstash](https://www.npmjs.com/package/@oncely/upstash) - Upstash adapter
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oncely/core",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Idempotency engine for HTTP APIs - ensures operations execute exactly once",
   "author": "stacks0x",
   "license": "MIT",
@@ -48,7 +48,7 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "scripts": {
     "build": "tsup",