Mirroristas/orbitdb
2
0
Fork 0
mirror of https://github.com/orbitdb/orbitdb.git synced 2025-03-30 15:08:28 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #90 from orbitdb/docs/iterate-pre-release

Browse Source 
Iterate pre-release docs
This commit is contained in:
Hayden Young 2023-06-30 23:07:32 +08:00 committed by GitHub
commit 4f8a72237a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
17 changed files with 144 additions and 76 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
src/access-controllers/orbitdb.js
View File

@ -26,7 +26,7 @@ const type = 'orbitdb'
* Defines an OrbitDB access controller.
* @param {Object} options Various options for configuring the
* IPFSAccessController.
* @param {Array} [params.write] An array of identity ids who can write to the
* @param {Array} [params.write] An array of ids of identities who can write to the
* database.
* @return {module:AccessControllers.AccessControllers-OrbitDB} An
* IPFSAccessController function.
@ -69,7 +69,7 @@ const OrbitDBAccessController = ({ write } = {}) => async ({ orbitdb, identities
*
* The returned capabilities will be a mixture of admin and write access
* addresses.
* @return {Array} A list of addresses with admin and write access.
* @return {Array} A list of ids of identities with admin and write access.
* @memberof module:AccessControllers.AccessControllers-OrbitDB
* @instance
*/
@ -97,7 +97,7 @@ const OrbitDBAccessController = ({ write } = {}) => async ({ orbitdb, identities
}
/**
* Gets a list of addresses with the specified capability.
* Gets a list of identities with the specified capability.
* @param {string} capability A capability (e.g. write).
* @return {Array} One or more addresses with the spcified capability.
* @memberof module:AccessControllers.AccessControllers-OrbitDB
@ -118,10 +118,10 @@ const OrbitDBAccessController = ({ write } = {}) => async ({ orbitdb, identities
}
/**
* Checks whether an address has a capability.
* Checks whether an identity has a capability.
* @param {string} capability A capability (e.g. write).
* @param {string} key An address.
* @return {boolean} True if the address has the capability, false
* @param {string} key An id of an identity.
* @return {boolean} True if the identity has the capability, false
* otherwise.
* @memberof module:AccessControllers.AccessControllers-OrbitDB
* @instance
@ -133,10 +133,10 @@ const OrbitDBAccessController = ({ write } = {}) => async ({ orbitdb, identities
}
/**
* Grants a capability to an address, storing it to the access control
* Grants a capability to an identity, storing it to the access control
* database.
* @param {string} capability A capability (e.g. write).
* @param {string} key An address.
* @param {string} key An id of an identity.
* @memberof module:AccessControllers.AccessControllers-OrbitDB
* @instance
*/
@ -147,10 +147,10 @@ const OrbitDBAccessController = ({ write } = {}) => async ({ orbitdb, identities
}
/**
* Revokes a capability from an address, removing it from the access control
* Revokes a capability from an identity, removing it from the access control
* database.
* @param {string} capability A capability (e.g. write).
* @param {string} key An address.
* @param {string} key An id of an identity.
* @memberof module:AccessControllers.AccessControllers-OrbitDB
* @instance
*/

4
src/address.js
View File

@ -59,8 +59,8 @@ const parseAddress = (address) => {
/**
* @typedef {Object} OrbitDBAddress
* @property {string} protocol The address protocol (/orbitdb/).
* @property {string} hash The hash of the database.
* @property {string} protocol Protocol prefix "/orbitdb/".
* @property {string} hash The hash of the database manifest.
* @property {string} address The full database address.
*/
const OrbitDBAddress = (address) => {

69
src/database.js
View File

@ -70,6 +70,25 @@ const Database = async ({ ipfs, identity, address, name, access, directory, meta
* database.events.on('drop', () => ...)
*/
/** Events inherited from Sync */
/**
* Event fired when when a peer has connected to the database.
* @event module:Databases~Database#join
* @param {PeerID} peerId PeerID of the peer who connected
* @param {Entry[]} heads An array of Log entries
* @example
* database.events.on('join', (peerID, heads) => ...)
*/
/**
* Event fired when a peer has disconnected from the database.
* @event module:Databases~Database#leave
* @param {PeerID} peerId PeerID of the peer who disconnected
* @example
* database.events.on('leave', (peerID) => ...)
*/
directory = pathJoin(directory || './orbitdb', `./${address}/`)
meta = meta || {}
referencesCount = referencesCount || defaultReferencesCount
@ -91,15 +110,6 @@ const Database = async ({ ipfs, identity, address, name, access, directory, meta
const log = await Log(identity, { logId: address, access, entryStorage, headsStorage, indexStorage })
/**
* Event emitter that emits Database changes.
* @†ype EventEmitter
* @fires update when an entry is added to the database.
* @fires close when the database is successfully closed.
* @fires drop when the database is successfully dropped.
* @memberof module:Sync~Sync
* @instance
*/
const events = new EventEmitter()
const queue = new PQueue({ concurrency: 1 })
@ -172,17 +182,58 @@ const Database = async ({ ipfs, identity, address, name, access, directory, meta
const sync = await Sync({ ipfs, log, events, onSynced: applyOperation, start: syncAutomatically })
return {
/**
* The address of the database.
* @†ype string
* @memberof module:Databases~Database
* @instance
*/
address,
/**
* The name of the database.
* @†ype string
* @memberof module:Databases~Database
* @instance
*/
name,
identity,
meta,
close,
drop,
addOperation,
/**
* The underlying [operations log]{@link module:Log~Log} of the database.
* @†ype {module:Log~Log}
* @memberof module:Databases~Database
* @instance
*/
log,
/**
* A [sync]{@link module:Sync~Sync} instance of the database.
* @†ype {module:Sync~Sync}
* @memberof module:Databases~Database
* @instance
*/
sync,
/**
* Set of currently connected peers for this Database instance.
* @†ype Set
* @memberof module:Databases~Database
* @instance
*/
peers: sync.peers,
/**
* Event emitter that emits Database changes. See Events section for details.
* @†ype EventEmitter
* @memberof module:Databases~Database
* @instance
*/
events,
/**
* The [access controller]{@link module:AccessControllers} instance of the database.
* @memberof module:Databases~Database
* @instance
*/
access
}
}

6
src/databases/documents.js
View File

@ -15,6 +15,8 @@
* const options = { indexBy: 'myCustomId'}
* const Partial = Documents(options)
* const documents = await Partial({ ipfs })
*
* @augments module:Databases~Database
*/
import Database from '../database.js'
@ -23,7 +25,7 @@ const DefaultOptions = { indexBy: '_id' }
/**
* Defines a Documents database.
* @param {Object} options Various options for configuring the Document store.
* @param {string} [params.indexBy=_id] An index.
* @param {string} [options.indexBy=_id] An index.
* @return {module:Databases.Databases-Documents} A Documents function.
* @memberof module:Databases
*/
@ -86,7 +88,7 @@ const Documents = ({ indexBy } = DefaultOptions) => async ({ ipfs, identity, add
*
* The findFn function's signature takes the form `function(doc)` where doc
* is a document's value property. The function should return true if the
* document is found, false otherwise.
* document should be included in the results, false otherwise.
* @return {Array} Found documents.
* @memberof module:Databases.Databases-Documents
* @instance

5
src/databases/events.js
View File

@ -1,7 +1,10 @@
/**
* @namespace Databases-Events
* @memberof module:Databases
* @description Events database.
* @description
* Events database is an immutable, append-only event log database.
*
* @augments module:Databases~Database
*/
import Database from '../database.js'

9
src/databases/keyvalue-indexed.js
View File

@ -2,9 +2,9 @@
* @namespace Databases-KeyValueIndexed
* @memberof module:Databases
* @description
* KeyValueIndexed database.
* Key-Value database that uses an index in order to provide fast queries.
*
* Key/value pairs are stored to the configured storage.
* Key-value pairs are stored to the configured storage.
* @example <caption>Specify a custom storage</caption>
* import { create } from 'IPFS'
*
@ -12,6 +12,9 @@
* const storage = await IPFSBlockStorage()
* const Partial = KeyValueIndexed({ storage })
* const keyValueIndexed = await Partial({ ipfs })
*
* @augments module:Databases~Database
* @augments module:Databases.Databases-KeyValue
*/
import KeyValue from './keyvalue.js'
import LevelStorage from '../storage/level.js'
@ -21,8 +24,6 @@ const valueEncoding = 'json'
/**
* Defines a KeyValueIndexed database.
* @param {Object} options Various options for configuring the KeyValueIndexed
* store.
* @param {module:Storage} [storage=LevelStorage] A compatible storage where
* the key/value pairs are indexed.
* @return {module:Databases.Databases-KeyValueIndexed} A KeyValueIndexed

5
src/databases/keyvalue.js
View File

@ -1,7 +1,10 @@
/**
* @namespace Databases-KeyValue
* @memberof module:Databases
* @description KeyValue database.
* @description
* Key-Value database.
*
* @augments module:Databases~Database
*/
import Database from '../database.js'

6
src/identities/identities.js
View File

@ -36,7 +36,7 @@ const DefaultIdentityKeysPath = pathJoin('./orbitdb', 'identities')
const Identities = async ({ keystore, path, storage, ipfs } = {}) => {
/**
* @namespace module:Identities~Identities
* @description The instance returned by {@link module:Identities~Identities}.
* @description The instance returned by {@link module:Identities}.
*/
keystore = keystore || await KeyStore({ path: path || DefaultIdentityKeysPath })
@ -52,7 +52,7 @@ const Identities = async ({ keystore, path, storage, ipfs } = {}) => {
/**
* Gets an identity by hash.
* @param {string} hash An identity hash.
* @return {Identity} An instance of identity.
* @return {module:Identities~Identity} An instance of identity.
* @memberof module:Identities~Identities
* @instance
*/
@ -137,6 +137,7 @@ const Identities = async ({ keystore, path, storage, ipfs } = {}) => {
* be retrieved.
* @memberof module:Identities~Identities
* @instance
* @private
*/
const sign = async (identity, data) => {
const signingKey = await keystore.getKey(identity.id)
@ -157,6 +158,7 @@ const Identities = async ({ keystore, path, storage, ipfs } = {}) => {
* otherwise.
* @memberof module:Identities~Identities
* @instance
* @private
*/
const verify = async (signature, publicKey, data) => {
return await verifyMessage(signature, publicKey, data)

5
src/identities/identity.js
View File

@ -13,12 +13,11 @@ const hashStringEncoding = base58btc
* @property {object} publicKey A public key.
* @property {object} signatures A signed identity id and public key.
* @property {string} type The type of identity provider.
* @property {function} sign A sign function.
* @property {function} verify A verify function.
* @property {function} sign A sign function to sign data using this identity.
* @property {function} verify A verify function to verify data signed by this identity.
*/
const Identity = async ({ id, publicKey, signatures, type, sign, verify } = {}) => {
/**
* @namespace module:Identities~Identity
* @description The Identity instance. Returned by
* [Identities.createIdentity()]{@link module:Identities~Identities#createIdentity}.
*/

22
src/key-store.js
View File

@ -55,6 +55,7 @@ const verifySignature = async (signature, publicKey, data) => {
* @throws No signing key given if no key is provided.
* @throws Given input data was undefined if no data is provided.
* @static
* @private
*/
const signMessage = async (key, data) => {
if (!key) {
@ -81,6 +82,7 @@ const verifiedCachePromise = LRUStorage({ size: 1000 })
* @param {string} data The data to be verified.
* @return {boolean} True if the the data and cache match, false otherwise.
* @static
* @private
*/
const verifyMessage = async (signature, publicKey, data) => {
const verifiedCache = await verifiedCachePromise
@ -144,8 +146,8 @@ const KeyStore = async ({ storage, path } = {}) => {
}
/**
* Checks if the key exists in the key store.
* @param {string} id The id of the private key in the key store.
* Checks if a key exists in the key store .
* @param {string} id The id of an [Identity]{@link module:Identities~Identity} to check the key for.
* @return {boolean} True if the key exists, false otherwise.
* @throws id needed to check a key if no id is specified.
* @memberof module:KeyStore~KeyStore
@ -170,9 +172,9 @@ const KeyStore = async ({ storage, path } = {}) => {
}
/**
* Adds a key to the keystore.
* @param {string} id A storage id for the key.
* @param {Uint8Array} key The key to store.
* Adds a private key to the keystore.
* @param {string} id An id of the [Identity]{@link module:Identities~Identity} to whom the key belongs to.
* @param {Uint8Array} key The private key to store.
* @memberof module:KeyStore~KeyStore
* @async
* @instance
@ -182,8 +184,8 @@ const KeyStore = async ({ storage, path } = {}) => {
}
/**
* Creates a key, storing it to the keystore.
* @param {string} id A storage id for the key.
* Creates a key pair and stores it to the keystore.
* @param {string} id An id of the [Identity]{@link module:Identities~Identity} to generate the key pair for.
* @throws id needed to create a key if no id is specified.
* @memberof module:KeyStore~KeyStore
* @async
@ -210,8 +212,8 @@ const KeyStore = async ({ storage, path } = {}) => {
}
/**
* Gets the key from keystore.
* @param {string} id A storage id of the key.
* Gets a key from keystore.
* @param {string} id An id of the [Identity]{@link module:Identities~Identity} whose key to retrieve.
* @return {Uint8Array} The key specified by id.
* @throws id needed to get a key if no id is specified.
* @memberof module:KeyStore~KeyStore
@ -238,7 +240,7 @@ const KeyStore = async ({ storage, path } = {}) => {
}
/**
* Gets th serialized public key from a key pair.
* Gets the serialized public key from a key pair.
* @param {*} keys A key pair.
* @param {Object} options One or more options.
* @param {Object} [options.format=hex] The format the public key should be

25
src/oplog/entry.js
View File

@ -1,9 +1,3 @@
/**
* @namespace module:Log~Entry
* @memberof module:Log
* @description A log entry.
* @private
*/
import Clock from './clock.js'
import * as Block from 'multiformats/block'
import * as dagCbor from '@ipld/dag-cbor'
@ -14,6 +8,20 @@ const codec = dagCbor
const hasher = sha256
const hashStringEncoding = base58btc
/**
* @typedef {Object} module:Log~Entry
* @property {string} id A string linking multiple entries together.
* @property {*} payload An arbitrary chunk of data.
* @property {Array<string>} next One or more hashes pointing to the next entries in a chain of
* entries.
* @property {Array<string>} refs One or more hashes which reference other entries in the chain.
* @property {Clock} clock A logical clock. See {@link module:Log~Clock}.
* @property {integer} v The version of the entry.
* @property {string} key The public key of the identity.
* @property {string} identity The identity of the entry's owner.
* @property {string} sig The signature of the entry signed by the owner.
*/
/**
* Creates an Entry.
* @param {module:Identities~Identity} identity The identity instance
@ -45,6 +53,7 @@ const hashStringEncoding = base58btc
* const entry = await Entry.create(identity, 'log1', 'hello')
* console.log(entry)
* // { payload: "hello", next: [], ... }
* @private
*/
const create = async (identity, id, payload, clock = null, next = [], refs = []) => {
if (identity == null) throw new Error('Identity is required, cannot create entry')
@ -80,6 +89,7 @@ const create = async (identity, id, payload, clock = null, next = [], refs = [])
* @return {Promise<boolean>} A promise that resolves to a boolean value indicating if
* the signature is valid.
* @memberof module:Log~Entry
* @private
*/
const verify = async (identities, entry) => {
if (!identities) throw new Error('Identities is required, cannot verify entry')
@ -106,6 +116,7 @@ const verify = async (identities, entry) => {
* @param {module:Log~Entry} obj
* @return {boolean}
* @memberof module:Log~Entry
* @private
*/
const isEntry = (obj) => {
return obj && obj.id !== undefined &&
@ -122,6 +133,7 @@ const isEntry = (obj) => {
* @param {module:Log~Entry} b An entry to compare.
* @return {boolean} True if a and b are equal, false otherwise.
* @memberof module:Log~Entry
* @private
*/
const isEqual = (a, b) => {
return a && b && a.hash === b.hash
@ -132,6 +144,7 @@ const isEqual = (a, b) => {
* @param {Uint8Array} bytes
* @return {module:Log~Entry}
* @memberof module:Log~Entry
* @private
*/
const decode = async (bytes) => {
const { value } = await Block.decode({ bytes, codec, hasher })

9
src/oplog/log.js
View File

@ -3,10 +3,8 @@
* @description
* Log is a verifiable, append-only log CRDT.
*
* Implemented as a Merkle-CRDT as per the paper:
* "Merkle-CRDTs: Merkle-DAGs meet CRDTs"
* https://arxiv.org/abs/2004.00107
* @private
* Implemented as a Merkle-CRDT as per the paper
* ["Merkle-CRDTs: Merkle-DAGs meet CRDTs"]{@link https://arxiv.org/abs/2004.00107}
*/
import LRU from 'lru'
import Entry from './entry.js'
@ -55,8 +53,7 @@ const DefaultAccessController = async () => {
const Log = async (identity, { logId, logHeads, access, entryStorage, headsStorage, indexStorage, sortFn } = {}) => {
/**
* @namespace Log
* @description The instance returned by {@link module:Log}.
* @private
* @description The instance returned by {@link module:Log}
*/
if (identity == null) {

17
src/orbitdb.js
View File

@ -21,12 +21,11 @@ const DefaultAccessController = IPFSAccessController
* @function
* @param {Object} params One or more parameters for configuring OrbitDB.
* @param {IPFS} params.ipfs An IPFS instance.
* @param {string} [params.id] The id of the OrbitDB instance.
* @param {module:Identities} [params.identities] An Identities instance.
* @param {string} [params.directory] A location for storing OrbitDB-related
* data.
* @param {string} [params.id] The id of the user to use for this OrbitDB instance.
* @param {module:Identities} [params.identities] An Identities system instance.
* @param {string} [params.directory] A location for storing OrbitDB data.
* @return {module:OrbitDB~OrbitDB} An instance of OrbitDB.
* @throws IPFSinstance is required argument if no IPFS instance is provided.
* @throws "IPFS instance is required argument" if no IPFS instance is provided.
* @instance
*/
const OrbitDB = async ({ ipfs, id, identities, directory } = {}) => {
@ -95,11 +94,11 @@ const OrbitDB = async ({ ipfs, id, identities, directory } = {}) => {
* @param {module:Storage} [params.entryStorage=[ComposedStorage]{@link module:Storage.Storage-Composed}] A compatible storage instance for storing
* log entries. Defaults to ComposedStorage(LRUStorage, IPFSBlockStorage).
* @param {module:Storage} [params.indexStorage=[ComposedStorage]{@link module:Storage.Storage-Composed}] A compatible storage instance for storing an " index of log entries. Defaults to ComposedStorage(LRUStorage, LevelStorage).
* @param {number} [params.referencesCount] The number of references to
* previous entries that should be stored with this entry.
* @param {number} [params.referencesCount] The number of references to
* use for [Log]{@link module:Log} entries.
* @memberof module:OrbitDB
* @return {module:Database} A database instance.
* @throws Unsupported database type if the type specified is not in the list
* @throws "Unsupported database type" if the type specified is not in the list
* of known databaseTypes.
* @memberof module:OrbitDB~OrbitDB
* @instance
@ -157,7 +156,7 @@ const OrbitDB = async ({ ipfs, id, identities, directory } = {}) => {
}
/**
* Stops OrbitDB, closing the underlying keystore and manifest.
* Stops OrbitDB, closing the underlying keystore and manifest store.
* @function stop
* @memberof module:OrbitDB~OrbitDB
* @instance

2
src/storage/composed.js
View File

@ -2,7 +2,7 @@
* @namespace Storage-Composed
* @memberof module:Storage
* @description
* ComposedStorage stores data to multiple storage mechanisms.
* ComposedStorage stores data to multiple storage backends.
* @example <caption>Store to LRU and Level</caption>
* await ComposedStorage(await LRUStorage(), await LevelStorage())
* @example <caption>Store to memory and IPFS</caption>

2
src/storage/index.js
View File

@ -1,7 +1,7 @@
/**
* @module Storage
* @description
* Various storage mechanisms with a common interface.
* Storage backends for OrbitDB.
*/
export { default as ComposedStorage } from './composed.js'
export { default as IPFSBlockStorage } from './ipfs-block.js'

2
src/storage/memory.js
View File

@ -8,7 +8,7 @@
/**
* Creates an instance of MemoryStorage.
* @function
* @return {module:Storage.Storage-Memory} An instance of LRUStorage.
* @return {module:Storage.Storage-Memory} An instance of MemoryStorage.
* @memberof module:Storage
* @instance
*/

12
src/sync.js
View File

@ -87,7 +87,8 @@ const Sync = async ({ ipfs, log, events, onSynced, start, timeout }) => {
*/
/**
* Event fired when new heads have been received from other peers.
* Event fired when when a peer has connected and the exchange of
* heads has been completed.
* @event module:Sync~Sync#join
* @param {PeerID} peerId PeerID of the peer who we received heads from
* @param {Entry[]} heads An array of Log entries
@ -98,7 +99,7 @@ const Sync = async ({ ipfs, log, events, onSynced, start, timeout }) => {
/**
* Event fired when a peer leaves the sync protocol.
* @event module:Sync~Sync#leave
* @param {PeerID} peerId PeerID of the peer who we received heads from
* @param {PeerID} peerId PeerID of the peer who left
* @example
* sync.events.on('leave', (peerID) => ...)
*/
@ -123,19 +124,14 @@ const Sync = async ({ ipfs, log, events, onSynced, start, timeout }) => {
* Set of currently connected peers for the log for this Sync instance.
* @name peers
* @†ype Set
* @return Set set of PeerIDs
* @memberof module:Sync~Sync
* @instance
*/
const peers = new Set()
/**
* Event emitter that emits Sync changes.
* Event emitter that emits Sync changes. See Events section for details.
* @†ype EventEmitter
* @fires module:Sync~Sync#join when a peer has connected and the exchange of
* heads has been completed.
* @fires module:Sync~Sync#leave when a peer disconnects
* @fires module:Sync~Sync#error when an error occurs
* @memberof module:Sync~Sync
* @instance
*/