Collection Fns is a set of flexible, type-safe functions designed to manipulate collections of models:
- a model is defined as an object with a common identifier such as
id
,guid
orsomeId
- a collection is defined as an
Array
of models sharing the sameid
key - flexible functions is defined that any function can applied to any collection of arbitrary models
The project has the following goals:
- to provide a basic set of array collection / model manipulation functions
- to target models by arbitrary property (defaulting to
id
) - to be expressive and flexible
- to be purely functional
- to be TypeScript native
The 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.
Note the "keyed" column below, for functions which take an optional key
parameter, allowing you to target any model schema (defaults to 'id'
).
- an
x
means the modelid
is keyed - an
o
means a different property is keyed
These functions manage single models within a collection:
Function | Keyed | Description | Returns |
---|---|---|---|
first | Get the first model in a collection | model | |
last | Get the last model in a collection | model | |
has | x | Test if a collection has a model | boolean |
get | x | Get a model from a collection | model |
getIndex | x | Get the index of a model in a collection | number |
getRandom | Get a random model from a collection | model | |
add | x | Add a model to a collection, or if it already exists, update | model |
addOrMove | x | Add a model to a collection, or if it already exists, move it to an index | model |
update | x | Update a model if it exists in a collection | model |
move | x | Move a model in a collection to a specific index in the same or a different array | model |
moveToEnd | x | Move a model in a collection to the end of the same or a different array | model |
moveByIndex | Move a model in a collection from one index to another in the same or a different array | model | |
remove | x | Remove a model from a collection | model |
These functions manipulate collections, offering simple lodash-like functionality:
Function | Keyed | Description | Returns |
---|---|---|---|
forEach | Iterate over a collection of models and call a function on each model | array | |
map | Iterate over a collection of models, call a function on each model, and return the updated array | array | |
filter | o | Filter a collection of models by property, including matched values | array |
omit | o | Filter a collection of models by property, omitting matched values | array |
dedupe | x | Filter a collection of models, omitting those with duplicate ids | array |
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 |
sort | o | Sort a collection of models by property | array |
sortBy | Utility function to return a sort() comparison function | function |
Add this line to your project's .npmrc
:
@likelylogic:registry=https://npm.pkg.github.com
Install via the command line:
npm i @likelylogic/collection-fns
Here are some basic examples showing the flexibility and functional nature of the library:
// get the model identified by an id of 5
get(models, 5)
// update the window identified by a windowId of 10 with new data
update(windows, 10, data, 'windowId')
// move a tab identified by a tabId 15 to the 5th index in another collection
move(left, 15, 5, right, 'tabId')
// sort a collection of users by first name
sort(users, 'firstName')
Check the example files for full code:
- Basic – manage arrays of arbitrary models
- Advanced – compose the functions into reusable collection classes
- Generics – example of using and overriding generic type-safety
The package's functions are generic meaning that the values you supply the function will enforce their own type checking.
Consider the following; the people
array should not be able to be updated with the wrong information:
import { update } from '@likelylogic/collection-fns'
const people = [
{ id: 1, name: 'tom' },
{ id: 2, name: 'dick' },
{ id: 3, name: 'harry' },
]
update(people, 2, { age: 100 }) // error! Object literal may only specify known properties, and 'age' does not exist in type 'Partial<{ id: number; name: string; }>'.
To force an update, type the payload as any
:
update(people, 2, { age: 100 } as any)
You can be sure that TypeScript's got your back when shuffling models within and between collections!
-
npm run dev
- build and watch the package for changes -
npm run build
- build the package for production -
npm run prepare
- lint and fix, then build the package ready for publishing -
npm run lint
- run linting -
npm run lint:fix
- run linting and fix errors -
npm run test
- run and watch unit tests
Adding new functionality:
- write code
- write tests
- run tests / check coverage
- update docs
Publishing:
- update package version (minor or patch)
- run scripts:
npm run prepare
npm publish