prisma-guard 1.30.0 → 1.32.0

package/README.md

@@ -644,10 +644,13 @@ For `groupBy`, normal grouped fields and `_count` fields must also be configured
 
 ### Unique where shapes
 
-`findUnique`, `findUniqueOrThrow`, `update`, `delete`, and `upsert` use Prisma's `WhereUniqueInput` syntax. For these methods, unique fields are configured directly in the shape:
+`findUnique`, `findUniqueOrThrow`, `update`, `delete`, and `upsert` use Prisma's `WhereUniqueInput` syntax.
+
+For these methods, configure selector fields directly in the shape:
 ```ts
 await prisma.project
   .guard({
+    data: { title: true },
     where: { id: true },
   })
   .update({
@@ -656,9 +659,108 @@ await prisma.project
   })
 ```
 
-Do not use filter operator objects such as `{ id: { equals: true } }` in unique where shapes. That syntax belongs to normal `WhereInput` filters used by methods such as `findMany`, `findFirst`, `count`, `updateMany`, and `deleteMany`.
+Do not use normal `WhereInput` filter operator objects such as `{ id: { equals: true } }` in unique where shapes. That syntax belongs to normal filter shapes used by methods such as `findMany`, `findFirst`, `count`, `updateMany`, and `deleteMany`.
+
+#### Extra non-unique filters in `update` and `delete`
+
+Prisma `WhereUniqueInput` can include additional non-unique scalar filters alongside a unique selector. This is useful for permission checks.
+
+For example, this is valid Prisma-style update filtering:
+```ts
+await prisma.post.update({
+  where: {
+    id: postId,
+    authorId: userId,
+  },
+  data: {
+    title: 'Updated',
+  },
+})
+```
+
+In prisma-guard shape syntax, model this with direct fields, not filter operators:
+```ts
+await prisma.post
+  .guard({
+    data: { title: true },
+    where: {
+      id: true,
+      authorId: force(userId),
+    },
+  })
+  .update({
+    data: { title: 'Updated' },
+    where: { id: postId },
+  })
+```
+
+The shape above means:
+
+* `id: true` is client-controlled and must be provided by the caller.
+* `authorId: force(userId)` is server-controlled and is merged into the final Prisma `where`.
+* The final Prisma call is constrained by both `id` and `authorId`.
+
+Do not write the same shape as:
+```ts
+where: {
+  id: true,
+  authorId: { equals: force(userId) },
+}
+```
+
+`authorId: { equals: ... }` is normal `WhereInput` filter syntax, not direct `WhereUniqueInput` syntax.
+
+At least one unique selector must still be present. Extra non-unique filters are additional constraints; they do not replace the unique selector requirement.
+
+#### Top-level unique where vs relation write selectors
+
+The direct forced-field syntax applies to **top-level** unique `where` shapes used by methods such as `update`, `delete`, `upsert`, `findUnique`, and `findUniqueOrThrow`.
+
+```ts
+where: {
+  id: true,
+  companyId: force(ctx.companyId),
+}
+```
+
+This lets the client provide `id`, while the server forces `companyId` into the final Prisma `where`.
+
+Do not assume the same forced-field syntax works inside relation write selectors such as `connect`, `disconnect`, `set`, nested `delete`, nested `update.where`, or `connectOrCreate.where`. Relation write selectors use their own validation path and should be configured as normal unique selector allowlists:
+
+```ts
+data: {
+  tags: {
+    connect: { id: true },
+  },
+}
+```
+
+If you need tenant-safe relation writes, validate ownership in application code, use a top-level guarded operation, or rely on database-level constraints such as foreign keys, RLS, or triggers. Nested relation writes bypass automatic tenant scope injection.
 
-If a model has multiple single-field unique selectors and the shape lists more than one, the client may use any allowed selector. For example, `where: { id: true, slug: true }` allows a request with `where: { id: '...' }` or `where: { slug: '...' }`. For compound unique constraints, use Prisma's generated compound selector name:
+#### Multiple unique selectors
+
+If a model has multiple single-field unique selectors and the shape lists more than one, the client may use any allowed selector.
+
+```ts
+where: {
+  id: true,
+  slug: true,
+}
+```
+
+This allows a request with:
+
+```ts
+where: { id: 'project_1' }
+```
+
+or:
+
+```ts
+where: { slug: 'my-project' }
+```
+
+For compound unique constraints, use Prisma's generated compound selector name:
 ```prisma
 model ProjectMember {
   tenantId String
@@ -731,7 +833,17 @@ await prisma.project
   })
 ```
 
-In update mode, all `data` fields are optional. The `where` shape must use Prisma unique selector syntax for `update`.
+In update mode, all `data` fields are optional. The `where` shape must use Prisma `WhereUniqueInput` syntax for `update`.
+
+For permission checks, you may include additional direct scalar filters alongside a unique selector:
+```ts
+where: {
+  id: true,
+  companyId: force(ctx.companyId),
+}
+```
+
+Do not use normal filter operator syntax such as `{ companyId: { equals: force(ctx.companyId) } }` in an update unique where shape.
 
 ### Forced values
 
@@ -774,7 +886,17 @@ await prisma.project
   .delete({ where: { id: 'abc123' } })
 ```
 
-`data` is not valid for delete shapes. The `where` shape must use Prisma unique selector syntax for `delete`.
+`data` is not valid for delete shapes. The `where` shape must use Prisma `WhereUniqueInput` syntax for `delete`.
+
+For permission checks, you may include additional direct scalar filters alongside a unique selector:
+```ts
+where: {
+  id: true,
+  companyId: force(ctx.companyId),
+}
+```
+
+Do not use normal filter operator syntax such as `{ companyId: { equals: force(ctx.companyId) } }` in a delete unique where shape.
 
 ### Batch creates
 ```ts
@@ -999,7 +1121,7 @@ The return value is:
 | `shape` | The concrete resolved guard shape after caller matching and dynamic shape execution |
 | `body` | The normalized request body. Omitted input becomes `{}` |
 | `effectiveReadBody` | The body used for read planning. If the body has no `select` or `include`, the shape's default read projection is applied |
-| `matchedKey` | The selected named-shape key, such as `default`, `admin`, or `/user/me` |
+| `matchedKey` | The selected declared key, such as `default`, `admin`, or `/user/:id`. For parameterized callers this is the pattern key, not the concrete caller value |
 | `wasDynamic` | `true` when the matched shape was a function and was executed with guard context |
 
 `resolve()` uses the same guard extension context and caller selection path as `.findMany()`, `.findFirst()`, and the other guarded methods. If the shape is context-dependent, the shape function is called with the current guard context.
@@ -1143,6 +1265,8 @@ members: {
 }
 ```
 
+Unlike top-level unique `where` shapes, relation write selector configs are allowlists for client-provided unique selectors. Do not rely on `force()` directly inside these selector configs unless your runtime version explicitly documents support for it.
+
 ### Scope implications
 
 Nested writes bypass the scope extension because Prisma extension hooks only fire for top-level operations. This means:
@@ -1791,22 +1915,40 @@ The `default` fallback works consistently across both `.guard()` and `guard.quer
 
 ### Note for generated route configs
 
-The direct `.guard({ where: ... })` form is still valid in the runtime API. Generated route configs from `prisma-generator-express`, however, type operation `shape` as a named shape map. For a single generated-route shape, put it under `default`:
+The direct runtime API accepts all three guard input forms:
+
+- one direct guard shape
+- one context-dependent shape function
+- a named shape map
+
+`prisma-generator-express` mirrors those forms under an operation's `shape` property. It also provides a `variants` descriptor API when each named shape needs its own route hooks:
 
 ```ts
 const projectConfig = {
   findMany: {
-    shape: {
+    before: [authenticate],
+    variants: {
+      admin: {
+        shape: {
+          where: { title: { contains: true }, status: { equals: true } },
+          take: { max: 100 },
+        },
+        before: [requireAdmin],
+      },
       default: {
-        where: { title: { contains: true } },
-        take: { max: 50, default: 20 },
+        shape: {
+          where: { title: { contains: true } },
+          take: { max: 20, default: 10 },
+        },
       },
     },
   },
 }
 ```
 
-Additional keys such as `admin`, `public`, or path patterns are caller-routed variants. Reserved shape keys such as `where`, `data`, `include`, and `select` cannot be used as caller keys.
+Within one generated operation, `shape` and `variants` cannot both be defined. Both may be omitted when the operation only needs operation-wide hooks or pagination. Each `variants[key].shape` is one direct shape or one context-dependent shape function; it is not another nested named map.
+
+Use `shape` when only guard routing is needed. Use `variants` when hooks need to differ by the matched named shape.
 
 ### Caller resolution order
 
@@ -1835,16 +1977,50 @@ await prisma.project.guard({ where: { ... } }).findMany(req.body)
 The `caller` key in the context object is not used for scope injection — it is only used for shape routing. Scope roots are identified by matching context keys against `@scope-root` model names.
 
 ### Parameterized caller patterns
+
 ```text
 /org/:orgId/users
 /org/:orgId/users/:userId
 ```
 
-Matching is case-sensitive. Exact matches are checked first. If no exact match is found, parameterized patterns are evaluated. Parameters are routing-only and are not extracted into context.
+Matching is case-sensitive. A parameter segment starts with `:` and matches exactly one path segment. Segment counts must be equal. Parameters are routing-only and are not extracted into context.
+
+Caller routing uses this precedence:
+
+1. Reject any named key that collides with a reserved guard shape key.
+2. If caller is not a string, use `default` when present; otherwise throw the missing-caller `CallerError`.
+3. If caller is blank or whitespace-only, skip exact and parameterized matching. Use `default` when present; otherwise throw unknown-caller `CallerError`.
+4. A non-blank exact key match wins immediately.
+5. If there is no exact match, evaluate parameterized patterns.
+6. One matching pattern selects that declared pattern key.
+7. Multiple matching patterns throw an ambiguous-caller `CallerError` listing every match.
+8. With no match, use `default` when present; otherwise throw unknown-caller `CallerError`.
+
+Exact matching therefore wins over a pattern that would also match:
+
+```ts
+const shapes = {
+  'customer/123': exactShape,
+  'customer/:id': parameterizedShape,
+}
+
+// Selects "customer/123", not "customer/:id".
+await prisma.order.guard(shapes, 'customer/123').findMany()
+```
+
+For a parameterized caller, `matchedKey` is the declared pattern key. A caller of `customer/123` matched by `customer/:id` produces `matchedKey === 'customer/:id'`. This is the key used for shape memoization and returned by `resolve()`.
 
 ### Fail-closed behavior
 
-If `caller` is missing or doesn't match any pattern and no `default` key exists, the request is rejected with a `CallerError`. If a caller matches multiple parameterized patterns, it is also rejected with a `CallerError`.
+Named routing fails closed:
+
+- A non-string caller with no `default` throws the missing-caller `CallerError`.
+- A blank or whitespace-only caller never matches a blank key or a parameterized key. It uses `default` or throws unknown-caller `CallerError`.
+- An unmatched caller uses `default` or throws unknown-caller `CallerError`.
+- Multiple matching parameterized patterns throw ambiguous-caller `CallerError`.
+- A caller key that collides with a reserved shape key throws `ShapeError`.
+
+The same precedence and error behavior apply to `.guard()` and `guard.query().parse()`.
 
 If a request body contains a `caller` field when using named shapes, it is rejected with a `CallerError` that directs the developer to use the second argument to `.guard()` or the context function instead.
 
@@ -2614,5 +2790,4 @@ Possible future improvements:
 
 ## License
 
-MIT
-
+MIT

package/dist/generator/index.js

@@ -302,6 +302,12 @@ function emitTypeMap(dmmf) {
         metaPairs.push(["isUnsupported", true]);
       if (field.isUnique)
         metaPairs.push(["isUnique", true]);
+      if (isRelation && Array.isArray(field.relationFromFields) && field.relationFromFields.length > 0) {
+        metaPairs.push([
+          "relationFromFields",
+          [...field.relationFromFields]
+        ]);
+      }
       return `    ${JSON.stringify(field.name)}: { ${serializeMeta(metaPairs)} },`;
     }).join("\n");
     return `  ${JSON.stringify(model.name)}: {