{"_id":"@edgefirst-dev/worker-kv-rate-limit","_rev":"1-c521d7afe803b93bc8ecba86743668ea","name":"@edgefirst-dev/worker-kv-rate-limit","dist-tags":{"latest":"1.0.0"},"versions":{"0.0.1":{"name":"@edgefirst-dev/worker-kv-rate-limit","version":"0.0.1","author":{"url":"https://sergiodxa.com","name":"Sergio Xalambrí","email":"hello+oss@sergiodxa.com"},"license":"MIT","_id":"@edgefirst-dev/worker-kv-rate-limit@0.0.1","maintainers":[{"name":"sergiodxa","email":"hello@sergiodxa.com"}],"homepage":"https://edgefirst-dev.github.io/worker-kv-rate-limit","bugs":{"url":"https://github.com/edgefirst-dev/worker-kv-rate-limit/issues"},"dist":{"shasum":"f0763758298b4aee9e045e0fa6ec7f79482ab03c","tarball":"https://registry.npmjs.org/@edgefirst-dev/worker-kv-rate-limit/-/worker-kv-rate-limit-0.0.1.tgz","fileCount":9,"integrity":"sha512-LgZx/XdXbb0aAe+Y0R59KjfVlsUZEJBaw0QmVn26HCaoTk2C8Hjn4+DxOAE5brd9QQOv4xcHSsDtiNIkUjhs+Q==","signatures":[{"sig":"MEUCIQCT9gXEnsuYmUjrEb/RhGR3NqL534wHdg3+/rOy1MTF2AIgJfBOU5G53rd37IJzgm9xjX0Z40jolRJQqhhn8hwOuNU=","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@edgefirst-dev%2fworker-kv-rate-limit@0.0.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":11361},"type":"module","engines":{"node":">=20.0.0"},"exports":{".":"./build/index.js","./package.json":"./package.json"},"funding":["https://github.com/sponsors/sergiodxa"],"gitHead":"5e5cfe5765c2a08c566d8bbb115d34d94b4d42e1","scripts":{"build":"tsc","exports":"bun run ./scripts/exports.ts","quality":"biome check .","typecheck":"tsc --noEmit","quality:fix":"biome check . --write --unsafe"},"_npmUser":{"name":"sergiodxa","email":"hello@sergiodxa.com"},"repository":{"url":"git+https://github.com/edgefirst-dev/worker-kv-rate-limit.git","type":"git"},"_npmVersion":"10.8.2","description":"A Rate Limit based on Cloudflare's Worker KV.","directories":{},"sideEffects":false,"_nodeVersion":"20.17.0","dependencies":{"@cloudflare/workers-types":"^4.20240903.0"},"_hasShrinkwrap":false,"devDependencies":{"consola":"^3.2.3","typedoc":"^0.26.6","@types/bun":"^1.1.8","typescript":"^5.5.4","@biomejs/biome":"^1.8.3","@arethetypeswrong/cli":"^0.16.1","typedoc-plugin-mdn-links":"^3.2.11","@total-typescript/tsconfig":"^1.0.4"},"peerDependencies":{},"_npmOperationalInternal":{"tmp":"tmp/worker-kv-rate-limit_0.0.1_1725676885257_0.6518255724473518","host":"s3://npm-registry-packages"}},"1.0.0":{"name":"@edgefirst-dev/worker-kv-rate-limit","version":"1.0.0","description":"A Rate Limit based on Cloudflare's Worker KV.","license":"MIT","funding":["https://github.com/sponsors/sergiodxa"],"author":{"name":"Sergio Xalambrí","email":"hello+oss@sergiodxa.com","url":"https://sergiodxa.com"},"repository":{"type":"git","url":"git+https://github.com/edgefirst-dev/worker-kv-rate-limit.git"},"homepage":"https://edgefirst-dev.github.io/worker-kv-rate-limit","bugs":{"url":"https://github.com/edgefirst-dev/worker-kv-rate-limit/issues"},"scripts":{"build":"tsc","typecheck":"tsc --noEmit","quality":"biome check .","quality:fix":"biome check . --write --unsafe","exports":"bun run ./scripts/exports.ts"},"sideEffects":false,"type":"module","engines":{"node":">=20.0.0"},"exports":{".":"./build/index.js","./package.json":"./package.json"},"dependencies":{"@cloudflare/workers-types":"^4.20240903.0"},"peerDependencies":{},"devDependencies":{"@arethetypeswrong/cli":"^0.16.1","@biomejs/biome":"^1.8.3","@total-typescript/tsconfig":"^1.0.4","@types/bun":"^1.1.8","consola":"^3.2.3","typedoc":"^0.26.6","typedoc-plugin-mdn-links":"^3.2.11","typescript":"^5.5.4"},"_id":"@edgefirst-dev/worker-kv-rate-limit@1.0.0","gitHead":"d451800e15cc7cd6da45b909bdab03781f4f759d","_nodeVersion":"20.17.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-YV3HMDmyzP/oBfTmqdlZoKebIlgk50pXakYyK0rdp8D9bxoGD9P5fM8fgJS1W2AWPYTmmskJhNn+ppah1vmjiA==","shasum":"3302eefa3aa329de316dc5dab349f8acf7830c35","tarball":"https://registry.npmjs.org/@edgefirst-dev/worker-kv-rate-limit/-/worker-kv-rate-limit-1.0.0.tgz","fileCount":9,"unpackedSize":12637,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@edgefirst-dev%2fworker-kv-rate-limit@1.0.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQCkmFaK6xTRJzy9E7bztR2vujGY4vnZ5eTxGteHr3yHngIhAKmi2m1//91IYH0VZaqcB0jjzqWJmDVFR/96CbPf4OJn"}]},"_npmUser":{"name":"sergiodxa","email":"hello@sergiodxa.com"},"directories":{},"maintainers":[{"name":"sergiodxa","email":"hello@sergiodxa.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/worker-kv-rate-limit_1.0.0_1725677529190_0.2798166909736379"},"_hasShrinkwrap":false}},"time":{"created":"2024-09-07T02:41:25.152Z","modified":"2024-09-07T02:52:09.752Z","0.0.1":"2024-09-07T02:41:25.481Z","1.0.0":"2024-09-07T02:52:09.348Z"},"bugs":{"url":"https://github.com/edgefirst-dev/worker-kv-rate-limit/issues"},"author":{"name":"Sergio Xalambrí","email":"hello+oss@sergiodxa.com","url":"https://sergiodxa.com"},"license":"MIT","homepage":"https://edgefirst-dev.github.io/worker-kv-rate-limit","repository":{"type":"git","url":"git+https://github.com/edgefirst-dev/worker-kv-rate-limit.git"},"description":"A Rate Limit based on Cloudflare's Worker KV.","maintainers":[{"name":"sergiodxa","email":"hello@sergiodxa.com"}],"readme":"# @edgefirst-dev/worker-kv-rate-limit\n\nA Rate Limit based on Cloudflare's Worker KV.\n\nThis class is based on Cloudflare's own [Rate Limit](https://developers.cloudflare.com/workers/runtime-apis/bindings/rate-limit/) feature currently in beta and only available to Cloudflare Workers.\n\nThis package can be used on your Cloudflare Pages application too as it uses Worker KV to keep the rate limit state.\n\n## Installation\n\nInstall from npm or GitHub Package Registry with;\n\n```bash\nbun add @edgefirst-dev/worker-kv-rate-limit\n```\n\n## Usage\n\n```ts\nimport { WorkerKVRateLimit } from \"@edgefirst-dev/worker-kv-rate-limit\";\n\nexport default {\n  async fetch(request, env): Promise<Response> {\n    let { pathname } = new URL(request.url);\n\n    let rateLimit = WorkerKVRateLimit(env.KV);\n\n    // key can be any string of your choosing\n    let { success } = await rateLimit.limit({ key: pathname });\n\n    if (!success) {\n      return new Response(`429 Failure – rate limit exceeded for ${pathname}`, {\n        status: 429,\n        headers: await rateLimit.writeHttpMetadata({\n          key: pathname,\n          resource: \"resource identifier\", // Optional\n        }),\n      });\n    }\n\n    return new Response(`Success!`, {\n      status: 200,\n      headers: await rateLimit.writeHttpMetadata({\n        key: pathname,\n        resource: \"resource identifier\", // Optional\n      }),\n    });\n  },\n} satisfies ExportedHandler<Env>;\n```\n\nThe `limit` function works exactly like Cloudflare's own Rate Limit feature. It returns an object with a `success` property that is `true` if the rate limit has not been exceeded and `false` if it has.\n\nThe `writeHttpMetadata` function returns an object with the necessary headers to be set on the response to the client. This is necessary to inform the client of the rate limit status.\n\nIf you want to apply extra headers, you can either keep the result Headers object and append headers there.\n\n```ts\nlet headers = await rateLimit.writeHttpMetadata({\n  key: pathname,\n  resource: \"resource identifier\", // Optional\n});\nheaders.set(\"X-Extra-Header\", \"Extra Value\");\n```\n\nOr you can pass a Headers object to the `writeHttpMetadata` function and it will append the necessary headers to it.\n\n```ts\nlet headers = new Headers();\nheaders.set(\"X-Extra-Header\", \"Extra Value\");\n\nawait rateLimit.writeHttpMetadata(\n  {\n    key: pathname,\n    resource: \"resource identifier\", // Optional\n  },\n  headers\n);\n```\n\nThe `writeHttpMetadata` will set the following headers:\n\n- `X-RateLimit-Limit`: The maximum number of requests allowed in the current window.\n- `X-RateLimit-Remaining`: The number of requests remaining in the current window.\n- `X-RateLimit-Used`: The number of requests used in the current window.\n- `X-RateLimit-Reset`: The time in seconds when the rate limit window resets.\n- `X-RateLimit-Resource`: The resource being rate limited (if provided).\n- `Retry-After`: The time in seconds when the rate limit window resets.\n\nThe `X-RateLimit-Reset` and `Retry-After` headers are the same and represent the time in seconds when the rate limit window resets, the reason to duplicate them is to keep compatibility with the `Retry-After` header that is used by the HTTP standard and consistency with common `X-RateLimit-` headers.\n\n## License\n\nSee [LICENSE](./LICENSE)\n\n## Author\n\n- [Sergio Xalambrí](https://sergiodxa.com)\n","readmeFilename":"README.md"}