js-db

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
Copy

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(
    ['level'],
    {
      lt: [Buffer.from([0x30, 0x32]), ''],
    })) {
    console.log(kP, v);
  }

  await db.stop();
}

main();
Copy

If you created the DB with a crypto object, then upon restarting the DB, you must pass in the same crypto object.

Development

This project uses Git submodules to bring in rocksdb. Make sure to clone recursively.

If you already cloned, run this:

git submodule update --init --recursive
Copy

Run nix develop, 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 tsx
# run the tests
npm run test
# lint the source code
npm run lint
# automatically fix the source
npm run lintfix
Copy

Benchmarks

npm run bench
Copy

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

Docs Generation

npm run docs
Copy

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
Copy

Release:

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

Manually:

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