Server contract (helpers)

aggregateCount, aggregateScalar, byCount, byField and 12 more: generated from the source of active-grid.

Exported by @workspace/active-grid. Generated from the package source; part of the index of every export.

Functions, hooks and constants#

Aggregate mapping for a count. With relation: produces Prisma _count: {<relation>: true} — number of related records per group. With relation: null or omitted: produces Prisma _count: {_all: true} — number of rows per group, regardless of any specific field.

(args?: { relation?: string; }) => AggregateCountMapping

Fields of args

The object it takes.

relation

Type: string

aggregateScalar

Aggregate mapping on a scalar field. Declares and selects: under the single-source-of-truth model, the listed ops are both "what is possible for this column" and "what is displayed per group". There is no aggregate-toggle UI; a separate selection layer (engine-state or opt-in prop) could sit on top of this declaration without breaking it.

If path is omitted, the column-id is used. ops must be a non-empty subset of AggregateOp (sum | avg | min | max | count). Prisma's _count/_sum/_avg/_min/_max-blocks are built from this list.

Note: count here is the non-null-count on the scalar (Prisma _count: {<field>: true}). For relation-counts use aggregateCount with a relation argument.

No DMMF-derived default for aggregates. Auto-defaulting sum/avg over every numeric scalar is semantically dangerous — a versionNumber column is valid Prisma but nonsensical UX. Consumer declares aggregate explicitly per column.

(args: { path?: string; ops: readonly AggregateOp[]; }) => AggregateScalarMapping

Fields of args

The object it takes.

path

Type: string

The field of the related record, as a dotted path (role.name).

opsrequired

Type: readonly AggregateOp[]

byCount

Type: (relation: string) => SortCountMapping

Sort mapping on the count of a relation. Produces Prisma orderBy: {<relation>: {_count: <direction>}}.

byField

Type: (path?: string) => SortFieldMapping

Sort mapping on a scalar field. If path is omitted, the server uses the column-id as path.

everyByField

Filter mapping with relation every. The filter passes only if every related record matches.

(args: { relation: string; path: string; filterType?: ColumnFilterType; }) => FilterRelationMapping

Fields of args

The object it takes.

relationrequired

Type: string

The relation on the record the condition runs through, as the server query names it (userRoles in userRoles: {some: …}).

pathrequired

Type: string

The field of the related record, as a dotted path (role.name).

filterType

Type: ColumnFilterType

Overrides type-inference when the operator alone is ambiguous (equals can be text, number or date).

fieldFilter

Filter mapping on a scalar field. If path is omitted, the server uses the column-id as path. filterType overrides type-inference when the operator alone is ambiguous (e.g. equals can be text / number / date).

(path?: string, options?: { filterType?: ColumnFilterType; }) => FilterFieldMapping

Fields of options

The object it takes.

filterType

Type: ColumnFilterType

Overrides type-inference when the operator alone is ambiguous (equals can be text, number or date).

globalEveryByField

Global-search mapping with relation every. The column participates in the search only if every related record matches the query.

(args: { relation: string; path: string; operator?: GlobalOperator; }) => GlobalRelationMapping

Fields of args

The object it takes.

relationrequired

Type: string

The relation on the record the condition runs through, as the server query names it (userRoles in userRoles: {some: …}).

pathrequired

Type: string

The field of the related record, as a dotted path (role.name).

operator

Type: GlobalOperator

How the query matches: "contains" (case-insensitive) when omitted, "startsWith" for a prefix match, "equals" for an exact match.

globalField

Mark a column as participating in the global search-box (the toolbar's single-search input). When the user types a query and column.server.global is set on at least one column, the server-action wraps the per-column conditions in an OR-clause that is ANDed with the column-filters and extraWhere.

If path is omitted, the column-id is used (consistent with byField / fieldFilter). operator defaults to "contains" (case-insensitive) on the server side; override for prefix-match ("startsWith") or exact-match ("equals") semantics.

(path?: string, options?: { operator?: GlobalOperator; }) => GlobalFieldMapping

Fields of options

The object it takes.

operator

Type: GlobalOperator

How the query matches: "contains" (case-insensitive) when omitted, "startsWith" for a prefix match, "equals" for an exact match.

globalNoneByField

Global-search mapping with relation none. The column participates in the search only if no related record matches the query.

(args: { relation: string; path: string; operator?: GlobalOperator; }) => GlobalRelationMapping

Fields of args

The object it takes.

relationrequired

Type: string

The relation on the record the condition runs through, as the server query names it (userRoles in userRoles: {some: …}).

pathrequired

Type: string

The field of the related record, as a dotted path (role.name).

operator

Type: GlobalOperator

How the query matches: "contains" (case-insensitive) when omitted, "startsWith" for a prefix match, "equals" for an exact match.

globalSomeByField

Global-search mapping with relation some. The column participates in the search if at least one related record matches the query.

(args: { relation: string; path: string; operator?: GlobalOperator; }) => GlobalRelationMapping

Fields of args

The object it takes.

relationrequired

Type: string

The relation on the record the condition runs through, as the server query names it (userRoles in userRoles: {some: …}).

pathrequired

Type: string

The field of the related record, as a dotted path (role.name).

operator

Type: GlobalOperator

How the query matches: "contains" (case-insensitive) when omitted, "startsWith" for a prefix match, "equals" for an exact match.

groupByField

Type: (path?: string) => GroupByFieldMapping

Group-by mapping on a scalar field. If path is omitted, the column-id is used as path (same convention as byField / fieldFilter / globalField).

Prisma's groupBy({by: [...]}) only accepts scalar field-names in by. groupByField is the helper for that direct case; for grouping through a 1:1 relation (where the FK is a scalar on the model itself) use groupByRelation(). One-to-many relations are not expressible as a declarative group key (grouping through a to-many relation is ambiguous); server-side grouping for such cases belongs in a resource view (@workspace/active-resources).

groupByRelation

Group-by mapping that resolves through a relation. Intended for 1:1 relations where the FK lives as a scalar on the to-be-grouped model — e.g. provider (FK providerId) with name as the display key. The server uses providerId for Prisma's groupBy.by and path for downstream display resolution; same pattern as how scalarField("user.email") separates Prisma-path from column-id.

For one-to-many relations grouping is ambiguous (which related record's value determines the group?) — those are not expressible here; server-side grouping for such cases belongs in a resource view.

(args: { relation: string; path: string; }) => GroupByRelationMapping

Fields of args

The object it takes.

relationrequired

Type: string

The relation on the record the condition runs through, as the server query names it (userRoles in userRoles: {some: …}).

pathrequired

Type: string

The field of the related record, as a dotted path (role.name).

multiField

Filter mapping that ORs across multiple scalar paths.

(paths: readonly string[], options?: { filterType?: ColumnFilterType; }) => FilterMultiFieldMapping

Fields of options

The object it takes.

filterType

Type: ColumnFilterType

Overrides type-inference when the operator alone is ambiguous (equals can be text, number or date).

noneByField

Filter mapping with relation none. The filter passes only if no related record matches.

(args: { relation: string; path: string; filterType?: ColumnFilterType; }) => FilterRelationMapping

Fields of args

The object it takes.

relationrequired

Type: string

The relation on the record the condition runs through, as the server query names it (userRoles in userRoles: {some: …}).

pathrequired

Type: string

The field of the related record, as a dotted path (role.name).

filterType

Type: ColumnFilterType

Overrides type-inference when the operator alone is ambiguous (equals can be text, number or date).

scalarField

Shortcut that fills both sort and filter for a scalar column. The 80%-case helper.

scalarField() — uses the column-id as path (deferred resolution on the server when the column-id is dotted).
scalarField("user.email") — explicit nested path; both sort and filter use this path.

Returns a Pick<ServerColumnContract, "sort" | "filter"> that can be spread or assigned directly to column.server.

(path?: string) => Pick<ServerColumnContract, "sort" | "filter">

someByField

Filter mapping with relation some. The filter passes if at least one related record matches.

(args: { relation: string; path: string; filterType?: ColumnFilterType; }) => FilterRelationMapping

Fields of args

The object it takes.

relationrequired

Type: string

The relation on the record the condition runs through, as the server query names it (userRoles in userRoles: {some: …}).

pathrequired

Type: string

The field of the related record, as a dotted path (role.name).

filterType

Type: ColumnFilterType

Overrides type-inference when the operator alone is ambiguous (equals can be text, number or date).