stratus-db

The stratus service from JavaScript: typed JSON over fetch (docs/json.md), no dependencies. Node 20+ or a browser.

The client is one ES module, stratus-db.js. Install it from npm (npm install stratus-db: the package holds only that file, this README and a package.json with no scripts, published from this repository's release workflow), or copy the file into your project. To pin it, use your lockfile's integrity hash, or compare the file's sha256 with the one published beside it.

import { connect, kw, squuid, decimal, instant, localDate } from "stratus-db";

const s = connect({ url: "https://api.stratus-db.com", apiKey: process.env.STRATUS_KEY });
const { id } = await s.createDb({ name: "invoices", primaryKey: "invoice/id" });

await s.transact(id, { tx: [{
  "invoice/id": squuid(),                    // every row carries its key
  "invoice/total": decimal("1234.50"),       // exact, scale kept
  "invoice/due": localDate("2026-11-01"),
  "invoice/sent": instant(new Date()),
  "invoice/status": kw("status/sent"),       // a keyword, not the string "status/sent"
}], txId: "import-42" });                    // a retry with the same id applies once

await s.requestIndex(id, "invoice/status");
await s.awaitIndex(id, "invoice/status");
const { rows, next } = await s.query(id, { where: ["=", "invoice/status", kw("status/sent")], limit: 100 });
for await (const row of s.queryAll(id, { where: ["range", "invoice/due", localDate("2026-11-01"), null] })) { /* ... */ }

Values

| stratus | JavaScript | |---|---| | string, boolean, nil | string, boolean, null | | long | number within ±2^53, else bigint (write either) | | double | number (an integral one is written as a long: double(1) keeps a double) | | BigDecimal | Decimal (its text; no arithmetic) | | BigInteger, ratio | BigInteger, Ratio | | keyword, symbol, char | Keyword (kw("a/b"), interned), Sym, Char | | UUID | Uuid (uuid("..."), squuid(); interned) | | instant | Instant (nanoseconds; instant(date or ISO), .toDate()); a Date writes as one | | local date | LocalDate (localDate("2026-10-09")) | | bytes | Uint8Array | | vector, list, set | Array, List (list(1, 2)), Set | | map | a plain object (keys are attribute names); Map when keys aren't keywords |

A UUID, instant or keyword passed as a plain string is stored as a string and matches nothing of the intended type.

API

All methods return promises; failures reject with StratusError (status, error - e.g. "invalid-query", "conflict" -, message). 429s are retried with backoff (retries), and so is API Gateway's 403 Forbidden for a brand-new key, which works within a minute or two (newKeyWaitMs, 120000).

• Catalog: listDbs({deleted}), dbByName(name), dbRecord(id), createDb({name, primaryKey}), renameDb(id, name), deleteDb(id).
• A database: status(id), transact(id, {tx, retract, delete, txId, match}), query(id, q), queryAll(id, q) (async iterator), pull(id, pks, {asOf}) (and asOf: t in a query: the database as it stood after t), requestIndex(id, att, {required}) (att an attribute, or an array of 2 to 8 for a multi-attribute index: queried by tuples, ["=", ["a", "b"], [x, y]]; docs/query.md), awaitIndex(id, att), dropIndex(id, att), history(id, {from, limit}), historyAll, fork(id, {t, name}) (a new database, this one as of t), excise(id, {rows, attributes}) (erasure: rows and {pk, att} out of the state, indexes, history and forks), setHistoryRetention(id, days) (history kept 30 to 36500 days, or null for forever).
• Keys (with a key reaching every database): listKeys(), createKey({name, scope}), revokeKey(keyId).
• Codec: encode, decode (typed-JSON text), toJSONValue, fromJSONValue.

Queries: docs/query.md ("JSON"). Requests go to <url>/v1/dbs/<id>/... with Authorization: Bearer <apiKey>.

Tests

node --test test/ejson.test.js (the codec: velojity's own output in clients/fixtures/velojity-ejson.json, which stratus's client-fixtures-test keeps current), and scripts/test-js-client from the repo root: the codec, then the client against the hosted product run locally.