@komed3/deepmerge 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Köhler
+
+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/README.md

@@ -0,0 +1,200 @@
+# @komed3/deepmerge
+
+A fast and efficient deep object merging and manipulation library for Node.js and the browser, optimized for performance and flexibility.
+
+`deepmerge` provides a high-performance `Merger` with a non-recursive stack-based implementation and a versatile `Accessor` for safe, deep object manipulation using dot and bracket notation. It includes a built-in path compiler with caching to ensure maximum efficiency during repeated operations.
+
+## Installation
+
+Install via npm:
+
+```bash
+npm install @komed3/deepmerge
+```
+
+## Import Methods
+
+`deepmerge` supports multiple module formats for seamless integration across different environments.
+
+### ESM (ECMAScript Modules)
+For modern projects using `import`:
+
+```ts
+import { factory, Merger, Accessor } from '@komed3/deepmerge';
+```
+
+### CommonJS
+For Node.js projects using `require`:
+
+```js
+const { factory, Merger, Accessor } = require( '@komed3/deepmerge' );
+```
+
+### UMD (Browser)
+Include the script in your HTML:
+
+```html
+<script src="node_modules/@komed3/deepmerge/dist/index.umd.min.js"></script>
+<script>
+    const { factory } = deepmerge;
+</script>
+```
+
+## Quick Usage
+
+The easiest way to get started is using the `factory()` function to create a new instance with a shared configuration.
+
+```ts
+import { factory } from '@komed3/deepmerge';
+
+// initialize with default options
+const qm = factory();
+
+const target = { user: { name: 'Max' } };
+const source = { user: { role: 'admin' }, tags: [ 'lead' ] };
+
+// deep merge objects
+qm.merger.merge( target, source );
+console.log( target ); // { user: { name: 'Max', role: 'admin' }, tags: [ 'lead' ] }
+
+// safe property access using dot/bracket notation
+const name = qm.accessor.get( target, 'user.name' ); // 'Max'
+qm.accessor.set( target, 'user.id', 123 );
+qm.accessor.update( target, 'tags[0]', v => v.toUpperCase() );
+
+console.log( target.user.id ); // 123
+console.log( target.tags ); // [ 'LEAD' ]
+```
+
+Instead of using the factory function, you can also create instances of `Merger`, `Accessor`, and `Path` directly:
+
+```ts
+import { Merger, Accessor, Path } from '@komed3/deepmerge';
+
+const merger = new Merger( { ... } );
+const accessor = new Accessor( { ... } );
+const path = new Path( { ... } );
+```
+
+## API Reference
+
+### factory( options? )
+Creates an object containing pre-configured instances of `Merger`, `Accessor`, and `Path`.
+
+```ts
+const { merger, accessor, path } = factory( { deep: true, protect: false } );
+```
+
+### Merger
+
+- `merge< T >( target: T, ...sources: any[] ) : T`  
+  Performs a deep merge of all source objects into the target.
+- `mergeAt< T >( target: T, path: PathLike, ...sources: any[] ) : T`  
+  Merges sources into the target at a specific nested path.
+
+### Accessor
+
+- `get< O, V >( obj: O, path: PathLike ) : V | undefined`  
+  Retrieves a value at the given path.
+- `set< O, V >( obj: O, path: PathLike, value: V ) : void`  
+  Sets a value at the path, creating missing structures if needed.
+- `has< O >( obj: O, path: PathLike ) : boolean`  
+  Checks if a nested property exists.
+- `delete< O >( obj: O, path: PathLike ) : void`  
+  Removes a property or array index at the path.
+- `update< O >( obj: O, path: PathLike, fn: ( v: any ) => any ) : void`  
+  Transforms a value at the path using a function.
+
+### Path
+
+- `compile( path: string ) : CompiledPath`  
+  Parses a path string into tokens and caches the result.
+- `normalize( path: PathLike ) : CompiledPath`  
+  Ensures a path is in its compiled format.
+
+## Options
+
+### MergeOptions
+- `deep` (boolean, default: `true`)  
+  Whether to perform deep merging of nested objects.
+- `protect` (boolean, default: `false`)  
+  If true, existing properties in the target are not overwritten.
+- `mergeUndefined` (boolean, default: `false`)  
+  Whether to allow `undefined` values from sources to overwrite target values.
+- `strict` (boolean, default: `false`)  
+  If true, new objects/arrays will not be created when paths are missing.
+- `createObject` (function, default: `() => Object.create( null )`)  
+  A factory function for creating new objects when missing structures are encountered during a deep merge.
+- `arrayMode` (`'replace' | 'keep' | 'concat' | 'unique'` | function, default: `'replace'`)  
+  Strategy for merging arrays or a custom merge function `( target: any[], source: any[] ) => any[]`.
+- `valueFn` (function)  
+  A custom function to handle specific value merging logic: `( key, targetVal, sourceVal ) => any`.
+- `pathOptions` (`PathOptions`)  
+  Configuration for the internal path compiler.
+
+### PathOptions
+- `cache` (boolean, default: `true`)  
+  Enable or disable caching of compiled path strings.
+- `maxCacheSize` (number, default: `1000`)  
+  The maximum number of paths to keep in the cache.
+
+## Customization
+
+### Custom Object Creation
+Use `createObject` to control how new objects are instantiated, for example to use plain objects instead of null-prototype objects:
+
+```ts
+const qm = factory( {
+  createObject: () => ( {} )
+} );
+```
+
+### Custom Array Merging
+Pass a function to `arrayMode` to implement your own logic, such as merging by a specific property:
+
+```ts
+const qm = factory( {
+  arrayMode: ( target, source ) => {
+    // custom merge logic
+    return [ ...target, ...source ].filter( v => v.active );
+  }
+} );
+```
+
+### Custom Value Merging
+Use `valueFn` to define custom logic for merging individual values:
+
+```ts
+const qm = factory( {
+  valueFn: ( key, targetVal, sourceVal ) => {
+    if ( key === 'count' ) {
+      return targetVal + sourceVal;
+    }
+    return sourceVal;
+  }
+} );
+```
+
+## Array Modes
+
+Control how arrays are handled during a merge using the built-in `ArrayMode` enums:
+
+- `Replace`: Overwrites the target array with the source array (default).
+- `Keep`: Retains the target array and ignores the source.
+- `Concat`: Appends source elements to the target array.
+- `Unique`: Combines both arrays and removes duplicates.
+
+```ts
+import { factory, ArrayMode } from '@komed3/deepmerge';
+
+const qm = factory( { arrayMode: ArrayMode.Unique } );
+const target = { ids: [ 1, 2 ] };
+qm.merger.merge( target, { ids: [ 2, 3 ] } );
+
+console.log( target.ids ); // [ 1, 2, 3 ]
+```
+
+----
+
+Copyright (c) 2026 Paul Köhler (komed3). All rights reserved.  
+Released under the MIT license. See LICENSE file in the project root for details.

package/dist/accessor.cjs

@@ -0,0 +1,62 @@
+'use strict';
+
+var path = require('./path.cjs');
+
+class Accessor {
+  path;
+  constructor(options = {}) {
+    this.path = new path.Path(options);
+  }
+  isUnsafeKey(key) {
+    return key === '__proto__' || key === 'constructor' || key === 'prototype';
+  }
+  walk(obj, path, create) {
+    const tokens = this.path.normalize(path).tokens;
+    let cur = obj;
+    for (let i = 0; i < tokens.length - 1; i++) {
+      const key = tokens[i];
+      if (this.isUnsafeKey(key)) return;
+      let next = cur?.[key];
+      if (next == null) {
+        if (!create) return;
+        next = typeof tokens[i + 1] === 'number' ? [] : {};
+        cur[key] = next;
+      }
+      cur = next;
+    }
+    const lastKey = tokens[tokens.length - 1];
+    return { parent: cur, key: lastKey, value: cur?.[lastKey] };
+  }
+  has(obj, path) {
+    const tokens = this.path.normalize(path).tokens;
+    let cur = obj;
+    for (let i = 0; i < tokens.length; i++) {
+      if (cur == null) return false;
+      cur = cur[tokens[i]];
+    }
+    return true;
+  }
+  get(obj, path) {
+    const tokens = this.path.normalize(path).tokens;
+    let cur = obj;
+    for (let i = 0; i < tokens.length; i++) {
+      if (cur == null) return undefined;
+      cur = cur[tokens[i]];
+    }
+    return cur;
+  }
+  set(obj, path, value) {
+    const res = this.walk(obj, path, true);
+    if (res) res.parent[res.key] = value;
+  }
+  delete(obj, path) {
+    const res = this.walk(obj, path, false);
+    if (res && res.parent != null) delete res.parent[res.key];
+  }
+  update(obj, path, fn) {
+    const res = this.walk(obj, path, true);
+    if (res) res.parent[res.key] = fn(res.value);
+  }
+}
+
+exports.Accessor = Accessor;

package/dist/accessor.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Accessor provides high-level methods for interacting with nested object structures.
+ *
+ * It allows for safe getting, setting, deleting, and updating of values at specific paths.
+ * The class handles path normalization and provides protection against prototype pollution.
+ *
+ * @author Paul Köhler
+ * @license MIT
+ */
+import { PathLike, PathOptions } from './path';
+/**
+ * The Accessor class provides a set of methods to access and manipulate data within objects
+ * using path strings or compiled path objects.
+ */
+export declare class Accessor {
+    /** The internal Path instance used for path normalization and compilation. */
+    private readonly path;
+    /**
+     * Creates a new Accessor instance with the given path options.
+     *
+     * @param {PathOptions} [options={}] - Configuration options for the internal Path handler.
+     */
+    constructor(options?: PathOptions);
+    /**
+     * Checks if a key is considered "unsafe" for object manipulation (prototype pollution protection).
+     *
+     * @param {any} key - The key to check.
+     * @returns {boolean} True if the key is unsafe, otherwise false.
+     */
+    private isUnsafeKey;
+    /**
+     * Internal method to traverse an object structure following a given path.
+     *
+     * @param {any} obj - The target object to walk through.
+     * @param {PathLike} path - The path to follow.
+     * @param {boolean} create - Whether to create missing objects/arrays along the path.
+     * @returns {{ parent: any, key: PathToken, value: any } | undefined} An object containing the parent, key, and value at the end of the path, or undefined if not found.
+     */
+    private walk;
+    /**
+     * Checks if a value exists at the specified path within an object.
+     *
+     * @template O
+     * @param {O} obj - The object to check.
+     * @param {PathLike} path - The path to verify.
+     * @returns {boolean} True if the path exists, otherwise false.
+     */
+    has<O = any>(obj: O, path: PathLike): boolean;
+    /**
+     * Retrieves the value at the specified path within an object.
+     *
+     * @template O, V
+     * @param {O} obj - The object to retrieve the value from.
+     * @param {PathLike} path - The path to the value.
+     * @returns {V | undefined} The value at the path, or undefined if not found.
+     */
+    get<O = any, V = any>(obj: O, path: PathLike): V | undefined;
+    /**
+     * Sets a value at the specified path within an object, creating missing structures if necessary.
+     *
+     * @template O, V
+     * @param {O} obj - The object to modify.
+     * @param {PathLike} path - The path where the value should be set.
+     * @param {V} value - The value to set.
+     */
+    set<O = any, V = any>(obj: O, path: PathLike, value: V): void;
+    /**
+     * Deletes the property/index at the specified path within an object.
+     *
+     * @template O
+     * @param {O} obj - The object to modify.
+     * @param {PathLike} path - The path to the property to delete.
+     */
+    delete<O = any>(obj: O, path: PathLike): void;
+    /**
+     * Updates the value at the specified path using a transformation function.
+     *
+     * @template O
+     * @param {O} obj - The object to modify.
+     * @param {PathLike} path - The path to the value to update.
+     * @param {( v: any ) => any} fn - The function to transform the existing value.
+     */
+    update<O = any>(obj: O, path: PathLike, fn: (v: any) => any): void;
+}

package/dist/accessor.mjs

@@ -0,0 +1,60 @@
+import { Path } from './path.mjs';
+
+class Accessor {
+  path;
+  constructor(options = {}) {
+    this.path = new Path(options);
+  }
+  isUnsafeKey(key) {
+    return key === '__proto__' || key === 'constructor' || key === 'prototype';
+  }
+  walk(obj, path, create) {
+    const tokens = this.path.normalize(path).tokens;
+    let cur = obj;
+    for (let i = 0; i < tokens.length - 1; i++) {
+      const key = tokens[i];
+      if (this.isUnsafeKey(key)) return;
+      let next = cur?.[key];
+      if (next == null) {
+        if (!create) return;
+        next = typeof tokens[i + 1] === 'number' ? [] : {};
+        cur[key] = next;
+      }
+      cur = next;
+    }
+    const lastKey = tokens[tokens.length - 1];
+    return { parent: cur, key: lastKey, value: cur?.[lastKey] };
+  }
+  has(obj, path) {
+    const tokens = this.path.normalize(path).tokens;
+    let cur = obj;
+    for (let i = 0; i < tokens.length; i++) {
+      if (cur == null) return false;
+      cur = cur[tokens[i]];
+    }
+    return true;
+  }
+  get(obj, path) {
+    const tokens = this.path.normalize(path).tokens;
+    let cur = obj;
+    for (let i = 0; i < tokens.length; i++) {
+      if (cur == null) return undefined;
+      cur = cur[tokens[i]];
+    }
+    return cur;
+  }
+  set(obj, path, value) {
+    const res = this.walk(obj, path, true);
+    if (res) res.parent[res.key] = value;
+  }
+  delete(obj, path) {
+    const res = this.walk(obj, path, false);
+    if (res && res.parent != null) delete res.parent[res.key];
+  }
+  update(obj, path, fn) {
+    const res = this.walk(obj, path, true);
+    if (res) res.parent[res.key] = fn(res.value);
+  }
+}
+
+export { Accessor };

package/dist/bundle.umd.js

@@ -0,0 +1,248 @@
+(function (global, factory) {
+  typeof exports === 'object' && typeof module !== 'undefined'
+    ? factory(exports)
+    : typeof define === 'function' && define.amd
+      ? define(['exports'], factory)
+      : ((global =
+          typeof globalThis !== 'undefined' ? globalThis : global || self),
+        factory((global.deepmerge = {})));
+})(this, function (exports) {
+  'use strict';
+
+  class Path {
+    cache;
+    maxCacheSize;
+    constructor(options = {}) {
+      if (options.cache !== false) this.cache = new Map();
+      this.maxCacheSize = options.maxCacheSize ?? 1000;
+    }
+    compile(path) {
+      if (!path) return Object.freeze({ tokens: [] });
+      if (this.cache) {
+        const cached = this.cache.get(path);
+        if (cached) return cached;
+      }
+      const tokens = [];
+      let i = 0,
+        key = '';
+      while (i < path.length) {
+        const c = path.charCodeAt(i);
+        if (c === 46) {
+          if (key) {
+            (tokens.push(key), (key = ''));
+          }
+          i++;
+          continue;
+        }
+        if (c === 91) {
+          if (key) {
+            (tokens.push(key), (key = ''));
+          }
+          i++;
+          const start = i;
+          while (i < path.length && path.charCodeAt(i) !== 93) i++;
+          const inner = path.slice(start, i);
+          const num = inner >>> 0;
+          if (String(num) === inner) tokens.push(num);
+          else tokens.push(inner);
+          i++;
+          continue;
+        }
+        ((key += path[i]), i++);
+      }
+      if (key) tokens.push(key);
+      const compiled = Object.freeze({ tokens });
+      if (this.cache) {
+        if (this.cache.size >= this.maxCacheSize) this.cache.clear();
+        this.cache.set(path, compiled);
+      }
+      return compiled;
+    }
+    isCompiled(path) {
+      return path && Array.isArray(path.tokens);
+    }
+    normalize(path) {
+      return typeof path === 'string' ? this.compile(path) : path;
+    }
+    clearCache() {
+      this.cache?.clear();
+    }
+    get size() {
+      return this.cache?.size ?? 0;
+    }
+  }
+
+  class Accessor {
+    path;
+    constructor(options = {}) {
+      this.path = new Path(options);
+    }
+    isUnsafeKey(key) {
+      return (
+        key === '__proto__' || key === 'constructor' || key === 'prototype'
+      );
+    }
+    walk(obj, path, create) {
+      const tokens = this.path.normalize(path).tokens;
+      let cur = obj;
+      for (let i = 0; i < tokens.length - 1; i++) {
+        const key = tokens[i];
+        if (this.isUnsafeKey(key)) return;
+        let next = cur?.[key];
+        if (next == null) {
+          if (!create) return;
+          next = typeof tokens[i + 1] === 'number' ? [] : {};
+          cur[key] = next;
+        }
+        cur = next;
+      }
+      const lastKey = tokens[tokens.length - 1];
+      return { parent: cur, key: lastKey, value: cur?.[lastKey] };
+    }
+    has(obj, path) {
+      const tokens = this.path.normalize(path).tokens;
+      let cur = obj;
+      for (let i = 0; i < tokens.length; i++) {
+        if (cur == null) return false;
+        cur = cur[tokens[i]];
+      }
+      return true;
+    }
+    get(obj, path) {
+      const tokens = this.path.normalize(path).tokens;
+      let cur = obj;
+      for (let i = 0; i < tokens.length; i++) {
+        if (cur == null) return undefined;
+        cur = cur[tokens[i]];
+      }
+      return cur;
+    }
+    set(obj, path, value) {
+      const res = this.walk(obj, path, true);
+      if (res) res.parent[res.key] = value;
+    }
+    delete(obj, path) {
+      const res = this.walk(obj, path, false);
+      if (res && res.parent != null) delete res.parent[res.key];
+    }
+    update(obj, path, fn) {
+      const res = this.walk(obj, path, true);
+      if (res) res.parent[res.key] = fn(res.value);
+    }
+  }
+
+  class Merger {
+    protect;
+    deep;
+    mergeUndefined;
+    strict;
+    createObject;
+    valueFn;
+    arrayFn;
+    path;
+    constructor(options = {}) {
+      this.protect = !!options.protect;
+      this.deep = options.deep !== false;
+      this.mergeUndefined = !!options.mergeUndefined;
+      this.strict = !!options.strict;
+      this.createObject = options.createObject ?? (() => Object.create(null));
+      this.valueFn = options.valueFn;
+      this.arrayFn = this.compileArrayFn(options.arrayMode);
+      this.path = new Path(options.pathOptions);
+    }
+    compileArrayFn(mode) {
+      switch (mode ?? 'replace') {
+        case 'replace':
+          return (_, s) => s;
+        case 'keep':
+          return (t, _) => t;
+        case 'concat':
+          return (t, s) => t.concat(s);
+        case 'unique':
+          return (t, s) => {
+            const set = new Set(t);
+            for (let i = 0; i < s.length; i++) set.add(s[i]);
+            return Array.from(set);
+          };
+      }
+      if (typeof mode === 'function') return mode;
+      else throw new Error(`Invalid array merge mode: ${mode}`);
+    }
+    isUnsafeKey(key) {
+      return (
+        key === '__proto__' || key === 'constructor' || key === 'prototype'
+      );
+    }
+    mergeInto(target, source) {
+      if (source == null) return;
+      const stack = [[target, source]];
+      while (stack.length) {
+        const [t, s] = stack.pop();
+        for (const key in s) {
+          if (this.isUnsafeKey(key)) continue;
+          const sv = s[key],
+            tv = t[key];
+          if (sv === undefined && !this.mergeUndefined) continue;
+          if (this.protect && key in t) continue;
+          if (this.valueFn) {
+            const res = this.valueFn(key, tv, sv);
+            if (res !== undefined) {
+              t[key] = res;
+              continue;
+            }
+          }
+          if (Array.isArray(sv)) {
+            if (Array.isArray(tv)) t[key] = this.arrayFn(tv, sv);
+            else t[key] = this.arrayFn([], sv);
+            continue;
+          }
+          if (this.deep && sv && typeof sv === 'object') {
+            if (tv && typeof tv === 'object') stack.push([tv, sv]);
+            else {
+              if (this.strict) continue;
+              const next = this.createObject();
+              t[key] = next;
+              stack.push([next, sv]);
+            }
+            continue;
+          }
+          t[key] = sv;
+        }
+      }
+    }
+    merge(target, ...sources) {
+      for (let i = 0; i < sources.length; i++)
+        this.mergeInto(target, sources[i]);
+      return target;
+    }
+    mergeAt(target, path, ...sources) {
+      const tokens = this.path.normalize(path).tokens;
+      let cur = target;
+      for (let i = 0; i < tokens.length; i++) {
+        const key = tokens[i];
+        if (this.isUnsafeKey(key)) return target;
+        let next = cur[key];
+        if (next == null) {
+          if (this.strict) return target;
+          next = typeof tokens[i + 1] === 'number' ? [] : this.createObject();
+          cur[key] = next;
+        }
+        cur = next;
+      }
+      for (let i = 0; i < sources.length; i++) this.mergeInto(cur, sources[i]);
+      return target;
+    }
+  }
+
+  const factory = (options) =>
+    Object.freeze({
+      accessor: new Accessor(options?.pathOptions),
+      merger: new Merger(options),
+      path: new Path(options?.pathOptions)
+    });
+
+  exports.Accessor = Accessor;
+  exports.Merger = Merger;
+  exports.Path = Path;
+  exports.factory = factory;
+});

package/dist/bundle.umd.min.js

@@ -0,0 +1 @@
+!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?t(exports):"function"==typeof define&&define.amd?define(["exports"],t):t((e="undefined"!=typeof globalThis?globalThis:e||self).deepmerge={})}(this,function(e){"use strict";class t{cache;maxCacheSize;constructor(e={}){!1!==e.cache&&(this.cache=new Map),this.maxCacheSize=e.maxCacheSize??1e3}compile(e){if(!e)return Object.freeze({tokens:[]});if(this.cache){const t=this.cache.get(e);if(t)return t}const t=[];let r=0,n="";for(;r<e.length;){const s=e.charCodeAt(r);if(46!==s){if(91===s){n&&(t.push(n),n=""),r++;const s=r;for(;r<e.length&&93!==e.charCodeAt(r);)r++;const i=e.slice(s,r),c=i>>>0;String(c)===i?t.push(c):t.push(i),r++;continue}n+=e[r],r++}else n&&(t.push(n),n=""),r++}n&&t.push(n);const s=Object.freeze({tokens:t});return this.cache&&(this.cache.size>=this.maxCacheSize&&this.cache.clear(),this.cache.set(e,s)),s}isCompiled(e){return e&&Array.isArray(e.tokens)}normalize(e){return"string"==typeof e?this.compile(e):e}clearCache(){this.cache?.clear()}get size(){return this.cache?.size??0}}class r{path;constructor(e={}){this.path=new t(e)}isUnsafeKey(e){return"__proto__"===e||"constructor"===e||"prototype"===e}walk(e,t,r){const n=this.path.normalize(t).tokens;let s=e;for(let e=0;e<n.length-1;e++){const t=n[e];if(this.isUnsafeKey(t))return;let i=s?.[t];if(null==i){if(!r)return;i="number"==typeof n[e+1]?[]:{},s[t]=i}s=i}const i=n[n.length-1];return{parent:s,key:i,value:s?.[i]}}has(e,t){const r=this.path.normalize(t).tokens;let n=e;for(let e=0;e<r.length;e++){if(null==n)return!1;n=n[r[e]]}return!0}get(e,t){const r=this.path.normalize(t).tokens;let n=e;for(let e=0;e<r.length;e++){if(null==n)return;n=n[r[e]]}return n}set(e,t,r){const n=this.walk(e,t,!0);n&&(n.parent[n.key]=r)}delete(e,t){const r=this.walk(e,t,!1);r&&null!=r.parent&&delete r.parent[r.key]}update(e,t,r){const n=this.walk(e,t,!0);n&&(n.parent[n.key]=r(n.value))}}class n{protect;deep;mergeUndefined;strict;createObject;valueFn;arrayFn;path;constructor(e={}){this.protect=!!e.protect,this.deep=!1!==e.deep,this.mergeUndefined=!!e.mergeUndefined,this.strict=!!e.strict,this.createObject=e.createObject??(()=>Object.create(null)),this.valueFn=e.valueFn,this.arrayFn=this.compileArrayFn(e.arrayMode),this.path=new t(e.pathOptions)}compileArrayFn(e){switch(e??"replace"){case"replace":return(e,t)=>t;case"keep":return(e,t)=>e;case"concat":return(e,t)=>e.concat(t);case"unique":return(e,t)=>{const r=new Set(e);for(let e=0;e<t.length;e++)r.add(t[e]);return Array.from(r)}}if("function"==typeof e)return e;throw new Error(`Invalid array merge mode: ${e}`)}isUnsafeKey(e){return"__proto__"===e||"constructor"===e||"prototype"===e}mergeInto(e,t){if(null==t)return;const r=[[e,t]];for(;r.length;){const[e,t]=r.pop();for(const n in t){if(this.isUnsafeKey(n))continue;const s=t[n],i=e[n];if((void 0!==s||this.mergeUndefined)&&(!this.protect||!(n in e))){if(this.valueFn){const t=this.valueFn(n,i,s);if(void 0!==t){e[n]=t;continue}}if(Array.isArray(s))Array.isArray(i)?e[n]=this.arrayFn(i,s):e[n]=this.arrayFn([],s);else if(this.deep&&s&&"object"==typeof s)if(i&&"object"==typeof i)r.push([i,s]);else{if(this.strict)continue;const t=this.createObject();e[n]=t,r.push([t,s])}else e[n]=s}}}}merge(e,...t){for(let r=0;r<t.length;r++)this.mergeInto(e,t[r]);return e}mergeAt(e,t,...r){const n=this.path.normalize(t).tokens;let s=e;for(let t=0;t<n.length;t++){const r=n[t];if(this.isUnsafeKey(r))return e;let i=s[r];if(null==i){if(this.strict)return e;i="number"==typeof n[t+1]?[]:this.createObject(),s[r]=i}s=i}for(let e=0;e<r.length;e++)this.mergeInto(s,r[e]);return e}}e.Accessor=r,e.Merger=n,e.Path=t,e.factory=e=>Object.freeze({accessor:new r(e?.pathOptions),merger:new n(e),path:new t(e?.pathOptions)})});

package/dist/index.cjs

@@ -0,0 +1,17 @@
+'use strict';
+
+var accessor = require('./accessor.cjs');
+var merger = require('./merger.cjs');
+var path = require('./path.cjs');
+
+const factory = (options) =>
+  Object.freeze({
+    accessor: new accessor.Accessor(options?.pathOptions),
+    merger: new merger.Merger(options),
+    path: new path.Path(options?.pathOptions)
+  });
+
+exports.Accessor = accessor.Accessor;
+exports.Merger = merger.Merger;
+exports.Path = path.Path;
+exports.factory = factory;

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * DeepMerge is a fast and flexible object merging library.
+ *
+ * Use the factory function to create a new instance of DeepMerge or
+ * import the individual classes to create your own instances.
+ *
+ * @author Paul Köhler
+ * @license MIT
+ */
+import { Accessor } from './accessor';
+import { Merger, type MergeOptions } from './merger';
+import { Path } from './path';
+export * from './accessor';
+export * from './merger';
+export * from './path';
+/**
+ * Creates a new instance of DeepMerge.
+ *
+ * @param {MergeOptions} options - Configuration options for the DeepMerge instance.
+ * @returns {DeepMerge} A new instance of DeepMerge.
+ */
+export declare const factory: (options?: MergeOptions) => Readonly<{
+    accessor: Accessor;
+    merger: Merger;
+    path: Path;
+}>;

package/dist/index.mjs

@@ -0,0 +1,12 @@
+import { Accessor } from './accessor.mjs';
+import { Merger } from './merger.mjs';
+import { Path } from './path.mjs';
+
+const factory = (options) =>
+  Object.freeze({
+    accessor: new Accessor(options?.pathOptions),
+    merger: new Merger(options),
+    path: new Path(options?.pathOptions)
+  });
+
+export { Accessor, Merger, Path, factory };

package/dist/merger.cjs

@@ -0,0 +1,105 @@
+'use strict';
+
+var path = require('./path.cjs');
+
+class Merger {
+  protect;
+  deep;
+  mergeUndefined;
+  strict;
+  createObject;
+  valueFn;
+  arrayFn;
+  path;
+  constructor(options = {}) {
+    this.protect = !!options.protect;
+    this.deep = options.deep !== false;
+    this.mergeUndefined = !!options.mergeUndefined;
+    this.strict = !!options.strict;
+    this.createObject = options.createObject ?? (() => Object.create(null));
+    this.valueFn = options.valueFn;
+    this.arrayFn = this.compileArrayFn(options.arrayMode);
+    this.path = new path.Path(options.pathOptions);
+  }
+  compileArrayFn(mode) {
+    switch (mode ?? 'replace') {
+      case 'replace':
+        return (_, s) => s;
+      case 'keep':
+        return (t, _) => t;
+      case 'concat':
+        return (t, s) => t.concat(s);
+      case 'unique':
+        return (t, s) => {
+          const set = new Set(t);
+          for (let i = 0; i < s.length; i++) set.add(s[i]);
+          return Array.from(set);
+        };
+    }
+    if (typeof mode === 'function') return mode;
+    else throw new Error(`Invalid array merge mode: ${mode}`);
+  }
+  isUnsafeKey(key) {
+    return key === '__proto__' || key === 'constructor' || key === 'prototype';
+  }
+  mergeInto(target, source) {
+    if (source == null) return;
+    const stack = [[target, source]];
+    while (stack.length) {
+      const [t, s] = stack.pop();
+      for (const key in s) {
+        if (this.isUnsafeKey(key)) continue;
+        const sv = s[key],
+          tv = t[key];
+        if (sv === undefined && !this.mergeUndefined) continue;
+        if (this.protect && key in t) continue;
+        if (this.valueFn) {
+          const res = this.valueFn(key, tv, sv);
+          if (res !== undefined) {
+            t[key] = res;
+            continue;
+          }
+        }
+        if (Array.isArray(sv)) {
+          if (Array.isArray(tv)) t[key] = this.arrayFn(tv, sv);
+          else t[key] = this.arrayFn([], sv);
+          continue;
+        }
+        if (this.deep && sv && typeof sv === 'object') {
+          if (tv && typeof tv === 'object') stack.push([tv, sv]);
+          else {
+            if (this.strict) continue;
+            const next = this.createObject();
+            t[key] = next;
+            stack.push([next, sv]);
+          }
+          continue;
+        }
+        t[key] = sv;
+      }
+    }
+  }
+  merge(target, ...sources) {
+    for (let i = 0; i < sources.length; i++) this.mergeInto(target, sources[i]);
+    return target;
+  }
+  mergeAt(target, path, ...sources) {
+    const tokens = this.path.normalize(path).tokens;
+    let cur = target;
+    for (let i = 0; i < tokens.length; i++) {
+      const key = tokens[i];
+      if (this.isUnsafeKey(key)) return target;
+      let next = cur[key];
+      if (next == null) {
+        if (this.strict) return target;
+        next = typeof tokens[i + 1] === 'number' ? [] : this.createObject();
+        cur[key] = next;
+      }
+      cur = next;
+    }
+    for (let i = 0; i < sources.length; i++) this.mergeInto(cur, sources[i]);
+    return target;
+  }
+}
+
+exports.Merger = Merger;

package/dist/merger.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Merger provides powerful and flexible object merging capabilities.
+ *
+ * It supports deep merging, multiple array merge modes, custom value handlers,
+ * and path-based merging. The implementation is optimized for performance
+ * using a non-recursive stack-based approach.
+ *
+ * @author Paul Köhler
+ * @license MIT
+ */
+import { PathLike, PathOptions } from './path';
+/**
+ * Defines how arrays should be merged when they exist in both target and source.
+ */
+export declare const enum ArrayMode {
+    /** Replace the target array with the source array (default). */
+    Replace = "replace",
+    /** Keep the target array and ignore the source array. */
+    Keep = "keep",
+    /** Concatenate the source array to the target array. */
+    Concat = "concat",
+    /** Merge unique elements from both arrays. */
+    Unique = "unique"
+}
+/** Function signature for custom array merging logic. */
+export type ArrayFn = (target: any[], source: any[]) => any[];
+/** Function signature for custom value merging logic. */
+export type ValueFn = (key: PropertyKey, targetVal: any, sourceVal: any) => any;
+/** Configuration options for the Merger. */
+export interface MergeOptions {
+    /** If true, existing properties in the target are not overwritten. */
+    protect?: boolean;
+    /** Whether to perform a deep merge (defaults to true). */
+    deep?: boolean;
+    /** If true, undefined values in the source will overwrite target values (defaults to false). */
+    mergeUndefined?: boolean;
+    /** If true, only existing objects in the target will be merged into. */
+    strict?: boolean;
+    /** Factory function for creating new objects during deep merge (defaults to Object.create( null )). */
+    createObject?: () => any;
+    /** The mode for merging arrays or a custom merge function. */
+    arrayMode?: ArrayMode | ArrayFn;
+    /** A custom function to handle specific value merging. */
+    valueFn?: ValueFn;
+    /** Options for the internal Path handler used in mergeAt. */
+    pathOptions?: PathOptions;
+}
+/**
+ * The Merger class implements the core logic for deep-merging objects.
+ * It is designed to be highly configurable and efficient.
+ */
+export declare class Merger {
+    /** Whether to protect existing properties in the target. */
+    private readonly protect;
+    /** Whether to perform deep merging. */
+    private readonly deep;
+    /** Whether to allow merging of undefined values. */
+    private readonly mergeUndefined;
+    /** Whether to operate in strict mode (no creation of missing structures). */
+    private readonly strict;
+    /** Function to create new objects when needed. */
+    private readonly createObject;
+    /** Custom value merging function. */
+    private readonly valueFn?;
+    /** Internal function used for array merging. */
+    private readonly arrayFn;
+    /** Internal Path instance for path-based operations. */
+    private readonly path;
+    /**
+     * Creates a new Merger instance with the specified options.
+     *
+     * @param {MergeOptions} options - Configuration options for the Merger.
+     */
+    constructor(options?: MergeOptions);
+    /**
+     * Compiles an array merge mode or function into an ArrayFn.
+     *
+     * @param {ArrayMode | ArrayFn} [mode] - The mode or function to compile.
+     * @returns {ArrayFn} The compiled array merge function.
+     * @throws {Error} If an invalid mode is provided.
+     */
+    private compileArrayFn;
+    /**
+     * Checks if a key is considered "unsafe" for object manipulation.
+     *
+     * @param {any} key - The key to check.
+     * @returns {boolean} True if the key is unsafe, otherwise false.
+     */
+    private isUnsafeKey;
+    /**
+     * Performs the actual merging of a source object into a target object.
+     * This method uses a stack-based approach to avoid recursion for better performance.
+     *
+     * @param {any} target - The destination object.
+     * @param {any} source - The source object to merge from.
+     */
+    private mergeInto;
+    /**
+     * Merges one or more source objects into the specified target object.
+     *
+     * @template T
+     * @param {T} target - The target object to merge into.
+     * @param {...any[]} sources - One or more source objects.
+     * @returns {T} The updated target object.
+     */
+    merge<T>(target: T, ...sources: any[]): T;
+    /**
+     * Merges source objects into the target object at a specific path.
+     *
+     * @template T
+     * @param {T} target - The target object.
+     * @param {PathLike} path - The path inside the target where sources should be merged.
+     * @param {...any[]} sources - One or more source objects to merge.
+     * @returns {T} The updated target object.
+     */
+    mergeAt<T>(target: T, path: PathLike, ...sources: any[]): T;
+}

package/dist/merger.mjs

@@ -0,0 +1,103 @@
+import { Path } from './path.mjs';
+
+class Merger {
+  protect;
+  deep;
+  mergeUndefined;
+  strict;
+  createObject;
+  valueFn;
+  arrayFn;
+  path;
+  constructor(options = {}) {
+    this.protect = !!options.protect;
+    this.deep = options.deep !== false;
+    this.mergeUndefined = !!options.mergeUndefined;
+    this.strict = !!options.strict;
+    this.createObject = options.createObject ?? (() => Object.create(null));
+    this.valueFn = options.valueFn;
+    this.arrayFn = this.compileArrayFn(options.arrayMode);
+    this.path = new Path(options.pathOptions);
+  }
+  compileArrayFn(mode) {
+    switch (mode ?? 'replace') {
+      case 'replace':
+        return (_, s) => s;
+      case 'keep':
+        return (t, _) => t;
+      case 'concat':
+        return (t, s) => t.concat(s);
+      case 'unique':
+        return (t, s) => {
+          const set = new Set(t);
+          for (let i = 0; i < s.length; i++) set.add(s[i]);
+          return Array.from(set);
+        };
+    }
+    if (typeof mode === 'function') return mode;
+    else throw new Error(`Invalid array merge mode: ${mode}`);
+  }
+  isUnsafeKey(key) {
+    return key === '__proto__' || key === 'constructor' || key === 'prototype';
+  }
+  mergeInto(target, source) {
+    if (source == null) return;
+    const stack = [[target, source]];
+    while (stack.length) {
+      const [t, s] = stack.pop();
+      for (const key in s) {
+        if (this.isUnsafeKey(key)) continue;
+        const sv = s[key],
+          tv = t[key];
+        if (sv === undefined && !this.mergeUndefined) continue;
+        if (this.protect && key in t) continue;
+        if (this.valueFn) {
+          const res = this.valueFn(key, tv, sv);
+          if (res !== undefined) {
+            t[key] = res;
+            continue;
+          }
+        }
+        if (Array.isArray(sv)) {
+          if (Array.isArray(tv)) t[key] = this.arrayFn(tv, sv);
+          else t[key] = this.arrayFn([], sv);
+          continue;
+        }
+        if (this.deep && sv && typeof sv === 'object') {
+          if (tv && typeof tv === 'object') stack.push([tv, sv]);
+          else {
+            if (this.strict) continue;
+            const next = this.createObject();
+            t[key] = next;
+            stack.push([next, sv]);
+          }
+          continue;
+        }
+        t[key] = sv;
+      }
+    }
+  }
+  merge(target, ...sources) {
+    for (let i = 0; i < sources.length; i++) this.mergeInto(target, sources[i]);
+    return target;
+  }
+  mergeAt(target, path, ...sources) {
+    const tokens = this.path.normalize(path).tokens;
+    let cur = target;
+    for (let i = 0; i < tokens.length; i++) {
+      const key = tokens[i];
+      if (this.isUnsafeKey(key)) return target;
+      let next = cur[key];
+      if (next == null) {
+        if (this.strict) return target;
+        next = typeof tokens[i + 1] === 'number' ? [] : this.createObject();
+        cur[key] = next;
+      }
+      cur = next;
+    }
+    for (let i = 0; i < sources.length; i++) this.mergeInto(cur, sources[i]);
+    return target;
+  }
+}
+
+export { Merger };

package/dist/path.cjs

@@ -0,0 +1,66 @@
+'use strict';
+
+class Path {
+  cache;
+  maxCacheSize;
+  constructor(options = {}) {
+    if (options.cache !== false) this.cache = new Map();
+    this.maxCacheSize = options.maxCacheSize ?? 1000;
+  }
+  compile(path) {
+    if (!path) return Object.freeze({ tokens: [] });
+    if (this.cache) {
+      const cached = this.cache.get(path);
+      if (cached) return cached;
+    }
+    const tokens = [];
+    let i = 0,
+      key = '';
+    while (i < path.length) {
+      const c = path.charCodeAt(i);
+      if (c === 46) {
+        if (key) {
+          (tokens.push(key), (key = ''));
+        }
+        i++;
+        continue;
+      }
+      if (c === 91) {
+        if (key) {
+          (tokens.push(key), (key = ''));
+        }
+        i++;
+        const start = i;
+        while (i < path.length && path.charCodeAt(i) !== 93) i++;
+        const inner = path.slice(start, i);
+        const num = inner >>> 0;
+        if (String(num) === inner) tokens.push(num);
+        else tokens.push(inner);
+        i++;
+        continue;
+      }
+      ((key += path[i]), i++);
+    }
+    if (key) tokens.push(key);
+    const compiled = Object.freeze({ tokens });
+    if (this.cache) {
+      if (this.cache.size >= this.maxCacheSize) this.cache.clear();
+      this.cache.set(path, compiled);
+    }
+    return compiled;
+  }
+  isCompiled(path) {
+    return path && Array.isArray(path.tokens);
+  }
+  normalize(path) {
+    return typeof path === 'string' ? this.compile(path) : path;
+  }
+  clearCache() {
+    this.cache?.clear();
+  }
+  get size() {
+    return this.cache?.size ?? 0;
+  }
+}
+
+exports.Path = Path;

package/dist/path.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Path provides utilities for compiling and normalizing object paths.
+ *
+ * It supports dot notation (e.g., 'a.b.c') and bracket notation (e.g., 'a[0].b').
+ * Efficient path compilation is achieved through optional caching.
+ *
+ * @author Paul Köhler
+ * @license MIT
+ */
+/** Represents a single segment of a path, either a string key or a numeric index. */
+export type PathToken = string | number;
+/** Represents a compiled path, consisting of an array of tokens. */
+export interface CompiledPath {
+    /** The tokens that make up the path. */
+    readonly tokens: PathToken[];
+}
+/** Types that can be treated as a path: a string or a pre-compiled path object. */
+export type PathLike = string | CompiledPath;
+/** Configuration options for path handling. */
+export interface PathOptions {
+    /** Whether to enable caching of compiled paths (defaults to true). */
+    cache?: boolean;
+    /** The maximum number of paths to keep in the cache (defaults to 1000). */
+    maxCacheSize?: number;
+}
+/**
+ * The Path class handles the parsing and compilation of path strings into tokens.
+ * It provides a centralized way to work with object paths across the library.
+ */
+export declare class Path {
+    /** Internal cache for compiled paths. */
+    private cache?;
+    /** The maximum allowed size of the path cache. */
+    private maxCacheSize;
+    /**
+     * Creates a new Path instance with the specified options.
+     *
+     * @param {PathOptions} [options={}] - Configuration options for the Path instance.
+     */
+    constructor(options?: PathOptions);
+    /**
+     * Compiles a path string into a CompiledPath object.
+     *
+     * @param {string} path - The path string to compile.
+     * @returns {CompiledPath} The compiled path object.
+     */
+    compile(path: string): CompiledPath;
+    /**
+     * Checks if a value is a CompiledPath object.
+     *
+     * @param {any} path - The value to check.
+     * @returns {path is CompiledPath} True if the value is a CompiledPath.
+     */
+    isCompiled(path: any): path is CompiledPath;
+    /**
+     * Normalizes a path-like value into a CompiledPath.
+     *
+     * @param {PathLike} path - The path-like value to normalize.
+     * @returns {CompiledPath} The normalized CompiledPath.
+     */
+    normalize(path: PathLike): CompiledPath;
+    /**
+     * Clears the internal path cache.
+     */
+    clearCache(): void;
+    /**
+     * Returns the current number of cached paths.
+     *
+     * @returns {number} The size of the cache.
+     */
+    get size(): number;
+}

package/dist/path.mjs

@@ -0,0 +1,64 @@
+class Path {
+  cache;
+  maxCacheSize;
+  constructor(options = {}) {
+    if (options.cache !== false) this.cache = new Map();
+    this.maxCacheSize = options.maxCacheSize ?? 1000;
+  }
+  compile(path) {
+    if (!path) return Object.freeze({ tokens: [] });
+    if (this.cache) {
+      const cached = this.cache.get(path);
+      if (cached) return cached;
+    }
+    const tokens = [];
+    let i = 0,
+      key = '';
+    while (i < path.length) {
+      const c = path.charCodeAt(i);
+      if (c === 46) {
+        if (key) {
+          (tokens.push(key), (key = ''));
+        }
+        i++;
+        continue;
+      }
+      if (c === 91) {
+        if (key) {
+          (tokens.push(key), (key = ''));
+        }
+        i++;
+        const start = i;
+        while (i < path.length && path.charCodeAt(i) !== 93) i++;
+        const inner = path.slice(start, i);
+        const num = inner >>> 0;
+        if (String(num) === inner) tokens.push(num);
+        else tokens.push(inner);
+        i++;
+        continue;
+      }
+      ((key += path[i]), i++);
+    }
+    if (key) tokens.push(key);
+    const compiled = Object.freeze({ tokens });
+    if (this.cache) {
+      if (this.cache.size >= this.maxCacheSize) this.cache.clear();
+      this.cache.set(path, compiled);
+    }
+    return compiled;
+  }
+  isCompiled(path) {
+    return path && Array.isArray(path.tokens);
+  }
+  normalize(path) {
+    return typeof path === 'string' ? this.compile(path) : path;
+  }
+  clearCache() {
+    this.cache?.clear();
+  }
+  get size() {
+    return this.cache?.size ?? 0;
+  }
+}
+
+export { Path };

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@komed3/deepmerge",
+  "description": "Fast and efficient deep object merging and manipulation library",
+  "license": "MIT",
+  "version": "1.0.0",
+  "author": {
+    "name": "komed3 (Paul Köhler)",
+    "email": "webmaster@komed3.de",
+    "url": "https://komed3.de"
+  },
+  "homepage": "https://github.com/komed3/deepmerge",
+  "keywords": [
+    "merge",
+    "object",
+    "manipulation",
+    "path",
+    "accessor",
+    "merger",
+    "deep-merge",
+    "deep-manipulation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/komed3/deepmerge.git"
+  },
+  "bugs": {
+    "url": "https://github.com/komed3/deepmerge/issues"
+  },
+  "funding": {
+    "type": "ko-fi",
+    "url": "https://ko-fi.com/komed3"
+  },
+  "files": [
+    "dist",
+    "README",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "types": "dist/index.d.ts",
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "browser": "dist/index.umd.min.js",
+  "jsdelivr": "dist/index.umd.min.js",
+  "unpkg": "dist/index.umd.min.js",
+  "scripts": {
+    "build": "rollup -c && tsc --emitDeclarationOnly",
+    "test": "node tests/access.js && node tests/merge.js && node tests/path.js"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^29.0.2",
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup/plugin-terser": "^1.0.0",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "rollup-plugin-cleanup": "^3.2.1",
+    "rollup-plugin-prettier": "^4.1.2",
+    "tslib": "^2.8.1",
+    "typescript": "^6.0.2"
+  }
+}