@bitblit/ratchet-rdbms 4.0.115-alpha

package/lib/non-pooled-mysql-style-connection-provider.d.ts

@@ -0,0 +1,8 @@
+import { Connection } from 'mysql2/promise';
+import { MysqlStyleConnectionProvider } from './model/mysql/mysql-style-connection-provider.js';
+export declare class NonPooledMysqlStyleConnectionProvider implements MysqlStyleConnectionProvider {
+    private connection;
+    constructor(connection: Connection);
+    getConnection(): Promise<Connection>;
+    clearConnectionCache(): Promise<boolean>;
+}

package/lib/non-pooled-mysql-style-connection-provider.js

@@ -0,0 +1,16 @@
+import { RequireRatchet } from '@bitblit/ratchet-common/lib/lang/require-ratchet.js';
+import { Logger } from '@bitblit/ratchet-common/lib/logger/logger.js';
+export class NonPooledMysqlStyleConnectionProvider {
+    connection;
+    constructor(connection) {
+        this.connection = connection;
+        RequireRatchet.notNullOrUndefined(connection);
+    }
+    async getConnection() {
+        return this.connection;
+    }
+    async clearConnectionCache() {
+        Logger.info('clearConnectionCache ignored - not pooled');
+        return true;
+    }
+}

package/lib/query-builder/query-builder-result.d.ts

@@ -0,0 +1,9 @@
+import { TransactionIsolationLevel } from '../model/transaction-isolation-level.js';
+import { Paginator } from '../model/paginator.js';
+export declare class QueryBuilderResult {
+    query: string;
+    namedParams: Record<string, unknown>;
+    paginator?: Paginator<any>;
+    transactionIsolationLevel: TransactionIsolationLevel;
+    constructor(query: string, namedParams: Record<string, unknown>, paginator: Paginator<any> | undefined, transactionIsolationLevel: TransactionIsolationLevel);
+}

package/lib/query-builder/query-builder-result.js

@@ -0,0 +1,12 @@
+export class QueryBuilderResult {
+    query;
+    namedParams;
+    paginator;
+    transactionIsolationLevel;
+    constructor(query, namedParams, paginator, transactionIsolationLevel) {
+        this.query = query;
+        this.namedParams = namedParams;
+        this.paginator = paginator;
+        this.transactionIsolationLevel = transactionIsolationLevel;
+    }
+}

package/lib/query-builder/query-builder.d.ts

@@ -0,0 +1,52 @@
+import { QueryBuilderResult } from './query-builder-result.js';
+import { TransactionIsolationLevel } from '../model/transaction-isolation-level.js';
+import { QueryTextProvider } from '../model/query-text-provider.js';
+import { Paginator } from '../model/paginator.js';
+export declare class QueryBuilder {
+    static readonly ALLOWED_SQL_CONSTRUCT: RegExp;
+    private readonly queryProvider;
+    private query?;
+    meta: {
+        queryPath?: string;
+    };
+    private sqlConstructs;
+    private namedParams;
+    private conditionals;
+    private debugComment;
+    private paginator?;
+    private debugAnnotateMode;
+    private transactionIsolationLevel;
+    constructor(queryProvider: QueryTextProvider);
+    clone(): QueryBuilder;
+    withTransactionIsolationLevel(level: TransactionIsolationLevel): QueryBuilder;
+    withDebugComment(comment: string): QueryBuilder;
+    appendDebugComment(comment: string): QueryBuilder;
+    withNamedQuery(queryPath: string): QueryBuilder;
+    withBaseQuery(baseQuery: string): void;
+    withSqlConstruct(key: string, value: unknown): QueryBuilder;
+    withSqlConstructs(params: Record<string, unknown>): QueryBuilder;
+    removeParam(key: string): QueryBuilder;
+    paramNames(): string[];
+    withParam(key: string, value: unknown): QueryBuilder;
+    withParams(params: unknown): QueryBuilder;
+    withExpandedParam(keyPrefix: string, values: unknown[], extendIfExists: boolean): QueryBuilder;
+    withConditional(tag: string, state?: boolean): QueryBuilder;
+    withConditionals(params: Record<string, boolean>): QueryBuilder;
+    withPaginator(paginator: Paginator<any>): QueryBuilder;
+    fetchCopyOfParam<T>(paramName: string): T | undefined;
+    fetchCopyOfConditional<T>(conditionalName: string): T | undefined;
+    containsParam(paramName: string): boolean;
+    getDebugComment(): string;
+    containsConditional(conditionalName: string): boolean;
+    build(): QueryBuilderResult;
+    buildUnfiltered(): QueryBuilderResult;
+    protected internalBuild(unfiltered: boolean): QueryBuilderResult;
+    private stripNonAsciiParams;
+    private runQueryChecks;
+    private applyComments;
+    applySqlConstructs(): void;
+    private applyRepeatBlocks;
+    private applyQueryFragments;
+    private applyPagination;
+    private applyConditionalBlocks;
+}

package/lib/query-builder/query-builder.js

@@ -0,0 +1,352 @@
+import { ErrorRatchet } from '@bitblit/ratchet-common/lib/lang/error-ratchet.js';
+import { Logger } from '@bitblit/ratchet-common/lib/logger/logger.js';
+import { RequireRatchet } from '@bitblit/ratchet-common/lib/lang/require-ratchet.js';
+import { StringRatchet } from '@bitblit/ratchet-common/lib/lang/string-ratchet.js';
+import _ from 'lodash';
+import { QueryBuilderResult } from './query-builder-result.js';
+import { TransactionIsolationLevel } from '../model/transaction-isolation-level.js';
+import { SortDirection } from '../model/sort-direction.js';
+export class QueryBuilder {
+    static ALLOWED_SQL_CONSTRUCT = /^[a-z0-9_.`]+$/i;
+    queryProvider;
+    query;
+    meta = Object.freeze({});
+    sqlConstructs = {};
+    namedParams = {};
+    conditionals = {};
+    debugComment = '';
+    paginator;
+    debugAnnotateMode = false;
+    transactionIsolationLevel = TransactionIsolationLevel.Default;
+    constructor(queryProvider) {
+        this.queryProvider = queryProvider;
+    }
+    clone() {
+        const clone = new QueryBuilder(this.queryProvider);
+        if (this.query) {
+            clone.withBaseQuery(this.query);
+        }
+        clone.sqlConstructs = _.clone(this.sqlConstructs);
+        clone.namedParams = _.clone(this.namedParams);
+        clone.conditionals = _.clone(this.conditionals);
+        clone.paginator = _.clone(this.paginator);
+        clone.debugComment = this.debugComment;
+        clone.transactionIsolationLevel = this.transactionIsolationLevel;
+        return clone;
+    }
+    withTransactionIsolationLevel(level) {
+        this.transactionIsolationLevel = level;
+        return this;
+    }
+    withDebugComment(comment) {
+        this.debugComment = comment;
+        return this;
+    }
+    appendDebugComment(comment) {
+        this.debugComment = this.debugComment + comment;
+        return this;
+    }
+    withNamedQuery(queryPath) {
+        this.query = this.queryProvider.fetchQuery(queryPath);
+        if (!StringRatchet.trimToNull(this.query)) {
+            ErrorRatchet.throwFormattedErr('Requested query that does not exist : %s', queryPath);
+        }
+        this.meta = Object.freeze({ queryPath: queryPath });
+        this.withDebugComment(' ' + queryPath + ' ');
+        return this;
+    }
+    withBaseQuery(baseQuery) {
+        this.query = baseQuery;
+    }
+    withSqlConstruct(key, value) {
+        this.sqlConstructs[key] = value;
+        return this;
+    }
+    withSqlConstructs(params) {
+        this.sqlConstructs = Object.assign(this.sqlConstructs, params);
+        return this;
+    }
+    removeParam(key) {
+        delete this.namedParams[key];
+        return this;
+    }
+    paramNames() {
+        return Object.keys(this.namedParams);
+    }
+    withParam(key, value) {
+        this.namedParams[key] = value;
+        return this;
+    }
+    withParams(params) {
+        this.namedParams = Object.assign(this.namedParams, params);
+        return this;
+    }
+    withExpandedParam(keyPrefix, values, extendIfExists) {
+        const lengthParamName = keyPrefix + 'Length';
+        let oldSize = this.fetchCopyOfParam(lengthParamName) ?? 0;
+        if (oldSize > 0 && !extendIfExists) {
+            Logger.silly('Old item found and not extending - removing old params');
+            const toRemove = this.paramNames().filter((s) => s.startsWith(keyPrefix));
+            toRemove.forEach((s) => this.removeParam(s));
+            oldSize = 0;
+        }
+        this.withParam(lengthParamName, values.length + oldSize);
+        for (let i = 0; i < values.length; i++) {
+            const value = values[i];
+            if (typeof value === 'object' && !!value) {
+                for (const key of Object.keys(value)) {
+                    const paramKey = keyPrefix + key.charAt(0).toUpperCase() + key.slice(1) + (i + oldSize);
+                    this.withParam(paramKey, value[key]);
+                }
+            }
+            else {
+                const paramKey = keyPrefix + i;
+                this.withParam(paramKey, value);
+            }
+        }
+        return this;
+    }
+    withConditional(tag, state = true) {
+        this.conditionals[tag] = state;
+        return this;
+    }
+    withConditionals(params) {
+        this.conditionals = Object.assign(this.conditionals, params);
+        return this;
+    }
+    withPaginator(paginator) {
+        RequireRatchet.notNullOrUndefined(paginator, 'paginator');
+        RequireRatchet.notNullOrUndefined(paginator.cn, 'paginator.cn');
+        RequireRatchet.true(paginator.min || paginator.max || paginator.l, 'paginator must have some limit');
+        paginator.s = paginator.s ?? SortDirection.Asc;
+        this.paginator = paginator;
+        return this;
+    }
+    fetchCopyOfParam(paramName) {
+        return this.namedParams[paramName];
+    }
+    fetchCopyOfConditional(conditionalName) {
+        return this.conditionals[conditionalName];
+    }
+    containsParam(paramName) {
+        return this.namedParams[paramName] != undefined;
+    }
+    getDebugComment() {
+        return this.debugComment;
+    }
+    containsConditional(conditionalName) {
+        return this.conditionals[conditionalName] != undefined;
+    }
+    build() {
+        const build = this.clone();
+        return build.internalBuild(false);
+    }
+    buildUnfiltered() {
+        const builder = this.clone();
+        return builder.internalBuild(true);
+    }
+    internalBuild(unfiltered) {
+        this.applyQueryFragments();
+        this.applyConditionalBlocks();
+        this.applyRepeatBlocks();
+        this.applyPagination(unfiltered);
+        this.applySqlConstructs();
+        this.applyComments();
+        this.runQueryChecks();
+        this.stripNonAsciiParams();
+        return new QueryBuilderResult((this.query ?? '').trim(), this.namedParams, this.paginator, this.transactionIsolationLevel);
+    }
+    stripNonAsciiParams() {
+        const reduced = StringRatchet.stripNonAscii(JSON.stringify(this.namedParams));
+        this.namedParams = JSON.parse(reduced);
+    }
+    runQueryChecks() {
+        const quotedNamedParams = [...(this.query?.matchAll(/['"]:[A-z-]*['"]/gm) ?? [])];
+        if (quotedNamedParams.length > 0) {
+            Logger.warn('The resulting query contains quoted named params check this this is intended. Instances found: %s', quotedNamedParams.join(', '));
+        }
+    }
+    applyComments() {
+        if (this.debugComment.length && this.query) {
+            const firstSpaceIndex = this.query.indexOf(' ');
+            const comment = this.debugComment;
+            this.query = this.query.substring(0, firstSpaceIndex + 1) + `/*${comment}*/` + this.query.substring(firstSpaceIndex + 1);
+        }
+    }
+    applySqlConstructs() {
+        for (const key of Object.keys(this.sqlConstructs)) {
+            let value;
+            const val = this.sqlConstructs[key];
+            if (Array.isArray(val)) {
+                val.forEach((v) => {
+                    if (typeof v !== 'string' || !v.match(QueryBuilder.ALLOWED_SQL_CONSTRUCT)) {
+                        throw new Error(`sql construct entry ${v} is invalid value must be alphanumeric only.`);
+                    }
+                });
+                value = val.join(', ');
+            }
+            else {
+                value = StringRatchet.safeString(val);
+                if (value.length > 0 && !value.match(QueryBuilder.ALLOWED_SQL_CONSTRUCT)) {
+                    throw new Error(`sql construct ${value} is invalid value must be alphanumeric only.`);
+                }
+            }
+            const sqlReservedWords = ['update', 'insert', 'delete', 'drop', 'select'];
+            for (const word of sqlReservedWords) {
+                if (value.toLowerCase().includes(word)) {
+                    throw new Error(`sql construct ${value} is invalid value must not contain reserved word ${word}.`);
+                }
+            }
+            const rawKey = `##sqlConstruct:${key}##`;
+            while (this.query?.includes(rawKey)) {
+                this.query = this.query.replace(rawKey, value);
+            }
+        }
+    }
+    applyRepeatBlocks() {
+        const startSymbol = '<repeat';
+        const endSymbol = '>';
+        while (true) {
+            const startIndex = this.query?.indexOf(startSymbol);
+            if (startIndex === -1 || !this.query || typeof startIndex !== 'number') {
+                return;
+            }
+            const endIndex = this.query.indexOf(endSymbol, startIndex);
+            if (endIndex == -1) {
+                throw new Error(`Invalid query when finding end symbol matching ${endSymbol} in ${this.query} check that you have closed all your tags correctly.`);
+            }
+            const content = this.query.substring(startIndex + startSymbol.length, endIndex).trim();
+            const countSymbol = 'count=';
+            let countParam = '';
+            const joinSymbol = 'join=';
+            let joinString;
+            const params = content.split(' ');
+            for (const param of params) {
+                if (param.includes(countSymbol)) {
+                    countParam = param.substring(param.indexOf(countSymbol) + countSymbol.length);
+                }
+                if (param.includes(joinSymbol)) {
+                    joinString = param.substring(param.indexOf(joinSymbol) + joinSymbol.length);
+                }
+            }
+            const endTag = `</repeat>`;
+            const endTagIndex = this.query.indexOf(endTag);
+            const repeatedContent = this.query.substring(endIndex + endSymbol.length, endTagIndex);
+            this.query = this.query.substring(0, startIndex) + this.query.substring(endTagIndex + endTag.length);
+            const count = this.namedParams[countParam.substring(1)];
+            for (let i = 0; i < count; i++) {
+                let indexedContent = repeatedContent;
+                if (joinString && i != 0) {
+                    indexedContent += joinString;
+                }
+                let startParamTagIndex = indexedContent.indexOf(`::`);
+                while (startParamTagIndex != -1) {
+                    const endParamTagIndex = indexedContent.indexOf(`::`, startParamTagIndex + 2);
+                    if (endParamTagIndex == -1) {
+                        throw new Error(`Invalid query when finding end symbol matching :: check that you have closed all your tags correctly. Query: ${this.query} `);
+                    }
+                    const param = indexedContent.substring(startParamTagIndex + 2, endParamTagIndex);
+                    indexedContent = indexedContent.replace('::' + param + '::', ':' + param + i);
+                    startParamTagIndex = indexedContent.indexOf(`::`);
+                }
+                this.query = this.query.substring(0, startIndex) + indexedContent + this.query.substring(startIndex);
+            }
+        }
+    }
+    applyQueryFragments() {
+        const startSymbol = '[[';
+        const endSymbol = ']]';
+        while (true) {
+            const startIndex = this.query?.indexOf(startSymbol);
+            if (startIndex == -1 || !this.query || typeof startIndex !== 'number') {
+                return;
+            }
+            const endIndex = this.query.indexOf(endSymbol, startIndex);
+            if (endIndex == -1) {
+                throw new Error(`Invalid query when finding end symbol matching ${endSymbol} in ${this.query} check that you have closed all your tags correctly.`);
+            }
+            const rawName = this.query.substring(startIndex + startSymbol.length, endIndex);
+            const namedQueryElement = this.queryProvider.fetchQuery(rawName);
+            if (!namedQueryElement) {
+                throw new Error(`Invalid query, query fragment ${rawName} not found in named queries.`);
+            }
+            this.query = this.query.replace(`[[${rawName}]]`, namedQueryElement);
+        }
+    }
+    applyPagination(unfiltered) {
+        const paginationRawKey = '##pagination##';
+        if (!unfiltered && this.paginator) {
+            const sortDirEnum = this.paginator.s == SortDirection.Desc ? SortDirection.Desc : SortDirection.Asc;
+            const sortDir = StringRatchet.safeString(sortDirEnum);
+            if (this.paginator.min || this.paginator.max) {
+                let wc = 'WHERE ##sqlConstruct:queryBuilderPaginatorWhere##';
+                this.withSqlConstruct('queryBuilderPaginatorWhere', this.paginator.cn);
+                if (this.paginator.min) {
+                    wc += '>= :queryBuilderPaginatorWhereMin';
+                    this.withParam('queryBuilderPaginatorWhereMin', this.paginator.min);
+                }
+                if (this.paginator.max) {
+                    if (this.paginator.min) {
+                        wc += ' AND ##sqlConstruct:queryBuilderPaginatorWhere##';
+                    }
+                    wc += '< :queryBuilderPaginatorWhereMax';
+                    this.withParam('queryBuilderPaginatorWhereMax', this.paginator.max);
+                }
+                this.query += wc;
+            }
+            this.query += ` ORDER BY ##sqlConstruct:queryBuilderOrderBy## ${sortDir}`;
+            this.withSqlConstruct('queryBuilderOrderBy', this.paginator.cn);
+            if (this.paginator.l) {
+                this.query += ' LIMIT :queryBuilderLimit';
+                this.withParam('queryBuilderLimit', this.paginator.l);
+            }
+        }
+        if (unfiltered && this.query) {
+            const paginationSplitIndex = this.query.indexOf(paginationRawKey);
+            if (paginationSplitIndex != -1) {
+                this.query = 'SELECT COUNT(*) ' + this.query.substring(paginationSplitIndex + paginationRawKey.length);
+            }
+        }
+        while (this.query?.includes(paginationRawKey)) {
+            this.query = this.query.replace(paginationRawKey, '');
+        }
+    }
+    applyConditionalBlocks() {
+        const startSymbol = '<<';
+        const endSymbol = '>>';
+        while (true) {
+            const startIndex = this.query?.indexOf(startSymbol);
+            if (startIndex == -1 || !this.query || typeof startIndex !== 'number') {
+                return;
+            }
+            const endIndex = this.query.indexOf(endSymbol, startIndex);
+            if (endIndex == -1) {
+                throw new Error(`Invalid query when finding end symbol matching ${endSymbol} in ${this.query} check that you have closed all your tags correctly.`);
+            }
+            const rawTag = this.query.substring(startIndex + startSymbol.length, endIndex);
+            const tag = rawTag.replace(':', '');
+            const endTag = `<</${rawTag}>>`;
+            const endTagIndex = this.query.indexOf(endTag);
+            if (endTagIndex == -1) {
+                throw new Error(`Invalid query when finding conditional end tag matching ${endTag} in ${this.query} check that your query contains an exact match of this tag.`);
+            }
+            let replacement = this.query.substring(endIndex + endSymbol.length, endTagIndex);
+            if (rawTag.startsWith(':')) {
+                const param = this.namedParams[tag];
+                if (param == null || (Array.isArray(param) && param.length == 0)) {
+                    replacement = '';
+                }
+            }
+            else {
+                const conditional = this.conditionals[tag.replace('!', '')];
+                if (conditional == undefined || conditional == tag.startsWith('!')) {
+                    replacement = '';
+                }
+            }
+            if (this.debugAnnotateMode) {
+                replacement = '/* conditional ' + tag + '*/';
+            }
+            this.query = this.query.substring(0, startIndex) + replacement + this.query.substring(endTagIndex + endTag.length);
+        }
+    }
+}

package/lib/query-builder/query-builder.spec.d.ts

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

package/lib/query-builder/query-builder.spec.js

@@ -0,0 +1,126 @@
+import { NamedParameterMariaDbService } from '../named-parameter-maria-db-service.js';
+import { JestRatchet } from '@bitblit/ratchet-jest/lib/jest/jest-ratchet.js';
+import { SortDirection } from '../model/sort-direction.js';
+import { jest } from '@jest/globals';
+const prov = {
+    fetchQuery(queryPath) {
+        return this.fetchAllQueries()[queryPath];
+    },
+    fetchAllQueries() {
+        return {
+            'named_parameter_tests.named_fragment_1': 'SELECT b.`id`, b.`owner_id`, b.`name` FROM boards b',
+            'named_parameter_tests.named_test_1': '[[named_parameter_tests.named_fragment_1]] WHERE id=:boardId OR owner_id=:ownerId',
+            'named_parameter_tests.conditional_section_test': 'SELECT b.`id` FROM boards b WHERE b.id < 1000<<COND1>> AND b.owner_id = :ownerId <</COND1>>',
+            'named_parameter_tests.pagination_count_test': 'SELECT b.`id` ##pagination## FROM boards b WHERE b.id < 1000 UNION (SELECT x.`id` ##pagination## FROM somewherelse WHERE x.`id` = 3)',
+            'named_parameter_tests.negated_conditional_section_test': 'SELECT b.`id` FROM boards b WHERE b.id < 1000 <<!COND1>> AND b.owner_id = :ownerId <</!COND1>>',
+            'named_parameter_tests.conditional_param_section_test': 'SELECT b.`id` FROM boards b WHERE b.id < 1000 <<:ownerId>> AND b.owner_id = :ownerId <</:ownerId>>',
+            'named_parameter_tests.new_repeat_section_test': '<repeat count=:clsLength join=AND> repeated ::clsW:: ::clsH:: clause </repeat>',
+            'named_parameter_tests.sql_construct_test': 'GROUP BY x.##sqlConstruct:groupingColumn##',
+            'named_parameter_tests.constant_test': 'SELECT b.`id`, :constantName as constant FROM boards b where b.`id` = 52',
+        };
+    },
+};
+const mariaDb = new NamedParameterMariaDbService(prov, JestRatchet.mock(jest.fn), { databaseName: 'test', timeoutMS: 2_000 });
+describe('query-builder', () => {
+    it('builds filtered', () => {
+        const queryBuilder = mariaDb.queryBuilder('named_parameter_tests.pagination_count_test');
+        const build = queryBuilder.build();
+        expect(build.query).toBe('SELECT /* named_parameter_tests.pagination_count_test */b.`id`  FROM boards b WHERE b.id < 1000 UNION (SELECT x.`id`  FROM somewherelse WHERE x.`id` = 3)');
+    });
+    it('builds unfiltered', () => {
+        const queryBuilder = mariaDb.queryBuilder('named_parameter_tests.pagination_count_test');
+        const build = queryBuilder.buildUnfiltered();
+        expect(build.query).toBe('SELECT /* named_parameter_tests.pagination_count_test */COUNT(*)  FROM boards b WHERE b.id < 1000 UNION (SELECT x.`id`  FROM somewherelse WHERE x.`id` = 3)');
+    });
+    it('fails if param is missing', () => {
+        const queryBuilder = mariaDb.queryBuilder('named_parameter_tests.pagination_count_test');
+        const build = queryBuilder.build();
+        expect(build.query).toBe('SELECT /* named_parameter_tests.pagination_count_test */b.`id`  FROM boards b WHERE b.id < 1000 UNION (SELECT x.`id`  FROM somewherelse WHERE x.`id` = 3)');
+    });
+    it('removes conditional blocks when missing', () => {
+        const queryBuilder = mariaDb.queryBuilder('named_parameter_tests.conditional_section_test');
+        const build = queryBuilder.build();
+        expect(build.query).toBe('SELECT /* named_parameter_tests.conditional_section_test */b.`id` FROM boards b WHERE b.id < 1000');
+    });
+    it('handles negated conditional blocks true state', () => {
+        const queryBuilder = mariaDb.queryBuilder('named_parameter_tests.negated_conditional_section_test');
+        queryBuilder.withConditional('COND1');
+        const build = queryBuilder.build();
+        expect(build.query).toBe('SELECT /* named_parameter_tests.negated_conditional_section_test */b.`id` FROM boards b WHERE b.id < 1000');
+    });
+    it('handles negated conditional blocks false state', () => {
+        const queryBuilder = mariaDb.queryBuilder('named_parameter_tests.negated_conditional_section_test');
+        queryBuilder.withConditional('COND1', false);
+        const build = queryBuilder.build();
+        expect(build.query).toBe('SELECT /* named_parameter_tests.negated_conditional_section_test */b.`id` FROM boards b WHERE b.id < 1000  AND b.owner_id = :ownerId');
+    });
+    it('leaves conditional blocks when present', () => {
+        const queryBuilder = mariaDb.queryBuilder('named_parameter_tests.conditional_section_test');
+        queryBuilder.withConditional('COND1');
+        const build = queryBuilder.build();
+        expect(build.query).toBe('SELECT /* named_parameter_tests.conditional_section_test */b.`id` FROM boards b WHERE b.id < 1000 AND b.owner_id = :ownerId');
+    });
+    it('leaves param-conditional blocks when param exists', () => {
+        const queryBuilder = mariaDb.queryBuilder('named_parameter_tests.conditional_param_section_test');
+        queryBuilder.withParam('ownerId', 'testvalue');
+        const build = queryBuilder.build();
+        expect(build.query).toBe('SELECT /* named_parameter_tests.conditional_param_section_test */b.`id` FROM boards b WHERE b.id < 1000  AND b.owner_id = :ownerId');
+    });
+    it('removes param-conditional blocks when param missing', () => {
+        const queryBuilder = mariaDb.queryBuilder('named_parameter_tests.conditional_param_section_test');
+        const build = queryBuilder.build();
+        expect(build.query).toBe('SELECT /* named_parameter_tests.conditional_param_section_test */b.`id` FROM boards b WHERE b.id < 1000');
+    });
+    it('removes param-conditional blocks when param is an empty array', () => {
+        const queryBuilder = mariaDb.queryBuilder('named_parameter_tests.conditional_param_section_test');
+        queryBuilder.withParam('ownerId', []);
+        const build = queryBuilder.build();
+        expect(build.query).toBe('SELECT /* named_parameter_tests.conditional_param_section_test */b.`id` FROM boards b WHERE b.id < 1000');
+    });
+    it('applies query fragments', () => {
+        const queryBuilder = mariaDb.queryBuilder('named_parameter_tests.named_test_1');
+        const build = queryBuilder.build();
+        expect(build.query).toBe('SELECT /* named_parameter_tests.named_test_1 */b.`id`, b.`owner_id`, b.`name` FROM boards b WHERE id=:boardId OR owner_id=:ownerId');
+    });
+    it('applies sql constructs', () => {
+        const queryBuilder = mariaDb.queryBuilder('named_parameter_tests.sql_construct_test');
+        queryBuilder.withSqlConstruct('groupingColumn', 'test_column');
+        const build = queryBuilder.build();
+        expect(build.query).toBe('GROUP /* named_parameter_tests.sql_construct_test */BY x.test_column');
+    });
+    it('expands object arrays', () => {
+        const queryBuilder = mariaDb.queryBuilder('named_parameter_tests.new_repeat_section_test');
+        queryBuilder.withExpandedParam('cls', [
+            { w: 1, h: 1 },
+            { w: 2, h: 2 },
+        ], true);
+        expect(queryBuilder.fetchCopyOfParam('clsW0')).toBe(1);
+        expect(queryBuilder.fetchCopyOfParam('clsW1')).toBe(2);
+        expect(queryBuilder.fetchCopyOfParam('clsH0')).toBe(1);
+        expect(queryBuilder.fetchCopyOfParam('clsH1')).toBe(2);
+    });
+    it('expands string arrays', () => {
+        const queryBuilder = mariaDb.queryBuilder('named_parameter_tests.new_repeat_section_test');
+        queryBuilder.withExpandedParam('cls', ['s0', 's1'], true);
+        expect(queryBuilder.fetchCopyOfParam('cls0')).toBe('s0');
+        expect(queryBuilder.fetchCopyOfParam('cls1')).toBe('s1');
+    });
+    it('applies repeat blocks', () => {
+        const queryBuilder = mariaDb.queryBuilder('named_parameter_tests.new_repeat_section_test');
+        queryBuilder.withExpandedParam('cls', [
+            { w: 1, h: 1 },
+            { w: 2, h: 2 },
+        ], true);
+        const build = queryBuilder.build();
+        expect(build.query).toBe('/* named_parameter_tests.new_repeat_section_test */repeated :clsW1 :clsH1 clause AND repeated :clsW0 :clsH0 clause');
+    });
+    xit('applies pagination', () => {
+        const queryBuilder = mariaDb.queryBuilder('named_parameter_tests.conditional_param_section_test');
+        queryBuilder.withPaginator({ s: SortDirection.Desc, cn: 'b.id', max: 1000, l: 25 });
+        const build = queryBuilder.build();
+        expect(build.query).toBe('SELECT /* named_parameter_tests.conditional_param_section_test */b.`id` FROM boards b WHERE b.id < 1000 ORDER BY id Desc LIMIT :queryBuilderLimit');
+        expect(build.namedParams).toStrictEqual({
+            queryBuilderLimit: 20,
+        });
+    });
+});

package/lib/query-builder/query-util.d.ts

@@ -0,0 +1,12 @@
+export declare class QueryUtil {
+    private fields;
+    private replacements;
+    addReplacement(replacement: Record<string, unknown>, ...fields: string[]): void;
+    appendReplacement(replacementKey: string, appendValue: string, ...fields: string[]): void;
+    addFields(...fields: string[]): void;
+    getFields(): string[];
+    getReplacements(): Record<string, unknown>;
+    static sqlInjectionUnsafeParamRenderer(value: unknown): string;
+    static renderQueryStringForPasteIntoTool(query: string, inFields: object | null, transform?: (x: unknown) => string): string | null;
+    static reformatQueryForLogging(qry: string, inMaxLineLength?: number): string | null;
+}

package/lib/query-builder/query-util.js

@@ -0,0 +1,69 @@
+import { StringRatchet } from '@bitblit/ratchet-common/lib/lang/string-ratchet.js';
+import { Logger } from '@bitblit/ratchet-common/lib/logger/logger.js';
+export class QueryUtil {
+    fields = [];
+    replacements = {};
+    addReplacement(replacement, ...fields) {
+        this.replacements = Object.assign(this.replacements, replacement);
+        this.addFields(...fields);
+    }
+    appendReplacement(replacementKey, appendValue, ...fields) {
+        this.replacements[replacementKey] = this.replacements[replacementKey] + appendValue;
+        this.addFields(...fields);
+    }
+    addFields(...fields) {
+        this.fields = this.fields.concat(...fields);
+    }
+    getFields() {
+        return this.fields;
+    }
+    getReplacements() {
+        return this.replacements;
+    }
+    static sqlInjectionUnsafeParamRenderer(value) {
+        const rFn = (val) => (typeof val === 'string' ? '"' + val + '"' : StringRatchet.safeString(val));
+        const repl = Array.isArray(value) ? value.map((s) => rFn(s)).join(',') : rFn(value);
+        return repl;
+    }
+    static renderQueryStringForPasteIntoTool(query, inFields, transform = QueryUtil.sqlInjectionUnsafeParamRenderer) {
+        const fields = inFields ?? {};
+        let rval = QueryUtil.reformatQueryForLogging(query);
+        if (rval) {
+            const keys = Object.keys(fields);
+            keys.sort((b, a) => a.length - b.length);
+            for (const key of keys) {
+                const val = fields[key];
+                const find = ':' + key;
+                const repl = transform(val);
+                rval = rval.split(find).join(repl);
+            }
+            if (!rval.endsWith(';')) {
+                rval += ';';
+            }
+        }
+        return rval;
+    }
+    static reformatQueryForLogging(qry, inMaxLineLength = 80) {
+        let maxLineLength = inMaxLineLength;
+        if (!StringRatchet.trimToNull(qry)) {
+            return null;
+        }
+        let loggableQuery = '';
+        let cleaned = StringRatchet.trimToEmpty(qry).split('\n').join(' ').split('\r').join(' ');
+        while (cleaned.length > maxLineLength) {
+            let idx = Math.min(cleaned.length, maxLineLength);
+            while (idx > 0 && ![' ', ','].includes(cleaned.charAt(idx))) {
+                idx--;
+            }
+            if (idx > 0) {
+                loggableQuery += cleaned.substring(0, idx) + '\n';
+                cleaned = StringRatchet.trimToEmpty(cleaned.substring(idx));
+            }
+            else {
+                Logger.silly('Input contains a string longer than the max line length - bumping');
+                maxLineLength += 2;
+            }
+        }
+        return loggableQuery + (cleaned.length > 0 ? cleaned : '');
+    }
+}