chronicle-js

The TypeScript SDK for chronicle — a datastore as a service where the writes are the record: @impire-io/chronicle. It speaks chronicle's SDK contract over nats.js, in the browser through a websocket and in Node, in the words of chronicle's vocabulary: a store holds types; you create instances of a type, named by a path (type/id, then name/id for each child); every change is an operation applied to an instance and kept in its history — replayable, nothing lost to an update; the current state is derived from it, one read away; the indexes you declare are derived from the same history.

npm install @impire-io/chronicle

Support

An SDK supports chronicle when it passes the conformance suite of the contract version it declares (chronicle design 12). This table is rendered from the suite's last result, never edited by hand:

| SDK | Contract | Suite (chronicle release) | Fixtures | Scenarios | Supports | | ---------------------------- | -------- | ------------------------- | ------------ | ----------- | -------- | | @impire-io/chronicle 0.5.1 | 3.3.0 | v0.11.0 | ✅ 95 passed | ✅ 5 passed | yes |

Connecting

To a local chronicle up --websocket-port 9222, as its one user:

import { Client } from "@impire-io/chronicle";
import { readFileSync } from "node:fs";

const dir = `${process.env.HOME}/.chronicle/dev`;
const c = await Client.connect({
  servers: readFileSync(`${dir}/websocket.url`, "utf8"),
  nkeySeed: readFileSync(`${dir}/user.nk`, "utf8"),
  author: "admin",
});

With a credential file the principal is the file's name: Client.connect({ servers, creds }). Any other transport — a Node TCP connection from @nats-io/transport-node — is adopted with Client.wrap(nc, principal).

To the hosted platform at chronicle.impire.dev, through the GitHub identity bridge — the install profile names the websocket and the sentinel:

import { connectBridge, connectIdentity, fetchInstallProfile } from "@impire-io/chronicle";

const profile = await fetchInstallProfile();
const auth = { servers: profile.websocket_url!, sentinel: profile.sentinel, githubToken };

const id = await connectIdentity(auth); // the identity plane
const { memberships } = await id.memberships();
const account = memberships[0]?.account ?? (await id.createAccount()).name;
await id.close();

const c = await connectBridge({ ...auth, account });

The profile also lists the solutions the environment hosts (profile.solutions, each a name and the address of its install manifest); fetchInstallManifest(address) reads one — the stores, the types and the announcement that enabling the solution in an account means (chronicle-hq design 14 § the install manifest).

An admin of an account issues a service account's credential on the same plane, and gets it back exactly once; rotateServiceAccount hands down a new credential for the same service account (the old one no longer connects) and revokeServiceAccount kills it:

const id = await connectIdentity(auth);
const { creds } = await id.issueServiceAccount(account, "billing-svc", "writer");
await id.close();

The sentences

Collections are async iterables; single values are replies (design 12 § the surface rule). Instances are named by path.

await c.createStore("orders");
await c.defineType("orders", "invoice", {
  schema: { type: "object", required: ["total"] },
  children: { comments: "comment" },
  operations: {
    create: { schema: { type: "object" }, effect: "merge" },
    send: { schema: { type: "object", required: ["to"] }, effect: "merge" },
    note: { schema: { type: "object" }, effect: "none" },
  },
});

await c.create("orders", "invoice/inv-1", "create", { total: 120 });
const { seq, state } = await c.state("orders", "invoice/inv-1");
await c.apply("orders", "invoice/inv-1", "send", { to: "x" }, { expectedSeq: seq });

for await (const op of c.history("orders", "invoice/inv-1")) console.log(op.seq, op.type);
for await (const i of c.listInstances("orders", { type: "invoice", where: { to: "x" } }))
  console.log(i.path, i.state);
for await (const i of c.listInstances("orders", { under: "invoice/inv-1" })) console.log(i.path); // its children

const ctl = new AbortController();
for await (const sv of c.watch("orders", "invoice/inv-1", { signal: ctl.signal })) render(sv.state);

await c.snapshot("orders", "invoice/inv-1"); // the current state as one entry; the history before it compacted

await c.declareIndex("orders", "text", "search");
const hits = c.queryIndex("orders", "text", "widgets");
for await (const hit of hits) console.log(hit.instance, hit.score);
console.log(hits.trailer?.total);

await c.addMember("jordan", "reader", { githubId: 4242 });
await c.addServiceAccount("billing-svc", "writer");
await c.setRole("jordan", "admin"); // in place, from jordan's next request on; the only admin keeps the role

await c.deleteType("orders", "invoice"); // its instances keep their history, untyped until the type is defined again
await c.deleteStore("orders"); // total: history, state and indexes go, whatever the history policy; the name is free again

Writes are checked before they are sent: data that fails its operation's schema is a SchemaViolationError, an operation the type does not define an UndefinedOperationError, a child the parent type does not declare an UndeclaredChildError, a create whose path resolves to no type a NoTypeError (createFromSnapshot is the untyped form). A write whose expected sequence the instance moved past is an InstanceMovedError; a create of an instance that exists is an InstanceExistsError; a service's refusal is a ServiceError carrying a code from the contract's error catalog. Where the environment resolves roles itself (chronicle's --roles callout, chronicle-hq decision 0061), addMember, addServiceAccount, setRole and revokeMember are refused with membership-elsewhere — membership is managed where the roles live — and a verb or query whose role check the environment's responder did not answer is refused with role-source-unavailable, never answered from the registry.

Developing

make check is the gate — see CONTRIBUTING.md. Licensed under the Apache License 2.0.