prisma-guard 1.31.0 → 1.32.0

package/README.md

@@ -1121,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.
@@ -1915,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
 
@@ -1959,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.
 
@@ -2738,6 +2790,4 @@ Possible future improvements:
 
 ## License
 
-MIT
-
-
+MIT

package/dist/runtime/index.cjs

@@ -975,40 +975,75 @@ function unsupported() {
   return marker;
 }
 
-// src/shared/match-caller.ts
-function matchCallerPattern(patterns, caller) {
-  if (typeof caller !== "string" || caller.trim().length === 0)
-    return null;
-  if (patterns.includes(caller))
-    return caller;
+// src/shared/guard-variant-routing.ts
+function matchVariantPatterns(keys, caller) {
+  const callerParts = caller.split("/");
   const matches = [];
-  for (const pattern of patterns) {
+  for (const pattern of keys) {
     if (!pattern.includes(":"))
       continue;
     const patternParts = pattern.split("/");
-    const callerParts = caller.split("/");
     if (patternParts.length !== callerParts.length)
       continue;
-    let ok = true;
-    for (let i = 0; i < patternParts.length; i++) {
-      if (patternParts[i].startsWith(":"))
+    let matchesCaller = true;
+    for (let index = 0; index < patternParts.length; index++) {
+      if (patternParts[index].startsWith(":"))
         continue;
-      if (patternParts[i] !== callerParts[i]) {
-        ok = false;
+      if (patternParts[index] !== callerParts[index]) {
+        matchesCaller = false;
         break;
       }
     }
-    if (ok)
+    if (matchesCaller)
       matches.push(pattern);
   }
-  if (matches.length === 0)
-    return null;
+  return matches;
+}
+function resolveGuardVariantKey(input) {
+  if (input.kind === "single") {
+    return { ok: true, key: "_default" };
+  }
+  const { keys, caller, reservedKeys } = input;
+  for (const key of keys) {
+    if (reservedKeys.has(key)) {
+      return {
+        ok: false,
+        code: "reserved-key",
+        key,
+        keys
+      };
+    }
+  }
+  const hasDefault = keys.includes("default");
+  if (typeof caller !== "string") {
+    if (hasDefault)
+      return { ok: true, key: "default" };
+    return { ok: false, code: "missing-caller", keys };
+  }
+  if (caller.trim().length === 0) {
+    if (hasDefault)
+      return { ok: true, key: "default" };
+    return { ok: false, code: "unknown-caller", caller, keys };
+  }
+  if (keys.includes(caller)) {
+    return { ok: true, key: caller };
+  }
+  const matches = matchVariantPatterns(keys, caller);
+  if (matches.length === 1) {
+    return { ok: true, key: matches[0] };
+  }
   if (matches.length > 1) {
-    throw new CallerError(
-      `Ambiguous caller "${caller}" matches multiple patterns: ${matches.map((p) => `"${p}"`).join(", ")}`
-    );
+    return {
+      ok: false,
+      code: "ambiguous-caller",
+      caller,
+      keys,
+      matches
+    };
   }
-  return matches[0];
+  if (hasDefault)
+    return { ok: true, key: "default" };
+  return { ok: false, code: "unknown-caller", caller, keys };
 }
 
 // src/runtime/policy.ts
@@ -3441,22 +3476,27 @@ function createQueryBuilder(typeMap, enumMap, uniqueMap, scalarBase) {
       forcedSelectCountWhere
     };
   }
-  function matchCaller(shapes, caller) {
-    const matched = matchCallerPattern(Object.keys(shapes), caller);
-    if (!matched)
-      return null;
-    return { key: matched, shape: shapes[matched] };
-  }
-  function resolveDefaultShape(config, model, method, normalizedBody, opts, builtCache, isUnique) {
-    const shapeOrFn = config.default;
-    let built;
-    if (typeof shapeOrFn === "function") {
-      const resolved = resolveAndValidateShape(shapeOrFn, opts?.ctx);
-      built = buildShapeZodSchema(model, method, resolved);
-    } else {
-      built = builtCache.get("default");
+  function throwQueryVariantResolution(resolution) {
+    const keys = resolution.keys.map((key) => `"${key}"`).join(", ");
+    if (resolution.code === "reserved-key") {
+      throw new ShapeError(
+        `Caller key "${resolution.key}" collides with reserved shape config key. Rename the caller path.`
+      );
+    }
+    if (resolution.code === "missing-caller") {
+      throw new CallerError(
+        `Missing caller. This query uses named shape routing with keys: ${keys}. Provide caller via opts.caller.`
+      );
     }
-    return applyBuiltShape(built, normalizedBody, isUnique);
+    if (resolution.code === "ambiguous-caller") {
+      const matches = (resolution.matches ?? []).map((pattern) => `"${pattern}"`).join(", ");
+      throw new CallerError(
+        `Ambiguous caller "${resolution.caller}" matches multiple patterns: ${matches}`
+      );
+    }
+    throw new CallerError(
+      `Unknown caller: "${resolution.caller}". Allowed: ${keys}`
+    );
   }
   function buildQuerySchema(model, method, config) {
     const isSingle = typeof config === "function" || isShapeConfig(config);
@@ -3468,12 +3508,15 @@ function createQueryBuilder(typeMap, enumMap, uniqueMap, scalarBase) {
       );
     }
     if (!isSingle) {
-      for (const key of Object.keys(config)) {
-        if (SHAPE_CONFIG_KEYS.has(key)) {
-          throw new ShapeError(
-            `Caller key "${key}" collides with reserved shape config key. Rename the caller path.`
-          );
-        }
+      const keys = Object.keys(config);
+      const validation = resolveGuardVariantKey({
+        kind: "named",
+        keys,
+        caller: void 0,
+        reservedKeys: SHAPE_CONFIG_KEYS
+      });
+      if (!validation.ok && validation.code === "reserved-key") {
+        throwQueryVariantResolution(validation);
       }
       for (const [key, shapeOrFn] of Object.entries(
         config
@@ -3511,47 +3554,20 @@ function createQueryBuilder(typeMap, enumMap, uniqueMap, scalarBase) {
             );
           }
           const namedConfig = config;
-          const caller = opts?.caller;
-          if (typeof caller !== "string") {
-            if ("default" in namedConfig) {
-              return resolveDefaultShape(
-                namedConfig,
-                model,
-                method,
-                normalizedBody,
-                opts,
-                builtCache,
-                isUnique
-              );
-            }
-            const allowed = Object.keys(namedConfig);
-            throw new CallerError(
-              `Missing caller. This query uses named shape routing with keys: ${allowed.map((k) => `"${k}"`).join(", ")}. Provide caller via opts.caller.`
-            );
-          }
-          const matched = matchCaller(namedConfig, caller);
-          if (!matched) {
-            if ("default" in namedConfig) {
-              return resolveDefaultShape(
-                namedConfig,
-                model,
-                method,
-                normalizedBody,
-                opts,
-                builtCache,
-                isUnique
-              );
-            }
-            const allowed = Object.keys(namedConfig);
-            throw new CallerError(
-              `Unknown caller: "${caller}". Allowed: ${allowed.map((k) => `"${k}"`).join(", ")}`
-            );
-          }
-          if (typeof matched.shape === "function") {
-            const resolved = resolveAndValidateShape(matched.shape, opts?.ctx);
+          const resolution = resolveGuardVariantKey({
+            kind: "named",
+            keys: Object.keys(namedConfig),
+            caller: opts?.caller,
+            reservedKeys: SHAPE_CONFIG_KEYS
+          });
+          if (!resolution.ok)
+            throwQueryVariantResolution(resolution);
+          const shapeOrFn = namedConfig[resolution.key];
+          if (typeof shapeOrFn === "function") {
+            const resolved = resolveAndValidateShape(shapeOrFn, opts?.ctx);
             built = buildShapeZodSchema(model, method, resolved);
           } else {
-            built = builtCache.get(matched.key);
+            built = builtCache.get(resolution.key);
           }
         }
         return applyBuiltShape(built, normalizedBody, isUnique);
@@ -4786,34 +4802,43 @@ function resolveDynamicShape(shapeFn, ctx, context) {
   }
   return result;
 }
-function resolveNamedShape(input, body, contextFn, explicitCaller) {
-  assertNoCallerInBody(body);
-  const caller = explicitCaller;
-  const keys = Object.keys(input);
-  for (const key of keys) {
-    if (GUARD_SHAPE_KEYS.has(key)) {
-      throw new ShapeError(
-        `Caller key "${key}" collides with reserved guard shape key. Rename the caller path.`
-      );
-    }
+function throwVariantResolution(resolution) {
+  const keys = resolution.keys.map((key) => `"${key}"`).join(", ");
+  if (resolution.code === "reserved-key") {
+    throw new ShapeError(
+      `Caller key "${resolution.key}" collides with reserved guard shape key. Rename the caller path.`
+    );
   }
-  if (typeof caller !== "string") {
-    if ("default" in input) {
-      return resolveShapeEntry(input.default, body, contextFn, "default");
-    }
+  if (resolution.code === "missing-caller") {
     throw new CallerError(
-      `Missing caller. This guard uses named shape routing with keys: ${keys.map((k) => `"${k}"`).join(", ")}. Provide caller via guard(input, caller).`
+      `Missing caller. This guard uses named shape routing with keys: ${keys}. Provide caller via guard(input, caller).`
     );
   }
-  const matched = matchCallerPattern(keys, caller);
-  if (matched) {
-    return resolveShapeEntry(input[matched], body, contextFn, matched);
-  }
-  if ("default" in input) {
-    return resolveShapeEntry(input.default, body, contextFn, "default");
+  if (resolution.code === "ambiguous-caller") {
+    const matches = (resolution.matches ?? []).map((pattern) => `"${pattern}"`).join(", ");
+    throw new CallerError(
+      `Ambiguous caller "${resolution.caller}" matches multiple patterns: ${matches}`
+    );
   }
   throw new CallerError(
-    `Unknown caller: "${caller}". Allowed: ${keys.map((k) => `"${k}"`).join(", ")}`
+    `Unknown caller: "${resolution.caller}". Allowed: ${keys}`
+  );
+}
+function resolveNamedShape(input, body, contextFn, explicitCaller) {
+  assertNoCallerInBody(body);
+  const resolution = resolveGuardVariantKey({
+    kind: "named",
+    keys: Object.keys(input),
+    caller: explicitCaller,
+    reservedKeys: GUARD_SHAPE_KEYS
+  });
+  if (!resolution.ok)
+    throwVariantResolution(resolution);
+  return resolveShapeEntry(
+    input[resolution.key],
+    body,
+    contextFn,
+    resolution.key
   );
 }
 function resolveShapeEntry(entry, body, contextFn, matchedKey) {