@libs-ui/utils 0.2.245 → 0.2.247

package/fesm2022/libs-ui-utils.mjs

@@ -405,12 +405,44 @@ class UtilsHttpParamsRequest extends HttpParams {
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
 /**Các hàm tương tự thư viện lodash */
+/**
+ * Kiểm tra xem một giá trị có phải là null hoặc undefined hay không
+ * @param value Giá trị cần kiểm tra
+ * @returns true nếu giá trị là null hoặc undefined, false nếu không
+ * @example
+ * isNil(null); // true
+ * isNil(undefined); // true
+ * isNil(0); // false
+ * isNil('hello'); // false
+ */
 const isNil = (value) => {
     return value === null || value === undefined;
 };
+/**
+ * Kiểm tra xem một giá trị có phải là rỗng hay không
+ * @param value Giá trị cần kiểm tra
+ * @returns true nếu giá trị là null, rỗng hoặc undefined, false nếu không
+ * @example
+ * isEmpty(null); // true
+ * isEmpty(''); // true
+ * isEmpty(undefined); // true
+ * isEmpty({}); // true
+ * isEmpty([]); // true
+ * isEmpty([1, 2, 3]); // false
+ * isEmpty({ a: 1 }); // false
+ */
 const isEmpty = (value) => {
     return value === null || value === '' || value === undefined || (typeof value === 'object' && (JSON.stringify(value) === '{}' || JSON.stringify(value) === '[]'));
 };
+/**
+ * Loại bỏ các thuộc tính của đối tượng dựa trên một hàm điều kiện
+ * @param objData Đối tượng cần xử lý
+ * @param predicate Hàm điều kiện để kiểm tra giá trị của thuộc tính. Nếu hàm trả về true thì thuộc tính đó sẽ bị loại bỏ
+ * @returns Đối tượng mới sau khi đã loại bỏ các thuộc tính thỏa mãn điều kiện
+ * @example
+ * const obj = { a: 1, b: null, c: 3, d: undefined };
+ * omitBy(obj, isNil); // { a: 1, c: 3 }
+ */
 const omitBy = (objData, predicate) => {
     if (!objData || typeof objData !== 'object' || Array.isArray(objData)) {
         return objData;
@@ -459,6 +491,17 @@ const get = (obj, path, defaultValue = undefined, keepLastValueIfSignal) => {
     }
     return obj;
 };
+/**
+ * Thiết lập giá trị cho một thuộc tính trong đối tượng theo đường dẫn chỉ định
+ * @param obj Đối tượng cần thiết lập giá trị
+ * @param path Đường dẫn đến thuộc tính, có thể là chuỗi (vd: 'a.b.c') hoặc mảng (vd: ['a', 'b', 'c'])
+ * @param value Giá trị cần thiết lập
+ * @returns Đối tượng sau khi đã thiết lập giá trị
+ * @throws Error nếu tham số đầu tiên không phải là đối tượng
+ * @example
+ * const obj = { a: { b: 1 } };
+ * set(obj, 'a.b', 2); // { a: { b: 2 } }
+ */
 const set = (obj, path, value) => {
     if (!obj || (typeof obj !== "object" && !isSignal(obj)) || (isSignal(obj) && typeof obj() !== "object")) {
         throw new Error("The first argument must be an object");
@@ -503,7 +546,23 @@ const set = (obj, path, value) => {
     });
     return obj;
 };
-const cloneDeep = (data, seen = new WeakMap()) => {
+/**
+ * Tạo một bản sao sâu của một đối tượng hoặc giá trị bất kỳ
+ * @param data Dữ liệu cần sao chép
+ * @param options Tùy chọn cấu hình
+ * @param options.ignoreSignal Nếu true, sẽ không sao chép các signal mà trả về signal gốc
+ * @param seen WeakMap để theo dõi các tham chiếu đã được sao chép, tránh lặp vô hạn với các tham chiếu vòng
+ * @returns Bản sao sâu của dữ liệu đầu vào
+ * @example
+ * const obj = {
+ *   a: 1,
+ *   b: { c: 2 },
+ *   d: [1, 2, 3]
+ * };
+ * const clone = cloneDeep(obj);
+ * // clone là một bản sao hoàn toàn độc lập của obj
+ */
+const cloneDeep = (data, options = { ignoreSignal: false }, seen = new WeakMap()) => {
     if (data === null || (typeof data !== 'object' && !isSignal(data))) {
         return data;
     }
@@ -523,7 +582,7 @@ const cloneDeep = (data, seen = new WeakMap()) => {
         const mapCopy = new Map();
         seen.set(data, mapCopy);
         data.forEach((val, key) => {
-            mapCopy.set(cloneDeep(key, seen), cloneDeep(val, seen));
+            mapCopy.set(cloneDeep(key, options, seen), cloneDeep(val, options, seen));
         });
         return mapCopy;
     }
@@ -531,12 +590,12 @@ const cloneDeep = (data, seen = new WeakMap()) => {
         const setCopy = new Set();
         seen.set(data, setCopy);
         data.forEach(val => {
-            setCopy.add(cloneDeep(val, seen));
+            setCopy.add(cloneDeep(val, options, seen));
         });
         return setCopy;
     }
     if (Array.isArray(data)) {
-        seen.set(data, data.map(item => cloneDeep(item, seen)));
+        seen.set(data, data.map(item => cloneDeep(item, options, seen)));
         return seen.get(data);
     }
     if (data instanceof File || data instanceof Blob || Object.prototype.toString.call(data) === '[object File]') {
@@ -546,7 +605,10 @@ const cloneDeep = (data, seen = new WeakMap()) => {
         return data;
     }
     if (isSignal(data)) {
-        seen.set(data, signal(cloneDeep(data(), seen)));
+        if (options?.ignoreSignal) {
+            return data;
+        }
+        seen.set(data, signal(cloneDeep(data(), options, seen)));
         return seen.get(data);
     }
     const result = {};
@@ -562,11 +624,27 @@ const cloneDeep = (data, seen = new WeakMap()) => {
             continue;
         }
         if (Object.prototype.hasOwnProperty.call(data, key)) {
-            result[key] = cloneDeep(value, seen);
+            result[key] = cloneDeep(value, options, seen);
         }
     }
     return result;
 };
+/**
+ * Chuyển đổi một mảng các đối tượng thành một đối tượng với khóa được chỉ định
+ * @param data Mảng các đối tượng cần chuyển đổi
+ * @param key Tên thuộc tính được sử dụng làm khóa trong đối tượng kết quả
+ * @returns Đối tượng với các giá trị từ mảng được đánh key theo thuộc tính đã chỉ định
+ * @example
+ * const data = [
+ *   { id: 1, name: 'John' },
+ *   { id: 2, name: 'Jane' }
+ * ];
+ * keyBy(data, 'id');
+ * // Kết quả: {
+ * //   '1': { id: 1, name: 'John' },
+ * //   '2': { id: 2, name: 'Jane' }
+ * // }
+ */
 const keyBy = (data, key) => {
     if (!data || !data.length || !key) {
         return {};
@@ -580,6 +658,27 @@ const keyBy = (data, key) => {
         return dir;
     }, {});
 };
+/**
+ * Nhóm các đối tượng trong một mảng thành các nhóm dựa trên một thuộc tính cụ thể
+ * @param data Mảng các đối tượng cần nhóm
+ * @param key Tên thuộc tính được sử dụng làm khóa nhóm
+ * @returns Đối tượng với các giá trị từ mảng được nhóm theo thuộc tính đã chỉ định
+ * @example
+ * const data = [
+ *   { id: 1, name: 'John' },
+ *   { id: 2, name: 'Jane' },
+ *   { id: 1, name: 'John' }
+ * ];
+ * groupBy(data, 'id');
+ * // Kết quả: {
+ * //   '1': [
+ * //     { id: 1, name: 'John' },
+ * //     { id: 1, name: 'John' }
+ * //   ],
+ * //   '2': [
+ * //     { id: 2, name: 'Jane' }
+ * // }
+ */
 const groupBy = (data, key) => {
     if (!data || !Object.keys(data).length || !key) {
         return {};
@@ -596,6 +695,18 @@ const groupBy = (data, key) => {
         return dir;
     }, {});
 };
+/**
+ * Tạo một mảng các số từ giá trị bắt đầu đến giá trị kết thúc với bước nhảy tùy chọn
+ * @param start Giá trị bắt đầu của dãy số. Nếu chỉ có một tham số, đây sẽ là giá trị kết thúc và giá trị bắt đầu sẽ là 0
+ * @param end Giá trị kết thúc của dãy số (tùy chọn)
+ * @param step Bước nhảy giữa các số trong dãy (tùy chọn). Mặc định là 1 nếu end > start, -1 nếu end < start
+ * @returns Mảng các số từ start đến end với bước nhảy step
+ * @example
+ * range(4);      // [0, 1, 2, 3]
+ * range(1, 5);   // [1, 2, 3, 4]
+ * range(0, 20, 5); // [0, 5, 10, 15]
+ * range(5, 2);   // [5, 4, 3]
+ */
 const range = (start, end, step) => {
     if (end === undefined || end === null) {
         end = start;
@@ -625,11 +736,30 @@ const range = (start, end, step) => {
     }
     return arr;
 };
+/**
+ * So sánh hai giá trị bất kỳ có bằng nhau hay không
+ * @param value1 Giá trị thứ nhất cần so sánh
+ * @param value2 Giá trị thứ hai cần so sánh
+ * @param exactlyPosition Có so sánh chính xác vị trí các phần tử trong mảng hay không
+ * @returns true nếu hai giá trị bằng nhau, false nếu không bằng nhau
+ * @example
+ * isEqual([1,2,3], [1,2,3]); // true
+ * isEqual([1,2,3], [3,2,1]); // true khi exactlyPosition = false
+ * isEqual([1,2,3], [3,2,1]); // false khi exactlyPosition = true
+ * isEqual({a:1}, {a:1}); // true
+ */
 const isEqual = (value1, value2, exactlyPosition = false) => {
     if (value1 === value2 || (value1 === null && value2 === null) || (value1 === undefined && value2 === undefined)) {
         return true;
     }
-    if (typeof value1 !== 'object' || typeof value2 !== 'object' || (Array.isArray(value1) && !Array.isArray(value2))) {
+    // Handle signals
+    while (isSignal(value1)) {
+        value1 = value1();
+    }
+    while (isSignal(value2)) {
+        value2 = value2();
+    }
+    if (typeof value1 !== 'object' || typeof value2 !== 'object' || (Array.isArray(value1) && !Array.isArray(value2)) || (!Array.isArray(value1) && Array.isArray(value2))) {
         return false;
     }
     if (Array.isArray(value1)) {
@@ -646,6 +776,22 @@ const isEqual = (value1, value2, exactlyPosition = false) => {
     }
     return !Object.keys(value1).some((key) => !isEqual(value1[key], value2[key]));
 };
+/**
+ * Loại bỏ các phần tử trùng lặp trong mảng dựa trên một thuộc tính chỉ định
+ * @param data Mảng dữ liệu cần xử lý
+ * @param key Tên thuộc tính dùng để so sánh trùng lặp. Nếu không có key thì so sánh trực tiếp giá trị
+ * @returns Mảng mới chứa các phần tử không trùng lặp
+ * @example
+ * const arr = [
+ *   { id: 1, name: 'A' },
+ *   { id: 2, name: 'B' },
+ *   { id: 1, name: 'C' }
+ * ];
+ * uniqBy(arr, 'id'); // [{ id: 1, name: 'A' }, { id: 2, name: 'B' }]
+ *
+ * const numbers = [1, 2, 2, 3, 3];
+ * uniqBy(numbers); // [1, 2, 3]
+ */
 const uniqBy = (data, key) => {
     if (!key || !data || !data.length || typeof data[0] !== 'object') {
         return Array.from(new Set(data));
@@ -1879,7 +2025,16 @@ const getDayjs = (config) => {
     if (!config.date) {
         return undefined;
     }
-    const { date, utc, formatOfDate } = config;
+    let { date, utc, formatOfDate } = config;
+    while (isSignal(date)) {
+        date = date();
+    }
+    while (isSignal(utc)) {
+        utc = utc();
+    }
+    while (isSignal(formatOfDate)) {
+        formatOfDate = formatOfDate();
+    }
     if (utc) {
         if (formatOfDate) {
             return dayjs(date, formatOfDate).utc();