Class: Rbac<T>
Defined in: packages/core/src/rbac.ts:265
The RBAC engine. Create one per app with createRbac.
const rbac = createRbac({ adapter: new MemoryAdapter() })
await rbac.createPermission('edit articles')
await rbac.createRole('writer')
await rbac.role('writer').givePermissionTo('edit articles')
await rbac.for({ type: 'user', id: 1 }).assignRole('writer')
await rbac.for({ type: 'user', id: 1 }).can('edit articles') // trueT optionally narrows the accepted permission / role names, see RbacTypeConfig.
Type Parameters
| Type Parameter | Default type |
|---|---|
T extends RbacTypeConfig | DefaultRbacTypes |
Constructors
Constructor
new Rbac<T>(options): Rbac<T>;Defined in: packages/core/src/rbac.ts:282
Parameters
| Parameter | Type |
|---|---|
options | RbacOptions<T> |
Returns
Rbac<T>
Properties
| Property | Modifier | Type | Defined in |
|---|---|---|---|
adapter | readonly | RbacAdapter | packages/core/src/rbac.ts:266 |
defaultGuard | readonly | string | packages/core/src/rbac.ts:267 |
teams | readonly | boolean | packages/core/src/rbac.ts:269 |
wildcard | readonly | boolean | packages/core/src/rbac.ts:268 |
Methods
createPermission()
createPermission<G>(name, options?): Promise<Permission>;Defined in: packages/core/src/rbac.ts:362
Type Parameters
| Type Parameter | Default type |
|---|---|
G extends string | DefaultGuardName<T> |
Parameters
| Parameter | Type |
|---|---|
name | PermissionName<T, G> |
options? | GuardOptions<CheckGuard<T, G>> & ActorOptions |
Returns
Promise<Permission>
createRole()
createRole<G>(name, options?): Promise<Role>;Defined in: packages/core/src/rbac.ts:444
Type Parameters
| Type Parameter | Default type |
|---|---|
G extends string | DefaultGuardName<T> |
Parameters
| Parameter | Type |
|---|---|
name | RoleName<T, G> |
options? | ScopeOptions<CheckGuard<T, G>> & ActorOptions |
Returns
Promise<Role>
deletePermission()
deletePermission<G>(permission, options?): Promise<void>;Defined in: packages/core/src/rbac.ts:431
Type Parameters
| Type Parameter | Default type |
|---|---|
G extends string | DefaultGuardName<T> |
Parameters
| Parameter | Type |
|---|---|
permission | PermissionInput<PermissionName<T, G>> |
options? | GuardOptions<CheckGuard<T, G>> & ActorOptions |
Returns
Promise<void>
deleteRole()
deleteRole<G>(role, options?): Promise<void>;Defined in: packages/core/src/rbac.ts:521
Type Parameters
| Type Parameter | Default type |
|---|---|
G extends string | DefaultGuardName<T> |
Parameters
| Parameter | Type |
|---|---|
role | RoleInput<RoleName<T, G>> |
options? | ScopeOptions<CheckGuard<T, G>> & ActorOptions |
Returns
Promise<void>
deleteTeam()
deleteTeam(teamId): Promise<void>;Defined in: packages/core/src/rbac.ts:663
Deletes a team: every role and direct permission held in it (by any subject, in every guard), and every role scoped to it (teamId), with their permission links. Global roles and permissions stay. Emits role.detached / permission.detached per subject and guard, then role.deleted per team role. Clears the cache, so no member keeps cached access.
Throws TEAMS_NOT_ENABLED without teams: true, and ADAPTER_METHOD_MISSING (before any write) when the adapter has no getTeamLinks(). Not atomic: a failure midway leaves the rest of the team in place.
Parameters
| Parameter | Type |
|---|---|
teamId | Id |
Returns
Promise<void>
findOrCreatePermission()
findOrCreatePermission<G>(name, options?): Promise<Permission>;Defined in: packages/core/src/rbac.ts:418
Type Parameters
| Type Parameter | Default type |
|---|---|
G extends string | DefaultGuardName<T> |
Parameters
| Parameter | Type |
|---|---|
name | PermissionName<T, G> |
options? | GuardOptions<CheckGuard<T, G>> & ActorOptions |
Returns
Promise<Permission>
findOrCreateRole()
findOrCreateRole<G>(name, options?): Promise<Role>;Defined in: packages/core/src/rbac.ts:506
Type Parameters
| Type Parameter | Default type |
|---|---|
G extends string | DefaultGuardName<T> |
Parameters
| Parameter | Type |
|---|---|
name | RoleName<T, G> |
options? | ScopeOptions<CheckGuard<T, G>> & ActorOptions |
Returns
Promise<Role>
findPermission()
findPermission<G>(name, options?): Promise<Permission | null>;Defined in: packages/core/src/rbac.ts:392
Type Parameters
| Type Parameter | Default type |
|---|---|
G extends string | DefaultGuardName<T> |
Parameters
| Parameter | Type |
|---|---|
name | PermissionName<T, G> |
options? | GuardOptions<CheckGuard<T, G>> |
Returns
Promise<Permission | null>
findPermissionById()
findPermissionById(id, options?): Promise<Permission | null>;Defined in: packages/core/src/rbac.ts:413
Finds a permission by id in the guard (spatie: Permission::findById($id, $guard)), or null.
Parameters
| Parameter | Type |
|---|---|
id | Id |
options? | GuardOptions |
Returns
Promise<Permission | null>
findPermissionOrFail()
findPermissionOrFail<G>(name, options?): Promise<Permission>;Defined in: packages/core/src/rbac.ts:403
Type Parameters
| Type Parameter | Default type |
|---|---|
G extends string | DefaultGuardName<T> |
Parameters
| Parameter | Type |
|---|---|
name | PermissionName<T, G> |
options? | GuardOptions<CheckGuard<T, G>> |
Returns
Promise<Permission>
findRole()
findRole<G>(name, options?): Promise<Role | null>;Defined in: packages/core/src/rbac.ts:462
Finds a role. With a team, a team-specific role wins over a global role of the same name.
Type Parameters
| Type Parameter | Default type |
|---|---|
G extends string | DefaultGuardName<T> |
Parameters
| Parameter | Type |
|---|---|
name | RoleName<T, G> |
options? | ScopeOptions<CheckGuard<T, G>> |
Returns
Promise<Role | null>
findRoleById()
findRoleById(id, options?): Promise<Role | null>;Defined in: packages/core/src/rbac.ts:483
Finds a role by id in the guard (spatie: Role::findById($id, $guard)), or null.
Parameters
| Parameter | Type |
|---|---|
id | Id |
options? | GuardOptions |
Returns
Promise<Role | null>
findRoleOrFail()
findRoleOrFail<G>(name, options?): Promise<Role>;Defined in: packages/core/src/rbac.ts:473
Type Parameters
| Type Parameter | Default type |
|---|---|
G extends string | DefaultGuardName<T> |
Parameters
| Parameter | Type |
|---|---|
name | RoleName<T, G> |
options? | ScopeOptions<CheckGuard<T, G>> |
Returns
Promise<Role>
for()
for<G>(subject, options?): SubjectRbac<T, ScopedGuardName<T, G>>;Defined in: packages/core/src/rbac.ts:322
Work with the roles & permissions of a subject (usually a user). With per-guard names, the subject takes the names of options.guard (the default guard's without it).
Type Parameters
| Type Parameter | Default type |
|---|---|
G extends string | DefaultGuardName<T> |
Parameters
| Parameter | Type |
|---|---|
subject | Subject |
options? | ScopeOptions<CheckGuard<T, G>> & ActorOptions |
Returns
SubjectRbac<T, ScopedGuardName<T, G>>
forgetCachedPermissions()
forgetCachedPermissions(): Promise<void>;Defined in: packages/core/src/rbac.ts:714
Clears every cached role/permission lookup. Called automatically after each change.
Returns
Promise<void>
getPermissions()
getPermissions(options?): Promise<Permission[]>;Defined in: packages/core/src/rbac.ts:427
Parameters
| Parameter | Type |
|---|---|
options? | GuardOptions |
Returns
Promise<Permission[]>
getRoles()
getRoles(options?): Promise<Role[]>;Defined in: packages/core/src/rbac.ts:516
Lists roles visible in the given scope (global roles + roles of the given team).
Parameters
| Parameter | Type |
|---|---|
options? | ScopeOptions |
Returns
Promise<Role[]>
off()
off<K>(event, listener): void;Defined in: packages/core/src/rbac.ts:356
Removes a listener added with on.
Type Parameters
| Type Parameter |
|---|
K extends keyof RbacEventMap |
Parameters
| Parameter | Type |
|---|---|
event | K |
listener | RbacEventListener<K> |
Returns
void
on()
on<K>(event, listener): () => void;Defined in: packages/core/src/rbac.ts:351
Listens to an event. Listeners run in registration order and are awaited one by one, after the change has been written by the adapter. Returns an unsubscribe function.
Type Parameters
| Type Parameter |
|---|
K extends keyof RbacEventMap |
Parameters
| Parameter | Type |
|---|---|
event | K |
listener | RbacEventListener<K> |
Returns
() => void
pruneExpired()
pruneExpired(): Promise<DeletedLinkCounts>;Defined in: packages/core/src/rbac.ts:678
Deletes every role assignment and direct permission whose expiresAt has passed (by the engine's clock), for every subject, team and guard. Checks already ignore them, so access doesn't change: this only keeps the tables small. Run it from a scheduled job. Emits no events (the access ended at expiresAt, not now) and leaves the cache alone. Returns how many links were deleted.
A no-op returning zeros when the adapter has no expiry support. Throws ADAPTER_METHOD_MISSING when it declares supportsExpiry without deleteExpiredLinks().
Returns
Promise<DeletedLinkCounts>
role()
role<G>(role, options?): RoleRbac<T, ScopedGuardName<T, G>>;Defined in: packages/core/src/rbac.ts:335
Work with the permissions of a role. With per-guard names, the name and the permissions are those of options.guard (a role object keeps its own guard at runtime; pass guard to type it too).
Type Parameters
| Type Parameter | Default type |
|---|---|
G extends string | DefaultGuardName<T> |
Parameters
| Parameter | Type |
|---|---|
role | RoleInput<RoleName<T, G>> |
options? | ScopeOptions<CheckGuard<T, G>> & ActorOptions |
Returns
RoleRbac<T, ScopedGuardName<T, G>>
rolesWithPermission()
rolesWithPermission<G>(permission, options?): Promise<Role[]>;Defined in: packages/core/src/rbac.ts:492
Roles in the given scope that grant the permission directly (spatie: $permission->roles). Throws PermissionDoesNotExist for an unknown permission. Wildcard grants are not expanded.
Type Parameters
| Type Parameter | Default type |
|---|---|
G extends string | DefaultGuardName<T> |
Parameters
| Parameter | Type |
|---|---|
permission | PermissionInput<PermissionName<T, G>> |
options? | ScopeOptions<CheckGuard<T, G>> |
Returns
Promise<Role[]>
subjectsWithoutPermission()
subjectsWithoutPermission<G>(
subjectType,
permissions,
options
): Promise<Id[]>;Defined in: packages/core/src/rbac.ts:643
The ids of options.among that have NONE of the given permissions in the given scope, directly or through a role (spatie: User::withoutPermission('edit')->get()). Same rules, options and errors as subjectsWithPermission, including expandWildcards. Super-admins and the before hook are not taken into account: only stored data is.
Type Parameters
| Type Parameter | Default type |
|---|---|
G extends string | DefaultGuardName<T> |
Parameters
| Parameter | Type |
|---|---|
subjectType | string |
permissions | Many<PermissionInput<PermissionName<T, G>>> |
options | SubjectsWithoutPermissionOptions<CheckGuard<T, G>> |
Returns
Promise<Id[]>
subjectsWithoutRole()
subjectsWithoutRole<G>(
subjectType,
roles,
options
): Promise<Id[]>;Defined in: packages/core/src/rbac.ts:628
The ids of options.among that have NONE of the given roles in the given scope (spatie: User::withoutRole('writer')->get()). The engine only knows subjects with assignments, so pass the candidates: a page of your users, for example. Same rules and errors as subjectsWithRole: an expired assignment doesn't count, and unknown roles throw RoleDoesNotExist.
const ids = users.map((u) => u.id)
await rbac.subjectsWithoutRole('user', 'admin', { among: ids }) // the non-admins among themType Parameters
| Type Parameter | Default type |
|---|---|
G extends string | DefaultGuardName<T> |
Parameters
| Parameter | Type |
|---|---|
subjectType | string |
roles | Many<RoleInput<RoleName<T, G>>> |
options | SubjectsWithoutRoleOptions<CheckGuard<T, G>> |
Returns
Promise<Id[]>
subjectsWithPermission()
subjectsWithPermission<G>(
subjectType,
permissions,
options?
): Promise<Id[]>;Defined in: packages/core/src/rbac.ts:591
Ids of subjects of subjectType that have ANY of the given permissions in the given scope — directly or via one of their roles (spatie: User::permission('edit')->get()). Throws PermissionDoesNotExist for unknown permissions. Wildcards are not expanded, unless expandWildcards: true is passed with wildcard: true: then holders of a wildcard that implies a name (articles.*, *) are returned too, and the names don't need to exist.
Type Parameters
| Type Parameter | Default type |
|---|---|
G extends string | DefaultGuardName<T> |
Parameters
| Parameter | Type |
|---|---|
subjectType | string |
permissions | Many<PermissionInput<PermissionName<T, G>>> |
options? | SubjectsWithPermissionOptions<CheckGuard<T, G>> |
Returns
Promise<Id[]>
subjectsWithRole()
subjectsWithRole<G>(
subjectType,
roles,
options?
): Promise<Id[]>;Defined in: packages/core/src/rbac.ts:567
Ids of subjects of subjectType that have ANY of the given roles in the given scope (spatie: User::role('writer')->get()). Throws RoleDoesNotExist for unknown roles.
Type Parameters
| Type Parameter | Default type |
|---|---|
G extends string | DefaultGuardName<T> |
Parameters
| Parameter | Type |
|---|---|
subjectType | string |
roles | Many<RoleInput<RoleName<T, G>>> |
options? | ScopeOptions<CheckGuard<T, G>> |
Returns
Promise<Id[]>
sync()
sync<G>(definition, options?): Promise<SyncResult>;Defined in: packages/core/src/rbac.ts:553
Declaratively seeds roles & permissions (spatie's "Database Seeding"): creates missing permissions and roles, and syncs each role's permissions to exactly the given list. Idempotent — running it again changes nothing. Uses the regular engine methods, so the usual events fire.
await rbac.sync({
permissions: ['edit articles', 'delete articles'],
roles: { admin: '*', writer: ['edit articles'] },
})'*'gives a role every permission of its guard (after the sync).- Pass an array of definitions (each with its own
guard/team) to sync several scopes. prune: truedeletes roles & permissions of the synced scopes that aren't in the definition.dryRun: truereturns the plan without writing anything.
Not atomic: adapters have no transactions, so a failure midway leaves the earlier changes.
Type Parameters
| Type Parameter | Default type |
|---|---|
G extends string | DefaultGuardName<T> |
Parameters
| Parameter | Type |
|---|---|
definition | SyncDefinitions<T, G> |
options? | SyncOptions<CheckGuard<T, G>> |
Returns
Promise<SyncResult>
