import {Meta} from '@storybook/addon-docs/blocks'

<Meta title='@dxtmisha/vi/functional/! Về thư viện'/>

# [@dxtmisha/functional](https://github.com/dxtmisha/dxt-ui/tree/main/packages/functional)

`@dxtmisha/functional` là một thư viện chứa các tiện ích, lớp cơ sở (base class) và composable dùng cho việc phát triển web phức tạp trên Vue 3.

Các ứng dụng frontend hiện đại đòi hỏi phải quản lý hàng tá tiến trình bất đồng bộ: lấy dữ liệu thông qua API, đồng bộ hóa các tab, làm việc với bộ nhớ cục bộ, định dạng ngày tháng và thích ứng với ngôn ngữ của người dùng. Thông thường, lập trình viên giải quyết những vấn đề này theo cách cục bộ bên trong các component, dẫn đến việc lặp lại code, các tệp `.vue` trở nên "cồng kềnh", và xảy ra lỗi liên quan đến việc không dọn dẹp các sự kiện hay bộ đếm thời gian. Gói này hoạt động dựa trên cơ sở của [@dxtmisha/functional-basic](https://github.com/dxtmisha/dxt-ui/tree/main/packages/functional), cung cấp các lớp bọc phản ứng và các giải pháp kiến trúc được tạo ra đặc biệt để giải quyết những vấn đề này trong hệ sinh thái Vue (Composition API).

## Cài đặt

```bash
npm i @dxtmisha/functional
```

## Tại sao cần thư viện này?

Ý tưởng chính của gói là tách biệt logic nghiệp vụ thông thường và logic phụ (side effect) ra khỏi các component, làm cho quá trình này được định kiểu nghiêm ngặt và mặc định mang tính phản ứng (reactive).

Bạn không còn cần phải tự đồng bộ hóa các yêu cầu HTTP với trạng thái cục bộ của giao diện, viết wrapper để lưu cache dữ liệu phản ứng hay phát minh ra cách làm việc với LocalStorage bên trong component nữa. Thư viện cung cấp sẵn các cấu trúc phản ứng để tự động đảm nhận công việc này. Bạn chỉ cần gọi composable hoặc class cần thiết, và ở phần lõi bên dưới, thư viện sẽ tự động quản lý các tham chiếu phản ứng (`ref`), theo dõi vòng đời của Vue, dọp dẹp bộ nhớ (garbage collector) khi component bị unmount, và duy trì hệ thống định kiểu TypeScript nghiêm ngặt.

## Các đặc điểm nổi bật và Phương pháp phát triển

**Tích hợp hoàn toàn với Composition API**
Mỗi tiện ích trong thư viện đều được thiết kế xoay quanh hệ thống phản ứng của Vue 3. Dữ liệu từ kho lưu trữ trữ, phản hồi API, hay ngôn ngữ của hệ thống luôn được trả về dưới dạng các đối tượng phản ứng (reactive objects). Nếu cấu hình thay đổi, tất cả các component phụ thuộc vào dữ liệu đó đều sẽ tự động cập nhật.

**Phân tách cấu trúc rõ ràng (Separation of Concerns)**
Về tư tưởng kiến trúc, gói này khuyến khích nhà phát triển viết các component "mỏng". Toàn bộ logic validate form, quản lý nhiều trạng thái phức tạp (`loading`, `error`, `success`), chuẩn bị dữ liệu gọi API và lưu trữ cache đều được gom vào trong những class hay composable chuyên dụng. File `.vue` chỉ còn giữ lại việc khai báo liên kết cho các biến đối với giao diện (template).

**An toàn kiểu dữ liệu (Type Safety)**
Nhờ hệ thống giao diện Interface của TypeScript rất tối ưu, bộ code này bảo vệ tỷ lệ an toàn kiểu đạt 100% giữa kho dữ liệu API, bộ nhớ, và phía màn hình UI. Thuộc tính suy luận kiểu tự động (Type inference) cùng các Generic chống lại tình trạng sai chính tả hoặc trục trặc phát sinh khi sửa cấu trúc (Refactoring). IDE luôn nhận diện được dữ liệu nhận lại những trường (fields) gì từ API và gọi ra những method (hàm phương thức) nào trực thuộc Class.

**Quản lý tài nguyên dễ dự đoán**
Đảm bảo quản lý bảo mật thông tin và giải phóng tối ưu vùng lưu trữ RAM cho bộ nhớ. Nếu ứng dụng (component) có sinh lệnh báo với server hoặc liên tục tiếp nhận thông tin cập nhật (listener) mà bị hủy đi, mọi process và tiến trình chạy kèm sẽ được xử lý chấm dứt đúng quy chuẩn, bảo vệ cho ứng dụng của bạn không rò rỉ và tràn tốn Memory.

## Thư viện có thể làm gì?

Thư viện đáp ứng đầy đủ tất cả nhu cầu thiết yếu nhất khi bạn muốn phát triển một ứng dụng mạng lưới frontend mức độ đa nhiệm lớn:

**Gọi mạng từ xa (Requests API)**
Bao trọn nhóm composable đặc tả quy cách gọi server (`useApiGet`, `useApiPost`, `useApiPut`, `useApiDelete`, `useApiRequest`). Khi mới gọi, chúng đã trả về đầy đủ đối tượng mang thông số có sẵn, chứa đựng trạng thái theo dõi tiến trình (`loading`), cập nhật lưu lỗi lại, và các dữ liệu hoàn thành (`item`, `list`). Hệ thống "có sẵn" còn đem khả năng lưu giữ, huỷ nhanh (cancel) truy vết cũ dư thừa đi không gửi nhầm kết quả (tính chất siêu cần cho Live search lập lại truy vấn), tuỳ chọn cấu hình cực kì gọn nhẹ trong Header.

**Bộ duy trì tình trạng (State storages)**
Bao trọn các hook (`useStorageRef`, `useSessionRef`, `useCookieRef`, `useHashRef`). Chúng làm công cụ kết dính mọi biến khai báo Vue lên vùng bộ nhớ ảo có sẵn trên trình duyệt LocalStorage, SessionStorage, dấu `#` URL hash, hay trên tệp Cookie theo tiêu chuẩn. Chúng cho bạn thỏa thích xử lý biến như một tham trị `ref` tại gốc, rồi trình gói hỗ trợ (library) thực thi những việc gắn kết (sync) thông tin cho trình duyệt Browser lưu lâu dài, tức tốc phổ truyền tín hiệu tới cả màn hình hiển thị trong từng Tab (cửa sổ web) được người dùng song hành để duy trì sử dụng.

**Chuẩn Hóa Đa Ngôn Ngữ (Internationalization) & Format**
Dành bao trọn bộ nhóm xử lý cực chuẩn chỉnh (`useTranslateRef`, `useGeoIntlRef`, `DatetimeRef` hay `GeoFlagRef`), thực thi phản xạ nhận diện các hiệu ứng tại từng tham số (Thay mã nguồn Tiếng, lựa ngoại tệ hay thay Vùng Quốc gia). Những tính chất cập nhật Format tự làm tự tái hiện (Tiếng nói dịch chuyển ngay, đổi thay biểu định Giá, lịch chuyển đổi tháng ngày). Phần việc tái lắp component thực hiện độc lập, nhà tạo tác (dev) không gõ tạo liên lạc các listener phiền toái kia nữa. 

**Nâng Tầm Kiểu Mẫu Giao Diện (Engineering UI - Components)**
Sở hữu phân cấp Class cốt lõi tiêu chuẩn gồm: `DesignAbstract`, `DesignComp`, `DesignChanged`, `DesignAsyncAbstract`. Sự bao quanh vững chắc đã che phủ kín (encapsulate) mọi phần logic hoạt động chuyên biệt xử lý ở cấp chuyên sâu không rập khuôn (Custom selectors, Form hỗn hợp, Các sổ Modal pop up biến chuyển states liên tục), rồi xếp chia chúng tự chủ hoàn toán về các Classes. Nắn tạo việc tính toán các hàm vụ (business logic) sẽ dễ dàng ngắt gắn tại các trang markup tĩnh (HTML), thực hiện kiểm thử an hòa thuận lợi (Testable code), cùng mục đích mang những cấu trúc trên đem trao vào tái triển khai ở phần mềm khác (Re-usable func).

**Công Cụ Hỗ Trợ Đầy Sức Phản Ứng Khác**
Gom chứa tính năng giải toả xử lí các góc ứng suất phụ phản ứng:
- Kẻ thiết định SEO bằng code (`useMeta`), nắn bóp nội hàm tags trên tính trạng màn hình;
- Điệp truyền dữ liệu giữa các web window theo cấp thời lượng Live Real-Time (`useBroadcastValueRef`);
- Phân luồng tín hiệu trạng thái điều tiết đường chuyền Loading (`useLoadingRef`);
- Gọi sự chạy chức năng song hành mà nhẹ tựa bay ngay trên cỗ máy xử lí tạo mã Vue bằng `computedAsync` và `toComputed`.

## Dành cho ai?

Bộ tài nguyên chuyên tâm phục vụ toàn thể đội thi công Frontend Developers đang nặn chế những bộ mã nguồn công nghiệp kinh doanh siêu cỡ lớn, khối bảng mạch Dashboard bao phủ chằng chịt, hoặc đội tự nặn cho mình một khuôn Framework UI từ lõi công nghệ hệ Vue 3. Khử đi triệt để thói gõ tạo Boilerplate lặp liên hồi tốn không gian, tạo những khung sườn đã kinh qua ứng kiểm định hoàn hảo nhất của Patterns (kiểu hình tái thiết hệ sinh thái Dev) bảo toàn chất lương trong tạo dựng an toàn.

## Git

[https://github.com/dxtmisha/dxt-ui/tree/main/packages/functional](https://github.com/dxtmisha/dxt-ui/tree/main/packages/functional)
