@mrxsys/mrx-core 2.3.3-canary-20250514-a17e993

package/dist/repository/repository.d.ts

@@ -0,0 +1,381 @@
+import type { Knex } from 'knex';
+import type { Table } from '../database/table';
+import type { StreamWithAsyncIterable } from '../utils/types/streamWithAsyncIterable';
+import type { AdvancedSearch } from './types/advancedSearch';
+import type { QueryOptions } from './types/queryOptions';
+import type { QueryOptionsExtendPagination } from './types/queryOptionsExtendPagination';
+import type { QueryOptionsExtendStream } from './types/queryOptionsExtendStream';
+import type { WhereClause } from './types/whereClause';
+export type OperatorFn = (query: Knex.QueryBuilder, column: string, value: unknown) => Knex.QueryBuilder;
+export declare const operators: Record<keyof WhereClause<unknown>, OperatorFn>;
+/**
+ * Provides a type-safe, extensible interface for database operations (CRUD, search, streaming) on a table.
+ *
+ * - Wraps Knex.js for query building and execution.
+ * - Supports advanced search, pagination, field selection, and streaming.
+ * - Centralizes error handling for MSSQL.
+ *
+ * @template TModel - The data model type handled by the repository.
+ *
+ * Example:
+ * ```typescript
+ * 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.
+     * @see {@link Table}
+     */
+    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. ({@link QueryOptionsExtendStream})
+     *
+     * @returns A stream with an async iterable interface for consuming the results. ({@link StreamWithAsyncIterable})
+     *
+     *
+     * ### Usage Examples:
+     * @example
+     * ```typescript
+     * // Basic usage with async iteration
+     * const stream = userRepository.findStream();
+     * for await (const user of stream) {
+     *   console.log(user);
+     * }
+     *
+     * // With ordering and field selection
+     * const stream = userRepository.findStream({
+     *   selectedFields: ['id', 'name', 'email'],
+     *   orderBy: ['createdDate', 'desc']
+     * });
+     *
+     * // Using event listeners
+     * 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');
+     * });
+     *
+     * // With transform function to process records
+     * 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. ({@link QueryOptionsExtendPagination})
+     *
+     * @throws ({@link CoreError}) Throws an error if no records are found and the `throwIfNoResult` option is enabled. ({@link databaseKeyError.mssqlNoResult})
+     * @throws ({@link CoreError}) Throws an error if an MSSQL-specific error occurs during the query execution. ({@link databaseKeyError})
+     *
+     * @returns An array of records matching the query options. ({@link KModel})
+     *
+     * ### Usage Examples:
+     * @example
+     * ```typescript
+     * // Basic usage with pagination
+     * const users = await userRepository.find({
+     *   limit: 25,
+     *   offset: 50  // Get users 51-75
+     * });
+     *
+     * // With field selection
+     * const userNames = await userRepository.find({
+     *   selectedFields: ['id', 'firstName', 'lastName']
+     * });
+     *
+     * // With advanced filtering
+     * const activeAdmins = await userRepository.find({
+     *   advancedSearch: {
+     *     role: 'admin',
+     *     status: { $eq: 'active' },
+     *     lastLogin: { $gte: new Date('2023-01-01') }
+     *   }
+     * });
+     *
+     * // With OR conditions
+     * const results = await userRepository.find({
+     *   advancedSearch: [
+     *     { department: 'engineering' },
+     *     { department: 'design', role: 'lead' }
+     *   ]
+     * });
+     *
+     * // With sorting
+     * const sortedUsers = await userRepository.find({
+     *   orderBy: ['lastName', 'asc']
+     * });
+     *
+     * // Using a transaction
+     * await knex.transaction(async (trx) => {
+     *   const users = await userRepository.find({
+     *     advancedSearch: { department: 'finance' },
+     *     transaction: trx
+     *   });
+     * });
+     * ```
+     */
+    find<KModel extends TModel = NoInfer<TModel>>(options?: QueryOptionsExtendPagination<KModel>): Promise<KModel[]>;
+    /**
+     * Finds a single record in the database based on the specified query options and returns the result.
+     * This method supports comprehensive filtering, 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. ({@link QueryOptionsExtendPagination})
+     *
+     * @throws ({@link CoreError}) Throws an error if no records are found and the `throwIfNoResult` option is enabled. ({@link databaseKeyError.mssqlNoResult})
+     * @throws ({@link CoreError}) Throws an error if an MSSQL-specific error occurs during the query execution. ({@link databaseKeyError})
+     *
+     * @returns A single record matching the query options. ({@link KModel})
+     *
+     * ### Usage Examples:
+     * @example
+     * ```typescript
+     * // Basic usage
+     * const user = await userRepository.findOne({
+     *   advancedSearch: { id: 1 }
+     * });
+     *
+     * // With field selection
+     * const user = await userRepository.findOne({
+     *   selectedFields: ['id', 'firstName', 'lastName'],
+     *   advancedSearch: { id: 1 }
+     * });
+     *
+     * // With advanced filtering
+     * const user = await userRepository.findOne({
+     *   advancedSearch: {
+     *     role: 'admin',
+     *     status: { $eq: 'active' },
+     *   }
+     * });
+     *
+     * // With sorting
+     * const user = await userRepository.findOne({
+     *   orderBy: ['lastName', 'asc']
+     * });
+     *
+     * // Using a transaction
+     * await knex.transaction(async (trx) => {
+     *   const user = await userRepository.findOne({
+     *       advancedSearch: { department: 'finance' },
+     *       transaction: trx
+     *   });
+     * });
+     * ```
+     */
+    findOne<KModel extends TModel = NoInfer<TModel>>(options: Omit<QueryOptions<KModel>, 'advancedSearch'> & Required<Pick<QueryOptions<KModel>, 'advancedSearch'>>): Promise<KModel>;
+    /**
+     * Counts the number of records in the database based on the specified query options.
+     * This method supports advanced search capabilities to filter the records before counting.
+     *
+     * @template KModel - The type of the object to count.
+     * @param options - The query options to apply to the search. ({@link QueryOptions})
+     *
+     * @throws ({@link CoreError}) Throws an error if no records are found and the `throwIfNoResult` option is enabled. ({@link databaseKeyError.mssqlNoResult})
+     * @throws ({@link CoreError}) Throws an error if an MSSQL-specific error occurs during the query execution. ({@link databaseKeyError})
+     *
+     * @returns The count of records matching the query options.
+     *
+     * ### Usage Examples:
+     * @example
+     * ```typescript
+     * // Basic usage
+     * const userCount = await userRepository.count();
+     *
+     * // With advanced filtering
+     * const activeUserCount = await userRepository.count({
+     *   advancedSearch: { status: 'active' }
+     * });
+     *
+     * // Using a transaction
+     * await knex.transaction(async (trx) => {
+     *   const userCount = await userRepository.count({
+     *       advancedSearch: { 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. ({@link QueryOptions})
+     *
+     * @throws ({@link CoreError}) Throws an error if an MSSQL-specific error occurs during the query execution. ({@link databaseKeyError})
+     *
+     * @returns An array of inserted records.
+     *
+     * ### Usage Examples:
+     * @example
+     * ```typescript
+     * // Basic usage
+     * const newUser = await userRepository.insert({ name: 'John Doe', email: 'john.doe@example.com' });
+     *
+     * // With bulk insertion
+     * const users = await userRepository.insert([
+     *   { name: 'Jane Doe', email: 'jane.doe@example.com' },
+     *   { name: 'John Smith', email: 'john.smith@example.com' }
+     * ]);
+     *
+     * // Using a transaction
+     * 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>, 'advancedSearch' | 'orderBy'>): Promise<KModel[]>;
+    /**
+     * Updates existing records in the database based on the specified query options and returns the updated records.
+     * This method supports advanced search capabilities to filter the records before updating.
+     *
+     * @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. ({@link QueryOptions})
+     *
+     * @throws ({@link CoreError}) Throws an error if an MSSQL-specific error occurs during the query execution. ({@link databaseKeyError})
+     *
+     * @returns An array of updated records.
+     *
+     * ### Usage Examples:
+     * @example
+     * ```typescript
+     * // Basic usage
+     * const updatedUser = await userRepository.update({ name: 'John Doe' }, {
+     *   advancedSearch: { id: 1 }
+     * });
+     *
+     * // With advanced filtering
+     * const updatedUsers = await userRepository.update({ status: 'inactive' }, {
+     *   advancedSearch: { role: 'admin' }
+     * });
+     *
+     * // Using a transaction
+     * await knex.transaction(async (trx) => {
+     *   const updatedUser = await userRepository.update({ name: 'John Doe' }, {
+     *       advancedSearch: { id: 1 },
+     *       transaction: trx
+     *   });
+     * });
+     * ```
+     */
+    update<KModel extends TModel = NoInfer<TModel>>(data: Partial<KModel>, options: Omit<QueryOptions<KModel>, 'orderBy' | 'advancedSearch'> & Required<Pick<QueryOptions<KModel>, 'advancedSearch'>>): Promise<KModel[]>;
+    /**
+     * Deletes records from the database based on the specified query options and returns the deleted records.
+     * This method supports advanced search 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. ({@link QueryOptions})
+     *
+     * @throws ({@link CoreError}) Throws an error if an MSSQL-specific error occurs during the query execution. ({@link databaseKeyError})
+     *
+     * @returns An array of deleted records.
+     *
+     * ### Usage Examples:
+     * @example
+     * ```typescript
+     * // Basic usage
+     * const deletedUser = await userRepository.delete({
+     *   advancedSearch: { id: 1 }
+     * });
+     *
+     * // With advanced filtering
+     * const deletedUsers = await userRepository.delete({
+     *   advancedSearch: { status: 'inactive' }
+     * });
+     *
+     * // Using a transaction
+     * await knex.transaction(async (trx) => {
+     *   const deletedUser = await userRepository.delete({
+     *       advancedSearch: { id: 1 },
+     *       transaction: trx
+     *   });
+     * });
+     * ```
+     */
+    delete<KModel extends TModel = NoInfer<TModel>>(options: Omit<QueryOptions<KModel>, 'orderBy' | 'advancedSearch'> & Required<Pick<QueryOptions<KModel>, 'advancedSearch'>>): Promise<KModel[]>;
+    /**
+     * Applies advanced search 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. ({@link Knex.QueryBuilder})
+     * @param search - The advanced search criteria to apply. Can be a single object or an array of objects. ({@link AdvancedSearch})
+     */
+    protected _applySearch<KModel>(query: Knex.QueryBuilder, search: AdvancedSearch<KModel> | AdvancedSearch<KModel>[]): void;
+    /**
+     * Handles errors that occur during query execution. This method centralizes error handling
+     * for MSSQL-specific errors and throws a {@link CoreError} 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 CoreError}) Throws an error if an MSSQL-specific error occurs during the query execution. ({@link databaseKeyError})
+     *
+     * @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 _isComplexQuery;
+    /**
+     * 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 CoreError}) Throws an error if no records are found and the `throwIfNoResult` option is enabled. ({@link databaseKeyError.mssqlNoResult})
+     * @throws ({@link CoreError}) Throws an error if an MSSQL-specific error occurs during the query execution. ({@link databaseKeyError})
+     *
+     * @returns An array of records returned by the query.
+     */
+    protected _executeQuery<KModel>(query: Knex.QueryBuilder, throwIfNoResult?: boolean): Promise<KModel[]>;
+}

package/dist/repository/types/advancedSearch.d.ts

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

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

@@ -0,0 +1,8 @@
+export type * from './advancedSearch';
+export type * from './orderBy';
+export type * from './queryOptions';
+export type * from './queryOptionsExtendPagination';
+export type * from './queryOptionsExtendStream';
+export type * from './selectedFields';
+export type * from './transaction';
+export type * from './whereClause';

package/dist/repository/types/index.js

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

package/dist/repository/types/orderBy.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Represents an ordering instruction for queries.
+ *
+ * This tuple specifies the field to order by and the direction of the ordering.
+ *
+ * @template TModel - The type of the object to order by.
+ *
+ * @example
+ * ```typescript
+ * type User = {
+ *   id: number;
+ *   name: string;
+ * };
+ *
+ * const orderBy: OrderBy<User> = ['id', 'asc'];
+ * ```
+ */
+export type OrderBy<TModel> = [
+    Extract<keyof TModel, string>,
+    'asc' | 'desc'
+];

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

@@ -0,0 +1,33 @@
+import type { AdvancedSearch } from './advancedSearch';
+import type { OrderBy } from './orderBy';
+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 advanced search options to apply to the query. Can be a single object or an array of objects.
+     * @see {@link AdvancedSearch}
+     */
+    advancedSearch?: AdvancedSearch<NoInfer<TModel>> | AdvancedSearch<NoInfer<TModel>>[];
+    /**
+     * The fields to select in the query. If not provided, all fields are selected. ({@link SelectedFields})
+     */
+    selectedFields?: SelectedFields<NoInfer<TModel>>;
+    /**
+     * Order the results by a specific column and direction. ({@link OrderBy})
+     */
+    orderBy?: OrderBy<NoInfer<TModel>>;
+    /**
+     * Whether to throw an error if the query does not return any result.
+     * @defaultValue false
+     */
+    throwIfNoResult?: boolean;
+    /**
+     * The transaction context for the query. ({@link Transaction})
+     */
+    transaction?: Transaction;
+}

package/dist/repository/types/queryOptionsExtendPagination.d.ts

@@ -0,0 +1,21 @@
+import type { QueryOptions } from './queryOptions';
+/**
+ * Extends {@link QueryOptions} to add pagination capabilities for queries.
+ *
+ * @template TModel - The type of the object to retrieve.
+ *
+ * This interface allows specifying pagination options such as limit and offset
+ * in addition to the base query options.
+ */
+export interface QueryOptionsExtendPagination<TModel> extends QueryOptions<TModel> {
+    /**
+     * The limit of the query
+     * @defaultValue 100
+     */
+    limit?: number;
+    /**
+     * The offset of the query
+     * @defaultValue 0
+     */
+    offset?: number;
+}

package/dist/repository/types/queryOptionsExtendStream.d.ts

@@ -0,0 +1,16 @@
+import type { QueryOptions } from './queryOptions';
+/**
+ * Interface Option query with stream option inherited from {@link QueryOptions}
+ *
+ * @template TModel - The type of the object to retrieve.
+ */
+export interface QueryOptionsExtendStream<TModel> extends QueryOptions<TModel> {
+    /**
+     * Transform the chunk before emitting it.
+     *
+     * @param chunk - The chunk to transform.
+     * @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;
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Defines which columns to select in a query using an array of keys from the model type.
+ *
+ * @template TModel - The type of the object to select fields from.
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *     id: number;
+ *     name: string;
+ * }
+ *
+ * const selection: SelectedFields<User> = ['id', 'name'];
+ * ```
+ */
+export type SelectedFields<TModel> = (keyof TModel extends string ? keyof TModel : never)[] | string[];

package/dist/repository/types/transaction.d.ts

@@ -0,0 +1,10 @@
+import type { Knex } from 'knex';
+/**
+ * Represents a database transaction object provided by Knex.
+ *
+ * This type is used to perform a series of database operations as a single unit of work,
+ * ensuring that either all operations succeed or none are applied.
+ *
+ * @see {@link https://knexjs.org/ Knex documentation} for more details on transaction usage. ({@link Knex.Transaction})
+ */
+export type Transaction = Knex.Transaction;

package/dist/repository/types/whereClause.d.ts

@@ -0,0 +1,15 @@
+export interface WhereClause<TValue> {
+    $eq: TValue;
+    $neq: TValue;
+    $lt: TValue;
+    $lte: TValue;
+    $gt: TValue;
+    $gte: TValue;
+    $in: TValue[];
+    $nin: TValue[];
+    $between: [TValue, TValue];
+    $nbetween: [TValue, TValue];
+    $like: string;
+    $nlike: string;
+    $isNull: boolean;
+}

package/dist/store/index.d.ts

@@ -0,0 +1 @@
+export * from './redis';

package/dist/store/index.js

@@ -0,0 +1,2 @@
+// @bun
+import"../chunk-rr6e20n5.js";import{Redis as i}from"ioredis";class t{_client;constructor(e){this._client=new i(e)}get client(){return this._client}}export{t as Redis};export{t as c};

package/dist/store/redis.d.ts

@@ -0,0 +1,6 @@
+import { Redis as IoRedis, type RedisOptions } from 'ioredis';
+export declare class Redis {
+    private readonly _client;
+    constructor(options: RedisOptions);
+    get client(): IoRedis;
+}

package/dist/utils/enums/index.d.ts

@@ -0,0 +1 @@
+export * from './utilKeyError';

package/dist/utils/enums/index.js

@@ -0,0 +1,2 @@
+// @bun
+import{e}from"../../chunk-0pft81dh.js";import"../../chunk-rr6e20n5.js";export{e as utilKeyError};

package/dist/utils/enums/utilKeyError.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Util error key is a list of errors in the util context.
+ * Each property represents a specific util error scenario.
+ */
+export declare const utilKeyError: {
+    /** Error when the environment is invalid. */
+    readonly invalidEnvironment: "core.error.util.invalid_environment";
+};

package/dist/utils/env.d.ts

@@ -0,0 +1,10 @@
+import type { TSchema } from '@sinclair/typebox';
+/**
+ * Validates the environment variables based on the provided schema.
+ *
+ * @param schema - The schema to validate the environment variables against.
+ * @param env - The environment variables to validate. Defaults to `process.env`.
+ *
+ * @throws ({@link CoreError}): If the environment variables are invalid based on the schema. ({@link utilKeyError.invalidEnvironment})
+ */
+export declare const validateEnv: (schema: TSchema, env?: Record<string, unknown>) => void;

package/dist/utils/index.d.ts

@@ -0,0 +1,3 @@
+export * from './env';
+export * from './isIsoDateString';
+export * from './stream';