@libs-ui/pipes-convert-object-to-signal 0.2.356-8 → 0.2.357-0

package/README.md

@@ -1,73 +1,27 @@
 # @libs-ui/pipes-convert-object-to-signal
 
-> Version: `0.2.355-15`
->
-> Pipe chuyển đổi object/array thành cấu trúc Signals lồng nhau để tận dụng fine-grained reactivity.
+> Pipe chuyển đổi object/array thành cấu trúc Signals lồng nhau để tận dụng fine-grained reactivity của Angular.
 
 ## Giới thiệu
 
-`LibsUiPipesConvertObjectToSignalPipe` chuyển đổi một object hoặc array thành cấu trúc Signals lồng nhau (nested signals). Mỗi property của object trở thành một Signal riêng biệt, cho phép Angular chỉ re-render các phần UI thực sự thay đổi thay vì cả component.
+`LibsUiPipesConvertObjectToSignalPipe` chuyển đổi một plain object hoặc array thành cấu trúc nested `WritableSignal`. Mỗi property của object trở thành một `WritableSignal` riêng biệt, cho phép Angular chỉ re-render đúng phần UI phụ thuộc vào property đó thay vì toàn bộ component. Pipe ủy quyền xử lý cho hàm tiện ích `convertObjectToSignal` từ `@libs-ui/utils`.
 
-### Tính năng
+## Tính năng
 
-- ✅ Chuyển object thành nested WritableSignals
-- ✅ Chuyển array thành Signal chứa các Signal items
-- ✅ Deep clone mặc định (an toàn)
-- ✅ Hỗ trợ nested objects (multi-level)
-- ✅ Fine-grained reactivity - tối ưu performance
+- ✅ Chuyển object thành nested `WritableSignal` — mỗi property là một signal độc lập
+- ✅ Chuyển array thành `WritableSignal<WritableSignal<T>[]>` — mỗi phần tử là một signal
+- ✅ Hỗ trợ nested objects đa cấp (multi-level)
+- ✅ Deep clone mặc định — an toàn, không mutate data gốc
+- ✅ Tùy chọn shallow (no-clone) để tăng performance khi cần thiết
+- ✅ Fine-grained reactivity — tối ưu hiệu năng cho form/table phức tạp
+- ✅ Trả về nguyên nếu input là `null` hoặc `undefined`
 
 ## Khi nào sử dụng
 
-### 📝 Form với nhiều fields
-
-Khi form có nhiều field, dùng nested signals để thay đổi một field không ảnh hưởng đến các field khác:
-
-```typescript
-// ❌ Nguyên object là Signal - không hiệu quả
-user = signal({ name: 'John', email: 'john@example.com' });
-// user.set({ ...user(), name: 'Jane' }) => Cả name và email đều trigger re-render!
-
-// ✅ Nested Signals - hiệu quả
-user = { name: 'John', email: 'john@example.com' } | LibsUiPipesConvertObjectToSignalPipe;
-user().name.set('Jane'); // => Chỉ name trigger re-render
-```
-
-### 📊 Data table lớn
-
-Trong bảng dữ liệu lớn, chỉ re-render cell thay đổi thay vì cả row:
-
-```typescript
-rows = data | LibsUiPipesConvertObjectToSignalPipe;
-
-// Trong template
-@for (row of rows(); track row().id) {
-  <tr>
-    <td>{{ row().name() }}</td> <!-- Chỉ re-render khi name thay đổi -->
-    <td>{{ row().email() }}</td> <!-- Không re-render khi name thay đổi -->
-  </tr>
-}
-```
-
-### 🔄 Two-way binding tối ưu
-
-Dễ dàng bind từng property đến component con:
-
-```typescript
-<app-input-field 
-  [value]="user().name()"
-  (change)="user().name.set($event)"
-/>
-<app-input-field 
-  [value]="user().email()"
-  (change)="user().email.set($event)"
-/>
-```
-
-## ⚠️ Important Notes
-
-- **🔄 Nested Signals**: Mỗi property của object trở thành một Signal. Thay đổi một property chỉ trigger re-render ở component sử dụng property đó.
-- **🔀 Shallow vs Deep Clone**: Mặc định deep clone để tránh mutate data gốc. Dùng `isCloneDeep = false` để giữ nguyên reference.
-- **⚡ Fine-grained Reactivity**: Hiệu quả hơn so với nguyên object làm Signal vì chỉ re-render khi property cụ thể thay đổi.
+- **Form nhiều fields**: Thay đổi một field không trigger re-render các field khác — mỗi `<input>` bind vào signal riêng.
+- **Data table lớn**: Chỉ re-render cell thay đổi thay vì cả row khi cập nhật một giá trị.
+- **Two-way binding tối ưu**: Bind từng property đến component con mà không cần spread cả object.
+- **Performance-critical UI**: Giảm tối đa số lần re-render trong component phức tạp có nhiều phần tử phụ thuộc cùng một nguồn dữ liệu.
 
 ## Cài đặt
 
@@ -85,29 +39,48 @@ import { LibsUiPipesConvertObjectToSignalPipe } from '@libs-ui/pipes-convert-obj
   imports: [LibsUiPipesConvertObjectToSignalPipe],
   // ...
 })
-export class YourComponent {}
+export class MyComponent {}
+```
+
+Khi cần dùng trong class TypeScript (inject trực tiếp):
+
+```typescript
+import { LibsUiPipesConvertObjectToSignalPipe } from '@libs-ui/pipes-convert-object-to-signal';
+
+@Component({
+  standalone: true,
+  imports: [LibsUiPipesConvertObjectToSignalPipe],
+  providers: [LibsUiPipesConvertObjectToSignalPipe],
+})
+export class MyComponent {
+  private readonly convertPipe = inject(LibsUiPipesConvertObjectToSignalPipe);
+
+  constructor() {
+    this.userSig = this.convertPipe.transform({ name: 'John', age: 30 });
+  }
+}
 ```
 
-## Ví dụ
+## Ví dụ sử dụng
 
-### 1. Object thành Nested Signals
+### 1. Object thành Nested Signals (Template)
 
 ```html
 @let user = ({ name: 'John', email: 'john@example.com', age: 30 } | LibsUiPipesConvertObjectToSignalPipe);
 
-<div>
-  <input [value]="user().name()" (input)="user().name.set($event.target.value)" />
-  <input [value]="user().email()" (input)="user().email.set($event.target.value)" />
-</div>
+<input [value]="user().name()" (input)="user().name.set($any($event.target).value)" />
+<input [value]="user().email()" (input)="user().email.set($any($event.target).value)" />
+<input type="number" [value]="user().age()" (input)="user().age.set(+$any($event.target).value)" />
 
 <p>Name: {{ user().name() }}</p>
 <p>Email: {{ user().email() }}</p>
+<p>Age: {{ user().age() }}</p>
 ```
 
 ```typescript
-// user() trả về object với mỗi property là WritableSignal
-// user().name() - lấy giá trị
-// user().name.set('Jane') - set giá trị mới
+// Đọc signal: user().name()
+// Set signal: user().name.set('Jane')
+// Thay đổi name KHÔNG trigger re-render cho email và age
 ```
 
 ### 2. Array thành Signal của Signals
@@ -116,21 +89,22 @@ export class YourComponent {}
 @let items = (['apple', 'banana', 'orange'] | LibsUiPipesConvertObjectToSignalPipe);
 
 <ul>
-  @for (item of items(); track $index) {
+  @for (item of items(); track item) {
     <li>
-      <input [value]="item()" (input)="item.set($event.target.value)" />
+      <input [value]="item()" (input)="item.set($any($event.target).value)" />
+      <span>{{ item() }}</span>
     </li>
   }
 </ul>
 ```
 
 ```typescript
-// items() là WritableSignal<WritableSignal<string>[]>
-// items()[0]() - lấy giá trị item đầu tiên
-// items()[0].set('new') - set giá trị mới
+// items() → WritableSignal<WritableSignal<string>[]>
+// items()[0]() → 'apple'
+// items()[0].set('grape') → chỉ re-render item[0]
 ```
 
-### 3. Nested Object
+### 3. Nested Object (Multi-level)
 
 ```html
 @let company = ({
@@ -138,14 +112,15 @@ export class YourComponent {}
   ceo: { name: 'John', age: 45 }
 } | LibsUiPipesConvertObjectToSignalPipe);
 
-<input [value]="company().name()" (input)="company().name.set($event.target.value)" />
-<input [value]="company().ceo().name()" (input)="company().ceo().name.set($event.target.value)" />
+<input [value]="company().name()" (input)="company().name.set($any($event.target).value)" />
+<input [value]="company().ceo().name()" (input)="company().ceo().name.set($any($event.target).value)" />
+<input type="number" [value]="company().ceo().age()" (input)="company().ceo().age.set(+$any($event.target).value)" />
 
 <p>Company: {{ company().name() }}</p>
-<p>CEO: {{ company().ceo().name() }}</p>
+<p>CEO: {{ company().ceo().name() }}, tuổi {{ company().ceo().age() }}</p>
 ```
 
-### 4. Giữ nguyên Reference (nhanh hơn)
+### 4. Shallow (No-clone) — giữ nguyên reference
 
 ```html
 @let user = (userData | LibsUiPipesConvertObjectToSignalPipe : false);
@@ -154,95 +129,135 @@ export class YourComponent {}
 ```
 
 ```typescript
-// isCloneDeep = false: Giữ nguyên reference đến data gốc
-// Nhanh hơn nhưng cẩn thận mutate!
-```
+readonly userData = { name: 'John', age: 30 };
 
-## API
+// isCloneDeep = false: nhanh hơn, nhưng mutate userData cũng ảnh hưởng signal
+// isCloneDeep = true (default): an toàn, data được deep clone trước khi convert
+```
 
-### LibsUiPipesConvertObjectToSignalPipe
+### 5. Sử dụng trong TypeScript (inject pipe)
 
 ```typescript
-data | LibsUiPipesConvertObjectToSignalPipe : isCloneDeep?
+import { LibsUiPipesConvertObjectToSignalPipe } from '@libs-ui/pipes-convert-object-to-signal';
+
+@Component({
+  standalone: true,
+  imports: [LibsUiPipesConvertObjectToSignalPipe],
+  providers: [LibsUiPipesConvertObjectToSignalPipe],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class UserFormComponent {
+  private readonly convertPipe = inject(LibsUiPipesConvertObjectToSignalPipe);
+
+  protected userSig = this.convertPipe.transform({ name: 'John', email: 'john@example.com' });
+
+  protected handlerSaveName(event: Event): void {
+    event.stopPropagation();
+    const value = (event.target as HTMLInputElement).value;
+    this.userSig().name.set(value);
+  }
+}
 ```
 
-#### Parameters
+## Transform
+
+| Tham số | Type | Bắt buộc | Default | Mô tả | Ví dụ |
+|---|---|---|---|---|---|
+| `data` | `any` | Có | — | Object hoặc array cần chuyển đổi thành nested Signals. Trả về nguyên nếu là `null`/`undefined`. | `{ name: 'John' }` |
+| `isCloneDeep` | `boolean \| undefined` | Không | `true` | `true`: deep clone data trước khi convert (an toàn). `false`: giữ nguyên reference (nhanh hơn, cẩn thận mutate). | `false` |
+
+**Cú pháp template:**
+
+```html
+{{ data | LibsUiPipesConvertObjectToSignalPipe }}
+{{ data | LibsUiPipesConvertObjectToSignalPipe : false }}
+```
 
-| Property      | Type                    | Default  | Description                                               |
-| ------------- | ----------------------- | -------- | --------------------------------------------------------- |
-| `data`        | `any`                   | -        | Object/array cần chuyển đổi thành Signals.                |
-| `isCloneDeep` | `boolean \| undefined`  | `true`   | `true` để deep clone (an toàn), `false` để giữ reference. |
+**Cú pháp standalone (TypeScript):**
 
-#### Returns
+```typescript
+const signalObj = pipe.transform(data);
+const signalObj = pipe.transform(data, false);
+```
 
-Nested structure với WritableSignals:
+## Kiểu dữ liệu đầu ra
 
 ```typescript
-// Object -> WritableSignal<{ prop: WritableSignal<...> }>
-// Array -> WritableSignal<WritableSignal<T>[]>
+// Pipe transform signature
+transform<T>(data: T, isCloneDeep?: boolean): T
+
+// Object → Nested WritableSignals
+{ name: 'John', age: 30 }
+=>
+WritableSignal<{
+  name: WritableSignal<string>,
+  age: WritableSignal<number>
+}>
+
+// Array → WritableSignal<WritableSignal<T>[]>
+['apple', 'banana']
+=>
+WritableSignal<[
+  WritableSignal<string>,
+  WritableSignal<string>
+]>
 ```
 
-## Hidden Logic
+**Bảng hành vi theo kiểu đầu vào:**
 
-### 1. 🔄 Fine-grained Reactivity
+| Kiểu dữ liệu | Kết quả |
+|---|---|
+| `null` / `undefined` | Trả về nguyên (không convert) |
+| Primitive (`string`, `number`, `boolean`) | Wrapped trong `WritableSignal<T>` |
+| Plain object | `WritableSignal<{ [key]: WritableSignal<V> }>` — mỗi property là signal |
+| Array | `WritableSignal<WritableSignal<T>[]>` — mỗi phần tử là signal |
+| Nested object | Đệ quy — mọi cấp độ đều được convert |
+| `Promise` / `Observable` | Trả về nguyên (async objects không convert) |
+| `Map` / `Set` | Được xử lý đặc biệt theo logic trong `convertObjectToSignal` |
 
-Khác với nguyên object làm Signal, nested signals chỉ re-render component khi property cụ thể thay đổi:
+## Lưu ý quan trọng
 
-```typescript
-// ❌ Object là signal
-user = signal({ name: 'John', email: 'john@example.com' });
-user.set({ ...user(), name: 'Jane' });
-// => Cả name và email đều trigger re-render!
+⚠️ **Fine-grained Reactivity**: Khác với `signal({ name, email })` — khi dùng pipe này, thay đổi `name` không trigger re-render phần template dùng `email`. Đây là lợi thế chính để tối ưu hiệu năng.
 
-// ✅ Nested signals
-user = object | LibsUiPipesConvertObjectToSignalPipe;
-user().name.set('Jane');
-// => Chỉ name trigger re-render, email không!
-```
+⚠️ **isCloneDeep = false**: Khi tắt deep clone, mutate object gốc (data nguồn) cũng ảnh hưởng trực tiếp đến các signal. Chỉ dùng khi chắc chắn không có side effect từ code khác.
 
-### 2. 🔀 Shallow vs Deep Clone
+⚠️ **@let trong template**: Dùng `@let` để khai báo biến từ pipe trong template (Angular 18+). Với Angular < 18, cần dùng `as` trong `*ngIf` hoặc chuyển sang inject pipe trong TS.
 
-| Tùy chọn | Behavior | Khi nào dùng |
-| -------- | -------- | ------------ |
-| `true` (default) | Deep clone data trước khi convert | Luôn an toàn, không mutate gốc |
-| `false` | Giữ nguyên reference | Performance critical, chắc chắn không mutate |
+⚠️ **track trong @for với Array Signals**: Khi dùng pipe với array, BẮT BUỘC `track item` (track signal reference bất biến) — KHÔNG dùng `track $index`.
 
-```typescript
-// Deep clone (default) - An toàn
-user = userData | LibsUiPipesConvertObjectToSignalPipe;
-user().name.set('Jane'); // Không ảnh hưởng userData
+```html
+<!-- ✅ ĐÚNG — track signal reference -->
+@for (item of items(); track item) { ... }
 
-// No clone - Nhanh hơn
-user = userData | LibsUiPipesConvertObjectToSignalPipe : false;
-user().name.set('Jane'); // Cẩn thận: ảnh hưởng userData!
+<!-- ❌ SAI — BLOCKER -->
+@for (item of items(); track $index) { ... }
 ```
 
-### 3. 📦 Các kiểu dữ liệu được hỗ trợ
+⚠️ **Không dùng trong computed()**: Pipe gọi `convertObjectToSignal` là stateful. Không nên wrap kết quả pipe trong `computed()` vì mỗi lần computed chạy lại sẽ tạo signal mới, mất state đã set trước đó.
 
-| Kiểu dữ liệu | Kết quả |
-| ------------ | ------- |
-| Primitives (string, number, boolean) | Trả về nguyên (không convert) |
-| Object | WritableSignal với mỗi property là Signal |
-| Array | WritableSignal chứa array của Signals |
-| Map/Set | Được xử lý đặc biệt |
-| Promise/Observer | Trả về nguyên (async objects) |
-| null/undefined | Trả về nguyên |
+## So sánh: Object Signal vs Nested Signals
 
 ```typescript
-123 | pipe => 123 (primitive)
-{ name: 'John' } | pipe => WritableSignal<...> (object)
-['a', 'b'] | pipe => WritableSignal<WritableSignal<string>[]> (array)
-Promise/Observer | pipe => Trả về nguyên (async)
+// ❌ Object là một signal duy nhất — không hiệu quả
+protected user = signal({ name: 'John', email: 'john@example.com' });
+// Khi thay đổi name:
+this.user.set({ ...this.user(), name: 'Jane' });
+// => Cả name VÀ email đều trigger re-render!
+
+// ✅ Nested Signals — fine-grained
+// Trong template:
+// @let user = (userData | LibsUiPipesConvertObjectToSignalPipe)
+// Hoặc trong TS:
+protected userSig = this.convertPipe.transform({ name: 'John', email: 'john@example.com' });
+// Khi thay đổi name:
+this.userSig().name.set('Jane');
+// => Chỉ phần template dùng user().name() re-render, email() KHÔNG re-render
 ```
 
 ## Demo
 
-- **Local Development**: [http://localhost:4500/pipes/convert-object-to-signal](http://localhost:4500/pipes/convert-object-to-signal)
-
-## Unit Tests
-
-Xem file `test-commands.md` để biết cách chạy unit tests.
-
-## License
+```bash
+npx nx serve core-ui
+```
 
-MIT
+Truy cập: [http://localhost:4500/pipes/convert-object-to-signal](http://localhost:4500/pipes/convert-object-to-signal)

package/fesm2022/libs-ui-pipes-convert-object-to-signal.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"libs-ui-pipes-convert-object-to-signal.mjs","sources":["../../../../../libs-ui/pipes/convert-object-to-signal/src/convert-object-to-signal.pipe.ts","../../../../../libs-ui/pipes/convert-object-to-signal/src/libs-ui-pipes-convert-object-to-signal.ts"],"sourcesContent":["import { Pipe, PipeTransform } from '@angular/core';\nimport { convertObjectToSignal } from '@libs-ui/utils';\n@Pipe({\n  name: 'LibsUiPipesConvertObjectToSignalPipe',\n  standalone: true,\n})\nexport class LibsUiPipesConvertObjectToSignalPipe implements PipeTransform {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  transform(data: any, isCloneDeep?: boolean): any {\n    if (!data) {\n      return data;\n    }\n\n    return convertObjectToSignal(data, isCloneDeep);\n  }\n}\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './index';\n"],"names":[],"mappings":";;;;MAMa,oCAAoC,CAAA;;IAE/C,SAAS,CAAC,IAAS,EAAE,WAAqB,EAAA;QACxC,IAAI,CAAC,IAAI,EAAE;AACT,YAAA,OAAO,IAAI;QACb;AAEA,QAAA,OAAO,qBAAqB,CAAC,IAAI,EAAE,WAAW,CAAC;IACjD;wGARW,oCAAoC,EAAA,IAAA,EAAA,EAAA,EAAA,MAAA,EAAA,EAAA,CAAA,eAAA,CAAA,IAAA,EAAA,CAAA;sGAApC,oCAAoC,EAAA,YAAA,EAAA,IAAA,EAAA,IAAA,EAAA,sCAAA,EAAA,CAAA;;4FAApC,oCAAoC,EAAA,UAAA,EAAA,CAAA;kBAJhD,IAAI;AAAC,YAAA,IAAA,EAAA,CAAA;AACJ,oBAAA,IAAI,EAAE,sCAAsC;AAC5C,oBAAA,UAAU,EAAE,IAAI;AACjB,iBAAA;;;ACLD;;AAEG;;;;"}
+{"version":3,"file":"libs-ui-pipes-convert-object-to-signal.mjs","sources":["../../../../../libs-ui/pipes/convert-object-to-signal/src/convert-object-to-signal.pipe.ts","../../../../../libs-ui/pipes/convert-object-to-signal/src/libs-ui-pipes-convert-object-to-signal.ts"],"sourcesContent":["import { Pipe, PipeTransform } from '@angular/core';\nimport { convertObjectToSignal } from '@libs-ui/utils';\n@Pipe({\n  name: 'LibsUiPipesConvertObjectToSignalPipe',\n  standalone: true,\n})\nexport class LibsUiPipesConvertObjectToSignalPipe implements PipeTransform {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  transform(data: any, isCloneDeep?: boolean): any {\n    if (!data) {\n      return data;\n    }\n\n    return convertObjectToSignal(data, isCloneDeep);\n  }\n}\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './index';\n"],"names":[],"mappings":";;;;MAMa,oCAAoC,CAAA;;IAE/C,SAAS,CAAC,IAAS,EAAE,WAAqB,EAAA;QACxC,IAAI,CAAC,IAAI,EAAE;AACT,YAAA,OAAO,IAAI,CAAC;SACb;AAED,QAAA,OAAO,qBAAqB,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;KACjD;wGARU,oCAAoC,EAAA,IAAA,EAAA,EAAA,EAAA,MAAA,EAAA,EAAA,CAAA,eAAA,CAAA,IAAA,EAAA,CAAA,CAAA;sGAApC,oCAAoC,EAAA,YAAA,EAAA,IAAA,EAAA,IAAA,EAAA,sCAAA,EAAA,CAAA,CAAA;;4FAApC,oCAAoC,EAAA,UAAA,EAAA,CAAA;kBAJhD,IAAI;AAAC,YAAA,IAAA,EAAA,CAAA;AACJ,oBAAA,IAAI,EAAE,sCAAsC;AAC5C,oBAAA,UAAU,EAAE,IAAI;AACjB,iBAAA,CAAA;;;ACLD;;AAEG;;;;"}

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@libs-ui/pipes-convert-object-to-signal",
-  "version": "0.2.356-8",
+  "version": "0.2.357-0",
   "peerDependencies": {
     "@angular/core": ">=18.0.0",
-    "@libs-ui/utils": "0.2.356-8"
+    "@libs-ui/utils": "0.2.357-0"
   },
   "sideEffects": false,
   "module": "fesm2022/libs-ui-pipes-convert-object-to-signal.mjs",