dotHIFT://Amarok — Amarok-Lite Node.js SDK

@dothift/amarok-lite is an embeddable TypeScript/Node.js database engine for dotHIFT://Amarok. It wraps better-sqlite3 in WAL mode and exposes the Amarok API surface so that code written for Amarok-Lite is compatible with the full Amarok server SDK.

Install

npm install @dothift/amarok-lite

Quick start — synchronous

import { Store } from '@dothift/amarok-lite'

const db = Store.open('./myapp.db')

db.exec('CREATE TABLE IF NOT EXISTS tickets (id TEXT PRIMARY KEY, data TEXT)')
db.exec('INSERT INTO tickets VALUES ($1, $2)', ['t-001', { title: 'First ticket' }])

const rows = db.query('SELECT * FROM tickets WHERE id = $1', ['t-001'])
console.log(rows.fetchall())

db.close()

Quick start — async

import { Store } from '@dothift/amarok-lite'

const db = Store.open('./myapp.db')

await db.execAsync('CREATE TABLE IF NOT EXISTS tickets (id TEXT PRIMARY KEY, data TEXT)')
await db.execAsync('INSERT INTO tickets VALUES ($1, $2)', ['t-002', { title: 'Second' }])

const rows = await db.queryAsync('SELECT * FROM tickets')
console.log(rows.fetchall())

db.close()

Transactions

import { Store } from '@dothift/amarok-lite'

const db = Store.open('./bank.db')
db.exec('CREATE TABLE IF NOT EXISTS accounts (id TEXT PRIMARY KEY, balance INTEGER)')
db.exec('INSERT INTO accounts VALUES ($1, $2)', ['alice', 1000])
db.exec('INSERT INTO accounts VALUES ($1, $2)', ['bob', 500])

db.transaction((tx) => {
  tx.exec('UPDATE accounts SET balance = balance - 100 WHERE id = $1', ['alice'])
  tx.exec('UPDATE accounts SET balance = balance + 100 WHERE id = $1', ['bob'])
})

db.close()

JSONB operators

Queries using Amarok's PostgreSQL-style JSONB operators are automatically rewritten to SQLite3 JSON functions:

| Amarok operator | SQLite equivalent | |------------------------|----------------------------------------------| | col->>'key' | json_extract(col, '$.key') | | col->'key' | json_extract(col, '$.key') | | col ? 'key' | (json_type(col, '$.key') IS NOT NULL) | | col @> '{"k":"v"}' | (json_patch(col, '{"k":"v"}') = col) |

Options

| Option | Default | Description | |--------------------|---------|------------------------------------------| | wal | true | Enable WAL journal mode | | cacheKB | 8000 | Page cache size in KB (~8 MB) | | walAutocheckpoint| 1000 | WAL auto-checkpoint threshold (pages) | | timeoutMs | 30000 | Busy-wait timeout in milliseconds | | enableEventLog | true | Create Phase 2 event log stub tables |

Part of dotHIFT

See the .platform repo for cross-product architecture decisions and the dependency manifest.