@ai0x0/utils 0.0.47 → 0.0.48

package/.agents/skills/ai0x0-utils/backend/SKILL.md

@@ -36,7 +36,7 @@ The bundled ESLint preset treats every custom rule as an error. Backend examples
 - Use braces for every control-flow block because `curly` is enabled as `error`.
 - Keep route files thin. Put reusable logic in `utils/actions/<resource>.ts` instead of exporting helpers from `route.ts`.
 - For files with 150+ lines, add the three-line `===` section divider blocks described in the `nextjs` skill.
-- Avoid `try/catch` in route handlers; use `onError` or the factory default error handling.
+- Avoid `try/catch` in route handlers; use `catch` or the factory default error handling.
 
 ## Project Setup
 
@@ -87,24 +87,22 @@ export const getListOperation = createGetListOperation({ db, getSession });
 
 ## Factory Catalog
 
-| Export              | Purpose                    | Required options            | Notable optional options                                                                                                     |
-| ------------------- | -------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| `createTableSchema` | pg `Table` + 5 zod schemas | `name`, `columns`           | `refineSchema`, `extraConfig`                                                                                                |
-| `getOperation`      | GET one by filters         | `bodySchema`, `querySchema` | `table`, `setParams`, `relations`, `jsonArrayFields`, `byCreator`, `onSuccess`, `onError`, `summary`, `description`, `tags`  |
-| `getListOperation`  | GET paginated list         | `bodySchema`, `querySchema` | `table`, `setParams`, `relations`, `jsonArrayFields`, `onSuccess`, `onError`, `summary`, `description`, `tags`               |
-| `postOperation`     | POST create                | `bodySchema`                | `table`, `contentType`, `parseBody`, `outputBodySchema`, `setBody`, `onSuccess`, `onError`, `summary`, `description`, `tags` |
-| `putOperation`      | PUT update                 | `bodySchema`                | `table`, `outputBodySchema`, `setBody`, `byCreator`, `onSuccess`, `onError`, `summary`, `description`, `tags`                |
-| `deleteOperation`   | DELETE                     | —                           | `table`, `byCreator`, `onSuccess`, `onError`, `summary`, `description`, `tags`                                               |
+| Export              | Purpose                    | Required options                    | Notable optional options                                                                                         |
+| ------------------- | -------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `createTableSchema` | pg `Table` + 5 zod schemas | `name`, `columns`                   | `refineSchema`, `extraConfig`                                                                                    |
+| `getOperation`      | GET one by filters         | `schemas.query`, `schemas.response` | `table`, `setParams`, `relations`, `jsonArrayFields`, `access.byCreator`, `handler`, `catch`, `openApiOperation` |
+| `getListOperation`  | GET paginated list         | `schemas.query`, `schemas.response` | `table`, `setParams`, `relations`, `jsonArrayFields`, `handler`, `catch`, `openApiOperation`                     |
+| `postOperation`     | POST create                | `schemas.body`                      | `table`, `contentType`, `parseBody`, `schemas.response`, `setBody`, `handler`, `catch`, `openApiOperation`       |
+| `putOperation`      | PUT update                 | `schemas.body`                      | `table`, `schemas.response`, `setBody`, `access.byCreator`, `handler`, `catch`, `openApiOperation`               |
+| `deleteOperation`   | DELETE                     | —                                   | `table`, `schemas.body`, `access.byCreator`, `handler`, `catch`, `openApiOperation`                              |
 
-`tags` can be passed manually to override the default OpenAPI tag inferred from `table`.
-
-`summary` and `description` are forwarded into the OpenAPI operation object.
+`openApiOperation` is spread directly into the `next-rest-framework` operation metadata. Use it for `summary`, `description`, `tags`, `deprecated`, `security`, `externalDocs`, and future OpenAPI operation fields. When omitted, `tags` defaults to the table name when `table` is supplied.
 
 `postOperation` defaults to `contentType: "application/json"`. Pass `contentType: "multipart/form-data"` to read `await req.formData()` as body, or pass both a custom `contentType` and `parseBody(req)` for custom payload parsing.
 
-In `postOperation` and `putOperation`, `onSuccess({ params })` is typed from `bodySchema` plus the injected `creatorId` / `editorId`, so custom action helpers can usually consume `params` directly without reparsing the body schema.
+In `postOperation` and `putOperation`, `handler({ params })` is typed from `schemas.body` plus the injected `creatorId` / `editorId`, so custom action helpers can usually consume `params` directly without reparsing the body schema.
 
-`table` and factory-level `db` are optional for route operations. When `table` is omitted or `db` is not provided, the operation still parses input, applies `setParams` / `setBody`, session-derived fields, and `onSuccess`, but skips the built-in table action (`select` / `insert` / `update` / `delete`). Use this for custom endpoints that want the same OpenAPI and response wiring without a direct table operation.
+`table` and factory-level `db` are optional for route operations. When `table` is omitted or `db` is not provided, the operation still parses input, applies `setParams` / `setBody`, session-derived fields, and `handler`, but skips the built-in table action (`select` / `insert` / `update` / `delete`). Use this for custom endpoints that want the same OpenAPI and response wiring without a direct table operation.
 
 ## Canonical Examples
 
@@ -168,7 +166,7 @@ export const queryListAgentSchema = queryListSchema(
 export const queryListSelectAgentSchema = selectAgentSchema;
 ```
 
-Note the two-layer shape: `queryListSchema(...)` input is the **partial of the select schema** (optionally merged with extra querystring-only fields); `bodySchema` in `getListOperation` stays as the full select schema (`queryListSelectAgentSchema`).
+Note the two-layer shape: `queryListSchema(...)` input is the **partial of the select schema** (optionally merged with extra querystring-only fields); `schemas.response` in `getListOperation` stays as the full select schema (`queryListSelectAgentSchema`).
 
 ### 2. Detail CRUD route
 
@@ -193,10 +191,12 @@ import { seedAgentData } from "@backend/utils/actions";
 
 export const { POST, GET, DELETE, PUT } = route({
   getAgent: getOperation({
-    querySchema: queryAgentSchema,
-    bodySchema: selectAgentSchema,
+    schemas: {
+      query: queryAgentSchema,
+      response: selectAgentSchema,
+    },
     table: agents,
-    summary: "助手详情",
+    openApiOperation: { summary: "助手详情" },
     setParams: async (req) => {
       const { userId } = (await getSession(req)) || {};
       await seedAgentData(userId as string);
@@ -204,24 +204,24 @@ export const { POST, GET, DELETE, PUT } = route({
     },
   }),
   postAgent: postOperation({
-    bodySchema: insertAgentSchema,
+    schemas: { body: insertAgentSchema },
     table: agents,
-    summary: "添加助手",
+    openApiOperation: { summary: "添加助手" },
     setBody: async () => ({ tags: ["my"] }),
   }),
   putAgent: putOperation({
-    bodySchema: updateAgentSchema,
+    schemas: { body: updateAgentSchema },
     table: agents,
-    summary: "编辑助手",
+    openApiOperation: { summary: "编辑助手" },
   }),
   deleteAgent: deleteOperation({
     table: agents,
-    summary: "删除助手",
+    openApiOperation: { summary: "删除助手" },
   }),
 });
 ```
 
-### 3. List route with relations + `onSuccess` tree building
+### 3. List route with relations + `handler` tree building
 
 ```ts
 // app/(backend)/api/channel/list/route.ts
@@ -239,10 +239,12 @@ import { seedChannelData } from "@backend/utils/actions/channel";
 
 export const { GET } = route({
   getChannelList: getListOperation({
-    querySchema: queryListChannelSchema,
-    bodySchema: queryListSelectChannelSchema,
+    schemas: {
+      query: queryListChannelSchema,
+      response: queryListSelectChannelSchema,
+    },
     table: channels,
-    summary: "获取渠道列表",
+    openApiOperation: { summary: "获取渠道列表" },
     relations: [
       {
         table: models,
@@ -261,9 +263,9 @@ export const { GET } = route({
       await seedChannelData(userId as string);
       return {};
     },
-    onSuccess: async (result) => {
+    handler: async ({ data }) => {
       // 内部字段过滤 / 映射 / 树化都写在这里
-      return result;
+      return data;
     },
   }),
 });
@@ -328,8 +330,8 @@ export const { GET } = route({
 ## Built-in Conventions
 
 - **Base fields** auto-added by `createTableSchema`: `id` (uuid, pk, default random) / `creatorId` / `editorId` / `accessedAt` / `createdAt` / `updatedAt`.
-- **Ownership check**: with `byCreator: true` (default on PUT/DELETE/GET), PUT/DELETE pre-fetch the row filtered by `creatorId = session.userId` and throw `"未找到…对象，或没有权限"` if missing. Set `byCreator: false` to skip (e.g. admin endpoints).
-- **Auto injection**: POST writes `creatorId = session.userId`; PUT writes `editorId = session.userId`; GET/GET_LIST append `creatorId = session.userId` to the filter when `byCreator` is on.
+- **Ownership check**: with `access: { byCreator: true }` (default on PUT/DELETE/GET), PUT/DELETE pre-fetch the row filtered by `creatorId = session.userId` and throw `"未找到…对象，或没有权限"` if missing. Set `access: { byCreator: false }` to skip (e.g. admin endpoints).
+- **Auto injection**: POST writes `creatorId = session.userId`; PUT writes `editorId = session.userId`; GET/GET_LIST append `creatorId = session.userId` to the filter when `access.byCreator` is on.
 - **Date coercion**: any body field ending in `At` is passed through `dayjs(value).toDate()` before write — accept ISO strings from clients.
 - **List filtering** (all querystring values are strings):
   - `key=a,b,c` → `IN (...)` when key ends with `Id`; otherwise `OR ILIKE %a% OR ILIKE %b%`
@@ -342,20 +344,20 @@ export const { GET } = route({
 ## Guardrails
 
 - Always pass `insertXxxSchema` to POST, `updateXxxSchema` (has `.required({ id: true })`) to PUT, `selectXxxSchema` to GET body, `queryListSchema(selectXxxSchema.partial())` to GET_LIST query.
-- Query-string schemas stay `z.string()` — numbers / arrays from querystrings must stay strings and be parsed inside `onSuccess` or `setParams`.
+- Query-string schemas stay `z.string()` — numbers / arrays from querystrings must stay strings and be parsed inside `handler` or `setParams`.
 - Do not reuse `insertSchema` for PUT — missing `id` silently dispatches an update without a where clause.
-- `bodySchema` on list/get is the **response item** schema, not the query shape. Query shape goes in `querySchema`.
+- `schemas.response` on list/get is the **response item** schema, not the query shape. Query shape goes in `schemas.query`.
 - Do not inline `{ db, getSession }` into individual route files — always import the pre-bound `postOperation` / `getListOperation` / … from `@backend/utils/route-operation` so session/DB swaps are one-file changes.
 - `jsonb` columns declared with `jsonb(...)` carry no zod info — extend the matching insert/select schema with `.merge(z.object({ field: z.array(z.string()).optional() }))` to keep typing accurate.
-- Swallowing errors: an unhandled throw in a handler propagates to next-rest-framework as a 500. Provide `onError` for any operation exposed to untrusted clients.
+- Swallowing errors: an unhandled throw in a handler propagates to next-rest-framework as a 500. Provide `catch` for any operation exposed to untrusted clients.
 - For non-CRUD behavior (middleware chains, streaming, custom `TypedNextResponse` unions, RPC) stop using these factories and switch to the `create-next-rest-framework-api` skill.
 
 ## Escape Hatches
 
 - Extra server-side filters — `setParams(req) => Promise<Record<string, unknown>>` on GET/GET_LIST; returned keys are merged into the filter.
-- Extra columns on write — `setBody(req) => Promise<Partial<infer<IB>>>` on POST/PUT; returned fields are merged into the body before validation runs against `bodySchema`.
-- Post-processing output — `onSuccess({ params, data, req }) => Promise<data>`; POST/PUT params are inferred from `bodySchema`, and on GET_LIST `data` is `{ data, total }`.
-- Error rewriting — `onError(err) => Promise<Response | undefined>`. Return `undefined` to rethrow.
+- Extra columns on write — `setBody(req) => Promise<Partial<infer<IB>>>` on POST/PUT; returned fields are merged into the body before validation runs against `schemas.body`.
+- Post-processing output — `handler({ params, data, req }) => Promise<data>`; POST/PUT params are inferred from `schemas.body`, and on GET_LIST `data` is `{ data, total }`.
+- Error rewriting — `catch(err) => Promise<Response | undefined>`. Return `undefined` to rethrow.
 
 ## Imports
 
@@ -373,6 +375,6 @@ ESM consumers can substitute `/es/backend/...` instead of `/lib/backend/...` whe
 - Route files contain zero hand-written `{ db, getSession }` wiring; all operations come from `@backend/utils/route-operation`.
 - Each domain has a `table.ts` (columns + `createTableSchema`) and an `index.ts` (five zod schemas + re-exports).
 - Every list endpoint accepts `current / pageSize / orderBy / orderDir / *AtFrom / *AtTo` and — where applicable — `jsonArrayFields` is declared.
-- `byCreator` is explicitly set when the endpoint is admin-facing or otherwise crosses ownership boundaries.
+- `access.byCreator` is explicitly set when the endpoint is admin-facing or otherwise crosses ownership boundaries.
 - Non-CRUD endpoints are implemented via raw `routeOperation` + action helpers, not by forcing a CRUD factory.
 - `next-rest-framework validate` / `generate` (from the partner skill) still pass — the factory values are plain `RouteOperationDefinition` and participate in OpenAPI generation.

package/SKILL.md

@@ -66,24 +66,22 @@ export const getListOperation = createGetListOperation({ db, getSession });
 
 ## Factory Catalog
 
-| Export              | Purpose                    | Required options            | Notable optional options                                                                                                     |
-| ------------------- | -------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| `createTableSchema` | pg `Table` + 5 zod schemas | `name`, `columns`           | `refineSchema`, `extraConfig`                                                                                                |
-| `getOperation`      | GET one by filters         | `bodySchema`, `querySchema` | `table`, `setParams`, `relations`, `jsonArrayFields`, `byCreator`, `onSuccess`, `onError`, `summary`, `description`, `tags`  |
-| `getListOperation`  | GET paginated list         | `bodySchema`, `querySchema` | `table`, `setParams`, `relations`, `jsonArrayFields`, `onSuccess`, `onError`, `summary`, `description`, `tags`               |
-| `postOperation`     | POST create                | `bodySchema`                | `table`, `contentType`, `parseBody`, `outputBodySchema`, `setBody`, `onSuccess`, `onError`, `summary`, `description`, `tags` |
-| `putOperation`      | PUT update                 | `bodySchema`                | `table`, `outputBodySchema`, `setBody`, `byCreator`, `onSuccess`, `onError`, `summary`, `description`, `tags`                |
-| `deleteOperation`   | DELETE                     | —                           | `table`, `byCreator`, `onSuccess`, `onError`, `summary`, `description`, `tags`                                               |
+| Export              | Purpose                    | Required options                    | Notable optional options                                                                                         |
+| ------------------- | -------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `createTableSchema` | pg `Table` + 5 zod schemas | `name`, `columns`                   | `refineSchema`, `extraConfig`                                                                                    |
+| `getOperation`      | GET one by filters         | `schemas.query`, `schemas.response` | `table`, `setParams`, `relations`, `jsonArrayFields`, `access.byCreator`, `handler`, `catch`, `openApiOperation` |
+| `getListOperation`  | GET paginated list         | `schemas.query`, `schemas.response` | `table`, `setParams`, `relations`, `jsonArrayFields`, `handler`, `catch`, `openApiOperation`                     |
+| `postOperation`     | POST create                | `schemas.body`                      | `table`, `contentType`, `parseBody`, `schemas.response`, `setBody`, `handler`, `catch`, `openApiOperation`       |
+| `putOperation`      | PUT update                 | `schemas.body`                      | `table`, `schemas.response`, `setBody`, `access.byCreator`, `handler`, `catch`, `openApiOperation`               |
+| `deleteOperation`   | DELETE                     | —                                   | `table`, `schemas.body`, `access.byCreator`, `handler`, `catch`, `openApiOperation`                              |
 
-`tags` can be passed manually to override the default OpenAPI tag inferred from `table`.
-
-`summary` and `description` are forwarded into the OpenAPI operation object.
+`openApiOperation` is spread directly into the `next-rest-framework` operation metadata. Use it for `summary`, `description`, `tags`, `deprecated`, `security`, `externalDocs`, and future OpenAPI operation fields. When omitted, `tags` defaults to the table name when `table` is supplied.
 
 `postOperation` defaults to `contentType: "application/json"`. Pass `contentType: "multipart/form-data"` to read `await req.formData()` as body, or pass both a custom `contentType` and `parseBody(req)` for custom payload parsing.
 
-In `postOperation` and `putOperation`, `onSuccess({ params })` is typed from `bodySchema` plus the injected `creatorId` / `editorId`, so custom action helpers can usually consume `params` directly without reparsing the body schema.
+In `postOperation` and `putOperation`, `handler({ params })` is typed from `schemas.body` plus the injected `creatorId` / `editorId`, so custom action helpers can usually consume `params` directly without reparsing the body schema.
 
-`table` and factory-level `db` are optional for route operations. When `table` is omitted or `db` is not provided, the operation still parses input, applies `setParams` / `setBody`, session-derived fields, and `onSuccess`, but skips the built-in table action (`select` / `insert` / `update` / `delete`). Use this for custom endpoints that want the same OpenAPI and response wiring without a direct table operation.
+`table` and factory-level `db` are optional for route operations. When `table` is omitted or `db` is not provided, the operation still parses input, applies `setParams` / `setBody`, session-derived fields, and `handler`, but skips the built-in table action (`select` / `insert` / `update` / `delete`). Use this for custom endpoints that want the same OpenAPI and response wiring without a direct table operation.
 
 ## Canonical Examples
 
@@ -147,7 +145,7 @@ export const queryListAgentSchema = queryListSchema(
 export const queryListSelectAgentSchema = selectAgentSchema;
 ```
 
-Note the two-layer shape: `queryListSchema(...)` input is the **partial of the select schema** (optionally merged with extra querystring-only fields); `bodySchema` in `getListOperation` stays as the full select schema (`queryListSelectAgentSchema`).
+Note the two-layer shape: `queryListSchema(...)` input is the **partial of the select schema** (optionally merged with extra querystring-only fields); `schemas.response` in `getListOperation` stays as the full select schema (`queryListSelectAgentSchema`).
 
 ### 2. Detail CRUD route
 
@@ -172,10 +170,12 @@ import { seedAgentData } from "@backend/utils/actions";
 
 export const { POST, GET, DELETE, PUT } = route({
   getAgent: getOperation({
-    querySchema: queryAgentSchema,
-    bodySchema: selectAgentSchema,
+    schemas: {
+      query: queryAgentSchema,
+      response: selectAgentSchema,
+    },
     table: agents,
-    summary: "助手详情",
+    openApiOperation: { summary: "助手详情" },
     setParams: async (req) => {
       const { userId } = (await getSession(req)) || {};
       await seedAgentData(userId as string);
@@ -183,24 +183,24 @@ export const { POST, GET, DELETE, PUT } = route({
     },
   }),
   postAgent: postOperation({
-    bodySchema: insertAgentSchema,
+    schemas: { body: insertAgentSchema },
     table: agents,
-    summary: "添加助手",
+    openApiOperation: { summary: "添加助手" },
     setBody: async () => ({ tags: ["my"] }),
   }),
   putAgent: putOperation({
-    bodySchema: updateAgentSchema,
+    schemas: { body: updateAgentSchema },
     table: agents,
-    summary: "编辑助手",
+    openApiOperation: { summary: "编辑助手" },
   }),
   deleteAgent: deleteOperation({
     table: agents,
-    summary: "删除助手",
+    openApiOperation: { summary: "删除助手" },
   }),
 });
 ```
 
-### 3. List route with relations + `onSuccess` tree building
+### 3. List route with relations + `handler` tree building
 
 ```ts
 // app/(backend)/api/channel/list/route.ts
@@ -218,10 +218,12 @@ import { seedChannelData } from "@backend/utils/actions/channel";
 
 export const { GET } = route({
   getChannelList: getListOperation({
-    querySchema: queryListChannelSchema,
-    bodySchema: queryListSelectChannelSchema,
+    schemas: {
+      query: queryListChannelSchema,
+      response: queryListSelectChannelSchema,
+    },
     table: channels,
-    summary: "获取渠道列表",
+    openApiOperation: { summary: "获取渠道列表" },
     relations: [
       {
         table: models,
@@ -240,9 +242,9 @@ export const { GET } = route({
       await seedChannelData(userId as string);
       return {};
     },
-    onSuccess: async (result) => {
+    handler: async ({ data }) => {
       // 内部字段过滤 / 映射 / 树化都写在这里
-      return result;
+      return data;
     },
   }),
 });
@@ -307,8 +309,8 @@ export const { GET } = route({
 ## Built-in Conventions
 
 - **Base fields** auto-added by `createTableSchema`: `id` (uuid, pk, default random) / `creatorId` / `editorId` / `accessedAt` / `createdAt` / `updatedAt`.
-- **Ownership check**: with `byCreator: true` (default on PUT/DELETE/GET), PUT/DELETE pre-fetch the row filtered by `creatorId = session.userId` and throw `"未找到…对象，或没有权限"` if missing. Set `byCreator: false` to skip (e.g. admin endpoints).
-- **Auto injection**: POST writes `creatorId = session.userId`; PUT writes `editorId = session.userId`; GET/GET_LIST append `creatorId = session.userId` to the filter when `byCreator` is on.
+- **Ownership check**: with `access: { byCreator: true }` (default on PUT/DELETE/GET), PUT/DELETE pre-fetch the row filtered by `creatorId = session.userId` and throw `"未找到…对象，或没有权限"` if missing. Set `access: { byCreator: false }` to skip (e.g. admin endpoints).
+- **Auto injection**: POST writes `creatorId = session.userId`; PUT writes `editorId = session.userId`; GET/GET_LIST append `creatorId = session.userId` to the filter when `access.byCreator` is on.
 - **Date coercion**: any body field ending in `At` is passed through `dayjs(value).toDate()` before write — accept ISO strings from clients.
 - **List filtering** (all querystring values are strings):
   - `key=a,b,c` → `IN (...)` when key ends with `Id`; otherwise `OR ILIKE %a% OR ILIKE %b%`
@@ -321,20 +323,20 @@ export const { GET } = route({
 ## Guardrails
 
 - Always pass `insertXxxSchema` to POST, `updateXxxSchema` (has `.required({ id: true })`) to PUT, `selectXxxSchema` to GET body, `queryListSchema(selectXxxSchema.partial())` to GET_LIST query.
-- Query-string schemas stay `z.string()` — numbers / arrays from querystrings must stay strings and be parsed inside `onSuccess` or `setParams`.
+- Query-string schemas stay `z.string()` — numbers / arrays from querystrings must stay strings and be parsed inside `handler` or `setParams`.
 - Do not reuse `insertSchema` for PUT — missing `id` silently dispatches an update without a where clause.
-- `bodySchema` on list/get is the **response item** schema, not the query shape. Query shape goes in `querySchema`.
+- `schemas.response` on list/get is the **response item** schema, not the query shape. Query shape goes in `schemas.query`.
 - Do not inline `{ db, getSession }` into individual route files — always import the pre-bound `postOperation` / `getListOperation` / … from `@backend/utils/route-operation` so session/DB swaps are one-file changes.
 - `jsonb` columns declared with `jsonb(...)` carry no zod info — extend the matching insert/select schema with `.merge(z.object({ field: z.array(z.string()).optional() }))` to keep typing accurate.
-- Swallowing errors: an unhandled throw in a handler propagates to next-rest-framework as a 500. Provide `onError` for any operation exposed to untrusted clients.
+- Swallowing errors: an unhandled throw in a handler propagates to next-rest-framework as a 500. Provide `catch` for any operation exposed to untrusted clients.
 - For non-CRUD behavior (middleware chains, streaming, custom `TypedNextResponse` unions, RPC) stop using these factories and switch to the `create-next-rest-framework-api` skill.
 
 ## Escape Hatches
 
 - Extra server-side filters — `setParams(req) => Promise<Record<string, unknown>>` on GET/GET_LIST; returned keys are merged into the filter.
-- Extra columns on write — `setBody(req) => Promise<Partial<infer<IB>>>` on POST/PUT; returned fields are merged into the body before validation runs against `bodySchema`.
-- Post-processing output — `onSuccess({ params, data, req }) => Promise<data>`; POST/PUT params are inferred from `bodySchema`, and on GET_LIST `data` is `{ data, total }`.
-- Error rewriting — `onError(err) => Promise<Response | undefined>`. Return `undefined` to rethrow.
+- Extra columns on write — `setBody(req) => Promise<Partial<infer<IB>>>` on POST/PUT; returned fields are merged into the body before validation runs against `schemas.body`.
+- Post-processing output — `handler({ params, data, req }) => Promise<data>`; POST/PUT params are inferred from `schemas.body`, and on GET_LIST `data` is `{ data, total }`.
+- Error rewriting — `catch(err) => Promise<Response | undefined>`. Return `undefined` to rethrow.
 
 ## Imports
 
@@ -352,6 +354,6 @@ ESM consumers can substitute `/es/backend/...` instead of `/lib/backend/...` whe
 - Route files contain zero hand-written `{ db, getSession }` wiring; all operations come from `@backend/utils/route-operation`.
 - Each domain has a `table.ts` (columns + `createTableSchema`) and an `index.ts` (five zod schemas + re-exports).
 - Every list endpoint accepts `current / pageSize / orderBy / orderDir / *AtFrom / *AtTo` and — where applicable — `jsonArrayFields` is declared.
-- `byCreator` is explicitly set when the endpoint is admin-facing or otherwise crosses ownership boundaries.
+- `access.byCreator` is explicitly set when the endpoint is admin-facing or otherwise crosses ownership boundaries.
 - Non-CRUD endpoints are implemented via raw `routeOperation` + action helpers, not by forcing a CRUD factory.
 - `next-rest-framework validate` / `generate` (from the partner skill) still pass — the factory values are plain `RouteOperationDefinition` and participate in OpenAPI generation.

package/es/__shims__/next-rest-framework.d.ts

@@ -23,7 +23,9 @@ declare module "next-rest-framework" {
   export const routeOperation: <M extends string>(opts: {
     method: M;
     openApiOperation?: {
+      deprecated?: boolean;
       description?: string;
+      security?: unknown[];
       summary?: string;
       tags?: string[];
     };

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

@@ -1,31 +1,14 @@
-import { TypedNextResponse } from "next-rest-framework";
-import { z } from "zod";
-import { BaseTable } from "../types.js";
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
 import { NextRequest } from "next/server";
-type DeleteOperationParams<B extends z.ZodSchema> = z.infer<B> & Record<string, unknown> & {
-    creatorId?: string;
-    id: string;
-};
-export interface DeleteOperationOptions<TTable extends BaseTable, B extends z.ZodSchema> {
-    table?: TTable;
-    bodySchema?: B;
-    description?: string;
-    summary?: string;
-    tags?: string[];
-    onSuccess?: (payload: {
-        params: DeleteOperationParams<B>;
-        data: unknown;
-    }) => Promise<void>;
-    onError?(error: Error): Promise<ReturnType<(typeof TypedNextResponse)["json"]> | undefined>;
-    byCreator?: boolean;
-}
+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, }: {
     db?: NodePgDatabase<Record<string, unknown>> | undefined;
     getSession(req: NextRequest): Promise<{
         userId?: string;
     } | undefined>;
-}) => <TTable extends BaseTable, B extends z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>> = z.ZodObject<{
-    id: z.ZodString;
-}, z.core.$strip>>({ table, bodySchema, description, summary, tags, onSuccess, onError, byCreator, }: DeleteOperationOptions<TTable, B>) => import("next-rest-framework").RouteOperationDefinition<"DELETE">;
-export {};
+}) => <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>) => import("next-rest-framework").RouteOperationDefinition<"DELETE">;

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

@@ -1,133 +1,15 @@
-function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
-function _regeneratorRuntime() { "use strict"; /*! regenerator-runtime -- Copyright (c) 2014-present, Facebook, Inc. -- license (MIT): https://github.com/facebook/regenerator/blob/main/LICENSE */ _regeneratorRuntime = function _regeneratorRuntime() { return e; }; var t, e = {}, r = Object.prototype, n = r.hasOwnProperty, o = Object.defineProperty || function (t, e, r) { t[e] = r.value; }, i = "function" == typeof Symbol ? Symbol : {}, a = i.iterator || "@@iterator", c = i.asyncIterator || "@@asyncIterator", u = i.toStringTag || "@@toStringTag"; function define(t, e, r) { return Object.defineProperty(t, e, { value: r, enumerable: !0, configurable: !0, writable: !0 }), t[e]; } try { define({}, ""); } catch (t) { define = function define(t, e, r) { return t[e] = r; }; } function wrap(t, e, r, n) { var i = e && e.prototype instanceof Generator ? e : Generator, a = Object.create(i.prototype), c = new Context(n || []); return o(a, "_invoke", { value: makeInvokeMethod(t, r, c) }), a; } function tryCatch(t, e, r) { try { return { type: "normal", arg: t.call(e, r) }; } catch (t) { return { type: "throw", arg: t }; } } e.wrap = wrap; var h = "suspendedStart", l = "suspendedYield", f = "executing", s = "completed", y = {}; function Generator() {} function GeneratorFunction() {} function GeneratorFunctionPrototype() {} var p = {}; define(p, a, function () { return this; }); var d = Object.getPrototypeOf, v = d && d(d(values([]))); v && v !== r && n.call(v, a) && (p = v); var g = GeneratorFunctionPrototype.prototype = Generator.prototype = Object.create(p); function defineIteratorMethods(t) { ["next", "throw", "return"].forEach(function (e) { define(t, e, function (t) { return this._invoke(e, t); }); }); } function AsyncIterator(t, e) { function invoke(r, o, i, a) { var c = tryCatch(t[r], t, o); if ("throw" !== c.type) { var u = c.arg, h = u.value; return h && "object" == _typeof(h) && n.call(h, "__await") ? e.resolve(h.__await).then(function (t) { invoke("next", t, i, a); }, function (t) { invoke("throw", t, i, a); }) : e.resolve(h).then(function (t) { u.value = t, i(u); }, function (t) { return invoke("throw", t, i, a); }); } a(c.arg); } var r; o(this, "_invoke", { value: function value(t, n) { function callInvokeWithMethodAndArg() { return new e(function (e, r) { invoke(t, n, e, r); }); } return r = r ? r.then(callInvokeWithMethodAndArg, callInvokeWithMethodAndArg) : callInvokeWithMethodAndArg(); } }); } function makeInvokeMethod(e, r, n) { var o = h; return function (i, a) { if (o === f) throw new Error("Generator is already running"); if (o === s) { if ("throw" === i) throw a; return { value: t, done: !0 }; } for (n.method = i, n.arg = a;;) { var c = n.delegate; if (c) { var u = maybeInvokeDelegate(c, n); if (u) { if (u === y) continue; return u; } } if ("next" === n.method) n.sent = n._sent = n.arg;else if ("throw" === n.method) { if (o === h) throw o = s, n.arg; n.dispatchException(n.arg); } else "return" === n.method && n.abrupt("return", n.arg); o = f; var p = tryCatch(e, r, n); if ("normal" === p.type) { if (o = n.done ? s : l, p.arg === y) continue; return { value: p.arg, done: n.done }; } "throw" === p.type && (o = s, n.method = "throw", n.arg = p.arg); } }; } function maybeInvokeDelegate(e, r) { var n = r.method, o = e.iterator[n]; if (o === t) return r.delegate = null, "throw" === n && e.iterator.return && (r.method = "return", r.arg = t, maybeInvokeDelegate(e, r), "throw" === r.method) || "return" !== n && (r.method = "throw", r.arg = new TypeError("The iterator does not provide a '" + n + "' method")), y; var i = tryCatch(o, e.iterator, r.arg); if ("throw" === i.type) return r.method = "throw", r.arg = i.arg, r.delegate = null, y; var a = i.arg; return a ? a.done ? (r[e.resultName] = a.value, r.next = e.nextLoc, "return" !== r.method && (r.method = "next", r.arg = t), r.delegate = null, y) : a : (r.method = "throw", r.arg = new TypeError("iterator result is not an object"), r.delegate = null, y); } function pushTryEntry(t) { var e = { tryLoc: t[0] }; 1 in t && (e.catchLoc = t[1]), 2 in t && (e.finallyLoc = t[2], e.afterLoc = t[3]), this.tryEntries.push(e); } function resetTryEntry(t) { var e = t.completion || {}; e.type = "normal", delete e.arg, t.completion = e; } function Context(t) { this.tryEntries = [{ tryLoc: "root" }], t.forEach(pushTryEntry, this), this.reset(!0); } function values(e) { if (e || "" === e) { var r = e[a]; if (r) return r.call(e); if ("function" == typeof e.next) return e; if (!isNaN(e.length)) { var o = -1, i = function next() { for (; ++o < e.length;) if (n.call(e, o)) return next.value = e[o], next.done = !1, next; return next.value = t, next.done = !0, next; }; return i.next = i; } } throw new TypeError(_typeof(e) + " is not iterable"); } return GeneratorFunction.prototype = GeneratorFunctionPrototype, o(g, "constructor", { value: GeneratorFunctionPrototype, configurable: !0 }), o(GeneratorFunctionPrototype, "constructor", { value: GeneratorFunction, configurable: !0 }), GeneratorFunction.displayName = define(GeneratorFunctionPrototype, u, "GeneratorFunction"), e.isGeneratorFunction = function (t) { var e = "function" == typeof t && t.constructor; return !!e && (e === GeneratorFunction || "GeneratorFunction" === (e.displayName || e.name)); }, e.mark = function (t) { return Object.setPrototypeOf ? Object.setPrototypeOf(t, GeneratorFunctionPrototype) : (t.__proto__ = GeneratorFunctionPrototype, define(t, u, "GeneratorFunction")), t.prototype = Object.create(g), t; }, e.awrap = function (t) { return { __await: t }; }, defineIteratorMethods(AsyncIterator.prototype), define(AsyncIterator.prototype, c, function () { return this; }), e.AsyncIterator = AsyncIterator, e.async = function (t, r, n, o, i) { void 0 === i && (i = Promise); var a = new AsyncIterator(wrap(t, r, n, o), i); return e.isGeneratorFunction(r) ? a : a.next().then(function (t) { return t.done ? t.value : a.next(); }); }, defineIteratorMethods(g), define(g, u, "Generator"), define(g, a, function () { return this; }), define(g, "toString", function () { return "[object Generator]"; }), e.keys = function (t) { var e = Object(t), r = []; for (var n in e) r.push(n); return r.reverse(), function next() { for (; r.length;) { var t = r.pop(); if (t in e) return next.value = t, next.done = !1, next; } return next.done = !0, next; }; }, e.values = values, Context.prototype = { constructor: Context, reset: function reset(e) { if (this.prev = 0, this.next = 0, this.sent = this._sent = t, this.done = !1, this.delegate = null, this.method = "next", this.arg = t, this.tryEntries.forEach(resetTryEntry), !e) for (var r in this) "t" === r.charAt(0) && n.call(this, r) && !isNaN(+r.slice(1)) && (this[r] = t); }, stop: function stop() { this.done = !0; var t = this.tryEntries[0].completion; if ("throw" === t.type) throw t.arg; return this.rval; }, dispatchException: function dispatchException(e) { if (this.done) throw e; var r = this; function handle(n, o) { return a.type = "throw", a.arg = e, r.next = n, o && (r.method = "next", r.arg = t), !!o; } for (var o = this.tryEntries.length - 1; o >= 0; --o) { var i = this.tryEntries[o], a = i.completion; if ("root" === i.tryLoc) return handle("end"); if (i.tryLoc <= this.prev) { var c = n.call(i, "catchLoc"), u = n.call(i, "finallyLoc"); if (c && u) { if (this.prev < i.catchLoc) return handle(i.catchLoc, !0); if (this.prev < i.finallyLoc) return handle(i.finallyLoc); } else if (c) { if (this.prev < i.catchLoc) return handle(i.catchLoc, !0); } else { if (!u) throw new Error("try statement without catch or finally"); if (this.prev < i.finallyLoc) return handle(i.finallyLoc); } } } }, abrupt: function abrupt(t, e) { for (var r = this.tryEntries.length - 1; r >= 0; --r) { var o = this.tryEntries[r]; if (o.tryLoc <= this.prev && n.call(o, "finallyLoc") && this.prev < o.finallyLoc) { var i = o; break; } } i && ("break" === t || "continue" === t) && i.tryLoc <= e && e <= i.finallyLoc && (i = null); var a = i ? i.completion : {}; return a.type = t, a.arg = e, i ? (this.method = "next", this.next = i.finallyLoc, y) : this.complete(a); }, complete: function complete(t, e) { if ("throw" === t.type) throw t.arg; return "break" === t.type || "continue" === t.type ? this.next = t.arg : "return" === t.type ? (this.rval = this.arg = t.arg, this.method = "return", this.next = "end") : "normal" === t.type && e && (this.next = e), y; }, finish: function finish(t) { for (var e = this.tryEntries.length - 1; e >= 0; --e) { var r = this.tryEntries[e]; if (r.finallyLoc === t) return this.complete(r.completion, r.afterLoc), resetTryEntry(r), y; } }, catch: function _catch(t) { for (var e = this.tryEntries.length - 1; e >= 0; --e) { var r = this.tryEntries[e]; if (r.tryLoc === t) { var n = r.completion; if ("throw" === n.type) { var o = n.arg; resetTryEntry(r); } return o; } } throw new Error("illegal catch attempt"); }, delegateYield: function delegateYield(e, r, n) { return this.delegate = { iterator: values(e), resultName: r, nextLoc: n }, "next" === this.method && (this.arg = t), y; } }, e; }
-function asyncGeneratorStep(gen, resolve, reject, _next, _throw, key, arg) { try { var info = gen[key](arg); var value = info.value; } catch (error) { reject(error); return; } if (info.done) { resolve(value); } else { Promise.resolve(value).then(_next, _throw); } }
-function _asyncToGenerator(fn) { return function () { var self = this, args = arguments; return new Promise(function (resolve, reject) { var gen = fn.apply(self, args); function _next(value) { asyncGeneratorStep(gen, resolve, reject, _next, _throw, "next", value); } function _throw(err) { asyncGeneratorStep(gen, resolve, reject, _next, _throw, "throw", err); } _next(undefined); }); }; }
-import { routeOperation, TypedNextResponse } from "next-rest-framework";
-import { z } from "zod";
+import { createDeleteAction } from "../actions/create-delete-action.js";
 import getTableName from "./get-table-name.js";
-import { createDeleteAction } from "../actions/index.js";
-import { HttpError } from "../errors.js";
-var defaultDeleteBodySchema = z.object({
-  id: z.string()
+import { createDeleteOperationFactory } from "./operation-core.js";
+var createOperation = createDeleteOperationFactory({
+  createAction: createDeleteAction,
+  getTableName: getTableName
 });
 export var createDeleteOperation = function createDeleteOperation(_ref) {
   var db = _ref.db,
     getSession = _ref.getSession;
-  return function (_ref2) {
-    var table = _ref2.table,
-      _ref2$bodySchema = _ref2.bodySchema,
-      bodySchema = _ref2$bodySchema === void 0 ? defaultDeleteBodySchema : _ref2$bodySchema,
-      description = _ref2.description,
-      summary = _ref2.summary,
-      tags = _ref2.tags,
-      onSuccess = _ref2.onSuccess,
-      onError = _ref2.onError,
-      _ref2$byCreator = _ref2.byCreator,
-      byCreator = _ref2$byCreator === void 0 ? true : _ref2$byCreator;
-    return routeOperation({
-      method: "DELETE",
-      openApiOperation: {
-        description: description,
-        summary: summary,
-        tags: tags !== null && tags !== void 0 ? tags : table ? [getTableName(table)] : []
-      }
-    }).input({
-      body: bodySchema,
-      contentType: "application/json"
-    }).handler( /*#__PURE__*/function () {
-      var _ref3 = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime().mark(function _callee(req) {
-        var body, _ref4, userId, tableParams, data, response;
-        return _regeneratorRuntime().wrap(function _callee$(_context) {
-          while (1) switch (_context.prev = _context.next) {
-            case 0:
-              _context.prev = 0;
-              _context.t0 = bodySchema;
-              _context.next = 4;
-              return req.json();
-            case 4:
-              _context.t1 = _context.sent;
-              body = _context.t0.parse.call(_context.t0, _context.t1);
-              if (!byCreator) {
-                _context.next = 15;
-                break;
-              }
-              _context.next = 9;
-              return getSession(req);
-            case 9:
-              _context.t2 = _context.sent;
-              if (_context.t2) {
-                _context.next = 12;
-                break;
-              }
-              _context.t2 = {};
-            case 12:
-              _ref4 = _context.t2;
-              userId = _ref4.userId;
-              body.creatorId = userId;
-            case 15:
-              tableParams = body;
-              if (!(table && db)) {
-                _context.next = 22;
-                break;
-              }
-              _context.next = 19;
-              return createDeleteAction({
-                table: table,
-                db: db
-              })(tableParams);
-            case 19:
-              _context.t3 = _context.sent;
-              _context.next = 23;
-              break;
-            case 22:
-              _context.t3 = body;
-            case 23:
-              data = _context.t3;
-              _context.next = 26;
-              return onSuccess === null || onSuccess === void 0 ? void 0 : onSuccess({
-                data: data,
-                params: body
-              });
-            case 26:
-              return _context.abrupt("return", TypedNextResponse.json(data, {
-                status: 200
-              }));
-            case 29:
-              _context.prev = 29;
-              _context.t4 = _context["catch"](0);
-              if (!(_context.t4 instanceof HttpError)) {
-                console.error(_context.t4);
-              }
-              _context.next = 34;
-              return onError === null || onError === void 0 ? void 0 : onError(_context.t4);
-            case 34:
-              response = _context.sent;
-              if (!response) {
-                _context.next = 37;
-                break;
-              }
-              return _context.abrupt("return", response);
-            case 37:
-              if (!(_context.t4 instanceof HttpError)) {
-                _context.next = 39;
-                break;
-              }
-              return _context.abrupt("return", TypedNextResponse.json({
-                message: _context.t4.message
-              }, {
-                status: _context.t4.status
-              }));
-            case 39:
-              throw _context.t4;
-            case 40:
-            case "end":
-              return _context.stop();
-          }
-        }, _callee, null, [[0, 29]]);
-      }));
-      return function (_x) {
-        return _ref3.apply(this, arguments);
-      };
-    }());
-  };
+  return createOperation({
+    db: db,
+    getSession: getSession
+  });
 };

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

@@ -1,38 +1,12 @@
-import { z, ZodSchema } from "zod";
-import { NextRequest } from "next/server";
-import { TypedNextRequest, TypedNextResponse } from "next-rest-framework";
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { NextRequest } from "next/server";
+import { ZodSchema } from "zod";
 import { BaseTable, GetListRelations } from "../types.js";
-type GetListOperationParams<Q extends ZodSchema> = z.infer<Q> & Record<string, unknown> & {
-    creatorId?: string;
-};
-export interface GetListOperationOptions<T extends ZodSchema, Q extends ZodSchema, TTable extends BaseTable> {
-    bodySchema: T;
-    jsonArrayFields?: string[];
-    querySchema: Q;
-    relations?: GetListRelations;
-    setParams?(req: TypedNextRequest<"GET", "application/json", unknown, z.infer<Q>>): Promise<Record<string, unknown>>;
-    byCreator?: boolean;
-    description?: string;
-    summary?: string;
-    tags?: string[];
-    table?: TTable;
-    onSuccess?<D extends T>(payload: {
-        params: GetListOperationParams<Q>;
-        data: {
-            data: z.infer<D>[];
-            total: number;
-        };
-    }): Promise<{
-        data: z.infer<T>[];
-        total: number;
-    }>;
-    onError?(error: Error): Promise<ReturnType<(typeof TypedNextResponse)["json"]> | undefined>;
-}
+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, }: {
     db?: NodePgDatabase<Record<string, unknown>> | undefined;
     getSession(req: NextRequest): Promise<{
         userId?: string;
     } | undefined>;
-}) => <T extends z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, Q extends z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, TTable extends BaseTable>({ querySchema, bodySchema, table, description, summary, tags, relations, jsonArrayFields, setParams, onSuccess, onError, byCreator, }: GetListOperationOptions<T, Q, TTable>) => import("next-rest-framework").RouteOperationDefinition<"GET">;
-export {};
+}) => <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>) => import("next-rest-framework").RouteOperationDefinition<"GET">;