orbit-db/API.md

orbit-db API documentation

WORK IN PROGRESS

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
  • 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)

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)

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)

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.

counter(name)

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) => ... )