hypercore 10.0.0-alpha.5 → 10.0.0-alpha.50

package/README.md

@@ -62,13 +62,19 @@ Note that `tree`, `data`, and `bitfield` are normally heavily sparse files.
 {
   createIfMissing: true, // create a new Hypercore key pair if none was present in storage
   overwrite: false, // overwrite any old Hypercore that might already exist
+  sparse: true, // enable sparse mode, counting unavailable blocks towards core.length and core.byteLength
   valueEncoding: 'json' | 'utf-8' | 'binary', // defaults to binary
-  keyPair: kp // optionally pass the public key and secret key as a key pair
+  encodeBatch: batch => { ... }, // optionally apply an encoding to complete batches
+  keyPair: kp, // optionally pass the public key and secret key as a key pair
+  encryptionKey: k, // optionally pass an encryption key to enable block encryption
+  onwait: () => {} // hook that is called if gets are waiting for download
 }
 ```
 
 You can also set valueEncoding to any [abstract-encoding](https://github.com/mafintosh/abstract-encoding) or [compact-encoding](https://github.com/compact-encoding) instance.
 
+valueEncodings will be applied to individually blocks, even if you append batches. If you want to control encoding at the batch-level, you can use the `encodeBatch` option, which is a function that takes a batch and returns a binary-encoded batch. If you provide a custom valueEncoding, it will not be applied prior to `encodeBatch`.
+
 #### `const seq = await core.append(block)`
 
 Append a block of data (or an array of blocks) to the core.
@@ -83,7 +89,7 @@ Options include
 
 ``` js
 {
-  wait: true, // wait for index to be downloaded
+  wait: true, // wait for block to be downloaded
   onwait: () => {}, // hook that is called if the get is waiting for download
   timeout: 0, // wait at max some milliseconds (0 means no timeout)
   valueEncoding: 'json' | 'utf-8' | 'binary' // defaults to the core's valueEncoding
@@ -97,6 +103,23 @@ Truncate the core to a smaller length.
 Per default this will update the fork id of the core to `+ 1`, but you can set the fork id you prefer with the option.
 Note that the fork id should be monotonely incrementing.
 
+#### `const hash = await core.treeHash([length])`
+
+Get the Merkle Tree hash of the core at a given length, defaulting to the current length of the core.
+
+#### `const stream = core.createReadStream([options])`
+
+Make a read stream. Options include:
+
+``` js
+{
+  start: 0,
+  end: core.length,
+  live: false,
+  snapshot: true // auto set end to core.length on open or update it on every read
+}
+```
+
 #### `const range = core.download([range])`
 
 Download a range of data.
@@ -113,6 +136,7 @@ A range can have the following properties:
 {
   start: startIndex,
   end: nonInclusiveEndIndex,
+  blocks: [index1, index2, ...],
   linear: false // download range linearly and not randomly
 }
 ```
@@ -125,6 +149,12 @@ To download the full core continously (often referred to as non sparse mode) do
 core.download({ start: 0, end: -1 })
 ```
 
+To downloaded a discrete range of blocks pass a list of indices.
+
+```js
+core.download({ blocks: [4, 9, 7] });
+```
+
 To cancel downloading a range simply destroy the range instance.
 
 ``` js
@@ -188,6 +218,12 @@ Buffer containing the public key identifying this core.
 
 Populated after `ready` has been emitted. Will be `null` before the event.
 
+#### `core.keyPair`
+
+Object containing buffers of the core's public and secret key
+
+Populated after `ready` has been emitted. Will be `null` before the event.
+
 #### `core.discoveryKey`
 
 Buffer containing a key derived from the core's public key.
@@ -195,15 +231,31 @@ In contrast to `core.key` this key does not allow you to verify the data but can
 
 Populated after `ready` has been emitted. Will be `null` before the event.
 
+#### `core.encryptionKey`
+
+Buffer containing the optional block encryption key of this core. Will be `null` unless block encryption is enabled.
+
 #### `core.length`
 
-How many blocks of data are available on this core?
+How many blocks of data are available on this core? If `sparse: false`, this will equal `core.contiguousLength`.
 
 Populated after `ready` has been emitted. Will be `0` before the event.
 
 #### `core.byteLength`
 
-How much data is available on this core in bytes?
+How much data is available on this core in bytes? If `sparse: false`, this will equal `core.contiguousByteLength`.
+
+Populated after `ready` has been emitted. Will be `0` before the event.
+
+#### `core.contiguousLength`
+
+How many blocks are contiguously available starting from the first block of this core?
+
+Populated after `ready` has been emitted. Will be `0` before the event.
+
+#### `core.contiguousByteLength`
+
+How much data is contiguously available starting from the first block of this core?
 
 Populated after `ready` has been emitted. Will be `0` before the event.
 
@@ -213,6 +265,10 @@ What is the current fork id of this core?
 
 Populated after `ready` has been emitted. Will be `0` before the event.
 
+#### `core.padding`
+
+How much padding is applied to each block of this core? Will be `0` unless block encryption is enabled.
+
 #### `const stream = core.replicate(isInitiatorOrReplicationStream)`
 
 Create a replication stream. You should pipe this to another Hypercore instance.
@@ -238,10 +294,17 @@ const socket = net.connect(...)
 socket.pipe(localCore.replicate(true)).pipe(socket)
 ```
 
+#### `const done = core.findingPeers()`
+
+Create a hook that tells Hypercore you are finding peers for this core in the background. Call `done` when your current discovery iteration is done.
+If you're using Hyperswarm, you'd normally call this after a `swarm.flush()` finishes.
+
+This allows `core.update` to wait for either the `findingPeers` hook to finish or one peer to appear before deciding whether it should wait for a merkle tree update before returning.
+
 #### `core.on('append')`
 
 Emitted when the core has been appended to (i.e. has a new length / byteLength), either locally or remotely.
 
-#### `core.on('truncate')`
+#### `core.on('truncate', ancestors, forkId)`
 
 Emitted when the core has been truncated, either locally or remotely.