@helia/interface 0.0.0-ab0a451 → 0.0.0-d15d76c

package/dist/src/index.d.ts

@@ -17,8 +17,10 @@ import type { Libp2p } from '@libp2p/interface-libp2p';
 import type { Blockstore } from 'interface-blockstore';
 import type { AbortOptions } from '@libp2p/interfaces';
 import type { PeerId } from '@libp2p/interface-peer-id';
-import type { Multiaddr } from '@multiformats/multiaddr';
 import type { Datastore } from 'interface-datastore';
+import type { Pins } from './pins.js';
+import type { ProgressEvent, ProgressOptions } from 'progress-events';
+import type { CID } from 'multiformats/cid';
 /**
  * The API presented by a Helia node.
  */
@@ -36,20 +38,9 @@ export interface Helia {
      */
     datastore: Datastore;
     /**
-     * Returns information about this node
-     *
-     * @example
-     *
-     * ```typescript
-     * import { createHelia } from 'helia'
-     *
-     * const node = await createHelia()
-     * const id = await node.info()
-     * console.info(id)
-     * // { peerId: PeerId(12D3Foo), ... }
-     * ```
+     * Pinning operations for blocks in the blockstore
      */
-    info: (options?: InfoOptions) => Promise<InfoResponse>;
+    pins: Pins;
     /**
      * Starts the Helia node
      */
@@ -58,6 +49,13 @@ export interface Helia {
      * Stops the Helia node
      */
     stop: () => Promise<void>;
+    /**
+     * Remove any unpinned blocks from the blockstore
+     */
+    gc: (options?: GCOptions) => Promise<void>;
+}
+export type GcEvents = ProgressEvent<'helia:gc:deleted', CID>;
+export interface GCOptions extends AbortOptions, ProgressOptions<GcEvents> {
 }
 export interface InfoOptions extends AbortOptions {
     /**
@@ -66,30 +64,4 @@ export interface InfoOptions extends AbortOptions {
      */
     peerId?: PeerId;
 }
-export interface InfoResponse {
-    /**
-     * The ID of the peer this info is about
-     */
-    peerId: PeerId;
-    /**
-     * The multiaddrs the peer is listening on
-     */
-    multiaddrs: Multiaddr[];
-    /**
-     * The peer's reported agent version
-     */
-    agentVersion: string;
-    /**
-     * The peer's reported protocol version
-     */
-    protocolVersion: string;
-    /**
-     * The protocols the peer supports
-     */
-    protocols: string[];
-    /**
-     * The status of the node
-     */
-    status: 'running' | 'stopped';
-}
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAA;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAA;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAEpD;;GAEG;AACH,MAAM,WAAW,KAAK;IACpB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IAEd;;OAEG;IACH,UAAU,EAAE,UAAU,CAAA;IAEtB;;OAEG;IACH,SAAS,EAAE,SAAS,CAAA;IAEpB;;;;;;;;;;;;;OAaG;IACH,IAAI,EAAE,CAAC,OAAO,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,CAAC,CAAA;IAEtD;;OAEG;IACH,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAE1B;;OAEG;IACH,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1B;AAED,MAAM,WAAW,WAAY,SAAQ,YAAY;IAC/C;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IAEd;;OAEG;IACH,UAAU,EAAE,SAAS,EAAE,CAAA;IAEvB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAA;IAEpB;;OAEG;IACH,eAAe,EAAE,MAAM,CAAA;IAEvB;;OAEG;IACH,SAAS,EAAE,MAAM,EAAE,CAAA;IAEnB;;OAEG;IACH,MAAM,EAAE,SAAS,GAAG,SAAS,CAAA;CAC9B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAA;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAA;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AACrC,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACrE,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAA;AAE3C;;GAEG;AACH,MAAM,WAAW,KAAK;IACpB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IAEd;;OAEG;IACH,UAAU,EAAE,UAAU,CAAA;IAEtB;;OAEG;IACH,SAAS,EAAE,SAAS,CAAA;IAEpB;;OAEG;IACH,IAAI,EAAE,IAAI,CAAA;IAEV;;OAEG;IACH,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAE1B;;OAEG;IACH,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAEzB;;OAEG;IACH,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3C;AAED,MAAM,MAAM,QAAQ,GAClB,aAAa,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAA;AAExC,MAAM,WAAW,SAAU,SAAQ,YAAY,EAAE,eAAe,CAAC,QAAQ,CAAC;CAEzE;AAED,MAAM,WAAW,WAAY,SAAQ,YAAY;IAC/C;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB"}

package/dist/src/pins.d.ts

@@ -0,0 +1,48 @@
+import type { AbortOptions } from '@libp2p/interfaces';
+import type { CID } from 'multiformats/cid';
+import type { ProgressEvent, ProgressOptions } from 'progress-events';
+export type PinType = 'recursive' | 'direct' | 'indirect';
+export interface Pin {
+    cid: CID;
+    depth: number;
+    metadata: Record<string, any>;
+}
+export type AddPinEvents = ProgressEvent<'helia:pin:add', unknown>;
+export interface AddOptions extends AbortOptions, ProgressOptions<AddPinEvents> {
+    /**
+     * How deeply to pin the DAG, defaults to Infinity
+     */
+    depth?: number;
+    /**
+     * Optional user-defined metadata to store with the pin
+     */
+    metadata?: Record<string, string | number | boolean>;
+}
+export interface RmOptions extends AbortOptions {
+}
+export interface LsOptions extends AbortOptions {
+    cid?: CID;
+}
+export interface IsPinnedOptions extends AbortOptions {
+}
+export interface Pins {
+    /**
+     * Pin a block in the blockstore. It will not be deleted
+     * when garbage collection is run.
+     */
+    add: (cid: CID, options?: AddOptions) => Promise<Pin>;
+    /**
+     * Unpin the block that corresponds to the passed CID. The block will
+     * be deleted when garbage collection is run.
+     */
+    rm: (cid: CID, options?: RmOptions) => Promise<Pin>;
+    /**
+     * List all blocks that have been pinned.
+     */
+    ls: (options?: LsOptions) => AsyncGenerator<Pin, void, undefined>;
+    /**
+     * Return true if the passed CID is pinned
+     */
+    isPinned: (cid: CID, options?: IsPinnedOptions) => Promise<boolean>;
+}
+//# sourceMappingURL=pins.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pins.d.ts","sourceRoot":"","sources":["../../src/pins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAErE,MAAM,MAAM,OAAO,GAAG,WAAW,GAAG,QAAQ,GAAG,UAAU,CAAA;AAEzD,MAAM,WAAW,GAAG;IAClB,GAAG,EAAE,GAAG,CAAA;IACR,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAC9B;AAED,MAAM,MAAM,YAAY,GACtB,aAAa,CAAC,eAAe,EAAE,OAAO,CAAC,CAAA;AAEzC,MAAM,WAAW,UAAW,SAAQ,YAAY,EAAE,eAAe,CAAC,YAAY,CAAC;IAC7E;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAA;CACrD;AAED,MAAM,WAAW,SAAU,SAAQ,YAAY;CAE9C;AAED,MAAM,WAAW,SAAU,SAAQ,YAAY;IAC7C,GAAG,CAAC,EAAE,GAAG,CAAA;CACV;AAED,MAAM,WAAW,eAAgB,SAAQ,YAAY;CAEpD;AAED,MAAM,WAAW,IAAI;IACnB;;;OAGG;IACH,GAAG,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,UAAU,KAAK,OAAO,CAAC,GAAG,CAAC,CAAA;IAErD;;;OAGG;IACH,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,SAAS,KAAK,OAAO,CAAC,GAAG,CAAC,CAAA;IAEnD;;OAEG;IACH,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,SAAS,KAAK,cAAc,CAAC,GAAG,EAAE,IAAI,EAAE,SAAS,CAAC,CAAA;IAEjE;;OAEG;IACH,QAAQ,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,eAAe,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CACpE"}

package/dist/src/pins.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=pins.js.map

package/dist/src/pins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pins.js","sourceRoot":"","sources":["../../src/pins.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helia/interface",
-  "version": "0.0.0-ab0a451",
+  "version": "0.0.0-d15d76c",
   "description": "The Helia API",
   "license": "Apache-2.0 OR MIT",
   "homepage": "https://github.com/ipfs/helia/tree/master/packages/interface#readme",
@@ -47,9 +47,9 @@
       "types": "./dist/src/index.d.ts",
       "import": "./dist/src/index.js"
     },
-    "./errors": {
-      "types": "./dist/src/errors.d.ts",
-      "import": "./dist/src/errors.js"
+    "./pins": {
+      "types": "./dist/src/pins.d.ts",
+      "import": "./dist/src/pins.js"
     }
   },
   "eslintConfig": {
@@ -156,7 +156,9 @@
     "@libp2p/interfaces": "^3.3.1",
     "@multiformats/multiaddr": "^11.1.5",
     "interface-blockstore": "^4.0.1",
-    "interface-datastore": "^7.0.3"
+    "interface-datastore": "^7.0.3",
+    "multiformats": "^11.0.1",
+    "progress-events": "^1.0.0"
   },
   "devDependencies": {
     "aegir": "^38.1.0"

package/src/index.ts

@@ -18,8 +18,10 @@ import type { Libp2p } from '@libp2p/interface-libp2p'
 import type { Blockstore } from 'interface-blockstore'
 import type { AbortOptions } from '@libp2p/interfaces'
 import type { PeerId } from '@libp2p/interface-peer-id'
-import type { Multiaddr } from '@multiformats/multiaddr'
 import type { Datastore } from 'interface-datastore'
+import type { Pins } from './pins.js'
+import type { ProgressEvent, ProgressOptions } from 'progress-events'
+import type { CID } from 'multiformats/cid'
 
 /**
  * The API presented by a Helia node.
@@ -41,20 +43,9 @@ export interface Helia {
   datastore: Datastore
 
   /**
-   * Returns information about this node
-   *
-   * @example
-   *
-   * ```typescript
-   * import { createHelia } from 'helia'
-   *
-   * const node = await createHelia()
-   * const id = await node.info()
-   * console.info(id)
-   * // { peerId: PeerId(12D3Foo), ... }
-   * ```
+   * Pinning operations for blocks in the blockstore
    */
-  info: (options?: InfoOptions) => Promise<InfoResponse>
+  pins: Pins
 
   /**
    * Starts the Helia node
@@ -65,44 +56,24 @@ export interface Helia {
    * Stops the Helia node
    */
   stop: () => Promise<void>
-}
 
-export interface InfoOptions extends AbortOptions {
   /**
-   * If passed, return information about this PeerId, defaults
-   * to the ID of the current node.
+   * Remove any unpinned blocks from the blockstore
    */
-  peerId?: PeerId
+  gc: (options?: GCOptions) => Promise<void>
 }
 
-export interface InfoResponse {
-  /**
-   * The ID of the peer this info is about
-   */
-  peerId: PeerId
-
-  /**
-   * The multiaddrs the peer is listening on
-   */
-  multiaddrs: Multiaddr[]
-
-  /**
-   * The peer's reported agent version
-   */
-  agentVersion: string
+export type GcEvents =
+  ProgressEvent<'helia:gc:deleted', CID>
 
-  /**
-   * The peer's reported protocol version
-   */
-  protocolVersion: string
+export interface GCOptions extends AbortOptions, ProgressOptions<GcEvents> {
 
-  /**
-   * The protocols the peer supports
-   */
-  protocols: string[]
+}
 
+export interface InfoOptions extends AbortOptions {
   /**
-   * The status of the node
+   * If passed, return information about this PeerId, defaults
+   * to the ID of the current node.
    */
-  status: 'running' | 'stopped'
+  peerId?: PeerId
 }

package/src/pins.ts

@@ -0,0 +1,62 @@
+import type { AbortOptions } from '@libp2p/interfaces'
+import type { CID } from 'multiformats/cid'
+import type { ProgressEvent, ProgressOptions } from 'progress-events'
+
+export type PinType = 'recursive' | 'direct' | 'indirect'
+
+export interface Pin {
+  cid: CID
+  depth: number
+  metadata: Record<string, any>
+}
+
+export type AddPinEvents =
+  ProgressEvent<'helia:pin:add', unknown>
+
+export interface AddOptions extends AbortOptions, ProgressOptions<AddPinEvents> {
+  /**
+   * How deeply to pin the DAG, defaults to Infinity
+   */
+  depth?: number
+
+  /**
+   * Optional user-defined metadata to store with the pin
+   */
+  metadata?: Record<string, string | number | boolean>
+}
+
+export interface RmOptions extends AbortOptions {
+
+}
+
+export interface LsOptions extends AbortOptions {
+  cid?: CID
+}
+
+export interface IsPinnedOptions extends AbortOptions {
+
+}
+
+export interface Pins {
+  /**
+   * Pin a block in the blockstore. It will not be deleted
+   * when garbage collection is run.
+   */
+  add: (cid: CID, options?: AddOptions) => Promise<Pin>
+
+  /**
+   * Unpin the block that corresponds to the passed CID. The block will
+   * be deleted when garbage collection is run.
+   */
+  rm: (cid: CID, options?: RmOptions) => Promise<Pin>
+
+  /**
+   * List all blocks that have been pinned.
+   */
+  ls: (options?: LsOptions) => AsyncGenerator<Pin, void, undefined>
+
+  /**
+   * Return true if the passed CID is pinned
+   */
+  isPinned: (cid: CID, options?: IsPinnedOptions) => Promise<boolean>
+}