@ikeboy003/cloudrest-client 0.0.1

package/dist/rpc.js

@@ -0,0 +1,50 @@
+// RPC caller. Posts JSON args to `/rpc/<name>` and returns the parsed body.
+// Awaitable directly (PromiseLike), matching the QueryBuilder ergonomics:
+//
+//   const result = await db.rpc("update_mastery", { p_concept_id, p_correct: true });
+//
+// PostgREST RPC convention:
+//   - POST /rpc/<fn>  body = { argName: value, ... }
+//   - Response is the function return — scalar, row, or set-of rows.
+import { CloudRestError } from "./errors.js";
+export class RpcCaller {
+    ctx;
+    fn;
+    args;
+    constructor(ctx, fn, args = {}) {
+        this.ctx = ctx;
+        this.fn = fn;
+        this.args = args;
+    }
+    async exec() {
+        const url = `${this.ctx.baseUrl}/rpc/${this.fn}`;
+        const headers = {
+            Accept: "application/json",
+            "Content-Type": "application/json",
+            ...this.ctx.headers,
+        };
+        const token = await this.ctx.getToken?.();
+        if (token)
+            headers["Authorization"] = `Bearer ${token}`;
+        const res = await this.ctx.fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(this.args),
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => "");
+            throw new CloudRestError(res.status, res.statusText, body);
+        }
+        // Functions returning void produce 204; everything else returns JSON.
+        if (res.status === 204)
+            return undefined;
+        const text = await res.text();
+        if (!text)
+            return undefined;
+        return JSON.parse(text);
+    }
+    then(onfulfilled, onrejected) {
+        return this.exec().then(onfulfilled, onrejected);
+    }
+}
+//# sourceMappingURL=rpc.js.map

package/dist/rpc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc.js","sourceRoot":"","sources":["../src/rpc.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,0EAA0E;AAC1E,EAAE;AACF,sFAAsF;AACtF,EAAE;AACF,4BAA4B;AAC5B,qDAAqD;AACrD,qEAAqE;AAGrE,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,OAAO,SAAS;IAED;IACA;IACA;IAHnB,YACmB,GAAgB,EAChB,EAAU,EACV,OAAgC,EAAE;QAFlC,QAAG,GAAH,GAAG,CAAa;QAChB,OAAE,GAAF,EAAE,CAAQ;QACV,SAAI,GAAJ,IAAI,CAA8B;IAClD,CAAC;IAEI,KAAK,CAAC,IAAI;QAChB,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,QAAQ,IAAI,CAAC,EAAE,EAAE,CAAC;QACjD,MAAM,OAAO,GAA2B;YACtC,MAAM,EAAE,kBAAkB;YAC1B,cAAc,EAAE,kBAAkB;YAClC,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO;SACpB,CAAC;QACF,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,CAAC;QAC1C,IAAI,KAAK;YAAE,OAAO,CAAC,eAAe,CAAC,GAAG,UAAU,KAAK,EAAE,CAAC;QAExD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE;YACpC,MAAM,EAAE,MAAM;YACd,OAAO;YACP,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC;SAChC,CAAC,CAAC;QAEH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;YAC9C,MAAM,IAAI,cAAc,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QAC7D,CAAC;QAED,sEAAsE;QACtE,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;YAAE,OAAO,SAAmB,CAAC;QACnD,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QAC9B,IAAI,CAAC,IAAI;YAAE,OAAO,SAAmB,CAAC;QACtC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAW,CAAC;IACpC,CAAC;IAED,IAAI,CACF,WAA8D,EAC9D,UAA+D;QAE/D,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,UAAmB,CAAC,CAAC;IAC5D,CAAC;CACF"}

package/dist/serialize.d.ts

@@ -0,0 +1,2 @@
+export declare function serializeValue(v: unknown): string;
+//# sourceMappingURL=serialize.d.ts.map

package/dist/serialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../src/serialize.ts"],"names":[],"mappings":"AAgBA,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAOjD"}

package/dist/serialize.js

@@ -0,0 +1,46 @@
+// PostgREST-grammar value serialization. Mirrors the server's parser
+// expectations: see cloudrest-workerd/src/parser/operators.ts.
+//
+// Rules:
+// - null  → "null"  (use with `is.null`, never `eq.null`)
+// - Date  → ISO string
+// - array → "(a,b,c)" with each element quoted if it contains special chars
+// - string with special chars → wrapped in double quotes, internal " → \"
+// Scalar values: only `,` and `"` need quoting. Parens / dots / spaces
+// are fine bare — wrapping them in quotes makes the server search for
+// the literal quoted string and return 0 rows.
+const SCALAR_SPECIAL = /[,"]/;
+// List items are inside `(a,b,c)`, so `(`, `)`, and `,` all need quoting.
+const LIST_SPECIAL = /[(),."]/;
+export function serializeValue(v) {
+    if (v === null || v === undefined)
+        return "null";
+    if (v instanceof Date)
+        return v.toISOString();
+    if (Array.isArray(v))
+        return `(${v.map(serializeListItem).join(",")})`;
+    if (typeof v === "boolean")
+        return v ? "true" : "false";
+    if (typeof v === "number" || typeof v === "bigint")
+        return String(v);
+    return escapeIfNeeded(String(v), SCALAR_SPECIAL);
+}
+function serializeListItem(v) {
+    if (v === null || v === undefined)
+        return "null";
+    if (v instanceof Date)
+        return v.toISOString();
+    if (typeof v === "boolean")
+        return v ? "true" : "false";
+    if (typeof v === "number" || typeof v === "bigint")
+        return String(v);
+    return escapeIfNeeded(String(v), LIST_SPECIAL);
+}
+function escapeIfNeeded(s, special) {
+    if (s === "")
+        return '""';
+    if (!special.test(s))
+        return s;
+    return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+//# sourceMappingURL=serialize.js.map

package/dist/serialize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.js","sourceRoot":"","sources":["../src/serialize.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,+DAA+D;AAC/D,EAAE;AACF,SAAS;AACT,0DAA0D;AAC1D,uBAAuB;AACvB,4EAA4E;AAC5E,0EAA0E;AAE1E,uEAAuE;AACvE,sEAAsE;AACtE,+CAA+C;AAC/C,MAAM,cAAc,GAAG,MAAM,CAAC;AAC9B,0EAA0E;AAC1E,MAAM,YAAY,GAAG,SAAS,CAAC;AAE/B,MAAM,UAAU,cAAc,CAAC,CAAU;IACvC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IACjD,IAAI,CAAC,YAAY,IAAI;QAAE,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC;IAC9C,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IACvE,IAAI,OAAO,CAAC,KAAK,SAAS;QAAE,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;IACxD,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;IACrE,OAAO,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC;AACnD,CAAC;AAED,SAAS,iBAAiB,CAAC,CAAU;IACnC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IACjD,IAAI,CAAC,YAAY,IAAI;QAAE,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC;IAC9C,IAAI,OAAO,CAAC,KAAK,SAAS;QAAE,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;IACxD,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;IACrE,OAAO,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC;AACjD,CAAC;AAED,SAAS,cAAc,CAAC,CAAS,EAAE,OAAe;IAChD,IAAI,CAAC,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC1B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC;IAC/B,OAAO,IAAI,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC;AAC9D,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,21 @@
+export type AnyPaths = Record<string, any>;
+export type RowOf<P extends AnyPaths, T extends keyof P> = P[T] extends {
+    get: {
+        responses: {
+            200: {
+                content: {
+                    "application/json": infer Body;
+                };
+            };
+        };
+    };
+} ? Body extends ReadonlyArray<infer Item> ? Item : Body : never;
+export type TableName<P extends AnyPaths> = Extract<keyof P, string>;
+export type TokenGetter = () => string | null | Promise<string | null>;
+export interface ClientOptions {
+    baseUrl: string;
+    getToken?: TokenGetter;
+    headers?: Record<string, string>;
+    fetch?: typeof fetch;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAK3C,MAAM,MAAM,KAAK,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,MAAM,CAAC,IACrD,CAAC,CAAC,CAAC,CAAC,SAAS;IAAE,GAAG,EAAE;QAAE,SAAS,EAAE;YAAE,GAAG,EAAE;gBAAE,OAAO,EAAE;oBAAE,kBAAkB,EAAE,MAAM,IAAI,CAAA;iBAAE,CAAA;aAAE,CAAA;SAAE,CAAA;KAAE,CAAA;CAAE,GACzF,IAAI,SAAS,aAAa,CAAC,MAAM,IAAI,CAAC,GACpC,IAAI,GACJ,IAAI,GACN,KAAK,CAAC;AAGZ,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;AAGrE,MAAM,MAAM,WAAW,GAAG,MAAM,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AAEvE,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB"}

package/dist/types.js

@@ -0,0 +1,8 @@
+// Generic helpers that let callers parameterize the client with their
+// openapi-typescript-generated `paths` interface.
+//
+// Usage:
+//   import type { paths } from "./schema";
+//   const db = createClient<paths>({ baseUrl, getToken });
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,kDAAkD;AAClD,EAAE;AACF,SAAS;AACT,2CAA2C;AAC3C,2DAA2D"}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@ikeboy003/cloudrest-client",
+  "version": "0.0.1",
+  "description": "Typed query builder for cloudrest. PostgREST-grammar compatible.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "src", "README.md"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0"
+  }
+}

package/src/client.ts

@@ -0,0 +1,57 @@
+import type { AnyPaths, ClientOptions, RowOf, TableName } from "./types.js";
+import { QueryBuilder, type ExecContext } from "./query.js";
+import { InsertBuilder, UpdateBuilder, DeleteBuilder } from "./mutation.js";
+import { RpcCaller } from "./rpc.js";
+
+export class CloudRestClient<P extends AnyPaths> {
+  private readonly ctx: ExecContext;
+
+  constructor(opts: ClientOptions) {
+    // Trim trailing slash so we can always use `${baseUrl}/table` cleanly.
+    const baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    this.ctx = {
+      baseUrl,
+      getToken: opts.getToken,
+      fetch: opts.fetch ?? globalThis.fetch.bind(globalThis),
+      headers: opts.headers ?? {},
+    };
+  }
+
+  /** Start a typed read query against `table`. */
+  from<T extends TableName<P>>(table: T): QueryBuilder<P, T> {
+    return new QueryBuilder<P, T>(this.ctx, table);
+  }
+
+  /** Insert one row or many rows into `table`. Add `.returning()` to get them back. */
+  insert<T extends TableName<P>>(
+    table: T,
+    rows: Partial<RowOf<P, T>> | Partial<RowOf<P, T>>[],
+  ): InsertBuilder<P, T> {
+    return new InsertBuilder<P, T>(this.ctx, table, rows);
+  }
+
+  /** Update rows in `table` matching subsequent filters. */
+  update<T extends TableName<P>>(
+    table: T,
+    patch: Partial<RowOf<P, T>>,
+  ): UpdateBuilder<P, T> {
+    return new UpdateBuilder<P, T>(this.ctx, table, patch);
+  }
+
+  /** Delete rows in `table` matching subsequent filters. */
+  delete<T extends TableName<P>>(table: T): DeleteBuilder<P, T> {
+    return new DeleteBuilder<P, T>(this.ctx, table);
+  }
+
+  /** Call a Postgres function via `POST /rpc/<fn>`. Awaitable. */
+  rpc<Result = unknown>(
+    fn: string,
+    args: Record<string, unknown> = {},
+  ): RpcCaller<Result> {
+    return new RpcCaller<Result>(this.ctx, fn, args);
+  }
+}
+
+export function createClient<P extends AnyPaths>(opts: ClientOptions): CloudRestClient<P> {
+  return new CloudRestClient<P>(opts);
+}

package/src/errors.ts

@@ -0,0 +1,10 @@
+export class CloudRestError extends Error {
+  constructor(
+    public status: number,
+    public statusText: string,
+    public body?: unknown,
+  ) {
+    super(`${status} ${statusText}`);
+    this.name = "CloudRestError";
+  }
+}

package/src/filter.ts

@@ -0,0 +1,50 @@
+// Filter ops — v0 covers the 80% of queries: equality, comparison, set membership,
+// null checks, pattern match. Composite ops (or, and, fts, jsonpath) come later.
+//
+// Each filter contributes one entry to URLSearchParams as `column=op.value`.
+
+import { serializeValue } from "./serialize.js";
+
+export type IsValue = "null" | "true" | "false" | "unknown";
+
+export interface FilterEntry {
+  column: string;
+  expr: string;
+}
+
+export function fEq(column: string, value: unknown): FilterEntry {
+  return { column, expr: `eq.${serializeValue(value)}` };
+}
+export function fNeq(column: string, value: unknown): FilterEntry {
+  return { column, expr: `neq.${serializeValue(value)}` };
+}
+export function fGt(column: string, value: unknown): FilterEntry {
+  return { column, expr: `gt.${serializeValue(value)}` };
+}
+export function fGte(column: string, value: unknown): FilterEntry {
+  return { column, expr: `gte.${serializeValue(value)}` };
+}
+export function fLt(column: string, value: unknown): FilterEntry {
+  return { column, expr: `lt.${serializeValue(value)}` };
+}
+export function fLte(column: string, value: unknown): FilterEntry {
+  return { column, expr: `lte.${serializeValue(value)}` };
+}
+export function fLike(column: string, pattern: string): FilterEntry {
+  return { column, expr: `like.${serializeValue(pattern)}` };
+}
+export function fIlike(column: string, pattern: string): FilterEntry {
+  return { column, expr: `ilike.${serializeValue(pattern)}` };
+}
+export function fIn(column: string, values: readonly unknown[]): FilterEntry {
+  return { column, expr: `in.${serializeValue(values)}` };
+}
+// `is` is the correct way to check NULL / boolean — `eq.null` is a no-op in SQL.
+export function fIs(column: string, value: IsValue): FilterEntry {
+  return { column, expr: `is.${value}` };
+}
+// Negate any single-op filter: PostgREST prefixes the operator with `not.`
+// e.g. `column=not.is.null`, `column=not.eq.5`.
+export function fNot(entry: FilterEntry): FilterEntry {
+  return { column: entry.column, expr: `not.${entry.expr}` };
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export { createClient, CloudRestClient } from "./client.js";
+export { CloudRestError } from "./errors.js";
+export { QueryBuilder } from "./query.js";
+export { InsertBuilder, UpdateBuilder, DeleteBuilder } from "./mutation.js";
+export { RpcCaller } from "./rpc.js";
+export type {
+  AnyPaths,
+  ClientOptions,
+  RowOf,
+  TableName,
+  TokenGetter,
+} from "./types.js";
+export type { OrderOptions } from "./query.js";
+export type { IsValue } from "./filter.js";

package/src/mutation.ts

@@ -0,0 +1,158 @@
+// Mutations: insert / update / delete. PostgREST conventions:
+// - POST /table     with array body → insert
+// - PATCH /table?filters → update
+// - DELETE /table?filters → delete
+// - Prefer: return=representation header makes the server return rows.
+
+import type { AnyPaths, RowOf, TableName } from "./types.js";
+import {
+  fEq, fNeq, fGt, fGte, fLt, fLte, fLike, fIlike, fIn, fIs,
+  type FilterEntry, type IsValue,
+} from "./filter.js";
+import type { ExecContext } from "./query.js";
+
+class FilterableMutation<Row> {
+  protected filters: FilterEntry[] = [];
+  eq(col: string, v: unknown): this { this.filters.push(fEq(col, v)); return this; }
+  neq(col: string, v: unknown): this { this.filters.push(fNeq(col, v)); return this; }
+  gt(col: string, v: unknown): this { this.filters.push(fGt(col, v)); return this; }
+  gte(col: string, v: unknown): this { this.filters.push(fGte(col, v)); return this; }
+  lt(col: string, v: unknown): this { this.filters.push(fLt(col, v)); return this; }
+  lte(col: string, v: unknown): this { this.filters.push(fLte(col, v)); return this; }
+  like(col: string, pat: string): this { this.filters.push(fLike(col, pat)); return this; }
+  ilike(col: string, pat: string): this { this.filters.push(fIlike(col, pat)); return this; }
+  in(col: string, vals: readonly unknown[]): this { this.filters.push(fIn(col, vals)); return this; }
+  is(col: string, v: IsValue): this { this.filters.push(fIs(col, v)); return this; }
+}
+
+async function send(
+  ctx: ExecContext,
+  method: "POST" | "PATCH" | "DELETE",
+  url: string,
+  body: unknown | undefined,
+  returnRepresentation: boolean,
+): Promise<unknown> {
+  const headers: Record<string, string> = {
+    Accept: "application/json",
+    "Content-Type": "application/json",
+    ...ctx.headers,
+  };
+  if (returnRepresentation) headers["Prefer"] = "return=representation";
+  const token = await ctx.getToken?.();
+  if (token) headers["Authorization"] = `Bearer ${token}`;
+
+  const res = await ctx.fetch(url, {
+    method,
+    headers,
+    ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+  });
+  if (!res.ok) {
+    const errBody = await res.json().catch(() => null);
+    const { CloudRestError } = await import("./errors.js");
+    throw new CloudRestError(res.status, res.statusText, errBody);
+  }
+  if (res.status === 204) return [];
+  return res.json();
+}
+
+export class InsertBuilder<P extends AnyPaths, T extends TableName<P>, Row = RowOf<P, T>>
+  implements PromiseLike<Row[]>
+{
+  private rows: Partial<Row>[];
+  private returnRows = false;
+
+  constructor(
+    private readonly ctx: ExecContext,
+    private readonly table: T,
+    rows: Partial<Row> | Partial<Row>[],
+  ) {
+    this.rows = Array.isArray(rows) ? rows : [rows];
+  }
+
+  /** Return inserted rows (adds Prefer: return=representation). */
+  returning(): this {
+    this.returnRows = true;
+    return this;
+  }
+
+  then<R1 = Row[], R2 = never>(
+    onfulfilled?: ((value: Row[]) => R1 | PromiseLike<R1>) | null,
+    onrejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null,
+  ): PromiseLike<R1 | R2> {
+    const url = `${this.ctx.baseUrl}${String(this.table)}`;
+    return send(this.ctx, "POST", url, this.rows, this.returnRows)
+      .then((v) => v as Row[])
+      .then(onfulfilled, onrejected as never);
+  }
+}
+
+export class UpdateBuilder<P extends AnyPaths, T extends TableName<P>, Row = RowOf<P, T>>
+  extends FilterableMutation<Row>
+  implements PromiseLike<Row[]>
+{
+  private returnRows = false;
+
+  constructor(
+    private readonly ctx: ExecContext,
+    private readonly table: T,
+    private readonly patch: Partial<Row>,
+  ) {
+    super();
+  }
+
+  returning(): this {
+    this.returnRows = true;
+    return this;
+  }
+
+  private url(): string {
+    const params = new URLSearchParams();
+    for (const f of this.filters) params.append(f.column, f.expr);
+    const qs = params.toString();
+    return `${this.ctx.baseUrl}${String(this.table)}${qs ? `?${qs}` : ""}`;
+  }
+
+  then<R1 = Row[], R2 = never>(
+    onfulfilled?: ((value: Row[]) => R1 | PromiseLike<R1>) | null,
+    onrejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null,
+  ): PromiseLike<R1 | R2> {
+    return send(this.ctx, "PATCH", this.url(), this.patch, this.returnRows)
+      .then((v) => v as Row[])
+      .then(onfulfilled, onrejected as never);
+  }
+}
+
+export class DeleteBuilder<P extends AnyPaths, T extends TableName<P>, Row = RowOf<P, T>>
+  extends FilterableMutation<Row>
+  implements PromiseLike<Row[]>
+{
+  private returnRows = false;
+
+  constructor(
+    private readonly ctx: ExecContext,
+    private readonly table: T,
+  ) {
+    super();
+  }
+
+  returning(): this {
+    this.returnRows = true;
+    return this;
+  }
+
+  private url(): string {
+    const params = new URLSearchParams();
+    for (const f of this.filters) params.append(f.column, f.expr);
+    const qs = params.toString();
+    return `${this.ctx.baseUrl}${String(this.table)}${qs ? `?${qs}` : ""}`;
+  }
+
+  then<R1 = Row[], R2 = never>(
+    onfulfilled?: ((value: Row[]) => R1 | PromiseLike<R1>) | null,
+    onrejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null,
+  ): PromiseLike<R1 | R2> {
+    return send(this.ctx, "DELETE", this.url(), undefined, this.returnRows)
+      .then((v) => v as Row[])
+      .then(onfulfilled, onrejected as never);
+  }
+}

package/src/query.ts

@@ -0,0 +1,152 @@
+// Read query builder. Chainable, immutable-ish: each call returns `this` after
+// pushing to internal state. Terminal `then` (PromiseLike) makes the builder
+// awaitable directly:
+//
+//   const rows = await db.from("x").select("a,b").eq("a", 1);
+
+import type { AnyPaths, RowOf, TableName } from "./types.js";
+import {
+  fEq, fNeq, fGt, fGte, fLt, fLte, fLike, fIlike, fIn, fIs, fNot,
+  type FilterEntry, type IsValue,
+} from "./filter.js";
+import type { CloudRestError } from "./errors.js";
+
+export interface ExecContext {
+  baseUrl: string;
+  getToken?: () => string | null | Promise<string | null>;
+  fetch: typeof fetch;
+  headers: Record<string, string>;
+}
+
+export interface OrderOptions {
+  ascending?: boolean;
+  nullsFirst?: boolean;
+}
+
+export class QueryBuilder<P extends AnyPaths, T extends TableName<P>, Row = RowOf<P, T>>
+  implements PromiseLike<Row[]>
+{
+  private filters: FilterEntry[] = [];
+  private selectExpr?: string;
+  private orderExpr?: string;
+  private limitN?: number;
+  private offsetN?: number;
+  private rangeFrom?: number;
+  private rangeTo?: number;
+  private singleMode = false;
+
+  constructor(
+    private readonly ctx: ExecContext,
+    private readonly table: T,
+  ) {}
+
+  // ── projection ──────────────────────────────────────────────────────────
+  select(columns: string): this {
+    this.selectExpr = columns;
+    return this;
+  }
+
+  // ── filters ─────────────────────────────────────────────────────────────
+  eq(col: string, v: unknown): this { this.filters.push(fEq(col, v)); return this; }
+  neq(col: string, v: unknown): this { this.filters.push(fNeq(col, v)); return this; }
+  gt(col: string, v: unknown): this { this.filters.push(fGt(col, v)); return this; }
+  gte(col: string, v: unknown): this { this.filters.push(fGte(col, v)); return this; }
+  lt(col: string, v: unknown): this { this.filters.push(fLt(col, v)); return this; }
+  lte(col: string, v: unknown): this { this.filters.push(fLte(col, v)); return this; }
+  like(col: string, pat: string): this { this.filters.push(fLike(col, pat)); return this; }
+  ilike(col: string, pat: string): this { this.filters.push(fIlike(col, pat)); return this; }
+  in(col: string, vals: readonly unknown[]): this { this.filters.push(fIn(col, vals)); return this; }
+  is(col: string, v: IsValue): this { this.filters.push(fIs(col, v)); return this; }
+  // Negated `is` — e.g. `notIs("col", "null")` → `col=not.is.null`.
+  notIs(col: string, v: IsValue): this { this.filters.push(fNot(fIs(col, v))); return this; }
+  // Generic negation: pass the column + a non-negated filter helper output.
+  not(entry: FilterEntry): this { this.filters.push(fNot(entry)); return this; }
+
+  // ── ordering / paging ───────────────────────────────────────────────────
+  order(column: string, opts: OrderOptions = {}): this {
+    const { ascending = true, nullsFirst } = opts;
+    const parts = [column, ascending ? "asc" : "desc"];
+    if (nullsFirst !== undefined) parts.push(nullsFirst ? "nullsfirst" : "nullslast");
+    this.orderExpr = (this.orderExpr ? `${this.orderExpr},` : "") + parts.join(".");
+    return this;
+  }
+  limit(n: number): this { this.limitN = n; return this; }
+  offset(n: number): this { this.offsetN = n; return this; }
+  range(from: number, to: number): this { this.rangeFrom = from; this.rangeTo = to; return this; }
+
+  // ── result shape ────────────────────────────────────────────────────────
+  /**
+   * Expect exactly one row. Resolves to `Row` (not `Row[]`).
+   * Throws if 0 or >1 rows match.
+   */
+  single(): SingleQuery<Row> {
+    this.singleMode = true;
+    return this as unknown as SingleQuery<Row>;
+  }
+
+  // ── build + execute ─────────────────────────────────────────────────────
+  private buildUrl(): string {
+    const params = new URLSearchParams();
+    if (this.selectExpr) params.set("select", this.selectExpr);
+    for (const f of this.filters) params.append(f.column, f.expr);
+    if (this.orderExpr) params.set("order", this.orderExpr);
+    if (this.limitN !== undefined) params.set("limit", String(this.limitN));
+    if (this.offsetN !== undefined) params.set("offset", String(this.offsetN));
+    const qs = params.toString();
+    return `${this.ctx.baseUrl}${String(this.table)}${qs ? `?${qs}` : ""}`;
+  }
+
+  private async exec(): Promise<Row[]> {
+    const url = this.buildUrl();
+    const headers: Record<string, string> = {
+      Accept: "application/json",
+      ...this.ctx.headers,
+    };
+    if (this.rangeFrom !== undefined && this.rangeTo !== undefined) {
+      headers["Range-Unit"] = "items";
+      headers["Range"] = `${this.rangeFrom}-${this.rangeTo}`;
+    }
+    const token = await this.ctx.getToken?.();
+    if (token) headers["Authorization"] = `Bearer ${token}`;
+
+    const res = await this.ctx.fetch(url, { method: "GET", headers });
+    if (!res.ok) {
+      const body = await res.json().catch(() => null);
+      const { CloudRestError } = await import("./errors.js");
+      throw new CloudRestError(res.status, res.statusText, body);
+    }
+    const rows = (await res.json()) as Row[];
+    if (this.singleMode) {
+      if (rows.length !== 1) {
+        const { CloudRestError } = await import("./errors.js");
+        throw new CloudRestError(
+          rows.length === 0 ? 404 : 409,
+          rows.length === 0 ? "Not Found" : "Conflict",
+          { expected: 1, got: rows.length },
+        );
+      }
+      return rows[0] as unknown as Row[];
+    }
+    return rows;
+  }
+
+  // PromiseLike — `await db.from(...).select(...)` works without `.exec()`.
+  then<TResult1 = Row[], TResult2 = never>(
+    onfulfilled?: ((value: Row[]) => TResult1 | PromiseLike<TResult1>) | null,
+    onrejected?: ((reason: CloudRestError) => TResult2 | PromiseLike<TResult2>) | null,
+  ): PromiseLike<TResult1 | TResult2> {
+    return this.exec().then(onfulfilled, onrejected as never);
+  }
+  // Match Promise surface so `.catch()` / `.finally()` work directly on builders.
+  catch<TResult = never>(
+    onrejected?: ((reason: CloudRestError) => TResult | PromiseLike<TResult>) | null,
+  ): Promise<Row[] | TResult> {
+    return this.exec().catch(onrejected as never);
+  }
+  finally(onfinally?: (() => void) | null): Promise<Row[]> {
+    return this.exec().finally(onfinally);
+  }
+}
+
+// Phantom type alias for `.single()` — narrows the awaited type from Row[] to Row.
+export interface SingleQuery<Row> extends PromiseLike<Row> {}