{"_id":"@davestewart/collection-fns","_rev":"1-2ed8b56d89ce3724bee130ea7ab1f482","name":"@davestewart/collection-fns","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.1":{"name":"@davestewart/collection-fns","version":"1.0.1","description":"A set of flexible functions to query and manipulate arrays of models","author":{"name":"Dave Stewart"},"keywords":["models","collections","typescript","utility"],"license":"MIT","homepage":"https://github.com/davestewart/collection-fns#readme","bugs":{"url":"https://github.com/davestewart/collection-fns/issues"},"repository":{"type":"git","url":"git+https://github.com/davestewart/collection-fns.git"},"main":"dist/collection-fns.js","module":"dist/collection-fns.esm.js","jsnext:main":"dist/collection-fns.esm.js","types":"dist/index.d.ts","scripts":{"dev":"rollup -c build/rollup.js -w","build":"rollup -c build/rollup.js","prepare":"npm run lint:fix && npm run build","lint":"eslint 'src/**/*.ts' 'tests/**/*.ts'","lint:fix":"npm run lint -- --fix","test":"jest --watchAll --verbose","test:coverage":"jest --coverage"},"devDependencies":{"@rollup/plugin-buble":"^0.21.3","@rollup/plugin-commonjs":"^11.1.0","@types/jest":"^25.2.1","@typescript-eslint/eslint-plugin":"^2.29.0","@typescript-eslint/parser":"^2.29.0","eslint":"^6.8.0","eslint-config-standard":"^14.1.1","eslint-plugin-import":"^2.20.2","eslint-plugin-jest":"^23.8.2","eslint-plugin-node":"^11.1.0","eslint-plugin-promise":"^4.2.1","eslint-plugin-standard":"^4.0.1","jest":"^25.4.0","rollup":"^2.7.2","rollup-plugin-license":"^2.0.0","rollup-plugin-typescript2":"^0.27.0","rollup-plugin-uglify":"^6.0.4","ts-jest":"^25.4.0","typescript":"^3.8.3"},"gitHead":"d2c3ee38cb8b6acf9741882ca81775de66740c13","_id":"@davestewart/collection-fns@1.0.1","_nodeVersion":"14.16.0","_npmVersion":"6.14.11","dist":{"integrity":"sha512-kpHwwTfRmzsQGCFl+GPuSmnLp9r1HHdeT1dhREE5ZTuD2eeARGX8NHUdtO+efsgjFMYVLx41B7qCDzKl22AmZA==","shasum":"98ee700d38a59d253aba1baf481dc59e8c5f856d","tarball":"https://registry.npmjs.org/@davestewart/collection-fns/-/collection-fns-1.0.1.tgz","fileCount":19,"unpackedSize":74920,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.13\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJhlCrHCRA9TVsSAnZWagAAwzgP/1EQl3LXeKHA6LkRuunb\nZbghUu+6fEDHIpPe35NDMeC8TfpwzEbhySWYFX3BKEwmhuQs8D6pYxF9CXKb\nChlWbq+HZcpdbzdbUbHkuE4lZHeM+nTXAXoRfqrRGx1NuBT7hfMzm5K0xih5\ngjFwInWh71LIHeDpYY7RyfiDCN3QeXx7UvBUP43K3as1wHVnrMqCg7C3U2a7\nphu64z9KO3ftHHG0qm7gNqEr7aVz40JbBK9c4+BglHQcleyfuv/o8DMA0Y63\nwrNuIs+vE3WwuJ0g1wzrnHao/7EsdOf+WKZQ+M4f3lFgVeptVum6Zt5uMjBV\n9r7tRphMZ/vIA3XEjW4jcx71H31/MQw5JjUuRJLa2TfQtpEMVaXk+zds5Idc\nd70LZ0Da7lLUjmnzGYJuqTU3/5Soy2OvZevHwHdGZpVxELELcI8f0hyNq70J\nWKlTxb89tcq0iL8uhXwltrfKdVgrJ6G31QMQoH/SA66HTUoQcuPahT6ci5kv\n0TMYvF6Cf6Y4FWv2DzfiFrLpugON0HUIITQvRVabp+AFKlsZug8dhQTV6ks9\nXc8TIND3jReGXilOmc3LzgrGECklwdwKdgh5CrLdoPEbvp8Jy3yt7mEu7YKB\n/ARCyebo2kMVlfNSrAIF5cOjUQKRxoLfko99W2DamHC47Trfu9436cP/2YJn\nYu/n\r\n=S5rU\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQCNn7niCJTEbY9gizI3iszcgQ72gXvgDjTx/ZW+e5dl2AIgA6FhTCSLw8e8rif0dDy1frldPBgL5pGI89Aab4CAvvg="}]},"_npmUser":{"name":"davestewart","email":"dev@davestewart.co.uk"},"directories":{},"maintainers":[{"name":"davestewart","email":"dev@davestewart.co.uk"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/collection-fns_1.0.1_1637100231697_0.9590049667777456"},"_hasShrinkwrap":false}},"time":{"created":"2021-11-16T22:03:51.622Z","1.0.1":"2021-11-16T22:03:51.917Z","modified":"2022-04-05T03:05:22.368Z"},"maintainers":[{"name":"davestewart","email":"dev@davestewart.co.uk"}],"description":"A set of flexible functions to query and manipulate arrays of models","homepage":"https://github.com/davestewart/collection-fns#readme","keywords":["models","collections","typescript","utility"],"repository":{"type":"git","url":"git+https://github.com/davestewart/collection-fns.git"},"author":{"name":"Dave Stewart"},"bugs":{"url":"https://github.com/davestewart/collection-fns/issues"},"license":"MIT","readme":"# Collection Fns\n\n## Abstract\n\nCollection Fns is a set of flexible, type-safe functions designed to manipulate collections of models:\n\n- a **model** is defined as an object with a common identifier such as `id`, `guid` or `someId`\n- a **collection** is defined as an `Array` of models sharing the same `id` key\n- **flexible functions** is defined that any function can applied to any collection of arbitrary models\n\nThe project has the following goals:\n\n- to provide a basic set of array collection / model manipulation functions\n- to target models by arbitrary property (defaulting to `id`)\n- to be expressive and flexible\n- to be purely functional\n- to be TypeScript native\n\nThe end result is you use simple, safe and robust helper functions to maniulate arrays of models without ever having to resort to writing repetitive, complex, fragile or error-prone array-centric code.\n\n\n## Functions\n\nNote the  \"keyed\" column below, for functions which take an optional `key` parameter, allowing you to target any model schema (defaults to `'id'`).\n\n- an `x` means the model `id` is keyed\n- an `o` means a different property is keyed\n\n### Models\n\nThese functions manage single models within a collection:\n\n| Function    | Keyed  | Description                                                  | Returns |\n| ----------- | ------ | ------------------------------------------------------------ | ------- |\n| first       | &nbsp; | Get the first model in a collection                          | model   |\n| last        | &nbsp; | Get the last model in a collection                           | model   |\n| has         | x      | Test if a collection has a model                             | boolean |\n| get         | x      | Get a model from a collection                                | model   |\n| getIndex    | x      | Get the index of a model in a collection                     | number  |\n| getRandom   | &nbsp; | Get a random model from a collection                         | model   |\n| add         | x      | Add a model to a collection, or if it already exists, update | model   |\n| addOrMove   | x      | Add a model to a collection, or if it already exists, move it to an index | model   |\n| update      | x      | Update a model if it exists in a collection                  | model   |\n| move        | x      | Move a model in a collection to a specific index in the same or a different array | model   |\n| moveToEnd   | x      | Move a model in a collection to the end of the same or a different array | model   |\n| moveByIndex | &nbsp; | Move a model in a collection from one index to another in the same or a different array | model   |\n| remove      | x      | Remove a model from a collection                             | model   |\n\n### Collections\n\nThese functions manipulate collections, offering simple lodash-like functionality:\n\n| Function | Keyed  | Description                                                  | Returns  |\n| -------- | ------ | ------------------------------------------------------------ | -------- |\n| forEach  | &nbsp; | Iterate over a collection of models and call a function on each model | array    |\n| map      | &nbsp; | Iterate over a collection of models, call a function on each model, and return the updated array | array    |\n| filter   | o      | Filter a collection of models by property, including matched values | array    |\n| omit     | o      | Filter a collection of models by property, omitting matched values | array    |\n| dedupe   | x      | Filter a collection of models, omitting those with duplicate ids | array    |\n| merge    | x      | Given two arrays of models, add the models not found in the first array from the second array, and return the new array | array    |\n| sort     | o      | Sort a collection of models by property                      | array    |\n| sortBy   | &nbsp; | Utility function to return a sort() comparison function      | function |\n\n\n## Installation\n\nInstall via the command line:\n\n```bash\nnpm i @davestewart/collection-fns\n```\n\n## Usage\n\nHere are some basic examples showing the flexibility and functional nature of the library:\n\n```js\n// get the model identified by an id of 5\nget(models, 5)\n```\n\n```js\n// update the window identified by a windowId of 10 with new data \nupdate(windows, 10, data, 'windowId')\n```\n\n```js\n// move a tab identified by a tabId 15 to the 5th index in another collection\nmove(left, 15, 5, right, 'tabId')\n```\n\n```js\n// sort a collection of users by first name\nsort(users, 'firstName')\n```\n\nCheck the example files for full code:\n\n- [Basic](./examples/basic.ts) – manage arrays of arbitrary models\n- [Advanced](./examples/advanced.ts) – compose the functions into reusable collection classes\n- [Generics](./examples/generics.ts) – example of using and overriding generic type-safety\n\n\n## Generic type safety\n\nThe package's functions are [generic](https://www.typescriptlang.org/docs/handbook/generics.html#using-type-parameters-in-generic-constraints) meaning that the values you supply the function will enforce their own type checking.\n\nConsider the following; the `people` array should not be able to be updated with the wrong information:\n\n```ts\nimport { update } from '@davestewart/collection-fns'\n\nconst people = [\n  { id: 1, name: 'tom' },\n  { id: 2, name: 'dick' },\n  { id: 3, name: 'harry' },\n]\n\nupdate(people, 2, { age: 100 }) // error! Object literal may only specify known properties, and 'age' does not exist in type 'Partial<{ id: number; name: string; }>'.\n```\n\nTo force an update, type the payload as `any`:\n\n```ts\nupdate(people, 2, { age: 100 } as any)\n```\n\nYou can be sure that TypeScript's got your back when shuffling models within and between collections!\n\n## Scripts\n\n - `npm run dev` - build and watch the package for changes\n\n- `npm run build` - build the package for production\n- `npm run prepare` - lint and fix, then build the package ready for publishing\n- `npm run lint` - run linting\n- `npm run lint:fix` - run linting and fix errors\n- `npm run test` - run and watch unit tests\n\n## Contributing\n\nAdding new functionality:\n\n- write code\n- write tests\n- run tests / check coverage\n- update docs\n\nPublishing:\n\n- update package version (minor or patch)\n- run scripts:\n\n```\nnpm run prepare\nnpm publish\n```\n","readmeFilename":"README.md"}