imm

IMM.js

Immutable data collections build on top of seamless-immutable

Seemless-immutable.js is great, but it doesn't have an API that feels right for CRUD applications. Imm wraps it to provide a convenient API. For example:

collection.add(record);
collection.get(id);
collection.update(record);
...

Install

Using NPM

npm install imm

Browser global

Download dist/imm.js or dist/imm.min.js

This library requires seamless-immutable to be loaded.

API

imm

Returns an Imm collection Keys are always sorted in alphabetical order

• {Array}: records Array of records
• {Object}: args Optional arguments
• {String}: args.key=id Optional name of id key e.g. _id
• returns {Imm}: Imm collection

Example

var records = [{id: 1, label: 'Sam'}, {...}];
collection = imm(records);

imm assumes that the id key is called id. You can provide an optional argument:

collection = imm(records, {key: '_id'});

add

Adds one or more records. If record already exists then it gets replaced. If a record doesn't have a key, then the key will be autogenerated.

• {Object|Array}: recordOrRecords Record or records to add
• {Object}: args Optional arguments
• {Boolean}: args.strict=false Throw if record already exists
• returns {Imm}: modified collection

Example

// add one
collection = collection.add(record)

// add many records
collection = collection.add(array)

allExist

Check if the given ID or all given IDs exist.

• {Number|String|Array}: idOrIds ID or IDs to check
• returns: {Boolean}

Example

var exist = allExist(21);
var exist = allExist([11, 21]);

anyExist

Check if the given ID or any given IDs exist

• {Number|String|Array}: idOrIds Id or Ids to check
• returns: {Boolean}

Example

var exist = anyExist(21);
var exist = anyExist([11, 21]);

array

Get all records. Records in the array are plain mutable JS objects.

• returns {Array}: records Plain array with records

Example

var records = collection.array();

count

Records count.

• returns {Number}: count

Example

count = collection.count();

filter

Filters the collection based on a filtering function.

• {Function}: filterer Filtering function
• returns {Imm}: Modified collection

Example

collection = collection.filter(function (record) {
  return record.age > 18;
});

find

Finds one record. Returns a plain JS mutable object.

• {Function}: finder Finder function
• returns {Object}: record Record or undefined

Example

var record = collection.find(function (record) {
  return record.age === 18;
});

get

Get a record. Returned record is a plain JS mutable object.

• {Number|String}: id Id to fetch
• returns {Object}: record

Example

var record = collection.get(11)
var record = collection.get('11') // same as 11

map

Map the collection through a given function

• {Function}: mapper Mapping function
• returns {Array}: array

Example

collection = collection.map(function (record) {
  return {foo: record.id};
});

remove

Removes one or many records based on the id. If record is not found then it just gets skipped.

• {Number|String|Array}: idOrIds Id or ids to remove
• {Object}: args Optional arguments
• {Boolean}: args.strict=false Throw if record(s) doesn't exists
• returns {Imm}: Modified collection

Example

collection = collection.remove(id);
collection = collection.remove(arrayOfIds);

replace

Replaces one item or many. This discards any previous data from the replaced items. If records doesn't exist then it just gets added. This throws if a record doesn't have an key.

• {Object}: recordOrRecords Record or records to replace
• {Object}: args Optional arguments
• {Boolean}: args.strict=false Throws if record exist
• {Boolean}: args.requireKey=true Throws if record doesn't have a key
• returns {Imm}: Modified Imm collection

Example

collection = collection.replace(record)
collection = collection.replace(array)

update

Updates one record or many. This merges the given data with the existing one. If a record is not found then it gets added. This throws if a record doesn't have an key

• {Object|Array}: recordOrRecords Record or records to update
• {Object}: args Optional arguments
• {Boolean}: args.strict=false Throws if record exist
• returns {Imm}: Modified collection

Example

collection = collection.update(record)
collection = collection.update(array)

Things to note

• Methods that return collections (e.g. filter) return an instance of Imm
• Methods that return one record (e.g. get, find), return a plain JS object

Test

npm install
npm test

Build

This will lint, test, minify and create documentation

gulp

Related projects

• immutable.js
• seamless-immutable