@decaf-ts/core/lib/query/MethodQueryBuilder.d.ts

Core persistence module for the decaf framework

import { QueryAssist } from "./types";
import { LoggedClass, Logger } from "@decaf-ts/logging";
/**
 * @description
 * Utility class to build query objects from repository method names.
 *
 * @summary
 * The `MethodQueryBuilder` class parses method names that follow a specific naming convention
 * (e.g., `findByNameAndAgeOrderByCountryAsc`) and converts them into structured query objects
 * (`QueryAssist`). It extracts clauses such as `select`, `where`, `groupBy`, `orderBy`, `limit`,
 * and `offset`, ensuring that developers can declare repository queries using expressive method names.
 *
 * @param methodName {string} - The repository method name to parse and convert into a query.
 * @param values {any[]} - The values corresponding to method parameters used for query conditions.
 *
 * @return {QueryAssist} A structured query object describing the parsed action, select, where,
 * groupBy, orderBy, limit, and offset clauses.
 *
 * @class
 *
 * @example
 * ```ts
 * const query = MethodQueryBuilder.build(
 *   "findByNameAndAgeOrderByCountryAsc",
 *   "John",
 *   25,
 *   [["country", "ASC"]]
 * );
 *
 * console.log(query);
 * // {
 * //   action: "find",
 * //   select: undefined,
 * //   where: { ... },
 * //   groupBy: undefined,
 * //   orderBy: [["country", "ASC"]],
 * //   limit: undefined,
 * //   offset: undefined
 * // }
 * ```
 *
 * @mermaid
 * sequenceDiagram
 *   participant Repo as Repository Method
 *   participant MQB as MethodQueryBuilder
 *   participant Query as QueryAssist
 *
 *   Repo->>MQB: build(methodName, ...values)
 *   MQB->>MQB: extractCore(methodName)
 *   MQB->>MQB: extractSelect(methodName)
 *   MQB->>MQB: extractGroupBy(methodName)
 *   MQB->>MQB: buildWhere(core, values)
 *   MQB->>MQB: extractOrderLimitOffset(core, values)
 *   MQB->>Query: return structured QueryAssist object
 */
export declare class MethodQueryBuilder extends LoggedClass {
    private static _logger;
    protected static get log(): Logger;
    /**
     * @description
     * Builds a `QueryAssist` object by parsing a repository method name and values.
     *
     * @summary
     * The method validates the method name, extracts clauses (core, select, groupBy, where,
     * orderBy, limit, and offset), and assembles them into a structured query object
     * that can be executed against a data source.
     *
     * @param methodName {string} - The repository method name that encodes query information.
     * @param values {any[]} - The values corresponding to conditions and extra clauses.
     *
     * @return {QueryAssist} A structured query object representing the parsed query.
     */
    static build(methodName: string, ...values: any[]): QueryAssist;
    /**
     * @description
     * Extracts the core part of the method name after `findBy` and before any special clauses.
     *
     * @summary
     * Removes prefixes and detects delimiters (`Then`, `OrderBy`, `GroupBy`, `Limit`, `Offset`)
     * to isolate the main conditional part of the query.
     *
     * @param methodName {string} - The method name to parse.
     *
     * @return {string} The extracted core string used for building conditions.
     */
    private static extractCore;
    static getFieldsFromMethodName(methodName: string): Array<string>;
    /**
     * @description
     * Extracts the select clause from a method name.
     *
     * @summary
     * Detects the `Select` keyword in the method name, isolates the fields following it,
     * and returns them as an array of lowercase-first strings.
     *
     * @param methodName {string} - The method name to parse.
     *
     * @return {string[] | undefined} An array of selected fields or `undefined` if no select clause exists.
     */
    private static extractSelect;
    /**
     * @description
     * Extracts the group by clause from a method name.
     *
     * @summary
     * Detects the `GroupBy` keyword in the method name, isolates the fields following it,
     * and returns them as an array of lowercase-first strings.
     *
     * @param methodName {string} - The method name to parse.
     *
     * @return {string[] | undefined} An array of group by fields or `undefined` if no group by clause exists.
     */
    private static extractGroupBy;
    /**
     * @description
     * Builds the `where` condition object based on the parsed core string and parameter values.
     *
     * @summary
     * Splits the core string by logical operators (`And`, `Or`), parses each token into a field
     * and operator, and combines them into a `Condition` object using the provided values.
     *
     * @param core {string} - The extracted core string from the method name.
     * @param values {any[]} - The values corresponding to the conditions.
     *
     * @return {Condition<any>} A structured condition object representing the query's where clause.
     */
    private static buildWhere;
    /**
     * @description
     * Parses a field name and operator from a string token.
     *
     * @summary
     * Identifies the operator suffix (if present) and returns a descriptor containing the field
     * name in lowercase-first format along with the operator.
     *
     * @param str {string} - The token string to parse.
     *
     * @return {FilterDescriptor} An object containing the field name and operator.
     */
    private static parseFieldAndOperator;
    private static extractOrderByField;
    private static getProperlyOrderByOrThrow;
    /**
     * @description
     * Extracts `orderBy`, `limit`, and `offset` clauses from method arguments.
     *
     * @summary
     * Determines the number of condition arguments, then checks the remaining arguments
     * to resolve sorting, limiting, and pagination.
     *
     * @param methodName {string} - The extracted core string from the method name.
     * @param values {any[]} - The values corresponding to method arguments, including conditions and extras.
     *
     * @return {OrderLimitOffsetExtract} An object containing orderBy, limit, and offset values if present.
     */
    private static extractOrderLimitOffset;
}