Wondering what’s next for npm?Check out our public roadmap! »

    allowjs
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.3 • Public • Published

    Welcome to Allow 👋

    Documentation Coverage Maintenance License: MIT

    A lightweight permissioning library.

    🏠 Homepage

    Prerequisites

    • node >=10.0.0

    Installation

    npm install allowjs

    or

    yarn add allowjs

    Usage

    Imports

    import Ability, { Permissions, AbilityInterface, NotAuthorizedError } from 'allowjs';

    Simple Allowance

    const userAbility = new Ability<User>(abilityInterface => {
      const { allow } = abilityInterface;
    
      allow(Permissions.READ, SomeClass, (user: User, entity: SomeClass) => user.id === entity.userId);
    });

    Disallowing

    const userAbility = new Ability<User>(abilityInterface => {
      const { allow, disallow } = abilityInterface;
    
      allow(Permissions.READ, SomeClass, (user: User, entity: SomeClass) => user.id === entity.userId);
    
      disallow(Permissions.READ, SomeClass, (user: User, entity: SomeClass) => user.roles.includes("role"));
    });

    Permissions are granted based on the following conditions:

    • At least one allow criteria is satisfied the by provided user.
    • No disallow criteria are satisfied by the provided user.

    Checking Permissions

    You can check permissions by using permits and ensures functions on the ability.

    • permits - Will return a boolean, whether or not the user has the specified permissions.
    • ensure - Will throw a NotAuthorizedError if the user does not have the required permissions. This can be useful in frameworks like Express where you can specify an error handler for this type of exception and return a 401 status code.
    if(userAbility.permits(user).toPerform(Permissions.READ).on(someEntity)) {
      // Take some action
    }
    // Throws a NotAuthorizedError if user cannot perform READ on someEntity
    userAbility.ensure(user).canPerform(Permissions.READ).on(someEntity)

    Class Level Permissions

    You can also specify that some particular user has permissions broadly across some class type.

    const userAbility = new Ability<User>(abilityInterface => {
      const { allow, disallow } = abilityInterface;
    
      allow(Permissions.READ, SomeClass, (user: User) => user.roles.includes('role'));
    });

    and check them by passing in the class type instead of an instance during the permissions check

    if(userAbility.permits(user).toPerform(Permissions.READ).on(SomeClass)) {
      // Take some action
    }

    or

    // Throws a NotAuthorizedError if user cannot perform READ on SomeClass
    userAbility.ensure(user).canPerform(Permissions.READ).on(SomeClass)

    Default Permissions

    Out of the box the following permissions are provided:

    Permissions.CREATE
    Permissions.READ
    Permissions.UPDATE
    Permissions.DELETE
    

    CRUD Expansion

    Permissions.CRUD is provided as a shorthand for specifying all of Permissions.CREATE, Permissions.READ, Permissions.UPDATE, and Permissions.DELETE.

    allow(Permissions.CRUD, SomeClass, (user: User, entity: SomeClass) => entity.userId === user.id);
    
    // is equivalent to
    allow(Permissions.CREATE, SomeClass, (user: User, entity: SomeClass) => entity.userId === user.id);
    allow(Permissions.READ, SomeClass, (user: User, entity: SomeClass) => entity.userId === user.id);
    allow(Permissions.UPDATE, SomeClass, (user: User, entity: SomeClass) => entity.userId === user.id);
    allow(Permissions.DELETE, SomeClass, (user: User, entity: SomeClass) => entity.userId === user.id);

    Custom Permissions

    You can provide permissions in the form of a string if the standard CRUD operations are insufficent.

    userAbility.allow('permission.custom', SomeClass, (user: User, entity: SomeClass) => entity.userId === user.id);
    
    userAbility.permits(user).toPerform('permission.custom').on(someEntity);

    Freeform Entity Types

    You can also specify a custom entity type that isn't restricted to a particular class as a name string. When checking the permissions against the object, you will need to specify the type you want to treat it as.

    userAbility.allow(Permission.READ, 'type.custom', (user: User, entity: { userId: string }) => entity.userId === user.id);
    
    userAbility.permits(user).toPerform(Permission.READ).on(someObject, 'type.custom');

    If you don't mind it, you could also just entity: any in plcae of the entity type definition.

    Development

    Install

    yarn install

    Tests

    yarn test
    yarn prettier:check
    yarn lint:check

    Author

    👤 Peter Myers

    🤝 Contributing

    Contributions, issues and feature requests are welcome!
    Feel free to check issues page.

    Show your support

    Give a ⭐️ if this project helped you!

    📝 License

    Copyright © 2020 Peter Myers.
    This project is MIT licensed.


    This README was generated with ❤️ by readme-md-generator

    Install

    npm i allowjs

    DownloadsWeekly Downloads

    1

    Version

    1.0.3

    License

    MIT

    Unpacked Size

    17.3 kB

    Total Files

    13

    Last publish

    Collaborators

    • avatar