hypercore-storage 1.0.1 → 1.0.3

package/README.md

@@ -10,7 +10,198 @@ npm install hypercore-storage
 
 The following API is what Hypercore 11 binds to to do I/O.
 
-TODO
+```js
+const Storage = require('hypercore-storage')
+```
+
+#### `store = new Storage(dbOrPath)`
+
+Make a new storage engine.
+
+#### `core = await store.create({ key, discoveyKey, manifest?, keyPair?, encryptionKey?, userData? })`
+
+Create a new core, returns a storage instance for that core.
+
+#### `core = await store.resume(discoveryKey)`
+
+Resume a previously make core. If it doesn't exist it returns `null`.
+
+#### `atom = store.createAtom()`
+
+Primitive for making atomic batches across ops. See below for `core.atomize` on how to use it.
+When you wanna flush your changes to the underlying storage, use `await atom.flush()`.
+
+Internally to "listen" for when that happens you can add an sync hook with `atom.onflush(fn)`
+
+#### `bool = await store.has(discoveryKey)`
+
+Check if a core exists.
+
+#### `stream = store.createCoreStream()`
+
+List all cores. Stream data looks like this `{ discoveryKey, core }` where core contains the core header.
+
+#### `await store.close()`
+
+Close the storage instance.
+
+#### `rx = core.read()`
+
+Make a read batch on a core storage.
+
+**NOTE:** a read batch DOES NOT flush until you call `rx.tryFlush()`.
+
+#### `await rx.getAuth()`
+
+Returns the auth data around a core.
+
+#### `await rx.getHead()`
+
+Returns the head of the merkle tree.
+
+#### `await rx.getSessions()`
+
+Returns an array of all named sessions.
+
+#### `await rx.getDependency()`
+
+Returns the core this has a dependency on.
+
+#### `await rx.getHints()`
+
+Returns the various storage/replication hints.
+
+#### `await rx.getBlock(index)`
+
+Returns a block stored.
+
+#### `await rx.getTreeNode(index)`
+
+Returns a tree node stored.
+
+#### `await rx.getBitfieldPage(index)`
+
+Return a bitfield page.
+
+#### `await rx.getUserData(key)`
+
+Return a user stored buffer.
+
+#### `rx.tryFlush()`
+
+Flushes the read batch, non of the above promises will resolve until you call this.
+
+#### `tx = core.write()`
+
+Make a write batch on a core storage.
+
+**NOTE:** all the apis below are sync as they just buffer mutations until you flush them.
+
+#### `tx.setAuth(auth)`
+
+Set the auth data around a core.
+
+#### `tx.setHead(auth)`
+
+Set the head of the merkle tree.
+
+#### `tx.setSessions(sessions)`
+
+Set an array of all named sessions.
+
+#### `tx.setDependency(dep)`
+
+Set the core this has a dependency on.
+
+#### `tx.setHints(hints)`
+
+Set the various storage/replication hints.
+
+#### `tx.putBlock(index, buffer)`
+
+Put a block at a specific index.
+
+#### `tx.deleteBlock(index)`
+
+Delete a block at a specific index.
+
+#### `tx.deleteBlockRange(start, index)`
+
+Delete blocks between two indexes.
+
+#### `tx.putTreeNode(node)`
+
+Put a tree node (at its described index).
+
+#### `tx.deleteTreeNode(index)`
+
+Delete a tree node at a specific index.
+
+#### `tx.deleteTreeNodeRange(start, index)`
+
+Delete blocks between two tree indexes.
+
+#### `tx.putBitfieldPage(index, page)`
+
+Put a bitfield page at its described index.
+
+#### `tx.deleteBitfieldPage(index)`
+
+Delete a bitfield page.
+
+#### `tx.deleteBitfieldPageRange(start, end)`
+
+Delete bitfield pages between two indexes.
+
+#### `tx.putUserData(key, value)`
+
+Put a user provided buffer at a user provided key.
+
+#### `tx.deleteUserData(key)`
+
+Delete a user provided key.
+
+#### `await tx.flush()`
+
+Flushes the write batch.
+
+#### `stream = core.createBlockStream(opts)`
+
+Create a stream of all blocks.
+
+#### `stream = core.createTreeNodeStream(opts)`
+
+Create a stream of all tree nodes.
+
+#### `stream = core.createBitfieldStream(opts)`
+
+Create a stream of all bitfield pages.
+
+#### `stream = core.createUserDataStream(opts)`
+
+Create a stream of all user data.
+
+#### `await core.close()`
+
+Close the core storage engine.
+
+#### `atom = core.createAtom()`
+
+Same as `store.createAtom()` but here again for conveinience.
+
+#### `core = core.atomize(atom)`
+
+Atomize a core. Allows you to build up cross core atomic batches and operations.
+An atomized core will not flush its changes until you call `atom.flush()`, but you can still read your writes.
+
+#### `core = core.createSession(name, head)`
+
+Create a named session on top of a core. A named session points back to the previous storage,
+but is otherwise independent and stored on disk, like a branch in git if you will.
+
+#### `core.dependencies`
+
+Array containing the full list of dependencies for this core (ie tree of named sessions).
 
 ## License
 

package/index.js

@@ -40,19 +40,19 @@ class Atom {
     this.view.reset()
 
     const promises = []
-    while (this.flushes.length) promises.push(this.flushes.pop()())
+    for (let i = 0; i < this.flushes.length; i++) promises.push(this.flushes[i]())
 
     await Promise.all(promises)
   }
 }
 
 class HypercoreStorage {
-  constructor (store, db, core, view, atomic) {
+  constructor (store, db, core, view, atom) {
     this.store = store
     this.db = db
     this.core = core
     this.view = view
-    this.atomic = atomic
+    this.atom = atom
 
     this.view.readStart()
   }
@@ -95,15 +95,15 @@ class HypercoreStorage {
   }
 
   snapshot () {
-    return new HypercoreStorage(this.store, this.db.snapshot(), this.core, this.view.snapshot(), this.atomic)
+    return new HypercoreStorage(this.store, this.db.snapshot(), this.core, this.view.snapshot(), this.atom)
   }
 
   atomize (atom) {
-    return new HypercoreStorage(this.store, this.db.session(), this.core, atom.view, true)
+    return new HypercoreStorage(this.store, this.db.session(), this.core, atom.view, atom)
   }
 
-  atom () {
-    return this.store.atom()
+  createAtom () {
+    return this.store.createAtom()
   }
 
   createBlockStream (opts) {
@@ -149,11 +149,11 @@ class HypercoreStorage {
     const dependency = await dependencyPromise
     if (dependency) core.dependencies = this._addDependency(dependency)
 
-    return new HypercoreStorage(this.store, this.db.session(), core, this.atomic ? this.view : new View(), this.atomic)
+    return new HypercoreStorage(this.store, this.db.session(), core, this.atom ? this.view : new View(), this.atom)
   }
 
-  async createSession (name, head, atom) {
-    const rx = this.read(atom)
+  async createSession (name, head) {
+    const rx = this.read()
 
     const existingSessionsPromise = rx.getSessions()
     const existingHeadPromise = rx.getHead()
@@ -174,7 +174,7 @@ class HypercoreStorage {
       session.dataPointer = await this.store._allocData()
     }
 
-    const tx = this.write(atom)
+    const tx = this.write()
 
     tx.setSessions(sessions)
 
@@ -193,7 +193,7 @@ class HypercoreStorage {
 
     await tx.flush()
 
-    return new HypercoreStorage(this.store, this.db.session(), core, atom ? atom.view : this.atomic ? this.view : new View(), !!atom || this.atomic)
+    return new HypercoreStorage(this.store, this.db.session(), core, this.atom ? this.view : new View(), this.atom)
   }
 
   async createAtomicSession (atom, head) {
@@ -233,12 +233,12 @@ class HypercoreStorage {
     return deps
   }
 
-  read (atom) {
-    return new CoreRX(this.core, this.db, atom ? atom.view : this.view)
+  read () {
+    return new CoreRX(this.core, this.db, this.view)
   }
 
-  write (atom) {
-    return new CoreTX(this.core, this.db, atom ? atom.view : this.atomic ? this.view : null, [])
+  write () {
+    return new CoreTX(this.core, this.db, this.atom ? this.view : null, [])
   }
 
   close () {
@@ -429,7 +429,7 @@ class CorestoreStorage {
     return head === null ? initStoreHead() : head
   }
 
-  atom () {
+  createAtom () {
     return new Atom(this.db)
   }
 
@@ -585,7 +585,7 @@ class CorestoreStorage {
       dataPointer = dependency.dataPointer
     }
 
-    const result = new HypercoreStorage(this, this.db.session(), core, EMPTY, false)
+    const result = new HypercoreStorage(this, this.db.session(), core, EMPTY, null)
 
     if (result.core.version === 0) await this._migrateCore(result, discoveryKey, create)
     return result
@@ -635,7 +635,7 @@ class CorestoreStorage {
 
     tx.apply()
 
-    return new HypercoreStorage(this, this.db.session(), ptr, EMPTY, false)
+    return new HypercoreStorage(this, this.db.session(), ptr, EMPTY, null)
   }
 
   async create (data) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hypercore-storage",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "main": "index.js",
   "files": [
     "index.js",

package/spec/hyperschema/index.js

@@ -401,8 +401,8 @@ const encoding13 = {
   }
 }
 
-// @core/sessions
-const encoding14 = c.array({
+// @core/session
+const encoding14 = {
   preencode (state, m) {
     c.string.preencode(state, m.name)
     c.uint.preencode(state, m.dataPointer)
@@ -420,10 +420,13 @@ const encoding14 = c.array({
       dataPointer: r1
     }
   }
-})
+}
+
+// @core/sessions
+const encoding15 = c.array(encoding14)
 
 // @core/dependency
-const encoding15 = {
+const encoding16 = {
   preencode (state, m) {
     c.uint.preencode(state, m.dataPointer)
     c.uint.preencode(state, m.length)
@@ -481,8 +484,9 @@ function getEncoding (name) {
     case '@core/auth': return encoding11
     case '@core/head': return encoding12
     case '@core/hints': return encoding13
-    case '@core/sessions': return encoding14
-    case '@core/dependency': return encoding15
+    case '@core/session': return encoding14
+    case '@core/sessions': return encoding15
+    case '@core/dependency': return encoding16
     default: throw new Error('Encoder not found ' + name)
   }
 }