Random Entry Storage (RES) - dwCore/dwCore-Wiki GitHub Wiki

Library For Creating dPack Memory-Based Storage Instances With Random Entry.

Table of Contents

• Background
• Installation
• Usage
• API

Background

A randomized memory-based dPack dPackMemStorage instance is created using this library and provides the following API.

• dPackRead(offset, size) - Read a buffer at a custom offset.
• dPackWrite(offset, data) - Write a buffer to a custom offset.
• dPackDelete(offset, size) - Delete data at a custom offset.

Installation

Install With NPM

npm install @dwcore/res

Install With YARN

yarn add @dwcore/res

Usage

var dWebRandEntry = require('@dwcore/res')
var fs = require('fs')

var dPackFile = dWebRandEntry('index.js')

dPackFile.dPackRead(0, 10, (err, buf) => console.log('0-10: ' + buf.toString()))
dPackFile.dPackRead(40, 15, (err, buf) => console.log('40-55: ' + buf.toString()))
dPackFile.dPackClose()

function dWebRandEntry (name) {
  var fd = 0
  return dWebRandEntry({
    dPackOpen: function (req) {
      // called once automatically before the first read call
      fs.open(name, 'r', function (err, res) {
        if (err) return req.callback(err)
        fd = res
        req.callback(null)
      })
    },
    dPackRead: function (req) {
      var buf = Buffer.allocUnsafe(req.size)
      fs.read(fd, buf, 0, buf.length, req.offset, function (err, dPackRead) {
        if (err) return req.callback(err)
        if (dPackRead < buf.length) return req.callback(new Error('Could not read'))
        req.callback(null, buf)
      })
    },
    dPackClose: function (req) {
      if (!fd) return req.callback(null)
      fs.close(fd, err => req.callback(err))
    }
  })
}

API

var dPackMemStorage = dWebRandEntryStorage([options])

Make a new instance. Options include:

{
  dPackOpen: fn, // sets ._dPackOpen
  dPackOpenReadonly: fn, // sets ._dPackOpenReadonly
  dPackRead: fn, // sets ._dPackRead
  dPackWrite: fn, // sets ._dPackWrite
  dPackDelete: fn, // sets ._dPackDelete
  dPackStat: fn, // sets ._dPackStat
  dPackClose: fn, // sets ._dPackClose
  dPackKill: fn // sets ._dPackKill
}

dPackMemStorage.dPackReadable

True if the dPackMemStorage implements ._dPackRead.

dPackMemStorage.dPackWritable

True if the dPackMemStorage implements ._dPackWrite.

dPackMemStorage.dPackDeletable

True if the dPackMemStorage implements ._dPackDelete.

dPackMemStorage.dPackStatable

True if the dPackMemStorage implements ._dPackStat.

dPackMemStorage.dPackOpened

True if the dPackMemStorage has been fully opened.

dPackMemStorage.dPackClosed

True if the dPackMemStorage has been fully closed.

dPackMemStorage.dPackKilled

True is the dPackMemStorage has been fully killed.

dPackMemStorage.on('dPackOpen')

Emitted when the dPackMemStorage is fully open.

dPackMemStorage.on('dPackClose')

Emitted when the dPackMemStorage is fully dPackClosed.

dPackMemStorage.on('dPackKill')

Emitted when the dPackMemStorage is fully killed.

dPackMemStorage.dPackOpen(cb)

Explicitly open the dPackMemStorage. If you do not call this yourself, it will automatically called before any read/write/del/stat operation.

It is safe to call this more than once.

Triggers one call to _dPackOpen if you implement that.

If you implement _dPackOpenReadonly and the operation that triggers the open is not a write/del then _dPackOpenReadonly will be called instead.

If a write is later performed a _dPackOpen call will be triggered as well, expecting you to open the dPackMemStorage in read/write mode.

dPackMemStorage._dPackOpen(req)

Implement dPackMemStorage open.

Call req.callback when it is fully opened.

dPackMemStorage._dPackOpenReadonly(req)

Implement dPackMemStorage readonly open.

Useful if you prefer to open the dPackMemStorage in readonly mode unless a write is performed. Call req.callback when it is fully opened.

dPackMemStorage.dPackRead(offset, size, callback)

Read the specified bytes from the dPackMemStorage at the specified byte offset. Calls the callback with a (err, buffer).

dPackMemStorage._dPackRead(req)

Implement dPackMemStorage read.

• req.offset contains the byte offset you should read at.
• req.size contains the amount of bytes you should read.

Call req.callback(err, buffer) when the read is completed.

Note that this is guaranteed to run after the dPackMemStorage has been opened and not after it has been closed.

dPackMemStorage.dPackWrite(offset, buffer, [callback])

Write the specified buffer to the specified byte offset. Optionally pass a callback that is called with (err) when the write has completed.

dPackMemStorage._dPackWrite(req)

Implement dPackMemStorage write.

• req.offset contains the byte offset you should write at.
• req.data contains the buffer you should write.

Call req.callback(err) when the write is completed.

Note that this is guaranteed to run after the dPackMemStorage has been opened and not after it has been closed.

dPackMemStorage.dPackDelete(offset, size, [callback])

Delete the specified amount of bytes as the specified offset. Optionally pass a callback that is called with (err) when the delete has completed.

dPackMemStorage._dPackDelete(req)

Implement dPackMemStorage delete.

• req.offset contains the byte offset to delete at.
• req.size contains the amount of bytes to delete.

Call req.callback(err) when the delete has completed.

Note that this is guaranteed to run after the dPackMemStorage has been opened and not after it has been closed.

dPackMemStorage.dPackStat(callback)

Stat the dPackMemStorage. Should return an object with useful information about the underlying dPackMemStorage, including:

{
  size: number // how many bytes of data is stored?
}

dPackMemStorage._dPackStat(req)

Implement dPackMemStorage stat.

Call req.callback(err, dPackStatObject) when the stat has completed.

Note that this is guaranteed to run after the dPackMemStorage has been opened and not after it has been dPackClosed.

dPackMemStorage.dPackClose([callback])

Close the dPackMemStorage instance.

dPackMemStorage._dPackClose(req)

Implement dPackMemStorage close.

Call req.callback(err) when the dPackMemStorage is fully closed.

Note this is guaranteed to run after all pending read/write/stat/del operations has finished and no methods will run after.

dPackMemStorage.dPackKill([callback])

Destroy the dPackMemStorage instance, removing all underlying data.

dPackMemStorage._dPackKill(req)

Implement dPackMemStorage kill.

Call req.callback(err) when the dPackMemStorage has been fully killed.

Note this is guaranteed to run after .dPackClose() has been called and no methods will be run after.