@fireproof/core 0.0.2 → 0.0.4

package/src/fireproof.js

@@ -1,28 +1,34 @@
-// import { vis } from './clock.js'
 import { put, get, getAll, eventsSince } from './prolly.js'
 import Blockstore, { doTransaction } from './blockstore.js'
 
 // const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
 
 /**
- * Represents a Fireproof instance that wraps a ProllyDB instance and Merkle clock head.
+ * @class Fireproof
+ * @classdesc Fireproof stores data in IndexedDB and provides a Merkle clock.
+ *  This is the main class for saving and loading JSON and other documents with the database. You can find additional examples and
+ *  usage guides in the repository README.
  *
- * @class
- * @classdesc A Fireproof instance can be used to store and retrieve values from a ProllyDB instance.
- *
- * @param {Blockstore} blocks - The block storage instance to use for the underlying ProllyDB instance.
- * @param {import('../clock').EventLink<import('../crdt').EventData>[]} clock - The Merkle clock head to use for the Fireproof instance.
+ * @param {Blockstore} blocks - The block storage instance to use documents and indexes
+ * @param {CID[]} clock - The Merkle clock head to use for the Fireproof instance.
  * @param {object} [config] - Optional configuration options for the Fireproof instance.
  * @param {object} [authCtx] - Optional authorization context object to use for any authentication checks.
  *
  */
-
 export default class Fireproof {
+  #listeners = new Set()
+
   /**
-   * @param {Blockstore} blocks
-   * @param {import('../clock').EventLink<import('../crdt').EventData>[]} clock
+   * @function storage
+   * @memberof Fireproof
+   * Creates a new Fireproof instance with default storage settings
+   * Most apps should use this and not worry about the details.
+   * @static
+   * @returns {Fireproof} - a new Fireproof instance
    */
-  #listeners = new Set()
+  static storage = () => {
+    return new Fireproof(new Blockstore(), [])
+  }
 
   constructor (blocks, clock, config = {}, authCtx = {}) {
     this.blocks = blocks
@@ -33,12 +39,13 @@ export default class Fireproof {
   }
 
   /**
-   * Returns a snapshot of the current Fireproof instance.
-   *
-   * @param {import('../clock').EventLink<import('../crdt').EventData>[]} clock
-   *    Clock to use for the snapshot.
+   * Returns a snapshot of the current Fireproof instance as a new instance.
+   * @function snapshot
+   * @param {CID[]} clock - The Merkle clock head to use for the snapshot.
    * @returns {Fireproof}
    *    A new Fireproof instance representing the snapshot.
+   * @memberof Fireproof
+   * @instance
    */
   snapshot (clock) {
     // how to handle listeners, views, and config?
@@ -47,14 +54,26 @@ export default class Fireproof {
   }
 
   /**
-   * This triggers a notification to all listeners of the Fireproof instance.
+   * Move the current instance to a new point in time. This triggers a notification to all listeners
+   * of the Fireproof instance so they can repaint UI, etc.
+   * @param {CID[] } clock
+   *    Clock to use for the snapshot.
+   * @returns {Promise<void>}
+   * @memberof Fireproof
+   * @instance
    */
   async setClock (clock) {
     // console.log('setClock', this.instanceId, clock)
-    this.clock = clock.map((item) => item['/'] ? item['/'] : item)
+    this.clock = clock.map((item) => (item['/'] ? item['/'] : item))
     await this.#notifyListeners({ reset: true, clock })
   }
 
+  /**
+   * Renders the Fireproof instance as a JSON object.
+   * @returns {Object} - The JSON representation of the Fireproof instance. Includes clock heads for the database and its indexes.
+   * @memberof Fireproof
+   * @instance
+   */
   toJSON () {
     // todo this also needs to return the index roots...
     return { clock: this.clock }
@@ -62,13 +81,11 @@ export default class Fireproof {
 
   /**
    * Returns the changes made to the Fireproof instance since the specified event.
-   *
-   * @param {import('../clock').EventLink<import('../crdt').EventData>?} event -
-   * The event to retrieve changes since. If null or undefined, retrieves all changes.
-   * @returns {Promise<{
-   *   rows: { key: string, value?: any, del?: boolean }[],
-   *   head: import('../clock').EventLink<import('../crdt').EventData>[]
-   * }>} - An object `{rows : [...{key, value, del}], head}` containing the rows and the head of the instance's clock.
+   * @function changesSince
+   * @param {CID[]} [event] - The clock head to retrieve changes since. If null or undefined, retrieves all changes.
+   * @returns {Object<{rows : Object[], clock: CID[]}>} An object containing the rows and the head of the instance's clock.
+   * @memberof Fireproof
+   * @instance
    */
   async changesSince (event) {
     // console.log('changesSince', this.instanceId, event, this.clock)
@@ -97,6 +114,7 @@ export default class Fireproof {
    * Recieves live changes from the database after they are committed.
    * @param {Function} listener - The listener to be called when the clock is updated.
    * @returns {Function} - A function that can be called to unregister the listener.
+   * @memberof Fireproof
    */
   registerListener (listener) {
     this.#listeners.add(listener)
@@ -107,15 +125,21 @@ export default class Fireproof {
 
   async #notifyListeners (changes) {
     // await sleep(0)
-    this.#listeners.forEach((listener) => listener(changes))
+    for (const listener of this.#listeners) {
+      await listener(changes)
+    }
   }
 
   /**
-   * Runs validation on the specified document using the Fireproof instance's configuration.
+   * Runs validation on the specified document using the Fireproof instance's configuration. Throws an error if the document is invalid.
    *
    * @param {Object} doc - The document to validate.
+   * @returns {Promise<void>}
+   * @throws {Error} - Throws an error if the document is invalid.
+   * @memberof Fireproof
+   * @instance
    */
-  async runValidation (doc) {
+  async #runValidation (doc) {
     if (this.config && this.config.validateChange) {
       const oldDoc = await this.get(doc._id)
         .then((doc) => doc)
@@ -125,35 +149,50 @@ export default class Fireproof {
   }
 
   /**
-   * Adds a new document to the database, or updates an existing document.
+   * Adds a new document to the database, or updates an existing document. Returns the ID of the document and the new clock head.
    *
    * @param {Object} doc - the document to be added
    * @param {string} doc._id - the document ID. If not provided, a random ID will be generated.
    * @param {Object} doc.* - the document data to be added
-   * @returns {Promise<import('./prolly').PutResult>} - the result of adding the document
+   * @returns {Object<{ id: string, clock: CID[]  }>} - The result of adding the document to the database
+   * @memberof Fireproof
+   * @instance
    */
   async put ({ _id, ...doc }) {
     const id = _id || 'f' + Math.random().toString(36).slice(2)
-    await this.runValidation({ _id: id, ...doc })
-    return await this.putToProllyTree({ key: id, value: doc })
+    await this.#runValidation({ _id: id, ...doc })
+    return await this.#putToProllyTree({ key: id, value: doc })
   }
 
   /**
    * Deletes a document from the database
    * @param {string} id - the document ID
-   * @returns {Promise<import('./prolly').PutResult>} - the result of deleting the document
+   * @returns {Object<{ id: string, clock: CID[] }>} - The result of deleting the document from the database
+   * @memberof Fireproof
+   * @instance
    */
   async del (id) {
-    await this.runValidation({ _id: id, _deleted: true })
-    // return await this.putToProllyTree({ key: id, del: true }) // not working at prolly tree layer?
+    await this.#runValidation({ _id: id, _deleted: true })
+    // return await this.#putToProllyTree({ key: id, del: true }) // not working at prolly tree layer?
     // this tombstone is temporary until we can get the prolly tree to delete
-    return await this.putToProllyTree({ key: id, value: null })
+    return await this.#putToProllyTree({ key: id, value: null })
   }
 
-  async putToProllyTree (event) {
-    const result = await doTransaction('putToProllyTree', this.blocks, async (blocks) => await put(blocks, this.clock, event))
+  /**
+   * Updates the underlying storage with the specified event.
+   * @private
+   * @param {CID[]} event - the event to add
+   * @returns {Object<{ id: string, clock: CID[] }>} - The result of adding the event to storage
+   */
+  async #putToProllyTree (event) {
+    const result = await doTransaction(
+      '#putToProllyTree',
+      this.blocks,
+      async (blocks) => await put(blocks, this.clock, event)
+    )
     if (!result) {
-      console.log('failed', event)
+      console.error('failed', event)
+      throw new Error('failed to put at storage layer')
     }
     this.clock = result.head // do we want to do this as a finally block
     result.id = event.key
@@ -164,8 +203,6 @@ export default class Fireproof {
   //   /**
   //    * Advances the clock to the specified event and updates the root CID
   //    *   Will be used by replication
-  //    * @param {import('../clock').EventLink<import('../crdt').EventData>} event - the event to advance to
-  //    * @returns {import('../clock').EventLink<import('../crdt').EventData>[]} - the new clock after advancing
   //    */
   //     async advance (event) {
   //       this.clock = await advance(this.blocks, this.clock, event)
@@ -191,7 +228,9 @@ export default class Fireproof {
    * Retrieves the document with the specified ID from the database
    *
    * @param {string} key - the ID of the document to retrieve
-   * @returns {Promise<import('./prolly').GetResult>} - the document with the specified ID
+   * @returns {Object<{_id: string, ...doc: Object}>} - the document with the specified ID
+   * @memberof Fireproof
+   * @instance
    */
   async get (key) {
     const got = await get(this.blocks, this.clock, key)
@@ -202,8 +241,15 @@ export default class Fireproof {
     got._id = key
     return got
   }
-}
 
-Fireproof.storage = (_email) => {
-  return new Fireproof(new Blockstore(), [])
+  setCarUploader (carUploaderFn) {
+    console.log('registering car uploader')
+    // https://en.wikipedia.org/wiki/Law_of_Demeter - this is a violation of the law of demeter
+    this.blocks.valet.uploadFunction = carUploaderFn
+  }
+
+  setRemoteBlockReader (remoteBlockReaderFn) {
+    // console.log('registering remote block reader')
+    this.blocks.valet.remoteBlockFunction = remoteBlockReaderFn
+  }
 }

package/src/listener.js

@@ -1,13 +1,14 @@
 /**
  * A Fireproof database Listener allows you to react to events in the database.
  *
- * @class
- * @classdesc An listener can be notified of events as they happen or on reconection
- *
- * @param {import('./fireproof').Fireproof} database - The Fireproof database instance to index.
- * @param {Function} eventFun - The map function to apply to each entry in the database.
+ * @class Listener
+ * @classdesc An listener attaches to a Fireproof database and runs a routing function on each change, sending the results to subscribers.
  *
+ * @param {Fireproof} database - The Fireproof database instance to index.
+ * @param {Function} routingFn - The routing function to apply to each entry in the database.
  */
+// import { ChangeEvent } from './db-index'
+
 export default class Listener {
   #subcribers = new Map()
 
@@ -18,15 +19,10 @@ export default class Listener {
   // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakRef
   #doStopListening = null
 
-  /**
-   * Creates a new index with the given map function and database.
-   * @param {import('./fireproof').Fireproof} database - The Fireproof database instance to index.
-   * @param {Function} eventFun - The event function to apply to each current change to the database.
-   */
-  constructor (database, eventFun) {
-    /** eventFun
+  constructor (database, routingFn) {
+    /** routingFn
      * The database instance to index.
-     * @type {import('./fireproof').Fireproof}
+     * @type {Fireproof}
      */
     this.database = database
     this.#doStopListening = database.registerListener((changes) => this.#onChanges(changes))
@@ -34,7 +30,11 @@ export default class Listener {
      * The map function to apply to each entry in the database.
      * @type {Function}
      */
-    this.eventFun = eventFun || function (_, emit) { emit('*') }
+    this.routingFn =
+      routingFn ||
+      function (_, emit) {
+        emit('*')
+      }
     this.dbHead = null
   }
 
@@ -43,13 +43,15 @@ export default class Listener {
    * @param {string} topic - The topic to subscribe to.
    * @param {Function} subscriber - The function to call when the topic is emitted.
    * @returns {Function} A function to unsubscribe from the topic.
+   * @memberof Listener
+   * @instance
    */
   on (topic, subscriber, since) {
     const listOfTopicSubscribers = getTopicList(this.#subcribers, topic)
     listOfTopicSubscribers.push(subscriber)
     if (typeof since !== 'undefined') {
       this.database.changesSince(since).then(({ rows: changes }) => {
-        const keys = topicsForChanges(changes, this.eventFun).get(topic)
+        const keys = topicsForChanges(changes, this.routingFn).get(topic)
         if (keys) keys.forEach((key) => subscriber(key))
       })
     }
@@ -61,7 +63,7 @@ export default class Listener {
 
   #onChanges (changes) {
     if (Array.isArray(changes)) {
-      const seenTopics = topicsForChanges(changes, this.eventFun)
+      const seenTopics = topicsForChanges(changes, this.routingFn)
       for (const [topic, keys] of seenTopics) {
         const listOfTopicSubscribers = getTopicList(this.#subcribers, topic)
         listOfTopicSubscribers.forEach((subscriber) => keys.forEach((key) => subscriber(key)))
@@ -94,15 +96,16 @@ const makeDoc = ({ key, value }) => ({ _id: key, ...value })
 /**
  * Transforms a set of changes to events using an emitter function.
  *
- * @param {Array<{ key: string, value: import('./link').AnyLink, del?: boolean }>} changes
- * @param {Function} eventFun
+ * @param {ChangeEvent[]} changes
+ * @param {Function} routingFn
  * @returns {Array<string>} The topics emmitted by the event function.
+ * @private
  */
-const topicsForChanges = (changes, eventFun) => {
+const topicsForChanges = (changes, routingFn) => {
   const seenTopics = new Map()
   changes.forEach(({ key, value, del }) => {
     if (del || !value) value = { _deleted: true }
-    eventFun(makeDoc({ key, value }), (t) => {
+    routingFn(makeDoc({ key, value }), (t) => {
       const topicList = getTopicList(seenTopics, t)
       topicList.push(key)
     })

package/src/prolly.js

@@ -1,4 +1,10 @@
-import { advance, EventFetcher, EventBlock, findCommonAncestorWithSortedEvents, findUnknownSortedEvents } from './clock.js'
+import {
+  advance,
+  EventFetcher,
+  EventBlock,
+  findCommonAncestorWithSortedEvents,
+  findUnknownSortedEvents
+} from './clock.js'
 import { create, load } from 'prolly-trees/map'
 import * as codec from '@ipld/dag-cbor'
 import { sha256 as hasher } from 'multiformats/hashes/sha2'
@@ -21,7 +27,36 @@ const makeGetBlock = (blocks) => async (address) => {
   return createBlock({ cid, bytes, hasher, codec })
 }
 
-async function createAndSaveNewEvent (inBlocks, mblocks, getBlock, bigPut, root, { key, value, del }, head, additions, removals = []) {
+/**
+ * Creates and saves a new event.
+ * @param {import('./blockstore.js').Blockstore} inBlocks - A persistent blockstore.
+ * @param {MemoryBlockstore} mblocks - A temporary blockstore.
+ * @param {Function} getBlock - A function that gets a block.
+ * @param {Function} bigPut - A function that puts a block.
+ * @param {import('prolly-trees/map').Root} root - The root node.
+ * @param {Object<{ key: string, value: any, del: boolean }>} event - The update event.
+ * @param {CID[]} head - The head of the event chain.
+ * @param {Array<import('multiformats/block').Block>} additions - A array of additions.
+ * @param {Array<mport('multiformats/block').Block>>} removals - An array of removals.
+ * @returns {Promise<{
+ *   root: import('prolly-trees/map').Root,
+ *   additions: Map<string, import('multiformats/block').Block>,
+ *   removals: Array<string>,
+ *   head: CID[],
+ *   event: CID[]
+ * }>}
+ */
+async function createAndSaveNewEvent (
+  inBlocks,
+  mblocks,
+  getBlock,
+  bigPut,
+  root,
+  { key, value, del },
+  head,
+  additions,
+  removals = []
+) {
   const data = {
     type: 'put',
     root: {
@@ -100,7 +135,7 @@ const prollyRootFromAncestor = async (events, ancestor, getBlock) => {
  * @param {import('./block').BlockFetcher} blocks Bucket block storage.
  * @param {import('./clock').EventLink<EventData>[]} head Merkle clock head.
  * @param {string} key The key of the value to put.
- * @param {import('./link').AnyLink} value The value to put.
+ * @param {CID} value The value to put.
  * @param {object} [options]
  * @returns {Promise<Result>}
  */
@@ -132,8 +167,16 @@ export async function put (inBlocks, head, event, options) {
     bigPut(nb, additions)
   }
 
-  return createAndSaveNewEvent(inBlocks, mblocks, getBlock, bigPut,
-    prollyRootBlock, event, head, Array.from(additions.values()) /*, Array.from(removals.values()) */)
+  return createAndSaveNewEvent(
+    inBlocks,
+    mblocks,
+    getBlock,
+    bigPut,
+    prollyRootBlock,
+    event,
+    head,
+    Array.from(additions.values()) /*, Array.from(removals.values()) */
+  )
 }
 
 /**
@@ -180,8 +223,11 @@ export async function eventsSince (blocks, head, since) {
     throw new Error('no head')
   }
   const sinceHead = [...since, ...head]
-  const unknownSorted3 = await findUnknownSortedEvents(blocks, sinceHead,
-    await findCommonAncestorWithSortedEvents(blocks, sinceHead))
+  const unknownSorted3 = await findUnknownSortedEvents(
+    blocks,
+    sinceHead,
+    await findCommonAncestorWithSortedEvents(blocks, sinceHead)
+  )
   return unknownSorted3.map(({ value: { data } }) => data)
 }
 
@@ -218,18 +264,3 @@ export async function get (blocks, head, key) {
   const { result } = await prollyRootNode.get(key)
   return result
 }
-
-/**
- * @typedef {{
- *   type: 'put'|'del'
- *   key: string
- *   value: import('./link').AnyLink
- *   root: import('./shard').ShardLink
- * }} EventData
- *
- * @typedef {{
- *   root: import('./shard').ShardLink
- *   head: import('./clock').EventLink<EventData>[]
- *   event: import('./clock').EventBlockView<EventData>
- * } & import('./db-index').ShardDiff} Result
- */