Instancify

Simple CoW (copy on write) strategy for javascript data structures.

Getting Started

npm install instancify

const instancify = require("instancify");
const instance1 = instancify([1,2,3]);

Guarantees

• All data accessible from instancify is read only

• No external references to the instancify internal data so must use instancify methods to access data

• Every write returns a brand new instance with brand new references

• Can only set an instance once so instance always follow a linear path

Uses

Basic use

const instance1 = instancify([1,2,3]);
const instance2 = instance1.writeNewInstanceWithTransformation(data => data.map(val => val + 1));
//instance1 and instance2 share no refernces with each other

Works with 3rd party libraries like ramda and lodash

const instance1 = instancify([1,2,3]);
const instance2 = instance1.writeNewInstanceWithTransformation(data => R.pipe(R.map(val => val + 1))(data));
//instance2 => [2,3,4]

Read only values

const instance1 = instancify([1,2,3]);
instance1[0] = 2;
//throws an error

Can only set an instance once

const instance1 = instancify([1,2,3]);
const instance2a = instance1.writeNewInstanceWithTransformation(data => data.map(val => val + 1));
const instance2b = instance1.writeNewInstanceWithTransformation(data => data.map(val => val + 2));
//returns instance1 and also calls user defined callback function or logs a warning    

Can add methods to instancify

const instance1 = instancify([1,2,3], {
    customSetters: {
        someTransformation: .....
    }
});
const instance2 = instance1.someTransformation();

Lazy

const instance1 = instancify([1,2,3]);
const addToEachElement = instance1.writeNewInstanceWithTransformation(data => num => data.map(val => val + num);
const instance2 = addToEachElement(5);

Can be used as an interface for third party persistent data libraries

const Immutable = require('immutable');
const map = Immutable.Map({num:10});
const instance1 = instancify(map, {
    shouldClone: false,
    shouldFreeze: false,
    customSetters: {
        changeNum: (data, val) => data.set('num', val)
    },
    customGetters: {
        getNum: (data) => data.get('num')
    }
});
const num1 = instance1.getNum();//10
const instance2 = instance1.changeNum(20);
const num2 = instance2.getNum();//20

API

instancify(data, options)

Methods

• writeNewInstance

"Sets new instance"
const instance1 = instancify([1,2,3]).writeNewInstance([4,5,6]);
//[4,5,6]

• writeNewInstanceWithPath

"Sets a property of the new instance"
const instance1 = instancify([{a:1},{b:2}]).writeNewInstanceWithPath([0, "a"], 2);
//[{a:2},{b:2}]
const instance2 = instance1.writeNewInstanceWithPath("[0].a"], 3);
//[{a:3},{b:2}]

• writeNewInstanceWithTransformation

"Sets the new instance with a transformation"
const instance1 = instancify([{a:1},{b:2}]).writeNewInstanceWithTransformation(function(data) {
    data[0].a = 3;
    data[1].b = 4;
    return data;
});
//[{a:3},{b:4}]

Options

• customClone

"Replace the clone implementation instancify is using with another"
const instance1 = instancify(data, {
    customClone: //whatever clone implementation you'd like instancify to use
});

• shouldClone

"Turn cloning on or off"
const instance1 = instancify(data, {
    shouldClone: true//defaults to true
});

• shouldFreeze

"Turn freezing on or off"
const instance1 = instancify(data, {
    shouldFreeze: true//defaults to true
});

• customSetters

"Add you own setter methods onto instancify"
const instance1 = instancify(data, {
    customSetters: {
        myOwnMethod: function(data, prop, val) {
            data[prop] = val;
            return data;
        }
    }
});

• customGetters

"Add you own getter methods onto instancify"
const instance1 = instancify(data, {
    customGetters: {
        getSomething: function(data, prop) {
            return data[prop];
        }
    }
});

• errorFunction

"Add you own error function for when setter get called on an instance more than once"
const instance1 = instancify(data, {
    errorFunction: function(instance) {
        alert("tried to set this instance twice", instance)
    }
});

• lift

"Add you own setter methods onto instancify after initializing instancify"
const instance1 = instancify(data);
const instance2 = instance1.lift({
    customSetters: {
        myOwnMethod: function(data, prop, val) {
            data[prop] = val;
            return data;
        }
    },
    customGetters: {
        getSomething: function(data, prop) {
            return data[prop];
        }
    }
});

• getLatestInstance

"Get the latest instance"
const instance1 = instancify(data);
const instance2 = instance1.writeNewInstanceWithTransformation(someTransformFunction);
console.log(instance1.getLatestInstance() === instance2)
//true

Tests

To run test in root directory use command npm run test

LICENSE

LICENSE