@stackline/deepmerge 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
+
+- Immutable deep object and array merge with zero runtime dependencies.
+- Default API compatibility with `deepmerge` v4, including `all`,
+  `arrayMerge`, `customMerge`, `clone`, and `isMergeableObject`.
+- Prototype-pollution protection for `__proto__`, `prototype`, and
+  `constructor` in target and source objects at every depth.
+- Optional strict unsafe-key rejection through `onUnsafeKey: 'throw'`.
+- Circular and shared-reference preservation.
+- Configurable `maxDepth` and `maxKeys` traversal limits.
+- ESM, callable CommonJS, browser-global, and source-map distributions.
+- TypeScript declarations tested from 3.9 through 7.0.
+- Differential compatibility tests against `deepmerge@4.3.1`.
+- Public documentation, security policy, CI matrix, and live playground.
+
+[1.0.0]: https://github.com/alexandroit/stackline-deepmerge/releases/tag/v1.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,51 @@
+# Contributing
+
+Thank you for improving `@stackline/deepmerge`.
+
+## Development
+
+Use Node.js 20 or newer for the development toolchain. The published runtime
+is separately tested on older supported Node.js versions.
+
+```bash
+npm ci
+npm test
+npm run test:attw
+npm run benchmark
+```
+
+## Pull requests
+
+Keep each change focused. A pull request should include:
+
+- a clear behavior statement;
+- tests for new or changed behavior;
+- compatibility impact;
+- security impact when object traversal changes;
+- documentation for public API changes.
+
+Do not weaken dangerous-key filtering, cycle handling, or resource limits to
+gain benchmark throughput.
+
+## Compatibility changes
+
+The default API intentionally tracks documented `deepmerge` v4 behavior.
+Before changing merge semantics:
+
+1. add a focused local test;
+2. add or update a differential compatibility case;
+3. document intentional differences;
+4. validate direct and npm-alias installation shapes.
+
+## Security changes
+
+Security fixes should not be discussed 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,14 @@
+@stackline/deepmerge
+Copyright (c) 2026 Alexandro Paixao Marques and contributors
+
+This package is an independent implementation. Its public behavior is designed
+to support migration from deepmerge version 4, a separate MIT-licensed project
+by James Halliday, Josh Duff, and other contributors:
+
+https://github.com/TehShrike/deepmerge
+
+The upstream package is used as a development-only behavioral reference in the
+differential compatibility tests. It is not included as a runtime dependency.
+
+The name "deepmerge" is used descriptively for API compatibility. This project
+is not affiliated with or endorsed by the upstream maintainers.

package/README.md

@@ -0,0 +1,311 @@
+# @stackline/deepmerge
+
+> Secure, immutable, zero-dependency deep merge for modern JavaScript, with a
+> `deepmerge`-compatible API.
+
+[![npm version](https://img.shields.io/npm/v/@stackline/deepmerge.svg?style=flat-square)](https://www.npmjs.com/package/@stackline/deepmerge)
+[![npm downloads](https://img.shields.io/npm/dm/@stackline/deepmerge.svg?style=flat-square)](https://www.npmjs.com/package/@stackline/deepmerge)
+[![CI](https://img.shields.io/github/actions/workflow/status/alexandroit/stackline-deepmerge/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/alexandroit/stackline-deepmerge/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/@stackline/deepmerge.svg?style=flat-square)](LICENSE)
+[![zero dependencies](https://img.shields.io/badge/runtime%20dependencies-0-159957?style=flat-square)](package.json)
+
+**[Docs and playground](https://alexandro.net/docs/vanilla/deepmerge/)** |
+**[npm](https://www.npmjs.com/package/@stackline/deepmerge)** |
+**[Security](SECURITY.md)** |
+**[Changelog](CHANGELOG.md)** |
+**[Issues](https://github.com/alexandroit/stackline-deepmerge/issues)**
+
+## Why this package?
+
+Deep merge sits on a trust boundary in configuration loaders, build tools,
+servers, CLIs, and browser applications. A useful replacement must be safe for
+untrusted object keys without forcing existing projects to rewrite every merge.
+
+`@stackline/deepmerge` combines:
+
+- rejection of `__proto__`, `prototype`, and `constructor` at every depth;
+- immutable merges with cycle and shared-reference preservation;
+- configurable depth and key limits for hostile or malformed inputs;
+- the familiar `deepmerge` v4 default API and extension hooks;
+- ESM, callable CommonJS, TypeScript, and browser builds;
+- TypeScript compatibility tested from 3.9 through 7.0;
+- zero runtime dependencies.
+
+## Installation
+
+Install under the package's public name:
+
+```bash
+npm install @stackline/deepmerge
+```
+
+Or replace `deepmerge` without changing application imports:
+
+```bash
+npm install deepmerge@npm:@stackline/deepmerge
+```
+
+Existing code can continue to use:
+
+```js
+import merge from 'deepmerge';
+
+const config = merge(defaults, environment);
+```
+
+## Quick start
+
+```js
+import merge from '@stackline/deepmerge';
+
+const defaults = {
+  server: { port: 3000, headers: { accept: 'application/json' } },
+  plugins: ['core']
+};
+
+const production = {
+  server: { port: 8080, headers: { authorization: 'Bearer token' } },
+  plugins: ['metrics']
+};
+
+const config = merge(defaults, production);
+
+// {
+//   server: {
+//     port: 8080,
+//     headers: {
+//       accept: 'application/json',
+//       authorization: 'Bearer token'
+//     }
+//   },
+//   plugins: ['core', 'metrics']
+// }
+```
+
+Neither input is mutated.
+
+## Secure by default
+
+Dangerous keys are skipped from both inputs before their values are read:
+
+```js
+import merge from '@stackline/deepmerge';
+
+const payload = JSON.parse(`{
+  "profile": {
+    "name": "Ada",
+    "constructor": {
+      "prototype": { "isAdmin": true }
+    }
+  }
+}`);
+
+const result = merge({}, payload);
+
+console.log(result);                    // { profile: { name: 'Ada' } }
+console.log(Object.prototype.isAdmin); // undefined
+```
+
+Use strict rejection when silent filtering is not appropriate:
+
+```js
+merge({}, payload, { onUnsafeKey: 'throw' });
+// UnsafeKeyError: Refusing to merge unsafe key constructor at
+// <root>.profile.constructor
+```
+
+Security limits are enabled by default:
+
+```js
+merge(target, source, {
+  maxDepth: 1000,
+  maxKeys: 100000
+});
+```
+
+Set a smaller limit at an exposed API boundary. `Infinity` is accepted when
+the input is already trusted.
+
+## API compatibility
+
+### `merge(target, source, options?)`
+
+Returns a new merged value. Objects merge recursively. Arrays concatenate by
+default. When an array and object occupy the same position, the source wins.
+
+### `merge.all(objects, options?)`
+
+```js
+const config = merge.all([
+  { logging: { level: 'info' } },
+  { logging: { format: 'json' } },
+  { region: 'ca-central-1' }
+]);
+```
+
+### Options
+
+| Option | Default | Purpose |
+| :--- | :--- | :--- |
+| `arrayMerge` | concatenate | Replace or customize array behavior |
+| `clone` | `true` | Set `false` to preserve nested input references |
+| `customMerge` | none | Select a merge function for a property |
+| `isMergeableObject` | built in | Decide which values can be traversed |
+| `onUnsafeKey` | `"skip"` | Skip or throw on dangerous keys |
+| `maxDepth` | `1000` | Bound recursive traversal |
+| `maxKeys` | `100000` | Bound enumerable object keys per merge |
+
+The callback options include `cloneUnlessOtherwiseSpecified`, matching the
+extension-hook shape used by `deepmerge` v4.
+
+### Named exports
+
+```js
+import merge, {
+  DeepMergeLimitError,
+  UnsafeKeyError,
+  all,
+  deepmerge,
+  isMergeableObject
+} from '@stackline/deepmerge';
+```
+
+CommonJS remains callable:
+
+```js
+const merge = require('@stackline/deepmerge');
+
+merge({ left: true }, { right: true });
+merge.all([{ one: 1 }, { two: 2 }]);
+```
+
+## Array strategies
+
+Overwrite arrays:
+
+```js
+const overwrite = (_target, source) => source;
+const result = merge([1, 2], [3], { arrayMerge: overwrite });
+// [3]
+```
+
+Merge arrays by index:
+
+```js
+const byIndex = (target, source, options) => {
+  const output = target.slice();
+
+  source.forEach((value, index) => {
+    output[index] = index in output
+      ? merge(output[index], value, options)
+      : options.cloneUnlessOtherwiseSpecified(value, options);
+  });
+
+  return output;
+};
+```
+
+## Cycles and shared references
+
+Circular and repeated references are preserved instead of overflowing the
+stack or being duplicated unexpectedly:
+
+```js
+const shared = { enabled: true };
+const source = { first: shared, second: shared };
+source.self = source;
+
+const result = merge({}, source);
+
+result.first === result.second; // true
+result.self === result;         // true
+```
+
+## TypeScript
+
+The package ships declaration files for modern ESM, CommonJS, and older
+TypeScript resolvers. Return types recursively combine the target and source.
+
+```ts
+import merge from '@stackline/deepmerge';
+
+const result = merge(
+  { service: { port: 3000 } },
+  { service: { secure: true } }
+);
+
+result.service.port;   // number
+result.service.secure; // boolean
+```
+
+The release matrix tests TypeScript `3.9`, `4.7`, `4.9`, `5.9`, `6.0`, and
+`7.0`. The JavaScript runtime supports Node.js `14.17` and newer.
+
+## Browser
+
+Use the ESM build with a bundler, or load the small browser global directly:
+
+```html
+<script src="https://unpkg.com/@stackline/deepmerge@1.0.0/dist/index.min.js"></script>
+<script>
+  const merged = StacklineDeepmerge(
+    { theme: { contrast: 'normal' } },
+    { theme: { motion: 'reduced' } }
+  );
+</script>
+```
+
+## Migration from `deepmerge`
+
+The lowest-change migration uses an npm alias:
+
+```bash
+npm uninstall deepmerge
+npm install deepmerge@npm:@stackline/deepmerge
+```
+
+The compatibility suite covers documented options and 5,000 deterministic,
+JSON-compatible differential cases against `deepmerge@4.3.1`.
+
+Intentional hardening differences:
+
+- dangerous keys are always rejected or skipped;
+- cycles are preserved;
+- traversal limits are enabled by default;
+- invalid option values fail early with a controlled error.
+
+See [Compatibility](docs/COMPATIBILITY.md) for the full contract.
+
+## Performance
+
+Security checks, cycle tracking, and resource limits add measurable work. The
+included benchmark compares this package with `deepmerge@4.3.1` on the same
+process:
+
+```bash
+npm run benchmark
+```
+
+Use benchmark results as regression signals, not universal claims. Runtime,
+CPU, input shape, and custom callbacks materially affect throughput.
+
+## Trust and maintenance
+
+- No runtime dependencies.
+- Every release is built from the public repository.
+- CI validates behavior, types, package exports, clean installs, and supported
+  runtimes.
+- Security reports have a dedicated private process in [SECURITY.md](SECURITY.md).
+- Release history is recorded in [CHANGELOG.md](CHANGELOG.md).
+
+## Contributing
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. Changes
+to compatibility or security behavior require focused regression tests.
+
+## License
+
+MIT. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
+
+`@stackline/deepmerge` is an independent project and is not affiliated with or
+endorsed by the maintainers of the `deepmerge` package.

package/SECURITY.md

@@ -0,0 +1,50 @@
+# 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-deepmerge/security/advisories/new).
+
+Include:
+
+- the affected version;
+- a minimal reproducer or malicious input;
+- the observed impact;
+- the runtime and module system;
+- any proposed mitigation.
+
+We aim to acknowledge complete reports within three business days. Confirmed
+issues are fixed privately, covered by regression tests, and disclosed after a
+patched release is available.
+
+## Security contract
+
+The default merge path:
+
+- rejects `__proto__`, `prototype`, and `constructor` at every object depth;
+- checks both target and source keys;
+- does not read values behind rejected unsafe keys;
+- copies only own enumerable string and symbol keys;
+- writes accepted keys as data properties;
+- bounds depth and enumerable key traversal;
+- tracks circular and shared references.
+
+Use `{ onUnsafeKey: 'throw' }` when an unsafe key must reject the entire
+operation instead of being filtered.
+
+## Trust boundary
+
+Options and callbacks are executable application code. Do not accept
+`arrayMerge`, `customMerge`, or `isMergeableObject` functions from untrusted
+input. Safe property getters may execute when their values are merged, just as
+normal JavaScript property access does. Convert hostile wire formats with a
+trusted parser and use strict input limits at exposed boundaries.