@prisma/sqlcommenter-query-insights 0.0.1

package/README.md

@@ -0,0 +1,120 @@
+# @prisma/sqlcommenter-query-insights
+
+A SQL commenter plugin for Prisma ORM that adds query shape information to SQL comments. This enables observability tools to analyze and group queries by their structural patterns rather than specific values.
+
+## Installation
+
+```bash
+npm install @prisma/sqlcommenter-query-insights
+```
+
+## Usage
+
+```typescript
+import { prismaQueryInsights } from '@prisma/sqlcommenter-query-insights'
+import { PrismaClient } from '@prisma/client'
+
+const prisma = new PrismaClient({
+  adapter: myAdapter, // Driver adapter required (alternatively, Accelerate URL)
+  comments: [prismaQueryInsights()],
+})
+```
+
+The resulting SQL will include comments like:
+
+```sql
+SELECT ... FROM "User" /*prismaQuery='User.findMany:eyJ3aGVyZSI6eyJhY3RpdmUiOnsiJHR5cGUiOiJQYXJhbSJ9fSwiaW5jbHVkZSI6eyJwb3N0cyI6dHJ1ZX19'*/
+```
+
+## What It Does
+
+This plugin adds a `prismaQuery` comment tag to every SQL query. The tag contains:
+
+- **Model name**: The Prisma model being queried (e.g., `User`, `Post`)
+- **Action**: The Prisma operation (e.g., `findMany`, `createOne`, `updateOne`)
+- **Query shape**: A parameterized representation of the query structure (base64url encoded)
+
+### Example Outputs
+
+| Query Type               | Output Format                                                      |
+| ------------------------ | ------------------------------------------------------------------ |
+| Raw query                | `queryRaw`                                                         |
+| Simple find (all fields) | `User.findMany:e30`                                                |
+| Find with where          | `User.findUnique:eyJ3aGVyZSI6eyJpZCI6eyIkdHlwZSI6IlBhcmFtIn19fQ`   |
+| Find with include        | `User.findMany:eyJpbmNsdWRlIjp7InBvc3RzIjp0cnVlfX0`                |
+| Find with select         | `User.findMany:eyJzZWxlY3QiOnsibmFtZSI6dHJ1ZX19`                   |
+| Batched queries          | `User.findUnique:W3sid2hlcmUiOnsiaWQiOnsiJHR5cGUiOiJQYXJhbSJ9fX1d` |
+
+## Security
+
+**User data is never included in the comments.** All values that could contain user data are replaced with placeholder markers before encoding. This includes:
+
+- Filter values (in `where` clauses)
+- Data values (in `create`/`update` operations)
+- Values in all filter operators (`equals`, `contains`, `in`, etc.)
+- Tagged values (DateTime, Decimal, BigInt, Bytes, Json)
+
+Only structural information is preserved:
+
+- Field names and relationships
+- Query structure (selection, filters, ordering)
+- Pagination parameters (`take`, `skip`)
+- Sort directions and null handling options
+
+## Use Cases
+
+### Query Analysis
+
+Group queries by their shape to identify:
+
+- Most frequently executed query patterns
+- Slow query patterns that need optimization
+- Unusual query patterns that might indicate bugs
+
+### Observability Integration
+
+The `prismaQuery` tag can be parsed by observability tools to:
+
+- Create dashboards showing query pattern distribution
+- Set up alerts for specific query patterns
+- Correlate application behavior with database load
+
+### Debugging
+
+Quickly identify which Prisma operation generated a specific SQL query in your database logs.
+
+## Combining with Other Plugins
+
+```typescript
+import { prismaQueryInsights } from '@prisma/sqlcommenter-query-insights'
+import { traceContext } from '@prisma/sqlcommenter-trace-context'
+import { queryTags, withQueryTags } from '@prisma/sqlcommenter-query-tags'
+
+const prisma = new PrismaClient({
+  adapter: myAdapter,
+  comments: [prismaQueryInsights(), traceContext(), queryTags()],
+})
+
+// All tags are merged into the SQL comment
+await withQueryTags({ route: '/api/users' }, () => prisma.user.findMany())
+```
+
+## API
+
+### `prismaQueryInsights()`
+
+Creates a SQL commenter plugin that adds query shape information.
+
+```typescript
+function prismaQueryInsights(): SqlCommenterPlugin
+```
+
+**Returns:** A `SqlCommenterPlugin` that adds the `prismaQuery` tag.
+
+## Technical Details
+
+For integrators building observability tools that parse these comments, see the [Embedder Documentation](./docs/embedder-guide.md).
+
+## License
+
+Apache-2.0

package/dist/format.d.ts

@@ -0,0 +1,15 @@
+import type { SqlCommenterQueryInfo } from '@prisma/sqlcommenter';
+/**
+ * Encodes data to base64url (URL-safe base64 without padding)
+ */
+export declare function toBase64Url(data: string): string;
+/**
+ * Formats query info into the compact prismaQuery format.
+ *
+ * Format: [modelName].action[:base64urlEncodedPayload]
+ *
+ * - Raw queries: just the action (e.g., "queryRaw", "executeRaw")
+ * - Single queries: Model.action:base64url(query)
+ * - Compacted batches: Model.action:base64url(queries)
+ */
+export declare function formatQueryInsight(queryInfo: SqlCommenterQueryInfo): string;

package/dist/index.d.mts

@@ -0,0 +1,133 @@
+declare type JsonQueryAction = 'findUnique' | 'findUniqueOrThrow' | 'findFirst' | 'findFirstOrThrow' | 'findMany' | 'createOne' | 'createMany' | 'createManyAndReturn' | 'updateOne' | 'updateMany' | 'updateManyAndReturn' | 'deleteOne' | 'deleteMany' | 'upsertOne' | 'aggregate' | 'groupBy' | 'executeRaw' | 'queryRaw' | 'runCommandRaw' | 'findRaw' | 'aggregateRaw';
+
+/**
+ * Creates a SQL commenter plugin that adds Prisma query shape information
+ * to SQL queries as `prismaQuery` comments.
+ *
+ * The query shapes are parameterized to remove user data, making them safe
+ * for logging and observability while still providing useful structural
+ * information about the queries being executed.
+ *
+ * @example
+ * ```ts
+ * import { prismaQueryInsights } from '@prisma/sqlcommenter-query-insights'
+ *
+ * const prisma = new PrismaClient({
+ *   adapter: myAdapter,
+ *   comments: [prismaQueryInsights()],
+ * })
+ * ```
+ *
+ * Output examples:
+ * - Raw query: `/*prismaQuery='queryRaw'* /`
+ * - Single query: `/*prismaQuery='User.findMany:eyJzZWxlY3Rpb24iOnsiJHNjYWxhcnMiOnRydWV9fX0'* /`
+ * - Batched queries: `/*prismaQuery='User.findUnique:W3siYXJndW1lbnRzIjp7IndoZXJlIjp7ImlkIjp7IiR0eXBlIjoiUGFyYW0ifX19fV0'* /`
+ */
+export declare function prismaQueryInsights(): SqlCommenterPlugin;
+
+/**
+ * Information about a compacted batch query (e.g. multiple independent
+ * `findUnique` queries automatically merged into a single `SELECT` SQL
+ * statement).
+ */
+declare interface SqlCommenterCompactedQueryInfo {
+    /**
+     * The model name (e.g., "User", "Post").
+     */
+    readonly modelName: string;
+    /**
+     * The Prisma operation (e.g., "findUnique").
+     */
+    readonly action: SqlCommenterQueryAction;
+    /**
+     * The full query objects (selections, arguments, etc.).
+     * Specifics of the query representation are not part of the public API yet.
+     */
+    readonly queries: ReadonlyArray<unknown>;
+}
+
+/**
+ * Context provided to SQL commenter plugins.
+ */
+declare interface SqlCommenterContext {
+    /**
+     * Information about the Prisma query being executed.
+     */
+    readonly query: SqlCommenterQueryInfo;
+    /**
+     * Raw SQL query generated from this Prisma query.
+     *
+     * It is always available when `PrismaClient` connects to the database and
+     * renders SQL queries directly.
+     *
+     * When using Prisma Accelerate, SQL rendering happens on Accelerate side and the raw
+     * SQL strings are not yet available when SQL commenter plugins are executed.
+     */
+    readonly sql?: string;
+}
+
+/**
+ * A SQL commenter plugin that returns key-value pairs to be added as comments.
+ * Return an empty object to add no comments. Keys with undefined values will be omitted.
+ *
+ * @example
+ * ```ts
+ * const myPlugin: SqlCommenterPlugin = (context) => {
+ *   return {
+ *     application: 'my-app',
+ *     model: context.query.modelName ?? 'raw',
+ *     // Conditional key - will be omitted if ctx.sql is undefined
+ *     sqlLength: context.sql ? String(context.sql.length) : undefined,
+ *   }
+ * }
+ * ```
+ */
+declare interface SqlCommenterPlugin {
+    (context: SqlCommenterContext): SqlCommenterTags;
+}
+
+/**
+ * Prisma query type corresponding to this SQL query.
+ */
+declare type SqlCommenterQueryAction = JsonQueryAction;
+
+/**
+ * Information about the query or queries being executed.
+ *
+ * - `single`: A single query is being executed
+ * - `compacted`: Multiple queries have been compacted into a single SQL statement
+ */
+declare type SqlCommenterQueryInfo = ({
+    readonly type: 'single';
+} & SqlCommenterSingleQueryInfo) | ({
+    readonly type: 'compacted';
+} & SqlCommenterCompactedQueryInfo);
+
+/**
+ * Information about a single Prisma query.
+ */
+declare interface SqlCommenterSingleQueryInfo {
+    /**
+     * The model name (e.g., "User", "Post"). Undefined for raw queries.
+     */
+    readonly modelName?: string;
+    /**
+     * The Prisma operation (e.g., "findMany", "createOne", "queryRaw").
+     */
+    readonly action: SqlCommenterQueryAction;
+    /**
+     * The full query object (selection, arguments, etc.).
+     * Specifics of the query representation are not part of the public API yet.
+     */
+    readonly query: unknown;
+}
+
+/**
+ * Key-value pairs to add as SQL comments.
+ * Keys with undefined values will be omitted from the final comment.
+ */
+declare type SqlCommenterTags = {
+    readonly [key: string]: string | undefined;
+};
+
+export { }

package/dist/index.d.ts

@@ -0,0 +1,133 @@
+declare type JsonQueryAction = 'findUnique' | 'findUniqueOrThrow' | 'findFirst' | 'findFirstOrThrow' | 'findMany' | 'createOne' | 'createMany' | 'createManyAndReturn' | 'updateOne' | 'updateMany' | 'updateManyAndReturn' | 'deleteOne' | 'deleteMany' | 'upsertOne' | 'aggregate' | 'groupBy' | 'executeRaw' | 'queryRaw' | 'runCommandRaw' | 'findRaw' | 'aggregateRaw';
+
+/**
+ * Creates a SQL commenter plugin that adds Prisma query shape information
+ * to SQL queries as `prismaQuery` comments.
+ *
+ * The query shapes are parameterized to remove user data, making them safe
+ * for logging and observability while still providing useful structural
+ * information about the queries being executed.
+ *
+ * @example
+ * ```ts
+ * import { prismaQueryInsights } from '@prisma/sqlcommenter-query-insights'
+ *
+ * const prisma = new PrismaClient({
+ *   adapter: myAdapter,
+ *   comments: [prismaQueryInsights()],
+ * })
+ * ```
+ *
+ * Output examples:
+ * - Raw query: `/*prismaQuery='queryRaw'* /`
+ * - Single query: `/*prismaQuery='User.findMany:eyJzZWxlY3Rpb24iOnsiJHNjYWxhcnMiOnRydWV9fX0'* /`
+ * - Batched queries: `/*prismaQuery='User.findUnique:W3siYXJndW1lbnRzIjp7IndoZXJlIjp7ImlkIjp7IiR0eXBlIjoiUGFyYW0ifX19fV0'* /`
+ */
+export declare function prismaQueryInsights(): SqlCommenterPlugin;
+
+/**
+ * Information about a compacted batch query (e.g. multiple independent
+ * `findUnique` queries automatically merged into a single `SELECT` SQL
+ * statement).
+ */
+declare interface SqlCommenterCompactedQueryInfo {
+    /**
+     * The model name (e.g., "User", "Post").
+     */
+    readonly modelName: string;
+    /**
+     * The Prisma operation (e.g., "findUnique").
+     */
+    readonly action: SqlCommenterQueryAction;
+    /**
+     * The full query objects (selections, arguments, etc.).
+     * Specifics of the query representation are not part of the public API yet.
+     */
+    readonly queries: ReadonlyArray<unknown>;
+}
+
+/**
+ * Context provided to SQL commenter plugins.
+ */
+declare interface SqlCommenterContext {
+    /**
+     * Information about the Prisma query being executed.
+     */
+    readonly query: SqlCommenterQueryInfo;
+    /**
+     * Raw SQL query generated from this Prisma query.
+     *
+     * It is always available when `PrismaClient` connects to the database and
+     * renders SQL queries directly.
+     *
+     * When using Prisma Accelerate, SQL rendering happens on Accelerate side and the raw
+     * SQL strings are not yet available when SQL commenter plugins are executed.
+     */
+    readonly sql?: string;
+}
+
+/**
+ * A SQL commenter plugin that returns key-value pairs to be added as comments.
+ * Return an empty object to add no comments. Keys with undefined values will be omitted.
+ *
+ * @example
+ * ```ts
+ * const myPlugin: SqlCommenterPlugin = (context) => {
+ *   return {
+ *     application: 'my-app',
+ *     model: context.query.modelName ?? 'raw',
+ *     // Conditional key - will be omitted if ctx.sql is undefined
+ *     sqlLength: context.sql ? String(context.sql.length) : undefined,
+ *   }
+ * }
+ * ```
+ */
+declare interface SqlCommenterPlugin {
+    (context: SqlCommenterContext): SqlCommenterTags;
+}
+
+/**
+ * Prisma query type corresponding to this SQL query.
+ */
+declare type SqlCommenterQueryAction = JsonQueryAction;
+
+/**
+ * Information about the query or queries being executed.
+ *
+ * - `single`: A single query is being executed
+ * - `compacted`: Multiple queries have been compacted into a single SQL statement
+ */
+declare type SqlCommenterQueryInfo = ({
+    readonly type: 'single';
+} & SqlCommenterSingleQueryInfo) | ({
+    readonly type: 'compacted';
+} & SqlCommenterCompactedQueryInfo);
+
+/**
+ * Information about a single Prisma query.
+ */
+declare interface SqlCommenterSingleQueryInfo {
+    /**
+     * The model name (e.g., "User", "Post"). Undefined for raw queries.
+     */
+    readonly modelName?: string;
+    /**
+     * The Prisma operation (e.g., "findMany", "createOne", "queryRaw").
+     */
+    readonly action: SqlCommenterQueryAction;
+    /**
+     * The full query object (selection, arguments, etc.).
+     * Specifics of the query representation are not part of the public API yet.
+     */
+    readonly query: unknown;
+}
+
+/**
+ * Key-value pairs to add as SQL comments.
+ * Keys with undefined values will be omitted from the final comment.
+ */
+declare type SqlCommenterTags = {
+    readonly [key: string]: string | undefined;
+};
+
+export { }

package/dist/index.js

@@ -0,0 +1,415 @@
+"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);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  prismaQueryInsights: () => prismaQueryInsights
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/parameterize/parameterize.ts
+var PARAM_PLACEHOLDER = { $type: "Param" };
+function isTaggedValue(value) {
+  return typeof value === "object" && value !== null && "$type" in value && typeof value.$type === "string";
+}
+function isSelectionMarker(key) {
+  return key === "$scalars" || key === "$composites";
+}
+var STRUCTURE_KEYS = /* @__PURE__ */ new Set([
+  // Selection/field specifiers
+  "select",
+  "include",
+  "omit",
+  "selection",
+  // Relation operations
+  "connect",
+  "connectOrCreate",
+  "disconnect",
+  "set",
+  "create",
+  "createMany",
+  "update",
+  "updateMany",
+  "upsert",
+  "delete",
+  "deleteMany",
+  // Query structure
+  "where",
+  "data",
+  "orderBy",
+  "cursor",
+  "distinct",
+  "relationLoadStrategy",
+  // Aggregation
+  "_count",
+  "_sum",
+  "_avg",
+  "_min",
+  "_max"
+]);
+var STRUCTURAL_VALUE_KEYS = /* @__PURE__ */ new Set([
+  // Sort directions
+  "sort",
+  // Null handling
+  "nulls",
+  // Relation load strategy
+  "relationLoadStrategy"
+]);
+var NUMERIC_STRUCTURE_KEYS = /* @__PURE__ */ new Set(["take", "skip"]);
+var FILTER_OPERATORS = /* @__PURE__ */ new Set([
+  "equals",
+  "not",
+  "in",
+  "notIn",
+  "lt",
+  "lte",
+  "gt",
+  "gte",
+  "contains",
+  "startsWith",
+  "endsWith",
+  "search",
+  "mode",
+  "has",
+  "hasEvery",
+  "hasSome",
+  "isEmpty",
+  // JSON operators
+  "path",
+  "string_contains",
+  "string_starts_with",
+  "string_ends_with",
+  "array_contains",
+  "array_starts_with",
+  "array_ends_with"
+]);
+var LOGICAL_OPERATORS = /* @__PURE__ */ new Set(["AND", "OR", "NOT", "is", "isNot", "some", "every", "none"]);
+var SORT_DIRECTIONS = /* @__PURE__ */ new Set(["asc", "desc"]);
+function parameterizeValue(value, context) {
+  if (value === null || value === void 0) {
+    return value;
+  }
+  if (isTaggedValue(value)) {
+    if (value.$type === "FieldRef") {
+      return value;
+    }
+    if (value.$type === "Enum" && context.isStructuralEnum) {
+      return value;
+    }
+    return PARAM_PLACEHOLDER;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => parameterizeValue(item, context));
+  }
+  if (typeof value === "object") {
+    return parameterizeObject(value, context);
+  }
+  if (context.isDataContext) {
+    return PARAM_PLACEHOLDER;
+  }
+  if (context.isSelectionContext && typeof value === "boolean") {
+    return value;
+  }
+  if (context.isStructuralValue) {
+    return value;
+  }
+  if (context.isOrderByContext && typeof value === "string" && SORT_DIRECTIONS.has(value)) {
+    return value;
+  }
+  return PARAM_PLACEHOLDER;
+}
+function parameterizeObject(obj, context) {
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (isSelectionMarker(key)) {
+      result[key] = value;
+      continue;
+    }
+    const newContext = getContextForKey(key, context);
+    result[key] = parameterizeValue(value, newContext);
+  }
+  return result;
+}
+function isStructuralKey(key) {
+  return key === "arguments" || STRUCTURE_KEYS.has(key);
+}
+function getContextForKey(key, parentContext) {
+  if (key === "arguments") {
+    return {
+      isDataContext: false,
+      isStructuralValue: false,
+      isStructuralEnum: false,
+      isSelectionContext: false,
+      isOrderByContext: false,
+      parentKey: key
+    };
+  }
+  if (key === "selection" || parentContext.isSelectionContext && !isStructuralKey(key)) {
+    return {
+      isDataContext: false,
+      isStructuralValue: false,
+      isStructuralEnum: false,
+      isSelectionContext: true,
+      isOrderByContext: false,
+      parentKey: key
+    };
+  }
+  if (key === "data" || parentContext.isDataContext) {
+    if (STRUCTURE_KEYS.has(key)) {
+      return {
+        isDataContext: false,
+        isStructuralValue: false,
+        isStructuralEnum: false,
+        isSelectionContext: false,
+        isOrderByContext: false,
+        parentKey: key
+      };
+    }
+    return {
+      isDataContext: true,
+      isStructuralValue: false,
+      isStructuralEnum: false,
+      isSelectionContext: false,
+      isOrderByContext: false,
+      parentKey: key
+    };
+  }
+  if (STRUCTURAL_VALUE_KEYS.has(key)) {
+    return {
+      isDataContext: false,
+      isStructuralValue: true,
+      isStructuralEnum: true,
+      isSelectionContext: false,
+      isOrderByContext: false,
+      parentKey: key
+    };
+  }
+  if (NUMERIC_STRUCTURE_KEYS.has(key)) {
+    return {
+      isDataContext: false,
+      isStructuralValue: true,
+      isStructuralEnum: false,
+      isSelectionContext: false,
+      isOrderByContext: false,
+      parentKey: key
+    };
+  }
+  if (key === "orderBy" || parentContext.isOrderByContext) {
+    return {
+      isDataContext: false,
+      isStructuralValue: false,
+      isStructuralEnum: false,
+      isSelectionContext: false,
+      isOrderByContext: true,
+      parentKey: key
+    };
+  }
+  if (FILTER_OPERATORS.has(key)) {
+    if (key === "mode") {
+      return {
+        isDataContext: false,
+        isStructuralValue: true,
+        isStructuralEnum: true,
+        isSelectionContext: false,
+        isOrderByContext: false,
+        parentKey: key
+      };
+    }
+    return {
+      isDataContext: false,
+      isStructuralValue: false,
+      isStructuralEnum: false,
+      isSelectionContext: false,
+      isOrderByContext: false,
+      parentKey: key
+    };
+  }
+  if (LOGICAL_OPERATORS.has(key)) {
+    return {
+      isDataContext: false,
+      isStructuralValue: false,
+      isStructuralEnum: false,
+      isSelectionContext: false,
+      isOrderByContext: false,
+      parentKey: key
+    };
+  }
+  if (STRUCTURE_KEYS.has(key)) {
+    return {
+      isDataContext: false,
+      isStructuralValue: false,
+      isStructuralEnum: false,
+      isSelectionContext: key === "selection",
+      isOrderByContext: false,
+      parentKey: key
+    };
+  }
+  return {
+    isDataContext: parentContext.isDataContext,
+    isStructuralValue: false,
+    isStructuralEnum: false,
+    isSelectionContext: parentContext.isSelectionContext,
+    isOrderByContext: parentContext.isOrderByContext,
+    parentKey: key
+  };
+}
+function parameterizeQuery(query) {
+  const initialContext = {
+    isDataContext: false,
+    isStructuralValue: false,
+    isStructuralEnum: false,
+    isSelectionContext: false,
+    isOrderByContext: false
+  };
+  return parameterizeValue(query, initialContext);
+}
+
+// src/shape/shape.ts
+function isNestedQuery(value) {
+  return typeof value === "object" && value !== null && ("arguments" in value || "selection" in value);
+}
+function isEmptyObject(value) {
+  return typeof value === "object" && value !== null && Object.keys(value).length === 0;
+}
+function canSimplifySelectionToTrue(selection) {
+  if (selection.$scalars !== true) {
+    return false;
+  }
+  for (const key of Object.keys(selection)) {
+    if (key !== "$scalars" && key !== "$composites") {
+      return false;
+    }
+  }
+  return true;
+}
+function canSimplifyNestedQueryToTrue(args, selection) {
+  const argsEmpty = args === void 0 || isEmptyObject(args);
+  if (!argsEmpty) {
+    return false;
+  }
+  if (!selection) {
+    return false;
+  }
+  return canSimplifySelectionToTrue(selection);
+}
+function shapeRelation(relation) {
+  if (relation === true) {
+    return true;
+  }
+  if (typeof relation !== "object" || relation === null) {
+    return relation;
+  }
+  const relationObj = relation;
+  if (isNestedQuery(relationObj)) {
+    const args = relationObj.arguments;
+    const selection = relationObj.selection;
+    if (canSimplifyNestedQueryToTrue(args, selection)) {
+      return true;
+    }
+    return shapeQuery(relationObj);
+  } else {
+    if (canSimplifySelectionToTrue(relationObj)) {
+      return true;
+    }
+    const shaped = shapeSelectionObject(relationObj);
+    return shaped || true;
+  }
+}
+function shapeSelectionObject(selection) {
+  const hasScalars = selection.$scalars === true;
+  const booleanFields = {};
+  const objectFields = {};
+  for (const [key, value] of Object.entries(selection)) {
+    if (key === "$scalars" || key === "$composites") {
+      continue;
+    }
+    if (typeof value === "boolean") {
+      booleanFields[key] = value;
+    } else if (typeof value === "object" && value !== null) {
+      objectFields[key] = value;
+    }
+  }
+  const hasBooleanFields = Object.keys(booleanFields).length > 0;
+  const hasObjectFields = Object.keys(objectFields).length > 0;
+  if (!hasBooleanFields && !hasObjectFields) {
+    return null;
+  }
+  const shapedObjects = {};
+  for (const [key, value] of Object.entries(objectFields)) {
+    shapedObjects[key] = shapeRelation(value);
+  }
+  if (hasScalars) {
+    if (!hasObjectFields) {
+      return null;
+    }
+    return { include: shapedObjects };
+  } else {
+    return { select: { ...booleanFields, ...shapedObjects } };
+  }
+}
+function shapeQuery(query) {
+  if (typeof query !== "object" || query === null) {
+    return query;
+  }
+  const queryObj = query;
+  const args = queryObj.arguments;
+  const selection = queryObj.selection;
+  const result = args ? { ...args } : {};
+  if (selection) {
+    const shaped = shapeSelectionObject(selection);
+    if (shaped) {
+      Object.assign(result, shaped);
+    }
+  }
+  return result;
+}
+
+// src/format.ts
+function toBase64Url(data) {
+  return Buffer.from(data, "utf-8").toString("base64url");
+}
+function formatQueryInsight(queryInfo) {
+  if (queryInfo.type === "single") {
+    const { modelName: modelName2, action: action2, query } = queryInfo;
+    if (!modelName2) {
+      return action2;
+    }
+    const parameterizedQuery = parameterizeQuery(query);
+    const shapedQuery = shapeQuery(parameterizedQuery);
+    const encoded2 = toBase64Url(JSON.stringify(shapedQuery));
+    return `${modelName2}.${action2}:${encoded2}`;
+  }
+  const { modelName, action, queries } = queryInfo;
+  const shapedQueries = queries.map((q) => shapeQuery(parameterizeQuery(q)));
+  const encoded = toBase64Url(JSON.stringify(shapedQueries));
+  return `${modelName}.${action}:${encoded}`;
+}
+
+// src/index.ts
+function prismaQueryInsights() {
+  return (context) => {
+    const insight = formatQueryInsight(context.query);
+    return { prismaQuery: insight };
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  prismaQueryInsights
+});

package/dist/index.mjs

@@ -0,0 +1,388 @@
+// src/parameterize/parameterize.ts
+var PARAM_PLACEHOLDER = { $type: "Param" };
+function isTaggedValue(value) {
+  return typeof value === "object" && value !== null && "$type" in value && typeof value.$type === "string";
+}
+function isSelectionMarker(key) {
+  return key === "$scalars" || key === "$composites";
+}
+var STRUCTURE_KEYS = /* @__PURE__ */ new Set([
+  // Selection/field specifiers
+  "select",
+  "include",
+  "omit",
+  "selection",
+  // Relation operations
+  "connect",
+  "connectOrCreate",
+  "disconnect",
+  "set",
+  "create",
+  "createMany",
+  "update",
+  "updateMany",
+  "upsert",
+  "delete",
+  "deleteMany",
+  // Query structure
+  "where",
+  "data",
+  "orderBy",
+  "cursor",
+  "distinct",
+  "relationLoadStrategy",
+  // Aggregation
+  "_count",
+  "_sum",
+  "_avg",
+  "_min",
+  "_max"
+]);
+var STRUCTURAL_VALUE_KEYS = /* @__PURE__ */ new Set([
+  // Sort directions
+  "sort",
+  // Null handling
+  "nulls",
+  // Relation load strategy
+  "relationLoadStrategy"
+]);
+var NUMERIC_STRUCTURE_KEYS = /* @__PURE__ */ new Set(["take", "skip"]);
+var FILTER_OPERATORS = /* @__PURE__ */ new Set([
+  "equals",
+  "not",
+  "in",
+  "notIn",
+  "lt",
+  "lte",
+  "gt",
+  "gte",
+  "contains",
+  "startsWith",
+  "endsWith",
+  "search",
+  "mode",
+  "has",
+  "hasEvery",
+  "hasSome",
+  "isEmpty",
+  // JSON operators
+  "path",
+  "string_contains",
+  "string_starts_with",
+  "string_ends_with",
+  "array_contains",
+  "array_starts_with",
+  "array_ends_with"
+]);
+var LOGICAL_OPERATORS = /* @__PURE__ */ new Set(["AND", "OR", "NOT", "is", "isNot", "some", "every", "none"]);
+var SORT_DIRECTIONS = /* @__PURE__ */ new Set(["asc", "desc"]);
+function parameterizeValue(value, context) {
+  if (value === null || value === void 0) {
+    return value;
+  }
+  if (isTaggedValue(value)) {
+    if (value.$type === "FieldRef") {
+      return value;
+    }
+    if (value.$type === "Enum" && context.isStructuralEnum) {
+      return value;
+    }
+    return PARAM_PLACEHOLDER;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => parameterizeValue(item, context));
+  }
+  if (typeof value === "object") {
+    return parameterizeObject(value, context);
+  }
+  if (context.isDataContext) {
+    return PARAM_PLACEHOLDER;
+  }
+  if (context.isSelectionContext && typeof value === "boolean") {
+    return value;
+  }
+  if (context.isStructuralValue) {
+    return value;
+  }
+  if (context.isOrderByContext && typeof value === "string" && SORT_DIRECTIONS.has(value)) {
+    return value;
+  }
+  return PARAM_PLACEHOLDER;
+}
+function parameterizeObject(obj, context) {
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (isSelectionMarker(key)) {
+      result[key] = value;
+      continue;
+    }
+    const newContext = getContextForKey(key, context);
+    result[key] = parameterizeValue(value, newContext);
+  }
+  return result;
+}
+function isStructuralKey(key) {
+  return key === "arguments" || STRUCTURE_KEYS.has(key);
+}
+function getContextForKey(key, parentContext) {
+  if (key === "arguments") {
+    return {
+      isDataContext: false,
+      isStructuralValue: false,
+      isStructuralEnum: false,
+      isSelectionContext: false,
+      isOrderByContext: false,
+      parentKey: key
+    };
+  }
+  if (key === "selection" || parentContext.isSelectionContext && !isStructuralKey(key)) {
+    return {
+      isDataContext: false,
+      isStructuralValue: false,
+      isStructuralEnum: false,
+      isSelectionContext: true,
+      isOrderByContext: false,
+      parentKey: key
+    };
+  }
+  if (key === "data" || parentContext.isDataContext) {
+    if (STRUCTURE_KEYS.has(key)) {
+      return {
+        isDataContext: false,
+        isStructuralValue: false,
+        isStructuralEnum: false,
+        isSelectionContext: false,
+        isOrderByContext: false,
+        parentKey: key
+      };
+    }
+    return {
+      isDataContext: true,
+      isStructuralValue: false,
+      isStructuralEnum: false,
+      isSelectionContext: false,
+      isOrderByContext: false,
+      parentKey: key
+    };
+  }
+  if (STRUCTURAL_VALUE_KEYS.has(key)) {
+    return {
+      isDataContext: false,
+      isStructuralValue: true,
+      isStructuralEnum: true,
+      isSelectionContext: false,
+      isOrderByContext: false,
+      parentKey: key
+    };
+  }
+  if (NUMERIC_STRUCTURE_KEYS.has(key)) {
+    return {
+      isDataContext: false,
+      isStructuralValue: true,
+      isStructuralEnum: false,
+      isSelectionContext: false,
+      isOrderByContext: false,
+      parentKey: key
+    };
+  }
+  if (key === "orderBy" || parentContext.isOrderByContext) {
+    return {
+      isDataContext: false,
+      isStructuralValue: false,
+      isStructuralEnum: false,
+      isSelectionContext: false,
+      isOrderByContext: true,
+      parentKey: key
+    };
+  }
+  if (FILTER_OPERATORS.has(key)) {
+    if (key === "mode") {
+      return {
+        isDataContext: false,
+        isStructuralValue: true,
+        isStructuralEnum: true,
+        isSelectionContext: false,
+        isOrderByContext: false,
+        parentKey: key
+      };
+    }
+    return {
+      isDataContext: false,
+      isStructuralValue: false,
+      isStructuralEnum: false,
+      isSelectionContext: false,
+      isOrderByContext: false,
+      parentKey: key
+    };
+  }
+  if (LOGICAL_OPERATORS.has(key)) {
+    return {
+      isDataContext: false,
+      isStructuralValue: false,
+      isStructuralEnum: false,
+      isSelectionContext: false,
+      isOrderByContext: false,
+      parentKey: key
+    };
+  }
+  if (STRUCTURE_KEYS.has(key)) {
+    return {
+      isDataContext: false,
+      isStructuralValue: false,
+      isStructuralEnum: false,
+      isSelectionContext: key === "selection",
+      isOrderByContext: false,
+      parentKey: key
+    };
+  }
+  return {
+    isDataContext: parentContext.isDataContext,
+    isStructuralValue: false,
+    isStructuralEnum: false,
+    isSelectionContext: parentContext.isSelectionContext,
+    isOrderByContext: parentContext.isOrderByContext,
+    parentKey: key
+  };
+}
+function parameterizeQuery(query) {
+  const initialContext = {
+    isDataContext: false,
+    isStructuralValue: false,
+    isStructuralEnum: false,
+    isSelectionContext: false,
+    isOrderByContext: false
+  };
+  return parameterizeValue(query, initialContext);
+}
+
+// src/shape/shape.ts
+function isNestedQuery(value) {
+  return typeof value === "object" && value !== null && ("arguments" in value || "selection" in value);
+}
+function isEmptyObject(value) {
+  return typeof value === "object" && value !== null && Object.keys(value).length === 0;
+}
+function canSimplifySelectionToTrue(selection) {
+  if (selection.$scalars !== true) {
+    return false;
+  }
+  for (const key of Object.keys(selection)) {
+    if (key !== "$scalars" && key !== "$composites") {
+      return false;
+    }
+  }
+  return true;
+}
+function canSimplifyNestedQueryToTrue(args, selection) {
+  const argsEmpty = args === void 0 || isEmptyObject(args);
+  if (!argsEmpty) {
+    return false;
+  }
+  if (!selection) {
+    return false;
+  }
+  return canSimplifySelectionToTrue(selection);
+}
+function shapeRelation(relation) {
+  if (relation === true) {
+    return true;
+  }
+  if (typeof relation !== "object" || relation === null) {
+    return relation;
+  }
+  const relationObj = relation;
+  if (isNestedQuery(relationObj)) {
+    const args = relationObj.arguments;
+    const selection = relationObj.selection;
+    if (canSimplifyNestedQueryToTrue(args, selection)) {
+      return true;
+    }
+    return shapeQuery(relationObj);
+  } else {
+    if (canSimplifySelectionToTrue(relationObj)) {
+      return true;
+    }
+    const shaped = shapeSelectionObject(relationObj);
+    return shaped || true;
+  }
+}
+function shapeSelectionObject(selection) {
+  const hasScalars = selection.$scalars === true;
+  const booleanFields = {};
+  const objectFields = {};
+  for (const [key, value] of Object.entries(selection)) {
+    if (key === "$scalars" || key === "$composites") {
+      continue;
+    }
+    if (typeof value === "boolean") {
+      booleanFields[key] = value;
+    } else if (typeof value === "object" && value !== null) {
+      objectFields[key] = value;
+    }
+  }
+  const hasBooleanFields = Object.keys(booleanFields).length > 0;
+  const hasObjectFields = Object.keys(objectFields).length > 0;
+  if (!hasBooleanFields && !hasObjectFields) {
+    return null;
+  }
+  const shapedObjects = {};
+  for (const [key, value] of Object.entries(objectFields)) {
+    shapedObjects[key] = shapeRelation(value);
+  }
+  if (hasScalars) {
+    if (!hasObjectFields) {
+      return null;
+    }
+    return { include: shapedObjects };
+  } else {
+    return { select: { ...booleanFields, ...shapedObjects } };
+  }
+}
+function shapeQuery(query) {
+  if (typeof query !== "object" || query === null) {
+    return query;
+  }
+  const queryObj = query;
+  const args = queryObj.arguments;
+  const selection = queryObj.selection;
+  const result = args ? { ...args } : {};
+  if (selection) {
+    const shaped = shapeSelectionObject(selection);
+    if (shaped) {
+      Object.assign(result, shaped);
+    }
+  }
+  return result;
+}
+
+// src/format.ts
+function toBase64Url(data) {
+  return Buffer.from(data, "utf-8").toString("base64url");
+}
+function formatQueryInsight(queryInfo) {
+  if (queryInfo.type === "single") {
+    const { modelName: modelName2, action: action2, query } = queryInfo;
+    if (!modelName2) {
+      return action2;
+    }
+    const parameterizedQuery = parameterizeQuery(query);
+    const shapedQuery = shapeQuery(parameterizedQuery);
+    const encoded2 = toBase64Url(JSON.stringify(shapedQuery));
+    return `${modelName2}.${action2}:${encoded2}`;
+  }
+  const { modelName, action, queries } = queryInfo;
+  const shapedQueries = queries.map((q) => shapeQuery(parameterizeQuery(q)));
+  const encoded = toBase64Url(JSON.stringify(shapedQueries));
+  return `${modelName}.${action}:${encoded}`;
+}
+
+// src/index.ts
+function prismaQueryInsights() {
+  return (context) => {
+    const insight = formatQueryInsight(context.query);
+    return { prismaQuery: insight };
+  };
+}
+export {
+  prismaQueryInsights
+};

package/dist/parameterize/parameterize.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Query parameterization logic for Prisma query insights.
+ *
+ * This module handles the conversion of Prisma queries into parameterized shapes
+ * where user data values are replaced with placeholder markers.
+ */
+/**
+ * Placeholder object used to replace parameterized values in query shapes.
+ * In the future, this may include additional fields like `value` containing
+ * param name and/or param type when queries are parameterized by the query compiler.
+ */
+export declare const PARAM_PLACEHOLDER: {
+    $type: string;
+};
+/**
+ * Parameterizes a query object, replacing all user data values with placeholders
+ */
+export declare function parameterizeQuery(query: unknown): unknown;

package/dist/parameterize.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Query parameterization logic for Prisma query insights.
+ *
+ * This module handles the conversion of Prisma queries into parameterized shapes
+ * where user data values are replaced with placeholder markers.
+ */
+/**
+ * Placeholder object used to replace parameterized values in query shapes.
+ * In the future, this may include additional fields like `value` containing
+ * param name and/or param type when queries are parameterized by the query compiler.
+ */
+export declare const PARAM_PLACEHOLDER: {
+    $type: string;
+};
+/**
+ * Parameterizes a query object, replacing all user data values with placeholders
+ */
+export declare function parameterizeQuery(query: unknown): unknown;

package/dist/shape/shape.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Query shaping logic for Prisma query insights.
+ *
+ * This module transforms JSON protocol query representations into a format
+ * that more closely resembles the original Prisma query API, making the
+ * encoded query shapes more intuitive to read and understand.
+ *
+ * Key transformations:
+ * - Move `arguments` contents one level up
+ * - Convert `selection` to `select`/`include`:
+ *   - If `$scalars: true`, use `include` for relations
+ *   - If no `$scalars`, use `select` for both scalars and relations
+ * - Simplify relation selections to `true` when possible
+ */
+/**
+ * Shapes a query object from JSON protocol format to Prisma-like format.
+ *
+ * Transforms:
+ * - `{ arguments: {...}, selection: {...} }` → `{ ..., select/include: {...} }`
+ *
+ * @param query - The query object in JSON protocol format
+ * @returns The shaped query in Prisma-like format
+ */
+export declare function shapeQuery(query: unknown): unknown;

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@prisma/sqlcommenter-query-insights",
+  "version": "0.0.1",
+  "description": "Query insights plugin for Prisma SQL commenter",
+  "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.mts",
+        "default": "./dist/index.mjs"
+      }
+    }
+  },
+  "license": "Apache-2.0",
+  "homepage": "https://www.prisma.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/prisma/prisma.git",
+    "directory": "packages/sqlcommenter-query-insights"
+  },
+  "bugs": "https://github.com/prisma/prisma/issues",
+  "scripts": {
+    "dev": "DEV=true tsx helpers/build.ts",
+    "build": "tsx helpers/build.ts",
+    "prepublishOnly": "pnpm run build",
+    "test": "vitest run"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "devDependencies": {
+    "@prisma/sqlcommenter": "workspace:*",
+    "fast-check": "4.3.0"
+  }
+}