Pre release (#85)

* docs: Update README to match new version.

* docs: Update events example to use new API.

* docs: Correctly print out db query results.

* test: Remove concurrent.

* test: Remove unimplemented and 3rd party AC tests.

* test: Remove unimplemented and 3rd party identity tests.

* docs: Move jsdoc config to conf directory.

* Point package.json main at index.js to access all exported functions.

* docs: Vetted AC docs; these examples should work if implemented in code. Explicitly show orbit-db function imports.

* docs: Fix incorrectly declared write objects.

* docs: Improved canAppend documentation. Better JS syntax highlighting.

* docs: wss and define filters for localhost separately.

* docs: Simplified webSockets implementation with filters.

* docs: Return manifest json only (no hash). JS highlighting.

* docs: Remove operations documentation.

* docs: Update heading levels.

* docs: Differentiate between db types which expose put/add function.

* docs: Correctly import IPFS and pass config.

* docs: A simple method for full db replication.

* docs: Link to existing examples of db implementation.

* docs: Update heading.

* docs: JS code formatting. import statements.

* docs: Expand on the concepts of identities and identity management.

* docs: Describe head sync-ing and full replication.

* docs: Comprehensive explanation of setting up a db and sync-ing/replicating data across peers. Examples can be run in node.js.

* docs: Syntax highlighting. Correct code implementation for custom/3rd party storage implementations.

* docs: Getting started cleanup.

* docs: Manifest as an IPLD data strcture.

Author: haydenyoung

docs/ACCESS_CONTROLLERS.md

@@ -6,8 +6,17 @@ An access controller is passed when a database is opened for the first time. Onc
 
 Different access controllers can be assigned to the database using the `AccessController` param and passing it to OrbitDB's `open` function.
 
-```
-const orbitdb = await OrbitDB()
+```js
+import { create } from 'ipfs-core'
+import { OrbitDB, getAccessController } from 'orbit-db'
+
+const ipfs = create({ options })
+
+const orbitdb = await OrbitDB({ ipfs })
+
+// SomeAccessController must already be available in the AC list.
+const SomeAccessController = getAccessController('some-access-controller')
+
 const db = orbitdb.open('my-db', { AccessController: SomeAccessController() })
 ```
 
@@ -17,65 +26,99 @@ OrbitDB is bundled with two AccessControllers; IPFSAccessController, an immutabl
 
 By default, the database `db` will use the IPFSAccessController and allow only the creator to write to the database.
 
-```
-const orbitdb = await OrbitDB()
+```js
+const orbitdb = await OrbitDB({ ipfs })
 const db = orbitdb.open('my-db')
+
+await db.add('hello world') // only orbitdb.identity.id can write to the db.
 ```
 
-To change write access, pass the IPFSAccessController with the `write ` parameter and an array of one or more Identity ids:
+To change write access, pass the IPFSAccessController with the `write` parameter and an array of one or more Identity ids:
+
+```js
+import { create } from 'ipfs-core'
+import { OrbitDB, Identities, getAccessController } from 'orbit-db'
+
+const ipfs = create({ options })
 
-```
 const identities = await Identities()
-const identity1 = identities.createIdentity('userA')
-const identity2 = identities.createIdentity('userB')
+const anotherIdentity = identities.createIdentity('userB')
+
+// OrbitDB will create an identity using the id 'UserA'.
+const orbitdb = await OrbitDB({ ipfs, id: 'userA' })
+
+// Retrieve the access controller from the list of preloaded ACs.
+const IPFSAccessController = getAccessController('ipfs')
 
-const orbitdb = await OrbitDB()
-const db = orbitdb.open('my-db', { AccessController: IPFSAccessController(write: [identity1.id, identity2.id]) })
+// Open a db with write access for userA and userB.
+const db = orbitdb.open('my-db', { AccessController: IPFSAccessController({ write: [orbitdb.identity.id, anotherIdentity.id]) })
 ```
 
 To allow anyone to write to the database, specify the wildcard '*':
 
+```js
+import { create } from 'ipfs-core'
+import { OrbitDB, Identities, getAccessController } from 'orbit-db'
+
+const ipfs = create({ options })
+
+const orbitdb = await OrbitDB({ ipfs })
+
+const IPFSAccessController = getAccessController('ipfs')
+
+const db = orbitdb.open('my-db', { AccessController: IPFSAccessController({ write: ['*'] }) })
 ```
-const orbitdb = await OrbitDB()
-const db = orbitdb.open('my-db', { AccessController: IPFSAccessController(write: ['*']) })
-```
+
+**The access information cannot be changed after the initial setup (as it is immutable).** If different write access is needed, you will need to set up a new database and associated IPFSAccessController. It is important to note that this will change the address of the database.
 
 ## OrbitDB Access Controller
 
 The OrbitDB access controller provides configurable write access using grant and revoke.
 
-```
+```js
+import { create } from 'ipfs-core'
+import { OrbitDB, Identities, getAccessController } from 'orbit-db'
+
+const ipfs = create({ options })
+
+const orbitdb = await OrbitDB({ ipfs })
+
 const identities = await Identities()
-const identity1 = identities.createIdentity('userA')
-const identity2 = identities.createIdentity('userB')
+const anotherIdentity = identities.createIdentity('userB')
 
-const orbitdb = await OrbitDB()
-const db = orbitdb.open('my-db', { AccessController: OrbitDBAccessController(write: [identity1.id]) })
+// Retrieve the access controller from the list of preloaded ACs.
+const OrbitDBAccessController = getAccessController('orbitdb')
 
-db.access.grant('write', identity2.id)
-db.access.revoke('write', identity2.id)
+const db = orbitdb.open('my-db', { AccessController: OrbitDBAccessController({ write: [orbitdb.identity.id, anotherIdentity.id]) })
+
+db.access.grant('write', anotherIdentity.id)
+db.access.revoke('write', anotherIdentity.id)
 ```
 
 When granting or revoking access, a capability and the identity's id must be defined.
 
 Grant and revoke are not limited to 'write' access only. A custom access capability can be specified, for example, `db.access.grant('custom-access', identity1.id)`.
 
+The OrbitDBAccessController is a mutable access controller. Granting and revoking access does not change the address of the database.
+
 ## Custom Access Controller
 
 Access can be customized by implementing a custom access controller. To implement a custom access controller, specify:
 
-- A curried function with the function signature `async ({ orbitdb, identities, address })`,
+- A partial function with the function signature `async ({ orbitdb, identities, address })`,
 - A `type` constant,
-- A canAppend function with the param `entry`.
+- A canAppend function with the param `entry` and a boolean return type.
 
-```
+The canAppend function must return true if the entry can be appended to the log or false otherwise.
+
+```js
 const type = 'custom'
 
 const CustomAccessController = () => async ({ orbitdb, identities, address }) => {
   address = '/custom/access-controller'
 
   const canAppend = (entry) => {
-
+    // return true if the entry can be appended to the log, false otherwise.
   }
 }
 
@@ -84,7 +127,7 @@ CustomAccessController.type = type
 
 Additional configuration can be passed to the access controller by adding one or more parameters to the `CustomAccessController` function. For example, passing a configurable object parameter with the variable `write`:
 
-```
+```js
 const CustomAccessController = ({ write }) => async ({ orbitdb, identities, address }) => {
 }
 ```
@@ -95,7 +138,7 @@ The main driver of the access controller is the canAppend function. This specifi
 
 How the custom access controller evaluates access will be determined by its use case, but in most instances, the canAppend function will want to check whether the entry being created can be written to the database (and underlying operations log). Therefore, the entry's identity will need to be used to retrieve the identity's id:
 
-```
+```js
 write = [identity.id]
 
 const canAppend = async (entry) => {
@@ -119,8 +162,11 @@ In the above example, the `entry.identity` will be the hash of the identity. Usi
 
 Before passing the custom access controller to the `open` function, it must be added to OrbitDB's AccessControllers:
 
-```
-AccessControllers.add(CustomAccessController)
-const orbitdb = await OrbitDB()
+```js
+import { create } from 'ipfs-core'
+import { OrbitDB, addAccessController } from 'orbit-db'
+
+addAccessController(CustomAccessController)
+const orbitdb = await OrbitDB({ ipfs })
 const db = await orbitdb.open('my-db', { AccessController: CustomAccessController(params) })
 ```

docs/CONNECTING_PEERS.md

@@ -7,20 +7,24 @@ OrbitDB peers connect to one another using js-libp2p. Connection settings will v
 Node.js allows libp2p to open connections with other Node.js daemons.
 
 ```javascript
-ipfs1 = await IPFS.create({ repo: './ipfs1' })
-ipfs2 = await IPFS.create({ repo: './ipfs2' })
+import { create } from 'ipfs-core'
+
+const ipfs1 = await create({ repo: './ipfs1' })
+const ipfs2 = await create({ repo: './ipfs2' })
 
 const cid = await ipfs1.block.put('here is some data')
 const block = await ipfs2.block.get(cid)
 ```
 
-On localhost or a local network, both ipfs nodes should discover each other quickly enough that ipfs2 will retrieve the block added to ipfs1.
+On localhost or a local network, both ipfs nodes should discover each other quickly enough so that ipfs2 will retrieve the block added to ipfs1.
 
-In remote networks, retrieval of content across peers may take significantly longer. To speed up communication between the two peers, connect one peer to another directly using the swarm API and a peer's publicly accessible address. For example, assuming ipfs1 is listening on the address /ip4/1.2.3.4/tcp/12345/p2p/ipfs1-peer-hash:
+In remote networks, retrieval of content across peers may take significantly longer. To speed up communication between the two peers, one peer can be directly connected to another using the swarm API and a peer's publicly accessible address. For example, assuming ipfs1 is listening on the address /ip4/1.2.3.4/tcp/12345/p2p/ipfs1-peer-hash:
 
 ```javascript
-ipfs1 = await IPFS.create({ repo: './ipfs1' })
-ipfs2 = await IPFS.create({ repo: './ipfs2' })
+import { create } from 'ipfs-core'
+
+const ipfs1 = await create({ repo: './ipfs1' })
+const ipfs2 = await create({ repo: './ipfs2' })
 
 await ipfs2.swarm.connect('/ip4/1.2.3.4/tcp/12345/p2p/ipfs1-peer-hash')
 
@@ -35,17 +39,17 @@ For various security reasons, a browser cannot dial another peer over a raw TCP
 On the server, listen for incoming websocket connections:
 
 ```javascript
-import { WebSockets } from '@libp2p/websockets'
+import { webSockets } from '@libp2p/websockets'
 import { create } from 'ipfs-core'
 
-ipfs1 = await IPFS.create({ 
+ipfs1 = await create({ 
   libp2p: { 
     addresses: {
       listen: [
-        '/ip4/0.0.0.0/tcp/0/ws'
+        '/ip4/0.0.0.0/tcp/0/wss'
       ]
     },
-    transports: [new WebSockets()] 
+    transports: [webSockets()] 
   },
   repo: './ipfs1'
 })
@@ -55,21 +59,27 @@ Within the browser, dial into the server using the server's exposed web socket:
 
 ```javascript
 // import the following libraries if using a build environment such as vite.
-import { WebSockets } from '@libp2p/websockets'
+import { webSockets } from '@libp2p/websockets'
 import { create } from 'ipfs-core'
-import { all } from '@libp2p/websockets/filters'
 
-// uncomment { filter: all } if no tls certificate is deployed. Only do this in development environments.
-const ws = new webSockets(/* { filter: all } */)
+const ws = new webSockets()
 
-ipfs1 = await IPFS.create({
+ipfs1 = await create({
   libp2p: {
-    transports: [new webSockets()] 
+    transports: [ws] 
   }},
   repo: './ipfs1'
 })
 ```
 
+You may find IPFS is unable to connect to a local WebRTC Star server. This will likely to due to the local WebSockets transport being insecure (ws instead of wss). To solve this issue, pass the `all` filter to the `webSockets` function:
+
+```
+import { all } from '@libp2p/websockets/filters'
+
+const ws = webSockets({ filter: all })
+```
+
 ## Browser to Browser and Node Daemon to Browser
 
 A connection cannot be made directly to a browser node. Browsers do not listen for incoming connections, they operate in a server/client environment where the server address is known and the browser connects to the server using the known address. Therefore, for a browser to respond to an incoming connection a relay is required to "listen" on the browser's behalf. The relay assigns and advertises multi addresses on behalf of the browser nodes, allowing the nodes to create a direct connection between each other.
@@ -86,7 +96,7 @@ In the first browser peer, configure
 import { create } from 'ipfs-core'
 import { multiaddr } from 'multiaddr'
 
-ipfs = await IPFS.create({
+ipfs = await create({
   config: {
     Addresses: { 
       Swarm: ['/ip4/0.0.0.0/tcp/12345/ws/p2p-webrtc-star']
@@ -101,7 +111,7 @@ Configure the second browser node in the same way as the first, then dial in to
 import { create } from 'ipfs-core'
 import { multiaddr } from 'multiaddr'
 
-ipfs = await IPFS.create({
+ipfs = await create({
   config: {
     Addresses: { 
       Swarm: ['/ip4/0.0.0.0/tcp/12345/ws/p2p-webrtc-star']