{"id":48921437,"url":"https://github.com/y14e/gattai-merge","last_synced_at":"2026-05-16T04:24:03.746Z","repository":{"id":351572373,"uuid":"1211605903","full_name":"y14e/gattai-merge","owner":"y14e","description":"High-performance deep merge with structural sharing.","archived":false,"fork":false,"pushed_at":"2026-04-17T03:49:32.000Z","size":86,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-17T05:37:35.322Z","etag":null,"topics":["circular-reference","clone","deep-merge","immutable","map","merge","set","structural-sharing","typescript","utility"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/gattai-merge","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/y14e.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-15T15:01:14.000Z","updated_at":"2026-04-17T03:49:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/y14e/gattai-merge","commit_stats":null,"previous_names":["y14e/gattai-merge"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/y14e/gattai-merge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/y14e%2Fgattai-merge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/y14e%2Fgattai-merge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/y14e%2Fgattai-merge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/y14e%2Fgattai-merge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/y14e","download_url":"https://codeload.github.com/y14e/gattai-merge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/y14e%2Fgattai-merge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32181374,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-23T11:42:27.955Z","status":"ssl_error","status_checked_at":"2026-04-23T11:42:18.877Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["circular-reference","clone","deep-merge","immutable","map","merge","set","structural-sharing","typescript","utility"],"created_at":"2026-04-17T05:07:55.722Z","updated_at":"2026-05-16T04:24:03.741Z","avatar_url":"https://github.com/y14e.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gattai Merge\n\nHigh-performance deep merge utility with structural sharing. Supports circular ref and complex built-in types.\n\n* Fast (copy-on-write, minimal cloning)\n* Structural sharing (immutable-friendly)\n* Supports circular ref\n* Handles Map, Set, Array, TypedArray, Date, RegExp, etc.\n* Customizable array merge functions\n* Optional descriptor preservation\n\n---\n\n## Install\n\n```bash\nnpm i gattai-merge\n```\n\n```ts\n// npm\nimport gattaiMerge from 'gattai-merge';\n\n// CDNs\nimport gattaiMerge from 'https://esm.sh/gattai-merge'\n// or\nimport gattaiMerge from 'https://cdn.jsdelivr.net/npm/gattai-merge/+esm';\n// or\nimport gattaiMerge from 'https://unpkg.com/gattai-merge/dist/index.js';\n```\n\n## Usage\n\n```ts\ngattaiMerge(target, ...sources, options)\n// =\u003e DeepMergedObject\u003cT, S\u003e\n// \n// target: T\n// ...sources: ...S\n// options (optional): GattaiMergeOptions\n```\n\n### 🪄 Options\n\n```ts\ninterface GattaiMergeOptions {\n  arrays?: 'replace' | 'concat' | 'merge' | ArrayMergeFunction; // (default: 'replace')\n  nullish?: 'loose' | 'strict' | 'throw';                       // (default: 'loose')\n  preserveDescriptors?: boolean;                                // (default: false)\n  strictDescriptors?: boolean;                                  // (default: false)\n}\n```\n\n**arrays**\n\n* `'replace'`: replace target array (shallow copy)\n* `'concat'`: concatenate arrays\n* `'merge'`: deep merge by index\n* `ArrayMergeFunction`: custom array merge function (advanced usage)\n\n**nullish**\n\n* `'loose'`: keep target value if source is nullish\n* `'strict'`: overwrite target value if source is nullish\n* `'throw'`: throw TypeError if source is nullish\n\n**preserveDescriptors**\n\n* `false`: use standard merge (faster, ignores property descriptors)\n* `true`: preserve property descriptors (getters/setters, etc.)\n\n**strictDescriptors**\n\n* `false`: skip incompatible descriptors\n* `true`: throw if descriptor cannot be merged (e.g. non-configurable or non-writable)\n\n**ArrayMergeFunction**\n \n```ts\n(target, source, {\n  merge: (target, source) =\u003e {};\n  clone: (node) =\u003e {};\n}) =\u003e {};\n```\n\n## Examples\n\n### Array\n\n```ts\ngattaiMerge([1, 2], [3, 4]);\n// =\u003e [3, 4]\n\ngattaiMerge([1, 2], [3, 4], { arrays: 'concat' });\n// =\u003e [1, 2, 3, 4]\n\ngattaiMerge([{ a: 1 }], [{ b: 2 }], { arrays: 'merge' });\n// =\u003e [{ a: 1, b: 2 }]\n```\n\n### Custom array merge function\n\n```ts\ngattaiMerge(\n  [{ id: 1, value: 'A' }],\n  [{ id: 1, value: 'B' }, { id: 2, value: 'C' }],\n  {\n    // merge items by id\n    arrays: (target, source, { merge, clone }) =\u003e {\n      const map = new Map();\n\n      for (const item of target) {\n        map.set(item.id, item);\n      }\n\n      for (const item of source) {\n        if (map.has(item.id)) {\n          map.set(item.id, merge(map.get(item.id), item));\n        } else {\n          map.set(item.id, clone(item));\n        }\n      }\n\n      return Array.from(map.values());\n    },\n  }\n);\n// =\u003e [{ id: 1, value: 'B' }, { id: 2, value: 'C' }]\n```\n\n### Map / Set\n\n```ts\ngattaiMerge(\n  new Map([['a', 1]]),\n  new Map([['b', 2]])\n);\n// =\u003e Map { 'a' =\u003e 1, 'b' =\u003e 2 }\n```\n\n## Caution\n\nGattai Merge is optimized for performance using structural sharing (copy-on-write).\n\nObjects are only cloned when a change is actually required.\n\n\u003cdetails\u003e\n\u003csummary\u003eRead more\u003c/summary\u003e\n  \n### What this implies\n\nIf no changes occur during merging, the original target object is returned as-is:\n\n```ts\nconst a = { x: 1 };\nconst b = { x: 1 };\n\nconst result = gattaiMerge(a, b);\n\nresult === a; // true\n```\n\n### Important\n\nBecause the same ref may be returned, mutating the result can also mutate the original input:\n\n```ts\nresult.x = 2;\n\nconsole.log(a.x); // 2 (mutated!)\n```\n\n### When does this happen?\n\n* When merging produces **no effective changes**\n* When merging Map, Set, or nested structures with identical values\n* When structural sharing is preserved for performance\n\n### How to avoid this\n\n#### 1. Force a new object\n\n```ts\nconst result = gattaiMerge({}, a, b);\n```\n\n#### 2. Defensive cloning\n\n```ts\nconst result = gattaiMerge(a, b);\nconst safe = result === a ? { ...result } : result;\n```\n\n### Design note\n\nThis behavior is intentional and aligns with libraries like Immer, prioritizing performance by avoiding unnecessary cloning.\n\nIf you require strict immutability guarantees, consider wrapping or extending the API to always return a new object.\n\u003c/details\u003e\n\n## Performance\n\n* Avoids unnecessary cloning\n* Only clones changed branches\n* Comparable or faster than typical deep merge libraries in real-world scenarios\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fy14e%2Fgattai-merge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fy14e%2Fgattai-merge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fy14e%2Fgattai-merge/lists"}