npm package: @libs-ui/services-format-date
Description: Service định dạng ngày giờ dựa trên dayjs. Thin wrapper của `formatDate()` từ `@libs-ui/utils`. Hỗ trợ nhiều kiểu input, định dạng tùy chỉnh, đa ngôn ngữ (vi/en) và format aliases locale-aware.
Latest version: 0.2.356-23

# Format Date Service

Service định dạng ngày giờ dựa trên dayjs. Thin wrapper của `formatDate()` từ `@libs-ui/utils`. Hỗ trợ nhiều kiểu input, định dạng tùy chỉnh, đa ngôn ngữ (vi/en) và format aliases locale-aware.

## Tính năng

- ✅ Input types đa dạng: Unix timestamp (giây), ISO string, dayjs object, Date
- ✅ Format aliases locale-aware: `dmy`, `dmy hm`, `dmy hms`, `my`, `dm`... tự chọn format theo ngôn ngữ
- ✅ Đa ngôn ngữ: vi/en — tiếng Việt ngày trước tháng, tiếng Anh tháng trước ngày
- ✅ Tự lấy ngôn ngữ từ `UtilsCache.getLang()` nếu không truyền
- ✅ null/undefined → trả về `''` (không throw error)
- ✅ Custom format override hook toàn cục (`updateFunctionFormatDate`)

## Cài đặt

```bash
npm install @libs-ui/services-format-date
```

## Import

```typescript
import { FormatDateService } from '@libs-ui/services-format-date';
```

## Cách sử dụng

### Trong Component

```typescript
import { Component, inject } from '@angular/core';
import { FormatDateService } from '@libs-ui/services-format-date';

@Component({
  standalone: true,
  template: `
    <p>{{ formatDateService.transform(timestamp) }}</p>
    <p>{{ formatDateService.transform(date, 'dmy hm', 'vi') }}</p>
  `,
})
export class ExampleComponent {
  readonly formatDateService = inject(FormatDateService);

  timestamp = 1716222600; // Unix timestamp (giây)
  date = '2024-05-20T10:30:00'; // ISO string
}
```

### Dùng trong TypeScript (khuyến nghị)

Service là thin wrapper của `formatDate` trong `@libs-ui/utils`. Khi cần dùng trong TypeScript, import thẳng hàm đó — **không cần inject service**:

```typescript
import { formatDate } from '@libs-ui/utils';

// Không cần inject service
const result = formatDate(1716222600, 'YYYY/MM/DD HH:mm');
// Output: '2024/05/20 17:30'

const viDate = formatDate('2024-05-20', 'dmy hm', 'vi');
// Output: '20 Th5, 2024 00:00'

// Trong component class:
class ExampleComponent {
  formattedDate = formatDate(this.rawDate, 'DD/MM/YYYY');
}
```

## API

### `transform(time, format?, lang?)`

| Parameter | Type                                                   | Default                | Mô tả                                    |
| --------- | ------------------------------------------------------ | ---------------------- | ---------------------------------------- |
| `time`    | `string \| number \| dayjs.Dayjs \| undefined \| null` | -                      | Giá trị thời gian. null/undefined → `''` |
| `format`  | `string`                                               | `'YYYY/MM/DD HH:mm'`   | Format dayjs hoặc alias ngắn gọn         |
| `lang`    | `string \| undefined`                                  | `UtilsCache.getLang()` | Ngôn ngữ: `'vi'` hoặc `'en'`             |

**Returns:** `string` — chuỗi đã format, hoặc `''` nếu input là null/undefined.

## Format Aliases (locale-aware)

| Alias      | Format vi                  | Format en                  | Ghi chú                 |
| ---------- | -------------------------- | -------------------------- | ----------------------- |
| `dmy hm`   | `D MMM, YYYY HH:mm`        | `MMM D, YYYY HH:mm`        | Ngày tháng năm giờ phút |
| `dmy`      | `D MMM, YYYY`              | `MMM D, YYYY`              | Ngày tháng năm          |
| `dm`       | `D MMM`                    | `MMM D`                    | Ngày tháng              |
| `my`       | `MMM, YYYY`                | `MMM YYYY`                 | Tháng năm               |
| `dmy hms`  | `D MMM, YYYY HH:mm:ss`     | `MMM D, YYYY HH:mm:ss`     | Có giây                 |
| `dmy hmsS` | `D MMM, YYYY HH:mm:ss:SSS` | `MMM D, YYYY HH:mm:ss:SSS` | Có millisecond          |
| `HH:mm`    | `HH:mm`                    | `HH:mm`                    | 24h format              |
| `HH:mm A`  | `HH:mm A`                  | `HH:mm A`                  | 12h AM/PM               |

Format string trực tiếp (như `DD/MM/YYYY`, `YYYY-MM-DD`...) cũng được hỗ trợ — không locale-aware.

## Lưu ý quan trọng

- **Inject service hay dùng thẳng utils?** Nếu chỉ cần trong TypeScript class, dùng thẳng `formatDate()` từ `@libs-ui/utils` — không inject service. Inject service khi cần DI (mock test) hoặc dùng trong template qua service reference.
- **lang** không truyền → tự lấy từ `UtilsCache.getLang()`. Đảm bảo set ngôn ngữ global trước khi dùng.
- **Unix timestamp** là số nguyên **giây** (không phải milliseconds). `Date.now()` trả về ms → chia 1000.
- **Format aliases** chỉ có tác dụng locale-aware khi dùng với `lang='vi'` hoặc `lang='en'`. Format string trực tiếp không phụ thuộc ngôn ngữ.