@ai0x0/utils 0.6.0 → 0.7.0

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/create-put-action.d.ts

@@ -6,6 +6,6 @@ export declare function createPutAction<T extends ZodSchema, TTable extends Base
     bodySchema: T;
     db: NodePgDatabase<Record<string, unknown>>;
     table: TTable;
-}): (body: Partial<z.infer<T>> & Record<string, unknown>, { scope }: {
+}): (body: Partial<z.infer<T>> & Record<string, unknown>, options: {
     scope: ScopeArg;
 }) => Promise<z.infer<T>>;

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

@@ -22,26 +22,13 @@ __export(create_put_action_exports, {
   createPutAction: () => createPutAction
 });
 module.exports = __toCommonJS(create_put_action_exports);
-var import_transform_body = require("./transform-body");
-var import_drizzle_orm = require("drizzle-orm");
-var import_scope = require("../scope");
-var import_errors = require("../errors");
+var import_write_action_core = require("./write-action-core");
 function createPutAction({
   db,
   table
 }) {
-  return async (body, { scope }) => {
-    const id = body.id;
-    if (!id) {
-      throw new import_errors.HttpError(400, "缺少 id");
-    }
-    const guard = (0, import_scope.scopeCondition)(table, scope);
-    const [data] = await db.update(table).set((0, import_transform_body.transformBody)(body)).where(guard ? (0, import_drizzle_orm.and)((0, import_drizzle_orm.eq)(table.id, id), guard) : (0, import_drizzle_orm.eq)(table.id, id)).returning();
-    if (!data && scope !== import_scope.NO_SCOPE) {
-      throw new import_errors.HttpError(404, "未找到编辑对象，或没有权限");
-    }
-    return data;
-  };
+  const run = (0, import_write_action_core.createPutActionCore)({ db, table });
+  return async (body, options) => await run(body, options);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

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

@@ -0,0 +1,67 @@
+import { Column, SQL } from "drizzle-orm";
+import { ScopeArg } from "../scope.js";
+/**
+ * 核心用得到表的哪一部分：只有 `id`（计数与分组要它）和「按列名取列」。
+ * 两棵树的 BaseTable 都满足它，而 dialect 各自的 Table 类型不必进来。
+ */
+export interface ListQueryTable {
+    id: Column;
+}
+export interface ListQueryRelation {
+    groupBy?: boolean;
+    select?: Record<string, unknown>;
+    sql?: SQL;
+    table?: ListQueryTable;
+}
+/** 两套方言之间**全部**的差异。加第三种数据库时要写的也只有这两条。 */
+export interface ListQueryDialect {
+    /**
+     * 大小写不敏感的「包含」。收到的 pattern 是**已经转义、已经带好 `%` 的完整模式串** ——
+     * 转义收在核心里做（见 escapeLikePattern），免得加第三种方言时漏掉那一步：漏掉不会报错，
+     * 只会让 `%` 重新变回通配符。
+     */
+    contains(_column: Column, _pattern: string): SQL;
+    /** 「这个 JSON 数组列里有没有元素匹配这个模式」。pattern 同上，已转义。 */
+    jsonArrayContains(_column: Column, _pattern: string): SQL;
+}
+export interface ListQueryParams {
+    [field: string]: unknown;
+    orderBy?: string;
+    orderDir?: "asc" | "desc";
+    page?: number;
+    pageSize?: number;
+}
+/**
+ * 把用户输入变成 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 —— 写成可选的话，漏传就退化成查全表，
+     * 而那是静默的越权（见 scope.ts）。它不走下面 params 那条筛选通道，因为那条的规矩是
+     * 「空值跳过」，一个取不到值的作用域会让整条 where 消失。
+     */
+    scope: ScopeArg;
+    params: ListQueryParams;
+    relations?: ListQueryRelation[] | undefined;
+    table: TTable;
+}) => {
+    countQuery: any;
+    query: any;
+};

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

@@ -0,0 +1,206 @@
+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, desc2) => {
+  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: !(desc2 = __getOwnPropDesc(from, key)) || desc2.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/backend/actions/get-list-query-core.ts
+var get_list_query_core_exports = {};
+__export(get_list_query_core_exports, {
+  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) {
+  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,
+    scope,
+    table
+  }) {
+    const {
+      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) {
+        for (const { select } of relations) {
+          queryFields = { ...queryFields, ...select };
+        }
+      }
+      const query2 = db.select(queryFields).from(table);
+      if (relations == null ? void 0 : relations.length) {
+        query2.groupBy(
+          table.id,
+          ...relations.filter(({ groupBy }) => groupBy).filter(({ table: joined }) => joined).map(({ table: joined }) => joined.id)
+        );
+      }
+      return query2;
+    }
+    function findTargetColumn(key) {
+      return [table].concat(
+        (relations == null ? void 0 : relations.filter(({ table: joined }) => joined).map(({ table: joined }) => joined)) || []
+      ).map((candidate) => columnAt(candidate, key)).find(Boolean);
+    }
+    function addCondition(conditions2, key, value, targetColumn) {
+      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));
+        return;
+      }
+      if (value.includes(",")) {
+        const values = value.split(",").map((item) => item.trim()).filter(Boolean);
+        if (!values.length) {
+          return;
+        }
+        if (isJsonArray) {
+          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, escapeLikePattern(item))
+              )
+            )
+          );
+        }
+        return;
+      }
+      if (isJsonArray) {
+        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, escapeLikePattern(value))
+        );
+      }
+    }
+    function buildConditions() {
+      const conditions2 = [];
+      for (const [key, value] of Object.entries(filters)) {
+        if (!value) {
+          continue;
+        }
+        if (key.endsWith("AtFrom") || key.endsWith("AtTo")) {
+          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, at) : (0, import_drizzle_orm.lte)(targetColumn2, at)
+          );
+          continue;
+        }
+        if (!isFilterable(key)) {
+          continue;
+        }
+        const targetColumn = findTargetColumn(key);
+        if (!targetColumn) {
+          continue;
+        }
+        addCondition(conditions2, key, value, targetColumn);
+      }
+      return conditions2;
+    }
+    function buildOrderBy() {
+      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();
+    const scopeSql = (0, import_scope.scopeCondition)(table, scope);
+    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((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) {
+        if (relationTable) {
+          query.leftJoin(relationTable, joinSql);
+          countQuery.leftJoin(relationTable, joinSql);
+        }
+      }
+    }
+    return { countQuery, query };
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createGetListQuery,
+  escapeLikePattern
+});

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

@@ -1,34 +1,23 @@
 import { BaseTable, GetListRelations } from "../types.js";
 import { SelectedFields } from "drizzle-orm/pg-core/query-builders/select.types";
-import { SQL } from "drizzle-orm";
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
 import { ScopeArg } from "../scope.js";
-export declare function getListQuery<TTable extends BaseTable, TSelection extends SelectedFields>({ db, fields, jsonArrayFields, params, relations, scope, table, }: {
+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 —— 写成可选的话，漏传就退化成查全表，
-     * 而那是静默的越权（见 scope.ts）。它不走下面 params 那条筛选通道，因为那条的规矩是
-     * 「空值跳过」，一个取不到值的作用域会让整条 where 消失。
+     * 而那是静默的越权（见 scope.ts）。
      */
     scope: ScopeArg;
-    params: {
-        [field: string]: unknown;
-        orderBy?: keyof BaseTable;
-        orderDir?: "asc" | "desc";
-        page?: number;
-        pageSize?: number;
-    };
+    params: ListQueryParams;
     relations?: GetListRelations;
     table: TTable;
 }): {
-    countQuery: Omit<import("drizzle-orm/pg-core").PgSelectBase<string, {
-        count: SQL<unknown>;
-    }, "partial", Record<string, "not-null">, false, "where", {
-        count: unknown;
-    }[], {
-        count: import("drizzle-orm").DrizzleTypeError<"You cannot reference this field without assigning it an alias first - use `.as(<alias>)`">;
-    }>, "where">;
+    countQuery: any;
     query: any;
 };

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

@@ -6,11 +6,11 @@ var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
 };
-var __copyProps = (to, from, except, desc2) => {
+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: !(desc2 = __getOwnPropDesc(from, key)) || desc2.enumerable });
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
   }
   return to;
 };
@@ -23,145 +23,20 @@ __export(get_list_query_exports, {
 });
 module.exports = __toCommonJS(get_list_query_exports);
 var import_drizzle_orm = require("drizzle-orm");
-var import_scope = require("../scope");
-function getListQuery({
-  db,
-  fields,
-  jsonArrayFields,
-  params,
-  relations,
-  scope,
-  table
-}) {
-  const {
-    page = 1,
-    pageSize = 10,
-    orderBy = "createdAt",
-    orderDir = "desc",
-    ...filters
-  } = params;
-  function buildBaseQuery(table2, fields2, relations2) {
-    let queryFields = { ...fields2 };
-    if (relations2 == null ? void 0 : relations2.length) {
-      for (const { select } of relations2) {
-        queryFields = { ...queryFields, ...select };
-      }
-    }
-    const query2 = db.select(queryFields).from(table2);
-    if (relations2 == null ? void 0 : relations2.length) {
-      query2.groupBy(
-        table2.id,
-        ...relations2.filter(({ groupBy }) => groupBy).filter(({ table: table3 }) => table3).map(({ table: table3 }) => table3.id)
-      );
-    }
-    return query2;
-  }
-  function findTargetColumn(key, table2, relations2) {
-    var _a;
-    return (_a = [table2].concat(
-      (relations2 == null ? void 0 : relations2.filter(({ table: table3 }) => table3).map(({ table: table3 }) => table3)) || []
-    ).find((table3) => table3[key])) == null ? void 0 : _a[key];
-  }
-  function addCondition(conditions2, key, value, targetColumn) {
-    const isIdField = /id/i.test(key);
-    const isJsonArray = jsonArrayFields == null ? void 0 : jsonArrayFields.includes(key);
-    if (typeof value === "string") {
-      if (value.includes(",")) {
-        const values = value.split(",").map((val) => val.trim()).filter(Boolean);
-        if (values.length > 0) {
-          if (isJsonArray) {
-            conditions2.push(
-              import_drizzle_orm.sql`
-                EXISTS (
-                  SELECT 1 FROM jsonb_array_elements_text(${targetColumn}) tag
-                  WHERE tag LIKE ${`%${values[0]}%`}
-                )
-              `
-            );
-          } else if (isIdField) {
-            conditions2.push((0, import_drizzle_orm.inArray)(targetColumn, values));
-          } else {
-            conditions2.push(
-              (0, import_drizzle_orm.or)(
-                ...values.map((val) => (0, import_drizzle_orm.ilike)(targetColumn, `%${val}%`))
-              )
-            );
-          }
-        }
-      } else {
-        if (isJsonArray) {
-          conditions2.push(
-            import_drizzle_orm.sql`
-              EXISTS (
-                SELECT 1 FROM jsonb_array_elements_text(${targetColumn}) tag
-                WHERE tag LIKE ${`%${value}%`}
-              )
-            `
-          );
-        } else if (isIdField) {
-          conditions2.push((0, import_drizzle_orm.eq)(targetColumn, value));
-        } else {
-          conditions2.push((0, import_drizzle_orm.ilike)(targetColumn, `%${value}%`));
-        }
-      }
-    } else {
-      conditions2.push((0, import_drizzle_orm.eq)(targetColumn, value));
-    }
-  }
-  function buildConditions(filters2, table2, relations2) {
-    const conditions2 = [];
-    for (const [key, value] of Object.entries(filters2)) {
-      if (!value) {
-        continue;
-      }
-      if (key.endsWith("AtFrom") || key.endsWith("AtTo")) {
-        const baseFieldName = key.replace(/(AtFrom|AtTo)$/, "");
-        const targetColumn2 = findTargetColumn(
-          `${baseFieldName}At`,
-          table2,
-          relations2
-        );
-        if (!targetColumn2) {
-          continue;
-        }
-        if (key.endsWith("AtFrom")) {
-          conditions2.push((0, import_drizzle_orm.gte)(targetColumn2, new Date(value)));
-        } else if (key.endsWith("AtTo")) {
-          conditions2.push((0, import_drizzle_orm.lte)(targetColumn2, new Date(value)));
-        }
-        continue;
-      }
-      const targetColumn = findTargetColumn(
-        key,
-        table2,
-        relations2
-      );
-      if (!targetColumn) {
-        continue;
-      }
-      addCondition(conditions2, key, value, targetColumn);
-    }
-    return conditions2;
-  }
-  function buildOrderBy(table2, orderBy2, orderDir2) {
-    const orderColumn = table2[orderBy2];
-    return orderDir2 === "asc" ? (0, import_drizzle_orm.asc)(orderColumn) : (0, import_drizzle_orm.desc)(orderColumn);
-  }
-  const baseQuery = buildBaseQuery(table, fields, relations);
-  const scopeSql = (0, import_scope.scopeCondition)(table, scope);
-  const conditions = scopeSql ? [scopeSql] : [];
-  conditions.push(...buildConditions(filters, table, relations));
-  const query = baseQuery.where(conditions.length > 0 ? (0, import_drizzle_orm.and)(...conditions) : void 0).orderBy(buildOrderBy(table, orderBy, orderDir)).limit(pageSize).offset((page - 1) * pageSize);
-  const countQuery = db.select({ count: import_drizzle_orm.sql`COUNT(DISTINCT ${table.id})` }).from(table).where(conditions.length > 0 ? (0, import_drizzle_orm.and)(...conditions) : void 0);
-  if (relations == null ? void 0 : relations.length) {
-    for (const { table: relationTable, sql: joinSql } of relations) {
-      if (relationTable) {
-        query.leftJoin(relationTable, joinSql);
-        countQuery.leftJoin(relationTable, joinSql);
-      }
-    }
-  }
-  return { countQuery, query };
+var import_get_list_query_core = require("./get-list-query-core");
+var run = (0, import_get_list_query_core.createGetListQuery)({
+  contains: (column, pattern) => (0, import_drizzle_orm.ilike)(column, pattern),
+  // jsonb 数组展开成行再逐个 LIKE。列存的是 text[] 形状的 jsonb（见 createTableSchema 的
+  // jsonArrayFields），所以用 _text 那个变体，取到的 tag 直接就是字符串。
+  jsonArrayContains: (column, pattern) => import_drizzle_orm.sql`
+    EXISTS (
+      SELECT 1 FROM jsonb_array_elements_text(${column}) tag
+      WHERE tag LIKE ${pattern}
+    )
+  `
+});
+function getListQuery(args) {
+  return run(args);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

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