dWeb Vault API

@dwebs/vault

A nodejs API for the dWeb (Distributed Web) which is compatible with dPack's and dBrowser's DPackVault API. Useful for testing and for writing apps that work in the browser and in nodejs.

var DWebVault = require('@dwebs/vault')

// create a new vault
var vault = await DWebVault.create({
  localPath: './my-dweb-vault-data',
  title: 'My dWeb Vault',
  description: 'A test of the core DWebVault API'
})

// load an existing vault from disk
var vault = await DWebVault.load({
  localPath: './my-dweb-vault-data'
})

// load an existing vault from the URL:
var vault = new DWebVault(dwebURL, {localPath: './my-dweb-vault-data'})

// using the instance
await vault.writeFile('hello.txt', 'world')
var names = await vault.readdir('/')
console.log(names) // => ['hello.txt']

By default, @dwebs/vault stores the dWeb data in the localPath folder using the SLEEP format (dWeb's internal structure). If you want the folder to show the latest files (the dpack cli behavior) pass latest: true in the dpackOptions.

var vault = await DWebVault.create({
  localPath: './my-dweb-vault-data',
  dpackOptions: {latest: true}
})
var vault = await DWebVault.load({
  localPath: './my-dweb-vault-data',
  dpackOptions: {latest: true}
})
var vault = new DWebVault(dwebURL, {
  localPath: './my-dweb-vault-data',
  dpackOptions: {latest: true}
})

You can also pass options through to @dpack/core with dpackOptions, or pass options to its .joinNetwork([opts]) method with netOptions:

var vault = new DWebVault(dwebURL, {
  localPath: './my-dweb-vault-data',
  dpackOptions: {
    live: true
  },
  netOptions: {
    upload: false
  }
})

This will extend @dwebs/vault's defaults.

Differences from dBrowser and dPack API

• Uses the DWebVault prototype instead of DPackVault.
• This module adds the localPath parameter. Use the localPath to specify where the data for the vault should be stored. If not provided, the vault will be stored in memory.
• This module also adds dpackOptions and netOptions to configure the @dpack/core usage.
• This module also adds DWebVault.load() to read an vault from disk.
• This module does yet not include DWebVault.fork.
• This module does yet not include DWebVault.unlink.
• This module will not include DWebVault.selectVault.
• vault.getInfo() does not give a valid mtime or size.
• networked: opt is not yet supported.

Quick API reference

Refer to the dWeb's DWebVault documentation.

var vault = new DWebVault(url, {localPath:, dpackOptions:, netOptions:})
var vault = await DWebVault.create({localPath:, dpackOptions:, netOptions:, title:, description:, type:, author:, networked:})
var vault = await DWebVault.load({localPath:, dpackOptions:, netOptions:})
var key = await DWebVault.resolveName(url)
vault.url
await vault.configure({title:, description:, type:, author:, networked:})
var info = await vault.getInfo({timeout:})
var stat = await vault.stat(path, {timeout:})
var content = await vault.readFile(path, {encoding:, timeout:})
var names = vault.readdir(path, {recursive:, stat:, timeout:})
await vault.writeFile(path, data, encoding)
await vault.mkdir(path)
await vault.unlink(path)
await vault.rmdir(path, {recursive:})
var history = await vault.history({start:, end:, reverse:, timeout:})
await vault.download(path, {timeout:})
var emitter = vault.createFileActivityStream(pattern)
var emitter = vault.createNetworkActivityStream()

// node-only:
vault._loadPromise // promise for when the vault is ready to use
vault._close() // exit swarm, close all files