@decaf-ts/core 0.19.0 → 0.20.0

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

@@ -1,185 +0,0 @@
-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

@@ -1,105 +0,0 @@
-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

@@ -1,136 +0,0 @@
-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

@@ -1,69 +0,0 @@
-/**
- * @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

@@ -1,8 +0,0 @@
-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

@@ -1,21 +0,0 @@
-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

@@ -1,16 +0,0 @@
-/**
- * @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";