Crystal
Repositories Projects Packages

@crysteam/ability (1.0.1)

Published 2025-06-05 13:12:39 +00:00 by Kiefe

Installation

@crysteam:registry=
npm install @crysteam/ability@1.0.1
"@crysteam/ability": "1.0.1"

About this package

Ability Management Library

A lightweight and flexible permissions/ability management library for TypeScript/JavaScript applications. This library allows you to define and check user permissions with support for actions, subjects, and contextual conditions.

Features

  • Define permissions using simple rules
  • Check abilities with can/cannot methods
  • Enforce permissions with mustCan/mustCannot that throw errors
  • Support for contextual permissions with conditions
  • Works with string subjects, classes, and instances
  • Rule serialization/deserialization
  • Fluent builder API for defining rules

Installation

npm install @crysteam/ability
# or
yarn add @crysteam/ability

Basic Usage

Defining Abilities

import { AbilityBuilder } from '@crysteam/ability';

const builder = new AbilityBuilder();

// Grant permissions
builder
  .can('read', 'Article')
  .can('delete', 'Article', { authorId: 123 })
  .cannot('delete', 'Article', { isPublished: true });

const ability = builder.build();

Checking Permissions

// Simple check
ability.can('read', 'Article'); // true
ability.cannot('delete', 'Article'); // false (depends on context)

// With context
ability.can('delete', 'Article', { authorId: 123 }); // true
ability.can('delete', 'Article', { authorId: 456 }); // false

// Enforcing permissions
try {
  ability.mustCan('delete', 'Article', { authorId: 123 });
  // Proceed with operation
} catch (error) {
  // Handle permission error
}

Advanced Usage

Working with Class Subjects

class Article {
  constructor(public authorId: number, public isPublished: boolean) {}
}

const builder = new AbilityBuilder();
builder.can('read', Article);
builder.can('update', Article, { authorId: 123 });

const ability = builder.build();

const article = new Article(123, false);
ability.can('update', article); // true

Serializing Rules

const builder = new AbilityBuilder();
builder.can('read', 'Article');
const ability = builder.build();

// Export rules
const rulesJson = ability.exportRules();

// Import rules
const newAbility = Ability.importRules(rulesJson);

API Reference

Ability Class

  • can(action: string, subject: SubjectType, context?: Record<string, any>): boolean Checks if the action is allowed on the subject

  • cannot(action: string, subject: SubjectType, context?: Record<string, any>): boolean Checks if the action is not allowed on the subject

  • mustCan(action: string, subject: SubjectType, context?: Record<string, any>): void Throws an error if the action is not allowed

  • mustCannot(action: string, subject: SubjectType, context?: Record<string, any>): void Throws an error if the action is allowed

  • exportRules(): string Serializes rules to JSON

  • static importRules(json: string): Ability Creates Ability instance from serialized rules

AbilityBuilder Class

  • can(actions: string | string[], subjects: SubjectType | SubjectType[], conditions?: Record<string, any>) Adds an allow rule

  • cannot(actions: string | string[], subjects: SubjectType | SubjectType[], conditions?: Record<string, any>) Adds a deny rule

  • build(): Ability Creates Ability instance with the defined rules

Types

  • SubjectType: string | SubjectClass | object Represents a subject that permissions can be granted for

  • Rule:

    {
  actions: string[];
  subjects: SubjectType[];
  conditions?: Record<string, any>;
  inverted: boolean;
}

License

MIT

Dependencies

Dependencies

ID Version
msgpackr ^1.11.4

Development Dependencies

ID Version
@types/node ^22.15.29
ts-node ^10.9.2
typescript ^5.8.3
Details
npm
2025-06-05 13:12:39 +00:00
44
Crysteam
ISC
latest
4.1 KiB
Assets (1)
ability-1.0.1.tgz 4.1 KiB
Versions (3) View all
1.0.1 2025-06-05
1.0.1-0 2025-06-05
1.0.0 2025-06-05