CASL 4.0. — What’s inside?
Tags: javascript, webdev, acl, casl
Published: 2020-04-18 14:08:42

> _First time you’ve heard about_ [_CASL_](https://github.com/stalniy/casl)_? You may want to read “_[_What is CASL?_](https://stalniy.github.io/casl/v4/en/guide/intro)_”._

I’m glad to announce that **CASL 4.0 was released few days ago** and brought several powerful possibilities on our desk:

# Type Safety

`@casl/*` packages were rewritten to [TypeScript](https://www.typescriptlang.org/). This makes your apps safer and developer experience more enjoyable. Let’s see how:

> I know I know… I was one of those skeptics who have never liked TypeScript until recent time. It’s really powerful now, especially inference logic!

Starting from 4.0 `Ability` class accepts 2 generic parameters:

*   application abilities (actions defined for subjects)
*   conditions shape

This allows you restrict what actions can be applied on specified subjects. For example, in a blog app which has `Article`, `Comment`, and `User` entities, logged in user can:

*   `read`, `create`, `update`, `delete` `Article`s
*   `read`, `create`, `update` `Comment`s
*   `read` other `User`s

And we can express this as

```ts
import { Ability } from '@casl/ability';

type AppAbilities = [
  'read' | 'update' | 'delete' | 'create',
  'Article' | 'Comment' | 'User'
];

export type AppAbility = Ability<AppAbilities>;
```

Or even stricter

```ts
import { Ability } from '@casl/ability';

type AppAbilities = 
  ['create' | 'read' | 'update' | 'delete', 'Article'] |
  ['create' | 'read' | 'update', 'Comment'] |
  ['read', 'User']
;

export type AppAbility = Ability<AppAbilities>;
```

This allows TypeScript to check that you don’t make a typo in action or subject name at compile time! Moreover, IDE (e.g., VSCode) will suggest possible options to choose from:

![CASL Typescript VSCode hints](https://dev-to-uploads.s3.amazonaws.com/i/q2o2t5889a45q843vlmj.png)

This types hints works even in your favorite frontend libraries, thanks to complementary packages! So, you will get hints for React’s `Can` component and Vue’s `$can` function in templates. The nice thing about VSCode is that it uses typescript definition files even for JavaScript files, so you will get better IDE support for JavaScript apps as well. Isn’t that cool?

To get more details about new [TypeScript support in CASL](https://stalniy.github.io/casl/v4/en/advanced/typescript), read about it in the [docs](https://stalniy.github.io/casl/v4/en).

# Smaller library size

The library is smaller, [~4.5KB mingzipped](https://bundlephobia.com/result?p=@casl/ability) (together with sift.js!) and has better support for tree-shaking. This was achieved thanks to [terser.js minifier](https://github.com/terser/terser) and several breaking changes that you can find in the [CHANGELOG](https://github.com/stalniy/casl/blob/master/packages/casl-ability/CHANGELOG.md#breaking-changes).

Starting from 4.0, there are classes that allows to create `Ability` instance:

*   `PureAbility` base class that implements core logic
*   `Ability` that extends `PureAbility` and configures it to use `mongoQueryMatcher` and `fieldPatternMatcher`

This was done in order to be able to shake out `sift.js` dependency in case you don’t use conditions at all or when you implement a custom matcher. As a result `AbilityBuilder` now accepts Ability class as a first argument. By default, the argument is `PureAbility`, so if you used `AbilityBuilder.extract`, you will need to change it from:

```js
const { can, cannot, rules } = AbilityBuilder.extract();  
// rule definitions  
const ability = new Ability(rules);
```

to

```js
const { can, cannot, rules } = new AbilityBuilder(Ability);  
// rule definitions  
const ability = new Ability(rules);
```

# Customization

In 4.0, you can customize `Ability` instance behavior. Do you want to extend MongoDB query with custom operator, use [json-schema](https://json-schema.org) or arrow functions as conditions? Not a problem anymore, just implement a custom `conditionsMatcher`.

To get more in depth details, read [Customize Ability](https://stalniy.github.io/casl/v4/en/advanced/customize-ability) in the docs.

# Better subject type detection support

If you use **P**lain **O**ld **J**avaScript **O**bjects as models, you have a simpler option to specify subject type now. No need to provide custom `detectSubjectType` function (`subjectName` option was renamed to `detectSubjectType`), just use `subject` helper:

```js
import { defineAbility, subject as an } from '@casl/ability';

const object = {
  title: 'My article', 
  description: '...',
};

ability.can('read', an('Article', object));

// or

const article = an.bind(null, 'Article');
ability.can('read', article(object));
```

To get better understanding of how CASL detect subject type, check [Subject Type Detection](https://stalniy.github.io/casl/v4/en/guide/subject-type-detection) page.

# Much better documentation

Documentation was completely rewritten. First of all, now it’s a Single Page Application written on top of awesome [lit-html](https://lit-html.polymer-project.org/) and [lit-element](https://lit-element.polymer-project.org) libraries (the final mingzipped size of the app is 47KB for modern browsers! It even somehow works in IE11). It’s available for offline usage, all documentation texts less than 1MB, so don’t worry it won’t take much of your disk :)

Now it’s organized and easily extendable. It also tries to be beginner friendly and have cookbook and examples sections! Every complementary package now have a separate page with documentation for it, so you don’t need to look for README files through repository.

# The Future

CASL gets more and more attraction from developers. This requires additional time to write new features, complementary packages, documentation and answering questions in [gitter chat](https://gitter.im/stalniy-casl/casl). Besides doing my best to do all of this, I need to use my unique talents to fill important roles for the organization, otherwise my wife would expel me a long time ago ;)

I like CASL and like to contribute to Open Source. That’s why I’m seeking for a way to work more on Open Source projects. Thankfully, there are platforms that help to support people like me. And I’m thrilled to announce that[**CASL is now on Open Collective**](https://opencollective.com/casljs)**!**

> If you want to get more details about what Open Collective is, and you can contribute, please read [Sustaining CASL development](https://medium.com/@sergiy.stotskiy/sustaining-casl-js-development-c25628e7648b)

If you have the same vision of the world, and you like CASL, your contributions are very welcome! You are not restricted to financial contributions, as usually you can just share CASL with your colleague from another project, help to answer questions in [gitter chat](https://gitter.im/stalniy-casl/casl) and triage issues, share your examples of CASL integrations, and contribute code and documentation! Finally, you can become a core contributor and support CASL on regular basis.

# How do I migrate?

CASL has introduced several breaking changes in all `@casl/*` packages, so **please spend time** **reading CHANGELOG.md** of the packages you use. You can find all changes (including breaking ones) in that file of each package in [casl repository](https://github.com/stalniy/casl/tree/master/packages).

If you find any issues or something is unclear, please fill in [an issue on github](https://github.com/stalniy/casl/issues/new).

# Where can I start as a beginner?

As of now, CASL has quite good documentation, so start from the [Guide](https://stalniy.github.io/casl/v4/en/guide/intro). Then move to documentation for the frontend or backend package of your choice and read it. Later you can check existing articles that explains how to integrate CASL in popular frameworks:

*   [Managing User Permissions in Angular application](https://medium.com/dailyjs/managing-user-permissions-in-angular-application-504c83752f83)
*   [Vue ACL with CASL](https://medium.com/dailyjs/vue-acl-with-casl-781a374b987a)
*   [Managing user permissions in React app](https://medium.com/dailyjs/managing-user-permissions-in-your-react-app-a93a94ff9b40)
*   [Permissions in Aurelia](https://medium.com/@sergiy.stotskiy/casl-based-authorization-in-aurelia-app-3e44c0fe1703) app
*   [Authorization in Expressjs app](https://medium.com/@sergiy.stotskiy/authorization-with-casl-in-express-app-d94eb2e2b73b)
*   [Easy API Authorization with CASL and Feathers](https://blog.feathersjs.com/authorization-with-casl-in-feathersjs-app-fd6e24eefbff)

Despite the fact, that they are a bit outdated, CASL was not changed much during its lifetime, so they are still relevant.

----

Thanks for trusting CASL! I hope CASL made permission management in your app as easy as pie