casl

@casl/ability is CASL’s core package: an isomorphic authorization library that lets you describe what a user can and cannot do with a small, declarative set of rules instead of scattering permission checks through your codebase. Rules combine an action, a subject type, optional MongoDB-style conditions, and optional field restrictions, so you can express anything from simple role checks (“admins can manage everything”) to attribute-based rules (“authors can edit their own posts, but not delete one older than a day”).

Because rules are plain serializable objects, the same ability definition can be computed once on the server and reused to drive UI conditionals on the client, or rehydrated from JSON sent over the wire. A family of companion packages (@casl/react, @casl/vue, @casl/angular, @casl/mongoose, @casl/prisma) plugs the same rule set into frameworks and ORMs, so permission logic doesn’t have to be reimplemented at each layer of an application.

What You Get

• An AbilityBuilder DSL for declaring can/cannot rules with actions, subject types, MongoDB-style conditions, and per-field restrictions in one place.
• A RuleIndex/Ability runtime that indexes rules by subject type and action (with ‘any subject’/‘any action’ wildcards) for near-constant-time can() checks.
• ForbiddenError.from(ability).throwUnlessCan(...) for guard-clause-style authorization that throws a descriptive, typed error on a failed check.
• Action aliasing via createAliasResolver (e.g. modify: ['update', 'delete']) so checks can be expressed at whatever granularity your domain needs.
• Serializable rule objects, so an ability computed on the server can be sent as JSON and rehydrated into an identical client-side Ability instance.
• A defineAbility helper and createMongoAbility factory that wire up Mongo-style condition matching (via @ucast/mongo2js) without extra boilerplate.

Common Use Cases

• Defining role- and attribute-based permissions once and reusing them across API routes, background jobs, and UI components.
• Restricting which fields of a resource a given role can read or write (e.g. a moderator can edit hidden but not title).
• Turning permission rules directly into database query filters via @casl/mongoose or @casl/prisma instead of hand-writing per-row checks.
• Serializing a computed ability from the backend and rehydrating it in a React/Vue/Angular frontend to keep UI and API permissions in sync.

Under The Hood

Architecture The library is organized around a small set of composable classes: AbilityBuilder produces plain RawRule objects from a can/cannot DSL, RuleIndex (in RuleIndex.ts) turns those raw rules into an indexed tree keyed by subject type and action, wrapping each in a Rule instance that knows how to match conditions and fields, and Ability (in Ability.ts) extends RuleIndex with the public can/cannot/relevantRuleFor checks. Rules are indexed in reverse declaration order so later, more specific rules take priority, and possibleRulesFor lazily merges and freezes per-action rule lists (including ‘any action’/‘any subject’ wildcard rules) the first time they’re requested, caching the merged result for subsequent checks. This gives the library a clear layering: building rules, indexing them, and evaluating them are each a separate, independently testable concern, and swapping createMongoAbility’s condition matcher is the main extension point the rest of the codebase depends on.

Tech Stack Written in TypeScript and built with the project’s internal @casl/dx tooling, which wraps tsdown for bundling to dual ESM/CJS output with type declarations, and typescript-eslint plus a @stylistic/eslint-plugin config for linting. Condition matching against MongoDB-style query operators is delegated to the @ucast/mongo2js package, keeping the core free of a hand-rolled query matcher. The package ships as tree-shakeable ESM and CJS builds (dist/esm, dist/cjs) with generated .d.ts types, and is published from a pnpm-workspace monorepo alongside its framework/ORM integration packages (casl-react, casl-vue, casl-angular, casl-mongoose, casl-prisma).

Code Quality Tests are written with Jest (via ts-jest/the project’s dx jest wrapper) and cover the builder, ability checks, error handling, and rule-serialization helpers in dedicated spec files under spec/. Error handling favors throwing typed errors (ForbiddenError) over silent failure, and the public API is fully typed with generics that let consumers get typed action/subject tuples out of their own domain types. Linting is enforced through typescript-eslint and a CI workflow runs on GitHub Actions for every change, and lint-staged gates commits locally.

API Design The API favors a small, memorable vocabulary — can, cannot, build from AbilityBuilder, and can/cannot again on the resulting Ability — so defining and checking permissions read almost like natural language. Getting started requires minimal boilerplate: defineAbility(can => can('read', 'Post')) is enough for a working ability, while the same API scales up to per-field restrictions, condition objects, and action aliases without introducing new concepts. Companion integration packages reuse this same vocabulary in React, Vue, Angular, Mongoose, and Prisma contexts, which keeps the developer experience consistent across the whole ecosystem rather than requiring a different API to learn per integration.