{"id":13715075,"url":"https://github.com/planttheidea/unchanged","last_synced_at":"2025-10-11T13:35:02.849Z","repository":{"id":27603706,"uuid":"114571580","full_name":"planttheidea/unchanged","owner":"planttheidea","description":"A tiny, fast, unopinionated handler for updating JS objects and arrays immutably","archived":false,"fork":false,"pushed_at":"2024-03-28T17:33:26.000Z","size":2944,"stargazers_count":239,"open_issues_count":3,"forks_count":9,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-10-11T13:35:00.939Z","etag":null,"topics":["functional-programming","immutable","javascript"],"latest_commit_sha":null,"homepage":"","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/planttheidea.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2017-12-17T21:57:05.000Z","updated_at":"2025-06-19T19:37:47.000Z","dependencies_parsed_at":"2024-06-18T14:07:02.145Z","dependency_job_id":"66aadeb2-c7a6-4ddf-81d0-4b1c60666aa9","html_url":"https://github.com/planttheidea/unchanged","commit_stats":{"total_commits":175,"total_committers":6,"mean_commits":"29.166666666666668","dds":"0.23428571428571432","last_synced_commit":"e643445169250bff0c76ad65067ae5f0cfe9f2e0"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/planttheidea/unchanged","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/planttheidea%2Funchanged","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/planttheidea%2Funchanged/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/planttheidea%2Funchanged/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/planttheidea%2Funchanged/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/planttheidea","download_url":"https://codeload.github.com/planttheidea/unchanged/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/planttheidea%2Funchanged/sbom","scorecard":{"id":737120,"data":{"date":"2025-08-11","repo":{"name":"github.com/planttheidea/unchanged","commit":"d1388c99553f74de0e192300530f9d4a2de4e9dc"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":2.4,"checks":[{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Code-Review","score":-1,"reason":"Found no human activity in the last 24 changesets","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 30 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Vulnerabilities","score":0,"reason":"63 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GHSA-968p-4wvh-cqc8","Warn: Project is vulnerable to: GHSA-6chw-6frg-f759","Warn: Project is vulnerable to: GHSA-whgm-jr23-g3j9","Warn: Project is vulnerable to: GHSA-93q8-gq69-wqmw","Warn: Project is vulnerable to: GHSA-qwcr-r2fm-qrc7","Warn: Project is vulnerable to: GHSA-v6h2-p8h4-qcjw","Warn: Project is vulnerable to: GHSA-grv7-fg5c-xmjg","Warn: Project is vulnerable to: GHSA-pxg6-pf52-xh8x","Warn: Project is vulnerable to: GHSA-3xgq-45jj-v275","Warn: Project is vulnerable to: GHSA-gxpj-cx7g-858c","Warn: Project is vulnerable to: GHSA-434g-2637-qmqr","Warn: Project is vulnerable to: GHSA-49q7-c7j4-3p7m","Warn: Project is vulnerable to: GHSA-977x-g7h5-7qgw","Warn: Project is vulnerable to: GHSA-f7q4-pwc6-w24p","Warn: Project is vulnerable to: GHSA-fc9h-whq2-v747","Warn: Project is vulnerable to: GHSA-vjh7-7g9h-fjfh","Warn: Project is vulnerable to: GHSA-rv95-896h-c2vc","Warn: Project is vulnerable to: GHSA-qw6h-vgh9-j6wx","Warn: Project is vulnerable to: GHSA-cxjh-pqwp-8mfp","Warn: Project is vulnerable to: GHSA-fjxv-7rqg-78g4","Warn: Project is vulnerable to: GHSA-ww39-953v-wcq6","Warn: Project is vulnerable to: GHSA-pfq8-rq6v-vf5m","Warn: Project is vulnerable to: GHSA-c7qv-q95q-8v27","Warn: Project is vulnerable to: GHSA-78xj-cgh5-2h22","Warn: Project is vulnerable to: GHSA-2p57-rm9w-gvfp","Warn: Project is vulnerable to: GHSA-896r-f27r-55mw","Warn: Project is vulnerable to: GHSA-9c47-m6qq-7p4h","Warn: Project is vulnerable to: GHSA-6c8f-qphg-qjgp","Warn: Project is vulnerable to: GHSA-76p3-8jx3-jpfq","Warn: Project is vulnerable to: GHSA-3rfm-jhwj-7488","Warn: Project is vulnerable to: GHSA-hhq3-ff78-jv3g","Warn: Project is vulnerable to: GHSA-952p-6rrq-rcjv","Warn: Project is vulnerable to: GHSA-92xj-mqp7-vmcj","Warn: Project is vulnerable to: GHSA-wxgw-qj99-44c2","Warn: Project is vulnerable to: GHSA-5rrq-pxf6-6jx5","Warn: Project is vulnerable to: GHSA-8fr3-hfg3-gpgp","Warn: Project is vulnerable to: GHSA-gf8q-jrpm-jvxq","Warn: Project is vulnerable to: GHSA-2r2c-g63r-vccr","Warn: Project is vulnerable to: GHSA-cfm4-qjh2-4765","Warn: Project is vulnerable to: GHSA-x4jg-mjrx-434g","Warn: Project is vulnerable to: GHSA-5fw9-fq32-wv5p","Warn: Project is vulnerable to: GHSA-rp65-9cf3-cjxr","Warn: Project is vulnerable to: GHSA-76c9-3jph-rj3q","Warn: Project is vulnerable to: GHSA-9wv6-86v2-598j","Warn: Project is vulnerable to: GHSA-rhx6-c78j-4q9w","Warn: Project is vulnerable to: GHSA-h7cp-r72f-jxh6","Warn: Project is vulnerable to: GHSA-v62p-rq8g-8h59","Warn: Project is vulnerable to: GHSA-p8p7-x288-28g6","Warn: Project is vulnerable to: GHSA-gcx4-mw62-g8wm","Warn: Project is vulnerable to: GHSA-m6fv-jmcg-4jfg","Warn: Project is vulnerable to: GHSA-h9rv-jmmf-4pgx","Warn: Project is vulnerable to: GHSA-hxcc-f52p-wc94","Warn: Project is vulnerable to: GHSA-cm22-4g7w-348p","Warn: Project is vulnerable to: GHSA-c9g6-9335-x697","Warn: Project is vulnerable to: GHSA-52f5-9888-hmc6","Warn: Project is vulnerable to: GHSA-72xf-g2v4-qvf3","Warn: Project is vulnerable to: GHSA-wr3j-pwj9-hqq6","Warn: Project is vulnerable to: GHSA-4v9v-hfq4-rm2v","Warn: Project is vulnerable to: GHSA-9jgg-88mc-972h","Warn: Project is vulnerable to: GHSA-3h5v-q93c-6h6q","Warn: Project is vulnerable to: GHSA-6fc8-4gx4-v693","Warn: Project is vulnerable to: GHSA-c4w7-xm78-47vh","Warn: Project is vulnerable to: GHSA-p9pc-299p-vxgp"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-22T16:11:27.418Z","repository_id":27603706,"created_at":"2025-08-22T16:11:27.418Z","updated_at":"2025-08-22T16:11:27.418Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279007346,"owners_count":26084282,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["functional-programming","immutable","javascript"],"created_at":"2024-08-03T00:00:53.702Z","updated_at":"2025-10-11T13:35:02.819Z","avatar_url":"https://github.com/planttheidea.png","language":"TypeScript","funding_links":[],"categories":["JavaScript","TypeScript","Framework agnostic packages"],"sub_categories":["Immutable"],"readme":"# unchanged\n\nA tiny (~2.1kB minified+gzipped), [fast](https://github.com/planttheidea/unchanged/blob/master/benchmark_results.csv), unopinionated handler for updating JS objects and arrays immutably.\n\nSupports nested key paths via path arrays or [dotty syntax](https://github.com/planttheidea/pathington), and all methods are curriable (with placeholder support) for composability. Can be a drop-in replacement for the `lodash/fp` methods `get`, `set`, `merge`, and `omit` with a 90% smaller footprint.\n\n## Table of contents\n\n- [unchanged](#unchanged)\n  - [Table of contents](#Table-of-contents)\n  - [Usage](#Usage)\n  - [Types](#Types)\n  - [Standard methods](#Standard-methods)\n    - [get](#get)\n    - [getOr](#getOr)\n    - [set](#set)\n    - [remove](#remove)\n    - [has](#has)\n    - [is](#is)\n    - [not](#not)\n    - [add](#add)\n    - [merge](#merge)\n    - [assign](#assign)\n    - [call](#call)\n  - [Transform methods](#Transform-methods)\n    - [getWith](#getWith)\n    - [getWithOr](#getWithOr)\n    - [setWith](#setWith)\n    - [removeWith](#removeWith)\n    - [hasWith](#hasWith)\n    - [isWith](#isWith)\n    - [notWith](#notWith)\n    - [addWith](#addWith)\n    - [mergeWith](#mergeWith)\n    - [assignWith](#assignWith)\n    - [callWith](#callWith)\n  - [Additional objects](#Additional-objects)\n    - [\\_\\_](#)\n  - [Differences from other libraries](#Differences-from-other-libraries)\n    - [lodash](#lodash)\n    - [ramda](#ramda)\n    - [Other immutability libraries](#Other-immutability-libraries)\n  - [Browser support](#Browser-support)\n  - [Development](#Development)\n\n## Usage\n\n```typescript\nimport {\n  __,\n  add,\n  addWith,\n  assign,\n  assignWith,\n  call,\n  callWith,\n  get,\n  getWith,\n  getOr,\n  getWithOr,\n  has,\n  hasWith,\n  is,\n  isWith,\n  merge,\n  mergeWith,\n  remove,\n  removeWith,\n  set,\n  setWith\n} from \"unchanged\";\n\nconst object: unchanged.Unchangeable = {\n  foo: \"foo\",\n  bar: [\n    {\n      baz: \"quz\"\n    }\n  ]\n};\n\n// handle standard properties\nconst foo = get(\"foo\", object);\n\n// or nested properties\nconst baz = set(\"bar[0].baz\", \"not quz\", object);\n\n// all methods are curriable\nconst removeBaz = remove(\"bar[0].baz\");\nconst sansBaz = removeBaz(object);\n```\n\n**NOTE**: There is no `default` export, so if you want to import all methods to a single namespace you should use the `import *` syntax:\n\n```typescript\nimport * as uc from \"unchanged\";\n```\n\n## Types\n\nThis library is both written in, and provided with, types by TypeScript. The internal types used for specific parameters are scoped to the `unchanged` namespace.\n\n```typescript\n// the path used to compute nested locations\ntype Path = (number | string)[] | number | string;\n// the callback used in transform methods\ntype WithHandler = (value: any, ...extraParams: any[]) =\u003e any;\n// the generic object that is computed upon, either an array or object\ninterface Unchangeable {\n  [key: string]: any;\n  [index: number]: any;\n}\n```\n\nNotice in the `Unchangeable` interface, there is no reference to symbols. That is because to date, TypeScript does not support Symbols as an index type. If you need to use symbols as object keys, the best workaround I've found is to typecast when it complains:\n\n```typescript\nconst symbolKey = (Symbol(\"key\") as unknown) as string;\n\nconst object: { [symbolKey]: string } = {\n  [symbolKey]: \"bar\"\n};\n```\n\nIf there is a better alternative for having dynamic Symbol indices, let me know! Happy to accept any PRs from those more experienced in TypeScript than myself.\n\n## Standard methods\n\n### get\n\n```typescript\nfunction get(path: unchanged.Path, object: unchanged.Unchangeable): any;\n```\n\nGet the value at the `path` requested on the `object` passed.\n\n```typescript\nconst object: unchanged.Unchangeable = {\n  foo: [\n    {\n      bar: \"baz\"\n    }\n  ]\n};\n\nconsole.log(get(\"foo[0].bar\", object)); // baz\nconsole.log(get([\"foo\", 0, \"bar\"], object)); // baz\n```\n\n### getOr\n\n```typescript\nfunction getOr(\n  fallbackValue: any,\n  path: unchanged.Path,\n  object: unchanged.Unchangeable\n): any;\n```\n\nGet the value at the `path` requested on the `object` passed, with a fallback value if that path does not exist.\n\n```typescript\nconst object: unchanged.Unchangeable = {\n  foo: [\n    {\n      bar: \"baz\"\n    }\n  ]\n};\n\nconsole.log(getOr(\"blah\", \"foo[0].bar\", object)); // baz\nconsole.log(getOr(\"blah\", [\"foo\", 0, \"bar\"], object)); // baz\nconsole.log(getOr(\"blah\", \"foo[0].nonexistent\", object)); // blah\n```\n\n### set\n\n```typescript\nfunction set(\n  path: unchanged.Path,\n  value: any,\n  object: unchanged.Unchangeable\n): unchanged.Unchangeable;\n```\n\nReturns a new object based on the `object` passed, with the `value` assigned to the final key on the `path` specified.\n\n```typescript\nconst object: unchanged.Unchangeable = {\n  foo: [\n    {\n      bar: \"baz\"\n    }\n  ]\n};\n\nconsole.log(set(\"foo[0].bar\", \"quz\", object)); // {foo: [{bar: 'quz'}]}\nconsole.log(set([\"foo\", 0, \"bar\"], \"quz\", object)); // {foo: [{bar: 'quz'}]}\n```\n\n### remove\n\n```typescript\nfunction remove(\n  path: unchanged.Path,\n  object: unchanged.Unchangeable\n): unchanged.Unchangeable;\n```\n\nReturns a new object based on the `object` passed, with the final key on the `path` removed if it exists.\n\n```typescript\nconst object: unchanged.Unchangeable = {\n  foo: [\n    {\n      bar: \"baz\"\n    }\n  ]\n};\n\nconsole.log(remove(\"foo[0].bar\", object)); // {foo: [{}]}\nconsole.log(remove([\"foo\", 0, \"bar\"], object)); // {foo: [{}]}\n```\n\n### has\n\n```typescript\nfunction has(path: unchanged.Path, object: unchanged.Unchangeable): boolean;\n```\n\nReturns `true` if the object has the path provided, `false` otherwise.\n\n```typescript\nconst object: unchanged.Unchangeable = {\n  foo: [\n    {\n      bar: \"baz\"\n    }\n  ]\n};\n\nconsole.log(has(\"foo[0].bar\", object)); // true\nconsole.log(has([\"foo\", 0, \"bar\"], object)); // true\nconsole.log(has(\"bar\", object)); // false\n```\n\n### is\n\n```typescript\nfunction is(\n  path: unchanged.Path,\n  value: any,\n  object: unchanged.Unchangeable\n): boolean;\n```\n\nReturns `true` if the value at the `path` in `object` is equal to `value` based on [SameValueZero](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Equality_comparisons_and_sameness#Same-value-zero_equality) equality, `false` otherwise.\n\n```typescript\nconst object: unchanged.Unchangeable = {\n  foo: [\n    {\n      bar: \"baz\"\n    }\n  ]\n};\n\nconsole.log(is(\"foo[0].bar\", \"baz\", object)); // true\nconsole.log(is([\"foo\", 0, \"bar\"], \"baz\", object)); // true\nconsole.log(is(\"foo[0].bar\", \"quz\", object)); // false\n```\n\n### not\n\n```typescript\nfunction not(\n  path: unchanged.Path,\n  value: any,\n  object: unchanged.Unchangeable\n): boolean;\n```\n\nReturns `false` if the value at the `path` in `object` is equal to `value` based on [SameValueZero](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Equality_comparisons_and_sameness#Same-value-zero_equality) equality, `true` otherwise.\n\n```typescript\nconst object: unchanged.Unchangeable = {\n  foo: [\n    {\n      bar: \"baz\"\n    }\n  ]\n};\n\nconsole.log(not(\"foo[0].bar\", \"baz\", object)); // false\nconsole.log(not([\"foo\", 0, \"bar\"], \"baz\", object)); // false\nconsole.log(not(\"foo[0].bar\", \"quz\", object)); // true\n```\n\n### add\n\n```typescript\nfunction add(\n  path: unchanged.Path,\n  value: any,\n  object: unchanged.Unchangeable\n): unchanged.Unchangeable;\n```\n\nReturns a new object based on the `object` passed, with the `value` added at the `path` specified. This can have different behavior depending on whether the item is an object or an array; objects will simply add / set the key provided, whereas arrays will add a new value to the end.\n\n```typescript\nconst object: unchanged.Unchangeable = {\n  foo: [\n    {\n      bar: 'baz'\n    }\n  ]\n};\n\n// object\nconsole.log(add('foo', 'added value' object)); // {foo: [{bar: 'baz'}, 'added value']}\nconsole.log(add(['foo'], 'added value', object)); // {foo: [{bar: 'baz'}, 'added value']}\n\n// array\nconsole.log(add('foo[0].quz', 'added value' object)); // {foo: [{bar: 'baz', quz: 'added value'}]}\nconsole.log(add(['foo', 0, 'quz'], 'added value', object)); // {foo: [{bar: 'baz', quz: 'added value'}]}\n```\n\nNotice that the `Object` usage is idential to the `set` method, where a key needs to be specified for assignment. In the case of an `Array`, however, the value is pushed to the array at that key.\n\n**NOTE**: If you want to add an item to a top-level array, pass `null` as the key:\n\n```typescript\nconst object = [\"foo\"];\n\nconsole.log(add(null, \"bar\", object)); // ['foo', 'bar']\n```\n\n### merge\n\n```typescript\nfunction merge(\n  path: unchanged.Path,\n  value: unchanged.Unchangeable,\n  object: unchanged.Unchangeable\n): unchanged.Unchangeable;\n```\n\nReturns a new object that is a deep merge of `value` into `object` at the `path` specified. If you want to perform a shallow merge, see [`assign`](#assign).\n\n```typescript\nconst object1: unchanged.Unchangeable = {\n  foo: \"bar\",\n  baz: {\n    one: \"value1\",\n    deeply: {\n      nested: \"value\",\n      untouched: true\n    },\n    two: \"value2\"\n  }\n};\nconst object2: unchanged.Unchangeable = {\n  one: \"new value\",\n  deeply: {\n    nested: \"other value\"\n  },\n  three: \"value3\"\n};\n\nconsole.log(merge(\"baz\", object2, object1));\n/*\n{\n  foo: 'bar',\n  baz: {\n    one: 'new value',\n    deeply: {\n      nested: 'other value',\n      untouched: true,\n    },\n    two: 'value2',\n    three: 'value3\n  }\n}\n```\n\n**NOTE**: If you want to `merge` the entirety of both objects, pass `null` as the key:\n\n```typescript\nconsole.log(merge(null, object2, object1));\n/*\n{\n  foo: \"bar\",\n  baz: {\n    one: \"value1\",\n    deeply: {\n      nested: \"value\",\n      untouched: true\n    },\n    two: \"value2\"\n  },\n  one: \"new value\",\n  deeply: {\n    nested: \"other value\"\n  },\n  three: \"value3\"\n}\n*/\n```\n\n### assign\n\n```typescript\nfunction assign(\n  path: unchanged.Path,\n  value: unchanged.Unchangeable,\n  object: unchanged.Unchangeable\n): unchanged.Unchangeable;\n```\n\nReturns a new object that is a shallow merge of `value` into `object` at the `path` specified. If you want to perform a deep merge, see [`merge`](#merge).\n\n```typescript\nconst object1: unchanged.Unchangeable = {\n  foo: \"bar\",\n  baz: {\n    one: \"value1\",\n    deeply: {\n      nested: \"value\",\n      untouched: true\n    },\n    two: \"value2\"\n  }\n};\nconst object2: unchanged.Unchangeable = {\n  one: \"new value\",\n  deeply: {\n    nested: \"other value\"\n  },\n  three: \"value3\"\n};\n\nconsole.log(assign(\"baz\", object2, object1));\n/*\n{\n  foo: 'bar',\n  baz: {\n    one: 'new value',\n    deeply: {\n      nested: 'other value',\n    },\n    two: 'value2',\n    three: 'value3\n  }\n}\n```\n\n**NOTE**: If you want to `assign` the entirety of both objects, pass `null` as the key:\n\n```typescript\nconsole.log(assign(null, object2, object1));\n/*\n{\n  foo: \"bar\",\n  baz: {\n    one: \"value1\",\n    deeply: {\n      nested: \"value\",\n      untouched: true\n    },\n    two: \"value2\"\n  },\n  one: \"new value\",\n  deeply: {\n    nested: \"other value\"\n  },\n  three: \"value3\"\n}\n*/\n```\n\n### call\n\n```typescript\nfunction call(\n  path: unchanged.Path,\n  parameters: any[],\n  object: unchanged.Unchangeable,\n  context?: any = object\n): any;\n```\n\nCall the method at the `path` requested on the `object` passed, and return what it's call returns.\n\n```typescript\nconst object: unchanged.Unchangeable = {\n  foo: [\n    {\n      bar(a, b) {\n        return a + b;\n      }\n    }\n  ]\n};\n\nconsole.log(call(\"foo[0].bar\", [1, 2], object)); // 3\nconsole.log(call([\"foo\", 0, \"bar\"], [1, 2], object)); // 3\n```\n\nYou can also provide an optional fourth parameter of `context`, which will be the `this` value in the method call. This will default to the `object` itself.\n\n```typescript\nconst object: unchanged.Unchangeable = {\n  calculate: true,\n  foo: [\n    {\n      bar(a, b) {\n        return this.calculate ? a + b : 0;\n      }\n    }\n  ]\n};\n\nconsole.log(call(\"foo[0].bar\", [1, 2], object)); // 3\nconsole.log(call(\"foo[0].bar\", [1, 2], object, {})); // 0\n```\n\n**NOTE**: Because `context` is optional, it cannot be independently curried; you must apply it in the call when the `object` is passed.\n\n## Transform methods\n\nEach standard method has it's own related `With` method, which accepts a callback `fn` as the first curried parameter. In most cases this callback serves as a transformer for the value retrieved, set, merged, etc.; the exception is `removeWith`, where the callback serves as a validator as to whether to remove or not.\n\nThe signature of all callbacks is the `withHandler` specified in [`Types`](#types). Because `extraParams` are optional parameters, they cannot be independently curried; you must apply them in the call when the `object` is passed.\n\n### getWith\n\n```typescript\nfunction getWith(\n  fn: unchanged.withHandler,\n  path: unchanged.Path,\n  object: unchanged.Unchangeable,\n  ...extraParams?: any[]\n): any;\n```\n\nGet the return value of `fn` based on the value at the `path` requested on the `object` passed. `fn` is called with the current value at the `path` as the first parameter, and any additional parameters passed as `extraParams` following that.\n\n```typescript\nconst object: unchanged.Unchangeable = {\n  foo: [\n    {\n      bar: \"baz\"\n    }\n  ]\n};\nconst fn: unchanged.withHandler = (value: any, nullValue: any): any =\u003e\n  currentValue === nullValue ? null : currentValue;\n\nconsole.log(getWith(fn, \"foo[0].bar\", object)); // 'baz'\nconsole.log(getWith(fn, \"foo[0].bar\", object, \"baz\")); // null\nconsole.log(getWith(fn, [\"foo\", 0, \"bar\"], object)); // 'baz'\nconsole.log(getWith(fn, [\"foo\", 0, \"bar\"], object, \"baz\")); // null\n```\n\n### getWithOr\n\n```typescript\nfunction getWithOr(\n  fn: unchanged.withHandler,\n  fallbackValue: any,\n  path: unchanged.Path,\n  object: unchanged.Unchangeable,\n  ...extraParams?: any[]\n): any;\n```\n\nGet the return value of `fn` based on the value at the `path` requested on the `object` passed, falling back to `fallbackValue` when no match is found at `path`. When a match is found, `fn` is called with the current value at the `path` as the first parameter, and any additional parameters passed as `extraParams` following that.\n\n```typescript\nconst object: unchanged.Unchangeable = {\n  foo: [\n    {\n      bar: \"baz\"\n    }\n  ]\n};\nconst fn: unchanged.withHandler = (value: any, nullValue: any): any =\u003e\n  currentValue === nullValue ? null : currentValue;\n\nconsole.log(getWithOr(fn, \"quz\", \"foo[0].bar\", object)); // 'baz'\nconsole.log(getWithOr(fn, \"quz\", \"foo[0].bar\", object, \"baz\")); // null\nconsole.log(getWithOr(fn, \"quz\", \"foo[0].notFound\", object, \"baz\")); // 'quz'\nconsole.log(getWithOr(fn, \"quz\", [\"foo\", 0, \"bar\"], object)); // 'baz'\nconsole.log(getWithOr(fn, \"quz\", [\"foo\", 0, \"bar\"], object, \"baz\")); // null\nconsole.log(getWithOr(fn, \"quz\", [\"foo\", 0, \"notFound\"], object, \"baz\")); // 'quz'\n```\n\n### setWith\n\n```typescript\nfunction setWith(\n  fn: unchanged.withHandler,\n  path: unchanged.Path,\n  object: unchanged.Unchangeable,\n  ...extraParams?: any[]\n): unchanged.Unchangeable;\n```\n\nReturns a new object based on the `object` passed, with the return value of `fn` assigned to the final key on the `path` specified. `fn` is called with the current value at the `path` as the first parameter, and any additional parameters passed as `extraParams` following that.\n\n```typescript\nconst object: unchanged.Unchangeable = {\n  foo: [\n    {\n      bar: \"baz\"\n    }\n  ]\n};\nconst fn: unchanged.withHandler = (value: any, preventUpdate: boolean): any =\u003e\n  preventUpdate ? currentValue : \"quz\";\n\nconsole.log(setWith(fn, \"foo[0].bar\", object)); // {foo: [{bar: 'quz'}]}\nconsole.log(setWith(fn, \"foo[0].bar\", object, true)); // {foo: [{bar: 'baz'}]}\nconsole.log(setWith(fn, [\"foo\", 0, \"bar\"], object)); // {foo: [{bar: 'quz'}]}\nconsole.log(setWith(fn, [\"foo\", 0, \"bar\"], object, true)); // {foo: [{bar: 'baz'}]}\n```\n\n### removeWith\n\n```typescript\nfunction removeWith(\n  fn: unchanged.withHandler,\n  path: unchanged.Path,\n  object: unchanged.Unchangeable,\n  ...extraParams?: any[]\n): unchanged.Unchangeable;\n```\n\nReturns a new object based on the `object` passed, with the final key on the `path` removed if it exists and the return from `fn` is truthy.\n\n```typescript\nconst object: unchanged.Unchangeable = {\n  foo: [\n    {\n      bar: \"baz\"\n    }\n  ]\n};\nconst fn: unchanged.withHandler = (\n  value: any,\n  shouldNotRemove: boolean\n): boolean =\u003e !shouldNotRemove \u0026\u0026 value === \"baz\";\n\nconsole.log(removeWith(fn, \"foo[0].bar\", object)); // {foo: [{}]}\nconsole.log(removeWith(fn, \"foo[0].bar\", object, true)); // {foo: [{bar: 'baz'}]}\nconsole.log(removeWith([fn, \"foo\", 0, \"bar\"], object)); // {foo: [{}]}\nconsole.log(removeWith([fn, \"foo\", 0, \"bar\"], object, true)); // {foo: [{bar: 'baz'}]}\n```\n\n### hasWith\n\n```typescript\nfunction hasWith(\n  fn: unchanged.withHandler,\n  path: unchanged.Path,\n  object: unchanged.Unchangeable,\n  ...extraParams?: any[]\n): boolean;\n```\n\nReturns `true` if the return value of `fn` based on the value returned from `path` in the `object` returns truthy, `false` otherwise.\n\n```typescript\nconst object: unchanged.Unchangeable = {\n  foo: [\n    {\n      bar: \"baz\"\n    }\n  ]\n};\nconst fn: unchanged.withHandler = (\n  value: any,\n  shouldBeNull: boolean\n): boolean =\u003e (shouldBeNull ? value === null : value === \"baz\");\n\nconsole.log(hasWith(fn, \"foo[0].bar\", object)); // true\nconsole.log(hasWith(fn, \"foo[0].bar\", object, true)); // false\nconsole.log(hasWith(fn, [\"foo\", 0, \"bar\"], object)); // true\nconsole.log(hasWith(fn, [\"foo\", 0, \"bar\"], object, true)); // false\nconsole.log(hasWith(fn, \"bar\", object)); // false\n```\n\n### isWith\n\n```typescript\nfunction isWith(\n  fn: unchanged.withHandler,\n  path: unchanged.Path,\n  object: unchanged.Unchangeable\n): boolean;\n```\n\nReturns `true` if the return value of `fn` based on the value returned from `path` in the `object` is equal to `value` based on [SameValueZero](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Equality_comparisons_and_sameness#Same-value-zero_equality) equality, `false` otherwise.\n\n```typescript\nconst object: unchanged.Unchangeable = {\n  foo: [\n    {\n      bar: \"baz\",\n      quz: \"not baz\"\n    }\n  ]\n};\nconst fn: unchanged.withHandler = (value: any): number =\u003e\n  value \u0026\u0026 value.length === 3;\n\nconsole.log(isWith(fn, \"foo[0].bar\", object)); // true\nconsole.log(isWith(fn, [\"foo\", 0, \"bar\"], object)); // true\nconsole.log(isWith(fn, \"foo[0].quz\", object)); // false\n```\n\n### notWith\n\n```typescript\nfunction notWith(\n  fn: unchanged.withHandler,\n  path: unchanged.Path,\n  object: unchanged.Unchangeable\n): boolean;\n```\n\nReturns `false` if the return value of `fn` based on the value returned from `path` in the `object` is equal to `value` based on [SameValueZero](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Equality_comparisons_and_sameness#Same-value-zero_equality) equality, `true` otherwise.\n\n```typescript\nconst object: unchanged.Unchangeable = {\n  foo: [\n    {\n      bar: \"baz\",\n      quz: \"not baz\"\n    }\n  ]\n};\nconst fn: unchanged.withHandler = (value: any): number =\u003e\n  value \u0026\u0026 value.length === 3;\n\nconsole.log(notWith(fn, \"foo[0].bar\", object)); // false\nconsole.log(notWith(fn, [\"foo\", 0, \"bar\"], object)); // false\nconsole.log(notWith(fn, \"foo[0].quz\", object)); // true\n```\n\n### addWith\n\n```typescript\nfunction addWith(\n  fn: unchanged.withHandler,\n  path: unchanged.Path,\n  object: unchanged.Unchangeable\n): unchanged.Unchangeable;\n```\n\nReturns a new object based on the `object` passed, with the return value of `fn` added at the `path` specified. This can have different behavior depending on whether the item is an object or an array; objects will simply add / set the key provided, whereas arrays will add a new value to the end.\n\n```typescript\nconst object: unchanged.Unchangeable = {\n  foo: [\n    {\n      bar: \"baz\"\n    }\n  ]\n};\nconst fn: unchanged.withHandler = (value: any) =\u003e\n  value\n    ? value\n        .split(\"\")\n        .reverse()\n        .join(\"\")\n    : \"new value\";\n\n// object\nconsole.log(addWith(fn, \"foo\", object)); // {foo: [{bar: 'baz'}, 'new value']}\nconsole.log(addWith(fn, [\"foo\"], object)); // {foo: [{bar: 'baz'}, 'new value']}\n\n// array\nconsole.log(addWith(fn, \"foo[0].bar\", object)); // {foo: [{bar: 'zab'}]}\nconsole.log(addWith(fn, [\"foo\", 0, \"bar\"], object)); // {foo: [{bar: 'zab''}]}\n```\n\n### mergeWith\n\n```typescript\nfunction mergeWith(\n  fn: unchanged.withHandler,\n  path: unchanged.Path,\n  object: unchanged.Unchangeable\n): unchanged.Unchangeable;\n```\n\nReturns a new object that is a deep merge of the return value of `fn` into `object` at the `path` specified if a valid mergeable object, else returns the original object. If you want to perform a shallow merge, see [`assignWith`](#assignwith).\n\n```typescript\nconst object1: unchanged.Unchangeable = {\n  foo: \"bar\",\n  baz: {\n    one: \"value1\",\n    deeply: {\n      nested: \"value\",\n      untouched: true\n    },\n    two: \"value2\"\n  }\n};\nconst object2: unchanged.Unchangeable = {\n  one: \"new value\",\n  deeply: {\n    nested: \"other value\"\n  },\n  three: \"value3\"\n};\nconst fn: unchanged.withHandler = (value: any) =\u003e\n  value \u0026\u0026 value.one === \"value1\" ? object2 : null;\n\nconsole.log(mergeWith(fn, \"baz\", object1));\n/*\n{\n  foo: 'bar',\n  baz: {\n    one: 'new value',\n    deeply: {\n      nested: 'other value',\n      untouched: true,\n    },\n    two: 'value2',\n    three: 'value3\n  }\n}\n*/\nconsole.log(mergeWith(fn, \"baz.deeply\", object1));\n/*\n// untouched object1\n{\n  foo: \"bar\",\n  baz: {\n    one: \"value1\",\n    deeply: {\n      nested: 'value',\n      untouched: true,\n    },\n    two: \"value2\"\n  }\n}\n*/\n```\n\n**NOTE**: If you want to `merge` the entirety of both objects, pass `null` as the key:\n\n```typescript\nconsole.log(mergeWith(fn, null, object1));\n/*\n{\n  foo: \"bar\",\n  baz: {\n    one: \"value1\",\n    deeply: {\n      nested: \"value\",\n      untouched: true\n    },\n    two: \"value2\"\n  },\n  one: \"new value\",\n  deeply: {\n    nested: \"other value\"\n  },\n  three: \"value3\"\n}\n*/\n```\n\n### assignWith\n\n```typescript\nfunction assignWith(\n  fn: unchanged.withHandler,\n  path: unchanged.Path,\n  object: unchanged.Unchangeable\n): unchanged.Unchangeable;\n```\n\nReturns a new object that is a shallow merge of the return value of `fn` into `object` at the `path` specified if a valid mergeable object, else returns the original object. If you want to perform a deep merge, see [`mergeWith`](#mergeWith).\n\n```typescript\nconst object1: unchanged.Unchangeable = {\n  foo: \"bar\",\n  baz: {\n    one: \"value1\",\n    deeply: {\n      nested: \"value\",\n      untouched: true\n    },\n    two: \"value2\"\n  }\n};\nconst object2: unchanged.Unchangeable = {\n  one: \"new value\",\n  deeply: {\n    nested: \"other value\"\n  },\n  three: \"value3\"\n};\nconst fn: unchanged.withHandler = (value: any) =\u003e\n  value \u0026\u0026 value.one === \"value1\" ? object2 : null;\n\nconsole.log(assignWith(fn, \"baz\", object1));\n/*\n{\n  foo: 'bar',\n  baz: {\n    one: 'new value',\n    deeply: {\n      nested: 'other value',\n    },\n    two: 'value2',\n    three: 'value3\n  }\n}\n*/\nconsole.log(assignWith(fn, \"baz.deeply\", object1));\n/*\n// untouched object1\n{\n  foo: \"bar\",\n  baz: {\n    one: \"value1\",\n    deeply: {\n      nested: 'value',\n      untouched: true,\n    },\n    two: \"value2\"\n  }\n}\n*/\n```\n\n### callWith\n\n```typescript\nfunction callWith(\n  path: unchanged.Path,\n  parameters: any[],\n  object: unchanged.Unchangeable,\n  context?: any = object\n): any;\n```\n\nCall the method returned from `fn` based on the `path` specified on the `object`, and if a function return what it's call returns.\n\n```typescript\nconst object: unchanged.Unchangeable = {\n  foo: [\n    {\n      bar(a, b) {\n        return a + b;\n      }\n    }\n  ]\n};\nconst fn: unchanged.withHandler = (value: any): any =\u003e\n  typeof value === fn\n    ? fn\n    : () =\u003e\n        console.error(\"Error: Requested call of a method that does not exist.\");\n\nconsole.log(callWith(fn, \"foo[0].bar\", [1, 2], object)); // 3\nconsole.log(callWith(fn, [\"foo\", 0, \"bar\"], [1, 2], object)); // 3\ncallWith(fn, \"foo[1].nope\", object); // Error: Requested call of a method that does not exist.\n```\n\nYou can also provide an optional fourth parameter of `context`, which will be the `this` value in the method call. This will default to the `object` itself.\n\n```typescript\nconst object: unchanged.Unchangeable = {\n  calculate: true,\n  foo: [\n    {\n      bar(a, b) {\n        return this.calculate ? a + b : 0;\n      }\n    }\n  ]\n};\nconst fn: unchanged.withHandler = (value: any): any =\u003e\n  typeof value === fn\n    ? fn\n    : () =\u003e\n        console.error(\"Error: Requested call of a method that does not exist.\");\n\nconsole.log(callWith(fn, \"foo[0].bar\", [1, 2], object)); // 3\nconsole.log(callWith(fn, \"foo[0].bar\", [1, 2], object, {})); // 0\n```\n\n**NOTE**: Because `context` is optional, it cannot be independently curried; you must apply it in the call when the `object` is passed.\n\n## Additional objects\n\n### \\_\\_\n\nA placeholder value used to identify \"gaps\" in a curried function, allowing for earlier application of arguments later in the argument order.\n\n```typescript\nimport {__, set} from 'unchanged';\n\nconst thing = {\n  foo: 'foo';\n};\n\nconst setFoo = set('foo', __, thing);\n\nsetFooOnThing('bar');\n```\n\n## Differences from other libraries\n\n### lodash\n\n[`lodash/fp`](https://lodash.com/) (the functional programming implementation of `lodash`) is identical in implementation to `unchanged`'s methods, just with a _10.5x_ larger footprint. These methods should map directly:\n\n- _lodash/fp_ =\u003e _unchanged_\n- `curry.placeholder` =\u003e `__`\n- `get` =\u003e `get`\n- `getOr` =\u003e `getOr`\n- `merge` =\u003e `merge`\n- `omit` =\u003e `remove`\n- `set` =\u003e `set`\n\n### ramda\n\n[`ramda`](http://ramdajs.com/) is similar in its implementation, however the first big difference is that dot-bracket syntax is not supported by `ramda`, only path arrays. The related methods are:\n\n- _ramda_ =\u003e _unchanged_\n- `__` =\u003e `__`\n- `path` =\u003e `get`\n- `pathOr` =\u003e `getOr`\n- `merge` =\u003e `merge`\n- `omit` =\u003e `remove`\n- `assocPath` =\u003e `set`\n\nAnother difference is that the `ramda` methods that clone (`assocPath`, for example) only work with objects; arrays are implicitly converted into objects, which can make updating collections challenging.\n\nThe last main difference is the way that objects are copied, example:\n\n```typescript\nfunction Foo(value) {\n  this.value = value;\n}\n\nFoo.prototype.getValue = function() {\n  return this.value;\n};\n\nconst foo = new Foo(\"foo\");\n\n// in ramda, both own properties and prototypical methods are copied to the new object as own properties\nconst ramdaResult = assoc(\"bar\", \"baz\", foo);\n\nconsole.log(ramdaResult); // {value: 'foo', bar: 'baz', getValue: function getValue() { return this.value; }}\nconsole.log(ramdaResult instanceof Foo); // false\n\n// in unchanged, the prototype of the original object is maintained, and only own properties are copied as own properties\nconst unchangedResult = set(\"bar\", \"baz\", foo);\n\nconsole.log(unchangedResult); // {value: 'foo', bar: 'baz'}\nconsole.log(unchangedResult instanceof Foo); // true\n```\n\nThis can make `ramda` more performant in certain scenarios, but at the cost of having potentially unexpected behavior.\n\n### Other immutability libraries\n\nThis includes popular solutions like [Immutable.js](https://facebook.github.io/immutable-js/), [seamless-immutable](https://github.com/rtfeldman/seamless-immutable), [mori](http://swannodette.github.io/mori/), etc. These solutions all work well, but with one caveat: _you need to buy completely into their system_. Each of these libraries redefines how the objects are stored internally, and require that you learn a new, highly specific API to use these custom objects. `unchanged` is unopinionated, accepting standard JS objects and returning standard JS objects, no transformation or learning curve required.\n\n## Browser support\n\n- Chrome (all versions)\n- Firefox (all versions)\n- Edge (all versions)\n- Opera 15+\n- IE 9+\n- Safari 6+\n- iOS 8+\n- Android 4+\n\n## Development\n\nStandard stuff, clone the repo and `npm install` dependencies. The npm scripts available:\n\n- `benchmark` =\u003e run benchmark suite comparing top-level and deeply-nested `get` and `set` operations with `lodash` and `ramda`\n- `build` =\u003e run `rollup` to build `dist` files for CommonJS, ESM, and UMD consumers\n- `clean` =\u003e run `rimraf` on the `dist` folder\n- `dev` =\u003e run webpack dev server to run example app / playground\n- `dist` =\u003e runs `clean` and `build`\n- `lint` =\u003e run ESLint against all files in the `src` folder\n- `lint:fix` =\u003e run `lint` with autofixing applied\n- `prepublish` =\u003e runs `prepublish:compile` when publishing\n- `prepublish:compile` =\u003e run `lint`, `test:coverage`, `dist`\n- `test` =\u003e run AVA test functions with `NODE_ENV=test`\n- `test:coverage` =\u003e run `test` but with `nyc` for coverage checker\n- `test:watch` =\u003e run `test`, but with persistent watcher\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplanttheidea%2Funchanged","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplanttheidea%2Funchanged","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplanttheidea%2Funchanged/lists"}