@fireproof/core 0.0.3 → 0.0.4

package/hooks/use-fireproof.md

@@ -0,0 +1,149 @@
+# useFireproof hook for React
+
+ React hook to initialize a Fireproof database, automatically saving and loading the clock.
+ 
+ The hook takes two optional setup function arguments, `defineDatabaseFn` and `setupDatabaseFn`. See below for examples.
+ 
+The return value looks like `{ ready, database, addSubscriber }` where the `database` is your Fireproof instance that you can interact with using `put` and `get`, or via your indexes. The `ready` flag turns true after setup completes, you can use this to activate your UI. The `addSubscriber` function is used to update your app in realtime, see example. 
+
+## Usage Example
+
+In App.js:
+
+```js
+import { FireproofCtx, useFireproof } from '@fireproof/core/hooks/use-fireproof'
+
+function App() {
+  // establish the Fireproof context value
+  const fpCtxValue = useFireproof()
+
+  // render the rest of the application wrapped in the Fireproof provider
+  return (
+    <FireproofCtx.Provider value={fpCtxValue}>
+        <MyComponent />
+    </FireproofCtx.Provider>
+  )
+}
+```
+
+In your components:
+
+```js
+import { FireproofCtx } from '@fireproof/core/hooks/use-fireproof'
+
+function MyComponent() {
+  // get Fireproof context
+  const { ready, database, addSubscriber } = useContext(FireproofCtx)
+
+  // set a default empty document
+  const [doc, setDoc] = useState({})
+  
+  // function to load the document from the database
+  const getDataFn = async () => {
+    setDoc(await database.get("my-doc-id"))
+  }
+
+  // run that function when the database changes
+  addSubscriber('MyComponent', getDataFn)
+
+  // run the loader on first mount
+  useEffect(() => getDataFn(), [])
+
+  // a function to change the value of the document
+  const updateFn = async () => {
+    await database.put({ _id : "my-doc-id", hello: "world", updated_at: new Date()})
+  }
+
+  // render the document with a click handler to update it
+  return <pre onclick={updateFn}>JSON.stringify(doc)</pre>
+}
+```
+
+This should result in a tiny application that updates the document when you click it. In a real appliction you'd probably query an index to present eg. all of the photos in a gallery.
+
+## Setup Functions
+
+### defineDatabaseFn 
+ 
+ Synchronous function that defines the database, run this before any async calls. You can use it to do stuff like set up Indexes. Here's an example:
+
+ ```js
+ const defineIndexes = (database) => {
+  database.allLists = new Index(database, function (doc, map) {
+    if (doc.type === 'list') map(doc.type, doc)
+  })
+  database.todosByList = new Index(database, function (doc, map) {
+    if (doc.type === 'todo' && doc.listId) {
+      map([doc.listId, doc.createdAt], doc)
+    }
+  })
+  window.fireproof = database // 🤫 for dev
+  return database
+}
+ ```
+
+### setupDatabaseFn
+
+ Asynchronous function that uses the database when it's ready, run this to load fixture data, insert a dataset from somewhere else, etc. Here's a simple example:
+
+
+```
+async function setupDatabase(database)) {
+    const apiData = await (await fetch('https://dummyjson.com/products')).json()
+    for (const product of apiData.products) {
+        await database.put(product)
+    }  
+}
+```
+
+Note there are no protections against you running the same thing over and over again, so you probably want to put some logic in there to do the right thing.
+
+Here is an example of generating deterministic fixtures, using `mulberry32` for determinstic randomness so re-runs give the same CID, avoiding unnecessary bloat at development time, taken from the TodoMVC demo app.
+
+ ```js
+ function mulberry32(a) {
+  return function () {
+    let t = (a += 0x6d2b79f5)
+    t = Math.imul(t ^ (t >>> 15), t | 1)
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61)
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+  }
+}
+const rand = mulberry32(1) // determinstic fixtures
+
+export default async function loadFixtures(database) {
+  const nextId = (prefix = '') => prefix + rand().toString(32).slice(2)
+  const listTitles = ['Building Apps', 'Having Fun', 'Getting Groceries']
+  const todoTitles = [
+    [
+      'In the browser',
+      'On the phone',
+      'With or without Redux',
+      'Login components',
+      'GraphQL queries',
+      'Automatic replication and versioning',
+    ],
+    ['Rollerskating meetup', 'Motorcycle ride', 'Write a sci-fi story with ChatGPT'],
+    ['Macadamia nut milk', 'Avocado toast', 'Coffee', 'Bacon', 'Sourdough bread', 'Fruit salad'],
+  ]
+  let ok
+  for (let j = 0; j < 3; j++) {
+    ok = await database.put({ 
+        title: listTitles[j], 
+        type: 'list', 
+        _id: nextId('' + j) 
+    })
+    for (let i = 0; i < todoTitles[j].length; i++) {
+      await database.put({
+        _id: nextId(),
+        title: todoTitles[j][i],
+        listId: ok.id,
+        completed: rand() > 0.75,
+        type: 'todo',
+      })
+    }
+  }
+}
+ ```
+
+ 

package/hooks/use-fireproof.ts

@@ -0,0 +1,112 @@
+/* global localStorage */
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore
+import { useEffect, useState, createContext } from 'react'
+import { Fireproof, Listener } from '@fireproof/core'
+
+export interface FireproofCtxValue {
+  addSubscriber: (label: String, fn: Function) => void
+  database: Fireproof
+  ready: boolean
+}
+export const FireproofCtx = createContext<FireproofCtxValue>({
+  addSubscriber: () => {},
+  database: null,
+  ready: false,
+})
+
+
+
+const inboundSubscriberQueue = new Map()
+const database = Fireproof.storage()
+const listener = new Listener(database)
+
+/**
+ * @function useFireproof
+ * React hook to initialize a Fireproof database, automatically saving and loading the clock.
+ * @param [defineDatabaseFn] Synchronous function that defines the database, run this before any async calls
+ * @param [setupDatabaseFn] Asynchronous function that sets up the database, run this to load fixture data etc
+ * @returns {FireproofCtxValue} { addSubscriber, database, ready }
+ */
+export function useFireproof(defineDatabaseFn: Function, setupDatabaseFn: Function): FireproofCtxValue {
+  const [ready, setReady] = useState(false)
+  defineDatabaseFn = defineDatabaseFn || (() => {})
+  setupDatabaseFn = setupDatabaseFn || (() => {})
+
+  if (!ready) {
+    defineDatabaseFn(database)
+  }
+
+  const addSubscriber = (label: String, fn: Function) => {
+    inboundSubscriberQueue.set(label, fn)
+  }
+
+  const listenerCallback = async () => {
+    localSet('fireproof', JSON.stringify(database))
+    for (const [, fn] of inboundSubscriberQueue) fn()
+  }
+
+  useEffect(() => {
+    const doSetup = async () => {
+      if (ready) return
+      const fp = localGet('fireproof')
+      if (fp) {
+        const { clock } = JSON.parse(fp)
+        console.log("Loading previous database clock. (localStorage.removeItem('fireproof') to reset)")
+        await database.setClock(clock)
+        try {
+          await database.changesSince()
+        } catch (e) {
+          console.error('Error loading previous database clock.', e)
+          await database.setClock([])
+          await setupDatabaseFn(database)
+          localSet('fireproof', JSON.stringify(database))
+        }
+      } else {
+        await setupDatabaseFn(database)
+        localSet('fireproof', JSON.stringify(database))
+      }
+      setReady(true)
+      listener.on('*', hushed('*', listenerCallback, 250))
+    }
+    doSetup()
+  }, [ready])
+
+  return {
+    addSubscriber,
+    database,
+    ready,
+  }
+}
+
+const husherMap = new Map()
+const husher = (id: string, workFn: { (): Promise<any> }, ms: number) => {
+  if (!husherMap.has(id)) {
+    husherMap.set(
+      id,
+      workFn().finally(() => setTimeout(() => husherMap.delete(id), ms))
+    )
+  }
+  return husherMap.get(id)
+}
+const hushed = (id: string, workFn: { (): Promise<any> }, ms: number) => () => husher(id, workFn, ms)
+
+let storageSupported = false
+try {
+  storageSupported = window.localStorage && true
+} catch (e) {}
+export function localGet(key: string) {
+  if (storageSupported) {
+    return localStorage && localStorage.getItem(key)
+  }
+}
+function localSet(key: string, value: string) {
+  if (storageSupported) {
+    return localStorage && localStorage.setItem(key, value)
+  }
+}
+// function localRemove(key) {
+//   if (storageSupported) {
+//     return localStorage && localStorage.removeItem(key)
+//   }
+// }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fireproof/core",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Realtime database for IPFS",
   "main": "index.js",
   "type": "module",

package/src/db-index.js

@@ -16,13 +16,32 @@ const makeGetBlock = (blocks) => async (address) => {
 }
 const makeDoc = ({ key, value }) => ({ _id: key, ...value })
 
+/**
+ * JDoc for the result row type.
+ * @typedef {Object} ChangeEvent
+ * @property {string} key - The key of the document.
+ * @property {Object} value - The new value of the document.
+ * @property {boolean} [del] - Is the row deleted?
+ * @memberof DbIndex
+ */
+
+/**
+ * JDoc for the result row type.
+ * @typedef {Object} DbIndexEntry
+ * @property {string[]} key - The key for the DbIndex entry.
+ * @property {Object} value - The value of the document.
+ * @property {boolean} [del] - Is the row deleted?
+ * @memberof DbIndex
+ */
+
 /**
  * Transforms a set of changes to DbIndex entries using a map function.
  *
- * @param {Array<{ key: string, value: import('./link').AnyLink, del?: boolean }>} changes
+ * @param {ChangeEvent[]} changes
  * @param {Function} mapFun
- * @returns {Array<{ key: [string, string], value: any }>} The DbIndex entries generated by the map function.
+ * @returns {DbIndexEntry[]} The DbIndex entries generated by the map function.
  * @private
+ * @memberof DbIndex
  */
 const indexEntriesForChanges = (changes, mapFun) => {
   const indexEntries = []
@@ -52,7 +71,7 @@ const indexEntriesForOldChanges = async (blocks, byIDindexRoot, ids, mapFun) =>
  * @class DbIndex
  * @classdesc An DbIndex can be used to order and filter the documents in a Fireproof database.
  *
- * @param {import('./fireproof').Fireproof} database - The Fireproof database instance to DbIndex.
+ * @param {Fireproof} database - The Fireproof database instance to DbIndex.
  * @param {Function} mapFun - The map function to apply to each entry in the database.
  *
  */
@@ -60,7 +79,7 @@ export default class DbIndex {
   constructor (database, mapFun) {
     /**
      * The database instance to DbIndex.
-     * @type {import('./fireproof').Fireproof}
+     * @type {Fireproof}
      */
     this.database = database
     /**
@@ -73,9 +92,16 @@ export default class DbIndex {
     this.dbHead = null
   }
 
+  /**
+   * JSDoc for Query type.
+   * @typedef {Object} DbQuery
+   * @property {string[]} [range] - The range to query.
+   * @memberof DbIndex
+   */
+
   /**
    * Query object can have {range}
-   * @param {Object<{range:[startKey, endKey]}>} query - the query range to use
+   * @param {DbQuery} query - the query range to use
    * @param {CID} [root] - an optional root to query a snapshot
    * @returns {Promise<{rows: Array<{id: string, key: string, value: any}>}>}
    * @memberof DbIndex
@@ -148,8 +174,8 @@ export default class DbIndex {
 /**
  * Update the DbIndex with the given entries
  * @param {Blockstore} blocks
- * @param {import('multiformats/block').Block} inRoot
- * @param {import('prolly-trees/db-DbIndex').IndexEntry[]} indexEntries
+ * @param {Block} inRoot
+ * @param {DbIndexEntry[]} indexEntries
  * @private
  */
 async function bulkIndex (blocks, inRoot, indexEntries) {
@@ -180,14 +206,6 @@ async function bulkIndex (blocks, inRoot, indexEntries) {
   }
 }
 
-/**
- * Query the DbIndex for the given range
- * @param {Blockstore} blocks
- * @param {import('multiformats/block').Block} inRoot
- * @param {import('prolly-trees/db-DbIndex').Query} query
- * @returns {Promise<import('prolly-trees/db-DbIndex').QueryResult>}
- * @private
- **/
 async function doIndexQuery (blocks, root, query) {
   const cid = root && root.cid
   if (!cid) return { result: [] }

package/src/fireproof.js

@@ -35,7 +35,7 @@ export default class Fireproof {
     this.clock = clock
     this.config = config
     this.authCtx = authCtx
-    this.instanceId = 'fp.' + Math.random().toString(36).substring(2, 7)
+    this.instanceId = 'db.' + Math.random().toString(36).substring(2, 7)
   }
 
   /**
@@ -181,8 +181,8 @@ export default class Fireproof {
   /**
    * Updates the underlying storage with the specified event.
    * @private
-   * @param {import('../clock').EventLink<import('../crdt').EventData>} event - the event to add
-   * @returns {Object<{ id: string, clock: import('../clock').EventLink<import('../crdt').EventData }>} - The result of adding the event to storage
+   * @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(
@@ -203,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)
@@ -250,12 +248,6 @@ export default class Fireproof {
     this.blocks.valet.uploadFunction = carUploaderFn
   }
 
-  /**
-   * Sets the function that will be used to read blocks from a remote peer.
-   * @param {Function} remoteBlockReaderFn - the function that will be used to read blocks from a remote peer
-   * @memberof Fireproof
-   * @instance
-   */
   setRemoteBlockReader (remoteBlockReaderFn) {
     // console.log('registering remote block reader')
     this.blocks.valet.remoteBlockFunction = remoteBlockReaderFn

package/src/listener.js

@@ -4,9 +4,11 @@
  * @class Listener
  * @classdesc An listener attaches to a Fireproof database and runs a routing function on each change, sending the results to subscribers.
  *
- * @param {import('./fireproof').Fireproof} database - The Fireproof database instance to index.
+ * @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()
 
@@ -20,7 +22,7 @@ export default class Listener {
   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))
@@ -94,7 +96,7 @@ 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 {ChangeEvent[]} changes
  * @param {Function} routingFn
  * @returns {Array<string>} The topics emmitted by the event function.
  * @private

package/src/prolly.js

@@ -35,15 +35,15 @@ const makeGetBlock = (blocks) => async (address) => {
  * @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 {import('./clock').EventLink<import('./crdt').EventData>} head - The head of the event chain.
+ * @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: import('./clock').EventLink<import('./crdt').EventData>,
- *   event: import('./clock').EventLink<import('./crdt').EventData>
+ *   head: CID[],
+ *   event: CID[]
  * }>}
  */
 async function createAndSaveNewEvent (
@@ -135,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>}
  */