{"id":17159255,"url":"https://github.com/akuzko/update-js","last_synced_at":"2025-08-11T20:12:58.427Z","repository":{"id":45050558,"uuid":"86173250","full_name":"akuzko/update-js","owner":"akuzko","description":"JS object immutability helper","archived":false,"fork":false,"pushed_at":"2022-01-12T13:38:17.000Z","size":36,"stargazers_count":10,"open_issues_count":2,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-08-09T18:22:14.921Z","etag":null,"topics":["helper","immutability","immutable-objects","javascript","object","update"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/akuzko.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-03-25T16:54:25.000Z","updated_at":"2022-01-12T13:26:56.000Z","dependencies_parsed_at":"2022-08-25T13:50:48.787Z","dependency_job_id":null,"html_url":"https://github.com/akuzko/update-js","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/akuzko/update-js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akuzko%2Fupdate-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akuzko%2Fupdate-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akuzko%2Fupdate-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akuzko%2Fupdate-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/akuzko","download_url":"https://codeload.github.com/akuzko/update-js/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akuzko%2Fupdate-js/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269814225,"owners_count":24479357,"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-08-10T02:00:08.965Z","response_time":71,"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":["helper","immutability","immutable-objects","javascript","object","update"],"created_at":"2024-10-14T22:13:48.046Z","updated_at":"2025-08-11T20:12:58.363Z","avatar_url":"https://github.com/akuzko.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"update-js\n=========\n\nJS object immutability helper\n\n[![build status](https://img.shields.io/travis/akuzko/update-js/master.svg?style=flat-square)](https://travis-ci.org/akuzko/update-js)\n[![npm version](https://img.shields.io/npm/v/update-js.svg?style=flat-square)](https://www.npmjs.com/package/update-js)\n\n## Installation\n\n```\nnpm install --save update-js\n```\n\n## Usage\n\n### Basic Usage\n\n```js\nimport update from 'update-js';\n\nconst obj = { foo: { bar: [{ baz: 1 }, { baz: 2 }] }, bak: { barbaz: 1 } };\nconst upd = update(obj, 'foo.bar.1.baz', 3);\n// ^ the same as:\n// const upd = { ...obj, foo: { ...obj.foo, bar: [obj.foo.bar[0], { ...obj.foo.bar[1], baz: 3 }] } };\n\n// all of the following is true:\nupd.foo.bar[1].baz === 3;\nupd                !== obj;\nupd.foo            !== obj.foo;\nupd.foo.bar        !== obj.foo.bar;\nupd.foo.bar[0]     === obj.foo.bar[0];\nupd.foo.bar[1]     !== obj.foo.bar[1];\nupd.bak            === obj.bak;\n```\n\n### Updating Multiple Keys at Once\n\nBy passing object instead of string path you can update multiple values with one operation. In this\ncase object keys are used as paths at which corresponding object values should be assigned.\n\n```js\nconst obj = { foo: { bar: 'baz' }, baz: [{ bak: 'foo' }] };\nconst upd = update(obj, {\n  'foo.bar': 'baz2',\n  'foo.baz.0.bak': 'foo2'\n});\n\nupd.foo.bar // =\u003e 'baz2'\nupd.foo.baz[0].bak // =\u003e 'foo2'\n```\n\n#### Using Helper Methods in Multi-Keys Updates\n\nYou can also use [helper methods](#helper-methods) when updating multiple keys at once. When\ncalling them, you just have to omit first two `obj` and `path` arguments:\n\n```js\nconst obj = { foo: true, bar: { baz: [1, 2], bak: [{ a: 'a1' }, { a: 'a2' }] } };\nconst upd = update(obj, {\n  foo: false,\n  'bar.baz': update.push(3),\n  'bar.bak.{a:a2}': update.assign({ b: 'b2' })\n});\n\nupd // =\u003e { foo: false, bar: { baz: [1, 2, 3], bak: [{ a: 'a1' }, { a: 'a2', b: 'b2' }] } }\n```\n\n### Using Custom Updater Function\n\nYou can use `update.with` function that accepts updater function instead of value.\nThe current value at the path is passed as only argument to this function:\n\n```js\nconst obj = { foo: { bar: [1, 2, 3, 4] }, bak: { barbaz: 1 } };\nconst upd = update.with(obj, 'foo.bar', (old) =\u003e old.filter(i =\u003e i % 2 === 0));\n\nupd.foo.bar // =\u003e [2, 4]\n```\n\nBe careful not to update old object in place when using updater function.\n\n### Using Object Lookup Keys\n\nLookup keys are used to index objects in array by their property values. For example:\n\n```js\nimport update from 'update-js';\n\nconst obj = {\n  foo: {\n    items: [\n      { id: 1, bar: 2 },\n      { id: 2, bar: 3 },\n      { id: 3, bar: 4 }\n    ]\n  }\n}\nconst upd = update(obj, 'foo.items.{id:2}.bar', 5);\n\nupd.foo.items[1].bar === 5 // true\n```\n\nNotes on object lookup:\n- Object auto-generation is not supported when using path with object lookup,\n  i.e. both collection and object specified by lookup key should exist. If\n  no object exists, update action will be ignored.\n- Lookup should be used with simple values since it uses `==` comparison.\n- It is possible to specify several lookup fields, like `{type:foo,name:bar}`.\n\n#### Handling Missing Objects\n\nWhen `update` encounters lookup key that doesn't correspond to any object in\ncollection, it invokes `update.onLookupMissingObject` handler, passing collection\nand lookup key to that function. There may be different strategies for handling\nsuch cases, depending on execution environment and your needs.\n\n`update-js` provides 3 predefined handlers, available from `update-js/utils`:\n\n```js\nimport update from 'update-js';\nimport { warnOnMissing, throwOnMissing, noop } from 'update-js/utils';\n\nupdate.onLookupMissingObject = warnOnMissing;\n// ^ this will `console.warn` message regarding attempt to update missing object\n\nupdate.onLookupMissingObject = throwOnMissing;\n// ^ this will throw exception on attempt to update missing object\n\nupdate.onLookupMissingObject = noop;\n// ^ this will ignore attempt entirely\n```\n\nThe default value for `update.onLookupMissingObject` is `noop`.\n\n## `update-js/fp` Module\n\nAside from main functionality of `update` function, `update-js` also provides `update-js/fp` module.\nThe `updateFp` function imported from it generates a transformation-currying function that accepts\na subject of update as it's only argument. It can be used as a callback for some state-updater\nfunction. For example, one may have something like:\n\n```js\nimport update from 'update-js/fp';\n\nsetState(update('foo.bar.baz', 5));\n// ^ with `update` from 'update-js' it is the same as:\n// setState((state) =\u003e {\n//   return update(state, 'foo.bar.baz', 5);\n// });\n```\n\n`updateFp` function has the same helper methods as it's `update` counterpart, for example:\n\n```js\nimport update from 'update';\nimport updateFp from 'update/fp';\n\nupdate.add(state, 'list.items', obj);\n// ^ the same as:\nupdateFp.add('list.items', obj)(state);\n```\n\n**NOTE:** if you want to use update helpers in multi-key updates, you have to use the ones\nprovided by base `update` package.\n\n## Helper Methods\n\n### Array Update Helpers\n\n#### `update.unshift`\n\nAdds item to the array at the beginning of it.\n\n```js\nimport update from 'update-js';\n\nconst obj = { foo: { bar: [1, 2] } };\nconst upd = update.unshift(obj, 'foo.bar', 3);\n\nupd.foo.bar // =\u003e [3, 1, 2];\n```\n\n_Alias:_ `update.prepend`\n\n#### `update.push`\n\nAdds item to the array.\n\n```js\nimport update from 'update-js';\n\nconst obj = { foo: { bar: [1, 2] } };\nconst upd = update.push(obj, 'foo.bar', 3);\n\nupd.foo.bar // =\u003e [1, 2, 3];\n```\n\n_Alias:_ `update.add`\n\n#### `update.remove`\n\nRemoves item from the array by index or lookup key.\n\n```js\nimport update from 'update-js';\n\nconst obj = { foo: { bar: [1, 2, 3, 4] } };\nconst upd = update.remove(obj, 'foo.bar.1');\n\nupd.foo.bar // =\u003e [1, 3, 4];\n```\n\nWith lookup key:\n\n```js\nconst obj = {\n  foo: {\n    items: [\n      { id: 1, bar: 2 },\n      { id: 2, bar: 3 },\n      { id: 3, bar: 4 }\n    ]\n  }\n}\nconst upd = update.remove(obj, 'foo.items.{id:2}');\n\nupd.foo.items // =\u003e [{ id: 1, bar: 2 }, { id: 3, bar: 4 }]\n```\n\nNote that this helper cannot be used to remove item from array if the latter is used as\ntarget object, i.e. `update.remove(obj, '1')` won't work.\n\n### Object Update Helpers\n\n#### `update.assign`\n\nAssigns properties of the given object to the one specified by the path.\n\n```js\nimport update from 'update-js';\n\nconst obj = { foo: { bar: { baz: 'bak' } } };\nconst upd = update.assign(obj, 'foo.bar', { bak: 'baz' });\n\nupd.foo.bar // =\u003e { baz: 'bak', bak: 'baz' };\n```\n\n#### `update.del`\n\nDeletes object property at specified path.\n\n```js\nimport update from 'update-js';\n\nconst obj = { foo: { bar: { baz: 'bak', bak: 'baz' } } };\nconst upd = update.del(obj, 'foo.bar.baz');\n\nupd.foo.bar // =\u003e { bak: 'baz' };\n```\n\nNote that this helper cannot be used to delete property for target object itself,\ni.e. `update.del(obj, 'foo')` won't work.\n\n## Credits\n\n- [Aleksandr Zhukov](https://github.com/AleksandrZhukov) - Opening issues,\n  feature suggestions and contributions.\n- [Maksym Agryzko](https://github.com/avv123avv) - Maintenance, fixing\n  vulnerability issues.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakuzko%2Fupdate-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fakuzko%2Fupdate-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakuzko%2Fupdate-js/lists"}