@bjornstar/tomes

Evented Storage Agnostic Data API

Usage no npm install needed!

<script type="module">
  import bjornstarTomes from 'https://cdn.skypack.dev/@bjornstar/tomes';
</script>

README

NPM

Build Status

Tomes

Evented Storage Agnostic Data API

Tomes Logo

Problem: You've got data and you want to do something whenever it changes.

Access and modify your data through the Tomes API and you'll get change events.

Play with a live demo here - https://bjornstar.github.io/tomes/

Example

var filmData = {
    cast: [
        { name: "Mr. Blonde", guns: 1, razors: 1 },
        { name: "Marvin Nash", ears: [ "left", "right" ], cop: true },
    ]
};

var reservoirDogs = Tome.conjure(filmData);

reservoirDogs.cast[1].on('readable', function (marvinNash) {
    console.log(marvinNash.ears.length);
});
// >>> 2

reservoirDogs.cast[1].ears.pop();
// >>> 1

Tomes API

Tome

Tome.conjure( data )

Returns a new Tome containing your data.

Tome.typeOf( data )

Returns data's type as a string. Tomes has types that exist in JSON which are:

  • array
  • boolean
  • null
  • number
  • object
  • string As well as:
  • undefined

Tome.isTome( data )

Returns a boolean indicating whether data is a Tome or not.

Tome.unTome( tome )

Returns a regular JavaScript version of your Tome.

TomeTypes

  • ArrayTome
  • BooleanTome
  • NullTome
  • NumberTome
  • ObjectTome
  • StringTome
  • UndefinedTome

Tome.destroy( tome )

Make a tome and all of it's sub-tomes emit destroy. This will not delete anything.

Methods

assign( data )

Assign data to a Tome.

set( key, data )

Assign data to key on a Tome. Set will create a Tome on the key if it does not exist.

del( key )

Delete a key from a Tome.

swap( key, tome )

Swap key with tome.

rename( key, newkey )

Rename key to newkey.

move( key, tome, [ newkey ] )

Move key to tome. Optionally call it newkey on that tome.

read( )

Get a single change operation from the root Tome, removing it in the process. Returns null if there are no changes.

readAll( )

Get all change operations from the Tome

merge( diff )

Applies a change operation or an array of change operations to a Tome.

destroy( )

Makes the tome and all of it's sub-tomes emit destroy. Does not delete anything.

unTome( )

Returns a regular javascript version of your Tome.

getKey( )

Returns a Tome's key.

getParent( )

Returns a Tome's parent Tome.

getVersion( )

Returns a Tome's version.

is( value )

Returns a boolean value indicating whether or not the Tome is observably indistinguishable from value (ref). If no value is given, returns whether or not the Tome's value is truthy.

isDirty( )

Returns whether a Tome has been changed, but the change has not been read.

Events

add( key )

Emitted when a Tome receives a new key.

del( key )

Emitted when a key is deleted from a Tome.

destroy( )

Emitted when a Tome is deleted. Removes all event listeners for this Tome.

readable( was )

Emitted every time a Tome or any of its child Tomes are altered. If the Tome was a primitive (ie. string, number, or boolean) the previous value will be emitted as well, but only if it did not change types.

typeChange( tome, oldType, newType )

Emitted by the root tome when a Tome changes type.