Bun SQL Store

A storage backend for idempotency that supports SQLite, PostgreSQL, and MySQL via Bun's native SQL API.

Installation

bun add @idempot/bun-sql-store

Usage

import { BunSqlIdempotencyStore } from "@idempot/bun-sql-store";

// SQLite (in-memory)
const store = new BunSqlIdempotencyStore("sqlite://:memory:");
// or: new BunSqlIdempotencyStore(":memory:");

// PostgreSQL
const pgStore = new BunSqlIdempotencyStore(
  "postgres://user:pass@localhost:5432/db"
);

// MySQL
const mysqlStore = new BunSqlIdempotencyStore(
  "mysql://user:pass@localhost:3306/db"
);

Connection String Formats

| Database | Examples | | ---------- | -------------------------------------------------------------------- | | SQLite | :memory:, sqlite://:memory:, sqlite://app.db, file://data.db | | PostgreSQL | postgres://user:pass@localhost:5432/db | | MySQL | mysql://user:pass@localhost:3306/db, mysql2://... |

API

new BunSqlIdempotencyStore(connectionString, options?)

Creates a new store instance.

• connectionString: Database connection string or path (default: sqlite://idempotency.db)
• options.lazy: Don't create connection until first query (default: false)

store.lookup(key, fingerprint)

Look up an idempotency record by key and fingerprint. Returns {byKey, byFingerprint}.

store.startProcessing(key, fingerprint, ttlMs)

Mark a request as being processed. Creates a new record with status 'processing'.

store.complete(key, response)

Mark a request as complete with its response data. Updates the record with status 'complete'.

store.close()

Close the database connection. Call this on shutdown.

Example with Hono

import { Hono } from "hono";
import { idempotency } from "@idempot/hono";
import { BunSqlIdempotencyStore } from "@idempot/bun-sql-store";

const app = new Hono();
const store = new BunSqlIdempotencyStore("sqlite://:memory:");

app.post("/orders", idempotency({ store }), async (c) => {
  const body = await c.req.json();
  return c.json({ id: crypto.randomUUID(), ...body }, 201);
});

export default {
  port: 3000,
  fetch: app.fetch
};

Requirements

• Bun runtime (uses bun:sqlite and bun package for SQL)

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 { BunSqlIdempotencyStore } from "@idempot/bun-sql-store";

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