@ai0x0/utils 0.5.0 → 0.6.1

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, keyword) => (0, import_drizzle_orm.ilike)(column, `%${keyword}%`),
+  // jsonb 数组展开成行再逐个 LIKE。列存的是 text[] 形状的 jsonb（见 createTableSchema 的
+  // jsonArrayFields），所以用 _text 那个变体，取到的 tag 直接就是字符串。
+  jsonArrayContains: (column, keyword) => import_drizzle_orm.sql`
+    EXISTS (
+      SELECT 1 FROM jsonb_array_elements_text(${column}) tag
+      WHERE tag LIKE ${`%${keyword}%`}
+    )
+  `
+});
+function getListQuery(args) {
+  return run(args);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/lib/backend/actions/write-action-core.d.ts

@@ -0,0 +1,18 @@
+import { ScopeArg } from "../scope.js";
+/** 核心用得到表的哪一部分：只有 id。dialect 各自的 Table 类型不进来。 */
+export interface WriteActionTable {
+    id: unknown;
+}
+interface WriteActionDeps<TTable extends WriteActionTable> {
+    db: any;
+    table: TTable;
+}
+export declare function createPutActionCore<TTable extends WriteActionTable>({ db, table, }: WriteActionDeps<TTable>): (body: Record<string, unknown>, { scope }: {
+    scope: ScopeArg;
+}) => Promise<unknown>;
+export declare function createDeleteActionCore<TTable extends WriteActionTable>({ db, table, }: WriteActionDeps<TTable>): ({ id }: {
+    id: string;
+}, { scope }: {
+    scope: ScopeArg;
+}) => Promise<any>;
+export {};

package/lib/backend/actions/write-action-core.js

@@ -0,0 +1,70 @@
+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/write-action-core.ts
+var write_action_core_exports = {};
+__export(write_action_core_exports, {
+  createDeleteActionCore: () => createDeleteActionCore,
+  createPutActionCore: () => createPutActionCore
+});
+module.exports = __toCommonJS(write_action_core_exports);
+var import_drizzle_orm = require("drizzle-orm");
+var import_scope = require("../scope");
+var import_errors = require("../errors");
+var import_transform_body = require("./transform-body");
+function byId(table, id, scope) {
+  const guard = (0, import_scope.scopeCondition)(table, scope);
+  const same = (0, import_drizzle_orm.eq)(table.id, id);
+  return guard ? (0, import_drizzle_orm.and)(same, guard) : same;
+}
+function createPutActionCore({
+  db,
+  table
+}) {
+  return async (body, { scope }) => {
+    const id = body.id;
+    if (!id) {
+      throw new import_errors.HttpError(400, "缺少 id");
+    }
+    const [data] = await db.update(table).set((0, import_transform_body.transformBody)(body)).where(byId(table, id, scope)).returning();
+    if (!data && scope !== import_scope.NO_SCOPE) {
+      throw new import_errors.HttpError(404, "未找到编辑对象，或没有权限");
+    }
+    return data;
+  };
+}
+function createDeleteActionCore({
+  db,
+  table
+}) {
+  return async ({ id }, { scope }) => {
+    if (!id) {
+      throw new import_errors.HttpError(400, "缺少 id");
+    }
+    const rows = await db.delete(table).where(byId(table, id, scope)).returning();
+    if (rows.length === 0 && scope !== import_scope.NO_SCOPE) {
+      throw new import_errors.HttpError(404, "未找到删除对象，或没有权限");
+    }
+    return rows;
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createDeleteActionCore,
+  createPutActionCore
+});

package/lib/backend/route-operation/operation-common.d.ts

@@ -8,6 +8,18 @@ export type RouteCatch = (error: Error) => Promise<JsonResponse | undefined>;
 export interface DefaultSession {
     userId?: string;
 }
+/**
+ * 「这次请求是谁发的」。四个方法都会把它盖进 params.callerId，自定义 handler 判权、署名、
+ * 判「是不是本人」一律读它。
+ *
+ * **不要拿 params.creatorId 当调用者用。** 那是另一件事：POST 上的 creatorId 是**归属戳**
+ * （access.scope 指的那一列，换成 ownerId 时它就不叫 creatorId 了），PUT 上的 editorId 是要
+ * 写进行里的**审计列**。两者都恰好等于调用者只是默认配置下的巧合。
+ *
+ * 会话形状是泛型的（调用方可以塞自己的 Scope 进来），所以这里按 DefaultSession 取 userId ——
+ * 自定义会话只要带着这个字段就通用。
+ */
+export declare function callerIdOf(session: unknown): string | undefined;
 /**
  * 会话读取器。泛型化是为了让调用方能在这里一次性解析出「你是谁 + 你现在站在哪个空间 +
  * 你在那个空间里是什么角色」，后面 access.scope / access.can 都读同一份，不必各自再查一遍库。
@@ -99,7 +111,7 @@ export declare function getDefaultTags<TTable>({ getTableName, table, }: {
     table?: TTable;
 }): string[];
 export type GetOperationParams<Q extends ZodSchema> = z.infer<Q> & Record<string, unknown> & {
-    creatorId?: string;
+    callerId?: string;
 };
 /**
  * 读操作的参数与作用域。

package/lib/backend/route-operation/operation-common.js

@@ -19,6 +19,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/backend/route-operation/operation-common.ts
 var operation_common_exports = {};
 __export(operation_common_exports, {
+  callerIdOf: () => callerIdOf,
   getDefaultTags: () => getDefaultTags,
   getReadParams: () => getReadParams,
   handleOperationError: () => handleOperationError,
@@ -30,6 +31,9 @@ module.exports = __toCommonJS(operation_common_exports);
 var import_next_rest_framework = require("next-rest-framework");
 var import_errors = require("../errors");
 var import_scope = require("../scope");
+function callerIdOf(session) {
+  return session == null ? void 0 : session.userId;
+}
 var DEFAULT_SCOPE_COLUMN = "creatorId";
 function sessionLoader(getSession, req) {
   let pending;
@@ -124,6 +128,9 @@ async function getReadParams({
     Object.fromEntries(new URL(req.url).searchParams)
   );
   return {
+    // 这一份**不带 callerId**：它会被当成筛选条件送进查询构造器，而 callerId 不是任何表的列。
+    // 列表那边认不出的键会跳过（get-list-query 的 `if (!targetColumn) continue`），但别指望
+    // 这条兜底 —— 交给 handler 的那一份在 read-operation-core 里单独拼，见那里。
     params: { ...queryParams, ...extraParams },
     scope,
     session
@@ -131,6 +138,7 @@ async function getReadParams({
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  callerIdOf,
   getDefaultTags,
   getReadParams,
   handleOperationError,

package/lib/backend/route-operation/read-operation-core.js

@@ -60,7 +60,11 @@ function createGetOperationFactory({
     }
   ]).handler(async (req) => {
     try {
-      const { params: mergedParams, scope } = await (0, import_operation_common.getReadParams)({
+      const {
+        params: mergedParams,
+        scope,
+        session
+      } = await (0, import_operation_common.getReadParams)({
         access,
         getSession,
         req,
@@ -78,7 +82,8 @@ function createGetOperationFactory({
       if (handler) {
         result = await handler({
           data: result,
-          params: mergedParams,
+          // callerId 只给 handler，不进上面那份筛选/写入用的 params（见 getReadParams）。
+          params: { ...mergedParams, callerId: (0, import_operation_common.callerIdOf)(session) },
           req
         });
       }
@@ -121,7 +126,11 @@ function createGetListOperationFactory({
     }
   ]).handler(async (req) => {
     try {
-      const { params: mergedParams, scope } = await (0, import_operation_common.getReadParams)({
+      const {
+        params: mergedParams,
+        scope,
+        session
+      } = await (0, import_operation_common.getReadParams)({
         access,
         getSession,
         req,
@@ -138,7 +147,8 @@ function createGetListOperationFactory({
       if (handler) {
         result = await handler({
           data: result,
-          params: mergedParams,
+          // callerId 只给 handler，不进上面那份筛选/写入用的 params（见 getReadParams）。
+          params: { ...mergedParams, callerId: (0, import_operation_common.callerIdOf)(session) },
           req
         });
       }

package/lib/backend/route-operation/write-operation-core.d.ts

@@ -5,6 +5,7 @@ import { type RouteOpenApiOperation } from "./open-api-operation.js";
 import { AccessOptions, ActionFactory, DefaultSession, RouteCatch, SessionGetter } from "./operation-common.js";
 import { ScopeArg } from "../scope.js";
 export type PostOperationParams<IB extends ZodSchema> = z.infer<IB> & Record<string, unknown> & {
+    callerId?: string;
     creatorId?: string;
 };
 export interface PostOperationOptions<IB extends ZodSchema, OB extends ZodSchema, TTable, TSession = DefaultSession> {
@@ -37,6 +38,7 @@ export declare function createPostOperationFactory<TTable>({ createAction, getTa
     getSession: SessionGetter<TSession>;
 }) => <IB extends z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, OB extends z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>({ schemas, access, contentType, openApiOperation, parseBody, setBody, table, handler, catch: catchHandler, }: PostOperationOptions<IB, OB, TTable, TSession>) => import("next-rest-framework").RouteOperationDefinition<"POST">;
 export type PutOperationParams<IB extends ZodSchema> = z.infer<IB> & Record<string, unknown> & {
+    callerId?: string;
     editorId?: string;
 };
 export interface PutOperationOptions<IB extends ZodSchema, OB extends ZodSchema, TTable, TSession = DefaultSession> {
@@ -65,7 +67,7 @@ export declare function createPutOperationFactory<TTable>({ createAction, getTab
     getSession: SessionGetter<TSession>;
 }) => <IB extends z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, OB extends z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>({ schemas, access, openApiOperation, table, setBody, handler, catch: catchHandler, }: PutOperationOptions<IB, OB, TTable, TSession>) => import("next-rest-framework").RouteOperationDefinition<"PUT">;
 export type DeleteOperationParams<B extends ZodSchema> = z.infer<B> & Record<string, unknown> & {
-    creatorId?: string;
+    callerId?: string;
     id: string;
 };
 export interface DeleteOperationOptions<TTable, B extends ZodSchema, TSession = DefaultSession> {

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

@@ -85,7 +85,12 @@ function createPostOperationFactory({
       })(params))[0] : params;
       const data = handler ? await handler({
         data: raw,
-        params,
+        // callerId 只加在**交给 handler 的那一份**上，不进上面 createAction 收到的
+        // params —— 那一份会被原样 insert，而 callerId 不是任何表的列。
+        params: {
+          ...params,
+          callerId: (0, import_operation_common.callerIdOf)(session)
+        },
         req
       }) : raw;
       return import_next_rest_framework.TypedNextResponse.json(data, { status: 200 });
@@ -146,7 +151,12 @@ function createPutOperationFactory({
       })(params, { scope }) : params;
       const data = handler ? await handler({
         data: raw,
-        params,
+        // 同 POST：callerId 不进 createAction 那一份（它会被 .set() 原样写进 UPDATE，
+        // 而 callerId 不是列）。editorId 是列，所以它留在 params 里。
+        params: {
+          ...params,
+          callerId: editorId
+        },
         req
       }) : raw;
       return import_next_rest_framework.TypedNextResponse.json(data, { status: 200 });
@@ -187,13 +197,23 @@ function createDeleteOperationFactory({
       const body = bodySchema.parse(
         await req.json()
       );
+      const loadSession = (0, import_operation_common.sessionLoader)(getSession, req);
       const { scope } = await (0, import_operation_common.resolveAccess)({
         access,
-        loadSession: (0, import_operation_common.sessionLoader)(getSession, req),
+        loadSession,
         method: "DELETE"
       });
       const data = table && db ? await createAction({ db, table })({ id: body.id }, { scope }) : body;
-      await (handler == null ? void 0 : handler({ data, params: body, req }));
+      if (handler) {
+        await handler({
+          data,
+          params: {
+            ...body,
+            callerId: (0, import_operation_common.callerIdOf)(await loadSession())
+          },
+          req
+        });
+      }
       return import_next_rest_framework.TypedNextResponse.json(data, { status: 200 });
     } catch (error) {
       return (0, import_operation_common.handleOperationError)(error, catchHandler);

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

@@ -0,0 +1,112 @@
+import { z } from "zod";
+/**
+ * 业务侧 insert schema 需要从 drizzle-zod 生成的 schema 中排除的基础字段。
+ * 这些字段由后端在 createPostAction 中自动写入。
+ *
+ * 使用方式（在业务 schema 中）：
+ *   const insertFooSchema = createInsertSchema(foos)
+ *     .omit(BASIC_INSERT_OMIT)
+ *     .extend({ ... });
+ *
+ * 说明：上游导出为 const 而不是 helper function，是为了避免经过泛型
+ * wrapper 后 TS 把 drizzle-zod 推导出的深层条件 Shape 归约成 Omit，
+ * 从而在下游 `.extend(...)` 时丢失原有字段类型。
+ */
+export declare const BASIC_INSERT_OMIT: {
+    readonly id: true;
+    readonly creatorId: true;
+    readonly editorId: true;
+    readonly accessedAt: true;
+    readonly createdAt: true;
+    readonly updatedAt: true;
+};
+/**
+ * 业务侧 update schema 需要从 drizzle-zod 生成的 schema 中排除的基础字段。
+ * update 保留 id（随后用 `.required({ id: true })` 变成必填），其余由
+ * 后端 createPutAction 自动维护。
+ */
+export declare const BASIC_UPDATE_OMIT: {
+    readonly creatorId: true;
+    readonly editorId: true;
+    readonly accessedAt: true;
+    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 ? {
+    current: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    pageSize: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    createdAtFrom: z.ZodOptional<z.ZodString>;
+    createdAtTo: z.ZodOptional<z.ZodString>;
+    orderBy: z.ZodOptional<z.ZodString>;
+    creatorId: z.ZodOptional<z.ZodString>;
+    orderDir: z.ZodOptional<z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
+} & Incoming["shape"] : ({
+    current: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    pageSize: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    createdAtFrom: z.ZodOptional<z.ZodString>;
+    createdAtTo: z.ZodOptional<z.ZodString>;
+    orderBy: z.ZodOptional<z.ZodString>;
+    creatorId: z.ZodOptional<z.ZodString>;
+    orderDir: z.ZodOptional<z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
+} extends infer T_1 extends z.core.util.SomeObject ? { [K in keyof T_1 as K extends keyof Incoming["shape"] ? never : K]: {
+    current: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    pageSize: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    createdAtFrom: z.ZodOptional<z.ZodString>;
+    createdAtTo: z.ZodOptional<z.ZodString>;
+    orderBy: z.ZodOptional<z.ZodString>;
+    creatorId: z.ZodOptional<z.ZodString>;
+    orderDir: z.ZodOptional<z.ZodEnum<{
+        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 ? {
+    current: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    pageSize: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    createdAtFrom: z.ZodOptional<z.ZodString>;
+    createdAtTo: z.ZodOptional<z.ZodString>;
+    orderBy: z.ZodOptional<z.ZodString>;
+    creatorId: z.ZodOptional<z.ZodString>;
+    orderDir: z.ZodOptional<z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
+} & Incoming["shape"] : ({
+    current: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    pageSize: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    createdAtFrom: z.ZodOptional<z.ZodString>;
+    createdAtTo: z.ZodOptional<z.ZodString>;
+    orderBy: z.ZodOptional<z.ZodString>;
+    creatorId: z.ZodOptional<z.ZodString>;
+    orderDir: z.ZodOptional<z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
+} extends infer T_1 extends z.core.util.SomeObject ? { [K in keyof T_1 as K extends keyof Incoming["shape"] ? never : K]: {
+    current: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    pageSize: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    createdAtFrom: z.ZodOptional<z.ZodString>;
+    createdAtTo: z.ZodOptional<z.ZodString>;
+    orderBy: z.ZodOptional<z.ZodString>;
+    creatorId: z.ZodOptional<z.ZodString>;
+    orderDir: z.ZodOptional<z.ZodEnum<{
+        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))[k]; } : never, Incoming["_zod"]["config"]>;
+export declare const listBodySchema: <T extends z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>(schema: T) => z.ZodObject<{
+    total: z.ZodNumber;
+    data: z.ZodArray<T>;
+}, z.core.$strip>;
+/**
+ * 给 schema 上已有的字段挂说明。字段不在这个 schema 里就跳过 —— 同一张表的
+ * insert / update / select 三份含的列不一样（basicFields 只在 select 里），一份说明表要能同时
+ * 喂给三者，就不能对「字段一定存在」有要求。**不给不存在的字段凭空造一个。**
+ */
+export declare const describeFields: <T extends z.ZodObject<z.core.$ZodLooseShape, z.core.$strip>>(schema: T, notes: Record<string, string>) => T;
+export declare const describeBasicFields: <T extends z.ZodObject<z.core.$ZodLooseShape, z.core.$strip>>(schema: T) => T;

package/lib/backend/schemas/common.js

@@ -0,0 +1,112 @@
+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/schemas/common.ts
+var common_exports = {};
+__export(common_exports, {
+  BASIC_INSERT_OMIT: () => BASIC_INSERT_OMIT,
+  BASIC_UPDATE_OMIT: () => BASIC_UPDATE_OMIT,
+  describeBasicFields: () => describeBasicFields,
+  describeFields: () => describeFields,
+  listBodySchema: () => listBodySchema,
+  queryListSchema: () => queryListSchema
+});
+module.exports = __toCommonJS(common_exports);
+var import_zod = require("zod");
+var BASIC_INSERT_OMIT = {
+  id: true,
+  creatorId: true,
+  editorId: true,
+  accessedAt: true,
+  createdAt: true,
+  updatedAt: true
+};
+var BASIC_UPDATE_OMIT = {
+  creatorId: true,
+  editorId: true,
+  accessedAt: true,
+  createdAt: true,
+  updatedAt: true
+};
+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."
+  ),
+  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)."
+  ),
+  createdAtTo: import_zod.z.string().optional().describe("Keep only rows created at or before this instant."),
+  orderBy: import_zod.z.string().optional().describe(
+    "Column to sort by — a column name of this resource (createdAt / updatedAt and the like)."
+  ),
+  creatorId: import_zod.z.string().optional().describe(
+    "Keep only rows created by this user. Useful in shared spaces to filter down to one member."
+  ),
+  orderDir: import_zod.z.enum(["asc", "desc"]).optional().describe("Sort ascending or descending.")
+}).merge(schema);
+var listBodySchema = (schema) => import_zod.z.object({
+  total: import_zod.z.number().describe(
+    "Total number of rows matching the filters — not the length of `data`. Use it to decide whether another page exists."
+  ),
+  data: import_zod.z.array(schema).describe("This page's rows.")
+});
+var BASIC_FIELD_NOTES = {
+  creatorId: "User id of the creator. Stamped by the server; clients cannot send it.",
+  editorId: "User id of whoever changed this row last. Stamped by the server; clients cannot send it.",
+  id: "Primary key of this row (uuid)."
+};
+var BASIC_TIMESTAMP_NOTES = {
+  accessedAt: "When this row was last accessed.",
+  createdAt: "When this row was created.",
+  updatedAt: "When this row was last modified."
+};
+var describeFields = (schema, notes) => {
+  const overlay = {};
+  for (const [field, note] of Object.entries(notes)) {
+    const existing = schema.shape[field];
+    if (existing) {
+      overlay[field] = existing.describe(note);
+    }
+  }
+  return Object.keys(overlay).length ? schema.extend(overlay) : schema;
+};
+var describeBasicFields = (schema) => {
+  const withNotes = describeFields(schema, BASIC_FIELD_NOTES);
+  const overlay = {};
+  for (const [field, note] of Object.entries(BASIC_TIMESTAMP_NOTES)) {
+    const existing = withNotes.shape[field];
+    if (existing) {
+      overlay[field] = existing.meta({
+        description: note,
+        format: "date-time",
+        type: "string"
+      });
+    }
+  }
+  return Object.keys(overlay).length ? withNotes.extend(overlay) : withNotes;
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BASIC_INSERT_OMIT,
+  BASIC_UPDATE_OMIT,
+  describeBasicFields,
+  describeFields,
+  listBodySchema,
+  queryListSchema
+});