@ai0x0/utils 0.0.38 → 0.0.40

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

@@ -85,14 +85,18 @@ 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         | `table`, `bodySchema`, `querySchema` | `setParams`, `relations`, `jsonArrayFields`, `byCreator`, `onSuccess`, `onError`, `summary` |
-| `getListOperation`  | GET paginated list         | `table`, `bodySchema`, `querySchema` | `setParams`, `relations`, `jsonArrayFields`, `onSuccess`, `onError`, `summary`              |
-| `postOperation`     | POST create                | `table`, `bodySchema`                | `outputBodySchema`, `setBody`, `onSuccess`, `onError`, `summary`                            |
-| `putOperation`      | PUT update                 | `table`, `bodySchema`                | `outputBodySchema`, `setBody`, `byCreator`, `onSuccess`, `onError`, `summary`               |
-| `deleteOperation`   | DELETE                     | `table`                              | `byCreator`, `onSuccess`, `onError`, `summary`                                              |
+| 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`, `tags` |
+| `getListOperation`  | GET paginated list         | `bodySchema`, `querySchema` | `table`, `setParams`, `relations`, `jsonArrayFields`, `onSuccess`, `onError`, `summary`, `tags`              |
+| `postOperation`     | POST create                | `bodySchema`                | `table`, `outputBodySchema`, `setBody`, `onSuccess`, `onError`, `summary`, `tags`                            |
+| `putOperation`      | PUT update                 | `bodySchema`                | `table`, `outputBodySchema`, `setBody`, `byCreator`, `onSuccess`, `onError`, `summary`, `tags`               |
+| `deleteOperation`   | DELETE                     | —                           | `table`, `byCreator`, `onSuccess`, `onError`, `summary`, `tags`                                              |
+
+`tags` can be passed manually to override the default OpenAPI tag inferred from `table`.
+
+`table` is optional for route operations. When omitted, 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.
 
 ## Canonical Examples
 
@@ -342,7 +346,7 @@ export const { GET } = route({
 
 - 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(data) => Promise<data>`; on GET_LIST the payload is `{ data, total }`.
+- Post-processing output — `onSuccess({ params, data }) => Promise<data>`; on GET_LIST `data` is `{ data, total }`.
 - Error rewriting — `onError(err) => Promise<Response | undefined>`. Return `undefined` to rethrow.
 
 ## Imports

package/SKILL.md

@@ -64,14 +64,18 @@ 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         | `table`, `bodySchema`, `querySchema` | `setParams`, `relations`, `jsonArrayFields`, `byCreator`, `onSuccess`, `onError`, `summary` |
-| `getListOperation`  | GET paginated list         | `table`, `bodySchema`, `querySchema` | `setParams`, `relations`, `jsonArrayFields`, `onSuccess`, `onError`, `summary`              |
-| `postOperation`     | POST create                | `table`, `bodySchema`                | `outputBodySchema`, `setBody`, `onSuccess`, `onError`, `summary`                            |
-| `putOperation`      | PUT update                 | `table`, `bodySchema`                | `outputBodySchema`, `setBody`, `byCreator`, `onSuccess`, `onError`, `summary`               |
-| `deleteOperation`   | DELETE                     | `table`                              | `byCreator`, `onSuccess`, `onError`, `summary`                                              |
+| 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`, `tags` |
+| `getListOperation`  | GET paginated list         | `bodySchema`, `querySchema` | `table`, `setParams`, `relations`, `jsonArrayFields`, `onSuccess`, `onError`, `summary`, `tags`              |
+| `postOperation`     | POST create                | `bodySchema`                | `table`, `outputBodySchema`, `setBody`, `onSuccess`, `onError`, `summary`, `tags`                            |
+| `putOperation`      | PUT update                 | `bodySchema`                | `table`, `outputBodySchema`, `setBody`, `byCreator`, `onSuccess`, `onError`, `summary`, `tags`               |
+| `deleteOperation`   | DELETE                     | —                           | `table`, `byCreator`, `onSuccess`, `onError`, `summary`, `tags`                                              |
+
+`tags` can be passed manually to override the default OpenAPI tag inferred from `table`.
+
+`table` is optional for route operations. When omitted, 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.
 
 ## Canonical Examples
 
@@ -321,7 +325,7 @@ export const { GET } = route({
 
 - 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(data) => Promise<data>`; on GET_LIST the payload is `{ data, total }`.
+- Post-processing output — `onSuccess({ params, data }) => Promise<data>`; on GET_LIST `data` is `{ data, total }`.
 - Error rewriting — `onError(err) => Promise<Response | undefined>`. Return `undefined` to rethrow.
 
 ## Imports

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

@@ -1,10 +1,17 @@
 import { TypedNextResponse } from "next-rest-framework";
 import { BaseTable } from "../types.js";
 export interface DeleteOperationOptions<TTable extends BaseTable> {
-    table: TTable;
+    table?: TTable;
     summary?: string;
-    onSuccess?: () => Promise<void>;
-    onError?: (error: Error) => Promise<ReturnType<(typeof TypedNextResponse)["json"]> | undefined>;
+    tags?: string[];
+    onSuccess?: (payload: {
+        params: {
+            id: string;
+            creatorId?: string;
+        };
+        data: unknown;
+    }) => Promise<void>;
+    onError?(error: Error): Promise<ReturnType<(typeof TypedNextResponse)["json"]> | undefined>;
     byCreator?: boolean;
 }
 export declare const createDeleteOperation: any;

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

@@ -13,6 +13,7 @@ export var createDeleteOperation = function createDeleteOperation(_ref) {
   return function (_ref2) {
     var table = _ref2.table,
       summary = _ref2.summary,
+      tags = _ref2.tags,
       onSuccess = _ref2.onSuccess,
       onError = _ref2.onError,
       _ref2$byCreator = _ref2.byCreator,
@@ -21,7 +22,7 @@ export var createDeleteOperation = function createDeleteOperation(_ref) {
       method: "DELETE",
       openApiOperation: {
         summary: summary,
-        tags: [getTableName(table)]
+        tags: tags !== null && tags !== void 0 ? tags : table ? [getTableName(table)] : []
       }
     }).input({
       body: z.object({
@@ -57,49 +58,64 @@ export var createDeleteOperation = function createDeleteOperation(_ref) {
               userId = _ref4.userId;
               body.creatorId = userId;
             case 13:
-              _context.next = 15;
+              if (!table) {
+                _context.next = 19;
+                break;
+              }
+              _context.next = 16;
               return createDeleteAction({
                 table: table,
                 db: db
               })(body);
-            case 15:
-              data = _context.sent;
-              _context.next = 18;
-              return onSuccess === null || onSuccess === void 0 ? void 0 : onSuccess();
-            case 18:
+            case 16:
+              _context.t1 = _context.sent;
+              _context.next = 20;
+              break;
+            case 19:
+              _context.t1 = body;
+            case 20:
+              data = _context.t1;
+              _context.next = 23;
+              return onSuccess === null || onSuccess === void 0 ? void 0 : onSuccess({
+                data: data,
+                params: body
+              });
+            case 23:
               return _context.abrupt("return", TypedNextResponse.json(data, {
                 status: 200
               }));
-            case 21:
-              _context.prev = 21;
-              _context.t1 = _context["catch"](0);
-              if (!(_context.t1 instanceof HttpError)) console.error(_context.t1);
-              _context.next = 26;
-              return onError === null || onError === void 0 ? void 0 : onError(_context.t1);
             case 26:
+              _context.prev = 26;
+              _context.t2 = _context["catch"](0);
+              if (!(_context.t2 instanceof HttpError)) {
+                console.error(_context.t2);
+              }
+              _context.next = 31;
+              return onError === null || onError === void 0 ? void 0 : onError(_context.t2);
+            case 31:
               response = _context.sent;
               if (!response) {
-                _context.next = 29;
+                _context.next = 34;
                 break;
               }
               return _context.abrupt("return", response);
-            case 29:
-              if (!(_context.t1 instanceof HttpError)) {
-                _context.next = 31;
+            case 34:
+              if (!(_context.t2 instanceof HttpError)) {
+                _context.next = 36;
                 break;
               }
               return _context.abrupt("return", TypedNextResponse.json({
-                message: _context.t1.message
+                message: _context.t2.message
               }, {
-                status: _context.t1.status
+                status: _context.t2.status
               }));
-            case 31:
-              throw _context.t1;
-            case 32:
+            case 36:
+              throw _context.t2;
+            case 37:
             case "end":
               return _context.stop();
           }
-        }, _callee, null, [[0, 21]]);
+        }, _callee, null, [[0, 26]]);
       }));
       return function (_x) {
         return _ref3.apply(this, arguments);

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

@@ -6,17 +6,21 @@ export interface GetListOperationOptions<T extends ZodSchema, Q extends ZodSchem
     jsonArrayFields?: string[];
     querySchema: Q;
     relations?: GetListRelations;
-    setParams?: (req: TypedNextRequest<"GET", "application/json", unknown, z.infer<Q>>) => Promise<Record<string, unknown>>;
+    setParams?(req: TypedNextRequest<"GET", "application/json", unknown, z.infer<Q>>): Promise<Record<string, unknown>>;
     byCreator?: boolean;
     summary?: string;
-    table: TTable;
-    onSuccess?: <D extends T>(data: {
-        data: z.infer<D>[];
-        total: number;
-    }) => Promise<{
+    tags?: string[];
+    table?: TTable;
+    onSuccess?<D extends T>(payload: {
+        params: Partial<z.infer<T>> & Record<string, unknown>;
+        data: {
+            data: z.infer<D>[];
+            total: number;
+        };
+    }): Promise<{
         data: z.infer<T>[];
         total: number;
     }>;
-    onError?: (error: Error) => Promise<ReturnType<(typeof TypedNextResponse)["json"]> | undefined>;
+    onError?(error: Error): Promise<ReturnType<(typeof TypedNextResponse)["json"]> | undefined>;
 }
 export declare const createGetListOperation: any;

package/es/backend/route-operation/get-list-operation.js

@@ -14,6 +14,7 @@ export var createGetListOperation = function createGetListOperation(_ref) {
       bodySchema = _ref2.bodySchema,
       table = _ref2.table,
       summary = _ref2.summary,
+      tags = _ref2.tags,
       relations = _ref2.relations,
       jsonArrayFields = _ref2.jsonArrayFields,
       setParams = _ref2.setParams,
@@ -25,7 +26,7 @@ export var createGetListOperation = function createGetListOperation(_ref) {
       method: "GET",
       openApiOperation: {
         summary: summary,
-        tags: [getTableName(table)]
+        tags: tags !== null && tags !== void 0 ? tags : table ? [getTableName(table)] : []
       }
     }).input({
       query: querySchema
@@ -35,7 +36,7 @@ export var createGetListOperation = function createGetListOperation(_ref) {
       status: 200
     }]).handler( /*#__PURE__*/function () {
       var _ref3 = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime().mark(function _callee(req) {
-        var params, _ref4, userId, result, response;
+        var params, _ref4, userId, mergedParams, result, response;
         return _regeneratorRuntime().wrap(function _callee$(_context) {
           while (1) switch (_context.prev = _context.next) {
             case 0:
@@ -69,48 +70,65 @@ export var createGetListOperation = function createGetListOperation(_ref) {
               userId = _ref4.userId;
               params.creatorId = userId;
             case 16:
-              _context.next = 18;
+              mergedParams = Object.assign(Object.fromEntries(new URL(req.url).searchParams), params);
+              if (!table) {
+                _context.next = 23;
+                break;
+              }
+              _context.next = 20;
               return createGetListAction({
                 bodySchema: bodySchema,
                 db: db,
                 jsonArrayFields: jsonArrayFields,
                 relations: relations,
                 table: table
-              })(Object.assign(Object.fromEntries(new URL(req.url).searchParams), params));
-            case 18:
-              result = _context.sent;
+              })(mergedParams);
+            case 20:
+              _context.t2 = _context.sent;
+              _context.next = 24;
+              break;
+            case 23:
+              _context.t2 = {
+                data: [],
+                total: 0
+              };
+            case 24:
+              result = _context.t2;
               if (!onSuccess) {
-                _context.next = 23;
+                _context.next = 29;
                 break;
               }
-              _context.next = 22;
-              return onSuccess(result);
-            case 22:
+              _context.next = 28;
+              return onSuccess({
+                data: result,
+                params: mergedParams
+              });
+            case 28:
               result = _context.sent;
-            case 23:
+            case 29:
               return _context.abrupt("return", TypedNextResponse.json(result, {
                 status: 200
               }));
-            case 26:
-              _context.prev = 26;
-              _context.t2 = _context["catch"](0);
-              console.error(_context.t2);
-              _context.next = 31;
-              return onError === null || onError === void 0 ? void 0 : onError(_context.t2);
-            case 31:
+            case 32:
+              _context.prev = 32;
+              _context.t3 = _context["catch"](0);
+              console.error(_context.t3);
+              _context.next = 37;
+              return onError === null || onError === void 0 ? void 0 : onError(_context.t3);
+            case 37:
               response = _context.sent;
               if (!response) {
-                _context.next = 36;
+                _context.next = 42;
                 break;
               }
               return _context.abrupt("return", response);
-            case 36:
-              throw _context.t2;
-            case 37:
+            case 42:
+              throw _context.t3;
+            case 43:
             case "end":
               return _context.stop();
           }
-        }, _callee, null, [[0, 26]]);
+        }, _callee, null, [[0, 32]]);
       }));
       return function (_x) {
         return _ref3.apply(this, arguments);

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

@@ -6,11 +6,15 @@ export interface GetOperationOptions<T extends ZodSchema, Q extends ZodSchema, T
     jsonArrayFields?: string[];
     querySchema: Q;
     relations?: GetListRelations;
-    setParams?: (req: TypedNextRequest<"GET", "application/json", unknown, z.infer<Q>>) => Promise<Record<string, unknown>>;
-    onSuccess?: (data: z.infer<T>) => Promise<z.infer<T>>;
-    onError?: (error: Error) => Promise<ReturnType<(typeof TypedNextResponse)["json"]> | undefined>;
+    setParams?(req: TypedNextRequest<"GET", "application/json", unknown, z.infer<Q>>): Promise<Record<string, unknown>>;
+    onSuccess?(payload: {
+        params: Partial<z.infer<T>> & Record<string, unknown>;
+        data: z.infer<T>;
+    }): Promise<z.infer<T>>;
+    onError?(error: Error): Promise<ReturnType<(typeof TypedNextResponse)["json"]> | undefined>;
     summary?: string;
-    table: TTable;
+    tags?: string[];
+    table?: TTable;
     byCreator?: boolean;
 }
 export declare const createGetOperation: any;

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

@@ -13,6 +13,7 @@ export var createGetOperation = function createGetOperation(_ref) {
       bodySchema = _ref2.bodySchema,
       table = _ref2.table,
       summary = _ref2.summary,
+      tags = _ref2.tags,
       relations = _ref2.relations,
       setParams = _ref2.setParams,
       jsonArrayFields = _ref2.jsonArrayFields,
@@ -24,7 +25,7 @@ export var createGetOperation = function createGetOperation(_ref) {
       method: "GET",
       openApiOperation: {
         summary: summary,
-        tags: [getTableName(table)]
+        tags: tags !== null && tags !== void 0 ? tags : table ? [getTableName(table)] : []
       }
     }).input({
       query: querySchema
@@ -34,7 +35,7 @@ export var createGetOperation = function createGetOperation(_ref) {
       status: 200
     }]).handler( /*#__PURE__*/function () {
       var _ref3 = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime().mark(function _callee(req) {
-        var params, _ref4, userId, rawResult, result, response;
+        var params, _ref4, userId, mergedParams, rawResult, result, response;
         return _regeneratorRuntime().wrap(function _callee$(_context) {
           while (1) switch (_context.prev = _context.next) {
             case 0:
@@ -68,49 +69,63 @@ export var createGetOperation = function createGetOperation(_ref) {
               userId = _ref4.userId;
               params.creatorId = userId;
             case 16:
-              _context.next = 18;
+              mergedParams = Object.assign(Object.fromEntries(new URL(req.url).searchParams), params);
+              if (!table) {
+                _context.next = 23;
+                break;
+              }
+              _context.next = 20;
               return createGetAction({
                 bodySchema: bodySchema,
                 db: db,
                 jsonArrayFields: jsonArrayFields,
                 relations: relations,
                 table: table
-              })(Object.assign(Object.fromEntries(new URL(req.url).searchParams), params));
-            case 18:
-              rawResult = _context.sent;
+              })(mergedParams);
+            case 20:
+              _context.t2 = _context.sent;
+              _context.next = 24;
+              break;
+            case 23:
+              _context.t2 = mergedParams;
+            case 24:
+              rawResult = _context.t2;
               result = rawResult !== null && rawResult !== void 0 ? rawResult : {};
               if (!onSuccess) {
-                _context.next = 24;
+                _context.next = 30;
                 break;
               }
-              _context.next = 23;
-              return onSuccess(result);
-            case 23:
+              _context.next = 29;
+              return onSuccess({
+                data: result,
+                params: mergedParams
+              });
+            case 29:
               result = _context.sent;
-            case 24:
+            case 30:
               return _context.abrupt("return", TypedNextResponse.json(result, {
                 status: 200
               }));
-            case 27:
-              _context.prev = 27;
-              _context.t2 = _context["catch"](0);
-              console.error(_context.t2);
-              _context.next = 32;
-              return onError === null || onError === void 0 ? void 0 : onError(_context.t2);
-            case 32:
+            case 33:
+              _context.prev = 33;
+              _context.t3 = _context["catch"](0);
+              console.error(_context.t3);
+              _context.next = 38;
+              return onError === null || onError === void 0 ? void 0 : onError(_context.t3);
+            case 38:
               response = _context.sent;
               if (!response) {
-                _context.next = 37;
+                _context.next = 43;
                 break;
               }
               return _context.abrupt("return", response);
-            case 37:
-              throw _context.t2;
-            case 38:
+            case 43:
+              throw _context.t3;
+            case 44:
             case "end":
               return _context.stop();
           }
-        }, _callee, null, [[0, 27]]);
+        }, _callee, null, [[0, 33]]);
       }));
       return function (_x) {
         return _ref3.apply(this, arguments);

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

@@ -4,10 +4,14 @@ import { TypedNextRequest, TypedNextResponse } from "next-rest-framework";
 export interface PostOperationOptions<IB extends ZodSchema, OB extends ZodSchema, TTable extends PgTable> {
     bodySchema: IB;
     outputBodySchema?: IB;
-    setBody?: (req: TypedNextRequest<"POST", "application/json", z.infer<IB>>) => Promise<Partial<z.infer<IB>>>;
+    setBody?(req: TypedNextRequest<"POST", "application/json", z.infer<IB>>): Promise<Partial<z.infer<IB>>>;
     summary?: string;
-    onSuccess?: (data: z.infer<OB>) => Promise<z.infer<OB>>;
-    onError?: (error: Error) => Promise<ReturnType<(typeof TypedNextResponse)["json"]> | undefined>;
-    table: TTable;
+    tags?: string[];
+    onSuccess?(payload: {
+        params: Record<string, unknown>;
+        data: z.infer<OB>;
+    }): Promise<z.infer<OB>>;
+    onError?(error: Error): Promise<ReturnType<(typeof TypedNextResponse)["json"]> | undefined>;
+    table?: TTable;
 }
 export declare const createPostOperation: any;