@mrxsys/mrx-core 2.4.0 → 2.5.0

package/dist/modules/repository/repository.d.ts

@@ -0,0 +1,421 @@
+import type { Knex } from 'knex';
+import type { Table } from '../../modules/database/table';
+import type { StreamWithAsyncIterable } from '../../utils/types/streamWithAsyncIterable';
+import type { Filter } from './types/filter';
+import type { OrderByItem } from './types/orderByItem';
+import type { QueryOptions } from './types/queryOptions';
+import type { QueryOptionsExtendPagination } from './types/queryOptionsExtendPagination';
+import type { QueryOptionsExtendStream } from './types/queryOptionsExtendStream';
+/**
+ * Repository allowing interaction with a database table using Knex.js fully typed.
+ *
+ * @template TModel - The data model type handled by the repository.
+ *
+ * Example:
+ * ```ts
+ * const repo = new Repository<User>(knex, userTable);
+ * const users = await repo.find({ limit: 10 });
+ * ```
+ */
+export declare class Repository<TModel = unknown> {
+    /**
+     * The Knex instance used for database operations.
+     */
+    protected readonly _knex: Knex;
+    /**
+     * The table associated with this repository.
+     */
+    protected readonly _table: Table;
+    /**
+     * Creates a new `Repository` instance with the specified Knex.js instance and table object.
+     *
+     * @param knex - The Knex.js instance used to interact with the database.
+     * @param table - The table object representing the database table to interact with.
+     */
+    constructor(knex: Knex, table: Table);
+    /**
+     * Finds records in the database based on the specified query options and returns a stream
+     * for async iteration. This method is particularly useful when working with large datasets
+     * that would be inefficient to load entirely into memory.
+     *
+     * The stream emits data events for each record and an end event when the stream is finished.
+     * It can be consumed using either async iteration or event listeners.
+     *
+     * @template KModel - The type of the object to retrieve.
+     *
+     * @param options - The query options to apply to the search.
+     *
+     * @returns A stream with an async iterable interface for consuming the results.
+     *
+     * @example
+     * Basic usage with async iteration
+     * ```ts
+     * const stream = userRepository.findStream();
+     * for await (const user of stream) {
+     *     console.log(user);
+     * }
+     * ```
+     * @example
+     * With single field selection
+     * ```ts
+     * const stream = userRepository.findStream({
+     *    selectedFields: 'name'
+     * });
+     * ```
+     * @example
+     * With multiple fields selection
+     * ```ts
+     * const stream = userRepository.findStream({
+     *    selectedFields: ['id', 'name', 'email']
+     * });
+     * ```
+     * @example
+     * With single order by field
+     * ```ts
+     * const stream = userRepository.findStream({
+     *     orderBy: {
+     *         selectedField: 'createdAt',
+     *         direction: 'desc'
+     *     }
+     * });
+     * ```
+     * @example
+     * With multiple order by fields
+     * ```ts
+     * const stream = userRepository.findStream({
+     *     orderBy: [
+     *         { selectedField: 'createdAt', direction: 'desc' },
+     *         { selectedField: 'name', direction: 'asc' }
+     *     ]
+     * });
+     * ```
+     * @example
+     * With filtering
+     * ```ts
+     * const stream = userRepository.findStream({
+     *     filters: {
+     *         isActive: false
+     *     }
+     * });
+     * ```
+     * @example
+     * Using event listeners
+     * ```ts
+     * const stream = userRepository.findStream();
+     * stream.on('data', (user) => {
+     *     console.log('User:', user);
+     * });
+     * stream.on('error', (error) => {
+     *     console.error('Stream error:', error);
+     * });
+     * stream.on('end', () => {
+     *     console.log('Stream completed');
+     * });
+     * ```
+     * @example
+     * With transform function to process records
+     * ```ts
+     * const stream = userRepository.findStream({
+     *     transform: (chunk, encoding, callback) => {
+     *         // Transform the data
+     *         const transformedData = { ...chunk, processed: true };
+     *         callback(null, transformedData);
+     *     }
+     * });
+     * ```
+     */
+    findStream<KModel extends TModel = NoInfer<TModel>>(options?: QueryOptionsExtendStream<KModel>): StreamWithAsyncIterable<KModel>;
+    /**
+     * Finds records in the database based on the specified query options and returns the results
+     * as an array. This method supports comprehensive filtering, pagination, field selection, and sorting
+     * to provide flexible data retrieval capabilities.
+     *
+     * @template KModel - The type of the object to retrieve.
+     *
+     * @param options - The query options to apply to the search.
+     *
+     * @throws ({@link HttpError}) - Throws an error if no records are found if the {@link QueryOptions.throwIfNoResult} option is enabled.
+     * @throws ({@link HttpError}) - Throws an error if an MSSQL-specific error occurs during the query execution.
+     *
+     * @returns An array of records matching the query options.
+     *
+     * @example
+     * Basic usage with pagination
+     * ```ts
+     * const users = await userRepository.find({
+     *     limit: 25,
+     *     offset: 50  // Get users 51-75
+     * });
+     * ```
+     * @example
+     * With field selection
+     * ```ts
+     * const userNames = await userRepository.find({
+     *     selectedFields: ['id', 'firstName', 'lastName']
+     * });
+     * ```
+     * @example
+     * With filtering
+     * ```ts
+     * const activeAdmins = await userRepository.find({
+     *     filters: {
+     *         isActive: { $eq: true }
+     *     }
+     * });
+     * ```
+     * @example
+     * With OR conditions
+     * ```ts
+     * const results = await userRepository.find({
+     *     filters: [
+     *         { department: 'engineering' },
+     *         { department: 'design', role: 'lead' }
+     *     ]
+     * });
+     * ```
+     * @example
+     * With sorting
+     * ```ts
+     * const sortedUsers = await userRepository.find({
+     *     orderBy: ['lastName', 'asc']
+     * });
+     * ```
+     * @example
+     * Using a transaction
+     * ```ts
+     * await knex.transaction(async (trx) => {
+     *     const users = await userRepository.find({
+     *         filters: { department: 'finance' },
+     *         transaction: trx
+     *     });
+     * });
+     * ```
+     */
+    find<KModel extends TModel = NoInfer<TModel>>(options?: QueryOptionsExtendPagination<KModel>): Promise<KModel[]>;
+    /**
+     * Counts the number of records in the database based on the specified query options.
+     * This method supports advanced filtering capabilities to count records that match specific criteria.
+     *
+     * @template KModel - The type of the object to count.
+     *
+     * @param options - The query options to apply to the search.
+     *
+     * @throws ({@link HttpError}) - Throws an error if no records are found if the {@link QueryOptions.throwIfNoResult} option is enabled.
+     * @throws ({@link HttpError}) - Throws an error if an MSSQL-specific error occurs during the query execution.
+     *
+     * @returns The count of records matching the query options.
+     *
+     * @example
+     * Basic usage
+     * ```ts
+     * const userCount = await userRepository.count();
+     * ```
+     * @example
+     * With filtering
+     * ```ts
+     * const activeUserCount = await userRepository.count({
+     *     filters: { isActive: true }
+     * });
+     * ```
+     * @example
+     * Using a transaction
+     * ```ts
+     * await knex.transaction(async (trx) => {
+     *     const userCount = await userRepository.count({
+     *         filters: { department: 'finance' },
+     *         transaction: trx
+     *     });
+     * });
+     * ```
+     */
+    count<KModel extends TModel = NoInfer<TModel>>(options?: Omit<QueryOptions<KModel>, 'selectedFields' | 'orderBy'>): Promise<number>;
+    /**
+     * Inserts new records into the database and returns the inserted records.
+     * This method supports bulk insertion of multiple records at once.
+     *
+     * @template KModel - The type of the object to insert.
+     *
+     * @param data - The data to insert. Can be a single object or an array of objects.
+     * @param options - The query options to apply to the insertion.
+     *
+     * @throws ({@link HttpError}) - Throws an error if an MSSQL-specific error occurs during the query execution.
+     *
+     * @returns An array of inserted records.
+     *
+     * @example
+     * Basic usage
+     * ```ts
+     * const newUser = await userRepository.insert({ name: 'John Doe', email: 'john.doe@example.com' });
+     * ```
+     * @example
+     * With bulk insertion
+     * ```ts
+     * const users = await userRepository.insert([
+     *     { name: 'Jane Doe', email: 'jane.doe@example.com' },
+     *     { name: 'John Smith', email: 'john.smith@example.com' }
+     * ]);
+     * ```
+     * @example
+     * Using a transaction
+     * ```ts
+     * await knex.transaction(async (trx) => {
+     *     const newUser = await userRepository.insert({ name: 'John Doe', email: 'john.doe@example.com' }, {
+     *         transaction: trx
+     *     });
+     * });
+     * ```
+     */
+    insert<KModel extends TModel = NoInfer<TModel>>(data: Partial<KModel> | Partial<KModel>[], options?: Omit<QueryOptions<KModel>, 'filters' | 'orderBy'>): Promise<KModel[]>;
+    /**
+     * Updates existing records in the database based on the specified query options and returns the updated records.
+     * This method supports advanced filtering capabilities to update records that match specific criteria.
+     *
+     * @template KModel - The type of the object to update.
+     *
+     * @param data - The data to update. Can be a single object or an array of objects.
+     * @param options - The query options to apply to the update.
+     *
+     * @throws ({@link HttpError}) - Throws an error if an MSSQL-specific error occurs during the query execution.
+     *
+     * @returns An array of updated records.
+     *
+     * @example
+     * Basic usage
+     * ```ts
+     * const updatedUser = await userRepository.update({ name: 'John Doe' }, {
+     *     filters: { id: 1 }
+     * });
+     * ```
+     * @example
+     * With filtering
+     * ```ts
+     * const updatedUsers = await userRepository.update({ status: 'inactive' }, {
+     *     filters: { role: 'admin' }
+     * });
+     * ```
+     * @example
+     * Using a transaction
+     * ```ts
+     * await knex.transaction(async (trx) => {
+     *   const updatedUser = await userRepository.update({ name: 'John Doe' }, {
+     *       filters: { id: 1 },
+     *       transaction: trx
+     *   });
+     * });
+     * ```
+     */
+    update<KModel extends TModel = NoInfer<TModel>>(data: Partial<KModel>, options: Omit<QueryOptions<KModel>, 'orderBy' | 'filters'> & Required<Pick<QueryOptions<KModel>, 'filters'>>): Promise<KModel[]>;
+    /**
+     * Deletes records from the database based on the specified query options and returns the deleted records.
+     * This method supports advanced filtering capabilities to filter the records before deletion.
+     *
+     * @template KModel - The type of the object to delete.
+     *
+     * @param options - The query options to apply to the deletion.
+     *
+     * @throws ({@link HttpError}) - Throws an error if an MSSQL-specific error occurs during the query execution.
+     *
+     * @returns An array of deleted records.
+     *
+     * @example
+     * Basic usage
+     * ```ts
+     * const deletedUser = await userRepository.delete({
+     *     filters: { id: 1 }
+     * });
+     * ```
+     * @example
+     * With filtering
+     * ```ts
+     * const deletedUsers = await userRepository.delete({
+     *     filters: { status: 'inactive' }
+     * });
+     * ```
+     * @example
+     * Using a transaction
+     * ```ts
+     * await knex.transaction(async (trx) => {
+     *     const deletedUser = await userRepository.delete({
+     *         filters: { id: 1 },
+     *         transaction: trx
+     *     });
+     * });
+     * ```
+     */
+    delete<KModel extends TModel = NoInfer<TModel>>(options: Omit<QueryOptions<KModel>, 'orderBy' | 'filters'> & Required<Pick<QueryOptions<KModel>, 'filters'>>): Promise<KModel[]>;
+    /**
+     * Applies selected fields to a Knex.js query builder. This method supports both single and multiple field selections.
+     * It is used to specify which fields should be returned in the query results.
+     *
+     * @template KModel - The type of the object for query options.
+     *
+     * @param query - The Knex.js query builder to apply the selected fields to.
+     * @param selectedFields - The fields to select. Can be a single field or an array of fields.
+     */
+    protected _applySelectedFields<KModel>(query: Knex.QueryBuilder, selectedFields: QueryOptions<KModel>['selectedFields'] | undefined): void;
+    /**
+     * Applies filter criteria to a Knex.js query builder. This method supports complex queries
+     * using operators like `$eq`, `$neq`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$nin`, `$between`, `$nbetween`,
+     * `$like`, `$nlike`, and `$isNull`. It also supports basic string searches and field selection.
+     *
+     * @template KModel - The type of the object to search for.
+     *
+     * @param query - The Knex.js query builder to apply the search criteria to.
+     * @param search - The advanced search criteria to apply. Can be a single object or an array of objects.
+     */
+    protected _applyFilter<KModel>(query: Knex.QueryBuilder, search: Filter<KModel> | Filter<KModel>[] | undefined): void;
+    /**
+     * Applies order by criteria to a Knex.js query builder. This method supports both single and multiple order by items.
+     * It is used to specify the sorting order of the query results.
+     *
+     * @template KModel - The type of the object for query options.
+     *
+     * @param query - The Knex.js query builder to apply the order by criteria to.
+     * @param orderBy - The order by criteria. Can be a single item or an array of items.
+     */
+    protected _applyOrderBy<KModel>(query: Knex.QueryBuilder, orderBy: OrderByItem<KModel> | OrderByItem<KModel>[] | undefined): void;
+    /**
+     * Applies query options such as filters, orderBy, and transaction to a Knex.js query builder.
+     *
+     * @template KModel - The type of the object for query options.
+     *
+     * @param query - The Knex.js query builder to apply the options to.
+     * @param options - The query options to apply.
+     */
+    protected _applyQueryOptions<KModel>(query: Knex.QueryBuilder, options?: Omit<QueryOptions<KModel>, 'throwIfNoResult'>): void;
+    /**
+     * Handles errors that occur during query execution. This method centralizes error handling
+     * for MSSQL-specific errors and throws a {@link HttpError} with relevant information.
+     *
+     * @param error - The error object thrown by Knex.js.
+     * @param query - The Knex.js query builder that caused the error.
+     *
+     * @throws ({@link HttpError}) - Throws an error if an MSSQL-specific error occurs during the query execution.
+     *
+     * @returns Never returns, always throws an error.
+     */
+    protected _handleError(error: unknown, query: Knex.QueryBuilder): never;
+    /**
+     * Determines if the provided data is a complex query (i.e., a WhereClause).
+     *
+     * @param data - The data to check.
+     *
+     * @returns True if the data is a WhereClause, false otherwise.
+     */
+    private _filterIsAdaptiveWhereClause;
+    /**
+     * Executes a Knex.js query and returns the result. This method provides centralized
+     * error handling and supports the option to throw an error if no records are found.
+     *
+     * @template KModel - The type of the records returned by the query.
+     *
+     * @param query - The Knex.js query builder to execute.
+     * @param throwIfNoResult - Whether to throw an error if no records are found.
+     *
+     * @throws ({@link HttpError}) - Throws an error if no records are found if the {@link QueryOptions.throwIfNoResult} option is enabled.
+     * @throws ({@link HttpError}) - Throws an error if an MSSQL-specific error occurs during the query execution.
+     *
+     * @returns An array of records returned by the query.
+     */
+    protected _executeQuery<KModel>(query: Knex.QueryBuilder, throwIfNoResult?: QueryOptions<KModel>['throwIfNoResult']): Promise<KModel[]>;
+}

package/dist/modules/repository/types/adaptiveWhereClause.d.ts

@@ -0,0 +1,30 @@
+export type AdaptiveWhereClause<TValue> = TValue extends string ? {
+    $eq?: TValue;
+    $neq?: TValue;
+    $isNull?: boolean;
+} & {
+    $in?: TValue[];
+    $nin?: TValue[];
+    $like?: string;
+    $nlike?: string;
+} : TValue extends number | Date | bigint ? {
+    $eq?: TValue;
+    $neq?: TValue;
+    $isNull?: boolean;
+} & {
+    $in?: TValue[];
+    $nin?: TValue[];
+    $like?: string;
+    $nlike?: string;
+} & {
+    $lt?: TValue;
+    $lte?: TValue;
+    $gt?: TValue;
+    $gte?: TValue;
+    $between?: [TValue, TValue];
+    $nbetween?: [TValue, TValue];
+} : {
+    $eq?: boolean;
+    $neq?: boolean;
+    $isNull?: boolean;
+};

package/dist/modules/repository/types/filter.d.ts

@@ -0,0 +1,43 @@
+import type { AdaptiveWhereClause } from './adaptiveWhereClause';
+import type { SelectedFields } from './selectedFields';
+/**
+ * Defines an filter model using either plain partials of the model TModel or a {@link AdaptiveWhereClause} filter for more dynamic querying.
+ *
+ * @template TModel - The model type to be used for the filter.
+ *
+ * @example
+ * ```ts
+ * interface User {
+ *    id: number;
+ *    name: string;
+ * }
+ *
+ * interface Basket {
+ *   id: number;
+ *   userId: number;
+ *   products: Product[];
+ * }
+ *
+ * const example1: Filter<User> = {
+ *     id: 1
+ * };
+ *
+ * const example2: Filter<User> = {
+ *     name: {
+ *         $eq: 'John'
+ *     }
+ * };
+ *
+ * const example3: Filter<User> = {
+ *     $q: 'John'
+ * };
+ * ```
+ */
+export type Filter<TModel> = {
+    $q?: string | number | {
+        selectedFields: SelectedFields<TModel>;
+        value: string | number;
+    };
+} & {
+    [Key in keyof TModel]?: TModel[Key] | Partial<AdaptiveWhereClause<TModel[Key]>>;
+};

package/dist/modules/repository/types/index.d.ts

@@ -0,0 +1,8 @@
+export type { AdaptiveWhereClause } from './adaptiveWhereClause';
+export type { Filter } from './filter';
+export type { OrderByItem } from './orderByItem';
+export type { QueryOptions } from './queryOptions';
+export type { QueryOptionsExtendPagination } from './queryOptionsExtendPagination';
+export type { QueryOptionsExtendStream } from './queryOptionsExtendStream';
+export type { SelectedFields } from './selectedFields';
+export type { Transaction } from './transaction';

package/dist/modules/repository/types/index.js

@@ -0,0 +1 @@
+// @bun

package/dist/modules/repository/types/orderByItem.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Represents an ordering instruction for queries.
+ *
+ * This interface specifies the field to order by and the direction of the ordering.
+ *
+ * @template TModel - The type of the object to order by.
+ *
+ * @example
+ * Define a model
+ * ```ts
+ * interface User {
+ *   id: number;
+ *   name: string;
+ * }
+ * ```
+ * @example
+ * Order by a single field ascending
+ * ```ts
+ * const orderBy1: OrderByItem<User> = {
+ *   selectedField: 'id',
+ *   direction: 'asc'
+ * };
+ * ```
+ * @example
+ * Order by a single field descending
+ * ```ts
+ * const orderBy2: OrderByItem<User> = {
+ *   selectedField: 'name',
+ *   direction: 'desc'
+ * };
+ * ```
+ */
+export interface OrderByItem<TModel> {
+    /**
+     * The field to order by. Must be a key of the model or a string.
+     */
+    selectedField: (keyof TModel extends string ? keyof TModel : string);
+    /**
+     * The direction of the ordering: 'asc' for ascending, 'desc' for descending.
+     */
+    direction: 'asc' | 'desc';
+}

package/dist/modules/repository/types/queryOptions.d.ts

@@ -0,0 +1,36 @@
+import type { Filter } from './filter';
+import type { OrderByItem } from './orderByItem';
+import type { SelectedFields } from './selectedFields';
+import type { Transaction } from './transaction';
+/**
+ * This interface defines the basic options for a repository query.
+ *
+ * @template TModel - The type of the object to retrieve.
+*/
+export interface QueryOptions<TModel> {
+    /**
+     * The fields to select in the query. If not provided, all fields are selected. ({@link SelectedFields})
+     *
+     * @defaultValue If not provided, all fields are selected.
+     */
+    readonly selectedFields?: SelectedFields<NoInfer<TModel>>;
+    /**
+     * The filters options to apply to the query. Can be a single object or an array of objects.
+     * @see {@link Filter}
+     */
+    readonly filters?: Filter<NoInfer<TModel>> | Filter<NoInfer<TModel>>[];
+    /**
+     * Order the results by a specific column and direction. ({@link OrderByItem})
+     * @defaultValue If not provided, the primary key of the model is used in ascending order.
+     */
+    readonly orderBy?: OrderByItem<NoInfer<TModel>> | OrderByItem<NoInfer<TModel>>[];
+    /**
+     * Whether to throw an error if the query does not return any result.
+     * @defaultValue false
+     */
+    readonly throwIfNoResult?: boolean | string;
+    /**
+     * The transaction context for the query. ({@link Transaction})
+     */
+    readonly transaction?: Transaction;
+}

package/dist/{repository → modules/repository}/types/queryOptionsExtendPagination.d.ts

@@ -12,10 +12,10 @@ export interface QueryOptionsExtendPagination<TModel> extends QueryOptions<TMode
      * The limit of the query
      * @defaultValue 100
      */
-    limit?: number;
+    readonly limit?: number;
     /**
      * The offset of the query
      * @defaultValue 0
      */
-    offset?: number;
+    readonly offset?: number;
 }

package/dist/{repository → modules/repository}/types/queryOptionsExtendStream.d.ts

@@ -12,5 +12,5 @@ export interface QueryOptionsExtendStream<TModel> extends QueryOptions<TModel> {
      * @param encoding - The encoding of the chunk.
      * @param callback - The callback to call when the transformation is complete.
      */
-    transform?: (chunk: NoInfer<TModel>, encoding: string, callback: (error?: Error | null, data?: NoInfer<TModel>) => void) => void;
+    readonly transform?: (chunk: NoInfer<TModel>, encoding: string, callback: (error?: Error | null, data?: NoInfer<TModel>) => void) => void;
 }

package/dist/modules/repository/types/selectedFields.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Specifies the fields to select in a query for a given model type.
+ *
+ * This type allows you to define which columns should be included in the query result.
+ * You can provide a single field name or an array of field names, using either keys from the model type or arbitrary strings.
+ *
+ * @template TModel - The type of the object to select fields from.
+ *
+ * @remarks
+ * - If you use keys from the model type, TypeScript will provide type safety.
+ * - You may also use string values for dynamic or computed fields.
+ *
+ * @example
+ * Define a model
+ * ```ts
+ * interface User {
+ *     id: number;
+ *     name: string;
+ * }
+ * ```
+ * @example
+ * Select specific fields using model keys
+ * ```ts
+ * const selection1: SelectedFields<User> = ['id', 'name'];
+ * ```
+ * @example
+ * Select a single field
+ * ```ts
+ * const selection2: SelectedFields<User> = 'id';
+ * ```
+ * @example
+ * Select fields using arbitrary strings (e.g., computed columns)
+ * ```ts
+ * const selection3: SelectedFields<User> = ['id', 'fullName'];
+ * ```
+ */
+export type SelectedFields<TModel> = (keyof TModel extends string ? keyof TModel : string) | '*' | (keyof TModel extends string ? keyof TModel : string)[];

package/dist/modules/singletonManager/enums/singletonManagerErrorKeys.d.ts

@@ -0,0 +1,4 @@
+export declare const SINGLETON_MANAGER_ERROR_KEYS: {
+    readonly CLASS_CONSTRUCTOR_ALREADY_REGISTERED: "singletonManager.error.class_constructor_already_registered";
+    readonly CLASS_CONSTRUCTOR_NOT_REGISTERED: "singletonManager.error.class_constructor_not_registered";
+};

package/dist/modules/singletonManager/index.d.ts

@@ -0,0 +1 @@
+export { SingletonManager } from './singletonManager';

package/dist/modules/singletonManager/index.js

@@ -0,0 +1,8 @@
+// @bun
+import {
+  SingletonManager
+} from "../../chunk-370444pc.js";
+import"../../chunk-vknq69e0.js";
+export {
+  SingletonManager
+};