@decaf-ts/core 0.18.0 → 0.19.0

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

@@ -0,0 +1,158 @@
+import { Condition } from "./Condition.js";
+import { OrderBySelector } from "./selectors.js";
+import { Model } from "@decaf-ts/decorator-validation";
+import { Constructor } from "@decaf-ts/decoration";
+import { OrderDirection } from "../repository/constants.js";
+/**
+ * @description
+ * Options for configuring query building behavior.
+ *
+ * @summary
+ * The `QueryOptions` type defines flags that determine whether certain clauses
+ * (limit, offset, order by) are permitted, as well as whether violations
+ * should throw an error during query construction.
+ *
+ * @memberOf module:query
+ */
+export type QueryOptions = {
+    allowLimit?: boolean;
+    allowOffset?: boolean;
+    allowOrderBy?: boolean;
+    throws?: boolean;
+};
+export type OrderLimitOffsetExtract = {
+    orderBy?: OrderBySelector<any>[];
+    limit?: number;
+    offset?: number;
+};
+export type DirectionLimitOffset = {
+    direction?: OrderDirection;
+    order?: OrderBySelector<any>[];
+    limit?: number;
+    offset?: number;
+    bookmark?: string | number;
+};
+export type PreparedStatement<M extends Model> = {
+    class: Constructor<M>;
+    method: string;
+    args: any[];
+    params: DirectionLimitOffset;
+};
+/**
+ * @description
+ * Structured query object representing parsed query clauses.
+ *
+ * @summary
+ * The `QueryAssist` interface defines the standard structure returned
+ * by query builders. It includes actions such as find, optional clauses
+ * like select, groupBy, and orderBy, and pagination controls (limit, offset).
+ *
+ * @template T The entity or record type that conditions may apply to.
+ *
+ * @interface QueryAssist
+ * @memberOf module:query
+ */
+/**
+ * @description
+ * Supported query action types for method-based queries.
+ *
+ * @summary
+ * The `QueryAction` type defines the possible actions that can be
+ * performed by a query built from a method name.
+ *
+ * @memberOf module:query
+ */
+export type QueryAction = "find" | "page" | "count" | "sum" | "avg" | "min" | "max" | "distinct" | "group";
+export interface QueryAssist {
+    action: QueryAction;
+    select: undefined | string[];
+    selector?: string;
+    where?: Condition<any>;
+    groupBy?: string[];
+    orderBy?: OrderBySelector<any>[];
+    limit: number | undefined;
+    offset: number | undefined;
+}
+/**
+ * @description
+ * Enumeration of supported query clauses for building method-based queries.
+ *
+ * @summary
+ * The `QueryClause` enum defines string literals that represent
+ * different segments of a query (e.g., `findBy`, `Select`, `And`, `Or`).
+ *
+ * @enum QueryClause
+ * @memberOf module:query
+ */
+export declare enum QueryClause {
+    FIND_BY = "findBy",
+    PAGE_BY = "pageBy",
+    COUNT_BY = "countBy",
+    SUM_BY = "sumBy",
+    AVG_BY = "avgBy",
+    MIN_BY = "minBy",
+    MAX_BY = "maxBy",
+    DISTINCT_BY = "distinctBy",
+    GROUP_BY_PREFIX = "groupBy",
+    SELECT = "Select",
+    AND = "And",
+    OR = "Or",
+    GROUP_BY = "GroupBy",
+    ORDER_BY = "OrderBy",
+    THEN = "Then",
+    THEN_BY = "ThenBy"
+}
+/**
+ * @description
+ * Function signature for parsing operators in query building.
+ *
+ * @summary
+ * The `OperatorParser` type represents a function that takes a field name
+ * and arguments, then produces a `Condition` object that can be used in a query.
+ *
+ * @template T The type of the condition result.
+ *
+ * @param field {string} - The name of the field being parsed.
+ * @param args {any[]} - Additional arguments for operator evaluation.
+ *
+ * @return {Condition<any>} A condition object representing the parsed operator.
+ *
+ * @memberOf module:query
+ */
+export type OperatorParser = (field: string, ...args: any) => Condition<any>;
+/**
+ * @description
+ * Descriptor for fields and their associated operators in query parsing.
+ *
+ * @summary
+ * The `FilterDescriptor` interface defines the structure used when parsing
+ * method segments into filterable fields and associated operators.
+ *
+ * @interface FilterDescriptor
+ * @memberOf module:query
+ */
+export interface FilterDescriptor {
+    field: string;
+    operator?: string;
+}
+export type ViewKey = string | string[];
+export type ViewKind = "view" | "groupBy" | "count" | "sum" | "max" | "min" | "distinct";
+export interface ViewAuthOptions {
+    expression?: string;
+    field?: string;
+    roles?: string[];
+    mode?: "any" | "all";
+}
+export interface ViewOptions {
+    name?: string;
+    key?: ViewKey;
+    value?: ViewKey | null;
+    condition?: Condition<any> | string;
+    auth?: string | ViewAuthOptions;
+    compositions?: string[];
+    directions?: OrderDirection[];
+}
+export interface ViewMetadata extends ViewOptions {
+    kind: ViewKind;
+    attribute: string;
+}

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

@@ -0,0 +1,40 @@
+import { OperatorParser } from "./types.cjs";
+/**
+ * @description
+ * Map of supported operators to their corresponding parser functions.
+ *
+ * @summary
+ * The `OperatorsMap` defines a collection of operator names as keys
+ * (such as `Equals`, `LessThan`, `Between`, etc.), each mapped to a
+ * function that constructs a `Condition` object for that operator.
+ * These functions translate query clauses into concrete condition
+ * builders, enabling dynamic query construction from method names.
+ *
+ * @template T The type of the field values used in conditions.
+ *
+ * @param f {string} - The field name the condition applies to.
+ * @param v1 {any} - The value to compare the field against or the lower bound value for range-based operators.
+ * @param v2 {any} - The upper bound value for range-based operators.
+ *
+ * @return {Condition<any>} A condition object representing the operator applied to the field.
+ *
+ * @function OperatorsMap
+ *
+ * @mermaid
+ * sequenceDiagram
+ *   participant Client as Caller
+ *   participant Map as OperatorsMap
+ *   participant Parser as OperatorParser
+ *   participant Cond as Condition
+ *
+ *   Client->>Map: Request operator parser ("Between", field, v1, v2)
+ *   Map->>Parser: Call corresponding operator function
+ *   Parser->>Cond: Condition.attribute(field)
+ *   Cond-->>Parser: Condition instance
+ *   Parser->>Cond: Apply gte(v1)
+ *   Parser->>Cond: Apply and(lte(v2))
+ *   Parser-->>Client: Return built Condition
+ *
+ * @memberOf module:query
+ */
+export declare const OperatorsMap: Record<string, OperatorParser>;

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

@@ -0,0 +1,40 @@
+import { OperatorParser } from "./types.js";
+/**
+ * @description
+ * Map of supported operators to their corresponding parser functions.
+ *
+ * @summary
+ * The `OperatorsMap` defines a collection of operator names as keys
+ * (such as `Equals`, `LessThan`, `Between`, etc.), each mapped to a
+ * function that constructs a `Condition` object for that operator.
+ * These functions translate query clauses into concrete condition
+ * builders, enabling dynamic query construction from method names.
+ *
+ * @template T The type of the field values used in conditions.
+ *
+ * @param f {string} - The field name the condition applies to.
+ * @param v1 {any} - The value to compare the field against or the lower bound value for range-based operators.
+ * @param v2 {any} - The upper bound value for range-based operators.
+ *
+ * @return {Condition<any>} A condition object representing the operator applied to the field.
+ *
+ * @function OperatorsMap
+ *
+ * @mermaid
+ * sequenceDiagram
+ *   participant Client as Caller
+ *   participant Map as OperatorsMap
+ *   participant Parser as OperatorParser
+ *   participant Cond as Condition
+ *
+ *   Client->>Map: Request operator parser ("Between", field, v1, v2)
+ *   Map->>Parser: Call corresponding operator function
+ *   Parser->>Cond: Condition.attribute(field)
+ *   Cond-->>Parser: Condition instance
+ *   Parser->>Cond: Apply gte(v1)
+ *   Parser->>Cond: Apply and(lte(v2))
+ *   Parser-->>Client: Return built Condition
+ *
+ * @memberOf module:query
+ */
+export declare const OperatorsMap: Record<string, OperatorParser>;

package/lib/types/ram/RamAdapter.d.cts

@@ -0,0 +1,341 @@
+import { RamConfig, RamContext, RamFlags, RamStorage, RawRamQuery } from "./types.cjs";
+import { RamStatement } from "./RamStatement.cjs";
+import { Repository } from "../repository/Repository.cjs";
+import { Dispatch } from "../persistence/Dispatch.cjs";
+import { Adapter, AdapterFlags, RawResult } from "../persistence/index.cjs";
+import { Model } from "@decaf-ts/decorator-validation";
+import { BaseError, OperationKeys, PrimaryKeyType } from "@decaf-ts/db-decorators";
+import type { Constructor } from "@decaf-ts/decoration";
+import { RamPaginator } from "./RamPaginator.cjs";
+import { ContextualArgs } from "../utils/ContextualLoggedClass.cjs";
+/**
+ * @description In-memory adapter for data persistence
+ * @summary The RamAdapter provides an in-memory implementation of the persistence layer.
+ * It stores data in JavaScript Maps and provides CRUD operations and query capabilities.
+ * This adapter is useful for testing, prototyping, and applications that don't require
+ * persistent storage across application restarts.
+ * @class RamAdapter
+ * @category Ram
+ * @example
+ * ```typescript
+ * // Create a new RAM adapter
+ * const adapter = new RamAdapter('myRamAdapter');
+ *
+ * // Create a repository for a model
+ * const userRepo = new (adapter.repository<User>())(User, adapter);
+ *
+ * // Perform CRUD operations
+ * const user = new User({ name: 'John', email: 'john@example.com' });
+ * await userRepo.create(user);
+ * const retrievedUser = await userRepo.findById(user.id);
+ * ```
+ * @mermaid
+ * sequenceDiagram
+ *   participant Client
+ *   participant Repository
+ *   participant RamAdapter
+ *   participant Storage as In-Memory Storage
+ *
+ *   Client->>Repository: create(model)
+ *   Repository->>RamAdapter: create(tableName, id, model)
+ *   RamAdapter->>RamAdapter: lock.acquire()
+ *   RamAdapter->>Storage: set(id, model)
+ *   RamAdapter->>RamAdapter: lock.release()
+ *   RamAdapter-->>Repository: model
+ *   Repository-->>Client: model
+ *
+ *   Client->>Repository: findById(id)
+ *   Repository->>RamAdapter: read(tableName, id)
+ *   RamAdapter->>Storage: get(id)
+ *   Storage-->>RamAdapter: model
+ *   RamAdapter-->>Repository: model
+ *   Repository-->>Client: model
+ */
+export declare class RamAdapter extends Adapter<RamConfig, RamStorage, RawRamQuery, RamContext> {
+    constructor(conf?: RamConfig, alias?: string);
+    /**
+     * @description Gets the repository constructor for a model
+     * @summary Returns a constructor for creating repositories that work with the specified model type.
+     * This method overrides the base implementation to provide RAM-specific repository functionality.
+     * @template M - The model type for the repository
+     * @return {Constructor<RamRepository<M>>} A constructor for creating RAM repositories
+     */
+    repository<R extends Repository<any, Adapter<any, any, any, any>>>(): Constructor<R>;
+    /**
+     * @description Creates operation flags with UUID
+     * @summary Extends the base flags with a UUID for user identification.
+     * This method ensures that all operations have a unique identifier for tracking purposes.
+     * @template M - The model type for the operation
+     * @param {OperationKeys} operation - The type of operation being performed
+     * @param {Constructor<M>} model - The model constructor
+     * @param {Partial<RamFlags>} flags - Partial flags to be extended
+     * @return {Promise<RamFlags>} Complete flags with UUID
+     */
+    flags<M extends Model<boolean>>(operation: OperationKeys, model: Constructor<M>, flags: Partial<RamFlags>): Promise<RamFlags>;
+    protected Dispatch(): Dispatch<RamAdapter>;
+    private indexes;
+    private lock;
+    /**
+     * @description Indexes models in the RAM adapter
+     * @summary A no-op indexing method for the RAM adapter.
+     * Since RAM adapter doesn't require explicit indexing, this method simply resolves immediately.
+     * @param models - Models to be indexed (unused)
+     * @return {Promise<any>} A promise that resolves when indexing is complete
+     */
+    index(...models: Record<string, any>[]): Promise<any>;
+    /**
+     * @description Prepares a model for storage
+     * @summary Converts a model instance to a format suitable for storage in the RAM adapter.
+     * This method extracts the primary key and creates a record without the primary key field.
+     * @template M - The model type being prepared
+     * @param {M} model - The model instance to prepare
+     * @param pk - The primary key property name
+     * @return Object containing the record and ID
+     */
+    prepare<M extends Model>(model: M, ...args: [...any[], RamContext]): {
+        record: Record<string, any>;
+        id: string;
+        transient?: Record<string, any>;
+    };
+    /**
+     * @description Converts a stored record back to a model instance
+     * @summary Reconstructs a model instance from a stored record by adding back the primary key.
+     * This method is the inverse of the prepare method.
+     * @template M - The model type to revert to
+     * @param {Record<string, any>} obj - The stored record
+     * @param {Constructor<M>} clazz - The model class or name
+     * @param {PrimaryKeyType} id - The primary key value
+     * @return {M} The reconstructed model instance
+     */
+    revert<M extends Model>(obj: Record<string, any>, clazz: Constructor<M>, id: PrimaryKeyType, transient?: Record<string, any>, ...args: [...any[], RamContext]): M;
+    /**
+     * @description Creates a new record in the in-memory storage
+     * @summary Stores a new record in the specified table with the given ID.
+     * This method acquires a lock to ensure thread safety, creates the table if it doesn't exist,
+     * checks for conflicts, and stores the model.
+     * @param {string} clazz - The name of the table to store the record in
+     * @param {string | number} id - The unique identifier for the record
+     * @param {Record<string, any>} model - The record data to store
+     * @return {Promise<Record<string, any>>} A promise that resolves to the stored record
+     * @mermaid
+     * sequenceDiagram
+     *   participant Caller
+     *   participant RamAdapter
+     *   participant Storage as In-Memory Storage
+     *
+     *   Caller->>RamAdapter: create(tableName, id, model)
+     *   RamAdapter->>RamAdapter: lock.acquire()
+     *   RamAdapter->>Storage: has(tableName)
+     *   alt Table doesn't exist
+     *     RamAdapter->>Storage: set(tableName, new Map())
+     *   end
+     *   RamAdapter->>Storage: has(id)
+     *   alt Record exists
+     *     RamAdapter-->>Caller: throw ConflictError
+     *   end
+     *   RamAdapter->>Storage: set(id, model)
+     *   RamAdapter->>RamAdapter: lock.release()
+     *   RamAdapter-->>Caller: model
+     */
+    create<M extends Model>(clazz: Constructor<M>, id: PrimaryKeyType, model: Record<string, any>, ...args: ContextualArgs<RamContext>): Promise<Record<string, any>>;
+    /**
+     * @description Retrieves a record from in-memory storage
+     * @summary Fetches a record with the specified ID from the given table.
+     * This method checks if the table and record exist and throws appropriate errors if not.
+     * @param {Constructor} clazz - The name of the table to retrieve from
+     * @param {PrimaryKeyType} id - The unique identifier of the record to retrieve
+     * @return {Promise<Record<string, any>>} A promise that resolves to the retrieved record
+     * @mermaid
+     * sequenceDiagram
+     *   participant Caller
+     *   participant RamAdapter
+     *   participant Storage as In-Memory Storage
+     *
+     *   Caller->>RamAdapter: read(tableName, id)
+     *   RamAdapter->>Storage: has(tableName)
+     *   alt Table doesn't exist
+     *     RamAdapter-->>Caller: throw NotFoundError
+     *   end
+     *   RamAdapter->>Storage: has(id)
+     *   alt Record doesn't exist
+     *     RamAdapter-->>Caller: throw NotFoundError
+     *   end
+     *   RamAdapter->>Storage: get(id)
+     *   Storage-->>RamAdapter: record
+     *   RamAdapter-->>Caller: record
+     */
+    read<M extends Model>(clazz: Constructor<M>, id: PrimaryKeyType, ...args: ContextualArgs<RamContext>): Promise<Record<string, any>>;
+    /**
+     * @description Updates an existing record in the in-memory storage
+     * @summary Updates a record with the specified ID in the given table.
+     * This method acquires a lock to ensure thread safety, checks if the table and record exist,
+     * and updates the record with the new data.
+     * @param {string} tableName - The name of the table containing the record
+     * @param {string | number} id - The unique identifier of the record to update
+     * @param {Record<string, any>} model - The new record data
+     * @return {Promise<Record<string, any>>} A promise that resolves to the updated record
+     * @mermaid
+     * sequenceDiagram
+     *   participant Caller
+     *   participant RamAdapter
+     *   participant Storage as In-Memory Storage
+     *
+     *   Caller->>RamAdapter: update(tableName, id, model)
+     *   RamAdapter->>RamAdapter: lock.acquire()
+     *   RamAdapter->>Storage: has(tableName)
+     *   alt Table doesn't exist
+     *     RamAdapter-->>Caller: throw NotFoundError
+     *   end
+     *   RamAdapter->>Storage: has(id)
+     *   alt Record doesn't exist
+     *     RamAdapter-->>Caller: throw NotFoundError
+     *   end
+     *   RamAdapter->>Storage: set(id, model)
+     *   RamAdapter->>RamAdapter: lock.release()
+     *   RamAdapter-->>Caller: model
+     */
+    update<M extends Model>(clazz: Constructor<M>, id: PrimaryKeyType, model: Record<string, any>, ...args: ContextualArgs<RamContext>): Promise<Record<string, any>>;
+    /**
+     * @description Deletes a record from the in-memory storage
+     * @summary Removes a record with the specified ID from the given table.
+     * This method acquires a lock to ensure thread safety, checks if the table and record exist,
+     * retrieves the record before deletion, and then removes it from storage.
+     * @param {string} tableName - The name of the table containing the record
+     * @param {string | number} id - The unique identifier of the record to delete
+     * @return {Promise<Record<string, any>>} A promise that resolves to the deleted record
+     * @mermaid
+     * sequenceDiagram
+     *   participant Caller
+     *   participant RamAdapter
+     *   participant Storage as In-Memory Storage
+     *
+     *   Caller->>RamAdapter: delete(tableName, id)
+     *   RamAdapter->>RamAdapter: lock.acquire()
+     *   RamAdapter->>Storage: has(tableName)
+     *   alt Table doesn't exist
+     *     RamAdapter-->>Caller: throw NotFoundError
+     *   end
+     *   RamAdapter->>Storage: has(id)
+     *   alt Record doesn't exist
+     *     RamAdapter-->>Caller: throw NotFoundError
+     *   end
+     *   RamAdapter->>Storage: get(id)
+     *   Storage-->>RamAdapter: record
+     *   RamAdapter->>Storage: delete(id)
+     *   RamAdapter->>RamAdapter: lock.release()
+     *   RamAdapter-->>Caller: record
+     */
+    delete<M extends Model>(clazz: Constructor<M>, id: PrimaryKeyType, ...args: ContextualArgs<RamContext>): Promise<Record<string, any>>;
+    /**
+     * @description Gets or creates a table in the in-memory storage
+     * @summary Retrieves the Map representing a table for a given model class.
+     * If the table doesn't exist, it creates a new one so callers can insert or
+     * query entities without null reference checks.
+     * @template M - The model type for the table
+     * @param {Constructor<M>} from - The model class
+     * @return {Map<string | number, any> | undefined} The table Map or undefined
+     */
+    protected tableFor<M extends Model>(from: Constructor<M>): Map<PrimaryKeyType, any> | undefined;
+    /**
+     * @description Executes a raw query against the in-memory storage
+     * @summary Performs a query operation on the in-memory data store using the provided query specification.
+     * This method supports filtering, sorting, pagination, and field selection.
+     * @template R - The return type of the query
+     * @param {RawRamQuery<any>} rawInput - The query specification
+     * @return {Promise<R>} A promise that resolves to the query results
+     * @mermaid
+     * sequenceDiagram
+     *   participant Caller
+     *   participant RamAdapter
+     *   participant Storage as In-Memory Storage
+     *
+     *   Caller->>RamAdapter: raw(rawInput)
+     *   RamAdapter->>RamAdapter: tableFor(from)
+     *   alt Table doesn't exist
+     *     RamAdapter-->>Caller: throw InternalError
+     *   end
+     *   RamAdapter->>RamAdapter: findPrimaryKey(new from())
+     *   RamAdapter->>Storage: entries()
+     *   Storage-->>RamAdapter: entries
+     *   loop For each entry
+     *     RamAdapter->>RamAdapter: revert(r, from, id, pk)
+     *   end
+     *   alt Where condition exists
+     *     RamAdapter->>RamAdapter: result.filter(where)
+     *   end
+     *   alt Sort condition exists
+     *     RamAdapter->>RamAdapter: result.sort(sort)
+     *   end
+     *   alt Skip specified
+     *     RamAdapter->>RamAdapter: result.slice(skip)
+     *   end
+     *   alt Limit specified
+     *     RamAdapter->>RamAdapter: result.slice(0, limit)
+     *   end
+     *   alt Select fields specified
+     *     loop For each result
+     *       RamAdapter->>RamAdapter: Filter to selected fields
+     *     end
+     *   end
+     *   RamAdapter-->>Caller: result
+     */
+    raw<R, D extends boolean>(rawInput: RawRamQuery<any>, docsOnly?: D, ...args: ContextualArgs<RamContext>): Promise<RawResult<R, D>>;
+    private groupRecords;
+    private normalizeGroupKey;
+    private applyGroupPagination;
+    /**
+     * @description Parses and converts errors to appropriate types
+     * @summary Ensures that errors are of the correct type for consistent error handling.
+     * If the error is already a BaseError, it's returned as is; otherwise, it's wrapped in an InternalError.
+     * @template V - The expected error type, extending BaseError
+     * @param {Error} err - The error to parse
+     * @return {V} The parsed error of the expected type
+     */
+    parseError<V extends BaseError>(err: Error): V;
+    /**
+     * @description Creates a new statement builder for queries
+     * @summary Factory method that creates a new RamStatement instance for building queries.
+     * This method allows for fluent query construction against the RAM adapter.
+     * @template M - The model type for the statement
+     * @return {RamStatement<M, any>} A new statement builder instance
+     */
+    Statement<M extends Model<boolean>>(overrides?: Partial<AdapterFlags>): RamStatement<M, any, Adapter<any, any, RawRamQuery<M>, RamContext>>;
+    Paginator<M extends Model<boolean>>(query: RawRamQuery, size: number, clazz: Constructor<M>): RamPaginator<M>;
+    for(config: Partial<RamConfig>, ...args: any[]): typeof this;
+    /**
+     * @description Sets up RAM-specific decorations for model properties
+     * @summary Configures decorations for createdBy and updatedBy fields in the RAM adapter.
+     * This static method is called during initialization to set up handlers that automatically
+     * populate these fields with the current user's UUID during create and update operations.
+     * @return {void}
+     * @mermaid
+     * sequenceDiagram
+     *   participant RamAdapter
+     *   participant Decoration
+     *   participant Repository
+     *
+     *   RamAdapter->>Repository: key(PersistenceKeys.CREATED_BY)
+     *   Repository-->>RamAdapter: createdByKey
+     *   RamAdapter->>Repository: key(PersistenceKeys.UPDATED_BY)
+     *   Repository-->>RamAdapter: updatedByKey
+     *
+     *   RamAdapter->>Decoration: flavouredAs(RamFlavour)
+     *   Decoration-->>RamAdapter: DecoratorBuilder
+     *   RamAdapter->>Decoration: for(createdByKey)
+     *   RamAdapter->>Decoration: define(onCreate, propMetadata)
+     *   RamAdapter->>Decoration: apply()
+     *
+     *   RamAdapter->>Decoration: flavouredAs(RamFlavour)
+     *   Decoration-->>RamAdapter: DecoratorBuilder
+     *   RamAdapter->>Decoration: for(updatedByKey)
+     *   RamAdapter->>Decoration: define(onCreate, propMetadata)
+     *   RamAdapter->>Decoration: apply()
+     */
+    static decoration(): void;
+    private ensureFieldType;
+    private resolveFieldType;
+    private normalizeMetaType;
+    private isNumericType;
+    private toNumericValue;
+    protected getClient(): RamStorage;
+}