@bob-kit/client

> Disclaimer:
> Bob is under development! Use at your own risk.

Official Bob client for consuming the bob DSL from JavaScript/TypeScript.

This package loads Bob’s runtime (WASM) and exposes a small API to:

- Transpile your bob input into SQL for a given engine (SQLite, MariaDB/MySQL, PostgreSQL).
- Automatically execute the generated SQL using a Driver you provide.
- Optionally cache transpilation results.

What is Bob?

Bob is a lightweight, declarative transpiler that lets you define database schemas and queries using a simple, human‑readable DSL called bob.
Bob then converts those definitions into SQL for multiple engines such as SQLite, MariaDB/MySQL, and PostgreSQL.

Instead of writing verbose SQL by hand, you describe tables, relationships, and queries concisely, and Bob generates the corresponding SQL.

Installation

With pnpm:

``bash
pnpm add @bob-kit/client
`

With npm:

`bash
npm i @bob-kit/client
`

With yarn:

`bash
yarn add @bob-kit/client
`

Environment requirements

Right now, @bob-kit/client loads the WASM using Node APIs (fs, vm).
That means it’s currently Node.js-oriented (not browser) as implemented today.

Concepts: Driver and cache

The client needs a Driver (from @bob-kit/types) to execute the generated SQL:

- driver: target engine ("sqlite" | "mariadb" | "mysql" | "postgres").
- querier(query, ...params): async function that executes SQL (and returns rows for SELECT).
- cache: optional implementation to cache transpilation results (memory, redis, etc.).

This package also exports a ready-to-use in-memory cache: MemoryCache.

Quick start (Node + SQLite)

Complete example using @bob-kit/sqlite as the querier:

`ts
import bob from "@bob-kit/client";
import { MemoryCache } from "@bob-kit/client/cache";
import { sqlite } from "@bob-kit/sqlite";

const querier = sqlite(":memory:");

const client = bob({
driver: "sqlite",
querier,
cache: new MemoryCache(),
});

// 1) Define multiple tables in a single query
await client.query
table Profile {
id id
avatar string
}

table Users {
id id
name string
lastName string
Profile
}
;

// 2) Insert one entity
await client.query
new Profile {
avatar "bear"
}
;

// 3) Bulk insert with multiple rows and columns
await client.query
new Users name lastName Profile.id {
"John" "Doe" 1
"Mary" "Jane" 3
"Robert" "Smith" 3
}
;

// 4) Create reusable query functions with types
const getUserByName = (name: string) => client.query
get Users {
name
profile_id

-> Profile {
avatar
}

desc Profile.id
}
;

const users = await getUserByName("John");
`

$3

#### Joins and relationships

`ts
// Join with related table
const usersWithProfiles = await client.query
get Users {
id
name
lastName

-> Profile {
avatar
}
}
;
`

#### Filtering and sorting

`ts
const filteredUsers = await client.query
get Users {
id
name
if name = "John" || "Mary"
}
;

const sortedUsers = await client.query
get Users {
id
name
desc id
}
;
`

$3

The API accepts parameters as arguments to query(...). Internally, the template literal is converted to a string using ? as the placeholder.

`ts
const byEmail = await client.query
get Users {
id
name
email
if email == ?
}
("ada@lovelace.dev");
`

API

$3

Creates a client instance.

Returns an object with:

- query(input, ...params): Promise: executes a bob input. You can destructure it for convenience: const { query: b } = bob(...).
- cache(id)(input, ...params): Promise: same as query, but caches the transpilation result under a fixed id.
- factory.(input, ...params): Promise: shortcut for cache("")(...).

$3

Low-level function that only performs transpilation (and applies cache if present). You usually won’t need it.

$3

Includes:

- MemoryCache: in-memory (Map) cache for BobQueryResult.

Errors

When Bob returns a parsing/validation/transpilation error, the client throws BobError with:

- name: a value from BobErrors (from @bob-kit/types/errors)
- message: error details

Important notes

- Multiple actions: if your input generates more than 1 SQL action, the client throws (MultipleActions).
The current flow assumes 0 or 1 action per execution.
- Table execution: if the output includes tables`, all of them are executed (in order) before the action/query.