@ai0x0/utils 0.3.0 → 0.5.0

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

@@ -99,10 +99,12 @@ export var queryListSchema = function queryListSchema(schema) {
 // =============================================================================
 // 列表返回字段
 // =============================================================================
+// 这两个字段出现在**每一个** list 端点的响应里，所以说明写在这儿一次就够 —— 下游那边它们是
+// 逐个 list 命令重复一遍的（在一个 101 端点的项目上是 24 行空白）。
 export var listBodySchema = function listBodySchema(schema) {
   return z.object({
-    total: z.number(),
-    data: z.array(schema)
+    total: z.number().describe("Total number of rows matching the filters — not the length of `data`. Use it to decide whether another page exists."),
+    data: z.array(schema).describe("This page's rows.")
   });
 };
 
@@ -136,32 +138,42 @@ var BASIC_TIMESTAMP_NOTES = {
   createdAt: "When this row was created.",
   updatedAt: "When this row was last modified."
 };
-var describeBasicFields = function describeBasicFields(schema) {
+
+/**
+ * 给 schema 上已有的字段挂说明。字段不在这个 schema 里就跳过 —— 同一张表的
+ * insert / update / select 三份含的列不一样（basicFields 只在 select 里），一份说明表要能同时
+ * 喂给三者，就不能对「字段一定存在」有要求。**不给不存在的字段凭空造一个。**
+ */
+export var describeFields = function describeFields(schema, notes) {
   var overlay = {};
-  for (var _i = 0, _Object$entries = Object.entries(BASIC_FIELD_NOTES); _i < _Object$entries.length; _i++) {
+  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 = schema.shape[_field];
-    if (_existing) {
-      overlay[_field] = _existing.meta({
-        description: _note,
+      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 schema.extend(overlay);
+  return Object.keys(overlay).length ? withNotes.extend(overlay) : withNotes;
 };
 
 // =============================================================================
@@ -175,17 +187,21 @@ 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 = describeBasicFields(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().describe("Id of the row to update.")
-  });
+  }), notes);
   var querySchema = z.object({
     id: z.string().describe("Id of the row to fetch.")
   });

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

@@ -105,10 +105,12 @@ export var queryListSchema = function queryListSchema(schema) {
 // =============================================================================
 // 列表返回字段
 // =============================================================================
+// 这两个字段出现在**每一个** list 端点的响应里，所以说明写在这儿一次就够 —— 下游那边它们是
+// 逐个 list 命令重复一遍的（在一个 101 端点的项目上是 24 行空白）。
 export var listBodySchema = function listBodySchema(schema) {
   return z.object({
-    total: z.number(),
-    data: z.array(schema)
+    total: z.number().describe("Total number of rows matching the filters — not the length of `data`. Use it to decide whether another page exists."),
+    data: z.array(schema).describe("This page's rows.")
   });
 };
 
@@ -142,32 +144,42 @@ var BASIC_TIMESTAMP_NOTES = {
   createdAt: "When this row was created.",
   updatedAt: "When this row was last modified."
 };
-var describeBasicFields = function describeBasicFields(schema) {
+
+/**
+ * 给 schema 上已有的字段挂说明。字段不在这个 schema 里就跳过 —— 同一张表的
+ * insert / update / select 三份含的列不一样（basicFields 只在 select 里），一份说明表要能同时
+ * 喂给三者，就不能对「字段一定存在」有要求。**不给不存在的字段凭空造一个。**
+ */
+export var describeFields = function describeFields(schema, notes) {
   var overlay = {};
-  for (var _i = 0, _Object$entries = Object.entries(BASIC_FIELD_NOTES); _i < _Object$entries.length; _i++) {
+  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 = schema.shape[_field];
-    if (_existing) {
-      overlay[_field] = _existing.meta({
-        description: _note,
+      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 schema.extend(overlay);
+  return Object.keys(overlay).length ? withNotes.extend(overlay) : withNotes;
 };
 
 // =============================================================================
@@ -181,17 +193,21 @@ 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 = describeBasicFields(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().describe("Id of the row to update.")
-  });
+  }), notes);
   var querySchema = z.object({
     id: z.string().describe("Id of the row to fetch.")
   });

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
 });
@@ -75,8 +76,10 @@ var queryListSchema = (schema) => import_zod.z.object({
   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)
+  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.",
@@ -88,16 +91,21 @@ var BASIC_TIMESTAMP_NOTES = {
   createdAt: "When this row was created.",
   updatedAt: "When this row was last modified."
 };
-var describeBasicFields = (schema) => {
+var describeFields = (schema, notes) => {
   const overlay = {};
-  for (const [field, note] of Object.entries(BASIC_FIELD_NOTES)) {
+  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 = schema.shape[field];
+    const existing = withNotes.shape[field];
     if (existing) {
       overlay[field] = existing.meta({
         description: note,
@@ -106,13 +114,14 @@ var describeBasicFields = (schema) => {
       });
     }
   }
-  return schema.extend(overlay);
+  return Object.keys(overlay).length ? withNotes.extend(overlay) : withNotes;
 };
 var createTableSchema = ({
   name,
   columns,
   serverColumns,
-  extraConfig
+  extraConfig,
+  describe
 }) => {
   const mergedColumns = {
     ...basicFields,
@@ -120,11 +129,21 @@ var createTableSchema = ({
     ...columns
   };
   const table = (0, import_pg_core.pgTable)(name, mergedColumns, extraConfig);
-  const selectSchema = describeBasicFields((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().describe("Id of the row to update.") });
+  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.")
   });
@@ -147,6 +166,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
 });
@@ -77,8 +78,10 @@ var queryListSchema = (schema) => import_zod.z.object({
   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)
+  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.",
@@ -90,16 +93,21 @@ var BASIC_TIMESTAMP_NOTES = {
   createdAt: "When this row was created.",
   updatedAt: "When this row was last modified."
 };
-var describeBasicFields = (schema) => {
+var describeFields = (schema, notes) => {
   const overlay = {};
-  for (const [field, note] of Object.entries(BASIC_FIELD_NOTES)) {
+  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 = schema.shape[field];
+    const existing = withNotes.shape[field];
     if (existing) {
       overlay[field] = existing.meta({
         description: note,
@@ -108,9 +116,9 @@ var describeBasicFields = (schema) => {
       });
     }
   }
-  return schema.extend(overlay);
+  return Object.keys(overlay).length ? withNotes.extend(overlay) : withNotes;
 };
-var createTableSchema = ({ name, columns, serverColumns, extraConfig }) => {
+var createTableSchema = ({ name, columns, serverColumns, extraConfig, describe }) => {
   const mergedColumns = {
     ...basicFields,
     ...serverColumns,
@@ -121,11 +129,23 @@ var createTableSchema = ({ name, columns, serverColumns, extraConfig }) => {
     mergedColumns,
     extraConfig
   );
-  const selectSchema = describeBasicFields((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().describe("Id of the row to update.") });
+  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.")
   });
@@ -148,6 +168,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.3.0",
+  "version": "0.5.0",
   "description": "AI0x0 utils",
   "keywords": [
     "ai0x0"