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.
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')
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
Creates an IPFS Repo.
Arguments:
path
(string, mandatory): the path for this repooptions
(object, optional): may contain the following valueslock
(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 todatastore-fs
in Node.js anddatastore-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 todatastore-fs
in Node.js anddatastore-level
in the browser). Defines the back-end type used for gets and puts of values atrepo.blocks
.keys
(defaults todatastore-fs
in Node.js anddatastore-level
in the browser). Defines the back-end type used for gets and puts of encrypted keys atrepo.keys
datastore
(defaults todatastore-level
). Defines the back-end type used as the key-valye store used for gets and puts of values atrepo.datastore
.
const repo = new Repo('path/to/repo')
Creates the necessary folder structure inside the repo.
Locks the repo to prevent conflicts arising from simultaneous access.
Unlocks the repo.
Tells whether this repo exists or not. Returns a boolean.
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.
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.
Datastore:
This 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:
await repo.config.set('a.b.c', 'c value')
const config = await repo.config.get()
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. Returns the same type that was set before.
key
is a string specifying the object path. Example:
const value = await repo.config.get('a.b.c')
console.log('config.a.b.c = ', value)
Get the entire config value.
Whether the config sub-repo exists.
Gets the repo version (an integer).
Sets the repo version
Gets the API address.
Sets the API address.
value
should be a Multiaddr or a String representing a valid one.
Gets the repo status.
options
is an object which might contain the key human
, which is a boolean indicating whether or not the repoSize
should be displayed in MiB or not.
Returns an Object with the following keys:
numObjects
repoPath
repoSize
version
storageMax
IPFS Repo comes with two built in locks: memory and fs. These can be imported via the following:
const fsLock = require('ipfs-repo/src/lock') // Default in Node.js
const memoryLock = require('ipfs-repo/src/lock-memory') // Default in browser
You can also provide your own custom Lock. It must be an object with the following interface:
Sets the lock if one does not already exist. If a lock already exists, should throw an error.
dir
is a string to the directory the lock should be created at. The repo typically creates the lock at its root.
Returns closer
, where closer
has a close
method for removing the lock.
Closes the lock created by lock.open
If no error was thrown, the lock was successfully removed.
Checks the existence of the lock.
dir
is a string to the directory to check for the lock. The repo typically checks for the lock at its root.
Returns a boolean
indicating the existence of the lock.
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.