@databob/engine
v0.0.5
Published
The databob analytics runtime: typed event schemas, a JSON query language compiled to SQLite, per-tenant storage, embed tokens, and one HTTP API.
Readme
@databob/engine
The runtime behind @databob/sdk. Most apps install @databob/sdk; use this package to embed the engine or to host it.
schema (JSON) ──► prepareEvent ──► Tenants.insert ──► one SQLite database per tenant
metric (JSON) ──► compileQuery ──► Tenants.select ──► shapeAggregate / shapeFunnel
(bound SQL)
createHandler(): the HTTP API, identical on Node and Cloudflare| File | What it does |
| --- | --- |
| values.ts | Validators. Plain JSON at runtime, typed at compile time |
| schema.ts | defineSchema, event, and the checks that refuse personal-data property names |
| privacy.ts | Value checks: email, IP, phone, card number |
| events.ts | Turns an incoming event into a row: validates, hashes the user id, checks the tenant |
| query.ts | The typed builder. It produces a JSON query, never SQL |
| compile.ts | JSON query to SQLite. Fields are checked against the schema, values are bound |
| time.ts | Time zones without a tz database in SQL: offset segments plus a CASE in the query |
| store.ts | TenantStore over a 4-method SqlDriver, plus the Durable Object driver |
| engine.ts | Engine: track, metric, query, erase. Projects and Tenants are the two ports |
| http.ts | createHandler: auth (secret keys and embed tokens), routes, live server-sent events |
| token.ts | HMAC-signed embed tokens scoped to one tenant and optionally a list of metrics |
| node.ts | @databob/engine/node: node:sqlite driver, LocalTenants, StaticProjects, Node HTTP bridge |
Storage
Each tenant has its own database with one events table (ts, name, user hash, props JSON, idempotency key) and indexes on time, event and time, and user. Per-tenant data is small, so a query scans that tenant's rows directly; there are no rollup jobs and no snapshots. On Cloudflare each tenant is a Durable Object (cloud/), so an idle tenant costs nothing and dropping a tenant deletes its object's storage.
Ports
interface Projects { bySecretKey(key): Promise<ProjectConfig | null>; byId(id): Promise<ProjectConfig | null> }
interface Tenants {
insert(projectId, tenant, rows); select(projectId, tenant, sql, params);
eraseUser(projectId, userHash); drop(projectId, tenant);
subscribe?(projectId, tenant, onChange); // live queries poll every 10s without it
}Implement those two to run the engine anywhere SQLite runs.
License
FSL-1.1-ALv2 (LICENSE.md). Use it, change it, and self-host it, including inside a commercial product. Do not offer it as a competing hosted service. Each release becomes Apache-2.0 on its second anniversary.
