@cqrs-ddd/safe-stringify 0.2.0

package/dist/stableStringify.d.ts

@@ -0,0 +1,64 @@
+/**
+ * A strictly JSON-serializable value (primitives, arrays, and plain records).
+ */
+export type StrictJsonValue = null | boolean | number | string | StrictJsonValue[] | {
+    [key: string]: StrictJsonValue;
+};
+/**
+ * Normalizes a value to the strict, portable JSON domain used for deterministic
+ * hashing, idempotency fingerprints, and cache key generation.
+ *
+ * Enforces strict JSON boundaries:
+ * - Primitives (`string`, `boolean`, `null`, finite `number`) are preserved.
+ * - Dates are explicitly converted to ISO-8601 strings (`.toISOString()`).
+ * - Custom objects with `.toJSON()` methods are validated through their returned
+ *   representation; internal fields excluded by that method are not inspected.
+ * - Object keys are optionally sorted recursively for deterministic serialization.
+ * - Unsupported types (non-finite numbers, `Map`, `Set`, `Error`, `RegExp`,
+ *   binary buffers, promises, symbols, and sparse arrays) throw a {@link TypeError}.
+ * - Cyclic references are detected via a `WeakSet` and throw a {@link TypeError}.
+ *
+ * @param value The value to normalize.
+ * @param sortKeys Whether to sort object keys recursively in lexicographical order.
+ * @returns The strictly normalized JSON-compatible value.
+ * @throws {TypeError} If the value contains cycles or elements outside the JSON domain.
+ *
+ * @example
+ * ```ts
+ * const normalized = toStrictJsonValue({ b: 2, a: 1 }, true);
+ * // → { a: 1, b: 2 }
+ * ```
+ */
+export declare function toStrictJsonValue(value: unknown, sortKeys?: boolean): StrictJsonValue;
+/**
+ * Deterministically serializes a value to a JSON string with lexicographically
+ * sorted object keys, for cache keys, idempotency fingerprints and snapshots.
+ *
+ * Guarantees that structurally equal payloads produce byte-identical JSON strings
+ * regardless of property insertion order. The output forms stored keys, so it must
+ * never change: `golden-output.spec.ts` pins it.
+ *
+ * Enforces strict JSON boundaries, as {@link toStrictJsonValue} does:
+ * - Primitives (`string`, `boolean`, `null`, finite `number`) are preserved.
+ * - Dates are explicitly converted to ISO-8601 strings (`.toISOString()`).
+ * - Custom objects with `.toJSON()` methods are validated through their returned
+ *   representation; internal fields excluded by that method are not inspected.
+ * - Object keys are sorted recursively.
+ * - Unsupported types (`undefined`, `bigint`, symbols, functions, non-finite
+ *   numbers, `Map`, `Set`, `Error`, `RegExp`, binary buffers, promises,
+ *   symbol-keyed properties and sparse arrays) throw a {@link TypeError}.
+ * - Cyclic references are detected via a `WeakSet` and throw a {@link TypeError}.
+ *
+ * @param value The value to serialize.
+ * @returns The deterministic JSON string representation.
+ * @throws {TypeError} If the value is cyclic, contains non-serializable types, or
+ *   cannot be represented in JSON. The precise reason is the error's `cause`.
+ *
+ * @example
+ * ```ts
+ * stableStringify({ z: 1, a: 2 });
+ * // → '{"a":2,"z":1}'
+ * ```
+ */
+export declare function stableStringify(value: unknown): string;
+//# sourceMappingURL=stableStringify.d.ts.map

package/dist/stableStringify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stableStringify.d.ts","sourceRoot":"","sources":["../src/stableStringify.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,MAAM,eAAe,GACvB,IAAI,GACJ,OAAO,GACP,MAAM,GACN,MAAM,GACN,eAAe,EAAE,GACjB;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAAA;CAAE,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EACd,QAAQ,UAAQ,GACf,eAAe,CAEjB;AAoGD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAStD"}

package/dist/stableStringify.js

@@ -0,0 +1,149 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toStrictJsonValue = toStrictJsonValue;
+exports.stableStringify = stableStringify;
+/**
+ * Normalizes a value to the strict, portable JSON domain used for deterministic
+ * hashing, idempotency fingerprints, and cache key generation.
+ *
+ * Enforces strict JSON boundaries:
+ * - Primitives (`string`, `boolean`, `null`, finite `number`) are preserved.
+ * - Dates are explicitly converted to ISO-8601 strings (`.toISOString()`).
+ * - Custom objects with `.toJSON()` methods are validated through their returned
+ *   representation; internal fields excluded by that method are not inspected.
+ * - Object keys are optionally sorted recursively for deterministic serialization.
+ * - Unsupported types (non-finite numbers, `Map`, `Set`, `Error`, `RegExp`,
+ *   binary buffers, promises, symbols, and sparse arrays) throw a {@link TypeError}.
+ * - Cyclic references are detected via a `WeakSet` and throw a {@link TypeError}.
+ *
+ * @param value The value to normalize.
+ * @param sortKeys Whether to sort object keys recursively in lexicographical order.
+ * @returns The strictly normalized JSON-compatible value.
+ * @throws {TypeError} If the value contains cycles or elements outside the JSON domain.
+ *
+ * @example
+ * ```ts
+ * const normalized = toStrictJsonValue({ b: 2, a: 1 }, true);
+ * // → { a: 1, b: 2 }
+ * ```
+ */
+function toStrictJsonValue(value, sortKeys = false) {
+    return normalize(value, new WeakSet(), sortKeys);
+}
+function normalize(value, ancestors, sortKeys) {
+    if (value === null ||
+        typeof value === 'string' ||
+        typeof value === 'boolean') {
+        return value;
+    }
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            throw new TypeError('Non-finite numbers are not JSON-serializable.');
+        }
+        return value;
+    }
+    if (typeof value !== 'object') {
+        throw new TypeError(`Unsupported JSON value type: ${typeof value}.`);
+    }
+    if (ancestors.has(value)) {
+        throw new TypeError('Cyclic values are not JSON-serializable.');
+    }
+    if (value instanceof Date) {
+        if (Number.isNaN(value.getTime())) {
+            throw new TypeError('Invalid dates are not JSON-serializable.');
+        }
+        return value.toISOString();
+    }
+    if (isUnsupportedObject(value)) {
+        throw new TypeError(`${value.constructor?.name || 'Object'} is outside the supported JSON domain.`);
+    }
+    const toJSON = value.toJSON;
+    if (typeof toJSON === 'function') {
+        ancestors.add(value);
+        try {
+            return normalize(toJSON.call(value), ancestors, sortKeys);
+        }
+        finally {
+            ancestors.delete(value);
+        }
+    }
+    if (Object.getOwnPropertySymbols(value).length > 0) {
+        throw new TypeError('Symbol-keyed properties are outside the supported JSON domain.');
+    }
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            const result = [];
+            for (let index = 0; index < value.length; index += 1) {
+                if (!(index in value)) {
+                    throw new TypeError('Sparse arrays are not JSON-serializable.');
+                }
+                result.push(normalize(value[index], ancestors, sortKeys));
+            }
+            return result;
+        }
+        const source = value;
+        const keys = Object.keys(source);
+        if (sortKeys)
+            keys.sort();
+        const result = Object.create(null);
+        for (const key of keys) {
+            result[key] = normalize(source[key], ancestors, sortKeys);
+        }
+        return result;
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+function isUnsupportedObject(value) {
+    return (value instanceof RegExp ||
+        value instanceof Error ||
+        value instanceof Map ||
+        value instanceof Set ||
+        value instanceof WeakMap ||
+        value instanceof WeakSet ||
+        value instanceof ArrayBuffer ||
+        ArrayBuffer.isView(value) ||
+        value instanceof Promise);
+}
+/**
+ * Deterministically serializes a value to a JSON string with lexicographically
+ * sorted object keys, for cache keys, idempotency fingerprints and snapshots.
+ *
+ * Guarantees that structurally equal payloads produce byte-identical JSON strings
+ * regardless of property insertion order. The output forms stored keys, so it must
+ * never change: `golden-output.spec.ts` pins it.
+ *
+ * Enforces strict JSON boundaries, as {@link toStrictJsonValue} does:
+ * - Primitives (`string`, `boolean`, `null`, finite `number`) are preserved.
+ * - Dates are explicitly converted to ISO-8601 strings (`.toISOString()`).
+ * - Custom objects with `.toJSON()` methods are validated through their returned
+ *   representation; internal fields excluded by that method are not inspected.
+ * - Object keys are sorted recursively.
+ * - Unsupported types (`undefined`, `bigint`, symbols, functions, non-finite
+ *   numbers, `Map`, `Set`, `Error`, `RegExp`, binary buffers, promises,
+ *   symbol-keyed properties and sparse arrays) throw a {@link TypeError}.
+ * - Cyclic references are detected via a `WeakSet` and throw a {@link TypeError}.
+ *
+ * @param value The value to serialize.
+ * @returns The deterministic JSON string representation.
+ * @throws {TypeError} If the value is cyclic, contains non-serializable types, or
+ *   cannot be represented in JSON. The precise reason is the error's `cause`.
+ *
+ * @example
+ * ```ts
+ * stableStringify({ z: 1, a: 2 });
+ * // → '{"a":2,"z":1}'
+ * ```
+ */
+function stableStringify(value) {
+    try {
+        return JSON.stringify(toStrictJsonValue(value, true));
+    }
+    catch (cause) {
+        throw new TypeError('stableStringify requires an acyclic JSON-serializable value.', { cause });
+    }
+}
+//# sourceMappingURL=stableStringify.js.map

package/dist/stableStringify.js.map

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

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@cqrs-ddd/safe-stringify",
+  "version": "0.2.0",
+  "description": "Deterministic JSON for identity (cache keys, fingerprints) and safe, redacting JSON for logs, with no dependencies and no framework.",
+  "author": "Aristotelis",
+  "license": "SEE LICENSE IN LICENSE",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aristoteliss/nestjs-pipeline.git",
+    "directory": "packages/safe-stringify"
+  },
+  "homepage": "https://github.com/aristoteliss/nestjs-pipeline/tree/master/packages/safe-stringify#readme",
+  "bugs": {
+    "url": "https://github.com/aristoteliss/nestjs-pipeline/issues"
+  },
+  "keywords": [
+    "json",
+    "stable-stringify",
+    "deterministic",
+    "redaction",
+    "cache-key"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "COMMERCIAL_LICENSE.txt"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.11",
+    "vitest": "^4.1.11"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "build:watch": "tsc -p tsconfig.build.json --watch",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "rebuild": "pnpm run clean && pnpm run build",
+    "lint": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}