@ai0x0/utils 0.0.37 → 0.0.39

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
 

package/README.md

@@ -17,6 +17,47 @@ Declarative CRUD factories on top of `next-rest-framework`, `drizzle-orm/pg-core
 
 See [SKILL.md](./SKILL.md) for detailed workflow, setup, and escape hatches.
 
+## SQLite Backend (`src/backend/sqlite/`)
+
+Projects that use a local SQLite database can import the same CRUD factory surface from `@ai0x0/utils/es/backend/sqlite`.
+
+```ts
+import {
+  createTableSchema,
+  queryListSchema,
+} from "@ai0x0/utils/es/backend/sqlite/schemas/index.js";
+import {
+  createGetOperation,
+  createPostOperation,
+} from "@ai0x0/utils/es/backend/sqlite/index.js";
+```
+
+The SQLite helpers mirror the PostgreSQL helpers, but use `drizzle-orm/sqlite-core`, SQLite `LIKE`, and `json_each(...)` for JSON-array filtering.
+
+Focused SQLite coverage should verify:
+
+1. `createTableSchema` generates SQLite tables with the base fields: `id`, `creatorId`, `editorId`, `accessedAt`, `createdAt`, and `updatedAt`.
+2. `queryListSchema` preserves pagination defaults.
+3. `createGetListAction` works with SQLite query builders that expose `.all()`.
+4. `getListData` executes plain queries directly and does not depend on `next-rest-framework` RPC wrappers.
+5. `createPostAction` and `createPutAction` normalize `*At` fields through `transformBody`.
+6. String filters use SQLite `LIKE`, comma-separated id filters use `inArray`, JSON-array filters use `json_each(...)`, and date range filters map `createdAtFrom` / `createdAtTo` to the matching timestamp column.
+
+Run the focused SQLite tests:
+
+```bash
+pnpm test -- src/__tests__/sqlite-actions.test.ts src/__tests__/sqlite-schemas.test.ts
+```
+
+Run the full package checks before publishing:
+
+```bash
+pnpm test
+pnpm exec tsc --noEmit
+pnpm build
+npm pack --dry-run --json
+```
+
 ## Agent Skills
 
 This package also ships reusable project skills under `.agents/skills`:
@@ -114,7 +155,7 @@ Restrictions cover: `TryStatement`, `as` (non-const), `useState`, `useEffect`, `
 pnpm add @ai0x0/utils
 ```
 
-Peer dependencies: `drizzle-orm ^0.45.x`, `drizzle-zod ^0.8.x`, `zod ^4.x`.
+Peer dependencies: `drizzle-orm ^0.45.x`, `drizzle-zod ^0.8.x`, `next ^16.x`, `next-rest-framework`, `zod ^4.x`.
 
 ## Docs
 

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
 

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

@@ -1,10 +1,11 @@
 import { TypedNextResponse } from "next-rest-framework";
 import { BaseTable } from "../types.js";
 export interface DeleteOperationOptions<TTable extends BaseTable> {
-    table: TTable;
+    table?: TTable;
     summary?: string;
+    tags?: string[];
     onSuccess?: () => Promise<void>;
-    onError?: (error: Error) => Promise<ReturnType<(typeof TypedNextResponse)["json"]> | undefined>;
+    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,61 @@ 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;
+            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();
-            case 18:
+            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,18 @@ 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: {
+    tags?: string[];
+    table?: TTable;
+    onSuccess?<D extends T>(data: {
         data: z.infer<D>[];
         total: number;
-    }) => Promise<{
+    }): 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,62 @@ 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;
+              _context.next = 28;
               return onSuccess(result);
-            case 22:
+            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,12 @@ 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?(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,60 @@ 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;
+              _context.next = 29;
               return onSuccess(result);
-            case 23:
+            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,11 @@ 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?(data: z.infer<OB>): Promise<z.infer<OB>>;
+    onError?(error: Error): Promise<ReturnType<(typeof TypedNextResponse)["json"]> | undefined>;
+    table?: TTable;
 }
 export declare const createPostOperation: any;