@fireproof/core 0.3.22 → 0.4.0

package/src/database.js

@@ -0,0 +1,338 @@
+// @ts-nocheck
+import { visMerkleClock, visMerkleTree, vis, put, get, getAll, eventsSince } from './prolly.js'
+import { doTransaction } from './blockstore.js'
+import charwise from 'charwise'
+import { localSet } from './utils.js'
+
+// TypeScript Types
+// eslint-disable-next-line no-unused-vars
+// import { CID } from 'multiformats/dist/types/src/cid.js'
+// eslint-disable-next-line no-unused-vars
+class Proof {}
+
+/**
+ * @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.
+ *
+ * @param {import('./blockstore.js').TransactionBlockstore} 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 class Database {
+  listeners = new Set()
+
+  // todo refactor this for the next version
+  constructor (blocks, clock, config = {}) {
+    this.name = config.name
+    this.instanceId = `fp.${this.name}.${Math.random().toString(36).substring(2, 7)}`
+    this.blocks = blocks
+    this.clock = clock
+    this.config = config
+    this.indexes = new Map()
+  }
+
+  /**
+   * 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.clockToJSON(),
+      name: this.name,
+      key: this.blocks.valet?.getKeyMaterial(),
+      indexes: [...this.indexes.values()].map(index => index.toJSON())
+    }
+  }
+
+  /**
+   * Returns the Merkle clock heads for the Fireproof instance.
+   * @returns {string[]} - The Merkle clock heads for the Fireproof instance.
+   * @memberof Fireproof
+   * @instance
+   */
+  clockToJSON () {
+    return this.clock.map(cid => cid.toString())
+  }
+
+  hydrate ({ clock, name, key }) {
+    this.name = name
+    this.clock = clock
+    this.blocks.valet?.setKeyMaterial(key)
+    this.indexBlocks = null
+  }
+
+  maybeSaveClock () {
+    if (this.name && this.blocks.valet) {
+      localSet('fp.' + this.name, JSON.stringify(this))
+    }
+  }
+
+  /**
+   * Triggers a notification to all listeners
+   * of the Fireproof instance so they can repaint UI, etc.
+   * @returns {Promise<void>}
+   * @memberof Fireproof
+   * @instance
+   */
+  async notifyReset () {
+    await this.notifyListeners({ _reset: true, _clock: this.clockToJSON() })
+  }
+
+  // used be indexes etc to notify database listeners of new availability
+  async notifyExternal (source = 'unknown') {
+    await this.notifyListeners({ _external: source, _clock: this.clockToJSON() })
+  }
+
+  /**
+   * Returns the changes made to the Fireproof instance since the specified event.
+   * @function changesSince
+   * @param {CID[]} [event] - The clock head to retrieve changes since. If null or undefined, retrieves all changes.
+   * @returns {Promise<{rows : Object[], clock: CID[], proof: {}}>} 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)
+    let rows, dataCIDs, clockCIDs
+    // if (!event) event = []
+    if (event) {
+      const resp = await eventsSince(this.blocks, this.clock, event)
+      const docsMap = new Map()
+      for (const { key, type, value } of resp.result.map(decodeEvent)) {
+        if (type === 'del') {
+          docsMap.set(key, { key, del: true })
+        } else {
+          docsMap.set(key, { key, value })
+        }
+      }
+      rows = Array.from(docsMap.values())
+      clockCIDs = resp.clockCIDs
+      // console.log('change rows', this.instanceId, rows)
+    } else {
+      const allResp = await getAll(this.blocks, this.clock)
+      rows = allResp.result.map(({ key, value }) => (decodeEvent({ key, value })))
+      dataCIDs = allResp.cids
+      // console.log('dbdoc rows', this.instanceId, rows)
+    }
+    return {
+      rows,
+      clock: this.clockToJSON(),
+      proof: { data: await cidsToProof(dataCIDs), clock: await cidsToProof(clockCIDs) }
+    }
+  }
+
+  async allDocuments () {
+    const allResp = await getAll(this.blocks, this.clock)
+    const rows = allResp.result.map(({ key, value }) => (decodeEvent({ key, value }))).map(({ key, value }) => ({ key, value: { _id: key, ...value } }))
+    return {
+      rows,
+      clock: this.clockToJSON(),
+      proof: await cidsToProof(allResp.cids)
+    }
+  }
+
+  /**
+   * 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) {
+    if (this.config && this.config.validateChange) {
+      const oldDoc = await this.get(doc._id)
+        .then((doc) => doc)
+        .catch(() => ({}))
+      this.config.validateChange(doc, oldDoc, this.authCtx)
+    }
+  }
+
+  /**
+   * Retrieves the document with the specified ID from the database
+   *
+   * @param {string} key - the ID of the document to retrieve
+   * @param {Object} [opts] - options
+   * @returns {Promise<{_id: string}>} - the document with the specified ID
+   * @memberof Fireproof
+   * @instance
+   */
+  async get (key, opts = {}) {
+    const clock = opts.clock || this.clock
+    const resp = await get(this.blocks, clock, charwise.encode(key))
+
+    // this tombstone is temporary until we can get the prolly tree to delete
+    if (!resp || resp.result === null) {
+      throw new Error('Not found')
+    }
+    const doc = resp.result
+    if (opts.mvcc === true) {
+      doc._clock = this.clockToJSON()
+    }
+    doc._proof = {
+      data: await cidsToProof(resp.cids),
+      clock: this.clockToJSON()
+    }
+    doc._id = key
+    return doc
+  }
+  /**
+ * @typedef {any} Document
+ * @property {string} _id - The ID of the document (required)
+ * @property {string} [_proof] - The proof of the document (optional)
+ * @property {string} [_clock] - The clock of the document (optional)
+ * @property {any} [key: string] - Index signature notation to allow any other unknown fields
+ */
+
+  /**
+   * Adds a new document to the database, or updates an existing document. Returns the ID of the document and the new clock head.
+   *
+   * @param {Document} doc - the document to be added
+   * @returns {Promise<{ id: string, clock: CID[]  }>} - The result of adding the document to the database
+   * @memberof Fireproof
+   * @instance
+   */
+  async put ({ _id, _proof, ...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 }, doc._clock)
+  }
+
+  /**
+   * Deletes a document from the database
+   * @param {string | any} docOrId - the document ID
+   * @returns {Promise<{ id: string, clock: CID[] }>} - The result of deleting the document from the database
+   * @memberof Fireproof
+   * @instance
+   */
+  async del (docOrId) {
+    let id
+    let clock = null
+    if (docOrId._id) {
+      id = docOrId._id
+      clock = docOrId._clock
+    } else {
+      id = docOrId
+    }
+    await this.runValidation({ _id: id, _deleted: true })
+    return await this.putToProllyTree({ key: id, del: true }, clock) // 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 }, clock)
+  }
+
+  /**
+   * Updates the underlying storage with the specified event.
+   * @private
+   * @param {{del?: true, key : string, value?: any}} decodedEvent - the event to add
+   * @returns {Promise<{ proof:{}, id: string, clock: CID[] }>} - The result of adding the event to storage
+   */
+  async putToProllyTree (decodedEvent, clock = null) {
+    const event = encodeEvent(decodedEvent)
+    if (clock && JSON.stringify(clock) !== JSON.stringify(this.clockToJSON())) {
+      // we need to check and see what version of the document exists at the clock specified
+      // if it is the same as the one we are trying to put, then we can proceed
+      const resp = await eventsSince(this.blocks, this.clock, event.value._clock)
+      const missedChange = resp.result.find(({ key }) => key === event.key)
+      if (missedChange) {
+        throw new Error('MVCC conflict, document is changed, please reload the document and try again.')
+      }
+    }
+    const result = await doTransaction(
+      'putToProllyTree',
+      this.blocks,
+      async (blocks) => await put(blocks, this.clock, event)
+    )
+    if (!result) {
+      console.error('failed', event)
+      throw new Error('failed to put at storage layer')
+    }
+    // console.log('new clock head', this.instanceId, result.head.toString())
+    this.clock = result.head // do we want to do this as a finally block
+    await this.notifyListeners([decodedEvent]) // this type is odd
+    return {
+      id: decodedEvent.key,
+      clock: this.clockToJSON(),
+      proof: { data: await cidsToProof(result.cids), clock: await cidsToProof(result.clockCIDs) }
+    }
+    // todo should include additions (or split clock)
+  }
+
+  //   /**
+  //    * Advances the clock to the specified event and updates the root CID
+  //    *   Will be used by replication
+  //    */
+  //     async advance (event) {
+  //       this.clock = await advance(this.blocks, this.clock, event)
+  //       this.rootCid = await root(this.blocks, this.clock)
+  //       return this.clock
+  //     }
+
+  async * vis () {
+    return yield * vis(this.blocks, this.clock)
+  }
+
+  async visTree () {
+    return await visMerkleTree(this.blocks, this.clock)
+  }
+
+  async visClock () {
+    return await visMerkleClock(this.blocks, this.clock)
+  }
+
+  /**
+   * Registers a Listener to be called when the Fireproof instance's clock is updated.
+   * 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)
+    return () => {
+      this.listeners.delete(listener)
+    }
+  }
+
+  async notifyListeners (changes) {
+    // await sleep(10)
+    await this.maybeSaveClock()
+    for (const listener of this.listeners) {
+      await listener(changes)
+    }
+  }
+
+  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) {
+    this.blocks.remoteBlockFunction = remoteBlockReaderFn
+  }
+}
+
+export async function cidsToProof (cids) {
+  if (!cids || !cids.all) return []
+  const all = await cids.all()
+  return [...all].map((cid) => cid.toString())
+}
+
+function decodeEvent (event) {
+  const decodedKey = charwise.decode(event.key)
+  return { ...event, key: decodedKey }
+}
+
+function encodeEvent (event) {
+  if (!(event && event.key)) return
+  const encodedKey = charwise.encode(event.key)
+  return { ...event, key: encodedKey }
+}

package/src/db-index.js

@@ -9,7 +9,7 @@ import { nocache as cache } from 'prolly-trees/cache'
 import { bf, simpleCompare } from 'prolly-trees/utils'
 import { makeGetBlock } from './prolly.js'
 // eslint-disable-next-line no-unused-vars
-import { Fireproof, cidsToProof } from './fireproof.js'
+import { Database, cidsToProof } from './database.js'
 
 import * as codec from '@ipld/dag-cbor'
 // import { create as createBlock } from 'multiformats/block'
@@ -88,7 +88,7 @@ const indexEntriesForChanges = (changes, mapFn) => {
  * @class DbIndex
  * @classdesc An DbIndex can be used to order and filter the documents in a Fireproof database.
  *
- * @param {Fireproof} database - The Fireproof database instance to DbIndex.
+ * @param {Database} database - The Fireproof database instance to DbIndex.
  * @param {Function} mapFn - The map function to apply to each entry in the database.
  *
  */
@@ -96,7 +96,7 @@ export class DbIndex {
   constructor (database, mapFn, clock, opts = {}) {
     this.database = database
     if (!database.indexBlocks) {
-      database.indexBlocks = new TransactionBlockstore(database.name + '.indexes', database.blocks.valet.getKeyMaterial())
+      database.indexBlocks = new TransactionBlockstore(database?.name + '.indexes', database.blocks.valet?.getKeyMaterial())
     }
     /**
      * The map function to apply to each entry in the database.