@ikeboy003/cloudrest-client 0.1.0 → 0.2.0

package/src/query.ts

@@ -4,13 +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, fOr,
-  type FilterEntry, type IsValue,
-} from "./filter.js";
-import type { CloudRestError } from "./errors.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 { CloudRestError } from "@/errors.js";
+import { joinUrl } from "@/serialize.js";
 
 export interface ExecContext {
   baseUrl: string;
@@ -24,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[]>
 {
@@ -35,7 +35,8 @@ export class QueryBuilder<P extends AnyPaths, T extends TableName<P>, Row = RowO
   private rangeFrom?: number;
   private rangeTo?: number;
   private singleMode = false;
-  private wantCount = false;
+  private countStrategy?: CountStrategy;
+  private preferExtra: string[] = [];
 
   constructor(
     private readonly ctx: ExecContext,
@@ -43,29 +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; }
-  // Composite OR — pass bare condition helpers (e.g. `cond.ilike("title","*x*")`).
-  // Emits `or=(title.ilike.*x*,author.ilike.*x*)`.
-  or(...entries: FilterEntry[]): this { this.filters.push(fOr(entries)); 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 {
@@ -79,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[]`).
@@ -90,12 +121,12 @@ export class QueryBuilder<P extends AnyPaths, T extends TableName<P>, Row = RowO
   }
 
   /**
-   * Page-aware terminal: returns the rows AND the exact total row count via
-   * `Prefer: count=exact` + the `Content-Range` response header. Use with
-   * `.range(from,to)` for paginated lists that need a total/page count.
+   * 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> {
-    this.wantCount = true;
+    if (!this.countStrategy) this.countStrategy = "exact";
     return { then: (f, r) => this.execPaged().then(f as never, r as never) };
   }
 
@@ -111,6 +142,12 @@ export class QueryBuilder<P extends AnyPaths, T extends TableName<P>, Row = RowO
     return `${joinUrl(this.ctx.baseUrl, String(this.table))}${qs ? `?${qs}` : ""}`;
   }
 
+  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();
@@ -122,14 +159,15 @@ export class QueryBuilder<P extends AnyPaths, T extends TableName<P>, Row = RowO
       headers["Range-Unit"] = "items";
       headers["Range"] = `${this.rangeFrom}-${this.rangeTo}`;
     }
-    if (this.wantCount) headers["Prefer"] = "count=exact";
+    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);
     }
     return { res, rows: (await res.json()) as Row[] };
@@ -149,7 +187,7 @@ export class QueryBuilder<P extends AnyPaths, T extends TableName<P>, Row = RowO
     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",

package/src/rpc.ts

@@ -7,9 +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 { joinUrl } from "./serialize.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(

package/src/serialize.ts

@@ -30,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";
@@ -38,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;