field-redactor 1.1.0 → 1.5.0

package/docs/reference/config.md

@@ -0,0 +1,135 @@
+# Configuration reference
+
+## Overview
+
+| Doc label | Config field | Type | Default | Effect |
+|-----------|--------------|------|---------|--------|
+| — | `redactor` | `(val) => Promise<string>` | `"REDACTED"` async | Custom async redactor; enables async traversal when sole redactor |
+| — | `syncRedactor` | `(val) => string` | `"REDACTED"` sync | Sync redactor; enables `redactSync()` without per-field Promises |
+| **Shallow** | `secretKeys` | `RegExp[]` | `null` | Redact matching scalar values; if no rules at all, everything matches |
+| **Deep** | `deepSecretKeys` | `RegExp[]` | `[]` | Deeply redact all primitives under matching keys |
+| **Opaque** | `fullSecretKeys` | `RegExp[]` | `[]` | Stringify and redact entire values |
+| **Remove** | `deleteSecretKeys` | `RegExp[]` | `[]` | Delete matching keys |
+| **Schema** | `customObjects` | `CustomObject[]` | `[]` | Per-shape rules; see [metadata guide](../guides/metadata-redaction.md) |
+| **Value-pattern** | `valuePatterns` | `RegExp[]` | `[]` | Opt-in: redact scalars whose string form matches a pattern |
+| — | `schemaNames` | `string[]` | — | Optional labels parallel to `customObjects` for `dryRun` reports |
+| — | `ignoreBooleans` | `boolean` | `false` | Skip boolean redaction when `true` |
+| — | `ignoreNullOrUndefined` | `boolean` | `true` | Skip null/undefined redaction when `true` |
+| — | `cloneInput` | `boolean` | `true` | Copy-on-write for `redact()` / `redactSync()` |
+| — | `strict` | `boolean` | `false` | Throw on config warnings when `true` |
+| — | `onConfigWarning` | `(msg) => void` | — | Callback for non-fatal config warnings |
+
+## FieldRedactor API
+
+| Method | Returns | Notes |
+|--------|---------|-------|
+| `redact(value)` | `Promise<T>` | Copy-on-write by default |
+| `redactSync(value)` | `T` | Sync path when no async-only `redactor` |
+| `redactInPlace(value)` | `Promise<void>` | Mutates traversable input |
+| `redactInPlaceSync(value)` | `void` | Sync in-place |
+| `dryRun(value)` | `Promise<{ result, report }>` | Redact + path audit |
+| `dryRunSync(value)` | `{ result, report }` | Sync dry run |
+| `configWarnings` | `readonly string[]` | Warnings from construction |
+
+### Static factories
+
+- `FieldRedactor.createSafe(config)` — requires at least one rule; throws `FieldRedactorConfigurationError` otherwise
+- `new FieldRedactor(config)` — legacy; no rules ⇒ redact everything
+
+## Builder API
+
+```typescript
+import { CustomObjectMatchType, FieldRedactorConfigBuilder } from 'field-redactor';
+
+const redactor = FieldRedactorConfigBuilder.create()
+  .usePreset(presets.applicationLogging())
+  .valuePattern(/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/)
+  .shallow(/ssn/i)
+  .deep(/accountInfo/i)
+  .opaque(/rawPayload/i)
+  .remove(/authKey/i)
+  .schema(metadataSchema, { name: 'metadata-entry' })
+  .syncRedactor((val) => `REDACTED:${val}`)
+  .strict()
+  .buildSafeRedactor();
+```
+
+Methods: `shallow`, `deep`, `opaque`, `remove` / `delete`, `schema`, `valuePattern`, `usePreset`, `redactor`, `syncRedactor`, `ignoreBooleans`, `ignoreNullOrUndefined`, `cloneInput`, `strict`, `onConfigWarning`, `build`, `buildRedactor`, `buildSafeRedactor`.
+
+## Configuration validation
+
+```typescript
+import { validateFieldRedactorConfig } from 'field-redactor';
+
+const warnings = validateFieldRedactorConfig({ secretKeys: [/email/] });
+```
+
+Warnings include: no rules configured, duplicate regex across key groups, global regex flag, missing schema sibling keys, overlapping schemas. Set `strict: true` to throw on warnings.
+
+## Presets
+
+```typescript
+import { FieldRedactor, presets } from 'field-redactor';
+
+FieldRedactor.createSafe({
+  ...presets.applicationLogging(),
+  secretKeys: [/ssn/] // extend defaults
+});
+```
+
+| Preset | Contents |
+| --- | --- |
+| `loggingMetadata()` | `{ name, type, value }` schema + auth key removal |
+| `applicationLogging()` | Common PII patterns + event metadata schema |
+| `keyValueEntries()` | `{ key, value }` schema |
+
+## Dry run report
+
+```typescript
+type DryRunReport = {
+  redactedPaths: string[];
+  deletedPaths: string[];
+  matchedSchemas: { path: string; schemaIndex: number; schemaName?: string }[];
+  pathRules: {
+    path: string;
+    action: 'redact' | 'delete';
+    rule: 'schema' | 'opaque' | 'deep' | 'remove' | 'shallow' | 'value' | 'default';
+    pattern?: string;
+    schemaIndex?: number;
+    schemaName?: string;
+  }[];
+};
+```
+
+`pathRules` explains **why** each path changed (which rule matched). Use alongside `redactedPaths` / `deletedPaths` for iteration.
+
+## Errors
+
+| Class | When |
+| --- | --- |
+| `FieldRedactorError` | Redaction failure at runtime |
+| `FieldRedactorConfigurationError` | Invalid config, `createSafe()` with no rules, `strict` warnings |
+
+## `redactor` / `syncRedactor`
+
+Provide `syncRedactor` (or use the default) when you want `redactSync()` without Promise overhead. Async-only `redactor` keeps `redact()` fully async.
+
+```typescript
+import * as crypto from 'crypto';
+import { FieldRedactor, Redactor } from 'field-redactor';
+
+const redactor: Redactor = (val) =>
+  Promise.resolve(crypto.createHash('sha256').update(String(val)).digest('hex'));
+
+const fieldRedactor = new FieldRedactor({ redactor, secretKeys: [/email/] });
+```
+
+## Object schemas (`customObjects`)
+
+Highest precedence. See [Metadata redaction](../guides/metadata-redaction.md) for sibling-key patterns and [Secret key modes](../guides/secret-key-modes.md) for key-based modes.
+
+## Guides
+
+- [Secret key modes](../guides/secret-key-modes.md)
+- [Metadata redaction](../guides/metadata-redaction.md)
+- [Anti-patterns](../guides/anti-patterns.md)

package/docs/release-notes/2.0.0.md

@@ -0,0 +1,19 @@
+# Release notes — 2.0.0
+
+> **Note:** `2.x` tags mark internal development milestones. The published npm line remains `1.x`; feature content through `2.0.0` is included in **v1.3.0**.
+
+## Added
+
+- **`redactSync()`** and **`redactInPlaceSync()`** — synchronous redaction without per-field `Promise` overhead.
+- **`syncRedactor`** config option for a dedicated synchronous redactor function.
+- Shared sync traversal module extracted from the async path.
+
+## Migration
+
+When using the default redactor, prefer `redactSync()` over `await redact()` on hot paths:
+
+```typescript
+const output = redactor.redactSync(payload);
+```
+
+Async `redact()` still works and delegates to the sync path when no async-only `redactor` is configured.

package/docs/release-notes/2.1.0.md

@@ -0,0 +1,17 @@
+# Release notes — 2.1.0
+
+> **Note:** `2.x` tags mark internal development milestones. The published npm line remains `1.x`; feature content through `2.1.0` is included in **v1.3.0**.
+
+## Added
+
+- **Copy-on-write redaction** — `redact()` and `redactSync()` clone only mutated branches (`cloneInput: true` by default).
+- **`cloneInput`** config option — set `false` to mutate the input in place (equivalent to `redactInPlace`).
+
+## Changed
+
+- Replaced upfront full deep clone with structural sharing for default `redact()` / `redactSync()`.
+- Unified in-place and copy-on-write traversal behind a shared `ContainerMutation` layer.
+
+## Behavior note
+
+Unredacted subtrees may share references with the input. If you need every nested object to be a new reference, deep-clone before redacting.

package/docs/release-notes/2.2.0.md

@@ -0,0 +1,16 @@
+# Release notes — 2.2.0
+
+> **Note:** `2.x` tags mark internal development milestones. The published npm line remains `1.x`; feature content through `2.2.0` is included in **v1.3.0**.
+
+## Added
+
+- **`FieldRedactor.createSafe()`** — requires at least one explicit redaction rule.
+- **`dryRun()` / `dryRunSync()`** — returns `{ result, report }` with `redactedPaths`, `deletedPaths`, and `matchedSchemas`.
+- **Configuration validation** — `validateFieldRedactorConfig()`, `configWarnings`, `strict`, `onConfigWarning`.
+- **Presets** — `presets.loggingMetadata()`, `presets.applicationLogging()`, `presets.keyValueEntries()`.
+- Onboarding docs: decision guide, cheat sheet, Shallow/Deep/Opaque/Remove/Schema labels.
+
+```typescript
+const { result, report } = redactor.dryRunSync(sample);
+console.log(report.redactedPaths);
+```

package/docs/release-notes/2.3.0.md

@@ -0,0 +1,17 @@
+# Release notes — 2.3.0
+
+> **Note:** `2.x` tags mark internal development milestones. The published npm line remains `1.x`; feature content through `2.3.0` is included in **v1.3.0**.
+
+## Added
+
+- **`FieldRedactorConfigBuilder`** — fluent API mapping doc labels to config fields.
+- **`schema(..., { name })`** — optional schema names in `dryRun` reports (`schemaName` on `matchedSchemas`).
+- Split documentation: `docs/guides/` and `docs/reference/config.md`.
+
+```typescript
+FieldRedactorConfigBuilder.create()
+  .shallow(/email/i)
+  .remove(/authKey/i)
+  .schema(metadataSchema, { name: 'metadata-entry' })
+  .buildSafeRedactor();
+```

package/docs/release-notes/2.3.1.md

@@ -0,0 +1,17 @@
+# Release notes — 2.3.1
+
+> **Note:** `2.3.1` is the final internal `2.x` milestone before the **v1.3.0** npm release. Package version at this tag is `2.3.1`; the equivalent published version is **v1.3.0**.
+
+## Added
+
+- **`CHANGELOG.md`** — version history for the `1.x` npm line.
+- **`prepublishOnly`** script — runs `yarn build` before npm publish.
+- Release notes for all existing tags under `docs/release-notes/`.
+
+## Changed
+
+- Package version at this tag set to `2.3.1` to match the git tag.
+
+## Published equivalent
+
+For npm consumers, use **v1.3.0** (next commit on `master`). See [v1.3.0.md](v1.3.0.md).

package/docs/release-notes/2.4.0.md

@@ -0,0 +1,30 @@
+# Release notes — 2.4.0
+
+> **Superseded:** This internal milestone is included in npm **[v1.5.0](v1.5.0.md)**. Git tag `2.4.0` has been removed.
+
+## Added
+
+- **`FieldRedactorConfigBuilder.usePreset()`** — merge a `presets.*()` return value (or any partial config) into the builder. Regex arrays and schemas accumulate; scalar options apply only when not already set.
+- **`dryRun` rule attribution** — `report.pathRules` lists each redacted or deleted path with the matching rule (`schema`, `opaque`, `deep`, `remove`, `shallow`, or `default`), optional regex `pattern`, and schema metadata when applicable.
+- **Exported types** — `DryRunPathRule`, `RedactionRuleLabel`, and `MatchedSchemaReport` from the public API.
+- **Anti-patterns guide** — [docs/guides/anti-patterns.md](../guides/anti-patterns.md) documents common configuration mistakes (bare constructor, duplicate regexes, global flags, tuning without `dryRun`).
+
+```typescript
+import { FieldRedactorConfigBuilder, presets } from 'field-redactor';
+
+const redactor = FieldRedactorConfigBuilder.create()
+  .usePreset(presets.applicationLogging())
+  .shallow(/ssn/i)
+  .buildSafeRedactor();
+
+const { report } = redactor.dryRunSync(payload);
+// report.pathRules → [{ path: 'email', action: 'redact', rule: 'shallow', pattern: '/email/i' }, ...]
+```
+
+## Changed
+
+- Package version at this tag set to `2.4.0` to match the git tag.
+
+## Published equivalent
+
+Shipped in **[v1.5.0](v1.5.0.md)** on npm.

package/docs/release-notes/2.5.0.md

@@ -0,0 +1,33 @@
+# Release notes — 2.5.0
+
+> **Superseded:** This internal milestone is included in npm **[v1.5.0](v1.5.0.md)**. Git tag `2.5.0` has been removed.
+
+## Added
+
+- **Value-pattern redaction** — opt-in `valuePatterns: RegExp[]` redacts scalar fields when their string form matches a pattern, regardless of key name. Lowest precedence: runs only when key-based rules leave the value unchanged.
+- **`FieldRedactorConfigBuilder.valuePattern()`** — fluent builder method for `valuePatterns`.
+- **`dryRun` value rule attribution** — `report.pathRules` includes `rule: 'value'` with the matching regex when value-pattern redaction fired.
+- **Value-pattern guide** — [docs/guides/value-pattern-redaction.md](../guides/value-pattern-redaction.md).
+
+```typescript
+import { FieldRedactor, FieldRedactorConfigBuilder } from 'field-redactor';
+
+const emailPattern = /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/;
+
+const redactor = FieldRedactor.createSafe({ valuePatterns: [emailPattern] });
+
+const { report } = redactor.dryRunSync({
+  description: 'Contact alice@example.com',
+  note: 'no pii here'
+});
+// report.pathRules → [{ path: 'description', action: 'redact', rule: 'value', pattern: '...' }]
+```
+
+## Changed
+
+- Package version at this tag set to `2.5.0` to match the git tag.
+- Internal refactor: centralized field-redactor dependency wiring (`fieldRedactorDeps`), shared regex utilities, and simplified dry-run path attribution.
+
+## Published equivalent
+
+Shipped in **[v1.5.0](v1.5.0.md)** on npm.

package/docs/release-notes/2.5.1.md

@@ -0,0 +1,17 @@
+# Release notes — 2.5.1
+
+> **Superseded:** This internal milestone is included in npm **[v1.5.0](v1.5.0.md)**. Git tag `2.5.1` has been removed.
+
+## Changed
+
+- **Unified JSON traversal** — sync in-place, copy-on-write, and async in-place redaction now share `ObjectRedactorTraversal` with a common `ContainerMutation` adapter. `ObjectRedactor` is a thin orchestrator; `ObjectRedactorSyncTraversal` remains as a compatibility alias.
+- **Shared custom-object handlers** — `objectRedactorCustomObject.ts` centralizes match-type `switch` logic used by both sync and async traversal paths.
+- Package version at this tag set to `2.5.1` to match the git tag.
+
+## Fixed
+
+- Async in-place redaction now uses the same `ContainerMutation` path as sync traversal, keeping nested object and array behavior consistent across redaction modes.
+
+## Published equivalent
+
+Shipped in **[v1.5.0](v1.5.0.md)** on npm.

package/docs/release-notes/README.md

@@ -0,0 +1,30 @@
+# Release notes index
+
+Per-version release notes for published **field-redactor** git tags. npm releases use the same `v1.x.x` tag names.
+
+| Version | npm | Notes |
+| --- | --- | --- |
+| **v1.5.0** | Yes | [v1.5.0.md](v1.5.0.md) — DX polish, value patterns, unified traversal |
+| v1.3.0 | No (superseded by 1.5.0) | [v1.3.0.md](v1.3.0.md) — sync API, COW, builder, dryRun, presets |
+| v1.2.2 | No | [v1.2.2.md](v1.2.2.md) |
+| v1.2.1 | No | [v1.2.1.md](v1.2.1.md) |
+| v1.2.0 | Yes | [v1.2.0.md](v1.2.0.md) |
+| v1.1.0 | Yes | [v1.1.0.md](v1.1.0.md) |
+| v1.0.0 | Yes | [v1.0.0.md](v1.0.0.md) |
+
+## Migration
+
+- [1.2.x → 1.5.0](../guides/migration-1.2-to-1.5.md) — recommended upgrade path from the previous npm line.
+
+## Internal milestones (removed)
+
+Git tags `2.0.0`–`2.5.1` tracked incremental development toward **v1.3.0** and **v1.5.0**. They were never published to npm and are removed from the repository. Their notes remain for archaeology:
+
+| Tag | Notes |
+| --- | --- |
+| 2.4.0 | [2.4.0.md](2.4.0.md) — included in v1.5.0 |
+| 2.5.0 | [2.5.0.md](2.5.0.md) — included in v1.5.0 |
+| 2.5.1 | [2.5.1.md](2.5.1.md) — included in v1.5.0 |
+| 2.0.0–2.3.1 | [2.0.0.md](2.0.0.md) … [2.3.1.md](2.3.1.md) — included in v1.3.0 / v1.5.0 |
+
+Full history: [CHANGELOG.md](../../CHANGELOG.md).

package/docs/release-notes/v1.0.0.md

@@ -0,0 +1,17 @@
+# Release notes — v1.0.0
+
+Initial public release of **field-redactor**.
+
+## Added
+
+- `FieldRedactor` with async `redact()` and `redactInPlace()`
+- Regex key rules: `secretKeys`, `deepSecretKeys`, `fullSecretKeys`
+- **Schema** rules (`customObjects`) for shaped objects with sibling-key indirection
+- Configurable `redactor` function (default replaces values with `"REDACTED"`)
+- Deep-clone via `rfdc` so `redact()` leaves the input untouched
+
+## Install
+
+```bash
+npm install field-redactor
+```

package/docs/release-notes/v1.1.0.md

@@ -0,0 +1,18 @@
+# Release notes — v1.1.0
+
+## Changed
+
+- Root-level primitives, `null`, `undefined`, `Date`, and functions are returned unchanged instead of throwing `FieldRedactorError`.
+
+This makes the redactor safe to call on values that may or may not be traversable JSON objects.
+
+```typescript
+const redactor = new FieldRedactor({ secretKeys: [/email/] });
+
+redactor.redact(undefined); // → undefined (no throw)
+redactor.redact('plain string'); // → 'plain string'
+```
+
+## Full changelog
+
+See [CHANGELOG.md](../../CHANGELOG.md#110---2025-01-30).

package/docs/release-notes/v1.2.0.md

@@ -0,0 +1,18 @@
+# Release notes — v1.2.0
+
+## Added
+
+- **`deleteSecretKeys`** — Remove matching keys from the output entirely (**Remove** mode).
+
+```typescript
+const redactor = new FieldRedactor({
+  deleteSecretKeys: [/authKey/i]
+});
+
+await redactor.redact({ username: 'alice', authKey: 'secret' });
+// → { username: 'REDACTED' }  (authKey key removed)
+```
+
+## Full changelog
+
+See [CHANGELOG.md](../../CHANGELOG.md#120---2025-02-10).

package/docs/release-notes/v1.2.1.md

@@ -0,0 +1,16 @@
+# Release notes — v1.2.1
+
+Bug-fix and ergonomics release for schema matching and sibling-key redaction.
+
+## Changed
+
+- **Relaxed schema matching** — objects match a `CustomObject` when they contain every schema key; extra keys on the input are allowed.
+
+## Fixed
+
+- Sibling-key schema redaction for falsy values (`""`, `0`, `false`) when the sibling key is present on the object.
+- `ignoreBooleans` default documented to match runtime behavior (`false` — booleans are redacted unless `ignoreBooleans: true`).
+
+## Full changelog
+
+See [CHANGELOG.md](../../CHANGELOG.md#121---2026-06-24).

package/docs/release-notes/v1.2.2.md

@@ -0,0 +1,19 @@
+# Release notes — v1.2.2
+
+Type-safety and public error surface release.
+
+## Added
+
+- Export `FieldRedactorError` and `FieldRedactorConfigurationError` from the package entry point.
+
+## Changed
+
+- Replace heavy `any` usage with explicit JSON and redaction types (`JsonValue`, `RedactableInput`, generic `redact<T>()`, etc.).
+
+```typescript
+import { FieldRedactor, FieldRedactorError, FieldRedactorConfigurationError } from 'field-redactor';
+```
+
+## Full changelog
+
+See [CHANGELOG.md](../../CHANGELOG.md#122---2026-06-24).

package/docs/release-notes/v1.3.0.md

@@ -0,0 +1,112 @@
+# Release notes — v1.3.0
+
+Field Redactor **1.3.0** is a feature release focused on developer experience, synchronous performance, and safer defaults for new integrations. Existing `new FieldRedactor(config)` call sites remain compatible; new APIs are opt-in.
+
+## Highlights
+
+| Area | What’s new |
+| --- | --- |
+| **Safe construction** | `FieldRedactor.createSafe()` and `FieldRedactorConfigBuilder.buildSafeRedactor()` require explicit rules |
+| **Config iteration** | `dryRun()` / `dryRunSync()` return path-level audit reports |
+| **Faster sync path** | `redactSync()` / `redactInPlaceSync()` avoid per-field `Promise` overhead |
+| **Lower clone cost** | Copy-on-write structural sharing for `redact()` / `redactSync()` (input still untouched by default) |
+| **Onboarding** | Presets, builder API, split guides, config validation with warnings |
+
+## New APIs
+
+```typescript
+import {
+  FieldRedactor,
+  FieldRedactorConfigBuilder,
+  presets,
+  validateFieldRedactorConfig,
+  hasExplicitRedactionRules,
+  EMPTY_DRY_RUN_REPORT
+} from 'field-redactor';
+```
+
+### Recommended entry points
+
+```typescript
+// Explicit rules — throws if no secretKeys, deepSecretKeys, fullSecretKeys, deleteSecretKeys, or customObjects
+const redactor = FieldRedactor.createSafe({
+  ...presets.applicationLogging(),
+  secretKeys: [/ssn/i]
+});
+
+// Fluent builder with doc labels
+const built = FieldRedactorConfigBuilder.create()
+  .shallow(/email/i)
+  .remove(/authKey/i)
+  .schema(metadataSchema, { name: 'metadata-entry' })
+  .buildSafeRedactor();
+```
+
+### Preview redaction without guessing
+
+```typescript
+const { result, report } = redactor.dryRunSync(payload);
+// report.redactedPaths   — e.g. ['contactInfo.email']
+// report.deletedPaths    — e.g. ['authKey']
+// report.matchedSchemas  — e.g. [{ path: 'metadata[0]', schemaIndex: 0, schemaName: 'metadata-entry' }]
+```
+
+### Sync redaction (no async overhead)
+
+```typescript
+const redactor = new FieldRedactor({
+  secretKeys: [/email/i],
+  syncRedactor: (val) => `REDACTED:${val}` // optional; default sync redactor works too
+});
+
+const output = redactor.redactSync(payload);
+```
+
+## Behavior changes
+
+### Copy-on-write instead of full deep clone
+
+`redact()` and `redactSync()` no longer deep-clone the entire input up front. They traverse with copy-on-write: unmodified subtrees may **share references** with the input; only branches that are redacted or deleted are cloned.
+
+| Before (≤ 1.2.x) | After (1.3.0) |
+| --- | --- |
+| Full `rfdc` clone, then redact in place on the copy | COW traversal; clone only mutated paths |
+| Input never mutated | Input still never mutated when `cloneInput: true` (default) |
+
+**If you relied on every nested object being a new reference**, compare outputs with `===` against the original or set `cloneInput: false` only when you intend in-place mutation.
+
+```typescript
+// Restore in-place mutation semantics for redact() / redactSync()
+new FieldRedactor({ secretKeys: [/email/], cloneInput: false });
+```
+
+### Configuration warnings
+
+`new FieldRedactor()` without rules still redacts **all** values (legacy default). Construction now emits warnings (e.g. “All values will be redacted…”). Use `createSafe()`, the builder’s `buildSafeRedactor()`, or set `strict: true` to fail fast.
+
+```typescript
+const warnings = validateFieldRedactorConfig({ secretKeys: [/email/] });
+// or
+const redactor = new FieldRedactor({ secretKeys: [/email/], strict: true });
+```
+
+## Migration checklist
+
+1. **New projects** — prefer `createSafe()` or `FieldRedactorConfigBuilder.buildSafeRedactor()` over bare `new FieldRedactor()`.
+2. **Hot paths** — switch `await redact()` to `redactSync()` when you use the default or `syncRedactor` (no async-only `redactor`).
+3. **Debugging config** — use `dryRunSync(sample)` while tuning regexes and schemas.
+4. **Presets** — spread `presets.applicationLogging()` or `presets.loggingMetadata()` as a starting point.
+5. **Reference equality** — if tests assert `result.child !== input.child` for unredacted branches, update expectations (sharing is intentional) or deep-clone before redacting if you need isolation.
+
+## Documentation
+
+| Resource | Path |
+| --- | --- |
+| Quickstart | [README.md](../../README.md) |
+| Secret key modes | [docs/guides/secret-key-modes.md](../guides/secret-key-modes.md) |
+| Metadata / schemas | [docs/guides/metadata-redaction.md](../guides/metadata-redaction.md) |
+| Full API reference | [docs/reference/config.md](../reference/config.md) |
+
+## Full changelog
+
+See [CHANGELOG.md](../../CHANGELOG.md#130---2026-06-24).

package/docs/release-notes/v1.5.0.md

@@ -0,0 +1,88 @@
+# Release notes — v1.5.0
+
+Field Redactor **1.5.0** is the first npm release since **1.2.0**. It publishes the accumulated work from git tags **v1.2.1** through **v1.3.0** and the former internal **2.4.0**–**2.5.1** milestones in a single consumer-facing release.
+
+**Migration:** If you are on npm **1.2.x** or earlier, read [Migration: 1.2 → 1.5](../guides/migration-1.2-to-1.5.md) before upgrading.
+
+## Highlights
+
+| Area | What’s new since npm 1.2.0 |
+| --- | --- |
+| **Safe construction** | `FieldRedactor.createSafe()`, `FieldRedactorConfigBuilder`, config validation |
+| **Sync & performance** | `redactSync()`, copy-on-write traversal, `syncRedactor` |
+| **Iteration** | `dryRun()` / `dryRunSync()` with `pathRules` rule attribution |
+| **Presets & DX** | `presets.*()`, `.usePreset()`, anti-patterns guide |
+| **Value-pattern defense** | Opt-in `valuePatterns` for PII embedded in free-text fields |
+| **Correctness** | Relaxed schema matching, falsy sibling-key fix, unified sync/async traversal |
+
+## New since 1.3.0 (this release)
+
+### `usePreset()` and `pathRules`
+
+```typescript
+import { FieldRedactorConfigBuilder, presets } from 'field-redactor';
+
+const redactor = FieldRedactorConfigBuilder.create()
+  .usePreset(presets.applicationLogging())
+  .shallow(/ssn/i)
+  .buildSafeRedactor();
+
+const { report } = redactor.dryRunSync(payload);
+// report.pathRules → [{ path: 'email', action: 'redact', rule: 'shallow', pattern: '/email/i' }, ...]
+```
+
+### Value-pattern redaction
+
+```typescript
+const emailPattern = /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/;
+
+const redactor = FieldRedactor.createSafe({ valuePatterns: [emailPattern] });
+
+const { report } = redactor.dryRunSync({
+  description: 'Contact alice@example.com',
+  note: 'no pii here'
+});
+// report.pathRules → [{ path: 'description', action: 'redact', rule: 'value', pattern: '...' }]
+```
+
+**Precedence:** Schema → Opaque → Deep → Remove → Shallow → **Value-pattern** → default redactor.
+
+### Internal (no API change)
+
+- Unified `ObjectRedactorTraversal` for sync in-place, copy-on-write, and async in-place redaction.
+- Shared custom-object handler dispatch in `objectRedactorCustomObject.ts`.
+
+## Behavior changes (since 1.2.x)
+
+| Topic | Before (≤ 1.2.x) | After (1.5.0) |
+| --- | --- | --- |
+| Default `redact()` clone | Full deep clone via `rfdc` | Copy-on-write; unredacted subtrees may share references with input |
+| Schema matching | Exact key set | Input may contain extra keys beyond the schema |
+| Falsy sibling values | Could skip redaction | Redacts `""`, `0`, `false` when sibling key is present |
+| Bare `new FieldRedactor()` | Silent all-value redaction | Emits config warnings; use `createSafe()` or `strict: true` |
+
+## Migration checklist
+
+1. Read [Migration: 1.2 → 1.5](../guides/migration-1.2-to-1.5.md).
+2. Prefer `FieldRedactor.createSafe()` or `FieldRedactorConfigBuilder.buildSafeRedactor()`.
+3. Use `redactSync()` on hot paths when you do not need async `redactor`.
+4. Tune config with `dryRunSync()` and inspect `pathRules`.
+5. Add `valuePatterns` only when PII can appear in arbitrary string fields without sensitive key names.
+
+## Documentation
+
+| Resource | Path |
+| --- | --- |
+| Migration guide | [docs/guides/migration-1.2-to-1.5.md](../guides/migration-1.2-to-1.5.md) |
+| Secret key modes | [docs/guides/secret-key-modes.md](../guides/secret-key-modes.md) |
+| Value-pattern redaction | [docs/guides/value-pattern-redaction.md](../guides/value-pattern-redaction.md) |
+| Anti-patterns | [docs/guides/anti-patterns.md](../guides/anti-patterns.md) |
+| Configuration reference | [docs/reference/config.md](../reference/config.md) |
+
+## Full changelog
+
+See [CHANGELOG.md](../../CHANGELOG.md#150---2026-06-24).
+
+## Supersedes internal tags
+
+Git tags `2.4.0`, `2.5.0`, and `2.5.1` were development milestones and are removed from the repository. Their content is included in this **v1.5.0** release.

package/jest.config.js

@@ -6,7 +6,10 @@ module.exports = {
   },
   cacheDirectory: './tmp/jest-cache',
   coverageDirectory: './tmp/jest-coverage',
-  coveragePathIgnorePatterns: ['./node_modules/', './tests/mocks/'],
+  coveragePathIgnorePatterns: [
+    './node_modules/',
+    './tests/mocks/'
+  ],
   collectCoverage: true,
   coverageThreshold: {
     global: {