timm

What is timm?

The 'timm' npm package is a small, fast, and pure immutable collections library. It provides utilities for working with immutable data structures, making it easier to manage state in JavaScript applications.

What are timm's main functionalities?

Immutable Object Update

This feature allows you to update an object immutably. The `set` function creates a new object with the updated value, leaving the original object unchanged.

const timm = require('timm');
const obj = { a: 1, b: 2 };
const newObj = timm.set(obj, 'b', 3);
console.log(newObj); // { a: 1, b: 3 }

Deep Merge

The `merge` function allows you to deeply merge two objects, creating a new object that combines the properties of both input objects.

const timm = require('timm');
const obj1 = { a: 1, b: { c: 2 } };
const obj2 = { b: { d: 3 } };
const mergedObj = timm.merge(obj1, obj2);
console.log(mergedObj); // { a: 1, b: { c: 2, d: 3 } }

Array Push

This feature allows you to add an element to the end of an array immutably. The `addLast` function creates a new array with the added element, leaving the original array unchanged.

const timm = require('timm');
const arr = [1, 2, 3];
const newArr = timm.addLast(arr, 4);
console.log(newArr); // [1, 2, 3, 4]

Array Remove

The `removeAt` function allows you to remove an element from an array immutably. It creates a new array without the specified element, leaving the original array unchanged.

const timm = require('timm');
const arr = [1, 2, 3];
const newArr = timm.removeAt(arr, 1);
console.log(newArr); // [1, 3]

Other packages similar to timm

immutable

The 'immutable' package provides persistent immutable data structures, including List, Map, Set, and Record. It is more comprehensive and feature-rich compared to 'timm', but also larger in size and complexity.

immer

The 'immer' package allows you to work with immutable state by using a 'draft' state that you can modify directly. It is more intuitive for developers who are used to mutable operations, but it uses a different approach compared to 'timm'.

seamless-immutable

The 'seamless-immutable' package provides immutable data structures that are backwards-compatible with normal JavaScript arrays and objects. It is similar to 'timm' in terms of simplicity and ease of use, but it offers a different API.

README

timm

Immutability helpers with fast reads and acceptable writes

Install

$ npm install --save timm

Motivation and benchmarks

TBW

Usage

Arrays

addLast()

Returns a new array with an appended item.

Usage: addLast(array: Array, val: any): Array

arr = ['a', 'b']
arr2 = addLast(arr, 'c')
// [ 'a', 'b', 'c' ]
arr2 === arr
// false

addFirst()

Returns a new array with a prepended item.

Usage: addFirst(array: Array, val: any): Array

arr = ['a', 'b']
arr2 = addFirst(arr, 'c')
// [ 'c', 'a', 'b' ]
arr2 === arr
// false

removeAt()

Returns a new array obtained by removing an item at a specified index.

Usage: removeAt(array: Array, idx: number): Array

arr = ['a', 'b', 'c']
arr2 = removeAt(arr, 1)
// [ 'a', 'c' ]
arr2 === arr
// false

replaceAt()

Returns a new array obtained by replacing an item at a specified index. If the provided item is the same (referentially equal to) the previous item at that position, the original array is returned.

Usage: replaceAt(array: Array, idx: number, newItem: any): Array

arr = ['a', 'b', 'c']
arr2 = replaceAt(arr, 1, 'd')
// [ 'a', 'd', 'c' ]
arr2 === arr
// false
replaceAt(arr, 1, 'b') === arr
// true

Objects

set()

Returns a new object with a modified attribute. If the provided value is the same (referentially equal to) the previous value, the original object is returned.

Usage: set(obj: Object, key: string, val: any): Object

obj = {a: 1, b: 2, c: 3}
obj2 = set(obj, 'b', 5)
// { a: 1, b: 5, c: 3 }
obj2 === obj
// false
set(obj, 'b', 2) === obj
// true

setIn()

Returns a new object with a modified nested attribute.

Usage: setIn(obj: Object, path: Array<string>, val: any): Object If the provided value is the same (referentially equal to) the previous value, the original object is returned.

obj = {a: 1, b: 2, d: {d1: 3, d2: 4}, e: {e1: 'foo', e2: 'bar'}}
obj2 = setIn(obj, ['d', 'd1'], 4)
// { a: 1, b: 2, d: { d1: 4, d2: 4 }, e: { e1: 'foo', e2: 'bar' } }
obj2 === obj
// false
obj2.d === obj.d
// false
obj2.e === obj.e
// true
obj3 = setIn(obj, ['d', 'd1'], 3)
// { a: 1, b: 2, d: { d1: 3, d2: 4 }, e: { e1: 'foo', e2: 'bar' } }
obj3 === obj
// true
obj3.d === obj.d
// true
obj3.e === obj.e
// true

merge()

Returns a new object built as follows: the overlapping keys from the second one overwrite the corresponding entries from the first one. Similar to Object.assign(), but immutable.

Usage: merge(obj1: Object, obj2: Object): Object

The unmodified obj1 is returned if obj2 does not provide something new to obj1, i.e. if either of the following conditions are true:

• obj2 is null or undefined
• obj2 is an object, but it is empty
• All attributes of obj2 are referentially equal to the corresponding attributes of obj

addDefaults()

Returns a new object built as follows: undefined keys in the first one are filled in with the corresponding values from the second one. Similar to underscore's defaults() function, but immutable.

Usage: merge(obj: Object, defaults: Object): Object

MIT license

Copyright (c) Guillermo Grau Panea 2016

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.