orbit-db/API.md

orbit-db API documentation

OrbitDB provides various types of databases for different data models:

• kvstore is a key-value database just like your favourite key-value database.
• eventlog is an append-only log with traversable history. Useful for "latest N" use cases or as a message queue.
• feed is a log with traversable history. Entries can be added and removed. Useful for *"shopping cart" type of use cases, or for example as a feed of blog posts or "tweets".
• counter for counting. Useful for example counting events separate from log/feed data.
• docstore is a document database to which documents can be stored and indexed by a specified key. Useful for example building search indices or version controlling documents and data.

Which database to use depends on your use case and data model.

Getting Started

Install orbit-db and ipfs from npm:

npm install orbit-db ipfs

Require it in your program and create the instance:

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

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

orbitdb is now the OrbitDB instance we can use to interact with the databases.

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)

orbitdb is now the OrbitDB instance we can use to interact with the databases.

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

Usage

• 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

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' }
  

• load()

  Load the locally persisted database state to memory.

  db.events.on('ready', () => {
    /* query */
  })
  db.load()
  

• events

  db.events.on('ready', () => /* local database loaded in memory */ )
  db.events.on('synced', () => /* query for updated results */ )
  

  See events for full description.

eventlog(name)

Package: orbit-db-eventstore

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

  options : It is an object which supports the following properties

  gt - (string) Greater than

  gte - (string) Greater than or equal to

  lt - (string) Less than

  lte - (string) Less than or equal to

  limit - (integer) Limiting the entries of result

  reverse - (boolean) If set to true will result in reversing the result.

  const all = db.iterator({ limit: -1 })
    .collect()
    .map((e) => e.payload.value)
  // [{ name: 'User1' }]
  

• load()

  Load the locally persisted database state to memory.

  db.events.on('ready', () => {
    /* query */
  })
  db.load()
  

• events

  db.events.on('ready', () => /* local database loaded in memory */ )
  db.events.on('synced', () => /* query for updated results */ )
  

  See events for full description.

feed(name)

Package: orbit-db-feedstore

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

  options : It is an object which supports the following properties

  gt - (string) Greater than

  gte - (string) Greater than or equal to

  lt - (string) Less than

  lte - (string) Less than or equal to

  limit - (integer) Limiting the entries of result

  reverse - (boolean) If set to true will result in reversing the result.

  const all = db.iterator({ limit: -1 })
    .collect()
    .map((e) => e.payload.value)
  // [{ name: 'User1' }]
  

• remove(hash)

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

• load()

  Load the locally persisted database state to memory.

  db.events.on('ready', () => {
    /* query */
  })
  db.load()
  

• events

  db.events.on('ready', () => /* local database loaded in memory */ )
  db.events.on('synced', () => /* query for updated results */ )
  

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

• load()

  Load the locally persisted database state to memory.

  db.events.on('ready', () => {
    /* query */
  })
  db.load()
  

• events

  db.events.on('ready', () => /* local database loaded in memory */ )
  db.events.on('synced', () => /* query for updated results */ )
  

  See events for full description.

counter(name)

Package: orbit-db-counterstore

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
  

• load()

  Load the locally persisted database state to memory.

  db.events.on('ready', () => {
    /* query */
  })
  db.load()
  

• events

  db.events.on('ready', () => /* local database loaded in memory */ )
  db.events.on('synced', () => /* query for updated results */ )
  

  See events for full description.

disconnect()

orbitdb.disconnect()

events

• stores

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

  • synced - (dbname)

    Emitted when an update happens in the databases. Eg. when the database was synchronized with a peer. This is usually a good place to requery the database for updated results, eg. if a value of a key was changed or if there are new events in an event log.

    db.events.on('synced', () => ... )
    

  • sync - (dbname)

    Emitted before starting a database sync with a peer.

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

  • load - (dbname)

    Emitted before loading the local database.

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

  • ready - (dbname)

    Emitted after fully loading the local database.

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

  • write - (dbname, hash, entry)

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

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

  • load.progress - (dbname, hash, entry, progress)

    Emitted while loading the local database, once for each entry. dbname is the name of the database that emitted the event. hash is the multihash of the entry that was just loaded. entry is the database operation entry. progress is a sequential number starting from 0 upon calling load().

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

  • error - (error)

    Emitted on an error.

    db.events.on('error', (err) => ... )