@davestewart/collection-fns

Collection Fns

Abstract

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 or someId
• a collection is defined as an Array of models sharing the same id 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.

Functions

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 model id is keyed
• an o means a different property is keyed

Models

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

Collections

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

Installation

Install via the command line:

npm i @davestewart/collection-fns

Usage

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

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 '@davestewart/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!

Scripts

• 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

Contributing

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