npm package: @libs-ui/pipes-call-function-in-template
Description: > Version: `0.2.355-15` > > Pipe đa năng giúp gọi function xử lý logic ngay trong template, hỗ trợ truyền tham số và xử lý kết quả Async (Observable).
Latest version: 0.2.356-23

# @libs-ui/pipes-call-function-in-template

> Version: `0.2.355-15`
>
> Pipe đa năng giúp gọi function xử lý logic ngay trong template, hỗ trợ truyền tham số và xử lý kết quả Async (Observable).

## Giới thiệu

`LibsUiPipesCallFunctionInTemplatePipe` là một giải pháp linh hoạt cho phép bạn thực hiện các phép biến đổi dữ liệu phức tạp ngay trong template HTML của Angular thông qua các hàm helper trong Component, thay vì phải tạo nhiều Pipe đơn lẻ cho từng mục đích cụ thể.

### Tính năng

- ✅ Gọi function xử lý logic ngay trong template
- ✅ Hỗ trợ truyền tham số phụ (item, otherData)
- ✅ Xử lý bất đồng bộ (Async) với Observable
- ✅ Tự động xử lý giá trị rỗng (null, undefined, 0)
- ✅ Tùy chỉnh giá trị mặc định cho các trường hợp đặc biệt
- ✅ Standalone pipe (Angular 16+)

## Khi nào sử dụng

- Khi cần xử lý logic phức tạp để hiển thị dữ liệu mà không muốn tạo Pipe riêng biệt cho từng trường hợp.
- Khi cần truyền thêm tham số phụ (item, otherData) vào hàm xử lý.
- Khi logic xử lý có thể tái sử dụng dưới dạng function helper.
- Hỗ trợ xử lý bất đồng bộ (Async) đơn giản trong template.

## Cài đặt

```bash
npm install @libs-ui/pipes-call-function-in-template
```

## Import

```typescript
import { LibsUiPipesCallFunctionInTemplatePipe } from '@libs-ui/pipes-call-function-in-template';

@Component({
  standalone: true,
  imports: [LibsUiPipesCallFunctionInTemplatePipe],
  // ...
})
```

## Cách sử dụng

### 1. Transform String Cơ bản

```html
{{ 'hello world' | LibsUiPipesCallFunctionInTemplatePipe : transformUppercase | async }}
```

```typescript
transformUppercase = (data: { value: string }): Observable<string> => {
  return of((data.value || '').toUpperCase());
};
```

### 2. Truyền tham số nâng cao

```html
{{ 100 | LibsUiPipesCallFunctionInTemplatePipe : calculateTotal : 5 : 20 | async }}
```

```typescript
calculateTotal = (data: { value: number; item?: number; otherData?: number }): Observable<string> => {
  const qty = data.item || 0;
  const discount = data.otherData || 0;
  const total = (data.value * qty) - discount;
  return of(`$${total.toFixed(2)}`);
};
```

### 3. Xử lý giá trị rỗng/mặc định

```html
<!-- Case 1: Null Input -->
{{ null | LibsUiPipesCallFunctionInTemplatePipe : undefined : undefined : undefined : { valueIsEmpty: 'Empty Data' } | async }}

<!-- Case 2: Zero Input -->
{{ 0 | LibsUiPipesCallFunctionInTemplatePipe : undefined : undefined : undefined : { valueIs0: 'Zero Value' } | async }}
```

### 4. Async Data (Mock API)

```html
@if (('active' | LibsUiPipesCallFunctionInTemplatePipe : fetchStatus | async) as status) {
  {{ status }}
} @else {
  <span>Loading status...</span>
}
```

```typescript
fetchStatus = (data: { value: string }): Observable<string> => {
  const statusMap: Record<string, string> = {
    'active': 'Đang hoạt động (Online)',
    'inactive': 'Ngừng kích hoạt (Offline)',
    'pending': 'Đang chờ xử lý'
  };
  return of(statusMap[data.value] || 'Unknown').pipe(delay(1000));
};
```

## API Reference

### LibsUiPipesCallFunctionInTemplatePipe

#### Parameters

| Property           | Type                                 | Default     | Description                                      |
| ------------------ | ------------------------------------ | ----------- | ------------------------------------------------ |
| `value`            | `any`                                | `-`         | Giá trị đầu vào cần xử lý.                      |
| `functionCall`     | `TYPE_FUNCTION`                     | `undefined` | Hàm xử lý logic chính. Nhận object chứa input và params, trả về Observable. |
| `item`             | `any`                                | `undefined` | Tham số phụ thứ nhất truyền vào functionCall.    |
| `otherData`        | `any`                                | `undefined` | Tham số phụ thứ hai truyền vào functionCall.    |
| `defaultValueEmpty`| `{ valueIs0?: any; valueIsEmpty?: any }` | `undefined` | Cấu hình giá trị trả về mặc định khi kết quả là 0 hoặc rỗng/null. |

## Types & Interfaces

### TYPE_FUNCTION

```typescript
export type TYPE_FUNCTION<T = any> = (
  data: { value: any; item?: any; otherData?: any }
) => Observable<T>;
```

**Mô tả**: Type cho function xử lý logic. Nhận object chứa value, item, otherData và trả về Observable.

## Lưu ý quan trọng (Important Notes)

> ⚠️ **Caveats**:
>
> - **Yêu cầu `async` pipe**: Pipe này trả về một `Observable`. Bạn **BẮT BUỘC** phải sử dụng thêm `async` pipe trong template để hiển thị giá trị cuối cùng (ví dụ: `value | LibsUiPipesCallFunctionInTemplatePipe : fn | async`).
> - **Cơ chế SwitchMap**: Pipe sử dụng `switchMap` bên trong, do đó hàm xử lý của bạn phải trả về một Observable hoặc Promise.
> - **Xử lý giá trị rỗng**: Pipe tích hợp sẵn logic để handle `null`, `undefined` hoặc `0`. Bạn có thể tùy chỉnh thông qua tham số cuối cùng.
> - **Tham số truyền vào**: Hàm xử lý (`functionCall`) sẽ nhận một object duy nhất chứa `{ value, item, otherData }` để thuận tiện cho việc giải nén (destructuring).

## Công nghệ sử dụng

- Angular 18+
- RxJS 7.8+
- TypeScript 5+

## Demo

- **Local Development**: [http://localhost:4500/pipes/call-function-in-template](http://localhost:4500/pipes/call-function-in-template)

## Unit Tests

Xem file `test-commands.md` để biết cách chạy unit tests.

## License

MIT