@ai0x0/utils 0.1.3 → 0.3.0

package/es/backend/route-operation/delete-operation.d.ts

@@ -1,16 +1,12 @@
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
-import { NextRequest } from "next/server";
 import { ZodSchema } from "zod";
 import { BaseTable } from "../types.js";
 import { type DeleteOperationOptions as CoreDeleteOperationOptions } from "./operation-core.js";
-export type DeleteOperationOptions<TTable extends BaseTable, B extends ZodSchema> = CoreDeleteOperationOptions<TTable, B>;
-export declare const createDeleteOperation: ({ db, getSession, }: {
+import type { DefaultSession, SessionGetter } from "./operation-common.js";
+export type DeleteOperationOptions<TTable extends BaseTable, B extends ZodSchema, TSession = DefaultSession> = CoreDeleteOperationOptions<TTable, B, TSession>;
+export declare const createDeleteOperation: <TSession = DefaultSession>({ db, getSession, }: {
     db?: NodePgDatabase<Record<string, unknown>> | undefined;
-    getSession(req: NextRequest): Promise<{
-        userId?: string;
-    } | undefined>;
+    getSession: SessionGetter<TSession>;
 }) => <B extends ZodSchema<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> = import("zod").ZodObject<{
     id: import("zod").ZodString;
-}, import("zod/v4/core").$strip>>({ table, schemas, access, openApiOperation, handler, catch: catchHandler, }: CoreDeleteOperationOptions<BaseTable, B, {
-    userId?: string | undefined;
-}>) => import("next-rest-framework").RouteOperationDefinition<"DELETE">;
+}, import("zod/v4/core").$strip>>({ table, schemas, access, openApiOperation, handler, catch: catchHandler, }: CoreDeleteOperationOptions<BaseTable, B, TSession>) => import("next-rest-framework").RouteOperationDefinition<"DELETE">;

package/es/backend/route-operation/get-list-operation.d.ts

@@ -1,14 +1,10 @@
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
-import { NextRequest } from "next/server";
 import { ZodSchema } from "zod";
 import { BaseTable, GetListRelations } from "../types.js";
 import { type GetListOperationOptions as CoreGetListOperationOptions } from "./operation-core.js";
-export type GetListOperationOptions<T extends ZodSchema, Q extends ZodSchema, TTable extends BaseTable> = CoreGetListOperationOptions<T, Q, TTable, GetListRelations>;
-export declare const createGetListOperation: ({ db, getSession, }: {
+import type { DefaultSession, SessionGetter } from "./operation-common.js";
+export type GetListOperationOptions<T extends ZodSchema, Q extends ZodSchema, TTable extends BaseTable, TSession = DefaultSession> = CoreGetListOperationOptions<T, Q, TTable, GetListRelations, TSession>;
+export declare const createGetListOperation: <TSession = DefaultSession>({ db, getSession, }: {
     db?: NodePgDatabase<Record<string, unknown>> | undefined;
-    getSession(req: NextRequest): Promise<{
-        userId?: string;
-    } | undefined>;
-}) => <T extends ZodSchema<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>, Q extends ZodSchema<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>>({ schemas, access, table, openApiOperation, relations, jsonArrayFields, setParams, handler, catch: catchHandler, }: CoreGetListOperationOptions<T, Q, BaseTable, GetListRelations, {
-    userId?: string | undefined;
-}>) => import("next-rest-framework").RouteOperationDefinition<"GET">;
+    getSession: SessionGetter<TSession>;
+}) => <T extends ZodSchema<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>, Q extends ZodSchema<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>>({ schemas, access, table, openApiOperation, relations, jsonArrayFields, setParams, handler, catch: catchHandler, }: CoreGetListOperationOptions<T, Q, BaseTable, GetListRelations, TSession>) => import("next-rest-framework").RouteOperationDefinition<"GET">;

package/es/backend/route-operation/get-operation.d.ts

@@ -1,14 +1,10 @@
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
-import { NextRequest } from "next/server";
 import { ZodSchema } from "zod";
 import { BaseTable, GetListRelations } from "../types.js";
 import { type GetOperationOptions as CoreGetOperationOptions } from "./operation-core.js";
-export type GetOperationOptions<T extends ZodSchema, Q extends ZodSchema, TTable extends BaseTable> = CoreGetOperationOptions<T, Q, TTable, GetListRelations>;
-export declare const createGetOperation: ({ getSession, db, }: {
+import type { DefaultSession, SessionGetter } from "./operation-common.js";
+export type GetOperationOptions<T extends ZodSchema, Q extends ZodSchema, TTable extends BaseTable, TSession = DefaultSession> = CoreGetOperationOptions<T, Q, TTable, GetListRelations, TSession>;
+export declare const createGetOperation: <TSession = DefaultSession>({ getSession, db, }: {
     db?: NodePgDatabase<Record<string, unknown>> | undefined;
-    getSession(req: NextRequest): Promise<{
-        userId?: string;
-    } | undefined>;
-}) => <T extends ZodSchema<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>, Q extends ZodSchema<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>>({ schemas, access, table, openApiOperation, relations, setParams, jsonArrayFields, handler, catch: catchHandler, }: CoreGetOperationOptions<T, Q, BaseTable, GetListRelations, {
-    userId?: string | undefined;
-}>) => import("next-rest-framework").RouteOperationDefinition<"GET">;
+    getSession: SessionGetter<TSession>;
+}) => <T extends ZodSchema<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>, Q extends ZodSchema<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>>({ schemas, access, table, openApiOperation, relations, setParams, jsonArrayFields, handler, catch: catchHandler, }: CoreGetOperationOptions<T, Q, BaseTable, GetListRelations, TSession>) => import("next-rest-framework").RouteOperationDefinition<"GET">;

package/es/backend/route-operation/index.d.ts

@@ -4,3 +4,5 @@ export * from "./delete-operation.js";
 export * from "./post-operation.js";
 export * from "./put-operation.js";
 export * from "./open-api-operation.js";
+export type { AccessDenial, AccessOptions, DefaultSession, HttpMethod, SessionGetter, } from "./operation-common.js";
+export type { ScopeCondition, ScopeValue } from "../scope.js";

package/es/backend/route-operation/index.js

@@ -3,4 +3,7 @@ export * from "./get-list-operation.js";
 export * from "./delete-operation.js";
 export * from "./post-operation.js";
 export * from "./put-operation.js";
-export * from "./open-api-operation.js";
+export * from "./open-api-operation.js";
+// 调用方要自己拼 access 预设（把 scope / can / stamp 收在一处复用）就得有这几个类型 ——
+// 不导出的话只能在业务里重写一遍 HttpMethod 之类，两边一旦漂移就是静默的错配。
+export {};

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

@@ -44,6 +44,18 @@ export interface AccessOptions<TSession = DefaultSession> {
         session: TSession;
         method: HttpMethod;
     }) => boolean | AccessDenial | Promise<boolean | AccessDenial>;
+    /**
+     * 新建（POST）时额外要盖在行上的列。归属列由 `scope` 盖，这里管别的服务端字段 ——
+     * 最典型的就是「谁建的」：归属列一旦不是 `creatorId`（比如换成 `ownerId`），作者就没人写了，
+     * 而 `setBody` 只能返回请求体 schema 里有的字段，`creatorId` 不在里面。
+     *
+     * 与归属戳同一条不变量：**最后展开，客户端覆盖不了**。所以这里能安全地盖任何服务端字段，
+     * 不必担心请求体里塞一个同名键把它顶掉。
+     *
+     * 库不替业务猜要盖什么（哪张表有 creatorId、要不要记作者，都是业务的事），所以给的是钩子
+     * 而不是默认行为。
+     */
+    stamp?: (session: TSession) => Record<string, unknown>;
 }
 /**
  * 把会话读取包成「本次请求最多取一次」的取值器。

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

@@ -69,7 +69,8 @@ function _resolveAccess() {
         case 0:
           access = _ref.access, loadSession = _ref.loadSession, method = _ref.method;
           wantsScope = Boolean(access === null || access === void 0 ? void 0 : access.scope) || ((_access$byCreator = access === null || access === void 0 ? void 0 : access.byCreator) !== null && _access$byCreator !== void 0 ? _access$byCreator : true); // 不需要就不取：关掉隔离的路由（多半是公开端点）不该为此白付一次会话读取。
-          if (!(wantsScope || access !== null && access !== void 0 && access.can)) {
+          // stamp 也要会话 —— 它是拿会话算「盖哪些列」的。
+          if (!(wantsScope || access !== null && access !== void 0 && access.can || access !== null && access !== void 0 && access.stamp)) {
             _context.next = 8;
             break;
           }

package/es/backend/route-operation/post-operation.d.ts

@@ -1,14 +1,10 @@
 import { PgTable } from "drizzle-orm/pg-core";
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
-import { NextRequest } from "next/server";
 import { ZodSchema } from "zod";
 import { type PostOperationOptions as CorePostOperationOptions } from "./operation-core.js";
-export type PostOperationOptions<IB extends ZodSchema, OB extends ZodSchema, TTable extends PgTable> = CorePostOperationOptions<IB, OB, TTable>;
-export declare const createPostOperation: ({ getSession, db, }: {
+import type { DefaultSession, SessionGetter } from "./operation-common.js";
+export type PostOperationOptions<IB extends ZodSchema, OB extends ZodSchema, TTable extends PgTable, TSession = DefaultSession> = CorePostOperationOptions<IB, OB, TTable, TSession>;
+export declare const createPostOperation: <TSession = DefaultSession>({ getSession, db, }: {
     db?: NodePgDatabase<Record<string, unknown>> | undefined;
-    getSession(req: NextRequest): Promise<{
-        userId?: string;
-    } | undefined>;
-}) => <IB extends ZodSchema<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>, OB extends ZodSchema<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>>({ schemas, access, contentType, openApiOperation, parseBody, setBody, table, handler, catch: catchHandler, }: CorePostOperationOptions<IB, OB, PgTable<import("drizzle-orm/pg-core").TableConfig>, {
-    userId?: string | undefined;
-}>) => import("next-rest-framework").RouteOperationDefinition<"POST">;
+    getSession: SessionGetter<TSession>;
+}) => <IB extends ZodSchema<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>, OB extends ZodSchema<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>>({ schemas, access, contentType, openApiOperation, parseBody, setBody, table, handler, catch: catchHandler, }: CorePostOperationOptions<IB, OB, PgTable<import("drizzle-orm/pg-core").TableConfig>, TSession>) => import("next-rest-framework").RouteOperationDefinition<"POST">;

package/es/backend/route-operation/put-operation.d.ts

@@ -1,14 +1,10 @@
 import { PgTable } from "drizzle-orm/pg-core";
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
-import { NextRequest } from "next/server";
 import { ZodSchema } from "zod";
 import { type PutOperationOptions as CorePutOperationOptions } from "./operation-core.js";
-export type PutOperationOptions<IB extends ZodSchema, OB extends ZodSchema, TTable extends PgTable> = CorePutOperationOptions<IB, OB, TTable>;
-export declare const createPutOperation: ({ getSession, db, }: {
-    getSession(req: NextRequest): Promise<{
-        userId?: string;
-    } | undefined>;
+import type { DefaultSession, SessionGetter } from "./operation-common.js";
+export type PutOperationOptions<IB extends ZodSchema, OB extends ZodSchema, TTable extends PgTable, TSession = DefaultSession> = CorePutOperationOptions<IB, OB, TTable, TSession>;
+export declare const createPutOperation: <TSession = DefaultSession>({ getSession, db, }: {
+    getSession: SessionGetter<TSession>;
     db?: NodePgDatabase<Record<string, unknown>> | undefined;
-}) => <IB extends ZodSchema<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>, OB extends ZodSchema<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>>({ schemas, access, openApiOperation, table, setBody, handler, catch: catchHandler, }: CorePutOperationOptions<IB, OB, PgTable<import("drizzle-orm/pg-core").TableConfig>, {
-    userId?: string | undefined;
-}>) => import("next-rest-framework").RouteOperationDefinition<"PUT">;
+}) => <IB extends ZodSchema<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>, OB extends ZodSchema<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>>({ schemas, access, openApiOperation, table, setBody, handler, catch: catchHandler, }: CorePutOperationOptions<IB, OB, PgTable<import("drizzle-orm/pg-core").TableConfig>, TSession>) => import("next-rest-framework").RouteOperationDefinition<"PUT">;

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

@@ -48,13 +48,13 @@ 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
       }]).handler( /*#__PURE__*/function () {
         var _ref4 = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime().mark(function _callee(req) {
-          var _yield$resolveAccess, scope, body, extraBody, params, raw, data;
+          var _access$stamp, _access$stamp2, _yield$resolveAccess, scope, session, body, extraBody, stamped, params, raw, data;
           return _regeneratorRuntime().wrap(function _callee$(_context) {
             while (1) switch (_context.prev = _context.next) {
               case 0:
@@ -68,27 +68,31 @@ export function createPostOperationFactory(_ref) {
               case 3:
                 _yield$resolveAccess = _context.sent;
                 scope = _yield$resolveAccess.scope;
-                _context.next = 7;
+                session = _yield$resolveAccess.session;
+                _context.next = 8;
                 return readPostBody(req, {
                   contentType: contentType,
                   parseBody: parseBody
                 });
-              case 7:
+              case 8:
                 body = _context.sent;
-                _context.next = 10;
+                _context.next = 11;
                 return setBody === null || setBody === void 0 ? void 0 : setBody(req);
-              case 10:
+              case 11:
                 _context.t0 = _context.sent;
                 if (_context.t0) {
-                  _context.next = 13;
+                  _context.next = 14;
                   break;
                 }
                 _context.t0 = {};
-              case 13:
+              case 14:
                 extraBody = _context.t0;
                 // 新建的行归属这次请求的作用域。默认情形下作用域就是 creatorId = 当前用户，
                 // 换了归属列（比如 ownerId）时它自动跟着换。
-                // 想再记一个「谁建的」用 setBody 补 —— 那是调用方的语义，库不猜。
+                //
+                // 别的服务端字段（最典型的是「谁建的」）由 access.stamp 盖：归属列一旦不是
+                // creatorId，作者就没人写了，而 setBody 只能返回请求体 schema 里有的字段。
+                // 归属戳排在它后面 —— 两者撞同一个键时以归属为准，那是更强的那条不变量。
                 //
                 // **归属戳必须最后展开**，这是一条安全不变量，别为了「让调用方能覆盖」而调顺序：
                 // `.input({ body })` 只校验、**不替换**请求体（next-rest-framework 交给 handler 的
@@ -96,55 +100,56 @@ export function createPostOperationFactory(_ref) {
                 // schema 过滤。所以只要 body 排在戳后面，客户端在 JSON 里塞一个 `ownerId` /
                 // `creatorId` 就能把行写到别人名下 —— 调用方把该列从 schema 里 omit 掉也拦不住。
                 // 见 __tests__/route-operation-scope-stamp。
-                params = _objectSpread(_objectSpread(_objectSpread({}, body), extraBody), scopeStamp(scope));
+                stamped = session === undefined ? {} : (_access$stamp = access === null || access === void 0 || (_access$stamp2 = access.stamp) === null || _access$stamp2 === void 0 ? void 0 : _access$stamp2.call(access, session)) !== null && _access$stamp !== void 0 ? _access$stamp : {};
+                params = _objectSpread(_objectSpread(_objectSpread(_objectSpread({}, body), extraBody), stamped), scopeStamp(scope));
                 if (!(table && db)) {
-                  _context.next = 21;
+                  _context.next = 23;
                   break;
                 }
-                _context.next = 18;
+                _context.next = 20;
                 return createAction({
                   bodySchema: schemas.body,
                   db: db,
                   table: table
                 })(params);
-              case 18:
+              case 20:
                 _context.t1 = _context.sent[0];
-                _context.next = 22;
+                _context.next = 24;
                 break;
-              case 21:
+              case 23:
                 _context.t1 = params;
-              case 22:
+              case 24:
                 raw = _context.t1;
                 if (!handler) {
-                  _context.next = 29;
+                  _context.next = 31;
                   break;
                 }
-                _context.next = 26;
+                _context.next = 28;
                 return handler({
                   data: raw,
                   params: params,
                   req: req
                 });
-              case 26:
+              case 28:
                 _context.t2 = _context.sent;
-                _context.next = 30;
+                _context.next = 32;
                 break;
-              case 29:
+              case 31:
                 _context.t2 = raw;
-              case 30:
+              case 32:
                 data = _context.t2;
                 return _context.abrupt("return", TypedNextResponse.json(data, {
                   status: 200
                 }));
-              case 34:
-                _context.prev = 34;
+              case 36:
+                _context.prev = 36;
                 _context.t3 = _context["catch"](0);
                 return _context.abrupt("return", handleOperationError(_context.t3, catchHandler));
-              case 37:
+              case 39:
               case "end":
                 return _context.stop();
             }
-          }, _callee, null, [[0, 34]]);
+          }, _callee, null, [[0, 36]]);
         }));
         return function (_x) {
           return _ref4.apply(this, arguments);
@@ -311,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/delete-operation.d.ts

@@ -1,16 +1,12 @@
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
-import { NextRequest } from "next/server";
 import { ZodSchema } from "zod";
 import { BaseTable } from "../types.js";
 import { type DeleteOperationOptions as CoreDeleteOperationOptions } from "./operation-core.js";
-export type DeleteOperationOptions<TTable extends BaseTable, B extends ZodSchema> = CoreDeleteOperationOptions<TTable, B>;
-export declare const createDeleteOperation: ({ db, getSession, }: {
+import type { DefaultSession, SessionGetter } from "./operation-common.js";
+export type DeleteOperationOptions<TTable extends BaseTable, B extends ZodSchema, TSession = DefaultSession> = CoreDeleteOperationOptions<TTable, B, TSession>;
+export declare const createDeleteOperation: <TSession = DefaultSession>({ db, getSession, }: {
     db?: NodePgDatabase<Record<string, unknown>> | undefined;
-    getSession(req: NextRequest): Promise<{
-        userId?: string;
-    } | undefined>;
+    getSession: SessionGetter<TSession>;
 }) => <B extends ZodSchema<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> = import("zod").ZodObject<{
     id: import("zod").ZodString;
-}, import("zod/v4/core").$strip>>({ table, schemas, access, openApiOperation, handler, catch: catchHandler, }: CoreDeleteOperationOptions<BaseTable, B, {
-    userId?: string | undefined;
-}>) => import("next-rest-framework").RouteOperationDefinition<"DELETE">;
+}, import("zod/v4/core").$strip>>({ table, schemas, access, openApiOperation, handler, catch: catchHandler, }: CoreDeleteOperationOptions<BaseTable, B, TSession>) => import("next-rest-framework").RouteOperationDefinition<"DELETE">;

package/lib/backend/route-operation/get-list-operation.d.ts

@@ -1,14 +1,10 @@
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
-import { NextRequest } from "next/server";
 import { ZodSchema } from "zod";
 import { BaseTable, GetListRelations } from "../types.js";
 import { type GetListOperationOptions as CoreGetListOperationOptions } from "./operation-core.js";
-export type GetListOperationOptions<T extends ZodSchema, Q extends ZodSchema, TTable extends BaseTable> = CoreGetListOperationOptions<T, Q, TTable, GetListRelations>;
-export declare const createGetListOperation: ({ db, getSession, }: {
+import type { DefaultSession, SessionGetter } from "./operation-common.js";
+export type GetListOperationOptions<T extends ZodSchema, Q extends ZodSchema, TTable extends BaseTable, TSession = DefaultSession> = CoreGetListOperationOptions<T, Q, TTable, GetListRelations, TSession>;
+export declare const createGetListOperation: <TSession = DefaultSession>({ db, getSession, }: {
     db?: NodePgDatabase<Record<string, unknown>> | undefined;
-    getSession(req: NextRequest): Promise<{
-        userId?: string;
-    } | undefined>;
-}) => <T extends ZodSchema<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>, Q extends ZodSchema<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>>({ schemas, access, table, openApiOperation, relations, jsonArrayFields, setParams, handler, catch: catchHandler, }: CoreGetListOperationOptions<T, Q, BaseTable, GetListRelations, {
-    userId?: string | undefined;
-}>) => import("next-rest-framework").RouteOperationDefinition<"GET">;
+    getSession: SessionGetter<TSession>;
+}) => <T extends ZodSchema<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>, Q extends ZodSchema<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>>({ schemas, access, table, openApiOperation, relations, jsonArrayFields, setParams, handler, catch: catchHandler, }: CoreGetListOperationOptions<T, Q, BaseTable, GetListRelations, TSession>) => import("next-rest-framework").RouteOperationDefinition<"GET">;

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

@@ -1,14 +1,10 @@
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
-import { NextRequest } from "next/server";
 import { ZodSchema } from "zod";
 import { BaseTable, GetListRelations } from "../types.js";
 import { type GetOperationOptions as CoreGetOperationOptions } from "./operation-core.js";
-export type GetOperationOptions<T extends ZodSchema, Q extends ZodSchema, TTable extends BaseTable> = CoreGetOperationOptions<T, Q, TTable, GetListRelations>;
-export declare const createGetOperation: ({ getSession, db, }: {
+import type { DefaultSession, SessionGetter } from "./operation-common.js";
+export type GetOperationOptions<T extends ZodSchema, Q extends ZodSchema, TTable extends BaseTable, TSession = DefaultSession> = CoreGetOperationOptions<T, Q, TTable, GetListRelations, TSession>;
+export declare const createGetOperation: <TSession = DefaultSession>({ getSession, db, }: {
     db?: NodePgDatabase<Record<string, unknown>> | undefined;
-    getSession(req: NextRequest): Promise<{
-        userId?: string;
-    } | undefined>;
-}) => <T extends ZodSchema<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>, Q extends ZodSchema<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>>({ schemas, access, table, openApiOperation, relations, setParams, jsonArrayFields, handler, catch: catchHandler, }: CoreGetOperationOptions<T, Q, BaseTable, GetListRelations, {
-    userId?: string | undefined;
-}>) => import("next-rest-framework").RouteOperationDefinition<"GET">;
+    getSession: SessionGetter<TSession>;
+}) => <T extends ZodSchema<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>, Q extends ZodSchema<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>>({ schemas, access, table, openApiOperation, relations, setParams, jsonArrayFields, handler, catch: catchHandler, }: CoreGetOperationOptions<T, Q, BaseTable, GetListRelations, TSession>) => import("next-rest-framework").RouteOperationDefinition<"GET">;

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

@@ -4,3 +4,5 @@ export * from "./delete-operation.js";
 export * from "./post-operation.js";
 export * from "./put-operation.js";
 export * from "./open-api-operation.js";
+export type { AccessDenial, AccessOptions, DefaultSession, HttpMethod, SessionGetter, } from "./operation-common.js";
+export type { ScopeCondition, ScopeValue } from "../scope.js";

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

@@ -44,6 +44,18 @@ export interface AccessOptions<TSession = DefaultSession> {
         session: TSession;
         method: HttpMethod;
     }) => boolean | AccessDenial | Promise<boolean | AccessDenial>;
+    /**
+     * 新建（POST）时额外要盖在行上的列。归属列由 `scope` 盖，这里管别的服务端字段 ——
+     * 最典型的就是「谁建的」：归属列一旦不是 `creatorId`（比如换成 `ownerId`），作者就没人写了，
+     * 而 `setBody` 只能返回请求体 schema 里有的字段，`creatorId` 不在里面。
+     *
+     * 与归属戳同一条不变量：**最后展开，客户端覆盖不了**。所以这里能安全地盖任何服务端字段，
+     * 不必担心请求体里塞一个同名键把它顶掉。
+     *
+     * 库不替业务猜要盖什么（哪张表有 creatorId、要不要记作者，都是业务的事），所以给的是钩子
+     * 而不是默认行为。
+     */
+    stamp?: (session: TSession) => Record<string, unknown>;
 }
 /**
  * 把会话读取包成「本次请求最多取一次」的取值器。

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

@@ -42,7 +42,7 @@ async function resolveAccess({
 }) {
   var _a;
   const wantsScope = Boolean(access == null ? void 0 : access.scope) || ((access == null ? void 0 : access.byCreator) ?? true);
-  const session = wantsScope || (access == null ? void 0 : access.can) ? await loadSession() : void 0;
+  const session = wantsScope || (access == null ? void 0 : access.can) || (access == null ? void 0 : access.stamp) ? await loadSession() : void 0;
   if (access == null ? void 0 : access.can) {
     if (!session) {
       throw new import_errors.HttpError(401, "未登录");

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

@@ -1,14 +1,10 @@
 import { PgTable } from "drizzle-orm/pg-core";
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
-import { NextRequest } from "next/server";
 import { ZodSchema } from "zod";
 import { type PostOperationOptions as CorePostOperationOptions } from "./operation-core.js";
-export type PostOperationOptions<IB extends ZodSchema, OB extends ZodSchema, TTable extends PgTable> = CorePostOperationOptions<IB, OB, TTable>;
-export declare const createPostOperation: ({ getSession, db, }: {
+import type { DefaultSession, SessionGetter } from "./operation-common.js";
+export type PostOperationOptions<IB extends ZodSchema, OB extends ZodSchema, TTable extends PgTable, TSession = DefaultSession> = CorePostOperationOptions<IB, OB, TTable, TSession>;
+export declare const createPostOperation: <TSession = DefaultSession>({ getSession, db, }: {
     db?: NodePgDatabase<Record<string, unknown>> | undefined;
-    getSession(req: NextRequest): Promise<{
-        userId?: string;
-    } | undefined>;
-}) => <IB extends ZodSchema<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>, OB extends ZodSchema<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>>({ schemas, access, contentType, openApiOperation, parseBody, setBody, table, handler, catch: catchHandler, }: CorePostOperationOptions<IB, OB, PgTable<import("drizzle-orm/pg-core").TableConfig>, {
-    userId?: string | undefined;
-}>) => import("next-rest-framework").RouteOperationDefinition<"POST">;
+    getSession: SessionGetter<TSession>;
+}) => <IB extends ZodSchema<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>, OB extends ZodSchema<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>>({ schemas, access, contentType, openApiOperation, parseBody, setBody, table, handler, catch: catchHandler, }: CorePostOperationOptions<IB, OB, PgTable<import("drizzle-orm/pg-core").TableConfig>, TSession>) => import("next-rest-framework").RouteOperationDefinition<"POST">;

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

@@ -1,14 +1,10 @@
 import { PgTable } from "drizzle-orm/pg-core";
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
-import { NextRequest } from "next/server";
 import { ZodSchema } from "zod";
 import { type PutOperationOptions as CorePutOperationOptions } from "./operation-core.js";
-export type PutOperationOptions<IB extends ZodSchema, OB extends ZodSchema, TTable extends PgTable> = CorePutOperationOptions<IB, OB, TTable>;
-export declare const createPutOperation: ({ getSession, db, }: {
-    getSession(req: NextRequest): Promise<{
-        userId?: string;
-    } | undefined>;
+import type { DefaultSession, SessionGetter } from "./operation-common.js";
+export type PutOperationOptions<IB extends ZodSchema, OB extends ZodSchema, TTable extends PgTable, TSession = DefaultSession> = CorePutOperationOptions<IB, OB, TTable, TSession>;
+export declare const createPutOperation: <TSession = DefaultSession>({ getSession, db, }: {
+    getSession: SessionGetter<TSession>;
     db?: NodePgDatabase<Record<string, unknown>> | undefined;
-}) => <IB extends ZodSchema<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>, OB extends ZodSchema<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>>({ schemas, access, openApiOperation, table, setBody, handler, catch: catchHandler, }: CorePutOperationOptions<IB, OB, PgTable<import("drizzle-orm/pg-core").TableConfig>, {
-    userId?: string | undefined;
-}>) => import("next-rest-framework").RouteOperationDefinition<"PUT">;
+}) => <IB extends ZodSchema<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>, OB extends ZodSchema<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>>({ schemas, access, openApiOperation, table, setBody, handler, catch: catchHandler, }: CorePutOperationOptions<IB, OB, PgTable<import("drizzle-orm/pg-core").TableConfig>, TSession>) => import("next-rest-framework").RouteOperationDefinition<"PUT">;

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

@@ -57,20 +57,27 @@ 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
     }
   ]).handler(async (req) => {
+    var _a;
     try {
-      const { scope } = await (0, import_operation_common.resolveAccess)({
+      const { scope, session } = await (0, import_operation_common.resolveAccess)({
         access,
         loadSession: (0, import_operation_common.sessionLoader)(getSession, req),
         method: "POST"
       });
       const body = await (0, import_operation_common.readPostBody)(req, { contentType, parseBody });
       const extraBody = await (setBody == null ? void 0 : setBody(req)) || {};
-      const params = { ...body, ...extraBody, ...scopeStamp(scope) };
+      const stamped = session === void 0 ? {} : ((_a = access == null ? void 0 : access.stamp) == null ? void 0 : _a.call(access, session)) ?? {};
+      const params = {
+        ...body,
+        ...extraBody,
+        ...stamped,
+        ...scopeStamp(scope)
+      };
       const raw = table && db ? (await createAction({
         bodySchema: schemas.body,
         db,
@@ -149,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.1.3",
+  "version": "0.3.0",
   "description": "AI0x0 utils",
   "keywords": [
     "ai0x0"