@ai0x0/utils 0.6.1 → 0.7.0

package/.agents/skills/ai0x0-utils/backend/SKILL.md

@@ -338,12 +338,14 @@ export const { GET } = route({
 - **Auto injection**: POST stamps the scope column with the scope value (by default that is `creatorId = session.userId`); PUT writes `editorId = session.userId`; GET/GET_LIST apply the scope as a mandatory `where`.
 - **Session shape** is yours: `getSession` is generic, so resolve "who + which space + what role" once and let `scope.value` / `can` read the same object instead of each querying again.
 - **Date coercion**: any body field ending in `At` is passed through `dayjs(value).toDate()` before write — accept ISO strings from clients.
-- **List filtering** (all querystring values are strings):
-  - `key=a,b,c` → `IN (...)` when key ends with `Id`; otherwise `OR ILIKE %a% OR ILIKE %b%`
-  - `key=foo` where key ends with `Id` → `eq`; otherwise `ILIKE %foo%`
-  - `${anything}AtFrom` / `${anything}AtTo` → `gte` / `lte` against the matching `${anything}At` column
+- **List filtering** (all querystring values are strings). **A column is filterable only if it appears in `schemas.response`** — the filter surface is the readable surface, so a list that returns `id / title` cannot be probed with `?secret=…` (unknown or unreadable keys are ignored, not rejected). Anything you want filterable belongs in the response schema.
+  - `key=a,b,c` → `IN (...)` when the key is `id` or ends with `Id`; otherwise `OR ILIKE %a% OR ILIKE %b%`
+  - `key=foo` where the key is `id` or ends with `Id` → `eq`; otherwise `ILIKE %foo%`
+  - non-text columns (uuid / number / date / enum) are always `eq` whatever the key looks like — `ILIKE` against them is a database type error, not an empty result
+  - `%` and `_` inside a value match literally; they are not wildcards
+  - `${anything}AtFrom` / `${anything}AtTo` → `gte` / `lte` against the matching `${anything}At` column; a value that is not a recognizable date is a 400
   - `jsonArrayFields: ["tags"]` → `EXISTS (SELECT 1 FROM jsonb_array_elements_text(col) t WHERE t LIKE %v%)`
-- **Pagination / sort**: `current` (default `"1"`), `pageSize` (default `"10"`), `orderBy` (default `createdAt`), `orderDir` (`asc|desc`, default `desc`).
+- **Pagination / sort**: `current` (default `"1"`), `pageSize` (default `"10"`, capped at `10000`, unparseable values fall back to the default — never to "no limit"), `orderBy` (default `createdAt`; must name a real column on the table, otherwise 400), `orderDir` (`asc|desc`, default `desc`).
 - **Relations**: `relations: [{ table, sql, select, groupBy? }]` drives `leftJoin` + optional `groupBy(root.id, relation.id)`; `select` merges into the final `SELECT` projection and can contain raw `sql\`…\`` correlated sub-queries.
 
 ## Guardrails
@@ -351,6 +353,7 @@ export const { GET } = route({
 - Always pass `insertXxxSchema` to POST, `updateXxxSchema` (has `.required({ id: true })`) to PUT, `selectXxxSchema` to GET body, `queryListSchema(selectXxxSchema.partial())` to GET_LIST query.
 - Query-string schemas stay `z.string()` — numbers / arrays from querystrings must stay strings and be parsed inside `handler` or `setParams`.
 - Do not reuse `insertSchema` for PUT — missing `id` silently dispatches an update without a where clause.
+- A `contentType: "multipart/form-data"` POST is reachable from a cross-site HTML form; a JSON one is not (the framework answers 415 on a mismatched content type). If the app authenticates with cookies, gate those routes on an `Origin` check of your own.
 - `schemas.response` on list/get is the **response item** schema, not the query shape. Query shape goes in `schemas.query`.
 - Do not inline `{ db, getSession }` into individual route files — always import the pre-bound `postOperation` / `getListOperation` / … from `@backend/utils/route-operation` so session/DB swaps are one-file changes.
 - `jsonb` columns declared with `jsonb(...)` carry no zod info — extend the matching insert/select schema with `.merge(z.object({ field: z.array(z.string()).optional() }))` to keep typing accurate.

package/SKILL.md

@@ -318,12 +318,14 @@ export const { GET } = route({
 - **Auto injection**: POST stamps the scope column with the scope value (by default that is `creatorId = session.userId`); PUT writes `editorId = session.userId`; GET/GET_LIST apply the scope as a mandatory `where`.
 - **Session shape** is yours: `getSession` is generic, so resolve "who + which space + what role" once and let `scope.value` / `can` read the same object instead of each querying again.
 - **Date coercion**: any body field ending in `At` is passed through `dayjs(value).toDate()` before write — accept ISO strings from clients.
-- **List filtering** (all querystring values are strings):
-  - `key=a,b,c` → `IN (...)` when key ends with `Id`; otherwise `OR ILIKE %a% OR ILIKE %b%`
-  - `key=foo` where key ends with `Id` → `eq`; otherwise `ILIKE %foo%`
-  - `${anything}AtFrom` / `${anything}AtTo` → `gte` / `lte` against the matching `${anything}At` column
+- **List filtering** (all querystring values are strings). **A column is filterable only if it appears in `schemas.response`** — the filter surface is the readable surface, so a list that returns `id / title` cannot be probed with `?secret=…` (unknown or unreadable keys are ignored, not rejected). Anything you want filterable belongs in the response schema.
+  - `key=a,b,c` → `IN (...)` when the key is `id` or ends with `Id`; otherwise `OR ILIKE %a% OR ILIKE %b%`
+  - `key=foo` where the key is `id` or ends with `Id` → `eq`; otherwise `ILIKE %foo%`
+  - non-text columns (uuid / number / date / enum) are always `eq` whatever the key looks like — `ILIKE` against them is a database type error, not an empty result
+  - `%` and `_` inside a value match literally; they are not wildcards
+  - `${anything}AtFrom` / `${anything}AtTo` → `gte` / `lte` against the matching `${anything}At` column; a value that is not a recognizable date is a 400
   - `jsonArrayFields: ["tags"]` → `EXISTS (SELECT 1 FROM jsonb_array_elements_text(col) t WHERE t LIKE %v%)`
-- **Pagination / sort**: `current` (default `"1"`), `pageSize` (default `"10"`), `orderBy` (default `createdAt`), `orderDir` (`asc|desc`, default `desc`).
+- **Pagination / sort**: `current` (default `"1"`), `pageSize` (default `"10"`, capped at `10000`, unparseable values fall back to the default — never to "no limit"), `orderBy` (default `createdAt`; must name a real column on the table, otherwise 400), `orderDir` (`asc|desc`, default `desc`).
 - **Relations**: `relations: [{ table, sql, select, groupBy? }]` drives `leftJoin` + optional `groupBy(root.id, relation.id)`; `select` merges into the final `SELECT` projection and can contain raw `sql\`…\`` correlated sub-queries.
 
 ## Guardrails
@@ -331,6 +333,7 @@ export const { GET } = route({
 - Always pass `insertXxxSchema` to POST, `updateXxxSchema` (has `.required({ id: true })`) to PUT, `selectXxxSchema` to GET body, `queryListSchema(selectXxxSchema.partial())` to GET_LIST query.
 - Query-string schemas stay `z.string()` — numbers / arrays from querystrings must stay strings and be parsed inside `handler` or `setParams`.
 - Do not reuse `insertSchema` for PUT — missing `id` silently dispatches an update without a where clause.
+- A `contentType: "multipart/form-data"` POST is reachable from a cross-site HTML form; a JSON one is not (the framework answers 415 on a mismatched content type). If the app authenticates with cookies, gate those routes on an `Origin` check of your own.
 - `schemas.response` on list/get is the **response item** schema, not the query shape. Query shape goes in `schemas.query`.
 - Do not inline `{ db, getSession }` into individual route files — always import the pre-bound `postOperation` / `getListOperation` / … from `@backend/utils/route-operation` so session/DB swaps are one-file changes.
 - `jsonb` columns declared with `jsonb(...)` carry no zod info — extend the matching insert/select schema with `.merge(z.object({ field: z.array(z.string()).optional() }))` to keep typing accurate.

package/es/backend/actions/create-get-action.js

@@ -18,14 +18,17 @@ export function createGetAction(_ref) {
     table = _ref.table;
   return /*#__PURE__*/function () {
     var _ref3 = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime().mark(function _callee(params, _ref2) {
-      var scope, fields, _i, _Object$keys, key, field, _getListQuery, query, countQuery, _yield$getListData, _yield$getListData$da, result;
+      var scope, exposed, fields, _i, _exposed, key, field, _getListQuery, query, countQuery, _yield$getListData, _yield$getListData$da, result;
       return _regeneratorRuntime().wrap(function _callee$(_context) {
         while (1) switch (_context.prev = _context.next) {
           case 0:
             scope = _ref2.scope;
-            fields = {}; // @ts-ignore
-            for (_i = 0, _Object$keys = Object.keys(bodySchema.shape); _i < _Object$keys.length; _i++) {
-              key = _Object$keys[_i];
+            // 筛选面与可见面同源，理由见 create-get-list-action 里的同一段。
+            // @ts-ignore
+            exposed = Object.keys(bodySchema.shape);
+            fields = {};
+            for (_i = 0, _exposed = exposed; _i < _exposed.length; _i++) {
+              key = _exposed[_i];
               // @ts-ignore
               field = table[key];
               if (field) {
@@ -35,13 +38,14 @@ export function createGetAction(_ref) {
             _getListQuery = getListQuery({
               db: db,
               fields: fields,
+              filterable: exposed,
               jsonArrayFields: jsonArrayFields,
               params: params,
               relations: relations,
               scope: scope,
               table: table
             }), query = _getListQuery.query, countQuery = _getListQuery.countQuery;
-            _context.next = 6;
+            _context.next = 7;
             return getListData({
               bodySchema: bodySchema,
               countQuery: countQuery,
@@ -49,12 +53,12 @@ export function createGetAction(_ref) {
               pageSize: 1,
               query: query
             })();
-          case 6:
+          case 7:
             _yield$getListData = _context.sent;
             _yield$getListData$da = _slicedToArray(_yield$getListData.data, 1);
             result = _yield$getListData$da[0];
             return _context.abrupt("return", result);
-          case 10:
+          case 11:
           case "end":
             return _context.stop();
         }

package/es/backend/actions/create-get-list-action.js

@@ -15,15 +15,19 @@ export function createGetListAction(_ref) {
     table = _ref.table;
   return /*#__PURE__*/function () {
     var _ref3 = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime().mark(function _callee(params, _ref2) {
-      var scope, _ref4, current, pageSize, other, fields, _i, _Object$keys, key, field, _getListQuery, query, countQuery;
+      var scope, _ref4, current, pageSize, other, exposed, fields, _i, _exposed, key, field, _getListQuery, query, countQuery;
       return _regeneratorRuntime().wrap(function _callee$(_context) {
         while (1) switch (_context.prev = _context.next) {
           case 0:
             scope = _ref2.scope;
-            _ref4 = params, current = _ref4.current, pageSize = _ref4.pageSize, other = _objectWithoutProperties(_ref4, _excluded);
-            fields = {}; // @ts-ignore
-            for (_i = 0, _Object$keys = Object.keys(bodySchema.shape); _i < _Object$keys.length; _i++) {
-              key = _Object$keys[_i];
+            _ref4 = params, current = _ref4.current, pageSize = _ref4.pageSize, other = _objectWithoutProperties(_ref4, _excluded); // 响应 schema 的字段集 = 调用方读得到的那些列。它同时决定两件事：**查什么**（下面的
+            // fields）和**能按什么筛**（filterable）。两者必须是同一份 —— 否则一个只返回 id / title 的
+            // 列表照样能 `?secret=sk-a` 让数据库去 ilike，再从 total 上把那一列逐字符读出来。
+            // @ts-ignore
+            exposed = Object.keys(bodySchema.shape);
+            fields = {};
+            for (_i = 0, _exposed = exposed; _i < _exposed.length; _i++) {
+              key = _exposed[_i];
               // @ts-ignore
               field = table[key];
               if (field) {
@@ -33,6 +37,7 @@ export function createGetListAction(_ref) {
             _getListQuery = getListQuery({
               db: db,
               fields: fields,
+              filterable: exposed,
               jsonArrayFields: jsonArrayFields,
               params: other,
               relations: relations,
@@ -46,7 +51,7 @@ export function createGetListAction(_ref) {
               pageSize: pageSize,
               query: query
             })());
-          case 6:
+          case 7:
           case "end":
             return _context.stop();
         }

package/es/backend/actions/get-list-data.d.ts

@@ -1,6 +1,6 @@
 import { ZodSchema } from "zod";
 import { getListQuery } from "./get-list-query.js";
-export declare function getListData<B extends ZodSchema>({ query, countQuery, pageSize, current, bodySchema, }: {
+export declare function getListData<B extends ZodSchema>({ query, countQuery, pageSize: rawPageSize, current: rawCurrent, bodySchema, }: {
     bodySchema: B;
     current?: number;
     pageSize?: number;

package/es/backend/actions/get-list-data.js

@@ -10,14 +10,21 @@ function asyncGeneratorStep(gen, resolve, reject, _next, _throw, key, arg) { try
 function _asyncToGenerator(fn) { return function () { var self = this, args = arguments; return new Promise(function (resolve, reject) { var gen = fn.apply(self, args); function _next(value) { asyncGeneratorStep(gen, resolve, reject, _next, _throw, "next", value); } function _throw(err) { asyncGeneratorStep(gen, resolve, reject, _next, _throw, "throw", err); } _next(undefined); }); }; }
 import { rpcOperation } from "next-rest-framework";
 import { listBodySchema } from "../schemas/index.js";
+import { normalizePaging } from "./paging.js";
 export function getListData(_ref) {
   var query = _ref.query,
     countQuery = _ref.countQuery,
-    _ref$pageSize = _ref.pageSize,
-    pageSize = _ref$pageSize === void 0 ? 10 : _ref$pageSize,
-    _ref$current = _ref.current,
-    current = _ref$current === void 0 ? 1 : _ref$current,
+    rawPageSize = _ref.pageSize,
+    rawCurrent = _ref.current,
     bodySchema = _ref.bodySchema;
+  // 这两个值到这儿还是 query 里来的字符串。归一化的三个理由见 paging.ts —— 最要紧的一条是
+  // `+"abc"` 是 NaN，而 drizzle 遇到 falsy 的 limit 是**整条 LIMIT 不加**，一个笔误就是全量返回。
+  var _normalizePaging = normalizePaging({
+      current: rawCurrent,
+      pageSize: rawPageSize
+    }),
+    current = _normalizePaging.current,
+    pageSize = _normalizePaging.pageSize;
   return rpcOperation().outputs([{
     body: listBodySchema(bodySchema),
     contentType: "application/json"
@@ -27,7 +34,7 @@ export function getListData(_ref) {
       while (1) switch (_context.prev = _context.next) {
         case 0:
           _context.next = 2;
-          return query.limit(+pageSize).offset((+current - 1) * +pageSize).execute();
+          return query.limit(pageSize).offset((current - 1) * pageSize).execute();
         case 2:
           data = _context.sent;
           _context.next = 5;

package/es/backend/actions/get-list-query-core.d.ts

@@ -15,10 +15,14 @@ export interface ListQueryRelation {
 }
 /** 两套方言之间**全部**的差异。加第三种数据库时要写的也只有这两条。 */
 export interface ListQueryDialect {
-    /** 大小写不敏感的「包含」。 */
-    contains(_column: Column, _keyword: string): SQL;
-    /** 「这个 JSON 数组列里有没有元素含这段文字」。 */
-    jsonArrayContains(_column: Column, _keyword: string): SQL;
+    /**
+     * 大小写不敏感的「包含」。收到的 pattern 是**已经转义、已经带好 `%` 的完整模式串** ——
+     * 转义收在核心里做（见 escapeLikePattern），免得加第三种方言时漏掉那一步：漏掉不会报错，
+     * 只会让 `%` 重新变回通配符。
+     */
+    contains(_column: Column, _pattern: string): SQL;
+    /** 「这个 JSON 数组列里有没有元素匹配这个模式」。pattern 同上，已转义。 */
+    jsonArrayContains(_column: Column, _pattern: string): SQL;
 }
 export interface ListQueryParams {
     [field: string]: unknown;
@@ -27,9 +31,26 @@ export interface ListQueryParams {
     page?: number;
     pageSize?: number;
 }
-export declare function createGetListQuery(dialect: ListQueryDialect): <TTable extends ListQueryTable, TSelection extends Record<string, unknown>>({ db, fields, jsonArrayFields, params, relations, scope, table, }: {
+/**
+ * 把用户输入变成 LIKE 模式里的**字面量**。
+ *
+ * 不转义的话 `?name=%` 就是「匹配全部」、`?name=a_c` 里的下划线是「任意一个字符」—— 前者只是
+ * 筛不准，后者配合「能按某一列筛」就是一个逐字符试探值的通道。反斜杠自己也要转，否则
+ * `?name=\` 会把后面那个 `%` 吃掉。
+ */
+export declare function escapeLikePattern(keyword: string): string;
+export declare function createGetListQuery(dialect: ListQueryDialect): <TTable extends ListQueryTable, TSelection extends Record<string, unknown>>({ db, fields, filterable, jsonArrayFields, params, relations, scope, table, }: {
     db: any;
     fields: TSelection;
+    /**
+     * 允许被当成筛选条件的键。**不传等于不限制**（直接调 getListQuery 的老调用方行为不变）。
+     *
+     * 为什么需要它：筛选是按列名在表上找列的，而那跟「这个端点返回哪些列」完全脱钩 —— 于是
+     * 一个只返回 id / title 的列表，照样可以 `?secret=sk-a` 让数据库去 `ilike '%sk-a%'`，再从
+     * 返回的 total 上把这一列逐字符读出来。列表工厂传进来的是响应 schema 的字段集，也就是
+     * 「调用方本来就读得到的那些列」，筛选面与可见面因此对齐。
+     */
+    filterable?: readonly string[] | undefined;
     jsonArrayFields?: string[] | undefined;
     /**
      * 行级作用域。**必填**，不想隔离就显式传 NO_SCOPE —— 写成可选的话，漏传就退化成查全表，

package/es/backend/actions/get-list-query-core.js

@@ -27,7 +27,8 @@ function _objectWithoutPropertiesLoose(source, excluded) { if (source == null) r
 // 日期范围怎么认、多值怎么拆、排序与分页怎么加、计数查询怎么建，两边一模一样。**真正的方言
 // 差异只有两条原语**：
 //
-//   · 大小写不敏感的模糊匹配 —— pg 要 ilike，sqlite 的 like 本来就不区分大小写；
+//   · 大小写不敏感的模糊匹配 —— pg 用 ilike，sqlite 的 like 本来就不区分大小写，但要自己带
+//     ESCAPE（pg 的 LIKE 默认拿反斜杠当转义符，sqlite 不带 ESCAPE 子句就一个转义符都没有）；
 //   · 「JSON 数组列里有没有含这段文字的元素」—— pg 用 jsonb_array_elements_text，
 //     sqlite 用 json_each（而且取值的字段名也不同：tag vs tag.value）。
 //
@@ -37,8 +38,10 @@ function _objectWithoutPropertiesLoose(source, excluded) { if (source == null) r
 // 抄两份的代价不是抽象的：这个文件改过好几次（作用域先于筛选、空值跳过、日期范围），
 // 每一次都得记得改另一棵树，而漏掉不会有任何东西报错 —— 只会让 sqlite 那边悄悄少一条规则。
 
-import { and, asc, desc, eq, gte, inArray, lte, or, sql } from "drizzle-orm";
+import { and, asc, Column, desc, eq, gte, inArray, is, lte, or, sql } from "drizzle-orm";
+import { HttpError } from "../errors.js";
 import { scopeCondition } from "../scope.js";
+import { normalizePaging } from "./paging.js";
 
 /**
  * 核心用得到表的哪一部分：只有 `id`（计数与分组要它）和「按列名取列」。
@@ -47,29 +50,71 @@ import { scopeCondition } from "../scope.js";
 
 /** 两套方言之间**全部**的差异。加第三种数据库时要写的也只有这两条。 */
 
+/**
+ * 把用户输入变成 LIKE 模式里的**字面量**。
+ *
+ * 不转义的话 `?name=%` 就是「匹配全部」、`?name=a_c` 里的下划线是「任意一个字符」—— 前者只是
+ * 筛不准，后者配合「能按某一列筛」就是一个逐字符试探值的通道。反斜杠自己也要转，否则
+ * `?name=\` 会把后面那个 `%` 吃掉。
+ */
+export function escapeLikePattern(keyword) {
+  return "%".concat(keyword.replace(/[\\%_]/g, function (char) {
+    return "\\".concat(char);
+  }), "%");
+}
+
 // 按列名从表（或它的关联表）里取列。**唯一一处按字符串索引的地方** —— 收在这儿，
 // 免得每个用到的地方都写一次断言。取不到回 undefined，调用方据此跳过这个条件。
+//
+// is(…, Column) 这层不是多余的：按字符串取属性会取到原型链上的东西（`?orderBy=constructor`
+// 拿到的是 Object 构造函数），而它不会在这里报错，会一路流到 drizzle 里才炸 —— 症状是 500，
+// 而正确的症状是「这不是一个列」。
 function columnAt(table, key) {
-  return table[key];
+  var value = table[key];
+  return is(value, Column) ? value : undefined;
+}
+
+// 「这个键该精确匹配还是模糊匹配」。
+//
+// 从前是 `/id/i.test(key)` —— 「名字里带 id」，于是 width / hidden / video 这类列名也被当成 id
+// 列。文档写的一直是「以 Id 结尾」，这里按文档来。
+function isIdKey(key) {
+  return key === "id" || key.endsWith("Id");
+}
+
+// 模糊匹配只在**文本列**上成立。uuid / 数字 / 时间 / 枚举列上 ILIKE 不是「筛不出东西」，是
+// 数据库层面的类型错误（PG：operator does not exist: uuid ~~* unknown），也就是一个 500。
+// 所以这些列一律退回精确匹配 —— 这同时让上面那条 isIdKey 的收紧变得安全：一个不以 Id 结尾的
+// uuid 列（比如 parent、owner）从「精确」掉到「模糊」也不会炸。
+function isFuzzyMatchable(column) {
+  return column.dataType === "string" && !/uuid|enum/i.test(column.columnType);
 }
 export function createGetListQuery(dialect) {
   return function getListQuery(_ref) {
     var db = _ref.db,
       fields = _ref.fields,
+      filterable = _ref.filterable,
       jsonArrayFields = _ref.jsonArrayFields,
       params = _ref.params,
       relations = _ref.relations,
       scope = _ref.scope,
       table = _ref.table;
-    var _params$page = params.page,
-      page = _params$page === void 0 ? 1 : _params$page,
-      _params$pageSize = params.pageSize,
-      pageSize = _params$pageSize === void 0 ? 10 : _params$pageSize,
-      _params$orderBy = params.orderBy,
-      orderBy = _params$orderBy === void 0 ? "createdAt" : _params$orderBy,
+    var page = params.page,
+      rawPageSize = params.pageSize,
+      orderBy = params.orderBy,
       _params$orderDir = params.orderDir,
       orderDir = _params$orderDir === void 0 ? "desc" : _params$orderDir,
       filters = _objectWithoutProperties(params, _excluded);
+    var _normalizePaging = normalizePaging({
+        current: page,
+        pageSize: rawPageSize
+      }),
+      current = _normalizePaging.current,
+      pageSize = _normalizePaging.pageSize;
+    var allowed = filterable ? new Set(filterable) : undefined;
+    var isFilterable = function isFilterable(key) {
+      return !allowed || allowed.has(key);
+    };
 
     // ==========================================================================
     // 基础查询
@@ -123,11 +168,11 @@ export function createGetListQuery(dialect) {
     // 单个筛选条件
     // ==========================================================================
     // 三条规矩，两套方言一致：
-    //   · 名字里带 id 的按精确匹配（多值走 IN），其余按模糊；
+    //   · 以 Id 结尾的键（以及非文本列）按精确匹配（多值走 IN），其余按模糊；
     //   · 逗号分隔视为多值；
     //   · JSON 数组列走 dialect 那条 EXISTS。
     function addCondition(conditions, key, value, targetColumn) {
-      var isIdField = /id/i.test(key);
+      var isExact = isIdKey(key) || !isFuzzyMatchable(targetColumn);
       var isJsonArray = jsonArrayFields === null || jsonArrayFields === void 0 ? void 0 : jsonArrayFields.includes(key);
       if (typeof value !== "string") {
         conditions.push(eq(targetColumn, value));
@@ -142,22 +187,22 @@ export function createGetListQuery(dialect) {
         }
         if (isJsonArray) {
           // 多值时只认第一个 —— 与从前逐字一致，不趁重构改行为。
-          conditions.push(dialect.jsonArrayContains(targetColumn, values[0]));
-        } else if (isIdField) {
+          conditions.push(dialect.jsonArrayContains(targetColumn, escapeLikePattern(values[0])));
+        } else if (isExact) {
           conditions.push(inArray(targetColumn, values));
         } else {
           conditions.push(or.apply(void 0, _toConsumableArray(values.map(function (item) {
-            return dialect.contains(targetColumn, item);
+            return dialect.contains(targetColumn, escapeLikePattern(item));
           }))));
         }
         return;
       }
       if (isJsonArray) {
-        conditions.push(dialect.jsonArrayContains(targetColumn, value));
-      } else if (isIdField) {
+        conditions.push(dialect.jsonArrayContains(targetColumn, escapeLikePattern(value)));
+      } else if (isExact) {
         conditions.push(eq(targetColumn, value));
       } else {
-        conditions.push(dialect.contains(targetColumn, value));
+        conditions.push(dialect.contains(targetColumn, escapeLikePattern(value)));
       }
     }
     function buildConditions() {
@@ -173,12 +218,26 @@ export function createGetListQuery(dialect) {
 
         // 日期范围：xxxAtFrom / xxxAtTo 落到 xxxAt 那一列上。
         if (key.endsWith("AtFrom") || key.endsWith("AtTo")) {
-          var baseFieldName = key.replace(/(AtFrom|AtTo)$/, "");
-          var _targetColumn = findTargetColumn("".concat(baseFieldName, "At"));
+          var baseFieldName = "".concat(key.replace(/(AtFrom|AtTo)$/, ""), "At");
+          // 准入按落到的**那一列**判，不按参数名 —— createdAtFrom 能不能用，取决于
+          // createdAt 是不是一个调用方读得到的列。
+          if (!isFilterable(baseFieldName)) {
+            continue;
+          }
+          var _targetColumn = findTargetColumn(baseFieldName);
           if (!_targetColumn) {
             continue;
           }
-          conditions.push(key.endsWith("AtFrom") ? gte(_targetColumn, new Date(value)) : lte(_targetColumn, new Date(value)));
+          var at = new Date(value);
+          // 认不出来的日期不能往下传：drizzle 序列化 Invalid Date 时抛 RangeError，
+          // 那是一个 500，而这明明是请求写错了。
+          if (Number.isNaN(at.getTime())) {
+            throw new HttpError(400, "".concat(key, " \u4E0D\u662F\u4E00\u4E2A\u80FD\u8BC6\u522B\u7684\u65F6\u95F4\uFF0C\u8BF7\u7528 ISO 8601\uFF08\u5982 2026-08-01T00:00:00Z\uFF09\u3002"));
+          }
+          conditions.push(key.endsWith("AtFrom") ? gte(_targetColumn, at) : lte(_targetColumn, at));
+          continue;
+        }
+        if (!isFilterable(key)) {
           continue;
         }
         var targetColumn = findTargetColumn(key);
@@ -190,7 +249,18 @@ export function createGetListQuery(dialect) {
       return conditions;
     }
     function buildOrderBy() {
-      var orderColumn = columnAt(table, orderBy);
+      // 请求里给了值、和「谁都没给于是走默认」是两件事，错误也就不是同一种：前者是请求写错
+      // （400），后者是这张表上根本没有 createdAt，属于配置错（跟 scopeCondition 那边同一类，
+      // 抛普通 Error）。从前两种都退化成 `order by  desc` —— 一句语法错误的 SQL，500。
+      var requested = typeof orderBy === "string" && orderBy ? orderBy : undefined;
+      var orderKey = requested !== null && requested !== void 0 ? requested : "createdAt";
+      var orderColumn = columnAt(table, orderKey);
+      if (!orderColumn) {
+        if (requested) {
+          throw new HttpError(400, "orderBy \"".concat(requested, "\" \u4E0D\u662F\u8FD9\u5F20\u8868\u4E0A\u7684\u5217\u3002"));
+        }
+        throw new Error("\u9ED8\u8BA4\u6392\u5E8F\u5217 createdAt \u4E0D\u5728\u8FD9\u5F20\u8868\u4E0A\u3002\u7ED9\u8FD9\u5F20\u8868\u7684\u5217\u8868\u67E5\u8BE2\u663E\u5F0F\u4F20\u4E00\u4E2A orderBy\u3002");
+      }
       return orderDir === "asc" ? asc(orderColumn) : desc(orderColumn);
     }
 
@@ -205,7 +275,7 @@ export function createGetListQuery(dialect) {
     var conditions = scopeSql ? [scopeSql] : [];
     conditions.push.apply(conditions, _toConsumableArray(buildConditions()));
     var where = conditions.length > 0 ? and.apply(void 0, conditions) : undefined;
-    var query = baseQuery.where(where).orderBy(buildOrderBy()).limit(pageSize).offset((page - 1) * pageSize);
+    var query = baseQuery.where(where).orderBy(buildOrderBy()).limit(pageSize).offset((current - 1) * pageSize);
     var countQuery = db.select({
       count: sql(_templateObject || (_templateObject = _taggedTemplateLiteral(["COUNT(DISTINCT ", ")"])), table.id)
     }).from(table).where(where);

package/es/backend/actions/get-list-query.d.ts

@@ -6,6 +6,8 @@ import { type ListQueryParams } from "./get-list-query-core.js";
 export declare function getListQuery<TTable extends BaseTable, TSelection extends SelectedFields>(args: {
     db: NodePgDatabase<Record<string, unknown>>;
     fields: TSelection;
+    /** 允许被当成筛选条件的键。不传等于不限制，见核心里的说明。 */
+    filterable?: readonly string[];
     jsonArrayFields?: string[];
     /**
      * 行级作用域。**必填**，不想隔离就显式传 NO_SCOPE —— 写成可选的话，漏传就退化成查全表，

package/es/backend/actions/get-list-query.js

@@ -8,14 +8,17 @@ function _taggedTemplateLiteral(strings, raw) { if (!raw) { raw = strings.slice(
 
 import { ilike, sql } from "drizzle-orm";
 import { createGetListQuery } from "./get-list-query-core.js";
+
+// pattern 由核心转义好再传进来（见 escapeLikePattern）。pg 这边不用写 ESCAPE 子句：
+// LIKE / ILIKE 默认就拿反斜杠当转义符，而模式串是绑定参数，不经过字符串字面量那套解析。
 var run = createGetListQuery({
-  contains: function contains(column, keyword) {
-    return ilike(column, "%".concat(keyword, "%"));
+  contains: function contains(column, pattern) {
+    return ilike(column, pattern);
   },
   // jsonb 数组展开成行再逐个 LIKE。列存的是 text[] 形状的 jsonb（见 createTableSchema 的
   // jsonArrayFields），所以用 _text 那个变体，取到的 tag 直接就是字符串。
-  jsonArrayContains: function jsonArrayContains(column, keyword) {
-    return sql(_templateObject || (_templateObject = _taggedTemplateLiteral(["\n    EXISTS (\n      SELECT 1 FROM jsonb_array_elements_text(", ") tag\n      WHERE tag LIKE ", "\n    )\n  "])), column, "%".concat(keyword, "%"));
+  jsonArrayContains: function jsonArrayContains(column, pattern) {
+    return sql(_templateObject || (_templateObject = _taggedTemplateLiteral(["\n    EXISTS (\n      SELECT 1 FROM jsonb_array_elements_text(", ") tag\n      WHERE tag LIKE ", "\n    )\n  "])), column, pattern);
   }
 });
 export function getListQuery(args) {

package/es/backend/actions/index.d.ts

@@ -4,3 +4,4 @@ export { createGetListAction } from "./create-get-list-action.js";
 export { createPostAction } from "./create-post-action.js";
 export { createPutAction } from "./create-put-action.js";
 export { getListQuery } from "./get-list-query.js";
+export { MAX_PAGE_SIZE, normalizePaging } from "./paging.js";

package/es/backend/actions/index.js

@@ -3,4 +3,5 @@ export { createGetAction } from "./create-get-action.js";
 export { createGetListAction } from "./create-get-list-action.js";
 export { createPostAction } from "./create-post-action.js";
 export { createPutAction } from "./create-put-action.js";
-export { getListQuery } from "./get-list-query.js";
+export { getListQuery } from "./get-list-query.js";
+export { MAX_PAGE_SIZE, normalizePaging } from "./paging.js";

package/es/backend/actions/paging.d.ts

@@ -0,0 +1,11 @@
+/** pageSize 的硬上界。取这个量级是因为「一次把一整块数据取回来」是列表的正常用法。 */
+export declare const MAX_PAGE_SIZE = 10000;
+export declare const DEFAULT_PAGE_SIZE = 10;
+/** 返回一定能安全喂给 limit / offset 的一对整数。 */
+export declare function normalizePaging({ current, pageSize, }: {
+    current?: unknown;
+    pageSize?: unknown;
+}): {
+    current: number;
+    pageSize: number;
+};

package/es/backend/actions/paging.js

@@ -0,0 +1,32 @@
+// ==============================================================================
+// 分页参数归一化（pg / sqlite 共用）
+// ==============================================================================
+// query 参数在线上只有字符串，而这两个值最后是直接进 `.limit()` / `.offset()` 的。不归一化的
+// 后果不是「筛不准」，是三种更难看的症状：
+//
+//   · `?pageSize=abc` → `+"abc"` 是 NaN，而 drizzle 对 falsy 的 limit 是**整条 LIMIT 不加** ——
+//     一个笔误就是全量返回。这是这个文件存在的首要理由。
+//   · `?current=0` → OFFSET 变成负数，数据库直接报错，一个 500。
+//   · `?pageSize=99999999` → 真的去拉这么多行。
+//
+// 上界是**截断**而不是报错：列表的 describe 一直在教调用方「要整批就把 pageSize 调大」，
+// 那些调用方传的是 5000 这种量级的真实值，为了一个上界让它们 400 不值当。截断之后 total 照常
+// 是真实总数，调用方分得清自己有没有拿全。
+
+/** pageSize 的硬上界。取这个量级是因为「一次把一整块数据取回来」是列表的正常用法。 */
+export var MAX_PAGE_SIZE = 10000;
+export var DEFAULT_PAGE_SIZE = 10;
+function toPositiveInt(value, fallback) {
+  var parsed = Math.floor(Number(value));
+  return Number.isFinite(parsed) && parsed >= 1 ? parsed : fallback;
+}
+
+/** 返回一定能安全喂给 limit / offset 的一对整数。 */
+export function normalizePaging(_ref) {
+  var current = _ref.current,
+    pageSize = _ref.pageSize;
+  return {
+    current: toPositiveInt(current, 1),
+    pageSize: Math.min(toPositiveInt(pageSize, DEFAULT_PAGE_SIZE), MAX_PAGE_SIZE)
+  };
+}

package/es/backend/route-operation/write-operation-core.js

@@ -98,11 +98,18 @@ export function createPostOperationFactory(_ref) {
                 // creatorId，作者就没人写了，而 setBody 只能返回请求体 schema 里有的字段。
                 // 归属戳排在它后面 —— 两者撞同一个键时以归属为准，那是更强的那条不变量。
                 //
-                // **归属戳必须最后展开**，这是一条安全不变量，别为了「让调用方能覆盖」而调顺序：
-                // `.input({ body })` 只校验、**不替换**请求体（next-rest-framework 交给 handler 的
-                // clone 会重新解析原始 JSON），而 createPostAction 直接 insert，中间没有第二道
-                // schema 过滤。所以只要 body 排在戳后面，客户端在 JSON 里塞一个 `ownerId` /
-                // `creatorId` 就能把行写到别人名下 —— 调用方把该列从 schema 里 omit 掉也拦不住。
+                // **归属戳必须最后展开**，这是一条安全不变量，别为了「让调用方能覆盖」而调顺序。
+                //
+                // 请求体到这里已经被 `.input({ body })` 过了一遍 zod：next-rest-framework 把 handler
+                // 收到的那个 clone 的 `.json()` 换成了校验后的结果，所以 schema 里没有的键（归属列、
+                // basicFields、serverColumns）在这一步之前就没了。**但别把那当成这里的边界**：
+                //   · 它是被钉住的那个 fork 的行为，本仓库拦不住它变（见
+                //     __tests__/write-body-strip，那组用例就是钉它的）；
+                //   · 自定义 parseBody 会绕开它；`.catchall()` / `.passthrough()` 的 body schema
+                //     也会让未知键活着过来；
+                //   · createPostAction 是 `db.insert(table).values(body)`，中间没有第二道 schema
+                //     过滤，而 drizzle 会老老实实写下每一个**是真列**的键。
+                // 所以归属这一条不靠 schema，靠顺序：戳排在 body 后面，客户端塞什么都盖不掉。
                 // 见 __tests__/route-operation-scope-stamp。
                 stamped = session === undefined ? {} : (_access$stamp = access === null || access === void 0 || (_access$stamp2 = access.stamp) === null || _access$stamp2 === void 0 ? void 0 : _access$stamp2.call(access, session)) !== null && _access$stamp !== void 0 ? _access$stamp : {};
                 params = _objectSpread(_objectSpread(_objectSpread(_objectSpread({}, body), extraBody), stamped), scopeStamp(scope));

package/es/backend/schemas/common.d.ts

@@ -32,7 +32,7 @@ export declare const BASIC_UPDATE_OMIT: {
     readonly createdAt: true;
     readonly updatedAt: true;
 };
-export declare const queryListSchema: <Incoming extends z.ZodObject<z.core.$ZodLooseShape, z.core.$strip>>(schema: Incoming) => z.ZodObject<(("orderBy" | "orderDir" | "pageSize" | "creatorId" | "current" | "createdAtFrom" | "createdAtTo") & keyof Incoming["shape"] extends never ? {
+export declare const queryListSchema: <Incoming extends z.ZodObject<z.core.$ZodLooseShape, z.core.$strip>>(schema: Incoming) => z.ZodObject<(("current" | "pageSize" | "orderBy" | "orderDir" | "creatorId" | "createdAtFrom" | "createdAtTo") & keyof Incoming["shape"] extends never ? {
     current: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     pageSize: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     createdAtFrom: z.ZodOptional<z.ZodString>;
@@ -65,7 +65,7 @@ export declare const queryListSchema: <Incoming extends z.ZodObject<z.core.$ZodL
         asc: "asc";
         desc: "desc";
     }>>;
-}[K]; } : never) & (Incoming["shape"] extends infer T_2 extends z.core.util.SomeObject ? { [K_1 in keyof T_2]: Incoming["shape"][K_1]; } : never)) extends infer T ? { [k in keyof T]: (("orderBy" | "orderDir" | "pageSize" | "creatorId" | "current" | "createdAtFrom" | "createdAtTo") & keyof Incoming["shape"] extends never ? {
+}[K]; } : never) & (Incoming["shape"] extends infer T_2 extends z.core.util.SomeObject ? { [K_1 in keyof T_2]: Incoming["shape"][K_1]; } : never)) extends infer T ? { [k in keyof T]: (("current" | "pageSize" | "orderBy" | "orderDir" | "creatorId" | "createdAtFrom" | "createdAtTo") & keyof Incoming["shape"] extends never ? {
     current: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     pageSize: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     createdAtFrom: z.ZodOptional<z.ZodString>;

package/es/backend/schemas/common.js

@@ -66,7 +66,7 @@ export var BASIC_UPDATE_OMIT = {
 export var queryListSchema = function queryListSchema(schema) {
   return z.object({
     current: z.string().optional().default("1").describe("Page number, starting at 1."),
-    pageSize: z.string().optional().default("10").describe("Rows per page. Omitting it yields only 10 — pass a larger value to get the whole set."),
+    pageSize: z.string().optional().default("10").describe("Rows per page. Omitting it yields only 10 — pass a larger value to get the whole set. Capped at 10000; compare `total` against what you received to tell whether more remain."),
     createdAtFrom: z.string().optional().describe("Keep only rows created at or after this instant (ISO 8601, e.g. 2026-08-01T00:00:00Z)."),
     createdAtTo: z.string().optional().describe("Keep only rows created at or before this instant."),
     orderBy: z.string().optional().describe("Column to sort by — a column name of this resource (createdAt / updatedAt and the like)."),