tspace-mysql 1.9.3 → 1.9.4

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,261 @@ 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.toArray('id',{
+     *       where : {
+     *           id: 1
+     *       }
+     *   })
+     *
+     * // [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 'count' method is used to retrieve the total number of records that match the specified query conditions.
+     *
+     * It returns an integer representing the count of records.
+     * @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 count = await User.count('id',{
+     *       where : {
+     *           id: 1
+     *       }
+     *   })
+     *
+     *  // 1
+     *
+     */
+    static count(column, options = {}) {
+        return (0, Repository_1.Repository)(this).count(column, options);
+    }
+    /**
+     * The 'sum' method is used to retrieve the total number of records that match the specified query conditions.
+     *
+     * It returns an integer representing the sum of records.
+     * @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 sum = await User.sum('id')
+     *
+     *
+     */
+    static sum(column, options = {}) {
+        return (0, Repository_1.Repository)(this).sum(column, options);
+    }
+    /**
+     * The 'avg' method is used to retrieve the total number of records that match the specified query conditions.
+     *
+     * It returns an integer representing the avg of records.
+     * @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 avg = await User.avg('id')
+     *
+     *
+     */
+    static avg(column, options = {}) {
+        return (0, Repository_1.Repository)(this).avg(column, options);
+    }
+    /**
+     * The 'max' method is used to retrieve the total number of records that match the specified query conditions.
+     *
+     * It returns an integer representing the max of records.
+     * @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 max = await User.max('id')
+     *
+     *
+     */
+    static max(column, options = {}) {
+        return (0, Repository_1.Repository)(this).max(column, options);
+    }
+    /**
+     * The 'min' method is used to retrieve the total number of records that match the specified query conditions.
+     *
+     * It returns an integer representing the min of records.
+     * @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 min = await User.min('id')
+     *
+     *
+     */
+    static min(column, options = {}) {
+        return (0, Repository_1.Repository)(this).min(column, 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 +685,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 +701,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 +717,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 +734,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 +750,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 +767,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 +779,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 +881,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 +4647,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]
@@ -4764,10 +5085,7 @@ class Model extends AbstractModel_1.AbstractModel {
             columns[key] = `( ${updateColumns[key].join(" ")} )`;
         }
         const keyValue = Object.entries(columns).map(([column, value]) => {
-            if (typeof value === "string" &&
-                !value.includes(this.$constants("RAW"))) {
-                value = this.$utils.escapeActions(value);
-            }
+            value = this.$utils.escapePayload(value);
             return `${this.bindColumn(column)} = ${value == null || value === this.$constants("NULL")
                 ? this.$constants("NULL")
                 : this.$utils.transfromValueHasRaw(value)}`;
@@ -5013,6 +5331,7 @@ class Model extends AbstractModel_1.AbstractModel {
             throw this._assertError("Unknow table.");
         }
         const schemaModel = this.getSchemaModel();
+        await this.sync({ force: true, index: true, foreign: true }).catch(() => null);
         const fields = schemaModel == null
             ? await this.getSchema()
             : Object.entries(schemaModel)
@@ -5969,10 +6288,7 @@ class Model extends AbstractModel_1.AbstractModel {
             });
         }
         const keyValue = Object.entries(objects).map(([column, value]) => {
-            if (typeof value === "string" &&
-                !value.includes(this.$constants("RAW"))) {
-                value = this.$utils.escapeActions(value);
-            }
+            value = this.$utils.escapePayload(value);
             return `${this.bindColumn(column)} = ${value == null || value === this.$constants("NULL")
                 ? this.$constants("NULL")
                 : this.$utils.transfromValueHasRaw(value)}`;
@@ -6015,10 +6331,7 @@ class Model extends AbstractModel_1.AbstractModel {
         }
         const columns = Object.keys(data).map((c) => `\`${this._valuePattern(c).replace(/\`/g, "")}\``);
         const values = Object.values(data).map((value) => {
-            if (typeof value === "string" &&
-                !value.includes(this.$constants("RAW"))) {
-                value = this.$utils.escapeActions(value);
-            }
+            value = this.$utils.escapePayload(value);
             if (this.$utils.typeOf(value) === "object" ||
                 this.$utils.typeOf(value) === "array") {
                 value = JSON.stringify(value);
@@ -6073,10 +6386,7 @@ class Model extends AbstractModel_1.AbstractModel {
                 columns = [`\`${uuidFormat}\``, ...columns];
             }
             const v = Object.values(objects).map((value) => {
-                if (typeof value === "string" &&
-                    !value.includes(this.$constants("RAW"))) {
-                    value = this.$utils.escapeActions(value);
-                }
+                value = this.$utils.escapePayload(value);
                 if (this.$utils.typeOf(value) === "object" ||
                     this.$utils.typeOf(value) === "array") {
                     value = JSON.stringify(value);