@decaf-ts/core 0.20.0 → 0.21.0

package/lib/types/query/MethodQueryBuilder.d.ts

@@ -0,0 +1,185 @@
+import { QueryAction, QueryAssist } from "./types";
+import { LoggedClass, Logger } from "@decaf-ts/logging";
+export type QueryActionPrefix = {
+    action: QueryAction;
+    prefix: string;
+};
+/**
+ * @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
+     * Map of query prefixes to their corresponding actions.
+     */
+    private static readonly prefixMap;
+    /**
+     * @description
+     * Determines the action and prefix length from a method name.
+     *
+     * @param methodName {string} - The repository method name.
+     * @return {QueryActionPrefix} | undefined} The action and prefix if found.
+     */
+    private static getActionFromMethodName;
+    /**
+     * @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 aggregation selector field from method names like countByAge, sumByPrice.
+     *
+     * @param methodName {string} - The method name.
+     * @param prefix {string} - The prefix to remove.
+     * @return {string | undefined} The selector field name.
+     */
+    private static extractAggregationSelector;
+    /**
+     * @description
+     * Extracts the core part of the method name after the prefix 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.
+     * @param prefix {string} - The prefix to remove (e.g., "findBy", "countBy").
+     *
+     * @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 method name.
+     * @param values {any[]} - The values corresponding to method arguments, including conditions and extras.
+     * @param core {string} - The pre-extracted core string.
+     *
+     * @return {OrderLimitOffsetExtract} An object containing orderBy, limit, and offset values if present.
+     */
+    private static extractOrderLimitOffset;
+}

package/lib/types/query/Paginator.d.ts

@@ -0,0 +1,105 @@
+import { Adapter } from "../persistence/Adapter";
+import { Model } from "@decaf-ts/decorator-validation";
+import { Constructor } from "@decaf-ts/decoration";
+import { LoggedClass } from "@decaf-ts/logging";
+import { ContextualArgs, MaybeContextualArg } from "../utils/ContextualLoggedClass";
+import { PreparedStatement } from "./types";
+/**
+ * @description Handles pagination for database queries
+ * @summary Provides functionality for navigating through paginated query results
+ *
+ * This abstract class manages the state and navigation of paginated database query results.
+ * It tracks the current page, total pages, and record count, and provides methods for
+ * moving between pages.
+ *
+ * @template M - The model type this paginator operates on
+ * @template R - The return type of the paginated query (defaults to M[])
+ * @template Q - The query type (defaults to any)
+ * @param {Adapter<any, Q, any, any>} adapter - The database adapter to use for executing queries
+ * @param {Q} query - The query to paginate
+ * @param {number} size - The number of records per page
+ * @param {Constructor<M>} clazz - The constructor for the model type
+ * @class Paginator
+ * @example
+ * // Create a paginator for a user query
+ * const userQuery = db.select().from(User);
+ * const paginator = await userQuery.paginate(10); // 10 users per page
+ *
+ * // Get the first page of results
+ * const firstPage = await paginator.page(1);
+ *
+ * // Navigate to the next page
+ * const secondPage = await paginator.next();
+ *
+ * // Get information about the pagination
+ * console.log(`Page ${paginator.current} of ${paginator.total}, ${paginator.count} total records`);
+ *
+ * @mermaid
+ * sequenceDiagram
+ *   participant Client
+ *   participant Paginator
+ *   participant Adapter
+ *   participant Database
+ *
+ *   Client->>Paginator: new Paginator(adapter, query, size, clazz)
+ *   Client->>Paginator: page(1)
+ *   Paginator->>Paginator: validatePage(1)
+ *   Paginator->>Paginator: prepare(query)
+ *   Paginator->>Adapter: execute query with pagination
+ *   Adapter->>Database: execute query
+ *   Database-->>Adapter: return results
+ *   Adapter-->>Paginator: return results
+ *   Paginator-->>Client: return page results
+ *
+ *   Client->>Paginator: next()
+ *   Paginator->>Paginator: page(current + 1)
+ *   Paginator->>Paginator: validatePage(current + 1)
+ *   Paginator->>Adapter: execute query with pagination
+ *   Adapter->>Database: execute query
+ *   Database-->>Adapter: return results
+ *   Adapter-->>Paginator: return results
+ *   Paginator-->>Client: return page results
+ */
+export declare abstract class Paginator<M extends Model, R = M[], Q = any> extends LoggedClass {
+    protected readonly adapter: Adapter<any, any, Q, any>;
+    protected readonly query: Q | PreparedStatement<M>;
+    readonly size: number;
+    protected readonly clazz: Constructor<M>;
+    protected _currentPage: number;
+    protected _totalPages: number;
+    protected _recordCount: number;
+    protected _bookmark?: number | string;
+    protected limit: number;
+    private _statement?;
+    get current(): number;
+    get total(): number;
+    get count(): number;
+    protected get statement(): Q;
+    protected constructor(adapter: Adapter<any, any, Q, any>, query: Q | PreparedStatement<M>, size: number, clazz: Constructor<M>);
+    protected isPreparedStatement(): "" | RegExpMatchArray | null;
+    protected pagePrefix(page?: number, ...args: MaybeContextualArg<any>): Promise<any[]>;
+    protected pagePrepared(page: number, bookmark?: any, ...argz: ContextualArgs<any>): Promise<M[]>;
+    /**
+     * @description Prepares a statement for pagination
+     * @summary Modifies the raw query statement to include pagination parameters.
+     * This protected method sets the limit parameter on the query to match the page size.
+     * @param {RawRamQuery<M>} rawStatement - The original query statement
+     * @return {RawRamQuery<M>} The modified query with pagination parameters
+     */
+    protected abstract prepare(rawStatement: Q): Q;
+    next(...args: MaybeContextualArg<any>): Promise<R>;
+    previous(...args: MaybeContextualArg<any>): Promise<R>;
+    protected validatePage(page: number): number;
+    page(page?: number, bookmark?: any, ...args: MaybeContextualArg<any>): Promise<R>;
+    serialize(data: M[], toString?: boolean): string | SerializedPage<M>;
+    apply(serialization: string | SerializedPage<M>): M[];
+    static deserialize<M extends Model>(str: string): SerializedPage<M>;
+    static isSerializedPage(obj: SerializedPage<any> | any): any;
+}
+export type SerializedPage<M extends Model> = {
+    current: number;
+    total: number;
+    count: number;
+    data: M[];
+    bookmark?: number | string;
+};

package/lib/types/query/Statement.d.ts

@@ -0,0 +1,136 @@
+import { Model } from "@decaf-ts/decorator-validation";
+import type { Executor, RawExecutor } from "../interfaces";
+import type { FromSelector, GroupBySelector, OrderBySelector, OrderDirectionInput, SelectSelector } from "./selectors";
+import { Condition } from "./Condition";
+import { Logger } from "@decaf-ts/logging";
+import type { CountDistinctOption, CountOption, DistinctOption, GroupByResult, MaxOption, MinOption, OffsetOption, OrderAndGroupOption, OrderByResult, OrderByThenByOption, PreparableStatementExecutor, SelectOption, StatementExecutor, SumOption, AvgOption, WhereOption } from "./options";
+import { Paginatable } from "../interfaces/Paginatable";
+import { Paginator } from "./Paginator";
+import { Adapter } from "../persistence/Adapter";
+import type { AdapterFlags, ContextOf } from "../persistence/types";
+import { Constructor } from "@decaf-ts/decoration";
+import { type ContextualArgs, ContextualLoggedClass, type MaybeContextualArg } from "../utils/ContextualLoggedClass";
+import { PreparedStatement } from "./types";
+import { Repository } from "../repository/Repository";
+/**
+ * @description Base class for database query statements
+ * @summary Provides a foundation for building and executing database queries
+ *
+ * This abstract class implements the query builder pattern for constructing
+ * database queries. It supports various query operations like select, from,
+ * where, orderBy, groupBy, limit, and offset. It also provides methods for
+ * executing queries and handling pagination.
+ *
+ * @template Q - The query type specific to the database adapter
+ * @template M - The model type this statement operates on
+ * @template R - The return type of the query
+ * @param {Adapter<any, Q, any, any>} adapter - The database adapter to use for executing queries
+ * @class Statement
+ * @example
+ * // Create a statement to query users
+ * const statement = new SQLStatement(adapter);
+ * const users = await statement
+ *   .select()
+ *   .from(User)
+ *   .where(Condition.attribute("status").eq("active"))
+ *   .orderBy(["createdAt", "DESC"])
+ *   .limit(10)
+ *   .execute();
+ *
+ * // Use pagination
+ * const paginator = await statement
+ *   .select()
+ *   .from(User)
+ *   .paginate(20); // 20 users per page
+ *
+ * @mermaid
+ * sequenceDiagram
+ *   participant Client
+ *   participant Statement
+ *   participant Adapter
+ *   participant Database
+ *
+ *   Client->>Statement: select()
+ *   Client->>Statement: from(Model)
+ *   Client->>Statement: where(condition)
+ *   Client->>Statement: orderBy([field, direction])
+ *   Client->>Statement: limit(value)
+ *   Client->>Statement: execute()
+ *   Statement->>Statement: build()
+ *   Statement->>Adapter: raw(query)
+ *   Adapter->>Database: execute query
+ *   Database-->>Adapter: return results
+ *   Adapter-->>Statement: return processed results
+ *   Statement-->>Client: return final results
+ */
+export declare abstract class Statement<M extends Model, A extends Adapter<any, any, any, any>, R, Q = A extends Adapter<any, any, infer Q, any> ? Q : never> extends ContextualLoggedClass<ContextOf<A>> implements Executor<R>, RawExecutor<Q>, Paginatable<M, R, Q> {
+    protected adapter: Adapter<any, any, Q, any>;
+    protected overrides?: Partial<AdapterFlags> | undefined;
+    protected readonly selectSelector?: SelectSelector<M>[];
+    protected distinctSelector?: SelectSelector<M>;
+    protected maxSelector?: SelectSelector<M>;
+    protected minSelector?: SelectSelector<M>;
+    protected countSelector?: SelectSelector<M> | null;
+    protected countDistinctSelector?: SelectSelector<M> | null;
+    protected sumSelector?: SelectSelector<M>;
+    protected avgSelector?: SelectSelector<M>;
+    protected _inCountMode: boolean;
+    protected fromSelector: Constructor<M>;
+    protected whereCondition?: Condition<M>;
+    protected orderBySelectors?: OrderBySelector<M>[];
+    protected groupBySelectors?: GroupBySelector<M>[];
+    protected limitSelector?: number;
+    protected offsetSelector?: number;
+    protected prepared?: PreparedStatement<M>;
+    protected constructor(adapter: Adapter<any, any, Q, any>, overrides?: Partial<AdapterFlags> | undefined);
+    protected executionPrefix(method: any, ...args: MaybeContextualArg<ContextOf<A>>): Promise<[Constructor<M>, ...any[], any]>;
+    protected get log(): Logger;
+    select<S extends readonly SelectSelector<M>[]>(): SelectOption<M, M[]>;
+    select<S extends readonly SelectSelector<M>[]>(selector: readonly [...S]): SelectOption<M, Pick<M, S[number]>[]>;
+    distinct<S extends SelectSelector<M>>(selector: S): DistinctOption<M, M[S][]>;
+    distinct(): CountDistinctOption<M>;
+    max<S extends SelectSelector<M>>(selector: S): MaxOption<M, M[S]>;
+    min<S extends SelectSelector<M>>(selector: S): MinOption<M, M[S]>;
+    sum<S extends SelectSelector<M>>(selector: S): SumOption<M, number>;
+    avg<S extends SelectSelector<M>>(selector: S): AvgOption<M, number>;
+    count<S extends SelectSelector<M>>(selector?: S): CountOption<M>;
+    from(selector: FromSelector<M>): WhereOption<M, R>;
+    where(condition: Condition<M>): OrderAndGroupOption<M, R>;
+    orderBy(selector: OrderBySelector<M>): OrderByResult<M, R>;
+    orderBy(attribute: keyof M, direction: OrderDirectionInput): OrderByResult<M, R>;
+    thenBy(selector: GroupBySelector<M>): GroupByResult<M>;
+    thenBy(selector: OrderBySelector<M>): OrderByThenByOption<M, R>;
+    thenBy(attribute: keyof M, direction: OrderDirectionInput): OrderByThenByOption<M, R>;
+    private normalizeOrderCriterion;
+    private normalizeOrderDirection;
+    groupBy<Key extends GroupBySelector<M>>(selector: Key): GroupByResult<M, [Key]>;
+    limit(value: number): OffsetOption<M, R>;
+    offset(value: number): PreparableStatementExecutor<M, R>;
+    execute(...args: MaybeContextualArg<ContextOf<A>>): Promise<R>;
+    protected revertGroupedResults(value: any, processor: (record: any) => any): any;
+    protected executePrepared(...argz: ContextualArgs<ContextOf<A>>): Promise<R>;
+    raw<R>(rawInput: Q, ...args: ContextualArgs<ContextOf<A>>): Promise<R>;
+    protected processRecord(record: any, ctx: ContextOf<A>): M;
+    protected applyAfterHandlersToResult(value: any, ctx: ContextOf<A>): Promise<any>;
+    protected getRepository(): Repository<M, A>;
+    protected prepareCondition(condition: Condition<any>, ctx: ContextOf<A>): PreparedStatement<any>;
+    protected squash(ctx: ContextOf<A>): PreparedStatement<any> | undefined;
+    private matchDefaultQueryCondition;
+    private extractDefaultStartsWithAttributes;
+    private collectStartsWithAttributes;
+    private getOrderDirection;
+    prepare(ctx?: ContextOf<A>): Promise<StatementExecutor<M, R>>;
+    protected isSimpleQuery(): boolean;
+    protected hasAggregation(): boolean;
+    protected abstract build(): Q;
+    protected abstract parseCondition(condition: Condition<M>, ...args: any[]): Q;
+    /**
+     * @description Creates a paginator for the query
+     * @summary Builds the query and wraps it in a RamPaginator to enable pagination of results.
+     * This allows retrieving large result sets in smaller chunks.
+     * @param {number} size - The page size (number of results per page)
+     * @return {Promise<Paginator<M, R, RawRamQuery<M>>>} A promise that resolves to a paginator for the query
+     */
+    paginate(size: number, ...args: MaybeContextualArg<ContextOf<A>>): Promise<Paginator<M, R, Q>>;
+    toString(): string;
+}

package/lib/types/query/constants.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @description Comparison operators for query conditions
+ * @summary Enum defining the available operators for comparing values in database queries
+ * @enum {string}
+ * @readonly
+ * @memberOf module:core
+ */
+export declare enum Operator {
+    /** Equal comparison (=) */
+    EQUAL = "EQUAL",
+    /** Not equal comparison (!=) */
+    DIFFERENT = "DIFFERENT",
+    /** Greater than comparison (>) */
+    BIGGER = "BIGGER",
+    /** Greater than or equal comparison (>=) */
+    BIGGER_EQ = "BIGGER_EQ",
+    /** Less than comparison (<) */
+    SMALLER = "SMALLER",
+    /** Less than or equal comparison (<=) */
+    SMALLER_EQ = "SMALLER_EQ",
+    /** Between comparison (BETWEEN) */
+    BETWEEN = "BETWEEN",
+    /** Negation operator (NOT) */
+    NOT = "NOT",
+    /** Inclusion operator (IN) */
+    IN = "IN",
+    /** Regular expression matching */
+    REGEXP = "REGEXP",
+    /** String starts-with comparison */
+    STARTS_WITH = "STARTS_WITH",
+    /** String ends-with comparison */
+    ENDS_WITH = "ENDS_WITH",
+    GROUP_BY = "group-by",
+    COUNT = "count",
+    SUM = "sum",
+    MAX = "v_max",
+    MIN = "v_min",
+    DISTINCT = "distinct",
+    VIEW = "view"
+}
+/**
+ * @description Logical operators for combining query conditions
+ * @summary Enum defining the available operators for grouping multiple conditions in database queries
+ * @enum {string}
+ * @readonly
+ * @memberOf module:core
+ */
+export declare enum GroupOperator {
+    /** Logical AND operator - all conditions must be true */
+    AND = "AND",
+    /** Logical OR operator - at least one condition must be true */
+    OR = "OR"
+}
+export declare enum PreparedStatementKeys {
+    LIST_BY = "listBy",
+    FIND_BY = "findBy",
+    FIND_BY_PAGINATE = "findByPaginate",
+    FIND_ONE_BY = "findOneBy",
+    PAGE_BY = "paginateBy",
+    FIND = "find",
+    PAGE = "page",
+    COUNT_OF = "countOf",
+    MAX_OF = "maxOf",
+    MIN_OF = "minOf",
+    AVG_OF = "avgOf",
+    SUM_OF = "sumOf",
+    DISTINCT_OF = "distinctOf",
+    GROUP_OF = "groupOf"
+}

package/lib/types/query/decorators.d.ts

@@ -0,0 +1,8 @@
+import { QueryOptions, ViewKind, ViewOptions } from "./types";
+import { PersistenceKeys } from "../persistence/constants";
+import { Operator } from "./constants";
+export declare function defaultQueryAttr(): (obj: object, prop?: any) => void;
+export declare function prepared(): (target: any, propertyKey?: any, descriptor?: TypedPropertyDescriptor<any>) => any;
+export declare function query(options?: QueryOptions): (target: any, propertyKey?: any, descriptor?: TypedPropertyDescriptor<any>) => any;
+export declare function applyViewDecorator(metaKey: PersistenceKeys | Operator, kind: ViewKind, opts?: ViewOptions): (target: any, attr: any) => void;
+export declare function view<OPTS extends ViewOptions>(opts?: OPTS): (target: any, propertyKey?: any, descriptor?: TypedPropertyDescriptor<any>) => any;

package/lib/types/query/errors.d.ts

@@ -0,0 +1,21 @@
+import { InternalError } from "@decaf-ts/db-decorators";
+/**
+ * @description Error thrown during query operations
+ * @summary Represents errors that occur during query building or execution
+ * @param {string | Error} msg - The error message or Error object
+ * @class QueryError
+ * @category Errors
+ */
+export declare class QueryError extends InternalError {
+    constructor(msg: string | Error);
+}
+/**
+ * @description Error thrown during pagination operations
+ * @summary Represents errors that occur during pagination setup or execution
+ * @param {string | Error} msg - The error message or Error object
+ * @class PagingError
+ * @category Errors
+ */
+export declare class PagingError extends InternalError {
+    constructor(msg: string | Error);
+}

package/lib/types/query/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @description Exports for the query module.
+ * @summary This file exports all the necessary components for the query functionality, including Condition, constants, errors, and more.
+ * @module core/query
+ */
+export * from "./Condition";
+export * from "./constants";
+export * from "./errors";
+export * from "./options";
+export * from "./Paginator";
+export * from "./selectors";
+export * from "./Statement";
+export * from "./decorators";
+export * from "./MethodQueryBuilder";
+export * from "./types";
+export * from "./utils";