harlantwood / js-ipfs-repo

Implementation of the IPFS repo spec (https://github.com/ipfs/specs/tree/master/repo) in JavaScript

IPFS Repo JavaScript Implementation

Implementation of the IPFS repo spec (https://github.com/ipfs/specs/tree/master/repo) in JavaScript

This is the implementation of the IPFS repo spec in JavaScript.

Table of Contents

• Background
  • Good to know (historical context)
• Install
  • npm
  • Use in Node.js
  • Use in a browser with browserify, webpack or any other bundler
  • Use in a browser Using a script tag
• Usage
• API
  • var repo = new IPFSRepo(path, opts)
  • repo.exists(cb)
  • repo.version.get(cb(err, version))
  • repo.version.set(version, cb(err))
  • repo.config.get(cb(err, config))
  • repo.config.set(config, cb(err))
  • repo.keys
  • repo.blockstore.putStream()
  • repo.blockstore.getStream(key, extension)
  • repo.datastore
• Contribute
• License

Background

Here is the architectural reasoning for this repo:

┌─────────────────────────────────┐
│ interface defined by Repo Spec  │
├─────────────────────────────────┤
│                                 │                                  ┌──────────────────────┐
│                                 │                                  │ interface-pull-blob-store  │
│           IPFS REPO             │─────────────────────────────────▶│     interface        │
│                                 │                                  ├──────────────────────┤
│                                 │                                  │      locks           │
└─────────────────────────────────┘                                  └──────────────────────┘
                 │
      ┌──────────┴────┬───────────────┬───────────────┬───────────────┬───────────────┐
      ▼               ▼               ▼               ▼               ▼               ▼
┌───────────┐   ┌───────────┐   ┌───────────┐   ┌───────────┐   ┌───────────┐   ┌───────────┐
│ abstract  │   │ abstract  │   │ abstract  │   │ abstract  │   │ abstract  │   │ abstract  │
│ -blob     │   │ -blob     │   │ -blob     │   │ -blob     │   │ -blob     │   │ -blob     │
│ -store    │   │ -store    │   │ -store    │   │ -store    │   │ -store    │   │ -store    │
│ interface │   │ interface │   │ interface │   │ interface │   │ interface │   │ interface │
├───────────┤   ├───────────┤   ├───────────┤   ├───────────┤   ├───────────┤   ├───────────┤
│           │   │           │   │           │   │           │   │           │   │           │
│   keys    │   │  config   │   │ blockstore │   │ datastore │   │   logs    │   │  version  │
│           │   │           │   │           │   │           │   │           │   │           │
└───────────┘   └───────────┘   └───────────┘   └───────────┘   └───────────┘   └───────────┘

This provides a well defined interface for creating and interacting with an IPFS Repo backed by a group of abstract backends for keys, configuration, logs, and more. Each of the individual repos has an interface defined by interface-pull-blob-store: this enables us to make IPFS Repo portable (running on Node.js vs the browser) and accept different types of storage mechanisms for each repo (fs, levelDB, etc).

Good to know (historical context)

• The datastore folder holds the legacy version of datastore, still built in levelDB, there is a current endeavour of pushing it to fs completely.
• The blocks folder is the current version of datastore.
• The keys repo doesn't exist yet, as the private key is simply stored inside config

Install

npm

> npm i ipfs-repo

Use in Node.js

var IPFSRepo = require('ipfs-repo')

Use in a browser with browserify, webpack or any other bundler

The code published to npm that gets loaded on require is in fact a ES5 transpiled version with the right shims added. This means that you can require it and use with your favourite bundler without having to adjust asset management process.

var IPFSRepo = require('ipfs-repo')

Use in a browser Using a script tag

Loading this module through a script tag will make the Unixfs obj available in the global namespace.

<script src="https://unpkg.com/ipfs-repo/dist/index.min.js"></script>
<!-- OR -->
<script src="https://unpkg.com/ipfs-repo/dist/index.js"></script>

Usage

Example:

var fsBlobStore = require('fs-blob-store')  // an in-memory blob store
var IPFSRepo = require('js-ipfs-repo')
var repo = new IPFSRepo('/Users/someone/.ipfs', {
  stores: blobStore
})

API

var IPFSRepo = require('ipfs-repo')

var repo = new IPFSRepo(path, opts)

Creates a reference to an IPFS repository at the path path. This does not create the repo, but is an object that refers to the repo at such a path.

Valid keys for opts include:

• stores: either an interface-pull-blob-store, or a map of the form

{
  keys: someBlobStore,
  config: someBlobStore,
  datastore: someBlobStore,
  logs: someBlobStore,
  locks: someBlobStore,
  version: someBlobStore
}

If you use the former form, all of the sub-blob-stores will use the same store.

repo.exists(cb)

Check if the repo you are going to access already exists. Calls the callback cb(err, exists), where exists is true or false.

repo.version.get(cb(err, version))

repo.version.set(version, cb(err))

Read/write the version number of the repository. The version number is the repo version number.

repo.config.get(cb(err, config))

repo.config.set(config, cb(err))

Read/write the configuration object of the repository.

repo.keys

Read/write keys inside the repo. This feature will be expanded once IPRS and KeyChain are finalized and implemented on go-ipfs.

repo.blockstore.putStream()

repo.datastore.getStream(key, extension)

repo.datastore.has(key, extension, cb)

repo.datastore.delete(key, extension, cb)

Read and write buffers to/from the repo's block store.

repo.datastore

WIP

Contribute

There are some ways you can make this module better:

• Consult our open issues and take on one of them
• Help our tests reach 100% coverage!

This repository falls under the IPFS Code of Conduct.

License

MIT