@ai0x0/utils 0.2.0 → 0.3.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.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,64 @@ 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."
+};
+var describeBasicFields = function describeBasicFields(schema) {
+  var overlay = {};
+  for (var _i = 0, _Object$entries = Object.entries(BASIC_FIELD_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);
+    }
+  }
+  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,
+        format: "date-time",
+        type: "string"
+      });
+    }
+  }
+  return schema.extend(overlay);
+};
+
 // =============================================================================
 // 建表 —— 表 + 5 份 zod schema
 // =============================================================================
@@ -112,16 +178,16 @@ export var createTableSchema = function createTableSchema(_ref) {
     extraConfig = _ref.extraConfig;
   var mergedColumns = _objectSpread(_objectSpread(_objectSpread({}, basicFields), serverColumns), columns);
   var table = pgTable(name, mergedColumns, extraConfig);
-  var selectSchema = createSelectSchema(table);
+  var selectSchema = describeBasicFields(createSelectSchema(table));
   // 只从 columns 推 —— basicFields 与 serverColumns 都由服务端写，不该出现在请求体里。
   var insertSchema = createInsertSchema(pgTable(name, columns));
   var updateSchema = createUpdateSchema(pgTable(name, _objectSpread({
     id: uuid("id")
   }, columns))).extend({
-    id: z.string()
+    id: z.string().describe("Id of the row to update.")
   });
   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.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,64 @@ 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."
+};
+var describeBasicFields = function describeBasicFields(schema) {
+  var overlay = {};
+  for (var _i = 0, _Object$entries = Object.entries(BASIC_FIELD_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);
+    }
+  }
+  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,
+        format: "date-time",
+        type: "string"
+      });
+    }
+  }
+  return schema.extend(overlay);
+};
+
 // =============================================================================
 // 建表 —— 表 + 5 份 zod schema
 // =============================================================================
@@ -118,16 +184,16 @@ export var createTableSchema = function createTableSchema(_ref) {
     extraConfig = _ref.extraConfig;
   var mergedColumns = _objectSpread(_objectSpread(_objectSpread({}, basicFields), serverColumns), columns);
   var table = sqliteTable(name, mergedColumns, extraConfig);
-  var selectSchema = createSelectSchema(table);
+  var selectSchema = describeBasicFields(createSelectSchema(table));
   // 只从 columns 推 —— basicFields 与 serverColumns 都由服务端写，不该出现在请求体里。
   var insertSchema = createInsertSchema(sqliteTable(name, columns));
   var updateSchema = createUpdateSchema(sqliteTable(name, _objectSpread({
     id: text("id")
   }, columns))).extend({
-    id: z.string()
+    id: z.string().describe("Id of the row to update.")
   });
   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.js

@@ -58,22 +58,56 @@ 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 describeBasicFields = (schema) => {
+  const overlay = {};
+  for (const [field, note] of Object.entries(BASIC_FIELD_NOTES)) {
+    const existing = schema.shape[field];
+    if (existing) {
+      overlay[field] = existing.describe(note);
+    }
+  }
+  for (const [field, note] of Object.entries(BASIC_TIMESTAMP_NOTES)) {
+    const existing = schema.shape[field];
+    if (existing) {
+      overlay[field] = existing.meta({
+        description: note,
+        format: "date-time",
+        type: "string"
+      });
+    }
+  }
+  return schema.extend(overlay);
+};
 var createTableSchema = ({
   name,
   columns,
@@ -86,12 +120,14 @@ var createTableSchema = ({
     ...columns
   };
   const table = (0, import_pg_core.pgTable)(name, mergedColumns, extraConfig);
-  const selectSchema = (0, import_drizzle_zod.createSelectSchema)(table);
+  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() });
-  const querySchema = import_zod.z.object({ id: import_zod.z.string() });
+  ).extend({ id: import_zod.z.string().describe("Id of the row to update.") });
+  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())
   );

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

@@ -60,22 +60,56 @@ 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 describeBasicFields = (schema) => {
+  const overlay = {};
+  for (const [field, note] of Object.entries(BASIC_FIELD_NOTES)) {
+    const existing = schema.shape[field];
+    if (existing) {
+      overlay[field] = existing.describe(note);
+    }
+  }
+  for (const [field, note] of Object.entries(BASIC_TIMESTAMP_NOTES)) {
+    const existing = schema.shape[field];
+    if (existing) {
+      overlay[field] = existing.meta({
+        description: note,
+        format: "date-time",
+        type: "string"
+      });
+    }
+  }
+  return schema.extend(overlay);
+};
 var createTableSchema = ({ name, columns, serverColumns, extraConfig }) => {
   const mergedColumns = {
     ...basicFields,
@@ -87,12 +121,14 @@ var createTableSchema = ({ name, columns, serverColumns, extraConfig }) => {
     mergedColumns,
     extraConfig
   );
-  const selectSchema = (0, import_drizzle_zod.createSelectSchema)(table);
+  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() });
-  const querySchema = import_zod.z.object({ id: import_zod.z.string() });
+  ).extend({ id: import_zod.z.string().describe("Id of the row to update.") });
+  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())
   );

package/package.json

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