0.5.25 • Published 6 years ago

referential v0.5.25

Weekly downloads
328
License
MIT
Repository
github
Last release
6 years ago

referential

npm build dependencies downloads license chat

Refer to mutable state safely.

Referential makes it easy to share mutable state safely. A Ref to an object or subtree always refers to the same underlying data regardless how it's mutated.

Heavily optimized for reads.

Motivating example

var state = {a: {b: {c: "world"}}}

var render = (function() {
    var template = state.a.b.c;
    return function() {
        return "Hello " + template
    }
}())

state.a.b.c = "This will be lost on you."

console.log(render()) // Hello world

Install

$ npm install referential --save

Usage

refer = require('referential')

// Create a reference
ref = refer({a: 1})

// Get underlying value of reference
ref()    // {a: 1}
ref('a') // 1

// Mutate state
ref.set('b', 2) // {a: 1, b: 2}
ref.set({c: 3}) // {a: 1, b: 2, c: 3}

// Extend state
ref.extend({c: {d: 1, e: 2}}) // {a: 1, b: 2, c: {d: 1, e: 2}}
ref.extend({c: {d: 3}})       // {a: 1, b: 2, c: {d: 3, e: 2}}

// Create entire tree as needed
ref.set('d.e.f', 4) // {a: 1, b: 2, c: 3, d: {e: {f: 4}}}

// Get reference to subtree
ref2 = ref.refer('d.e')
ref2() // {f: 4}

// Mutate subtree (and update parent)
ref2.set('g', 5)
ref2() // {f: 4, g: 5}

// Mutate parent (and update subtree)
ref.set('d.e.f', 6)
ref()  // {a: 1, b: 2, c: 3, d: {e: {f: 6, g: 5}}}
ref2() // {f: 6, g: 5}

// Clone ref, create new tree
ref3 = ref2.clone()
ref3.set('g', 6)
ref3() // {f: 6, g: 6}
ref2() // {f: 6, g: 5}

// Bind to update event, should print `x was set to 2 from 1`
ref4 = refer({x: 1})
ref4.on('set', function(name, newValue, oldValue) {
    console.log(name + ' was set to ' + newValue + ' from ' + oldValue)
})
ref4.set('x', 2)

Check the tests for more examples.

License

MIT

0.5.25

6 years ago

0.5.23

7 years ago

0.5.22

7 years ago

0.5.21

7 years ago

0.5.18

8 years ago

0.5.17

8 years ago

0.5.15

8 years ago

0.5.14

8 years ago

0.5.13

8 years ago

0.5.12

8 years ago

0.5.11

8 years ago

0.5.10

8 years ago

0.5.9

8 years ago

0.5.8

8 years ago

0.5.7

8 years ago

0.5.6

8 years ago

0.5.5

8 years ago

0.5.4

8 years ago

0.5.3

8 years ago

0.5.2

8 years ago

0.5.1

8 years ago

0.5.0

8 years ago

0.4.6

8 years ago

0.4.5

9 years ago

0.4.4

9 years ago

0.4.3

9 years ago

0.4.2

9 years ago

0.4.1

9 years ago

0.4.0

9 years ago

0.3.13

9 years ago

0.3.12

9 years ago

0.3.11

9 years ago

0.3.10

9 years ago

0.3.9

9 years ago

0.3.8

9 years ago

0.3.7

9 years ago

0.3.6

9 years ago

0.3.5

9 years ago

0.3.4

9 years ago

0.3.3

9 years ago

0.3.2

9 years ago

0.3.1

9 years ago

0.3.0

9 years ago

0.2.0

9 years ago

0.1.3

9 years ago

0.1.2

9 years ago

0.1.1

9 years ago

0.1.0

9 years ago