orbit-db/API.md

orbit-db API documentation

Table of Contents

• Getting Started
• orbitdb
  • kvstore(name)
    • put(key, value)
    • set(key, value)
    • get(key)
    • events
  • eventlog(name)
    • add(event)
    • get(hash)
    • iterator([options])
    • events
  • feed(name)
    • add(data)
    • get(hash)
    • iterator([options])
    • remove(hash)
    • events
  • docstore(name, options)
    • put(doc)
    • get(hash)
    • query(mapper)
    • del(key)
    • events
  • counter(name)
    • value
    • inc([amount])
    • events
  • disconnect()
  • events
    • orbitdb
    • stores

Getting Started

Install orbit-db and ipfs from npm:

npm install orbit-db ipfs

Require it in your program:

const IPFS = require('ipfs')
const OrbitDB = require('orbit-db')

const ipfs = new IPFS()
const orbitdb = new OrbitDB(ipfs)

This will tell orbit-db to use the Javascript implementation of IPFS. Choose this options if you're using orbitd-db to develop Browser applications.

Alternatively, you can use ipfs-api to use orbit-db with a locally running IPFS daemon:

npm install orbit-db ipfs-api

const IpfsApi = require('ipfs-api')
const OrbitDB = require('orbit-db')

const ipfs = IpfsApi('localhost', '5001')
const orbitdb = new OrbitDB(ipfs)

Choose this options if you're using orbitd-db to develop Desktop (or "headless") applications, eg. with Electron.

orbitdb

After creating an instance of orbitd-db, you can now access the different data stores.

kvstore(name)

Package: orbit-db-kvstore

const db = orbitdb.kvstore('application.settings')

• put(key, value)

  db.put('hello', { name: 'World' }).then(() => ...)
  

• set(key, value)

  db.set('hello', { name: 'Friend' }).then(() => ...)
  

• get(key)

  const value = db.get('hello')
  // { name: 'Friend' }
  

• events

  db.events.on('data', (dbname, event) => ... )
  

  See events for full description.

eventlog(name)

Package: orbit-db-eventlog

const db = orbitdb.eventlog('site.visitors')

• add(event)

  db.add({ name: 'User1' }).then((hash) => ...)
  

• get(hash)

  const event = db.get(hash)
    .map((e) => e.payload.value)
  // { name: 'User1' }
  

• iterator([options])

  // TODO: add all options - gt, gte, lt, lte, limit, reverse
  const all = db.iterator({ limit: -1 })
    .collect()
    .map((e) => e.payload.value)
  // [{ name: 'User1' }]
  

• events

  db.events.on('data', (dbname, event) => ... )
  

  See events for full description.

feed(name)

Package: orbit-db-feed

const db = orbitdb.feed('orbit-db.issues')

• add(data)

  db.add({ name: 'User1' }).then((hash) => ...)
  

• get(hash)

  const event = db.get(hash)
    .map((e) => e.payload.value)
  // { name: 'User1' }
  

• iterator([options])

  // TODO: add all options - gt, gte, lt, lte, limit, reverse
  const all = db.iterator({ limit: -1 })
    .collect()
    .map((e) => e.payload.value)
  // [{ name: 'User1' }]
  

• remove(hash)

  db.remove(hash).then((removed) => ...)
  

• events

  db.events.on('data', (dbname, event) => ... )
  

  See events for full description.

docstore(name, options)

Package: orbit-db-docstore

const db = orbitdb.docstore('orbit.users.shamb0t.profile')

By default, documents are indexed by field '_id'. You can also specify the field to index by:

const db = orbitdb.docstore('orbit.users.shamb0t.profile', { indexBy: 'name' })

• put(doc)

  db.put({ _id: 'QmAwesomeIpfsHash', name: 'shamb0t', followers: 500 }).then((hash) => ...)
  

• get(key)

  const profile = db.get('shamb0t')
    .map((e) => e.payload.value)
  // [{ _id: 'shamb0t', name: 'shamb0t', followers: 500 }]
  

• query(mapper)

  const all = db.query((doc) => doc.followers >= 500)
  // [{ _id: 'shamb0t', name: 'shamb0t', followers: 500 }]
  

• del(key)

  db.del('shamb0t').then((removed) => ...)
  

• events

  db.events.on('data', (dbname, event) => ... )
  

  See events for full description.

counter(name)

Package: orbit-db-counter

const counter = orbitdb.counter('song_123.play_count')

• value

  counter.value // 0
  

• inc([value])

  counter.inc()
  counter.value // 1
  counter.inc(7)
  counter.value // 8
  counter.inc(-2)
  counter.value // 8
  

• events

  db.events.on('data', (dbname, event) => ... )
  

  See events for full description.

disconnect()

orbitdb.disconnect()

events

• orbitdb

  • data - (dbname, event)

    Emitted when an update happens in any of the open databases.

    orbitdb.events.on('data', (dbname, event) => ...)
    

• stores

  Each database in orbit-db contains an events (EventEmitter) object that emits events that describe what's happening in the database.

  • data - (dbname, event)

    Emitted after an entry was added to the database

    db.events.on('data', (dbname, event) => ... )
    

  • sync - (dbname)

    Emitted before starting a database sync with a peer.

    db.events.on('sync', (dbname) => ... )
    

  • load - (dbname, hash)

    Emitted before loading the database history. hash is the hash from which the history is loaded from.

    db.events.on('load', (dbname, hash) => ... )
    

  • history - (dbname, entries)

    Emitted after loading the database history. entries is an Array of entries that were loaded.

    db.events.on('history', (dbname, entries) => ... )
    

  • ready - (dbname)

    Emitted after fully loading the database history.

    db.events.on('ready', (dbname) => ... )
    

  • write - (dbname, hash)

    Emitted after an entry was added locally to the database. hash is the IPFS hash of the latest state of the database.

    db.events.on('write', (dbname, hash) => ... )