Skip to content

Class: Rbac<T> ​

Defined in: packages/core/src/rbac.ts:265

The RBAC engine. Create one per app with createRbac.

ts
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') // true

T optionally narrows the accepted permission / role names, see RbacTypeConfig.

Type Parameters ​

Type ParameterDefault type
T extends RbacTypeConfigDefaultRbacTypes

Constructors ​

Constructor ​

ts
new Rbac<T>(options): Rbac<T>;

Defined in: packages/core/src/rbac.ts:282

Parameters ​

ParameterType
optionsRbacOptions<T>

Returns ​

Rbac<T>

Properties ​

PropertyModifierTypeDefined in
adapterreadonlyRbacAdapterpackages/core/src/rbac.ts:266
defaultGuardreadonlystringpackages/core/src/rbac.ts:267
teamsreadonlybooleanpackages/core/src/rbac.ts:269
wildcardreadonlybooleanpackages/core/src/rbac.ts:268

Methods ​

createPermission() ​

ts
createPermission<G>(name, options?): Promise<Permission>;

Defined in: packages/core/src/rbac.ts:362

Type Parameters ​

Type ParameterDefault type
G extends stringDefaultGuardName<T>

Parameters ​

ParameterType
namePermissionName<T, G>
options?GuardOptions<CheckGuard<T, G>> & ActorOptions

Returns ​

Promise<Permission>


createRole() ​

ts
createRole<G>(name, options?): Promise<Role>;

Defined in: packages/core/src/rbac.ts:444

Type Parameters ​

Type ParameterDefault type
G extends stringDefaultGuardName<T>

Parameters ​

ParameterType
nameRoleName<T, G>
options?ScopeOptions<CheckGuard<T, G>> & ActorOptions

Returns ​

Promise<Role>


deletePermission() ​

ts
deletePermission<G>(permission, options?): Promise<void>;

Defined in: packages/core/src/rbac.ts:431

Type Parameters ​

Type ParameterDefault type
G extends stringDefaultGuardName<T>

Parameters ​

ParameterType
permissionPermissionInput<PermissionName<T, G>>
options?GuardOptions<CheckGuard<T, G>> & ActorOptions

Returns ​

Promise<void>


deleteRole() ​

ts
deleteRole<G>(role, options?): Promise<void>;

Defined in: packages/core/src/rbac.ts:521

Type Parameters ​

Type ParameterDefault type
G extends stringDefaultGuardName<T>

Parameters ​

ParameterType
roleRoleInput<RoleName<T, G>>
options?ScopeOptions<CheckGuard<T, G>> & ActorOptions

Returns ​

Promise<void>


deleteTeam() ​

ts
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 ​

ParameterType
teamIdId

Returns ​

Promise<void>


findOrCreatePermission() ​

ts
findOrCreatePermission<G>(name, options?): Promise<Permission>;

Defined in: packages/core/src/rbac.ts:418

Type Parameters ​

Type ParameterDefault type
G extends stringDefaultGuardName<T>

Parameters ​

ParameterType
namePermissionName<T, G>
options?GuardOptions<CheckGuard<T, G>> & ActorOptions

Returns ​

Promise<Permission>


findOrCreateRole() ​

ts
findOrCreateRole<G>(name, options?): Promise<Role>;

Defined in: packages/core/src/rbac.ts:506

Type Parameters ​

Type ParameterDefault type
G extends stringDefaultGuardName<T>

Parameters ​

ParameterType
nameRoleName<T, G>
options?ScopeOptions<CheckGuard<T, G>> & ActorOptions

Returns ​

Promise<Role>


findPermission() ​

ts
findPermission<G>(name, options?): Promise<Permission | null>;

Defined in: packages/core/src/rbac.ts:392

Type Parameters ​

Type ParameterDefault type
G extends stringDefaultGuardName<T>

Parameters ​

ParameterType
namePermissionName<T, G>
options?GuardOptions<CheckGuard<T, G>>

Returns ​

Promise<Permission | null>


findPermissionById() ​

ts
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 ​

ParameterType
idId
options?GuardOptions

Returns ​

Promise<Permission | null>


findPermissionOrFail() ​

ts
findPermissionOrFail<G>(name, options?): Promise<Permission>;

Defined in: packages/core/src/rbac.ts:403

Type Parameters ​

Type ParameterDefault type
G extends stringDefaultGuardName<T>

Parameters ​

ParameterType
namePermissionName<T, G>
options?GuardOptions<CheckGuard<T, G>>

Returns ​

Promise<Permission>


findRole() ​

ts
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 ParameterDefault type
G extends stringDefaultGuardName<T>

Parameters ​

ParameterType
nameRoleName<T, G>
options?ScopeOptions<CheckGuard<T, G>>

Returns ​

Promise<Role | null>


findRoleById() ​

ts
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 ​

ParameterType
idId
options?GuardOptions

Returns ​

Promise<Role | null>


findRoleOrFail() ​

ts
findRoleOrFail<G>(name, options?): Promise<Role>;

Defined in: packages/core/src/rbac.ts:473

Type Parameters ​

Type ParameterDefault type
G extends stringDefaultGuardName<T>

Parameters ​

ParameterType
nameRoleName<T, G>
options?ScopeOptions<CheckGuard<T, G>>

Returns ​

Promise<Role>


for() ​

ts
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 ParameterDefault type
G extends stringDefaultGuardName<T>

Parameters ​

ParameterType
subjectSubject
options?ScopeOptions<CheckGuard<T, G>> & ActorOptions

Returns ​

SubjectRbac<T, ScopedGuardName<T, G>>


forgetCachedPermissions() ​

ts
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() ​

ts
getPermissions(options?): Promise<Permission[]>;

Defined in: packages/core/src/rbac.ts:427

Parameters ​

ParameterType
options?GuardOptions

Returns ​

Promise<Permission[]>


getRoles() ​

ts
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 ​

ParameterType
options?ScopeOptions

Returns ​

Promise<Role[]>


off() ​

ts
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 ​

ParameterType
eventK
listenerRbacEventListener<K>

Returns ​

void


on() ​

ts
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 ​

ParameterType
eventK
listenerRbacEventListener<K>

Returns ​

() => void


pruneExpired() ​

ts
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() ​

ts
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 ParameterDefault type
G extends stringDefaultGuardName<T>

Parameters ​

ParameterType
roleRoleInput<RoleName<T, G>>
options?ScopeOptions<CheckGuard<T, G>> & ActorOptions

Returns ​

RoleRbac<T, ScopedGuardName<T, G>>


rolesWithPermission() ​

ts
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 ParameterDefault type
G extends stringDefaultGuardName<T>

Parameters ​

ParameterType
permissionPermissionInput<PermissionName<T, G>>
options?ScopeOptions<CheckGuard<T, G>>

Returns ​

Promise<Role[]>


subjectsWithoutPermission() ​

ts
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 ParameterDefault type
G extends stringDefaultGuardName<T>

Parameters ​

ParameterType
subjectTypestring
permissionsMany<PermissionInput<PermissionName<T, G>>>
optionsSubjectsWithoutPermissionOptions<CheckGuard<T, G>>

Returns ​

Promise<Id[]>


subjectsWithoutRole() ​

ts
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.

ts
const ids = users.map((u) => u.id)
await rbac.subjectsWithoutRole('user', 'admin', { among: ids }) // the non-admins among them

Type Parameters ​

Type ParameterDefault type
G extends stringDefaultGuardName<T>

Parameters ​

ParameterType
subjectTypestring
rolesMany<RoleInput<RoleName<T, G>>>
optionsSubjectsWithoutRoleOptions<CheckGuard<T, G>>

Returns ​

Promise<Id[]>


subjectsWithPermission() ​

ts
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 ParameterDefault type
G extends stringDefaultGuardName<T>

Parameters ​

ParameterType
subjectTypestring
permissionsMany<PermissionInput<PermissionName<T, G>>>
options?SubjectsWithPermissionOptions<CheckGuard<T, G>>

Returns ​

Promise<Id[]>


subjectsWithRole() ​

ts
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 ParameterDefault type
G extends stringDefaultGuardName<T>

Parameters ​

ParameterType
subjectTypestring
rolesMany<RoleInput<RoleName<T, G>>>
options?ScopeOptions<CheckGuard<T, G>>

Returns ​

Promise<Id[]>


sync() ​

ts
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.

ts
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: true deletes roles & permissions of the synced scopes that aren't in the definition.
  • dryRun: true returns the plan without writing anything.

Not atomic: adapters have no transactions, so a failure midway leaves the earlier changes.

Type Parameters ​

Type ParameterDefault type
G extends stringDefaultGuardName<T>

Parameters ​

ParameterType
definitionSyncDefinitions<T, G>
options?SyncOptions<CheckGuard<T, G>>

Returns ​

Promise<SyncResult>

Released under the MIT License. Inspired by spatie/laravel-permission.