@ai0x0/utils 0.2.0 → 0.4.0

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

@@ -48,7 +48,7 @@ export function createPostOperationFactory(_ref) {
         contentType: contentType
       }).outputs([{
         body: schemas.response || z.object({
-          id: z.string()
+          id: z.string().describe("Id of the row created.")
         }),
         contentType: "application/json",
         status: 200
@@ -316,7 +316,7 @@ export function createPutOperationFactory(_ref5) {
 // ==============================================================================
 
 var defaultDeleteBodySchema = z.object({
-  id: z.string()
+  id: z.string().describe("Id of the row to delete.")
 });
 export function createDeleteOperationFactory(_ref9) {
   var createAction = _ref9.createAction,

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

@@ -113,13 +113,33 @@ export declare const listBodySchema: <T extends z.ZodType<unknown, unknown, z.co
     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;
 /**
  * 基于 drizzle + drizzle-zod 快速生成带基础字段（id / 创建时间等）的
  * 表定义以及 select / insert / update / query / list zod schema。
  */
-export declare const createTableSchema: <TTableName extends string, TColumnsMap extends Record<string, PgColumnBuilderBase<import("drizzle-orm").ColumnBuilderBaseConfig<import("drizzle-orm").ColumnDataType, string>, object>>, TServerColumns extends Record<string, PgColumnBuilderBase<import("drizzle-orm").ColumnBuilderBaseConfig<import("drizzle-orm").ColumnDataType, string>, object>> = {}>({ name, columns, serverColumns, extraConfig, }: {
+export declare const createTableSchema: <TTableName extends string, TColumnsMap extends Record<string, PgColumnBuilderBase<import("drizzle-orm").ColumnBuilderBaseConfig<import("drizzle-orm").ColumnDataType, string>, object>>, TServerColumns extends Record<string, PgColumnBuilderBase<import("drizzle-orm").ColumnBuilderBaseConfig<import("drizzle-orm").ColumnDataType, string>, object>> = {}>({ name, columns, serverColumns, extraConfig, describe, }: {
     /** 客户端能写的业务列。insert / update schema 只从这里推。 */
     columns: TColumnsMap;
+    /**
+     * 每一列的说明，键是列名。**同时挂到 insert / update / select 三份 schema 上** —— 同一列在
+     * 请求体里和响应里是同一个东西，说明没有理由写两遍。
+     *
+     * 为什么需要这个参数：drizzle 列没有「描述」这个概念，而 `.describe()` 只能挂在 zod 上。不给
+     * 这条路，业务侧就只能在每张表后面自己把三份 schema 各 `.extend()` 一遍 —— 那是三份副本，
+     * 而副本会漂。
+     *
+     * 键有类型约束（列名的联合），所以列改名了、拼错了都是编译错误，不是静默失效。
+     *
+     * 说明会出现在 OpenAPI spec 里，再流进按 spec 生成的 client 与文档 —— 所以它是写给调用方
+     * 看的：这一列是什么、合法值从哪来、不传会怎样。
+     */
+    describe?: Partial<Record<Extract<keyof TColumnsMap, string> | Extract<keyof TServerColumns, string>, string>> | undefined;
     name: TTableName;
     /**
      * 由服务端盖、**绝不接受客户端传**的业务列：承载归属的 `ownerId`（配合

package/es/backend/schemas/index.js

@@ -4,6 +4,12 @@ function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t =
 function _defineProperty(obj, key, value) { key = _toPropertyKey(key); if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
 function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == _typeof(i) ? i : String(i); }
 function _toPrimitive(t, r) { if ("object" != _typeof(t) || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != _typeof(i)) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+function _slicedToArray(arr, i) { return _arrayWithHoles(arr) || _iterableToArrayLimit(arr, i) || _unsupportedIterableToArray(arr, i) || _nonIterableRest(); }
+function _nonIterableRest() { throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
+function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
+function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) arr2[i] = arr[i]; return arr2; }
+function _iterableToArrayLimit(r, l) { var t = null == r ? null : "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (null != t) { var e, n, i, u, a = [], f = !0, o = !1; try { if (i = (t = t.call(r)).next, 0 === l) { if (Object(t) !== t) return; f = !1; } else for (; !(f = (e = i.call(t)).done) && (a.push(e.value), a.length !== l); f = !0); } catch (r) { o = !0, n = r; } finally { try { if (!f && null != t.return && (u = t.return(), Object(u) !== u)) return; } finally { if (o) throw n; } } return a; } }
+function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
 import { z } from "zod";
 import { pgTable, timestamp, uuid } from "drizzle-orm/pg-core";
 import { createInsertSchema, createSelectSchema, createUpdateSchema } from "drizzle-zod";
@@ -72,19 +78,21 @@ export var BASIC_UPDATE_OMIT = {
 // =============================================================================
 // 列表查询字段
 // =============================================================================
+// 说明写成 `.describe()` 而不是行末注释：注释只有读源码的人看得到，而这七个字段会出现在每一个
+// list 端点的 OpenAPI spec 里，再从那里流进生成的 client 与 CLI 文档。写成注释的代价是下游只能
+// 自己再手写一份 —— 那份必然会漂，而且漂了没有任何东西会报错。
+//
+// 类型是 string 而不是 number：query 参数在线上只有字符串，服务端收下之后才转数字。默认值也
+// 因此是 "1" / "10"。
 export var queryListSchema = function queryListSchema(schema) {
   return z.object({
-    current: z.string().optional().default("1"),
-    // 默认页码为 1
-    pageSize: z.string().optional().default("10"),
-    // 默认每页条数为 10
-    createdAtFrom: z.string().optional(),
-    // 筛选开始日期
-    createdAtTo: z.string().optional(),
-    // 筛选结束日期
-    orderBy: z.string().optional(),
-    creatorId: z.string().optional(),
-    orderDir: z.enum(["asc", "desc"]).optional()
+    current: z.string().optional().default("1").describe("Page number, starting at 1."),
+    pageSize: z.string().optional().default("10").describe("Rows per page. Omitting it yields only 10 — pass a larger value to get the whole set."),
+    createdAtFrom: z.string().optional().describe("Keep only rows created at or after this instant (ISO 8601, e.g. 2026-08-01T00:00:00Z)."),
+    createdAtTo: z.string().optional().describe("Keep only rows created at or before this instant."),
+    orderBy: z.string().optional().describe("Column to sort by — a column name of this resource (createdAt / updatedAt and the like)."),
+    creatorId: z.string().optional().describe("Keep only rows created by this user. Useful in shared spaces to filter down to one member."),
+    orderDir: z.enum(["asc", "desc"]).optional().describe("Sort ascending or descending.")
   }).merge(schema);
 };
 
@@ -98,6 +106,74 @@ export var listBodySchema = function listBodySchema(schema) {
   });
 };
 
+// =============================================================================
+// 给基础字段挂说明
+// =============================================================================
+// basicFields 是 drizzle 列，而 drizzle 列没有「描述」这个概念 —— 所以说明只能挂在
+// drizzle-zod 出来的 schema 上。值得做是因为这六个字段出现在**每一张表**的 select schema 里：
+// 一处写完，所有 list / get 端点的返回字段表都有了（在 do-tv 上是 173 行）。
+//
+// 一律只挂元数据，**不换类型**：`.describe()` / `.meta()` 返回的是带元数据的克隆，校验行为一模
+// 一样。selectSchema 是有人拿去 safeParse 的（本包自己的测试就在用 Date 校验它），换类型等于改
+// 这个包的契约。
+//
+// 时间戳那三列额外用 `.meta()` 补上 JSON Schema 表示，因为不补就是错的：drizzle-zod 给的是
+// `z.date()`，而 `Date` 在 JSON Schema 里表达不出来，于是这三个字段在 spec 里是**空对象** ——
+// 没有 `type`，照 spec 生成的 client / CLI 只能得到 `unknown`。而线上根本不可能是 Date：响应一经
+// JSON 序列化就是 ISO 8601 字符串。
+//
+// `.meta({ type, format })` 恰好只改「怎么描述」不改「怎么校验」：spec 里成为
+// `{"type":"string","format":"date-time"}`，而 `safeParse(new Date())` 照样通过。
+// 不用 `z.iso.datetime()` 换掉它，是因为那既改了校验（不再收 Date），又会往 JSON Schema 里塞一条
+// 380 字节的正则 —— 乘上每张表几十 KB，而 `format` 已经把「按日期时间解析」说清楚了。
+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."
+};
+
+/**
+ * 给 schema 上已有的字段挂说明。字段不在这个 schema 里就跳过 —— 同一张表的
+ * insert / update / select 三份含的列不一样（basicFields 只在 select 里），一份说明表要能同时
+ * 喂给三者，就不能对「字段一定存在」有要求。**不给不存在的字段凭空造一个。**
+ */
+export var describeFields = function describeFields(schema, notes) {
+  var overlay = {};
+  for (var _i = 0, _Object$entries = Object.entries(notes); _i < _Object$entries.length; _i++) {
+    var _Object$entries$_i = _slicedToArray(_Object$entries[_i], 2),
+      field = _Object$entries$_i[0],
+      note = _Object$entries$_i[1];
+    var existing = schema.shape[field];
+    if (existing) {
+      overlay[field] = existing.describe(note);
+    }
+  }
+  return Object.keys(overlay).length ? schema.extend(overlay) : schema;
+};
+var describeBasicFields = function describeBasicFields(schema) {
+  var withNotes = describeFields(schema, BASIC_FIELD_NOTES);
+  var overlay = {};
+  for (var _i2 = 0, _Object$entries2 = Object.entries(BASIC_TIMESTAMP_NOTES); _i2 < _Object$entries2.length; _i2++) {
+    var _Object$entries2$_i = _slicedToArray(_Object$entries2[_i2], 2),
+      field = _Object$entries2$_i[0],
+      note = _Object$entries2$_i[1];
+    var 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;
+};
+
 // =============================================================================
 // 建表 —— 表 + 5 份 zod schema
 // =============================================================================
@@ -109,19 +185,23 @@ export var createTableSchema = function createTableSchema(_ref) {
   var name = _ref.name,
     columns = _ref.columns,
     serverColumns = _ref.serverColumns,
-    extraConfig = _ref.extraConfig;
+    extraConfig = _ref.extraConfig,
+    describe = _ref.describe;
   var mergedColumns = _objectSpread(_objectSpread(_objectSpread({}, basicFields), serverColumns), columns);
   var table = pgTable(name, mergedColumns, extraConfig);
-  var selectSchema = createSelectSchema(table);
+
+  // 同一份说明喂给三份 schema：含哪些列各不相同，describeFields 会跳过不存在的。
+  var notes = describe !== null && describe !== void 0 ? describe : {};
+  var selectSchema = describeFields(describeBasicFields(createSelectSchema(table)), notes);
   // 只从 columns 推 —— basicFields 与 serverColumns 都由服务端写，不该出现在请求体里。
-  var insertSchema = createInsertSchema(pgTable(name, columns));
-  var updateSchema = createUpdateSchema(pgTable(name, _objectSpread({
+  var insertSchema = describeFields(createInsertSchema(pgTable(name, columns)), notes);
+  var updateSchema = describeFields(createUpdateSchema(pgTable(name, _objectSpread({
     id: uuid("id")
   }, columns))).extend({
-    id: z.string()
-  });
+    id: z.string().describe("Id of the row to update.")
+  }), notes);
   var querySchema = z.object({
-    id: z.string()
+    id: z.string().describe("Id of the row to fetch.")
   });
   var queryListWithSchema = queryListSchema(z.object({}).catchall(z.unknown()));
   return {

package/es/backend/sqlite/schemas/index.d.ts

@@ -113,6 +113,12 @@ export declare const listBodySchema: <T extends z.ZodType<unknown, unknown, z.co
     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;
 /**
  * 基于 drizzle + drizzle-zod 快速生成带基础字段（id / 创建时间等）的
  * 表定义以及 select / insert / update / query / list zod schema。
@@ -121,6 +127,11 @@ export declare const createTableSchema: <TTableName extends string, TColumnsMap
     name: TTableName;
     /** 客户端能写的业务列。insert / update schema 只从这里推。 */
     columns: TColumnsMap;
+    /**
+     * 每一列的说明，键是列名。同时挂到 insert / update / select 三份 schema 上。语义与 pg 版
+     * 一致，见那边的说明。
+     */
+    describe?: Partial<Record<string, string>>;
     /** 由服务端盖、绝不接受客户端传的业务列（归属、租户 id 这类）。语义与 pg 版一致，见那边的说明。 */
     serverColumns?: Record<string, SQLiteColumnBuilderBase>;
     extraConfig?: (_self: BuildExtraConfigColumns<TTableName, typeof basicFields & TColumnsMap, "sqlite">) => SQLiteTableExtraConfigValue[];

package/es/backend/sqlite/schemas/index.js

@@ -4,6 +4,12 @@ function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t =
 function _defineProperty(obj, key, value) { key = _toPropertyKey(key); if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
 function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == _typeof(i) ? i : String(i); }
 function _toPrimitive(t, r) { if ("object" != _typeof(t) || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != _typeof(i)) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+function _slicedToArray(arr, i) { return _arrayWithHoles(arr) || _iterableToArrayLimit(arr, i) || _unsupportedIterableToArray(arr, i) || _nonIterableRest(); }
+function _nonIterableRest() { throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
+function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
+function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) arr2[i] = arr[i]; return arr2; }
+function _iterableToArrayLimit(r, l) { var t = null == r ? null : "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (null != t) { var e, n, i, u, a = [], f = !0, o = !1; try { if (i = (t = t.call(r)).next, 0 === l) { if (Object(t) !== t) return; f = !1; } else for (; !(f = (e = i.call(t)).done) && (a.push(e.value), a.length !== l); f = !0); } catch (r) { o = !0, n = r; } finally { try { if (!f && null != t.return && (u = t.return(), Object(u) !== u)) return; } finally { if (o) throw n; } } return a; } }
+function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
 import { z } from "zod";
 import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
 import { createInsertSchema, createSelectSchema, createUpdateSchema } from "drizzle-zod";
@@ -78,19 +84,21 @@ export var BASIC_UPDATE_OMIT = {
 // =============================================================================
 // 列表查询字段
 // =============================================================================
+// 说明写成 `.describe()` 而不是行末注释：注释只有读源码的人看得到，而这七个字段会出现在每一个
+// list 端点的 OpenAPI spec 里，再从那里流进生成的 client 与 CLI 文档。写成注释的代价是下游只能
+// 自己再手写一份 —— 那份必然会漂，而且漂了没有任何东西会报错。
+//
+// 类型是 string 而不是 number：query 参数在线上只有字符串，服务端收下之后才转数字。默认值也
+// 因此是 "1" / "10"。
 export var queryListSchema = function queryListSchema(schema) {
   return z.object({
-    current: z.string().optional().default("1"),
-    // 默认页码为 1
-    pageSize: z.string().optional().default("10"),
-    // 默认每页条数为 10
-    createdAtFrom: z.string().optional(),
-    // 筛选开始日期
-    createdAtTo: z.string().optional(),
-    // 筛选结束日期
-    orderBy: z.string().optional(),
-    creatorId: z.string().optional(),
-    orderDir: z.enum(["asc", "desc"]).optional()
+    current: z.string().optional().default("1").describe("Page number, starting at 1."),
+    pageSize: z.string().optional().default("10").describe("Rows per page. Omitting it yields only 10 — pass a larger value to get the whole set."),
+    createdAtFrom: z.string().optional().describe("Keep only rows created at or after this instant (ISO 8601, e.g. 2026-08-01T00:00:00Z)."),
+    createdAtTo: z.string().optional().describe("Keep only rows created at or before this instant."),
+    orderBy: z.string().optional().describe("Column to sort by — a column name of this resource (createdAt / updatedAt and the like)."),
+    creatorId: z.string().optional().describe("Keep only rows created by this user. Useful in shared spaces to filter down to one member."),
+    orderDir: z.enum(["asc", "desc"]).optional().describe("Sort ascending or descending.")
   }).merge(schema);
 };
 
@@ -104,6 +112,74 @@ export var listBodySchema = function listBodySchema(schema) {
   });
 };
 
+// =============================================================================
+// 给基础字段挂说明
+// =============================================================================
+// basicFields 是 drizzle 列，而 drizzle 列没有「描述」这个概念 —— 所以说明只能挂在
+// drizzle-zod 出来的 schema 上。值得做是因为这六个字段出现在**每一张表**的 select schema 里：
+// 一处写完，所有 list / get 端点的返回字段都有说明了。
+//
+// 一律只挂元数据，**不换类型**：`.describe()` / `.meta()` 返回的是带元数据的克隆，校验行为一模
+// 一样。selectSchema 是有人拿去 safeParse 的（本包自己的测试就在用 Date 校验它），换类型等于改
+// 这个包的契约。
+//
+// 时间戳那三列额外用 `.meta()` 补上 JSON Schema 表示，因为不补就是错的：drizzle-zod 给的是
+// `z.date()`，而 `Date` 在 JSON Schema 里表达不出来，于是这三个字段在 spec 里是**空对象** ——
+// 没有 `type`，照 spec 生成的 client / CLI 只能得到 `unknown`。而线上根本不可能是 Date：响应一经
+// JSON 序列化就是 ISO 8601 字符串。
+//
+// `.meta({ type, format })` 恰好只改「怎么描述」不改「怎么校验」：spec 里成为
+// `{"type":"string","format":"date-time"}`，而 `safeParse(new Date())` 照样通过。
+// 不用 `z.iso.datetime()` 换掉它，是因为那既改了校验（不再收 Date），又会往 JSON Schema 里塞一条
+// 380 字节的正则 —— 乘上每张表几十 KB，而 `format` 已经把「按日期时间解析」说清楚了。
+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."
+};
+
+/**
+ * 给 schema 上已有的字段挂说明。字段不在这个 schema 里就跳过 —— 同一张表的
+ * insert / update / select 三份含的列不一样（basicFields 只在 select 里），一份说明表要能同时
+ * 喂给三者，就不能对「字段一定存在」有要求。**不给不存在的字段凭空造一个。**
+ */
+export var describeFields = function describeFields(schema, notes) {
+  var overlay = {};
+  for (var _i = 0, _Object$entries = Object.entries(notes); _i < _Object$entries.length; _i++) {
+    var _Object$entries$_i = _slicedToArray(_Object$entries[_i], 2),
+      field = _Object$entries$_i[0],
+      note = _Object$entries$_i[1];
+    var existing = schema.shape[field];
+    if (existing) {
+      overlay[field] = existing.describe(note);
+    }
+  }
+  return Object.keys(overlay).length ? schema.extend(overlay) : schema;
+};
+var describeBasicFields = function describeBasicFields(schema) {
+  var withNotes = describeFields(schema, BASIC_FIELD_NOTES);
+  var overlay = {};
+  for (var _i2 = 0, _Object$entries2 = Object.entries(BASIC_TIMESTAMP_NOTES); _i2 < _Object$entries2.length; _i2++) {
+    var _Object$entries2$_i = _slicedToArray(_Object$entries2[_i2], 2),
+      field = _Object$entries2$_i[0],
+      note = _Object$entries2$_i[1];
+    var 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;
+};
+
 // =============================================================================
 // 建表 —— 表 + 5 份 zod schema
 // =============================================================================
@@ -115,19 +191,23 @@ export var createTableSchema = function createTableSchema(_ref) {
   var name = _ref.name,
     columns = _ref.columns,
     serverColumns = _ref.serverColumns,
-    extraConfig = _ref.extraConfig;
+    extraConfig = _ref.extraConfig,
+    describe = _ref.describe;
   var mergedColumns = _objectSpread(_objectSpread(_objectSpread({}, basicFields), serverColumns), columns);
   var table = sqliteTable(name, mergedColumns, extraConfig);
-  var selectSchema = createSelectSchema(table);
+
+  // 同一份说明喂给三份 schema：含哪些列各不相同，describeFields 会跳过不存在的。
+  var notes = describe !== null && describe !== void 0 ? describe : {};
+  var selectSchema = describeFields(describeBasicFields(createSelectSchema(table)), notes);
   // 只从 columns 推 —— basicFields 与 serverColumns 都由服务端写，不该出现在请求体里。
-  var insertSchema = createInsertSchema(sqliteTable(name, columns));
-  var updateSchema = createUpdateSchema(sqliteTable(name, _objectSpread({
+  var insertSchema = describeFields(createInsertSchema(sqliteTable(name, columns)), notes);
+  var updateSchema = describeFields(createUpdateSchema(sqliteTable(name, _objectSpread({
     id: text("id")
   }, columns))).extend({
-    id: z.string()
-  });
+    id: z.string().describe("Id of the row to update.")
+  }), notes);
   var querySchema = z.object({
-    id: z.string()
+    id: z.string().describe("Id of the row to fetch.")
   });
   var queryListWithSchema = queryListSchema(z.object({}).catchall(z.unknown()));
   return {

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

@@ -57,7 +57,7 @@ function createPostOperationFactory({
     contentType
   }).outputs([
     {
-      body: schemas.response || import_zod.z.object({ id: import_zod.z.string() }),
+      body: schemas.response || import_zod.z.object({ id: import_zod.z.string().describe("Id of the row created.") }),
       contentType: "application/json",
       status: 200
     }
@@ -156,7 +156,7 @@ function createPutOperationFactory({
   });
 }
 var defaultDeleteBodySchema = import_zod.z.object({
-  id: import_zod.z.string()
+  id: import_zod.z.string().describe("Id of the row to delete.")
 });
 function createDeleteOperationFactory({
   createAction,

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

@@ -113,13 +113,33 @@ export declare const listBodySchema: <T extends z.ZodType<unknown, unknown, z.co
     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;
 /**
  * 基于 drizzle + drizzle-zod 快速生成带基础字段（id / 创建时间等）的
  * 表定义以及 select / insert / update / query / list zod schema。
  */
-export declare const createTableSchema: <TTableName extends string, TColumnsMap extends Record<string, PgColumnBuilderBase<import("drizzle-orm").ColumnBuilderBaseConfig<import("drizzle-orm").ColumnDataType, string>, object>>, TServerColumns extends Record<string, PgColumnBuilderBase<import("drizzle-orm").ColumnBuilderBaseConfig<import("drizzle-orm").ColumnDataType, string>, object>> = {}>({ name, columns, serverColumns, extraConfig, }: {
+export declare const createTableSchema: <TTableName extends string, TColumnsMap extends Record<string, PgColumnBuilderBase<import("drizzle-orm").ColumnBuilderBaseConfig<import("drizzle-orm").ColumnDataType, string>, object>>, TServerColumns extends Record<string, PgColumnBuilderBase<import("drizzle-orm").ColumnBuilderBaseConfig<import("drizzle-orm").ColumnDataType, string>, object>> = {}>({ name, columns, serverColumns, extraConfig, describe, }: {
     /** 客户端能写的业务列。insert / update schema 只从这里推。 */
     columns: TColumnsMap;
+    /**
+     * 每一列的说明，键是列名。**同时挂到 insert / update / select 三份 schema 上** —— 同一列在
+     * 请求体里和响应里是同一个东西，说明没有理由写两遍。
+     *
+     * 为什么需要这个参数：drizzle 列没有「描述」这个概念，而 `.describe()` 只能挂在 zod 上。不给
+     * 这条路，业务侧就只能在每张表后面自己把三份 schema 各 `.extend()` 一遍 —— 那是三份副本，
+     * 而副本会漂。
+     *
+     * 键有类型约束（列名的联合），所以列改名了、拼错了都是编译错误，不是静默失效。
+     *
+     * 说明会出现在 OpenAPI spec 里，再流进按 spec 生成的 client 与文档 —— 所以它是写给调用方
+     * 看的：这一列是什么、合法值从哪来、不传会怎样。
+     */
+    describe?: Partial<Record<Extract<keyof TColumnsMap, string> | Extract<keyof TServerColumns, string>, string>> | undefined;
     name: TTableName;
     /**
      * 由服务端盖、**绝不接受客户端传**的业务列：承载归属的 `ownerId`（配合

package/lib/backend/schemas/index.js

@@ -23,6 +23,7 @@ __export(schemas_exports, {
   BASIC_UPDATE_OMIT: () => BASIC_UPDATE_OMIT,
   basicFields: () => basicFields,
   createTableSchema: () => createTableSchema,
+  describeFields: () => describeFields,
   listBodySchema: () => listBodySchema,
   queryListSchema: () => queryListSchema
 });
@@ -58,27 +59,67 @@ var BASIC_UPDATE_OMIT = {
   updatedAt: true
 };
 var queryListSchema = (schema) => import_zod.z.object({
-  current: import_zod.z.string().optional().default("1"),
-  // 默认页码为 1
-  pageSize: import_zod.z.string().optional().default("10"),
-  // 默认每页条数为 10
-  createdAtFrom: import_zod.z.string().optional(),
-  // 筛选开始日期
-  createdAtTo: import_zod.z.string().optional(),
-  // 筛选结束日期
-  orderBy: import_zod.z.string().optional(),
-  creatorId: import_zod.z.string().optional(),
-  orderDir: import_zod.z.enum(["asc", "desc"]).optional()
+  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(),
   data: import_zod.z.array(schema)
 });
+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;
+};
 var createTableSchema = ({
   name,
   columns,
   serverColumns,
-  extraConfig
+  extraConfig,
+  describe
 }) => {
   const mergedColumns = {
     ...basicFields,
@@ -86,12 +127,24 @@ var createTableSchema = ({
     ...columns
   };
   const table = (0, import_pg_core.pgTable)(name, mergedColumns, extraConfig);
-  const selectSchema = (0, import_drizzle_zod.createSelectSchema)(table);
-  const insertSchema = (0, import_drizzle_zod.createInsertSchema)((0, import_pg_core.pgTable)(name, columns));
-  const updateSchema = (0, import_drizzle_zod.createUpdateSchema)(
-    (0, import_pg_core.pgTable)(name, { id: (0, import_pg_core.uuid)("id"), ...columns })
-  ).extend({ id: import_zod.z.string() });
-  const querySchema = import_zod.z.object({ id: import_zod.z.string() });
+  const notes = describe ?? {};
+  const selectSchema = describeFields(
+    describeBasicFields((0, import_drizzle_zod.createSelectSchema)(table)),
+    notes
+  );
+  const insertSchema = describeFields(
+    (0, import_drizzle_zod.createInsertSchema)((0, import_pg_core.pgTable)(name, columns)),
+    notes
+  );
+  const updateSchema = describeFields(
+    (0, import_drizzle_zod.createUpdateSchema)((0, import_pg_core.pgTable)(name, { id: (0, import_pg_core.uuid)("id"), ...columns })).extend({
+      id: import_zod.z.string().describe("Id of the row to update.")
+    }),
+    notes
+  );
+  const querySchema = import_zod.z.object({
+    id: import_zod.z.string().describe("Id of the row to fetch.")
+  });
   const queryListWithSchema = queryListSchema(
     import_zod.z.object({}).catchall(import_zod.z.unknown())
   );
@@ -111,6 +164,7 @@ var createTableSchema = ({
   BASIC_UPDATE_OMIT,
   basicFields,
   createTableSchema,
+  describeFields,
   listBodySchema,
   queryListSchema
 });

package/lib/backend/sqlite/schemas/index.d.ts

@@ -113,6 +113,12 @@ export declare const listBodySchema: <T extends z.ZodType<unknown, unknown, z.co
     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;
 /**
  * 基于 drizzle + drizzle-zod 快速生成带基础字段（id / 创建时间等）的
  * 表定义以及 select / insert / update / query / list zod schema。
@@ -121,6 +127,11 @@ export declare const createTableSchema: <TTableName extends string, TColumnsMap
     name: TTableName;
     /** 客户端能写的业务列。insert / update schema 只从这里推。 */
     columns: TColumnsMap;
+    /**
+     * 每一列的说明，键是列名。同时挂到 insert / update / select 三份 schema 上。语义与 pg 版
+     * 一致，见那边的说明。
+     */
+    describe?: Partial<Record<string, string>>;
     /** 由服务端盖、绝不接受客户端传的业务列（归属、租户 id 这类）。语义与 pg 版一致，见那边的说明。 */
     serverColumns?: Record<string, SQLiteColumnBuilderBase>;
     extraConfig?: (_self: BuildExtraConfigColumns<TTableName, typeof basicFields & TColumnsMap, "sqlite">) => SQLiteTableExtraConfigValue[];

package/lib/backend/sqlite/schemas/index.js

@@ -23,6 +23,7 @@ __export(schemas_exports, {
   BASIC_UPDATE_OMIT: () => BASIC_UPDATE_OMIT,
   basicFields: () => basicFields,
   createTableSchema: () => createTableSchema,
+  describeFields: () => describeFields,
   listBodySchema: () => listBodySchema,
   queryListSchema: () => queryListSchema
 });
@@ -60,23 +61,62 @@ var BASIC_UPDATE_OMIT = {
   updatedAt: true
 };
 var queryListSchema = (schema) => import_zod.z.object({
-  current: import_zod.z.string().optional().default("1"),
-  // 默认页码为 1
-  pageSize: import_zod.z.string().optional().default("10"),
-  // 默认每页条数为 10
-  createdAtFrom: import_zod.z.string().optional(),
-  // 筛选开始日期
-  createdAtTo: import_zod.z.string().optional(),
-  // 筛选结束日期
-  orderBy: import_zod.z.string().optional(),
-  creatorId: import_zod.z.string().optional(),
-  orderDir: import_zod.z.enum(["asc", "desc"]).optional()
+  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(),
   data: import_zod.z.array(schema)
 });
-var createTableSchema = ({ name, columns, serverColumns, extraConfig }) => {
+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;
+};
+var createTableSchema = ({ name, columns, serverColumns, extraConfig, describe }) => {
   const mergedColumns = {
     ...basicFields,
     ...serverColumns,
@@ -87,12 +127,26 @@ var createTableSchema = ({ name, columns, serverColumns, extraConfig }) => {
     mergedColumns,
     extraConfig
   );
-  const selectSchema = (0, import_drizzle_zod.createSelectSchema)(table);
-  const insertSchema = (0, import_drizzle_zod.createInsertSchema)((0, import_sqlite_core.sqliteTable)(name, columns));
-  const updateSchema = (0, import_drizzle_zod.createUpdateSchema)(
-    (0, import_sqlite_core.sqliteTable)(name, { id: (0, import_sqlite_core.text)("id"), ...columns })
-  ).extend({ id: import_zod.z.string() });
-  const querySchema = import_zod.z.object({ id: import_zod.z.string() });
+  const notes = describe ?? {};
+  const selectSchema = describeFields(
+    describeBasicFields((0, import_drizzle_zod.createSelectSchema)(table)),
+    notes
+  );
+  const insertSchema = describeFields(
+    (0, import_drizzle_zod.createInsertSchema)((0, import_sqlite_core.sqliteTable)(name, columns)),
+    notes
+  );
+  const updateSchema = describeFields(
+    (0, import_drizzle_zod.createUpdateSchema)(
+      (0, import_sqlite_core.sqliteTable)(name, { id: (0, import_sqlite_core.text)("id"), ...columns })
+    ).extend({
+      id: import_zod.z.string().describe("Id of the row to update.")
+    }),
+    notes
+  );
+  const querySchema = import_zod.z.object({
+    id: import_zod.z.string().describe("Id of the row to fetch.")
+  });
   const queryListWithSchema = queryListSchema(
     import_zod.z.object({}).catchall(import_zod.z.unknown())
   );
@@ -112,6 +166,7 @@ var createTableSchema = ({ name, columns, serverColumns, extraConfig }) => {
   BASIC_UPDATE_OMIT,
   basicFields,
   createTableSchema,
+  describeFields,
   listBodySchema,
   queryListSchema
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai0x0/utils",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "AI0x0 utils",
   "keywords": [
     "ai0x0"