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

package/README.md

@@ -2,172 +2,267 @@
 
 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).
 
-The following conditions are supported: `and`, `or`, `eq`, `ne`, `lt`, `gt`, `lte`, `gte` and `in`, as well as relational filters `some`, `none`, `is` and `isNot`.
+## Features
 
-Not Supported:
+### Supported Operators
 
-- `every`
-- `contains`
-- `search`
-- `mode`
-- `startsWith`
-- `endsWith`
-- `isSet`
-- Scalar filters
-- Atomic number operations
-- Composite keys
+- 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
 
 ## Requirements
 
-- Cerbos > v0.16
+- Cerbos > v0.40
 - `@cerbos/http` or `@cerbos/grpc` client
 
-## Usage
+## Installation
 
-```
+```bash
 npm install @cerbos/orm-prisma
 ```
 
-This package exports a function:
+## Usage
+
+The package exports a function:
 
 ```ts
 import { queryPlanToPrisma, PlanKind } from "@cerbos/orm-prisma";
 
-queryPlanToPrisma({ queryPlan, fieldNameMapper, relationMapper }): {
+queryPlanToPrisma({
+  queryPlan,                // The Cerbos query plan response
+  mapper,                   // Map Cerbos field names to Prisma field names
+}): {
   kind: PlanKind,
-  filters?: any // a filter to pass to the findMany() function of Prisma
+  filters?: any             // Prisma where conditions
 }
 ```
 
-where `PlanKind` is:
+### Basic Example
 
 ```ts
-export enum PlanKind {
-  /**
-   * The specified action is always allowed for the principal on resources matching the input.
-   */
-  ALWAYS_ALLOWED = "KIND_ALWAYS_ALLOWED",
-
-  /**
-   * The specified action is always denied for the principal on resources matching the input.
-   */
-  ALWAYS_DENIED = "KIND_ALWAYS_DENIED",
-
-  /**
-   * The specified action is conditionally allowed for the principal on resources matching the input.
-   */
-  CONDITIONAL = "KIND_CONDITIONAL",
-}
-```
-
-The function reqiures the full query plan from Cerbos to be passed in an object along with a `fieldNameMapper` and option `relationMapper` if the model has relations.
-
-A basic implementation can be as simple as:
-
-```js
 import { GRPC as Cerbos } from "@cerbos/grpc";
 import { PrismaClient } from "@prisma/client";
-
 import { queryPlanToPrisma, PlanKind } from "@cerbos/orm-prisma";
 
 const prisma = new PrismaClient();
 const cerbos = new Cerbos("localhost:3592", { tls: false });
 
-// Fetch the query plan from Cerbos passing in the principal
-// resource type and action
+// Fetch query plan from Cerbos
 const queryPlan = await cerbos.planResources({
-  principal: {....},
-  resource: { kind: "resourceKind" },
-  action: "view"
-})
+  principal: { id: "user1", roles: ["USER"] },
+  resource: { kind: "resource" },
+  action: "view",
+});
 
-// Generate the prisma filter from the query plan
+// Convert query plan to Prisma filters
 const result = queryPlanToPrisma({
   queryPlan,
-  fieldNameMapper: {
-    "request.resource.attr.aFieldName": "prismaModelFieldName"
+  mapper: {
+    "request.resource.attr.title": { field: "title" },
+    "request.resource.attr.status": { field: "status" },
   },
-  relationMapper: {
-    "request.resource.attr.aRelatedModel": {
-      "relation": "aRelatedModel",
-      "field": "id" // the column it is joined on
-    }
-  }
 });
 
-// The query plan says the user would always be denied
-// return empty or throw an error depending on your app.
-if(result.kind == PlanKind.ALWAYS_DENIED) {
-  return console.log([]);
+if (result.kind === PlanKind.ALWAYS_DENIED) {
+  return [];
 }
 
-// Pass the filters in as where conditions
-// If you have prexisting where conditions, you can pass them in an AND clause
-const result = await prisma.myModel.findMany({
+// Use filters in Prisma query
+const records = await prisma.resource.findMany({
+  where: result.filters,
+});
+
+// Use filters in Prisma query with other conditions
+const records = await prisma.resource.findMany({
   where: {
-    AND: result.filters
+    AND: [
+      {
+        status: "DRAFT"
+      },
+      result.filters,
+    ]
+});
+```
+
+### Field Name Mapping
+
+Fields can be mapped using either an object or a function:
+
+```ts
+// Object mapping
+const result = queryPlanToPrisma({
+  queryPlan,
+  mapper: {
+    "request.resource.attr.fieldName": { field: "prismaFieldName" },
   },
 });
 
-console.log(result)
+// Function mapping
+const result = queryPlanToPrisma({
+  queryPlan,
+  mapper: (fieldName) => ({
+    field: fieldName.replace("request.resource.attr.", ""),
+  }),
+});
 ```
 
-The `fieldNameMapper` is used to convert the field names in the query plan response to names of fields in the Prisma model - this can be done as a map or a function:
+### Relations Mapping
+
+Relations are mapped with their types and optional field configurations. Fields can be automatically inferred from the path if not explicitly mapped:
 
-```js
-const filters = queryPlanToPrisma({
+```ts
+const result = queryPlanToPrisma({
   queryPlan,
-  fieldNameMapper: {
-    "request.resource.attr.aFieldName": "prismaModelFieldName",
+  mapper: {
+    // Simple relation mapping - fields will be inferred
+    "request.resource.attr.owner": {
+      relation: {
+        name: "owner",
+        type: "one", // "one" for one-to-one, "many" for one-to-many
+      },
+    },
+
+    // Relation with explicit field mapping
+    "request.resource.attr.tags": {
+      relation: {
+        name: "tags",
+        type: "many",
+        field: "name", // Optional: specify field for direct comparisons
+      },
+    },
+
+    // Relation with nested field mappings
+    "request.resource.attr.nested": {
+      relation: {
+        name: "nested",
+        type: "one",
+        fields: {
+          // Optional: specify mappings for nested fields
+          aBool: { field: "aBool" },
+          aNumber: { field: "aNumber" },
+        },
+      },
+    },
   },
 });
+```
 
-//or
+### Field Inference Example
 
-const filters = queryPlanToPrisma({
-  queryPlan,
-  fieldNameMapper: (fieldName: string): string => {
-    if (fieldName.indexOf("request.resource.") > 0) {
-      return fieldName.replace("request.resource.attr", "");
+When using relations, fields are automatically inferred from the path unless explicitly mapped:
+
+```ts
+// These mappers are equivalent for handling: request.resource.attr.nested.aNumber
+{
+  "request.resource.attr.nested": {
+    relation: {
+      name: "nested",
+      type: "one",
+      fields: {
+        aNumber: { field: "aNumber" }
+      }
     }
+  }
+}
 
-    if (fieldName.indexOf("request.principal.") > 0) {
-      return fieldName.replace("request.principal.attr", "");
+// Shorter version - aNumber will be inferred from the path
+{
+  "request.resource.attr.nested": {
+    relation: {
+      name: "nested",
+      type: "one"
     }
-  },
-});
+  }
+}
 ```
 
-The `relationMapper` is used to convert references to fields which are joins at the database level
+### Complex Example with Multiple Relations and Direct Fields
 
-```js
-const filters = queryPlanToPrisma({
+```ts
+const result = queryPlanToPrisma({
   queryPlan,
-  fieldNameMapper: {},
-  relationMapper: {
-    "request.resource.attr.aRelatedModel": {
-      relation: "aRelatedModel",
-      field: "id", // the column it is joined on
+  mapper: {
+    "request.resource.attr.status": { field: "status" },
+    "request.resource.attr.owner": {
+      relation: {
+        name: "owner",
+        type: "one",
+      },
+    },
+    "request.resource.attr.tags": {
+      relation: {
+        name: "tags",
+        type: "many",
+        field: "name",
+      },
     },
   },
 });
 
-//or
+// Results in Prisma filters like:
+const result = await primsa.resource.findMany({
+  where: {
+    AND: [
+      { status: { equals: "active" } },
+      { owner: { is: { id: { equals: "user1" } } } },
+      { tags: { some: { name: { in: ["tag1", "tag2"] } } } },
+    ];
+  }
+})
+```
 
-const filters = queryPlanToPrisma({
+### Complex Examples
+
+#### Lambda Expression Examples
+
+```ts
+// Using exists with lambda expressions
+const result = queryPlanToPrisma({
   queryPlan,
-  fieldNameMapper: {},
-  relationMapper: (fieldName: string): string => {
-    if (fieldName.indexOf("request.resource.") > 0) {
-      return {
-        relation: fieldName.replace("request.resource.attr.", ""),
-        field: "id", // the column it is joined on
-      };
-    }
+  mapper: {
+    "request.resource.attr.comments": {
+      relation: {
+        name: "comments",
+        type: "many",
+        fields: {
+          author: {
+            relation: {
+              name: "author",
+              type: "one",
+            },
+          },
+          status: { field: "status" },
+        },
+      },
+    },
+  },
+});
+
+// This can handle complex exists queries like:
+// "Does the resource have any approved comments by specific users?"
+const result = await primsa.resource.findMany({
+  where: {
+    comments: {
+      some: {
+        AND: [
+          { status: { equals: "approved" } },
+          {
+            author: {
+              is: {
+                id: { in: ["user1", "user2"] },
+              },
+            },
+          },
+        ],
+      },
+    },
   },
 });
 ```
 
 ## Full Example
 
-A full Prisma application making use of this adapater can be found at [https://github.com/cerbos/express-prisma-cerbos](https://github.com/cerbos/express-prisma-cerbos)
+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)

package/lib/cjs/index.d.ts

@@ -1,24 +1,31 @@
-import { PlanResourcesResponse, PlanKind as PK } from "@cerbos/core";
-export declare type PlanKind = PK;
-export declare const PlanKind: typeof PK;
-declare type FieldMapper = {
-    [key: string]: string;
-} | ((key: string) => string);
-declare type Relation = {
-    relation: string;
-    field: string;
+import { PlanResourcesResponse, PlanKind } from "@cerbos/core";
+export { PlanKind };
+export type PrismaFilter = Record<string, any>;
+export type MapperConfig = {
+    field?: string;
+    relation?: {
+        name: string;
+        type: "one" | "many";
+        field?: string;
+        fields?: {
+            [key: string]: MapperConfig;
+        };
+    };
 };
-declare type RelationMapper = {
-    [key: string]: Relation;
-} | ((key: string) => Relation);
-interface QueryPlanToPrismaArgs {
+export type Mapper = {
+    [key: string]: MapperConfig;
+} | ((key: string) => MapperConfig);
+export interface QueryPlanToPrismaArgs {
     queryPlan: PlanResourcesResponse;
-    fieldNameMapper: FieldMapper;
-    relationMapper?: RelationMapper;
+    mapper?: Mapper;
 }
-interface QueryPlanToPrismaResult {
+export interface QueryPlanToPrismaResult {
     kind: PlanKind;
-    filters?: any;
+    filters?: Record<string, any>;
 }
-export declare function queryPlanToPrisma({ queryPlan, fieldNameMapper, relationMapper, }: QueryPlanToPrismaArgs): QueryPlanToPrismaResult;
-export {};
+/**
+ * Converts a Cerbos query plan to a Prisma filter.
+ * @param {QueryPlanToPrismaArgs} args - The arguments containing the query plan and mapper.
+ * @returns {QueryPlanToPrismaResult} The result containing the kind and filters.
+ */
+export declare function queryPlanToPrisma({ queryPlan, mapper, }: QueryPlanToPrismaArgs): QueryPlanToPrismaResult;