@prisma-next/sql-orm-client 0.7.0 → 0.8.0

package/src/query-plan-meta.ts

@@ -1,7 +1,9 @@
 import type { Contract, PlanMeta } from '@prisma-next/contract/types';
+import type { AnnotationValue, OperationKind } from '@prisma-next/framework-components/runtime';
 import type { SqlStorage } from '@prisma-next/sql-contract/types';
 import { type AnyQueryAst, collectOrderedParamRefs } from '@prisma-next/sql-relational-core/ast';
 import type { SqlQueryPlan } from '@prisma-next/sql-relational-core/plan';
+import { ifDefined } from '@prisma-next/utils/defined';
 
 export function deriveParamsFromAst(ast: AnyQueryAst): {
   params: unknown[];
@@ -19,12 +21,20 @@ export function resolveTableColumns(contract: Contract<SqlStorage>, tableName: s
   return Object.keys(table.columns);
 }
 
-export function buildOrmPlanMeta(contract: Contract<SqlStorage>): PlanMeta {
+export function buildOrmPlanMeta(
+  contract: Contract<SqlStorage>,
+  annotations?: ReadonlyMap<string, AnnotationValue<unknown, OperationKind>>,
+): PlanMeta {
+  const annotationRecord =
+    annotations !== undefined && annotations.size > 0
+      ? Object.freeze(Object.fromEntries(annotations))
+      : undefined;
   return {
     target: contract.target,
     targetFamily: contract.targetFamily,
     storageHash: contract.storage.storageHash,
-    ...(contract.profileHash !== undefined ? { profileHash: contract.profileHash } : {}),
+    ...ifDefined('profileHash', contract.profileHash),
+    ...ifDefined('annotations', annotationRecord),
     lane: 'orm-client',
   };
 }
@@ -33,10 +43,54 @@ export function buildOrmQueryPlan<Row>(
   contract: Contract<SqlStorage>,
   ast: AnyQueryAst,
   params: readonly unknown[],
+  annotations?: ReadonlyMap<string, AnnotationValue<unknown, OperationKind>>,
 ): SqlQueryPlan<Row> {
   return Object.freeze({
     ast,
     params: [...params],
-    meta: buildOrmPlanMeta(contract),
+    meta: buildOrmPlanMeta(contract, annotations),
+  });
+}
+
+/**
+ * Merges annotations into an existing `SqlQueryPlan`'s
+ * `meta.annotations` and returns a new frozen plan.
+ *
+ * Used by the ORM dispatch path to attach terminal-call annotations to
+ * plans produced by mutation compile functions (which don't take
+ * annotations as parameters). Reads compile through `compileSelect`-
+ * family functions that pass `state.annotations` directly to
+ * `buildOrmQueryPlan`; this helper is the alternate path for write
+ * terminals where annotations arrive at the call site, not via state.
+ *
+ * Returns the input plan unchanged when `annotations` is undefined
+ * or empty. Reserved framework namespaces (`codecs`, `limit`) on the
+ * input plan win over caller-supplied entries under the same key —
+ * see the reserved-namespace policy on `defineAnnotation`.
+ */
+export function mergeAnnotations<Row>(
+  plan: SqlQueryPlan<Row>,
+  annotations: ReadonlyMap<string, AnnotationValue<unknown, OperationKind>> | undefined,
+): SqlQueryPlan<Row> {
+  if (annotations === undefined || annotations.size === 0) {
+    return plan;
+  }
+  const callerEntries: Record<string, AnnotationValue<unknown, OperationKind>> = {};
+  for (const [namespace, value] of annotations) {
+    callerEntries[namespace] = value;
+  }
+  // Caller-supplied annotations go first so framework-reserved keys on
+  // the existing plan (codecs, limit) override any collision under the
+  // same namespace.
+  const mergedAnnotations = Object.freeze({
+    ...callerEntries,
+    ...(plan.meta.annotations ?? {}),
+  });
+  return Object.freeze({
+    ...plan,
+    meta: Object.freeze({
+      ...plan.meta,
+      annotations: mergedAnnotations,
+    }),
   });
 }

package/src/query-plan-select.ts

@@ -23,6 +23,7 @@ import {
 } from '@prisma-next/sql-relational-core/ast';
 import { codecRefForStorageColumn } from '@prisma-next/sql-relational-core/codec-descriptor-registry';
 import type { SqlQueryPlan } from '@prisma-next/sql-relational-core/plan';
+import { ifDefined } from '@prisma-next/utils/defined';
 import {
   type PolymorphismInfo,
   resolvePolymorphismInfo,
@@ -451,7 +452,7 @@ export function compileSelect(
   );
 
   const { params } = deriveParamsFromAst(ast);
-  return buildOrmQueryPlan(contract, ast, params);
+  return buildOrmQueryPlan(contract, ast, params, state.annotations);
 }
 
 export function compileRelationSelect(
@@ -522,10 +523,10 @@ export function compileSelectWithIncludeStrategy(
     {
       joins: includeJoins,
       includeProjection,
-      ...(topLevelWhere ? { where: topLevelWhere } : {}),
+      ...ifDefined('where', topLevelWhere),
     },
   );
 
   const { params } = deriveParamsFromAst(ast);
-  return buildOrmQueryPlan(contract, ast, params);
+  return buildOrmQueryPlan(contract, ast, params, state.annotations);
 }

package/src/query-plan.ts

@@ -2,6 +2,7 @@ export {
   compileAggregate,
   compileGroupedAggregate,
 } from './query-plan-aggregate';
+export { mergeAnnotations } from './query-plan-meta';
 export {
   compileDeleteCount,
   compileDeleteReturning,

package/src/types.ts

@@ -1,4 +1,5 @@
 import type { Contract } from '@prisma-next/contract/types';
+import type { AnnotationValue, OperationKind } from '@prisma-next/framework-components/runtime';
 import type {
   ExtractCodecTypes,
   ExtractQueryOperationTypes,
@@ -72,6 +73,14 @@ export interface CollectionState {
   readonly limit: number | undefined;
   readonly offset: number | undefined;
   readonly variantName: string | undefined;
+  /**
+   * Annotations attached to this query at terminal-call time.
+   * Populated transiently by terminal methods (`first`, `all`, `create`,
+   * etc.) just before dispatch — `Collection` itself has no chainable
+   * `.annotate()`. Stored as a `Map<namespace, AnnotationValue>` so
+   * duplicate namespaces last-write-win. Empty on a fresh state.
+   */
+  readonly annotations: ReadonlyMap<string, AnnotationValue<unknown, OperationKind>>;
 }
 
 export function emptyState(): CollectionState {
@@ -86,6 +95,7 @@ export function emptyState(): CollectionState {
     limit: undefined,
     offset: undefined,
     variantName: undefined,
+    annotations: new Map(),
   };
 }