@cerbos/orm-prisma 2.0.0-alpha.1 → 2.0.0

package/README.md

@@ -1,22 +1,37 @@
 # Cerbos + Prisma ORM Adapter
 
-An adapter library that takes a [Cerbos](https://cerbos.dev) Query Plan ([PlanResources API](https://docs.cerbos.dev/cerbos/latest/api/index.html#resources-query-plan)) response and converts it into a [Prisma](https://prisma.io) where class object. This is designed to work alongside a project using the [Cerbos Javascript SDK](https://github.com/cerbos/cerbos-sdk-javascript).
+An adapter library that takes a [Cerbos](https://cerbos.dev) Query Plan ([PlanResources API](https://docs.cerbos.dev/cerbos/latest/api/index.html#resources-query-plan)) response and converts it into a [Prisma](https://prisma.io) where clause object. This is designed to work alongside a project using the [Cerbos Javascript SDK](https://github.com/cerbos/cerbos-sdk-javascript).
 
 ## Features
 
 ### Supported Operators
 
+#### Basic Operators
+
 - Logical operators: `and`, `or`, `not`
 - Comparison operators: `eq`, `ne`, `lt`, `gt`, `lte`, `gte`, `in`
-- Relation operators: `some`, `none`, `is`, `isNot`, `hasIntersection`
 - String operations: `startsWith`, `endsWith`, `contains`, `isSet`
-- Support for nested fields and relations
-- Support for both one-to-one, one-to-many and many-to-many relationships
+
+#### Relation Operators
+
+- One-to-one: `is`, `isNot`
+- One-to-many/Many-to-many: `some`, `none`, `every`
+- Collection operators: `exists`, `exists_one`, `all`, `filter`
+- Set operations: `hasIntersection`
+
+#### Advanced Features
+
+- Deep nested relations support
+- Automatic field inference
+- Collection mapping and filtering
+- Complex condition combinations
+- Type-safe field mappings
 
 ## Requirements
 
 - Cerbos > v0.40
 - `@cerbos/http` or `@cerbos/grpc` client
+- Prisma > v6.0
 
 ## Installation
 
@@ -42,6 +57,49 @@ queryPlanToPrisma({
 
 ### Basic Example
 
+1. Create a basic policy file in the `policies` directory:
+
+```yaml
+apiVersion: api.cerbos.dev/v1
+resourcePolicy:
+  resource: resource
+  version: default
+  rules:
+    - actions: ["view"]
+      effect: EFFECT_ALLOW
+      roles: ["USER"]
+      condition:
+        match:
+          expr: request.resource.attr.status == "active"
+```
+
+2. Start Cerbos PDP:
+
+```bash
+docker run --rm -i -p 3592:3592 -v $(pwd)/policies:/policies ghcr.io/cerbos/cerbos:latest
+```
+
+3. Create Prisma schema (`prisma/schema.prisma`):
+
+```prisma
+datasource db {
+  provider = "sqlite"
+  url      = env("DATABASE_URL")
+}
+
+generator client {
+  provider = "prisma-client-js"
+}
+
+model Resource {
+  id     Int     @id @default(autoincrement())
+  title  String
+  status String
+}
+```
+
+4. Implement the mapper
+
 ```ts
 import { GRPC as Cerbos } from "@cerbos/grpc";
 import { PrismaClient } from "@prisma/client";
@@ -263,6 +321,89 @@ const result = await primsa.resource.findMany({
 });
 ```
 
+## Types
+
+### Query Plan Response Types
+
+The adapter is fully typed and provides clear type definitions for all responses:
+
+```ts
+import { PlanKind, QueryPlanToPrismaResult } from "@cerbos/orm-prisma";
+
+// The result will be one of these types:
+type QueryPlanToPrismaResult =
+  | {
+      kind: PlanKind.ALWAYS_ALLOWED | PlanKind.ALWAYS_DENIED;
+    }
+  | {
+      kind: PlanKind.CONDITIONAL;
+      filters: Record<string, any>;
+    };
+
+// Example usage with type narrowing:
+const result = queryPlanToPrisma({ queryPlan });
+
+if (result.kind === PlanKind.CONDITIONAL) {
+  // TypeScript knows `filters` exists here
+  const records = await prisma.resource.findMany({
+    where: result.filters,
+  });
+} else if (result.kind === PlanKind.ALWAYS_ALLOWED) {
+  // No filters needed
+  const records = await prisma.resource.findMany();
+} else {
+  // Must be ALWAYS_DENIED
+  return [];
+}
+```
+
+### Mapper Types
+
+The mapper configuration is also fully typed:
+
+```ts
+type MapperConfig = {
+  field?: string;
+  relation?: {
+    name: string;
+    type: "one" | "many";
+    field?: string;
+    fields?: {
+      [key: string]: MapperConfig; // Recursive for nested fields
+    };
+  };
+};
+
+type Mapper = { [key: string]: MapperConfig } | ((key: string) => MapperConfig);
+```
+
 ## Full Example
 
 A complete example application using this adapter can be found at [https://github.com/cerbos/express-prisma-cerbos](https://github.com/cerbos/express-prisma-cerbos)
+
+## Resources
+
+### Documentation
+
+- [Cerbos Documentation](https://docs.cerbos.dev)
+- [Prisma Documentation](https://www.prisma.io/docs)
+- [Query Plan API Reference](https://docs.cerbos.dev/cerbos/latest/api/index.html#resources-query-plan)
+
+### Examples and Tutorials
+
+- [Express + Prisma + Cerbos Example](https://github.com/cerbos/express-prisma-cerbos)
+- [Cerbos Query Planning Guide](https://docs.cerbos.dev/cerbos/latest/policies/compile.html)
+- [Prisma Filtering Guide](https://www.prisma.io/docs/concepts/components/prisma-client/filtering-and-sorting)
+
+### Related Projects
+
+- [Cerbos JavaScript SDK](https://github.com/cerbos/cerbos-sdk-javascript)
+
+### Community
+
+- [Cerbos Slack](https://community.cerbos.dev)
+- [Cerbos GitHub Discussions](https://github.com/cerbos/cerbos/discussions)
+
+## License
+
+Apache 2.0 - See [LICENSE](../LICENSE) for more information.

package/lib/cjs/index.d.ts

@@ -19,10 +19,12 @@ export interface QueryPlanToPrismaArgs {
     queryPlan: PlanResourcesResponse;
     mapper?: Mapper;
 }
-export interface QueryPlanToPrismaResult {
-    kind: PlanKind;
-    filters?: Record<string, any>;
-}
+export type QueryPlanToPrismaResult = {
+    kind: PlanKind.ALWAYS_ALLOWED | PlanKind.ALWAYS_DENIED;
+} | {
+    kind: PlanKind.CONDITIONAL;
+    filters: Record<string, any>;
+};
 /**
  * Converts a Cerbos query plan to a Prisma filter.
  * @param {QueryPlanToPrismaArgs} args - The arguments containing the query plan and mapper.