@matrixai/db

js-db

staging: master:

DB is library managing key value state for MatrixAI's JavaScript/TypeScript applications.

This forks classic-level's C++ binding code around LevelDB 1.20. Differences from classic-level:

• Uses TypeScript from ground-up
• Supports Snapshot-Isolation based transactions via DBTransaction
• API supports "key paths" which can be used to manipulate "levels" of nested keys
• Value encryption (key-encryption is not supported yet) - requires additional work with block-encryption
• Uses RocksDB

Installation

npm install --save @matrixai/db

Usage

import { DB } from '@matrixai/db';

async function main () {

  const key = Buffer.from([
    0x00, 0x01, 0x02, 0x03, 0x00, 0x01, 0x02, 0x03,
    0x00, 0x01, 0x02, 0x03, 0x00, 0x01, 0x02, 0x03,
  ]);

  const encrypt = async (
    key: ArrayBuffer,
    plainText: ArrayBuffer
  ): Promise<ArrayBuffer> {
    return plainText;
  };

  const decrypt = async (
    key: ArrayBuffer,
    cipherText: ArrayBuffer
  ): Promise<ArrayBuffer | undefined> {
    return cipherText;
  }

  const db = await DB.createDB({
    dbPath: './tmp/db',
    crypto: {
      key,
      ops: { encrypt, decrypt },
    },
    fresh: true,
  });

  await db.put(['level', Buffer.from([0x30, 0x30]), 'a'], 'value');
  await db.put(['level', Buffer.from([0x30, 0x31]), 'b'], 'value');
  await db.put(['level', Buffer.from([0x30, 0x32]), 'c'], 'value');
  await db.put(['level', Buffer.from([0x30, 0x33]), 'c'], 'value');

  console.log(await db.get(['level', Buffer.from([0x30, 0x32]), 'c']));

  await db.del(['level', Buffer.from([0x30, 0x32]), 'c']);

  for await (const [kP, v] of db.iterator({
    lt: [Buffer.from([0x30, 0x32]), ''],
  }, ['level'])) {
    console.log(kP, v);
  }

  await db.stop();
}

main();

Development

Run nix-shell, and once you're inside, you can use:

# install (or reinstall packages from package.json)
npm install
# build the dist
npm run build
# run the repl (this allows you to import from ./src)
npm run ts-node
# run the tests
npm run test
# lint the source code
npm run lint
# automatically fix the source
npm run lintfix

Benchmarks

npm run bench

View benchmarks here: https://github.com/MatrixAI/js-db/blob/master/benches/results with https://raw.githack.com/

Docs Generation

npm run docs

See the docs at: https://matrixai.github.io/js-db/

Publishing

Publishing is handled automatically by the staging pipeline.

Prerelease:

# npm login
npm version prepatch --preid alpha # premajor/preminor/prepatch
git push --follow-tags

Release:

# npm login
npm version patch # major/minor/patch
git push --follow-tags

Manually:

# npm login
npm version patch # major/minor/patch
npm run build
npm publish --access public
git push
git push --tags