listSchema, listOf
listSchema kiểm query của API danh sách: trang, tìm, lọc, sắp xếp. listOf chạy truy vấn đó trên một bảng và trả { data, total }.
Cách dùng
app/orders/get.ts
import { z } from "@hono/zod-openapi";
import { listSchema } from "app/db";
import { OrderStatus } from "app/shared/order";
import { listOrders } from "./repository";
export const schema = {
query: listSchema({ filters: { status: z.enum(OrderStatus.values).optional() }, sort: ["createdAt", "total"] }),
};
export default (c, { user, query }) => listOrders(user, query);app/orders/repository.ts
import { eq, listOf } from "app/db";
import { orders } from "./orders.table";
export const listOrders = (user, query) =>
listOf(orders, query, {
search: [orders.customerName, orders.code],
filters: { status: orders.status },
sort: { createdAt: orders.createdAt, total: orders.total },
where: user.role === "sales" ? eq(orders.createdBy, user.id) : undefined,
});Chữ ký
app/db.ts
function listSchema(opts?: {
filters?: Record<string, z.ZodType>;
sort?: string[];
pageSize?: number;
maxPageSize?: number;
}): z.ZodObject;
function listOf(table: SQLiteTable, query: object, opts?: {
where?: SQL;
search?: Column[];
filters?: Record<string, Column>;
sort?: Record<string, Column>;
defaultSort?: SQL;
maxPageSize?: number;
counts?: string;
}): Promise<{ data: Row[]; total: number; counts?: Record<string, number> }>;Tham số
listSchema(opts):
filters: các trường lọc thêm, mỗi trường một schema zod. Trường không khai báo ở đây bị bỏ khỏi query.sort: tên các cột client được sắp xếp theo.pageSize: cỡ trang mặc định, mặc định 20.maxPageSize: cỡ trang lớn nhất, mặc định 100.
listOf(table, query, opts):
table: bảng cần đọc.query: query đã qualistSchema.opts.where: điều kiện luôn áp, dùng để giới hạn dòng theo vai.opts.search: các cột tìm theosearch, khớpLIKE '%…%'trên bất kỳ cột nào.opts.filters: tên trường query → cột, so bằng. Giá trị rỗng thì bỏ qua.opts.sort: tên trongsort→ cột. Chỉ các tên có ở đây mới sắp xếp được.opts.defaultSort: thứ tự khi client không chọn. Mặc địnhcreatedAtgiảm dần, bảng không cócreatedAtthì theoid.opts.maxPageSize: cỡ trang lớn nhất, mặc định 100.opts.counts: tên một khoá trongfilters, thường là"status". Kết quả có thêm số dòng theo từng giá trị của trường đó, đã áp mọi bộ lọc khác, để vẽ tab trạng thái có số đếm.
Trả về
listSchema trả một object zod nhận page (hoặc current của ProTable), pageSize, search (tối đa 200 ký tự), order (asc hoặc desc), sort (chỉ các tên đã khai báo) và các trường trong filters.
listOf trả Promise<{ data, total }>: data là các dòng của đúng một trang, total là tổng số dòng khớp điều kiện. Có counts thì thêm counts, ví dụ { new: 3, done: 12 }.
Ví dụ
Trang danh sách gửi tham số của ProTable thẳng tới API bằng tableRequest (hoặc <ResourceList> của manh/shell). Tự gọi thì truyền như sau:
app/orders/page.tsx
const { data, total } = await api.orders.list({ ...params, search: keyword });- Đánh index cho các cột trong
sort;checkcảnh báoperf.order-unindexedkhi thiếu. - Join, gộp nhóm, cột tính toán: viết Drizzle bằng db.
listOfdành cho danh sách thường.
Bước tiếp theo
- tableRequest: phía giao diện của cùng trang danh sách.
- Database: khai báo bảng và repository.
Cập nhật