@libs-ui/utils 0.2.355-10 → 0.2.355-11

package/README.md

@@ -1,3 +1,156 @@
-## utils
+# @libs-ui/utils
 
-This library was generated with [Nx](https://nx.dev).
+> Thư viện tập trung toàn bộ **utility functions** dùng chung cho các libs-ui trong project.
+
+**Version**: `0.2.355-10`
+
+## Giới thiệu
+
+Thư viện `@libs-ui/utils` cung cấp các hàm tiện ích dùng chung (format, transform, validate...) để:
+
+- Giảm trùng lặp code utility trong nhiều libs khác nhau
+- Dễ bảo trì và mở rộng khi cần thêm utility mới
+- Chuẩn hóa cách xử lý dữ liệu trong toàn bộ project
+
+## Cài đặt
+
+```bash
+npm install @libs-ui/utils
+# hoặc
+yarn add @libs-ui/utils
+```
+
+## Sử dụng
+
+### Import
+
+```typescript
+import { isNil, isEmpty, get, set, cloneDeep, keyBy, groupBy, range, isEqual, uniqBy } from '@libs-ui/utils';
+```
+
+### Ví dụ cơ bản
+
+#### Kiểm tra giá trị
+
+```typescript
+import { isNil, isEmpty, isTruthy, isFalsy } from '@libs-ui/utils';
+
+// Kiểm tra null/undefined
+isNil(null);        // true
+isNil(undefined);    // true
+isNil(0);           // false
+
+// Kiểm tra rỗng
+isEmpty(null);      // true
+isEmpty('');        // true
+isEmpty({});        // true
+isEmpty([]);        // true
+isEmpty({a:1});     // false
+```
+
+#### Thao tác Object
+
+```typescript
+import { get, set, cloneDeep } from '@libs-ui/utils';
+
+const user = {
+  profile: {
+    name: 'John',
+    address: { city: 'Hanoi' }
+  }
+};
+
+// Lấy giá trị theo path
+get(user, 'profile.name');              // 'John'
+get(user, 'profile.address.city');      // 'Hanoi'
+get(user, 'profile.email', 'N/A');      // 'N/A' (default value)
+
+// Thiết lập giá trị theo path
+set(user, 'profile.name', 'Jane');
+set(user, 'profile.age', 25);
+
+// Clone sâu
+const cloned = cloneDeep(user);
+cloned.profile.name = 'Bob';  // Không ảnh hưởng user gốc
+```
+
+#### Thao tác Array
+
+```typescript
+import { keyBy, groupBy, range, uniqBy, isEqual } from '@libs-ui/utils';
+
+const users = [
+  { id: 1, name: 'John', type: 'admin' },
+  { id: 2, name: 'Jane', type: 'user' },
+  { id: 3, name: 'Bob', type: 'admin' }
+];
+
+// Chuyển array thành object
+keyBy(users, 'id');
+// { "1": {id:1,name:"John",type:"admin"}, "2": {...}, "3": {...} }
+
+// Nhóm theo type
+groupBy(users, 'type');
+// { "admin": [{...}, {...}], "user": [{...}] }
+
+// Tạo mảng số
+range(5);           // [0, 1, 2, 3, 4]
+range(1, 5);        // [1, 2, 3, 4]
+range(0, 10, 2);    // [0, 2, 4, 6, 8]
+
+// Loại bỏ trùng lặp
+uniqBy([{id:1},{id:2},{id:1}], 'id');  // [{id:1}, {id:2}]
+
+// So sánh deep equality
+isEqual({a:1, b:2}, {a:1, b:2});  // true
+isEqual([1,2,3], [1,2,3]);         // true
+```
+
+## Important Notes
+
+⚠️ **Lưu ý quan trọng khi sử dụng**:
+
+- Các functions hỗ trợ unwrap Signal tự động (trừ khi dùng option `ignoreUnWrapSignal`).
+- `get()` và `set()` hỗ trợ path dạng string (vd: `"user.profile.name"`) hoặc array (vd: `["user", "profile", "name"]`).
+- `cloneDeep()` có thể clone Signal, Date, RegExp, Map, Set và các object phức tạp khác.
+- `isEqual()` có thể so sánh deep equality cho objects và arrays.
+
+## API Reference
+
+Xem chi tiết API tại [Documentation](./docs/utils/utils.md) hoặc [Demo Live](http://localhost:4500/utils/helpers).
+
+### Các Functions chính
+
+| Function | Mô tả |
+| --- | --- |
+| `isNil(value, options?)` | Kiểm tra giá trị có phải null hoặc undefined |
+| `isEmpty(value, options?)` | Kiểm tra giá trị có rỗng không |
+| `isTruthy(value, options?)` | Kiểm tra giá trị truthy |
+| `isFalsy(value, options?)` | Kiểm tra giá trị falsy |
+| `get(obj, path, defaultValue?, keepLastValueIfSignal?)` | Lấy giá trị theo path |
+| `set(obj, path, value, options?)` | Thiết lập giá trị theo path |
+| `cloneDeep(data, options?, seen?)` | Clone sâu object/array |
+| `keyBy(data, key)` | Chuyển array thành object |
+| `groupBy(data, key)` | Nhóm array theo key |
+| `range(start, end?, step?)` | Tạo mảng số |
+| `isEqual(value1, value2, options?)` | So sánh deep equality |
+| `uniqBy(data, key?)` | Loại bỏ trùng lặp |
+| `omitBy(objData, predicate)` | Loại bỏ thuộc tính theo điều kiện |
+| `generateInterface(obj, interfaceName)` | Tạo interface từ object |
+
+## Demo
+
+- **Local**: [http://localhost:4500/utils/helpers](http://localhost:4500/utils/helpers)
+- **Production**: (Chưa có)
+
+## Công nghệ sử dụng
+
+- **Angular**: >=18.0.0
+- **TypeScript**: Latest
+- **RxJS**: ~7.8.0
+- **dayjs**: 1.11.5
+- **crypto-es**: ^2.1.0
+
+## Tài liệu
+
+Xem thêm tài liệu chi tiết tại [docs/utils/utils.md](../../docs/utils/utils.md).

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@libs-ui/utils",
-  "version": "0.2.355-10",
+  "version": "0.2.355-11",
   "peerDependencies": {
     "@angular/common": ">=18.0.0",
     "@angular/core": ">=18.0.0",
     "crypto-es": "^2.1.0",
     "dayjs": "1.11.5",
-    "@libs-ui/interfaces-types": "0.2.355-10",
+    "@libs-ui/interfaces-types": "0.2.355-11",
     "rxjs": "~7.8.0"
   },
   "sideEffects": false,