snoman

Immutable data structures using ES6 proxies. Lean, native, and simple.

This works by wrapping the existing data item in a Proxy. It will intercept any methods which mutate the item and replace them with methods that return new copies of the item. Item setters are disabled. Item getters work as normal.

Installing

npm i snoman

Usage

const sno = require('snoman')

const arr = sno([])

// Array methods return a new array instead of modifying existing
const newArr = arr.push('olaf') // --> [ 'olaf' ]

// get an item from the array works
newArr[0] // --> 'olaf'

// setting an item however does not
arr[0] = 66 // --> error!

// can use helper 'set' method instead
arr.set(0, 'sven') // --> [ 'sven' ]

// chaining still works
arr.push(1,2,3).filter(n => n > 1) // --> [ 2, 3 ]


const obj = sno({})

// Object has some helper methods added
const newObj = obj.set('elsa', 'queen') // --> { elsa: 'queen' }

// setting a property fails
obj.elsa = 66 // --> error!

// getting a property works as normal
newObj.elsa // --> 'queen'

// still a native object
JSON.stringify(newObj) // --> '{"elsa": "queen"}'


// Map methods return a new map instead of modifying existing
const map = sno(new Map())
const newMap = map.set('olaf', 'impaled') // --> Map {"olaf" => "impaled"}


// Set methods return a new set instead of modifying existing
const set = sno(new Set())
const newSet = set.add('anna') // --> Set {"anna"}

Documentation

sno(item)

Returns an item with immutable properties. Setting properties on the item results in an error. Methods which mutate the item will return a new copy of the item instead.

• item Object|Array|Map|Set - Data structure to make immutable

Extra Array helper methods

• set(index, val) - Same idea as array[index] = val Returns a new array with val inserted at index
• remove(val) - Returns a new array with val removed

Extra Object helper methods

• set(key, val) - Same idea as object[key] = val Returns a new object with val as key
• merge(...objects) - Returns a new object and merges existing object with n-number of other objects
• delete(key) - Returns a new object with property key removed
• entries() - Returns an array with all object items. e.g. [ ['key1', 'value1'], ['key2', 'value2'] ]
• keys() - Returns an array with all object keys. e.g. [ 'key1', 'key2' ]
• values() - Returns an array with all object values. e.g. [ 'value1', 'value2' ]

Proxied Array methods

• push
• unshift
• pop
• shift
• sort
• reverse
• splice

Proxied Map methods

• set
• delete

Proxied Set methods

• add
• delete

Development

Install necessary dependencies

npm install

Run the tests

npm test

Wish list

• deep init option - walk through an object tree and freeze all object-like items with sno()

Contributing

Contributions welcome. Submit a Pull Request :)

License

MIT