@stackline/stable-stringify 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes are documented here. This project follows Semantic
+Versioning.
+
+## [1.0.0] - 2026-08-16
+
+### Added
+
+- Deterministic recursive JSON serialization with zero runtime dependencies.
+- Compatible `fast-json-stable-stringify` comparator and cycle options.
+- Circular object and array policies: throw, marker, path, and null.
+- Iterative traversal tested with 25,000 nested containers.
+- BigInt, replacer, indentation, accessor, and `toJSON` policies.
+- Opt-in depth, entry, and output-length limits with structured errors.
+- Safe diagnostic serialization with bounded defaults and controlled fallback.
+- Strict RFC 8785 JSON canonicalization and UTF-8 byte output.
+- ESM, callable CommonJS, browser-global, and source-map distributions.
+- TypeScript declarations tested from 3.9 through 7.0.
+- 30,000 differential cases against `fast-json-stable-stringify@2.1.0`.
+- Public documentation, security policy, CI matrix, and live playground.
+
+[1.0.0]: https://github.com/alexandroit/stackline-stable-stringify/releases/tag/v1.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing
+
+Thank you for improving `@stackline/stable-stringify`.
+
+## Development
+
+Use Node.js 20 or newer for the development toolchain. Published runtime
+support is tested separately.
+
+```bash
+npm ci
+npm test
+npm run test:attw
+npm run benchmark
+```
+
+## Pull requests
+
+Keep each change focused. Include:
+
+- the behavior being changed;
+- tests for normal and adversarial input;
+- compatibility impact;
+- performance and security impact for traversal changes;
+- documentation for public API changes.
+
+Do not reduce canonical strictness, safe-mode limits, or error visibility to
+improve a benchmark.
+
+## Compatibility changes
+
+The default API tracks documented `fast-json-stable-stringify@2.1.0` behavior.
+Before changing stable-mode semantics:
+
+1. add a focused local regression;
+2. update the differential corpus when applicable;
+3. document every intentional difference;
+4. validate direct and npm-alias installation shapes.
+
+Canonical mode follows RFC 8785 and I-JSON constraints. Standards changes need
+a source citation and interoperability vector.
+
+## Security changes
+
+Do not discuss a suspected vulnerability in a public issue before a patched
+release exists. Follow [SECURITY.md](SECURITY.md).
+
+## Commits
+
+Use a short imperative subject. Keep generated output and unrelated formatting
+out of the same commit.
+
+By contributing, you agree that your contribution is licensed under the MIT
+License.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexandro Paixao Marques and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,21 @@
+@stackline/stable-stringify
+Copyright (c) 2026 Alexandro Paixao Marques and contributors
+
+This package is an independent implementation. Its default public behavior is
+designed to support migration from fast-json-stable-stringify version 2.1.0,
+a separate MIT-licensed project originally authored by James Halliday and
+maintained by Evgeny Poberezkin and contributors:
+
+https://github.com/epoberezkin/fast-json-stable-stringify
+
+The upstream package is used only as a development dependency and behavioral
+reference in differential tests. Its source code is not bundled and it is not
+a runtime dependency.
+
+The package names "fast-json-stable-stringify", "safe-stable-stringify",
+"fast-safe-stringify", and "json-stringify-safe" are used descriptively in
+compatibility tests, benchmarks, and market research. This project is not
+affiliated with or endorsed by their maintainers.
+
+RFC 8785, JSON Canonicalization Scheme (JCS), is an Internet Engineering Task
+Force standards-track document. Standards references do not imply endorsement.

package/README.md

@@ -0,0 +1,290 @@
+# @stackline/stable-stringify
+
+[![npm version](https://img.shields.io/npm/v/%40stackline%2Fstable-stringify)](https://www.npmjs.com/package/@stackline/stable-stringify)
+[![CI](https://github.com/alexandroit/stackline-stable-stringify/actions/workflows/ci.yml/badge.svg)](https://github.com/alexandroit/stackline-stable-stringify/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/alexandroit/stackline-stable-stringify/actions/workflows/codeql.yml/badge.svg)](https://github.com/alexandroit/stackline-stable-stringify/actions/workflows/codeql.yml)
+[![license](https://img.shields.io/npm/l/%40stackline%2Fstable-stringify)](LICENSE)
+
+Deterministic JSON serialization, safe diagnostics, and RFC 8785 canonical
+JSON in one zero-dependency package.
+
+The default export follows the familiar `fast-json-stable-stringify` API. It
+also handles circular arrays, deeply nested data without recursive call-stack
+failure, BigInt policies, resource limits, safe logging, and strict JSON
+Canonicalization Scheme output.
+
+## Why this package
+
+Stable serialization is infrastructure for cache keys, signatures, snapshots,
+deduplication, logs, and reproducible builds. The JavaScript ecosystem has
+separate high-volume packages for deterministic key order, circular data, safe
+logging, and canonical JSON. This package provides those contracts through one
+small, tested runtime while keeping the established call shape.
+
+- recursive deterministic key ordering;
+- compatible comparator and `{ cmp, cycles }` options;
+- cycle policies for objects and arrays;
+- safe defaults for diagnostics and logging;
+- RFC 8785 / JCS canonical strings and UTF-8 bytes;
+- iterative traversal for very deep input;
+- opt-in depth, entry, and output-size limits;
+- ESM, callable CommonJS, browser global, and TypeScript declarations;
+- zero runtime dependencies.
+
+## Install
+
+```bash
+npm install @stackline/stable-stringify
+```
+
+Keep an existing package name and imports with an npm alias:
+
+```bash
+npm install fast-json-stable-stringify@npm:@stackline/stable-stringify
+```
+
+```js
+const stringify = require('fast-json-stable-stringify');
+```
+
+## Quick start
+
+```js
+import stringify from '@stackline/stable-stringify';
+
+const first = { z: 1, nested: { y: 2, x: 3 }, a: true };
+const second = { a: true, nested: { x: 3, y: 2 }, z: 1 };
+
+stringify(first) === stringify(second); // true
+// {"a":true,"nested":{"x":3,"y":2},"z":1}
+```
+
+Arrays retain their input order. Object keys are sorted at every depth. Input
+objects are never mutated.
+
+## Safe serialization
+
+`safeStringify` is intended for logs, diagnostics, and error reporting. It
+serializes BigInt as strings, marks cycles, and applies bounded defaults.
+
+```js
+import { safeStringify } from '@stackline/stable-stringify';
+
+const event = { id: 42n };
+event.request = event;
+
+safeStringify(event);
+// {"id":"42","request":"[Circular]"}
+```
+
+Its default budgets are `maxDepth: 100`, `maxEntries: 100000`, and
+`maxLength: 1000000`. A hostile getter, throwing `toJSON`, or exceeded limit
+returns a controlled JSON string. Set `throwOnError: true` to propagate the
+original error.
+
+```js
+safeStringify(value, replacer, 2, {
+  depthLimit: 20,
+  edgesLimit: 5000,
+  maxLength: 250000,
+  throwOnError: true
+});
+```
+
+## RFC 8785 canonical JSON
+
+Use `canonicalize` when bytes must be reproducible across systems, such as
+digital signatures, content-addressed storage, or cryptographic hashes.
+
+```js
+import {
+  canonicalize,
+  canonicalizeBytes
+} from '@stackline/stable-stringify';
+
+canonicalize({ amount: 4.50, currency: 'CAD', active: true });
+// {"active":true,"amount":4.5,"currency":"CAD"}
+
+const bytes = canonicalizeBytes({ z: 1, a: 2 });
+// Uint8Array containing UTF-8 bytes for {"a":2,"z":1}
+```
+
+Canonical mode intentionally rejects data that cannot satisfy RFC 8785 and
+I-JSON, including:
+
+- `NaN`, `Infinity`, BigInt, `undefined`, functions, and symbols;
+- circular references and sparse arrays;
+- lone UTF-16 surrogates;
+- accessors, enumerable symbol properties, and class instances.
+
+It does not invoke getters or `toJSON`. Convert application objects to plain
+JSON data before canonicalization.
+
+## API
+
+### `stringify(value, options?)`
+
+The default export and the named `stableStringify` and `stringify` exports are
+the same function.
+
+```js
+import stringify from '@stackline/stable-stringify';
+
+stringify(value);
+stringify(value, comparator);
+stringify(value, { cmp: comparator, cycles: true });
+```
+
+Like `JSON.stringify`, a root `undefined`, function, or symbol returns
+`undefined`. Unsupported object properties are omitted and unsupported array
+items become `null`.
+
+### Stable options
+
+| Option | Default | Purpose |
+| :--- | :--- | :--- |
+| `cmp` | key order | Compare `{ key, value }` records |
+| `cycles` | `false` | Compatible shortcut for a `__cycle__` marker |
+| `onCycle` | `throw` | `throw`, `marker`, `path`, or `null` |
+| `cycleValue` | `__cycle__` | Custom marker for `onCycle: 'marker'` |
+| `bigint` | `throw` | `throw`, `string`, or safe `number` |
+| `replacer` | none | Function or JSON-style property list |
+| `space` | none | JSON-style indentation, capped at 10 characters |
+| `accessors` | `invoke` | `invoke`, `omit`, or `throw` |
+| `toJSON` | `true` | Invoke compatible `toJSON` hooks |
+| `maxDepth` | unlimited | Maximum container nesting depth |
+| `maxEntries` | unlimited | Maximum visited array items and object keys |
+| `maxLength` | unlimited | Maximum UTF-16 output length |
+
+Unlimited defaults preserve compatibility. Apply explicit limits at exposed
+trust boundaries, or use `safeStringify`.
+
+### Cycle paths
+
+```js
+const value = { id: 1 };
+value.child = { owner: value };
+
+stringify(value, { onCycle: 'path' });
+// {"child":{"owner":"[Circular <root>]"},"id":1}
+```
+
+Repeated sibling references are serialized normally; only references to an
+active ancestor are cycles.
+
+### Comparator
+
+```js
+const descending = (left, right) =>
+  right.key.localeCompare(left.key);
+
+stringify({ a: 1, c: 3, b: 2 }, descending);
+// {"c":3,"b":2,"a":1}
+```
+
+### `configure(defaults?)`
+
+Create a reusable serializer without rebuilding option objects at call sites.
+
+```js
+import { configure } from '@stackline/stable-stringify';
+
+const cacheKey = configure({
+  maxDepth: 50,
+  maxEntries: 10000,
+  maxLength: 500000
+});
+
+cacheKey({ route: '/users', query: { page: 2 } });
+```
+
+Per-call options override configured defaults.
+
+### Errors
+
+`StableStringifyLimitError` extends `RangeError` and exposes `code`, `kind`,
+`limit`, and `path`. `CanonicalizationError` extends `TypeError` and exposes
+`code`, `reason`, and `path`.
+
+## CommonJS
+
+```js
+const stringify = require('@stackline/stable-stringify');
+
+stringify({ z: 1, a: 2 });
+stringify.safeStringify(value);
+stringify.canonicalize(value);
+```
+
+## Browser
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@stackline/stable-stringify/dist/index.min.js"></script>
+<script>
+  const output = StacklineStableStringify({ z: 1, a: 2 });
+</script>
+```
+
+The browser global is callable and includes the same helper methods as the
+CommonJS export.
+
+## Compatibility
+
+The default contract is tested against `fast-json-stable-stringify@2.1.0`.
+The regression suite includes 30,000 deterministic differential
+serializations across generated values and comparator forms.
+
+Intentional additions do not alter default output:
+
+- circular arrays are handled instead of overflowing the call stack;
+- very deep structures use an iterative task stack;
+- replacer, indentation, BigInt, accessor, and resource policies are opt-in;
+- safe and canonical modes are separate named APIs.
+
+See [compatibility details](docs/COMPATIBILITY.md) before replacing a
+serializer that relies on undocumented edge behavior.
+
+## Runtime support
+
+The package is tested on Node.js 14.17 through current releases, Linux,
+Windows, macOS, Deno 2, Bun, and browsers. Type declarations are compiled in a
+matrix from TypeScript 3.9 through 7.0.
+
+## Performance
+
+Run the local comparison:
+
+```bash
+npm run benchmark
+```
+
+The benchmark reports native `JSON.stringify`,
+`fast-json-stable-stringify@2.1.0`, stable mode, safe mode, and RFC 8785 mode
+on the same payload. Native JSON is shown only as a throughput baseline; it
+does not recursively sort object keys. Measure with representative production
+data before selecting limits or modes.
+
+## Verification
+
+Every release runs:
+
+- 100% statement, line, and function coverage with at least 95% branches;
+- differential compatibility tests;
+- TypeScript 3.9 through 7.0 compilation;
+- clean tarball installs for direct and aliased package names;
+- ESM, CommonJS, browser, Deno, and Bun runtime checks;
+- `publint`, `attw`, dependency audit, CodeQL, SBOM, and checksum generation.
+
+The [live playground](https://alexandro.net/docs/vanilla/stable-stringify/)
+runs the published browser bundle.
+
+## Security
+
+Read [SECURITY.md](SECURITY.md) for the supported versions, trust boundaries,
+resource-limit guidance, and private reporting process.
+
+## License
+
+MIT. This is an independent implementation and is not affiliated with or
+endorsed by the maintainers of the comparison packages. See [NOTICE](NOTICE)
+for attribution and compatibility context.

package/SECURITY.md

@@ -0,0 +1,55 @@
+# Security Policy
+
+## Supported versions
+
+| Version | Security updates |
+| :--- | :---: |
+| `1.x` | Yes |
+| `< 1.0.0` | No public releases |
+
+## Reporting a vulnerability
+
+Do not open a public issue for a suspected vulnerability. Use the repository's
+[private security advisory form](https://github.com/alexandroit/stackline-stable-stringify/security/advisories/new).
+
+Include the affected version, a minimal reproducer, observed impact, runtime,
+module system, and proposed mitigation when available. Complete reports are
+normally acknowledged within three business days. Confirmed issues are fixed
+privately, covered by regression tests, and disclosed after a patched release.
+
+## Trust boundaries
+
+Stable mode preserves `JSON.stringify`-style behavior for compatibility. It
+may invoke a value's `toJSON`, a replacer callback, custom comparator, or
+property getter. Those are executable application code and must not be sourced
+from untrusted input.
+
+For hostile or externally supplied object graphs:
+
+- use `accessors: 'omit'` or `accessors: 'throw'`;
+- use `toJSON: false`;
+- set finite `maxDepth`, `maxEntries`, and `maxLength` values;
+- do not accept comparator or replacer functions from users.
+
+`safeStringify` applies finite defaults but preserves compatible getter and
+`toJSON` behavior unless explicitly disabled. Its fallback prevents a logging
+path from throwing by default; use `throwOnError: true` when failure must be
+observable by the caller.
+
+## Canonical mode
+
+`canonicalize` is the strictest input boundary. It does not invoke getters or
+`toJSON` and rejects accessors, class instances, symbol members, cycles, sparse
+arrays, non-finite numbers, BigInt, and malformed Unicode. It still traverses
+the supplied data, so keep finite limits when the input size is attacker
+controlled.
+
+Canonical JSON only provides deterministic bytes. It does not validate domain
+schemas, authenticate input, create signatures, or choose a cryptographic hash.
+
+## Denial-of-service controls
+
+The iterative traversal avoids JavaScript call-stack exhaustion. Memory and
+CPU use still grow with visited input and produced output. Resource limits are
+part of the security contract for public endpoints, log ingestion, and build
+systems processing third-party data.