@helia/remote-pinning/dist/src/index.js

Add remote pinning capabilities to Helia

/**
 * @packageDocumentation
 *
 * Remote pinning allows you to delegate the hosting of content to another,
 * perhaps better connected, node or service on the IPFS network.
 *
 * Instead of pinning blocks locally, we can use a Remote Pinning Service API
 * server to pin the blocks, ensuring they are persisted beyond the scope of the
 * current Helia node.
 *
 * This is ideal for when creating content in short-lived environments, such as
 * browsers, for example.
 *
 * This module exports two functions to help you do this - `createRemotePins`
 * and `heliaWithRemotePins`.
 *
 * ## createRemotePins
 *
 * The `createRemotePins` function returns an object that implements the Helia
 * `Pins` interface.
 *
 * The returned object can be used to replace the `.pins` property of your Helia
 * node so you can transparently ensure the longevity of pinned content, or you
 * can use it directly.
 *
 * ## heliaWithRemotePins
 *
 * This function takes a Helia instance and some remote pinning config and
 * returns a Helia node that has been augmented with remote pinning.
 *
 * You can then use the `.pins` API as normal, and pinned blocks will be pulled
 * up by the remote pinning service.
 *
 * @example
 *
 * ```TypeScript
 * import { createHelia } from 'helia'
 * import { heliaWithRemotePins } from '@helia/remote-pinning'
 * import { unixfs } from '@helia/unixfs'
 *
 * // this node uses only remote pinning
 * const helia = heliaWithRemotePins(await createHelia(), {
 *   endpointUrl: `http://localhost:${process.env.PINNING_SERVER_PORT}`, // the URI for your pinning provider, e.g. `http://localhost:3000`
 *   accessToken: process.env.PINNING_SERVICE_TOKEN // the secret token/key given to you by your pinning provider
 * })
 *
 * // add a block to Helia
 * const fs = unixfs(helia)
 * const cid = await fs.addBytes(Uint8Array.from([0, 1, 2, 3]))
 *
 * // pin the block
 * for await(const cid of helia.pins.add(cid, { signal: AbortSignal.timeout(5000) })) {
 *   console.info('pinned', cid)
 * }
 *
 * // the block can now be retrieved from the remote pinning service
 * ```
 *
 * ## API differences
 *
 * The mapping between the Helia pinning API and the remote pinning API is not
 * perfect. The differences are:
 *
 * 1. The remote pinning API does not give detailed progress information, consequently the only CID yielded from `pins.add` will be the root CID
 * 2. Helia's metadata support is richer than that of the remote pinning API - metadata values can only be strings
 * 3. The remote pinning API accepts several extra arguments to several operations - these can be sent in a type-safe way using the `HeliaWithRemotePins` interface, which is the return type of the exported `heliaWithRemotePins` function
 */
import { Configuration, RemotePinningServiceClient } from '@ipfs-shipyard/pinning-service-client';
import { HeliaRemotePins } from "./helia-remote-pins.js";
/**
 * Create a remote pins instance powered by the passed Helia node
 */
export function createRemotePins(helia, init = {}) {
    return new HeliaRemotePins(helia, new RemotePinningServiceClient(new Configuration(init)), init);
}
/**
 * Patches the passed Helia node with the remote pins instance, this function
 * makes dealing with the types a little easier
 */
export function heliaWithRemotePins(helia, init = {}) {
    helia.pins = createRemotePins(helia, init);
    return helia;
}
//# sourceMappingURL=index.js.map