Install

``console
$ npm i ipfs-repo
`

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

Background

Here is the architectural reasoning for this repo:

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

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

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

`sh
> npm install ipfs-repo
`

`js
import { createRepo } from 'ipfs-repo'
`

Usage

Example:

`js
import { createRepo } from 'ipfs-repo'

const repo = createRepo('/tmp/ipfs-repo')

await repo.init({ cool: 'config' })
await repo.open()
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
├── keys
└── version

API

$3

#### createRepo(path[, options])

Creates an IPFS Repo.

Arguments:

- path (string, mandatory): the path for this repo
- options (object, optional): may contain the following values
- autoMigrate (bool, defaults to true): controls automatic migrations of repository.
- onMigrationProgress (function(version, percentComplete, message)): callback function to be notified of migration progress
- lock (Lock or string Deprecated): what type of lock to use. Lock has to be acquired when opening. string can be "fs" or "memory".
- 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.
- keys (defaults to datastore-fs in Node.js and datastore-level in the browser). Defines the back-end type used for gets and puts of encrypted keys at repo.keys
- datastore (defaults to datastore-level). Defines the back-end type used as the key-value store used for gets and puts of values at repo.datastore.

`js
const repo = createRepo('path/to/repo')
`

#### Promise repo.init()

Creates the necessary folder structure inside the repo

#### Promise repo.open()

Locks the repo to prevent conflicts arising from simultaneous access

#### Promise repo.close()

Unlocks the repo.

#### Promise repo.exists()

Tells whether this repo exists or not. Returned promise resolves to a boolean

#### Promise repo.isInitialized()

The returned promise resolves to false if the repo has not been initialized and true if it has

$3

Root repo:

#### Promise repo.put(key, value:Uint8Array)

Put a value at the root of the repo

- key can be a Uint8Array, a string or a [Key][]

#### Promise repo.get(key)

Get a value at the root of the repo

- key can be a Uint8Array, a string or a [Key][]

$3

#### Promise repo.blocks.put(block:Block)

- block should be of type [Block][]

#### AsyncIterator repo.blocks.putMany(source:AsyncIterable)

Put many blocks.

- source should be an AsyncIterable that yields entries of type [Block][]

#### Promise repo.blocks.get(cid:CID)

Get block.

- cid is the content id of type [CID][]

#### AsyncIterable repo.blocks.getMany(source:AsyncIterable)

Get many blocks

- source should be an AsyncIterable that yields entries of type [CID][]

#### Promise repo.blocks.has (cid:CID)

Indicate if a block is present for the passed CID

- cid should be of the type [CID][]

#### Promise repo.blocks.delete (cid:CID)

Deletes a block

- cid should be of the type [CID][]

#### AsyncIterator repo.blocks.query (query)

Query what blocks are available in blockstore.

If query.keysOnly is true, the returned iterator will yield [CID][]s, otherwise it will yield [Block][]s

- query is a object as specified in interface-datastore.

Datastore:

#### Promise repo.blocks.delete(cid:CID)

- cid should be of the type [CID][]

Delete a block

#### AsyncIterator repo.blocks.deleteMany(source:AsyncIterable)

- source should be an Iterable or AsyncIterable that yields entries of the type [CID][]

Delete many blocks

$3

#### repo.datastore

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

$3

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.

#### Promise repo.config.set(key:String, value:Object)

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

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

`js
await repo.config.set('a.b.c', 'c value')
const config = await repo.config.get()
assert.equal(config.a.b.c, 'c value')
`

#### Promise repo.config.replace(value:Object)

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

#### Promise repo.config.get(key:String)

Get a config value. Returned promise resolves to the same type that was set before.

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

`js
const value = await repo.config.get('a.b.c')
console.log('config.a.b.c = ', value)
`

#### Promise