@drasi/lib on @drasi/lib Docs

JavaScript Sources

Mon, 01 Jan 0001 00:00:00 +0000

A JavaScript source lets you feed the engine directly from your application — an event stream, a webhook handler, database CDC, or anything else your code already sees. You register the source with addJsSource and push changes into it with pushChange. No Rust and no plugins required.

Register a source

import { Drasi } from '@drasi/lib';

const drasi = await Drasi.create('orders-app');
await drasi.start();

await drasi.addJsSource('orders');

A JS source maintains a current-state snapshot of the elements you’ve pushed, so a query that subscribes after you’ve already pushed changes still receives a bootstrap replay of the live elements.

Tutorial: Trading Demo

Mon, 01 Jan 0001 00:00:00 +0000

The trading demo is a self-contained desktop app that embeds @drasi/lib and renders live query results in its own window — no browser, no HTTP/SSE, no REST, no Python. It’s a faithful port of drasi-server’s examples/trading demo, and it’s the best way to see every concept in this documentation working together.

The full source is in examples/trading.

What it demonstrates

Real PostgreSQL CDC — reference data (stocks, portfolio, watchlist) lives in a real Postgres database and is streamed into the engine via Drasi’s Postgres source (logical replication) plus a Postgres bootstrap snapshot.
Synthetic joins — HAS_PRICE, OWNS_STOCK, and ON_WATCHLIST relate elements across sources (and across a database and a live feed) with no foreign keys, entirely inside the query. See Concepts → Synthetic joins.
In-process price feed — a tiny Node random-walk generator pushes stock_prices into a JavaScript source.
Application reactions — one addJsReaction per query streams result diffs straight to the renderer over a single IPC channel; the dashboard merges ADD/UPDATE/DELETE/aggregation diffs into live tables.
Plugins downloaded at runtime — the Postgres source and bootstrap plugins are pulled from ghcr.io/drasi-project on first launch and cached locally. Nothing is baked in. See Working with plugins.

Architecture

flowchart LR
 subgraph pg[PostgreSQL - Docker]
 T1[stocks]
 T2[portfolio]
 T3[watchlist]
 end
 subgraph main[Electron main - embeds @drasi/lib]
 PS[postgres source<br/>downloaded OCI]
 PF[price-feed<br/>JS source]
 Q[5 continuous queries<br/>+ synthetic joins]
 RX[addJsReaction]
 end
 R[Electron renderer<br/>React dashboard]

 pg -->|logical replication + bootstrap| PS
 PS --> Q
 PF -->|pushChange| Q
 Q --> RX
 RX -->|IPC: trading:stream| R

The native addon is N-API v9 (ABI-stable), so it loads directly in Electron’s main process with no electron-rebuild.

JavaScript Reactions

Mon, 01 Jan 0001 00:00:00 +0000

A JavaScript reaction is the simplest way to wire query results into your application: register a callback with addJsReaction and the engine invokes it with the result diffs each time a subscribed query’s result set changes.

Add a reaction

await drasi.addQuery(
 'hot-sensors',
 'MATCH (s:SensorReading) WHERE s.temperature > 25 RETURN s.sensor_id AS sensor, s.temperature AS temp',
 ['sensors'],
);

await drasi.addJsReaction('on-hot', ['hot-sensors'], (event) => {
 for (const diff of event.results) {
 if (diff.type === 'ADD') console.log('HOT:', diff.data);
 else if (diff.type === 'UPDATE') console.log('CHANGED:', diff.after);
 else if (diff.type === 'DELETE') console.log('COOLED:', diff.data);
 }
});

The callback receives a QueryResultEvent. It is invoked once per non-empty batch of changes — empty batches are skipped. A single reaction can subscribe to multiple queries by listing several ids in the second argument.

Working with Plugins

Mon, 01 Jan 0001 00:00:00 +0000

Beyond JavaScript sources and reactions, @drasi/lib can host Drasi’s native plugins — the same self-contained cdylib files (.so/.dylib/.dll) that drasi-server loads. This lets you connect to real systems (for example PostgreSQL) with the exact same connectors used in production Drasi deployments.

How plugin hosting works

A .node addon is itself a cdylib, so it can host the embeddable engine and dlopen plugin cdylibs through drasi-host-sdk — the same mechanism drasi-server uses. Each plugin is fully self-contained (its own async runtime) and talks to the host across a stable #[repr(C)] FFI with load-time version negotiation.

Error Handling

Mon, 01 Jan 0001 00:00:00 +0000

Argument and validation failures throw a stable, machine-readable code so your code can branch on it instead of matching human-readable messages. The DrasiErrorCode enum is exported from the package.

Branch on `err.code`

DrasiErrorCode is a regular (non-const) enum with string values. It is safe under isolatedModules / esbuild / swc / Vite and has a real runtime value, so both the type and the value are usable:

import { Drasi, DrasiErrorCode } from '@drasi/lib';

try {
 await drasi.addSource('unknown', 's', {});
} catch (err) {
 if ((err as { code?: string }).code === DrasiErrorCode.UnknownSourceKind) {
 // handle the unregistered-kind case
 }
}

Sync throws vs. async fallbacks

Because napi-rs can only attach a custom code on a synchronous throw (async promise rejections are forced to code === 'GenericFailure'), errors fall into two classes. The human-readable message is the same in both cases.

TypeScript Types

Mon, 01 Jan 0001 00:00:00 +0000

@drasi/lib ships first-class TypeScript support. The generated index.d.ts is self-contained: every config parameter, result, return value, and callback payload is exposed with a concrete type — no bare any — so you get full editor completion and type-checking out of the box.

Import types directly

import type { SourceChangeInput, QueryResultEvent } from '@drasi/lib';

const change: SourceChangeInput = { op: 'insert', id: 'o1', labels: ['Order'] };

const onResult = (event: QueryResultEvent) => console.log(event.results.length);

Types you’ll use most

Type	Where it appears
`CreateOptions`	`Drasi.create(id, options)`
`DrasiConfig`	`Drasi.fromConfig(config)`
`SourceChangeInput`	`pushChange(sourceId, change)`
`QueryJoin`	the `joins` argument to `addQuery` / `updateQuery`
`QueryResultEvent`, `ResultDiff`	JS reaction callbacks
`LogMessage`, `ComponentEvent`	streaming callbacks
`QueryMetrics`, `ReactionQueryMetrics`, `LifecycleMetrics`	the metrics accessors
`ComponentStatusEntry`	`listSources` / `listQueries` / `listReactions`
`DrasiErrorCode`	typed error handling (a real runtime enum)

`DrasiErrorCode` is a real value, not just a type

Unlike the shape types above, DrasiErrorCode is exported as a regular (non-const) enum with string values, so you can import it as a value and compare against it at runtime — safe under isolatedModules, esbuild, swc, and Vite:

@drasi/lib on @drasi/lib Docs

JavaScript Sources

Register a source

Tutorial: Trading Demo

What it demonstrates

Architecture

JavaScript Reactions

Add a reaction

Working with Plugins

How plugin hosting works

Error Handling

Branch on err.code

Sync throws vs. async fallbacks

TypeScript Types

Import types directly

Types you’ll use most

DrasiErrorCode is a real value, not just a type

Branch on `err.code`

`DrasiErrorCode` is a real value, not just a type