Registry / devops / throttlekit-server

throttlekit-server

library0.1.0-experimental.7jsnpmunverified

gRPC service door for ThrottleKit — run the rate-limiting core (GALE/TALE engines) as a network service for polyglot clients. Current stable version v0.1.0-experimental.7, pre-1.0 experimental release. Key differentiator: exposes the exact same decision logic as the in-process library over gRPC, so clients in any language get identical rate-limit behavior without reimplementing algorithms. Supports multiple backing stores (memory, Redis, Postgres, DynamoDB) with bit-identical decisions. Release cadence: experimental, evolves independently from core throttlekit (which is 1.0 and frozen).

devops

npm install throttlekit-server

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · THROTTLEKIT-SERVER

throttlekit-server

devopsjavascriptv0.1.0-experimental.7

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

startServer

✓ import { startServer } from 'throttlekit-server'

✗ const startServer = require('throttlekit-server').startServer

The package is ESM-only (engine >=18). No default export.

ServerOptions

✓ import type { ServerOptions } from 'throttlekit-server'

✗ import { ServerOptions } from 'throttlekit-server'

ServerOptions is a TypeScript type export, not a value.

startServer

✓ import { startServer } from 'throttlekit-server'

✗ const startServer = require('throttlekit-server')

CommonJS require() is not supported; package is ESM-only.

Starts the gRPC server with config, port, and optional Redis store. Uses environment variables for auth.

import { startServer } from 'throttlekit-server'; startServer({ configPath: '.throttlekit.yaml', port: parseInt(process.env.PORT ?? '50051'), storeUrl: process.env.REDIS_URL ?? '', }).then(() => console.log('Server started'));

Debug

Known issues

breakingRequires Node >=18; ESM-only. No CommonJS support.

fix

Use Node >=18 and ESM imports.

affects: >=0.0.0

gotchaExperimental pre-1.0: API may change without major semver bump. The core throttlekit is stable, but server API is not frozen.

fix

Pin to exact version and test upgrades.

affects: <1.0.0

gotchaMemory store is default; if you run multiple instances without shared store (Redis/Postgres/DynamoDB), each instance will have independent rate limits, which can lead to overshoot.

fix

Use --redis, --postgres-url, or --store dynamodb for fleet coordination.

affects: >=0.0.0

deprecatedDenoKV and Cloudflare stores are not supported in throttlekit-server (only in edge runtimes).

fix

Do not attempt to use those stores with this package; run ThrottleKit inside those runtimes instead.

affects: >=0.0.0

gotchagRPC errors are reserved for operational faults; rate-limit denials return allowed: false, not an error. Misunderstanding this can lead to incorrect error handling.

fix

Check the 'allowed' field in the Decision response; do not treat denials as gRPC errors.

affects: >=0.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module

CommonJS require() used on ESM-only package.

fix

Use ESM import syntax: import { startServer } from 'throttlekit-server'

Error: listen EADDRINUSE :::50051

Port already in use by another server.

fix

Change port with --port <number> or kill the existing process on that port.

Error: config path '.throttlekit.yaml' not found

Missing configuration file.

fix

Create .throttlekit.yaml in the working directory or pass explicit path with --config.

Error: Unknown store type: dynamodb (missing --store flag?)

DynamoDB store requires explicit --store dynamodb flag.

fix

Set --store dynamodb or rely on URL inference (--postgres-url, --redis).

Upgrade

Version history

0.1.0-experimental.7latest on npm

Audit

Dependencies

throttlekitrequiredThrottleKit core providing the rate-limiting engines and decision logic

Agent activity

7 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/AmeyaBorkar/throttlekit ↗

packagethrottlekit-server ↗

homepagehttps://github.com/AmeyaBorkar/throttlekit/tree/main/server#readme ↗