@decaf-ts/core 0.18.0 → 0.20.0

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

@@ -0,0 +1,50 @@
+import { Model } from "@decaf-ts/decorator-validation";
+import { Repository } from "../repository/index.cjs";
+import { Constructor } from "@decaf-ts/decoration";
+import { Adapter, AdapterFlags } from "../persistence/index.cjs";
+import { Context } from "../persistence/Context.cjs";
+import { MultiLock } from "@decaf-ts/transactional-decorators";
+import { PrimaryKeyType } from "@decaf-ts/db-decorators";
+/**
+ * @description In-memory storage structure for the RAM adapter
+ * @summary A nested Map structure that stores all entities by their table name and primary key.
+ * The outer Map uses table names as keys, while the inner Map uses entity IDs as keys and entity instances as values.
+ * @typedef {Map<string, Map<string | number, any>>} RamStorage
+ * @memberOf module:core
+ * @category Ram
+ */
+export type RamStorage = Map<string, Map<PrimaryKeyType, any>>;
+export type RawRamQuery<M extends Model = any> = {
+    select: undefined | (keyof M)[];
+    from: Constructor<M>;
+    where: (el: M) => boolean;
+    sort?: (el: M, el2: M) => number;
+    groupBy?: (keyof M)[];
+    limit?: number;
+    skip?: number;
+    count?: keyof M | null;
+    countDistinct?: keyof M;
+    min?: keyof M;
+    max?: keyof M;
+    sum?: keyof M;
+    avg?: keyof M;
+    distinct?: keyof M;
+};
+/**
+ * @description Flags for RAM adapter operations
+ * @summary Interface that extends the base repository flags with RAM-specific flags.
+ * Contains user identification information needed for tracking entity creation and updates.
+ * @interface RamFlags
+ * @property {string} UUID - Unique identifier for the current user
+ * @memberOf module:core
+ * @category Ram
+ */
+export interface RamFlags extends AdapterFlags {
+    UUID: string;
+}
+export type RamRepository<M extends Model<boolean>> = Repository<M, Adapter<RamConfig, RamStorage, RawRamQuery<any>, RamContext>>;
+export type RamContext = Context<RamFlags>;
+export type RamConfig = {
+    user: string;
+    lock?: MultiLock;
+};

package/lib/types/ram/{types.d.ts → types.d.mts}

@@ -1,8 +1,8 @@
 import { Model } from "@decaf-ts/decorator-validation";
-import { Repository } from "../repository";
+import { Repository } from "../repository/index.js";
 import { Constructor } from "@decaf-ts/decoration";
-import { Adapter, AdapterFlags } from "../persistence";
-import { Context } from "../persistence/Context";
+import { Adapter, AdapterFlags } from "../persistence/index.js";
+import { Context } from "../persistence/Context.js";
 import { MultiLock } from "@decaf-ts/transactional-decorators";
 import { PrimaryKeyType } from "@decaf-ts/db-decorators";
 /**

package/lib/types/repository/Repository.d.cts

@@ -0,0 +1,501 @@
+import { IRepository, Repository as Rep, PrimaryKeyType } from "@decaf-ts/db-decorators";
+import { Logger } from "@decaf-ts/logging";
+import { ContextualArgs, ContextualizedArgs, MaybeContextualArg, MethodOrOperation } from "../utils/ContextualLoggedClass.cjs";
+import { Adapter } from "../persistence/Adapter.cjs";
+import { ObserverHandler } from "../persistence/ObserverHandler.cjs";
+import type { DirectionLimitOffset, QueryOptions } from "../query/types.cjs";
+import { SelectSelector } from "../query/selectors.cjs";
+import { CountWhereOption, WhereOption } from "../query/options.cjs";
+import { Condition } from "../query/Condition.cjs";
+import { Queriable } from "../interfaces/Queriable.cjs";
+import { SequenceOptions } from "../interfaces/SequenceOptions.cjs";
+import { OrderDirection } from "./constants.cjs";
+import type { AllOperationKeys, ContextOf, EventIds, FlagsOf, InferredAdapterConfig, ObserverFilter, PersistenceObservable, PersistenceObserver } from "../persistence/types.cjs";
+import type { Observer } from "../interfaces/Observer.cjs";
+import { Constructor } from "@decaf-ts/decoration";
+import { Model } from "@decaf-ts/decorator-validation";
+import { SerializedPage } from "../query/Paginator.cjs";
+/**
+ * @description Type alias for Repository class with simplified generic parameters.
+ * @summary Provides a more concise way to reference the Repository class with its generic parameters.
+ * @template M - The model type that extends Model.
+ * @template F - The repository flags type.
+ * @template C - The context type.
+ * @template Q - The query type.
+ * @template A - The adapter type.
+ * @typedef Repo
+ * @memberOf module:core
+ */
+export type Repo<M extends Model<boolean>> = Repository<M, any>;
+/**
+ * @description Core repository implementation for database operations on models on a table by table way.
+ * @summary Provides CRUD operations, querying capabilities, and observer pattern implementation for model persistence.
+ * @template M - The model type that extends Model.
+ * @template Q - The query type used by the adapter.
+ * @template A - The adapter type for database operations.
+ * @template F - The repository flags type.
+ * @template C - The context type for operations.
+ * @param {A} [adapter] - Optional adapter instance for database operations.
+ * @param {Constructor<M>} [clazz] - Optional constructor for the model class.
+ * @param {...any[]} [args] - Additional arguments for repository initialization.
+ * @class Repository
+ * @example
+ * // Creating a repository for User model
+ * const userRepo = Repository.forModel(User);
+ *
+ * // Using the repository for CRUD operations
+ * const user = await userRepo.create(new User({ name: 'John' }));
+ * const retrievedUser = await userRepo.read(user.id);
+ * user.name = 'Jane';
+ * await userRepo.update(user);
+ * await userRepo.delete(user.id);
+ *
+ * // Querying with conditions
+ * const users = await userRepo
+ *   .select()
+ *   .where({ name: 'Jane' })
+ *   .orderBy('createdAt', OrderDirection.DSC)
+ *   .limit(10)
+ *   .execute();
+ * @mermaid
+ * sequenceDiagram
+ *   participant C as Client Code
+ *   participant R as Repository
+ *   participant A as Adapter
+ *   participant DB as Database
+ *   participant O as Observers
+ *
+ *   C->>+R: create(model)
+ *   R->>R: createPrefix(model)
+ *   R->>+A: prepare(model)
+ *   A-->>-R: prepared data
+ *   R->>+A: create(table, id, record)
+ *   A->>+DB: Insert Operation
+ *   DB-->>-A: Result
+ *   A-->>-R: record
+ *   R->>+A: revert(record)
+ *   A-->>-R: model instance
+ *   R->>R: createSuffix(model)
+ *   R->>+O: updateObservers(table, CREATE, id)
+ *   O-->>-R: Notification complete
+ *   R-->>-C: created model
+ */
+export declare class Repository<M extends Model<boolean>, A extends Adapter<any, any, any, any>> extends Rep<M, ContextOf<A>> implements PersistenceObservable<ContextOf<A>>, PersistenceObserver<ContextOf<A>>, Queriable<M>, IRepository<M, ContextOf<A>> {
+    private static _cache;
+    protected observers: Observer[];
+    protected observerHandler?: ObserverHandler;
+    private readonly _adapter;
+    private _tableName;
+    protected _overrides: Partial<FlagsOf<ContextOf<A>>>;
+    private logger;
+    /**
+     * @description Logger instance for this repository.
+     * @summary Provides access to the logger for this repository instance.
+     * @return {Logger} The logger instance.
+     */
+    get log(): Logger;
+    /**
+     * @description Adapter for database operations.
+     * @summary Provides access to the adapter instance for this repository.
+     * @template A - The adapter type.
+     * @return {A} The adapter instance.
+     * @throws {InternalError} If no adapter is found.
+     */
+    protected get adapter(): A;
+    /**
+     * @description Table name for this repository's model.
+     * @summary Gets the database table name associated with this repository's model.
+     * @return {string} The table name.
+     */
+    protected get tableName(): string;
+    /**
+     * @description Primary key properties for this repository's model.
+     * @summary Gets the sequence options containing primary key information.
+     * @return {SequenceOptions} The primary key properties.
+     * @deprecated for Model.sequenceFor(class)
+     */
+    protected get pkProps(): SequenceOptions;
+    get filters(): Record<"onlyOnCreate" | "onlyOnUpdate" | "onlyOnDelete" | "onlyOnTransactional" | "onlyOnSingle" | "onlyOnBulk", ObserverFilter>;
+    constructor(adapter?: A, clazz?: Constructor<M>, force?: boolean, ...args: any[]);
+    protected logCtx<ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<ContextOf<A>, ARGS>, operation: METHOD): ContextualizedArgs<ContextOf<A>, ARGS, METHOD extends string ? true : false>;
+    protected logCtx<ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<ContextOf<A>, ARGS>, operation: METHOD, allowCreate: false): ContextualizedArgs<ContextOf<A>, ARGS, METHOD extends string ? true : false>;
+    protected logCtx<ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<ContextOf<A>, ARGS>, operation: METHOD, allowCreate: true): Promise<ContextualizedArgs<ContextOf<A>, ARGS, METHOD extends string ? true : false>>;
+    protected logCtx<ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<ContextOf<A>, ARGS>, operation: METHOD, allowCreate: true, overrides?: Partial<FlagsOf<ContextOf<A>>>): Promise<ContextualizedArgs<ContextOf<A>, ARGS, METHOD extends string ? true : false>>;
+    protected logCtx<ARGS extends any[] = any[], METHOD extends MethodOrOperation = MethodOrOperation>(args: MaybeContextualArg<ContextOf<A>, ARGS>, operation: METHOD, allowCreate: false, overrides?: Partial<FlagsOf<ContextOf<A>>>): ContextualizedArgs<ContextOf<A>, ARGS, METHOD extends string ? true : false>;
+    /**
+     * @description Creates a proxy with overridden repository flags.
+     * @summary Returns a proxy of this repository with the specified flags overridden.
+     * @param {Partial<F>} flags - The flags to override.
+     * @return {Repository} A proxy of this repository with overridden flags.
+     */
+    override(flags: Partial<FlagsOf<ContextOf<A>>>): this;
+    /**
+     * @description Creates a new instance of the Repository class with a specific adapter and arguments.
+     *
+     * @template A - The type of the adapter.
+     * @template Q - The type of the query builder.
+     * @template F - The type of the filter.
+     * @template C - The type of the context.
+     *
+     * @param {Partial<InferredAdapterConfig<A>>} conf - adapter configurations to override.
+     * @param [args] - Additional arguments to be passed to the new instance.
+     *
+     * @return A new instance of the Repository class with the specified adapter and arguments.
+     */
+    for(conf: Partial<InferredAdapterConfig<A>>, ...args: any[]): this;
+    /**
+     * @description Creates a new observer handler.
+     * @summary Factory method for creating an observer handler instance.
+     * @return {ObserverHandler} A new observer handler instance.
+     */
+    protected ObserverHandler(): ObserverHandler;
+    /**
+     * @description Prepares a model for creation.
+     * @summary Validates the model and prepares it for creation in the database.
+     * @template M - The model type.
+     * @param {M} model - The model to create.
+     * @param {...any[]} args - Additional arguments.
+     * @return The prepared model and context arguments.
+     * @throws {ValidationError} If the model fails validation.
+     */
+    protected createPrefix(model: M, ...args: MaybeContextualArg<ContextOf<A>>): Promise<[M, ...any[], ContextOf<A>]>;
+    /**
+     * @description Creates a model in the database.
+     * @summary Persists a model instance to the database.
+     * @param {M} model - The model to create.
+     * @param {...any[]} args - Additional arguments.
+     * @return {Promise<M>} The created model with updated properties.
+     */
+    create(model: M, ...args: MaybeContextualArg<ContextOf<A>>): Promise<M>;
+    /**
+     * @description Creates multiple models in the database.
+     * @summary Persists multiple model instances to the database in a batch operation.
+     * @param {M[]} models - The models to create.
+     * @param {...any[]} args - Additional arguments.
+     * @return {Promise<M[]>} The created models with updated properties.
+     */
+    createAll(models: M[], ...args: MaybeContextualArg<ContextOf<A>>): Promise<M[]>;
+    /**
+     * @description Prepares multiple models for creation.
+     * @summary Validates multiple models and prepares them for creation in the database.
+     * @param {M[]} models - The models to create.
+     * @param {...any[]} args - Additional arguments.
+     * @return The prepared models and context arguments.
+     * @throws {ValidationError} If any model fails validation.
+     */
+    protected createAllPrefix(models: M[], ...args: MaybeContextualArg<ContextOf<A>>): Promise<[M[], ...any[], ContextOf<A>]>;
+    /**
+     * @description Prepares for reading a model by ID.
+     * @summary Prepares the context and enforces decorators before reading a model.
+     * @param {string} key - The primary key of the model to read.
+     * @param {...any[]} args - Additional arguments.
+     * @return The key and context arguments.
+     */
+    protected readPrefix(key: PrimaryKeyType, ...args: MaybeContextualArg<ContextOf<A>>): Promise<[PrimaryKeyType, ...any[], ContextOf<A>]>;
+    /**
+     * @description Reads a model from the database by ID.
+     * @summary Retrieves a model instance from the database using its primary key.
+     * @param {PrimaryKeyType} id - The primary key of the model to read.
+     * @param {...any[]} args - Additional arguments.
+     * @return {Promise<M>} The retrieved model instance.
+     */
+    read(id: PrimaryKeyType, ...args: MaybeContextualArg<ContextOf<A>>): Promise<M>;
+    /**
+     * @description Prepares for reading multiple models by IDs.
+     * @summary Prepares the context and enforces decorators before reading multiple models.
+     * @param {string[]|number[]} keys - The primary keys of the models to read.
+     * @param {...any[]} args - Additional arguments.
+     * @return The keys and context arguments.
+     */
+    protected readAllPrefix(keys: PrimaryKeyType[], ...args: MaybeContextualArg<ContextOf<A>>): Promise<[PrimaryKeyType[], ...any[], ContextOf<A>]>;
+    /**
+     * @description Reads multiple models from the database by IDs.
+     * @summary Retrieves multiple model instances from the database using their primary keys.
+     * @param {string[]|number[]} keys - The primary keys of the models to read.
+     * @param {...any[]} args - Additional arguments.
+     * @return {Promise<M[]>} The retrieved model instances.
+     */
+    readAll(keys: PrimaryKeyType[], ...args: MaybeContextualArg<ContextOf<A>>): Promise<M[]>;
+    /**
+     * @description Updates a model in the database.
+     * @summary Persists changes to an existing model instance in the database.
+     * @param {M} model - The model to update.
+     * @param {...any[]} args - Additional arguments.
+     * @return {Promise<M>} The updated model with refreshed properties.
+     */
+    update(model: M, ...args: MaybeContextualArg<ContextOf<A>>): Promise<M>;
+    /**
+     * @description Prepares a model for update.
+     * @summary Validates the model and prepares it for update in the database.
+     * @param {M} model - The model to update.
+     * @param {...any[]} args - Additional arguments.
+     * @return The prepared model and context arguments.
+     * @throws {InternalError} If the model has no primary key value.
+     * @throws {ValidationError} If the model fails validation.
+     */
+    protected updatePrefix(model: M, ...args: MaybeContextualArg<ContextOf<A>>): Promise<[M, ...args: any[], ContextOf<A>, M | undefined]>;
+    /**
+     * @description Updates multiple models in the database.
+     * @summary Persists changes to multiple existing model instances in the database in a batch operation.
+     * @param {M[]} models - The models to update.
+     * @param {...any[]} args - Additional arguments.
+     * @return {Promise<M[]>} The updated models with refreshed properties.
+     */
+    updateAll(models: M[], ...args: MaybeContextualArg<ContextOf<A>>): Promise<M[]>;
+    /**
+     * @description Prepares multiple models for update.
+     * @summary Validates multiple models and prepares them for update in the database.
+     * @param {M[]} models - The models to update.
+     * @param {...any[]} args - Additional arguments.
+     * @return {Promise<any[]>} The prepared models and context arguments.
+     * @throws {InternalError} If any model has no primary key value.
+     * @throws {ValidationError} If any model fails validation.
+     */
+    protected updateAllPrefix(models: M[], ...args: MaybeContextualArg<ContextOf<A>>): Promise<[M[], ...args: any[], ContextOf<A>, M[] | undefined]>;
+    /**
+     * @description Prepares for deleting a model by ID.
+     * @summary Prepares the context and enforces decorators before deleting a model.
+     * @param {any} key - The primary key of the model to delete.
+     * @param {...any[]} args - Additional arguments.
+     * @return The key and context arguments.
+     */
+    protected deletePrefix(key: PrimaryKeyType, ...args: MaybeContextualArg<ContextOf<A>>): Promise<[PrimaryKeyType, ...any[], ContextOf<A>]>;
+    /**
+     * @description Deletes a model from the database by ID.
+     * @summary Removes a model instance from the database using its primary key.
+     * @param {string|number|bigint} id - The primary key of the model to delete.
+     * @param {...any[]} args - Additional arguments.
+     * @return {Promise<M>} The deleted model instance.
+     */
+    delete(id: PrimaryKeyType, ...args: MaybeContextualArg<ContextOf<A>>): Promise<M>;
+    /**
+     * @description Prepares for deleting multiple models by IDs.
+     * @summary Prepares the context and enforces decorators before deleting multiple models.
+     * @param {string[]|number[]} keys - The primary keys of the models to delete.
+     * @param {...any[]} args - Additional arguments.
+     * @return The keys and context arguments.
+     */
+    protected deleteAllPrefix(keys: PrimaryKeyType[], ...args: MaybeContextualArg<ContextOf<A>>): Promise<[PrimaryKeyType[], ...any[], ContextOf<A>]>;
+    /**
+     * @description Deletes multiple models from the database by IDs.
+     * @summary Removes multiple model instances from the database using their primary keys.
+     * @param {string[]|number[]} keys - The primary keys of the models to delete.
+     * @param {...any[]} args - Additional arguments.
+     * @return {Promise<M[]>} The deleted model instances.
+     */
+    deleteAll(keys: PrimaryKeyType[], ...args: MaybeContextualArg<ContextOf<A>>): Promise<M[]>;
+    /**
+     * @description Creates a select query without specifying fields.
+     * @summary Starts building a query that will return all fields of the model.
+     * @template S - The array type of select selectors.
+     * @return A query builder for the model.
+     */
+    select<S extends readonly SelectSelector<M>[]>(): WhereOption<M, M[]>;
+    /**
+     * @description Creates a select query with specific fields.
+     * @summary Starts building a query that will return only the specified fields of the model.
+     * @template S - The array type of select selectors.
+     * @param selector - The fields to select.
+     * @return A query builder for the selected fields.
+     */
+    select<S extends readonly SelectSelector<M>[]>(selector: readonly [...S]): WhereOption<M, Pick<M, S[number]>[]>;
+    /**
+     * @description Creates a count query
+     * @summary Starts building a query that will count records
+     * @template S - The select selector type
+     * @param {S} [selector] - Optional field to count (counts all if not specified)
+     * @return A count query builder with distinct() available
+     */
+    count<S extends SelectSelector<M>>(selector?: S): CountWhereOption<M>;
+    /**
+     * @description Creates a min query
+     * @summary Starts building a query that will find the minimum value
+     * @template S - The select selector type
+     * @param {S} selector - Field to find minimum value of
+     * @return A min query builder
+     */
+    min<S extends SelectSelector<M>>(selector: S): WhereOption<M, M[S]>;
+    /**
+     * @description Creates a max query
+     * @summary Starts building a query that will find the maximum value
+     * @template S - The select selector type
+     * @param {S} selector - Field to find maximum value of
+     * @return A max query builder
+     */
+    max<S extends SelectSelector<M>>(selector: S): WhereOption<M, M[S]>;
+    /**
+     * @description Creates a sum query
+     * @summary Starts building a query that will sum values
+     * @template S - The select selector type
+     * @param {S} selector - Field to sum
+     * @return A sum query builder
+     */
+    sum<S extends SelectSelector<M>>(selector: S): WhereOption<M, number>;
+    /**
+     * @description Creates an average query
+     * @summary Starts building a query that will compute the average value
+     * @template S - The select selector type
+     * @param {S} selector - Field to average
+     * @return An average query builder
+     */
+    avg<S extends SelectSelector<M>>(selector: S): WhereOption<M, number>;
+    /**
+     * @description Creates a distinct query
+     * @summary Starts building a query that will find distinct values
+     * @template S - The select selector type
+     * @param {S} selector - Field to find distinct values of
+     * @return A distinct query builder
+     */
+    distinct<S extends SelectSelector<M>>(selector: S): WhereOption<M, M[S][]>;
+    /**
+     * @description Executes a query with the specified conditions and options.
+     * @summary Provides a simplified way to query the database with common query parameters.
+     * @param {Condition<M>} condition - The condition to filter records.
+     * @param orderBy - The field to order results by.
+     * @param {OrderDirection} [order=OrderDirection.ASC] - The sort direction.
+     * @param {number} [limit] - Optional maximum number of results to return.
+     * @param {number} [skip] - Optional number of results to skip.
+     * @return {Promise<M[]>} The query results as model instances.
+     */
+    query(condition: Condition<M>, orderBy: keyof M, order?: OrderDirection, limit?: number, skip?: number, ...args: MaybeContextualArg<ContextOf<A>>): Promise<M[]>;
+    listBy(key: keyof M, order: OrderDirection, ...args: MaybeContextualArg<ContextOf<A>>): Promise<M[]>;
+    paginateBy(key: keyof M, order: OrderDirection, ref?: Omit<DirectionLimitOffset, "direction">, ...args: MaybeContextualArg<ContextOf<A>>): Promise<SerializedPage<M>>;
+    find(value: string, order?: OrderDirection, ...args: MaybeContextualArg<ContextOf<A>>): Promise<M[]>;
+    page(value: string, direction?: OrderDirection, ref?: Omit<DirectionLimitOffset, "direction">, ...args: MaybeContextualArg<ContextOf<A>>): Promise<SerializedPage<M>>;
+    findOneBy(key: keyof M, value: any, ...args: MaybeContextualArg<ContextOf<A>>): Promise<M>;
+    findBy(key: keyof M, value: any, ...args: MaybeContextualArg<ContextOf<A>>): Promise<M[]>;
+    findByPaginate(key: keyof M, value: any, ref?: DirectionLimitOffset, ...args: MaybeContextualArg<ContextOf<A>>): Promise<SerializedPage<M>>;
+    /**
+     * @description Counts records, optionally filtered by a key value
+     * @summary Returns the count of records matching the optional key condition
+     * @param {string} key - The field to count (optional, counts all if not specified)
+     * @param {...any[]} args - Additional arguments including context
+     * @return {Promise<number>} The count of matching records
+     */
+    countOf(key?: keyof M, ...args: MaybeContextualArg<ContextOf<A>>): Promise<number>;
+    /**
+     * @description Finds the maximum value of a field
+     * @summary Returns the maximum value for the specified field across all records
+     * @param {string} key - The field to find the maximum value of
+     * @param {...any[]} args - Additional arguments including context
+     * @return {Promise<any>} The maximum value
+     */
+    maxOf<K extends keyof M>(key: K, ...args: MaybeContextualArg<ContextOf<A>>): Promise<M[K]>;
+    /**
+     * @description Finds the minimum value of a field
+     * @summary Returns the minimum value for the specified field across all records
+     * @param {string} key - The field to find the minimum value of
+     * @param {...any[]} args - Additional arguments including context
+     * @return {Promise<any>} The minimum value
+     */
+    minOf<K extends keyof M>(key: K, ...args: MaybeContextualArg<ContextOf<A>>): Promise<M[K]>;
+    /**
+     * @description Calculates the average value of a field
+     * @summary Returns the average value for the specified numeric field across all records
+     * @param {string} key - The field to calculate the average of
+     * @param {...any[]} args - Additional arguments including context
+     * @return {Promise<number>} The average value
+     */
+    avgOf<K extends keyof M>(key: K, ...args: MaybeContextualArg<ContextOf<A>>): Promise<number>;
+    /**
+     * @description Calculates the sum of a field
+     * @summary Returns the sum of values for the specified numeric field across all records
+     * @param {string} key - The field to sum
+     * @param {...any[]} args - Additional arguments including context
+     * @return {Promise<number>} The sum
+     */
+    sumOf<K extends keyof M>(key: K, ...args: MaybeContextualArg<ContextOf<A>>): Promise<number>;
+    /**
+     * @description Finds distinct values of a field
+     * @summary Returns an array of unique values for the specified field
+     * @param {string} key - The field to get distinct values of
+     * @param {...any[]} args - Additional arguments including context
+     * @return {Promise<any[]>} An array of distinct values
+     */
+    distinctOf<K extends keyof M>(key: K, ...args: MaybeContextualArg<ContextOf<A>>): Promise<M[K][]>;
+    /**
+     * @description Groups records by a field
+     * @summary Returns records grouped by the specified field
+     * @param {string} key - The field to group by
+     * @param {...any[]} args - Additional arguments including context
+     * @return {Promise<Record<string, M[]>>} Records grouped by the field value
+     */
+    groupOf<K extends keyof M>(key: K, ...args: MaybeContextualArg<ContextOf<A>>): Promise<Record<string, M[]>>;
+    statement(name: string, ...args: MaybeContextualArg<ContextOf<A>>): Promise<any>;
+    private getDefaultQueryAttributes;
+    private buildDefaultStartsWithCondition;
+    attr(prop: keyof M): import("..").AttributeOption<M>;
+    /**
+     * @description Registers an observer for this repository.
+     * @summary Adds an observer that will be notified of changes to models in this repository.
+     * @param {Observer} observer - The observer to register.
+     * @param {ObserverFilter} [filter] - Optional filter to limit which events the observer receives.
+     * @return {void}
+     * @see {Observable#observe}
+     */
+    observe(observer: Observer, filter?: ObserverFilter): () => void;
+    /**
+     * @description Unregisters an observer from this repository.
+     * @summary Removes an observer so it will no longer receive notifications of changes.
+     * @param {Observer} observer - The observer to unregister.
+     * @return {void}
+     * @throws {InternalError} If the observer handler is not initialized.
+     * @see {Observable#unObserve}
+     */
+    unObserve(observer: Observer): void;
+    /**
+     * @description Notifies all observers of an event.
+     * @summary Updates all registered observers with information about a database event.
+     * @param {string} table - The table name where the event occurred.
+     * @param {OperationKeys|BulkCrudOperationKeys|string} event - The type of event that occurred.
+     * @param {EventIds} id - The ID or IDs of the affected records.
+     * @param {...any[]} args - Additional arguments.
+     * @return {Promise<void>} A promise that resolves when all observers have been notified.
+     * @throws {InternalError} If the observer handler is not initialized.
+     */
+    updateObservers(table: Constructor<M> | string, event: AllOperationKeys, id: EventIds, ...args: ContextualArgs<ContextOf<A>>): Promise<void>;
+    /**
+     * @description Alias for updateObservers.
+     * @summary Notifies all observers of an event (alias for updateObservers).
+     * @param {string} table - The table name where the event occurred.
+     * @param {OperationKeys|BulkCrudOperationKeys|string} event - The type of event that occurred.
+     * @param {EventIds} id - The ID or IDs of the affected records.
+     * @param {...any[]} args - Additional arguments.
+     * @return {Promise<void>} A promise that resolves when all observers have been notified.
+     */
+    refresh(table: Constructor<M> | string, event: AllOperationKeys, id: EventIds, ...args: ContextualArgs<ContextOf<A>>): Promise<void>;
+    /**
+     * @description Creates or retrieves a repository for a model.
+     * @summary Factory method that returns a repository instance for the specified model.
+     * @template M - The model type that extends Model.
+     * @template R - The repository type that extends Repo<M>.
+     * @param {Constructor<M>} model - The model constructor.
+     * @param {string} [alias] - Optional default adapter flavour if not specified on the model.
+     * @param {...any[]} [args] - Additional arguments to pass to the repository constructor.
+     * @return {R} A repository instance for the model.
+     * @throws {InternalError} If no adapter is registered for the flavour.
+     */
+    static forModel<M extends Model, R extends Repo<M>>(model: Constructor<M>, alias?: string, ...args: any[]): R;
+    /**
+     * @description Retrieves a repository for a model from the cache.
+     * @summary Gets a repository constructor or instance for the specified model from the internal cache.
+     * @template M - The model type that extends Model.
+     * @param {Constructor<M>} model - The model constructor.
+     * @param {string} [alias] - The adapter alias.
+     * @return {Constructor<Repo<M>> | Repo<M>} The repository constructor or instance.
+     * @throws {InternalError} If no repository is registered for the model.
+     */
+    private static get;
+    /**
+     * @description Registers a repository for a model.
+     * @summary Associates a repository constructor or instance with a model in the internal cache.
+     * @template M - The model type that extends Model.
+     * @param {Constructor<M>} model - The model constructor.
+     * @param {Constructor<Repo<M>> | Repo<M>} repo - The repository constructor or instance.
+     * @param {string} [alias] the adapter alias/flavour.
+     * @throws {InternalError} If a repository is already registered for the model.
+     */
+    static register<M extends Model>(model: Constructor<M>, repo: Constructor<Repo<M>> | Repo<M>, alias?: string, force?: boolean): void;
+    static statements<R extends Repository<any, any>, K extends keyof R>(repo: Constructor<R> | R, method?: K): undefined | (K extends keyof R ? boolean : (keyof R)[]);
+    static queries<R extends Repository<any, any>, K extends keyof R>(repo: Constructor<R> | R, method?: K): undefined | (K extends keyof R ? QueryOptions : Record<keyof R, QueryOptions>);
+}

package/lib/types/repository/{Repository.d.ts → Repository.d.mts}

@@ -1,20 +1,20 @@
 import { IRepository, Repository as Rep, PrimaryKeyType } from "@decaf-ts/db-decorators";
 import { Logger } from "@decaf-ts/logging";
-import { ContextualArgs, ContextualizedArgs, MaybeContextualArg, MethodOrOperation } from "../utils/ContextualLoggedClass";
-import { Adapter } from "../persistence/Adapter";
-import { ObserverHandler } from "../persistence/ObserverHandler";
-import type { DirectionLimitOffset, QueryOptions } from "../query/types";
-import { SelectSelector } from "../query/selectors";
-import { CountWhereOption, WhereOption } from "../query/options";
-import { Condition } from "../query/Condition";
-import { Queriable } from "../interfaces/Queriable";
-import { SequenceOptions } from "../interfaces/SequenceOptions";
-import { OrderDirection } from "./constants";
-import type { AllOperationKeys, ContextOf, EventIds, FlagsOf, InferredAdapterConfig, ObserverFilter, PersistenceObservable, PersistenceObserver } from "../persistence/types";
-import type { Observer } from "../interfaces/Observer";
+import { ContextualArgs, ContextualizedArgs, MaybeContextualArg, MethodOrOperation } from "../utils/ContextualLoggedClass.js";
+import { Adapter } from "../persistence/Adapter.js";
+import { ObserverHandler } from "../persistence/ObserverHandler.js";
+import type { DirectionLimitOffset, QueryOptions } from "../query/types.js";
+import { SelectSelector } from "../query/selectors.js";
+import { CountWhereOption, WhereOption } from "../query/options.js";
+import { Condition } from "../query/Condition.js";
+import { Queriable } from "../interfaces/Queriable.js";
+import { SequenceOptions } from "../interfaces/SequenceOptions.js";
+import { OrderDirection } from "./constants.js";
+import type { AllOperationKeys, ContextOf, EventIds, FlagsOf, InferredAdapterConfig, ObserverFilter, PersistenceObservable, PersistenceObserver } from "../persistence/types.js";
+import type { Observer } from "../interfaces/Observer.js";
 import { Constructor } from "@decaf-ts/decoration";
 import { Model } from "@decaf-ts/decorator-validation";
-import { SerializedPage } from "../query/Paginator";
+import { SerializedPage } from "../query/Paginator.js";
 /**
  * @description Type alias for Repository class with simplified generic parameters.
  * @summary Provides a more concise way to reference the Repository class with its generic parameters.

package/lib/types/repository/constants.d.cts

@@ -0,0 +1,36 @@
+import { CascadeMetadata } from "./types.cjs";
+/**
+ * @description Enumeration of possible sort directions.
+ * @summary Defines the available sort directions for ordering query results.
+ * @enum {string}
+ * @readonly
+ * @memberOf module:core
+ */
+export declare enum OrderDirection {
+    /** Ascending order (A to Z, 0 to 9) */
+    ASC = "asc",
+    /** Descending order (Z to A, 9 to 0) */
+    DSC = "desc"
+}
+/**
+ * @description Enumeration of cascade operation types.
+ * @summary Defines the available cascade behaviors for entity relationships.
+ * @enum {string}
+ * @readonly
+ * @memberOf module:core
+ */
+export declare enum Cascade {
+    /** Perform cascade operation on related entities */
+    CASCADE = "cascade",
+    /** Do not perform cascade operation on related entities */
+    NONE = "none"
+}
+/**
+ * @description Shape of the default cascade configuration object used in repositories.
+ * @summary Documents the structure of the cascade configuration with explicit update and delete behaviors.
+ * @property {'cascade'|'none'} update - Determines whether updates cascade to related entities.
+ * @property {'cascade'|'none'} delete - Determines whether deletes cascade to related entities.
+ * @typeDef DefaultCascadeConfig
+ * @memberOf module:core
+ */
+export declare const DefaultCascade: CascadeMetadata;

package/lib/types/repository/{constants.d.ts → constants.d.mts}

@@ -1,4 +1,4 @@
-import { CascadeMetadata } from "./types";
+import { CascadeMetadata } from "./types.js";
 /**
  * @description Enumeration of possible sort directions.
  * @summary Defines the available sort directions for ordering query results.