@helia/interface 0.0.0-270bb98

package/LICENSE

@@ -0,0 +1,4 @@
+This project is dual licensed under MIT and Apache-2.0.
+
+MIT: https://www.opensource.org/licenses/mit
+Apache-2.0: https://www.apache.org/licenses/license-2.0

package/README.md

@@ -0,0 +1,50 @@
+<p align="center">
+  <a href="https://github.com/ipfs/helia" title="Helia">
+    <img src="https://raw.githubusercontent.com/ipfs/helia/main/assets/helia.png" alt="Helia logo" width="300" />
+  </a>
+</p>
+
+# @helia/interface <!-- omit in toc -->
+
+[![ipfs.tech](https://img.shields.io/badge/project-IPFS-blue.svg?style=flat-square)](https://ipfs.tech)
+[![Discuss](https://img.shields.io/discourse/https/discuss.ipfs.tech/posts.svg?style=flat-square)](https://discuss.ipfs.tech)
+[![codecov](https://img.shields.io/codecov/c/github/ipfs/helia.svg?style=flat-square)](https://codecov.io/gh/ipfs/helia)
+[![CI](https://img.shields.io/github/actions/workflow/status/ipfs/helia/main.yml?branch=main\&style=flat-square)](https://github.com/ipfs/helia/actions/workflows/main.yml?query=branch%3Amain)
+
+> The Helia API
+
+## Table of contents <!-- omit in toc -->
+
+- [Install](#install)
+- [API Docs](#api-docs)
+- [License](#license)
+- [Contribute](#contribute)
+
+## Install
+
+```console
+$ npm i @helia/interface
+```
+
+## API Docs
+
+- <https://ipfs.github.io/helia/modules/_helia_interface.html>
+
+## License
+
+Licensed under either of
+
+- Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / <http://www.apache.org/licenses/LICENSE-2.0>)
+- MIT ([LICENSE-MIT](LICENSE-MIT) / <http://opensource.org/licenses/MIT>)
+
+## Contribute
+
+Contributions welcome! Please check out [the issues](https://github.com/ipfs/helia/issues).
+
+Also see our [contributing document](https://github.com/ipfs/community/blob/master/CONTRIBUTING_JS.md) for more information on how we work, and about contributing in general.
+
+Please be aware that all interactions related to this repo are subject to the IPFS [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md).
+
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
+
+[![](https://cdn.rawgit.com/jbenet/contribute-ipfs-gif/master/img/contribute.gif)](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md)

package/dist/index.min.js

@@ -0,0 +1,3 @@
+(function (root, factory) {(typeof module === 'object' && module.exports) ? module.exports = factory() : root.HeliaInterface = factory()}(typeof self !== 'undefined' ? self : this, function () {
+"use strict";var HeliaInterface=(()=>{var t=Object.defineProperty;var a=Object.getOwnPropertyDescriptor;var b=Object.getOwnPropertyNames;var c=Object.prototype.hasOwnProperty;var d=(o,e,x,r)=>{if(e&&typeof e=="object"||typeof e=="function")for(let p of b(e))!c.call(o,p)&&p!==x&&t(o,p,{get:()=>e[p],enumerable:!(r=a(e,p))||r.enumerable});return o};var f=o=>d(t({},"__esModule",{value:!0}),o);var g={};return f(g);})();
+return HeliaInterface}));

package/dist/src/index.d.ts

@@ -0,0 +1,109 @@
+/**
+ * @packageDocumentation
+ *
+ * The API defined by a Helia node
+ *
+ * @example
+ *
+ * ```typescript
+ * import type { Helia } from '@helia/interface'
+ *
+ * export function doSomething(helia: Helia) {
+ *   // use helia node functions here
+ * }
+ * ```
+ */
+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.
+ */
+export interface Helia {
+    /**
+     * The underlying libp2p node
+     */
+    libp2p: Libp2p;
+    /**
+     * Where the blocks are stored
+     */
+    blockstore: Blockstore;
+    /**
+     * A key/value store
+     */
+    datastore: Datastore;
+    /**
+     * Pinning operations for blocks in the blockstore
+     */
+    pins: Pins;
+    /**
+     * 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), ... }
+     * ```
+     */
+    info: (options?: InfoOptions) => Promise<InfoResponse>;
+    /**
+     * Starts the Helia node
+     */
+    start: () => Promise<void>;
+    /**
+     * 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 {
+    /**
+     * If passed, return information about this PeerId, defaults
+     * to the ID of the current node.
+     */
+    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

@@ -0,0 +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;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;;;;;;;;;;;;;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;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;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"}

package/dist/src/index.js

@@ -0,0 +1,17 @@
+/**
+ * @packageDocumentation
+ *
+ * The API defined by a Helia node
+ *
+ * @example
+ *
+ * ```typescript
+ * import type { Helia } from '@helia/interface'
+ *
+ * export function doSomething(helia: Helia) {
+ *   // use helia node functions here
+ * }
+ * ```
+ */
+export {};
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

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

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

@@ -0,0 +1,169 @@
+{
+  "name": "@helia/interface",
+  "version": "0.0.0-270bb98",
+  "description": "The Helia API",
+  "license": "Apache-2.0 OR MIT",
+  "homepage": "https://github.com/ipfs/helia/tree/master/packages/interface#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ipfs/helia.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ipfs/helia/issues"
+  },
+  "keywords": [
+    "IPFS"
+  ],
+  "engines": {
+    "node": ">=16.0.0",
+    "npm": ">=7.0.0"
+  },
+  "type": "module",
+  "types": "./dist/src/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "*": [
+        "*",
+        "dist/*",
+        "dist/src/*",
+        "dist/src/*/index"
+      ],
+      "src/*": [
+        "*",
+        "dist/*",
+        "dist/src/*",
+        "dist/src/*/index"
+      ]
+    }
+  },
+  "files": [
+    "src",
+    "dist",
+    "!dist/test",
+    "!**/*.tsbuildinfo"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    },
+    "./pins": {
+      "types": "./dist/src/pins.d.ts",
+      "import": "./dist/src/pins.js"
+    }
+  },
+  "eslintConfig": {
+    "extends": "ipfs",
+    "parserOptions": {
+      "sourceType": "module"
+    }
+  },
+  "release": {
+    "branches": [
+      "main"
+    ],
+    "plugins": [
+      [
+        "@semantic-release/commit-analyzer",
+        {
+          "preset": "conventionalcommits",
+          "releaseRules": [
+            {
+              "breaking": true,
+              "release": "major"
+            },
+            {
+              "revert": true,
+              "release": "patch"
+            },
+            {
+              "type": "feat",
+              "release": "minor"
+            },
+            {
+              "type": "fix",
+              "release": "patch"
+            },
+            {
+              "type": "docs",
+              "release": "patch"
+            },
+            {
+              "type": "test",
+              "release": "patch"
+            },
+            {
+              "type": "deps",
+              "release": "patch"
+            },
+            {
+              "scope": "no-release",
+              "release": false
+            }
+          ]
+        }
+      ],
+      [
+        "@semantic-release/release-notes-generator",
+        {
+          "preset": "conventionalcommits",
+          "presetConfig": {
+            "types": [
+              {
+                "type": "feat",
+                "section": "Features"
+              },
+              {
+                "type": "fix",
+                "section": "Bug Fixes"
+              },
+              {
+                "type": "chore",
+                "section": "Trivial Changes"
+              },
+              {
+                "type": "docs",
+                "section": "Documentation"
+              },
+              {
+                "type": "deps",
+                "section": "Dependencies"
+              },
+              {
+                "type": "test",
+                "section": "Tests"
+              }
+            ]
+          }
+        }
+      ],
+      "@semantic-release/changelog",
+      "@semantic-release/npm",
+      "@semantic-release/github",
+      "@semantic-release/git"
+    ]
+  },
+  "scripts": {
+    "clean": "aegir clean",
+    "lint": "aegir lint",
+    "dep-check": "aegir dep-check",
+    "build": "aegir build",
+    "release": "aegir release"
+  },
+  "dependencies": {
+    "@libp2p/interface-libp2p": "^1.1.0",
+    "@libp2p/interface-peer-id": "^2.0.1",
+    "@libp2p/interfaces": "^3.3.1",
+    "@multiformats/multiaddr": "^11.1.5",
+    "interface-blockstore": "^4.0.1",
+    "interface-datastore": "^7.0.3",
+    "multiformats": "^11.0.1",
+    "progress-events": "^1.0.0"
+  },
+  "devDependencies": {
+    "aegir": "^38.1.0"
+  },
+  "typedoc": {
+    "entryPoint": "./src/index.ts"
+  }
+}

package/src/index.ts

@@ -0,0 +1,128 @@
+/**
+ * @packageDocumentation
+ *
+ * The API defined by a Helia node
+ *
+ * @example
+ *
+ * ```typescript
+ * import type { Helia } from '@helia/interface'
+ *
+ * export function doSomething(helia: Helia) {
+ *   // use helia node functions here
+ * }
+ * ```
+ */
+
+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.
+ */
+export interface Helia {
+  /**
+   * The underlying libp2p node
+   */
+  libp2p: Libp2p
+
+  /**
+   * Where the blocks are stored
+   */
+  blockstore: Blockstore
+
+  /**
+   * A key/value store
+   */
+  datastore: Datastore
+
+  /**
+   * Pinning operations for blocks in the blockstore
+   */
+  pins: Pins
+
+  /**
+   * 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), ... }
+   * ```
+   */
+  info: (options?: InfoOptions) => Promise<InfoResponse>
+
+  /**
+   * Starts the Helia node
+   */
+  start: () => Promise<void>
+
+  /**
+   * 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 {
+  /**
+   * If passed, return information about this PeerId, defaults
+   * to the ID of the current node.
+   */
+  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'
+}

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>
+}