@wabot-dev/framework 0.8.3 → 0.9.1

package/dist/src/feature/pg/query/buildQuerySql.js

@@ -0,0 +1,164 @@
+// Fields stored as top-level columns; routed to the column instead of
+// extracting from the JSON blob (uses the index, preserves native type
+// for ordering/comparison). All other fields fall back to data->>'field',
+// which yields TEXT — so ORDER BY on numeric JSON fields is lexicographic
+// and In/NotIn compares as text. Use add.columns for sortable hot paths.
+const RESERVED_COLUMN_BY_FIELD = {
+    id: 'id',
+    createdAt: 'created_at',
+};
+function operatorArity(op) {
+    if (op === 'IsNull' || op === 'IsNotNull')
+        return 0;
+    return 1;
+}
+function escapeJsonKey(field) {
+    return field.replace(/'/g, "''");
+}
+function isReservedColumn(field) {
+    return Object.prototype.hasOwnProperty.call(RESERVED_COLUMN_BY_FIELD, field);
+}
+function fieldRef(field) {
+    const reserved = RESERVED_COLUMN_BY_FIELD[field];
+    if (reserved)
+        return reserved;
+    return `data->>'${escapeJsonKey(field)}'`;
+}
+function fieldExpr(field, op) {
+    const ref = fieldRef(field);
+    if (op === 'Gt' || op === 'Gte' || op === 'Lt' || op === 'Lte') {
+        if (isReservedColumn(field))
+            return ref;
+        return `(${ref})::numeric`;
+    }
+    return ref;
+}
+function renderCondition(cond, paramIndex) {
+    const lhs = fieldExpr(cond.field, cond.operator);
+    const reserved = isReservedColumn(cond.field);
+    const numCast = reserved ? '' : '::numeric';
+    // Note: In/NotIn cast the param to text[]; passing non-text JSON values
+    // (numbers, booleans) relies on pg's TEXT serialization. For sortable
+    // numeric fields, prefer a typed add.columns column.
+    const arrCast = reserved ? '' : '::text[]';
+    switch (cond.operator) {
+        case 'Equals':
+            return `${lhs} = $${paramIndex}`;
+        case 'Not':
+            return `${lhs} <> $${paramIndex}`;
+        case 'Like':
+            return `${lhs} LIKE $${paramIndex}`;
+        case 'NotLike':
+            return `${lhs} NOT LIKE $${paramIndex}`;
+        case 'In':
+            return `${lhs} = ANY($${paramIndex}${arrCast})`;
+        case 'NotIn':
+            return `NOT (${lhs} = ANY($${paramIndex}${arrCast}))`;
+        case 'Gt':
+            return `${lhs} > $${paramIndex}${numCast}`;
+        case 'Gte':
+            return `${lhs} >= $${paramIndex}${numCast}`;
+        case 'Lt':
+            return `${lhs} < $${paramIndex}${numCast}`;
+        case 'Lte':
+            return `${lhs} <= $${paramIndex}${numCast}`;
+        // IS NULL matches both missing JSON keys and explicit JSON nulls
+        // (PostgreSQL `data->>'k'` returns NULL for both cases).
+        case 'IsNull':
+            return `${lhs} IS NULL`;
+        case 'IsNotNull':
+            return `${lhs} IS NOT NULL`;
+    }
+}
+function renderWhere(conditions) {
+    if (conditions.length === 0)
+        return { sql: '', argCount: 0 };
+    const parts = [];
+    let paramIndex = 1;
+    conditions.forEach((cond, i) => {
+        const piece = renderCondition(cond, paramIndex);
+        paramIndex += operatorArity(cond.operator);
+        if (i === 0) {
+            parts.push(piece);
+        }
+        else {
+            parts.push((cond.connector ?? 'And').toUpperCase(), piece);
+        }
+    });
+    return { sql: ` WHERE ${parts.join(' ')}`, argCount: paramIndex - 1 };
+}
+function renderOrderBy(ast) {
+    if (ast.orderBy.length === 0)
+        return '';
+    const parts = ast.orderBy.map((o) => `${fieldRef(o.field)} ${o.direction}`);
+    return ` ORDER BY ${parts.join(', ')}`;
+}
+function renderLimit(ast) {
+    if (ast.prefix === 'findOne')
+        return ' LIMIT 1';
+    if (ast.limit !== undefined)
+        return ` LIMIT ${ast.limit}`;
+    return '';
+}
+function buildSelectSql(ast, table, columns) {
+    const where = renderWhere(ast.conditions);
+    const order = renderOrderBy(ast);
+    const limit = renderLimit(ast);
+    const sql = `SELECT ${columns} FROM ${table}${where.sql}${order}${limit}`;
+    return { sql, argCount: where.argCount };
+}
+function buildCountSql(ast, table) {
+    const where = renderWhere(ast.conditions);
+    const sql = `SELECT COUNT(*)::int AS count FROM ${table}${where.sql}`;
+    return { sql, argCount: where.argCount };
+}
+function buildExistsSql(ast, table) {
+    const where = renderWhere(ast.conditions);
+    const sql = `SELECT EXISTS(SELECT 1 FROM ${table}${where.sql} LIMIT 1) AS "exists"`;
+    return { sql, argCount: where.argCount };
+}
+function buildDeleteSql(ast, table) {
+    const where = renderWhere(ast.conditions);
+    const sql = `DELETE FROM ${table}${where.sql}`;
+    return { sql, argCount: where.argCount };
+}
+function buildQuerySql(ast, table, columns) {
+    let sql;
+    let argCount;
+    switch (ast.prefix) {
+        case 'find':
+        case 'findOne': {
+            const r = buildSelectSql(ast, table, columns);
+            sql = r.sql;
+            argCount = r.argCount;
+            break;
+        }
+        case 'count': {
+            const r = buildCountSql(ast, table);
+            sql = r.sql;
+            argCount = r.argCount;
+            break;
+        }
+        case 'exists': {
+            const r = buildExistsSql(ast, table);
+            sql = r.sql;
+            argCount = r.argCount;
+            break;
+        }
+        case 'delete': {
+            const r = buildDeleteSql(ast, table);
+            sql = r.sql;
+            argCount = r.argCount;
+            break;
+        }
+    }
+    const buildParams = (args) => {
+        if (args.length !== argCount) {
+            throw new Error(`Query expected ${argCount} argument(s), received ${args.length}`);
+        }
+        return args;
+    };
+    return { sql, argCount, buildParams };
+}
+
+export { buildQuerySql };

package/dist/src/feature/pg/query/parseQueryMethodName.js

@@ -0,0 +1,151 @@
+const PREFIXES = ['findOne', 'find', 'count', 'exists', 'delete'];
+const OPERATOR_MATCHERS = [
+    { tokens: ['Greater', 'Than', 'Equal'], op: 'Gte' },
+    { tokens: ['Less', 'Than', 'Equal'], op: 'Lte' },
+    { tokens: ['Greater', 'Than'], op: 'Gt' },
+    { tokens: ['Less', 'Than'], op: 'Lt' },
+    { tokens: ['Is', 'Not', 'Null'], op: 'IsNotNull' },
+    { tokens: ['Is', 'Null'], op: 'IsNull' },
+    { tokens: ['Not', 'Like'], op: 'NotLike' },
+    { tokens: ['Not', 'In'], op: 'NotIn' },
+    { tokens: ['Like'], op: 'Like' },
+    { tokens: ['In'], op: 'In' },
+    { tokens: ['Not'], op: 'Not' },
+    { tokens: ['Gte'], op: 'Gte' },
+    { tokens: ['Lte'], op: 'Lte' },
+    { tokens: ['Gt'], op: 'Gt' },
+    { tokens: ['Lt'], op: 'Lt' },
+];
+const CONNECTOR_TOKENS = new Set(['And', 'Or']);
+const FIELD_NAME_REGEX = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+function splitCamelCase(s) {
+    return s.match(/[A-Z][a-z0-9]*/g) ?? [];
+}
+function tokensToFieldName(tokens) {
+    if (tokens.length === 0) {
+        throw new Error('Query method: missing field name');
+    }
+    const joined = tokens.join('');
+    const field = joined.charAt(0).toLowerCase() + joined.slice(1);
+    if (!FIELD_NAME_REGEX.test(field)) {
+        throw new Error(`Query method: invalid field name "${field}"`);
+    }
+    return field;
+}
+function matchPrefix(name) {
+    for (const prefix of PREFIXES) {
+        if (name.startsWith(prefix)) {
+            const next = name.charAt(prefix.length);
+            if (next === '' || (next >= 'A' && next <= 'Z')) {
+                return { prefix, rest: name.slice(prefix.length) };
+            }
+        }
+    }
+    throw new Error(`Query method "${name}" must start with one of: ${PREFIXES.join(', ')}`);
+}
+function parseConditionTokens(tokens) {
+    for (const matcher of OPERATOR_MATCHERS) {
+        if (tokens.length < matcher.tokens.length)
+            continue;
+        const tail = tokens.slice(tokens.length - matcher.tokens.length);
+        if (tail.every((t, i) => t === matcher.tokens[i])) {
+            const head = tokens.slice(0, tokens.length - matcher.tokens.length);
+            return { field: tokensToFieldName(head), operator: matcher.op };
+        }
+    }
+    return { field: tokensToFieldName(tokens), operator: 'Equals' };
+}
+function parseConditions(body) {
+    if (body === '')
+        return [];
+    const tokens = splitCamelCase(body);
+    if (tokens.length === 0)
+        return [];
+    if (CONNECTOR_TOKENS.has(tokens[0])) {
+        throw new Error(`Query method: condition cannot start with connector "${tokens[0]}"`);
+    }
+    const conditions = [];
+    let buffer = [];
+    let pendingConnector;
+    const flush = () => {
+        if (buffer.length === 0) {
+            throw new Error('Query method: empty condition between connectors');
+        }
+        const { field, operator } = parseConditionTokens(buffer);
+        conditions.push({ field, operator, connector: pendingConnector });
+        buffer = [];
+    };
+    for (const token of tokens) {
+        if (CONNECTOR_TOKENS.has(token) && buffer.length > 0) {
+            flush();
+            pendingConnector = token;
+        }
+        else {
+            buffer.push(token);
+        }
+    }
+    flush();
+    return conditions;
+}
+function parseOrderBy(body) {
+    const tokens = splitCamelCase(body);
+    const result = [];
+    let buffer = [];
+    for (const token of tokens) {
+        if (token === 'Asc' || token === 'Desc') {
+            if (buffer.length === 0) {
+                throw new Error('Query method: OrderBy direction without field');
+            }
+            result.push({
+                field: tokensToFieldName(buffer),
+                direction: token === 'Asc' ? 'ASC' : 'DESC',
+            });
+            buffer = [];
+        }
+        else {
+            buffer.push(token);
+        }
+    }
+    if (buffer.length > 0) {
+        throw new Error(`Query method: OrderBy field "${tokensToFieldName(buffer)}" missing Asc/Desc direction`);
+    }
+    if (result.length === 0) {
+        throw new Error('Query method: OrderBy clause has no fields');
+    }
+    return result;
+}
+// Conditions are joined left-to-right; the DSL has no parentheses,
+// so SQL precedence applies (AND binds tighter than OR). Group with
+// explicit method names if the implicit precedence is not what you want.
+function parseQueryMethodName(name) {
+    const { prefix, rest: afterPrefix } = matchPrefix(name);
+    let rest = afterPrefix;
+    let limit;
+    const limitMatch = rest.match(/Limit(\d+)$/);
+    if (limitMatch) {
+        if (prefix === 'findOne') {
+            throw new Error(`Query method "${name}": findOne implies LIMIT 1; remove the Limit suffix`);
+        }
+        limit = parseInt(limitMatch[1], 10);
+        rest = rest.slice(0, rest.length - limitMatch[0].length);
+    }
+    let orderBy = [];
+    const orderByIdx = rest.indexOf('OrderBy');
+    if (orderByIdx >= 0) {
+        orderBy = parseOrderBy(rest.slice(orderByIdx + 'OrderBy'.length));
+        rest = rest.slice(0, orderByIdx);
+    }
+    let conditions = [];
+    if (rest === '' || rest === 'All') {
+        conditions = [];
+    }
+    else if (rest.startsWith('By')) {
+        conditions = parseConditions(rest.slice(2));
+    }
+    else {
+        throw new Error(`Query method "${name}": expected "By<...>" or "All" after prefix, got "${rest}"`);
+    }
+    return { prefix, conditions, orderBy, limit };
+}
+
+export { parseQueryMethodName };

package/dist/src/feature/pg/withPgClient.js

@@ -1,4 +1,4 @@
-import { AsyncLocalStorage } from 'async_hooks';
+import { AsyncLocalStorage } from 'node:async_hooks';
 
 // Async-local storage for clients per pool
 const pgStorage = new AsyncLocalStorage();

package/dist/src/feature/rest-controller/runRestControllers.js

@@ -6,11 +6,11 @@ import { validateModel } from '../../core/validation/core/validateModel.js';
 import { ValidationMetadataStore } from '../../core/validation/metadata/ValidationMetadataStore.js';
 import { ExpressProvider } from '../express/ExpressProvider.js';
 import { json, urlencoded } from 'express';
-import path__default from 'path';
+import path__default from 'node:path';
 import { EXPRESS_REQ, EXPRESS_RES } from './injection-tokens.js';
 import { RestControllerMetadataStore } from './metadata/RestControllerMetadataStore.js';
 import { RestRequest } from './RestRequest.js';
-import { IncomingMessage } from 'http';
+import { IncomingMessage } from 'node:http';
 import { Container } from '../../core/injection/Container.js';
 
 function buildRequest(req) {

package/dist/src/index.d.ts

@@ -4,11 +4,11 @@ export { DependencyContainer } from 'tsyringe';
 import InjectionToken from 'tsyringe/dist/typings/providers/injection-token';
 import DependencyContainer, { PreResolutionInterceptorCallback, PostResolutionInterceptorCallback } from 'tsyringe/dist/typings/types/dependency-container';
 import InterceptionOptions from 'tsyringe/dist/typings/types/interceptor-options';
-import { Server, IncomingMessage } from 'http';
+import { Server, IncomingMessage } from 'node:http';
 import { Express, Request, Response } from 'express';
 import * as big_js from 'big.js';
 import { Pool, PoolClient } from 'pg';
-import { AsyncLocalStorage } from 'async_hooks';
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { Server as Server$1, Socket } from 'socket.io';
 import { Algorithm } from 'jsonwebtoken';
 import { Socket as Socket$1 } from 'socket.io-client';
@@ -32,21 +32,26 @@ declare class Auth<D> {
 }
 
 type ConfigReferenceType = 'string' | 'number' | 'boolean' | 'object' | 'string-array' | 'number-array' | 'boolean-array';
-interface ConfigReference {
+interface ConfigReference<TResolved = unknown> {
     type: ConfigReferenceType;
     path: string;
     default?: string;
     __isConfigReference: true;
+    __resolvedType?: TResolved;
 }
 
-declare function str(strings: TemplateStringsArray): ConfigReference;
-declare function num(strings: TemplateStringsArray): ConfigReference;
-declare function bool(strings: TemplateStringsArray): ConfigReference;
-declare function obj(strings: TemplateStringsArray): ConfigReference;
-declare function strArr(strings: TemplateStringsArray): ConfigReference;
-declare function numArr(strings: TemplateStringsArray): ConfigReference;
-declare function boolArr(strings: TemplateStringsArray): ConfigReference;
+declare function str(strings: TemplateStringsArray): ConfigReference<string>;
+declare function num(strings: TemplateStringsArray): ConfigReference<number>;
+declare function bool(strings: TemplateStringsArray): ConfigReference<boolean>;
+declare function obj<T = unknown>(strings: TemplateStringsArray): ConfigReference<T>;
+declare function strArr(strings: TemplateStringsArray): ConfigReference<string[]>;
+declare function numArr(strings: TemplateStringsArray): ConfigReference<number[]>;
+declare function boolArr(strings: TemplateStringsArray): ConfigReference<boolean[]>;
 
+type ResolvedConfig<T> = {
+    [K in keyof T]: T[K] extends ConfigReference<infer R> ? R : T[K];
+};
+declare function resolveConfigReferences<T extends Record<string, any>>(config: T): ResolvedConfig<T>;
 declare class ConfigResolver {
     static resolve(reference: ConfigReference): unknown;
     private static loadFromEnv;
@@ -55,8 +60,6 @@ declare class ConfigResolver {
     private static parseArrayItems;
 }
 
-declare function resolveConfigReferences<T extends Record<string, any>>(config: T): T;
-
 interface ILockKey {
     run<T>(fn: () => Promise<T>): Promise<T>;
     tryRun<T>(fn: () => Promise<T>): Promise<T | undefined>;
@@ -724,17 +727,34 @@ interface IMindsetIdentity {
     personality?: string;
     emotions?: string;
 }
+/** @deprecated use {@link IMindsetModelRef} */
 interface IMindsetLlm {
     provider?: string;
     model: string;
 }
+interface IMindsetModelRef {
+    provider?: string;
+    model: string;
+}
+type IMindsetModelKind = 'llm' | 'visionLlm' | 'audioLlm' | 'speechToText' | 'textToSpeech' | 'imageGen' | 'embedding';
+interface IMindsetModels {
+    llm?: IMindsetModelRef[];
+    visionLlm?: IMindsetModelRef[];
+    audioLlm?: IMindsetModelRef[];
+    speechToText?: IMindsetModelRef[];
+    textToSpeech?: IMindsetModelRef[];
+    imageGen?: IMindsetModelRef[];
+    embedding?: IMindsetModelRef[];
+}
 interface IMindset {
     context(): Promise<string>;
     identity(): Promise<IMindsetIdentity>;
     skills(): Promise<string>;
     limits(): Promise<string>;
     workflow(): Promise<string>;
-    llms(): Promise<IMindsetLlm[]>;
+    models?(): Promise<IMindsetModels>;
+    /** @deprecated implement {@link IMindset.models} instead */
+    llms?(): Promise<IMindsetLlm[]>;
 }
 declare class Mindset implements IMindset {
     context(): Promise<string>;
@@ -742,7 +762,9 @@ declare class Mindset implements IMindset {
     skills(): Promise<string>;
     limits(): Promise<string>;
     workflow(): Promise<string>;
-    llms(): Promise<IMindsetLlm[]>;
+    models?(): Promise<IMindsetModels>;
+    /** @deprecated implement {@link Mindset.models} instead */
+    llms?(): Promise<IMindsetLlm[]>;
 }
 
 interface IMindsetConfig {
@@ -842,7 +864,10 @@ declare class MindsetOperator implements IMindset {
     skills(): Promise<string>;
     limits(): Promise<string>;
     workflow(): Promise<string>;
+    /** @deprecated use {@link MindsetOperator.models} */
     llms(): Promise<IMindsetLlm[]>;
+    models(): Promise<IMindsetModels>;
+    resolveModels(kind: IMindsetModelKind): Promise<IMindsetModelRef[]>;
     systemPrompt(): Promise<string>;
     tools(): IMindsetTool[];
     protected paramDescription(rawDescription: string, rawType: string): string;
@@ -887,6 +912,7 @@ interface IFunctionCall {
     name: string;
     arguments?: string;
     result?: string;
+    signature?: string;
 }
 
 declare const chatItemTypeOptions: readonly ["botMessage", "humanMessage", "functionCall"];
@@ -914,10 +940,15 @@ type IChatItemType = (typeof chatItemTypeOptions)[number];
 interface ILanguageModelUsage {
     inputTokens: number;
     outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    costUsd?: number;
+    provider?: string;
+    model?: string;
 }
 
 interface IChatAdapterNextItemsReq {
-    model: string;
+    models: IMindsetModelRef[];
     systemPrompt: string;
     tools: IMindsetTool[];
     prevItems: IChatItem[];
@@ -931,9 +962,16 @@ interface IChatAdapter {
 }
 
 declare class ChatAdapter implements IChatAdapter {
-    nextItems(req: IChatAdapterNextItemsReq & {
-        provider?: string;
-    }): Promise<IChatAdapterNextItemsRes>;
+    nextItems(req: IChatAdapterNextItemsReq): Promise<IChatAdapterNextItemsRes>;
+}
+
+declare class ChatAdapterRegistry {
+    private adapters;
+    private order;
+    register(provider: string, adapter: IChatAdapter): void;
+    get(provider: string): IChatAdapter | undefined;
+    defaultProvider(): string | undefined;
+    size(): number;
 }
 
 type IChatItemData = IEntityData & IChatItem;
@@ -1001,8 +1039,47 @@ declare class ChatOperator {
     removeAssociation(association: IChatAssociation): Promise<void>;
 }
 
+declare class UnionChatAdapter implements IChatAdapter {
+    private registry;
+    private logger;
+    constructor(registry: ChatAdapterRegistry);
+    nextItems(req: IChatAdapterNextItemsReq): Promise<IChatAdapterNextItemsRes>;
+    private groupByProvider;
+}
+
+interface IExtractChatMessageTextOptions {
+    supportedImageMimeTypes?: readonly string[];
+    supportedDocumentMimeTypes?: readonly string[];
+}
+declare function extractChatMessageText(message: IChatMessage, options?: IExtractChatMessageTextOptions): string;
+
+declare function isChatMessageEmpty(message: IChatMessage): boolean;
+
+/**
+ * Returns true when an error from a chat adapter is worth retrying with another
+ * model or another adapter (transient/availability issues), false when retrying
+ * would just propagate the same configuration problem (auth, validation).
+ */
+declare function isRetryableError(err: unknown): boolean;
+
+interface IChatAdapterDecoratorConfig {
+    provider: string;
+}
+declare function chatAdapter(config: IChatAdapterDecoratorConfig): (target: IConstructor<IChatAdapter>) => void;
+
 declare function chatBot(mindset: IConstructor<IMindset>): (target: object, propertyKey: string | symbol | undefined, parameterIndex: number) => void;
 
+interface IChatAdapterMetadata {
+    constructor: IConstructor<IChatAdapter>;
+    provider: string;
+}
+
+declare class ChatAdapterMetadataStore {
+    private adapters;
+    save(metadata: IChatAdapterMetadata): void;
+    get(ctor: IConstructor<IChatAdapter>): IChatAdapterMetadata | undefined;
+}
+
 interface IChatBotMetadata {
     constructor: IConstructor<any>;
     mindsetConstructor: IConstructor<IMindset>;
@@ -1015,15 +1092,9 @@ declare class ChatBotMetadataStore {
     getChatBotsMetadata(): IChatBotMetadata[];
 }
 
-declare function safeJsonParse<T = unknown>(json: string | undefined | null, context?: string): T;
+declare function runChatAdapters(adapters: IConstructor<IChatAdapter>[]): void;
 
-interface IExtractChatMessageTextOptions {
-    supportedImageMimeTypes?: readonly string[];
-    supportedDocumentMimeTypes?: readonly string[];
-}
-declare function extractChatMessageText(message: IChatMessage, options?: IExtractChatMessageTextOptions): string;
-
-declare function isChatMessageEmpty(message: IChatMessage): boolean;
+declare function safeJsonParse<T = unknown>(json: string | undefined | null, context?: string): T;
 
 interface IchatControllerConfig {
 }
@@ -1206,6 +1277,55 @@ declare const pgStorage: AsyncLocalStorage<ClientMap>;
  */
 declare function getClientMap(): ClientMap;
 
+declare function pgJsonRepository<P extends Entity<IEntityData>>(config: IPgRepositoryConfig<P>): (target: IConstructor<any>) => void;
+
+declare function query(): (target: object, propertyKey: string | symbol) => void;
+
+declare class PgJsonRepository<P extends Entity<IEntityData>> extends PgCrudRepository<P> {
+    constructor(pool: Pool);
+}
+
+interface IQueryMethodMetadata {
+    repositoryConstructor: IConstructor<any>;
+    functionName: string;
+}
+declare class PgRepositoryMetadataStore {
+    private queryMethods;
+    private repositoryConfigs;
+    saveQueryMethodMetadata(metadata: IQueryMethodMetadata): void;
+    saveRepositoryConfig<P extends Entity<IEntityData>>(ctor: IConstructor<any>, config: IPgRepositoryConfig<P>): void;
+    getRepositoryConfig(ctor: IConstructor<any>): IPgRepositoryConfig<any> | undefined;
+    getQueryMethods(ctor: IConstructor<any>): IQueryMethodMetadata[];
+}
+
+type QueryPrefix = 'find' | 'findOne' | 'count' | 'exists' | 'delete';
+type QueryOperator = 'Equals' | 'Not' | 'Like' | 'NotLike' | 'In' | 'NotIn' | 'Gt' | 'Gte' | 'Lt' | 'Lte' | 'IsNull' | 'IsNotNull';
+type QueryConnector = 'And' | 'Or';
+interface IQueryCondition {
+    field: string;
+    operator: QueryOperator;
+    connector?: QueryConnector;
+}
+interface IQueryOrderBy {
+    field: string;
+    direction: 'ASC' | 'DESC';
+}
+interface IQueryAst {
+    prefix: QueryPrefix;
+    conditions: IQueryCondition[];
+    orderBy: IQueryOrderBy[];
+    limit?: number;
+}
+
+interface IBuiltQuery {
+    sql: string;
+    argCount: number;
+    buildParams: (args: any[]) => any[];
+}
+declare function buildQuerySql(ast: IQueryAst, table: string, columns: string): IBuiltQuery;
+
+declare function parseQueryMethodName(name: string): IQueryAst;
+
 /**
  * Runs a function with a shared Postgres client for the given pool.
  * Reuses the client if already present in the async context.
@@ -2256,4 +2376,4 @@ declare function HtmlModule(options: IHtmlModuleOptions): {
     new (): {};
 };
 
-export { AnthropicChatAdapter, ApiKey, ApiKeyGuardMiddleware, ApiKeyHandshakeGuardMiddleware, ApiKeyRepository, Async, AsyncMetadataStore, Auth, Chat, ChatAdapter, ChatBot, ChatBotMetadataStore, ChatItem, ChatMemory, ChatOperator, ChatRepository, ChatResolver, type ClientMap, CmdChannel, type ConfigReference, type ConfigReferenceType, ConfigResolver, Container, ControllerMetadataStore, CronJob, CronJobRepository, CustomError, DeepSeekChatAdapter, DescriptionMetadataStore, EXPRESS_REQ, EXPRESS_RES, Entity, Env, EnvWhatsAppRepository, type ErrorSeverity, ExpressProvider, GoogleChatAdapter, type GoogleChatAdapterV2Options, HtmlModule, HttpServerProvider, type IApiKeyData, type IApiKeyRepository, type IArrayValidationError, type IArrayValidationResult, type IBotMessageItem, type IChannelMessage, type IChannelMetadata, type IChatAdapter, type IChatAdapterNextItemsReq, type IChatAdapterNextItemsRes, type IChatAssociation, type IChatBot, type IChatBotMetadata, type IChatChannel, type IChatConnection, type IChatControllerMetadata, type IChatData, type IChatItem, type IChatItemData, type IChatItemType, type IChatMemory, type IChatMessage, type IChatMessageDocument, type IChatMessageFile, type IChatMessageImage, type IChatMessagesPrivateFile, type IChatMessagesPublicFile, type IChatRepository, type IChatType, type ICmdChannelMessage, type ICmdReceivedMessage, type ICommandConfig, type ICommandHandler, type ICommandHandlerConfig, type IConstructor, type ICronConfig, type ICronJobData, type ICrudRepository, type ICustomErrorData, type IDescriptionMetadata, type IEndPointConfig, type IEndPointMetadata, type IEntityData, type IEnvType, type IErrorHandlersConfig, type IErrorMonitor, type IErrorMonitorContext, type IExtractChatMessageTextOptions, type IFunctionCall, type IFunctionCallItem, type IGenerateApiKeyReq, type IGenerateApiKeyRes, type IGetWhatsAppTemplateRequest, type IHandshakeMiddleware, type IHandshakeMiddlewareMetadata, type IHtmlModuleOptions, type IHumanMessageItem, type IJobData, type IJobRepository, type IJwtRefreshTokenData, type IJwtRefreshTokenRepository, type ILanguageModelUsage, type IListenWhatsAppMessageRequest, type ILockKey, type ILocker, type ILockerKey, type IMessageContext, type IMiddleware, type IMiddlewareMetadata, type IMindset, type IMindsetConfig, type IMindsetIdentity, type IMindsetLlm, type IMindsetMetadata, type IMindsetModuleConfig, type IMindsetModuleMetadata, type IMindsetTool, type IMindsetToolParameter, type IModelValidationError, type IModelValidationResult, type IModelValidatorsInfo, type IMoneyData, type IPersistentData, type IPgRepositoryConfig, type IPropertyValidatorInfo, type IReceivedMessage, type IRemoteApiKeyFetcher, type IRestControllerConfig, type IRestControllerMetadata, type IScheduleAt, type IScheduleDelay, type ISendByWasenderRequest, type ISendWhatsAppRequest, type ISendWhatsAppTemplateRequest, type ISocketChannelConfig, type ISocketChannelMessage, type ISocketChannelReceivedMessage, type ISocketControllerConfig, type ISocketControllerMetadata, type ISocketEventConfig, type ISocketEventMetadata, type ISocketReceivedMessage, type IStorableData, type ITelegramChannelConfig, type ITelegramChannelMessage, type ITelegramReceivedMessage, type IValidateArrayOptions, type IValidateArrayOptionsWithItemsValidators, type IValidateInputShape, type IValidateIsInOptions, type IValidateIsRecordOptions, type IValidateMaxOptions, type IValidateMinOptions, type IValidationError, type IValidationResult, type IValidator, type IValidatorMetadata, type IWasenderChannelMessageListener, type IWasenderDeviceListMetadata, type IWasenderEvent, type IWasenderMessageContent, type IWasenderMessageContextInfo, type IWasenderMessageKey, type IWasenderMessageReceivedData, type IWasenderMessageReceivedEvent, type IWasenderQrUpdatedEvent, type IWhatsAppBusinessAccount, type IWhatsAppBusinessNumber, type IWhatsAppByWasenderChannelConfig, type IWhatsAppByWasenderReceivedMessage, type IWhatsAppChannelMessage, type IWhatsAppCloudContact, type IWhatsAppCloudMessage, type IWhatsAppCloudMessageMetadata, type IWhatsAppCloudTemplate, type IWhatsAppCloudTemplateComponent, type IWhatsAppCloudTemplateMessage, type IWhatsAppCloudTemplateParameter, type IWhatsAppCloudTemplateResponse, type IWhatsAppCloudWebhookPayload, type IWhatsAppData, type IWhatsAppMessageListener, type IWhatsAppProxyListenMessageEventData, type IWhatsAppProxyListenMessageEventReq, type IWhatsAppProxyMessage, type IWhatsAppProxyMessageContent, type IWhatsAppProxyMessageEventReq, type IWhatsAppProxySendMessageEventReq, type IWhatsAppReceivedMessage, type IWhatsAppRepository, type IWhatsAppSenderOptions, type IWhatsappChannelConfig, type IchatControllerConfig, Job, JobRepository, JobRunner, Jwt, JwtAccessAndRefreshTokenDto, JwtConfig, JwtGuardMiddleware, JwtHandshakeGuardMiddleware, JwtRefreshToken, JwtRefreshTokenRepository, JwtSigner, JwtTokenDto, Lifecycle, Locker, Logger, Mapper, Mindset, MindsetMetadataStore, MindsetOperator, Money, MoneyDto, OpenRouterChatAdapter, OpenaiChatAdapter, Password, type PasswordHashOptions, Persistent, PgApiKeyRepository, PgChatMemory, PgChatRepository, PgCronJobRepository, PgCrudRepository, PgJobRepository, PgJwtRefreshTokenRepository, PgLockKey, PgLocker, PgRepositoryBase, PgWhatsAppRepository, RamChatMemory, RamChatRepository, Random, RemoteApiKeyRepository, RestControllerMetadataStore, RestRequest, SocketChannel, SocketChannelConfig, SocketChannelMessageFile, SocketChannelReceivedMessage, SocketControllerMetadataStore, SocketServerConfig, SocketServerProvider, Storable, TelegramChannel, TelegramChannelConfig, ValidationMetadataStore, WHATSAPP_MESSAGE_EVENT, WHATSAPP_PROXY_LISTEN_MESSAGE_EVENT, WHATSAPP_PROXY_SEND_MESSAGE_EVENT, WabotChatAdapter, WasenderWebhookController, WhatsApp, WhatsAppByWasenderChannel, WhatsAppByWasenderChannelConfig, WhatsAppChannel, WhatsAppReceiver, WhatsAppReceiverByCloudApi, WhatsAppReceiverByWabotProxy, WhatsAppReceiverByWasender, WhatsAppRepository, WhatsAppSender, WhatsAppSenderByCloudApi, WhatsAppSenderByWabotProxy, WhatsAppSenderByWasender, WhatsAppWabotProxyConnection, WhatsappChannelConfig, apiKeyGuard, apiKeyHandshakeGuard, bool, boolArr, chatBot, chatController, chatItemTypeOptions, cmd, cmdChannelName, command, commandHandler, container, cron, description, errorToPlainObject, extractChatMessageText, extractNumberFromWasenderMessageKey, getClientMap, getPgClient, handshakeMiddlewares, inject, injectable, isArray, isBoolean, isChatMessageEmpty, isDate, isIn, isModel, isNotEmpty, isNumber, isOptional, isPresent, isRecord, isString, jwtGuard, jwtHandshakeGuard, max, middleware, min, mindset, mindsetModule, modelInfo, num, numArr, obj, onDelete, onGet, onPost, onPut, onSocketEvent, pgStorage, readJsonFromFile, resolveConfigReferences, restController, runChatControllers, runCommandHandlers, runCronHandlers, runRestControllers, runSocketControllers, safeJsonParse, scoped, setupErrorHandlers, singleton, socket, socketChannelName, socketController, stopCommandHandlers, stopCronHandlers, str, strArr, telegram, telegramChannelName, validateAndTransform, validateArray, validateIsBoolean, validateIsDate, validateIsIn, validateIsNotEmpty, validateIsNumber, validateIsPresent, validateIsRecord, validateIsString, validateMax, validateMin, validateModel, whatsApp, whatsAppByWasender, whatsAppByWasenderChannelName, whatsAppChannelName, withPgClient, withPgTransaction, writeJsonToFile };
+export { AnthropicChatAdapter, ApiKey, ApiKeyGuardMiddleware, ApiKeyHandshakeGuardMiddleware, ApiKeyRepository, Async, AsyncMetadataStore, Auth, Chat, ChatAdapter, ChatAdapterMetadataStore, ChatAdapterRegistry, ChatBot, ChatBotMetadataStore, ChatItem, ChatMemory, ChatOperator, ChatRepository, ChatResolver, type ClientMap, CmdChannel, type ConfigReference, type ConfigReferenceType, ConfigResolver, Container, ControllerMetadataStore, CronJob, CronJobRepository, CustomError, DeepSeekChatAdapter, DescriptionMetadataStore, EXPRESS_REQ, EXPRESS_RES, Entity, Env, EnvWhatsAppRepository, type ErrorSeverity, ExpressProvider, GoogleChatAdapter, type GoogleChatAdapterV2Options, HtmlModule, HttpServerProvider, type IApiKeyData, type IApiKeyRepository, type IArrayValidationError, type IArrayValidationResult, type IBotMessageItem, type IBuiltQuery, type IChannelMessage, type IChannelMetadata, type IChatAdapter, type IChatAdapterDecoratorConfig, type IChatAdapterMetadata, type IChatAdapterNextItemsReq, type IChatAdapterNextItemsRes, type IChatAssociation, type IChatBot, type IChatBotMetadata, type IChatChannel, type IChatConnection, type IChatControllerMetadata, type IChatData, type IChatItem, type IChatItemData, type IChatItemType, type IChatMemory, type IChatMessage, type IChatMessageDocument, type IChatMessageFile, type IChatMessageImage, type IChatMessagesPrivateFile, type IChatMessagesPublicFile, type IChatRepository, type IChatType, type ICmdChannelMessage, type ICmdReceivedMessage, type ICommandConfig, type ICommandHandler, type ICommandHandlerConfig, type IConstructor, type ICronConfig, type ICronJobData, type ICrudRepository, type ICustomErrorData, type IDescriptionMetadata, type IEndPointConfig, type IEndPointMetadata, type IEntityData, type IEnvType, type IErrorHandlersConfig, type IErrorMonitor, type IErrorMonitorContext, type IExtractChatMessageTextOptions, type IFunctionCall, type IFunctionCallItem, type IGenerateApiKeyReq, type IGenerateApiKeyRes, type IGetWhatsAppTemplateRequest, type IHandshakeMiddleware, type IHandshakeMiddlewareMetadata, type IHtmlModuleOptions, type IHumanMessageItem, type IJobData, type IJobRepository, type IJwtRefreshTokenData, type IJwtRefreshTokenRepository, type ILanguageModelUsage, type IListenWhatsAppMessageRequest, type ILockKey, type ILocker, type ILockerKey, type IMessageContext, type IMiddleware, type IMiddlewareMetadata, type IMindset, type IMindsetConfig, type IMindsetIdentity, type IMindsetLlm, type IMindsetMetadata, type IMindsetModelKind, type IMindsetModelRef, type IMindsetModels, type IMindsetModuleConfig, type IMindsetModuleMetadata, type IMindsetTool, type IMindsetToolParameter, type IModelValidationError, type IModelValidationResult, type IModelValidatorsInfo, type IMoneyData, type IPersistentData, type IPgRepositoryConfig, type IPropertyValidatorInfo, type IQueryAst, type IQueryCondition, type IQueryMethodMetadata, type IQueryOrderBy, type IReceivedMessage, type IRemoteApiKeyFetcher, type IRestControllerConfig, type IRestControllerMetadata, type IScheduleAt, type IScheduleDelay, type ISendByWasenderRequest, type ISendWhatsAppRequest, type ISendWhatsAppTemplateRequest, type ISocketChannelConfig, type ISocketChannelMessage, type ISocketChannelReceivedMessage, type ISocketControllerConfig, type ISocketControllerMetadata, type ISocketEventConfig, type ISocketEventMetadata, type ISocketReceivedMessage, type IStorableData, type ITelegramChannelConfig, type ITelegramChannelMessage, type ITelegramReceivedMessage, type IValidateArrayOptions, type IValidateArrayOptionsWithItemsValidators, type IValidateInputShape, type IValidateIsInOptions, type IValidateIsRecordOptions, type IValidateMaxOptions, type IValidateMinOptions, type IValidationError, type IValidationResult, type IValidator, type IValidatorMetadata, type IWasenderChannelMessageListener, type IWasenderDeviceListMetadata, type IWasenderEvent, type IWasenderMessageContent, type IWasenderMessageContextInfo, type IWasenderMessageKey, type IWasenderMessageReceivedData, type IWasenderMessageReceivedEvent, type IWasenderQrUpdatedEvent, type IWhatsAppBusinessAccount, type IWhatsAppBusinessNumber, type IWhatsAppByWasenderChannelConfig, type IWhatsAppByWasenderReceivedMessage, type IWhatsAppChannelMessage, type IWhatsAppCloudContact, type IWhatsAppCloudMessage, type IWhatsAppCloudMessageMetadata, type IWhatsAppCloudTemplate, type IWhatsAppCloudTemplateComponent, type IWhatsAppCloudTemplateMessage, type IWhatsAppCloudTemplateParameter, type IWhatsAppCloudTemplateResponse, type IWhatsAppCloudWebhookPayload, type IWhatsAppData, type IWhatsAppMessageListener, type IWhatsAppProxyListenMessageEventData, type IWhatsAppProxyListenMessageEventReq, type IWhatsAppProxyMessage, type IWhatsAppProxyMessageContent, type IWhatsAppProxyMessageEventReq, type IWhatsAppProxySendMessageEventReq, type IWhatsAppReceivedMessage, type IWhatsAppRepository, type IWhatsAppSenderOptions, type IWhatsappChannelConfig, type IchatControllerConfig, Job, JobRepository, JobRunner, Jwt, JwtAccessAndRefreshTokenDto, JwtConfig, JwtGuardMiddleware, JwtHandshakeGuardMiddleware, JwtRefreshToken, JwtRefreshTokenRepository, JwtSigner, JwtTokenDto, Lifecycle, Locker, Logger, Mapper, Mindset, MindsetMetadataStore, MindsetOperator, Money, MoneyDto, OpenRouterChatAdapter, OpenaiChatAdapter, Password, type PasswordHashOptions, Persistent, PgApiKeyRepository, PgChatMemory, PgChatRepository, PgCronJobRepository, PgCrudRepository, PgJobRepository, PgJsonRepository, PgJwtRefreshTokenRepository, PgLockKey, PgLocker, PgRepositoryBase, PgRepositoryMetadataStore, PgWhatsAppRepository, type QueryConnector, type QueryOperator, type QueryPrefix, RamChatMemory, RamChatRepository, Random, RemoteApiKeyRepository, type ResolvedConfig, RestControllerMetadataStore, RestRequest, SocketChannel, SocketChannelConfig, SocketChannelMessageFile, SocketChannelReceivedMessage, SocketControllerMetadataStore, SocketServerConfig, SocketServerProvider, Storable, TelegramChannel, TelegramChannelConfig, UnionChatAdapter, ValidationMetadataStore, WHATSAPP_MESSAGE_EVENT, WHATSAPP_PROXY_LISTEN_MESSAGE_EVENT, WHATSAPP_PROXY_SEND_MESSAGE_EVENT, WabotChatAdapter, WasenderWebhookController, WhatsApp, WhatsAppByWasenderChannel, WhatsAppByWasenderChannelConfig, WhatsAppChannel, WhatsAppReceiver, WhatsAppReceiverByCloudApi, WhatsAppReceiverByWabotProxy, WhatsAppReceiverByWasender, WhatsAppRepository, WhatsAppSender, WhatsAppSenderByCloudApi, WhatsAppSenderByWabotProxy, WhatsAppSenderByWasender, WhatsAppWabotProxyConnection, WhatsappChannelConfig, apiKeyGuard, apiKeyHandshakeGuard, bool, boolArr, buildQuerySql, chatAdapter, chatBot, chatController, chatItemTypeOptions, cmd, cmdChannelName, command, commandHandler, container, cron, description, errorToPlainObject, extractChatMessageText, extractNumberFromWasenderMessageKey, getClientMap, getPgClient, handshakeMiddlewares, inject, injectable, isArray, isBoolean, isChatMessageEmpty, isDate, isIn, isModel, isNotEmpty, isNumber, isOptional, isPresent, isRecord, isRetryableError, isString, jwtGuard, jwtHandshakeGuard, max, middleware, min, mindset, mindsetModule, modelInfo, num, numArr, obj, onDelete, onGet, onPost, onPut, onSocketEvent, parseQueryMethodName, pgJsonRepository, pgStorage, query, readJsonFromFile, resolveConfigReferences, restController, runChatAdapters, runChatControllers, runCommandHandlers, runCronHandlers, runRestControllers, runSocketControllers, safeJsonParse, scoped, setupErrorHandlers, singleton, socket, socketChannelName, socketController, stopCommandHandlers, stopCronHandlers, str, strArr, telegram, telegramChannelName, validateAndTransform, validateArray, validateIsBoolean, validateIsDate, validateIsIn, validateIsNotEmpty, validateIsNumber, validateIsPresent, validateIsRecord, validateIsString, validateMax, validateMin, validateModel, whatsApp, whatsAppByWasender, whatsAppByWasenderChannelName, whatsAppChannelName, withPgClient, withPgTransaction, writeJsonToFile };