@idempot/fastify-middleware

Fastify middleware for idempotency.

Installation

npm install @idempot/fastify-middleware @idempot/sqlite-store

Usage

import Fastify from "fastify";
import { idempotency } from "@idempot/fastify-middleware";
import { SqliteIdempotencyStore } from "@idempot/sqlite-store";

const fastify = Fastify();
const store = new SqliteIdempotencyStore({ path: ":memory:" });

fastify.post(
  "/orders",
  { preHandler: idempotency({ store }) },
  async (request, reply) => {
    const orderId = crypto.randomUUID();
    return { id: orderId, ...request.body };
  }
);

fastify.listen({ port: 3000 });

API

idempotency(options)

Creates Fastify preHandler hook for idempotency.

Options:

• store (required): Storage backend implementing IdempotencyStore
• headerName: Header name for idempotency key (default: "Idempotency-Key")
• required: Whether idempotency key is required (default: false)
• ttlMs: Time-to-live for idempotency records in milliseconds
• excludeFields: Fields to exclude from fingerprint calculation
• resilience: Circuit breaker and retry options

Returns: Fastify preHandler hook function with circuit property for monitoring.

TypeScript Support

This library uses JavaScript with JSDoc comments for type information. Enable allowJs in your TypeScript configuration to use these types directly—no separate .d.ts files needed.

To use this library in a TypeScript project:

1. Add these settings to your tsconfig.json:

   {
     "allowJs": true,
     "checkJs": true
   }

2. Import the library as you normally would:

   import { idempotency } from "@idempot/fastify-middleware";

3. JSDoc comments provide full type safety: parameter types, return types, and detailed documentation in your IDE.

This approach simplifies maintenance while giving TypeScript users an excellent developer experience.

License

BSD-3-Clause