From 2c037a5236ecce9ee4ac8c1a90676fd16bf12550 Mon Sep 17 00:00:00 2001 From: Kia Rahimian Date: Thu, 12 Jul 2018 15:07:30 -0400 Subject: [PATCH] docs: refractor --- API.md | 210 ++++++++++++++++--------------------------------- GUIDE.md | 26 +++--- README.md | 230 +++++++++++++++++++++++++++++++++++------------------- 3 files changed, 229 insertions(+), 237 deletions(-) diff --git a/API.md b/API.md index c777f6b..5b12ca1 100644 --- a/API.md +++ b/API.md @@ -1,138 +1,16 @@ -# orbit-db API documentation - -OrbitDB provides various types of databases for different data models: -- [log](#lognameaddress) is an append-only log with traversable history. Useful for *"latest N"* use cases or as a message queue. -- [feed](#feednameaddress) 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](#keyvaluenameaddress) is a key-value database just like your favourite key-value database. -- [docs](#docsnameaddress-options) 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](#counternameaddress) 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 +# OrbitDB API Documentation Read the **[GETTING STARTED](https://github.com/orbitdb/orbit-db/blob/master/GUIDE.md)** guide for a more in-depth tutorial and to understand how OrbitDB works. -### Using as a module - -Install [orbit-db](https://www.npmjs.com/package/orbit-db) and [ipfs](https://www.npmjs.com/package/ipfs) from npm: - -``` -npm install orbit-db ipfs -``` - -Require it in your program and create the instance: - -```javascript -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](#orbitdb) instance we can use to interact with the databases. - -This will tell `orbit-db` to use the [Javascript implementation](https://github.com/ipfs/js-ipfs) 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](https://npmjs.org/package/ipfs-api) to use `orbit-db` with a locally running IPFS daemon: - -``` -npm install orbit-db ipfs-api -``` - -```javascript -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](#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](https://electron.atom.io). - - -## API - -- [OrbitDB](#orbitdb) - - [constructor(ipfs, [directory], [options])](#constructoripfs-directory-options) - - **Public Methods** - - [keyvalue(name|address)](#keyvaluenameaddress) - - [put(key, value)](#putkey-value) - - [set(key, value)](#setkey-value) - - [get(key)](#getkey) - - [log(name|address)](#lognameaddress) - - [add(event)](#addevent) - - [get(hash)](#gethash) - - [iterator([options])](#iteratoroptions) - - [feed(name|address)](#feednameaddress) - - [add(data)](#adddata) - - [get(hash)](#gethash-1) - - [remove(hash)](#removehash) - - [iterator([options])](#iteratoroptions) - - [docs(name|address, options)](#docsnameaddress-options) - - [put(doc)](#putdoc) - - [get(hash)](#getkey-1) - - [query(mapper)](#querymapper) - - [del(key)](#delkey) - - [counter(name|address)](#counternameaddress) - - [value](#value) - - [inc([value])](#incvalue) - - [create(name|address, type, [options])]() - - [stop()](#stop) - - **Static Properties** - - [databaseTypes](#databasetypes) - - **Static Methods** - - [isValidType(type)](#isvalidtypetype) - - [addDatabaseType(type, store)](#adddatabasetypetype-store) - - [getDatabaseTypes()](#getdatabasetypes) - - [isValidAddress(address)](#isvalidaddressaddress) - - [parseAddress(address)](#parseaddressaddress) -- [Store](#store) - - [load()](#load) - - [close()](#close) - - [drop()](#drop) - - [events](#events) - - [key](#key) - - [type](#type) - -## OrbitDB - ### constructor(ipfs, [directory], [options]) - ```javascript -const IPFS = require('ipfs') -const OrbitDB = require('orbit-db') - -const ipfs = new IPFS() -ipfs.on('ready', () => { - const orbitdb = new OrbitDB(ipfs) -}) +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](https://github.com/orbitdb/orbit-db-keystore). A custom keystore instance can be used, see [this](https://github.com/orbitdb/orbit-db/blob/master/test/utils/custom-test-keystore.js) 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](#store). See the [Store](#store) section for details of common methods and properties. @@ -140,8 +18,52 @@ After creating an `OrbitDB` instance , you can access the different data stores. const db = await orbitdb.keyvalue('profile') ``` -### **Public Methods** -### keyvalue(name|address) +- **Public OrbitDB Instance Methods** + - [orbitdb.keyvalue(name|address)](#keyvaluenameaddress) + - [kv.put(key, value)](#putkey-value) + - [kv.set(key, value)](#setkey-value) + - [kv.get(key)](#getkey) + - [orbitdb.log(name|address)](#lognameaddress) + - [log.add(event)](#addevent) + - [log.get(hash)](#gethash) + - [log.iterator([options])](#iteratoroptions) + - [orbitdb.feed(name|address)](#feednameaddress) + - [feed.add(data)](#adddata) + - [feed.get(hash)](#gethash-1) + - [feed.remove(hash)](#removehash) + - [feed.iterator([options])](#iteratoroptions) + - [orbitdb.docs(name|address, options)](#docsnameaddress-options) + - [docs.put(doc)](#putdoc) + - [docs.get(hash)](#getkey-1) + - [docs.query(mapper)](#querymapper) + - [del(key)](#delkey) + - [orbitdb.counter(name|address)](#counternameaddress) + - [counter.value](#value) + - [counter.inc([value])](#incvalue) + - [orbitdb.create(name|address, type, [options])]() + - [orbitdb.open(name|address, [options])]() + - [orbitdb.stop()](#stop) + - [orbitdb.disconnect()]() +- **Static Properties** + - [OrbitDB.databaseTypes](#databasetypes) +- **Static Methods** + - [OrbitDB.isValidType(type)](#isvalidtypetype) + - [OrbitDB.addDatabaseType(type, store)](#adddatabasetypetype-store) + - [OrbitDB.getDatabaseTypes()](#getdatabasetypes) + - [OrbitDB.isValidAddress(address)](#isvalidaddressaddress) + - [OrbitDB.parseAddress(address)](#parseaddressaddress) + +- [Store API](#store) + - [store.load()](#load) + - [store.close()](#close) + - [store.drop()](#drop) + - [store.events](#events) + - [store.key](#key) + - [store.type](#type) + + +## Public Instance Methods +### orbitdb.keyvalue(name|address) Module: [orbit-db-kvstore](https://github.com/orbitdb/orbit-db-kvstore) @@ -171,7 +93,7 @@ const db = await orbitdb.keyvalue(anotherkvdb.address) // { name: 'Friend' } ``` -### log(name|address) +### orbitdb.log(name|address) Module: [orbit-db-eventstore](https://github.com/orbitdb/orbit-db-eventstore) @@ -220,7 +142,7 @@ const all = db.iterator({ limit: -1 }) // [{ name: 'User1' }] ``` -### feed(name|address) +### orbitdb.feed(name|address) Module: [orbit-db-feedstore](https://github.com/orbitdb/orbit-db-feedstore) @@ -274,7 +196,7 @@ const all = db.iterator({ limit: -1 }) // [{ name: 'User1' }] ``` -### docs(name|address, options) +### orbitdb.docs(name|address, options) Module: [orbit-db-docstore](https://github.com/orbitdb/orbit-db-docstore) @@ -315,7 +237,7 @@ const db = await orbitdb.docs('orbit.users.shamb0t.profile', { indexBy: 'name' } const hash = await db.del('shamb0t') ``` -### counter(name|address) +### orbitdb.counter(name|address) Module: [orbit-db-counterstore](https://github.com/orbitdb/orbit-db-counterstore) @@ -342,38 +264,38 @@ const counter = await orbitdb.counter(anothercounterdb.address) counter.value // 8 ``` -### stop() +### orbitdb.stop() Stop OrbitDB, close databases and disconnect the databases from the network. ```javascript orbitdb.stop() ``` -### **Static Properties** -### databaseTypes +## Static Properties +### OrbitDB.databaseTypes Returns supported database types (i.e. store types) as an Array of strings ```js OrbitDB.databaseTypes // [ 'counter', 'eventlog', 'feed', 'docstore', 'keyvalue'] ``` -### **Static Methods** +## Static Methods -### isValidType(type) +### OrbitDB.isValidType(type) Returns `true` if the provided string is a supported database type ```js OrbitDB.isValidType('docstore') // true ``` -### addDatabaseType(type, store) +### OrbitDB.addDatabaseType(type, store) Adds a custom database type & store to OrbitDB ```js const CustomStore = require('./CustomStore') OrbitDB.addDatabaseType(CustomStore.type, CustomStore) ``` -### getDatabaseTypes() +### OrbitDB.getDatabaseTypes() Returns an object mapping database types to Store Classes ```js OrbitDB.getDatabaseTypes() @@ -383,13 +305,13 @@ OrbitDB.getDatabaseTypes() // docstore: [Function: DocumentStore], // keyvalue: [Function: KeyValueStore] } ``` -### isValidAddress(address) +### OrbitDB.isValidAddress(address) Returns `true` if the provided string is a valid orbitdb address ```js OrbitDB.isValidAddress('/orbitdb/Qmdgwt7w4uBsw8LXduzCd18zfGXeTmBsiR8edQ1hSfzcJC/first-database') // true ``` -### parseAddress(address) +### OrbitDB.parseAddress(address) Returns an instance of OrbitDBAddress if the provided string is a valid orbitdb address ```js OrbitDB.parseAddress('/orbitdb/Qmdgwt7w4uBsw8LXduzCd18zfGXeTmBsiR8edQ1hSfzcJC/first-database') diff --git a/GUIDE.md b/GUIDE.md index 81081b9..2ee017f 100644 --- a/GUIDE.md +++ b/GUIDE.md @@ -1,6 +1,6 @@ # Getting Started with OrbitDB -This guide will get you familiar using OrbitDB in your JavaScript application. OrbitDB and IPFS both work in Node.js applications as well as in browser applications. +This guide will get you familiar with using OrbitDB in your JavaScript application. OrbitDB and IPFS both work in Node.js applications as well as in browser applications. (Windows is not supported yet though) This guide is still being worked on and we would love to get [feedback and suggestions](https://github.com/orbitdb/orbit-db/issues) on how to improve it! @@ -26,7 +26,7 @@ OrbitDB is a peer-to-peer database meaning that each peer has its own instance o This means that each application contains the full database that they're using. This in turn changes the data modeling as compared to client-server model where there's usually one big database for all entries: in OrbitDB, the data should be stored, "partitioned" or "sharded" based on the access rights for that data. For example, in a twitter-like application, tweets would not be saved in a global "tweets" database to which millions of users write concurrently, but rather, ***each user would have their own database*** for their tweets. To follow a user, a peer would subscribe to a user's feed, ie. replicate their feed database. -OrbitDB supports multiple data models (see more details below) and as such the developer has a variety ways to structure data. Combined with the peer-to-peer paradigm, the data modeling is important factor to build scalable decentralized applications. +OrbitDB supports multiple data models (see more details below) and as such the developer has a variety of ways to structure data. Combined with the peer-to-peer paradigm, the data modeling is important factor to build scalable decentralized applications. This may not be intuitive or you might not be sure what the best approach would be and we'd be happy to help you decide on your data modeling and application needs, [feel free to reach out](https://github.com/orbitdb/orbit-db/issues)! @@ -47,13 +47,13 @@ const IPFS = require('ipfs') const OrbitDB = require('orbit-db') // OrbitDB uses Pubsub which is an experimental feature -// and need to be turned on manually. -// Note that these options need to be passed to IPFS in +// and need to be turned on manually. +// Note that these options need to be passed to IPFS in // all examples in this document even if not specfied so. const ipfsOptions = { EXPERIMENTAL: { pubsub: true - }, + } } // Create IPFS instance @@ -69,7 +69,7 @@ ipfs.on('ready', () => { ## Create a database -First, choose the data model you want to use. The available data models are: +First, choose the data model you want to use. The available data models are: - [Key-Value](https://github.com/orbitdb/orbit-db/blob/master/API.md##keyvaluenameaddress) - [Log](https://github.com/orbitdb/orbit-db/blob/master/API.md#lognameaddress) (append-only log) - [Feed](https://github.com/orbitdb/orbit-db/blob/master/API.md#feednameaddress) (same as log database but entries can be removed) @@ -116,7 +116,7 @@ ipfs.on('ready', async () => { #### Manifest -The second part of the address, the IPFS multihash `Qmdgwt7w4uBsw8LXduzCd18zfGXeTmBsiR8edQ1hSfzcJC`, is the manifest of a database. It's an IPFS object that contains information about the database. +The second part of the address, the IPFS multihash `Qmdgwt7w4uBsw8LXduzCd18zfGXeTmBsiR8edQ1hSfzcJC`, is the manifest of a database. It's an IPFS object that contains information about the database. The database manifest can be fetched from IPFS and it looks like this: @@ -136,8 +136,8 @@ Each entry in a database is signed by who created that entry. The signing key, t ``` const key = db.key console.log(key) -// > ``` @@ -175,9 +175,9 @@ ipfs.on('ready', async () => { }) ``` -To give write access to another peer, you'll need to get their public key with some means. They'll need to give you the output of their OrbitDB instance's key: `orbitdb.key.getPublic('hex')`. +To give write access to another peer, you'll need to get their public key with some means. They'll need to give you the output of their OrbitDB instance's key: `orbitdb.key.getPublic('hex')`. -The keys look like this: +The keys look like this: `042c07044e7ea51a489c02854db5e09f0191690dc59db0afd95328c9db614a2976e088cab7c86d7e48183191258fc59dc699653508ce25bf0369d67f33d5d77839` Give access to another peer to write to the database: @@ -207,7 +207,7 @@ ipfs.on('ready', async () => { #### Public databases -The access control mechanism also support "public" databases to which anyone can write to. +The access control mechanism also support "public" databases to which anyone can write to. This can be done by adding a `*` to the write access array: ```javascript @@ -247,7 +247,7 @@ For adding entries to other databases, see: - [docs.put()](https://github.com/orbitdb/orbit-db/blob/master/API.md#putdoc) - [counter.inc()](https://github.com/orbitdb/orbit-db/blob/master/API.md#incvalue) -**Parallelism** +**Parallelism** We currently don't support parallel updates. Updates to a database need to be executed in a sequential manner. The write throughput is several hundreds or thousands of writes per second (depending on your platform and hardware, YMMV), so this shouldn't slow down your app too much. If it does, [lets us know](https://github.com/orbitdb/orbit-db/issues)! diff --git a/README.md b/README.md index 2a95449..f304fae 100644 --- a/README.md +++ b/README.md @@ -10,30 +10,31 @@ OrbitDB is a serverless, distributed, peer-to-peer database. OrbitDB uses [IPFS](https://ipfs.io) as its data storage and [IPFS Pubsub](https://github.com/ipfs/go-ipfs/blob/master/core/commands/pubsub.go#L23) to automatically sync databases with peers. It's an eventually consistent database that uses [CRDTs](https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type) for conflict-free database merges making OrbitDB an excellent choice for decentralized apps (dApps), blockchain applications and offline-first web applications. -Data in OrbitDB can be stored in a +OrbitDB provides various types of databases for different data models and use cases: -- **[Key-Value Store](https://github.com/orbitdb/orbit-db/blob/master/API.md#keyvaluenameaddress)** -- **[Log Database](https://github.com/orbitdb/orbit-db/blob/master/API.md#lognameaddress)** (append-only log) -- **[Feed](https://github.com/orbitdb/orbit-db/blob/master/API.md#feednameaddress)** (same as log database but entries can be removed) -- **[Document Store](https://github.com/orbitdb/orbit-db/blob/master/API.md#docsnameaddress-options)** (store indexed JSON documents) -- **[Counters](https://github.com/orbitdb/orbit-db/blob/master/API.md#counternameaddress)** +- [log](#lognameaddress) is an append-only log with traversable history. Useful for *"latest N"* use cases or as a message queue. +- [feed](#feednameaddress) 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](#keyvaluenameaddress) is a key-value database just like your favourite key-value database. +- [docs](#docsnameaddress-options) 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](#counternameaddress) for counting. Useful for example counting events separate from log/feed data. -This is the Javascript implementation and it works both in **Node.js** and **Browsers**. +#### Project status & support +This is the Javascript implementation and it works both in **Browsers** and **Node.js** with support for Linux and OS X (Windows is not supported yet). *The minimum required version of Node.js is now 8.0.0. To use with older versions of Node.js, we provide an ES5-compatible build through the npm package, located in `dist/es5/` when installed through npm.* + +### Getting Started To get started, try the **[OrbitDB CLI](https://github.com/orbitdb/orbit-db-cli)**, read the **[Getting Started Guide](https://github.com/orbitdb/orbit-db/blob/master/GUIDE.md)** or check **[Live demo 1](https://ipfs.io/ipfs/QmeESXh9wPib8Xz7hdRzHuYLDuEUgkYTSuujZ2phQfvznQ/)**, **[Live demo 2](https://ipfs.io/ipfs/QmasHFRj6unJ3nSmtPn97tWDaQWEZw3W9Eh3gUgZktuZDZ/)** or **[P2P TodoMVC app](https://ipfs.io/ipfs/QmTJGHccriUtq3qf3bvAQUcDUHnBbHNJG2x2FYwYUecN43/)**! -

- - -

- ## Table of Contents - [Usage](#usage) + - [CLI](#cli) + - [Module with IPFS Instance]() + - [Module with IPFS Daemon]() - [API](#api) - [Examples](#examples) +- [Packages](#packages) - [Development](#development) -- [Background](#background) - [Contributing](#contributing) - [License](#license) @@ -41,7 +42,7 @@ To get started, try the **[OrbitDB CLI](https://github.com/orbitdb/orbit-db-cli) Read the **[GETTING STARTED](https://github.com/orbitdb/orbit-db/blob/master/GUIDE.md)** guide for a more in-depth tutorial and to understand how OrbitDB works. -OrbitDB currently supports Linux and OS X, Windows is not supported yet. +*For further details, see usage for [kvstore](https://github.com/orbitdb/orbit-db-kvstore#usage), [eventlog](https://github.com/haadcode/orbit-db-eventstore#usage), [feed](https://github.com/haadcode/orbit-db-feedstore#usage), [docstore](https://github.com/shamb0t/orbit-db-docstore#usage) and [counter](https://github.com/haadcode/orbit-db-counterstore#usage).* ### CLI @@ -53,7 +54,9 @@ It can be installed from Npm with: npm install orbit-db-cli -g ``` -### As a library +### Module with IPFS Instance + +If you're using `orbitd-db` to develop **browser** applications, use it as a module with the javascript instance of IPFS Install dependencies: @@ -61,20 +64,18 @@ Install dependencies: npm install orbit-db ipfs ``` -Use it as a module: - ```javascript const IPFS = require('ipfs') const OrbitDB = require('orbit-db') // OrbitDB uses Pubsub which is an experimental feature // and need to be turned on manually. -// Note that these options need to be passed to IPFS in +// Note that these options need to be passed to IPFS in // all examples even if not specfied so. const ipfsOptions = { EXPERIMENTAL: { pubsub: true - }, + } } // Create IPFS instance @@ -82,33 +83,127 @@ const ipfs = new IPFS(ipfsOptions) ipfs.on('error', (e) => console.error(e)) ipfs.on('ready', async () => { - // Create a database const orbitdb = new OrbitDB(ipfs) - const db = await orbitdb.log('database name') - // Add an entry to the database - const hash = await db.add('hello world') - // Get last 5 entries - const latest = db.iterator({ limit: 5 }).collect() - console.log(JSON.stringify(latest, null, 2)) + + // 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(JSON.stringify(result, null, 2)) }) ``` -*For more details, see examples for [kvstore](https://github.com/orbitdb/orbit-db-kvstore#usage), [eventlog](https://github.com/haadcode/orbit-db-eventstore#usage), [feed](https://github.com/haadcode/orbit-db-feedstore#usage), [docstore](https://github.com/shamb0t/orbit-db-docstore#usage) and [counter](https://github.com/haadcode/orbit-db-counterstore#usage).* +### Module with IPFS Daemon +Alternatively, you can use [ipfs-api](https://npmjs.org/package/ipfs-api) to use `orbit-db` with a locally running IPFS daemon. Use this method if you're using `orbitd-db` to develop **backend** or **desktop** applications, eg. with [Electron](https://electron.atom.io). -*The minimum required version of Node.js is now 8.0.0. To use with older versions of Node.js, we provide an ES5-compatible build through the npm package, located in `dist/es5/` when installed through npm.* +Install dependencies: + +``` +npm install orbit-db ipfs-api +``` + +```javascript +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') +... +``` ## API -See [API documentation](https://github.com/orbitdb/orbit-db/blob/master/API.md#orbit-db-api-documentation) for the full documentation. +See [API documentation](https://github.com/orbitdb/orbit-db/blob/master/API.md) for the full documentation. -- [Getting Started](https://github.com/orbitdb/orbit-db/blob/master/API.md#getting-started) -- [OrbitDB](https://github.com/orbitdb/orbit-db/blob/master/API.md#orbitdb) - - [keyvalue](https://github.com/orbitdb/orbit-db/blob/master/API.md#keyvaluenameaddress) - - [log](https://github.com/orbitdb/orbit-db/blob/master/API.md#lognameaddress) - - [feed](https://github.com/orbitdb/orbit-db/blob/master/API.md#feednameaddress) - - [docstore](https://github.com/orbitdb/orbit-db/blob/master/API.md#docsnameaddress-options) - - [counter](https://github.com/orbitdb/orbit-db/blob/master/API.md#counternameaddress) - - [common](https://github.com/orbitdb/orbit-db/blob/master/API.md#store) +### constructor(ipfs, [directory], [options]) +```javascript +OBconst 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](https://github.com/orbitdb/orbit-db-keystore). A custom keystore instance can be used, see [this](https://github.com/orbitdb/orbit-db/blob/master/test/utils/custom-test-keystore.js) for an example. + +- **Public OrbitDB Instance Methods** + - [orbitdb.keyvalue(name|address)](#keyvaluenameaddress) + - [kv.put(key, value)](#putkey-value) + - [kv.set(key, value)](#setkey-value) + - [kv.get(key)](#getkey) + - [orbitdb.log(name|address)](#lognameaddress) + - [log.add(event)](#addevent) + - [log.get(hash)](#gethash) + - [log.iterator([options])](#iteratoroptions) + - [orbitdb.feed(name|address)](#feednameaddress) + - [feed.add(data)](#adddata) + - [feed.get(hash)](#gethash-1) + - [feed.remove(hash)](#removehash) + - [feed.iterator([options])](#iteratoroptions) + - [orbitdb.docs(name|address, options)](#docsnameaddress-options) + - [docs.put(doc)](#putdoc) + - [docs.get(hash)](#getkey-1) + - [docs.query(mapper)](#querymapper) + - [del(key)](#delkey) + - [orbitdb.counter(name|address)](#counternameaddress) + - [counter.value](#value) + - [counter.inc([value])](#incvalue) + - [orbitdb.create(name|address, type, [options])]() + - [orbitdb.open(name|address, [options])]() + - [orbitdb.stop()](#stop) + - [orbitdb.disconnect()]() +- **Static Properties** + - [OrbitDB.databaseTypes](#databasetypes) +- **Static Methods** + - [OrbitDB.isValidType(type)](#isvalidtypetype) + - [OrbitDB.addDatabaseType(type, store)](#adddatabasetypetype-store) + - [OrbitDB.getDatabaseTypes()](#getdatabasetypes) + - [OrbitDB.isValidAddress(address)](#isvalidaddressaddress) + - [OrbitDB.parseAddress(address)](#parseaddressaddress) + +- [Store API](#store) + - [load()](#load) + - [close()](#close) + - [drop()](#drop) + - [events](#events) + - [key](#key) + - [type](#type) + +### Custom Store Types + +You can add custom store types to OrbitDB: + +```javascript +// define custom store type +class CustomStore extends DocumentStore { + constructor (ipfs, id, dbname, options) { + super(ipfs, id, dbname, options) + this._type = CustomStore.type + } + + static get type () { + return 'custom' + } +} + +// add custom type to orbitdb +OrbitDB.addDatabaseType(CustomStore.type, CustomStore) + +// instantiate custom store +let orbitdb = new OrbitDB(ipfs, dbPath) +let store = orbitdb.create(name, CustomStore.type) +``` ## Examples @@ -127,11 +222,11 @@ npm install --global babel-cli npm install --global webpack ``` -Some dependencies depend on native addon modules, so you'll also need to meet [node-gyp's](https://github.com/nodejs/node-gyp#installation) installation prerequisites. Therefore, Linux users may need to +Some dependencies depend on native addon modules, so you'll also need to meet [node-gyp's](https://github.com/nodejs/node-gyp#installation) installation prerequisites. Therefore, Linux users may need to ``` make clean && make ``` -to redo the local package-lock.json with working native dependencies. +to redo the local package-lock.json with working native dependencies. ### Browser example @@ -170,30 +265,25 @@ node examples/eventlog.js More examples at [examples](https://github.com/orbitdb/orbit-db/tree/master/examples). -### Custom Store Types +## Packages -You can add custom store types to OrbitDB: +OrbitDB uses the following modules: -```javascript -// define custom store type -class CustomStore extends DocumentStore { - constructor (ipfs, id, dbname, options) { - super(ipfs, id, dbname, options) - this._type = CustomStore.type - } +- [ipfs](https://github.com/ipfs/js-ipfs) +- [ipfs-log](https://github.com/orbitdb/ipfs-log) +- [ipfs-pubub-room](https://github.com/ipfs-shipyard/ipfs-pubsub-room) +- [crdts](https://github.com/orbitdb/crdts) +- [orbit-db-cache](https://github.com/orbitdb/orbit-db-cache) +- [orbit-db-store](https://github.com/orbitdb/orbit-db-store) +- [orbit-db-eventstore](https://github.com/orbitdb/orbit-db-eventstore) +- [orbit-db-feedstore](https://github.com/orbitdb/orbit-db-feedstore) +- [orbit-db-kvstore](https://github.com/orbitdb/orbit-db-kvstore) +- [orbit-db-docstore](https://github.com/orbitdb/orbit-db-docstore) +- [orbit-db-counterstore](https://github.com/orbitdb/orbit-db-counterstore) +- [orbit-db-pubsub](https://github.com/orbitdb/orbit-db-pubsub) +- [orbit-db-keystore](https://github.com/orbitdb/orbit-db-keystore) - static get type () { - return 'custom' - } -} - -// add custom type to orbitdb -OrbitDB.addDatabaseType(CustomStore.type, CustomStore) - -// instantiate custom store -let orbitdb = new OrbitDB(ipfs, dbPath) -let store = orbitdb.create(name, CustomStore.type) -``` +To understand a little bit about the architecture, check out a visualization of the data flow at https://github.com/haadcode/proto2 or a live demo: http://celebdil.benet.ai:8080/ipfs/Qmezm7g8mBpWyuPk6D84CNcfLKJwU6mpXuEN5GJZNkX3XK/. ## Development @@ -222,26 +312,6 @@ To enable OrbitDB's logging output, set a global ENV variable called `LOG` to `d LOG=debug node ``` -## Background - -Uses the following modules: - -- [ipfs-log](https://github.com/orbitdb/ipfs-log) -- [crdts](https://github.com/orbitdb/crdts) -- [orbit-db-cache](https://github.com/orbitdb/orbit-db-cache) -- [orbit-db-store](https://github.com/orbitdb/orbit-db-store) -- [orbit-db-eventstore](https://github.com/orbitdb/orbit-db-eventstore) -- [orbit-db-feedstore](https://github.com/orbitdb/orbit-db-feedstore) -- [orbit-db-kvstore](https://github.com/orbitdb/orbit-db-kvstore) -- [orbit-db-docstore](https://github.com/orbitdb/orbit-db-docstore) -- [orbit-db-counterstore](https://github.com/orbitdb/orbit-db-counterstore) -- [orbit-db-pubsub](https://github.com/orbitdb/orbit-db-pubsub) -- [orbit-db-keystore](https://github.com/orbitdb/orbit-db-keystore) -- [ipfs](https://github.com/ipfs/js-ipfs) -- [ipfs-pubub-room](https://github.com/ipfs-shipyard/ipfs-pubsub-room) - -To understand a little bit about the architecture, check out a visualization of the data flow at https://github.com/haadcode/proto2 or a live demo: http://celebdil.benet.ai:8080/ipfs/Qmezm7g8mBpWyuPk6D84CNcfLKJwU6mpXuEN5GJZNkX3XK/. - ## Contributing We would be happy to accept PRs! If you want to work on something, it'd be good to talk beforehand to make sure nobody else is working on it. You can reach us on IRC [#orbitdb](http://webchat.freenode.net/?channels=%23orbitdb) on Freenode, or in the comments of the [issues section](https://github.com/orbitdb/orbit-db/issues).