Product
Introducing License Enforcement in Socket
Ensure open-source compliance with Socket’s License Enforcement Beta. Set up your License Policy and secure your software!
Raven is a tool to manage state and do data-binding in JS vanilla applications.
It allows you to keep the state of your application in a single place (aka. the store) and allows you to attach callbacks that execute when changes happen to any particular piece of data.
It also allows you to link DOM elements to any piece os data in the store, so the changes to the store are reflected on the DOM and vice-versa.
Because the store doesn't rely on getters and setters, it is easy to inspect and easily detect changes to deeply nested properties, including arrays and objects.
Because in javascript arguments are "passed by value", references to an object or DOM elements property are made through an object with a target and a prop properties. We'll call it reference by object
.
For example, consider the following object:
const store = {
keyA: {
keyB: {
keyC: 'value'
}
}
}
To make a reference to value, you'd do:
const reference = {
target: store.keyA.keyB,
prop: keyC
}
There is a second, easier way to pass the reference: as a string of period separated props. We'll call it reference by string
. The same reference as above could be writen as:
const reference = 'keyA.keyB.keyC'
Raven is an ES6 module.
import raven from './node_modules/@dvo/raven/lib/index.js'
const store = {
a: []
b: {
c: 0, d: 0
}
}
raven.load(store)
Once a store is loaded, you nee to call raven.set
to change values (directly changing them would not fire any callback).
In the example below, we'd set the "c" property of the store above to 10 using reference by string
:
raven.set('b.c', 10)
Alternatively, if you pass a reference by object
, you can change multiple properties to different values in one go:
raven.set({
a: [1, 2, 3]
b: { c: 10 }
})
You can subscribe callbacks to run when any particular piece of data within the store is changed. The example below would output the new value of "c" whenever it changed - in this case, it'd log hello world".
raven.callback('b.c', console.log)
raven.set('b.c', 'hello world')
// Logs 'hello world'
If you subscribe a callback to a prop, any changes to its value - no matter how deep - will trigger the callback. So in the example below, note how one change to the store can trigger multiple callbacks:
raven.callback('b', console.log)
raven.callback('b.c', console.log)
raven.set('b.c', 'hello world')
// Logs 'hello world'
// Logs { c: 'hello world' }
(For future-proofing, you should not rely on the order of execution of the callbacks.)
You can clear all subscriptions by calling:
raven.clear()
If you pass a reference by string
or array such references, all callbacks attached to those properties are forgotten.
raven.clear(['b', 'b.c'])
If you pass a function or array of functions, any instance of that function registerd as a callback will be forgotten, no matter to what property it is attached to.
raven.clear(console.log)
You could pass arrays containing both reference by string
and functions.
To "push" means sending the value of an input up to the store, dynamically. Doing so requires you pass DOM element referenced by object
, and then the property of the store, usually referenced by string
. In the example below, we'll push any value typed on the input to the prop 'd' of the store.
raven.push({
target: document.querySelector('input[type="text"]')
prop: 'value'
},
'b.d'
)
Raven.push
takes an optional third parameter: a function that will receive and process the value of the input before setting it to the store. For example:
raven.push({
target: document.querySelector('input[type="text"]')
prop: 'value
},
'b.d',
Number
)
// Whatever the user types into the input gets coerced into a number.
(Push has a fourth and fith optional arguments for dependency injection for testing purposes. Normal use dispenses them.)
To "pull" means sending the value from the store back to a DOM element. Doing so requires referencing the property of the store (usually a reference by string
) and then the DOM element, referenced by object
. In the example below we'll pull the prop "d" of the store into the <h1>
of the page.
raven.pull(
'b.d',
{
target: document.querySelector('h1')
prop: 'textContent'
}
)
Raven.pull
takes an optional third parameter: a function that will receive and process the value of the store before pulling it into the DOM element. For example:
raven.pull({
target: document.querySelector('input[type="text"]')
prop: 'value
},
'b.d',
value => `USD $${value},00`
)
// Any value in the prop "d" will be masked into a currency notation before put in the <h1>.
(Pull has a fourth optional argument for dependency injection for testing purposes. Normal use dispenses it.)
Push and pull are often used together to create "controlled forms", which means: the input displays the value from the store, and any change to the input is reflected to the store. This very common use has its own shortcut in Raven.sync
.
It takes the property of the store (usually a reference by string
) and the element (reference by object
), setting both pull and push for you. For example:
raven.sync(
'b.d',
{
target: document.querySelector('input[type="text"]')
prop: 'value
}
)
Raven.sync
takes optional third and fourth parameters. The third is the intermediate function to format the value as it is pushed up to the store and the fourth is the intermediate function to format the value as it is pulled down to the input. For example:
raven.sync(
'b.d',
{
target: document.querySelector('input[type="text"]')
prop: 'value
},
value => value.slice(4),
value => `USD $${value}`
)
FAQs
A simple store and databinding tool for vanilla applications.
We found that @dvo/raven demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Ensure open-source compliance with Socket’s License Enforcement Beta. Set up your License Policy and secure your software!
Product
We're launching a new set of license analysis and compliance features for analyzing, managing, and complying with licenses across a range of supported languages and ecosystems.
Product
We're excited to introduce Socket Optimize, a powerful CLI command to secure open source dependencies with tested, optimized package overrides.