@bob-kit/client 0.0.28 → 0.0.30

package/README.md

@@ -0,0 +1,208 @@
+# @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");
+```
+
+### Advanced examples
+
+#### 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
+  }
+`;
+```
+
+### Parameters
+
+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
+
+### `default export function bob(driver: Driver)`
+
+Creates a client instance.
+
+Returns an object with:
+
+- **`query<A>(input, ...params): Promise<A[]>`**: executes a `bob` input. You can destructure it for convenience: `const { query: b } = bob(...)`.
+- **`cache(id)(input, ...params): Promise<A[]>`**: same as `query`, but caches the transpilation result under a fixed `id`.
+- **`factory.<id>(input, ...params): Promise<A[]>`**: shortcut for `cache("<id>")(...)`.
+
+### `bobQuery({ driver, input, id? })`
+
+Low-level function that only performs transpilation (and applies cache if present). You usually won’t need it.
+
+### `@bob-kit/client/cache`
+
+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.

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@bob-kit/client",
-  "version": "0.0.28",
+  "version": "0.0.30",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "description": "",
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "exports": {
     ".": {
@@ -28,7 +29,7 @@
     "typescript": "5.9.3"
   },
   "dependencies": {
-    "@bob-kit/types": "^0.0.11"
+    "@bob-kit/types": "^0.0.12"
   },
   "scripts": {
     "build": "tsc && tsc-alias",