orbitdb/API.md

orbit-db API documentation

OrbitDB provides various types of databases for different data models:

• log 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".
• keyvalue is a key-value database just like your favourite key-value database.
• docs 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.
• counter for counting. Useful for example counting events separate from log/feed data.

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

Usage

Read the GETTING STARTED guide for a more in-depth tutorial and to understand how OrbitDB works.

Using as a module

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()
ipfs.on('ready', () => {
  const orbitdb = new OrbitDB(ipfs)

  // Create / Open a database
  const db = await orbitdb.log('hello')
  await db.load()

  // Listen for updates from peers
  db.events.on('replicated', (address) => {
    console.log(db.iterator({ limit: -1 }).collect())
  })

  // Add an entry
  const hash = await db.add('world')
  console.log(hash)
  
  // Query
  const result = db.iterator({ limit: -1 }).collect()
  console.log(result)
})

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.

Using with a running IPFS daemon

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)
const db = await orbitdb.log('hello')
...

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 backend or desktop applications, eg. with Electron.

API

• OrbitDB
  • constructor(ipfs, [directory], [options])
  • keyvalue(name|address)
    • put(key, value)
    • set(key, value)
    • get(key)
  • log(name|address)
    • add(event)
    • get(hash)
    • iterator([options])
  • feed(name|address)
    • add(data)
    • get(hash)
    • remove(hash)
    • iterator([options])
  • docs(name|address, options)
    • put(doc)
    • get(hash)
    • query(mapper)
    • del(key)
  • counter(name|address)
    • value
    • inc([value])
  • stop()
• Store
  • load()
  • close()
  • drop()
  • events
  • key
  • type

OrbitDB

constructor(ipfs, [directory], [options])

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

const ipfs = new IPFS()
ipfs.on('ready', () => {
  const orbitdb = new OrbitDB(ipfs)
})

After creating an OrbitDB instance , you can access the different data stores. Creating a database instance, eg. with orbitdb.keyvalue(...), returns a Promise that resolves to a database instance. See the Store section for details of common methods and properties.

const db = await orbitdb.kvstore('profile')

keyvalue(name|address)

Module: orbit-db-kvstore

const db = await orbitdb.keyvalue('application.settings')
// Or:
const db = await orbitdb.keyvalue(anotherkvdb.address)

See the Store section for details of common methods and properties.

put(key, value)

await db.put('hello', { name: 'World' })

set(key, value)

await db.set('hello', { name: 'Friend' })

get(key)

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

log(name|address)

Module: orbit-db-eventstore

const db = await orbitdb.eventlog('site.visitors')
// Or:
const db = await orbitdb.eventlog(anotherlogdb.address)

See the Store section for details of common methods and properties.

add(event)

const hash = await db.add({ name: 'User1' })

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

feed(name|address)

Module: orbit-db-feedstore

const db = await orbitdb.feed('orbit-db.issues')
// Or:
const db = await orbitdb.feed(anotherfeeddb.address)

See the Store section for details of common methods and properties.

add(data)

const hash = await db.add({ name: 'User1' })

get(hash)

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

remove(hash)

const hash = await db.remove(hash)

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

docs(name|address, options)

Module: orbit-db-docstore

const db = await orbitdb.docs('orbit.users.shamb0t.profile')
// Or:
const db = await orbitdb.docs(anotherdocdb.address)

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

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

See the Store section for details of common methods and properties.

put(doc)

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

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)

const hash = await db.del('shamb0t')

counter(name|address)

Module: orbit-db-counterstore

const counter = await orbitdb.counter('song_123.play_count')
// Or:
const counter = await orbitdb.counter(anothercounterdb.address)

See the Store section for details of common methods and properties.

value

counter.value // 0

inc([value])

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

stop()

Stop OrbitDB, close databases and disconnect the databases from the network.

orbitdb.stop()

Store

Every database (store) has the following methods available in addition to their specific methods.

load()

Load the locally persisted database state to memory.

With events:

db.events.on('ready', () => {
  /* database is now ready to be queried */
})
db.load()

Async:

await db.load()
/* database is now ready to be queried */

close()

Close the database.

Async:

await db.close()

drop()

Remove the database locally. This does not delete any data from peers.

await db.drop()

key

The keypair used to access the database.

type

The type of the database as a string.

events

Each database in orbit-db contains an events (EventEmitter) object that emits events that describe what's happening in the database. Events can be listened to with:

db.events.on(name, callback)

• replicated - (address)

  Emitted when a the database was synced with another peer. This is usually a good place to re-query 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('replicated', (address) => ... )
  

• replicate - (address)

  Emitted before replicating a part of the database with a peer.

  db.events.on('replicate', (address) => ... )
  

• replicate.progress - (address, hash, entry, progress, have)

  Emitted while replicating a database. address is id 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 the current progress. have is a map of database pieces we have.

  db.events.on('replicate.progress', (address, hash, entry, progress, have) => ... )
  

• load - (dbname)

  Emitted before loading the database.

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

• load.progress - (address, hash, entry, progress, total)

  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', (address, hash, entry, progress, total) => ... )
  

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