field-redactor 1.2.0 → 1.5.0

package/dist/types.js

@@ -1,6 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CustomObjectMatchType = void 0;
+exports.isJsonObject = exports.CustomObjectMatchType = void 0;
+/**
+ * Per-field redaction mode inside a {@link CustomObject} schema.
+ * Values align with the top-level doc labels: Shallow, Deep, Opaque (Full), Remove (Delete).
+ */
 var CustomObjectMatchType;
 (function (CustomObjectMatchType) {
     CustomObjectMatchType[CustomObjectMatchType["Delete"] = 0] = "Delete";
@@ -10,4 +14,6 @@ var CustomObjectMatchType;
     CustomObjectMatchType[CustomObjectMatchType["Pass"] = 4] = "Pass";
     CustomObjectMatchType[CustomObjectMatchType["Ignore"] = 5] = "Ignore";
 })(CustomObjectMatchType || (exports.CustomObjectMatchType = CustomObjectMatchType = {}));
+const isJsonObject = (value) => !!value && typeof value === 'object' && !(value instanceof Date) && !Array.isArray(value);
+exports.isJsonObject = isJsonObject;
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;AAEA,IAAY,qBAOX;AAPD,WAAY,qBAAqB;IAC/B,qEAAM,CAAA;IACN,iEAAI,CAAA;IACJ,iEAAI,CAAA;IACJ,uEAAO,CAAA;IACP,iEAAI,CAAA;IACJ,qEAAM,CAAA;AACR,CAAC,EAPW,qBAAqB,qCAArB,qBAAqB,QAOhC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;AA4CA;;;GAGG;AACH,IAAY,qBAOX;AAPD,WAAY,qBAAqB;IAC/B,qEAAM,CAAA;IACN,iEAAI,CAAA;IACJ,iEAAI,CAAA;IACJ,uEAAO,CAAA;IACP,iEAAI,CAAA;IACJ,qEAAM,CAAA;AACR,CAAC,EAPW,qBAAqB,qCAArB,qBAAqB,QAOhC;AAkGM,MAAM,YAAY,GAAG,CAAC,KAA4B,EAAuB,EAAE,CAChF,CAAC,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,CAAC,KAAK,YAAY,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAD/E,QAAA,YAAY,gBACmE"}

package/dist/valuePatternMatcher.d.ts

@@ -0,0 +1,15 @@
+import { RedactablePrimitive } from './types';
+/**
+ * Opt-in regex matching against scalar **values** (not key names).
+ * Applied only when key-based rules do not already redact the field.
+ */
+export declare class ValuePatternMatcher {
+    private readonly patterns;
+    constructor(patterns?: RegExp[]);
+    hasPatterns(): boolean;
+    findMatching(value: RedactablePrimitive | undefined): RegExp | undefined;
+    formatPattern(regex: RegExp): string;
+}
+/** Shared empty matcher for tests and configs without value patterns. */
+export declare const EMPTY_VALUE_PATTERN_MATCHER: ValuePatternMatcher;
+//# sourceMappingURL=valuePatternMatcher.d.ts.map

package/dist/valuePatternMatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"valuePatternMatcher.d.ts","sourceRoot":"","sources":["../src/valuePatternMatcher.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAE9C;;;GAGG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAW;gBAExB,QAAQ,CAAC,EAAE,MAAM,EAAE;IAIxB,WAAW,IAAI,OAAO;IAItB,YAAY,CAAC,KAAK,EAAE,mBAAmB,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS;IASxE,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;CAG5C;AAED,yEAAyE;AACzE,eAAO,MAAM,2BAA2B,qBAA4B,CAAC"}

package/dist/valuePatternMatcher.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EMPTY_VALUE_PATTERN_MATCHER = exports.ValuePatternMatcher = void 0;
+const regexUtils_1 = require("./regexUtils");
+/**
+ * Opt-in regex matching against scalar **values** (not key names).
+ * Applied only when key-based rules do not already redact the field.
+ */
+class ValuePatternMatcher {
+    constructor(patterns) {
+        this.patterns = patterns !== null && patterns !== void 0 ? patterns : [];
+    }
+    hasPatterns() {
+        return this.patterns.length > 0;
+    }
+    findMatching(value) {
+        if (value === undefined || value === null || typeof value === 'boolean') {
+            return undefined;
+        }
+        const text = String(value);
+        return this.patterns.find((pattern) => pattern.test(text));
+    }
+    formatPattern(regex) {
+        return (0, regexUtils_1.formatRegExp)(regex);
+    }
+}
+exports.ValuePatternMatcher = ValuePatternMatcher;
+/** Shared empty matcher for tests and configs without value patterns. */
+exports.EMPTY_VALUE_PATTERN_MATCHER = new ValuePatternMatcher();
+//# sourceMappingURL=valuePatternMatcher.js.map

package/dist/valuePatternMatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"valuePatternMatcher.js","sourceRoot":"","sources":["../src/valuePatternMatcher.ts"],"names":[],"mappings":";;;AAAA,6CAA4C;AAG5C;;;GAGG;AACH,MAAa,mBAAmB;IAG9B,YAAY,QAAmB;QAC7B,IAAI,CAAC,QAAQ,GAAG,QAAQ,aAAR,QAAQ,cAAR,QAAQ,GAAI,EAAE,CAAC;IACjC,CAAC;IAEM,WAAW;QAChB,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;IAClC,CAAC;IAEM,YAAY,CAAC,KAAsC;QACxD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;YACxE,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC3B,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAC7D,CAAC;IAEM,aAAa,CAAC,KAAa;QAChC,OAAO,IAAA,yBAAY,EAAC,KAAK,CAAC,CAAC;IAC7B,CAAC;CACF;AAvBD,kDAuBC;AAED,yEAAyE;AAC5D,QAAA,2BAA2B,GAAG,IAAI,mBAAmB,EAAE,CAAC"}

package/docs/guides/anti-patterns.md

@@ -0,0 +1,107 @@
+# Configuration anti-patterns
+
+Common mistakes when configuring Field Redactor — and what to do instead. Many of these are also surfaced as `configWarnings` at construction time; set `strict: true` to fail fast in tests.
+
+## Using `new FieldRedactor()` without rules
+
+**Problem:** With no `secretKeys`, `deepSecretKeys`, `fullSecretKeys`, `deleteSecretKeys`, or `customObjects`, every value is redacted. Easy to ship a config that wipes entire payloads.
+
+**Instead:** Use `FieldRedactor.createSafe()`, `FieldRedactorConfigBuilder.buildSafeRedactor()`, or the builder with at least one explicit rule.
+
+```typescript
+// Avoid
+const redactor = new FieldRedactor();
+
+// Prefer
+const redactor = FieldRedactor.createSafe({ secretKeys: [/email/i] });
+```
+
+## Same regex in multiple key groups
+
+**Problem:** `/email/i` in both `secretKeys` and `deepSecretKeys` is confusing — only the higher-precedence group applies (Opaque → Deep → Remove → Shallow).
+
+**Instead:** Pick one mode per pattern. Use `dryRun()` and inspect `report.pathRules` to confirm which rule fired.
+
+```typescript
+const { report } = redactor.dryRunSync(sample);
+// report.pathRules → [{ path: 'email', action: 'redact', rule: 'shallow', pattern: '/email/i' }]
+```
+
+## Global (`g`) regex flags
+
+**Problem:** Global regexes can leave `lastIndex` set and make repeated `.test()` calls unreliable.
+
+**Instead:** Remove the `g` flag from config patterns.
+
+```typescript
+// Avoid
+secretKeys: [/email/gi]
+
+// Prefer
+secretKeys: [/email/i]
+```
+
+## Overlapping schemas
+
+**Problem:** Two `customObjects` where one schema’s keys are a subset of another’s can both match the same object. Only the schema with **more keys** wins.
+
+**Instead:** Make schemas disjoint, or order specificity by adding distinguishing keys to the more specific schema.
+
+## Identical schema key sets
+
+**Problem:** Two schemas with the exact same keys throw `FieldRedactorConfigurationError` at construction.
+
+**Instead:** Merge into one schema or differentiate the key sets.
+
+## Schema sibling reference typos
+
+**Problem:** `value: 'name'` in a schema requires a `name` key on the schema object. A typo references a sibling that is not part of the schema definition.
+
+**Instead:** Ensure every string sibling reference appears as a key on the schema. The validator warns when it does not.
+
+## Relying on schemas when keys are stable
+
+**Problem:** `customObjects` add complexity. If field names alone identify sensitive data (`password`, `ssn`), schemas are unnecessary.
+
+**Instead:** Use Shallow / Deep / Opaque / Remove on key names. Reserve schemas for sibling-key patterns like `{ name, value }`.
+
+## Expecting value-based detection
+
+**Problem:** `secretKeys: [/email/]` matches **key names**, not values. A field named `description` containing `alice@example.com` is not redacted by key rules alone.
+
+**Instead:** Opt in to **value-pattern** redaction with `valuePatterns`, add a schema when sensitivity depends on a sibling, or add explicit keys.
+
+```typescript
+FieldRedactor.createSafe({
+  valuePatterns: [/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/]
+});
+```
+
+See [Value-pattern redaction](value-pattern-redaction.md).
+
+## Ignoring `dryRun` before production
+
+**Problem:** Guessing which paths change on real log shapes.
+
+**Instead:** Run `dryRunSync()` on representative payloads and review `redactedPaths`, `deletedPaths`, `matchedSchemas`, and `pathRules`.
+
+```typescript
+FieldRedactorConfigBuilder.create()
+  .usePreset(presets.applicationLogging())
+  .shallow(/ssn/i)
+  .buildSafeRedactor()
+  .dryRunSync(productionSample);
+```
+
+## Mutating shared references unintentionally
+
+**Problem:** With `cloneInput: false`, `redact()` mutates the input. Shared object references elsewhere in the process may change.
+
+**Instead:** Keep the default `cloneInput: true` (copy-on-write) unless you intentionally own the input object.
+
+## Related guides
+
+- [Secret key modes](secret-key-modes.md)
+- [Metadata redaction](metadata-redaction.md)
+- [Value-pattern redaction](value-pattern-redaction.md)
+- [Configuration reference](../reference/config.md)

package/docs/guides/metadata-redaction.md

@@ -0,0 +1,112 @@
+# Metadata redaction
+
+Many log payloads encode sensitivity in **sibling fields** rather than key names:
+
+```json
+{
+  "name": "email",
+  "type": "String",
+  "value": "foo.bar@example.com"
+}
+```
+
+Redacting every `value` field destroys useful debug output. Instead, use a **Schema** (`customObjects`) so `value` is redacted only when `name` matches your Shallow / Deep / Opaque / Remove rules.
+
+## Schema matching
+
+An object matches a `CustomObject` schema when it contains **every key defined in the schema**. Extra keys on the input are allowed.
+
+When multiple schemas match, the one with the **most keys** wins.
+
+```typescript
+import { CustomObject, CustomObjectMatchType } from 'field-redactor';
+
+const metadataSchema: CustomObject = {
+  name: CustomObjectMatchType.Ignore,
+  type: CustomObjectMatchType.Ignore,
+  value: 'name' // sibling key: test `name`'s value against secretKeys
+};
+
+// Matches: { name: "email", type: "String", value: "foo@bar.com", id: 12 }
+// Does not match: { name: "email", value: "foo@bar.com" } — missing required "type"
+```
+
+## Sibling key rules
+
+When a schema field is a **string** (e.g. `value: 'name'`), that string names a sibling key. The sibling's **value** is tested against `secretKeys`, `deepSecretKeys`, `fullSecretKeys`, and `deleteSecretKeys`.
+
+Falsy sibling values (`""`, `0`, `false`) are evaluated when the sibling key is present.
+
+```typescript
+import { CustomObjectMatchType, FieldRedactor } from 'field-redactor';
+
+const fieldRedactor = new FieldRedactor({
+  secretKeys: [/email/],
+  customObjects: [
+    {
+      name: CustomObjectMatchType.Ignore,
+      type: CustomObjectMatchType.Ignore,
+      value: 'name'
+    }
+  ]
+});
+
+await fieldRedactor.redact({ name: 'email', type: 'String', value: 'foo@bar.com', id: 12 });
+// → value redacted, id unchanged
+
+await fieldRedactor.redact({ name: 'traceId', type: 'String', value: 'abc-123', id: 10 });
+// → value unchanged
+```
+
+## Builder with named schemas
+
+Name schemas to improve `dryRun` reports:
+
+```typescript
+import { CustomObjectMatchType, FieldRedactorConfigBuilder } from 'field-redactor';
+
+const redactor = FieldRedactorConfigBuilder.create()
+  .shallow(/email/i, /password/i, /phone/i)
+  .remove(/authKey/i)
+  .schema(
+    { name: CustomObjectMatchType.Ignore, type: CustomObjectMatchType.Ignore, value: 'name' },
+    { name: 'metadata-entry' }
+  )
+  .buildSafeRedactor();
+
+const { report } = redactor.dryRunSync({
+  metadata: [{ name: 'email', type: 'String', value: 'alice@example.com' }]
+});
+// report.matchedSchemas → [{ path: 'metadata[0]', schemaIndex: 0, schemaName: 'metadata-entry' }]
+```
+
+## Per-field modes (`CustomObjectMatchType`)
+
+Inside a schema, use enum values instead of sibling strings:
+
+| Enum | Doc label | Effect |
+| --- | --- | --- |
+| `Delete` | Remove | Delete the field |
+| `Full` | Opaque | Stringify and redact |
+| `Deep` | Deep | Deep redaction |
+| `Shallow` | Shallow | Redact scalar / primitive arrays |
+| `Pass` | — | Revert to normal traversal for nested content |
+| `Ignore` | — | Skip the field |
+
+## Preset: logging metadata
+
+```typescript
+import { FieldRedactor, presets } from 'field-redactor';
+
+const redactor = FieldRedactor.createSafe({
+  ...presets.loggingMetadata(),
+  secretKeys: [/email/i, /ssn/i]
+});
+```
+
+`presets.loggingMetadata()` includes `{ name, type, value }` schema and `deleteSecretKeys: [/authKey/i]`.
+
+## Related
+
+- [Secret key modes](secret-key-modes.md) — Shallow / Deep / Opaque / Remove
+- [Configuration reference](../reference/config.md) — full schema reference and examples

package/docs/guides/migration-1.2-to-1.5.md

@@ -0,0 +1,106 @@
+# Migration: npm 1.2.x → 1.5.0
+
+This guide covers upgrading from the last published npm line (**1.2.0**) to **1.5.0**, which bundles **v1.2.1**–**v1.3.0** git work plus Phase 2 DX polish and value-pattern redaction.
+
+## Install
+
+```bash
+npm install field-redactor@1.5.0
+# or
+yarn add field-redactor@1.5.0
+```
+
+## Breaking or behavior-sensitive changes
+
+### 1. Copy-on-write instead of full deep clone
+
+`redact()` and `redactSync()` no longer deep-clone the entire input first. Unmodified nested objects may **share references** with the input.
+
+```typescript
+// If tests assert result.child !== input.child for untouched branches, update expectations.
+// To mutate the input in place (old clone-then-mutate semantics on the copy):
+new FieldRedactor({ secretKeys: [/email/], cloneInput: false });
+```
+
+### 2. Relaxed custom object schema matching
+
+Schemas match when the input object contains **every** schema key. Extra keys on the input are allowed (previously required an exact key set in some cases).
+
+### 3. Configuration warnings
+
+`new FieldRedactor()` without explicit rules still redacts all values (legacy default) but now emits warnings. Use:
+
+```typescript
+FieldRedactor.createSafe({ secretKeys: [/email/i] });
+// or
+FieldRedactorConfigBuilder.create().shallow(/email/i).buildSafeRedactor();
+// or
+new FieldRedactor({ strict: true, secretKeys: [/email/i] });
+```
+
+## Recommended new APIs
+
+| Goal | API |
+| --- | --- |
+| Avoid accidental full redaction | `FieldRedactor.createSafe()`, `buildSafeRedactor()` |
+| Faster sync pipelines | `redactSync()`, `redactInPlaceSync()` |
+| Tune regexes / schemas | `dryRunSync()` → `report.redactedPaths`, `pathRules` |
+| Start from known fixtures | `presets.applicationLogging()`, `.usePreset()` |
+| PII in free-text values | `valuePatterns` or `.valuePattern()` |
+
+## Step-by-step upgrade
+
+### Step 1 — Audit current config
+
+```typescript
+import { validateFieldRedactorConfig } from 'field-redactor';
+
+const warnings = validateFieldRedactorConfig(yourConfig);
+console.log(warnings);
+```
+
+### Step 2 — Preview on real payloads
+
+```typescript
+const redactor = FieldRedactor.createSafe(yourConfig);
+const { result, report } = redactor.dryRunSync(samplePayload);
+// Review report.pathRules, report.matchedSchemas, report.deletedPaths
+```
+
+### Step 3 — Switch hot paths to sync (optional)
+
+If you use the default or `syncRedactor` and do not need async `redactor`:
+
+```typescript
+// Before
+const out = await redactor.redact(payload);
+
+// After
+const out = redactor.redactSync(payload);
+```
+
+### Step 4 — Add value patterns (optional)
+
+Only when sensitivity is in **values**, not key names:
+
+```typescript
+FieldRedactorConfigBuilder.create()
+  .shallow(/email/i, /password/i)
+  .valuePattern(/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/)
+  .buildSafeRedactor();
+```
+
+Value patterns run at **lowest precedence** — after schema and all key-based rules.
+
+## Fixes you get for free
+
+- **Falsy sibling keys** — `metadata: { name: 'email', value: '' }` redacts correctly when the sibling is present.
+- **`ignoreBooleans` default** — documented as `false` (booleans are redacted unless you opt out).
+- **Exported errors** — `FieldRedactorError`, `FieldRedactorConfigurationError`.
+- **Stronger typing** — `JsonValue`, `RedactableInput`, generic `redact<T>()`.
+
+## Further reading
+
+- [Release notes v1.5.0](../release-notes/v1.5.0.md)
+- [Release notes v1.3.0](../release-notes/v1.3.0.md) — detailed 1.3.0 feature breakdown
+- [Anti-patterns](anti-patterns.md)

package/docs/guides/secret-key-modes.md

@@ -0,0 +1,108 @@
+# Secret key modes
+
+FieldRedactor applies **Shallow**, **Deep**, **Opaque**, and **Remove** rules via regex key matching. Throughout the docs, these are the conceptual names; the config fields are `secretKeys`, `deepSecretKeys`, `fullSecretKeys`, and `deleteSecretKeys`.
+
+**Precedence** (highest wins): Schema (`customObjects`) → Opaque → Deep → Remove → Shallow → Value-pattern (`valuePatterns`)
+
+## Cheat sheet
+
+Same input for every row:
+
+```json
+{
+  "username": "alice",
+  "contactInfo": { "email": "alice@example.com", "city": "NYC" },
+  "authKey": "secret-token"
+}
+```
+
+| Mode | Config field | Example | Result |
+| --- | --- | --- | --- |
+| **Shallow** | `secretKeys` | `[/email/]` | `contactInfo.email` → `"REDACTED"`; `city`, `username` unchanged |
+| **Deep** | `deepSecretKeys` | `[/contactInfo/]` | All primitives inside `contactInfo` redacted |
+| **Opaque** | `fullSecretKeys` | `[/contactInfo/]` | Entire `contactInfo` replaced with `"REDACTED"` |
+| **Remove** | `deleteSecretKeys` | `[/authKey/]` | `authKey` key removed from output |
+
+### Builder API
+
+```typescript
+import { FieldRedactorConfigBuilder } from 'field-redactor';
+
+const config = FieldRedactorConfigBuilder.create()
+  .shallow(/email/i)
+  .deep(/contactInfo/i)
+  .opaque(/rawPayload/i)
+  .remove(/authKey/i)
+  .build();
+```
+
+## Shallow (`secretKeys`)
+
+Redact matching keys' scalar values without deep-walking child objects. If **no** redaction rules of any type are configured, every value is treated as Shallow (all fields redacted).
+
+```typescript
+import { FieldRedactor } from 'field-redactor';
+
+const fieldRedactor = new FieldRedactor({
+  secretKeys: [/email/i, /name/i, /userid/i]
+});
+
+await fieldRedactor.redact({
+  userId: 271,
+  contactInfo: { email: 'foo@bar.com', firstName: 'Foo', Salutation: 'Mr.' }
+});
+// → userId, email, firstName redacted; Salutation unchanged
+```
+
+Nested objects keep normal traversal rules; primitives inside arrays at matching keys are redacted.
+
+## Deep (`deepSecretKeys`)
+
+Redact matching keys and **all** descendant primitives. Higher precedence than Shallow.
+
+```typescript
+const fieldRedactor = new FieldRedactor({
+  deepSecretKeys: [/contactInfo/i]
+});
+
+await fieldRedactor.redact({
+  contactInfo: {
+    email: 'foo@bar.com',
+    lastUpdatedBy: { id: 1 }
+  }
+});
+// → email, id, and other primitives under contactInfo are redacted
+```
+
+## Opaque (`fullSecretKeys`)
+
+Stringify the entire value at matching keys, then redact. Typical for objects and arrays you want to hide completely.
+
+```typescript
+const fieldRedactor = new FieldRedactor({
+  fullSecretKeys: [/contactInfo/i]
+});
+
+await fieldRedactor.redact({
+  contactInfo: { email: 'foo@bar.com', firstName: 'Foo' }
+});
+// → { contactInfo: "REDACTED" }
+```
+
+## Remove (`deleteSecretKeys`)
+
+Delete matching keys from the output.
+
+```typescript
+const fieldRedactor = new FieldRedactor({
+  deleteSecretKeys: [/authKey/i]
+});
+
+await fieldRedactor.redact({ userId: 271, appAuthKey: '12345' });
+// → { userId: 271 }
+```
+
+## Related
+
+- [Metadata redaction](metadata-redaction.md) — when sensitivity depends on sibling fields
+- [Configuration reference](../reference/config.md) — all options and API details

package/docs/guides/value-pattern-redaction.md

@@ -0,0 +1,58 @@
+# Value-pattern redaction
+
+Opt-in redaction for scalar fields whose **value** matches a regex, regardless of key name. Use this when PII appears in free-text fields (`description`, `message`, `body`) that are not named like the data they contain.
+
+Value-pattern rules are **lowest precedence**: they run only when Shallow, Deep, Opaque, Remove, and Schema rules leave the field unchanged.
+
+## When to use
+
+| Situation | Approach |
+| --- | --- |
+| Key name identifies sensitivity (`password`, `email`) | Shallow / Deep / Opaque / Remove |
+| Sensitivity depends on a sibling (`{ name, value }`) | Schema |
+| PII may appear in arbitrary string fields | **Value-pattern** (`valuePatterns`) |
+
+## Configuration
+
+```typescript
+import { FieldRedactor, FieldRedactorConfigBuilder } from 'field-redactor';
+
+const emailPattern = /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/;
+
+// Plain config — valuePatterns-only is valid with createSafe()
+const redactor = FieldRedactor.createSafe({
+  valuePatterns: [emailPattern]
+});
+
+// Builder
+const built = FieldRedactorConfigBuilder.create()
+  .valuePattern(emailPattern, /\b\d{3}-\d{2}-\d{4}\b/) // SSN-shaped values
+  .shallow(/password/i) // key rules still apply
+  .buildSafeRedactor();
+```
+
+## Behavior
+
+- Matches **strings** and **numbers** (tested via `String(value)`). Booleans, `null`, and `undefined` are skipped.
+- Does not run inside Deep or Opaque subtrees that already redact all primitives.
+- Combine with key rules for defense in depth: key names catch structured fields; value patterns catch embedded PII in free text.
+
+```typescript
+const input = {
+  email: 'alice@example.com', // shallow key rule
+  description: 'Email alice@example.com' // value pattern
+};
+
+const { report } = redactor.dryRunSync(input);
+// pathRules → shallow on `email`, value on `description`
+```
+
+## dryRun attribution
+
+Redactions from value patterns appear in `report.pathRules` with `rule: 'value'` and the matching regex in `pattern`.
+
+## Related
+
+- [Secret key modes](secret-key-modes.md) — key-name rules
+- [Anti-patterns](anti-patterns.md) — do not confuse key rules with value detection
+- [Configuration reference](../reference/config.md)