Live CRDT DB over IPFS
$ npm install ipfs-live-db --save
In the browser environment, you can either use this library by including it and bundling your app together with it (using browserify or webpack, for instance), or you can
const DB = require('ipfs-live-db')
<!-- loading the minified version -->
<script src="https://unpkg.com/ipfs-live-db/dist/browser.min.js"></script>
<!-- loading the human-readable (not minified) version -->
<script src="https://unpkg.com/ipfs-live-db/dist/browser.js"></script>
Now you can access this library using the IpfsLiveDb
on the global namespace. (In this case, replace DB
on the examples below with IpfsLiveDb
).
const db = DB([options])
Arguments:
- options (object):
ipfs
: a js-ipfs options objectstore
(string, defaults to"memory"
): a local store, represented by a string. Can either be:"indexeddb"
: for in-browser persistence"leveldb"
: for Node.js persistence
partition
(string, mandatory): the partition this data belongs to. It's used to broadcast new record ids (so trackers can follow (and pin) the global partition state)
Defines and returns a type.
const TodoList = db.define('TodoList', {
type: 'Array',
of: {
name: 'TodoItem'
type: 'Object'
}
})
const list = TodoList()
You can chain them:
db.define('TodoItem', {
type: 'Object'
})
const TodoList = db.define('TodoList', {
type: 'Array',
of: 'TodoItem' // not necessary if you don't want a CRDT
})
or simply nest them:
const TodoItem = db.define({
type: 'Object'
})
const TodoList = db.define('TodoList', {
type: 'Array',
of: TodoItem
})
The basic types that come build-in are 'Map' and 'Array'. The rest is up to you.
Creates an instance for a given type.
Depending on the base type, it returns either a specized Map
or Array
instance (see below).
Example:
const id = 'some id'
const item = db.create('TodoItem', id)
Returns the value for the key.
Sets the value for that key
Deletes a property
Returns all keys for all values
The observer
is called whenever something on this object changes. The observer is called with one sole argument of the Event type, which has the following properties:
event.type
: The type of the event. "add" - a new key-value pair was added, "update" - an existing key-value pair was changed, or "delete" - a key-value pair was deleted)- event.name`: The key of the changed property
event.value
: If event type is either "update" or "add", this property defines the new value of the key-value pair
Same as .observe, but catches events from all children (if they support .observeDeep
).
event.path
specifies the path of the change event.
Deactivates an observer.
Inserts contents
at position position
.
Inserts contents
at the end of the array.
Deletes content. The length parameter is optional and defaults to 1.
Returns the complete content as an array.
Returns the content at a given position.
The observer
is called whenever something on this object changes. The observer is called with one sole argument of the Event type, which has the following properties:
event.type
: The type of the event. "insert" - a set of values was inserted, "delete" - a set of values was deletedevent.index
: The position the operation occurred at.event.length
: The number of positions affected.event.values
: The values inserted (if event.type is "insert")event.oldValues
: The values removed (if event.type is "delete")
Same as .observe, but catches events from all children (if they support .observeDeep).
event.path
specifies the path of the change event.
Deactivates an observer.
MIT
Feel free to join in. All welcome. Open an issue!
This repository falls under the IPFS Code of Conduct.