feat: extends createPrisma types to accept AppAbility as generic type

updates docs

Author: stalniy

packages/casl-prisma/README.md

@@ -21,19 +21,18 @@ pnpm add @casl/prisma @casl/ability
 
 ## Usage
 
-This package is a bit different from all others because it provides a custom `PrismaAbility` class that is configured to check permissions using Prisma [WhereInput](https://www.prisma.io/docs/reference/api-reference/prisma-client-reference#where):
+This package is a bit different from all others because it provides a custom `createPrismaAbility` factory function that is configured to check permissions using Prisma [WhereInput](https://www.prisma.io/docs/reference/api-reference/prisma-client-reference#where):
 
 ```ts
 import { User, Post, Prisma } from '@prisma/client';
-import { AbilityClass, AbilityBuilder, subject } from '@casl/ability';
-import { PrismaAbility, Subjects } from '@casl/prisma';
+import { PureAbility, AbilityBuilder, subject } from '@casl/ability';
+import { createPrismaAbility, PrismaQuery, Subjects } from '@casl/prisma';
 
-type AppAbility = PrismaAbility<[string, Subjects<{
+type AppAbility = PureAbility<[string, Subjects<{
   User: User,
   Post: Post
-}>]>;
-const AppAbility = PrismaAbility as AbilityClass<AppAbility>;
-const { can, cannot, build } = new AbilityBuilder(AppAbility);
+}>], PrismaQuery>;
+const { can, cannot, build } = new AbilityBuilder<AppAbility>(createPrismaAbility);
 
 can('read', 'Post', { authorId: 1 });
 cannot('read', 'Post', { title: { startsWith: '[WIP]:' } });
@@ -74,7 +73,7 @@ const accessiblePosts = await prisma.post.findMany({
 });
 ```
 
-That function accepts `PrismaAbility` instance and `action` (defaults to `read`),  returns an object with keys that corresponds to Prisma model names and values being aggregated from permission rules `WhereInput` objects.
+That function accepts `Ability` instance and `action` (defaults to `read`),  returns an object with keys that corresponds to Prisma model names and values being aggregated from permission rules `WhereInput` objects.
 
 **Important**: in case user doesn't have ability to access any posts, `accessibleBy` throws `ForbiddenError`, so be ready to catch it!
 
@@ -128,6 +127,16 @@ type AppSubjects = Subjects<{
 }>; // 'User' | Model<User, 'User'>
 ```
 
+To support rule definition for `all`, we just need to explicitly do it:
+
+```ts
+type AppSubjects = 'all' | Subjects<{
+  User: User
+}>; // 'User' | Model<User, 'User'>
+
+type AppAbility = PureAbility<[string, AppSubjects], PrismaQuery>;
+```
+
 ## Custom PrismaClient output path
 
 Prisma allows [to generate client into a custom directory](https://www.prisma.io/docs/concepts/components/prisma-client/working-with-prismaclient/generating-prisma-client#using-a-custom-output-path) in this case `@prisma/client` doesn't re-export needed types anymore and `@casl/prisma` cannot automatically detect and infer types. In this case, we need to provide required types manually. Let's assume that we have the next configuration:

packages/casl-prisma/spec/AppAbility.ts

@@ -1,14 +1,8 @@
-import { AbilityOptionsOf, PureAbility, RawRuleOf } from '@casl/ability'
+import { PureAbility } from '@casl/ability'
 import { User, Post } from '@prisma/client'
-import { createPrismaAbility, PrismaQuery, Subjects } from '../src'
+import { PrismaQuery, Subjects } from '../src'
 
 export type AppAbility = PureAbility<[string, 'all' | Subjects<{
   User: User,
   Post: Post
 }>], PrismaQuery>
-
-type AppAbilityFactory = (
-  rules?: RawRuleOf<AppAbility>[],
-  options?: AbilityOptionsOf<AppAbility>
-) => AppAbility
-export const createAppAbility = createPrismaAbility as AppAbilityFactory

packages/casl-prisma/spec/PrismaAbility.spec.ts

@@ -1,11 +1,11 @@
 import { AbilityBuilder, PureAbility, subject } from '@casl/ability'
 import { User, Post, Prisma } from '@prisma/client'
-import { Model as M, PrismaQuery } from '../src'
-import { createAppAbility } from './AppAbility'
+import { createPrismaAbility, Model as M, PrismaQuery } from '../src'
+import { AppAbility } from './AppAbility'
 
 describe('PrismaAbility', () => {
   it('uses PrismaQuery to evaluate conditions', () => {
-    const { can, build } = new AbilityBuilder(createAppAbility)
+    const { can, build } = new AbilityBuilder<AppAbility>(createPrismaAbility)
     can('read', 'Post', {
       authorId: { notIn: [1, 2] }
     })
@@ -24,7 +24,7 @@ describe('PrismaAbility', () => {
 
   describe('types', () => {
     it('ensures that only specified models can be used as subjects', () => {
-      expect(createAppAbility([
+      expect(createPrismaAbility<AppAbility>([
         {
           action: 'read',
           subject: 'Post'
@@ -54,7 +54,7 @@ describe('PrismaAbility', () => {
     })
 
     it('provides type validation in `AbilityBuilder`', () => {
-      const { can } = new AbilityBuilder(createAppAbility)
+      const { can } = new AbilityBuilder<AppAbility>(createPrismaAbility)
 
       can('read', 'Post', {
         // @ts-expect-error referencing User property

packages/casl-prisma/spec/accessibleBy.spec.ts

@@ -1,9 +1,9 @@
 import { ForbiddenError } from '@casl/ability'
-import { accessibleBy } from '../src'
-import { createAppAbility } from './AppAbility'
+import { accessibleBy, createPrismaAbility } from '../src'
+import { AppAbility } from './AppAbility'
 
 describe('accessibleBy', () => {
-  const ability = createAppAbility([
+  const ability = createPrismaAbility<AppAbility>([
     {
       action: 'read',
       subject: 'Post',

packages/casl-prisma/src/createAbilityFactory.ts

@@ -1,21 +1,35 @@
-import { AbilityOptions, AbilityTuple, fieldPatternMatcher, PureAbility, RawRuleFrom } from '@casl/ability';
+import {
+  AbilityOptions,
+  AbilityOptionsOf,
+  AbilityTuple,
+  fieldPatternMatcher,
+  PureAbility,
+  RawRuleFrom,
+  RawRuleOf
+} from '@casl/ability';
 import { prismaQuery } from './prisma/prismaQuery';
 
 export function createAbilityFactory<
   TModelName extends string,
   TPrismaQuery extends Record<string, any>
 >() {
-  return function createAbility<
+  function createAbility<
+    T extends PureAbility<any, TPrismaQuery>
+  >(rules?: RawRuleOf<T>[], options?: AbilityOptionsOf<T>): T;
+  function createAbility<
     A extends AbilityTuple = [string, TModelName],
     C extends TPrismaQuery = TPrismaQuery
   >(
     rules?: RawRuleFrom<A, C>[],
     options?: AbilityOptions<A, C>
-  ) {
-    return new PureAbility<A, C>(rules, {
+  ): PureAbility<A, C>;
+  function createAbility(rules: any[] = [], options = {}): PureAbility<any, any> {
+    return new PureAbility(rules, {
       ...options,
       conditionsMatcher: prismaQuery,
       fieldMatcher: fieldPatternMatcher,
     });
-  };
+  }
+
+  return createAbility;
 }