@idempotix/next

@idempotix/next

Next.js integration for HTTP idempotency. Supports App Router and Pages Router.

Installation

npm install @idempotix/core @idempotix/next

App Router

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

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

Pages Router

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

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

Configuration

Both next() and pages() accept the same options:

export const POST = next({
  storage: upstash(), // Storage adapter
  ttl: '1h', // Cache duration
  required: true, // Require Idempotency-Key header
  failOpen: true, // Continue if storage fails
  getKey: (req) => req.headers.get('x-request-id'), // Custom key extraction
  getHash: async (req) => hashObject(await req.json()), // Custom hash
  onHit: (key, response) => {}, // Cache hit callback
  onMiss: (key) => {}, // Cache miss callback
  onError: (key, error) => {}, // Error callback
})(handler);

Pre-configured Factory

Share configuration across routes:

// lib/idempotency.ts
import { configure } from '@idempotix/next';
import { upstash } from '@idempotix/upstash';

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

// app/api/orders/route.ts
import { idempotent } from '@/lib/idempotency';

export const POST = idempotent()(handler);

Pages Router has its own configure:

// lib/idempotency.ts
import { configure } from '@idempotix/next/pages';

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

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

export default idempotent()(handler);

Headers

Header	Direction	Description
Idempotency-Key	Request	Client-provided unique key
Idempotency-Key	Response	Echo of the key used
Idempotency-Replay	Response	true when returning cached response

Error Responses

All errors follow RFC 7807 Problem Details:

Status	Type	Cause
400	key-required	Missing key when required: true
409	conflict	Request with same key in progress
422	mismatch	Same key reused with different body

With Upstash (Serverless)

import { upstash } from '@idempotix/upstash';

export const POST = next({ storage: upstash() })(handler);

License

MIT