@metaobjectsdev/runtime-ts 0.5.0-rc.1

package/src/drizzle-fastify/filter-parser.ts

@@ -0,0 +1,229 @@
+import {
+  eq, ne, gt, gte, lt, lte, inArray, like, ilike, isNull, not, and, or, asc, desc,
+  type SQL, type SQLWrapper,
+} from "drizzle-orm";
+import type { FilterAllowlist, FilterOp, FilterFieldRule, SortAllowlist } from "./filter-allowlist.js";
+
+// biome-ignore lint/suspicious/noExplicitAny: dynamic dispatch over user's Drizzle table
+type AnyTable = any;
+
+export interface ParseFilterOpts {
+  query: Record<string, unknown>;
+  table: AnyTable;
+  allowlist: FilterAllowlist;
+  sortAllowlist: SortAllowlist;
+  dialect: "sqlite" | "postgres";
+  maxNesting?: number;
+  maxInListSize?: number;
+}
+
+export interface ParseFilterResult {
+  where?: SQL;
+  orderBy?: SQLWrapper[];
+  limit?: number;
+  offset?: number;
+  /** Search predicate — OR(like('%term%')) across @filterable string fields. */
+  searchWhere?: SQL;
+}
+
+export class FilterParseError extends Error {
+  constructor(public readonly code: string, message: string, public readonly details?: Record<string, unknown>) {
+    super(message);
+    this.name = "FilterParseError";
+  }
+}
+
+const DEFAULT_MAX_NESTING = 5;
+const DEFAULT_MAX_IN_LIST = 100;
+
+export function parseFilterParams(opts: ParseFilterOpts): ParseFilterResult {
+  const result: ParseFilterResult = {};
+
+  const limit = opts.query.limit;
+  if (limit !== undefined) {
+    const n = Number(limit);
+    if (Number.isFinite(n)) result.limit = n;
+  }
+  const offset = opts.query.offset;
+  if (offset !== undefined) {
+    const n = Number(offset);
+    if (Number.isFinite(n)) result.offset = n;
+  }
+
+  if (opts.query.filter && typeof opts.query.filter === "object") {
+    const where = parseNode(
+      opts.query.filter as Record<string, unknown>,
+      opts.table, opts.allowlist, opts.dialect,
+      opts.maxNesting ?? DEFAULT_MAX_NESTING,
+      opts.maxInListSize ?? DEFAULT_MAX_IN_LIST,
+      0,
+    );
+    if (where) result.where = where;
+  }
+
+  if (typeof opts.query.sort === "string") {
+    result.orderBy = parseSort(opts.query.sort, opts.table, opts.sortAllowlist);
+  }
+
+  if (typeof opts.query.search === "string" && opts.query.search !== "") {
+    const term = `%${opts.query.search}%`;
+    const stringCols = Object.entries(opts.allowlist)
+      .filter(([, rule]) => (rule as FilterFieldRule).subType === "string")
+      .map(([field]) => opts.table[field]);
+    if (stringCols.length > 0) {
+      // Case-insensitive on Postgres (ilike), case-sensitive on SQLite (like) —
+      // matches the dispatch the existing [like] op uses (parseNode, below).
+      const matcher = opts.dialect === "postgres" ? ilike : like;
+      const parts = stringCols.map((col) => matcher(col, term));
+      // or() is defined as returning SQL | undefined but will always return
+      // SQL when given a non-empty array. parts[0] is always defined here
+      // because stringCols.length > 0 guarantees at least one element.
+      // biome-ignore lint/style/noNonNullAssertion: parts is guaranteed non-empty
+      result.searchWhere = (parts.length === 1 ? parts[0] : or(...parts)) as SQL;
+    }
+  }
+
+  return result;
+}
+
+function parseNode(
+  node: Record<string, unknown>,
+  table: AnyTable,
+  allowlist: FilterAllowlist,
+  dialect: "sqlite" | "postgres",
+  maxNesting: number,
+  maxInList: number,
+  depth: number,
+): SQL | undefined {
+  if (depth > maxNesting) {
+    throw new FilterParseError("filter.nesting_too_deep", `Filter nesting depth exceeds limit (${maxNesting}).`, { limit: maxNesting });
+  }
+  const parts: SQL[] = [];
+  for (const [key, value] of Object.entries(node)) {
+    if (key === "or") {
+      const subs = ensureArray(value, "or").map((sub) =>
+        parseNode(sub as Record<string, unknown>, table, allowlist, dialect, maxNesting, maxInList, depth + 1)
+      ).filter((s): s is SQL => !!s);
+      if (subs.length > 0) parts.push(or(...subs)!);
+    } else if (key === "and") {
+      const subs = ensureArray(value, "and").map((sub) =>
+        parseNode(sub as Record<string, unknown>, table, allowlist, dialect, maxNesting, maxInList, depth + 1)
+      ).filter((s): s is SQL => !!s);
+      if (subs.length > 0) parts.push(and(...subs)!);
+    } else {
+      // key is a field name
+      const rule = allowlist[key];
+      if (!rule) {
+        throw new FilterParseError("filter.unknown_field", `Unknown filter field "${key}".`, { field: key, allowed: Object.keys(allowlist) });
+      }
+      const col = table[key];
+      if (col === undefined) {
+        throw new FilterParseError("filter.unknown_field", `Table has no column for field "${key}".`, { field: key });
+      }
+      if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        for (const [opKey, opValue] of Object.entries(value)) {
+          const expr = compileOp(col, rule, key, opKey, opValue, dialect, maxInList);
+          if (expr) parts.push(expr);
+        }
+      } else {
+        // Bare value = eq sugar
+        const expr = compileOp(col, rule, key, "eq", value, dialect, maxInList);
+        if (expr) parts.push(expr);
+      }
+    }
+  }
+  if (parts.length === 0) return undefined;
+  if (parts.length === 1) return parts[0];
+  return and(...parts);
+}
+
+function compileOp(
+  col: unknown,
+  rule: FilterFieldRule,
+  field: string,
+  op: string,
+  value: unknown,
+  dialect: "sqlite" | "postgres",
+  maxInList: number,
+): SQL | undefined {
+  if (!rule.ops.includes(op as FilterOp)) {
+    throw new FilterParseError("filter.unsupported_op", `Op "${op}" not supported for field "${field}".`, { field, op, allowed: rule.ops });
+  }
+  switch (op as FilterOp) {
+    case "eq":  return eq(col as any, coerce(value, rule.subType, field, op));
+    case "ne":  return ne(col as any, coerce(value, rule.subType, field, op));
+    case "gt":  return gt(col as any, coerce(value, rule.subType, field, op));
+    case "gte": return gte(col as any, coerce(value, rule.subType, field, op));
+    case "lt":  return lt(col as any, coerce(value, rule.subType, field, op));
+    case "lte": return lte(col as any, coerce(value, rule.subType, field, op));
+    case "in": {
+      const list = String(value).split(",").map((v) => coerce(v.trim(), rule.subType, field, op));
+      if (list.length > maxInList) {
+        throw new FilterParseError("filter.in_too_large", `In-list size ${list.length} exceeds limit ${maxInList}.`, { field, limit: maxInList });
+      }
+      return inArray(col as any, list);
+    }
+    case "like": {
+      const s = String(value);
+      if (s.startsWith("%") && !rule.leadingWildcard) {
+        throw new FilterParseError("filter.leading_wildcard_disallowed", `Leading wildcard not allowed for field "${field}".`, { field });
+      }
+      return dialect === "postgres" ? ilike(col as any, s) : like(col as any, s);
+    }
+    case "isNull": {
+      // isNull's value is always coerced as boolean (true/false), regardless of the
+      // field's declared subType — the operator is "is the value null?", not "is X
+      // equal to null?". Field subtype is irrelevant.
+      const b = coerce(value, "boolean", field, op) as boolean;
+      return b ? isNull(col as any) : not(isNull(col as any));
+    }
+  }
+}
+
+function coerce(value: unknown, subType: string, field: string, op: string): unknown {
+  if (value === null || value === undefined) return null;
+  const s = typeof value === "string" ? value : String(value);
+  switch (subType) {
+    case "string":   return s;
+    case "boolean":  {
+      if (s === "true"  || s === "1") return true;
+      if (s === "false" || s === "0") return false;
+      throw new FilterParseError("filter.invalid_value", `Field "${field}" op "${op}" requires boolean, got "${s}".`, { field, op, expected: "boolean" });
+    }
+    case "number":   {
+      const n = Number(s);
+      if (!Number.isFinite(n)) {
+        throw new FilterParseError("filter.invalid_value", `Field "${field}" op "${op}" requires number, got "${s}".`, { field, op, expected: "number" });
+      }
+      return n;
+    }
+    case "datetime": return s;
+    default: return s;
+  }
+}
+
+function ensureArray(v: unknown, key: string): unknown[] {
+  if (Array.isArray(v)) return v;
+  if (v && typeof v === "object") {
+    // qs.parse may produce { "0": ..., "1": ... } shape for filter[or][0]...
+    return Object.values(v);
+  }
+  // Defensive — qs.parse normally produces an object/array; this branch is
+  // only reachable if a caller hand-constructs a malformed query object.
+  throw new FilterParseError("filter.invalid_value", `Expected array for "${key}".`, { key });
+}
+
+function parseSort(spec: string, table: AnyTable, sortAllowlist: SortAllowlist): SQLWrapper[] {
+  const colonIdx = spec.indexOf(":");
+  const field = colonIdx === -1 ? spec : spec.slice(0, colonIdx);
+  const orderRaw = colonIdx === -1 ? "asc" : spec.slice(colonIdx + 1);
+  const order = orderRaw.toLowerCase();
+  if (!sortAllowlist[field]) {
+    throw new FilterParseError("sort.unknown_field", `Unknown sort field "${field}".`, { field, allowed: Object.keys(sortAllowlist) });
+  }
+  if (order !== "asc" && order !== "desc") {
+    throw new FilterParseError("sort.invalid_order", `Sort order must be asc|desc, got "${orderRaw}".`, { expected: "asc | desc" });
+  }
+  const col = table[field];
+  return [order === "asc" ? asc(col as any) : desc(col as any)];
+}

package/src/drizzle-fastify/index.ts

@@ -0,0 +1,225 @@
+// Drizzle-direct Fastify adapter — replaces the ObjectManager-flavored
+// mountCrudRoutes for consumers that already use Drizzle directly.
+//
+// Why: most TS apps stay on Drizzle for SQL queries. Routing CRUD through
+// ObjectManager + a Drizzle driver was indirection for no real win — generated
+// routes can just call Drizzle directly and stay self-evident as Drizzle code.
+//
+// What this gives you: one helper, same surface as before, but the runtime
+// dependency is Drizzle + Zod, not ObjectManager.
+//
+//   GET    {path}      list with ?limit / ?offset
+//   GET    {path}/:id  findById, 404 if missing
+//   POST   {path}      create, 400 on Zod validation error
+//   PATCH  {path}/:id  update, 400 on validation, 404 if missing
+//   DELETE {path}/:id  delete, 204 on success, 404 if missing
+
+import type { FastifyInstance, RouteShorthandOptions } from "fastify";
+import type { ZodTypeAny } from "zod";
+import { eq, count, and } from "drizzle-orm";
+import qs from "qs";
+import type { FilterAllowlist, SortAllowlist } from "./filter-allowlist.js";
+export type { FilterAllowlist, SortAllowlist } from "./filter-allowlist.js";
+import { parseFilterParams, FilterParseError } from "./filter-parser.js";
+import { isTruthyFlag } from "./util.js";
+export { isTruthyFlag } from "./util.js";
+
+// ---------------------------------------------------------------------------
+// Loose types — we don't bind to a specific Drizzle backend so the helper
+// works across libsql / better-sqlite3 / pg / etc.
+// ---------------------------------------------------------------------------
+
+// biome-ignore lint/suspicious/noExplicitAny: dynamic dispatch over user's Drizzle instance
+type AnyDrizzle = any;
+// biome-ignore lint/suspicious/noExplicitAny: dynamic dispatch over user's Drizzle table
+type AnyTable = any;
+
+export type CrudVerb = "list" | "get" | "create" | "update" | "delete";
+
+export interface CrudRoutesOptions {
+  fastify: FastifyInstance;
+  /** REST resource path, e.g. "/subscribers". */
+  path: string;
+  /** User's Drizzle instance. */
+  db: AnyDrizzle;
+  /** Drizzle table const. The helper requires this to have an `id` column. */
+  table: AnyTable;
+  /** Zod schema for create payloads (typically `<Entity>InsertSchema`). */
+  insertSchema: ZodTypeAny;
+  /** Zod schema for update payloads (typically `<Entity>UpdateSchema`). */
+  updateSchema: ZodTypeAny;
+  /** Limit which verbs are mounted. Defaults to all five. */
+  expose?: readonly CrudVerb[];
+  /**
+   * Fastify route-level hooks applied to every mounted verb (preHandler,
+   * onRequest, schema validation, etc.). Most common use is auth:
+   *   routeOptions: { preHandler: requireAuthHook }
+   */
+  routeOptions?: RouteShorthandOptions;
+  /**
+   * HTTP method for the update verb. Defaults to "patch". Set to "put" to
+   * preserve a legacy API contract that already uses PUT for updates.
+   */
+  updateMethod?: "patch" | "put";
+  filterAllowlist?: FilterAllowlist;
+  sortAllowlist?:   SortAllowlist;
+  /** Dialect — required if filterAllowlist or sortAllowlist is set (for like/ilike dispatch). */
+  dialect?: "sqlite" | "postgres";
+}
+
+const ALL_VERBS: readonly CrudVerb[] = ["list", "get", "create", "update", "delete"];
+
+export function mountCrudRoutes(opts: CrudRoutesOptions): void {
+  const verbs = new Set<CrudVerb>(opts.expose ?? ALL_VERBS);
+  if (verbs.has("list")) mountListRoute(opts);
+  if (verbs.has("get")) mountGetRoute(opts);
+  if (verbs.has("create")) mountCreateRoute(opts);
+  if (verbs.has("update")) mountUpdateRoute(opts);
+  if (verbs.has("delete")) mountDeleteRoute(opts);
+}
+
+type VerbOptions = Omit<CrudRoutesOptions, "expose">;
+
+function routeOpts(opts: VerbOptions): RouteShorthandOptions {
+  return opts.routeOptions ?? {};
+}
+
+export function mountListRoute(opts: VerbOptions): void {
+  opts.fastify.get(opts.path, routeOpts(opts), async (req, reply) => {
+    try {
+      let q = opts.db.select().from(opts.table).$dynamic();
+      // Re-parse the raw URL with qs so bracketed filter notation and the
+      // top-level withCount flag are available.
+      const rawSearch = req.raw.url?.includes("?")
+        ? req.raw.url.slice(req.raw.url.indexOf("?") + 1)
+        : "";
+      const qsParsed = qs.parse(rawSearch) as Record<string, unknown>;
+      const withCount = isTruthyFlag(qsParsed.withCount);
+
+      let where: ReturnType<typeof parseFilterParams>["where"];
+      if (opts.filterAllowlist && opts.sortAllowlist) {
+        const parsed = parseFilterParams({
+          query: qsParsed,
+          table: opts.table,
+          allowlist: opts.filterAllowlist,
+          sortAllowlist: opts.sortAllowlist,
+          dialect: opts.dialect ?? "sqlite",
+        });
+        const combinedWhere = parsed.where && parsed.searchWhere
+          ? and(parsed.where, parsed.searchWhere)
+          : (parsed.where ?? parsed.searchWhere);
+        if (combinedWhere) { q = q.where(combinedWhere); where = combinedWhere; }
+        if (parsed.orderBy) q = q.orderBy(...parsed.orderBy);
+        if (parsed.limit  !== undefined) q = q.limit(parsed.limit);
+        if (parsed.offset !== undefined) q = q.offset(parsed.offset);
+      } else {
+        // Legacy path — no allowlists configured. Only limit/offset.
+        const { limit, offset } = req.query as { limit?: string; offset?: string };
+        if (limit  !== undefined) q = q.limit(Number(limit));
+        if (offset !== undefined) q = q.offset(Number(offset));
+      }
+
+      const rows = await q.all();
+
+      if (!withCount) return rows;
+
+      // Count query: same WHERE, no limit/offset/orderBy.
+      let cq = opts.db.select({ c: count() }).from(opts.table).$dynamic();
+      if (where) cq = cq.where(where);
+      const countRow = (await cq.all())[0] as { c: number } | undefined;
+      const total = countRow?.c ?? 0;
+      return { rows, total };
+    } catch (err) {
+      if (err instanceof FilterParseError) {
+        return reply.code(400).send({ error: err.code, ...(err.details ?? {}) });
+      }
+      throw err;
+    }
+  });
+}
+
+export function mountGetRoute(opts: VerbOptions): void {
+  opts.fastify.get(`${opts.path}/:id`, routeOpts(opts), async (req, reply) => {
+    const { id } = req.params as { id: string };
+    const row = await opts.db
+      .select()
+      .from(opts.table)
+      .where(eq(opts.table.id, parseId(id)))
+      .get();
+    return row ?? reply.code(404).send({ error: "not_found" });
+  });
+}
+
+export function mountCreateRoute(opts: VerbOptions): void {
+  opts.fastify.post(opts.path, routeOpts(opts), async (req, reply) => {
+    const parsed = opts.insertSchema.safeParse(req.body);
+    if (!parsed.success) {
+      return reply.code(400).send({ error: "validation", issues: parsed.error.issues });
+    }
+    const result = await opts.db.insert(opts.table).values(parsed.data).returning();
+    const row = (result as unknown[])[0];
+    return reply.code(201).send(row);
+  });
+}
+
+export function mountUpdateRoute(opts: VerbOptions): void {
+  const handler = async (
+    req: { params: unknown; body: unknown },
+    reply: { code: (n: number) => { send: (b: unknown) => unknown } },
+  ) => {
+    const { id } = req.params as { id: string };
+    const parsed = opts.updateSchema.safeParse(req.body);
+    if (!parsed.success) {
+      return reply.code(400).send({ error: "validation", issues: parsed.error.issues });
+    }
+    const result = await opts.db
+      .update(opts.table)
+      .set(parsed.data)
+      .where(eq(opts.table.id, parseId(id)))
+      .returning();
+    const row = (result as unknown[])[0];
+    return row ?? reply.code(404).send({ error: "not_found" });
+  };
+  const path = `${opts.path}/:id`;
+  const ro = routeOpts(opts);
+  // biome-ignore lint/suspicious/noExplicitAny: handler signature is generic
+  if (opts.updateMethod === "put") {
+    opts.fastify.put(path, ro, handler as any);
+  } else {
+    opts.fastify.patch(path, ro, handler as any);
+  }
+}
+
+export function mountDeleteRoute(opts: VerbOptions): void {
+  opts.fastify.delete(`${opts.path}/:id`, routeOpts(opts), async (req, reply) => {
+    const { id } = req.params as { id: string };
+    const result = await opts.db
+      .delete(opts.table)
+      .where(eq(opts.table.id, parseId(id)));
+    // Both libsql and pg drivers expose a rows-affected counter, in different
+    // shapes. Treat anything > 0 as "found and deleted."
+    const affected = extractRowCount(result);
+    return affected > 0
+      ? reply.code(204).send()
+      : reply.code(404).send({ error: "not_found" });
+  });
+}
+
+function extractRowCount(result: unknown): number {
+  if (typeof result === "number") return result;
+  if (Array.isArray(result)) return result.length;
+  if (result && typeof result === "object") {
+    const obj = result as { rowsAffected?: number | bigint; rowCount?: number };
+    if (typeof obj.rowsAffected === "number") return obj.rowsAffected;
+    if (typeof obj.rowsAffected === "bigint") return Number(obj.rowsAffected);
+    if (typeof obj.rowCount === "number") return obj.rowCount;
+  }
+  return 0;
+}
+
+export function parseId(raw: string): number | string {
+  const n = Number(raw);
+  return Number.isFinite(n) && raw.trim() !== "" ? n : raw;
+}
+
+export { mountReadOnlyCrudRoutes, type MountReadOnlyOptions } from "./mount-read-only.js";

package/src/drizzle-fastify/mount-read-only.ts

@@ -0,0 +1,187 @@
+import type { FastifyInstance } from "fastify";
+import { sql, eq, and, count } from "drizzle-orm";
+import qs from "qs";
+import { parseFilterParams, FilterParseError } from "./filter-parser.js";
+import type { FilterAllowlist, SortAllowlist } from "./filter-allowlist.js";
+import { isTruthyFlag } from "./util.js";
+
+// biome-ignore lint/suspicious/noExplicitAny: dynamic dispatch over user-supplied views
+type AnyView = any;
+
+/**
+ * Drizzle v0.45 stores view config under this well-known Symbol.
+ * Accessing `view._` on a proxy-wrapped view (empty-column .existing()) throws
+ * because the proxy tries to spread `subquery._.selectedFields` which is undefined.
+ * Using the symbol bypasses the proxy entirely.
+ */
+const VIEW_BASE_CONFIG = Symbol.for("drizzle:ViewBaseConfig");
+
+export interface MountReadOnlyOptions {
+  readonly fastify: FastifyInstance;
+  readonly path: string;
+  // biome-ignore lint/suspicious/noExplicitAny: dynamic Drizzle client
+  readonly db: any;
+  readonly view: AnyView;
+  readonly filterAllowlist: FilterAllowlist;
+  readonly sortAllowlist: SortAllowlist;
+  readonly dialect: "postgres" | "sqlite";
+  /** Override default ID column name (defaults to "id"). */
+  readonly idColumn?: string;
+}
+
+const REJECT_MUTATION = async (
+  request: { method: string },
+  reply: { code: (n: number) => { send: (b: unknown) => unknown } },
+) => {
+  reply
+    .code(405)
+    .send({ error: "method_not_allowed", message: `${request.method} is not supported on a projection (read-only).` });
+};
+
+function getViewConfig(view: AnyView): Record<string, unknown> | undefined {
+  try {
+    const cfg = (view as Record<symbol, unknown>)[VIEW_BASE_CONFIG];
+    if (cfg && typeof cfg === "object") return cfg as Record<string, unknown>;
+  } catch {
+    // ignore — proxy handler may throw on unexpected shapes
+  }
+  return undefined;
+}
+
+function resolveViewName(view: AnyView): string | undefined {
+  const cfg = getViewConfig(view);
+  if (cfg) {
+    if (typeof cfg["name"] === "string") return cfg["name"] as string;
+  }
+  // Fallback for non-proxy shapes
+  const v = view as Record<string, unknown>;
+  return (
+    (typeof v["__tableName"] === "string" ? v["__tableName"] as string : undefined) ??
+    (typeof v["_name"] === "string" ? v["_name"] as string : undefined)
+  );
+}
+
+/**
+ * Detect whether a Drizzle view was declared with `.existing()` and an empty
+ * column schema (`{}`). In that case, `db.select().from(view)` generates
+ * `SELECT  FROM ...` (invalid SQL), and we must fall back to raw SQL.
+ */
+function isEmptyColumnView(view: AnyView): boolean {
+  const cfg = getViewConfig(view);
+  if (cfg) {
+    const fields = cfg["selectedFields"] as Record<string, unknown> | undefined;
+    return fields !== undefined && Object.keys(fields).length === 0;
+  }
+  return false;
+}
+
+function snakeToCamel(s: string): string {
+  return s.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+/** Normalise a raw SQL result row's keys from snake_case to camelCase. */
+function camelizeRow(row: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(row)) {
+    out[snakeToCamel(k)] = v;
+  }
+  return out;
+}
+
+export function mountReadOnlyCrudRoutes(opts: MountReadOnlyOptions): void {
+  const { fastify, path, db, view, filterAllowlist, sortAllowlist, dialect } = opts;
+  const idCol = opts.idColumn ?? "id";
+
+  const viewName = resolveViewName(view);
+  const useRawSql = isEmptyColumnView(view) && !!viewName;
+
+  // ── List ──────────────────────────────────────────────────────────────────
+  fastify.get(path, async (req, reply) => {
+    try {
+      if (useRawSql) {
+        // .existing() view with no column schema — use raw SQL.
+        // Simple limit/offset only; filter/sort via allowlist is not available
+        // because column refs don't exist. This is sufficient for projection
+        // endpoints that return small full-table results.
+        const url = req.raw.url ?? "";
+        const qIdx = url.indexOf("?");
+        const queryString = qIdx >= 0 ? url.slice(qIdx + 1) : "";
+        const parsed = qs.parse(queryString) as Record<string, unknown>;
+        const limitVal = Math.min(1000, Math.max(1, Number(typeof parsed["limit"] === "string" ? parsed["limit"] : 1000)));
+        const offsetVal = Math.max(0, Number(typeof parsed["offset"] === "string" ? parsed["offset"] : 0));
+        const withCount = isTruthyFlag(parsed["withCount"]);
+        // biome-ignore lint/suspicious/noExplicitAny: dynamic raw result
+        const rows = await db.all(sql.raw(`SELECT * FROM "${viewName}" LIMIT ${limitVal} OFFSET ${offsetVal}`)) as any[];
+        const camelRows = rows.map((r: Record<string, unknown>) => camelizeRow(r));
+        if (!withCount) return camelRows;
+        // biome-ignore lint/suspicious/noExplicitAny: dynamic raw result
+        const countRows = await db.all(sql.raw(`SELECT COUNT(*) AS c FROM "${viewName}"`)) as any[];
+        const total: number = Number(countRows[0]?.c ?? 0);
+        return { rows: camelRows, total };
+      }
+
+      const url = req.raw.url ?? "";
+      const qIdx = url.indexOf("?");
+      const queryString = qIdx >= 0 ? url.slice(qIdx + 1) : "";
+      const parsed = qs.parse(queryString) as Record<string, unknown>;
+      const withCount = isTruthyFlag(parsed["withCount"]);
+      const result = parseFilterParams({
+        query: parsed,
+        table: view,
+        allowlist: filterAllowlist,
+        sortAllowlist,
+        dialect,
+      });
+      const combinedWhere = result.where && result.searchWhere
+        ? and(result.where, result.searchWhere)
+        : (result.where ?? result.searchWhere);
+      let q = db.select().from(view);
+      if (combinedWhere) q = q.where(combinedWhere);
+      if (result.orderBy) q = q.orderBy(...result.orderBy);
+      if (result.limit !== undefined) q = q.limit(result.limit);
+      if (result.offset !== undefined) q = q.offset(result.offset);
+      const rows = await q.all();
+
+      if (!withCount) return rows;
+
+      // Count query: same WHERE, no limit/offset/orderBy.
+      let cq = db.select({ c: count() }).from(view);
+      if (combinedWhere) cq = cq.where(combinedWhere);
+      const countRow = (await cq.all())[0] as { c: number } | undefined;
+      const total = countRow?.c ?? 0;
+      return { rows, total };
+    } catch (err) {
+      if (err instanceof FilterParseError) {
+        reply.code(400).send({ error: err.code, message: err.message });
+        return;
+      }
+      throw err;
+    }
+  });
+
+  // ── Get by ID ─────────────────────────────────────────────────────────────
+  fastify.get(`${path}/:id`, async (req, reply) => {
+    const { id } = req.params as { id: string };
+    if (useRawSql) {
+      const numericId = Number(id);
+      if (!Number.isFinite(numericId)) {
+        return reply.code(400).send({ error: "invalid_id" });
+      }
+      // biome-ignore lint/suspicious/noExplicitAny: dynamic raw result
+      const rows = await db.all(sql.raw(`SELECT * FROM "${viewName}" WHERE "${idCol}" = ${numericId} LIMIT 1`)) as any[];
+      const row = rows[0] ? camelizeRow(rows[0]) : undefined;
+      return row ?? reply.code(404).send({ error: "not_found" });
+    }
+    // biome-ignore lint/suspicious/noExplicitAny: Drizzle table/view column ref
+    const colRef = (view as any)[idCol];
+    const row = await db.select().from(view).where(
+      colRef !== undefined ? eq(colRef, Number(id)) : undefined
+    ).get();
+    return row ?? reply.code(404).send({ error: "not_found" });
+  });
+
+  // ── Mutations explicitly rejected (405) ───────────────────────────────────
+  fastify.post(path, REJECT_MUTATION);
+  fastify.patch(`${path}/:id`, REJECT_MUTATION);
+  fastify.delete(`${path}/:id`, REJECT_MUTATION);
+}

package/src/drizzle-fastify/util.ts

@@ -0,0 +1,10 @@
+/**
+ * Shared utilities for drizzle-fastify route helpers.
+ */
+
+// Accepts "1" or boolean true (the qs serialization of withCount: 1 from buildFilterQs).
+export function isTruthyFlag(v: unknown): boolean {
+  if (v === undefined || v === null) return false;
+  if (typeof v === "boolean") return v;
+  return String(v) === "1";
+}