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

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { AsyncIterableResult } from "@prisma-next/framework-components/runtime";
+import { AsyncIterableResult, createMetaBuilder } from "@prisma-next/framework-components/runtime";
 import { AggregateExpr, AndExpr, BinaryExpr, ColumnRef, DefaultValueExpr, DeleteAst, DerivedTableSource, EqColJoinOn, ExistsExpr, InsertAst, InsertOnConflict, JoinAst, JsonArrayAggExpr, JsonObjectExpr, ListExpression, LiteralExpr, NotExpr, NullCheckExpr, OrExpr, OrderByItem, ParamRef, ProjectionItem, SelectAst, SubqueryExpr, TableSource, UpdateAst, collectOrderedParamRefs, isWhereExpr } from "@prisma-next/sql-relational-core/ast";
 import { codecRefForStorageColumn } from "@prisma-next/sql-relational-core/codec-descriptor-registry";
 import { ifDefined } from "@prisma-next/utils/defined";
@@ -448,20 +448,54 @@ function resolveTableColumns(contract, tableName) {
 	if (!table) throw new Error(`Unknown table "${tableName}" in SQL ORM query planner`);
 	return Object.keys(table.columns);
 }
-function buildOrmPlanMeta(contract) {
+function buildOrmPlanMeta(contract, annotations) {
+	const annotationRecord = annotations !== void 0 && annotations.size > 0 ? Object.freeze(Object.fromEntries(annotations)) : void 0;
 	return {
 		target: contract.target,
 		targetFamily: contract.targetFamily,
 		storageHash: contract.storage.storageHash,
-		...contract.profileHash !== void 0 ? { profileHash: contract.profileHash } : {},
+		...ifDefined("profileHash", contract.profileHash),
+		...ifDefined("annotations", annotationRecord),
 		lane: "orm-client"
 	};
 }
-function buildOrmQueryPlan(contract, ast, params) {
+function buildOrmQueryPlan(contract, ast, params, annotations) {
 	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`.
+*/
+function mergeAnnotations(plan, annotations) {
+	if (annotations === void 0 || annotations.size === 0) return plan;
+	const callerEntries = {};
+	for (const [namespace, value] of annotations) callerEntries[namespace] = value;
+	const mergedAnnotations = Object.freeze({
+		...callerEntries,
+		...plan.meta.annotations ?? {}
+	});
+	return Object.freeze({
+		...plan,
+		meta: Object.freeze({
+			...plan.meta,
+			annotations: mergedAnnotations
+		})
 	});
 }
 //#endregion
@@ -967,7 +1001,7 @@ function compileSelect(contract, tableName, state, modelName) {
 		includeProjection: mtiArtifacts.projection
 	} : void 0);
 	const { params } = deriveParamsFromAst(ast);
-	return buildOrmQueryPlan(contract, ast, params);
+	return buildOrmQueryPlan(contract, ast, params, state.annotations);
 }
 function compileRelationSelect(contract, relatedTableName, targetColumn, parentPks, nestedState) {
 	const inFilter = BinaryExpr.in(ColumnRef.of(relatedTableName, targetColumn), ListExpression.fromValues(parentPks));
@@ -1006,10 +1040,10 @@ function compileSelectWithIncludeStrategy(contract, tableName, state, strategy,
 	}, {
 		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);
 }
 //#endregion
 //#region src/collection-dispatch.ts
@@ -1430,12 +1464,25 @@ var GroupedCollection = class GroupedCollection {
 			havingFilters: [...this.havingFilters, havingExpr]
 		});
 	}
-	async aggregate(fn) {
+	/**
+	* Read terminal: run a grouped aggregate query.
+	*
+	* Accepts an optional `configure` callback that receives a
+	* `MetaBuilder<'read'>` for attaching typed annotations.
+	* Annotations are merged into the compiled plan's `meta.annotations`.
+	*/
+	async aggregate(fn, configure) {
 		const aggregateSpec = fn(createAggregateBuilder(this.contract, this.modelName));
 		const aggregateEntries = Object.entries(aggregateSpec);
 		if (aggregateEntries.length === 0) throw new Error("groupBy().aggregate() requires at least one aggregation selector");
 		for (const [alias, selector] of aggregateEntries) if (!isAggregateSelector(selector)) throw new Error(`groupBy().aggregate() selector "${alias}" is invalid`);
-		const compiled = compileGroupedAggregate(this.contract, this.tableName, this.baseFilters, this.groupByColumns, aggregateSpec, combineWhereExprs(this.havingFilters));
+		let annotationsMap;
+		if (configure !== void 0) {
+			const meta = createMetaBuilder("read", "groupBy.aggregate");
+			configure(meta);
+			if (meta.annotations.size > 0) annotationsMap = meta.annotations;
+		}
+		const compiled = mergeAnnotations(compileGroupedAggregate(this.contract, this.tableName, this.baseFilters, this.groupByColumns, aggregateSpec, combineWhereExprs(this.havingFilters)), annotationsMap);
 		return (await executeQueryPlan(this.ctx.runtime, compiled).toArray()).map((row) => {
 			const mapped = mapStorageRowToModelFields(this.contract, this.modelName, row);
 			for (const [alias, selector] of aggregateEntries) mapped[alias] = coerceAggregateValue(selector.fn, row[alias]);
@@ -1555,7 +1602,8 @@ function emptyState() {
 		selectedFields: void 0,
 		limit: void 0,
 		offset: void 0,
-		variantName: void 0
+		variantName: void 0,
+		annotations: /* @__PURE__ */ new Map()
 	};
 }
 function param(codec, value) {
@@ -2310,22 +2358,69 @@ var Collection = class Collection {
 	skip(n) {
 		return this.#clone({ offset: n });
 	}
-	all() {
-		return this.#dispatch();
+	/**
+	* Read terminal: stream all rows matching the current state.
+	*
+	* Accepts an optional `configure` callback that receives a
+	* `MetaBuilder<'read'>` so the caller can attach typed user
+	* annotations to the executed plan. `meta.annotate(...)` enforces
+	* applicability at the type level and at runtime; annotations are
+	* merged into `plan.meta.annotations` at compile time.
+	*/
+	all(configure) {
+		return this.#withAnnotationsFromMeta(configure, "all").#dispatch();
 	}
-	async first(filter) {
-		return (await (filter === void 0 ? this : typeof filter === "function" ? this.where(filter) : this.where(filter)).take(1).#dispatch().toArray())[0] ?? null;
+	/**
+	* Read terminal: return the first matching row, or `null`.
+	*
+	* Accepts an optional `filter` (function or shorthand) followed by an
+	* optional `configure` callback that receives a `MetaBuilder<'read'>`
+	* for attaching typed annotations. To attach annotations without
+	* narrowing further, pass `undefined` as the filter (or chain
+	* `.where(...)` first):
+	*
+	* ```typescript
+	* await db.User.first({ id }, (meta) => meta.annotate(cacheAnnotation({ ttl: 60 })));
+	* await db.User.first(undefined, (meta) => meta.annotate(cacheAnnotation({ ttl: 60 })));
+	* ```
+	*/
+	async first(filter, configure) {
+		return (await (filter === void 0 ? this : typeof filter === "function" ? this.where(filter) : this.where(filter)).take(1).#withAnnotationsFromMeta(configure, "first").#dispatch().toArray())[0] ?? null;
 	}
-	async aggregate(fn) {
+	/**
+	* Read terminal: run an aggregate query (count, sum, avg, min, max)
+	* built via the `AggregateBuilder` callback.
+	*
+	* Accepts an optional `configure` callback that receives a
+	* `MetaBuilder<'read'>` for attaching typed annotations.
+	* Annotations are merged into the compiled plan's `meta.annotations`.
+	*/
+	async aggregate(fn, configure) {
 		const aggregateSpec = fn(createAggregateBuilder(this.contract, this.modelName));
 		const entries = Object.entries(aggregateSpec);
 		if (entries.length === 0) throw new Error("aggregate() requires at least one aggregation selector");
 		for (const [alias, selector] of entries) if (!isAggregateSelector(selector)) throw new Error(`aggregate() selector "${alias}" is invalid`);
-		const compiled = compileAggregate(this.contract, this.tableName, this.state.filters, aggregateSpec);
+		const annotationsMap = this.#collectAnnotationsFromMeta(configure, "read", "aggregate");
+		const compiled = mergeAnnotations(compileAggregate(this.contract, this.tableName, this.state.filters, aggregateSpec), annotationsMap);
 		return normalizeAggregateResult(aggregateSpec, (await executeQueryPlan(this.ctx.runtime, compiled).toArray())[0] ?? {});
 	}
-	async create(data) {
+	/**
+	* Write terminal: insert one row and return it.
+	*
+	* Accepts an optional `configure` callback that receives a
+	* `MetaBuilder<'write'>` for attaching typed annotations.
+	* Annotations are merged into the compiled mutation plan's
+	* `meta.annotations`.
+	*
+	* Note: when the input contains nested-mutation callbacks, the
+	* operation is executed as a graph of internal queries via
+	* `withMutationScope`. In that path, annotations apply to the
+	* logical `create()` call but do not currently flow into each
+	* constituent SQL statement issued for the related rows.
+	*/
+	async create(data, configure) {
 		assertReturningCapability(this.contract, "create()");
+		const annotationsMap = this.#collectAnnotationsFromMeta(configure, "write", "create");
 		if (hasNestedMutationCallbacks(this.contract, this.modelName, data)) {
 			const createdRow = await executeNestedCreateMutation({
 				context: this.ctx.context,
@@ -2338,11 +2433,14 @@ var Collection = class Collection {
 			if (!reloaded) throw new Error(`create() for model "${this.modelName}" did not return a row`);
 			return reloaded;
 		}
-		const created = (await this.createAll([data]))[0];
+		const created = (await this.#createAllWithAnnotations([data], annotationsMap))[0];
 		if (created) return created;
 		throw new Error(`create() for model "${this.modelName}" did not return a row`);
 	}
-	createAll(data) {
+	createAll(data, configure) {
+		return this.#createAllWithAnnotations(data, this.#collectAnnotationsFromMeta(configure, "write", "createAll"));
+	}
+	#createAllWithAnnotations(data, annotationsMap) {
 		if (data.length === 0) {
 			const generator = async function* () {};
 			return new AsyncIterableResult(generator());
@@ -2356,7 +2454,7 @@ var Collection = class Collection {
 		const parentJoinColumns = this.state.includes.map((include) => include.localColumn);
 		const { selectedForQuery: selectedForInsert, hiddenColumns } = augmentSelectionForJoinColumns(this.state.selectedFields, parentJoinColumns);
 		if (this.contract.capabilities?.["sql"]?.["defaultInInsert"] !== true) {
-			const plans = compileInsertReturningSplit(this.contract, this.tableName, mappedRows, selectedForInsert);
+			const plans = compileInsertReturningSplit(this.contract, this.tableName, mappedRows, selectedForInsert).map((plan) => mergeAnnotations(plan, annotationsMap));
 			return dispatchSplitMutationRows({
 				contract: this.contract,
 				runtime: this.ctx.runtime,
@@ -2367,7 +2465,7 @@ var Collection = class Collection {
 				mapRow: (mapped) => mapped
 			});
 		}
-		const compiled = compileInsertReturning(this.contract, this.tableName, mappedRows, selectedForInsert);
+		const compiled = mergeAnnotations(compileInsertReturning(this.contract, this.tableName, mappedRows, selectedForInsert), annotationsMap);
 		return dispatchMutationRows({
 			contract: this.contract,
 			runtime: this.ctx.runtime,
@@ -2470,18 +2568,19 @@ var Collection = class Collection {
 			return mapped;
 		});
 	}
-	async createCount(data) {
+	async createCount(data, configure) {
 		if (data.length === 0) return 0;
 		this.#assertNotMtiVariant("createCount()");
+		const annotationsMap = this.#collectAnnotationsFromMeta(configure, "write", "createCount");
 		const rows = data;
 		const mappedRows = this.#mapCreateRows(rows);
 		applyCreateDefaults(this.ctx, this.tableName, mappedRows);
 		if (this.contract.capabilities?.["sql"]?.["defaultInInsert"] !== true) {
-			const plans = compileInsertCountSplit(this.contract, this.tableName, mappedRows);
+			const plans = compileInsertCountSplit(this.contract, this.tableName, mappedRows).map((plan) => mergeAnnotations(plan, annotationsMap));
 			for (const plan of plans) await executeQueryPlan(this.ctx.runtime, plan).toArray();
 			return data.length;
 		}
-		const compiled = compileInsertCount(this.contract, this.tableName, mappedRows);
+		const compiled = mergeAnnotations(compileInsertCount(this.contract, this.tableName, mappedRows), annotationsMap);
 		await executeQueryPlan(this.ctx.runtime, compiled).toArray();
 		return data.length;
 	}
@@ -2490,9 +2589,10 @@ var Collection = class Collection {
 	* On conflict, `ON CONFLICT DO NOTHING RETURNING ...` may return zero rows,
 	* so this method may issue a follow-up reload query to return the existing row.
 	*/
-	async upsert(input) {
+	async upsert(input, configure) {
 		assertReturningCapability(this.contract, "upsert()");
 		this.#assertNotMtiVariant("upsert()");
+		const annotationsMap = this.#collectAnnotationsFromMeta(configure, "write", "upsert");
 		const createValues = this.#mapCreateRows([input.create])[0] ?? {};
 		applyCreateDefaults(this.ctx, this.tableName, [createValues]);
 		const updateValues = mapModelDataToStorageRow(this.contract, this.modelName, input.update);
@@ -2502,7 +2602,7 @@ var Collection = class Collection {
 		if (conflictColumns.length === 0) throw new Error(`upsert() for model "${this.modelName}" requires conflict columns`);
 		const parentJoinColumns = this.state.includes.map((include) => include.localColumn);
 		const { selectedForQuery: selectedForUpsert, hiddenColumns } = augmentSelectionForJoinColumns(this.state.selectedFields, parentJoinColumns);
-		const compiled = compileUpsertReturning(this.contract, this.tableName, createValues, updateValues, conflictColumns, selectedForUpsert);
+		const compiled = mergeAnnotations(compileUpsertReturning(this.contract, this.tableName, createValues, updateValues, conflictColumns, selectedForUpsert), annotationsMap);
 		const row = await executeMutationReturningSingleRow({
 			contract: this.contract,
 			runtime: this.ctx.runtime,
@@ -2521,8 +2621,22 @@ var Collection = class Collection {
 		}
 		throw new Error(`upsert() for model "${this.modelName}" did not return a row`);
 	}
-	async update(data) {
+	/**
+	* Write terminal: update matching rows and return the first one (or
+	* null when no row matched).
+	*
+	* Accepts an optional `configure` callback that receives a
+	* `MetaBuilder<'write'>` for attaching typed annotations.
+	*
+	* Note: when the input contains nested-mutation callbacks, the
+	* operation is executed as a graph of internal queries via
+	* `withMutationScope`. In that path, annotations apply to the logical
+	* `update()` call but do not currently flow into each constituent SQL
+	* statement issued for the related rows.
+	*/
+	async update(data, configure) {
 		assertReturningCapability(this.contract, "update()");
+		const annotationsMap = this.#collectAnnotationsFromMeta(configure, "write", "update");
 		if (hasNestedMutationCallbacks(this.contract, this.modelName, data)) {
 			const updatedRow = await executeNestedUpdateMutation({
 				context: this.ctx.context,
@@ -2539,10 +2653,13 @@ var Collection = class Collection {
 			const scoped = this.#withRuntime(scope);
 			const identityWhere = await scoped.#findFirstMatchingRowIdentityWhere();
 			if (!identityWhere) return null;
-			return (await scoped.#clone({ filters: [identityWhere] }).updateAll(data))[0] ?? null;
+			return (await scoped.#clone({ filters: [identityWhere] }).#updateAllWithAnnotations(data, annotationsMap))[0] ?? null;
 		});
 	}
-	updateAll(data) {
+	updateAll(data, configure) {
+		return this.#updateAllWithAnnotations(data, this.#collectAnnotationsFromMeta(configure, "write", "updateAll"));
+	}
+	#updateAllWithAnnotations(data, annotationsMap) {
 		assertReturningCapability(this.contract, "updateAll()");
 		const mappedData = mapModelDataToStorageRow(this.contract, this.modelName, data);
 		if (Object.keys(mappedData).length === 0) {
@@ -2552,7 +2669,7 @@ var Collection = class Collection {
 		applyUpdateDefaults(this.ctx, this.tableName, mappedData);
 		const parentJoinColumns = this.state.includes.map((include) => include.localColumn);
 		const { selectedForQuery: selectedForUpdate, hiddenColumns } = augmentSelectionForJoinColumns(this.state.selectedFields, parentJoinColumns);
-		const compiled = compileUpdateReturning(this.contract, this.tableName, mappedData, this.state.filters, selectedForUpdate);
+		const compiled = mergeAnnotations(compileUpdateReturning(this.contract, this.tableName, mappedData, this.state.filters, selectedForUpdate), annotationsMap);
 		return dispatchMutationRows({
 			contract: this.contract,
 			runtime: this.ctx.runtime,
@@ -2563,10 +2680,11 @@ var Collection = class Collection {
 			mapRow: (mapped) => mapped
 		});
 	}
-	async updateCount(data) {
+	async updateCount(data, configure) {
 		const mappedData = mapModelDataToStorageRow(this.contract, this.modelName, data);
 		if (Object.keys(mappedData).length === 0) return 0;
 		applyUpdateDefaults(this.ctx, this.tableName, mappedData);
+		const annotationsMap = this.#collectAnnotationsFromMeta(configure, "write", "updateCount");
 		const primaryKeyColumn = resolvePrimaryKeyColumn(this.contract, this.tableName);
 		const countState = {
 			...emptyState(),
@@ -2575,27 +2693,38 @@ var Collection = class Collection {
 		};
 		const countCompiled = compileSelect(this.contract, this.tableName, countState);
 		const matchingRows = await executeQueryPlan(this.ctx.runtime, countCompiled).toArray();
-		const compiled = compileUpdateCount(this.contract, this.tableName, mappedData, this.state.filters);
+		const compiled = mergeAnnotations(compileUpdateCount(this.contract, this.tableName, mappedData, this.state.filters), annotationsMap);
 		await executeQueryPlan(this.ctx.runtime, compiled).toArray();
 		return matchingRows.length;
 	}
-	async delete() {
+	/**
+	* Write terminal: delete matching rows and return the first one (or
+	* null when no row matched).
+	*
+	* Accepts an optional `configure` callback that receives a
+	* `MetaBuilder<'write'>` for attaching typed annotations.
+	*/
+	async delete(configure) {
 		assertReturningCapability(this.contract, "delete()");
+		const annotationsMap = this.#collectAnnotationsFromMeta(configure, "write", "delete");
 		return withMutationScope(this.ctx.runtime, async (scope) => {
 			const scoped = this.#withRuntime(scope);
 			const identityWhere = await scoped.#findFirstMatchingRowIdentityWhere();
 			if (!identityWhere) return null;
-			return (await scoped.#clone({ filters: [identityWhere] }).#executeDeleteReturning().toArray())[0] ?? null;
+			return (await scoped.#clone({ filters: [identityWhere] }).#executeDeleteReturning(annotationsMap).toArray())[0] ?? null;
 		});
 	}
-	deleteAll() {
+	deleteAll(configure) {
+		return this.#deleteAllWithAnnotations(this.#collectAnnotationsFromMeta(configure, "write", "deleteAll"));
+	}
+	#deleteAllWithAnnotations(annotationsMap) {
 		assertReturningCapability(this.contract, "deleteAll()");
-		return this.#executeDeleteReturning();
+		return this.#executeDeleteReturning(annotationsMap);
 	}
-	#executeDeleteReturning() {
+	#executeDeleteReturning(annotationsMap) {
 		const parentJoinColumns = this.state.includes.map((include) => include.localColumn);
 		const { selectedForQuery: selectedForDelete, hiddenColumns } = augmentSelectionForJoinColumns(this.state.selectedFields, parentJoinColumns);
-		const compiled = compileDeleteReturning(this.contract, this.tableName, this.state.filters, selectedForDelete);
+		const compiled = mergeAnnotations(compileDeleteReturning(this.contract, this.tableName, this.state.filters, selectedForDelete), annotationsMap);
 		return dispatchMutationRows({
 			contract: this.contract,
 			runtime: this.ctx.runtime,
@@ -2606,7 +2735,8 @@ var Collection = class Collection {
 			mapRow: (mapped) => mapped
 		});
 	}
-	async deleteCount() {
+	async deleteCount(configure) {
+		const annotationsMap = this.#collectAnnotationsFromMeta(configure, "write", "deleteCount");
 		const primaryKeyColumn = resolvePrimaryKeyColumn(this.contract, this.tableName);
 		const countState = {
 			...emptyState(),
@@ -2615,7 +2745,7 @@ var Collection = class Collection {
 		};
 		const countCompiled = compileSelect(this.contract, this.tableName, countState);
 		const matchingRows = await executeQueryPlan(this.ctx.runtime, countCompiled).toArray();
-		const compiled = compileDeleteCount(this.contract, this.tableName, this.state.filters);
+		const compiled = mergeAnnotations(compileDeleteCount(this.contract, this.tableName, this.state.filters), annotationsMap);
 		await executeQueryPlan(this.ctx.runtime, compiled).toArray();
 		return matchingRows.length;
 	}
@@ -2722,6 +2852,45 @@ var Collection = class Collection {
 			modelName: this.modelName
 		});
 	}
+	/**
+	* Invokes the user-supplied configurator (if any) against a freshly
+	* constructed read meta builder, and returns a clone whose
+	* `state.annotations` carries the recorded map. Used by read
+	* terminals that flow annotations through state (`all`, `first`).
+	*
+	* Returns the receiver unchanged when no configurator was supplied
+	* or when the configurator did not call `meta.annotate(...)`. The
+	* meta builder's `annotate` method enforces applicability at the
+	* type level and at runtime, so terminal code does not need to
+	* re-validate.
+	*/
+	#withAnnotationsFromMeta(configure, terminalName) {
+		if (configure === void 0) return this;
+		const meta = createMetaBuilder("read", terminalName);
+		configure(meta);
+		if (meta.annotations.size === 0) return this;
+		const next = new Map(this.state.annotations);
+		for (const [namespace, value] of meta.annotations) next.set(namespace, value);
+		return this.#clone({ annotations: next });
+	}
+	/**
+	* Invokes the user-supplied configurator (if any) against a freshly
+	* constructed meta builder of the given operation kind, and returns
+	* the recorded annotation map (or `undefined` when empty). Used by
+	* terminals where annotations don't flow through `state` — the
+	* compiled plan is post-wrapped via `mergeAnnotations` instead.
+	* Read terminals `all` and `first` populate `state.annotations`
+	* via `#withAnnotationsFromMeta` instead; `aggregate` uses this
+	* post-wrap path because its compile function doesn't take `state`.
+	* The meta builder's `annotate` method enforces applicability at the
+	* type level and at runtime.
+	*/
+	#collectAnnotationsFromMeta(configure, kind, terminalName) {
+		if (configure === void 0) return;
+		const meta = createMetaBuilder(kind, terminalName);
+		configure(meta);
+		return meta.annotations.size === 0 ? void 0 : meta.annotations;
+	}
 };
 //#endregion
 //#region src/orm.ts