@arcjet/redact 1.0.0-beta.8 → 1.0.0

package/README.md

@@ -23,34 +23,62 @@ against common attacks.
 This is the [Arcjet][arcjet] TypeScript and JavaScript sensitive information
 redaction library.
 
-## Installation
+- [npm package (`@arcjet/redact`)](https://www.npmjs.com/package/@arcjet/redact)
+- [GitHub source code (`redact/` in `arcjet/arcjet-js`)](https://github.com/arcjet/arcjet-js/tree/main/redact)
 
-```shell
-npm install -S @arcjet/redact
+## What is this?
+
+This package provides functionality to redact sensitive info.
+The work is done in WebAssembly but is called here from JavaScript.
+
+The WebAssembly files are in [`@arcjet/redact-wasm`][github-arcjet-redact-wasm].
+For more info on why we maintain our WebAssembly and JavaScript projects like
+this,
+see [“What is this?” in the readme of
+`@arcjet/analyze-wasm`][github-arcjet-analyze-wasm-what].
+
+## When should I use this?
+
+You can use this package to redact sensitive information locally.
+You can redact email addresses, credit card numbers, and more.
+It is also possible to reverse the process: to un-redact what was found.
+
+## Install
+
+This package is ESM only.
+Install with npm in Node.js:
+
+```sh
+npm install @arcjet/redact
 ```
 
 ## Reference
 
 The full reference documentation can be found in the [Arcjet docs][redact-ref].
 
-## Example
+## Use
+
+```ts
+import { redact } from "@arcjet/redact";
+
+const value = "Hi, my name is John and my email adress is john@example.com";
 
-```typescript
-const text = "Hi, my name is John and my email adress is john@example.com";
-const [redacted, unredact] = await redact(text, {
-  redact: ["email", "phone-number"],
+const [redacted, unredact] = await redact(value, {
+  entities: ["email", "phone-number"],
 });
 console.log(redacted);
-// Hi, my name is John and my email address is <Redacted email #0>
+// => "Hi, my name is John and my email adress is <Redacted email #0>"
 
 const unredacted = unredact("Your email address is <Redacted email #0>");
-console.log(unredacted); // Your email address is john@example.com
+console.log(unredacted); // "Your email address is john@example.com"
 ```
 
 ## License
 
-Licensed under the [Apache License, Version 2.0][apache-license].
+[Apache License, Version 2.0][apache-license] © [Arcjet Labs, Inc.][arcjet]
 
+[apache-license]: http://www.apache.org/licenses/LICENSE-2.0
 [arcjet]: https://arcjet.com
 [redact-ref]: https://docs.arcjet.com/redact/reference
-[apache-license]: http://www.apache.org/licenses/LICENSE-2.0
+[github-arcjet-analyze-wasm-what]: https://github.com/arcjet/arcjet-js/tree/main/analyze-wasm#what-is-this
+[github-arcjet-redact-wasm]: https://github.com/arcjet/arcjet-js/tree/main/redact-wasm

package/index.d.ts

@@ -1,12 +1,68 @@
-export type ArcjetSensitiveInfoType = "email" | "phone-number" | "ip-address" | "credit-card-number";
-type DetectSensitiveInfoEntities<T> = (tokens: string[]) => Array<ArcjetSensitiveInfoType | T | undefined>;
-type ValidEntities<Detect> = Array<undefined extends Detect ? ArcjetSensitiveInfoType : Detect extends DetectSensitiveInfoEntities<infer CustomEntities> ? ArcjetSensitiveInfoType | CustomEntities : never>;
-export type RedactOptions<Detect> = {
-    entities?: ValidEntities<Detect>;
+import type { SensitiveInfoEntity } from "@arcjet/redact-wasm";
+/**
+ * Types of standard sensitive information that can be detected.
+ */
+export type ArcjetSensitiveInfoType = Exclude<SensitiveInfoEntity["tag"], "custom">;
+/**
+ * Options for the `redact` function.
+ *
+ * @template DetectedEntities
+ *   Custom entity names that are returned from `detect` and optionally listed in `entities`.
+ * @template ListedEntities
+ *   Entity names that can be listed in the `entities` option.
+ */
+export type RedactOptions<DetectedEntities extends string | undefined = undefined, ListedEntities extends ArcjetSensitiveInfoType | Exclude<DetectedEntities, undefined> = ArcjetSensitiveInfoType | Exclude<DetectedEntities, undefined>> = {
+    /**
+     * Entities to redact.
+     */
+    entities?: ReadonlyArray<ListedEntities | Exclude<DetectedEntities, undefined>>;
+    /**
+     * Size of tokens to consider.
+     */
     contextWindowSize?: number;
-    detect?: Detect;
-    replace?: (entity: ValidEntities<Detect>[number], plaintext: string) => string | undefined;
+    /**
+     * Custom detection function to identify sensitive information.
+     *
+     * @template DetectedEntities
+     *   Custom entity names that are returned from `detect` and optionally listed in `entities`.
+     * @template ListedEntities
+     *   Entity names that can be listed in the `entities` option.
+     * @param tokens
+     *   Tokens.
+     * @returns
+     *   List of entities (or undefined).
+     */
+    detect?: (tokens: string[]) => ReadonlyArray<DetectedEntities>;
+    /**
+     * Custom replace function to redact sensitive information.
+     *
+     * @template DetectedEntities
+     *   Custom entity names that are returned from `detect` and optionally listed in `entities`.
+     * @template ListedEntities
+     *   Entity names that can be listed in the `entities` option.
+     * @param entity
+     *   Entity to redact.
+     * @param plaintext
+     *   The plaintext string to redact.
+     * @returns
+     *   Redacted string or nothing.
+     */
+    replace?: (entity: ListedEntities, plaintext: string) => string | undefined;
 };
 type Unredact = (input: string) => string;
-export declare function redact<const Detect extends DetectSensitiveInfoEntities<CustomEntities> | undefined, const CustomEntities extends string>(candidate: string, options?: RedactOptions<Detect>): Promise<[string, Unredact]>;
+/**
+ * Redact sensitive info.
+ *
+ * @template DetectedEntities
+ *   Custom entity names that are returned from `detect` and optionally listed in `entities`.
+ * @template ListedEntities
+ *   Entity names that can be listed in the `entities` option.
+ * @param candidate
+ *   Value to redact.
+ * @param options
+ *   Configuration.
+ * @returns
+ *   Promise to a tuple with the redacted string and a function to unredact it.
+ */
+export declare function redact<const DetectedEntities extends string | undefined = undefined, const ListedEntities extends ArcjetSensitiveInfoType | Exclude<DetectedEntities, undefined> = ArcjetSensitiveInfoType | Exclude<DetectedEntities, undefined>>(candidate: string, options?: RedactOptions<DetectedEntities, ListedEntities>): Promise<[string, Unredact]>;
 export {};

package/index.js

@@ -4,17 +4,11 @@ function userEntitiesToWasm(entity) {
     if (typeof entity !== "string") {
         throw new Error("redaction entities must be strings");
     }
-    if (entity === "email") {
-        return { tag: "email" };
-    }
-    if (entity === "phone-number") {
-        return { tag: "phone-number" };
-    }
-    if (entity === "ip-address") {
-        return { tag: "ip-address" };
-    }
-    if (entity === "credit-card-number") {
-        return { tag: "credit-card-number" };
+    if (entity === "credit-card-number" ||
+        entity === "email" ||
+        entity === "ip-address" ||
+        entity === "phone-number") {
+        return { tag: entity };
     }
     return {
         tag: "custom",
@@ -22,17 +16,11 @@ function userEntitiesToWasm(entity) {
     };
 }
 function wasmEntitiesToString(entity) {
-    if (entity.tag === "email") {
-        return "email";
-    }
-    if (entity.tag === "ip-address") {
-        return "ip-address";
-    }
-    if (entity.tag === "credit-card-number") {
-        return "credit-card-number";
-    }
-    if (entity.tag === "phone-number") {
-        return "phone-number";
+    if (entity.tag === "credit-card-number" ||
+        entity.tag === "email" ||
+        entity.tag === "ip-address" ||
+        entity.tag === "phone-number") {
+        return entity.tag;
     }
     return entity.val;
 }
@@ -50,26 +38,31 @@ function noOpReplace(_input, _plaintext) {
 }
 function getWasmOptions(options) {
     if (typeof options === "object" && options !== null) {
-        if (typeof options.entities !== "undefined") {
-            if (Array.isArray(options.entities)) {
-                if (options.entities.length < 1) {
-                    throw new Error("no entities configured for redaction");
-                }
-            }
-            else {
+        const entities = options.entities;
+        if (entities !== undefined) {
+            if (!Array.isArray(entities)) {
                 throw new Error("entities must be an array");
             }
+            if (entities.length < 1) {
+                throw new Error("no entities configured for redaction");
+            }
         }
-        return {
-            entities: options.entities?.map(userEntitiesToWasm),
-            contextWindowSize: options.contextWindowSize || 1,
-            skipCustomDetect: typeof options.detect !== "function",
-            skipCustomRedact: typeof options.replace !== "function",
-        };
+        // `entities` is an optional field but not allowed to be `undefined`.
+        return entities
+            ? {
+                entities: entities.map(userEntitiesToWasm),
+                contextWindowSize: options.contextWindowSize || 1,
+                skipCustomDetect: typeof options.detect !== "function",
+                skipCustomRedact: typeof options.replace !== "function",
+            }
+            : {
+                contextWindowSize: options.contextWindowSize || 1,
+                skipCustomDetect: typeof options.detect !== "function",
+                skipCustomRedact: typeof options.replace !== "function",
+            };
     }
     else {
         return {
-            entities: undefined,
             contextWindowSize: 1,
             skipCustomDetect: true,
             skipCustomRedact: true,
@@ -109,6 +102,20 @@ async function callRedactWasm(candidate, options) {
         throw new Error("redact failed to run because Wasm is not supported in this environment");
     }
 }
+/**
+ * Redact sensitive info.
+ *
+ * @template DetectedEntities
+ *   Custom entity names that are returned from `detect` and optionally listed in `entities`.
+ * @template ListedEntities
+ *   Entity names that can be listed in the `entities` option.
+ * @param candidate
+ *   Value to redact.
+ * @param options
+ *   Configuration.
+ * @returns
+ *   Promise to a tuple with the redacted string and a function to unredact it.
+ */
 async function redact(candidate, options) {
     const redactions = await callRedactWasm(candidate, options);
     // Need to apply the redactions in reverse order so that the offsets aren't changed

package/package.json

@@ -1,7 +1,13 @@
 {
   "name": "@arcjet/redact",
-  "version": "1.0.0-beta.8",
+  "version": "1.0.0",
   "description": "Arcjet sensitive information redaction library",
+  "keywords": [
+    "arcjet",
+    "redact",
+    "utility",
+    "util"
+  ],
   "license": "Apache-2.0",
   "homepage": "https://arcjet.com",
   "repository": {
@@ -19,37 +25,33 @@
     "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/redact-wasm": "1.0.0-beta.8"
+    "@arcjet/redact-wasm": "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",