@oncely/client

@oncely/client

Client-side utilities for generating idempotency keys.

Installation

npm install @oncely/client

Usage

import { store, generateKey, randomKey, compositeKey } from '@oncely/client';

// Generate a UUID-based key const key = generateKey(); // "550e8400-e29b-41d4-a716-446655440000"

// Generate a random alphanumeric key const key = randomKey(); // "x7k9m2n4p1" const key = randomKey(32); // longer key

// Create composite keys const key = compositeKey('order', orderId, 'attempt', 1); // "order:123:attempt:1"

// Store and retrieve keys (in-memory) store.set('current-order', key); const stored = store.get('current-order'); store.delete('current-order'); store.clear();

License

MIT // Response headers include: Idempotency-Replay: true }

// Check if response indicates a conflict (409) if (oncely.isConflict(response)) { // Request with this key is already in progress const retryAfter = oncely.getRetryAfter(response); await delay(retryAfter * 1000); // Retry... }

// Check if response indicates a mismatch (422) if (oncely.isMismatch(response)) { // Key was reused with different request body // Generate a new key and retry }

// Parse RFC 7807 problem details from error response const problem = await oncely.getProblem(response); // => { type: "https://oncely.dev/errors/conflict", title: "Request in progress", ... }

### Constants

```typescript
import { oncely } from '@oncely/client';

// Standard header name (IETF draft)
oncely.HEADER; // => "Idempotency-Key"

// Replay indicator header
oncely.HEADER_REPLAY; // => "Idempotency-Replay"

Usage with Fetch Wrappers

With ky

import ky from 'ky';
import { oncely } from '@oncely/client';

const api = ky.extend({
  hooks: {
    beforeRequest: [
      (request) => {
        if (['POST', 'PUT', 'PATCH'].includes(request.method)) {
          request.headers.set(oncely.HEADER, oncely.key());
        }
      },
    ],
  },
});

With axios

import axios from 'axios';
import { oncely } from '@oncely/client';

const api = axios.create();

api.interceptors.request.use((config) => {
  if (['post', 'put', 'patch'].includes(config.method?.toLowerCase() ?? '')) {
    config.headers[oncely.HEADER] = oncely.key();
  }
  return config;
});

TypeScript

Full TypeScript support with exported types:

import type { ProblemDetails } from '@oncely/client';

const problem: ProblemDetails = await oncely.getProblem(response);

Browser Support

Works in all modern browsers. For older browsers, ensure you have:

• crypto.randomUUID() polyfill (or use custom key generator)
• localStorage / sessionStorage (for key store)

Related Packages

• @oncely/core - Core idempotency engine for servers
• @oncely/redis - Redis storage adapter
• @oncely/upstash - Upstash Redis adapter
• @oncely/express - Express.js middleware
• @oncely/next - Next.js API route handlers

License

MIT