@libp2p/fetch 1.0.10-bedfd0aa2 → 1.0.10-f0d2b52d0

package/README.md

@@ -1,3 +1,5 @@
+# @libp2p/fetch
+
 [![libp2p.io](https://img.shields.io/badge/project-libp2p-yellow.svg?style=flat-square)](http://libp2p.io/)
 [![Discuss](https://img.shields.io/discourse/https/discuss.libp2p.io/posts.svg?style=flat-square)](https://discuss.libp2p.io)
 [![codecov](https://img.shields.io/codecov/c/github/libp2p/js-libp2p.svg?style=flat-square)](https://codecov.io/gh/libp2p/js-libp2p)
@@ -7,6 +9,21 @@
 
 # About
 
+<!--
+
+!IMPORTANT!
+
+Everything in this README between "# About" and "# Install" is automatically
+generated and will be overwritten the next time the doc generator is run.
+
+To make changes to this section, please update the @packageDocumentation section
+of src/index.js or src/index.ts
+
+To experiment with formatting, please run "npm run docs" from the root of this
+repo and examine the changes made.
+
+-->
+
 An implementation of the Fetch protocol as described here: <https://github.com/libp2p/specs/tree/master/fetch>
 
 The fetch protocol is a simple protocol for requesting a value corresponding to a key from a peer.
@@ -16,6 +33,7 @@ The fetch protocol is a simple protocol for requesting a value corresponding to
 ```typescript
 import { createLibp2p } from 'libp2p'
 import { fetch } from '@libp2p/fetch'
+import { peerIdFromString } from '@libp2p/peer-id'
 
 const libp2p = await createLibp2p({
   services: {
@@ -23,19 +41,26 @@ const libp2p = await createLibp2p({
   }
 })
 
-// Given a key (as a string) returns a value (as a Uint8Array), or null if the key isn't found.
-// All keys must be prefixed my the same prefix, which will be used to find the appropriate key
-// lookup function.
-async function my_subsystem_key_lookup(key) {
+// Given a key (as a string) returns a value (as a Uint8Array), or undefined
+// if the key isn't found.
+// All keys must be prefixed my the same prefix, which will be used to find
+// the appropriate key lookup function.
+async function my_subsystem_key_lookup (key: string): Promise<Uint8Array | undefined> {
   // app specific callback to lookup key-value pairs.
+  return Uint8Array.from([0, 1, 2, 3, 4])
 }
 
-// Enable this peer to respond to fetch requests for keys that begin with '/my_subsystem_key_prefix/'
-libp2p.fetch.registerLookupFunction('/my_subsystem_key_prefix/', my_subsystem_key_lookup)
+// Enable this peer to respond to fetch requests for keys that begin with
+// '/my_subsystem_key_prefix/'
+libp2p.services.fetch.registerLookupFunction('/my_subsystem_key_prefix/', my_subsystem_key_lookup)
 
 const key = '/my_subsystem_key_prefix/{...}'
-const peerDst = PeerId.parse('Qmfoo...') // or Multiaddr instance
-const value = await libp2p.fetch(peerDst, key)
+const peerDst = peerIdFromString('Qmfoo...')
+
+// Load the value from the remote peer, timing out after 10s
+const value = await libp2p.services.fetch.fetch(peerDst, key, {
+  signal: AbortSignal.timeout(10_000)
+})
 ```
 
 # Install

package/dist/src/fetch.d.ts

@@ -39,7 +39,7 @@ export declare class Fetch implements Startable, FetchInterface {
      *
      * @example
      *
-     * ```js
+     * ```TypeScript
      * // ...
      * libp2p.fetchService.registerLookupFunction('/prefix', (key) => { ... })
      * ```
@@ -51,7 +51,7 @@ export declare class Fetch implements Startable, FetchInterface {
      *
      * @example
      *
-     * ```js
+     * ```TypeScript
      * // ...
      * libp2p.fetchService.unregisterLookupFunction('/prefix')
      * ```

package/dist/src/fetch.js

@@ -173,7 +173,7 @@ export class Fetch {
      *
      * @example
      *
-     * ```js
+     * ```TypeScript
      * // ...
      * libp2p.fetchService.registerLookupFunction('/prefix', (key) => { ... })
      * ```
@@ -190,7 +190,7 @@ export class Fetch {
      *
      * @example
      *
-     * ```js
+     * ```TypeScript
      * // ...
      * libp2p.fetchService.unregisterLookupFunction('/prefix')
      * ```

package/dist/src/index.d.ts

@@ -10,6 +10,7 @@
  * ```typescript
  * import { createLibp2p } from 'libp2p'
  * import { fetch } from '@libp2p/fetch'
+ * import { peerIdFromString } from '@libp2p/peer-id'
  *
  * const libp2p = await createLibp2p({
  *   services: {
@@ -17,19 +18,26 @@
  *   }
  * })
  *
- * // Given a key (as a string) returns a value (as a Uint8Array), or null if the key isn't found.
- * // All keys must be prefixed my the same prefix, which will be used to find the appropriate key
- * // lookup function.
- * async function my_subsystem_key_lookup(key) {
+ * // Given a key (as a string) returns a value (as a Uint8Array), or undefined
+ * // if the key isn't found.
+ * // All keys must be prefixed my the same prefix, which will be used to find
+ * // the appropriate key lookup function.
+ * async function my_subsystem_key_lookup (key: string): Promise<Uint8Array | undefined> {
  *   // app specific callback to lookup key-value pairs.
+ *   return Uint8Array.from([0, 1, 2, 3, 4])
  * }
  *
- * // Enable this peer to respond to fetch requests for keys that begin with '/my_subsystem_key_prefix/'
- * libp2p.fetch.registerLookupFunction('/my_subsystem_key_prefix/', my_subsystem_key_lookup)
+ * // Enable this peer to respond to fetch requests for keys that begin with
+ * // '/my_subsystem_key_prefix/'
+ * libp2p.services.fetch.registerLookupFunction('/my_subsystem_key_prefix/', my_subsystem_key_lookup)
  *
  * const key = '/my_subsystem_key_prefix/{...}'
- * const peerDst = PeerId.parse('Qmfoo...') // or Multiaddr instance
- * const value = await libp2p.fetch(peerDst, key)
+ * const peerDst = peerIdFromString('Qmfoo...')
+ *
+ * // Load the value from the remote peer, timing out after 10s
+ * const value = await libp2p.services.fetch.fetch(peerDst, key, {
+ *   signal: AbortSignal.timeout(10_000)
+ * })
  * ```
  */
 import type { AbortOptions, ComponentLogger, PeerId } from '@libp2p/interface';
@@ -62,9 +70,9 @@ export interface Fetch {
      *
      * @example
      *
-     * ```js
+     * ```TypeScript
      * // ...
-     * libp2p.fetchService.registerLookupFunction('/prefix', (key) => { ... })
+     * libp2p.services.fetch.registerLookupFunction('/prefix', (key) => { ... })
      * ```
      */
     registerLookupFunction(prefix: string, lookup: LookupFunction): void;
@@ -74,9 +82,9 @@ export interface Fetch {
      *
      * @example
      *
-     * ```js
+     * ```TypeScript
      * // ...
-     * libp2p.fetchService.unregisterLookupFunction('/prefix')
+     * libp2p.services.fetch.unregisterLookupFunction('/prefix')
      * ```
      */
     unregisterLookupFunction(prefix: string, lookup?: LookupFunction): void;

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC9E,OAAO,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAA;AAE9E,MAAM,WAAW,SAAS;IACxB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAE3B;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAA;CAC/C;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,SAAS,CAAA;IACpB,iBAAiB,EAAE,iBAAiB,CAAA;IACpC,MAAM,EAAE,eAAe,CAAA;CACxB;AAED,MAAM,WAAW,KAAK;IACpB;;OAEG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAA;IAEzF;;;;;;;;;;OAUG;IACH,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,IAAI,CAAA;IAEpE;;;;;;;;;;OAUG;IACH,wBAAwB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,cAAc,GAAG,IAAI,CAAA;CACxE;AAED,wBAAgB,KAAK,CAAE,IAAI,GAAE,SAAc,GAAG,CAAC,UAAU,EAAE,eAAe,KAAK,KAAK,CAEnF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC9E,OAAO,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAA;AAE9E,MAAM,WAAW,SAAS;IACxB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAE3B;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAA;CAC/C;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,SAAS,CAAA;IACpB,iBAAiB,EAAE,iBAAiB,CAAA;IACpC,MAAM,EAAE,eAAe,CAAA;CACxB;AAED,MAAM,WAAW,KAAK;IACpB;;OAEG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAA;IAEzF;;;;;;;;;;OAUG;IACH,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,IAAI,CAAA;IAEpE;;;;;;;;;;OAUG;IACH,wBAAwB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,cAAc,GAAG,IAAI,CAAA;CACxE;AAED,wBAAgB,KAAK,CAAE,IAAI,GAAE,SAAc,GAAG,CAAC,UAAU,EAAE,eAAe,KAAK,KAAK,CAEnF"}

package/dist/src/index.js

@@ -10,6 +10,7 @@
  * ```typescript
  * import { createLibp2p } from 'libp2p'
  * import { fetch } from '@libp2p/fetch'
+ * import { peerIdFromString } from '@libp2p/peer-id'
  *
  * const libp2p = await createLibp2p({
  *   services: {
@@ -17,19 +18,26 @@
  *   }
  * })
  *
- * // Given a key (as a string) returns a value (as a Uint8Array), or null if the key isn't found.
- * // All keys must be prefixed my the same prefix, which will be used to find the appropriate key
- * // lookup function.
- * async function my_subsystem_key_lookup(key) {
+ * // Given a key (as a string) returns a value (as a Uint8Array), or undefined
+ * // if the key isn't found.
+ * // All keys must be prefixed my the same prefix, which will be used to find
+ * // the appropriate key lookup function.
+ * async function my_subsystem_key_lookup (key: string): Promise<Uint8Array | undefined> {
  *   // app specific callback to lookup key-value pairs.
+ *   return Uint8Array.from([0, 1, 2, 3, 4])
  * }
  *
- * // Enable this peer to respond to fetch requests for keys that begin with '/my_subsystem_key_prefix/'
- * libp2p.fetch.registerLookupFunction('/my_subsystem_key_prefix/', my_subsystem_key_lookup)
+ * // Enable this peer to respond to fetch requests for keys that begin with
+ * // '/my_subsystem_key_prefix/'
+ * libp2p.services.fetch.registerLookupFunction('/my_subsystem_key_prefix/', my_subsystem_key_lookup)
  *
  * const key = '/my_subsystem_key_prefix/{...}'
- * const peerDst = PeerId.parse('Qmfoo...') // or Multiaddr instance
- * const value = await libp2p.fetch(peerDst, key)
+ * const peerDst = peerIdFromString('Qmfoo...')
+ *
+ * // Load the value from the remote peer, timing out after 10s
+ * const value = await libp2p.services.fetch.fetch(peerDst, key, {
+ *   signal: AbortSignal.timeout(10_000)
+ * })
  * ```
  */
 import { Fetch as FetchClass } from './fetch.js';

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAE,KAAK,IAAI,UAAU,EAAE,MAAM,YAAY,CAAA;AA0DhD,MAAM,UAAU,KAAK,CAAE,OAAkB,EAAE;IACzC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,IAAI,UAAU,CAAC,UAAU,EAAE,IAAI,CAAC,CAAA;AACzD,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,EAAE,KAAK,IAAI,UAAU,EAAE,MAAM,YAAY,CAAA;AA0DhD,MAAM,UAAU,KAAK,CAAE,OAAkB,EAAE;IACzC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,IAAI,UAAU,CAAC,UAAU,EAAE,IAAI,CAAC,CAAA;AACzD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@libp2p/fetch",
-  "version": "1.0.10-bedfd0aa2",
+  "version": "1.0.10-f0d2b52d0",
   "description": "Implementation of the Fetch Protocol",
   "license": "Apache-2.0 OR MIT",
   "homepage": "https://github.com/libp2p/js-libp2p/tree/main/packages/protocol-fetch#readme",
@@ -48,20 +48,21 @@
     "test:firefox": "aegir test -t browser -- --browser firefox",
     "test:firefox-webworker": "aegir test -t webworker -- --browser firefox",
     "test:node": "aegir test -t node --cov",
-    "dep-check": "aegir dep-check"
+    "dep-check": "aegir dep-check",
+    "doc-check": "aegir doc-check"
   },
   "dependencies": {
-    "@libp2p/interface": "1.1.3-bedfd0aa2",
-    "@libp2p/interface-internal": "1.0.8-bedfd0aa2",
+    "@libp2p/interface": "1.1.3-f0d2b52d0",
+    "@libp2p/interface-internal": "1.0.8-f0d2b52d0",
     "it-protobuf-stream": "^1.1.2",
     "protons-runtime": "^5.4.0",
     "uint8arraylist": "^2.4.8",
-    "uint8arrays": "^5.0.1"
+    "uint8arrays": "^5.0.2"
   },
   "devDependencies": {
-    "@libp2p/logger": "4.0.6-bedfd0aa2",
-    "@libp2p/peer-id-factory": "4.0.6-bedfd0aa2",
-    "aegir": "^42.2.3",
+    "@libp2p/logger": "4.0.6-f0d2b52d0",
+    "@libp2p/peer-id-factory": "4.0.6-f0d2b52d0",
+    "aegir": "^42.2.4",
     "it-pair": "^2.0.6",
     "protons": "^7.5.0",
     "sinon": "^17.0.1",

package/src/fetch.ts

@@ -195,7 +195,7 @@ export class Fetch implements Startable, FetchInterface {
    *
    * @example
    *
-   * ```js
+   * ```TypeScript
    * // ...
    * libp2p.fetchService.registerLookupFunction('/prefix', (key) => { ... })
    * ```
@@ -214,7 +214,7 @@ export class Fetch implements Startable, FetchInterface {
    *
    * @example
    *
-   * ```js
+   * ```TypeScript
    * // ...
    * libp2p.fetchService.unregisterLookupFunction('/prefix')
    * ```

package/src/index.ts

@@ -10,6 +10,7 @@
  * ```typescript
  * import { createLibp2p } from 'libp2p'
  * import { fetch } from '@libp2p/fetch'
+ * import { peerIdFromString } from '@libp2p/peer-id'
  *
  * const libp2p = await createLibp2p({
  *   services: {
@@ -17,19 +18,26 @@
  *   }
  * })
  *
- * // Given a key (as a string) returns a value (as a Uint8Array), or null if the key isn't found.
- * // All keys must be prefixed my the same prefix, which will be used to find the appropriate key
- * // lookup function.
- * async function my_subsystem_key_lookup(key) {
+ * // Given a key (as a string) returns a value (as a Uint8Array), or undefined
+ * // if the key isn't found.
+ * // All keys must be prefixed my the same prefix, which will be used to find
+ * // the appropriate key lookup function.
+ * async function my_subsystem_key_lookup (key: string): Promise<Uint8Array | undefined> {
  *   // app specific callback to lookup key-value pairs.
+ *   return Uint8Array.from([0, 1, 2, 3, 4])
  * }
  *
- * // Enable this peer to respond to fetch requests for keys that begin with '/my_subsystem_key_prefix/'
- * libp2p.fetch.registerLookupFunction('/my_subsystem_key_prefix/', my_subsystem_key_lookup)
+ * // Enable this peer to respond to fetch requests for keys that begin with
+ * // '/my_subsystem_key_prefix/'
+ * libp2p.services.fetch.registerLookupFunction('/my_subsystem_key_prefix/', my_subsystem_key_lookup)
  *
  * const key = '/my_subsystem_key_prefix/{...}'
- * const peerDst = PeerId.parse('Qmfoo...') // or Multiaddr instance
- * const value = await libp2p.fetch(peerDst, key)
+ * const peerDst = peerIdFromString('Qmfoo...')
+ *
+ * // Load the value from the remote peer, timing out after 10s
+ * const value = await libp2p.services.fetch.fetch(peerDst, key, {
+ *   signal: AbortSignal.timeout(10_000)
+ * })
  * ```
  */
 
@@ -70,9 +78,9 @@ export interface Fetch {
    *
    * @example
    *
-   * ```js
+   * ```TypeScript
    * // ...
-   * libp2p.fetchService.registerLookupFunction('/prefix', (key) => { ... })
+   * libp2p.services.fetch.registerLookupFunction('/prefix', (key) => { ... })
    * ```
    */
   registerLookupFunction(prefix: string, lookup: LookupFunction): void
@@ -83,9 +91,9 @@ export interface Fetch {
    *
    * @example
    *
-   * ```js
+   * ```TypeScript
    * // ...
-   * libp2p.fetchService.unregisterLookupFunction('/prefix')
+   * libp2p.services.fetch.unregisterLookupFunction('/prefix')
    * ```
    */
   unregisterLookupFunction(prefix: string, lookup?: LookupFunction): void