@decaf-ts/core 0.18.0 → 0.20.0

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

@@ -0,0 +1,136 @@
+import { Model } from "@decaf-ts/decorator-validation";
+import type { Executor, RawExecutor } from "../interfaces/index.cjs";
+import type { FromSelector, GroupBySelector, OrderBySelector, OrderDirectionInput, SelectSelector } from "./selectors.cjs";
+import { Condition } from "./Condition.cjs";
+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.cjs";
+import { Paginatable } from "../interfaces/Paginatable.cjs";
+import { Paginator } from "./Paginator.cjs";
+import { Adapter } from "../persistence/Adapter.cjs";
+import type { AdapterFlags, ContextOf } from "../persistence/types.cjs";
+import { Constructor } from "@decaf-ts/decoration";
+import { type ContextualArgs, ContextualLoggedClass, type MaybeContextualArg } from "../utils/ContextualLoggedClass.cjs";
+import { PreparedStatement } from "./types.cjs";
+import { Repository } from "../repository/Repository.cjs";
+/**
+ * @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/{Statement.d.ts → Statement.d.mts}

@@ -1,17 +1,17 @@
 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 type { Executor, RawExecutor } from "../interfaces/index.js";
+import type { FromSelector, GroupBySelector, OrderBySelector, OrderDirectionInput, SelectSelector } from "./selectors.js";
+import { Condition } from "./Condition.js";
 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 type { CountDistinctOption, CountOption, DistinctOption, GroupByResult, MaxOption, MinOption, OffsetOption, OrderAndGroupOption, OrderByResult, OrderByThenByOption, PreparableStatementExecutor, SelectOption, StatementExecutor, SumOption, AvgOption, WhereOption } from "./options.js";
+import { Paginatable } from "../interfaces/Paginatable.js";
+import { Paginator } from "./Paginator.js";
+import { Adapter } from "../persistence/Adapter.js";
+import type { AdapterFlags, ContextOf } from "../persistence/types.js";
 import { Constructor } from "@decaf-ts/decoration";
-import { type ContextualArgs, ContextualLoggedClass, type MaybeContextualArg } from "../utils/ContextualLoggedClass";
-import { PreparedStatement } from "./types";
-import { Repository } from "../repository/Repository";
+import { type ContextualArgs, ContextualLoggedClass, type MaybeContextualArg } from "../utils/ContextualLoggedClass.js";
+import { PreparedStatement } from "./types.js";
+import { Repository } from "../repository/Repository.js";
 /**
  * @description Base class for database query statements
  * @summary Provides a foundation for building and executing database queries

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

@@ -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.cts

@@ -0,0 +1,8 @@
+import { QueryOptions, ViewKind, ViewOptions } from "./types.cjs";
+import { PersistenceKeys } from "../persistence/constants.cjs";
+import { Operator } from "./constants.cjs";
+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/{decorators.d.ts → decorators.d.mts}

@@ -1,6 +1,6 @@
-import { QueryOptions, ViewKind, ViewOptions } from "./types";
-import { PersistenceKeys } from "../persistence/constants";
-import { Operator } from "./constants";
+import { QueryOptions, ViewKind, ViewOptions } from "./types.js";
+import { PersistenceKeys } from "../persistence/constants.js";
+import { Operator } from "./constants.js";
 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;

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

@@ -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.cts

@@ -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.cjs";
+export * from "./constants.cjs";
+export * from "./errors.cjs";
+export * from "./options.cjs";
+export * from "./Paginator.cjs";
+export * from "./selectors.cjs";
+export * from "./Statement.cjs";
+export * from "./decorators.cjs";
+export * from "./MethodQueryBuilder.cjs";
+export * from "./types.cjs";
+export * from "./utils.cjs";

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

@@ -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.js";
+export * from "./constants.js";
+export * from "./errors.js";
+export * from "./options.js";
+export * from "./Paginator.js";
+export * from "./selectors.js";
+export * from "./Statement.js";
+export * from "./decorators.js";
+export * from "./MethodQueryBuilder.js";
+export * from "./types.js";
+export * from "./utils.js";