@dxos/feed-store 2.32.1-dev.77d63563 → 2.32.1-dev.e93af3d9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/feed-store",
-  "version": "2.32.1-dev.77d63563",
+  "version": "2.32.1-dev.e93af3d9",
   "description": "A consistent store for your hypercore feeds.",
   "license": "MIT",
   "main": "dist/src/index.js",
@@ -10,8 +10,8 @@
     "dist"
   ],
   "dependencies": {
-    "@dxos/async": "2.32.1-dev.77d63563",
-    "@dxos/util": "2.32.1-dev.77d63563",
+    "@dxos/async": "2.32.1-dev.e93af3d9",
+    "@dxos/util": "2.32.1-dev.e93af3d9",
     "buffer-json-encoding": "^1.0.2",
     "debug": "^4.3.3",
     "end-of-stream": "^1.4.1",
@@ -24,10 +24,10 @@
   "devDependencies": {
     "@dxos/benchmark-suite": "^1.0.0-beta.1",
     "@dxos/browser-runner": "^1.0.0-beta.13",
-    "@dxos/crypto": "2.32.1-dev.77d63563",
+    "@dxos/crypto": "2.32.1-dev.e93af3d9",
     "@dxos/eslint-plugin": "~1.0.27",
     "@dxos/protocols-toolchain": "2.32.0",
-    "@dxos/random-access-multi-storage": "2.32.1-dev.77d63563",
+    "@dxos/random-access-multi-storage": "2.32.1-dev.e93af3d9",
     "@types/debug": "^4.1.7",
     "@types/end-of-stream": "^1.4.0",
     "@types/from2": "~2.3.1",
@@ -54,6 +54,5 @@
     "build:test": "toolchain build:test",
     "lint": "toolchain lint",
     "test": "toolchain test"
-  },
-  "readme": "# FeedStore\n\n> A consistent store for your hypercore feeds.\n\nFeedStore was created to administrate your hypercore feeds in a similar abstraction to work with files in a FileSystem.\n\nEach feed created by FeedStore works with an underlying object `descriptor` which provides additional information about the feed and how to work with it.\n\nFeatures:\n- Open/Close hypercore feeds.\n- Load hypercore feeds by demand.\n- Persist feeds metadata into a hypertrie database.\n- Search feeds by a path or any property related to the feed.\n- Add metadata to your feed.\n- Support for multiple codecs.\n\n## Install\n\n```\n$ npm install @dxos/feed-store\n```\n\n## Usage\n\n```javascript\nimport { FeedStore } from '@dxos/feed-store';\nimport { PublicKey, createKeyPair } from '@dxos/crypto';\n\n(async () => {\n  const feedStore = new FeedStore('./db', {\n    feedOptions: { valueEncoding: 'utf-8' }\n  });\n  await feedStore.open();\n\n  // Create a writebale feed.\n  const keypair1 = createKeyPair();\n  const foo = await feedStore.createReadWriteFeed({\n    key: PublicKey.from(keypair1.publicKey),\n    secretKey: keypair1.secretKey\n  });\n\n  foo.append('foo', () => {\n    foo.head(console.log);\n  });\n\n  // You can open a feed with custom hypercore options.\n  const keypair2 = createKeyPair();\n  const bar = await feedStore.createReadWriteFeed({\n    key: PublicKey.from(keypair2.publicKey),\n    secretKey: keypair2.secretKey\n    valueEncoding: 'json',\n    metadata: { tag: 'bar' } // Save serializable feed metadata.\n  });\n})();\n```\n\n## API\n\n#### `const feedStore = new FeedStore(storage, [options])`\n\n- `storage: RandomAccessStorage`: Storage used by the feeds to store their data.\n- `options`:\n  - `database: () => Hypertrie`: Defines a custom hypertrie database to index the feeds.\n  - `feedOptions: Object`: Default hypercore options for each feed.\n  - `codecs: Object`: Defines a list of available codecs to work with the feeds.\n  - `hypercore: Hypercore`: Defines the Hypercore class to create feeds.\n\nCreates a new FeedStore `without wait for their initialization.`\n\n> The initialization happens by running: `await feedStore.open()`\n\n#### `feedStore.openFeed(key) -> Promise<Hypercore>`\n\nCreates a new hypercore feed identified by a string path.\n\n> If the feed exists but is not loaded it will load the feed instead of creating a new one.\n\n- `path: string`: A require name to identify and index the feed to open.\n- `options: Object`: Feed options.\n  - `metadata: *`: Serializable value with custom data about the feed.\n  - `[...hypercoreOptions]`: Hypercore options.\n\n#### `feedStore.closeFeed(key) -> Promise`\n\nClose a feed by the path.\n\n#### `feedStore.deleteDescriptor(key) -> Promise`\n\nRemove a descriptor from the database by the path.\n\n> This operation would not close the feed.\n\n#### `feedStore.close() -> Promise`\n\nClose the hypertrie database and their feeds.\n\n#### `feedStore.openFeeds((descriptor) => Boolean) -> Promise<Hypercore[]>`\n\nOpen multiple feeds using a function to filter what feeds you want to load from the database.\n\n```javascript\nconst feeds = await feedStore.openFeeds(descriptor => descriptor.metadata.tag === 'foo')\n```\n\n#### `feedStore.ready() -> Promise`\n\nWait for feedStore to be ready.\n\n#### `FeedDescriptor`\n\nFor each feed created, FeedStore maintain `FeedDescriptor` object.\n\nA `FeedDescriptor` provides the next information:\n\n- `key: PublicKey`\n- `secretKey: Buffer`\n- `discoveryKey: Buffer`\n- `feed: (Hypercore|null)`\n- `opened: Boolean`\n- `valueEncoding: string|Codec`\n- `metadata: *`\n\n#### `feedStore.getDescriptors() -> FeedDescriptor[]`\n\nReturns a list of descriptors.\n\n#### `feedStore.getDescriptorByDiscoveryKey(discoveryKey) -> FeedDescriptor`\n\nFast access to get a descriptor.\n\n#### `feedStore.getOpenFeeds([descriptor => Boolean]) -> Hypercore[]`\n\nReturns a list of opened hypercore feeds, with optional filter.\n\n- `descriptor: FeedDescriptor`\n\n#### `feedStore.getOpenFeed(descriptor => Boolean) -> Hypercore[]`\n\nFind an opened feed using a filter callback.\n\n- `descriptor: FeedDescriptor`\n\n#### `feedStore.createReadStream([callback|options]) -> ReadableStream`\n\nCreates a ReadableStream from the loaded feeds.\n\n- `options: Object`: Default options for each feed.createReadStream(options). Optional.\n  - `batch: Number`: Defines the batch number of blocks to read in each iteration. Default: 100.\n  - `live: Boolean`: Defines the stream as a live stream. Will wait for new incoming data. Default: false.\n- `callback: descriptor => Promise<(Object|undefined)>`: Filter function to return options for each feed.createReadStream(). Returns `undefined` will ignore the feed. Optional.\n- `descriptor: FeedDescriptor`\n\nThe data returned will be an object with:\n\n- `data: Buffer`: The original chunk of the block data.\n- `seq: Number`: Sequence number of the read block.\n- `key: Buffer`: Key of the read feed.\n- `path: String`: FeedStore path of the read feed.\n- `metadata: Object`: FeedStore metadata of the read feed.\n- `sync: Boolean`: It reports if the current feed stream is sync.\n\nUsage:\n\n```javascript\n\n// Live streaming from all the opened feeds.\nconst stream = feedStore.createReadStream({ live: true })\n\n// Live streaming, from feeds filter by tag === 'foo'\nconst stream = feedStore.createReadStream({ live: true }, ({ metadata }) => {\n  return metadata.tag === 'foo';\n})\n\n// Live streaming, from feeds tag === 'foo'\nconst stream = feedStore.createReadStream(({ metadata }) => {\n  if (metadata.tag === 'foo') {\n    return { live: true, start: 10 } // Start reading from index 10.\n  }\n})\n```\n\n#### `feedStore.createBatchStream([callback|options]) -> ReadableStream`\n\nAlmost equal to `createReadStream` but the batch messages will be returned in a single array of messages.\n\n### Events\n\n#### `feedStore.on('ready', () => {})`\n\nEmitted when feedStore is loaded.\n\n#### `feedStore.on('append', (feed, descriptor) => {})`\n\nEmitted after an append in any of the loaded feeds.\n\n- `feed: Hypercore`\n- `descriptor: FeedDescriptor`\n\n#### `feedStore.on('download', (index, data, feed, descriptor) => {})`\n\nEmitted after a feed download event.\n\n- `index: number` Block index.\n- `data: Buffer`\n- `feed: Hypercore`\n- `descriptor: FeedDescriptor`\n\n#### `feedStore.on('feed', (feed, descriptor) => {})`\n\nEmitted when a feed is loaded.\n\n- `feed: Hypercore`\n- `descriptor: FeedDescriptor`\n\n## Contributing\n\nPRs accepted.\n\n## License\n\nGPL-3.0 © dxos\n"
+  }
 }