@playstack/rate-limit-prisma

@playstack/rate-limit-prisma implements the atomic RateLimitStore contract in Postgres for applications that prefer their existing relational database over another service.

Install

After confirming preview access, install the package at your application's shared Playstack version:

npm install --save-exact @playstack/rate-limit-prisma@0.1.0-beta.1

Check the peer requirements below before choosing a runtime or provider.

Compose the store

import { PrismaRateLimitStore } from '@playstack/rate-limit-prisma'

const store = new PrismaRateLimitStore(prisma)
const limiter = createRateLimiter({ definitions, store, clock, keyHasher, environment })

store.client is the exact structural Prisma client supplied by the application.

Atomic behavior

For each consume call, the adapter:

1. Creates missing buckets at full capacity.
2. Locks every row in lexicographic key order to avoid inconsistent lock ordering.
3. Refills and evaluates the complete group using application time.
4. Writes every resulting state in one transaction only when allowed.

A denied group consumes no bucket. Database or response-shape failures become RateLimitUnavailableError, allowing the core definition’s explicit open/closed policy to decide behavior.

Rolling-window store

PrismaRollingWindowRateLimitStore implements the separate rolling-expiry/cooldown policy from @playstack/rate-limit/rolling-window. Select the rate-limit.rolling-window.prisma artifact (playstack-rate-limit-rolling.prisma) and migrate it with the application's normal process. It does not reuse token-bucket rows.

The store serializes first writes, locks subjects in order and reads PostgreSQL clock_timestamp() after locks in one READ COMMITTED transaction. Returned evaluatedAtMs keeps retry headers on the same clock. Configure client statement/ transaction bounds; ambiguous commits do not trigger automatic retry/fallback.

The host schedules store.cleanupExpired(batchSize), default 1,000 and at most 10,000 rows, using database time and SKIP LOCKED. Active hit/cooldown state is retained. This adds no package-owned timer or worker. Match the raw-query schema/ search path to the generated Prisma model.

The rolling adapter's disposable PostgreSQL evidence uses Prisma 6.12.0 and PostgreSQL 17.11; it is not qualification of every Prisma driver/version.

Prisma boundary

Compose the managed playstack-rate-limit.prisma artifact with playstack database sync, generate the application client, and run application-owned migrations. The structural client contract requires $transaction, bucket createMany/update, and parameterized raw query support.

The adapter does not generate or disconnect clients, select a Prisma runtime, own pools, or run migrations. Use @playstack/prisma-runtime when an application explicitly selects among generated clients.

API entry points and requirements

Reference snapshot: @playstack/rate-limit-prisma@0.1.0-beta.1. Import only the entry point your runtime needs. Paths below are relative to the installed package; use Go to Definition in your editor to inspect exact parameters, return types and overloads. Do not import the declaration-file paths directly.

Node.js engine requirement: >=20. This is not a claim that every entry point works in browsers or Workers.

Peer dependencies

This package declares no peer dependencies. Its ordinary dependencies are resolved by the package manager.

For a complete first program, start with Getting started. For API lookup and partial-example conventions, see Reading the reference. Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.