@omegajs/volumes

Omega Volumes

@omegajs/volumes

A secure storage vault designed for Scroll, optimized for handling data "blobs" referred to as volumes.

Each volume is identified by its unique bounds within the Scroll, e.g. { byteOffset: 0, blockOffset: 0, blockLength: 5, byteLength: 327680 }, which makes them easy to save and retrieve:

const volumes = new Volumes(scroll)
// ID is { byteOffset: 0, blockOffset: 0, blockLength: 1, byteLength: 11 }
const id = await volumes.put(Buffer.from('hello world', 'utf-8')) 
await volumes.get(id) // Buffer.from('hello world', 'utf-8')

You can also get from start/end bounds within a single volume:

const volumes = new Volumes(scroll)
// ID is { byteOffset: 0, blockOffset: 0, blockLength: 1, byteLength: 11 }
const id = await volumes.put(Buffer.from('hello world', 'utf-8')) 
await volumes.get(id, { start: 1, length: 2 }) // Buffer.from('el', 'utf-8')

If the volume is large, there's a Streams interface (createReadStream and createWriteStream) too.

Install Via L1FE's NPM

npm config set registry https://npm.l1fe.tech
npm install @omegajs/volumes

Install Via L1FE's Git Repository

git clone https://lab.l1fe.tech/omega/volumes.git
cd volumes
npm install

API

const Volumes = require('@omegajs/volumes')

const volumes = new Volumes(scroll, opts)

Create a new volume vault wrapping a single Scroll.

Options can include:

{
  blockSize: 64KB // The block size that will be used when storing large volumes.
}

const id = await volumes.put(volume, opts)

Store a new volume. If the volume is large, it will be chunked according to opts.blockSize (default 64KB).

Options can include:

{
  blockSize: 64KB, // The block size that will be used when storing large volumes.
  start: 0, // Relative offset to start within the volume
  end: volume.length - 1, // End offset within the volume (inclusive)
  length: volume.length, // Number of bytes to read.
  scroll // A custom scroll to write (overrides the default scroll)
}

const content = await volumes.get(id, opts)

Return a complete volume as a Buffer.

id is the value returned by put

Options can include:

{
  scroll, // A custom scroll to read from (overrides the default scroll)
  wait: true, // Wait for block to be downloaded
  timeout: 0 // Wait at max some milliseconds (0 means no timeout)
}

await volumes.clear(id, opts)

Remove a volume from the scroll.

opts are the same as Scroll.clear method.

const stream = volumes.createReadStream(id, opts)

Create a Readable stream that will yield the id volume.

Options match the get options.

const stream = volumes.createWriteStream(opts)

Create a Writable stream that will save a volume.

The corresponding ID will be set on the stream at stream.id.

License

Apache-2.0