@cqrs-ddd/safe-stringify 0.2.0

package/README.md

@@ -0,0 +1,168 @@
+# @cqrs-ddd/safe-stringify
+
+Two JSON serializers with opposite goals, and the key-segment helpers that build
+identity keys. No runtime dependencies and no framework.
+
+| | Strict: `stableStringify`, `toStrictJsonValue` | Safe: `safeStringify`, `safeSanitize`, `redactValue` |
+| --- | --- | --- |
+| Use for | identity: cache keys, idempotency fingerprints, stored snapshots | display: logs, audit and dead-letter payloads |
+| Output | deterministic JSON, object keys sorted at every level, stable across releases | readable JSON in insertion order; the format may evolve |
+| Unsupported input | throws a `TypeError` | never throws |
+| Secrets | never redacts, because a key must not change | excludes and redacts on request |
+
+**Use the strict serializer for anything that identifies data. Never use `safeStringify`
+for a key or a fingerprint:** its output is not sorted, it replaces values it cannot
+represent, and its format may change.
+
+## Installation
+
+```bash
+npm install @cqrs-ddd/safe-stringify
+# or
+pnpm add @cqrs-ddd/safe-stringify
+```
+
+Requires Node.js 22 or later.
+
+## Strict serializer
+
+```typescript
+import { stableStringify, toStrictJsonValue } from '@cqrs-ddd/safe-stringify';
+
+stableStringify({ z: 1, a: { d: 2, c: new Date(0) } });
+// '{"a":{"c":"1970-01-01T00:00:00.000Z","d":2},"z":1}'
+
+toStrictJsonValue({ b: 2, a: 1 }, true); // { a: 1, b: 2 }, a null-prototype object
+```
+
+- Strings, booleans, `null` and finite numbers are kept. Dates become ISO-8601 strings.
+  An object with `toJSON()` is replaced by what that method returns.
+- Everything else throws a `TypeError`: `undefined`, functions, `bigint`, symbols and
+  symbol-keyed properties, non-finite numbers, invalid dates, cycles, sparse arrays,
+  `Map`, `Set`, `WeakMap`, `WeakSet`, `Error`, `RegExp`, `Promise`, `ArrayBuffer` and
+  typed arrays.
+- `stableStringify` wraps that failure in a `TypeError` whose `cause` is the original.
+- Structurally equal values produce byte-identical strings, whatever their property
+  insertion order. Keys sort by UTF-16 code unit, as `Array.prototype.sort` does.
+
+## Safe serializer
+
+```typescript
+import {
+  DEFAULT_REDACT_KEYS,
+  redactValue,
+  safeStringify,
+} from '@cqrs-ddd/safe-stringify';
+
+const payload: Record<string, unknown> = { user: 'jane', password: 'secret', amount: 10n };
+payload.self = payload;
+
+safeStringify(payload);
+// '{"user":"jane","password":"secret","amount":"[bigint]","self":"[Circular]"}'
+
+safeStringify(payload, { redactKeys: DEFAULT_REDACT_KEYS });
+// '{"user":"jane","password":"[REDACTED]","amount":"[bigint]","self":"[Circular]"}'
+
+redactValue(payload); // a deep clone with DEFAULT_REDACT_KEYS masked
+```
+
+- `safeStringify(value, options?, indent?)` and `safeSanitize(value, options?)` never
+  throw. Cycles become `"[Circular]"`, errors are expanded to `name`, `message`, `stack`
+  and their own enumerable properties, and values JSON cannot hold are replaced by a
+  readable marker (`"[bigint]"`, `"[Function]"`, `"[Invalid Date]"`, `"[Binary Data]"`,
+  `"[Stream]"`). A `Set<string>` in place of `options` is read as `excludeKeys`.
+  `safeStringify(undefined)` returns the string `'undefined'`.
+- **They redact nothing unless you pass `redactKeys`.** `redactValue(value, keys?)`
+  applies `DEFAULT_REDACT_KEYS` by default and keeps rich types (`mode: 'clone'`).
+- `SanitizeOptions`:
+
+  | Option | Effect |
+  | --- | --- |
+  | `excludeKeys` | keys or dot-paths removed from the output; exact, case-sensitive match |
+  | `redactKeys` | keys or dot-paths masked; matched ignoring case, `_` and `-`, so `refreshToken` also masks `refresh_token` |
+  | `redactReplacement` | the mask; default `REDACTED` (`"[REDACTED]"`) |
+  | `mode` | `'json'` (default) turns rich types into JSON-friendly values; `'clone'` deep-clones them keeping their classes |
+
+- Exclusion and redaction, with a key matched at any depth or a dot-path matched at one
+  place only:
+
+  ```typescript
+  safeStringify(
+    { user: { profile: { email: 'x' }, token: 't' } },
+    { excludeKeys: ['user.profile'], redactKeys: ['token'], redactReplacement: '***' },
+  );
+  // '{"user":{"token":"***"}}'
+
+  safeStringify({ when: new Date(0), tags: new Set(['a']), limits: new Map([['k', 1]]) });
+  // '{"when":"1970-01-01T00:00:00.000Z","tags":["a"],"limits":{"k":1}}'
+  ```
+
+- `DEFAULT_REDACT_KEYS` lists common secret names (passwords, tokens, API keys,
+  authorization headers, cookies, card data). No list recognizes every secret: add your
+  application's own names.
+
+## Key segments
+
+```typescript
+import {
+  ABSENT_SEGMENT,
+  escapeKeySegment,
+  joinKeySegments,
+} from '@cqrs-ddd/safe-stringify';
+
+joinKeySegments(['cache', 'tenant:a', undefined, 'user']);
+// 'cache:tenant\\:a:\\-:user'
+```
+
+- `joinKeySegments(segments)` escapes each segment and joins them with `:`.
+  `undefined` and `null` become `ABSENT_SEGMENT` (`\-`), so `['a', undefined]` and
+  `['a', '']` produce different keys.
+- `escapeKeySegment(value)` escapes `\` first, then `:`. A segment that is literally
+  `\-` is written `\\-`, so it never collides with an absent segment.
+
+Build a cache key from a tenant, a request name and a strict fingerprint of the payload:
+
+```typescript
+import { joinKeySegments, stableStringify } from '@cqrs-ddd/safe-stringify';
+import { createHash } from 'node:crypto';
+
+function cacheKey(tenantId: string | undefined, name: string, payload: unknown): string {
+  const fingerprint = createHash('sha256').update(stableStringify(payload)).digest('hex');
+  return joinKeySegments(['cache', tenantId, name, fingerprint]);
+}
+```
+
+The strict serializer's output and these key formats are part of the package contract:
+changing them would orphan every stored cache entry, rate-limit bucket and idempotency
+fingerprint. The package's golden-output specs pin them.
+
+## Migrating from @nestjs-pipeline/core 0.1.x
+
+`@nestjs-pipeline/core` 0.1.x did not export any serializer or key-segment helper from its
+entry point: `safeStringify` and `safeSanitize` lived in its internal
+`dist/helpers/safeStringify` module, and `stableStringify`, `toStrictJsonValue`,
+`redactValue`, `DEFAULT_REDACT_KEYS`, `REDACTED` and the key-segment helpers did not exist.
+Code that deep-imported the internal module moves to this package:
+
+```typescript
+// Before (0.1.x, an internal path)
+import { safeSanitize, safeStringify } from '@nestjs-pipeline/core/dist/helpers/safeStringify';
+
+safeStringify(value, new Set(['token', 'ctx.sessionUser']), 2);
+
+// After (0.2.0)
+import { safeSanitize, safeStringify } from '@cqrs-ddd/safe-stringify';
+
+safeStringify(value, { excludeKeys: ['token', 'ctx.sessionUser'] }, 2);
+```
+
+- The `Set<string>` second argument is still accepted and means `excludeKeys`.
+- `safeStringify(undefined)` now returns `'undefined'` instead of `undefined`.
+- Use `stableStringify`, not `safeStringify`, for any key or fingerprint you build.
+
+## License
+
+Dual-licensed under **AGPLv3** and a **Commercial License**. See the root
+[`LICENSE`](https://github.com/aristoteliss/nestjs-pipeline/blob/master/LICENSE) and
+[`COMMERCIAL_LICENSE.txt`](https://github.com/aristoteliss/nestjs-pipeline/blob/master/COMMERCIAL_LICENSE.txt)
+for details.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { ABSENT_SEGMENT, escapeKeySegment, joinKeySegments, } from './key-segment';
+export * from './safeStringify';
+export * from './stableStringify';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,eAAe,GAChB,MAAM,eAAe,CAAC;AACvB,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,25 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.joinKeySegments = exports.escapeKeySegment = exports.ABSENT_SEGMENT = void 0;
+var key_segment_1 = require("./key-segment");
+Object.defineProperty(exports, "ABSENT_SEGMENT", { enumerable: true, get: function () { return key_segment_1.ABSENT_SEGMENT; } });
+Object.defineProperty(exports, "escapeKeySegment", { enumerable: true, get: function () { return key_segment_1.escapeKeySegment; } });
+Object.defineProperty(exports, "joinKeySegments", { enumerable: true, get: function () { return key_segment_1.joinKeySegments; } });
+__exportStar(require("./safeStringify"), exports);
+__exportStar(require("./stableStringify"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA,sEAAsE;;;;;;;;;;;;;;;;;AAEtE,6CAIuB;AAHrB,6GAAA,cAAc,OAAA;AACd,+GAAA,gBAAgB,OAAA;AAChB,8GAAA,eAAe,OAAA;AAEjB,kDAAgC;AAChC,oDAAkC"}

package/dist/key-segment.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Marker written in place of a segment whose value is absent.
+ *
+ * Deliberately `\-` rather than a control character, so a key can be stored in
+ * a PostgreSQL `text` column, which rejects `U+0000`. It is also unambiguous — escaping a real
+ * value only ever produces `\\` or `\:`, so no genuine segment can render as
+ * `\-`, and a literal `\-` inside a value escapes to `\\-`.
+ */
+export declare const ABSENT_SEGMENT = "\\-";
+/**
+ * Escapes the structural characters of a `:`-joined composite key.
+ *
+ * Joining raw values with `:` makes two different tuples collapse into one key
+ * whenever a value contains the separator:
+ *
+ * ```text
+ * ['a:b', 'c'] → "a:b:c"
+ * ['a', 'b:c'] → "a:b:c"     ← same key, different callers
+ * ```
+ *
+ * Identifiers that reach a key are routinely email addresses, external subject
+ * claims and composite IDs. A collision means two callers share a rate-limit
+ * bucket or a cache entry.
+ *
+ * The backslash is escaped first so that an input already containing one cannot
+ * be used to forge a separator.
+ */
+export declare function escapeKeySegment(value: string): string;
+/**
+ * Joins segments into one key, escaping each so distinct tuples stay distinct.
+ *
+ * `undefined` and `null` become {@link ABSENT_SEGMENT} rather than being dropped,
+ * so a tuple with a missing value cannot collapse onto a shorter tuple that never
+ * had that position at all. Omitting an absent tenant, for example, would make a
+ * tenant-less key identical to the key of a single-tenant deployment.
+ */
+export declare function joinKeySegments(segments: readonly (string | undefined | null)[]): string;
+//# sourceMappingURL=key-segment.d.ts.map

package/dist/key-segment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-segment.d.ts","sourceRoot":"","sources":["../src/key-segment.ts"],"names":[],"mappings":"AAKA;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,QAAQ,CAAC;AAEpC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,SAAS,CAAC,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC,EAAE,GAC/C,MAAM,CAQR"}

package/dist/key-segment.js

@@ -0,0 +1,54 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ABSENT_SEGMENT = void 0;
+exports.escapeKeySegment = escapeKeySegment;
+exports.joinKeySegments = joinKeySegments;
+/** Character that separates the segments of a composite key. */
+const SEGMENT_SEPARATOR = ':';
+/**
+ * Marker written in place of a segment whose value is absent.
+ *
+ * Deliberately `\-` rather than a control character, so a key can be stored in
+ * a PostgreSQL `text` column, which rejects `U+0000`. It is also unambiguous — escaping a real
+ * value only ever produces `\\` or `\:`, so no genuine segment can render as
+ * `\-`, and a literal `\-` inside a value escapes to `\\-`.
+ */
+exports.ABSENT_SEGMENT = '\\-';
+/**
+ * Escapes the structural characters of a `:`-joined composite key.
+ *
+ * Joining raw values with `:` makes two different tuples collapse into one key
+ * whenever a value contains the separator:
+ *
+ * ```text
+ * ['a:b', 'c'] → "a:b:c"
+ * ['a', 'b:c'] → "a:b:c"     ← same key, different callers
+ * ```
+ *
+ * Identifiers that reach a key are routinely email addresses, external subject
+ * claims and composite IDs. A collision means two callers share a rate-limit
+ * bucket or a cache entry.
+ *
+ * The backslash is escaped first so that an input already containing one cannot
+ * be used to forge a separator.
+ */
+function escapeKeySegment(value) {
+    return value.replace(/\\/g, '\\\\').replace(/:/g, '\\:');
+}
+/**
+ * Joins segments into one key, escaping each so distinct tuples stay distinct.
+ *
+ * `undefined` and `null` become {@link ABSENT_SEGMENT} rather than being dropped,
+ * so a tuple with a missing value cannot collapse onto a shorter tuple that never
+ * had that position at all. Omitting an absent tenant, for example, would make a
+ * tenant-less key identical to the key of a single-tenant deployment.
+ */
+function joinKeySegments(segments) {
+    return segments
+        .map((segment) => segment === undefined || segment === null
+        ? exports.ABSENT_SEGMENT
+        : escapeKeySegment(segment))
+        .join(SEGMENT_SEPARATOR);
+}
+//# sourceMappingURL=key-segment.js.map

package/dist/key-segment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-segment.js","sourceRoot":"","sources":["../src/key-segment.ts"],"names":[],"mappings":";AAAA,sEAAsE;;;AAiCtE,4CAEC;AAUD,0CAUC;AArDD,gEAAgE;AAChE,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAE9B;;;;;;;GAOG;AACU,QAAA,cAAc,GAAG,KAAK,CAAC;AAEpC;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,gBAAgB,CAAC,KAAa;IAC5C,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,eAAe,CAC7B,QAAgD;IAEhD,OAAO,QAAQ;SACZ,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CACf,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,IAAI;QACvC,CAAC,CAAC,sBAAc;QAChB,CAAC,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAC9B;SACA,IAAI,CAAC,iBAAiB,CAAC,CAAC;AAC7B,CAAC"}

package/dist/safeStringify.d.ts

@@ -0,0 +1,47 @@
+/** Placeholder substituted for the value of a redacted field. */
+export declare const REDACTED = "[REDACTED]";
+/**
+ * Commonly sensitive field names. Redaction matches a key ignoring case, `_`
+ * and `-`, so `refreshToken` also masks `refresh_token` and `REFRESH-TOKEN`;
+ * a name list cannot recognize every secret, so add application-specific
+ * names through `redactKeys`.
+ */
+export declare const DEFAULT_REDACT_KEYS: readonly string[];
+export interface SanitizeOptions {
+    /** Keys or dot-paths to completely exclude from the output (exact, case-sensitive match). */
+    excludeKeys?: Set<string> | readonly string[];
+    /** Keys or dot-paths to mask with {@link REDACTED}, matched ignoring case, `_` and `-`. */
+    redactKeys?: Set<string> | readonly string[];
+    /** Replacement string for redacted fields. Default: {@link REDACTED}. */
+    redactReplacement?: string;
+    /**
+     * Sanitization mode:
+     * - 'json': normalizes rich types (Date, Map, Set, Error) to JSON-friendly primitives/objects.
+     * - 'clone': deeply clones Date, RegExp, Map, Set, and binary values with their classes. An
+     *   Error becomes a plain `Error` carrying its name, message, stack, and own enumerable
+     *   properties; any other object becomes a plain object.
+     */
+    mode?: 'json' | 'clone';
+}
+/**
+ * Sanitizes a value for structured logging or general processing: handles
+ * circular references, non-serializable types, exclusion, and redaction.
+ */
+export declare function safeSanitize(value: unknown, options?: SanitizeOptions | Set<string>): unknown;
+/**
+ * Safely converts a value to a JSON string, handling circular references,
+ * non-serializable types, and optional key exclusion/redaction.
+ */
+export declare function safeStringify(value: unknown, options?: SanitizeOptions | Set<string>, indent?: number): string;
+/**
+ * Returns a copy of `value` with the given keys masked with {@link REDACTED}.
+ *
+ * Copies in the `'clone'` mode of {@link SanitizeOptions}: Date, RegExp, Map,
+ * Set, and binary values keep their classes; an Error becomes a plain `Error`
+ * with the same name, message, stack, and own enumerable properties; any other
+ * object becomes a plain object. A cyclic reference becomes `'[Circular]'`,
+ * streams and Multer files become placeholder strings, and functions are
+ * returned by reference.
+ */
+export declare function redactValue(value: unknown, keys?: readonly string[]): unknown;
+//# sourceMappingURL=safeStringify.d.ts.map

package/dist/safeStringify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safeStringify.d.ts","sourceRoot":"","sources":["../src/safeStringify.ts"],"names":[],"mappings":"AAEA,iEAAiE;AACjE,eAAO,MAAM,QAAQ,eAAe,CAAC;AAErC;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAuBhD,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B,6FAA6F;IAC7F,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS,MAAM,EAAE,CAAC;IAC9C,2FAA2F;IAC3F,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS,MAAM,EAAE,CAAC;IAC7C,yEAAyE;IACzE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACzB;AAwPD;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,eAAe,GAAG,GAAG,CAAC,MAAM,CAAC,GACtC,OAAO,CAGT;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,eAAe,GAAG,GAAG,CAAC,MAAM,CAAC,EACvC,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,CAGR;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,OAAO,EACd,IAAI,GAAE,SAAS,MAAM,EAAwB,GAC5C,OAAO,CAKT"}

package/dist/safeStringify.js

@@ -0,0 +1,259 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_REDACT_KEYS = exports.REDACTED = void 0;
+exports.safeSanitize = safeSanitize;
+exports.safeStringify = safeStringify;
+exports.redactValue = redactValue;
+/** Placeholder substituted for the value of a redacted field. */
+exports.REDACTED = '[REDACTED]';
+/**
+ * Commonly sensitive field names. Redaction matches a key ignoring case, `_`
+ * and `-`, so `refreshToken` also masks `refresh_token` and `REFRESH-TOKEN`;
+ * a name list cannot recognize every secret, so add application-specific
+ * names through `redactKeys`.
+ */
+exports.DEFAULT_REDACT_KEYS = [
+    'password',
+    'passwordHash',
+    'pass',
+    'pwd',
+    'token',
+    'accessToken',
+    'refreshToken',
+    'idToken',
+    'sessionToken',
+    'secret',
+    'clientSecret',
+    'privateKey',
+    'apiKey',
+    'xApiKey',
+    'authorization',
+    'proxyAuthorization',
+    'cookie',
+    'setCookie',
+    'ssn',
+    'creditCard',
+    'cardNumber',
+    'cvv',
+];
+const SAFE_PRIMITIVES = new Set(['string', 'number', 'boolean']);
+function buildMatchers(options) {
+    const flatExclude = new Set();
+    const pathExclude = new Set();
+    const flatRedact = new Set();
+    const pathRedact = new Set();
+    let redactReplacement = exports.REDACTED;
+    let mode = 'json';
+    if (options instanceof Set)
+        options = { excludeKeys: options };
+    if (options) {
+        if (options.mode)
+            mode = options.mode;
+        if (options.redactReplacement)
+            redactReplacement = options.redactReplacement;
+        if (options.excludeKeys) {
+            for (const key of options.excludeKeys) {
+                if (key.includes('.'))
+                    pathExclude.add(key);
+                else
+                    flatExclude.add(key);
+            }
+        }
+        if (options.redactKeys) {
+            for (const key of options.redactKeys) {
+                const normalized = normalizeRedactKey(key);
+                if (normalized.includes('.'))
+                    pathRedact.add(normalized);
+                else
+                    flatRedact.add(normalized);
+            }
+        }
+    }
+    return {
+        flatExclude,
+        pathExclude,
+        flatRedact,
+        pathRedact,
+        redactReplacement,
+        mode,
+    };
+}
+function normalizeRedactKey(key) {
+    return key.toLowerCase().replace(/[_-]/g, '');
+}
+function isRedacted(key, path, matchers) {
+    return (matchers.flatRedact.has(normalizeRedactKey(key)) ||
+        matchers.pathRedact.has(normalizeRedactKey(path)));
+}
+function isExcluded(key, path, matchers) {
+    return matchers.flatExclude.has(key) || matchers.pathExclude.has(path);
+}
+function sanitizeValue(val, path, matchers, ancestors) {
+    if (val === null)
+        return null;
+    if (val === undefined)
+        return undefined;
+    // Primitives
+    if (typeof val !== 'object' && typeof val !== 'function') {
+        if (matchers.mode === 'clone')
+            return val;
+        const type = typeof val;
+        return SAFE_PRIMITIVES.has(type) ? val : `[${type}]`;
+    }
+    if (typeof val === 'function') {
+        return matchers.mode === 'clone' ? val : '[Function]';
+    }
+    // Circular reference guard
+    if (ancestors.has(val))
+        return '[Circular]';
+    ancestors.add(val);
+    try {
+        // 1. Date
+        if (val instanceof Date) {
+            if (matchers.mode === 'clone')
+                return new Date(val);
+            return Number.isNaN(val.getTime()) ? '[Invalid Date]' : val.toISOString();
+        }
+        // 2. RegExp
+        if (val instanceof RegExp) {
+            if (matchers.mode === 'clone') {
+                const clone = new RegExp(val.source, val.flags);
+                clone.lastIndex = val.lastIndex;
+                return clone;
+            }
+            return val.toString();
+        }
+        // 3. Error
+        if (val instanceof Error) {
+            if (matchers.mode === 'clone') {
+                const clone = new Error(val.message);
+                clone.name = val.name;
+                clone.stack = val.stack;
+                copyProperties(val, clone, path, matchers, ancestors);
+                return clone;
+            }
+            return { name: val.name, message: val.message, stack: val.stack };
+        }
+        // 4. Binary data
+        if ((typeof Buffer !== 'undefined' && Buffer.isBuffer(val)) ||
+            val instanceof ArrayBuffer ||
+            ArrayBuffer.isView(val)) {
+            if (matchers.mode === 'clone')
+                return structuredClone(val);
+            return '[Binary Data]';
+        }
+        // 5. Streams
+        if (typeof val.pipe === 'function' &&
+            typeof val.on === 'function') {
+            return '[Stream]';
+        }
+        // 6. Multer File
+        if ('originalname' in val &&
+            'buffer' in val &&
+            Buffer.isBuffer(val.buffer)) {
+            return `[File: ${val.originalname}]`;
+        }
+        // 7. Map
+        if (val instanceof Map) {
+            if (matchers.mode === 'clone') {
+                const clone = new Map();
+                for (const [k, v] of val) {
+                    const keyStr = typeof k === 'string' ? k : '';
+                    const currentPath = path && keyStr ? `${path}.${keyStr}` : keyStr;
+                    if (keyStr && isExcluded(keyStr, currentPath, matchers))
+                        continue;
+                    const isRedact = keyStr
+                        ? isRedacted(keyStr, currentPath, matchers)
+                        : false;
+                    clone.set(sanitizeValue(k, path, matchers, ancestors), isRedact
+                        ? matchers.redactReplacement
+                        : sanitizeValue(v, currentPath, matchers, ancestors));
+                }
+                return clone;
+            }
+            return sanitizeValue(Object.fromEntries(val), path, matchers, ancestors);
+        }
+        // 8. Set
+        if (val instanceof Set) {
+            if (matchers.mode === 'clone') {
+                return new Set(Array.from(val, (item) => sanitizeValue(item, path, matchers, ancestors)));
+            }
+            return sanitizeValue([...val], path, matchers, ancestors);
+        }
+        // 9. Array
+        if (Array.isArray(val)) {
+            return val.map((item) => sanitizeValue(item, path, matchers, ancestors));
+        }
+        // 10. Generic Object
+        const out = matchers.mode === 'json' ? Object.create(null) : {};
+        copyProperties(val, out, path, matchers, ancestors);
+        return out;
+    }
+    finally {
+        ancestors.delete(val);
+    }
+}
+function copyProperties(source, target, path, matchers, ancestors) {
+    for (const [k, v] of Object.entries(source)) {
+        const currentPath = path ? `${path}.${k}` : k;
+        if (isExcluded(k, currentPath, matchers)) {
+            continue;
+        }
+        const valOut = isRedacted(k, currentPath, matchers)
+            ? matchers.redactReplacement
+            : sanitizeValue(v, currentPath, matchers, ancestors);
+        Object.defineProperty(target, k, {
+            value: valOut,
+            writable: true,
+            enumerable: true,
+            configurable: true,
+        });
+    }
+    if (matchers.mode !== 'clone')
+        return;
+    for (const sym of Object.getOwnPropertySymbols(source)) {
+        const descriptor = Object.getOwnPropertyDescriptor(source, sym);
+        if (!descriptor?.enumerable)
+            continue;
+        Object.defineProperty(target, sym, {
+            value: sanitizeValue(Reflect.get(source, sym), path, matchers, ancestors),
+            writable: true,
+            enumerable: true,
+            configurable: true,
+        });
+    }
+}
+/**
+ * Sanitizes a value for structured logging or general processing: handles
+ * circular references, non-serializable types, exclusion, and redaction.
+ */
+function safeSanitize(value, options) {
+    const matchers = buildMatchers(options);
+    return sanitizeValue(value, '', matchers, new WeakSet());
+}
+/**
+ * Safely converts a value to a JSON string, handling circular references,
+ * non-serializable types, and optional key exclusion/redaction.
+ */
+function safeStringify(value, options, indent) {
+    const sanitized = safeSanitize(value, options);
+    return JSON.stringify(sanitized, undefined, indent) ?? 'undefined';
+}
+/**
+ * Returns a copy of `value` with the given keys masked with {@link REDACTED}.
+ *
+ * Copies in the `'clone'` mode of {@link SanitizeOptions}: Date, RegExp, Map,
+ * Set, and binary values keep their classes; an Error becomes a plain `Error`
+ * with the same name, message, stack, and own enumerable properties; any other
+ * object becomes a plain object. A cyclic reference becomes `'[Circular]'`,
+ * streams and Multer files become placeholder strings, and functions are
+ * returned by reference.
+ */
+function redactValue(value, keys = exports.DEFAULT_REDACT_KEYS) {
+    return safeSanitize(value, {
+        redactKeys: keys,
+        mode: 'clone',
+    });
+}
+//# sourceMappingURL=safeStringify.js.map

package/dist/safeStringify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safeStringify.js","sourceRoot":"","sources":["../src/safeStringify.ts"],"names":[],"mappings":"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"}