tspace-mysql 1.9.2 → 1.9.3-beta.2

package/dist/lib/core/Model.js

@@ -136,6 +136,7 @@ class Model extends AbstractModel_1.AbstractModel {
     }
     /**
      * 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
@@ -159,6 +160,7 @@ class Model extends AbstractModel_1.AbstractModel {
     }
     /**
      * The 'instance' method is used get instance.
+     * @static
      * @override
      * @static
      * @returns {Model} instance of the Model
@@ -181,6 +183,7 @@ class Model extends AbstractModel_1.AbstractModel {
      * 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
@@ -221,6 +224,7 @@ class Model extends AbstractModel_1.AbstractModel {
      * 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
@@ -261,6 +265,7 @@ class Model extends AbstractModel_1.AbstractModel {
      * 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
@@ -302,6 +307,7 @@ class Model extends AbstractModel_1.AbstractModel {
      *
      * 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
@@ -343,6 +349,7 @@ class Model extends AbstractModel_1.AbstractModel {
      * 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
@@ -378,6 +385,7 @@ class Model extends AbstractModel_1.AbstractModel {
      * 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
@@ -409,10 +417,89 @@ class Model extends AbstractModel_1.AbstractModel {
     static toQuery(options) {
         return (0, Repository_1.Repository)(this).toString(options);
     }
+    /**
+     * 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
+     * @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 toArray(column, options = {}) {
+        return (0, Repository_1.Repository)(this).toArray(column, options);
+    }
+    /**
+     *
+     * 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 async *toAsyncIterable(options = {}) {
+        return yield* (0, Repository_1.Repository)(this).toAsyncIterable(options);
+    }
     /**
      * 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
@@ -426,6 +513,7 @@ class Model extends AbstractModel_1.AbstractModel {
      * 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
@@ -441,6 +529,7 @@ class Model extends AbstractModel_1.AbstractModel {
      *
      * 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
@@ -456,7 +545,7 @@ class Model extends AbstractModel_1.AbstractModel {
      *
      * 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
@@ -473,6 +562,7 @@ class Model extends AbstractModel_1.AbstractModel {
      *
      * 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
@@ -488,6 +578,7 @@ class Model extends AbstractModel_1.AbstractModel {
      * 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
@@ -504,6 +595,7 @@ class Model extends AbstractModel_1.AbstractModel {
      * 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
@@ -515,8 +607,52 @@ class Model extends AbstractModel_1.AbstractModel {
         return (0, Repository_1.Repository)(this).updateMany(options);
     }
     /**
-     * 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() {
         const getCacheKey = (key) => {
@@ -573,6 +709,7 @@ class Model extends AbstractModel_1.AbstractModel {
      * - DELETE: waits
      *
      * The lock is released automatically after the callback completes.
+     * @static
      *
      * @Note
      * This approach is not recommended in clustered or load-balance environments,
@@ -4338,6 +4475,18 @@ class Model extends AbstractModel_1.AbstractModel {
     toSQL({ latest = false, oldest = false, } = {}) {
         return this.toString({ latest, oldest });
     }
+    /**
+     *
+     * @override
+     * @param {Function?} cb callback function return query sql
+     * @returns {AsyncIterable<T.Result<this, K>>}
+     */
+    async *toAsyncIterable(cb) {
+        if (this.$state.get("VOID"))
+            return yield* [];
+        const results = await this.get(cb);
+        return yield* results;
+    }
     /**
      * @override
      * @param {string=} column [column=id]
@@ -5946,7 +6095,7 @@ class Model extends AbstractModel_1.AbstractModel {
         }
         await this.$utils.hookHandle(this.$state.get("HOOKS"), result);
         await this._observer(result, "selected");
-        this._setCache(result);
+        await this._setCache(result);
         return result;
     }
     async _queryUpdateModel() {