orbitdb/API.md

OrbitDB API Documentation

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

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

const orbitdb = new OrbitDB(ipfs)

Creates and returns an instance of OrbitDB. Use the optional directory argument to specify a path to be used for the database files (Default: './orbitdb'). In addition, you can use the optional options argument for further configuration. It is an object with any of these properties:

• peerId (string): By default it uses the base58 string of the ipfs peer id.

• keystore (Keystore Instance) : By default creates an instance of Keystore. A custom keystore instance can be used, see this for an example.

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.

For further details, see usage for kvstore, eventlog, feed, docstore and counter.

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

Public OrbitDB Instance Methods

• orbitdb.create(name, type, [options])
• orbitdb.open(name|address, [options])
• orbitdb.disconnect()
• orbitdb.stop()
• orbitdb.keyvalue(name|address)
  • kv.put(key, value)
  • kv.set(key, value)
  • kv.get(key)
• orbitdb.log(name|address)
  • log.add(event)
  • log.get(hash)
  • log.iterator([options])
• orbitdb.feed(name|address)
  • feed.add(data)
  • feed.get(hash)
  • feed.remove(hash)
  • feed.iterator([options])
• orbitdb.docs(name|address, options)
  • docs.put(doc)
  • docs.get(hash)
  • docs.query(mapper)
  • del(key)
• orbitdb.counter(name|address)
  • counter.value
  • counter.inc([value])

Static Properties

• OrbitDB.databaseTypes

Static Methods

• OrbitDB.isValidType(type)
• OrbitDB.addDatabaseType(type, store)
• OrbitDB.getDatabaseTypes()
• OrbitDB.isValidAddress(address)
• OrbitDB.parseAddress(address)

Store API

• store.load()
• store.close()
• store.drop()
• store.key
• store.type

Store Events

• replicated
• replicate
• replicate.progress
• load
• load.progress
• ready
• write

Public Instance Methods

orbitdb.create(name, type, [options])

Creates and opens an OrbitDB database.

Returns a Promise that resolves to a database instance. name (string) should be the database name, not an OrbitDB address (i.e. user.posts). type is a supported database type (i.e. eventlog or an added custom type). options is an object with any of the following properties:

• directory (string): The directory where data will be stored (Default: uses directory option passed to OrbitDB constructor or ./orbitdb if none was provided).
• write (array): An array of hex encoded public keys which are used to set write acces to the database. ["*"] can be passed in to give write access to everyone. See the GETTING STARTED guide for more info. (Default: uses the OrbitDB instance key orbitdb.key, which would give write access only to yourself)
• overwrite (boolean): Overwrite an existing database (Default: false)

const db = await orbitdb.create('user.posts', 'eventlog', {
  write: [
    // Give access to ourselves
    orbitdb.key.getPublic('hex'),
    // Give access to the second peer
    '042c07044e7ea51a489c02854db5e09f0191690dc59db0afd95328c9db614a2976e088cab7c86d7e48183191258fc59dc699653508ce25bf0369d67f33d5d77839'
  ]
})
// db created & opened

orbitdb.open(address, [options])

Opens an OrbitDB database.

Convienance methods are available when opening/creating any of the default OrbitDB database types: feed, docs, log, keyvalue, counter

You can use: orbitdb.feed(address, options)

Instead of: orbitdb.open(address, { type: 'feed', ...options })

Returns a Promise that resolves to a database instance. address (string) should be a valid OrbitDB address. If a database name is provided instead, it will check options.create to determine if it should create the database. options is an object with any of the following properties:

• localOnly (boolean): If set to true, will throw an error if the database can't be found locally. (Default: false)
• directory (string): The directory where data will be stored (Default: uses directory option passed to OrbitDB constructor or ./orbitdb if none was provided).
• create (boolean): Whether or not to create the database if a valid OrbitDB address is not provided. (Default: false)
• type (string): A supported database type (i.e. eventlog or an added custom type). Required if create is set to true. Otherwise it's used to validate the manifest.
• overwrite (boolean): Overwrite an existing database (Default: false)

const db = await orbitdb.open('/orbitdb/Qmd8TmZrWASypEp4Er9tgWP4kCNQnW4ncSnvjvyHQ3EVSU/first-database')

orbitdb.disconnect()

Close databases, connections, pubsub and reset orbitdb state.

await orbitdb.disconnect()

orbitdb.stop()

Alias for orbitdb.disconnect()

await orbitdb.stop()

orbitdb.keyvalue(name|address)

Creates and opens a keyvalue database

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

set() is an alias of put(). They both work the same.

get(key)

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

orbitdb.log(name|address)

Creates and opens an eventlog database

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, takes an item's hash.

gte - (string) Greater than or equal to, takes an item's hash.

lt - (string) Less than, takes an item's hash.

lte - (string) Less than or equal to, takes an item's hash value.

limit - (integer) Limiting the entries of result, defaults to 1, and -1 means all items (no limit).

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

If hash not found when passing gt, gte, lt, or lte, the iterator will return all items (respecting limit and reverse).

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

orbitdb.feed(name|address)

Creates and opens a feed database

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, takes an item's hash.

gte - (string) Greater than or equal to, takes an item's hash.

lt - (string) Less than, takes an item's hash.

lte - (string) Less than or equal to, takes an item's hash.

limit - (integer) Limiting the entries of result, defaults to 1, and -1 means all items (no limit).

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

If hash not found when passing gt, gte, lt, or lte, the iterator will return all items (respecting limit and reverse).

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

orbitdb.docs(name|address, options)

Creates and opens a docstore database

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

orbitdb.counter(name|address)

Creates and opens a counter database

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

Static Properties

OrbitDB.databaseTypes

Returns supported database types (i.e. store types) as an Array of strings

OrbitDB.databaseTypes
// [ 'counter', 'eventlog', 'feed', 'docstore', 'keyvalue']

Static Methods

OrbitDB.isValidType(type)

Returns true if the provided string is a supported database type

OrbitDB.isValidType('docstore')
// true

OrbitDB.addDatabaseType(type, store)

Adds a custom database type & store to OrbitDB

const CustomStore = require('./CustomStore')
OrbitDB.addDatabaseType(CustomStore.type, CustomStore)

OrbitDB.getDatabaseTypes()

Returns an object mapping database types to Store Classes

OrbitDB.getDatabaseTypes()
// { counter: [Function: CounterStore],
//  eventlog: [Function: EventStore],
//  feed: [Function: FeedStore],
//  docstore: [Function: DocumentStore],
//  keyvalue: [Function: KeyValueStore] }

OrbitDB.isValidAddress(address)

Returns true if the provided string is a valid orbitdb address

OrbitDB.isValidAddress('/orbitdb/Qmdgwt7w4uBsw8LXduzCd18zfGXeTmBsiR8edQ1hSfzcJC/first-database')
// true

OrbitDB.parseAddress(address)

Returns an instance of OrbitDBAddress if the provided string is a valid orbitdb address

OrbitDB.parseAddress('/orbitdb/Qmdgwt7w4uBsw8LXduzCd18zfGXeTmBsiR8edQ1hSfzcJC/first-database')
// OrbitDBAddress {
//  root: 'Qmdgwt7w4uBsw8LXduzCd18zfGXeTmBsiR8edQ1hSfzcJC',
//  path: 'first-database' }

Store

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

store.load([amount])

Load the locally persisted database state to memory. Use the optional amount argument to limit the number of entries loaded into memory, starting from the head(s) (Default: -1 will load all entries)

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 */

store.close()

Close the database.

Async:

await db.close()

store.drop()

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

await db.drop()

store.key

The keypair used to access the database.

const key = db.key
console.log(key)
// <Key priv: db8ef129f3d26ac5d7c17b402027488a8f4b2e7fa855c27d680b714cf9c1f87e
// pub: <EC Point x: f0e33d60f9824ce10b2c8983d3da0311933e82cf5ec9374cd82c0af699cbde5b
// y: ce206bfccf889465c6g6f9a7fdf452f9c3e1204a6f1b4582ec427ec12b116de9> >

The key contains the keypair used to sign the database entries. The public key can be retrieved with:

console.log(db.key.getPublic('hex'))
// 04d009bd530f2fa0cda29202e1b15e97247893cb1e88601968abfe787f7ea03828fdb7624a618fd67c4c437ad7f48e670cc5a6ea2340b896e42b0c8a3e4d54aebe

The key can also be accessed from the OrbitDB instance: orbitdb.key.getPublic('hex').

store.type

The type of the database as a string.

Store 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

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

Emitted when the database has 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.

replicate

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

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

replicate.progress

db.events.on('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.

load

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

Emitted before loading the database.

load.progress

db.events.on('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().

ready

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

Emitted after fully loading the local database.

write

db.events.on('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.