defineRoles
defineRoles<
Name>(definitions,options?):object
Defined in: packages/schema/src/access/roles.ts:44
Defines roles as bundles of capability strings. Pass the resource and area names as the type
parameter to reject unknown names at compile time:
defineRoles<'orders' | 'costs'>({ sales: ['orders.read.own'] }).
An entry may limit capabilities to fields (an allowlist) and rows (an AIP-160 filter):
{ 'products.read': ['sku', 'price'] }, { 'products.read': { fields: ['name'], filter: 'published = true' } }.
The role anonymous, when defined, is what requests without a token act as; it may only read listed fields, and
create listed fields through a public form.
See Access.
Type Parameters
Section titled “Type Parameters”Name extends string = string
Parameters
Section titled “Parameters”definitions
Section titled “definitions”Record<string, readonly RoleEntry<Name>[]>
options?
Section titled “options?”RolesOptions = {}
Returns
Section titled “Returns”can: (
capability) =>Rule
A rule that allows when the user’s roles grant the capability: true for an unscoped
grant, a row filter for .own, .team and a limit’s filter, false otherwise.
Parameters
Section titled “Parameters”capability
Section titled “capability”Capability<Name>
Returns
Section titled “Returns”definitions
Section titled “definitions”definitions:
Record<string, readonlyRoleEntry<Name>[]>
The roles as defined, by name.
fields
Section titled “fields”fields: (
user,capability) => readonlystring[] |undefined
The fields the user’s roles allow for a capability: the union of their lists, or undefined when a role grants
it without a list (every field) or none grants it.
Parameters
Section titled “Parameters”capability
Section titled “capability”string
Returns
Section titled “Returns”readonly string[] | undefined
grants
Section titled “grants”grants: (
user,capability) =>Set<Grant>
Scopes granted by the user’s roles for a capability, without applying them.
Parameters
Section titled “Parameters”capability
Section titled “capability”string
Returns
Section titled “Returns”Set<Grant>
has: (
user,capability) =>boolean
Whether the user holds the capability at all, in any scope. For areas and field rules.
Parameters
Section titled “Parameters”capability
Section titled “capability”Capability<Name>
Returns
Section titled “Returns”boolean
is: (…
roles) =>Rule
A rule that allows when the user has any of the roles.
Parameters
Section titled “Parameters”…string[]
Returns
Section titled “Returns”limits
Section titled “limits”limits:
RoleLimit[]
The capabilities limited to fields or rows, by role.
Example
Section titled “Example”const roles = defineRoles<'orders' | 'products'>({ admin: ['*'], sales: ['orders.read.own', 'orders.create', 'products.read'], reseller: [{ 'products.read': { fields: ['sku', 'name', 'price'], filter: 'published = true' } }],})