@ai0x0/utils 0.6.1 → 0.7.1

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/eslint-rules/api-route-via-nrf.js

@@ -0,0 +1,83 @@
+/**
+ * api-route-via-nrf
+ * -----------------
+ * API 路由一律走 next-rest-framework（route / routeOperation），不许裸导 HTTP 方法。
+ *
+ * 裸写 `export async function POST(req)` 的代价不是风格不统一，是这条端点从此不存在于
+ * openapi.json：生成器不会给它出 client，CLI / agent 读不到它，前端只能手写 fetch 直连
+ * （那是 no-direct-api-url 拦的另一头）。框架统一做的鉴权预热、错误翻译、响应校验，
+ * 它也都得自己记得补。
+ *
+ * 判的是「导出形状」，不是「有没有 import route」：
+ * 报：`export async function POST(...)`、`export const GET = handler`；
+ * 放：`export const { POST } = route({...})`（从 route() 解构，id 是 ObjectPattern）。
+ *
+ * 作用范围由调用方在 flat config 里用 files 圈定（比如只在 api 目录的 route.ts 上开）；
+ * 确有理由裸导的文件（第三方库的整体转发，如 better-auth 的 catch-all）用 files override
+ * 单独关掉，并在那个文件里写明理由。
+ */
+
+const HTTP_METHODS = new Set([
+  "GET",
+  "POST",
+  "PUT",
+  "DELETE",
+  "PATCH",
+  "HEAD",
+  "OPTIONS",
+]);
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "API 路由必须用 next-rest-framework 的 route()/routeOperation() 构建，禁止裸导 HTTP 方法。",
+    },
+    schema: [],
+    messages: {
+      rawMethodExport:
+        "API 路由不许裸导 HTTP 方法，改用 next-rest-framework 的 route()/routeOperation" +
+        "（export const { POST } = route({...})）。裸导的端点进不了 openapi.json，" +
+        "前端与 CLI 都拿不到它的 client。",
+    },
+  },
+  create(context) {
+    return {
+      ExportNamedDeclaration(node) {
+        const declaration = node.declaration;
+        if (!declaration) {
+          return;
+        }
+        if (
+          declaration.type === "FunctionDeclaration" &&
+          declaration.id &&
+          HTTP_METHODS.has(declaration.id.name)
+        ) {
+          context.report({
+            node: declaration.id,
+            messageId: "rawMethodExport",
+          });
+          return;
+        }
+        if (declaration.type === "VariableDeclaration") {
+          for (const declarator of declaration.declarations) {
+            // 从 route() 解构出来的是 ObjectPattern，那才叫走框架。
+            if (
+              declarator.id.type === "Identifier" &&
+              HTTP_METHODS.has(declarator.id.name)
+            ) {
+              context.report({
+                node: declarator.id,
+                messageId: "rawMethodExport",
+              });
+            }
+          }
+        }
+      },
+    };
+  },
+};
+
+export default rule;

package/eslint-rules/index.js

@@ -12,6 +12,8 @@ import noThen from "./no-then.js";
 import noOneLetterVars from "./no-one-letter-vars.js";
 import noConsecutiveSetState from "./no-consecutive-setstate.js";
 import maxLines from "./max-lines.js";
+import apiRouteViaNrf from "./api-route-via-nrf.js";
+import noDirectApiUrl from "./no-direct-api-url.js";
 
 const rules = {
   "require-section-divider": requireSectionDivider,
@@ -25,8 +27,17 @@ const rules = {
   "no-one-letter-vars": noOneLetterVars,
   "no-consecutive-setstate": noConsecutiveSetState,
   "max-lines": maxLines,
+  "api-route-via-nrf": apiRouteViaNrf,
+  "no-direct-api-url": noDirectApiUrl,
 };
 
+// 这两条只管「特定位置」的代码，不能跟着 recommended 全局开：
+//   · api-route-via-nrf 只该挂在 API 路由文件上（别的文件 export 一个叫 GET 的函数是自由的）；
+//   · no-direct-api-url 只该挂在前端目录上（后端与中间件里出现 "/api/..." 字面量是本分）。
+// 调用方在 flat config 里用 files 圈定范围自行开启，豁免文件用 files override 关掉，
+// 用法写在两条规则各自的文件头。
+const SCOPED_RULES = new Set(["api-route-via-nrf", "no-direct-api-url"]);
+
 const plugin = {
   rules,
   configs: {
@@ -34,7 +45,9 @@ const plugin = {
       plugins: { ai0x0: { rules } },
       rules: {
         ...Object.fromEntries(
-          Object.keys(rules).map((name) => [`ai0x0/${name}`, "error"]),
+          Object.keys(rules)
+            .filter((name) => !SCOPED_RULES.has(name))
+            .map((name) => [`ai0x0/${name}`, "error"]),
         ),
         curly: "error",
         "ai0x0/max-lines": [

package/eslint-rules/no-direct-api-url.js

@@ -0,0 +1,55 @@
+/**
+ * no-direct-api-url
+ * -----------------
+ * 前端不许手写 "/api/..." 地址直连后端，一律走生成的 client。
+ *
+ * 手写 `fetch("/api/xxx")` 绕掉的不是一层方便，是一整套集中处理（401 重登、错误提示、
+ * 作用域头、重复请求去重），而且 TypeScript 对它是瞎的 —— 路由改了形状，编译不红。
+ * 所以要调一个端点：先让它进 openapi.json（后端路由走 nrf，见 api-route-via-nrf），
+ * 重新生成 client，再调生成出来的方法。
+ *
+ * 判的是字符串字面量与模板串的开头：`/api/`。注释与 JSDoc 不是 AST 节点，天然不报。
+ * 作用范围由调用方在 flat config 里用 files 圈定（比如只挂前端目录），client 封装层
+ * 自己（生成文件与拦截器）用 files override 关掉 —— 地址本来就该只写在那儿。
+ */
+
+const API_PREFIX = "/api/";
+
+function startsWithApi(value) {
+  return typeof value === "string" && value.startsWith(API_PREFIX);
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        '前端禁止手写 "/api/..." 地址直连后端，必须走生成的 client。',
+    },
+    schema: [],
+    messages: {
+      directApiUrl:
+        '前端不许手写 "/api/..." 直连后端：走生成的 client。端点先进 openapi.json' +
+        "（后端路由走 nrf），重新生成 client 之后调生成出来的方法；401 重登、错误提示、" +
+        "作用域头都在那一层集中处理，手写 fetch 全部绕开。",
+    },
+  },
+  create(context) {
+    return {
+      Literal(node) {
+        if (startsWithApi(node.value)) {
+          context.report({ node, messageId: "directApiUrl" });
+        }
+      },
+      TemplateLiteral(node) {
+        // 只看第一段静态文本：`${base}/api/x` 的地址不归这条管（那是封装层的拼法）。
+        if (startsWithApi(node.quasis[0]?.value.cooked)) {
+          context.report({ node, messageId: "directApiUrl" });
+        }
+      },
+    };
+  },
+};
+
+export default rule;

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
 });