@oncely/next

@oncely/next

Next.js integration for oncely idempotency.

Installation

npm install @oncely/core @oncely/next

App Router

// app/api/orders/route.ts import { next } from '@oncely/next';

export const POST = next()(async (req) => { const body = await req.json(); return Response.json(await createOrder(body), { status: 201 }); });

// With options export const POST = next({ required: true, ttl: '1h', })(handler);

Pages Router

// pages/api/orders.ts import { pages } from '@oncely/next/pages';

export default pages()(async (req, res) => { res.status(201).json(await createOrder(req.body)); });

Pre-configured Factory

import { configure } from '@oncely/next'; import { upstash } from '@oncely/upstash';

export const idempotent = configure({ storage: upstash(), ttl: '1h', });

// Usage export const POST = idempotent()(handler);

Headers

Request: Idempotency-Key Response: Idempotency-Key, Idempotency-Replay (on cache hit)

License

MIT }

  const result = await idempotency.run({
    key,
    hash: hashObject(body),
    handler: () => handler(req, ctx, body),
  });

  return result.data;
}

return handler(req, ctx, body);

}; }

## Pages Router

```typescript
// pages/api/orders.ts
import { oncely } from "oncely-next/pages";
import { memory } from "oncely";

export default oncely(
  async (req, res) => {
    const order = await createOrder(req.body);
    res.status(201).json(order);
  },
  { storage: memory },
);

Shared Configuration (Pages)

// lib/idempotency.ts
import { configure } from 'oncely-next/pages';
import { ioredis } from 'oncely-redis';

export const oncely = configure({
  storage: ioredis({ client: redis }),
  ttl: '24h',
});

// pages/api/orders.ts
import { oncely } from '@/lib/idempotency';

export default oncely(async (req, res) => {
  const order = await createOrder(req.body);
  res.status(201).json(order);
});

Options

oncely(handler, {
  // Required
  storage: StorageAdapter,

  // Optional
  keyHeader: 'Idempotency-Key', // Header name (default: 'Idempotency-Key')
  required: false, // Require key? (default: false)
  responseHeaders: true, // Add idempotency headers to response
  ttl: '24h', // Key expiration
  debug: false, // Enable debug logging

  // Custom hash function
  hashRequest: async (req) => hashObject(await req.json()),

  // Callbacks
  onHit: (key) => {},
  onMiss: (key) => {},
  onError: (key, err) => {},
});

Response Headers

When responseHeaders is enabled (default), responses include:

Idempotency-Key: <key>
Idempotency-Status: hit | created
Idempotency-Created: <ISO timestamp>  (on cache hit)
Retry-After: <seconds>                 (on 409 conflict)

License

MIT