{"id":16208460,"url":"https://github.com/ehmicky/set-array","last_synced_at":"2025-03-19T08:30:47.047Z","repository":{"id":40602331,"uuid":"479732181","full_name":"ehmicky/set-array","owner":"ehmicky","description":"Set array items declaratively","archived":false,"fork":false,"pushed_at":"2025-02-04T20:38:19.000Z","size":10568,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-11T08:37:08.806Z","etag":null,"topics":["algorithm","append","array","array-manipulations","array-methods","data-structures","functional","functional-programming","insert","javascript","library","merge","node","nodejs","omit","patch","set","slice","splice","typescript"],"latest_commit_sha":null,"homepage":"","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/ehmicky.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2022-04-09T13:19:23.000Z","updated_at":"2025-02-04T20:38:23.000Z","dependencies_parsed_at":"2024-04-22T20:27:46.088Z","dependency_job_id":"ea83f211-65b4-44a4-b21e-59f23156af18","html_url":"https://github.com/ehmicky/set-array","commit_stats":{"total_commits":375,"total_committers":2,"mean_commits":187.5,"dds":"0.021333333333333315","last_synced_commit":"7f741e8904e2e5306a2a323c40705ca7ef2ea904"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmicky%2Fset-array","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmicky%2Fset-array/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmicky%2Fset-array/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmicky%2Fset-array/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ehmicky","download_url":"https://codeload.github.com/ehmicky/set-array/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243976471,"owners_count":20377691,"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","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":["algorithm","append","array","array-manipulations","array-methods","data-structures","functional","functional-programming","insert","javascript","library","merge","node","nodejs","omit","patch","set","slice","splice","typescript"],"created_at":"2024-10-10T10:17:04.136Z","updated_at":"2025-03-19T08:30:46.605Z","avatar_url":"https://github.com/ehmicky.png","language":"JavaScript","readme":"[![Node](https://img.shields.io/badge/-Node.js-808080?logo=node.js\u0026colorA=404040\u0026logoColor=66cc33)](https://www.npmjs.com/package/set-array)\n[![Browsers](https://img.shields.io/badge/-Browsers-808080?logo=firefox\u0026colorA=404040)](https://unpkg.com/set-array?module)\n[![TypeScript](https://img.shields.io/badge/-Typed-808080?logo=typescript\u0026colorA=404040\u0026logoColor=0096ff)](/src/main.d.ts)\n[![Codecov](https://img.shields.io/badge/-Tested%20100%25-808080?logo=codecov\u0026colorA=404040)](https://codecov.io/gh/ehmicky/set-array)\n[![Minified size](https://img.shields.io/bundlephobia/minzip/set-array?label\u0026colorA=404040\u0026colorB=808080\u0026logo=webpack)](https://bundlephobia.com/package/set-array)\n[![Mastodon](https://img.shields.io/badge/-Mastodon-808080.svg?logo=mastodon\u0026colorA=404040\u0026logoColor=9590F9)](https://fosstodon.org/@ehmicky)\n[![Medium](https://img.shields.io/badge/-Medium-808080.svg?logo=medium\u0026colorA=404040)](https://medium.com/@ehmicky)\n\nSet array items declaratively.\n\nArray items can be [updated](#update), [merged](#mergeoldvalue-newvalue),\n[added](#add), [inserted](#insert), [appended](#append), [prepended](#prepend),\n[deleted](#delete) or [set](#set).\n\n# Hire me\n\nPlease\n[reach out](https://www.linkedin.com/feed/update/urn:li:activity:7117265228068716545/)\nif you're looking for a Node.js API or CLI engineer (11 years of experience).\nMost recently I have been [Netlify Build](https://github.com/netlify/build)'s\nand [Netlify Plugins](https://www.netlify.com/products/build/plugins/)'\ntechnical lead for 2.5 years. I am available for full-time remote positions.\n\n# Use cases\n\nThis is intended for cases where arrays manipulation in JavaScript is not\navailable.\n\nFor example, a library where shared configuration files can be extended.\n\n```yml\n# The shared configuration exports a `rules` array of objects\nextend: my-shared-config\n\nrules:\n  # Update a rule\n  1:\n    level: silent\n  # Append a rule\n  '-0':\n    name: appendedRule\n```\n\nOr a server receiving network patch requests.\n\n```http\nPATCH /pets/0\n\n{\n  \"toys\": { \"1\": \"updateSecondToy\", \"-0\": \"appendNewToy\" }\n}\n```\n\n# Examples\n\n## Update\n\n```js\nimport { set } from 'set-array'\n\n// Each element in the object argument updates array items.\n// The object keys are the array indices (before any updates).\n// The array is copied, not mutated.\nset(['a', 'b', 'c'], { 1: 'X' }) // ['a', 'X', 'c']\nset(['a', 'b', 'c'], { 1: 'X', 2: 'Y' }) // ['a', 'X', 'Y']\n```\n\n## Indices\n\n```js\nset(['a', 'b', 'c'], { '*': 'X' }) // ['X', 'X', 'X']\nset(['a', 'b', 'c'], { '-1': 'X' }) // ['a', 'b', 'X']\nset(['a', 'b', 'c'], { 4: 'X' }) // ['a', 'b', 'c', undefined, 'X']\n```\n\n## Add\n\n```js\n// Array of items can be used\nset(['a', 'b', 'c'], { 1: ['X', 'Y'] }) // ['a', 'X', 'Y', 'c']\nset(['a', 'b', 'c'], { 1: ['X'] }) // ['a', 'X', 'c']\nset(['a', 'b', 'c'], { 1: [['X']] }) // ['a', ['X'], 'c']\n```\n\n## Insert\n\n```js\n// If the key ends with +, items are prepended, not replaced\nset(['a', 'b', 'c'], { '1+': 'X' }) // ['a', 'X', 'b', 'c']\n```\n\n## Append\n\n```js\nset(['a', 'b', 'c'], { '-0': 'X' }) // ['a', 'b', 'c', 'X']\nset(['a', 'b', 'c'], { '-0': ['X', 'Y'] }) // ['a', 'b', 'c', 'X', 'Y']\n```\n\n## Prepend\n\n```js\nset(['a', 'b', 'c'], { '0+': ['X', 'Y'] }) // ['X', 'Y', 'a', 'b', 'c']\n```\n\n## Delete\n\n```js\nset(['a', 'b', 'c'], { 1: [] }) // ['a', 'c']\n```\n\n## Set\n\n```js\nset([], { 0: 'X', 2: 'Z' }) // ['X', undefined, 'Z']\n```\n\n# Install\n\n```bash\nnpm install set-array\n```\n\nThis package works in both Node.js \u003e=18.18.0 and\n[browsers](https://raw.githubusercontent.com/ehmicky/dev-tasks/main/src/browserslist).\n\nThis is an ES module. It must be loaded using\n[an `import` or `import()` statement](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c),\nnot `require()`. If TypeScript is used, it must be configured to\n[output ES modules](https://www.typescriptlang.org/docs/handbook/esm-node.html),\nnot CommonJS.\n\n# API\n\n## set(array, updates, options?)\n\n`array` `any[]`\\\n[`updates` `object`](#updates)\\\n[`options` `object?`](#options)\\\n_Return value_: `any[]`\n\nReturn a copy of `array` with each of the [`updates` applied](#updates).\n\n### Updates\n\n#### Values\n\n`updates` values are the items to add.\n\n- Array of values [add multiple items](#add)\n- Empty arrays [remove items](#delete)\n\n#### Keys\n\n`updates` keys are the `array` [indices](#indices) (before any updates).\n\n- [Negative indices](#indices) match from the end\n- `-0` [appends](#append) items\n- If the key [ends with `+`](#insert), items are [prepended](#prepend), not\n  replaced\n- `*` [targets all items](#indices)\n\n### Options\n\nOptions are an optional plain object.\n\n#### merge(oldValue, newValue)\n\n`oldValue` `any`\\\n`newValue` `any`\\\n_Return value_: `any`\n\nBy default, the [`updates`](#updates) items override the original `array`'s\nitems. The `merge` option can be used to merge those instead.\n\nIf an array of items is being added, `merge()` is called once per item.\n\n`merge()` is not called when the update's key ends with `+`, i.e. when items are\nbeing prepended.\n\n`merge()` is called even if the update's index is out-of-bound, with `oldValue`\nbeing `undefined`.\n\n```js\nconst merge = (oldValue, newValue) =\u003e [oldValue, newValue]\n\nset(['a', 'b', 'c'], { 1: 'X' }, { merge }) // ['a', ['b', 'X'], 'c']\nset(['a', 'b', 'c'], { '*': 'X' }, { merge }) // [['a', 'X'], ['b', 'X'], ['c', 'X']]\nset(['a', 'b', 'c'], { 1: ['X', 'Y'] }, { merge }) // ['a', ['b', 'X'], ['b', 'Y'], 'c']\nset(['a', 'b', 'c'], { '1+': 'X' }, { merge }) // ['a', 'X', 'b', 'c']\nset(['a', 'b', 'c'], { 4: 'X' }, { merge }) // ['a', 'b', 'c', undefined, [undefined, 'X']]\n```\n\n## test(updates)\n\n`updates` `any`\\\n_Return value_: `boolean`\n\nReturn whether the argument is an object that follows [the shape](#updates)\nexpected by [`set()`](#setarray-updates-options).\n\n```js\ntest({ 1: 'X' }) // true\ntest({ '1+': 'X' }) // true\ntest({ '-1': 'X' }) // true\ntest({ '*': 'X' }) // true\ntest({}) // true\n\ntest({ notAnIndex: 'X' }) // false\ntest('X') // false\n```\n\n# Related projects\n\n- [`declarative-merge`](https://github.com/ehmicky/declarative-merge): merge\n  objects/arrays declaratively\n- [`wild-wild-utils`](https://github.com/ehmicky/wild-wild-utils): apply\n  `set-array` on multiple properties at once using this module's\n  [`merge()` method](https://github.com/ehmicky/wild-wild-utils#mergetarget-query-value-options)\n\n# Support\n\nFor any question, _don't hesitate_ to [submit an issue on GitHub](../../issues).\n\nEveryone is welcome regardless of personal background. We enforce a\n[Code of conduct](CODE_OF_CONDUCT.md) in order to promote a positive and\ninclusive environment.\n\n# Contributing\n\nThis project was made with ❤️. The simplest way to give back is by starring and\nsharing it online.\n\nIf the documentation is unclear or has a typo, please click on the page's `Edit`\nbutton (pencil icon) and suggest a correction.\n\nIf you would like to help us fix a bug or add a new feature, please check our\n[guidelines](CONTRIBUTING.md). Pull requests are welcome!\n\n\u003c!-- Thanks go to our wonderful contributors: --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START --\u003e\n\u003c!-- prettier-ignore --\u003e\n\u003c!--\n\u003ctable\u003e\u003ctr\u003e\u003ctd align=\"center\"\u003e\u003ca href=\"https://fosstodon.org/@ehmicky\"\u003e\u003cimg src=\"https://avatars2.githubusercontent.com/u/8136211?v=4\" width=\"100px;\" alt=\"ehmicky\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eehmicky\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/ehmicky/set-array/commits?author=ehmicky\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"#design-ehmicky\" title=\"Design\"\u003e🎨\u003c/a\u003e \u003ca href=\"#ideas-ehmicky\" title=\"Ideas, Planning, \u0026 Feedback\"\u003e🤔\u003c/a\u003e \u003ca href=\"https://github.com/ehmicky/set-array/commits?author=ehmicky\" title=\"Documentation\"\u003e📖\u003c/a\u003e\u003c/td\u003e\u003c/tr\u003e\u003c/table\u003e\n --\u003e\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fehmicky%2Fset-array","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fehmicky%2Fset-array","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fehmicky%2Fset-array/lists"}