@devstroupe/devkit-nest 1.0.0

package/README.md

@@ -0,0 +1,72 @@
+# @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.
+
+## Instalação
+
+```bash
+npm install @devstroupe/devkit-nest
+```
+
+### Peer Dependencies
+```bash
+npm install @nestjs/common @nestjs/core @nestjs/swagger typeorm reflect-metadata
+```
+
+## Classes disponíveis
+
+### `BaseRepository<Entity>`
+
+Repositório TypeORM com parser automático de paginação e filtros. Todos os repositórios gerados pelo `devstroupe generate crud` herdam desta classe.
+
+```typescript
+import { BaseRepository } from '@devstroupe/devkit-nest';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+import { Cabin } from '../domain/entities/cabin.entity';
+
+@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>`
+
+Controller NestJS com endpoints CRUD padronizados e documentação Swagger automática.
+
+```typescript
+import { BaseCrudController } from '@devstroupe/devkit-nest';
+
+@Controller('cabins')
+export class CabinController extends BaseCrudController(
+  Cabin, CreateCabinDto, UpdateCabinDto
+) {}
+```
+
+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
+
+## Regras de governança
+
+A regra `use-standard-devkit-queries` do linter exige que:
+- Todos os **Controllers CRUD** herdem de `BaseCrudController`
+- Todos os **Repositories** herdem de `BaseRepository`
+
+Execute `devstroupe lint:rules` para verificar conformidade.

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

@@ -0,0 +1,16 @@
+import { Repository, SelectQueryBuilder, ObjectLiteral } from 'typeorm';
+import { IPaginator, IFilterPagination } from '@devstroupe/devkit-core';
+import { IQueryBuilderOptions } from './typeorm-query.builder';
+export declare abstract class BaseRepository<Entity extends ObjectLiteral, FilterDto extends IFilterPagination = IFilterPagination> {
+    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>>;
+}

package/dist/database/base.repository.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseRepository = void 0;
+const typeorm_query_builder_1 = require("./typeorm-query.builder");
+class BaseRepository {
+    repository;
+    allowedFilters;
+    allowedSorts;
+    searchableFields;
+    constructor(repository) {
+        this.repository = repository;
+    }
+    async create(data) {
+        const entity = this.repository.create(data);
+        return await this.repository.save(entity);
+    }
+    async update(id, data) {
+        await this.repository.save({ id, ...data });
+        const updated = await this.findOne(id);
+        if (!updated) {
+            throw new Error(`Entity with ID ${id} not found after update`);
+        }
+        return updated;
+    }
+    async delete(id) {
+        await this.repository.softDelete(id);
+    }
+    async findOne(id) {
+        return await this.repository.findOne({ where: { id } });
+    }
+    async findMany(filter) {
+        const alias = this.repository.metadata.name.toLowerCase();
+        const queryBuilder = this.repository.createQueryBuilder(alias);
+        return await this.paginate(queryBuilder, filter, {
+            allowedFilters: this.allowedFilters,
+            allowedSorts: this.allowedSorts,
+            searchableFields: this.searchableFields,
+        });
+    }
+    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,
+            meta: {
+                totalItems,
+                currentPage: page,
+                itemsPerPage: limit === 0 ? totalItems : limit,
+                itemCount: items.length,
+                totalPage: limit === 0 ? 1 : Math.ceil(totalItems / limit),
+            },
+        };
+    }
+}
+exports.BaseRepository = BaseRepository;

package/dist/database/factory-where.d.ts

@@ -0,0 +1,32 @@
+import { SelectQueryBuilder, ObjectLiteral } from 'typeorm';
+export declare const CONDITION_SUFFIXES: {
+    ARRAY: string;
+    DATE_START: string;
+    DATE_END: string;
+    IN: string;
+    NOT_IN: string;
+    BOOL: string;
+    GT: string;
+    GTE: string;
+    LT: string;
+    LTE: string;
+    NULL: string;
+    LIKE: string;
+    ILIKE: string;
+    NOT_LIKE: string;
+    NOT_ILIKE: string;
+};
+export declare class ConditionHandlers {
+    static handleArray<QR extends ObjectLiteral>(qb: SelectQueryBuilder<QR>, key: string, value: any, tableName: string): SelectQueryBuilder<QR>;
+    static handleDate<QR extends ObjectLiteral>(qb: SelectQueryBuilder<QR>, key: string, value: any, tableName: string, isEndDate: boolean): SelectQueryBuilder<QR>;
+    static handleInCondition<QR extends ObjectLiteral>(qb: SelectQueryBuilder<QR>, key: string, value: any, tableName: string, isNotIn?: boolean): SelectQueryBuilder<QR>;
+    static handleBoolean<QR extends ObjectLiteral>(qb: SelectQueryBuilder<QR>, key: string, value: any, tableName: string): SelectQueryBuilder<QR>;
+    static handleComparison<QR extends ObjectLiteral>(qb: SelectQueryBuilder<QR>, key: string, value: any, tableName: string, operator: '>' | '>=' | '<' | '<='): SelectQueryBuilder<QR>;
+    static handleNull<QR extends ObjectLiteral>(qb: SelectQueryBuilder<QR>, key: string, value: any, tableName: string): SelectQueryBuilder<QR>;
+    static handleDefault<QR extends ObjectLiteral>(qb: SelectQueryBuilder<QR>, key: string, value: any, tableName: string): SelectQueryBuilder<QR>;
+    static handleLike<QR extends ObjectLiteral>(qb: SelectQueryBuilder<QR>, key: string, value: any, tableName: string, options?: {
+        caseSensitive?: boolean;
+        not?: boolean;
+    }): SelectQueryBuilder<QR>;
+}
+export declare const factoryWhere: <QR extends ObjectLiteral, T>(queryBuilder: SelectQueryBuilder<QR>, where: T) => SelectQueryBuilder<QR>;

package/dist/database/factory-where.js

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.factoryWhere = exports.ConditionHandlers = exports.CONDITION_SUFFIXES = void 0;
+exports.CONDITION_SUFFIXES = {
+    ARRAY: '_$array',
+    DATE_START: '_$date_start',
+    DATE_END: '_$date_end',
+    IN: '_$in',
+    NOT_IN: '_$not_in',
+    BOOL: '_$bool',
+    GT: '_$gt',
+    GTE: '_$gte',
+    LT: '_$lt',
+    LTE: '_$lte',
+    NULL: '_$null',
+    LIKE: '_$like',
+    ILIKE: '_$ilike',
+    NOT_LIKE: '_$not_like',
+    NOT_ILIKE: '_$not_ilike',
+};
+function createParamName(key) {
+    return key.replace(/\./g, '_').replace(/[^a-zA-Z0-9_]/g, '') + Math.random().toString(36).slice(2, 6);
+}
+function StringToArray(value) {
+    if (Array.isArray(value))
+        return value;
+    if (typeof value === 'string') {
+        return value.split(',').map((v) => v.trim());
+    }
+    return [value];
+}
+function BooleanString(value) {
+    if (typeof value === 'boolean')
+        return value;
+    if (value === 'true' || value === '1' || value === 1)
+        return true;
+    return false;
+}
+function formatDateTime(value, isEndDate) {
+    const dateStr = typeof value === 'object' && value instanceof Date ? value.toISOString() : String(value);
+    if (dateStr.includes('T')) {
+        return dateStr;
+    }
+    // Se for apenas data YYYY-MM-DD
+    return isEndDate ? `${dateStr} 23:59:59` : `${dateStr} 00:00:00`;
+}
+class ConditionHandlers {
+    static handleArray(qb, key, value, tableName) {
+        const originalKey = key.replace(exports.CONDITION_SUFFIXES.ARRAY, '');
+        const paramName = `${createParamName(key)}_array`;
+        const prefix = key.includes('.') ? '' : `${tableName}.`;
+        const condition = `${prefix}${originalKey} IN (:${paramName})`;
+        return qb.andWhere(condition, {
+            [paramName]: StringToArray(value),
+        });
+    }
+    static handleDate(qb, key, value, tableName, isEndDate) {
+        const originalKey = key.replace(exports.CONDITION_SUFFIXES.DATE_END, '').replace(exports.CONDITION_SUFFIXES.DATE_START, '');
+        const paramName = `${createParamName(key)}_date`;
+        const operator = isEndDate ? '<=' : '>=';
+        const formattedDate = formatDateTime(value, isEndDate);
+        const prefix = key.includes('.') ? '' : `${tableName}.`;
+        const condition = `${prefix}${originalKey} ${operator} :${paramName}`;
+        return qb.andWhere(condition, { [paramName]: formattedDate });
+    }
+    static handleInCondition(qb, key, value, tableName, isNotIn = false) {
+        const originalKey = key.replace(isNotIn ? exports.CONDITION_SUFFIXES.NOT_IN : exports.CONDITION_SUFFIXES.IN, '');
+        const paramName = createParamName(key);
+        const prefix = key.includes('.') ? '' : `${tableName}.`;
+        const arr = StringToArray(value).map((v) => (typeof v === 'string' && /^\d+$/.test(v) ? Number(v) : v));
+        const condition = `${prefix}${originalKey} ${isNotIn ? 'NOT IN' : 'IN'} (:...${paramName})`;
+        return qb.andWhere(condition, { [paramName]: arr });
+    }
+    static handleBoolean(qb, key, value, tableName) {
+        const originalKey = key.replace(exports.CONDITION_SUFFIXES.BOOL, '');
+        const paramName = createParamName(key);
+        const prefix = key.includes('.') ? '' : `${tableName}.`;
+        const condition = `${prefix}${originalKey} = :${paramName}`;
+        return qb.andWhere(condition, { [paramName]: BooleanString(value) });
+    }
+    static handleComparison(qb, key, value, tableName, operator) {
+        const suffixMap = {
+            '>': exports.CONDITION_SUFFIXES.GT,
+            '>=': exports.CONDITION_SUFFIXES.GTE,
+            '<': exports.CONDITION_SUFFIXES.LT,
+            '<=': exports.CONDITION_SUFFIXES.LTE,
+        };
+        const originalKey = key.replace(suffixMap[operator], '');
+        const paramName = createParamName(key);
+        const prefix = key.includes('.') ? '' : `${tableName}.`;
+        const condition = `${prefix}${originalKey} ${operator} :${paramName}`;
+        return qb.andWhere(condition, { [paramName]: value });
+    }
+    static handleNull(qb, key, value, tableName) {
+        const originalKey = key.replace(exports.CONDITION_SUFFIXES.NULL, '');
+        const isNull = BooleanString(value);
+        const prefix = key.includes('.') ? '' : `${tableName}.`;
+        const condition = `${prefix}${originalKey} IS ${isNull ? 'NULL' : 'NOT NULL'}`;
+        return qb.andWhere(condition);
+    }
+    static handleDefault(qb, key, value, tableName) {
+        const paramName = createParamName(key);
+        if (key.includes('.')) {
+            return qb.andWhere(`${key} = :${paramName}`, { [paramName]: value });
+        }
+        return qb.andWhere(`${tableName}.${key} = :${paramName}`, { [paramName]: value });
+    }
+    static handleLike(qb, key, value, tableName, options = {}) {
+        const { caseSensitive = true, not = false } = options;
+        const originalKey = key
+            .replace(exports.CONDITION_SUFFIXES.LIKE, '')
+            .replace(exports.CONDITION_SUFFIXES.ILIKE, '')
+            .replace(exports.CONDITION_SUFFIXES.NOT_LIKE, '')
+            .replace(exports.CONDITION_SUFFIXES.NOT_ILIKE, '');
+        const paramName = createParamName(key);
+        const dbType = qb.connection.options.type;
+        const isMySQL = dbType === 'mysql' || dbType === 'mariadb';
+        const prefix = key.includes('.') ? '' : `${tableName}.`;
+        let condition;
+        let paramValue;
+        if (!caseSensitive && isMySQL) {
+            const operator = not ? 'NOT LIKE' : 'LIKE';
+            condition = `LOWER(${prefix}${originalKey}) ${operator} :${paramName}`;
+            paramValue = `%${String(value).toLowerCase()}%`;
+        }
+        else {
+            const operator = caseSensitive ? (not ? 'NOT LIKE' : 'LIKE') : not ? 'NOT ILIKE' : 'ILIKE';
+            condition = `${prefix}${originalKey} ${operator} :${paramName}`;
+            paramValue = `%${value}%`;
+        }
+        return qb.andWhere(condition, { [paramName]: paramValue });
+    }
+}
+exports.ConditionHandlers = ConditionHandlers;
+const CONDITION_HANDLERS = [
+    { suffix: exports.CONDITION_SUFFIXES.ARRAY, handle: (qb, k, v, t) => ConditionHandlers.handleArray(qb, k, v, t) },
+    { suffix: exports.CONDITION_SUFFIXES.DATE_END, handle: (qb, k, v, t) => ConditionHandlers.handleDate(qb, k, v, t, true) },
+    { suffix: exports.CONDITION_SUFFIXES.DATE_START, handle: (qb, k, v, t) => ConditionHandlers.handleDate(qb, k, v, t, false) },
+    { suffix: exports.CONDITION_SUFFIXES.IN, handle: (qb, k, v, t) => ConditionHandlers.handleInCondition(qb, k, v, t, false) },
+    { suffix: exports.CONDITION_SUFFIXES.NOT_IN, handle: (qb, k, v, t) => ConditionHandlers.handleInCondition(qb, k, v, t, true) },
+    { suffix: exports.CONDITION_SUFFIXES.BOOL, handle: (qb, k, v, t) => ConditionHandlers.handleBoolean(qb, k, v, t) },
+    { suffix: exports.CONDITION_SUFFIXES.GT, handle: (qb, k, v, t) => ConditionHandlers.handleComparison(qb, k, v, t, '>') },
+    { suffix: exports.CONDITION_SUFFIXES.GTE, handle: (qb, k, v, t) => ConditionHandlers.handleComparison(qb, k, v, t, '>=') },
+    { suffix: exports.CONDITION_SUFFIXES.LT, handle: (qb, k, v, t) => ConditionHandlers.handleComparison(qb, k, v, t, '<') },
+    { suffix: exports.CONDITION_SUFFIXES.LTE, handle: (qb, k, v, t) => ConditionHandlers.handleComparison(qb, k, v, t, '<=') },
+    { suffix: exports.CONDITION_SUFFIXES.NULL, handle: (qb, k, v, t) => ConditionHandlers.handleNull(qb, k, v, t) },
+    { suffix: exports.CONDITION_SUFFIXES.LIKE, handle: (qb, k, v, t) => ConditionHandlers.handleLike(qb, k, v, t, { caseSensitive: true, not: false }) },
+    { suffix: exports.CONDITION_SUFFIXES.ILIKE, handle: (qb, k, v, t) => ConditionHandlers.handleLike(qb, k, v, t, { caseSensitive: false, not: false }) },
+    { suffix: exports.CONDITION_SUFFIXES.NOT_LIKE, handle: (qb, k, v, t) => ConditionHandlers.handleLike(qb, k, v, t, { caseSensitive: true, not: true }) },
+    { suffix: exports.CONDITION_SUFFIXES.NOT_ILIKE, handle: (qb, k, v, t) => ConditionHandlers.handleLike(qb, k, v, t, { caseSensitive: false, not: true }) },
+];
+const factoryWhere = (queryBuilder, where) => {
+    if (!where || typeof where !== 'object')
+        return queryBuilder;
+    const tableName = queryBuilder.alias;
+    for (const [key, value] of Object.entries(where)) {
+        if (value === undefined || value === null || value === '')
+            continue;
+        try {
+            const handler = CONDITION_HANDLERS.find((h) => key.endsWith(h.suffix));
+            if (handler) {
+                queryBuilder = handler.handle(queryBuilder, key, value, tableName);
+            }
+            else {
+                queryBuilder = ConditionHandlers.handleDefault(queryBuilder, key, value, tableName);
+            }
+        }
+        catch (error) {
+            console.warn(`Erro ao processar condição para a chave "${key}":`, error);
+        }
+    }
+    return queryBuilder;
+};
+exports.factoryWhere = factoryWhere;

package/dist/database/factory-where.test.d.ts

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

package/dist/database/factory-where.test.js

@@ -0,0 +1,111 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_test_1 = require("node:test");
+const assert = __importStar(require("node:assert"));
+const factory_where_1 = require("./factory-where");
+// Mock de SelectQueryBuilder
+function createMockQueryBuilder(alias, dbType = 'postgres') {
+    const calls = [];
+    const qb = {
+        alias,
+        connection: {
+            options: {
+                type: dbType
+            }
+        },
+        andWhere(condition, params) {
+            calls.push({ condition, params });
+            return this;
+        },
+        getCalls() {
+            return calls;
+        }
+    };
+    return qb;
+}
+(0, node_test_1.test)('factoryWhere should process simple equality filters', () => {
+    const qb = createMockQueryBuilder('cabin');
+    const filter = {
+        company_id: 5,
+        name: 'Cabine A'
+    };
+    const result = (0, factory_where_1.factoryWhere)(qb, filter);
+    const calls = result.getCalls();
+    assert.strictEqual(calls.length, 2);
+    // Verifica primeiro filtro: company_id
+    assert.ok(calls[0].condition.startsWith('cabin.company_id = :company_id'));
+    assert.strictEqual(calls[0].params[Object.keys(calls[0].params)[0]], 5);
+    // Verifica segundo filtro: name
+    assert.ok(calls[1].condition.startsWith('cabin.name = :name'));
+    assert.strictEqual(calls[1].params[Object.keys(calls[1].params)[0]], 'Cabine A');
+});
+(0, node_test_1.test)('factoryWhere should process suffixes correctly', () => {
+    const qb = createMockQueryBuilder('cabin');
+    const filter = {
+        'is_active_$bool': 'true',
+        'code_$like': 'TX',
+        'company_id_$in': '1,2,3',
+        'id_$gt': 10
+    };
+    const result = (0, factory_where_1.factoryWhere)(qb, filter);
+    const calls = result.getCalls();
+    assert.strictEqual(calls.length, 4);
+    // 1. is_active_$bool
+    assert.ok(calls[0].condition.startsWith('cabin.is_active = :is_active_bool'));
+    assert.strictEqual(calls[0].params[Object.keys(calls[0].params)[0]], true);
+    // 2. code_$like
+    assert.ok(calls[1].condition.startsWith('cabin.code LIKE :code_like'));
+    assert.strictEqual(calls[1].params[Object.keys(calls[1].params)[0]], '%TX%');
+    // 3. company_id_$in
+    assert.ok(calls[2].condition.startsWith('cabin.company_id IN (:...company_id_in'));
+    assert.deepStrictEqual(calls[2].params[Object.keys(calls[2].params)[0]], [1, 2, 3]);
+    // 4. id_$gt
+    assert.ok(calls[3].condition.startsWith('cabin.id > :id_gt'));
+    assert.strictEqual(calls[3].params[Object.keys(calls[3].params)[0]], 10);
+});
+(0, node_test_1.test)('factoryWhere should ignore empty, null, and undefined values', () => {
+    const qb = createMockQueryBuilder('cabin');
+    const filter = {
+        name: '',
+        code: null,
+        company_id: undefined,
+        is_active: true
+    };
+    const result = (0, factory_where_1.factoryWhere)(qb, filter);
+    const calls = result.getCalls();
+    assert.strictEqual(calls.length, 1);
+    assert.ok(calls[0].condition.startsWith('cabin.is_active = :is_active'));
+});

package/dist/database/typeorm-query.builder.d.ts

@@ -0,0 +1,11 @@
+import { SelectQueryBuilder, ObjectLiteral } from 'typeorm';
+import { IFilterPagination } from '@devstroupe/devkit-core';
+export interface IQueryBuilderOptions {
+    allowedFilters?: string[];
+    allowedSorts?: string[];
+    searchableFields?: string[];
+}
+export declare class TypeOrmQueryBuilder {
+    static apply<Entity extends ObjectLiteral>(qb: SelectQueryBuilder<Entity>, filter: IFilterPagination, options?: IQueryBuilderOptions): SelectQueryBuilder<Entity>;
+    private static parseStructuredValue;
+}

package/dist/database/typeorm-query.builder.js

@@ -0,0 +1,192 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TypeOrmQueryBuilder = void 0;
+const typeorm_1 = require("typeorm");
+class TypeOrmQueryBuilder {
+    static apply(qb, filter, options = {}) {
+        const alias = qb.alias;
+        const { allowedFilters, allowedSorts, searchableFields } = options;
+        const structuredFilter = this.parseStructuredValue(filter.filter);
+        const structuredSort = this.parseStructuredValue(filter.sort);
+        // 1. Paginação e Limite
+        const page = Number(filter.page) || 1;
+        let limit = 10;
+        if (filter.limit === 'todos' || filter.limit === 'all') {
+            limit = 0;
+        }
+        else if (filter.limit) {
+            limit = Number(filter.limit);
+        }
+        if (limit > 0) {
+            qb.take(limit).skip((page - 1) * limit);
+        }
+        // 2. Busca Global (search)
+        if (filter.search && searchableFields?.length) {
+            qb.andWhere(new typeorm_1.Brackets((subQb) => {
+                searchableFields.forEach((field, index) => {
+                    const paramName = `search_param_${index}_${Math.random().toString(36).slice(2, 6)}`;
+                    const fullField = field.includes('.') ? field : `${alias}.${field}`;
+                    subQb.orWhere(`LOWER(${fullField}) LIKE :${paramName}`, {
+                        [paramName]: `%${String(filter.search).toLowerCase()}%`,
+                    });
+                });
+            }));
+        }
+        // 3. Filtros Estruturados (filter[field][operator]=value ou filter[field]=value)
+        if (structuredFilter) {
+            for (const [rawField, value] of Object.entries(structuredFilter)) {
+                // Tratar sufixos legados para retrocompatibilidade
+                let field = rawField;
+                let inferredOperator = null;
+                if (field.endsWith('_$bool')) {
+                    field = field.replace('_$bool', '');
+                    inferredOperator = 'eq';
+                }
+                else if (field.endsWith('_$like') || field.endsWith('_$ilike')) {
+                    field = field.replace(/_\$i?like/, '');
+                    inferredOperator = 'contains';
+                }
+                else if (field.endsWith('_$date_start') || field.endsWith('_$gte')) {
+                    field = field.replace(/_\$(date_start|gte)/, '');
+                    inferredOperator = 'gte';
+                }
+                else if (field.endsWith('_$date_end') || field.endsWith('_$lte')) {
+                    field = field.replace(/_\$(date_end|lte)/, '');
+                    inferredOperator = 'lte';
+                }
+                else if (field.endsWith('_$in')) {
+                    field = field.replace('_$in', '');
+                    inferredOperator = 'in';
+                }
+                else if (field.endsWith('_$not_in')) {
+                    field = field.replace('_$not_in', '');
+                    inferredOperator = 'notIn';
+                }
+                else if (field.endsWith('_$null')) {
+                    field = field.replace('_$null', '');
+                    inferredOperator = 'isNull';
+                }
+                // Validação de campos permitidos
+                if (allowedFilters && !allowedFilters.includes(field)) {
+                    console.warn(`Filter on field "${field}" is not allowed.`);
+                    continue;
+                }
+                const prefix = field.includes('.') ? '' : `${alias}.`;
+                const fullField = `${prefix}${field}`;
+                const applyCondition = (op, val) => {
+                    if (val === undefined || val === null || val === '')
+                        return;
+                    const paramName = `${field.replace(/\./g, '_')}_${op}_${Math.random().toString(36).slice(2, 6)}`;
+                    switch (op) {
+                        case 'eq':
+                            qb.andWhere(`${fullField} = :${paramName}`, { [paramName]: val });
+                            break;
+                        case 'neq':
+                            qb.andWhere(`${fullField} != :${paramName}`, { [paramName]: val });
+                            break;
+                        case 'contains':
+                            qb.andWhere(`LOWER(${fullField}) LIKE :${paramName}`, { [paramName]: `%${String(val).toLowerCase()}%` });
+                            break;
+                        case 'startsWith':
+                            qb.andWhere(`LOWER(${fullField}) LIKE :${paramName}`, { [paramName]: `${String(val).toLowerCase()}%` });
+                            break;
+                        case 'endsWith':
+                            qb.andWhere(`LOWER(${fullField}) LIKE :${paramName}`, { [paramName]: `%${String(val).toLowerCase()}` });
+                            break;
+                        case 'gt':
+                            qb.andWhere(`${fullField} > :${paramName}`, { [paramName]: val });
+                            break;
+                        case 'gte':
+                            qb.andWhere(`${fullField} >= :${paramName}`, { [paramName]: val });
+                            break;
+                        case 'lt':
+                            qb.andWhere(`${fullField} < :${paramName}`, { [paramName]: val });
+                            break;
+                        case 'lte':
+                            qb.andWhere(`${fullField} <= :${paramName}`, { [paramName]: val });
+                            break;
+                        case 'in':
+                            const inArr = Array.isArray(val) ? val : String(val).split(',').map((s) => s.trim());
+                            if (inArr.length > 0) {
+                                qb.andWhere(`${fullField} IN (:...${paramName})`, { [paramName]: inArr });
+                            }
+                            break;
+                        case 'notIn':
+                            const notInArr = Array.isArray(val) ? val : String(val).split(',').map((s) => s.trim());
+                            if (notInArr.length > 0) {
+                                qb.andWhere(`${fullField} NOT IN (:...${paramName})`, { [paramName]: notInArr });
+                            }
+                            break;
+                        case 'between':
+                            const betweenArr = Array.isArray(val) ? val : String(val).split(',').map((s) => s.trim());
+                            if (betweenArr.length === 2) {
+                                const p1 = `${paramName}_1`;
+                                const p2 = `${paramName}_2`;
+                                qb.andWhere(`${fullField} BETWEEN :${p1} AND :${p2}`, { [p1]: betweenArr[0], [p2]: betweenArr[1] });
+                            }
+                            break;
+                        case 'isNull':
+                            const isNullVal = typeof val === 'boolean' ? val : val === 'true' || val === '1';
+                            qb.andWhere(`${fullField} IS ${isNullVal ? 'NULL' : 'NOT NULL'}`);
+                            break;
+                        case 'isNotNull':
+                            const isNotNullVal = typeof val === 'boolean' ? val : val === 'true' || val === '1';
+                            qb.andWhere(`${fullField} IS ${isNotNullVal ? 'NOT NULL' : 'NULL'}`);
+                            break;
+                    }
+                };
+                if (inferredOperator) {
+                    applyCondition(inferredOperator, value);
+                }
+                else if (typeof value === 'object' && value !== null && !Array.isArray(value) && !(value instanceof Date)) {
+                    for (const [op, val] of Object.entries(value)) {
+                        applyCondition(op, val);
+                    }
+                }
+                else {
+                    // Valor direto, mapeia para 'eq'
+                    applyCondition('eq', value);
+                }
+            }
+        }
+        // 4. Ordenação Estruturada (sort[field]=asc)
+        if (structuredSort) {
+            for (const [field, direction] of Object.entries(structuredSort)) {
+                if (allowedSorts && !allowedSorts.includes(field)) {
+                    console.warn(`Sorting on field "${field}" is not allowed.`);
+                    continue;
+                }
+                const orderDirection = String(direction).toUpperCase() === 'DESC' ? 'DESC' : 'ASC';
+                const fullField = field.includes('.') ? field : `${alias}.${field}`;
+                qb.addOrderBy(fullField, orderDirection);
+            }
+        }
+        else if (filter.sort && typeof filter.sort === 'string' && filter.direction) {
+            // Retrocompatibilidade com query params planos (sort=name&direction=desc)
+            const field = filter.sort;
+            if (!allowedSorts || allowedSorts.includes(field)) {
+                const orderDirection = String(filter.direction).toUpperCase() === 'DESC' ? 'DESC' : 'ASC';
+                const fullField = field.includes('.') ? field : `${alias}.${field}`;
+                qb.addOrderBy(fullField, orderDirection);
+            }
+        }
+        return qb;
+    }
+    static parseStructuredValue(value) {
+        if (value && typeof value === 'object' && !Array.isArray(value)) {
+            return value;
+        }
+        if (typeof value !== 'string' || !value.trim().startsWith('{'))
+            return undefined;
+        try {
+            const parsed = JSON.parse(value);
+            return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+                ? parsed
+                : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+exports.TypeOrmQueryBuilder = TypeOrmQueryBuilder;

package/dist/database/typeorm-query.builder.test.d.ts

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

package/dist/database/typeorm-query.builder.test.js

@@ -0,0 +1,29 @@
+"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 typeorm_query_builder_1 = require("./typeorm-query.builder");
+function createQueryBuilder() {
+    const conditions = [];
+    return {
+        alias: 'cabin',
+        take() { return this; },
+        skip() { return this; },
+        andWhere(condition, params) {
+            conditions.push({ condition, params });
+            return this;
+        },
+        addOrderBy() { return this; },
+        conditions,
+    };
+}
+(0, node_test_1.default)('TypeOrmQueryBuilder parses JSON relationship filters from HTTP query params', () => {
+    const queryBuilder = createQueryBuilder();
+    typeorm_query_builder_1.TypeOrmQueryBuilder.apply(queryBuilder, { filter: JSON.stringify({ company_id: 42 }) }, { allowedFilters: ['company_id'] });
+    strict_1.default.equal(queryBuilder.conditions.length, 1);
+    strict_1.default.match(queryBuilder.conditions[0].condition, /^cabin\.company_id = :company_id_eq_/);
+    strict_1.default.equal(Object.values(queryBuilder.conditions[0].params)[0], 42);
+});

package/dist/http/base-crud.controller.d.ts

@@ -0,0 +1,9 @@
+export declare abstract class BaseCrudController<Entity, FilterDto = any> {
+    protected readonly service: any;
+    constructor(service: any);
+    create(body: any): Promise<Entity>;
+    update(id: string, body: any): Promise<Entity>;
+    findMany(filter: FilterDto): Promise<any>;
+    findById(id: string): Promise<Entity>;
+    delete(id: string): Promise<void>;
+}

package/dist/http/base-crud.controller.js

@@ -0,0 +1,82 @@
+"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;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseCrudController = void 0;
+const common_1 = require("@nestjs/common");
+const swagger_1 = require("@nestjs/swagger");
+class BaseCrudController {
+    service;
+    constructor(service) {
+        this.service = service;
+    }
+    async create(body) {
+        return await this.service.create(body);
+    }
+    async update(id, body) {
+        return await this.service.update(+id, body);
+    }
+    async findMany(filter) {
+        return await this.service.findMany(filter);
+    }
+    async findById(id) {
+        return await this.service.findOne(+id);
+    }
+    async delete(id) {
+        return await this.service.delete(+id);
+    }
+}
+exports.BaseCrudController = BaseCrudController;
+__decorate([
+    (0, common_1.Post)(),
+    (0, swagger_1.ApiOperation)({ summary: 'Create entity' }),
+    (0, swagger_1.ApiResponse)({ status: 201, description: 'Created successfully' }),
+    __param(0, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], BaseCrudController.prototype, "create", null);
+__decorate([
+    (0, common_1.Put)(':id'),
+    (0, swagger_1.ApiOperation)({ summary: 'Update entity' }),
+    (0, swagger_1.ApiResponse)({ status: 200, description: 'Updated successfully' }),
+    __param(0, (0, common_1.Param)('id')),
+    __param(1, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object]),
+    __metadata("design:returntype", Promise)
+], BaseCrudController.prototype, "update", null);
+__decorate([
+    (0, common_1.Get)(),
+    (0, swagger_1.ApiOperation)({ summary: 'List entities with filter and pagination' }),
+    __param(0, (0, common_1.Query)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], BaseCrudController.prototype, "findMany", null);
+__decorate([
+    (0, common_1.Get)(':id'),
+    (0, swagger_1.ApiOperation)({ summary: 'Find entity by ID' }),
+    __param(0, (0, common_1.Param)('id')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Promise)
+], BaseCrudController.prototype, "findById", null);
+__decorate([
+    (0, common_1.Delete)(':id'),
+    (0, swagger_1.ApiOperation)({ summary: 'Delete entity' }),
+    __param(0, (0, common_1.Param)('id')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Promise)
+], BaseCrudController.prototype, "delete", null);

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './database/factory-where';
+export * from './database/base.repository';
+export * from './database/typeorm-query.builder';
+export * from './http/base-crud.controller';

package/dist/index.js

@@ -0,0 +1,20 @@
+"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("./database/factory-where"), exports);
+__exportStar(require("./database/base.repository"), exports);
+__exportStar(require("./database/typeorm-query.builder"), exports);
+__exportStar(require("./http/base-crud.controller"), exports);

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@devstroupe/devkit-nest",
+  "version": "1.0.0",
+  "description": "DevsTroupe Development Kit — NestJS base classes: BaseRepository, BaseCrudController and query parsers",
+  "license": "MIT",
+  "keywords": [
+    "devstroupe",
+    "devkit",
+    "nestjs",
+    "typeorm",
+    "crud",
+    "repository",
+    "base-controller",
+    "typescript"
+  ],
+  "homepage": "https://github.com/devstroupe/devkit#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/devstroupe/devkit.git",
+    "directory": "packages/devkit-nest"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "@devstroupe/devkit-core": "^1.0.0"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^10.0.0 || ^11.0.0",
+    "@nestjs/core": "^10.0.0 || ^11.0.0",
+    "@nestjs/swagger": "^7.0.0 || ^8.0.0 || ^9.0.0 || ^10.0.0 || ^11.0.0",
+    "typeorm": "^0.3.0",
+    "reflect-metadata": "^0.1.13 || ^0.2.0"
+  },
+  "devDependencies": {
+    "@nestjs/common": "^10.3.8",
+    "@nestjs/core": "^10.3.8",
+    "@nestjs/swagger": "^7.3.1",
+    "@types/node": "^20.11.0",
+    "typeorm": "^0.3.17",
+    "reflect-metadata": "^0.1.13",
+    "typescript": "^5.4.5"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "tsc && node --test dist/**/*.test.js"
+  }
+}