@ikeboy003/cloudrest-client 0.0.1 → 0.2.0

package/src/mutation.ts

@@ -1,28 +1,96 @@
-// Mutations: insert / update / delete. PostgREST conventions:
-// - POST /table     with array body → insert
+// Mutations: insert / update / delete (+ upsert, bulk media, write tuning).
+// PostgREST conventions:
+// - POST /table          array/object body → insert (`?on_conflict=` → upsert)
 // - PATCH /table?filters → update
 // - DELETE /table?filters → delete
-// - Prefer: return=representation header makes the server return rows.
+// - Prefer: return=representation|minimal, resolution=*, missing=*, tx=rollback,
+//           max-affected/min-affected, timezone, response-buffered
 
-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";
+import type { AnyPaths, RowOf, TableName } from "@/types.js";
+import * as F from "@/filter.js";
+import type { FilterEntry, IsValue } from "@/filter.js";
+import type { ExecContext } from "@/query.js";
+import { joinUrl } from "@/serialize.js";
 
-class FilterableMutation<Row> {
+// Shared write-tuning state + Prefer assembly (insert/update/delete).
+abstract class WriteTuning<Row> {
+  protected returnMode?: "representation" | "minimal";
+  protected txMode?: "rollback" | "commit";
+  protected maxAff?: number;
+  protected minAff?: number;
+  protected tz?: string;
+  protected bufferedFlag = false;
+  protected missingMode?: "default" | "null";
+  protected resolution?: "merge-duplicates" | "ignore-duplicates";
+
+  /** Return affected rows (adds Prefer: return=representation). */
+  returning(): this { this.returnMode = "representation"; return this; }
+  /** No body back (Prefer: return=minimal) — the default if unset. */
+  minimal(): this { this.returnMode = "minimal"; return this; }
+  /** Dry-run: run + roll back (Prefer: tx=rollback). */
+  dryRun(): this { this.txMode = "rollback"; return this; }
+  /** Fail (PGRST) if more than N rows would be affected. */
+  maxAffected(n: number): this { this.maxAff = n; return this; }
+  /** Fail if fewer than N rows are affected. */
+  minAffected(n: number): this { this.minAff = n; return this; }
+  /** Render timestamptz output in this zone (Prefer: timezone=<tz>). */
+  timezone(tz: string): this { this.tz = tz; return this; }
+  /** Buffer the response + set Content-Length (Prefer: response-buffered). */
+  buffered(): this { this.bufferedFlag = true; return this; }
+
+  protected prefer(): string[] {
+    const p: string[] = [];
+    if (this.returnMode) p.push(`return=${this.returnMode}`);
+    if (this.resolution) p.push(`resolution=${this.resolution}`);
+    if (this.missingMode) p.push(`missing=${this.missingMode}`);
+    if (this.txMode) p.push(`tx=${this.txMode}`);
+    if (this.maxAff !== undefined) p.push(`max-affected=${this.maxAff}`);
+    if (this.minAff !== undefined) p.push(`min-affected=${this.minAff}`);
+    if (this.tz) p.push(`timezone=${this.tz}`);
+    if (this.bufferedFlag) p.push("response-buffered");
+    return p;
+  }
+}
+
+// Filter methods shared by update/delete (mirrors QueryBuilder's set).
+abstract class FilterableMutation<Row> extends WriteTuning<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; }
+  eq(c: string, v: unknown): this { this.filters.push(F.fEq(c, v)); return this; }
+  neq(c: string, v: unknown): this { this.filters.push(F.fNeq(c, v)); return this; }
+  gt(c: string, v: unknown): this { this.filters.push(F.fGt(c, v)); return this; }
+  gte(c: string, v: unknown): this { this.filters.push(F.fGte(c, v)); return this; }
+  lt(c: string, v: unknown): this { this.filters.push(F.fLt(c, v)); return this; }
+  lte(c: string, v: unknown): this { this.filters.push(F.fLte(c, v)); return this; }
+  like(c: string, p: string): this { this.filters.push(F.fLike(c, p)); return this; }
+  ilike(c: string, p: string): this { this.filters.push(F.fIlike(c, p)); return this; }
+  match(c: string, p: string): this { this.filters.push(F.fMatch(c, p)); return this; }
+  imatch(c: string, p: string): this { this.filters.push(F.fImatch(c, p)); return this; }
+  in(c: string, vals: readonly unknown[]): this { this.filters.push(F.fIn(c, vals)); return this; }
+  is(c: string, v: IsValue): this { this.filters.push(F.fIs(c, v)); return this; }
+  isDistinct(c: string, v: unknown): this { this.filters.push(F.fIsDistinct(c, v)); return this; }
+  fts(c: string, q: string, cfg?: string): this { this.filters.push(F.fFts(c, q, cfg)); return this; }
+  plfts(c: string, q: string, cfg?: string): this { this.filters.push(F.fPlfts(c, q, cfg)); return this; }
+  phfts(c: string, q: string, cfg?: string): this { this.filters.push(F.fPhfts(c, q, cfg)); return this; }
+  wfts(c: string, q: string, cfg?: string): this { this.filters.push(F.fWfts(c, q, cfg)); return this; }
+  cs(c: string, vals: readonly unknown[]): this { this.filters.push(F.fCs(c, vals)); return this; }
+  cd(c: string, vals: readonly unknown[]): this { this.filters.push(F.fCd(c, vals)); return this; }
+  ov(c: string, v: readonly unknown[] | string): this { this.filters.push(F.fOv(c, v)); return this; }
+  sl(c: string, r: unknown): this { this.filters.push(F.fSl(c, r)); return this; }
+  sr(c: string, r: unknown): this { this.filters.push(F.fSr(c, r)); return this; }
+  nxr(c: string, r: unknown): this { this.filters.push(F.fNxr(c, r)); return this; }
+  nxl(c: string, r: unknown): this { this.filters.push(F.fNxl(c, r)); return this; }
+  adj(c: string, r: unknown): this { this.filters.push(F.fAdj(c, r)); return this; }
+  not(entry: FilterEntry): this { this.filters.push(F.fNot(entry)); return this; }
+  notIs(c: string, v: IsValue): this { this.filters.push(F.fNot(F.fIs(c, v))); return this; }
+  filter(c: string, op: string, value: string): this { this.filters.push(F.fFilter(c, op, value)); return this; }
+  and(...entries: FilterEntry[]): this { this.filters.push(F.fAnd(entries)); return this; }
+  or(...entries: FilterEntry[]): this { this.filters.push(F.fOr(entries)); return this; }
+
+  protected filterQs(): string {
+    const params = new URLSearchParams();
+    for (const f of this.filters) params.append(f.column, f.expr);
+    return params.toString();
+  }
 }
 
 async function send(
@@ -30,25 +98,30 @@ async function send(
   method: "POST" | "PATCH" | "DELETE",
   url: string,
   body: unknown | undefined,
-  returnRepresentation: boolean,
+  prefer: string[],
 ): Promise<unknown> {
+  // A FormData body is a multipart media write — let the runtime set the
+  // multipart Content-Type (with boundary); don't JSON-encode or force a type.
+  const isForm = typeof FormData !== "undefined" && body instanceof FormData;
   const headers: Record<string, string> = {
     Accept: "application/json",
-    "Content-Type": "application/json",
+    ...(isForm ? {} : { "Content-Type": "application/json" }),
     ...ctx.headers,
   };
-  if (returnRepresentation) headers["Prefer"] = "return=representation";
+  if (prefer.length) headers["Prefer"] = prefer.join(",");
   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) } : {}),
+    ...(body !== undefined
+      ? { body: isForm ? (body as FormData) : JSON.stringify(body) }
+      : {}),
   });
   if (!res.ok) {
     const errBody = await res.json().catch(() => null);
-    const { CloudRestError } = await import("./errors.js");
+    const { CloudRestError } = await import("@/errors.js");
     throw new CloudRestError(res.status, res.statusText, errBody);
   }
   if (res.status === 204) return [];
@@ -56,31 +129,84 @@ async function send(
 }
 
 export class InsertBuilder<P extends AnyPaths, T extends TableName<P>, Row = RowOf<P, T>>
+  extends WriteTuning<Row>
   implements PromiseLike<Row[]>
 {
   private rows: Partial<Row>[];
-  private returnRows = false;
+  private files: Record<string, Blob> = {};
+  private onConflictCols?: string;
+  private columnsList?: string;
 
   constructor(
     private readonly ctx: ExecContext,
     private readonly table: T,
     rows: Partial<Row> | Partial<Row>[],
   ) {
+    super();
     this.rows = Array.isArray(rows) ? rows : [rows];
   }
 
-  /** Return inserted rows (adds Prefer: return=representation). */
-  returning(): this {
-    this.returnRows = true;
+  /**
+   * Upsert on conflict of `columns` (a PK/unique set). Default resolution
+   * merges (UPDATE); pass `{ ignoreDuplicates: true }` for DO NOTHING.
+   */
+  onConflict(columns: string | string[], opts: { ignoreDuplicates?: boolean } = {}): this {
+    this.onConflictCols = Array.isArray(columns) ? columns.join(",") : columns;
+    this.resolution = opts.ignoreDuplicates ? "ignore-duplicates" : "merge-duplicates";
     return this;
   }
 
+  /** Restrict the insert to these columns (`?columns=`) — consistent bulk keys. */
+  columns(cols: string[]): this {
+    this.columnsList = cols.join(",");
+    return this;
+  }
+
+  /** Treat keys absent from a row as `NULL` rather than the column default. */
+  missing(mode: "default" | "null"): this {
+    this.missingMode = mode;
+    return this;
+  }
+
+  /**
+   * Attach a file for a media column — switches to a multipart write (scalar
+   * columns as a JSON `payload` part, each file as a part named after its
+   * column). The server's media stage stores bytes → reference into the column.
+   * Single-row inserts only.
+   */
+  attach(column: string, file: Blob): this {
+    this.files[column] = file;
+    return this;
+  }
+
+  private buildUrl(): string {
+    const params = new URLSearchParams();
+    if (this.onConflictCols) params.set("on_conflict", this.onConflictCols);
+    if (this.columnsList) params.set("columns", this.columnsList);
+    const qs = params.toString();
+    return `${joinUrl(this.ctx.baseUrl, String(this.table))}${qs ? `?${qs}` : ""}`;
+  }
+
+  private formBody(): FormData {
+    if (this.rows.length !== 1) {
+      throw new Error("cloudrest: multipart insert (attach) supports a single row");
+    }
+    const fd = new FormData();
+    fd.append(
+      "payload",
+      new Blob([JSON.stringify(this.rows[0])], { type: "application/json" }),
+    );
+    for (const [column, file] of Object.entries(this.files)) fd.append(column, file);
+    return fd;
+  }
+
   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)
+    const hasFiles = Object.keys(this.files).length > 0;
+    const body = hasFiles ? this.formBody() : this.rows;
+    return send(this.ctx, "POST", this.buildUrl(), body, this.prefer())
       .then((v) => v as Row[])
       .then(onfulfilled, onrejected as never);
   }
@@ -90,8 +216,6 @@ export class UpdateBuilder<P extends AnyPaths, T extends TableName<P>, Row = Row
   extends FilterableMutation<Row>
   implements PromiseLike<Row[]>
 {
-  private returnRows = false;
-
   constructor(
     private readonly ctx: ExecContext,
     private readonly table: T,
@@ -100,23 +224,16 @@ export class UpdateBuilder<P extends AnyPaths, T extends TableName<P>, Row = 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}` : ""}`;
+    const qs = this.filterQs();
+    return `${joinUrl(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)
+    return send(this.ctx, "PATCH", this.url(), this.patch, this.prefer())
       .then((v) => v as Row[])
       .then(onfulfilled, onrejected as never);
   }
@@ -126,8 +243,6 @@ export class DeleteBuilder<P extends AnyPaths, T extends TableName<P>, Row = Row
   extends FilterableMutation<Row>
   implements PromiseLike<Row[]>
 {
-  private returnRows = false;
-
   constructor(
     private readonly ctx: ExecContext,
     private readonly table: T,
@@ -135,23 +250,16 @@ export class DeleteBuilder<P extends AnyPaths, T extends TableName<P>, Row = 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}` : ""}`;
+    const qs = this.filterQs();
+    return `${joinUrl(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)
+    return send(this.ctx, "DELETE", this.url(), undefined, this.prefer())
       .then((v) => v as Row[])
       .then(onfulfilled, onrejected as never);
   }

package/src/query.ts

@@ -4,12 +4,11 @@
 //
 //   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";
+import type { AnyPaths, RowOf, TableName } from "@/types.js";
+import * as F from "@/filter.js";
+import type { FilterEntry, IsValue } from "@/filter.js";
+import type { CloudRestError } from "@/errors.js";
+import { joinUrl } from "@/serialize.js";
 
 export interface ExecContext {
   baseUrl: string;
@@ -23,6 +22,8 @@ export interface OrderOptions {
   nullsFirst?: boolean;
 }
 
+export type CountStrategy = "exact" | "planned" | "estimated";
+
 export class QueryBuilder<P extends AnyPaths, T extends TableName<P>, Row = RowOf<P, T>>
   implements PromiseLike<Row[]>
 {
@@ -34,6 +35,8 @@ export class QueryBuilder<P extends AnyPaths, T extends TableName<P>, Row = RowO
   private rangeFrom?: number;
   private rangeTo?: number;
   private singleMode = false;
+  private countStrategy?: CountStrategy;
+  private preferExtra: string[] = [];
 
   constructor(
     private readonly ctx: ExecContext,
@@ -41,26 +44,51 @@ export class QueryBuilder<P extends AnyPaths, T extends TableName<P>, Row = RowO
   ) {}
 
   // ── projection ──────────────────────────────────────────────────────────
+  // Raw PostgREST select string — supports embedding (`*,author(*)`), aggregates
+  // (`count(),sum(x)`), JSON paths (`data->>k`), casts (`x::text`), spreads
+  // (`...t(*)`), and aliases (`alias:col`).
   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; }
+  eq(col: string, v: unknown): this { this.filters.push(F.fEq(col, v)); return this; }
+  neq(col: string, v: unknown): this { this.filters.push(F.fNeq(col, v)); return this; }
+  gt(col: string, v: unknown): this { this.filters.push(F.fGt(col, v)); return this; }
+  gte(col: string, v: unknown): this { this.filters.push(F.fGte(col, v)); return this; }
+  lt(col: string, v: unknown): this { this.filters.push(F.fLt(col, v)); return this; }
+  lte(col: string, v: unknown): this { this.filters.push(F.fLte(col, v)); return this; }
+  like(col: string, pat: string): this { this.filters.push(F.fLike(col, pat)); return this; }
+  ilike(col: string, pat: string): this { this.filters.push(F.fIlike(col, pat)); return this; }
+  match(col: string, pat: string): this { this.filters.push(F.fMatch(col, pat)); return this; }
+  imatch(col: string, pat: string): this { this.filters.push(F.fImatch(col, pat)); return this; }
+  in(col: string, vals: readonly unknown[]): this { this.filters.push(F.fIn(col, vals)); return this; }
+  is(col: string, v: IsValue): this { this.filters.push(F.fIs(col, v)); return this; }
+  isDistinct(col: string, v: unknown): this { this.filters.push(F.fIsDistinct(col, v)); return this; }
+  // full-text search (optional ts config, e.g. "english")
+  fts(col: string, q: string, config?: string): this { this.filters.push(F.fFts(col, q, config)); return this; }
+  plfts(col: string, q: string, config?: string): this { this.filters.push(F.fPlfts(col, q, config)); return this; }
+  phfts(col: string, q: string, config?: string): this { this.filters.push(F.fPhfts(col, q, config)); return this; }
+  wfts(col: string, q: string, config?: string): this { this.filters.push(F.fWfts(col, q, config)); return this; }
+  // array / range
+  cs(col: string, vals: readonly unknown[]): this { this.filters.push(F.fCs(col, vals)); return this; }
+  cd(col: string, vals: readonly unknown[]): this { this.filters.push(F.fCd(col, vals)); return this; }
+  ov(col: string, v: readonly unknown[] | string): this { this.filters.push(F.fOv(col, v)); return this; }
+  sl(col: string, range: unknown): this { this.filters.push(F.fSl(col, range)); return this; }
+  sr(col: string, range: unknown): this { this.filters.push(F.fSr(col, range)); return this; }
+  nxr(col: string, range: unknown): this { this.filters.push(F.fNxr(col, range)); return this; }
+  nxl(col: string, range: unknown): this { this.filters.push(F.fNxl(col, range)); return this; }
+  adj(col: string, range: unknown): this { this.filters.push(F.fAdj(col, range)); 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; }
+  notIs(col: string, v: IsValue): this { this.filters.push(F.fNot(F.fIs(col, v))); return this; }
+  // Generic negation: pass a non-negated filter helper output.
+  not(entry: FilterEntry): this { this.filters.push(F.fNot(entry)); return this; }
+  // Generic escape hatch: any operator + already-serialized value.
+  filter(col: string, op: string, value: string): this { this.filters.push(F.fFilter(col, op, value)); return this; }
+  // Composite logic — pass bare `cond.*` helpers; nestable (`cond.and(cond.or(...))`).
+  and(...entries: FilterEntry[]): this { this.filters.push(F.fAnd(entries)); return this; }
+  or(...entries: FilterEntry[]): this { this.filters.push(F.fOr(entries)); return this; }
 
   // ── ordering / paging ───────────────────────────────────────────────────
   order(column: string, opts: OrderOptions = {}): this {
@@ -74,6 +102,14 @@ export class QueryBuilder<P extends AnyPaths, T extends TableName<P>, Row = RowO
   offset(n: number): this { this.offsetN = n; return this; }
   range(from: number, to: number): this { this.rangeFrom = from; this.rangeTo = to; return this; }
 
+  // ── prefer tuning ─────────────────────────────────────────────────────────
+  /** Set the count strategy (`exact` | `planned` | `estimated`). withCount() implies `exact`. */
+  count(strategy: CountStrategy = "exact"): this { this.countStrategy = strategy; return this; }
+  /** `Prefer: timezone=<tz>` — render timestamptz output in this zone. */
+  timezone(tz: string): this { this.preferExtra.push(`timezone=${tz}`); return this; }
+  /** `Prefer: response-buffered` — server buffers + sets Content-Length (CF throttle fix). */
+  buffered(): this { this.preferExtra.push("response-buffered"); return this; }
+
   // ── result shape ────────────────────────────────────────────────────────
   /**
    * Expect exactly one row. Resolves to `Row` (not `Row[]`).
@@ -84,6 +120,16 @@ export class QueryBuilder<P extends AnyPaths, T extends TableName<P>, Row = RowO
     return this as unknown as SingleQuery<Row>;
   }
 
+  /**
+   * Page-aware terminal: returns the rows AND the total row count via the
+   * `Content-Range` response header. Use with `.range(from,to)` (and optionally
+   * `.count("estimated")` for big tables) for paginated lists.
+   */
+  withCount(): PagedQuery<Row> {
+    if (!this.countStrategy) this.countStrategy = "exact";
+    return { then: (f, r) => this.execPaged().then(f as never, r as never) };
+  }
+
   // ── build + execute ─────────────────────────────────────────────────────
   private buildUrl(): string {
     const params = new URLSearchParams();
@@ -93,10 +139,17 @@ export class QueryBuilder<P extends AnyPaths, T extends TableName<P>, Row = RowO
     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}` : ""}`;
+    return `${joinUrl(this.ctx.baseUrl, String(this.table))}${qs ? `?${qs}` : ""}`;
   }
 
-  private async exec(): Promise<Row[]> {
+  private preferHeader(): string | undefined {
+    const tokens = [...this.preferExtra];
+    if (this.countStrategy) tokens.push(`count=${this.countStrategy}`);
+    return tokens.length ? tokens.join(",") : undefined;
+  }
+
+  // Shared request path for every terminal (then / single / withCount).
+  private async request(): Promise<{ res: Response; rows: Row[] }> {
     const url = this.buildUrl();
     const headers: Record<string, string> = {
       Accept: "application/json",
@@ -106,19 +159,35 @@ export class QueryBuilder<P extends AnyPaths, T extends TableName<P>, Row = RowO
       headers["Range-Unit"] = "items";
       headers["Range"] = `${this.rangeFrom}-${this.rangeTo}`;
     }
+    const prefer = this.preferHeader();
+    if (prefer) headers["Prefer"] = prefer;
     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");
+      const { CloudRestError } = await import("@/errors.js");
       throw new CloudRestError(res.status, res.statusText, body);
     }
-    const rows = (await res.json()) as Row[];
+    return { res, rows: (await res.json()) as Row[] };
+  }
+
+  // Total count lives in the `Content-Range` trailer: `0-19/348` → 348.
+  // `*` (server declined to count) falls back to the rows already returned.
+  private async execPaged(): Promise<{ rows: Row[]; count: number }> {
+    const { res, rows } = await this.request();
+    const cr = res.headers.get("content-range");
+    const m = cr ? /\/(\d+|\*)$/.exec(cr) : null;
+    const count = m && m[1] !== "*" ? Number(m[1]) : rows.length;
+    return { rows, count: Number.isFinite(count) ? count : rows.length };
+  }
+
+  private async exec(): Promise<Row[]> {
+    const { rows } = await this.request();
     if (this.singleMode) {
       if (rows.length !== 1) {
-        const { CloudRestError } = await import("./errors.js");
+        const { CloudRestError } = await import("@/errors.js");
         throw new CloudRestError(
           rows.length === 0 ? 404 : 409,
           rows.length === 0 ? "Not Found" : "Conflict",
@@ -150,3 +219,5 @@ export class QueryBuilder<P extends AnyPaths, T extends TableName<P>, Row = RowO
 
 // Phantom type alias for `.single()` — narrows the awaited type from Row[] to Row.
 export interface SingleQuery<Row> extends PromiseLike<Row> {}
+// `.withCount()` awaits to rows + total count instead of a bare Row[].
+export interface PagedQuery<Row> extends PromiseLike<{ rows: Row[]; count: number }> {}

package/src/rpc.ts

@@ -7,8 +7,9 @@
 //   - POST /rpc/<fn>  body = { argName: value, ... }
 //   - Response is the function return — scalar, row, or set-of rows.
 
-import type { ExecContext } from "./query.js";
-import { CloudRestError } from "./errors.js";
+import type { ExecContext } from "@/query.js";
+import { CloudRestError } from "@/errors.js";
+import { joinUrl } from "@/serialize.js";
 
 export class RpcCaller<Result = unknown> implements PromiseLike<Result> {
   constructor(
@@ -18,7 +19,7 @@ export class RpcCaller<Result = unknown> implements PromiseLike<Result> {
   ) {}
 
   private async exec(): Promise<Result> {
-    const url = `${this.ctx.baseUrl}/rpc/${this.fn}`;
+    const url = joinUrl(this.ctx.baseUrl, `rpc/${this.fn}`);
     const headers: Record<string, string> = {
       Accept: "application/json",
       "Content-Type": "application/json",

package/src/serialize.ts

@@ -14,6 +14,13 @@ const SCALAR_SPECIAL = /[,"]/;
 // List items are inside `(a,b,c)`, so `(`, `)`, and `,` all need quoting.
 const LIST_SPECIAL = /[(),."]/;
 
+// Join the client baseUrl with a table/route, tolerant of trailing/leading
+// slashes on either side, so `baseUrl="http://h:3005"` + `table="catalog_public"`
+// (or "/catalog_public") both yield exactly one separating slash.
+export function joinUrl(base: string, path: string): string {
+  return `${base.replace(/\/+$/, "")}/${String(path).replace(/^\/+/, "")}`;
+}
+
 export function serializeValue(v: unknown): string {
   if (v === null || v === undefined) return "null";
   if (v instanceof Date) return v.toISOString();
@@ -23,7 +30,7 @@ export function serializeValue(v: unknown): string {
   return escapeIfNeeded(String(v), SCALAR_SPECIAL);
 }
 
-function serializeListItem(v: unknown): string {
+export function serializeListItem(v: unknown): string {
   if (v === null || v === undefined) return "null";
   if (v instanceof Date) return v.toISOString();
   if (typeof v === "boolean") return v ? "true" : "false";
@@ -31,6 +38,22 @@ function serializeListItem(v: unknown): string {
   return escapeIfNeeded(String(v), LIST_SPECIAL);
 }
 
+// PostgreSQL array literal `{a,b,c}` — used by the array operators cs/cd/ov
+// (`tags=cs.{a,b}`). Distinct from the `(a,b)` list form used by `in`.
+export function serializeArray(v: readonly unknown[]): string {
+  return `{${v.map(serializeListItem).join(",")}}`;
+}
+
+// Range/value argument for the range operators (sl/sr/nxr/nxl/adj). Accepts a
+// ready-made literal (`"(1,10)"`, `"[2020-01-01,2020-12-31]"`) or a `[lo, hi]`
+// tuple → `(lo,hi)`.
+export function serializeRange(v: unknown): string {
+  if (Array.isArray(v)) {
+    return `(${serializeListItem(v[0])},${serializeListItem(v[1])})`;
+  }
+  return String(v);
+}
+
 function escapeIfNeeded(s: string, special: RegExp): string {
   if (s === "") return '""';
   if (!special.test(s)) return s;

package/src/types.ts

@@ -15,7 +15,9 @@ export type RowOf<P extends AnyPaths, T extends keyof P> =
     ? Body extends ReadonlyArray<infer Item>
       ? Item
       : Body
-    : never;
+    // Loosely-typed clients (e.g. `createClient<Record<string, unknown>>`) have no
+    // openapi shape per path; fall back to an open row so insert/update stay usable.
+    : Record<string, unknown>;
 
 // Tables = path keys that look like top-level table routes ("/foo", not "/rpc/...").
 export type TableName<P extends AnyPaths> = Extract<keyof P, string>;