@ikeboy003/cloudrest-client 0.1.0 → 0.2.0

package/dist/serialize.js.map

@@ -1 +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,2EAA2E;AAC3E,kFAAkF;AAClF,kEAAkE;AAClE,MAAM,UAAU,OAAO,CAAC,IAAY,EAAE,IAAY;IAChD,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,EAAE,CAAC;AAC3E,CAAC;AAED,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"}
+{"version":3,"file":"serialize.js","sourceRoot":"","sources":["../src/serialize.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikeboy003/cloudrest-client",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Typed query builder for cloudrest. PostgREST-grammar compatible.",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,13 +17,15 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "dev": "tsc -p tsconfig.json --watch"
+    "build": "tsc -p tsconfig.json && tsc-alias -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "test": "node --test test/*.test.mjs"
   },
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
+    "tsc-alias": "^1.8.17",
     "typescript": "^5.5.0"
   }
 }

package/src/client.ts

@@ -1,7 +1,16 @@
-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";
+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 interface CopyOptions {
+  /** Target columns, in body order. Required (maps to `?columns=`). */
+  columns: string[];
+  /** Schema the table lives in (default "public"). */
+  schema?: string;
+  /** Wire format of `body` (default "csv"). NDJSON is transcoded server-side. */
+  format?: "csv" | "ndjson";
+}
 
 export class CloudRestClient<P extends AnyPaths> {
   private readonly ctx: ExecContext;
@@ -50,6 +59,42 @@ export class CloudRestClient<P extends AnyPaths> {
   ): RpcCaller<Result> {
     return new RpcCaller<Result>(this.ctx, fn, args);
   }
+
+  /**
+   * Bulk-ingest via the server's COPY endpoint
+   * (`POST /_copy/{schema}/{table}?columns=`). `body` is CSV (with a header row)
+   * or NDJSON. Streams straight into `COPY` — far faster than row-by-row
+   * inserts for large loads. Resolves to `{ inserted: N }`.
+   */
+  async copy(
+    table: TableName<P>,
+    body: string | Uint8Array,
+    opts: CopyOptions,
+  ): Promise<{ inserted: number }> {
+    const schema = opts.schema ?? "public";
+    const cols = opts.columns.map(encodeURIComponent).join(",");
+    const url = `${this.ctx.baseUrl}/_copy/${schema}/${String(table)}?columns=${cols}`;
+    const headers: Record<string, string> = {
+      Accept: "application/json",
+      "Content-Type":
+        opts.format === "ndjson" ? "application/x-ndjson" : "text/csv",
+      ...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: body as BodyInit,
+    });
+    if (!res.ok) {
+      const errBody = await res.json().catch(() => null);
+      const { CloudRestError } = await import("@/errors.js");
+      throw new CloudRestError(res.status, res.statusText, errBody);
+    }
+    return (await res.json()) as { inserted: number };
+  }
 }
 
 export function createClient<P extends AnyPaths>(opts: ClientOptions): CloudRestClient<P> {

package/src/filter.ts

@@ -1,57 +1,100 @@
-// Filter ops — equality, comparison, set membership, null checks, pattern match,
-// plus the `or` composite. (`and`, `fts`, `jsonpath` still to come.)
+// Filter ops — the full PostgREST operator set + nestable and/or/not logic.
 //
-// Each filter contributes one entry to URLSearchParams as `column=op.value`.
+// Each filter contributes one entry. A leaf renders as `column=op.value`; a
+// logic group renders as `and=(child,child)` / `or=(...)`. As a CHILD inside a
+// group, a leaf re-spells to `column.op.value` and a group to `and(...)`/`or(...)`,
+// which is how PostgREST nests them.
 
-import { serializeValue } from "./serialize.js";
+import { serializeValue, serializeArray, serializeRange } from "@/serialize.js";
 
 export type IsValue = "null" | "true" | "false" | "unknown";
 
 export interface FilterEntry {
+  /** Leaf: the column. Group: "and" | "or". */
   column: string;
+  /** Leaf: "op.value". Group: "(child,child,...)". */
   expr: string;
+  /** True for a logic group (and/or), so child-rendering omits the dot. */
+  group?: boolean;
 }
 
-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`.
+const leaf = (column: string, expr: string): FilterEntry => ({ column, expr });
+
+// ── comparison / equality ───────────────────────────────────────────────────
+export const fEq = (c: string, v: unknown): FilterEntry => leaf(c, `eq.${serializeValue(v)}`);
+export const fNeq = (c: string, v: unknown): FilterEntry => leaf(c, `neq.${serializeValue(v)}`);
+export const fGt = (c: string, v: unknown): FilterEntry => leaf(c, `gt.${serializeValue(v)}`);
+export const fGte = (c: string, v: unknown): FilterEntry => leaf(c, `gte.${serializeValue(v)}`);
+export const fLt = (c: string, v: unknown): FilterEntry => leaf(c, `lt.${serializeValue(v)}`);
+export const fLte = (c: string, v: unknown): FilterEntry => leaf(c, `lte.${serializeValue(v)}`);
+
+// ── pattern match ───────────────────────────────────────────────────────────
+export const fLike = (c: string, p: string): FilterEntry => leaf(c, `like.${serializeValue(p)}`);
+export const fIlike = (c: string, p: string): FilterEntry => leaf(c, `ilike.${serializeValue(p)}`);
+/** POSIX regex (`~`). */
+export const fMatch = (c: string, p: string): FilterEntry => leaf(c, `match.${serializeValue(p)}`);
+/** Case-insensitive POSIX regex (`~*`). */
+export const fImatch = (c: string, p: string): FilterEntry => leaf(c, `imatch.${serializeValue(p)}`);
+
+// ── set membership / null / distinct ────────────────────────────────────────
+export const fIn = (c: string, vals: readonly unknown[]): FilterEntry => leaf(c, `in.${serializeValue(vals)}`);
+// `is` is the correct NULL / boolean check — `eq.null` is a SQL no-op.
+export const fIs = (c: string, v: IsValue): FilterEntry => leaf(c, `is.${v}`);
+/** `IS DISTINCT FROM` — null-safe inequality. */
+export const fIsDistinct = (c: string, v: unknown): FilterEntry => leaf(c, `isdistinct.${serializeValue(v)}`);
+
+// ── full-text search ────────────────────────────────────────────────────────
+// Optional text-search config (e.g. "english") rides in parens: `fts(english).query`.
+const ftsOp = (op: string) => (c: string, query: string, config?: string): FilterEntry =>
+  leaf(c, config ? `${op}(${config}).${serializeValue(query)}` : `${op}.${serializeValue(query)}`);
+/** `to_tsquery` full-text search. */
+export const fFts = ftsOp("fts");
+/** `plainto_tsquery`. */
+export const fPlfts = ftsOp("plfts");
+/** `phraseto_tsquery`. */
+export const fPhfts = ftsOp("phfts");
+/** `websearch_to_tsquery`. */
+export const fWfts = ftsOp("wfts");
+
+// ── array / range containment + adjacency ───────────────────────────────────
+/** contains `@>` (array/range/jsonb). */
+export const fCs = (c: string, v: readonly unknown[]): FilterEntry => leaf(c, `cs.${serializeArray(v)}`);
+/** contained-in `<@`. */
+export const fCd = (c: string, v: readonly unknown[]): FilterEntry => leaf(c, `cd.${serializeArray(v)}`);
+/** overlap `&&` (array or range). */
+export const fOv = (c: string, v: readonly unknown[] | string): FilterEntry =>
+  leaf(c, `ov.${Array.isArray(v) ? serializeArray(v) : serializeRange(v)}`);
+/** strictly-left-of `<<`. */
+export const fSl = (c: string, range: unknown): FilterEntry => leaf(c, `sl.${serializeRange(range)}`);
+/** strictly-right-of `>>`. */
+export const fSr = (c: string, range: unknown): FilterEntry => leaf(c, `sr.${serializeRange(range)}`);
+/** does-not-extend-to-the-right-of `&<`. */
+export const fNxr = (c: string, range: unknown): FilterEntry => leaf(c, `nxr.${serializeRange(range)}`);
+/** does-not-extend-to-the-left-of `&>`. */
+export const fNxl = (c: string, range: unknown): FilterEntry => leaf(c, `nxl.${serializeRange(range)}`);
+/** adjacent `-|-`. */
+export const fAdj = (c: string, range: unknown): FilterEntry => leaf(c, `adj.${serializeRange(range)}`);
+
+// ── generic escape hatch ────────────────────────────────────────────────────
+/** Any operator + already-serialized value, e.g. `fFilter("data->>k", "eq", "x")`. */
+export const fFilter = (c: string, op: string, value: string): FilterEntry => leaf(c, `${op}.${value}`);
+
+// ── negation + logic groups (nestable) ──────────────────────────────────────
+/** Negate any single-op filter: `column=not.is.null`, `column=not.eq.5`. */
 export function fNot(entry: FilterEntry): FilterEntry {
   return { column: entry.column, expr: `not.${entry.expr}` };
 }
-// Composite OR: `or=(title.ilike.*x*,author.ilike.*x*)`. Each child is a normal
-// FilterEntry (`column` + `op.value`) re-spelled in the dotted inner grammar
-// `column.op.value`. Compose children from the same f* helpers above.
+
+/** Render an entry as a CHILD inside a logic group. */
+function renderChild(e: FilterEntry): string {
+  return e.group ? `${e.column}${e.expr}` : `${e.column}.${e.expr}`;
+}
+
+/** Composite AND — `and=(a.eq.1,b.gt.2)`. Children may be leaves or groups (nests). */
+export function fAnd(entries: readonly FilterEntry[]): FilterEntry {
+  return { column: "and", expr: `(${entries.map(renderChild).join(",")})`, group: true };
+}
+/** Composite OR — `or=(a.eq.1,b.gt.2)`. Children may be leaves or groups (nests). */
 export function fOr(entries: readonly FilterEntry[]): FilterEntry {
-  const inner = entries.map((e) => `${e.column}.${e.expr}`).join(",");
-  return { column: "or", expr: `(${inner})` };
+  return { column: "or", expr: `(${entries.map(renderChild).join(",")})`, group: true };
 }

package/src/index.ts

@@ -1,24 +1,32 @@
-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 { createClient, CloudRestClient } from "@/client.js";
+export type { CopyOptions } from "@/client.js";
+export { CloudRestError } from "@/errors.js";
+export { QueryBuilder } from "@/query.js";
+export type { OrderOptions, CountStrategy, SingleQuery, PagedQuery } 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, SingleQuery, PagedQuery } from "./query.js";
-export type { IsValue, FilterEntry } from "./filter.js";
+} from "@/types.js";
+export type { IsValue, FilterEntry } from "@/filter.js";
 
-// Bare condition builders for composing `.or(...)`. Each returns a FilterEntry:
-//   db.from("catalog_public").or(cond.ilike("title","*x*"), cond.ilike("author","*x*"))
-import {
-  fEq, fNeq, fGt, fGte, fLt, fLte, fLike, fIlike, fIn, fIs, fNot,
-} from "./filter.js";
+// Bare condition builders for composing `.and(...)` / `.or(...)` (nestable).
+//   db.from("books").or(cond.ilike("title","*x*"), cond.ilike("author","*x*"))
+//   db.from("books").and(cond.gte("year",2000), cond.or(cond.eq("a",1), cond.eq("b",2)))
+import * as F from "@/filter.js";
+import type { FilterEntry } from "@/filter.js";
 export const cond = {
-  eq: fEq, neq: fNeq, gt: fGt, gte: fGte, lt: fLt, lte: fLte,
-  like: fLike, ilike: fIlike, in: fIn, is: fIs, not: fNot,
+  eq: F.fEq, neq: F.fNeq, gt: F.fGt, gte: F.fGte, lt: F.fLt, lte: F.fLte,
+  like: F.fLike, ilike: F.fIlike, match: F.fMatch, imatch: F.fImatch,
+  in: F.fIn, is: F.fIs, isDistinct: F.fIsDistinct,
+  fts: F.fFts, plfts: F.fPlfts, phfts: F.fPhfts, wfts: F.fWfts,
+  cs: F.fCs, cd: F.fCd, ov: F.fOv, sl: F.fSl, sr: F.fSr, nxr: F.fNxr, nxl: F.fNxl, adj: F.fAdj,
+  filter: F.fFilter, not: F.fNot,
+  // Variadic so they compose ergonomically + nest: cond.and(cond.eq(..), cond.or(..)).
+  and: (...e: FilterEntry[]): FilterEntry => F.fAnd(e),
+  or: (...e: FilterEntry[]): FilterEntry => F.fOr(e),
 } as const;

package/src/mutation.ts

@@ -1,29 +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 { joinUrl } from "./serialize.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(
@@ -31,7 +98,7 @@ 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.
@@ -41,7 +108,7 @@ async function send(
     ...(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}`;
 
@@ -54,7 +121,7 @@ async function send(
   });
   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 [];
@@ -62,39 +129,62 @@ 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 the insert to a multipart
-   * write: the row's scalar columns ride as a `payload` JSON part and each
-   * file as a part named after its column. The server's media stage stores
-   * the bytes and puts a reference in the column. Single-row inserts only.
+   * 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 hasFiles(): boolean {
-    return Object.keys(this.files).length > 0;
+  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 {
@@ -106,9 +196,7 @@ export class InsertBuilder<P extends AnyPaths, T extends TableName<P>, Row = Row
       "payload",
       new Blob([JSON.stringify(this.rows[0])], { type: "application/json" }),
     );
-    for (const [column, file] of Object.entries(this.files)) {
-      fd.append(column, file);
-    }
+    for (const [column, file] of Object.entries(this.files)) fd.append(column, file);
     return fd;
   }
 
@@ -116,9 +204,9 @@ export class InsertBuilder<P extends AnyPaths, T extends TableName<P>, Row = Row
     onfulfilled?: ((value: Row[]) => R1 | PromiseLike<R1>) | null,
     onrejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null,
   ): PromiseLike<R1 | R2> {
-    const url = `${joinUrl(this.ctx.baseUrl, String(this.table))}`;
-    const body = this.hasFiles() ? this.formBody() : this.rows;
-    return send(this.ctx, "POST", url, body, 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);
   }
@@ -128,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,
@@ -138,15 +224,8 @@ 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();
+    const qs = this.filterQs();
     return `${joinUrl(this.ctx.baseUrl, String(this.table))}${qs ? `?${qs}` : ""}`;
   }
 
@@ -154,7 +233,7 @@ export class UpdateBuilder<P extends AnyPaths, T extends TableName<P>, Row = Row
     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);
   }
@@ -164,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,
@@ -173,15 +250,8 @@ 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();
+    const qs = this.filterQs();
     return `${joinUrl(this.ctx.baseUrl, String(this.table))}${qs ? `?${qs}` : ""}`;
   }
 
@@ -189,7 +259,7 @@ export class DeleteBuilder<P extends AnyPaths, T extends TableName<P>, Row = Row
     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);
   }