@ai0x0/utils 0.6.1 → 0.7.0

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

@@ -18,14 +18,16 @@ 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;
+            // 筛选面与可见面同源，理由见 backend/actions/create-get-list-action 里的同一段。
+            exposed = Object.keys(bodySchema.shape);
             fields = {};
-            for (_i = 0, _Object$keys = Object.keys(bodySchema.shape); _i < _Object$keys.length; _i++) {
-              key = _Object$keys[_i];
+            for (_i = 0, _exposed = exposed; _i < _exposed.length; _i++) {
+              key = _exposed[_i];
               field = table[key];
               if (field) {
                 fields[key] = field;
@@ -34,13 +36,14 @@ export function createGetAction(_ref) {
             _getListQuery = getListQuery({
               db: db,
               fields: fields,
+              filterable: exposed,
               jsonArrayFields: jsonArrayFields,
               params: params,
               scope: scope,
               relations: relations,
               table: table
             }), query = _getListQuery.query, countQuery = _getListQuery.countQuery;
-            _context.next = 6;
+            _context.next = 7;
             return getListData({
               bodySchema: bodySchema,
               countQuery: countQuery,
@@ -48,12 +51,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/sqlite/actions/create-get-list-action.js

@@ -15,15 +15,16 @@ 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);
+            _ref4 = params, current = _ref4.current, pageSize = _ref4.pageSize, other = _objectWithoutProperties(_ref4, _excluded); // 筛选面与可见面同源，理由见 backend/actions/create-get-list-action 里的同一段。
+            exposed = Object.keys(bodySchema.shape);
             fields = {};
-            for (_i = 0, _Object$keys = Object.keys(bodySchema.shape); _i < _Object$keys.length; _i++) {
-              key = _Object$keys[_i];
+            for (_i = 0, _exposed = exposed; _i < _exposed.length; _i++) {
+              key = _exposed[_i];
               field = table[key];
               if (field) {
                 fields[key] = field;
@@ -32,6 +33,7 @@ export function createGetListAction(_ref) {
             _getListQuery = getListQuery({
               db: db,
               fields: fields,
+              filterable: exposed,
               jsonArrayFields: jsonArrayFields,
               params: other,
               scope: scope,
@@ -45,7 +47,7 @@ export function createGetListAction(_ref) {
               pageSize: pageSize,
               query: query
             })());
-          case 6:
+          case 7:
           case "end":
             return _context.stop();
         }

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

@@ -1,5 +1,5 @@
 import { getListQuery } from "./get-list-query.js";
-export declare function getListData({ query, countQuery, pageSize, current, }: {
+export declare function getListData({ query, countQuery, pageSize: rawPageSize, current: rawCurrent, }: {
     bodySchema?: any;
     current?: number;
     pageSize?: number;

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

@@ -8,6 +8,7 @@ function _iterableToArrayLimit(r, l) { var t = null == r ? null : "undefined" !=
 function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
 function asyncGeneratorStep(gen, resolve, reject, _next, _throw, key, arg) { try { var info = gen[key](arg); var value = info.value; } catch (error) { reject(error); return; } if (info.done) { resolve(value); } else { Promise.resolve(value).then(_next, _throw); } }
 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 { normalizePaging } from "../../actions/paging.js";
 function runSelect(_x) {
   return _runSelect.apply(this, arguments);
 }
@@ -42,16 +43,21 @@ function _runSelect() {
 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;
+  // 归一化的理由见 backend/actions/paging。
+  var _normalizePaging = normalizePaging({
+      current: rawCurrent,
+      pageSize: rawPageSize
+    }),
+    current = _normalizePaging.current,
+    pageSize = _normalizePaging.pageSize;
   return /*#__PURE__*/_asyncToGenerator( /*#__PURE__*/_regeneratorRuntime().mark(function _callee() {
     var dataQuery, data, _yield$runSelect, _yield$runSelect2, count;
     return _regeneratorRuntime().wrap(function _callee$(_context) {
       while (1) switch (_context.prev = _context.next) {
         case 0:
-          dataQuery = query.limit(+pageSize).offset((+current - 1) * +pageSize);
+          dataQuery = query.limit(pageSize).offset((current - 1) * pageSize);
           _context.next = 3;
           return runSelect(dataQuery);
         case 3:

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

@@ -5,6 +5,8 @@ import { type ListQueryParams } from "../../actions/get-list-query-core.js";
 export declare function getListQuery<TTable extends BaseTable, TSelection extends SelectedFields>(args: {
     db: any;
     fields: TSelection;
+    /** 允许被当成筛选条件的键。不传等于不限制，见核心里的说明。 */
+    filterable?: readonly string[];
     jsonArrayFields?: string[];
     /** 必填。与 pg 那套同义，见 backend/scope.ts。 */
     scope: ScopeArg;

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

@@ -1,4 +1,4 @@
-var _templateObject;
+var _templateObject, _templateObject2;
 function _taggedTemplateLiteral(strings, raw) { if (!raw) { raw = strings.slice(0); } return Object.freeze(Object.defineProperties(strings, { raw: { value: Object.freeze(raw) } })); }
 // ==============================================================================
 // 列表查询（SQLite）
@@ -6,16 +6,20 @@ function _taggedTemplateLiteral(strings, raw) { if (!raw) { raw = strings.slice(
 // 实现在 backend/actions/get-list-query-core，与 pg 那套共用。这里只给它两条 sqlite 专属的
 // 原语：sqlite 的 like 本来就不区分大小写（没有 ilike），JSON 数组用 json_each 展开。
 
-import { like, sql } from "drizzle-orm";
+import { sql } from "drizzle-orm";
 import { createGetListQuery } from "../../actions/get-list-query-core.js";
+
+// pattern 由核心转义好再传进来（见 escapeLikePattern），但**转义符要自己声明**：sqlite 的 LIKE
+// 不带 ESCAPE 子句时一个转义符都没有，那样转义等于没做，`%` 照旧是通配符。这也是这里不能用
+// drizzle 的 like() 助手的原因 —— 它拼不出 ESCAPE。
 var run = createGetListQuery({
-  contains: function contains(column, keyword) {
-    return like(column, "%".concat(keyword, "%"));
+  contains: function contains(column, pattern) {
+    return sql(_templateObject || (_templateObject = _taggedTemplateLiteral(["", " LIKE ", " ESCAPE '\\'"], ["", " LIKE ", " ESCAPE '\\\\'"])), column, pattern);
   },
   // json_each 展开出来的行里，值在 tag.value 上（pg 那个 _text 变体是直接给字符串的）——
   // 这是两边唯一一处连字段名都不同的地方。
-  jsonArrayContains: function jsonArrayContains(column, keyword) {
-    return sql(_templateObject || (_templateObject = _taggedTemplateLiteral(["\n    EXISTS (\n      SELECT 1 FROM json_each(", ") tag\n      WHERE tag.value LIKE ", "\n    )\n  "])), column, "%".concat(keyword, "%"));
+  jsonArrayContains: function jsonArrayContains(column, pattern) {
+    return sql(_templateObject2 || (_templateObject2 = _taggedTemplateLiteral(["\n    EXISTS (\n      SELECT 1 FROM json_each(", ") tag\n      WHERE tag.value LIKE ", " ESCAPE '\\'\n    )\n  "], ["\n    EXISTS (\n      SELECT 1 FROM json_each(", ") tag\n      WHERE tag.value LIKE ", " ESCAPE '\\\\'\n    )\n  "])), column, pattern);
   }
 });
 export function getListQuery(args) {

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

@@ -32,8 +32,9 @@ function createGetAction({
   table
 }) {
   return async (params, { scope }) => {
+    const exposed = Object.keys(bodySchema.shape);
     const fields = {};
-    for (const key of Object.keys(bodySchema.shape)) {
+    for (const key of exposed) {
       const field = table[key];
       if (field) {
         fields[key] = field;
@@ -42,6 +43,7 @@ function createGetAction({
     const { query, countQuery } = (0, import_get_list_query.getListQuery)({
       db,
       fields,
+      filterable: exposed,
       jsonArrayFields,
       params,
       relations,

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

@@ -33,8 +33,9 @@ function createGetListAction({
 }) {
   return async (params, { scope }) => {
     const { current, pageSize, ...other } = params;
+    const exposed = Object.keys(bodySchema.shape);
     const fields = {};
-    for (const key of Object.keys(bodySchema.shape)) {
+    for (const key of exposed) {
       const field = table[key];
       if (field) {
         fields[key] = field;
@@ -43,6 +44,7 @@ function createGetListAction({
     const { query, countQuery } = (0, import_get_list_query.getListQuery)({
       db,
       fields,
+      filterable: exposed,
       jsonArrayFields,
       params: other,
       relations,

package/lib/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/lib/backend/actions/get-list-data.js

@@ -24,20 +24,25 @@ __export(get_list_data_exports, {
 module.exports = __toCommonJS(get_list_data_exports);
 var import_next_rest_framework = require("next-rest-framework");
 var import_schemas = require("../schemas");
+var import_paging = require("./paging");
 function getListData({
   query,
   countQuery,
-  pageSize = 10,
-  current = 1,
+  pageSize: rawPageSize,
+  current: rawCurrent,
   bodySchema
 }) {
+  const { current, pageSize } = (0, import_paging.normalizePaging)({
+    current: rawCurrent,
+    pageSize: rawPageSize
+  });
   return (0, import_next_rest_framework.rpcOperation)().outputs([
     {
       body: (0, import_schemas.listBodySchema)(bodySchema),
       contentType: "application/json"
     }
   ]).handler(async () => {
-    const data = await query.limit(+pageSize).offset((+current - 1) * +pageSize).execute();
+    const data = await query.limit(pageSize).offset((current - 1) * pageSize).execute();
     const [{ count }] = await countQuery.execute();
     return { data, total: Number(count) };
   });

package/lib/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/lib/backend/actions/get-list-query-core.js

@@ -19,18 +19,32 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/backend/actions/get-list-query-core.ts
 var get_list_query_core_exports = {};
 __export(get_list_query_core_exports, {
-  createGetListQuery: () => createGetListQuery
+  createGetListQuery: () => createGetListQuery,
+  escapeLikePattern: () => escapeLikePattern
 });
 module.exports = __toCommonJS(get_list_query_core_exports);
 var import_drizzle_orm = require("drizzle-orm");
+var import_errors = require("../errors");
 var import_scope = require("../scope");
+var import_paging = require("./paging");
+function escapeLikePattern(keyword) {
+  return `%${keyword.replace(/[\\%_]/g, (char) => `\\${char}`)}%`;
+}
 function columnAt(table, key) {
-  return table[key];
+  const value = table[key];
+  return (0, import_drizzle_orm.is)(value, import_drizzle_orm.Column) ? value : void 0;
+}
+function isIdKey(key) {
+  return key === "id" || key.endsWith("Id");
+}
+function isFuzzyMatchable(column) {
+  return column.dataType === "string" && !/uuid|enum/i.test(column.columnType);
 }
 function createGetListQuery(dialect) {
   return function getListQuery({
     db,
     fields,
+    filterable,
     jsonArrayFields,
     params,
     relations,
@@ -38,12 +52,18 @@ function createGetListQuery(dialect) {
     table
   }) {
     const {
-      page = 1,
-      pageSize = 10,
-      orderBy = "createdAt",
+      page,
+      pageSize: rawPageSize,
+      orderBy,
       orderDir = "desc",
       ...filters
     } = params;
+    const { current, pageSize } = (0, import_paging.normalizePaging)({
+      current: page,
+      pageSize: rawPageSize
+    });
+    const allowed = filterable ? new Set(filterable) : void 0;
+    const isFilterable = (key) => !allowed || allowed.has(key);
     function buildBaseQuery() {
       let queryFields = { ...fields };
       if (relations == null ? void 0 : relations.length) {
@@ -66,7 +86,7 @@ function createGetListQuery(dialect) {
       ).map((candidate) => columnAt(candidate, key)).find(Boolean);
     }
     function addCondition(conditions2, key, value, targetColumn) {
-      const isIdField = /id/i.test(key);
+      const isExact = isIdKey(key) || !isFuzzyMatchable(targetColumn);
       const isJsonArray = jsonArrayFields == null ? void 0 : jsonArrayFields.includes(key);
       if (typeof value !== "string") {
         conditions2.push((0, import_drizzle_orm.eq)(targetColumn, value));
@@ -78,24 +98,35 @@ function createGetListQuery(dialect) {
           return;
         }
         if (isJsonArray) {
-          conditions2.push(dialect.jsonArrayContains(targetColumn, values[0]));
-        } else if (isIdField) {
+          conditions2.push(
+            dialect.jsonArrayContains(
+              targetColumn,
+              escapeLikePattern(values[0])
+            )
+          );
+        } else if (isExact) {
           conditions2.push((0, import_drizzle_orm.inArray)(targetColumn, values));
         } else {
           conditions2.push(
             (0, import_drizzle_orm.or)(
-              ...values.map((item) => dialect.contains(targetColumn, item))
+              ...values.map(
+                (item) => dialect.contains(targetColumn, escapeLikePattern(item))
+              )
             )
           );
         }
         return;
       }
       if (isJsonArray) {
-        conditions2.push(dialect.jsonArrayContains(targetColumn, value));
-      } else if (isIdField) {
+        conditions2.push(
+          dialect.jsonArrayContains(targetColumn, escapeLikePattern(value))
+        );
+      } else if (isExact) {
         conditions2.push((0, import_drizzle_orm.eq)(targetColumn, value));
       } else {
-        conditions2.push(dialect.contains(targetColumn, value));
+        conditions2.push(
+          dialect.contains(targetColumn, escapeLikePattern(value))
+        );
       }
     }
     function buildConditions() {
@@ -105,16 +136,29 @@ function createGetListQuery(dialect) {
           continue;
         }
         if (key.endsWith("AtFrom") || key.endsWith("AtTo")) {
-          const baseFieldName = key.replace(/(AtFrom|AtTo)$/, "");
-          const targetColumn2 = findTargetColumn(`${baseFieldName}At`);
+          const baseFieldName = `${key.replace(/(AtFrom|AtTo)$/, "")}At`;
+          if (!isFilterable(baseFieldName)) {
+            continue;
+          }
+          const targetColumn2 = findTargetColumn(baseFieldName);
           if (!targetColumn2) {
             continue;
           }
+          const at = new Date(value);
+          if (Number.isNaN(at.getTime())) {
+            throw new import_errors.HttpError(
+              400,
+              `${key} 不是一个能识别的时间，请用 ISO 8601（如 2026-08-01T00:00:00Z）。`
+            );
+          }
           conditions2.push(
-            key.endsWith("AtFrom") ? (0, import_drizzle_orm.gte)(targetColumn2, new Date(value)) : (0, import_drizzle_orm.lte)(targetColumn2, new Date(value))
+            key.endsWith("AtFrom") ? (0, import_drizzle_orm.gte)(targetColumn2, at) : (0, import_drizzle_orm.lte)(targetColumn2, at)
           );
           continue;
         }
+        if (!isFilterable(key)) {
+          continue;
+        }
         const targetColumn = findTargetColumn(key);
         if (!targetColumn) {
           continue;
@@ -124,7 +168,17 @@ function createGetListQuery(dialect) {
       return conditions2;
     }
     function buildOrderBy() {
-      const orderColumn = columnAt(table, orderBy);
+      const requested = typeof orderBy === "string" && orderBy ? orderBy : void 0;
+      const orderKey = requested ?? "createdAt";
+      const orderColumn = columnAt(table, orderKey);
+      if (!orderColumn) {
+        if (requested) {
+          throw new import_errors.HttpError(400, `orderBy "${requested}" 不是这张表上的列。`);
+        }
+        throw new Error(
+          `默认排序列 createdAt 不在这张表上。给这张表的列表查询显式传一个 orderBy。`
+        );
+      }
       return orderDir === "asc" ? (0, import_drizzle_orm.asc)(orderColumn) : (0, import_drizzle_orm.desc)(orderColumn);
     }
     const baseQuery = buildBaseQuery();
@@ -132,7 +186,7 @@ function createGetListQuery(dialect) {
     const conditions = scopeSql ? [scopeSql] : [];
     conditions.push(...buildConditions());
     const where = conditions.length > 0 ? (0, import_drizzle_orm.and)(...conditions) : void 0;
-    const query = baseQuery.where(where).orderBy(buildOrderBy()).limit(pageSize).offset((page - 1) * pageSize);
+    const query = baseQuery.where(where).orderBy(buildOrderBy()).limit(pageSize).offset((current - 1) * pageSize);
     const countQuery = db.select({ count: import_drizzle_orm.sql`COUNT(DISTINCT ${table.id})` }).from(table).where(where);
     if (relations == null ? void 0 : relations.length) {
       for (const { table: relationTable, sql: joinSql } of relations) {
@@ -147,5 +201,6 @@ function createGetListQuery(dialect) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  createGetListQuery
+  createGetListQuery,
+  escapeLikePattern
 });

package/lib/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/lib/backend/actions/get-list-query.js

@@ -25,13 +25,13 @@ module.exports = __toCommonJS(get_list_query_exports);
 var import_drizzle_orm = require("drizzle-orm");
 var import_get_list_query_core = require("./get-list-query-core");
 var run = (0, import_get_list_query_core.createGetListQuery)({
-  contains: (column, keyword) => (0, import_drizzle_orm.ilike)(column, `%${keyword}%`),
+  contains: (column, pattern) => (0, import_drizzle_orm.ilike)(column, pattern),
   // jsonb 数组展开成行再逐个 LIKE。列存的是 text[] 形状的 jsonb（见 createTableSchema 的
   // jsonArrayFields），所以用 _text 那个变体，取到的 tag 直接就是字符串。
-  jsonArrayContains: (column, keyword) => import_drizzle_orm.sql`
+  jsonArrayContains: (column, pattern) => import_drizzle_orm.sql`
     EXISTS (
       SELECT 1 FROM jsonb_array_elements_text(${column}) tag
-      WHERE tag LIKE ${`%${keyword}%`}
+      WHERE tag LIKE ${pattern}
     )
   `
 });

package/lib/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/lib/backend/actions/index.js

@@ -19,12 +19,14 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/backend/actions/index.ts
 var actions_exports = {};
 __export(actions_exports, {
+  MAX_PAGE_SIZE: () => import_paging.MAX_PAGE_SIZE,
   createDeleteAction: () => import_create_delete_action.createDeleteAction,
   createGetAction: () => import_create_get_action.createGetAction,
   createGetListAction: () => import_create_get_list_action.createGetListAction,
   createPostAction: () => import_create_post_action.createPostAction,
   createPutAction: () => import_create_put_action.createPutAction,
-  getListQuery: () => import_get_list_query.getListQuery
+  getListQuery: () => import_get_list_query.getListQuery,
+  normalizePaging: () => import_paging.normalizePaging
 });
 module.exports = __toCommonJS(actions_exports);
 var import_create_delete_action = require("./create-delete-action");
@@ -33,12 +35,15 @@ var import_create_get_list_action = require("./create-get-list-action");
 var import_create_post_action = require("./create-post-action");
 var import_create_put_action = require("./create-put-action");
 var import_get_list_query = require("./get-list-query");
+var import_paging = require("./paging");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  MAX_PAGE_SIZE,
   createDeleteAction,
   createGetAction,
   createGetListAction,
   createPostAction,
   createPutAction,
-  getListQuery
+  getListQuery,
+  normalizePaging
 });

package/lib/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/lib/backend/actions/paging.js

@@ -0,0 +1,50 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/backend/actions/paging.ts
+var paging_exports = {};
+__export(paging_exports, {
+  DEFAULT_PAGE_SIZE: () => DEFAULT_PAGE_SIZE,
+  MAX_PAGE_SIZE: () => MAX_PAGE_SIZE,
+  normalizePaging: () => normalizePaging
+});
+module.exports = __toCommonJS(paging_exports);
+var MAX_PAGE_SIZE = 1e4;
+var DEFAULT_PAGE_SIZE = 10;
+function toPositiveInt(value, fallback) {
+  const parsed = Math.floor(Number(value));
+  return Number.isFinite(parsed) && parsed >= 1 ? parsed : fallback;
+}
+function normalizePaging({
+  current,
+  pageSize
+}) {
+  return {
+    current: toPositiveInt(current, 1),
+    pageSize: Math.min(
+      toPositiveInt(pageSize, DEFAULT_PAGE_SIZE),
+      MAX_PAGE_SIZE
+    )
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_PAGE_SIZE,
+  MAX_PAGE_SIZE,
+  normalizePaging
+});

package/lib/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/lib/backend/schemas/common.js

@@ -46,7 +46,7 @@ var BASIC_UPDATE_OMIT = {
 var queryListSchema = (schema) => import_zod.z.object({
   current: import_zod.z.string().optional().default("1").describe("Page number, starting at 1."),
   pageSize: import_zod.z.string().optional().default("10").describe(
-    "Rows per page. Omitting it yields only 10 — pass a larger value to get the whole set."
+    "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: import_zod.z.string().optional().describe(
     "Keep only rows created at or after this instant (ISO 8601, e.g. 2026-08-01T00:00:00Z)."