API Reference

This section provides a detailed reference of the Asgardian API, including all available functions, their parameters, and usage examples.

Core Functions

`createAbility`

Creates a new ability instance for defining and checking permissions.

Type Definition


function createAbility<
  ExtendedActions extends string = 'manage' | 'create' | 'read' | 'update' | 'delete',
  ExtendedResources extends string = 'all'
>(): CreateAbility<ExtendedActions, ExtendedResources>

Generic Parameters

ExtendedActions: Custom action types to extend the default actions
ExtendedResources: Custom resource types to extend the default resources

Returns

Returns an object with methods for defining and checking permissions.

Examples


// Basic usage
const ability = createAbility()
 
// With custom actions
const ability = createAbility<'publish' | 'archive'>()
 
// With custom resources
const ability = createAbility<never, 'Post' | 'Comment'>()
 
// With both custom actions and resources
const ability = createAbility<'publish' | 'archive', 'Post' | 'Comment'>()

Permission Methods

`can`

Defines rules allowing specific actions on resources.

Type Definition


can(
  action: Action<ExtendedActions> | Action<ExtendedActions>[],
  resource: Resource<ExtendedResources>,
  conditions?: Condition
): CreateAbility<ExtendedActions, ExtendedResources> & {
  reason: (message: string) => CreateAbility<ExtendedActions, ExtendedResources>
}

Parameters

action: Single action or array of actions to allow
resource: The resource the actions apply to
conditions: Optional conditions that must be met for the permission to apply

Examples


// Single action
ability.can('read', 'Post')
 
// Multiple actions
ability.can(['create', 'update'], 'Post')
 
// With reason
ability.can('delete', 'Post').reason('You can delete this post')
 
// With conditions
ability.can('read', 'Post', { published: true }).reason('Can only read published posts')
 
// Chaining
ability
  .can('read', 'Post')
  .can('create', 'Comment')
  .can('update', 'Comment', { authorId: 123 })
  .reason('Can only update own comments')

`cannot`

Defines rules explicitly denying specific actions on resources.

Type Definition


cannot(
  action: Action<ExtendedActions>,
  resource: Resource<ExtendedResources>,
  conditions?: Condition
): CreateAbility<ExtendedActions, ExtendedResources> & {
  reason: (message: string) => CreateAbility<ExtendedActions, ExtendedResources>
}

Parameters

action: Action to deny
resource: The resource the action applies to
conditions: Optional conditions for when the denial applies

Examples


// Single action
ability.cannot('delete', 'Post')
 
// Multiple actions
ability.cannot(['create', 'delete'], 'Post')
 
// With reason
ability.cannot('delete', 'Post').reason('Deletion not allowed for security')
 
// With conditions
ability.cannot('update', 'Post', { archived: true })
 
// Chaining
ability
  .cannot('read', 'Post')
  .cannot('create', 'Post')
  .cannot('update', 'Post', { authorId: 456 })
  .reason('Can only delete own posts')

`isAllowed`

Checks if an action is allowed on a resource.

Type Definition


isAllowed(
  action: Action<ExtendedActions> | Action<ExtendedActions>[],
  resource: Resource<ExtendedResources>,
  conditions?: Condition
): boolean

Parameters

action: Single action or array of actions to check
resource: The resource to check against
conditions: Optional conditions to evaluate

Examples


// Basic check
ability.isAllowed('read', 'Post') // true/false
 
// Check multiple actions
ability.isAllowed(['read', 'update'], 'Post') // true/false
 
// With conditions
ability.isAllowed('read', 'Post', { published: true }) // true/false

`notAllowed`

Inverse of isAllowed. Checks if an action is not allowed on a resource.

Type Definition


notAllowed(
  action: Action<ExtendedActions> | Action<ExtendedActions>[],
  resource: Resource<ExtendedResources>,
  conditions?: Condition
): boolean

Parameters

action: Single action or array of actions to check
resource: The resource to check against
conditions: Optional conditions to evaluate

Examples


// Basic check
ability.notAllowed('delete', 'Post') // true/false
 
// With conditions
ability.notAllowed('update', 'Post', { archived: true }) // true/false

`getReason`

Retrieves the reason why an action was denied on a resource.

Type Definition


getReason(
  action: Action<ExtendedActions> | Action<ExtendedActions>[],
  resource: Resource<ExtendedResources>,
  conditions?: Condition
): string | undefined

Parameters

action: Single action or array of actions to check
resource: The resource to check against
conditions: Optional conditions to evaluate

Examples


// Set up rules with reasons
ability
  .cannot('delete', 'Post').reason('Deletion not allowed')
  .cannot('update', 'Post', { archived: true }).reason('Cannot update archived posts')
 
// Get reasons
const deleteReason = ability.getReason('delete', 'Post')
// Returns: "Deletion not allowed"
 
const updateReason = ability.getReason('update', 'Post', { archived: true })
// Returns: "Cannot update archived posts"
 
const unknownReason = ability.getReason('create', 'Post')
// Returns: undefined

`throwIfNotAllowed`

Throws a ForbiddenError if an action is not allowed on a resource.

Type Definition


throwIfNotAllowed(
  action: Action<ExtendedActions> | Action<ExtendedActions>[],
  resource: Resource<ExtendedResources>,
  conditions?: Condition
): void

Parameters

action: Single action or array of actions to check
resource: The resource to check against
conditions: Optional conditions to evaluate

Examples


// Set up rules
ability.cannot('delete', 'Post').reason('Deletion forbidden')
 
// This will throw
try {
  ability.throwIfNotAllowed('delete', 'Post')
} catch (error) {
  if (error instanceof ForbiddenError) {
    console.error(error.message) // "Deletion forbidden"
  }
}
 
// This won't throw if allowed
ability.can('read', 'Post')
ability.throwIfNotAllowed('read', 'Post') // No error

Special Values

Default Actions

manage: Grants all permissions
create: Allows creation
read: Allows reading
update: Allows updates
delete: Allows deletion

Special Resources

all: Matches any resource

Rule Resolution

Rules are evaluated in order of definition
More specific rules take precedence over general rules
Multiple matching rules are combined with OR logic
cannot rules take precedence over can rules
Conditions must be fully satisfied for a rule to match
The most recent matching rule’s reason is returned by getReason()

Type Definitions


type Action<T extends string = never> =
  | 'manage'
  | 'create'
  | 'read'
  | 'update'
  | 'delete'
  | T
 
type Resource<T extends string = never> = 'all' | T
 
type Condition = Record<PropertyKey, unknown>
 
type Rule<A extends string, R extends string> = {
  action: Action<A> | Action<A>[]
  resource: Resource<R>
  inverted?: boolean
  conditions?: Condition
  reason?: string
}

💡

Tip

See the Operators guide for advanced condition handling using built-in operators.