victorb / js-ipfs-repo

Implementation of the IPFS Repo spec 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
• 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

Background

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.

Install

npm

> npm install ipfs-repo

Use in Node.js

var IPFSRepo = require('ipfs-repo')

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

var IPFSRepo = require('ipfs-repo')

Use in a browser Using a script tag

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>

Usage

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

API

Setup

new Repo(path[, options])

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')

repo.init (callback)

Creates the necessary folder structure inside the repo.

repo.open (callback)

Locks the repo.

repo.close (callback)

Unlocks the repo.

repo.exists (callback)

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

Repos

Root repo:

repo.put (key, value:Buffer, callback)

Put a value at the root of the repo.

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

repo.get (key, callback)

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:

repo.blocks.put (block:Block, callback)

• block should be of type Block.

repo.blocks.putMany (blocks, callback)

Put many blocks.

• block should be an array of type Block.

repo.blocks.get (cid, callback)

Get block.

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

Datastore:

repo.datastore

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

Utils

repo.config

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.

repo.config.set(key:string, value, callback)

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')
  })
})

repo.config.get(value, callback)

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

repo.config.get(key:string, callback)

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

repo.config.get(callback)

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

repo.config.exists(callback)

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

repo.version

repo.version.get (callback)

Gets the repo version.

repo.version.set (version:number, callback)

Sets the repo version

repo.apiAddr

repo.apiAddr.get (callback)

Gets the API address.

repo.apiAddr.set (value, callback)

Sets the API address.

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

Notes

• Explanation of how repo is structured

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