@arcjet/decorate 1.0.0-beta.8 → 1.0.0

package/README.md

@@ -18,53 +18,79 @@
 
 [Arcjet][arcjet] utilities for decorating responses with information.
 
-## Installation
+- [npm package (`@arcjet/decorate`)](https://www.npmjs.com/package/@arcjet/decorate)
+- [GitHub source code (`decorate/` in `arcjet/arcjet-js`)](https://github.com/arcjet/arcjet-js/tree/main/decorate)
 
-```shell
-npm install -S @arcjet/decorate
+## What is this?
+
+This is a utility that lets you decorate responses based on Arcjet decisions.
+It currently supports experimental rate limit headers.
+
+## When should I use this?
+
+You can use this package if you use the rate limit rule and want to set
+experimental `RateLimit-Policy` and `RateLimit` headers.
+See [_RateLimit header fields for HTTP_ on `ietf.org`][ietf-rate-limit] for
+more info.
+
+## Install
+
+This package is ESM only.
+Install with npm in Node.js:
+
+```sh
+npm install @arcjet/decorate
 ```
 
 ## Example
 
 ```ts
-import arcjet, { fixedWindow } from "@arcjet/next";
+import http from "node:http";
 import { setRateLimitHeaders } from "@arcjet/decorate";
-import { NextApiRequest, NextApiResponse } from "next";
+import arcjet, { shield } from "@arcjet/node";
+
+// Get your Arcjet key at <https://app.arcjet.com>.
+// Set it as an environment variable instead of hard coding it.
+const arcjetKey = process.env.ARCJET_KEY;
+
+if (!arcjetKey) {
+  throw new Error("Cannot find `ARCJET_KEY` environment variable");
+}
 
 const aj = arcjet({
-  key: process.env.ARCJET_KEY!, // Get your site key from https://app.arcjet.com
+  key: arcjetKey,
   rules: [
-    // Create a fixed window rate limit. Other algorithms are supported.
-    fixedWindow({
-      mode: "LIVE", // will block requests. Use "DRY_RUN" to log only
-      window: "1m", // 1 min fixed window
-      max: 1, // allow a single request
-    }),
+    // Shield protects your app from common attacks.
+    // Use `DRY_RUN` instead of `LIVE` to only log.
+    shield({ mode: "LIVE" }),
   ],
 });
 
-export default async function handler(
-  req: NextApiRequest,
-  res: NextApiResponse,
+const server = http.createServer(async function (
+  request: http.IncomingMessage,
+  response: http.ServerResponse,
 ) {
-  const decision = await aj.protect(req);
+  const decision = await aj.protect(request);
 
-  setRateLimitHeaders(res, decision);
+  setRateLimitHeaders(response, decision);
 
   if (decision.isDenied()) {
-    return res.status(429).json({
-      error: "Too Many Requests",
-      reason: decision.reason,
-    });
+    response.writeHead(403, { "Content-Type": "application/json" });
+    response.end(JSON.stringify({ message: "Forbidden" }));
+    return;
   }
 
-  res.status(200).json({ name: "Hello world" });
-}
+  response.writeHead(200, { "Content-Type": "application/json" });
+  response.end(JSON.stringify({ message: "Hello world" }));
+});
+
+server.listen(8000);
 ```
 
 ## License
 
-Licensed under the [Apache License, Version 2.0][apache-license].
+[Apache License, Version 2.0][apache-license] © [Arcjet Labs, Inc.][arcjet]
 
 [arcjet]: https://arcjet.com
 [apache-license]: http://www.apache.org/licenses/LICENSE-2.0
+[ietf-rate-limit]: https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-ratelimit-headers-08

package/index.d.ts

@@ -1,28 +1,40 @@
 import type { ArcjetDecision } from "@arcjet/protocol";
 interface HeaderLike {
-    has(name: string): boolean;
     get(name: string): string | null;
+    has(name: string): boolean;
     set(name: string, value: string): void;
 }
-export interface ArcjetCanDecorate {
-    has?: (name: string) => boolean;
-    get?: (name: string) => string | null;
-    set?: (name: string, value: string) => void;
-    headers?: HeaderLike;
-    headersSent?: boolean;
-    hasHeader?: (name: string) => boolean;
-    getHeader?: (name: string) => number | string | string[] | undefined;
-    setHeader?: (name: string, value: number | string | ReadonlyArray<string>) => unknown;
+interface ResponseLike {
+    headers: HeaderLike;
+}
+interface OutgoingMessageLike {
+    getHeader: (name: string) => string[] | number | string | undefined;
+    headersSent: boolean;
+    hasHeader: (name: string) => boolean;
+    setHeader: (name: string, value: ReadonlyArray<string> | number | string) => unknown;
 }
 /**
- * Decorates an object with `RateLimit` and `RateLimit-Policy` headers based
- * on an {@link ArcjetDecision} and conforming to the [Rate Limit fields for
+ * Decorable value.
+ *
+ * Something that looks like `Headers` (Fetch),
+ * `OutgoingMessage` (Node.js), or
+ * `Response` (Fetch).
+ */
+export type ArcjetCanDecorate = HeaderLike | OutgoingMessageLike | ResponseLike;
+/**
+ * Decorate something based on an Arcjet decision with rate limit headers.
+ *
+ * Sets `RateLimit-Policy` and `RateLimit` and conform to the
+ * [Rate Limit fields for
  * HTTP](https://ietf-wg-httpapi.github.io/ratelimit-headers/draft-ietf-httpapi-ratelimit-headers.html)
  * draft specification.
  *
- * @param value The object to decorate—must be similar to {@link Headers}, {@link Response} or
- * {@link OutgoingMessage}.
- * @param decision The {@link ArcjetDecision} that was made by calling `protect()` on the SDK.
+ * @param value
+ *   Decorable value.
+ * @param decision
+ *   Decision from `protect()`.
+ * @returns
+ *   Nothing.
  */
 export declare function setRateLimitHeaders(value: ArcjetCanDecorate, decision: ArcjetDecision): void;
 export {};

package/index.js

@@ -13,13 +13,14 @@ function isHeaderLike(value) {
     return false;
 }
 function isResponseLike(value) {
-    if (typeof value.headers === "undefined") {
+    if (!("headers" in value) || typeof value.headers === "undefined") {
         return false;
     }
     return isHeaderLike(value.headers);
 }
 function isOutgoingMessageLike(response) {
-    if (typeof response.headersSent !== "boolean") {
+    if (!("headersSent" in response) ||
+        typeof response.headersSent !== "boolean") {
         return false;
     }
     if (typeof response.hasHeader !== "function") {
@@ -71,14 +72,19 @@ function nearestLimit(current, next) {
     return next;
 }
 /**
- * Decorates an object with `RateLimit` and `RateLimit-Policy` headers based
- * on an {@link ArcjetDecision} and conforming to the [Rate Limit fields for
+ * Decorate something based on an Arcjet decision with rate limit headers.
+ *
+ * Sets `RateLimit-Policy` and `RateLimit` and conform to the
+ * [Rate Limit fields for
  * HTTP](https://ietf-wg-httpapi.github.io/ratelimit-headers/draft-ietf-httpapi-ratelimit-headers.html)
  * draft specification.
  *
- * @param value The object to decorate—must be similar to {@link Headers}, {@link Response} or
- * {@link OutgoingMessage}.
- * @param decision The {@link ArcjetDecision} that was made by calling `protect()` on the SDK.
+ * @param value
+ *   Decorable value.
+ * @param decision
+ *   Decision from `protect()`.
+ * @returns
+ *   Nothing.
  */
 function setRateLimitHeaders(value, decision) {
     const rateLimitReasons = decision.results

package/package.json

@@ -1,7 +1,13 @@
 {
   "name": "@arcjet/decorate",
-  "version": "1.0.0-beta.8",
+  "version": "1.0.0",
   "description": "Arcjet utilities for decorating responses with information",
+  "keywords": [
+    "arcjet",
+    "decore",
+    "utility",
+    "util"
+  ],
   "license": "Apache-2.0",
   "homepage": "https://arcjet.com",
   "repository": {
@@ -19,38 +25,34 @@
     "url": "https://arcjet.com"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "type": "module",
   "main": "./index.js",
   "types": "./index.d.ts",
   "files": [
-    "LICENSE",
-    "README.md",
-    "*.js",
-    "*.d.ts",
-    "!*.config.js"
+    "index.d.ts",
+    "index.js"
   ],
   "scripts": {
-    "prepublishOnly": "npm run build",
     "build": "rollup --config rollup.config.js",
     "lint": "eslint .",
-    "pretest": "npm run build",
-    "test": "node --test --experimental-test-coverage"
+    "prepublishOnly": "npm run build",
+    "test-api": "node --test -- test/*.test.js",
+    "test-coverage": "node --experimental-test-coverage --test -- test/*.test.js",
+    "test": "npm run build && npm run lint && npm run test-coverage"
   },
   "dependencies": {
-    "@arcjet/protocol": "1.0.0-beta.8",
-    "@arcjet/sprintf": "1.0.0-beta.8"
+    "@arcjet/protocol": "1.0.0",
+    "@arcjet/sprintf": "1.0.0"
   },
   "devDependencies": {
-    "@arcjet/eslint-config": "1.0.0-beta.8",
-    "@arcjet/rollup-config": "1.0.0-beta.8",
-    "@arcjet/tsconfig": "1.0.0-beta.8",
-    "@rollup/wasm-node": "4.41.1",
-    "@types/node": "18.18.0",
-    "eslint": "9.27.0",
-    "expect": "29.7.0",
-    "typescript": "5.8.3"
+    "@arcjet/eslint-config": "1.0.0",
+    "@arcjet/rollup-config": "1.0.0",
+    "@rollup/wasm-node": "4.55.1",
+    "@types/node": "25.0.8",
+    "eslint": "9.39.2",
+    "typescript": "5.9.3"
   },
   "publishConfig": {
     "access": "public",