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.

• Background
• 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
• Contribute
• License

Here is the architectural reasoning for this repo:

                          ┌────────────────────────────────────────┐
                          │                IPFSRepo                │
                          └────────────────────────────────────────┘
                                      ┌─────────────────┐
                                      │        /        │
                                      ├─────────────────┤
                                      │    Datastore    │
                                      └─────────────────┘
                                   ┌───────────┴───────────┐
                          ┌─────────────────┐     ┌─────────────────┐
                          │     /blocks     │     │   /datastore    │
                          ├─────────────────┤     ├─────────────────┤
                          │    Datastore    │     │ LevelDatastore  │
                          └─────────────────┘     └─────────────────┘

┌────────────────────────────────────────┐          ┌────────────────────────────────────────┐
│       IPFSRepo - Default Node.js       │          │       IPFSRepo - Default Browser       │
└────────────────────────────────────────┘          └────────────────────────────────────────┘
            ┌─────────────────┐                                 ┌─────────────────┐
            │        /        │                                 │        /        │
            ├─────────────────┤                                 ├─────────────────┤
            │   FsDatastore   │                                 │LevelJSDatastore │
            └─────────────────┘                                 └─────────────────┘
         ┌───────────┴───────────┐                           ┌───────────┴───────────┐
┌─────────────────┐     ┌─────────────────┐         ┌─────────────────┐     ┌─────────────────┐
│     /blocks     │     │   /datastore    │         │     /blocks     │     │   /datastore    │
├─────────────────┤     ├─────────────────┤         ├─────────────────┤     ├─────────────────┤
│ FlatfsDatastore │     │LevelDBDatastore │         │LevelJSDatastore │     │LevelJSDatastore │
└─────────────────┘     └─────────────────┘         └─────────────────┘     └─────────────────┘

This provides a well defined interface for creating and interacting with an IPFS repo.

> npm install ipfs-repo

var IPFSRepo = require('ipfs-repo')

var IPFSRepo = require('ipfs-repo')

Loading this module through a script tag will make the IpfsRepo 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>

Example:

const Repo = require('ipfs-repo')
const repo = new Repo('/tmp/ipfs-repo')

repo.init({ cool: 'config' }, (err) => {
  if (err) {
    throw err
  }

  repo.open((err) => {
    if (err) {
      throw err
    }

    console.log('repo is ready')
  })
})

This now has created the following structure, either on disk or as an in memory representation:

├── blocks
│   ├── SHARDING
│   └── _README
├── config
├── datastore
└── version

Creates an IPFS Repo.

Arguments:

• path (string, mandatory): the path for this repo
• options (object, optional): may contain the following values
  • lock (string, defaults to "fs" in Node.js, "memory" in the browser): what type of lock to use. Lock has to be acquired when opening.
  • storageBackends (object, optional): may contain the following values, which should each be a class implementing the datastore interface:
    • root (defaults to datastore-fs in Node.js and datastore-level in the browser). Defines the back-end type used for gets and puts of values at the root (repo.set(), repo.get())
    • blocks (defaults to datastore-fs in Node.js and datastore-level in the browser). Defines the back-end type used for gets and puts of values at repo.blocks.
    • datastore (defaults to datastore-level). Defines the back-end type used as the key-valye store used for gets and puts of values at repo.datastore.

const repo = new Repo('path/to/repo')

Creates the necessary folder structure inside the repo.

Locks the repo.

Unlocks the repo.

Tells whether this repo exists or not. Calls back with (err, bool).

Root repo:

Put a value at the root of the repo.

• key can be a buffer, a string or a Key.

Get a value at the root of the repo.

• key can be a buffer, a string or a Key.
• callback is a callback function function (err, result:Buffer)

Blocks:

• block should be of type Block.

Put many blocks.

• block should be an array of type Block.

Get block.

• cid is the content id of type CID.
• callback is a callback function function (err, result:Buffer)

Datastore:

This is contains a full implementation of the interface-datastore API.

Instead of using repo.set('config') this exposes an API that allows you to set and get a decoded config object, as well as, in a safe manner, change any of the config values individually.

Set a config value. value can be any object that is serializable to JSON.

• key is a string specifying the object path. Example:

repo.config.set('a.b.c', 'c value', (err) => {
  if (err) { throw err }
  repo.config.get((err, config) => {
    if (err) { throw err }
    assert.equal(config.a.b.c, 'c value')
  })
})

Set the whole config value. value can be any object that is serializable to JSON.

Get a config value. callback is a function with the signature: function (err, value), wehre the value is of the same type that was set before.

• key is a string specifying the object path. Example:

repo.config.get('a.b.c', (err, value) => {
  if (err) { throw err }
  console.log('config.a.b.c = ', value)
})

Get the entire config value. callback is a function with the signature: function (err, configValue:Object).

Whether the config sub-repo exists. Calls back with (err, bool).

Gets the repo version.

Sets the repo version

Gets the API address.

Sets the API address.

• value should be a Multiaddr or a String representing a valid one.

• Explanation of how repo is structured

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.

MIT