Define a resource
engine.defineResource(root, options) creates a resource for one root table. Every option is optional except the root name.
import { engine } from "./engine";
const ordersResource = engine.defineResource("orders", {
relations: {}, // relations that may be loaded and used in field paths
hydration: {}, // named subsets of relations per read method
views: {}, // exact response shapes
query: {}, // scope, search, sort, filters, facets, pagination, defaults
summary: undefined, // totals over the filtered set
strategy: {}, // custom implementations of single steps
});
| Option | Controls | Details |
|---|---|---|
root | The table the resource is built on, by its name in your schema. | This page |
relations | Which relations exist for this resource, for loading and field paths. | Relations |
hydration | Which relations each read method loads by default. | Relations |
views | Exact response shapes, each with an inferred row type. | Views |
query | Scope, search, sorting, filters, facets, pagination and defaults. | Below |
summary | Aggregates over the whole filtered set. | Summaries |
strategy | Your own implementation of the ids, rows, facets or full query step. | Strategies |
relations
The relations a resource may load and use in field paths:
import { engine } from "./engine";
engine.defineResource("orders", {
relations: {
customer: true,
orderLines: {
with: {
product: true,
},
},
},
});
This makes customer.name, orderLines.product.name and orderLines.product.category valid paths for search, sorting, filters and facets. Filtering through a relation does not require returning it: the page-ids query joins what the filters need, row loading uses what the read method asks for.
hydration
Named subsets of relations, so a list loads less than a detail page without a second resource:
import { engine } from "./engine";
engine.defineResource("orders", {
relations: {
customer: true,
orderLines: { with: { product: true } },
},
hydration: {
profiles: {
list: { customer: true },
detail: {
customer: true,
orderLines: { with: { product: true } },
},
root: {},
},
defaults: {
query: "list",
findById: "detail",
},
},
});
query() and queryRows() use the query default, findById() the findById default. Without a default, the full relations tree is loaded. A call can choose a profile, or pass its own subset, with load:
const detailPage = await ordersResource.query({
request,
context: { orgId: "acme" },
load: "detail",
});
const customerOnly = await ordersResource.findById({
id: "order_123",
context: { orgId: "acme" },
load: { customer: true },
});
load replaces the default exactly; profiles are never merged. It is a server-side choice and is not part of the client request.
query
query.scope
Filters added to every request on the server, typically the tenant:
const query = {
scope: (f: ExampleFilterBuilder, ctx: { orgId: string }) =>
f.and([f.is("customer.orgId", ctx.orgId)]),
};
See Scope.
query.search
The fields a search may match, and the ones used when the request lists none:
const query = {
search: {
allowed: ["reference", "customer.name", "orderLines.product.name"],
defaults: ["reference", "customer.name"],
},
} satisfies { search: ExampleSearchConfig };
See Search.
query.sort
The default order, and keys clients may not sort by:
const query = {
sort: {
defaults: [{ key: "createdAt", dir: "desc" }],
disabled: ["orderLines.product.name"],
},
} satisfies { sort: ExampleSortConfig };
See Sorting.
query.filters
Fields clients may not filter on:
const query = {
filters: {
hidden: [],
disabled: [],
},
} satisfies { filters: ExampleFiltersConfig };
hidden removes a field from client requests while the scope can still use it. disabled removes it for everyone, the scope included. See Field rules.
query.facets
Fields clients may request bucket counts for:
const query = {
facets: {
allowed: ["status", "customer.name", "orderLines.product.category.label"],
},
} satisfies { facets: ExampleFacetsConfig };
A facet key outside allowed is rejected. See Facets.
query.pagination and query.defaults
pagination.modes lists the modes clients may use ("offset", "cursor"). defaults.pagination fills in what the request leaves out:
const query = {
defaults: {
pagination: { pageSize: 25 },
},
} satisfies { defaults: ExampleDefaultsConfig };
See Pagination.
strategy
Your own implementation of one step, when the generated SQL isn't the plan you want. Measure first; see Strategies.