@angelps/prisma-query-builder 0.1.1

package/README.md

@@ -0,0 +1,709 @@
+# @angelps/prisma-query-builder
+
+Core library for backend projects built with Prisma + Express. Provides a query builder for HTTP parameters, a generic CRUD repository, a generic REST controller, an audit service, and shared utilities.
+
+## Installation
+
+```bash
+npm install @angelps/prisma-query-builder
+```
+
+### Peer dependencies
+
+```bash
+npm install @prisma/client express valibot
+```
+
+> **Note**: `valibot` is the default validation library, but you can use **Zod** or any other validator by providing a custom schema adapter. See [Schema Adapters](#8-schema-adapters).
+
+---
+
+## Table of contents
+
+1. [PrismaQueryBuilder](#1-prismaquerybuildert)
+2. [CrudRepository](#2-crudrepositoryt)
+3. [GenericController](#3-genericcontrollert)
+4. [AuditService](#4-auditservice)
+5. [Error handling](#5-error-handling)
+6. [Utilities](#6-utilities)
+7. [Types reference](#7-types-reference)
+8. [Schema Adapters](#8-schema-adapters)
+9. [Configurable Logger](#9-configurable-logger)
+
+---
+
+## 1. PrismaQueryBuilder\<T\>
+
+Translates HTTP query parameters into Prisma `where`, `orderBy`, `skip`, and `take` arguments.
+
+### Options
+
+| Option             | Type                     | Description                                 |
+| ------------------ | ------------------------ | ------------------------------------------- |
+| `filterableFields` | `(keyof T)[]`            | Fields that accept exact-match filtering    |
+| `likeFields`       | `(keyof T)[]`            | Fields included in `search` (OR contains)   |
+| `notLikeFields`    | `(keyof T)[]`            | Fields excluded by `notLike`                |
+| `sortableFields`   | `(keyof T)[]`            | Fields allowed in `sort`                    |
+| `searchDateFields` | `(keyof T)[]`            | Fields filtered by `from`/`to` date range   |
+| `operationFields`  | `(keyof T)[]`            | Fields filtered by `greaterThan`/`lessThan` |
+| `omitFields`       | `(keyof T)[]`            | Fields excluded from all filters            |
+| `orderBy`          | `{ field, direction }[]` | Default sort when none is provided          |
+
+### Supported query params
+
+| Param                      | Behavior                                                                                           |
+| -------------------------- | -------------------------------------------------------------------------------------------------- |
+| `page`                     | Page number (default: 1)                                                                           |
+| `size`                     | Page size (default: 10)                                                                            |
+| `sort`                     | Comma-separated fields. Prefix `-` for desc: `sort=-createdAt,name`                                |
+| `search`                   | OR contains across all `likeFields`                                                                |
+| `notLike`                  | AND NOT contains across `notLikeFields`. Supports CSV                                              |
+| `from` / `to`              | Date range filter on `searchDateFields`                                                            |
+| `greaterThan` / `lessThan` | Numeric comparison on `operationFields`                                                            |
+| `cursor`                   | Cursor for cursor-based pagination (last seen ID)                                                  |
+| `fields`                   | Comma-separated fields to return (`select`). Ignored if `extraArgs` already has `select`/`include` |
+| Any `filterableField`      | Exact match. Auto-casts numbers, booleans, and CSV → `in`                                          |
+
+### Field selection
+
+Return only the fields you need via the `fields` query param. Translates to Prisma `select`:
+
+```
+GET /users?fields=id,name,email
+→ select: { id: true, name: true, email: true }
+```
+
+> **Note**: `fields` is ignored when the repository's `extraFindManyArgs` already contains a `select` or `include` key, since Prisma does not allow both at the same level.
+
+### Operator suffix filters
+
+Apply operators directly to filterable fields via suffixes:
+
+| Suffix        | Prisma Operator            | Example                                  |
+| ------------- | -------------------------- | ---------------------------------------- |
+| `_gte`        | `gte`                      | `GET /products?price_gte=100`            |
+| `_lte`        | `lte`                      | `GET /products?price_lte=500`            |
+| `_gt`         | `gt`                       | `GET /products?price_gt=0`               |
+| `_lt`         | `lt`                       | `GET /products?price_lt=1000`            |
+| `_contains`   | `contains` (insensitive)   | `GET /products?name_contains=shirt`      |
+| `_startsWith` | `startsWith` (insensitive) | `GET /products?name_startsWith=A`        |
+| `_in`         | `in` (CSV → array)         | `GET /products?status_in=ACTIVE,PENDING` |
+| `_not`        | `not`                      | `GET /products?status_not=DELETED`       |
+
+### Null / Not-null filters
+
+```
+GET /users?deletedAt=null    →  WHERE deletedAt IS NULL
+GET /users?deletedAt=!null   →  WHERE deletedAt IS NOT NULL
+```
+
+### Nested / relational filters
+
+Filter by related model fields using dot notation:
+
+```
+GET /users?orders.status=PENDING
+→ WHERE orders: { some: { status: 'PENDING' } }
+
+GET /users?orders.items.productId=5
+→ WHERE orders: { some: { items: { some: { productId: 5 } } } }
+```
+
+### OR compound conditions
+
+Combine arbitrary filters with OR using indexed syntax:
+
+```
+GET /users?or[0][status]=ACTIVE&or[0][role]=ADMIN&or[1][status]=PENDING
+→ WHERE OR: [{ status: 'ACTIVE', role: 'ADMIN' }, { status: 'PENDING' }]
+```
+
+### Simplified instantiation
+
+Instead of specifying all Prisma types manually, use `PrismaQueryBuilder.from()`:
+
+```typescript
+import { PrismaQueryBuilder } from "@angelps/prisma-query-builder";
+
+// ✅ NEW — types inferred from delegate
+const qb = PrismaQueryBuilder.from(prisma.user, config, options);
+
+// ❌ OLD — still works, but verbose
+const qb = new PrismaQueryBuilder<
+  User,
+  Prisma.UserWhereInput,
+  Prisma.UserOrderByWithRelationInput
+>(config, options);
+```
+
+### Direct usage
+
+```typescript
+import { PrismaQueryBuilder } from "@angelps/prisma-query-builder";
+
+type User = {
+  id: number;
+  name: string;
+  email: string;
+  active: boolean;
+  createdAt: Date;
+};
+
+const qb = PrismaQueryBuilder.from(
+  prisma.user,
+  { softDeleteField: "deletedAt", excludeSoftDeleted: true },
+  {
+    filterableFields: ["active", "id"],
+    likeFields: ["name", "email"],
+    sortableFields: ["name", "createdAt"],
+    searchDateFields: ["createdAt"],
+  },
+);
+
+// Build where clause from HTTP params
+const where = qb.buildWhere({ active: "true", search: "angel" });
+// → { deletedAt: null, active: true, OR: [{ name: { contains: 'angel' } }, ...] }
+
+// Paginated result (offset-based)
+const result = await qb.findAllAndCount({
+  delegate: prisma.user,
+  queryParams: req.query,
+  buildWhere: (p) => qb.buildWhere(p),
+  buildOrderBy: (s) => qb.buildOrderBy(s),
+  extraArgs: { include: { posts: true } },
+});
+// result → { items: User[], pagination: { count, pages, size, current } }
+
+// Cursor-based pagination (better for large datasets)
+const cursorResult = await qb.findAllWithCursor({
+  delegate: prisma.user,
+  queryParams: { cursor: 42, size: 10 },
+  buildWhere: (p) => qb.buildWhere(p),
+});
+// cursorResult → { items: User[], nextCursor: number | null, hasMore: boolean }
+```
+
+---
+
+## 2. CrudRepository\<T\>
+
+Generic Prisma repository with pagination, soft delete, validation, and audit fields (`createdBy`, `updatedBy`, `deletedBy`).
+
+### Setup
+
+```typescript
+import { CrudRepository } from "@angelps/prisma-query-builder";
+import { object, string, number, pipe, minLength } from "valibot";
+
+export class UserRepository extends CrudRepository<
+  Prisma.User,
+  Prisma.UserWhereInput,
+  Prisma.UserOrderByWithRelationInput,
+  Prisma.UserFindManyArgs
+> {
+  createSchema = object({
+    name: pipe(string(), minLength(2)),
+    email: string(),
+  });
+
+  updateSchema = object({
+    name: pipe(string(), minLength(2)),
+  });
+
+  constructor() {
+    super(
+      prisma.user, // Prisma delegate
+      {
+        softDeleteField: "deletedAt",
+        excludeSoftDeleted: true,
+        primaryKeyField: "id",
+        defaultOrderBy: [{ field: "createdAt", direction: "desc" }],
+      },
+      {
+        filterableFields: ["active", "companyId"],
+        likeFields: ["name", "email"],
+        sortableFields: ["name", "createdAt"],
+      },
+    );
+  }
+
+  // Optional: transform data before hitting Prisma (e.g. string → Date)
+  protected transformData(data: Record<string, unknown>) {
+    return {
+      ...data,
+      birthDate: data.birthDate
+        ? new Date(data.birthDate as string)
+        : undefined,
+    };
+  }
+}
+
+export const userRepository = new UserRepository();
+```
+
+### Methods
+
+```typescript
+// Standard CRUD
+await userRepository.findAll(req.query, options); // PaginationModel<User>
+await userRepository.findById(1, options); // User | null
+await userRepository.findById(1, { include: { posts: true } }); // User with relations
+await userRepository.findOne({ email: "a@b.com" }); // User | null
+await userRepository.create(req.body, options); // User
+await userRepository.update(1, req.body, options); // void
+await userRepository.delete(1, options); // void (soft delete by default)
+
+// Bulk operations
+await userRepository.createMany([...items], options); // { count: number }
+await userRepository.updateMany([1, 2, 3], data, opts); // { count: number }
+await userRepository.deleteMany([1, 2], options); // { count: number } (soft delete)
+await userRepository.upsert(data, options); // User
+```
+
+### Using Zod instead of Valibot
+
+```typescript
+import { z } from 'zod';
+import { CrudRepository, ZodAdapter } from '@angelps/prisma-query-builder';
+
+class UserRepo extends CrudRepository<...> {
+  createSchema = z.object({ name: z.string().min(2), email: z.string().email() });
+  updateSchema = z.object({ name: z.string().min(2) });
+
+  constructor() {
+    super(prisma.user, config, options, { schemaAdapter: new ZodAdapter() });
+  }
+}
+```
+
+---
+
+## 3. GenericController\<T\>
+
+Express controller that wires HTTP methods to `IGenericRepository`. Handles validation, error mapping, audit, configurable user-field injection, and lifecycle hooks.
+
+### Setup
+
+```typescript
+import { GenericController } from "@angelps/prisma-query-builder";
+import { userRepository } from "./user.repository.js";
+import { MyAuditService } from "./audit.service.js";
+import { Router } from "express";
+
+class UserController extends GenericController<User> {
+  constructor() {
+    super(userRepository, "User", {
+      audit: true,
+      auditService: new MyAuditService(),
+      // Inject fields from req.user into query params
+      injectFromUser: [
+        { userField: "companyIds", queryField: "companyId" },
+        { userField: "branchIds", queryField: "branchId" },
+      ],
+      // Lifecycle hooks
+      hooks: {
+        beforeCreate: (req, data) => {
+          // Modify data before create
+          return { ...data, source: "api" };
+        },
+        afterCreate: (req, result) => {
+          // Send notification, etc.
+        },
+        beforeUpdate: (req, id, data) => {
+          return { ...data, lastModifiedSource: "api" };
+        },
+        afterDelete: (req, id) => {
+          // Cleanup related resources
+        },
+      },
+    });
+  }
+}
+
+const controller = new UserController();
+const router = Router();
+
+router.get("/", (req, res, next) => controller.getAll(req, res, next));
+router.get("/:id", (req, res, next) => controller.getById(req, res, next));
+router.post("/", (req, res, next) => controller.create(req, res, next));
+router.put("/:id", (req, res, next) => controller.update(req, res, next));
+router.delete("/:id", (req, res, next) => controller.delete(req, res, next));
+```
+
+### Custom operations with audit
+
+Use `executeWithAudit` in subclass methods for non-standard operations:
+
+```typescript
+class UserController extends GenericController<User> {
+  async activate(req: Request, res: Response, next: NextFunction) {
+    return this.executeWithAudit(
+      req,
+      res,
+      next,
+      async (id, options) => {
+        await userRepository.update(id, { active: true }, options);
+      },
+      "UPDATE",
+      "User activated successfully",
+    );
+  }
+}
+```
+
+### Config options
+
+| Option                    | Type                   | Default         | Description                                |
+| ------------------------- | ---------------------- | --------------- | ------------------------------------------ |
+| `entityName`              | `string`               | constructor arg | Name used in response messages and audit   |
+| `audit`                   | `boolean`              | `false`         | Enable audit logging                       |
+| `auditService`            | `IAuditService`        | —               | Required when `audit: true`                |
+| `injectFromUser`          | `UserFieldInjection[]` | `[]`            | Inject `req.user` fields into query params |
+| `hooks`                   | `ControllerHooks<T>`   | `{}`            | Lifecycle hooks (before/after each op)     |
+| ~~`filterByUserBranch`~~  | `boolean`              | `false`         | **Deprecated** — use `injectFromUser`      |
+| ~~`filterByUserCompany`~~ | `boolean`              | `false`         | **Deprecated** — use `injectFromUser`      |
+
+### Lifecycle hooks
+
+| Hook           | Signature                 | Description                        |
+| -------------- | ------------------------- | ---------------------------------- |
+| `beforeCreate` | `(req, data) => data`     | Modify/validate data before create |
+| `afterCreate`  | `(req, result) => void`   | Run side-effects after create      |
+| `beforeUpdate` | `(req, id, data) => data` | Modify/validate data before update |
+| `afterUpdate`  | `(req, id) => void`       | Run side-effects after update      |
+| `beforeDelete` | `(req, id) => void`       | Guard or cleanup before delete     |
+| `afterDelete`  | `(req, id) => void`       | Run side-effects after delete      |
+
+### Express type augmentation
+
+The library augments `req.user` and `req.audit`. To have your auth middleware populate them, declare them in your project:
+
+```typescript
+// src/types/express.d.ts  (in your project)
+import "@angelps/prisma-query-builder";
+
+// Optionally extend with your own fields:
+declare global {
+  namespace Express {
+    interface Request {
+      user?: {
+        id: number;
+        branchIds?: number | number[];
+        companyIds?: number | number[];
+        // add your own fields here
+      };
+    }
+  }
+}
+```
+
+---
+
+## 4. AuditService
+
+Extend `BaseAuditService` and implement `persist()` with your own Prisma model.
+
+```typescript
+import {
+  BaseAuditService,
+  type AuditLogInput,
+} from "@angelps/prisma-query-builder";
+
+export class AuditService extends BaseAuditService {
+  protected async persist(input: AuditLogInput): Promise<void> {
+    await prisma.auditLog.create({
+      data: {
+        action: input.action,
+        entity: input.entity,
+        entityId: input.entityId != null ? String(input.entityId) : null,
+        userId: input.options?.userId ?? null,
+        companyId: input.options?.companyId ?? null,
+        requestId: input.options?.requestId ?? null,
+        ip: input.options?.ip ?? null,
+        userAgent: input.options?.userAgent ?? null,
+        path: input.options?.path ?? null,
+        method: input.options?.method ?? null,
+        before: input.before as any,
+        after: input.after as any,
+        metadata: input.metadata as any,
+      },
+    });
+  }
+}
+
+export const auditService = new AuditService();
+```
+
+`BaseAuditService` automatically:
+
+- Strips sensitive fields: `password`, `passwordHash`, `refreshToken`, `accessToken`, `token`
+- Converts `Prisma.Decimal` → `number`
+- Converts `Date` → ISO string
+
+### Prisma schema
+
+```prisma
+model AuditLog {
+  id        Int      @id @default(autoincrement())
+  action    String
+  entity    String
+  entityId  String?
+  userId    Int?
+  companyId Int?
+  requestId String?
+  ip        String?
+  userAgent String?
+  path      String?
+  method    String?
+  before    Json?
+  after     Json?
+  metadata  Json?
+  createdAt DateTime @default(now())
+}
+```
+
+---
+
+## 5. Error handling
+
+`ErrorHandlerService` maps errors to HTTP responses automatically.
+
+### Handled error codes
+
+| Error type                                                                | HTTP status                    |
+| ------------------------------------------------------------------------- | ------------------------------ |
+| `AppError` subclass (`ConflictError`, `BadRequestError`, `NotFoundError`) | statusCode of the error        |
+| `PrismaClientKnownRequestError` P2002                                     | 409 Conflict                   |
+| `PrismaClientKnownRequestError` P2003                                     | 422 Unprocessable              |
+| `PrismaClientKnownRequestError` P2011                                     | 422 Null constraint violation  |
+| `PrismaClientKnownRequestError` P2012                                     | 422 Missing required value     |
+| `PrismaClientKnownRequestError` P2014                                     | 422 Required relation violated |
+| `PrismaClientKnownRequestError` P2016                                     | 422 Query interpretation error |
+| `PrismaClientKnownRequestError` P2021                                     | 500 Table does not exist       |
+| `PrismaClientKnownRequestError` P2025                                     | 404 Not Found                  |
+| `ValiError` (valibot)                                                     | 422 with field-level errors    |
+| Known `ErrorMessages` string                                              | matching statusCode            |
+| Unknown error                                                             | 500 Internal Server Error      |
+
+### Custom errors
+
+```typescript
+import {
+  AppError,
+  BadRequestError,
+  ConflictError,
+  NotFoundError,
+} from "@angelps/prisma-query-builder";
+
+throw new BadRequestError("Invalid date range"); // 400
+throw new ConflictError("Email already exists"); // 409
+throw new NotFoundError("User not found"); // 404
+```
+
+### Customizable error messages (i18n)
+
+Override default Prisma error messages for localization:
+
+```typescript
+import { ErrorHandlerService } from "@angelps/prisma-query-builder";
+
+const errorHandler = new ErrorHandlerService({
+  messages: {
+    P2002: "A record with this data already exists",
+    P2025: "The requested record was not found",
+    P2003: "The referenced record does not exist",
+    VALIDATION_FAILED: "Validation failed",
+    INTERNAL_SERVER_ERROR: "Internal server error",
+  },
+});
+```
+
+---
+
+## 6. Utilities
+
+### Date utils
+
+```typescript
+import {
+  startDateOfDay,
+  endDateOfDay,
+  formatDate,
+  getTimeFromDateString,
+  formatTimeWithTimezone,
+} from "@angelps/prisma-query-builder";
+
+startDateOfDay("2024-01-15"); // '2024-01-15T00:00:00.000Z'
+endDateOfDay("2024-01-15"); // '2024-01-15T23:59:59.999Z'
+formatDate(new Date(), "DD-MM-YYYY"); // '15-01-2024'
+formatDate(new Date(), "YYYY-MM-DD", true); // '2024-01-15 14:30'
+getTimeFromDateString("2024-01-15T14:30:00Z"); // '14:30'
+formatTimeWithTimezone(new Date(), "America/New_York"); // '09:30'
+```
+
+### Phone utils
+
+```typescript
+import { extractCountryCodeAndNumber } from "@angelps/prisma-query-builder";
+
+extractCountryCodeAndNumber("8091234567", "DO");
+// → { prefix: '+1', number: '8091234567', country: 'DO' }
+```
+
+### HTTP response utils
+
+```typescript
+import {
+  apiResponse,
+  apiPaginationResponse,
+} from "@angelps/prisma-query-builder";
+
+apiResponse(res, data, "Created successfully", 201);
+apiPaginationResponse(res, paginationModel, "Users retrieved", 200);
+```
+
+---
+
+## 7. Types reference
+
+```typescript
+// Pagination result (offset-based)
+type PaginationModel<T> = {
+  items: T[];
+  total?: number;
+  pagination: { count: number; pages: number; size: number; current: number };
+};
+
+// Cursor pagination result
+type CursorPaginationResult<T> = {
+  items: T[];
+  nextCursor: string | number | null;
+  hasMore: boolean;
+};
+
+// Query params (generic for type-safe field filtering)
+type QueryParams<T = Record<string, unknown>> = BaseQueryParams & {
+  [K in keyof T]?: T[K] | string;
+};
+
+// Options passed from controller to repository
+type RepositoryOptions = {
+  userId?: number;
+  companyId?: number;
+  requestId?: string;
+  ip?: string;
+  userAgent?: string;
+  path?: string;
+  method?: string;
+};
+
+// Generic repository contract
+interface IGenericRepository<T> {
+  findAll(queryParams?: QueryParams, options?: RepositoryOptions): Promise<PaginationModel<T>>;
+  findById(id: number, options?: FindByIdOptions): Promise<T | null>;
+  findOne(where: Partial<T>, options?: RepositoryOptions): Promise<T | null>;
+  create(data: unknown, options?: RepositoryOptions): Promise<T>;
+  update(id: number, data: unknown, options?: RepositoryOptions): Promise<void>;
+  delete(id: number, options?: RepositoryOptions): Promise<void>;
+  createMany(data: unknown[], options?: RepositoryOptions): Promise<{ count: number }>;
+  updateMany(ids: number[], data: unknown, options?: RepositoryOptions): Promise<{ count: number }>;
+  deleteMany(ids: number[], options?: RepositoryOptions): Promise<{ count: number }>;
+  upsert(data: unknown, options?: RepositoryOptions): Promise<T>;
+}
+
+// Audit service contract
+interface IAuditService {
+  log(input: AuditLogInput): Promise<void>;
+}
+
+type AuditAction = 'CREATE' | 'UPDATE' | 'DELETE' | 'LOGIN' | 'LOGOUT';
+
+// Utility types — infer Prisma types from delegate
+type InferResult<D>       // → Model type
+type InferWhere<D>        // → WhereInput
+type InferOrderBy<D>      // → OrderByWithRelationInput
+type InferFindManyArgs<D> // → FindManyArgs
+```
+
+---
+
+## 8. Schema Adapters
+
+The library ships with a pluggable validation layer. By default it uses **Valibot**, but you can switch to **Zod** or implement your own adapter.
+
+### Valibot (default)
+
+No configuration needed — this is the default behavior:
+
+```typescript
+import { CrudRepository } from '@angelps/prisma-query-builder';
+import { object, string } from 'valibot';
+
+class UserRepo extends CrudRepository<...> {
+  createSchema = object({ name: string() });
+}
+```
+
+### Zod
+
+```typescript
+import { CrudRepository, ZodAdapter } from '@angelps/prisma-query-builder';
+import { z } from 'zod';
+
+class UserRepo extends CrudRepository<...> {
+  createSchema = z.object({ name: z.string().min(2) });
+  updateSchema = z.object({ name: z.string().min(2) });
+
+  constructor() {
+    super(prisma.user, config, options, { schemaAdapter: new ZodAdapter() });
+  }
+}
+```
+
+### Custom adapter
+
+Implement the `SchemaAdapter` interface:
+
+```typescript
+import type { SchemaAdapter } from "@angelps/prisma-query-builder";
+
+class YupAdapter implements SchemaAdapter {
+  parse<T>(schema: unknown, data: unknown): T {
+    return (schema as any).validateSync(data);
+  }
+  isValidSchema(schema: unknown): boolean {
+    return !!schema && typeof (schema as any).validateSync === "function";
+  }
+}
+```
+
+---
+
+## 9. Configurable Logger
+
+Replace `console.*` calls with your preferred logging library (winston, pino, etc.):
+
+```typescript
+import { CrudRepository } from '@angelps/prisma-query-builder';
+import type { Logger } from '@angelps/prisma-query-builder';
+import pino from 'pino';
+
+const pinoLogger = pino();
+
+const logger: Logger = {
+  warn: (msg, ...args) => pinoLogger.warn(msg, ...args),
+  error: (msg, ...args) => pinoLogger.error(msg, ...args),
+  info: (msg, ...args) => pinoLogger.info(msg, ...args),
+  debug: (msg, ...args) => pinoLogger.debug(msg, ...args),
+};
+
+class UserRepo extends CrudRepository<...> {
+  constructor() {
+    super(prisma.user, { logger, ...otherConfig }, options);
+  }
+}
+```
+
+By default the library uses `console.*` — no configuration required.
+
+Holaa, solo probando :D

package/dist/adapters/index.d.ts

@@ -0,0 +1,3 @@
+export { ValibotAdapter, valibotAdapter } from './valibot.adapter.js';
+export { ZodAdapter, zodAdapter } from './zod.adapter.js';
+//# sourceMappingURL=index.d.ts.map