pg-ratelimit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Max Malm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,39 @@
+# pg-ratelimit
+
+PostgreSQL-backed rate limiting for Node.js. No Redis required.
+
+```typescript
+import { Pool } from "pg";
+import { Ratelimit } from "pg-ratelimit";
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+
+const ratelimit = new Ratelimit({
+  pool,
+  limiter: Ratelimit.slidingWindow(10, "1m"),
+  prefix: "api",
+});
+
+const { success } = await ratelimit.limit("user:123");
+```
+
+## Features
+
+- **Three algorithms** - fixed window, sliding window, token bucket
+- **Zero runtime deps** - just `pg` as a peer dependency
+- **Serverless-safe** - no background processes, probabilistic inline cleanup, no long-lived state
+- **Upstash-compatible API** - same `limit()`, `blockUntilReady()`, `getRemaining()`, `resetUsedTokens()` surface
+
+## Install
+
+```bash
+npm install pg-ratelimit pg
+```
+
+## Docs
+
+[benjick.js.org/pg-ratelimit](https://benjick.js.org/pg-ratelimit)
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,482 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Ratelimit: () => Ratelimit,
+  TABLE_SQL: () => TABLE_SQL
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/duration.ts
+var MULTIPLIERS = {
+  s: 1e3,
+  m: 6e4,
+  h: 36e5,
+  d: 864e5
+};
+var DURATION_RE = /^\s*(\d+)\s*(s|m|h|d)\s*$/;
+function toMs(duration) {
+  if (typeof duration === "number") {
+    if (!Number.isFinite(duration) || duration <= 0) {
+      throw new Error(
+        `Invalid duration: ${duration}. Must be a positive finite number of milliseconds.`
+      );
+    }
+    return duration;
+  }
+  const match = DURATION_RE.exec(duration);
+  if (!match) {
+    throw new Error(
+      `Invalid duration format: "${duration}". Expected format: "<number><unit>" where unit is s, m, h, or d.`
+    );
+  }
+  const value = Number(match[1]);
+  const unit = match[2];
+  if (value <= 0) {
+    throw new Error(`Invalid duration: "${duration}". Value must be positive.`);
+  }
+  return value * MULTIPLIERS[unit];
+}
+
+// src/tables.sql
+var tables_default = "CREATE UNLOGGED TABLE IF NOT EXISTS rate_limit_ephemeral (\n  prefix       TEXT NOT NULL,\n  key          TEXT NOT NULL,\n  count        BIGINT,\n  prev_count   BIGINT,\n  window_start TIMESTAMPTZ,\n  tokens       DOUBLE PRECISION,\n  last_refill  TIMESTAMPTZ,\n  expires_at   TIMESTAMPTZ NOT NULL,\n  PRIMARY KEY (prefix, key)\n);\n\nCREATE INDEX IF NOT EXISTS idx_rate_limit_ephemeral_cleanup\n  ON rate_limit_ephemeral (prefix, expires_at);\n\nCREATE TABLE IF NOT EXISTS rate_limit_durable (\n  prefix       TEXT NOT NULL,\n  key          TEXT NOT NULL,\n  count        BIGINT,\n  prev_count   BIGINT,\n  window_start TIMESTAMPTZ,\n  tokens       DOUBLE PRECISION,\n  last_refill  TIMESTAMPTZ,\n  expires_at   TIMESTAMPTZ NOT NULL,\n  PRIMARY KEY (prefix, key)\n);\n\nCREATE INDEX IF NOT EXISTS idx_rate_limit_durable_cleanup\n  ON rate_limit_durable (prefix, expires_at);\n";
+
+// src/tables.ts
+var TABLE_SQL = tables_default;
+var initialized = /* @__PURE__ */ new WeakSet();
+async function ensureTables(pool) {
+  if (initialized.has(pool)) {
+    return;
+  }
+  if (process.env.PG_RATELIMIT_DISABLE_AUTO_MIGRATE === "true") {
+    initialized.add(pool);
+    return;
+  }
+  await pool.query(TABLE_SQL);
+  initialized.add(pool);
+}
+
+// src/algorithms/fixed-window.ts
+async function fixedWindow(ctx, tokens, windowMs) {
+  const { pool, table, prefix, key, rate, now, debug } = ctx;
+  const windowInterval = `${windowMs} milliseconds`;
+  const sql = `
+    INSERT INTO ${table} (prefix, key, count, window_start, expires_at)
+    VALUES ($1, $2, $3, $4::timestamptz, $4::timestamptz + $5::interval)
+    ON CONFLICT (prefix, key) DO UPDATE
+      SET count = CASE
+        WHEN ${table}.expires_at < $4::timestamptz THEN $3
+        ELSE ${table}.count + $3
+      END,
+      window_start = CASE
+        WHEN ${table}.expires_at < $4::timestamptz THEN $4::timestamptz
+        ELSE ${table}.window_start
+      END,
+      expires_at = CASE
+        WHEN ${table}.expires_at < $4::timestamptz THEN $4::timestamptz + $5::interval
+        ELSE ${table}.expires_at
+      END
+    RETURNING count, expires_at
+  `;
+  const params = [prefix, key, rate, now, windowInterval];
+  if (debug) {
+    console.debug("pg-ratelimit fixed-window:", sql, params);
+  }
+  const result = await pool.query(sql, params);
+  const row = result.rows[0];
+  const count = Number(row.count);
+  return {
+    success: count <= tokens,
+    limit: tokens,
+    remaining: Math.max(0, tokens - count),
+    reset: new Date(row.expires_at).getTime()
+  };
+}
+
+// src/algorithms/sliding-window.ts
+async function slidingWindow(ctx, tokens, windowMs) {
+  const { pool, table, prefix, key, rate, now, debug, synchronousCommit } = ctx;
+  const client = await pool.connect();
+  try {
+    await client.query("BEGIN");
+    if (!synchronousCommit) {
+      await client.query("SET LOCAL synchronous_commit = off");
+    }
+    const doubleWindowInterval = `${2 * windowMs} milliseconds`;
+    const ensureSql = `
+      INSERT INTO ${table} (prefix, key, count, prev_count, window_start, expires_at)
+      VALUES ($1, $2, 0, 0, $3::timestamptz, $3::timestamptz + $4::interval)
+      ON CONFLICT (prefix, key) DO NOTHING
+    `;
+    await client.query(ensureSql, [prefix, key, now, doubleWindowInterval]);
+    const selectSql = `
+      SELECT count, prev_count, window_start, expires_at
+      FROM ${table}
+      WHERE prefix = $1 AND key = $2
+      FOR UPDATE
+    `;
+    if (debug) {
+      console.debug("pg-ratelimit sliding-window SELECT:", selectSql, [prefix, key]);
+    }
+    const existing = await client.query(selectSql, [prefix, key]);
+    const row = existing.rows[0];
+    const oldWindowStart = new Date(row.window_start).getTime();
+    const nowMs = now.getTime();
+    let prevCount;
+    let count;
+    let windowStart;
+    if (oldWindowStart + windowMs > nowMs) {
+      prevCount = Number(row.prev_count) || 0;
+      count = Number(row.count) || 0;
+      windowStart = new Date(row.window_start);
+    } else if (oldWindowStart + 2 * windowMs > nowMs) {
+      prevCount = Number(row.count) || 0;
+      count = 0;
+      windowStart = new Date(oldWindowStart + windowMs);
+    } else {
+      prevCount = 0;
+      count = 0;
+      windowStart = now;
+    }
+    const elapsed = now.getTime() - windowStart.getTime();
+    const weight = 1 - elapsed / windowMs;
+    const effective = prevCount * weight + count + rate;
+    const success = effective <= tokens;
+    if (success) {
+      const newCount = count + rate;
+      const upsertSql = `
+        INSERT INTO ${table} (prefix, key, count, prev_count, window_start, expires_at)
+        VALUES ($1, $2, $3, $4, $5::timestamptz, $5::timestamptz + $6::interval)
+        ON CONFLICT (prefix, key) DO UPDATE
+          SET count = $3,
+              prev_count = $4,
+              window_start = $5::timestamptz,
+              expires_at = $5::timestamptz + $6::interval
+      `;
+      const upsertParams = [prefix, key, newCount, prevCount, windowStart, doubleWindowInterval];
+      if (debug) {
+        console.debug("pg-ratelimit sliding-window UPSERT:", upsertSql, upsertParams);
+      }
+      await client.query(upsertSql, upsertParams);
+    }
+    await client.query("COMMIT");
+    const reset = windowStart.getTime() + windowMs;
+    return {
+      success,
+      limit: tokens,
+      remaining: Math.max(0, tokens - effective),
+      reset
+    };
+  } catch (err) {
+    await client.query("ROLLBACK").catch(() => {
+    });
+    throw err;
+  } finally {
+    client.release();
+  }
+}
+
+// src/algorithms/token-bucket.ts
+async function tokenBucket(ctx, maxTokens, refillRate, intervalMs) {
+  const { pool, table, prefix, key, rate, now, debug, synchronousCommit } = ctx;
+  const client = await pool.connect();
+  const ttlMs = maxTokens / refillRate * intervalMs;
+  try {
+    await client.query("BEGIN");
+    if (!synchronousCommit) {
+      await client.query("SET LOCAL synchronous_commit = off");
+    }
+    const ttlInterval = `${ttlMs} milliseconds`;
+    const ensureSql = `
+      INSERT INTO ${table} (prefix, key, tokens, last_refill, expires_at)
+      VALUES ($1, $2, $3, $4::timestamptz, $4::timestamptz + $5::interval)
+      ON CONFLICT (prefix, key) DO NOTHING
+    `;
+    await client.query(ensureSql, [prefix, key, maxTokens, now, ttlInterval]);
+    const selectSql = `
+      SELECT tokens, last_refill, expires_at
+      FROM ${table}
+      WHERE prefix = $1 AND key = $2
+      FOR UPDATE
+    `;
+    if (debug) {
+      console.debug("pg-ratelimit token-bucket SELECT:", selectSql, [prefix, key]);
+    }
+    const existing = await client.query(selectSql, [prefix, key]);
+    const row = existing.rows[0];
+    const lastRefill = new Date(row.last_refill).getTime();
+    const elapsed = now.getTime() - lastRefill;
+    const refilled = Math.floor(elapsed / intervalMs) * refillRate;
+    const currentTokens = Math.min(Number(row.tokens) + refilled, maxTokens);
+    const newTokens = currentTokens - rate;
+    const success = newTokens >= 0;
+    if (success) {
+      const upsertSql = `
+        INSERT INTO ${table} (prefix, key, tokens, last_refill, expires_at)
+        VALUES ($1, $2, $3, $4::timestamptz, $4::timestamptz + $5::interval)
+        ON CONFLICT (prefix, key) DO UPDATE
+          SET tokens = $3, last_refill = $4::timestamptz, expires_at = $4::timestamptz + $5::interval
+      `;
+      const upsertParams = [prefix, key, newTokens, now, ttlInterval];
+      if (debug) {
+        console.debug("pg-ratelimit token-bucket UPSERT:", upsertSql, upsertParams);
+      }
+      await client.query(upsertSql, upsertParams);
+    }
+    await client.query("COMMIT");
+    let reset;
+    if (success) {
+      reset = now.getTime() + ttlMs;
+    } else {
+      const tokensNeeded = rate - currentTokens;
+      const intervalsNeeded = Math.ceil(tokensNeeded / refillRate);
+      reset = now.getTime() + intervalsNeeded * intervalMs;
+    }
+    return {
+      success,
+      limit: maxTokens,
+      remaining: Math.max(0, success ? newTokens : currentTokens),
+      reset
+    };
+  } catch (err) {
+    await client.query("ROLLBACK").catch(() => {
+    });
+    throw err;
+  } finally {
+    client.release();
+  }
+}
+
+// src/limiter.ts
+var Ratelimit = class {
+  pool;
+  algorithm;
+  prefix;
+  table;
+  debug;
+  clock;
+  durable;
+  synchronousCommit;
+  cleanupProbability;
+  // Pre-parsed durations (only the relevant one is used per algorithm)
+  windowMs;
+  intervalMs;
+  constructor(config) {
+    if (!config.prefix) {
+      throw new Error("prefix must be a non-empty string");
+    }
+    const cleanupProbability = config.cleanupProbability ?? 0.1;
+    if (cleanupProbability < 0 || cleanupProbability > 1) {
+      throw new Error("cleanupProbability must be between 0 and 1");
+    }
+    this.pool = config.pool;
+    this.algorithm = config.limiter;
+    this.prefix = config.prefix;
+    this.debug = config.debug ?? false;
+    this.clock = config.clock ?? (() => /* @__PURE__ */ new Date());
+    this.durable = "durable" in config && config.durable === true;
+    this.table = this.durable ? "rate_limit_durable" : "rate_limit_ephemeral";
+    this.cleanupProbability = cleanupProbability;
+    this.synchronousCommit = !this.durable || "synchronousCommit" in config && config.synchronousCommit === true;
+    if (this.algorithm.type === "fixedWindow" || this.algorithm.type === "slidingWindow") {
+      this.windowMs = toMs(this.algorithm.window);
+      this.intervalMs = 0;
+    } else {
+      this.windowMs = 0;
+      this.intervalMs = toMs(this.algorithm.interval);
+    }
+  }
+  static fixedWindow(tokens, window) {
+    return { type: "fixedWindow", tokens, window };
+  }
+  static slidingWindow(tokens, window) {
+    return { type: "slidingWindow", tokens, window };
+  }
+  static tokenBucket(refillRate, interval, maxTokens) {
+    return { type: "tokenBucket", refillRate, interval, maxTokens };
+  }
+  async limit(key, opts) {
+    const rate = opts?.rate ?? 1;
+    const now = this.clock();
+    await ensureTables(this.pool);
+    const ctx = {
+      pool: this.pool,
+      table: this.table,
+      prefix: this.prefix,
+      key,
+      rate,
+      now,
+      debug: this.debug,
+      synchronousCommit: this.synchronousCommit
+    };
+    let result;
+    switch (this.algorithm.type) {
+      case "fixedWindow":
+        result = await fixedWindow(ctx, this.algorithm.tokens, this.windowMs);
+        break;
+      case "slidingWindow":
+        result = await slidingWindow(ctx, this.algorithm.tokens, this.windowMs);
+        break;
+      case "tokenBucket":
+        result = await tokenBucket(
+          ctx,
+          this.algorithm.maxTokens,
+          this.algorithm.refillRate,
+          this.intervalMs
+        );
+        break;
+    }
+    if (Math.random() < this.cleanupProbability) {
+      void this.pool.query(`DELETE FROM ${this.table} WHERE prefix = $1 AND expires_at < $2`, [
+        this.prefix,
+        now
+      ]).catch(() => {
+      });
+    }
+    return result;
+  }
+  async blockUntilReady(key, timeout, opts) {
+    const timeoutMs = toMs(timeout);
+    const deadline = this.clock().getTime() + timeoutMs;
+    let result = await this.limit(key, opts);
+    if (result.success) {
+      return result;
+    }
+    while (true) {
+      const now = this.clock().getTime();
+      const remaining = deadline - now;
+      if (remaining <= 0) {
+        return result;
+      }
+      const sleepMs = result.reset - now;
+      if (sleepMs > remaining) {
+        return result;
+      }
+      if (sleepMs > 0) {
+        await new Promise((resolve) => setTimeout(resolve, sleepMs));
+      }
+      result = await this.limit(key, opts);
+      if (result.success) {
+        return result;
+      }
+    }
+  }
+  async getRemaining(key) {
+    await ensureTables(this.pool);
+    const now = this.clock();
+    const selectSql = `
+      SELECT count, prev_count, window_start, expires_at, tokens, last_refill
+      FROM ${this.table}
+      WHERE prefix = $1 AND key = $2
+    `;
+    if (this.debug) {
+      console.debug("pg-ratelimit getRemaining:", selectSql, [this.prefix, key]);
+    }
+    const result = await this.pool.query(selectSql, [this.prefix, key]);
+    if (result.rows.length === 0) {
+      switch (this.algorithm.type) {
+        case "fixedWindow":
+          return {
+            remaining: this.algorithm.tokens,
+            reset: now.getTime() + this.windowMs
+          };
+        case "slidingWindow":
+          return {
+            remaining: this.algorithm.tokens,
+            reset: now.getTime() + this.windowMs
+          };
+        case "tokenBucket":
+          return {
+            remaining: this.algorithm.maxTokens,
+            reset: now.getTime() + this.algorithm.maxTokens / this.algorithm.refillRate * this.intervalMs
+          };
+      }
+    }
+    const row = result.rows[0];
+    switch (this.algorithm.type) {
+      case "fixedWindow": {
+        if (new Date(row.expires_at).getTime() < now.getTime()) {
+          return {
+            remaining: this.algorithm.tokens,
+            reset: now.getTime() + this.windowMs
+          };
+        }
+        const count = Number(row.count) || 0;
+        return {
+          remaining: Math.max(0, this.algorithm.tokens - count),
+          reset: new Date(row.expires_at).getTime()
+        };
+      }
+      case "slidingWindow": {
+        const oldWindowStart = new Date(row.window_start).getTime();
+        const nowMs = now.getTime();
+        let prevCount;
+        let count;
+        let windowStart;
+        if (oldWindowStart + this.windowMs > nowMs) {
+          prevCount = Number(row.prev_count) || 0;
+          count = Number(row.count) || 0;
+          windowStart = oldWindowStart;
+        } else if (oldWindowStart + 2 * this.windowMs > nowMs) {
+          prevCount = Number(row.count) || 0;
+          count = 0;
+          windowStart = oldWindowStart + this.windowMs;
+        } else {
+          return {
+            remaining: this.algorithm.tokens,
+            reset: nowMs + this.windowMs
+          };
+        }
+        const elapsed = nowMs - windowStart;
+        const weight = 1 - elapsed / this.windowMs;
+        const effective = prevCount * weight + count;
+        return {
+          remaining: Math.max(0, this.algorithm.tokens - effective),
+          reset: windowStart + this.windowMs
+        };
+      }
+      case "tokenBucket": {
+        const lastRefill = new Date(row.last_refill).getTime();
+        const elapsed = now.getTime() - lastRefill;
+        const refilled = Math.floor(elapsed / this.intervalMs) * this.algorithm.refillRate;
+        const currentTokens = Math.min(Number(row.tokens) + refilled, this.algorithm.maxTokens);
+        const ttlMs = this.algorithm.maxTokens / this.algorithm.refillRate * this.intervalMs;
+        return {
+          remaining: Math.max(0, currentTokens),
+          reset: now.getTime() + ttlMs
+        };
+      }
+    }
+  }
+  async resetUsedTokens(key) {
+    await ensureTables(this.pool);
+    const sql = `DELETE FROM ${this.table} WHERE prefix = $1 AND key = $2`;
+    if (this.debug) {
+      console.debug("pg-ratelimit resetUsedTokens:", sql, [this.prefix, key]);
+    }
+    await this.pool.query(sql, [this.prefix, key]);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Ratelimit,
+  TABLE_SQL
+});

package/dist/index.d.cts

@@ -0,0 +1,71 @@
+import { Pool } from 'pg';
+
+type TimeUnit = "s" | "m" | "h" | "d";
+type Duration = `${number} ${TimeUnit}` | `${number}${TimeUnit}`;
+type Algorithm = {
+    type: "fixedWindow";
+    tokens: number;
+    window: Duration | number;
+} | {
+    type: "slidingWindow";
+    tokens: number;
+    window: Duration | number;
+} | {
+    type: "tokenBucket";
+    refillRate: number;
+    interval: Duration | number;
+    maxTokens: number;
+};
+interface LimitResult {
+    success: boolean;
+    limit: number;
+    remaining: number;
+    reset: number;
+}
+type Clock = () => Date;
+type RatelimitConfig = {
+    pool: Pool;
+    limiter: Algorithm;
+    prefix: string;
+    debug?: boolean;
+    clock?: Clock;
+    cleanupProbability?: number;
+} & ({
+    durable?: false;
+} | {
+    durable: true;
+    synchronousCommit?: boolean;
+});
+
+declare class Ratelimit {
+    private readonly pool;
+    private readonly algorithm;
+    private readonly prefix;
+    private readonly table;
+    private readonly debug;
+    private readonly clock;
+    private readonly durable;
+    private readonly synchronousCommit;
+    private readonly cleanupProbability;
+    private readonly windowMs;
+    private readonly intervalMs;
+    constructor(config: RatelimitConfig);
+    static fixedWindow(tokens: number, window: Duration | number): Algorithm;
+    static slidingWindow(tokens: number, window: Duration | number): Algorithm;
+    static tokenBucket(refillRate: number, interval: Duration | number, maxTokens: number): Algorithm;
+    limit(key: string, opts?: {
+        rate?: number;
+    }): Promise<LimitResult>;
+    blockUntilReady(key: string, timeout: Duration | number, opts?: {
+        rate?: number;
+    }): Promise<LimitResult>;
+    getRemaining(key: string): Promise<{
+        remaining: number;
+        reset: number;
+    }>;
+    resetUsedTokens(key: string): Promise<void>;
+}
+
+declare const TABLE_SQL: string;
+
+export { type Algorithm, type Clock, type Duration, type LimitResult, Ratelimit, type RatelimitConfig, TABLE_SQL };

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+import { Pool } from 'pg';
+
+type TimeUnit = "s" | "m" | "h" | "d";
+type Duration = `${number} ${TimeUnit}` | `${number}${TimeUnit}`;
+type Algorithm = {
+    type: "fixedWindow";
+    tokens: number;
+    window: Duration | number;
+} | {
+    type: "slidingWindow";
+    tokens: number;
+    window: Duration | number;
+} | {
+    type: "tokenBucket";
+    refillRate: number;
+    interval: Duration | number;
+    maxTokens: number;
+};
+interface LimitResult {
+    success: boolean;
+    limit: number;
+    remaining: number;
+    reset: number;
+}
+type Clock = () => Date;
+type RatelimitConfig = {
+    pool: Pool;
+    limiter: Algorithm;
+    prefix: string;
+    debug?: boolean;
+    clock?: Clock;
+    cleanupProbability?: number;
+} & ({
+    durable?: false;
+} | {
+    durable: true;
+    synchronousCommit?: boolean;
+});
+
+declare class Ratelimit {
+    private readonly pool;
+    private readonly algorithm;
+    private readonly prefix;
+    private readonly table;
+    private readonly debug;
+    private readonly clock;
+    private readonly durable;
+    private readonly synchronousCommit;
+    private readonly cleanupProbability;
+    private readonly windowMs;
+    private readonly intervalMs;
+    constructor(config: RatelimitConfig);
+    static fixedWindow(tokens: number, window: Duration | number): Algorithm;
+    static slidingWindow(tokens: number, window: Duration | number): Algorithm;
+    static tokenBucket(refillRate: number, interval: Duration | number, maxTokens: number): Algorithm;
+    limit(key: string, opts?: {
+        rate?: number;
+    }): Promise<LimitResult>;
+    blockUntilReady(key: string, timeout: Duration | number, opts?: {
+        rate?: number;
+    }): Promise<LimitResult>;
+    getRemaining(key: string): Promise<{
+        remaining: number;
+        reset: number;
+    }>;
+    resetUsedTokens(key: string): Promise<void>;
+}
+
+declare const TABLE_SQL: string;
+
+export { type Algorithm, type Clock, type Duration, type LimitResult, Ratelimit, type RatelimitConfig, TABLE_SQL };

package/dist/index.js

@@ -0,0 +1,454 @@
+// src/duration.ts
+var MULTIPLIERS = {
+  s: 1e3,
+  m: 6e4,
+  h: 36e5,
+  d: 864e5
+};
+var DURATION_RE = /^\s*(\d+)\s*(s|m|h|d)\s*$/;
+function toMs(duration) {
+  if (typeof duration === "number") {
+    if (!Number.isFinite(duration) || duration <= 0) {
+      throw new Error(
+        `Invalid duration: ${duration}. Must be a positive finite number of milliseconds.`
+      );
+    }
+    return duration;
+  }
+  const match = DURATION_RE.exec(duration);
+  if (!match) {
+    throw new Error(
+      `Invalid duration format: "${duration}". Expected format: "<number><unit>" where unit is s, m, h, or d.`
+    );
+  }
+  const value = Number(match[1]);
+  const unit = match[2];
+  if (value <= 0) {
+    throw new Error(`Invalid duration: "${duration}". Value must be positive.`);
+  }
+  return value * MULTIPLIERS[unit];
+}
+
+// src/tables.sql
+var tables_default = "CREATE UNLOGGED TABLE IF NOT EXISTS rate_limit_ephemeral (\n  prefix       TEXT NOT NULL,\n  key          TEXT NOT NULL,\n  count        BIGINT,\n  prev_count   BIGINT,\n  window_start TIMESTAMPTZ,\n  tokens       DOUBLE PRECISION,\n  last_refill  TIMESTAMPTZ,\n  expires_at   TIMESTAMPTZ NOT NULL,\n  PRIMARY KEY (prefix, key)\n);\n\nCREATE INDEX IF NOT EXISTS idx_rate_limit_ephemeral_cleanup\n  ON rate_limit_ephemeral (prefix, expires_at);\n\nCREATE TABLE IF NOT EXISTS rate_limit_durable (\n  prefix       TEXT NOT NULL,\n  key          TEXT NOT NULL,\n  count        BIGINT,\n  prev_count   BIGINT,\n  window_start TIMESTAMPTZ,\n  tokens       DOUBLE PRECISION,\n  last_refill  TIMESTAMPTZ,\n  expires_at   TIMESTAMPTZ NOT NULL,\n  PRIMARY KEY (prefix, key)\n);\n\nCREATE INDEX IF NOT EXISTS idx_rate_limit_durable_cleanup\n  ON rate_limit_durable (prefix, expires_at);\n";
+
+// src/tables.ts
+var TABLE_SQL = tables_default;
+var initialized = /* @__PURE__ */ new WeakSet();
+async function ensureTables(pool) {
+  if (initialized.has(pool)) {
+    return;
+  }
+  if (process.env.PG_RATELIMIT_DISABLE_AUTO_MIGRATE === "true") {
+    initialized.add(pool);
+    return;
+  }
+  await pool.query(TABLE_SQL);
+  initialized.add(pool);
+}
+
+// src/algorithms/fixed-window.ts
+async function fixedWindow(ctx, tokens, windowMs) {
+  const { pool, table, prefix, key, rate, now, debug } = ctx;
+  const windowInterval = `${windowMs} milliseconds`;
+  const sql = `
+    INSERT INTO ${table} (prefix, key, count, window_start, expires_at)
+    VALUES ($1, $2, $3, $4::timestamptz, $4::timestamptz + $5::interval)
+    ON CONFLICT (prefix, key) DO UPDATE
+      SET count = CASE
+        WHEN ${table}.expires_at < $4::timestamptz THEN $3
+        ELSE ${table}.count + $3
+      END,
+      window_start = CASE
+        WHEN ${table}.expires_at < $4::timestamptz THEN $4::timestamptz
+        ELSE ${table}.window_start
+      END,
+      expires_at = CASE
+        WHEN ${table}.expires_at < $4::timestamptz THEN $4::timestamptz + $5::interval
+        ELSE ${table}.expires_at
+      END
+    RETURNING count, expires_at
+  `;
+  const params = [prefix, key, rate, now, windowInterval];
+  if (debug) {
+    console.debug("pg-ratelimit fixed-window:", sql, params);
+  }
+  const result = await pool.query(sql, params);
+  const row = result.rows[0];
+  const count = Number(row.count);
+  return {
+    success: count <= tokens,
+    limit: tokens,
+    remaining: Math.max(0, tokens - count),
+    reset: new Date(row.expires_at).getTime()
+  };
+}
+
+// src/algorithms/sliding-window.ts
+async function slidingWindow(ctx, tokens, windowMs) {
+  const { pool, table, prefix, key, rate, now, debug, synchronousCommit } = ctx;
+  const client = await pool.connect();
+  try {
+    await client.query("BEGIN");
+    if (!synchronousCommit) {
+      await client.query("SET LOCAL synchronous_commit = off");
+    }
+    const doubleWindowInterval = `${2 * windowMs} milliseconds`;
+    const ensureSql = `
+      INSERT INTO ${table} (prefix, key, count, prev_count, window_start, expires_at)
+      VALUES ($1, $2, 0, 0, $3::timestamptz, $3::timestamptz + $4::interval)
+      ON CONFLICT (prefix, key) DO NOTHING
+    `;
+    await client.query(ensureSql, [prefix, key, now, doubleWindowInterval]);
+    const selectSql = `
+      SELECT count, prev_count, window_start, expires_at
+      FROM ${table}
+      WHERE prefix = $1 AND key = $2
+      FOR UPDATE
+    `;
+    if (debug) {
+      console.debug("pg-ratelimit sliding-window SELECT:", selectSql, [prefix, key]);
+    }
+    const existing = await client.query(selectSql, [prefix, key]);
+    const row = existing.rows[0];
+    const oldWindowStart = new Date(row.window_start).getTime();
+    const nowMs = now.getTime();
+    let prevCount;
+    let count;
+    let windowStart;
+    if (oldWindowStart + windowMs > nowMs) {
+      prevCount = Number(row.prev_count) || 0;
+      count = Number(row.count) || 0;
+      windowStart = new Date(row.window_start);
+    } else if (oldWindowStart + 2 * windowMs > nowMs) {
+      prevCount = Number(row.count) || 0;
+      count = 0;
+      windowStart = new Date(oldWindowStart + windowMs);
+    } else {
+      prevCount = 0;
+      count = 0;
+      windowStart = now;
+    }
+    const elapsed = now.getTime() - windowStart.getTime();
+    const weight = 1 - elapsed / windowMs;
+    const effective = prevCount * weight + count + rate;
+    const success = effective <= tokens;
+    if (success) {
+      const newCount = count + rate;
+      const upsertSql = `
+        INSERT INTO ${table} (prefix, key, count, prev_count, window_start, expires_at)
+        VALUES ($1, $2, $3, $4, $5::timestamptz, $5::timestamptz + $6::interval)
+        ON CONFLICT (prefix, key) DO UPDATE
+          SET count = $3,
+              prev_count = $4,
+              window_start = $5::timestamptz,
+              expires_at = $5::timestamptz + $6::interval
+      `;
+      const upsertParams = [prefix, key, newCount, prevCount, windowStart, doubleWindowInterval];
+      if (debug) {
+        console.debug("pg-ratelimit sliding-window UPSERT:", upsertSql, upsertParams);
+      }
+      await client.query(upsertSql, upsertParams);
+    }
+    await client.query("COMMIT");
+    const reset = windowStart.getTime() + windowMs;
+    return {
+      success,
+      limit: tokens,
+      remaining: Math.max(0, tokens - effective),
+      reset
+    };
+  } catch (err) {
+    await client.query("ROLLBACK").catch(() => {
+    });
+    throw err;
+  } finally {
+    client.release();
+  }
+}
+
+// src/algorithms/token-bucket.ts
+async function tokenBucket(ctx, maxTokens, refillRate, intervalMs) {
+  const { pool, table, prefix, key, rate, now, debug, synchronousCommit } = ctx;
+  const client = await pool.connect();
+  const ttlMs = maxTokens / refillRate * intervalMs;
+  try {
+    await client.query("BEGIN");
+    if (!synchronousCommit) {
+      await client.query("SET LOCAL synchronous_commit = off");
+    }
+    const ttlInterval = `${ttlMs} milliseconds`;
+    const ensureSql = `
+      INSERT INTO ${table} (prefix, key, tokens, last_refill, expires_at)
+      VALUES ($1, $2, $3, $4::timestamptz, $4::timestamptz + $5::interval)
+      ON CONFLICT (prefix, key) DO NOTHING
+    `;
+    await client.query(ensureSql, [prefix, key, maxTokens, now, ttlInterval]);
+    const selectSql = `
+      SELECT tokens, last_refill, expires_at
+      FROM ${table}
+      WHERE prefix = $1 AND key = $2
+      FOR UPDATE
+    `;
+    if (debug) {
+      console.debug("pg-ratelimit token-bucket SELECT:", selectSql, [prefix, key]);
+    }
+    const existing = await client.query(selectSql, [prefix, key]);
+    const row = existing.rows[0];
+    const lastRefill = new Date(row.last_refill).getTime();
+    const elapsed = now.getTime() - lastRefill;
+    const refilled = Math.floor(elapsed / intervalMs) * refillRate;
+    const currentTokens = Math.min(Number(row.tokens) + refilled, maxTokens);
+    const newTokens = currentTokens - rate;
+    const success = newTokens >= 0;
+    if (success) {
+      const upsertSql = `
+        INSERT INTO ${table} (prefix, key, tokens, last_refill, expires_at)
+        VALUES ($1, $2, $3, $4::timestamptz, $4::timestamptz + $5::interval)
+        ON CONFLICT (prefix, key) DO UPDATE
+          SET tokens = $3, last_refill = $4::timestamptz, expires_at = $4::timestamptz + $5::interval
+      `;
+      const upsertParams = [prefix, key, newTokens, now, ttlInterval];
+      if (debug) {
+        console.debug("pg-ratelimit token-bucket UPSERT:", upsertSql, upsertParams);
+      }
+      await client.query(upsertSql, upsertParams);
+    }
+    await client.query("COMMIT");
+    let reset;
+    if (success) {
+      reset = now.getTime() + ttlMs;
+    } else {
+      const tokensNeeded = rate - currentTokens;
+      const intervalsNeeded = Math.ceil(tokensNeeded / refillRate);
+      reset = now.getTime() + intervalsNeeded * intervalMs;
+    }
+    return {
+      success,
+      limit: maxTokens,
+      remaining: Math.max(0, success ? newTokens : currentTokens),
+      reset
+    };
+  } catch (err) {
+    await client.query("ROLLBACK").catch(() => {
+    });
+    throw err;
+  } finally {
+    client.release();
+  }
+}
+
+// src/limiter.ts
+var Ratelimit = class {
+  pool;
+  algorithm;
+  prefix;
+  table;
+  debug;
+  clock;
+  durable;
+  synchronousCommit;
+  cleanupProbability;
+  // Pre-parsed durations (only the relevant one is used per algorithm)
+  windowMs;
+  intervalMs;
+  constructor(config) {
+    if (!config.prefix) {
+      throw new Error("prefix must be a non-empty string");
+    }
+    const cleanupProbability = config.cleanupProbability ?? 0.1;
+    if (cleanupProbability < 0 || cleanupProbability > 1) {
+      throw new Error("cleanupProbability must be between 0 and 1");
+    }
+    this.pool = config.pool;
+    this.algorithm = config.limiter;
+    this.prefix = config.prefix;
+    this.debug = config.debug ?? false;
+    this.clock = config.clock ?? (() => /* @__PURE__ */ new Date());
+    this.durable = "durable" in config && config.durable === true;
+    this.table = this.durable ? "rate_limit_durable" : "rate_limit_ephemeral";
+    this.cleanupProbability = cleanupProbability;
+    this.synchronousCommit = !this.durable || "synchronousCommit" in config && config.synchronousCommit === true;
+    if (this.algorithm.type === "fixedWindow" || this.algorithm.type === "slidingWindow") {
+      this.windowMs = toMs(this.algorithm.window);
+      this.intervalMs = 0;
+    } else {
+      this.windowMs = 0;
+      this.intervalMs = toMs(this.algorithm.interval);
+    }
+  }
+  static fixedWindow(tokens, window) {
+    return { type: "fixedWindow", tokens, window };
+  }
+  static slidingWindow(tokens, window) {
+    return { type: "slidingWindow", tokens, window };
+  }
+  static tokenBucket(refillRate, interval, maxTokens) {
+    return { type: "tokenBucket", refillRate, interval, maxTokens };
+  }
+  async limit(key, opts) {
+    const rate = opts?.rate ?? 1;
+    const now = this.clock();
+    await ensureTables(this.pool);
+    const ctx = {
+      pool: this.pool,
+      table: this.table,
+      prefix: this.prefix,
+      key,
+      rate,
+      now,
+      debug: this.debug,
+      synchronousCommit: this.synchronousCommit
+    };
+    let result;
+    switch (this.algorithm.type) {
+      case "fixedWindow":
+        result = await fixedWindow(ctx, this.algorithm.tokens, this.windowMs);
+        break;
+      case "slidingWindow":
+        result = await slidingWindow(ctx, this.algorithm.tokens, this.windowMs);
+        break;
+      case "tokenBucket":
+        result = await tokenBucket(
+          ctx,
+          this.algorithm.maxTokens,
+          this.algorithm.refillRate,
+          this.intervalMs
+        );
+        break;
+    }
+    if (Math.random() < this.cleanupProbability) {
+      void this.pool.query(`DELETE FROM ${this.table} WHERE prefix = $1 AND expires_at < $2`, [
+        this.prefix,
+        now
+      ]).catch(() => {
+      });
+    }
+    return result;
+  }
+  async blockUntilReady(key, timeout, opts) {
+    const timeoutMs = toMs(timeout);
+    const deadline = this.clock().getTime() + timeoutMs;
+    let result = await this.limit(key, opts);
+    if (result.success) {
+      return result;
+    }
+    while (true) {
+      const now = this.clock().getTime();
+      const remaining = deadline - now;
+      if (remaining <= 0) {
+        return result;
+      }
+      const sleepMs = result.reset - now;
+      if (sleepMs > remaining) {
+        return result;
+      }
+      if (sleepMs > 0) {
+        await new Promise((resolve) => setTimeout(resolve, sleepMs));
+      }
+      result = await this.limit(key, opts);
+      if (result.success) {
+        return result;
+      }
+    }
+  }
+  async getRemaining(key) {
+    await ensureTables(this.pool);
+    const now = this.clock();
+    const selectSql = `
+      SELECT count, prev_count, window_start, expires_at, tokens, last_refill
+      FROM ${this.table}
+      WHERE prefix = $1 AND key = $2
+    `;
+    if (this.debug) {
+      console.debug("pg-ratelimit getRemaining:", selectSql, [this.prefix, key]);
+    }
+    const result = await this.pool.query(selectSql, [this.prefix, key]);
+    if (result.rows.length === 0) {
+      switch (this.algorithm.type) {
+        case "fixedWindow":
+          return {
+            remaining: this.algorithm.tokens,
+            reset: now.getTime() + this.windowMs
+          };
+        case "slidingWindow":
+          return {
+            remaining: this.algorithm.tokens,
+            reset: now.getTime() + this.windowMs
+          };
+        case "tokenBucket":
+          return {
+            remaining: this.algorithm.maxTokens,
+            reset: now.getTime() + this.algorithm.maxTokens / this.algorithm.refillRate * this.intervalMs
+          };
+      }
+    }
+    const row = result.rows[0];
+    switch (this.algorithm.type) {
+      case "fixedWindow": {
+        if (new Date(row.expires_at).getTime() < now.getTime()) {
+          return {
+            remaining: this.algorithm.tokens,
+            reset: now.getTime() + this.windowMs
+          };
+        }
+        const count = Number(row.count) || 0;
+        return {
+          remaining: Math.max(0, this.algorithm.tokens - count),
+          reset: new Date(row.expires_at).getTime()
+        };
+      }
+      case "slidingWindow": {
+        const oldWindowStart = new Date(row.window_start).getTime();
+        const nowMs = now.getTime();
+        let prevCount;
+        let count;
+        let windowStart;
+        if (oldWindowStart + this.windowMs > nowMs) {
+          prevCount = Number(row.prev_count) || 0;
+          count = Number(row.count) || 0;
+          windowStart = oldWindowStart;
+        } else if (oldWindowStart + 2 * this.windowMs > nowMs) {
+          prevCount = Number(row.count) || 0;
+          count = 0;
+          windowStart = oldWindowStart + this.windowMs;
+        } else {
+          return {
+            remaining: this.algorithm.tokens,
+            reset: nowMs + this.windowMs
+          };
+        }
+        const elapsed = nowMs - windowStart;
+        const weight = 1 - elapsed / this.windowMs;
+        const effective = prevCount * weight + count;
+        return {
+          remaining: Math.max(0, this.algorithm.tokens - effective),
+          reset: windowStart + this.windowMs
+        };
+      }
+      case "tokenBucket": {
+        const lastRefill = new Date(row.last_refill).getTime();
+        const elapsed = now.getTime() - lastRefill;
+        const refilled = Math.floor(elapsed / this.intervalMs) * this.algorithm.refillRate;
+        const currentTokens = Math.min(Number(row.tokens) + refilled, this.algorithm.maxTokens);
+        const ttlMs = this.algorithm.maxTokens / this.algorithm.refillRate * this.intervalMs;
+        return {
+          remaining: Math.max(0, currentTokens),
+          reset: now.getTime() + ttlMs
+        };
+      }
+    }
+  }
+  async resetUsedTokens(key) {
+    await ensureTables(this.pool);
+    const sql = `DELETE FROM ${this.table} WHERE prefix = $1 AND key = $2`;
+    if (this.debug) {
+      console.debug("pg-ratelimit resetUsedTokens:", sql, [this.prefix, key]);
+    }
+    await this.pool.query(sql, [this.prefix, key]);
+  }
+};
+export {
+  Ratelimit,
+  TABLE_SQL
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "pg-ratelimit",
+  "version": "0.1.0",
+  "description": "PostgreSQL-backed rate limiting for Node.js",
+  "license": "MIT",
+  "author": "Max Malm",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/benjick/pg-ratelimit.git",
+    "directory": "packages/pg-ratelimit"
+  },
+  "homepage": "https://benjick.js.org/pg-ratelimit",
+  "bugs": {
+    "url": "https://github.com/benjick/pg-ratelimit/issues"
+  },
+  "keywords": [
+    "rate-limit",
+    "ratelimit",
+    "postgres",
+    "postgresql",
+    "rate-limiting",
+    "throttle"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "devDependencies": {
+    "@testcontainers/postgresql": "^10.0.0",
+    "@types/pg": "^8.0.0",
+    "pg": "^8.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  },
+  "peerDependencies": {
+    "pg": "^8.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run"
+  }
+}