Permission

Defined in: src/core/Permission.ts:42

Represents the resolved Permission for a query — the granted (or denied) access for the target role(s) and resource. Obtain one in two ways:

1. The chainable form via AccessControl#can(), which returns a Permission once an action method such as .createAny() is called:

   const permission = ac.can('user').createAny('video');
   console.log(permission.granted); // boolean

2. The one-shot form via AccessControl#check(), passing a fulfilled IQueryInfo object:

   const permission = ac.check({
     role: 'user',
     resource: 'video',
     action: 'create:any'
   });
   console.log(permission.granted); // boolean

Accessors

roles

Get Signature

get roles(): string[]

Defined in: src/core/Permission.ts:120

Specifies the roles for which the permission is queried for. Even if the permission is queried for a single role, this will still return an array.

If the returned array has multiple roles, this does not necessarily mean that the queried permission is granted or denied for each and all roles. Note that when a permission is queried for multiple roles, attributes are unioned (merged) for all given roles. This means “at least one of these roles” have the permission for this action and resource attribute.

Returns

string[]

---

resource

Get Signature

get resource(): string

Defined in: src/core/Permission.ts:128

Specifies the target resource for which the permission is queried for.

Returns

string

---

action

Get Signature

get action(): string

Defined in: src/core/Permission.ts:137

The action the permission was checked for — the bare verb, with any :possession suffix stripped (e.g. read for read:any, publish for a custom publish:own).

Returns

string

---

possession

Get Signature

get possession(): "own" | "any"

Defined in: src/core/Permission.ts:149

The possession that effectively granted access — 'own' or 'any'. Because any ⊇ own, a query for own that matched via an any grant resolves to 'any'. On denial, the requested possession is echoed back.

Throws

• If an applicable rule/gate has a custom/async { fn } condition; use Permission#grantedAsync first.

Returns

"own" | "any"

---

attributes

Get Signature

get attributes(): string[]

Defined in: src/core/Permission.ts:162

Gets an array of allowed attributes which are defined via Glob notation. If access is not granted, this will be an empty array.

Note that when a permission is queried for multiple roles, attributes are unioned (merged) for all given roles. This means “at least one of these roles” have the permission for this action and resource attribute.

Returns

string[]

---

granted

Get Signature

get granted(): boolean

Defined in: src/core/Permission.ts:174

Specifies whether the permission is granted. If true, this means at least one attribute of the target resource is allowed.

Throws

• If an applicable rule/gate has a custom/async { fn } condition; use Permission#grantedAsync instead.

Returns

boolean

---

grantedAsync

Get Signature

get grantedAsync(): Promise<boolean>

Defined in: src/core/Permission.ts:186

Async counterpart of Permission#granted. Resolves custom/async { fn } conditions (and works for fully-declarative checks too). After it resolves, the sync attributes/granted/filter accessors are usable.

Example

if (await ac.can('user', ctx).readAny('post').grantedAsync) { … }

Returns

Promise<boolean>

Methods

filter()

filter(data): UnknownObject | UnknownObject[]

Defined in: src/core/Permission.ts:197

Filters the given data object (or array of objects) by the permission attributes and returns this data with allowed attributes.

Parameters

data

UnknownObject | UnknownObject[]

Data object to be filtered. Either a single object or array of objects.

Returns

UnknownObject | UnknownObject[]

• The filtered data object.