docs: Add a README home page to API.

This commit is contained in:
Hayden Young 2023-06-25 00:18:39 +01:00
parent 0205ee3a95
commit bba53d730a
3 changed files with 58 additions and 50 deletions

View File

@ -1,4 +1,58 @@
# OrbitDB
OrbitDB is a serverless, distributed, peer-to-peer database. OrbitDB uses IPFS
as its data storage and Libp2p Pubsub to automatically sync databases with peers. It's an eventually consistent database that uses Merkle-CRDTs for conflict-free database writes and merges making OrbitDB an excellent choice for p2p and decentralized apps, blockchain applications and local first web applications.
## Getting Started
To install OrbitDB:
```bash
npm install orbit-db
```
IPFS is also required:
```bash
npm install ipfs-core
```
Instantiate OrbitDB and open a new database:
```js
import { create } from 'ipfs-core'
import { OrbitDB } from 'orbit-db'
const ipfs = await create() // IPFS is required for storage and syncing
const orbitdb = await OrbitDB({ ipfs })
const mydb = await orbitdb.open('mydb')
const dbAddress = mydb.address // E.g. /orbitdb/zdpuAuK3BHpS7NvMBivynypqciYCuy2UW77XYBPUYRnLjnw13
@example <caption>Open an existing database using its multiformat address:</caption>
const mydb = await orbitdb.open(dbAddress)
```
Use with pre-configured identities:
```js
import { create } from 'ipfs-core'
import { OrbitDB, Identities } from 'orbit-db'
import CustomStorage from './custom-storage.js'
const storage = await CustomStorage()
const identities = await Identities({ storage })
const ipfs = await create() // IPFS is required for storage and syncing
const orbitdb = await OrbitDB({ ipfs, identities })
const mydb = await orbitdb.open('mydb')
```
Use with existing identities:
```js
import { create } from 'ipfs-core'
import { OrbitDB, Identities } from 'orbit-db'
const identities = await Identities()
await identities.createIdentity('userA')
const ipfs = await create() // IPFS is required for storage and syncing
const orbitdb = await OrbitDB({ ipfs, identities, id: 'userA' })
const mydb = await orbitdb.open('mydb')
```
See the [OrbitDB module](./module-OrbitDB.html) for more information about how to open databases.

View File

@ -62,7 +62,7 @@
"build:examples": "webpack --config conf/webpack.example.config.js",
"build:dist": "webpack --config conf/webpack.config.js",
"build:debug": "webpack --config conf/webpack.debug.config.js",
"build:docs": "jsdoc -c ./conf/jsdoc/jsdoc.json -r src/** -d ./docs/api",
"build:docs": "jsdoc -c ./conf/jsdoc/jsdoc.json -r src/** -d ./docs/api -R ./docs/api/README.md",
"build:tests": "rm -f test/browser/bundle.js* && webpack --config ./conf/webpack.tests.config.js",
"prepublishOnly": "npm run build",
"lint": "standard --env=mocha",

View File

@ -1,52 +1,6 @@
/**
* @module OrbitDB
* @description
* OrbitDB is a serverless, distributed, peer-to-peer database. OrbitDB uses
* IPFS as its data storage and Libp2p Pubsub to automatically sync databases
* with peers. It's an eventually consistent database that uses Merkle-CRDTs
* for conflict-free database writes and merges making OrbitDB an excellent
* choice for p2p and decentralized apps, blockchain applications and local
* first web applications.
*
* To install OrbitDB:
* ```bash
* npm install orbit-db
* ```
*
* IPFS is also required:
* ```bash
* npm install ipfs-core
* ```
* @example <caption>Instantiate OrbitDB and open a new database:</caption>
* import { create } from 'ipfs-core'
* import { OrbitDB } from 'orbit-db'
*
* const ipfs = await create() // IPFS is required for storage and syncing
* const orbitdb = await OrbitDB({ ipfs })
* const mydb = await orbitdb.open('mydb')
* const dbAddress = mydb.address // E.g. /orbitdb/zdpuAuK3BHpS7NvMBivynypqciYCuy2UW77XYBPUYRnLjnw13
* @example <caption>Open an existing database using its multiformat address:</caption>
* const mydb = await orbitdb.open(dbAddress)
* @example <caption>Use with pre-configured identities:</caption>
* import { create } from 'ipfs-core'
* import { OrbitDB, Identities } from 'orbit-db'
* import CustomStorage from './custom-storage.js'
*
* const storage = await CustomStorage()
* const identities = await Identities({ storage })
* const ipfs = await create() // IPFS is required for storage and syncing
* const orbitdb = await OrbitDB({ ipfs, identities })
* const mydb = await orbitdb.open('mydb')
* @example <caption>Use with existing identities:</caption>
* import { create } from 'ipfs-core'
* import { OrbitDB, Identities } from 'orbit-db'
*
* const identities = await Identities()
* await identities.createIdentity('userA')
*
* const ipfs = await create() // IPFS is required for storage and syncing
* const orbitdb = await OrbitDB({ ipfs, identities, id: 'userA' })
* const mydb = await orbitdb.open('mydb')
* @description Provides an interface for users to interact with OrbitDB.
*/
import { getDatabaseType } from './db/index.js'
import KeyStore from './key-store.js'