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

package/README.md

@@ -1,145 +1,313 @@
 # @libs-ui/pipes-convert-signal-to-object
 
-> Version: `0.2.355-15`
->
-> Pipe chuyển đổi cấu trúc Signals lồng nhau thành plain object/value.
+> Pipe chuyển đổi cấu trúc Signals lồng nhau thành plain object/array để sẵn sàng gửi API hoặc tích hợp thư viện bên ngoài.
 
 ## Giới thiệu
 
-`LibsUiPipesConvertSignalToObjectPipe` là pipe ngược lại của `convert-object-to-signal`. Nó nhận vào một cấu trúc nested signals (object hoặc array chứa các signals) và unwrap toàn bộ chúng thành plain object/array. Điều này rất hữu ích khi bạn cần chuẩn bị dữ liệu để gửi đi (API call), lưu trữ (LocalStorage), hoặc sử dụng với các thư viện không hỗ trợ Signal.
+`LibsUiPipesConvertSignalToObjectPipe` nhận vào một cấu trúc signal lồng nhau (object hoặc array chứa các signal con) và đệ quy unwrap toàn bộ chúng thành plain object/array. Pipe này là cặp đôi ngược lại của `@libs-ui/pipes-convert-object-to-signal`, cho phép chuyển đổi hai chiều giữa dạng signal và plain object. Kết quả đầu ra là một plain object chuẩn, có thể serialize bằng `JSON.stringify`, gửi trực tiếp qua HTTP, hoặc truyền cho bất kỳ thư viện nào không hiểu Angular Signal.
 
-### Tính năng
+## Tính năng
 
-- ✅ Unwrap nested signals (multi-level)
+- ✅ Unwrap nested signals đệ quy nhiều cấp (multi-level)
 - ✅ Chuyển đổi Signal Object thành Plain Object
 - ✅ Chuyển đổi Signal Array thành Plain Array
-- ✅ Deep clone kết quả mặc định (an toàn)
-- ✅ Hỗ trợ primitive signals
+- ✅ Hỗ trợ Map và Set chứa signal
+- ✅ Hỗ trợ primitive signal (string, number, boolean)
+- ✅ Deep clone kết quả mặc định (bảo vệ signal gốc không bị mutate)
+- ✅ Tùy chọn tắt deep clone để tối ưu hiệu năng
+- ✅ Bỏ qua an toàn các đối tượng đặc biệt: Date, RegExp, DOM element, dayjs...
+- ✅ Chống vòng lặp vô hạn với circular reference detection
 
 ## Khi nào sử dụng
 
-### 📤 Gửi data đến API
+- Cần gửi state dạng signal lên API (HTTP POST/PUT) — các HTTP client yêu cầu plain object
+- Cần serialize state sang `JSON.stringify` để lưu vào `localStorage` / `sessionStorage`
+- Tích hợp với thư viện bên ngoài (chart, map, form lib...) chỉ nhận plain object
+- Cần log hoặc debug giá trị thực bên trong một cấu trúc signal phức tạp
+- Chuẩn bị payload trước khi submit form chứa các signal field
 
-Các HTTP client thường yêu cầu plain object. Pipe này giúp bạn chuẩn bị payload dễ dàng:
+## Cài đặt
 
-```typescript
-// Nested signals state
-const user = {
-  name: signal('John'),
-  settings: { theme: signal('dark') },
-};
+```bash
+npm install @libs-ui/pipes-convert-signal-to-object
+```
 
-// Convert to plain object
-const payload = user | LibsUiPipesConvertSignalToObjectPipe;
-// => { name: 'John', settings: { theme: 'dark' } }
+## Import
 
-http.post('/api/user', payload);
+```typescript
+import { LibsUiPipesConvertSignalToObjectPipe } from '@libs-ui/pipes-convert-signal-to-object';
+
+@Component({
+  standalone: true,
+  imports: [LibsUiPipesConvertSignalToObjectPipe],
+  // ...
+})
+export class UserFormComponent {}
 ```
 
-### 💾 Serialize đến LocalStorage
+## Ví dụ sử dụng
 
-Signal không thể được serialize trực tiếp bằng `JSON.stringify`. Hãy convert chúng trước:
+### 1. Unwrap signal object thành plain object (template)
 
 ```typescript
-const plainData = dataSignal | LibsUiPipesConvertSignalToObjectPipe;
-localStorage.setItem('data', JSON.stringify(plainData));
-```
+import { Component, signal } from '@angular/core';
+import { LibsUiPipesConvertSignalToObjectPipe } from '@libs-ui/pipes-convert-signal-to-object';
 
-### 🔌 Tích hợp External Libraries
+@Component({
+  standalone: true,
+  imports: [LibsUiPipesConvertSignalToObjectPipe],
+  template: `
+    @let user = (userSignal | LibsUiPipesConvertSignalToObjectPipe);
+    <p>Tên: {{ user.name }}</p>
+    <p>Email: {{ user.email }}</p>
+    <button (click)="handlerSave(user)">Lưu lên API</button>
+  `,
+})
+export class UserFormComponent {
+  readonly userSignal = signal({
+    name: signal('Nguyễn Văn A'),
+    email: signal('nva@example.com'),
+    age: signal(28),
+  });
+
+  handlerSave(payload: { name: string; email: string; age: number }): void {
+    // payload đã là plain object, sẵn sàng gửi API
+    // this.http.post('/api/users', payload).subscribe(...)
+  }
+}
+```
 
-Nhiều thư viện (charting, maps, etc.) chỉ chấp nhận plain JS objects/arrays:
+### 2. Unwrap signal array thành plain array
 
 ```typescript
-const chartData = signalsData | LibsUiPipesConvertSignalToObjectPipe;
-chart.update(chartData);
+import { Component, signal } from '@angular/core';
+import { LibsUiPipesConvertSignalToObjectPipe } from '@libs-ui/pipes-convert-signal-to-object';
+
+@Component({
+  standalone: true,
+  imports: [LibsUiPipesConvertSignalToObjectPipe],
+  template: `
+    @let items = (itemsSignal | LibsUiPipesConvertSignalToObjectPipe);
+    <ul>
+      @for (item of items; track item) {
+        <li>{{ item }}</li>
+      }
+    </ul>
+    <p>JSON: {{ items | json }}</p>
+  `,
+})
+export class ItemListComponent {
+  readonly itemsSignal = signal([
+    signal('Táo'),
+    signal('Chuối'),
+    signal('Cam'),
+  ]);
+}
 ```
 
-## Cài đặt
+### 3. Unwrap nested signal nhiều cấp
 
-```bash
-npm install @libs-ui/pipes-convert-signal-to-object
+```typescript
+import { Component, signal } from '@angular/core';
+import { LibsUiPipesConvertSignalToObjectPipe } from '@libs-ui/pipes-convert-signal-to-object';
+
+@Component({
+  standalone: true,
+  imports: [LibsUiPipesConvertSignalToObjectPipe],
+  template: `
+    @let company = (companySignal | LibsUiPipesConvertSignalToObjectPipe);
+    <p>Công ty: {{ company.name }}</p>
+    <p>Giám đốc: {{ company.ceo.name }} ({{ company.ceo.age }} tuổi)</p>
+    <pre>{{ company | json }}</pre>
+  `,
+})
+export class CompanyDetailComponent {
+  readonly companySignal = signal({
+    name: signal('Tech Corp'),
+    ceo: signal({
+      name: signal('Trần Văn B'),
+      age: signal(45),
+    }),
+  });
+
+  // companySignal | LibsUiPipesConvertSignalToObjectPipe
+  // => { name: 'Tech Corp', ceo: { name: 'Trần Văn B', age: 45 } }
+}
 ```
 
-## Import
+### 4. Tắt deep clone để tăng hiệu năng
 
 ```typescript
+import { Component, signal } from '@angular/core';
 import { LibsUiPipesConvertSignalToObjectPipe } from '@libs-ui/pipes-convert-signal-to-object';
 
 @Component({
   standalone: true,
   imports: [LibsUiPipesConvertSignalToObjectPipe],
-  // ...
+  template: `
+    <!-- Truyền false để bỏ qua deep clone — nhanh hơn nhưng không sao chép -->
+    @let rawData = (dataSignal | LibsUiPipesConvertSignalToObjectPipe : false);
+    <p>{{ rawData.title }}</p>
+  `,
 })
-export class YourComponent {}
+export class FastReadComponent {
+  readonly dataSignal = signal({
+    title: signal('Báo cáo tháng 6'),
+    count: signal(120),
+  });
+}
 ```
 
-## Ví dụ
-
-### 1. Basic Object Unwrap
+### 5. Sử dụng độc lập trong TypeScript (pipe.transform)
 
-```html
-@let user = (userSignal | LibsUiPipesConvertSignalToObjectPipe);
+```typescript
+import { Component, inject, signal } from '@angular/core';
+import { LibsUiPipesConvertSignalToObjectPipe } from '@libs-ui/pipes-convert-signal-to-object';
 
-<p>User: {{ user.name }}</p>
+@Component({
+  standalone: true,
+  imports: [LibsUiPipesConvertSignalToObjectPipe],
+  providers: [LibsUiPipesConvertSignalToObjectPipe],
+  template: `<button (click)="handlerSubmit()">Gửi form</button>`,
+})
+export class OrderFormComponent {
+  private readonly convertPipe = inject(LibsUiPipesConvertSignalToObjectPipe);
+
+  readonly orderSignal = signal({
+    productId: signal('P001'),
+    quantity: signal(5),
+    note: signal('Giao buổi sáng'),
+  });
+
+  handlerSubmit(): void {
+    const payload = this.convertPipe.transform(this.orderSignal);
+    // payload = { productId: 'P001', quantity: 5, note: 'Giao buổi sáng' }
+    // this.orderApi.create(payload).subscribe(...)
+  }
+}
 ```
 
-### 2. Array Unwrap
+### 6. Lưu state vào localStorage
 
-```html
-@let items = (itemsSignal | LibsUiPipesConvertSignalToObjectPipe);
+```typescript
+import { Component, inject, signal } from '@angular/core';
+import { LibsUiPipesConvertSignalToObjectPipe } from '@libs-ui/pipes-convert-signal-to-object';
 
-<ul>
-  @for (item of items; track $index) {
-  <li>{{ item }}</li>
+@Component({
+  standalone: true,
+  imports: [LibsUiPipesConvertSignalToObjectPipe],
+  providers: [LibsUiPipesConvertSignalToObjectPipe],
+  template: `<button (click)="handlerSaveFilter()">Lưu bộ lọc</button>`,
+})
+export class FilterBarComponent {
+  private readonly convertPipe = inject(LibsUiPipesConvertSignalToObjectPipe);
+
+  readonly filterSignal = signal({
+    keyword: signal('angular'),
+    status: signal('active'),
+    page: signal(1),
+  });
+
+  handlerSaveFilter(): void {
+    const plainFilter = this.convertPipe.transform(this.filterSignal);
+    // plainFilter = { keyword: 'angular', status: 'active', page: 1 }
+    localStorage.setItem('user-filter', JSON.stringify(plainFilter));
   }
-</ul>
+}
 ```
 
-### 3. No Clone (Faster)
+## Transform
+
+| Tham số | Type | Bắt buộc | Default | Mô tả |
+|---|---|---|---|---|
+| `data` | `any` | Có | — | Giá trị signal hoặc cấu trúc object/array chứa nested signals cần unwrap |
+| `isCloneDeep` | `boolean` | Không | `true` | `true` để deep clone kết quả (bảo vệ signal gốc); `false` để giữ reference gốc (nhanh hơn, cẩn thận mutate) |
 
-Nếu bạn chắc chắn không mutate kết quả hoặc cần performance tối đa:
+**Cú pháp template:**
 
 ```html
-@let rawData = (dataSignal | LibsUiPipesConvertSignalToObjectPipe : false);
+{{ dataSignal | LibsUiPipesConvertSignalToObjectPipe }}
+{{ dataSignal | LibsUiPipesConvertSignalToObjectPipe : false }}
+@let plain = (dataSignal | LibsUiPipesConvertSignalToObjectPipe);
 ```
 
-## API
+**Cú pháp standalone (inject):**
 
-### LibsUiPipesConvertSignalToObjectPipe
+```typescript
+const plain = this.convertPipe.transform(this.dataSignal);
+const plainNoClone = this.convertPipe.transform(this.dataSignal, false);
+```
+
+**Kiểu trả về:** Plain object, plain array, hoặc primitive value sau khi đã unwrap toàn bộ signal con.
+
+## Hành vi chi tiết
+
+### Unwrap đệ quy so với gọi `()`
 
 ```typescript
-data | LibsUiPipesConvertSignalToObjectPipe : isCloneDeep?
+// Gọi () chỉ unwrap 1 cấp — vẫn còn signal con bên trong
+userSignal()
+// => { name: WritableSignal<string>, age: WritableSignal<number> }
+
+// Pipe unwrap toàn bộ tất cả cấp
+userSignal | LibsUiPipesConvertSignalToObjectPipe
+// => { name: 'Nguyễn Văn A', age: 28 }
 ```
 
-#### Parameters
+### Quy tắc xử lý theo kiểu dữ liệu
+
+| Kiểu input | Hành vi |
+|---|---|
+| `Signal<primitive>` | Unwrap thành giá trị nguyên thủy |
+| `Signal<object>` | Unwrap object, tiếp tục đệ quy vào các property |
+| `Signal<array>` | Unwrap array, tiếp tục đệ quy từng phần tử |
+| `Signal<Map>` | Unwrap thành `Map` mới với values đã unwrap |
+| `Signal<Set>` | Unwrap thành `Set` mới với values đã unwrap |
+| `null` / `undefined` | Trả về nguyên như đầu vào, không throw |
+| `Date`, `RegExp`, DOM element, dayjs | Giữ nguyên, không xử lý |
+| Circular reference | Được phát hiện và xử lý an toàn, không bị stack overflow |
+
+### Deep clone (mặc định `true`)
+
+```typescript
+// isCloneDeep = true (mặc định) — AN TOÀN
+const plain = this.convertPipe.transform(this.dataSignal);
+plain.name = 'Jane'; // Không ảnh hưởng đến this.dataSignal
 
-| Property      | Type                   | Default | Description                                               |
-| ------------- | ---------------------- | ------- | --------------------------------------------------------- |
-| `data`        | `any`                  | -       | Nested signals cần chuyển đổi thành plain object.         |
-| `isCloneDeep` | `boolean \| undefined` | `true`  | `true` để deep clone (an toàn), `false` để giữ reference. |
+// isCloneDeep = false — NHANH HƠN nhưng cần cẩn thận
+const plainRef = this.convertPipe.transform(this.dataSignal, false);
+plainRef.name = 'Jane'; // Có thể ảnh hưởng đến giá trị bên trong signal gốc
+```
 
-#### Returns
+## Types & Interfaces
 
-Plain object, array, hoặc primitive value sau khi đã unwrap tất cả signals.
+```typescript
+import { LibsUiPipesConvertSignalToObjectPipe } from '@libs-ui/pipes-convert-signal-to-object';
 
-## Hidden Logic
+// Pipe transform signature
+// transform(data: any, isCloneDeep?: boolean): any
 
-### 1. 🔄 Recursive Unwrap
+// Ví dụ kiểu tường minh khi inject để dùng trong TS
+const result: { name: string; age: number } =
+  this.convertPipe.transform<{ name: string; age: number }>(this.userSignal);
+```
 
-Pipe sẽ đệ quy đi vào mọi property của object/array. Nếu gặp Signal, nó sẽ gọi `()` để lấy giá trị, sau đó tiếp tục đệ quy cho giá trị đó.
+## Lưu ý quan trọng
 
-### 2. 🔀 Deep Clone
+⚠️ **Không serialize trực tiếp Signal**: `JSON.stringify(signal)` sẽ không cho kết quả đúng vì signal là function object. Luôn dùng pipe này trước khi serialize.
 
-Mặc định, kết quả trả về là một bản sao deep clone của dữ liệu đã unwrap. Điều này đảm bảo rằng nếu bạn thay đổi property của object kết quả, nó **KHÔNG** ảnh hưởng ngược lại đến state trong Signal gốc.
+⚠️ **isCloneDeep = false và mutation**: Khi tắt deep clone, việc thay đổi property trên plain object kết quả có thể làm thay đổi giá trị bên trong signal gốc không mong muốn. Chỉ dùng `false` khi chắc chắn không mutate kết quả.
 
-## Demo
+⚠️ **Đối tượng đặc biệt được giữ nguyên**: `Date`, `RegExp`, dayjs, DOM element và các đối tượng framework sẽ được truyền nguyên vẹn mà không bị unwrap, đảm bảo không mất dữ liệu.
 
-- **Local Development**: [http://localhost:4500/pipes/convert-signal-to-object](http://localhost:4500/pipes/convert-signal-to-object)
+⚠️ **Pipe chỉ unwrap — không làm reactive**: Kết quả trả về là snapshot tại thời điểm pipe chạy. Nếu signal thay đổi sau đó, cần pipe chạy lại (Angular change detection sẽ tự kích hoạt trong template với OnPush khi signal thay đổi).
 
-## Unit Tests
+⚠️ **Dùng với inject khi cần trong TypeScript**: Để dùng ngoài template, khai báo trong `providers` của component và inject bằng `inject(LibsUiPipesConvertSignalToObjectPipe)`.
 
-Xem file `test-commands.md` để biết cách chạy unit tests.
+## Demo
 
-## License
+```bash
+npx nx serve core-ui
+```
 
-MIT
+Truy cập: http://localhost:4500/pipes/convert-signal-to-object

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

@@ -1 +1 @@
-{"version":3,"file":"libs-ui-pipes-convert-signal-to-object.mjs","sources":["../../../../../libs-ui/pipes/convert-signal-to-object/src/convert-signal-to-object.pipe.ts","../../../../../libs-ui/pipes/convert-signal-to-object/src/libs-ui-pipes-convert-signal-to-object.ts"],"sourcesContent":["import { Pipe, PipeTransform } from '@angular/core';\nimport { convertSignalToObject } from '@libs-ui/utils';\n@Pipe({\n  name: 'LibsUiPipesConvertSignalToObjectPipe',\n  standalone: true,\n})\nexport class LibsUiPipesConvertSignalToObjectPipe 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 convertSignalToObject(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-signal-to-object.mjs","sources":["../../../../../libs-ui/pipes/convert-signal-to-object/src/convert-signal-to-object.pipe.ts","../../../../../libs-ui/pipes/convert-signal-to-object/src/libs-ui-pipes-convert-signal-to-object.ts"],"sourcesContent":["import { Pipe, PipeTransform } from '@angular/core';\nimport { convertSignalToObject } from '@libs-ui/utils';\n@Pipe({\n  name: 'LibsUiPipesConvertSignalToObjectPipe',\n  standalone: true,\n})\nexport class LibsUiPipesConvertSignalToObjectPipe 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 convertSignalToObject(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-signal-to-object",
-  "version": "0.2.356-9",
+  "version": "0.2.357-0",
   "peerDependencies": {
     "@angular/core": ">=18.0.0",
-    "@libs-ui/utils": "0.2.356-9"
+    "@libs-ui/utils": "0.2.357-0"
   },
   "sideEffects": false,
   "module": "fesm2022/libs-ui-pipes-convert-signal-to-object.mjs",