refactor: renames PureAbility to Ability (#1205)

BREAKING CHANGE: renames PureAbility to Ability and dops default options. In order, to get the previous behavior of `Ability` class, clients are expected to use `createMongoAbility` and `MongoAbility` type

Author: stalniy

packages/casl-ability/spec/ability.spec.ts

@@ -1,4 +1,4 @@
-import { defineAbility, Ability, createAliasResolver, createMongoAbility, RuleOf, PureAbility } from '../src'
+import { defineAbility, Ability, createAliasResolver, createMongoAbility, RuleOf } from '../src'
 import { Post, ruleToObject } from './fixtures'
 
 describe('Ability', () => {
@@ -62,7 +62,7 @@ describe('Ability', () => {
   })
 
   it('allows to check abilities only by action', () => {
-    const ability = new PureAbility([{ action: 'read' }])
+    const ability = new Ability([{ action: 'read' }])
 
     expect(ability.can('read')).toBe(true)
   })
@@ -508,11 +508,16 @@ describe('Ability', () => {
 
     it('throws exception if 3rd argument is passed but "fieldMatchher" options was not provided', () => {
       const rules = [{ action: 'read', subject: 'Post', fields: ['title'] }]
-      expect(() => new PureAbility(rules)).toThrow(/"fieldMatcher" option/)
+      expect(() => new Ability(rules)).toThrow(/"fieldMatcher" option/)
+    })
+
+    it('throws exception if rule has conditions but "conditionsMatcher" options was not provided', () => {
+      const rules = [{ action: 'read', subject: 'Post', conditions: { authorId: 1 } }]
+      expect(() => new Ability(rules)).toThrow(/"conditionsMatcher" option/)
     })
 
     it('throws if there is a rule with "fields" property to be an empty array', () => {
-      expect(() => defineAbility(can => can('read', 'Post', []))).toThrow(/`rawRule.fields` cannot be an empty array/)
+      expect(() => defineAbility(can => can('read', 'Post', []))).toThrow(/`rawRule.fields` array cannot be empty/)
     })
 
     describe('when field patterns defined', () => {

packages/casl-ability/spec/builder.spec.js

@@ -1,4 +1,4 @@
-import { AbilityBuilder, defineAbility, PureAbility, createMongoAbility } from '../src'
+import { AbilityBuilder, defineAbility, Ability, createMongoAbility } from '../src'
 import { Post, ruleToObject } from './spec_helper'
 
 describe('AbilityBuilder', () => {
@@ -132,7 +132,7 @@ describe('AbilityBuilder', () => {
         cannot('read', 'Book', { private: true })
       })
 
-      expect(ability).to.be.instanceof(PureAbility)
+      expect(ability).to.be.instanceof(Ability)
       expect(ability.rules.map(ruleToObject)).to.deep.equal([
         { action: 'read', subject: 'Book' },
         { inverted: true, action: 'read', subject: 'Book', conditions: { private: true } }
@@ -145,7 +145,7 @@ describe('AbilityBuilder', () => {
         cannot('read', 'Book', { private: true })
       })
 
-      expect(ability).to.be.instanceof(PureAbility)
+      expect(ability).to.be.instanceof(Ability)
       expect(ability.rules.map(ruleToObject)).to.deep.equal([
         { action: 'read', subject: 'Book' },
         { inverted: true, action: 'read', subject: 'Book', conditions: { private: true } }

packages/casl-ability/spec/error.spec.ts

@@ -1,4 +1,4 @@
-import { ForbiddenError, getDefaultErrorMessage, PureAbility, SubjectType } from '../src'
+import { ForbiddenError, getDefaultErrorMessage, Ability, SubjectType } from '../src'
 
 describe('`ForbiddenError` class', () => {
   describe('`throwUnlessCan` method', () => {
@@ -13,13 +13,13 @@ describe('`ForbiddenError` class', () => {
     })
 
     it('raises error with context information', () => {
-      let thrownError: ForbiddenError<PureAbility> | undefined
+      let thrownError: ForbiddenError<Ability> | undefined
       const { error } = setup()
 
       try {
         error.throwUnlessCan('archive', 'Post')
       } catch (abilityError) {
-        thrownError = abilityError as ForbiddenError<PureAbility>
+        thrownError = abilityError as ForbiddenError<Ability>
       }
 
       expect(thrownError!.action).toBe('archive')
@@ -51,7 +51,7 @@ describe('`ForbiddenError` class', () => {
     it('correctly extracts subject type name from class subject types', () => {
       class Post {}
 
-      const ability = new PureAbility([
+      const ability = new Ability([
         { action: 'read', subject: Post }
       ], {
         detectSubjectType: o => o.constructor as SubjectType
@@ -61,8 +61,8 @@ describe('`ForbiddenError` class', () => {
         ForbiddenError.from(ability).throwUnlessCan('update', Post)
         expect('this code').toBe('never reached')
       } catch (error) {
-        expect((error as ForbiddenError<PureAbility>).subjectType).toBe('Post')
-        expect((error as ForbiddenError<PureAbility>).message).toBe('Cannot execute "update" on "Post"')
+        expect((error as ForbiddenError<Ability>).subjectType).toBe('Post')
+        expect((error as ForbiddenError<Ability>).message).toBe('Cannot execute "update" on "Post"')
       }
     })
   })
@@ -81,7 +81,7 @@ describe('`ForbiddenError` class', () => {
   })
 
   function setup() {
-    const ability = new PureAbility([
+    const ability = new Ability([
       { action: 'read', subject: 'Post' }
     ])
     const error = ForbiddenError.from(ability)

packages/casl-ability/spec/permitted_fields.spec.js

@@ -1,4 +1,4 @@
-import { defineAbility, PureAbility } from '../src'
+import { defineAbility, Ability } from '../src'
 import { permittedFieldsOf } from '../src/extra'
 import { Post } from './spec_helper'
 
@@ -8,7 +8,7 @@ describe('permittedFieldsOf', () => {
   }
 
   it('returns an empty array for `Ability` with empty rules', () => {
-    const ability = new PureAbility()
+    const ability = new Ability()
     expect(permittedFieldsOf(ability, 'read', 'Post', defaultOptions)).to.be.empty
   })
 

packages/casl-ability/spec/types/Ability.spec.ts

@@ -5,7 +5,7 @@ import {
   SubjectType,
   createAliasResolver,
   MongoAbility,
-  PureAbility,
+  Ability,
   createMongoAbility,
   MongoQuery
 } from '../../src'
@@ -32,7 +32,7 @@ describe('Ability types', () => {
   })
 
   it('can be casted to `AbilityClass`', () => {
-    const AppAbility = PureAbility as AbilityClass<AppAbility>
+    const AppAbility = Ability as AbilityClass<AppAbility>
     expectTypeOf(AppAbility).toEqualTypeOf<AbilityClass<AppAbility>>()
   })
 

packages/casl-ability/spec/types/AbilityBuilder.spec.ts

@@ -1,12 +1,12 @@
 import { expectTypeOf } from 'expect-type'
 import {
   AbilityBuilder,
-  AbilityClass, AbilityTuple, createMongoAbility, MongoAbility, PureAbility
+  AbilityClass, AbilityTuple, createMongoAbility, MongoAbility, Ability
 } from '../../src'
 
 describe('AbilityBuilder types', () => {
-  it('infers types from `PureAbility` default generics', () => {
-    const builder = new AbilityBuilder<PureAbility<AbilityTuple>>(PureAbility)
+  it('infers types from `Ability` default generics', () => {
+    const builder = new AbilityBuilder<Ability<AbilityTuple>>(Ability)
 
     builder.can('read', 'Subject')
     builder.can('read', class {})
@@ -77,7 +77,7 @@ describe('AbilityBuilder types', () => {
   })
 
   it('infers single action argument type from ClaimAbility', () => {
-    const ClaimAbility = PureAbility as AbilityClass<PureAbility<string>>
+    const ClaimAbility = Ability as AbilityClass<Ability<string>>
     // eslint-disable-next-line
     const builder = new AbilityBuilder(ClaimAbility)
     type Can = typeof builder.can

packages/casl-ability/src/Ability.ts

@@ -1,47 +1,56 @@
-import { PureAbility, AbilityOptions, AbilityOptionsOf } from './PureAbility';
-import { RawRuleFrom } from './RawRule';
-import { AbilityTuple } from './types';
-import { MongoQuery, mongoQueryMatcher } from './matchers/conditions';
-import { fieldPatternMatcher } from './matchers/field';
-import { Public, RawRuleOf } from './RuleIndex';
+import { RuleIndex, RuleIndexOptions, RuleIndexOptionsOf, Public, RawRuleOf } from './RuleIndex';
+import { Abilities, AbilityTuple, CanParameters, Subject } from './types';
+import { Rule } from './Rule';
+
+export interface AbilityOptions<A extends Abilities, Conditions>
+  extends RuleIndexOptions<A, Conditions> {}
+export interface AnyAbility extends Public<Ability<any, any>> {}
+export interface AbilityOptionsOf<T extends AnyAbility> extends RuleIndexOptionsOf<T> {}
+
+export type AbilityClass<T extends AnyAbility> = new (
+  rules?: RawRuleOf<T>[],
+  options?: AbilityOptionsOf<T>
+) => T;
+
+export type CreateAbility<T extends AnyAbility> = (
+  rules?: RawRuleOf<T>[],
+  options?: AbilityOptionsOf<T>
+) => T;
 
-/**
- * @deprecated use createMongoAbility function instead and MongoAbility<Abilities> interface.
- * In the next major version PureAbility will be renamed to Ability and this class will be removed
- */
 export class Ability<
-  A extends AbilityTuple = AbilityTuple,
-  C extends MongoQuery = MongoQuery
-> extends PureAbility<A, C> {
-  constructor(rules: RawRuleFrom<A, C>[] = [], options: AbilityOptions<A, C> = {}) {
-    super(rules, {
-      conditionsMatcher: mongoQueryMatcher,
-      fieldMatcher: fieldPatternMatcher,
-      ...options,
-    });
+  A extends Abilities = AbilityTuple,
+  Conditions = unknown
+> extends RuleIndex<A, Conditions> {
+  can(...args: CanParameters<A>): boolean;
+  can(action: string, subject?: Subject, field?: string): boolean {
+    const rule = (this as PrimitiveAbility).relevantRuleFor(action, subject, field);
+    return !!rule && !rule.inverted;
   }
-}
 
-export interface AnyMongoAbility extends Public<PureAbility<any, MongoQuery>> {}
-export interface MongoAbility<
-  A extends AbilityTuple = AbilityTuple,
-  C extends MongoQuery = MongoQuery
-> extends PureAbility<A, C> {}
+  relevantRuleFor(...args: CanParameters<A>): Rule<A, Conditions> | null;
+  relevantRuleFor(action: string, subject?: Subject, field?: string): Rule<A, Conditions> | null {
+    const subjectType = this.detectSubjectType(subject);
+    const rules = (this as any).rulesFor(action, subjectType, field);
+
+    for (let i = 0, length = rules.length; i < length; i++) {
+      if (rules[i].matchesConditions(subject)) {
+        return rules[i];
+      }
+    }
+
+    return null;
+  }
+
+  cannot(...args: CanParameters<A>): boolean;
+  cannot(action: string, subject?: Subject, field?: string): boolean {
+    return !(this as PrimitiveAbility).can(action, subject, field);
+  }
+}
 
 /**
- * Creates Ability with MongoDB conditions matcher
+ * helper interface that helps to emit js methods that have static parameters
  */
-export function createMongoAbility<
-  T extends AnyMongoAbility = MongoAbility
->(rules?: RawRuleOf<T>[], options?: AbilityOptionsOf<T>): T;
-export function createMongoAbility<
-  A extends AbilityTuple = AbilityTuple,
-  C extends MongoQuery = MongoQuery
->(rules?: RawRuleFrom<A, C>[], options?: AbilityOptions<A, C>): MongoAbility<A, C>;
-export function createMongoAbility(rules: any[] = [], options = {}): AnyMongoAbility {
-  return new PureAbility(rules, {
-    conditionsMatcher: mongoQueryMatcher,
-    fieldMatcher: fieldPatternMatcher,
-    ...options,
-  });
+interface PrimitiveAbility<A extends Abilities = AbilityTuple, Conditions = unknown> {
+  can(action: string, subject?: Subject, field?: string): boolean;
+  relevantRuleFor(action: string, subject?: Subject, field?: string): Rule<A, Conditions> | null
 }

packages/casl-ability/src/AbilityBuilder.ts

@@ -1,8 +1,8 @@
-import { AnyMongoAbility, createMongoAbility, MongoAbility } from './Ability';
-import { ProduceGeneric } from './hkt';
-import { AbilityOptionsOf, AnyAbility } from './PureAbility';
-import { Generics, RawRuleOf } from './RuleIndex';
-import {
+import { type AnyMongoAbility, createMongoAbility, type MongoAbility } from './createMongoAbility';
+import type { ProduceGeneric } from './hkt';
+import type { AbilityOptionsOf, AnyAbility } from './Ability';
+import type { Generics, RawRuleOf } from './RuleIndex';
+import type {
   AbilityTuple, AnyClass, AnyObject, ExtractSubjectType as E, Normalize, SubjectType,
   TaggedInterface
 } from './types';

packages/casl-ability/src/ForbiddenError.ts

@@ -1,6 +1,6 @@
-import { AnyAbility } from './PureAbility';
-import { Normalize, Subject } from './types';
-import { Generics } from './RuleIndex';
+import type { AnyAbility } from './Ability';
+import type { Normalize, Subject } from './types';
+import type { Generics } from './RuleIndex';
 import { getSubjectTypeName } from './utils';
 
 export type GetErrorMessage = (error: ForbiddenError<AnyAbility>) => string;