Source: databases/documents.js

  1. /**
  2.  * @namespace Databases-Documents
  3.  * @memberof module:Databases
  4.  * @description Documents database.
  5.  * @example <caption>Create documents db with custom index</caption>
  6.  * import { createHelia } from 'helia'
  7.  * import { createOrbitDB, Documents } from 'orbitdb'
  8.  *
  9.  * const ipfs = createHelia()
  10.  * const orbitdb = await createOrbitDB({ ipfs })
  11.  * const db = await orbitdb.open('my-docs', { Database: Documents({ indexBy: 'myCustomId'} ) }
  12.  *
  13.  * @augments module:Databases~Database
  14.  */
  15. import Database from '../database.js'
  17. const type = 'documents'
  19. const DefaultOptions = { indexBy: '_id' }
  21. /**
  22.  * Defines a Documents database.
  23.  * @param {Object} options Various options for configuring the Document store.
  24.  * @param {string} [options.indexBy=_id] An index.
  25.  * @return {module:Databases.Databases-Documents} A Documents function.
  26.  * @memberof module:Databases
  27.  */
  28. const Documents = ({ indexBy } = DefaultOptions) => async ({ ipfs, identity, address, name, access, directory, meta, headsStorage, entryStorage, indexStorage, referencesCount, syncAutomatically, onUpdate, encrypt }) => {
  29.   const database = await Database({ ipfs, identity, address, name, access, directory, meta, headsStorage, entryStorage, indexStorage, referencesCount, syncAutomatically, encrypt })
  31.   const { addOperation, log } = database
  33.   /**
  34.    * Stores a document to the store.
  35.    * @function
  36.    * @param {Object} doc An object representing a key/value list of fields.
  37.    * @return {string} The hash of the new oplog entry.
  38.    * @memberof module:Databases.Databases-Documents
  39.    * @instance
  40.    */
  41.   const put = async (doc) => {
  42.     const key = doc[indexBy]
  44.     if (!key) { throw new Error(`The provided document doesn't contain field '${indexBy}'`) }
  46.     return addOperation({ op: 'PUT', key, value: doc })
  47.   }
  49.   /**
  50.    * Deletes a document from the store.
  51.    * @function
  52.    * @param {string} key The key of the doc to delete.
  53.    * @return {string} The hash of the new oplog entry.
  54.    * @memberof module:Databases.Databases-Documents
  55.    * @instance
  56.    */
  57.   const del = async (key) => {
  58.     if (!await get(key)) { throw new Error(`No document with key '${key}' in the database`) }
  60.     return addOperation({ op: 'DEL', key, value: null })
  61.   }
  63.   /**
  64.    * Gets a document from the store by key.
  65.    * @function
  66.    * @param {string} key The key of the doc to get.
  67.    * @return {Object} The doc corresponding to key or null.
  68.    * @memberof module:Databases.Databases-Documents
  69.    * @instance
  70.    */
  71.   const get = async (key) => {
  72.     for await (const doc of iterator()) {
  73.       if (key === doc.key) {
  74.         return doc
  75.       }
  76.     }
  77.   }
  79.   /**
  80.    * Queries the document store for documents matching mapper filters.
  81.    * @function
  82.    * @param {function(Object)} findFn A function for querying for specific
  83.    * results.
  84.    *
  85.    * The findFn function's signature takes the form `function(doc)` where doc
  86.    * is a document's value property. The function should return true if the
  87.    * document should be included in the results, false otherwise.
  88.    * @return {Array} Found documents.
  89.    * @memberof module:Databases.Databases-Documents
  90.    * @instance
  91.    */
  92.   const query = async (findFn) => {
  93.     const results = []
  95.     for await (const doc of iterator()) {
  96.       if (findFn(doc.value)) {
  97.         results.push(doc.value)
  98.       }
  99.     }
  101.     return results
  102.   }
  104.   /**
  105.    * Iterates over documents.
  106.    * @function
  107.    * @param {Object} [filters={}] Various filters to apply to the iterator.
  108.    * @param {string} [filters.amount=-1] The number of results to fetch.
  109.    * @yields [string, string, string] The next document as hash/key/value.
  110.    * @memberof module:Databases.Databases-Documents
  111.    * @instance
  112.    */
  113.   const iterator = async function * ({ amount } = {}) {
  114.     const keys = {}
  115.     let count = 0
  116.     for await (const entry of log.iterator()) {
  117.       const { op, key, value } = entry.payload
  118.       if (op === 'PUT' && !keys[key]) {
  119.         keys[key] = true
  120.         count++
  121.         const hash = entry.hash
  122.         yield { hash, key, value }
  123.       } else if (op === 'DEL' && !keys[key]) {
  124.         keys[key] = true
  125.       }
  126.       if (count >= amount) {
  127.         break
  128.       }
  129.     }
  130.   }
  132.   /**
  133.    * Returns all documents.
  134.    * @function
  135.    * @return [][string, string, string] An array of documents as hash/key
  136.    * value entries.
  137.    * @memberof module:Databases.Databases-Documents
  138.    * @instance
  139.    */
  140.   const all = async () => {
  141.     const values = []
  142.     for await (const entry of iterator()) {
  143.       values.unshift(entry)
  144.     }
  145.     return values
  146.   }
  148.   return {
  149.     ...database,
  150.     type,
  151.     put,
  152.     del,
  153.     get,
  154.     iterator,
  155.     query,
  156.     indexBy,
  157.     all
  158.   }
  159. }
  161. Documents.type = type
  163. export default Documents