https://github.com/matrixai/js-db
Key-Value DB for TypeScript and JavaScript Applications
https://github.com/matrixai/js-db
database key-value-database rocksdb
Last synced: 11 months ago
JSON representation
Key-Value DB for TypeScript and JavaScript Applications
- Host: GitHub
- URL: https://github.com/matrixai/js-db
- Owner: MatrixAI
- License: apache-2.0
- Created: 2021-09-16T10:07:00.000Z (over 4 years ago)
- Default Branch: staging
- Last Pushed: 2023-11-09T00:32:29.000Z (over 2 years ago)
- Last Synced: 2024-10-31T13:27:03.492Z (over 1 year ago)
- Topics: database, key-value-database, rocksdb
- Language: TypeScript
- Homepage: https://polykey.com
- Size: 2.7 MB
- Stars: 5
- Watchers: 5
- Forks: 0
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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
```sh
npm install --save @matrixai/db
```
## Usage
```ts
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 => {
return plainText;
};
const decrypt = async (
key: ArrayBuffer,
cipherText: ArrayBuffer
): Promise => {
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();
```
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:
```sh
git submodule update --init --recursive
```
Run `nix develop`, and once you're inside, you can use:
```sh
# 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
```
## Benchmarks
```sh
npm run bench
```
View benchmarks here: https://github.com/MatrixAI/js-db/blob/master/benches/results with https://raw.githack.com/
### Docs Generation
```sh
npm run docs
```
See the docs at: https://matrixai.github.io/js-db/
### Publishing
Publishing is handled automatically by the staging pipeline.
Prerelease:
```sh
# npm login
npm version prepatch --preid alpha # premajor/preminor/prepatch
git push --follow-tags
```
Release:
```sh
# npm login
npm version patch # major/minor/patch
git push --follow-tags
```
Manually:
```sh
# npm login
npm version patch # major/minor/patch
npm run build
npm publish --access public
git push
git push --tags
```