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

package/dist/database/typeorm-explain.d.ts

@@ -0,0 +1,3 @@
+import type { DataSource, ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+/** Test/harness helper. Never expose database plans in a public endpoint. */
+export declare function explainQuery<Row extends ObjectLiteral = ObjectLiteral>(dataSource: Pick<DataSource, 'query'>, queryBuilder: Pick<SelectQueryBuilder<Row>, 'getQueryAndParameters'>): Promise<unknown[]>;

package/dist/database/typeorm-explain.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.explainQuery = explainQuery;
+/** Test/harness helper. Never expose database plans in a public endpoint. */
+async function explainQuery(dataSource, queryBuilder) {
+    const [sql, parameters] = queryBuilder.getQueryAndParameters();
+    return dataSource.query(`EXPLAIN ${sql}`, parameters);
+}

package/dist/database/typeorm-explain.test.d.ts

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

package/dist/database/typeorm-explain.test.js

@@ -0,0 +1,15 @@
+"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_explain_1 = require("./typeorm-explain");
+(0, node_test_1.default)('EXPLAIN harness preserves QueryBuilder parameters', async () => {
+    const calls = [];
+    const source = { query: async (...args) => { calls.push(args); return []; } };
+    const qb = { getQueryAndParameters: () => ['SELECT * FROM invoices WHERE tenant_id = ?', ['tenant-1']] };
+    await (0, typeorm_explain_1.explainQuery)(source, qb);
+    strict_1.default.deepEqual(calls, [['EXPLAIN SELECT * FROM invoices WHERE tenant_id = ?', ['tenant-1']]]);
+});

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

@@ -1,11 +1,39 @@
-import { SelectQueryBuilder, ObjectLiteral } from 'typeorm';
-import { IFilterPagination } from '@devstroupe/devkit-core';
-export interface IQueryBuilderOptions {
-    allowedFilters?: string[];
-    allowedSorts?: string[];
-    searchableFields?: string[];
+import { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+import { IFilterOperators, IFilterPagination, IPaginationPolicy } from '@devstroupe/devkit-core';
+export type PublicFilterOperator = keyof IFilterOperators | 'eq';
+export interface FilterDefinition<Entity extends ObjectLiteral> {
+    /** Trusted SQL expression declared by the application, never by the client. */
+    expression: string | ((alias: string) => string);
+    operators?: readonly PublicFilterOperator[];
+    transform?: (value: unknown) => unknown;
 }
+export type FilterRegistry<Entity extends ObjectLiteral> = Record<string, FilterDefinition<Entity>>;
+export interface MySqlFullTextSearchDefinition {
+    /** Trusted entity fields configured by the application, never by the client. */
+    fields: readonly string[];
+    mode?: 'natural' | 'boolean';
+}
+export interface IQueryBuilderOptions<Entity extends ObjectLiteral = ObjectLiteral> {
+    filterRegistry?: FilterRegistry<Entity>;
+    /** Transitional compatibility. Values are validated before becoming expressions. */
+    allowedFilters?: readonly string[];
+    allowedSorts?: readonly string[];
+    searchableFields?: readonly string[];
+    /** Uses MySQL MATCH ... AGAINST for indexes configured as FULLTEXT. */
+    fullTextSearch?: MySqlFullTextSearchDefinition;
+    /** Field used by readers that need a separate COUNT(DISTINCT ...) query. */
+    distinctCountField?: string;
+    pagination?: Partial<IPaginationPolicy>;
+    cursor?: {
+        field: string;
+        direction?: 'ASC' | 'DESC';
+    };
+    onUnknownFilter?: (field: string) => void;
+    /** Internal reader controls for an unbounded count query. */
+    applyPagination?: boolean;
+    applySorting?: boolean;
+}
+export declare function trustedQueryExpression(alias: string, field: string): string;
 export declare class TypeOrmQueryBuilder {
-    static apply<Entity extends ObjectLiteral>(qb: SelectQueryBuilder<Entity>, filter: IFilterPagination, options?: IQueryBuilderOptions): SelectQueryBuilder<Entity>;
-    private static parseStructuredValue;
+    static apply<Entity extends ObjectLiteral>(qb: SelectQueryBuilder<Entity>, filter: IFilterPagination, options?: IQueryBuilderOptions<Entity>): SelectQueryBuilder<Entity>;
 }

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

@@ -1,192 +1,177 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TypeOrmQueryBuilder = void 0;
+exports.trustedQueryExpression = trustedQueryExpression;
 const typeorm_1 = require("typeorm");
+const devkit_core_1 = require("@devstroupe/devkit-core");
+const SAFE_FIELD = /^[a-zA-Z_][a-zA-Z0-9_]*(?:\.[a-zA-Z_][a-zA-Z0-9_]*)?$/;
+function trustedQueryExpression(alias, field) {
+    if (!SAFE_FIELD.test(field))
+        throw new Error(`Unsafe configured query field: ${field}`);
+    return field.includes('.') ? field : `${alias}.${field}`;
+}
+function structuredValue(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;
+    }
+}
+function legacyField(raw) {
+    const suffixes = [
+        ['_$bool', 'eq'], ['_$ilike', 'contains'], ['_$like', 'contains'],
+        ['_$date_start', 'gte'], ['_$date_end', 'lte'], ['_$not_in', 'notIn'],
+        ['_$gte', 'gte'], ['_$lte', 'lte'], ['_$in', 'in'], ['_$null', 'isNull'],
+    ];
+    const matched = suffixes.find(([suffix]) => raw.endsWith(suffix));
+    return matched
+        ? { field: raw.slice(0, -matched[0].length), operator: matched[1] }
+        : { field: raw };
+}
 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) {
+        const policy = {
+            defaultLimit: options.pagination?.defaultLimit ?? devkit_core_1.DEFAULT_PAGINATION_POLICY.defaultLimit,
+            maxLimit: options.pagination?.maxLimit ?? devkit_core_1.DEFAULT_PAGINATION_POLICY.maxLimit,
+        };
+        if (options.applyPagination !== false) {
+            const limit = (0, devkit_core_1.resolvePaginationLimit)(filter.limit, policy);
+            const page = Math.max(1, Number(filter.page) || 1);
             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()}%`,
+        let parameterSequence = 0;
+        const parameter = (field, operator) => `devkit_${field.replace(/[^a-zA-Z0-9_]/g, '_')}_${operator}_${parameterSequence++}`;
+        const fullText = options.fullTextSearch;
+        const searchable = options.searchableFields ?? [];
+        if (filter.search && fullText?.fields.length) {
+            const fields = fullText.fields.map((field) => trustedQueryExpression(alias, field));
+            const mode = fullText.mode === 'boolean' ? ' IN BOOLEAN MODE' : '';
+            qb.andWhere(`MATCH(${fields.join(', ')}) AGAINST (:devkit_fulltext${mode})`, {
+                devkit_fulltext: filter.search,
+            });
+        }
+        else if (filter.search && searchable.length) {
+            qb.andWhere(new typeorm_1.Brackets((nested) => {
+                searchable.forEach((field, index) => {
+                    const expression = trustedQueryExpression(alias, field);
+                    nested.orWhere(`LOWER(${expression}) LIKE :devkit_search_${index}`, {
+                        [`devkit_search_${index}`]: `%${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.`);
+        const configuredRegistry = options.filterRegistry ?? {};
+        const compatibilityRegistry = Object.fromEntries((options.allowedFilters ?? []).map((field) => [field, { expression: trustedQueryExpression(alias, field) }]));
+        const registry = { ...compatibilityRegistry, ...configuredRegistry };
+        const parsedFilters = structuredValue(filter.filter);
+        for (const [rawField, rawValue] of Object.entries(parsedFilters ?? {})) {
+            const legacy = legacyField(rawField);
+            const definition = registry[legacy.field];
+            if (!definition) {
+                options.onUnknownFilter?.(legacy.field);
+                continue;
+            }
+            const expression = typeof definition.expression === 'function'
+                ? definition.expression(alias)
+                : definition.expression;
+            const allowedOperators = definition.operators ?? ['eq', 'neq', 'contains', 'startsWith', 'endsWith', 'gt', 'gte', 'lt', 'lte', 'in', 'notIn', 'between', 'isNull', 'isNotNull'];
+            const operations = legacy.operator
+                ? [[legacy.operator, rawValue]]
+                : rawValue && typeof rawValue === 'object' && !Array.isArray(rawValue)
+                    ? Object.entries(rawValue)
+                    : [['eq', rawValue]];
+            for (const [rawOperator, inputValue] of operations) {
+                const operator = rawOperator;
+                if (!allowedOperators.includes(operator))
                     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;
+                const value = definition.transform ? definition.transform(inputValue) : inputValue;
+                if (value === undefined || value === null || value === '')
+                    continue;
+                const param = parameter(legacy.field, operator);
+                switch (operator) {
+                    case 'eq':
+                        qb.andWhere(`${expression} = :${param}`, { [param]: value });
+                        break;
+                    case 'neq':
+                        qb.andWhere(`${expression} != :${param}`, { [param]: value });
+                        break;
+                    case 'contains':
+                        qb.andWhere(`LOWER(${expression}) LIKE :${param}`, { [param]: `%${String(value).toLowerCase()}%` });
+                        break;
+                    case 'startsWith':
+                        qb.andWhere(`LOWER(${expression}) LIKE :${param}`, { [param]: `${String(value).toLowerCase()}%` });
+                        break;
+                    case 'endsWith':
+                        qb.andWhere(`LOWER(${expression}) LIKE :${param}`, { [param]: `%${String(value).toLowerCase()}` });
+                        break;
+                    case 'gt':
+                        qb.andWhere(`${expression} > :${param}`, { [param]: value });
+                        break;
+                    case 'gte':
+                        qb.andWhere(`${expression} >= :${param}`, { [param]: value });
+                        break;
+                    case 'lt':
+                        qb.andWhere(`${expression} < :${param}`, { [param]: value });
+                        break;
+                    case 'lte':
+                        qb.andWhere(`${expression} <= :${param}`, { [param]: value });
+                        break;
+                    case 'in':
+                    case 'notIn': {
+                        const values = Array.isArray(value) ? value : String(value).split(',').map((item) => item.trim());
+                        if (values.length)
+                            qb.andWhere(`${expression} ${operator === 'in' ? 'IN' : 'NOT IN'} (:...${param})`, { [param]: values });
+                        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);
+                    case 'between': {
+                        const values = Array.isArray(value) ? value : String(value).split(',').map((item) => item.trim());
+                        if (values.length === 2)
+                            qb.andWhere(`${expression} BETWEEN :${param}_from AND :${param}_to`, {
+                                [`${param}_from`]: values[0], [`${param}_to`]: values[1],
+                            });
+                        break;
+                    }
+                    case 'isNull':
+                    case 'isNotNull': {
+                        const truthy = value === true || value === 'true' || value === '1';
+                        const wantsNull = operator === 'isNull' ? truthy : !truthy;
+                        qb.andWhere(`${expression} IS ${wantsNull ? 'NULL' : 'NOT NULL'}`);
+                        break;
                     }
-                }
-                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;
+        if (options.applySorting !== false) {
+            const parsedSort = structuredValue(filter.sort);
+            if (parsedSort) {
+                for (const [field, direction] of Object.entries(parsedSort)) {
+                    if (!options.allowedSorts?.includes(field))
+                        continue;
+                    qb.addOrderBy(trustedQueryExpression(alias, field), String(direction).toUpperCase() === 'DESC' ? 'DESC' : 'ASC');
                 }
-                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);
+            else if (typeof filter.sort === 'string' && options.allowedSorts?.includes(filter.sort)) {
+                qb.addOrderBy(trustedQueryExpression(alias, filter.sort), String(filter.direction).toUpperCase() === 'DESC' ? 'DESC' : 'ASC');
             }
         }
-        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;
+        if (filter.cursor && options.cursor) {
+            const cursorExpression = trustedQueryExpression(alias, options.cursor.field);
+            const cursorParam = parameter(options.cursor.field, 'cursor');
+            const direction = options.cursor.direction ?? 'ASC';
+            qb.andWhere(`${cursorExpression} ${direction === 'ASC' ? '>' : '<'} :${cursorParam}`, { [cursorParam]: filter.cursor });
+            qb.addOrderBy(cursorExpression, direction);
         }
+        return qb;
     }
 }
 exports.TypeOrmQueryBuilder = TypeOrmQueryBuilder;

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

@@ -24,6 +24,37 @@ function createQueryBuilder() {
     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.match(queryBuilder.conditions[0].condition, /^cabin\.company_id = :devkit_company_id_eq_/);
     strict_1.default.equal(Object.values(queryBuilder.conditions[0].params)[0], 42);
 });
+(0, node_test_1.default)('TypeOrmQueryBuilder caps all and ignores unknown public fields', () => {
+    const queryBuilder = createQueryBuilder();
+    let taken = 0;
+    const unknown = [];
+    queryBuilder.take = (value) => { taken = value; return queryBuilder; };
+    typeorm_query_builder_1.TypeOrmQueryBuilder.apply(queryBuilder, { limit: 'all', filter: { injected: { eq: 'x' } } }, { allowedFilters: ['name'], pagination: { maxLimit: 50 }, onUnknownFilter: (field) => unknown.push(field) });
+    strict_1.default.equal(taken, 50);
+    strict_1.default.equal(queryBuilder.conditions.length, 0);
+    strict_1.default.deepEqual(unknown, ['injected']);
+});
+(0, node_test_1.default)('TypeOrmQueryBuilder applies keyset cursor with a trusted configured field', () => {
+    const queryBuilder = createQueryBuilder();
+    typeorm_query_builder_1.TypeOrmQueryBuilder.apply(queryBuilder, { cursor: '100' }, { cursor: { field: 'id', direction: 'ASC' } });
+    strict_1.default.match(queryBuilder.conditions[0].condition, /^cabin\.id > :devkit_id_cursor_/);
+    strict_1.default.equal(Object.values(queryBuilder.conditions[0].params)[0], '100');
+});
+(0, node_test_1.default)('TypeOrmQueryBuilder uses a typed registry expression and parameters', () => {
+    const queryBuilder = createQueryBuilder();
+    typeorm_query_builder_1.TypeOrmQueryBuilder.apply(queryBuilder, { filter: { status: { eq: 'active' } } }, { filterRegistry: { status: { expression: (alias) => `${alias}.internal_status`, operators: ['eq'] } } });
+    strict_1.default.match(queryBuilder.conditions[0].condition, /^cabin\.internal_status = :devkit_status_eq_/);
+    strict_1.default.equal(Object.values(queryBuilder.conditions[0].params)[0], 'active');
+});
+(0, node_test_1.default)('TypeOrmQueryBuilder applies trusted MySQL full-text search without exposing SQL fields', () => {
+    const queryBuilder = createQueryBuilder();
+    typeorm_query_builder_1.TypeOrmQueryBuilder.apply(queryBuilder, { search: 'blue widget' }, { fullTextSearch: { fields: ['name', 'description'], mode: 'boolean' } });
+    strict_1.default.equal(queryBuilder.conditions[0].condition, 'MATCH(cabin.name, cabin.description) AGAINST (:devkit_fulltext IN BOOLEAN MODE)');
+    strict_1.default.deepEqual(queryBuilder.conditions[0].params, { devkit_fulltext: 'blue widget' });
+    strict_1.default.throws(() => typeorm_query_builder_1.TypeOrmQueryBuilder.apply(createQueryBuilder(), { search: 'x' }, {
+        fullTextSearch: { fields: ['name) AGAINST (secret'] },
+    }), /Unsafe configured query field/);
+});

package/dist/database/typeorm-reader.d.ts

@@ -0,0 +1,9 @@
+import type { ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+import type { IFilterPagination, IPaginator } from '@devstroupe/devkit-core';
+import type { ReadModelReader } from '../application';
+import { IQueryBuilderOptions } from './typeorm-query.builder';
+export declare abstract class TypeOrmReader<Source extends ObjectLiteral, Row, Filter extends IFilterPagination = IFilterPagination> implements ReadModelReader<Row, Filter> {
+    protected abstract query(): SelectQueryBuilder<Source>;
+    protected abstract options(): IQueryBuilderOptions<Source>;
+    read(filter: Filter): Promise<IPaginator<Row>>;
+}

package/dist/database/typeorm-reader.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TypeOrmReader = void 0;
+const devkit_core_1 = require("@devstroupe/devkit-core");
+const typeorm_query_builder_1 = require("./typeorm-query.builder");
+class TypeOrmReader {
+    async read(filter) {
+        const options = this.options();
+        const qb = typeorm_query_builder_1.TypeOrmQueryBuilder.apply(this.query(), filter, options);
+        const items = await qb.getRawMany();
+        const includeTotal = filter.includeTotal !== false;
+        let total;
+        if (includeTotal) {
+            const countQb = typeorm_query_builder_1.TypeOrmQueryBuilder.apply(this.query(), filter, {
+                ...options,
+                applyPagination: false,
+                applySorting: false,
+            });
+            if (options.distinctCountField) {
+                const expression = (0, typeorm_query_builder_1.trustedQueryExpression)(countQb.alias, options.distinctCountField);
+                const result = await countQb
+                    .select(`COUNT(DISTINCT ${expression})`, 'devkit_total')
+                    .getRawOne();
+                total = Number(result?.devkit_total ?? 0);
+            }
+            else {
+                total = await countQb.getCount();
+            }
+        }
+        const limit = (0, devkit_core_1.resolvePaginationLimit)(filter.limit, {
+            defaultLimit: options.pagination?.defaultLimit ?? 20,
+            maxLimit: options.pagination?.maxLimit ?? 100,
+        });
+        return {
+            items,
+            meta: {
+                currentPage: Math.max(1, Number(filter.page) || 1),
+                itemsPerPage: limit,
+                itemCount: items.length,
+                totalItems: total,
+                totalPage: total === undefined ? undefined : Math.ceil(total / limit),
+                hasNextPage: total === undefined
+                    ? items.length === limit
+                    : Math.max(1, Number(filter.page) || 1) * limit < total,
+            },
+        };
+    }
+}
+exports.TypeOrmReader = TypeOrmReader;

package/dist/database/typeorm-reader.test.d.ts

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

package/dist/database/typeorm-reader.test.js

@@ -0,0 +1,55 @@
+"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_reader_1 = require("./typeorm-reader");
+function queryBuilder(rows, total) {
+    const state = { joins: [], selection: '' };
+    return {
+        alias: 'order',
+        state,
+        leftJoin(table) { state.joins.push(table); return this; },
+        select(selection) { state.selection = selection; return this; },
+        take() { return this; },
+        skip() { return this; },
+        andWhere() { return this; },
+        addOrderBy() { return this; },
+        getRawMany: async () => rows,
+        getRawOne: async () => ({ devkit_total: String(total) }),
+        getCount: async () => total,
+    };
+}
+(0, node_test_1.default)('TypeOrmReader supports joins, typed raw projections and a separate COUNT DISTINCT', async () => {
+    const builders = [];
+    class OrderSummaryReader extends typeorm_reader_1.TypeOrmReader {
+        query() {
+            const qb = queryBuilder([{ customerId: 'customer-1', amount: 42 }], 7)
+                .leftJoin('order.items')
+                .select('order.customer_id AS customerId, SUM(item.amount) AS amount');
+            builders.push(qb);
+            return qb;
+        }
+        options() {
+            return { distinctCountField: 'customer_id', pagination: { maxLimit: 50 } };
+        }
+    }
+    const result = await new OrderSummaryReader().read({ page: 1, limit: 10, includeTotal: true });
+    strict_1.default.deepEqual(result.items, [{ customerId: 'customer-1', amount: 42 }]);
+    strict_1.default.equal(result.meta.totalItems, 7);
+    strict_1.default.equal(result.meta.totalPage, 1);
+    strict_1.default.deepEqual(builders[0].state.joins, ['order.items']);
+    strict_1.default.equal(builders[1].state.selection, 'COUNT(DISTINCT order.customer_id)');
+});
+(0, node_test_1.default)('TypeOrmReader skips the count query when the caller opts out of totals', async () => {
+    let queries = 0;
+    class FastReader extends typeorm_reader_1.TypeOrmReader {
+        query() { queries += 1; return queryBuilder([{ id: '1' }], 99); }
+        options() { return {}; }
+    }
+    const result = await new FastReader().read({ includeTotal: false });
+    strict_1.default.equal(queries, 1);
+    strict_1.default.equal(result.meta.totalItems, undefined);
+});

package/dist/database/typeorm-sql.d.ts

@@ -0,0 +1,3 @@
+import type { DataSource } from 'typeorm';
+/** Preserves TypeORM's parameterized SQL tag while allowing a typed row shape. */
+export declare function typeOrmSql<Row>(dataSource: Pick<DataSource, 'sql'>): (strings: TemplateStringsArray, ...values: unknown[]) => Promise<Row[]>;

package/dist/database/typeorm-sql.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.typeOrmSql = typeOrmSql;
+/** Preserves TypeORM's parameterized SQL tag while allowing a typed row shape. */
+function typeOrmSql(dataSource) {
+    return (strings, ...values) => dataSource.sql(strings, ...values);
+}

package/dist/database/typeorm-sql.test.d.ts

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

package/dist/database/typeorm-sql.test.js

@@ -0,0 +1,21 @@
+"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_sql_1 = require("./typeorm-sql");
+(0, node_test_1.default)('typeOrmSql forwards template values separately from SQL text', async () => {
+    let capturedValues = [];
+    const source = {
+        async sql(_strings, ...values) {
+            capturedValues = values;
+            return [{ id: 'invoice-1' }];
+        },
+    };
+    const invoiceId = "invoice-1' OR 1=1";
+    const rows = await (0, typeorm_sql_1.typeOrmSql)(source) `SELECT id FROM invoices WHERE id = ${invoiceId}`;
+    strict_1.default.deepEqual(capturedValues, [invoiceId]);
+    strict_1.default.deepEqual(rows, [{ id: 'invoice-1' }]);
+});