@metaobjectsdev/runtime-ts 1.0.9-rc.2 → 1.0.9-rc.4

package/src/drizzle-fastify/list-params.ts

@@ -0,0 +1,50 @@
+/**
+ * List-query parameter checks shared by every mount — the Drizzle mounts (Fastify and
+ * Hono) and the ObjectManager Fastify mount. Deliberately free of drizzle-orm (an
+ * OPTIONAL peer): the ObjectManager mount must not pull it in.
+ */
+
+export class FilterParseError extends Error {
+  constructor(public readonly code: string, message: string, public readonly details?: Record<string, unknown>) {
+    super(message);
+    this.name = "FilterParseError";
+  }
+}
+
+/** The page-size ceiling of a raw-SQL (column-less `.existing()`) view list, which has
+ *  no allowlist to page through and returns at most this many rows. */
+export const RAW_VIEW_MAX_LIMIT = 1000;
+
+/** The `expected` member of a `pagination.invalid_value` answer with no upper bound. */
+export const PAGINATION_EXPECTED = "a non-negative integer (0 or more)";
+
+/**
+ * Read `?limit=` / `?offset=` as a non-negative integer, or refuse it. Before, a value
+ * that was not a finite number (`?limit=abc`) was dropped — every row came back — and a
+ * negative or fractional one reached SQL. `max` is the ceiling a mount clamps to, when it
+ * has one: a bound above it is refused rather than silently lowered. TS-only (no corpus
+ * scenario sends a malformed page bound): see docs/features/api-contract.md, "TS-only
+ * error responses".
+ */
+export function parsePageBound(
+  query: Record<string, unknown>,
+  param: "limit" | "offset",
+  max?: number,
+): number | undefined {
+  const raw = query[param];
+  if (raw === undefined) return undefined;
+  const s = typeof raw === "string" ? raw : String(raw);
+  const n = /^\d+$/.test(s) ? Number(s) : Number.NaN;
+  if (!Number.isSafeInteger(n) || (max !== undefined && n > max)) {
+    const expected = max === undefined ? PAGINATION_EXPECTED : `an integer from 0 to ${max}`;
+    throw new FilterParseError(
+      "pagination.invalid_value",
+      `?${param}= must be ${expected}, got "${s}".`,
+      { param, value: s, expected },
+    );
+  }
+  return n;
+}
+
+/** The `expected` member of an `invalid_sort` answer — the one spelling `?sort` takes. */
+export const SORT_EXPECTED = "sort=<field>:asc|desc";

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

@@ -1,7 +1,7 @@
 import type { FastifyInstance, RouteShorthandOptions } from "fastify";
 import { sql, eq, and, count } from "drizzle-orm";
 import qs from "qs";
-import { parseFilterParams, FilterParseError } from "./filter-parser.js";
+import { parseFilterParams, parsePageBound, RAW_VIEW_MAX_LIMIT, FilterParseError } from "./filter-parser.js";
 import type { FilterAllowlist, SortAllowlist } from "./filter-allowlist.js";
 import { isTruthyFlag, contractErrorCode, coerceIdForColumn, rawIdLiteral, viewBaseConfig } from "./util.js";
 import { timestampWire } from "../timestamp-wire.js";
@@ -140,8 +140,9 @@ export function mountReadOnlyCrudRoutes(opts: MountReadOnlyOptions): void {
         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));
+        // A bound that is not an integer in range is a 400, not silently clamped.
+        const limitVal = parsePageBound(parsed, "limit", RAW_VIEW_MAX_LIMIT) ?? RAW_VIEW_MAX_LIMIT;
+        const offsetVal = parsePageBound(parsed, "offset") ?? 0;
         const withCount = isTruthyFlag(parsed["withCount"]);
         // biome-ignore lint/suspicious/noExplicitAny: dynamic raw result
         const rows = await rawRows(db, dialect, sql.raw(`SELECT * FROM "${viewName}" LIMIT ${limitVal} OFFSET ${offsetVal}`)) as any[];
@@ -223,7 +224,7 @@ export function mountReadOnlyCrudRoutes(opts: MountReadOnlyOptions): void {
   });
 
   // ── Mutations explicitly rejected (405) ───────────────────────────────────
-  // PUT is here because the WRITABLE mount serves it (a full-replace update), so a
+  // PUT is here because the WRITABLE mount serves it (an alias of PATCH), so a
   // projection must reject it the same way the other three are rejected. Omitting it
   // left `PUT /<collection>/:id` falling through to Fastify's 404 — telling a caller
   // the resource does not exist when it plainly does and answers GET.

package/src/fastify/index.ts

@@ -19,6 +19,7 @@
 import type { FastifyInstance } from "fastify";
 import { withConstraintMapping } from "../constraint-errors.js";
 import type { ZodTypeAny } from "zod";
+import { validationErrorBody } from "../route-errors.js";
 import qs from "qs";
 import type { ObjectManager } from "../object-manager.js";
 import type { Row } from "../persistence-driver.js";
@@ -26,6 +27,7 @@ import type { RouteShorthandOptions } from "fastify";
 import type { SortAllowlist } from "../drizzle-fastify/filter-allowlist.js";
 import { sortOrderSpec } from "../drizzle-fastify/filter-allowlist.js";
 import { isTruthyFlag, contractErrorCode } from "../drizzle-fastify/util.js";
+import { parsePageBound, FilterParseError, SORT_EXPECTED } from "../drizzle-fastify/list-params.js";
 import { withContractErrorHandler } from "../drizzle-fastify/route-error-handler.js";
 
 // ---------------------------------------------------------------------------
@@ -129,9 +131,15 @@ export function mountListRoute(opts: SingleVerbOptions): void {
     const withCount = isTruthyFlag(parsed["withCount"]);
 
     const readOpts: { limit?: number; offset?: number; orderBy?: [string, "asc" | "desc"] } = {};
-    const { limit, offset } = req.query as { limit?: string; offset?: string };
-    if (limit !== undefined) readOpts.limit = Number(limit);
-    if (offset !== undefined) readOpts.offset = Number(offset);
+    try {
+      const limit = parsePageBound(parsed, "limit");
+      const offset = parsePageBound(parsed, "offset");
+      if (limit !== undefined) readOpts.limit = limit;
+      if (offset !== undefined) readOpts.offset = offset;
+    } catch (err) {
+      if (err instanceof FilterParseError) return reply.code(400).send({ error: err.code, ...(err.details ?? {}) });
+      throw err;
+    }
 
     // Sort allowlist gate (cross-port REST contract). Only enforced when a
     // sortAllowlist is configured; absent → ?sort is ignored (back-compat).
@@ -140,7 +148,12 @@ export function mountListRoute(opts: SingleVerbOptions): void {
       if (sortParse.error) {
         // `field` is REQUIRED on the invalid_sort envelope cross-port (F20 ruling) —
         // it names the offending sort field instead of making the caller guess.
-        return reply.code(400).send({ error: contractErrorCode(sortParse.error), field: sortParse.field });
+        return reply.code(400).send({
+          error: contractErrorCode(sortParse.error),
+          field: sortParse.field,
+          expected: SORT_EXPECTED,
+          allowed: Object.keys(opts.sortAllowlist),
+        });
       }
       if (sortParse.orderBy) readOpts.orderBy = sortParse.orderBy;
     }
@@ -190,7 +203,7 @@ export function mountCreateRoute(opts: SingleVerbOptions): 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 });
+      return reply.code(400).send(validationErrorBody(parsed.error.issues));
     }
     // Zod returns `unknown` for parsed.data; the schema is authored from the
     // same metadata that drives ObjectManager, so the shape is guaranteed
@@ -217,7 +230,7 @@ export function mountUpdateRoute(opts: SingleVerbOptions): void {
     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 });
+      return reply.code(400).send(validationErrorBody(parsed.error.issues));
     }
     // Use ifMissing: "ignore" so the helper itself owns the 404 mapping
     // (consistent with mountDeleteRoute). ObjectManager's default behavior

package/src/hono/index.ts

@@ -24,11 +24,13 @@
 import type { Hono, Context } from "hono";
 import { classifyConstraintError, RedactedDatabaseError, logAndRedact } from "../constraint-errors.js";
 import type { ZodTypeAny } from "zod";
+import { validationErrorBody } from "../route-errors.js";
 import { eq, count, and } from "drizzle-orm";
 import qs from "qs";
 import { contractErrorCode } from "../drizzle-fastify/util.js";
 import {
   parseFilterParams,
+  parsePageBound,
   FilterParseError,
   type ParseFilterResult,
 } from "../drizzle-fastify/filter-parser.js";
@@ -204,9 +206,10 @@ export function mountListRoute(opts: VerbOptions): void {
         if (parsed.offset !== undefined) q = q.offset(parsed.offset);
       } else {
         // No allowlists configured. Only limit/offset.
-        const flat = c.req.query();
-        if (flat.limit  !== undefined) q = q.limit(Number(flat.limit));
-        if (flat.offset !== undefined) q = q.offset(Number(flat.offset));
+        const limit = parsePageBound(qsParsed, "limit");
+        const offset = parsePageBound(qsParsed, "offset");
+        if (limit  !== undefined) q = q.limit(limit);
+        if (offset !== undefined) q = q.offset(offset);
       }
 
       // Await the query directly rather than calling `.all()`: the drizzle-orm
@@ -258,7 +261,7 @@ export function mountCreateRoute(opts: VerbOptions): void {
     if (!read.ok) return read.response;
     const parsed = opts.insertSchema.safeParse(read.body);
     if (!parsed.success) {
-      return c.json({ error: "validation", issues: parsed.error.issues }, 400);
+      return c.json(validationErrorBody(parsed.error.issues), 400);
     }
     // Same redaction contract as the Fastify mount: a constraint the DB enforces must not
     // come back as a 500 carrying the SQL and its bound parameters. Both mounts are
@@ -285,7 +288,7 @@ export function mountUpdateRoute(opts: VerbOptions): void {
     if (!read.ok) return read.response;
     const parsed = opts.updateSchema.safeParse(read.body);
     if (!parsed.success) {
-      return c.json({ error: "validation", issues: parsed.error.issues }, 400);
+      return c.json(validationErrorBody(parsed.error.issues), 400);
     }
     // An empty patch is a no-op update, answered as a read — the Fastify mount's
     // rule; its block in drizzle-fastify/index.ts carries the full rationale.

package/src/hono/mount-read-only.ts

@@ -5,7 +5,7 @@
 import type { Hono } from "hono";
 import { sql, eq, and, count } from "drizzle-orm";
 import qs from "qs";
-import { parseFilterParams, FilterParseError } from "../drizzle-fastify/filter-parser.js";
+import { parseFilterParams, parsePageBound, RAW_VIEW_MAX_LIMIT, FilterParseError } from "../drizzle-fastify/filter-parser.js";
 import type {
   FilterAllowlist,
   SortAllowlist,
@@ -116,14 +116,9 @@ export function mountReadOnlyCrudRoutes(opts: MountReadOnlyOptions): void {
         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),
-        );
+        // A bound that is not an integer in range is a 400, not silently clamped.
+        const limitVal = parsePageBound(parsed, "limit", RAW_VIEW_MAX_LIMIT) ?? RAW_VIEW_MAX_LIMIT;
+        const offsetVal = parsePageBound(parsed, "offset") ?? 0;
         const withCount = isTruthyFlag(parsed["withCount"]);
         // biome-ignore lint/suspicious/noExplicitAny: dynamic raw result
         const rows = (await rawRows(db, dialect, sql.raw(`SELECT * FROM "${viewName}" LIMIT ${limitVal} OFFSET ${offsetVal}`))) as any[];

package/src/route-errors.ts

@@ -38,6 +38,28 @@ export interface ErrorEnvelope {
 }
 
 export const INTERNAL_ERROR_BODY: ErrorEnvelope = Object.freeze({ error: ERROR_CODE_INTERNAL });
+
+/** Wire code for a request body that failed its schema. */
+export const ERROR_CODE_VALIDATION = "validation";
+
+/**
+ * The 400 body for a body that failed its Zod schema: every issue as Zod reported it,
+ * minus `pattern`. Zod 4 attaches the regex SOURCE to a failed `.regex()` check, and for a
+ * generated `field.date` / `field.timestamp` check that is a ~300-character calendar regex
+ * (an authored `validator.regex` pattern is likewise the server's own business). The
+ * issue's `message` already names the expected format. Shared by every mount.
+ */
+export function validationErrorBody<T extends object>(
+  issues: readonly T[],
+): { readonly error: string; readonly issues: Omit<T, "pattern">[] } {
+  return {
+    error: ERROR_CODE_VALIDATION,
+    issues: issues.map((issue) => {
+      const { pattern: _pattern, ...rest } = issue as T & { pattern?: unknown };
+      return rest;
+    }),
+  };
+}
 export const INVALID_JSON_BODY: ErrorEnvelope = Object.freeze({ error: ERROR_CODE_INVALID_JSON });
 
 /**