Skip to Content

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 đã qua listSchema.
  • 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 theo search, khớp LIKE '%…%' 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 trong sort → 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 định createdAt giảm dần, bảng không có createdAt thì theo id.
  • opts.maxPageSize: cỡ trang lớn nhất, mặc định 100.
  • opts.counts: tên một khoá trong filters, 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; check cảnh báo perf.order-unindexed khi thiếu.
  • Join, gộp nhóm, cột tính toán: viết Drizzle bằng db. listOf dà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