---
title: "@playstack/rate-limit-do"
description: "Cloudflare Durable Object storage for Playstack rate-limit policies."
tags: ["package","operations","rate-limiting","cloudflare","free"]
---

{/* package-access:start */}

> **Free.** MIT licensed. Check preview availability before installing. See [package access](/docs/packages#access-policy).

{/* package-access:end */}

`@playstack/rate-limit-do` maps the atomic rate-limit storage contract onto Cloudflare Durable Objects while keeping policy portable.

{/* package-install:start */}

## Install

After confirming [preview access](/docs/packages#access-policy), install the package at your application's shared Playstack version:

```sh
npm install --save-exact @playstack/rate-limit-do@0.1.0-beta.1
```

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

{/* package-install:end */}

## Bind and compose

Export `PlaystackRateLimitDurableObject` from the Worker, bind its namespace, then construct the client-side store:

```ts
import {
  DurableObjectRateLimitStore,
  PlaystackRateLimitDurableObject,
} from '@playstack/rate-limit-do'

export { PlaystackRateLimitDurableObject }

const store = new DurableObjectRateLimitStore({
  namespace: env.PLAYSTACK_RATE_LIMIT,
  routeBucket: (bucket) => `account-group:${resolveGroup(bucket.key)}`,
})
```

## Store options

| Property | Contract |
| --- | --- |
| `namespace` | Structural `idFromName(name)` and `get(id).fetch(...)` Durable Object namespace. |
| `routeBucket` | Maps each compiled bucket to a non-empty deterministic object name. |

Every bucket in a multi-subject definition must route to the same object. The adapter checks this before any storage request. Single-bucket definitions may route directly from the bucket key; multi-bucket policies need an application-defined common group.

The Durable Object evaluates and writes the entire group within one storage transaction and uses application time because its storage has no Redis-style server-time command.

## Routing considerations

Object naming determines both atomicity and load distribution. Review common-group routes for hot spots, and never route related buckets to separate objects merely for distribution—the operation would no longer be atomic.

## Boundary

The application owns Worker bindings, object names, environment configuration, deployment, and observability. The package supplies the class and structural client adapter, not Cloudflare project configuration.

{/* package-reference:start */}

## API entry points and requirements

Reference snapshot: `@playstack/rate-limit-do@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.

| Public entry point | Declaration file |
| --- | --- |
| `@playstack/rate-limit-do` | `./dist/index.d.ts` |
| `@playstack/rate-limit-do/package.json` | No TypeScript declaration (asset or metadata export). |

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](/docs/getting-started). For API lookup and partial-example conventions, see [Reading the reference](/docs/packages#reading-the-reference). Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.

{/* package-reference:end */}