tspace-mysql 1.9.2 → 1.9.3-beta.2

package/dist/lib/core/Model.d.ts

@@ -64,6 +64,7 @@ declare class Model<TS extends Record<string, any> = any, TR = unknown, TA exten
     static get table(): string | null;
     /**
      * The 'formatPattern' method is used to change the format of the pattern.
+     * @static
      * @param {object} data { data , pattern }
      * @property {Record | string} data
      * @property {string} parttern
@@ -75,6 +76,7 @@ declare class Model<TS extends Record<string, any> = any, TR = unknown, TA exten
     }): T;
     /**
      * The 'instance' method is used get instance.
+     * @static
      * @override
      * @static
      * @returns {Model} instance of the Model
@@ -93,6 +95,7 @@ declare class Model<TS extends Record<string, any> = any, TR = unknown, TA exten
      * The 'find' method is used to retrieve a single record from a database table by its primary key.
      *
      * It allows you to retrieve a single record from a database table that meets the specified criteria.
+     * @static
      * @type     {?object}  options
      * @property {?object} options.select
      * @property {?object} options.except
@@ -131,6 +134,7 @@ declare class Model<TS extends Record<string, any> = any, TR = unknown, TA exten
      * The 'findOne' method is used to retrieve the get record that matches the query conditions.
      *
      * It allows you to retrieve a single record from a database table that meets the specified criteria.
+     * @static
      * @type     {?object}  options
      * @property {?object} options.select
      * @property {?object} options.except
@@ -169,6 +173,7 @@ declare class Model<TS extends Record<string, any> = any, TR = unknown, TA exten
      * The 'findMany' method is used to retrieve the get record that matches the query conditions.
      *
      * It allows you to retrieve a single record from a database table that meets the specified criteria.
+     * @static
      * @type     {?object}  options
      * @property {?object} options.select
      * @property {?object} options.except
@@ -208,6 +213,7 @@ declare class Model<TS extends Record<string, any> = any, TR = unknown, TA exten
      *
      * It allows you to split a large set of query results into smaller, more manageable pages,
      * making it easier to display data in a web application and improve user experience.
+     * @static
      * @type     {?object}  options
      * @property {?object} options.select
      * @property {?object} options.except
@@ -249,6 +255,7 @@ declare class Model<TS extends Record<string, any> = any, TR = unknown, TA exten
      * The 'exists' method is used to determine if any records exist in the database table that match the query conditions.
      *
      * It returns a boolean value indicating whether there are any matching records.
+     * @static
      * @type     {?object}  options
      * @property {?object} options.select
      * @property {?object} options.except
@@ -277,11 +284,46 @@ declare class Model<TS extends Record<string, any> = any, TR = unknown, TA exten
      *   })
      *
      */
-    static exists<Self extends Model, M extends Model = Self>(this: new () => Self, options: Partial<Omit<T.RepositoryOptions<M>, "relations" | "relationQuery">>): Promise<boolean>;
+    static exists<Self extends Model, M extends Model = Self>(this: new () => Self, options: Partial<Omit<T.RepositoryOptions<M>, "relations" | "relationsExists" | "relationQuery">>): Promise<boolean>;
     /**
      * The 'toQuery' method is used to retrieve the raw SQL query that would be executed by a query builder instance without actually executing it.
      *
      * This method is particularly useful for debugging and understanding the SQL queries generated by your application.
+     * @static
+     * @type     {?object}  options
+     * @property {?object} options.select
+     * @property {?object} options.except
+     * @property {?object[]} options.orderBy
+     * @property {?string[]} options.groupBy
+     * @property {?string} options.having
+     * @property {?number} options.limit
+     * @property {?number} options.offset
+     * @property {?object} options.where
+     * @property {?string[]} options.whereRaw
+     * @property {?object} options.whereQuery
+     * @property {?{condition,callback}} options.when
+     * @property {?{localKey , referenceKey}[]} options.join
+     * @property {?{localKey , referenceKey}[]} options.rightJoin
+     * @property {?{localKey , referenceKey}[]} options.leftJoin
+     * @property {?boolean} options.debug
+     * @property {?number} options.page
+     *
+     * @example
+     *  import { User } from '../Models/User'
+     *
+     *  const users = await User.exists({
+     *       where : {
+     *           id: 1
+     *       }
+     *   })
+     *
+     */
+    static toQuery<Self extends Model, M extends Model = Self>(this: new () => Self, options: Partial<Omit<T.RepositoryOptions<M>, "relations" | "relationsExists" | "relationQuery">>): string;
+    /**
+     * The 'toArray' method is used to retrieve the raw SQL query that would be executed by a query builder instance without actually executing it.
+     *
+     * This method is particularly useful for debugging and understanding the SQL queries generated by your application.
+     * @static
      * @type     {?object}  options
      * @property {?object} options.select
      * @property {?object} options.except
@@ -310,11 +352,52 @@ declare class Model<TS extends Record<string, any> = any, TR = unknown, TA exten
      *   })
      *
      */
-    static toQuery<Self extends Model, M extends Model = Self>(this: new () => Self, options: Partial<Omit<T.RepositoryOptions<M>, "relations" | "relationQuery">>): string;
+    static toArray<Self extends Model, K extends T.ColumnKeys<M> | `${string}.${string}`, M extends Model = Self>(this: new () => Self, column: K, options?: Partial<Omit<T.RepositoryOptions<M>, "relations" | "relationsExists" | "relationQuery">>): Promise<(K extends keyof T.Result<M> ? T.Result<M>[K] : unknown)[]>;
+    /**
+     *
+     * The 'toAsyncIterable' method is used to execute a database query and return the result set as an asynchronous iterable.
+     *
+     * It retrieves multiple records from a database table based on the criteria specified in the query.
+     * The optional callback function can be used to modify the generated SQL query before execution.
+     * @static
+     * @type     {?object}  options
+     * @property {?object} options.select
+     * @property {?object} options.except
+     * @property {?object[]} options.orderBy
+     * @property {?string[]} options.groupBy
+     * @property {?string} options.having
+     * @property {?number} options.limit
+     * @property {?number} options.offset
+     * @property {?object} options.where
+     * @property {?string[]} options.whereRaw
+     * @property {?object} options.whereQuery
+     * @property {?{condition,callback}} options.when
+     * @property {?{localKey , referenceKey}[]} options.join
+     * @property {?{localKey , referenceKey}[]} options.rightJoin
+     * @property {?{localKey , referenceKey}[]} options.leftJoin
+     * @property {?string[]} options.relations
+     * @property {string[]} options.relationExists
+     * @property {?{condition,callback}} options.relationQuery
+     * @property {?boolean} options.debug
+     * @returns {promise<object>[]}
+     *
+     * @example
+     * import { User } from '../Models/User'
+     *
+     * const users = await User.findMany({
+     *       select : { id: true, name: true },
+     *       where : {
+     *           id: 1
+     *       }
+     *   })
+     *
+     */
+    static toAsyncIterable<Self extends Model, M extends Model = Self, S extends T.SelectOptions<M> | undefined = undefined, SR extends T.RelationOptions<M> | undefined = undefined, E extends T.ExceptOptions<M> | undefined = undefined, SRS extends Record<string, TRawStringQuery> | undefined = undefined, G extends Record<string, T.RepositoryGenericTypeOptions> | undefined = {}>(this: new () => Self, options?: T.RepositoryOptions<M, S, SR, E, SRS, G>): AsyncIterable<T.ResultFiltered<M, S, SR, E, SRS, G>>;
     /**
      * The 'create' method is used to insert a new record into a database table associated.
      *
      * It simplifies the process of creating and inserting records.
+     * @static
      * @type     {object}  options
      * @property {object} options.data
      * @property {?boolean} options.debug
@@ -326,6 +409,7 @@ declare class Model<TS extends Record<string, any> = any, TR = unknown, TA exten
      * The 'createMany' method is used to insert a new records into a database table associated.
      *
      * It simplifies the process of creating and inserting records with an array.
+     * @static
      * @type     {object}  options
      * @property {object[]} options.data
      * @property {?boolean} options.debug
@@ -339,6 +423,7 @@ declare class Model<TS extends Record<string, any> = any, TR = unknown, TA exten
      *
      * This method is particularly useful when you want to update a record based on certain conditions and,
      * if the record matching those conditions doesn't exist, create a new one with the provided data.
+     * @static
      * @type     {object}  options
      * @property {object} options.data
      * @property {object} options.where
@@ -351,7 +436,7 @@ declare class Model<TS extends Record<string, any> = any, TR = unknown, TA exten
      *
      * This method is particularly useful when you want to insert records into a table and ensure that duplicates are not inserted,
      * but without raising an error or exception if duplicates are encountered.
-     *
+     * @static
      * @type     {object}  options
      * @property {object} options.data
      * @property {object} options.where
@@ -366,6 +451,7 @@ declare class Model<TS extends Record<string, any> = any, TR = unknown, TA exten
      *
      * This method is particularly useful when you want to insert records into a table and ensure that duplicates are not inserted,
      * but if exists should be returns a result.
+     * @static
      * @type     {object}  options
      * @property {object} options.data
      * @property {object} options.where
@@ -379,6 +465,7 @@ declare class Model<TS extends Record<string, any> = any, TR = unknown, TA exten
      * It simplifies the process of updating records by allowing you to specify the values to be updated using a single call.
      *
      * It allows you to remove one record that match certain criteria.
+     * @static
      * @type     {object} options
      * @property {object} options.data
      * @property {object} options.where
@@ -393,6 +480,7 @@ declare class Model<TS extends Record<string, any> = any, TR = unknown, TA exten
      * It simplifies the process of updating records by allowing you to specify the values to be updated using a single call.
      *
      * It allows you to remove more records that match certain criteria.
+     * @static
      * @type     {object} options
      * @property {object} options.data
      * @property {object} options.where
@@ -402,8 +490,52 @@ declare class Model<TS extends Record<string, any> = any, TR = unknown, TA exten
      */
     static updateMany<Self extends Model, M extends Model = Self, NR extends boolean | undefined = false>(this: new () => Self, options: T.RepositoryUpdate<M, NR>): Promise<NR extends true ? undefined : T.Result<M>[]>;
     /**
-     * The 'cache' method is used get the functions from the Cache
-     * @returns {TCacheModel} cache
+     * The 'cache' method is used to access to cache operations for the current model.
+     *
+     * The cache API exposes methods for retrieving the configured cache provider,
+     * selecting a cache driver, managing cache entries, and optionally generating
+     * model-scoped cache keys.
+     *
+     * When the `namespace` option is enabled, cache keys are automatically prefixed
+     * with the current database and table name in the following format:
+     *
+     * `database:table:key`
+     *
+     * This helps prevent cache key collisions between different models or tables.
+     * @static
+     * @returns {TCacheModel} An object containing cache provider, driver, and cache management methods.
+     *
+     * @example
+     * // Get the configured cache provider.
+     * const provider = User.cache.provider(); // "db" | "memory" | "redis"
+     *
+     * @example
+     * // Store a value using a model-scoped cache key.
+     * await User.cache.set("users", users, 60_000, {
+     *   namespace: true
+     * });
+     *
+     * @example
+     * // Retrieve a model-scoped cache value.
+     * const users = await User.cache.get("users", {
+     *   namespace: true
+     * });
+     *
+     * @example
+     * // Check whether a cache entry exists.
+     * const exists = await User.cache.exists("users", {
+     *   namespace: true
+     * });
+     *
+     * @example
+     * // Delete a cache entry.
+     * await User.cache.delete("users", {
+     *   namespace: true
+     * });
+     *
+     * @example
+     * // Clear all cache entries.
+     * await User.cache.clear();
      */
     static get cache(): TCacheModel;
     /**
@@ -428,6 +560,7 @@ declare class Model<TS extends Record<string, any> = any, TR = unknown, TA exten
      * - DELETE: waits
      *
      * The lock is released automatically after the callback completes.
+     * @static
      *
      * @Note
      * This approach is not recommended in clustered or load-balance environments,
@@ -1941,8 +2074,8 @@ declare class Model<TS extends Record<string, any> = any, TR = unknown, TA exten
      * @param {Object} columns
      * @returns {this}
      */
-    whereObject<K extends T.ColumnKeys<this>, T extends T.ColumnOptions<this>>(columns: {
-        [P in K & keyof T]: T[P];
+    whereObject<K extends T.ColumnKeys<this>, CO extends T.ColumnOptions<this>>(columns: {
+        [P in K & keyof CO]: CO[P];
     }): this;
     /**
      * @override
@@ -1991,28 +2124,28 @@ declare class Model<TS extends Record<string, any> = any, TR = unknown, TA exten
      * @param {array} array
      * @returns {this}
      */
-    whereIn<K extends T.ColumnKeys<this>>(column: K, array: any[]): this;
+    whereIn<K extends T.ColumnKeys<this>, V extends T.ColumnValue<this, K>>(column: K, array: V[]): this;
     /**
      * @override
      * @param {string} column
      * @param {array} array
      * @returns {this}
      */
-    orWhereIn<K extends T.ColumnKeys<this>>(column: K, array: any[]): this;
+    orWhereIn<K extends T.ColumnKeys<this>, V extends T.ColumnValue<this, K>>(column: K, array: V[]): this;
     /**
      * @override
      * @param {string} column
      * @param {array} array
      * @returns {this}
      */
-    whereNotIn<K extends T.ColumnKeys<this>>(column: K, array: any[]): this;
+    whereNotIn<K extends T.ColumnKeys<this>, V extends T.ColumnValue<this, K>>(column: K, array: V[]): this;
     /**
      * @override
      * @param {string} column
      * @param {array} array
      * @returns {this}
      */
-    orWhereNotIn<K extends T.ColumnKeys<this>>(column: K, array: any[]): this;
+    orWhereNotIn<K extends T.ColumnKeys<this>, V extends T.ColumnValue<this, K>>(column: K, array: V[]): this;
     /**
      * @override
      * @param {string} column
@@ -2381,6 +2514,13 @@ declare class Model<TS extends Record<string, any> = any, TR = unknown, TA exten
         latest?: boolean;
         oldest?: boolean;
     }): string;
+    /**
+     *
+     * @override
+     * @param {Function?} cb callback function return query sql
+     * @returns {AsyncIterable<T.Result<this, K>>}
+     */
+    toAsyncIterable<K>(cb?: Function): AsyncIterable<T.Result<this, K>>;
     /**
      * @override
      * @param {string=} column [column=id]
@@ -2493,27 +2633,27 @@ declare class Model<TS extends Record<string, any> = any, TR = unknown, TA exten
      * @param {object} data for insert
      * @returns {this} this
      */
-    insert<K extends T.ColumnKeys<this>, C extends T.ColumnOptions<this>>(data: T.InsertInput<K, C>): Model<TS, TR, "create">;
+    insert<K extends T.ColumnKeys<this>, C extends T.InputOptions<this>>(data: T.InsertInput<K, C>): Model<TS, TR, "create">;
     /**
      * @override
      * @param {object} data for insert
      * @returns {this} this
      */
-    create<K extends T.ColumnKeys<this>, C extends T.ColumnOptions<this>>(data: T.InsertInput<K, C>): Model<TS, TR, "create">;
+    create<K extends T.ColumnKeys<this>, C extends T.InputOptions<this>>(data: T.InsertInput<K, C>): Model<TS, TR, "create">;
     /**
      * @override
      * @param {object} data
      * @param {array?} updateNotExists options for except update some records in your ${data}
      * @returns {this} this
      */
-    update<K extends T.ColumnKeys<this>, C extends T.ColumnOptions<this>>(data: T.UpdateInput<K, C>, updateNotExists?: T.ColumnKeys<this>[]): Model<TS, TR, "update">;
+    update<K extends T.ColumnKeys<this>, C extends T.InputOptions<this>>(data: T.UpdateInput<K, C>, updateNotExists?: T.ColumnKeys<this>[]): Model<TS, TR, "update">;
     /**
      * @override
      * @param {object} data
      * @param {array?} updateNotExists options for except update some records in your ${data}
      * @returns {this} this
      */
-    updateMany<K extends T.ColumnKeys<this>, C extends T.ColumnOptions<this>>(data: T.UpdateInput<K, C>, updateNotExists?: string[]): Model<TS, TR, "updateMany">;
+    updateMany<K extends T.ColumnKeys<this>, C extends T.InputOptions<this>>(data: T.UpdateInput<K, C>, updateNotExists?: string[]): Model<TS, TR, "updateMany">;
     /**
      *
      * @override
@@ -2526,7 +2666,7 @@ declare class Model<TS extends Record<string, any> = any, TR = unknown, TA exten
      * @property {Record<string,string | number | boolean | null | undefined>}  cases.columns
      * @returns {this} this
      */
-    updateCases<T extends T.ColumnOptions<this>, K extends keyof T, U extends Model | unknown, M = U extends this ? this : U extends Model ? U : this>(cases: {
+    updateCases<T extends T.InputOptions<this>, K extends keyof T, U extends Model | unknown, M = U extends this ? this : U extends Model ? U : this>(cases: {
         condition: ((query: M) => M) | Partial<{
             [P in K & keyof T]: Extract<T[P], Record<string, unknown>> extends never ? T[P] : string;
         }>;
@@ -2539,84 +2679,84 @@ declare class Model<TS extends Record<string, any> = any, TR = unknown, TA exten
      * @param {object} data
      * @returns {this} this
      */
-    updateNotExists<K extends T.ColumnKeys<this>, C extends T.ColumnOptions<this>>(data: T.UpdateInput<K, C>): Model<TS, TR, "update">;
+    updateNotExists<K extends T.ColumnKeys<this>, C extends T.InputOptions<this>>(data: T.UpdateInput<K, C>): Model<TS, TR, "update">;
     /**
      * @override
      * @param {object} data for update or create
      * @returns {this} this
      */
-    updateOrCreate<K extends T.ColumnKeys<this>, C extends T.ColumnOptions<this>>(data: T.InsertOrUpdateInput<K, C>): Model<TS, TR, "createOrUpdate">;
+    updateOrCreate<K extends T.ColumnKeys<this>, C extends T.InputOptions<this>>(data: T.InsertOrUpdateInput<K, C>): Model<TS, TR, "createOrUpdate">;
     /**
      * @override
      * @param {object} data for update or create
      * @returns {this} this
      */
-    updateOrInsert<K extends T.ColumnKeys<this>, C extends T.ColumnOptions<this>>(data: T.InsertOrUpdateInput<K, C>): Model<TS, TR, "createOrUpdate">;
+    updateOrInsert<K extends T.ColumnKeys<this>, C extends T.InputOptions<this>>(data: T.InsertOrUpdateInput<K, C>): Model<TS, TR, "createOrUpdate">;
     /**
      * @override
      * @param {object} data for update or create
      * @returns {this} this
      */
-    insertOrUpdate<K extends T.ColumnKeys<this>, C extends T.ColumnOptions<this>>(data: T.InsertOrUpdateInput<K, C>): Model<TS, TR, "createOrUpdate">;
+    insertOrUpdate<K extends T.ColumnKeys<this>, C extends T.InputOptions<this>>(data: T.InsertOrUpdateInput<K, C>): Model<TS, TR, "createOrUpdate">;
     /**
      * @override
      * @param {object} data for update or create
      * @returns {this} this
      */
-    createOrUpdate<K extends T.ColumnKeys<this>, C extends T.ColumnOptions<this>>(data: T.InsertOrUpdateInput<K, C>): Model<TS, TR, "createOrUpdate">;
+    createOrUpdate<K extends T.ColumnKeys<this>, C extends T.InputOptions<this>>(data: T.InsertOrUpdateInput<K, C>): Model<TS, TR, "createOrUpdate">;
     /**
      * @override
      * @param {object} data for create
      * @returns {this} this
      */
-    createOrSelect<K extends T.ColumnKeys<this>, C extends T.ColumnOptions<this>>(data: T.InsertInput<K, C>): Model<TS, TR, "createOrSelect">;
+    createOrSelect<K extends T.ColumnKeys<this>, C extends T.InputOptions<this>>(data: T.InsertInput<K, C>): Model<TS, TR, "createOrSelect">;
     /**
      * @override
      * @param {object} data for update or create
      * @returns {this} this
      */
-    insertOrSelect<K extends T.ColumnKeys<this>, C extends T.ColumnOptions<this>>(data: T.InsertInput<K, C>): Model<TS, TR, "createOrSelect">;
+    insertOrSelect<K extends T.ColumnKeys<this>, C extends T.InputOptions<this>>(data: T.InsertInput<K, C>): Model<TS, TR, "createOrSelect">;
     /**
      *
      * @override
      * @param {object} data create not exists data
      * @returns {this} this
      */
-    createNotExists<K extends T.ColumnKeys<this>, C extends T.ColumnOptions<this>>(data: T.InsertInput<K, C>): Model<TS, TR, "createNotExists">;
+    createNotExists<K extends T.ColumnKeys<this>, C extends T.InputOptions<this>>(data: T.InsertInput<K, C>): Model<TS, TR, "createNotExists">;
     /**
      *
      * @override
      * @param {object} data create not exists data
      * @returns {this} this this
      */
-    insertNotExists<K extends T.ColumnKeys<this>, C extends T.ColumnOptions<this>>(data: T.InsertInput<K, C>): Model<TS, TR, "createNotExists">;
+    insertNotExists<K extends T.ColumnKeys<this>, C extends T.InputOptions<this>>(data: T.InsertInput<K, C>): Model<TS, TR, "createNotExists">;
     /**
      * @override
      * @param {Record<string,any>[]} data create multiple data
      * @returns {this} this this
      */
-    createMultiple<K extends T.ColumnKeys<this>, C extends T.ColumnOptions<this>>(data: T.InsertInput<K, C>[]): Model<TS, TR, "createMany">;
+    createMultiple<K extends T.ColumnKeys<this>, C extends T.InputOptions<this>>(data: T.InsertInput<K, C>[]): Model<TS, TR, "createMany">;
     /**
      *
      * @override
      * @param {Record<string,any>[]} data create multiple data
      * @returns {this} this
      */
-    createMany<K extends T.ColumnKeys<this>, C extends T.ColumnOptions<this>>(data: T.InsertInput<K, C>[]): Model<TS, TR, "createMany">;
+    createMany<K extends T.ColumnKeys<this>, C extends T.InputOptions<this>>(data: T.InsertInput<K, C>[]): Model<TS, TR, "createMany">;
     /**
      *
      * @override
      * @param {Record<string,any>[]} data create multiple data
      * @returns {this} this
      */
-    insertMultiple<K extends T.ColumnKeys<this>, C extends T.ColumnOptions<this>>(data: T.InsertInput<K, C>[]): Model<TS, TR, "createMany">;
+    insertMultiple<K extends T.ColumnKeys<this>, C extends T.InputOptions<this>>(data: T.InsertInput<K, C>[]): Model<TS, TR, "createMany">;
     /**
      *
      * @override
      * @param {Record<string,any>[]} data create multiple data
      * @returns {this} this
      */
-    insertMany<K extends T.ColumnKeys<this>, C extends T.ColumnOptions<this>>(data: T.InsertInput<K, C>[]): Model<TS, TR, "createMany">;
+    insertMany<K extends T.ColumnKeys<this>, C extends T.InputOptions<this>>(data: T.InsertInput<K, C>[]): Model<TS, TR, "createMany">;
     /**
      * The 'getSchemaModel' method is used get a schema model
      * @returns {Record<string, Blueprint> | null} Record<string, Blueprint> | null