@devstroupe/devkit-nest 1.1.15 → 1.2.0-beta.1

package/README.md

@@ -1,72 +1,52 @@
 # @devstroupe/devkit-nest
 
-[![npm version](https://img.shields.io/npm/v/@devstroupe/devkit-nest?color=red)](https://www.npmjs.com/package/@devstroupe/devkit-nest)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE)
-
-Classes base para **NestJS + TypeORM** do DT-DevKit. Provê repositórios genéricos paginados e controladores CRUD padronizados.
+Bases NestJS e TypeORM 1.x da arquitetura backend do DT-DevKit.
 
 ## Instalação
 
 ```bash
-npm install @devstroupe/devkit-nest
+npm install @devstroupe/devkit-nest typeorm@^1.0.0
 ```
 
-### Peer Dependencies
-```bash
-npm install @nestjs/common @nestjs/core @nestjs/swagger typeorm reflect-metadata
-```
-
-## Classes disponíveis
-
-### `BaseRepository<Entity>`
+Requer Node.js 20+, NestJS 10/11 e `@nestjs/typeorm` compatível com TypeORM 1.x.
 
-Repositório TypeORM com parser automático de paginação e filtros. Todos os repositórios gerados pelo `devstroupe generate crud` herdam desta classe.
+## CRUD tipado
 
-```typescript
-import { BaseRepository } from '@devstroupe/devkit-nest';
-import { InjectRepository } from '@nestjs/typeorm';
-import { Repository } from 'typeorm';
-import { Cabin } from '../domain/entities/cabin.entity';
+- `BaseCrudController<Entity, Filter, ID, Create, Update, ListResult>` recebe uma
+  aplicação/use cases tipados e um `IdCodec`; há codecs number, string e UUID.
+- `BaseRepository<Entity, ID, Filter, Projection>` permite chave customizada,
+  QueryBuilder extensível, escopo tenant e projeção de lista.
+- `CreateUseCase`, `UpdateUseCase`, `FindOneUseCase`, `ListUseCase` e
+  `SoftDeleteUseCase` removem repetição sem receber regras de negócio.
+- `TypeOrmQueryBuilder` usa registry de filtros, limites físicos obrigatórios e
+  busca full-text MySQL configurada somente por campos confiáveis.
+- `TypeOrmReader` retorna projeções raw tipadas, suporta count separado,
+  `COUNT(DISTINCT ...)` e permite omitir o total.
+- `explainQuery` cria um harness de `EXPLAIN` sem perder os parâmetros.
+- `typeOrmSql<Row>(dataSource)` expõe a SQL tagged template parametrizada.
 
-@Injectable()
-export class CabinRepository extends BaseRepository<Cabin> {
-  constructor(
-    @InjectRepository(Cabin)
-    private readonly repo: Repository<Cabin>
-  ) {
-    super(repo);
-  }
-}
-```
-
-Métodos herdados:
-- `findMany(query)` — paginação automática com filtros
-- `findById(id)` — busca por ID com validação
-
-### `BaseCrudController<Entity, CreateDto, UpdateDto>`
+Toda deleção do repositório base exige `@DeleteDateColumn` e executa soft delete.
+Não há restore público.
 
-Controller NestJS com endpoints CRUD padronizados e documentação Swagger automática.
+## Contexto e transações
 
-```typescript
-import { BaseCrudController } from '@devstroupe/devkit-nest';
-
-@Controller('cabins')
-export class CabinController extends BaseCrudController(
-  Cabin, CreateCabinDto, UpdateCabinDto
-) {}
-```
+- `executionContext` / `AppExecutionContext`: actor, tenant, correlation ID e
+  source propagados por `AsyncLocalStorage`; `requireTenantId()` falha fechado.
+- `TypeOrmUnitOfWork`: callback transacional com o mesmo `EntityManager` para
+  todos os repositories.
+- `TypeOrmOutboxWriter` e `OutboxPublisher`: persistência atômica, retry e ID de
+  evento como chave idempotente.
 
-Endpoints gerados automaticamente:
-- `GET /` — listagem paginada com filtros via query params
-- `GET /:id` — busca por ID
-- `POST /` — criação
-- `PATCH /:id` — atualização parcial
-- `DELETE /:id` — remoção
+## Platform
 
-## Regras de governança
+- security: `PasswordHasher`, `BcryptPasswordHasher`, `TokenIssuer`,
+  `TokenVerifier` e adapters JWT separados;
+- integrations: `ExternalHttpClient`, `CompanyRegistryGateway` e contratos de
+  webhook verificado/idempotente, com replay window, contexto de evento e
+  auditoria sem secrets;
+- messaging, storage, auth/RBAC, realtime e audit.
 
-A regra `use-standard-devkit-queries` do linter exige que:
-- Todos os **Controllers CRUD** herdem de `BaseCrudController`
-- Todos os **Repositories** herdem de `BaseRepository`
+`RealtimeModule.register({ tokenVerifier })` recebe somente `TokenVerifier`;
+WebSocket/realtime não importa JWT diretamente nem recebe chave de emissão.
 
-Execute `devstroupe lint:rules` para verificar conformidade.
+Detalhes e exemplos: [arquitetura backend](../../docs/backend-architecture.md).

package/dist/application/crud-use-cases.d.ts

@@ -0,0 +1,35 @@
+import type { DeepPartial, ObjectLiteral } from 'typeorm';
+import type { IFilterPagination, IPaginator } from '@devstroupe/devkit-core';
+export interface CrudRepositoryPort<Entity extends ObjectLiteral, ID, Filter extends IFilterPagination = IFilterPagination, ListProjection = Entity> {
+    create(input: DeepPartial<Entity>): Promise<Entity>;
+    update(id: ID, input: DeepPartial<Entity>): Promise<Entity>;
+    findOne(id: ID): Promise<Entity | null>;
+    findMany(filter: Filter): Promise<IPaginator<ListProjection>>;
+    delete(id: ID): Promise<void>;
+}
+export declare class CreateUseCase<Entity extends ObjectLiteral, ID, Filter extends IFilterPagination = IFilterPagination> {
+    protected readonly repository: CrudRepositoryPort<Entity, ID, Filter>;
+    constructor(repository: CrudRepositoryPort<Entity, ID, Filter>);
+    execute(input: DeepPartial<Entity>): Promise<Entity>;
+}
+export declare class UpdateUseCase<Entity extends ObjectLiteral, ID, Filter extends IFilterPagination = IFilterPagination> {
+    protected readonly repository: CrudRepositoryPort<Entity, ID, Filter>;
+    constructor(repository: CrudRepositoryPort<Entity, ID, Filter>);
+    execute(id: ID, input: DeepPartial<Entity>): Promise<Entity>;
+}
+export declare class FindOneUseCase<Entity extends ObjectLiteral, ID, Filter extends IFilterPagination = IFilterPagination> {
+    protected readonly repository: CrudRepositoryPort<Entity, ID, Filter>;
+    constructor(repository: CrudRepositoryPort<Entity, ID, Filter>);
+    execute(id: ID): Promise<Entity | null>;
+}
+export declare class ListUseCase<Entity extends ObjectLiteral, ID, Filter extends IFilterPagination = IFilterPagination, Projection = Entity> {
+    protected readonly repository: CrudRepositoryPort<Entity, ID, Filter, Projection>;
+    constructor(repository: CrudRepositoryPort<Entity, ID, Filter, Projection>);
+    execute(filter: Filter): Promise<IPaginator<Projection>>;
+}
+/** Override execute in a concrete use case when explicit dependent cascades are required. */
+export declare class SoftDeleteUseCase<Entity extends ObjectLiteral, ID, Filter extends IFilterPagination = IFilterPagination> {
+    protected readonly repository: CrudRepositoryPort<Entity, ID, Filter>;
+    constructor(repository: CrudRepositoryPort<Entity, ID, Filter>);
+    execute(id: ID): Promise<void>;
+}

package/dist/application/crud-use-cases.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SoftDeleteUseCase = exports.ListUseCase = exports.FindOneUseCase = exports.UpdateUseCase = exports.CreateUseCase = void 0;
+class CreateUseCase {
+    repository;
+    constructor(repository) {
+        this.repository = repository;
+    }
+    execute(input) { return this.repository.create(input); }
+}
+exports.CreateUseCase = CreateUseCase;
+class UpdateUseCase {
+    repository;
+    constructor(repository) {
+        this.repository = repository;
+    }
+    execute(id, input) { return this.repository.update(id, input); }
+}
+exports.UpdateUseCase = UpdateUseCase;
+class FindOneUseCase {
+    repository;
+    constructor(repository) {
+        this.repository = repository;
+    }
+    execute(id) { return this.repository.findOne(id); }
+}
+exports.FindOneUseCase = FindOneUseCase;
+class ListUseCase {
+    repository;
+    constructor(repository) {
+        this.repository = repository;
+    }
+    execute(filter) { return this.repository.findMany(filter); }
+}
+exports.ListUseCase = ListUseCase;
+/** Override execute in a concrete use case when explicit dependent cascades are required. */
+class SoftDeleteUseCase {
+    repository;
+    constructor(repository) {
+        this.repository = repository;
+    }
+    execute(id) { return this.repository.delete(id); }
+}
+exports.SoftDeleteUseCase = SoftDeleteUseCase;

package/dist/application/crud-use-cases.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/application/crud-use-cases.test.js

@@ -0,0 +1,19 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const strict_1 = __importDefault(require("node:assert/strict"));
+const node_test_1 = __importDefault(require("node:test"));
+const crud_use_cases_1 = require("./crud-use-cases");
+(0, node_test_1.default)('CRUD base use cases delegate only application mechanics', async () => {
+    const calls = [];
+    const repository = {
+        async create(input) { calls.push(`create:${input.name}`); return { id: 1, ...input }; },
+        async delete(id) { calls.push(`delete:${id}`); },
+    };
+    const created = await new crud_use_cases_1.CreateUseCase(repository).execute({ name: 'Catalog item' });
+    await new crud_use_cases_1.SoftDeleteUseCase(repository).execute(1);
+    strict_1.default.deepEqual(created, { id: 1, name: 'Catalog item' });
+    strict_1.default.deepEqual(calls, ['create:Catalog item', 'delete:1']);
+});

package/dist/application/index.d.ts

@@ -0,0 +1,2 @@
+export * from './crud-use-cases';
+export * from './read-model';

package/dist/application/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./crud-use-cases"), exports);
+__exportStar(require("./read-model"), exports);

package/dist/application/read-model.d.ts

@@ -0,0 +1,5 @@
+import type { IFilterPagination, IPaginator } from '@devstroupe/devkit-core';
+/** Add a reader port only for a query that justifies a dedicated projection. */
+export interface ReadModelReader<Row, Filter extends IFilterPagination = IFilterPagination> {
+    read(filter: Filter): Promise<IPaginator<Row>>;
+}

package/dist/application/read-model.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/context/execution-context.d.ts

@@ -0,0 +1,19 @@
+export type AppExecutionSource = 'http' | 'rpc' | 'job' | 'event';
+export interface AppExecutionContext {
+    actorId?: string;
+    tenantId?: string;
+    correlationId: string;
+    source: AppExecutionSource;
+}
+export declare class MissingTenantContextError extends Error {
+    constructor();
+}
+/** Transport-neutral request context shared by HTTP, RPC, jobs and events. */
+export declare class ExecutionContextAccessor {
+    private readonly storage;
+    run<T>(context: AppExecutionContext, callback: () => T): T;
+    current(): AppExecutionContext | undefined;
+    requireCurrent(): AppExecutionContext;
+    requireTenantId(): string;
+}
+export declare const executionContext: ExecutionContextAccessor;

package/dist/context/execution-context.interceptor.d.ts

@@ -0,0 +1,5 @@
+import { CallHandler, ExecutionContext, NestInterceptor } from '@nestjs/common';
+import { Observable } from 'rxjs';
+export declare class ExecutionContextInterceptor implements NestInterceptor {
+    intercept(host: ExecutionContext, next: CallHandler): Observable<unknown>;
+}

package/dist/context/execution-context.interceptor.js

@@ -0,0 +1,35 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExecutionContextInterceptor = void 0;
+const common_1 = require("@nestjs/common");
+const node_crypto_1 = require("node:crypto");
+const rxjs_1 = require("rxjs");
+const execution_context_1 = require("./execution-context");
+let ExecutionContextInterceptor = class ExecutionContextInterceptor {
+    intercept(host, next) {
+        const request = host.switchToHttp().getRequest();
+        const correlationHeader = request.headers?.['x-correlation-id'];
+        const correlationId = (Array.isArray(correlationHeader) ? correlationHeader[0] : correlationHeader) || (0, node_crypto_1.randomUUID)();
+        const actor = request.user?.id ?? request.user?.sub;
+        const context = {
+            actorId: actor === undefined ? undefined : String(actor),
+            tenantId: request.user?.tenantId === undefined ? undefined : String(request.user.tenantId),
+            correlationId,
+            source: 'http',
+        };
+        return new rxjs_1.Observable((subscriber) => execution_context_1.executionContext.run(context, () => {
+            const subscription = next.handle().subscribe(subscriber);
+            return () => subscription.unsubscribe();
+        }));
+    }
+};
+exports.ExecutionContextInterceptor = ExecutionContextInterceptor;
+exports.ExecutionContextInterceptor = ExecutionContextInterceptor = __decorate([
+    (0, common_1.Injectable)()
+], ExecutionContextInterceptor);

package/dist/context/execution-context.interceptor.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/context/execution-context.interceptor.test.js

@@ -0,0 +1,26 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const strict_1 = __importDefault(require("node:assert/strict"));
+const node_test_1 = __importDefault(require("node:test"));
+const rxjs_1 = require("rxjs");
+const execution_context_1 = require("./execution-context");
+const execution_context_interceptor_1 = require("./execution-context.interceptor");
+(0, node_test_1.default)('HTTP interceptor derives tenant from authenticated principal, not a free tenant header', async () => {
+    const host = {
+        switchToHttp: () => ({ getRequest: () => ({
+                user: { id: 7, tenantId: 'trusted-tenant' },
+                headers: { 'x-tenant-id': 'attacker-tenant', 'x-correlation-id': 'corr-http' },
+            }) }),
+    };
+    const next = { handle: () => new rxjs_1.Observable((subscriber) => {
+            subscriber.next(execution_context_1.executionContext.requireCurrent());
+            subscriber.complete();
+        }) };
+    const context = await (0, rxjs_1.firstValueFrom)(new execution_context_interceptor_1.ExecutionContextInterceptor().intercept(host, next));
+    strict_1.default.equal(context.tenantId, 'trusted-tenant');
+    strict_1.default.equal(context.actorId, '7');
+    strict_1.default.equal(context.correlationId, 'corr-http');
+});

package/dist/context/execution-context.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executionContext = exports.ExecutionContextAccessor = exports.MissingTenantContextError = void 0;
+const node_async_hooks_1 = require("node:async_hooks");
+class MissingTenantContextError extends Error {
+    constructor() {
+        super('A trusted tenant is required for this operation.');
+        this.name = 'MissingTenantContextError';
+    }
+}
+exports.MissingTenantContextError = MissingTenantContextError;
+/** Transport-neutral request context shared by HTTP, RPC, jobs and events. */
+class ExecutionContextAccessor {
+    storage = new node_async_hooks_1.AsyncLocalStorage();
+    run(context, callback) {
+        if (!context.correlationId?.trim()) {
+            throw new Error('Execution context requires a correlationId.');
+        }
+        return this.storage.run(Object.freeze({ ...context }), callback);
+    }
+    current() {
+        return this.storage.getStore();
+    }
+    requireCurrent() {
+        const context = this.current();
+        if (!context)
+            throw new Error('Execution context is unavailable.');
+        return context;
+    }
+    requireTenantId() {
+        const tenantId = this.current()?.tenantId;
+        if (!tenantId)
+            throw new MissingTenantContextError();
+        return tenantId;
+    }
+}
+exports.ExecutionContextAccessor = ExecutionContextAccessor;
+exports.executionContext = new ExecutionContextAccessor();

package/dist/context/execution-context.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/context/execution-context.test.js

@@ -0,0 +1,18 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const strict_1 = __importDefault(require("node:assert/strict"));
+const node_test_1 = __importDefault(require("node:test"));
+const execution_context_1 = require("./execution-context");
+(0, node_test_1.default)('execution context propagates trusted data across async work', async () => {
+    await execution_context_1.executionContext.run({ actorId: 'actor-1', tenantId: 'tenant-1', correlationId: 'corr-1', source: 'job' }, async () => {
+        await Promise.resolve();
+        strict_1.default.equal(execution_context_1.executionContext.requireTenantId(), 'tenant-1');
+        strict_1.default.equal(execution_context_1.executionContext.requireCurrent().source, 'job');
+    });
+});
+(0, node_test_1.default)('tenant-scoped work fails closed without a tenant', () => {
+    execution_context_1.executionContext.run({ correlationId: 'corr-2', source: 'http' }, () => strict_1.default.throws(() => execution_context_1.executionContext.requireTenantId(), execution_context_1.MissingTenantContextError));
+});

package/dist/context/index.d.ts

@@ -0,0 +1,2 @@
+export * from './execution-context';
+export * from './execution-context.interceptor';

package/dist/context/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./execution-context"), exports);
+__exportStar(require("./execution-context.interceptor"), exports);

package/dist/database/base.repository.d.ts

@@ -1,16 +1,28 @@
-import { Repository, SelectQueryBuilder, ObjectLiteral } from 'typeorm';
-import { IPaginator, IFilterPagination } from '@devstroupe/devkit-core';
+import { DeepPartial, ObjectLiteral, Repository, SelectQueryBuilder } from 'typeorm';
+import { IFilterPagination, IPaginator } from '@devstroupe/devkit-core';
 import { IQueryBuilderOptions } from './typeorm-query.builder';
-export declare abstract class BaseRepository<Entity extends ObjectLiteral, FilterDto extends IFilterPagination = IFilterPagination> {
+export interface BaseRepositoryOptions<Entity extends ObjectLiteral> {
+    idColumn?: keyof Entity & string;
+    alias?: string;
+    /** Trusted server-side scope, normally tenantId. */
+    scope?: () => Readonly<Partial<Entity>>;
+}
+export declare abstract class BaseRepository<Entity extends ObjectLiteral, ID = number, FilterDto extends IFilterPagination = IFilterPagination, ListProjection = Entity> {
     protected readonly repository: Repository<Entity>;
-    protected allowedFilters?: string[];
-    protected allowedSorts?: string[];
-    protected searchableFields?: string[];
-    constructor(repository: Repository<Entity>);
-    create(data: any): Promise<Entity>;
-    update(id: any, data: any): Promise<Entity>;
-    delete(id: any): Promise<void>;
-    findOne(id: any): Promise<Entity | null>;
-    findMany(filter: FilterDto): Promise<IPaginator<Entity>>;
-    protected paginate(qb: SelectQueryBuilder<Entity>, filter: any, options?: IQueryBuilderOptions): Promise<IPaginator<Entity>>;
+    private readonly options;
+    protected allowedFilters?: readonly string[];
+    protected allowedSorts?: readonly string[];
+    protected searchableFields?: readonly string[];
+    protected readonly idColumn: keyof Entity & string;
+    protected readonly alias: string;
+    constructor(repository: Repository<Entity>, options?: BaseRepositoryOptions<Entity>);
+    protected scope(): Readonly<Partial<Entity>>;
+    protected query(alias?: string): SelectQueryBuilder<Entity>;
+    create(data: DeepPartial<Entity>): Promise<Entity>;
+    update(id: ID, data: DeepPartial<Entity>): Promise<Entity>;
+    /** Performs one scoped UPDATE through TypeORM soft-delete; no restore API exists. */
+    delete(id: ID): Promise<void>;
+    findOne(id: ID): Promise<Entity | null>;
+    findMany(filter: FilterDto): Promise<IPaginator<ListProjection>>;
+    protected paginate<Projection extends ObjectLiteral = Entity>(qb: SelectQueryBuilder<Projection>, filter: FilterDto, options?: IQueryBuilderOptions<Projection>, project?: (entity: Projection) => ListProjection): Promise<IPaginator<ListProjection>>;
 }

package/dist/database/base.repository.js

@@ -1,61 +1,95 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseRepository = void 0;
+const devkit_core_1 = require("@devstroupe/devkit-core");
 const typeorm_query_builder_1 = require("./typeorm-query.builder");
 class BaseRepository {
     repository;
+    options;
     allowedFilters;
     allowedSorts;
     searchableFields;
-    constructor(repository) {
+    idColumn;
+    alias;
+    constructor(repository, options = {}) {
         this.repository = repository;
+        this.options = options;
+        this.idColumn = options.idColumn ?? 'id';
+        this.alias = options.alias ?? repository.metadata.name.toLowerCase();
+    }
+    scope() {
+        return this.options.scope?.() ?? {};
+    }
+    query(alias = this.alias) {
+        const qb = this.repository.createQueryBuilder(alias);
+        for (const [column, value] of Object.entries(this.scope())) {
+            qb.andWhere(`${alias}.${column} = :scope_${column}`, { [`scope_${column}`]: value });
+        }
+        return qb;
     }
     async create(data) {
-        const entity = this.repository.create(data);
-        return await this.repository.save(entity);
+        const entity = this.repository.create({ ...data, ...this.scope() });
+        return this.repository.save(entity);
     }
     async update(id, data) {
-        await this.repository.save({ id, ...data });
+        const current = await this.findOne(id);
+        if (!current)
+            throw new Error(`Entity with ID ${String(id)} not found`);
+        const entity = this.repository.merge(current, data, this.scope());
+        await this.repository.save(entity);
         const updated = await this.findOne(id);
-        if (!updated) {
-            throw new Error(`Entity with ID ${id} not found after update`);
-        }
+        if (!updated)
+            throw new Error(`Entity with ID ${String(id)} not found after update`);
         return updated;
     }
+    /** Performs one scoped UPDATE through TypeORM soft-delete; no restore API exists. */
     async delete(id) {
-        await this.repository.softDelete(id);
+        const metadata = this.repository.metadata;
+        const deleteColumn = metadata.deleteDateColumn;
+        if (!deleteColumn) {
+            throw new Error(`${metadata.name} must declare a DeleteDateColumn.`);
+        }
+        const qb = this.repository.createQueryBuilder(this.alias).softDelete();
+        qb.where(`${this.idColumn} = :id`, { id });
+        for (const [column, value] of Object.entries(this.scope())) {
+            qb.andWhere(`${column} = :scope_${column}`, { [`scope_${column}`]: value });
+        }
+        qb.andWhere(`${deleteColumn.propertyName} IS NULL`);
+        await qb.execute();
     }
     async findOne(id) {
-        return await this.repository.findOne({ where: { id } });
+        return this.query()
+            .andWhere(`${this.alias}.${this.idColumn} = :id`, { id })
+            .getOne();
     }
     async findMany(filter) {
-        const alias = this.repository.metadata.name.toLowerCase();
-        const queryBuilder = this.repository.createQueryBuilder(alias);
-        return await this.paginate(queryBuilder, filter, {
+        return this.paginate(this.query(), filter);
+    }
+    async paginate(qb, filter, options = {}, project = (entity) => entity) {
+        const configured = typeorm_query_builder_1.TypeOrmQueryBuilder.apply(qb, filter, {
             allowedFilters: this.allowedFilters,
             allowedSorts: this.allowedSorts,
             searchableFields: this.searchableFields,
+            ...options,
+        });
+        const includeTotal = filter.includeTotal !== false;
+        const [entities, total] = includeTotal
+            ? await configured.getManyAndCount()
+            : [await configured.getMany(), undefined];
+        const page = Math.max(1, Number(filter.page) || 1);
+        const limit = (0, devkit_core_1.resolvePaginationLimit)(filter.limit, {
+            defaultLimit: options.pagination?.defaultLimit ?? 20,
+            maxLimit: options.pagination?.maxLimit ?? 100,
         });
-    }
-    async paginate(qb, filter, options) {
-        const queryBuilder = typeorm_query_builder_1.TypeOrmQueryBuilder.apply(qb, filter, options);
-        const [items, totalItems] = await queryBuilder.getManyAndCount();
-        const page = Number(filter.page) || 1;
-        let limit = 10;
-        if (filter.limit === 'todos' || filter.limit === 'all') {
-            limit = totalItems;
-        }
-        else if (filter.limit) {
-            limit = Number(filter.limit);
-        }
         return {
-            items,
+            items: entities.map(project),
             meta: {
-                totalItems,
+                totalItems: total,
                 currentPage: page,
-                itemsPerPage: limit === 0 ? totalItems : limit,
-                itemCount: items.length,
-                totalPage: limit === 0 ? 1 : Math.ceil(totalItems / limit),
+                itemsPerPage: limit,
+                itemCount: entities.length,
+                totalPage: total === undefined ? undefined : Math.ceil(total / limit),
+                hasNextPage: total === undefined ? entities.length === limit : page * limit < total,
             },
         };
     }

package/dist/database/base.repository.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/database/base.repository.test.js

@@ -0,0 +1,46 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const strict_1 = __importDefault(require("node:assert/strict"));
+const node_test_1 = __importDefault(require("node:test"));
+const base_repository_1 = require("./base.repository");
+(0, node_test_1.default)('BaseRepository soft-delete includes ID, tenant and deleted marker in one command', async () => {
+    const conditions = [];
+    let executions = 0;
+    const deleteBuilder = {
+        softDelete() { return this; },
+        where(value) { conditions.push(value); return this; },
+        andWhere(value) { conditions.push(value); return this; },
+        async execute() { executions += 1; },
+    };
+    const repository = {
+        metadata: {
+            name: 'Invoice',
+            deleteDateColumn: { propertyName: 'deletedAt' },
+        },
+        createQueryBuilder() { return deleteBuilder; },
+    };
+    class InvoiceRepository extends base_repository_1.BaseRepository {
+        constructor() {
+            super(repository, { idColumn: 'uuid', scope: () => ({ tenantId: 'tenant-1' }) });
+        }
+    }
+    await new InvoiceRepository().delete('invoice-1');
+    strict_1.default.equal(executions, 1);
+    strict_1.default.deepEqual(conditions, [
+        'uuid = :id',
+        'tenantId = :scope_tenantId',
+        'deletedAt IS NULL',
+    ]);
+});
+(0, node_test_1.default)('BaseRepository refuses deletion when soft-delete metadata is absent', async () => {
+    const repository = {
+        metadata: { name: 'UnsafeEntity' },
+    };
+    class UnsafeRepository extends base_repository_1.BaseRepository {
+        constructor() { super(repository); }
+    }
+    await strict_1.default.rejects(() => new UnsafeRepository().delete(1), /DeleteDateColumn/);
+});