@prisma/param-graph 0.0.1

package/README.md

@@ -0,0 +1,17 @@
+# @prisma/param-graph
+
+This package is intended for Prisma's internal use.
+
+Contains the ParamGraph types and utilities for schema-aware query parameterization in Prisma Client.
+
+ParamGraph is a compact data structure generated from DMMF (Data Model Metadata Format) at client generation time. It enables precise, schema-driven parameterization of query values at runtime.
+
+## Contents
+
+- `ParamGraph` - The main type representing the compact schema
+- `InputNode` / `OutputNode` - Node types for input arguments and output selections
+- `InputEdge` / `OutputEdge` - Edge types describing field capabilities
+- `EdgeFlag` - Bit flags for input field capabilities
+- `ScalarMask` - Bit mask for scalar type categories
+- `scalarTypeToMask` - Maps DMMF scalar type names to mask values
+- `hasFlag` / `getScalarMask` - Helper functions for edge inspection

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export type { EdgeFlagValue, InputEdge, InputNode, NodeId, OutputEdge, OutputNode, ParamGraph, RootEntry, ScalarMaskValue, } from './param-graph';
+export { EdgeFlag, getScalarMask, hasFlag, ScalarMask, scalarTypeToMask } from './param-graph';

package/dist/index.js

@@ -0,0 +1,36 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var index_exports = {};
+__export(index_exports, {
+  EdgeFlag: () => import_param_graph.EdgeFlag,
+  ScalarMask: () => import_param_graph.ScalarMask,
+  getScalarMask: () => import_param_graph.getScalarMask,
+  hasFlag: () => import_param_graph.hasFlag,
+  scalarTypeToMask: () => import_param_graph.scalarTypeToMask
+});
+module.exports = __toCommonJS(index_exports);
+var import_param_graph = require("./param-graph");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  EdgeFlag,
+  ScalarMask,
+  getScalarMask,
+  hasFlag,
+  scalarTypeToMask
+});

package/dist/index.mjs

@@ -0,0 +1,8 @@
+import { EdgeFlag, getScalarMask, hasFlag, ScalarMask, scalarTypeToMask } from "./param-graph";
+export {
+  EdgeFlag,
+  ScalarMask,
+  getScalarMask,
+  hasFlag,
+  scalarTypeToMask
+};

package/dist/param-graph.d.ts

@@ -0,0 +1,171 @@
+/**
+ * ParamGraph: Compact schema for runtime parameterization.
+ *
+ * This data structure is generated from DMMF at client generation time
+ * and embedded in the generated client. It enables schema-aware
+ * parameterization where values are only parameterized when both schema
+ * rules and runtime value types agree.
+ */
+/**
+ * Compact schema embedded in the generated client.
+ */
+export type ParamGraph = {
+    /**
+     * String table to avoid repeating field names.
+     * Field names are referenced by index throughout the graph.
+     */
+    s: string[];
+    /**
+     * User enum names for runtime membership checks.
+     * Values are looked up via `runtimeDataModel.enums[enumName].values`.
+     */
+    en: string[];
+    /**
+     * Input nodes used for argument objects and input types.
+     * Each node describes which fields are parameterizable or lead to
+     * parameterizable descendants.
+     */
+    i: InputNode[];
+    /**
+     * Output nodes used for selection traversal.
+     * Each node describes which fields have arguments or lead to
+     * nested selections with arguments.
+     */
+    o: OutputNode[];
+    /**
+     * Root mapping: "Model.action" or "action" (for non-model ops).
+     * Points to the args node (input) and root output node.
+     */
+    r: Record<string, RootEntry>;
+};
+/**
+ * Entry point for a root operation.
+ */
+export type RootEntry = {
+    /** Args node id (into `i` array) */
+    a?: NodeId;
+    /** Output node id (into `o` array) */
+    o?: NodeId;
+};
+/**
+ * Node ID is an index into `i` or `o` array.
+ */
+export type NodeId = number;
+/**
+ * Input node: describes parameterizable fields in an input object.
+ * Only fields that are parameterizable or lead to parameterizable
+ * descendants are present.
+ */
+export type InputNode = {
+    /**
+     * Map from string-table index to edge descriptor.
+     * Omitted if the node has no fields (shouldn't happen in practice).
+     */
+    f?: Record<number, InputEdge>;
+};
+/**
+ * Output node: describes fields in a selection set that have args
+ * or nested selections that may contain parameterizable args.
+ */
+export type OutputNode = {
+    /**
+     * Map from string-table index to edge descriptor.
+     */
+    f?: Record<number, OutputEdge>;
+};
+/**
+ * Edge descriptor for input fields.
+ * Encodes what kinds of values the field accepts and how to handle them.
+ */
+export type InputEdge = {
+    /**
+     * Bit flags describing field capabilities.
+     * See EdgeFlag enum below.
+     */
+    k: number;
+    /**
+     * Child input node id (for object values or list of objects).
+     * Present when the field accepts input object types.
+     */
+    c?: NodeId;
+    /**
+     * Scalar type mask for allowed scalar categories.
+     * Present when field accepts scalar values.
+     * See ScalarMask enum below.
+     */
+    m?: number;
+    /**
+     * Enum name id (index into `en` array).
+     * Present when field accepts a user enum without a plain String scalar.
+     * Used for runtime membership validation.
+     */
+    e?: number;
+};
+/**
+ * Edge descriptor for output fields.
+ */
+export type OutputEdge = {
+    /** Args node for this field (if it accepts arguments) */
+    a?: NodeId;
+    /** Next output node for nested selection traversal */
+    o?: NodeId;
+};
+/**
+ * Bit flags for InputEdge.k describing what the field accepts.
+ */
+export declare const EdgeFlag: {
+    /**
+     * Field may be parameterized as a scalar value.
+     * Check ScalarMask to validate the value type.
+     */
+    readonly ParamScalar: 1;
+    /**
+     * Field accepts list-of-scalar values.
+     * Parameterize the whole list if all elements match ScalarMask.
+     */
+    readonly ListScalar: 2;
+    /**
+     * Field accepts list-of-object values.
+     * Recurse into each element using the child node.
+     */
+    readonly ListObject: 4;
+    /**
+     * Field accepts object values.
+     * Recurse into child input node.
+     */
+    readonly Object: 8;
+    /**
+     * Field accepts null as a valid value.
+     * Note: Null values are NEVER parameterized at runtime regardless of this flag.
+     * This flag is informational only (reflects isNullable from DMMF).
+     */
+    readonly Nullable: 16;
+};
+export type EdgeFlagValue = (typeof EdgeFlag)[keyof typeof EdgeFlag];
+/**
+ * Bit mask for scalar type categories.
+ * Used in InputEdge.m to validate runtime value types.
+ */
+export declare const ScalarMask: {
+    readonly String: 1;
+    readonly Number: 2;
+    readonly Boolean: 4;
+    readonly DateTime: 8;
+    readonly Decimal: 16;
+    readonly BigInt: 32;
+    readonly Bytes: 64;
+    readonly Json: 128;
+};
+export type ScalarMaskValue = (typeof ScalarMask)[keyof typeof ScalarMask];
+/**
+ * Helper function to check if an edge has a specific flag.
+ */
+export declare function hasFlag(edge: InputEdge, flag: number): boolean;
+/**
+ * Helper function to get the scalar mask from an edge.
+ */
+export declare function getScalarMask(edge: InputEdge): number;
+/**
+ * Maps DMMF scalar type names to ScalarMask values.
+ */
+export declare function scalarTypeToMask(typeName: string): number;

package/dist/param-graph.js

@@ -0,0 +1,103 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var param_graph_exports = {};
+__export(param_graph_exports, {
+  EdgeFlag: () => EdgeFlag,
+  ScalarMask: () => ScalarMask,
+  getScalarMask: () => getScalarMask,
+  hasFlag: () => hasFlag,
+  scalarTypeToMask: () => scalarTypeToMask
+});
+module.exports = __toCommonJS(param_graph_exports);
+const EdgeFlag = {
+  /**
+   * Field may be parameterized as a scalar value.
+   * Check ScalarMask to validate the value type.
+   */
+  ParamScalar: 1,
+  /**
+   * Field accepts list-of-scalar values.
+   * Parameterize the whole list if all elements match ScalarMask.
+   */
+  ListScalar: 2,
+  /**
+   * Field accepts list-of-object values.
+   * Recurse into each element using the child node.
+   */
+  ListObject: 4,
+  /**
+   * Field accepts object values.
+   * Recurse into child input node.
+   */
+  Object: 8,
+  /**
+   * Field accepts null as a valid value.
+   * Note: Null values are NEVER parameterized at runtime regardless of this flag.
+   * This flag is informational only (reflects isNullable from DMMF).
+   */
+  Nullable: 16
+};
+const ScalarMask = {
+  String: 1,
+  Number: 2,
+  // Int, Float
+  Boolean: 4,
+  DateTime: 8,
+  Decimal: 16,
+  BigInt: 32,
+  Bytes: 64,
+  Json: 128
+};
+function hasFlag(edge, flag) {
+  return (edge.k & flag) !== 0;
+}
+function getScalarMask(edge) {
+  return edge.m ?? 0;
+}
+function scalarTypeToMask(typeName) {
+  switch (typeName) {
+    case "String":
+      return ScalarMask.String;
+    case "Int":
+    case "Float":
+      return ScalarMask.Number;
+    case "Boolean":
+      return ScalarMask.Boolean;
+    case "DateTime":
+      return ScalarMask.DateTime;
+    case "Decimal":
+      return ScalarMask.Decimal;
+    case "BigInt":
+      return ScalarMask.BigInt;
+    case "Bytes":
+      return ScalarMask.Bytes;
+    case "Json":
+      return ScalarMask.Json;
+    default:
+      return 0;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  EdgeFlag,
+  ScalarMask,
+  getScalarMask,
+  hasFlag,
+  scalarTypeToMask
+});

package/dist/param-graph.mjs

@@ -0,0 +1,75 @@
+const EdgeFlag = {
+  /**
+   * Field may be parameterized as a scalar value.
+   * Check ScalarMask to validate the value type.
+   */
+  ParamScalar: 1,
+  /**
+   * Field accepts list-of-scalar values.
+   * Parameterize the whole list if all elements match ScalarMask.
+   */
+  ListScalar: 2,
+  /**
+   * Field accepts list-of-object values.
+   * Recurse into each element using the child node.
+   */
+  ListObject: 4,
+  /**
+   * Field accepts object values.
+   * Recurse into child input node.
+   */
+  Object: 8,
+  /**
+   * Field accepts null as a valid value.
+   * Note: Null values are NEVER parameterized at runtime regardless of this flag.
+   * This flag is informational only (reflects isNullable from DMMF).
+   */
+  Nullable: 16
+};
+const ScalarMask = {
+  String: 1,
+  Number: 2,
+  // Int, Float
+  Boolean: 4,
+  DateTime: 8,
+  Decimal: 16,
+  BigInt: 32,
+  Bytes: 64,
+  Json: 128
+};
+function hasFlag(edge, flag) {
+  return (edge.k & flag) !== 0;
+}
+function getScalarMask(edge) {
+  return edge.m ?? 0;
+}
+function scalarTypeToMask(typeName) {
+  switch (typeName) {
+    case "String":
+      return ScalarMask.String;
+    case "Int":
+    case "Float":
+      return ScalarMask.Number;
+    case "Boolean":
+      return ScalarMask.Boolean;
+    case "DateTime":
+      return ScalarMask.DateTime;
+    case "Decimal":
+      return ScalarMask.Decimal;
+    case "BigInt":
+      return ScalarMask.BigInt;
+    case "Bytes":
+      return ScalarMask.Bytes;
+    case "Json":
+      return ScalarMask.Json;
+    default:
+      return 0;
+  }
+}
+export {
+  EdgeFlag,
+  ScalarMask,
+  getScalarMask,
+  hasFlag,
+  scalarTypeToMask
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@prisma/param-graph",
+  "version": "0.0.1",
+  "description": "This package is intended for Prisma's internal use",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.mjs"
+      }
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/prisma/prisma.git",
+    "directory": "packages/param-graph"
+  },
+  "license": "Apache-2.0",
+  "scripts": {
+    "dev": "DEV=true tsx helpers/build.ts",
+    "build": "tsx helpers/build.ts",
+    "prepublishOnly": "pnpm run build"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false
+}