@fireproof/core 0.0.3 → 0.0.5

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 '../index'
+
+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.5",
   "description": "Realtime database for IPFS",
   "main": "index.js",
   "type": "module",

package/src/db-index.js

@@ -1,14 +1,30 @@
 import { create, load } from 'prolly-trees/db-index'
 import { sha256 as hasher } from 'multiformats/hashes/sha2'
 import { nocache as cache } from 'prolly-trees/cache'
-import { bf, simpleCompare as compare } from 'prolly-trees/utils'
+import { bf, simpleCompare } from 'prolly-trees/utils'
 import * as codec from '@ipld/dag-cbor'
 import { create as createBlock } from 'multiformats/block'
 import { doTransaction } from './blockstore.js'
 import charwise from 'charwise'
-const opts = { cache, chunker: bf(3), codec, hasher, compare }
 
-const ALWAYS_REBUILD = true // todo: remove this
+const arrayCompare = (a, b) => {
+  if (Array.isArray(a) && Array.isArray(b)) {
+    const len = Math.min(a.length, b.length)
+    for (let i = 0; i < len; i++) {
+      const comp = simpleCompare(a[i], b[i])
+      if (comp !== 0) {
+        return comp
+      }
+    }
+    return simpleCompare(a.length, b.length)
+  } else {
+    return simpleCompare(a, b)
+  }
+}
+
+const opts = { cache, chunker: bf(3), codec, hasher, compare: arrayCompare }
+
+const ALWAYS_REBUILD = false // todo: remove this
 
 const makeGetBlock = (blocks) => async (address) => {
   const { cid, bytes } = await blocks.get(address)
@@ -16,13 +32,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 = []
@@ -41,7 +76,7 @@ const indexEntriesForChanges = (changes, mapFun) => {
 const indexEntriesForOldChanges = async (blocks, byIDindexRoot, ids, mapFun) => {
   const getBlock = makeGetBlock(blocks)
   const byIDindex = await load({ cid: byIDindexRoot.cid, get: getBlock, ...opts })
-  // console.trace('ids', ids)
+
   const result = await byIDindex.getMany(ids)
   return result.result
 }
@@ -52,7 +87,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 +95,7 @@ export default class DbIndex {
   constructor (database, mapFun) {
     /**
      * The database instance to DbIndex.
-     * @type {import('./fireproof').Fireproof}
+     * @type {Fireproof}
      */
     this.database = database
     /**
@@ -73,9 +108,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
@@ -116,26 +158,16 @@ export default class DbIndex {
           result.rows.map(({ key }) => key),
           this.mapFun
         )
-      )
-        // .map((key) => ({ key, value: null })) // tombstone just adds more rows...
-        .map((key) => ({ key, del: true })) // should be this
-      // .map((key) => ({ key: undefined, del: true })) // todo why does this work?
-
+      ).map((key) => ({ key, del: true })) // should be this
       this.indexRoot = await bulkIndex(blocks, this.indexRoot, oldIndexEntries, opts)
-      // console.x('oldIndexEntries', oldIndexEntries)
-      // [ { key: ['b', 1], del: true } ]
-      // [ { key: [ 5, 'x' ], del: true } ]
-      // for now we just let the by id DbIndex grow and then don't use the results...
-      // const removeByIdIndexEntries = oldIndexEntries.map(({ key }) => ({ key: key[1], del: true }))
-      // this.byIDindexRoot = await bulkIndex(blocks, this.byIDindexRoot, removeByIdIndexEntries, opts)
+      const removeByIdIndexEntries = oldIndexEntries.map(({ key }) => ({ key: key[1], del: true }))
+      this.byIDindexRoot = await bulkIndex(blocks, this.byIDindexRoot, removeByIdIndexEntries, opts)
     }
     const indexEntries = indexEntriesForChanges(result.rows, this.mapFun)
     const byIdIndexEntries = indexEntries.map(({ key }) => ({ key: key[1], value: key }))
-    // [{key:  'xxxx-3c3a-4b5e-9c1c-8c5c0c5c0c5c', value : [ 53, 'xxxx-3c3a-4b5e-9c1c-8c5c0c5c0c5c' ]}]
     this.byIDindexRoot = await bulkIndex(blocks, this.byIDindexRoot, byIdIndexEntries, opts)
     // console.log('indexEntries', indexEntries)
     this.indexRoot = await bulkIndex(blocks, this.indexRoot, indexEntries, opts)
-    // console.log('did DbIndex', this.indexRoot)
     this.dbHead = result.clock
   }
 
@@ -148,8 +180,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) {
@@ -157,37 +189,22 @@ async function bulkIndex (blocks, inRoot, indexEntries) {
   const putBlock = blocks.put.bind(blocks)
   const getBlock = makeGetBlock(blocks)
   if (!inRoot) {
-    // make a new DbIndex
-
     for await (const node of await create({ get: getBlock, list: indexEntries, ...opts })) {
       const block = await node.block
       await putBlock(block.cid, block.bytes)
       inRoot = block
     }
-    // console.x('created DbIndex', inRoot.cid)
     return inRoot
   } else {
-    // load existing DbIndex
-    // console.x('loading DbIndex', inRoot.cid)
     const DbIndex = await load({ cid: inRoot.cid, get: getBlock, ...opts })
-    // console.log('new indexEntries', indexEntries)
     const { root, blocks } = await DbIndex.bulk(indexEntries)
     for await (const block of blocks) {
       await putBlock(block.cid, block.bytes)
     }
-    // console.x('updated DbIndex', root.block.cid)
     return await root.block // if we hold the root we won't have to load every time
   }
 }
 
-/**
- * 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

@@ -161,7 +161,7 @@ export default class Fireproof {
   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 })
+    return await this.#putToProllyTree({ key: id, value: doc }, doc._clock)
   }
 
   /**
@@ -171,20 +171,37 @@ export default class Fireproof {
    * @memberof Fireproof
    * @instance
    */
-  async del (id) {
+  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 }) // 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 }, clock)
   }
 
   /**
    * 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 {Object<{key : string, value: any}>} event - the event to add
+   * @returns {Object<{ id: string, clock: CID[] }>} - The result of adding the event to storage
    */
-  async #putToProllyTree (event) {
+  async #putToProllyTree (event, clock = null) {
+    if (clock && JSON.stringify(clock) !== JSON.stringify(this.clock)) {
+      // 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.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,
@@ -203,8 +220,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)
@@ -230,16 +245,25 @@ export default class Fireproof {
    * 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 {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)
+  async get (key, opts = {}) {
+    let got
+    if (opts.clock) {
+      got = await get(this.blocks, opts.clock, key)
+    } else {
+      got = await get(this.blocks, this.clock, key)
+    }
     // this tombstone is temporary until we can get the prolly tree to delete
     if (got === null) {
       throw new Error('Not found')
     }
+    if (opts.mvcc === true) {
+      got._clock = this.clock
+    }
     got._id = key
     return got
   }
@@ -250,12 +274,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>}
  */

package/src/valet.js

@@ -32,9 +32,15 @@ export default class Valet {
       )
       if (this.uploadFunction) {
         // todo we can coalesce these into a single car file
-        for (const task of tasks) {
-          await this.uploadFunction(task.carCid, task.value)
-        }
+        return await this.withDB(async (db) => {
+          for (const task of tasks) {
+            await this.uploadFunction(task.carCid, task.value)
+            // update the indexedb to mark this car as no longer pending
+            const carMeta = await db.get('cidToCar', task.carCid)
+            delete carMeta.pending
+            await db.put('cidToCar', carMeta)
+          }
+        })
       }
       callback()
     })

package/test/fireproof.test.js

@@ -20,12 +20,73 @@ describe('Fireproof', () => {
   it('put and get document', async () => {
     assert(resp0.id, 'should have id')
     assert.equal(resp0.id, '1ef3b32a-3c3a-4b5e-9c1c-8c5c0c5c0c5c')
-
     const avalue = await database.get('1ef3b32a-3c3a-4b5e-9c1c-8c5c0c5c0c5c')
     assert.equal(avalue.name, 'alice')
     assert.equal(avalue.age, 42)
     assert.equal(avalue._id, '1ef3b32a-3c3a-4b5e-9c1c-8c5c0c5c0c5c')
   })
+  it('mvcc put and get document with _clock that matches', async () => {
+    assert(resp0.clock, 'should have clock')
+    assert.equal(resp0.clock[0].toString(), 'bafyreieth2ckopwivda5mf6vu76xwqvox3q5wsaxgbmxy2dgrd4hfuzmma')
+    const theDoc = await database.get('1ef3b32a-3c3a-4b5e-9c1c-8c5c0c5c0c5c')
+    theDoc._clock = database.clock
+    const put2 = await database.put(theDoc)
+    assert.equal(put2.id, '1ef3b32a-3c3a-4b5e-9c1c-8c5c0c5c0c5c')
+    assert.equal(put2.clock[0].toString(), 'bafyreida2c2ckhjfoz5ulmbbfe66ey4svvedrl4tzbvtoxags2qck7lj2i')
+  })
+  it('get should return an object instance that is not the same as the one in the db', async () => {
+    const theDoc = await database.get('1ef3b32a-3c3a-4b5e-9c1c-8c5c0c5c0c5c')
+    const theDoc2 = await database.get('1ef3b32a-3c3a-4b5e-9c1c-8c5c0c5c0c5c')
+    assert.notEqual(theDoc, theDoc2)
+    theDoc.name = 'really alice'
+    assert.equal(theDoc.name, 'really alice')
+    assert.equal(theDoc2.name, 'alice')
+  })
+  it('get with mvcc option', async () => {
+    const theDoc = await database.get('1ef3b32a-3c3a-4b5e-9c1c-8c5c0c5c0c5c', { mvcc: true })
+    assert(theDoc._clock, 'should have _clock')
+    assert.equal(theDoc._clock[0].toString(), 'bafyreieth2ckopwivda5mf6vu76xwqvox3q5wsaxgbmxy2dgrd4hfuzmma')
+  })
+  it('get from an old snapshot with mvcc option', async () => {
+    const ogClock = resp0.clock
+    const theDoc = await database.get('1ef3b32a-3c3a-4b5e-9c1c-8c5c0c5c0c5c')
+    theDoc.name = 'not alice'
+    const put2 = await database.put(theDoc)
+    assert.equal(put2.id, '1ef3b32a-3c3a-4b5e-9c1c-8c5c0c5c0c5c')
+    assert.notEqual(put2.clock.toString(), ogClock.toString())
+    const theDoc2 = await database.get('1ef3b32a-3c3a-4b5e-9c1c-8c5c0c5c0c5c', { clock: ogClock })
+    assert.equal(theDoc2.name, 'alice')
+  })
+  it('put and get document with _clock that does not match b/c the doc changed', async () => {
+    const theDoc = await database.get('1ef3b32a-3c3a-4b5e-9c1c-8c5c0c5c0c5c', { mvcc: true })
+    theDoc.name = 'not alice'
+    const put2 = await database.put(theDoc)
+    assert.equal(put2.id, '1ef3b32a-3c3a-4b5e-9c1c-8c5c0c5c0c5c')
+    assert.notEqual(put2.clock.toString(), theDoc._clock.toString())
+
+    const err = await database.put(theDoc).catch((err) => err)
+    assert.match(err.message, /MVCC conflict/)
+  })
+  it('put and get document with _clock that does not match b/c a different doc changed should succeed', async () => {
+    const theDoc = await database.get('1ef3b32a-3c3a-4b5e-9c1c-8c5c0c5c0c5c', { mvcc: true })
+    assert.equal(theDoc.name, 'alice')
+
+    const putAnotherDoc = await database.put({ nothing: 'to see here' })
+    assert.notEqual(putAnotherDoc.clock.toString(), theDoc._clock.toString())
+
+    const ok = await database.put({ name: "isn't alice", ...theDoc })
+    assert.equal(ok.id, '1ef3b32a-3c3a-4b5e-9c1c-8c5c0c5c0c5c')
+  })
+  it('put and get document with _clock that does not match b/c the doc was deleted', async () => {
+    const theDoc = await database.get('1ef3b32a-3c3a-4b5e-9c1c-8c5c0c5c0c5c', { mvcc: true })
+    assert.equal(theDoc.name, 'alice')
+    const del = await database.del(theDoc)
+    assert(del.id)
+    const err = await database.put(theDoc).catch((err) => err)
+    console.log('err', err)
+    assert.match(err.message, /MVCC conflict/)
+  })
+
   it('has a factory for making new instances with default settings', async () => {
     // TODO if you pass it an email it asks the local keyring, and if no key, does the email validation thing
     const db = await Fireproof.storage({ email: 'jchris@gmail.com' })

package/README.md

@@ -1,148 +0,0 @@
-# 🔥 Fireproof
-
-Fireproof is a realtime database for today's interactive applications. It uses immutable data and distributed protocols 
-to offer a new kind of database that:
-- can be embedded in any page or app, with a flexible data ownership model
-- scales without incurring developer costs, thanks to Filecoin
-- uses cryptographically verifiable protocols (what plants crave)
-
-Learn more about the concepts and architecture behind Fireproof [in our plan,](https://hackmd.io/@j-chris/SyoE-Plpj) or jump to the [quick start](#quick-start) for React and server-side examples.
-
-### Status
-
-Fireproof is alpha software, you should only use it if you are planning to contribute. For now, [check out our React TodoMVC implementation running in browser-local mode.](https://main--lucky-naiad-5aa507.netlify.app/) It demonstrates document persistence, index queries, and event subscriptions, and uses the [`useFireproof()` React hook.](https://github.com/jchris/fireproof/blob/main/examples/todomvc/src/hooks/useFireproof.js)
-
-[![Test](https://github.com/jchris/fireproof/actions/workflows/test.yml/badge.svg)](https://github.com/jchris/fireproof/actions/workflows/test.yml)
-[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)
-
-## Usage
-
-```js
-import Fireproof from 'fireproof';
-
-async function main() {
-  const database = new Fireproof();
-  const ok = await database.put({
-    name: 'alice',
-    age: 42
-  });
-  
-  const doc = await database.get(ok.id);
-  console.log(doc.name); // 'alice'
-}
-
-main();
-```
-
-## Features
-
-### Document Store
-
-A simple put, get, and delete interface for keeping track of all your JSON documents. Once your data is in Fireproof you can access it from any app or website. Fireproof document store uses MVCC versioning and Merkle clocks so you can always recover the version you are looking for.
-
-```js
-const { id, ref } = await database.put({
-    _id: 'three-thousand'
-    name: 'André',
-    age: 47
-});
-const doc = await database.get('three-thousand')
-// {
-//    _id  : 'three-thousand'
-//    _ref : CID(bafy84...agfw7)
-//    name : 'André',
-//    age  : 47
-// }
-```
-
-The `_ref` allows you to query a stable snapshot of that version of the database. Fireproof uses immutable data structures under the hood, so you can always rollback to old data. Files can be embedded anywhere in your document using IPFS links like `{"/":"bafybeih3e3zdiehbqfpxzpppxrb6kaaw4xkbqzyr2f5pwr5refq2te2ape"}`, with API sugar coming soon.
-
-### Flexible Indexes
-
-Fireproof indexes are defined by custom JavaScript functions that you write, allowing you to easily index and search your data in the way that works best for your application. Easily handle data variety and schema drift by normalizing any data to the desired index.
-
-```js
-const index = new Index(database, function (doc, map) {
-  map(doc.age, doc.name)
-})
-const { rows, ref } = await index.query({ range: [40, 52] })
-// [ { key: 42, value: 'alice', id: 'a1s3b32a-3c3a-4b5e-9c1c-8c5c0c5c0c5c' },
-//   { key: 47, value: 'André', id: 'three-thousand' } ]
-```
-
-### Realtime Updates
-
-Subscribe to query changes in your application, so your UI updates automatically. Use the supplied React hooks, our Redux connector, or simple function calls to be notified of relevant changes.
-
-```js
-const listener = new Listener(database, function(doc, emit) {
-  if (doc.type == 'member') {
-    emit('member')
-  }
-})
-listener.on('member', (id) => {
-  const doc = await db.get(id)
-  alert(`Member update ${doc.name}`)
-})
-```
-
-### Self-soverign Identity
-
-Fireproof is so easy to integrate with any site or app because you can get started right away, and set up an account later. By default users write to their own database copy, so you can get pretty far before you even have to think about API keys. [Authorization is via non-extractable keypair](https://ucan.xyz), like TouchID / FaceID.
-
-### Automatic Replication
-
-Documents changes are persisted to [Filecoin](https://filecoin.io) via [web3.storage](https://web3.storage), and made available over [IPFS] and on a global content delivery network. All you need to do to sync state is send a link to the latest database head, and Fireproof will take care of the rest. [Learn how to enable replication.](#status)
-
-### Cryptographic Proofs
-
-The [UCAN protocol](https://ucan.xyz) verifably links Fireproof updates to authorized agents via cryptographic proof chains. These proofs are portable like bearer tokens, but because invocations are signed by end-user device keys, UCAN proofs don't need to be hidden to be secure, allowing for delegation of service capabilities across devices and parties. Additionally, Fireproof's Merkle clocks and hash trees are immutable and self-validating, making merging changes safe and efficient. Fireproof makes cryptographic proofs available for all of it's operations, making it an ideal verfiable document database for smart contracts and other applications running in trustless environments. [Proof chains provide performance benefits as well](https://purrfect-tracker-45c.notion.site/Data-Routing-23c37b269b4c4c3dacb60d0077113bcb), by allowing recipients to skip costly I/O operations and instead cryptographically verify that changes contain all of the required context.
-
-## Limitations 💣
-
-### Security
-
-Until encryption support is enabled, all data written to Fireproof is public. There are no big hurdles for this feature but it's not ready yet.
-
-### Persistence
-
-Currently Fireproof writes transactions and proofs to in-memory [CAR files](https://ipld.io/specs/transport/car/carv2/) which are well suited for peer and cloud replication. Durability coming soon.
-
-### Pre-beta Software
-
-While the underlying data structures and libraries Fireproof uses are trusted with billions of dollars worth of data, Fireproof started in February of 2023. Results may vary.
-
-## Thanks 🙏
-
-Fireproof is a synthesis of work done by people in the web community over the years. I couldn't even begin to name all the folks who made pivotal contributions. Without npm, React, and VS Code all this would have taken so much longer. Thanks to everyone who supported me getting into database development via Apache CouchDB, one of the original document databases. The distinguishing work on immutable datastructures comes from the years of consideration [IPFS](https://ipfs.tech), [IPLD](https://ipld.io), and the [Filecoin APIs](https://docs.filecoin.io) have enjoyed.
-
-Thanks to Alan Shaw and Mikeal Rogers without whom this project would have never got started. The core Merkle hash-tree clock is based on [Alan's Pail](https://github.com/alanshaw/pail), and you can see the repository history goes all the way back to work begun as a branch of that repo. Mikeal wrote [the prolly trees implementation](https://github.com/mikeal/prolly-trees).
-
-## Quick Start
-
-Look in the `examples/` directory for projects using the database. It's not picky how you use it, but we want to provide convenient jumping off places. Think of the examples as great to fork when starting your next project.
-
-If are adding Fireproof to an existing page, just install it and try some operations.
-
-```
-npm install @fireproof/core
-```
-
-In your `app.js` or `app.tsx` file:
-
-```
-import { Fireproof } from '@fireproof/core'
-const fireproof = Fireproof.storage()
-const ok = await fireproof.put({ hello: 'world' })
-const doc = await fireproof.get(ok.id)
-```
-
-🤫 I like to drop a `window.fireproof = fireproof` in there as a development aid.
-
-# Contributing
-
-Feel free to join in. All welcome. [Open an issue](https://github.com/jchris/fireproof/issues)!
-
-# License
-
-Dual-licensed under [MIT or Apache 2.0](https://github.com/jchris/fireproof/blob/main/LICENSE.md)