TypeScript SDK

A self-contained client for Node and Bun. The engine ships inside the package.

npm i jevql

That is the whole install. The package has no runtime dependencies and pulls in a small platform package with the jevql engine for your OS and CPU (@jevql/engine-darwin-arm64, -darwin-x64, -linux-x64, -linux-arm64). Node 18+ or Bun.

Embedded engine

import { Jevql } from "jevql"

const db = new Jevql()   // starts a private engine on localhost on first use

const res = await db.query(
  "SELECT name, jev_prob(people, 'could work from home') AS p FROM people WHERE country = 'PT' ORDER BY p DESC LIMIT 5",
  { threshold: 0.6 },
)
res.columns  // ["name", "p"]
res.rows     // [["Miguel Costa", 0.94], ...]
res.stats    // { judged: 6, requests: 1, cache_hits: 0, usd: 0.00005, ... }

const tickets = await db.queryObjects("SELECT * FROM tickets WHERE jev(tickets, 'is about billing')")
await db.close()         // stops the engine; it also stops when your process exits

The engine reads DATABASE_URL, PG*, TYPESAFE_API_KEY, TYPESAFE_API_URL and JEV_THRESHOLD from your environment, exactly like the CLI. Pass options to override:

new Jevql({
  databaseUrl: "postgres://...",
  apiKey: process.env.TYPESAFE_API_KEY,
  model: "jev-latest",
  threshold: 0.5,
  maxRows: 2500,
  cachePath: "~/.cache/jevql/cache.db",   // or noCache: true
  enginePath: "/opt/jevql/bin/jevql",     // rarely needed, see below
})

Remote engine

For a team, run one engine and share its cache:

jevql serve --listen 0.0.0.0:7433 --token secret    # behind your own TLS proxy

const db = new Jevql({ url: "https://jev.internal", token: process.env.JEVQL_TOKEN })

Same methods, same result shapes.

Engine discovery

The embedded mode finds the binary in this order: enginePath, the JEVQL_ENGINE_PATH environment variable, the bundled platform package, then jevql on your PATH. If none exists you get a JevqlError with code transport naming the install commands.

Errors

Every failure is a JevqlError with code (sql, budget, api, auth, internal, transport) and, for HTTP responses, status:

import { JevqlError } from "jevql"
try {
  await db.query("SELECT * FROM nope")
} catch (e) {
  if (e instanceof JevqlError && e.code === "sql") console.error(e.message)
}

Types

QueryResult, Stats, Explain and JevqlOptions are exported. rows is unknown[][]; queryObjects returns Record<string, unknown>[].

Edit this page on GitHub ↗