prisma-guard 1.28.0 → 1.29.0

package/README.md

@@ -41,6 +41,7 @@ database
 * [Before / After prisma-guard](#before--after-prisma-guard)
 * [Schema annotations](#schema-annotations)
 * [The guard API](#the-guard-api)
+* [Read planning with resolve()](#read-planning-with-resolve)
 * [Relation writes in data shapes](#relation-writes-in-data-shapes)
 * [Logical combinators in where shapes](#logical-combinators-in-where-shapes)
 * [Relation filters in where shapes](#relation-filters-in-where-shapes)
@@ -511,7 +512,7 @@ When a refine function returns a schema that handles undefined input (e.g. by in
 
 ## The guard API
 
-`.guard(shape)` is available on every model delegate. It returns an object with all Prisma methods. The shape defines the boundary; the method validates and executes.
+`.guard(shape, caller?)` is available on every model delegate. It returns an object with all Prisma methods plus `resolve()`. The shape defines the boundary; the chained Prisma method validates and executes. `resolve()` is a read-planning helper that resolves the same shape boundary without executing Prisma.
 
 ### Data shape syntax
 
@@ -938,8 +939,78 @@ Reads: `findMany`, `findFirst`, `findFirstOrThrow`, `findUnique`, `findUniqueOrT
 
 Writes: `create`, `createMany`, `createManyAndReturn`, `update`, `updateMany`, `updateManyAndReturn`, `upsert`, `delete`, `deleteMany`
 
+### `findManyPaginated`
+
+`findManyPaginated` is an intentional operation shape used by the integrated
+`prisma-generator-express` stack.
+
+It is not expected to map 1:1 to a native Prisma Client method. It exists so
+guard shapes can be generated for the paginated route/helper layer.
+
+
 ---
 
+
+## Read planning with resolve()
+
+`.guard(shape, caller?).resolve(body?)` resolves a read shape without executing a Prisma query.
+
+Use it when integration code needs to inspect the concrete guard shape and effective read body before deciding how to run a read. Typical use cases are generated routers, progressive response streaming, query planners, and adapters that need the same shape resolution as the real guarded method.
+
+```ts
+const resolved = prisma.user
+  .guard(
+    {
+      me: (ctx) => ({
+        where: {
+          id: { equals: force(ctx.userId) },
+        },
+        select: {
+          id: true,
+          email: true,
+          profile: {
+            select: {
+              id: true,
+              displayName: true,
+            },
+          },
+        },
+      }),
+    },
+    'me',
+  )
+  .resolve()
+```
+
+The return value is:
+
+```ts
+{
+  shape: GuardShape
+  body: Record<string, unknown>
+  effectiveReadBody: Record<string, unknown>
+  matchedKey: string
+  wasDynamic: boolean
+}
+```
+
+| Field | Meaning |
+| ----- | ------- |
+| `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` |
+| `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.
+
+`resolve()` is intentionally read-only. It rejects top-level `data`, `create`, and `update` keys on either the resolved shape or the request body. Use the corresponding guarded write method for writes.
+
+`effectiveReadBody` is planning input, not final Prisma args. It does not replace the normal guarded read execution pipeline. The actual guarded read method still validates the body, applies forced values, applies default projection rules, injects scope filters, and calls Prisma.
+
+No Prisma delegate method is called by `resolve()`.
+
+
 ## Relation writes in data shapes
 
 Data shapes support relation fields with a config object describing which nested write operations the client may use. Each operation (`connect`, `create`, `disconnect`, etc.) is configured individually.
@@ -1315,6 +1386,8 @@ where: {
 
 When a read shape defines `select` or `include`, the projection serves two roles: it whitelists what the client is allowed to request, and it provides the default projection when the client omits `select`/`include` from the body.
 
+The same default-projection behavior is exposed for planning through [`resolve()`](#read-planning-with-resolve): `effectiveReadBody` contains the request body plus the synthesized default projection when the client omitted projection.
+
 A client-provided `select` or `include` is treated as a narrowing request inside the shape's whitelist. It should not widen back to the full default projection. If the client asks for fewer fields than the shape allows, only the requested allowed fields are returned.
 
 If the client sends a body without `select` or `include`, the shape's projection is automatically synthesized and passed to Prisma. This eliminates the need for the client to duplicate the field list that the backend already defines.
@@ -2542,3 +2615,4 @@ Possible future improvements:
 ## License
 
 MIT
+

package/dist/generator/index.js

@@ -117,7 +117,7 @@ import { createGuard } from '${runtimeImportPath}'
 import { SCOPE_MAP, TYPE_MAP, ENUM_MAP, ZOD_CHAINS, GUARD_CONFIG, UNIQUE_MAP, ZOD_DEFAULTS } from '${indexImport}'
 import type { ScopeRoot } from '${indexImport}'
 
-` + emitGuardModelExtension(dmmf) + `
+${emitGuardModelExtension(dmmf)}
 export const guard = createGuard<typeof TYPE_MAP, ScopeRoot, GuardModelExtension>({
   scopeMap: SCOPE_MAP,
   typeMap: TYPE_MAP,
@@ -134,7 +134,7 @@ export const guard = createGuard<typeof TYPE_MAP, ScopeRoot, GuardModelExtension
 function isScopeRoot(documentation) {
   if (!documentation)
     return false;
-  const tokens = documentation.split(/[\s\n\r]+/);
+  const tokens = documentation.split(/\s+/);
   return tokens.some((t) => t === "@scope-root");
 }
 function reportScopeIssue(mode, errorMsg, warnMsg) {
@@ -143,9 +143,6 @@ function reportScopeIssue(mode, errorMsg, warnMsg) {
   if (mode === "warn")
     console.warn(`prisma-guard: ${warnMsg}`);
 }
-function serializeScopeEntry(e) {
-  return `{ fk: ${JSON.stringify(e.fk)}, root: ${JSON.stringify(e.root)}, relationName: ${JSON.stringify(e.relationName)} }`;
-}
 function emitScopeMap(dmmf, onAmbiguousScope) {
   const rootModels = /* @__PURE__ */ new Set();
   for (const model of dmmf.datamodel.models) {
@@ -205,8 +202,9 @@ function emitScopeMap(dmmf, onAmbiguousScope) {
     }
   }
   const roots = Array.from(rootModels).sort();
+  const formatEntry = (e) => `{ fk: ${JSON.stringify(e.fk)}, root: ${JSON.stringify(e.root)}, relationName: ${JSON.stringify(e.relationName)} }`;
   const mapEntries = Object.entries(scopeMap).map(([model, entries]) => {
-    const entriesStr = entries.map(serializeScopeEntry).join(", ");
+    const entriesStr = entries.map(formatEntry).join(", ");
     return `  ${model}: [${entriesStr}],`;
   }).join("\n");
   const scopeRootType = roots.length > 0 ? roots.map((r) => `'${r}'`).join(" | ") : "never";
@@ -323,7 +321,7 @@ ${fieldEntries}
       return `{ selector: ${JSON.stringify(c.selector)}, fields: [${fields}] }`;
     }).join(", ");
     return `  ${JSON.stringify(model.name)}: [${constraintsStr}],`;
-  }).filter(Boolean).join("\n");
+  }).filter((entry) => entry !== null).join("\n");
   const typeMapSource = `export const TYPE_MAP = {
 ${modelEntries}
 } as const
@@ -350,21 +348,22 @@ ${typesSource}
 // src/shared/operation-shape-keys.ts
 var OPERATION_SHAPE_KEYS = {
   findMany: ["where", "include", "select", "orderBy", "cursor", "take", "skip", "distinct"],
+  findManyPaginated: ["where", "include", "select", "orderBy", "cursor", "take", "skip", "distinct"],
   findFirst: ["where", "include", "select", "orderBy", "cursor", "take", "skip", "distinct"],
   findFirstOrThrow: ["where", "include", "select", "orderBy", "cursor", "take", "skip", "distinct"],
   findUnique: ["where", "include", "select"],
   findUniqueOrThrow: ["where", "include", "select"],
   count: ["where", "select", "cursor", "orderBy", "skip", "take"],
   aggregate: ["where", "orderBy", "cursor", "take", "skip", "_count", "_avg", "_sum", "_min", "_max"],
-  groupBy: ["where", "by", "having", "_count", "_avg", "_sum", "_min", "_max", "orderBy", "take", "skip"],
-  create: ["data", "select", "include"],
-  createMany: ["data"],
-  createManyAndReturn: ["data", "select", "include"],
-  update: ["data", "where", "select", "include"],
-  updateMany: ["data", "where"],
-  updateManyAndReturn: ["data", "where", "select", "include"],
-  upsert: ["where", "create", "update", "select", "include"],
-  delete: ["where", "select", "include"],
+  groupBy: ["where", "orderBy", "by", "having", "take", "skip", "_count", "_avg", "_sum", "_min", "_max"],
+  create: ["data", "include", "select"],
+  createMany: ["data", "skipDuplicates"],
+  createManyAndReturn: ["data", "select", "include", "skipDuplicates"],
+  update: ["where", "data", "include", "select"],
+  updateMany: ["where", "data"],
+  updateManyAndReturn: ["where", "data", "select", "include"],
+  upsert: ["where", "create", "update", "include", "select"],
+  delete: ["where", "include", "select"],
   deleteMany: ["where"]
 };
 var READ_METHOD_ALLOWED_ARGS = {
@@ -938,7 +937,7 @@ function createScalarBase(strictDecimal) {
   return {
     String: () => z.string(),
     Int: () => z.number().int(),
-    Float: () => z.number(),
+    Float: () => z.number().finite(),
     Decimal: createDecimalFactory(strictDecimal),
     BigInt: () => z.union([
       z.bigint(),
@@ -1085,6 +1084,33 @@ ${entries}
     defaults
   };
 }
+function emitZodDefaults(defaults) {
+  const entries = Object.entries(defaults);
+  if (entries.length === 0) {
+    return `export const ZOD_DEFAULTS: Record<string, readonly string[]> = {}
+`;
+  }
+  const mapEntries = entries.map(([model, fields]) => {
+    const fieldsStr = fields.map((field) => JSON.stringify(field)).join(", ");
+    return `  ${JSON.stringify(model)}: [${fieldsStr}],`;
+  }).join("\n");
+  return `export const ZOD_DEFAULTS: Record<string, readonly string[]> = {
+${mapEntries}
+}
+`;
+}
+
+// src/generator/emit-guard-config.ts
+function emitGuardConfig(cfg) {
+  return `export const GUARD_CONFIG = {
+  onMissingScopeContext: ${JSON.stringify(cfg.onMissingScopeContext)},
+  findUniqueMode: ${JSON.stringify(cfg.findUniqueMode)},
+  onScopeRelationWrite: ${JSON.stringify(cfg.onScopeRelationWrite)},
+  strictDecimal: ${JSON.stringify(cfg.strictDecimal)},
+  enforceProjection: ${JSON.stringify(cfg.enforceProjection)},
+} as const
+`;
+}
 
 // src/generator/index.ts
 var { generatorHandler } = pkg;
@@ -1112,21 +1138,6 @@ function parseGeneratorConfig(raw) {
   }).join("; ");
   throw new Error(`prisma-guard: Invalid generator config: ${issues}`);
 }
-function emitZodDefaults(defaults) {
-  const entries = Object.entries(defaults);
-  if (entries.length === 0) {
-    return `export const ZOD_DEFAULTS: Record<string, readonly string[]> = {}
-`;
-  }
-  const mapEntries = entries.map(([model, fields]) => {
-    const fieldsStr = fields.map((field) => JSON.stringify(field)).join(", ");
-    return `  ${JSON.stringify(model)}: [${fieldsStr}],`;
-  }).join("\n");
-  return `export const ZOD_DEFAULTS: Record<string, readonly string[]> = {
-${mapEntries}
-}
-`;
-}
 function getProviderValue(provider) {
   if (typeof provider === "string")
     return provider;
@@ -1195,14 +1206,13 @@ generatorHandler({
     const dmmf = options.dmmf;
     const parts = [];
     parts.push(
-      `export const GUARD_CONFIG = {
-  onMissingScopeContext: ${JSON.stringify(cfg.onMissingScopeContext)},
-  findUniqueMode: ${JSON.stringify(cfg.findUniqueMode)},
-  onScopeRelationWrite: ${JSON.stringify(cfg.onScopeRelationWrite)},
-  strictDecimal: ${JSON.stringify(cfg.strictDecimal)},
-  enforceProjection: ${JSON.stringify(cfg.enforceProjection)},
-} as const
-`
+      emitGuardConfig({
+        onMissingScopeContext: cfg.onMissingScopeContext,
+        findUniqueMode: cfg.findUniqueMode,
+        onScopeRelationWrite: cfg.onScopeRelationWrite,
+        strictDecimal: cfg.strictDecimal,
+        enforceProjection: cfg.enforceProjection
+      })
     );
     const { source: scopeSource } = emitScopeMap(dmmf, cfg.onAmbiguousScope);
     parts.push(scopeSource);