orbitdb/orbit-db
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
orbit-db/API.md
haad b4d4267e81 Fix typo in API docs
2016-11-02 14:27:27 +01:00

8.6 KiB
Raw Blame History

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

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

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

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

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