@prisma/orm-family-sql 8.0.0-rc.14-dev.42 → 8.0.0-rc.14-dev.44

package/dist/orm-client.mjs

@@ -1,9 +1,9 @@
 import { t as resolveStorageTable } from "./resolve-storage-table-DZsfnzeW.mjs";
 import { i as isUniqueConstraintViolation } from "./dist-x6jvtkKM.mjs";
-import { A as ParamRef, C as LiteralExpr, E as NullCheckExpr, F as SelectAst, H as isAggregateFn, I as SubqueryExpr, K as isWhereExpr, L as TableSource, M as ProjectionItem, O as OrExpr, R as UpdateAst, S as ListExpression, T as NotExpr, W as isOrderByNulls, _ as InsertAst, b as JsonArrayAggExpr, c as DeleteAst, f as EqColJoinOn, k as OrderByItem, l as DerivedTableSource, n as AndExpr, o as ColumnRef, p as ExistsExpr, r as BinaryExpr, s as DefaultValueExpr, t as AggregateExpr, v as InsertOnConflict, x as JsonObjectExpr, y as JoinAst, z as WindowFuncExpr } from "./types-C9UR53Lv-BF-_alNk.mjs";
+import { A as ParamRef, C as LiteralExpr, E as NullCheckExpr, F as SelectAst, G as isOrderByNulls, I as SubqueryExpr, L as TableSource, M as ProjectionItem, O as OrExpr, R as UpdateAst, S as ListExpression, T as NotExpr, U as isAggregateFn, V as checkLimitOffset, W as isOrderByDirection, _ as InsertAst, b as JsonArrayAggExpr, c as DeleteAst, f as EqColJoinOn, k as OrderByItem, l as DerivedTableSource, n as AndExpr, o as ColumnRef, p as ExistsExpr, q as isWhereExpr, r as BinaryExpr, s as DefaultValueExpr, t as AggregateExpr, v as InsertOnConflict, x as JsonObjectExpr, y as JoinAst, z as WindowFuncExpr } from "./types-NTQsD2MS-DAP2yVDn.mjs";
 import { t as collectOrderedParamRefs } from "./util-BBgcP3gI-XJBkxo1K.mjs";
-import { n as JsonDocumentProjection, r as NativeJsonValueProjection, t as CodecJsonValueProjection } from "./ast-DOubq2En.mjs";
-import { i as isExpression, o as toExpr } from "./expression-gmLQa4Ie.mjs";
+import { n as JsonDocumentProjection, r as NativeJsonValueProjection, t as CodecJsonValueProjection } from "./ast-DFvrXEbF.mjs";
+import { i as isExpression, o as toExpr } from "./expression-JOe6lo4g.mjs";
 import { n as codecRefForStorageColumn } from "./codec-descriptor-registry-DoGFktu5.mjs";
 import { structuredError } from "@prisma/orm-framework/utils/structured-error";
 import { blindCast, castAs } from "@prisma/orm-framework/utils/casts";
@@ -589,6 +589,15 @@ function mapResultRows(result, mapper) {
 	};
 	return new AsyncIterableResult(generator());
 }
+function resolveColumn(contract, namespaceId, tableName, columnName) {
+	return resolveTableForContract(contract, namespaceId, tableName)?.table.columns[columnName];
+}
+function codecTraits(context, codecId) {
+	return context.codecDescriptors.descriptorFor(codecId)?.traits ?? [];
+}
+function hasTrait(context, codecId, trait) {
+	return codecTraits(context, codecId).includes(trait);
+}
 /**
 * A keyset needs a cursor value for every order axis, so each active order must be a plain column without null placement.
 */
@@ -2440,7 +2449,7 @@ function resolveIncludedColumnBinding(contract, context, include, key) {
 	};
 }
 function resolveIncludedColumnRef(contract, include, key) {
-	const baseColumn = resolveStorageColumn(contract, include.relatedNamespaceId, include.relatedTableName, key);
+	const baseColumn = resolveColumn(contract, include.relatedNamespaceId, include.relatedTableName, key);
 	if (baseColumn) return {
 		table: include.relatedTableName,
 		column: key,
@@ -2452,7 +2461,7 @@ function resolveIncludedColumnRef(contract, include, key) {
 		const prefix = `${variant.table}__`;
 		if (!key.startsWith(prefix)) continue;
 		const column = key.slice(prefix.length);
-		const variantColumn = resolveStorageColumn(contract, include.relatedNamespaceId, variant.table, column);
+		const variantColumn = resolveColumn(contract, include.relatedNamespaceId, variant.table, column);
 		if (variantColumn) return {
 			table: variant.table,
 			column,
@@ -2460,9 +2469,6 @@ function resolveIncludedColumnRef(contract, include, key) {
 		};
 	}
 }
-function resolveStorageColumn(contract, namespaceId, tableName, columnName) {
-	return contract.storage.namespaces[namespaceId]?.entries.table?.[tableName]?.columns[columnName];
-}
 function decodeIncludedColumnValue(ref, codecId, codec, value) {
 	if (ref.storageColumn.many !== false) {
 		if (!Array.isArray(value)) wrapIncludedDecodeFailure(/* @__PURE__ */ new TypeError(`expected an array from the driver for many-typed column, got ${typeof value}`), ref, codecId);
@@ -2737,7 +2743,7 @@ function shorthandToWhereExpr(context, namespaceId, modelName, filters) {
 function assertFieldHasEqualityTrait(context, namespaceId, modelName, fieldName) {
 	const fieldType = modelOf(context.contract, namespaceId, modelName)?.fields?.[fieldName]?.type;
 	const codecId = fieldType?.kind === "scalar" ? fieldType.codecId : void 0;
-	if (!(codecId ? context.codecDescriptors.descriptorFor(codecId)?.traits ?? [] : []).includes("equality")) throw ormError("ORM.FILTER_UNSUPPORTED", `Shorthand filter on "${modelName}.${fieldName}": field does not support equality comparisons`, { meta: {
+	if (codecId === void 0 || !hasTrait(context, codecId, "equality")) throw ormError("ORM.FILTER_UNSUPPORTED", `Shorthand filter on "${modelName}.${fieldName}": field does not support equality comparisons`, { meta: {
 		model: modelName,
 		field: fieldName,
 		trait: "equality"
@@ -2874,26 +2880,12 @@ function createModelAccessorInScope(context, namespaceId, modelName, variantName
 		const columnName = variantField?.column ?? fieldToColumn[prop] ?? prop;
 		const column = resolveColumn(contract, namespaceId, resolvedTable, columnName);
 		if (!column) return;
-		const traits = context.codecDescriptors.descriptorFor(column.codecId)?.traits ?? [];
+		const traits = codecTraits(context, column.codecId);
 		const operations = opsByCodecId.get(column.codecId) ?? [];
 		const codec = codecRefForStorageColumn(contract.storage, namespaceId, resolvedTable, columnName);
 		return createScalarFieldAccessor(fieldBinding, columnName, column.codecId, column.nullable, codec, traits, operations, context);
 	} }));
 }
-function resolveColumn(contract, namespaceId, tableName, columnName) {
-	let table;
-	try {
-		table = storageTableForContract(contract, namespaceId, tableName);
-	} catch {
-		return;
-	}
-	const column = table.columns[columnName];
-	if (!column) return void 0;
-	return {
-		codecId: column.codecId,
-		nullable: column.nullable
-	};
-}
 function createScalarFieldAccessor(tableBinding, columnName, codecId, nullable, codec, traits, operations, context) {
 	const column = tableBinding.column(columnName);
 	const comparisonEntries = [];
@@ -2917,7 +2909,7 @@ function createExtensionMethodFactory(selfExpr, entry, context) {
 	return (...args) => {
 		const result = blindCast(entry.impl)(selfExpr, ...args);
 		const returnCodecId = result.returnType.codecId;
-		const returnTraits = context.codecDescriptors.descriptorFor(returnCodecId)?.traits ?? [];
+		const returnTraits = codecTraits(context, returnCodecId);
 		if (returnTraits.includes("boolean")) return result.buildAst();
 		const resultAst = result.buildAst();
 		const returnCodec = { codecId: returnCodecId };
@@ -2972,9 +2964,6 @@ function relatedOrderableField(context, relation, relatedTableName, correlate, f
 		return SubqueryExpr.of(rows.source.withProjection([ProjectionItem.of(columnName, rows.childScope.current.column(columnName))]).withWhere(rows.correlation));
 	});
 }
-function hasTrait(context, codecId, trait) {
-	return (context.codecDescriptors.descriptorFor(codecId)?.traits ?? []).includes(trait);
-}
 function buildRelationCountExpr(context, relation, rows, predicate) {
 	const childWhere = toRelationWhereExpr(context, relation.toNamespace, relation.to, predicate, rows.childScope);
 	return SubqueryExpr.of(rows.source.withProjection([ProjectionItem.of("count", plainAggregateExpr("count", void 0))]).withWhere(childWhere ? and(rows.correlation, childWhere) : rows.correlation));
@@ -3847,6 +3836,303 @@ function getRelationDefinitions(contract, namespaceId, modelName) {
 function toFieldName(contract, namespaceId, modelName, columnName) {
 	return getColumnToFieldMap(contract, namespaceId, modelName)[columnName] ?? columnName;
 }
+function nullability(nullable) {
+	return nullable ? "may be null" : "is never null";
+}
+function isFieldBuilder(value) {
+	return "build" in value && typeof value.build === "function";
+}
+function isListMultiplicity(value) {
+	return typeof value === "object" && value !== null && "elementNullable" in value && typeof value.elementNullable === "boolean";
+}
+function isMultiplicity(value) {
+	return value === void 0 || value === false || isListMultiplicity(value);
+}
+function isFieldSpec(value) {
+	return "codecId" in value && typeof value.codecId === "string" && "nullable" in value && typeof value.nullable === "boolean" && (!("many" in value) || isMultiplicity(value.many));
+}
+function multiplicity(many) {
+	return isListMultiplicity(many) ? { elementNullable: many.elementNullable } : false;
+}
+const FIELD_DECLARATION_FIX = "Declare each field with a field builder, such as field.temporal.timestamptz().optional(), or with { codecId, nullable }. Declare a list with .many() or many: { elementNullable: false }, or, when its elements may be null, with .many({ elementsNullable: true }) or many: { elementNullable: true }.";
+function declaredFieldSpec(name, declaration) {
+	if (typeof declaration === "object" && declaration !== null && isFieldBuilder(declaration)) {
+		const built = declaration.build();
+		const descriptor = typeof built === "object" && built !== null && "descriptor" in built ? built.descriptor : void 0;
+		const nullable = typeof built === "object" && built !== null && "nullable" in built ? built.nullable : void 0;
+		if (typeof descriptor !== "object" || descriptor === null || !("codecId" in descriptor) || typeof descriptor.codecId !== "string" || typeof nullable !== "boolean") throw ormError("ORM.ARGUMENT_INVALID", `Cannot define the scope: the field builder for ${name} names no column type`, {
+			why: "A scope for any model matches each declared field by its codec and nullability, and this builder refers to a named type instead of a column type.",
+			fix: "Declare the field with a builder that has a column type, such as field.text() or field.column(textColumn), or with { codecId, nullable }.",
+			meta: { field: name }
+		});
+		const many = typeof built === "object" && built !== null && "many" in built && built.many;
+		if (!isMultiplicity(many)) throw ormError("ORM.ARGUMENT_INVALID", `Cannot define the scope: the field builder for ${name} builds a many that is not false or { elementNullable }`, {
+			why: `A field builder's build() returns many as false or undefined for one value, or as { elementNullable } with a boolean elementNullable for a list; received ${describeReceived(many)} for ${name}.`,
+			fix: FIELD_DECLARATION_FIX,
+			meta: { field: name }
+		});
+		return {
+			codecId: descriptor.codecId,
+			nullable,
+			many: multiplicity(many)
+		};
+	}
+	if (typeof declaration === "object" && declaration !== null && isFieldSpec(declaration)) return {
+		codecId: declaration.codecId,
+		nullable: declaration.nullable,
+		many: multiplicity(declaration.many)
+	};
+	throw ormError("ORM.ARGUMENT_INVALID", `Cannot define the scope: the declaration of field ${name} is not a field builder or { codecId, nullable }`, {
+		why: `Each field of a scope is declared with a field builder or with an object that has a string codecId, a boolean nullable and, for a list, many: { elementNullable } with a boolean elementNullable; received ${describeReceived(declaration)} for ${name}.`,
+		fix: FIELD_DECLARATION_FIX,
+		meta: { field: name }
+	});
+}
+function declaredFieldSpecs(declarations) {
+	if (typeof declarations !== "object" || declarations === null || Array.isArray(declarations)) throw ormError("ORM.ARGUMENT_INVALID", "Cannot define the scope: the fields are not an object", {
+		why: `The first argument of scope maps the name of each field the scope needs to its declaration; received ${describeReceived(declarations)}.`,
+		fix: FIELD_DECLARATION_FIX,
+		meta: { argument: "fields" }
+	});
+	return Object.entries(declarations).map(([name, declaration]) => [name, declaredFieldSpec(name, declaration)]);
+}
+/** Throws `ORM.ARGUMENT_INVALID` unless `body`, the body of a scope, is a function. */
+function assertScopeBody(body) {
+	if (typeof body !== "function") throw ormError("ORM.ARGUMENT_INVALID", "Cannot define the scope: the body is not a function", {
+		why: `The body of a scope is a function that receives a collection and returns one; received ${describeReceived(body)}.`,
+		fix: "Pass a function, such as (rows) => rows.where(...).",
+		meta: { argument: "body" }
+	});
+}
+function hasContract(ctx) {
+	return "context" in ctx && typeof ctx.context === "object" && ctx.context !== null && "contract" in ctx.context && typeof ctx.context.contract === "object" && ctx.context.contract !== null;
+}
+function isModelCollection(value) {
+	return typeof value === "object" && value !== null && "ctx" in value && typeof value.ctx === "object" && value.ctx !== null && hasContract(value.ctx) && "modelName" in value && typeof value.modelName === "string" && "namespaceId" in value && typeof value.namespaceId === "string";
+}
+/** Throws `ORM.ARGUMENT_INVALID` unless `value`, what a scope is applied to, is a collection. */
+function assertScopeReceiver(value) {
+	if (!isModelCollection(value)) throw ormError("ORM.ARGUMENT_INVALID", "Cannot apply the scope: it was not given a collection", {
+		why: `A scope is applied to a collection, such as db.orm.public.Post; received ${describeReceived(value)}.`,
+		fix: "Run the scope with apply on a collection: collection.apply(scope).",
+		meta: { argument: "collection" }
+	});
+}
+/** Throws `ORM.ARGUMENT_INVALID` unless `value` is a collection of the model and namespace a scope for one model was made from. */
+function assertModelScopeReceiver(source, value) {
+	assertScopeReceiver(value);
+	if (value.modelName !== source.modelName || value.namespaceId !== source.namespaceId) {
+		const made = `${source.namespaceId}.${source.modelName}`;
+		const given = `${value.namespaceId}.${value.modelName}`;
+		throw ormError("ORM.ARGUMENT_INVALID", `Cannot apply a scope for ${made} to a collection of ${given}`, {
+			why: `The scope was made with ${made}.scope(...), and its body was written for that model.`,
+			fix: `Apply the scope to a collection of ${made}, or make a scope from ${given}.`,
+			meta: {
+				model: source.modelName,
+				namespace: source.namespaceId,
+				receivedModel: value.modelName,
+				receivedNamespace: value.namespaceId
+			}
+		});
+	}
+}
+/** The model as error messages name it: with its namespace when the contract has more than one. */
+function modelLabel(collection) {
+	return Object.keys(collection.ctx.context.contract.domain.namespaces).length > 1 ? `${collection.namespaceId}.${collection.modelName}` : collection.modelName;
+}
+/** Throws `ORM.ARGUMENT_INVALID` unless `result`, what a scope's body returned, is a collection of the receiver's model, namespace and class. */
+function assertScopeResult(receiver, result) {
+	if (!(isModelCollection(result) && result.modelName === receiver.modelName && result.namespaceId === receiver.namespaceId && result instanceof receiver.constructor)) {
+		const label = modelLabel(receiver);
+		throw ormError("ORM.ARGUMENT_INVALID", `Cannot apply the scope to ${label}: its body did not return a collection of ${label}`, {
+			why: `The body of a scope for any model returns the collection it received, after where, orderBy, limit or offset; it returned ${isModelCollection(result) ? `a collection of ${modelLabel(result)}` : describeReceived(result)}.`,
+			fix: "Return the collection the body receives, or one made from it by calling its methods.",
+			meta: {
+				model: receiver.modelName,
+				namespace: receiver.namespaceId,
+				returned: isModelCollection(result) ? result.modelName : describeReceived(result)
+			}
+		});
+	}
+}
+function elementNullability(elementNullable) {
+	return elementNullable ? "may be null" : "are never null";
+}
+function sameMultiplicity(a, b) {
+	return a === false || b === false ? a === b : a.elementNullable === b.elementNullable;
+}
+function fieldShape(many) {
+	return many === false ? "holds one value" : `is a list whose elements ${elementNullability(many.elementNullable)}`;
+}
+function declarationFor(many) {
+	if (many === false) return "as one value, without .many() or many";
+	return many.elementNullable ? "as a list whose elements may be null, with .many({ elementsNullable: true }) or many: { elementNullable: true }" : "as a list whose elements are never null, with .many() or many: { elementNullable: false }";
+}
+function describeField(field) {
+	const value = `with codec ${field.codecId} that ${nullability(field.nullable)}`;
+	return field.many === false ? value : `${value} and whose elements ${elementNullability(field.many.elementNullable)}`;
+}
+function assertScopeFields(collection, fields) {
+	const { contract } = collection.ctx.context;
+	const { modelName, namespaceId } = collection;
+	const label = modelLabel(collection);
+	const model = modelOf(contract, namespaceId, modelName);
+	for (const [name, spec] of fields) {
+		const declared = `The scope was declared for models that have a ${spec.many === false ? "field" : "list field"} ${name} ${describeField(spec)}.`;
+		const meta = {
+			model: modelName,
+			namespace: namespaceId,
+			field: name,
+			codecId: spec.codecId,
+			nullable: spec.nullable,
+			many: spec.many
+		};
+		const modelFields = model?.fields ?? {};
+		if (!Object.hasOwn(modelFields, name)) throw ormError("ORM.FIELD_UNKNOWN", `Cannot apply a scope to ${label}: it has no field ${name}`, {
+			why: declared,
+			fix: `Apply the scope to a model that has a field ${name}, or remove ${name} from the declaration in the scope.`,
+			meta
+		});
+		const fieldMany = multiplicity(modelFields[name]?.many);
+		const column = resolveColumn(contract, namespaceId, collection.tableName, resolveFieldToColumn(contract, namespaceId, modelName, name));
+		const actual = column === void 0 ? `${label}.${name} has no column.` : fieldMany === false ? `${label}.${name} has codec ${column.codecId} and ${nullability(column.nullable)}.` : `${label}.${name} is a list ${describeField({
+			codecId: column.codecId,
+			nullable: column.nullable,
+			many: fieldMany
+		})}.`;
+		const sameCodecAndNullability = column?.codecId === spec.codecId && column.nullable === spec.nullable;
+		if (!sameCodecAndNullability || !sameMultiplicity(fieldMany, spec.many)) throw ormError("ORM.FIELD_UNKNOWN", `Cannot apply a scope to ${label}: its field ${name} does not match the declaration`, {
+			why: `${declared} ${actual}`,
+			fix: sameCodecAndNullability ? `Apply the scope to a model whose ${name} field ${fieldShape(spec.many)}, or declare ${name} ${declarationFor(fieldMany)}.` : `Apply the scope to a model whose ${name} field has that codec and nullability, or change the declaration in the scope.`,
+			meta
+		});
+	}
+}
+/**
+* Define a scope for any model that has the declared fields. Reached as the `scope` method of the client `orm()` returns.
+*/
+function defineFieldScope(declarations, body) {
+	const fields = declaredFieldSpecs(declarations);
+	assertScopeBody(body);
+	return blindCast((collection) => {
+		const receiver = collection;
+		assertScopeReceiver(receiver);
+		assertScopeFields(receiver, fields);
+		const result = body(blindCast(collection));
+		assertScopeResult(receiver, result);
+		return result;
+	});
+}
+const SHOWN_LENGTH = 64;
+function shown(value) {
+	const characters = Array.from(value);
+	const cut = characters.length > SHOWN_LENGTH;
+	return {
+		text: JSON.stringify(cut ? `${characters.slice(0, SHOWN_LENGTH).join("")}…` : value),
+		cut
+	};
+}
+function describeReceived(value) {
+	if (value === void 0 || value === null) return String(value);
+	if (Array.isArray(value)) return "an array";
+	const kind = typeof value;
+	return kind === "object" ? "an object" : `a ${kind}`;
+}
+function cutNote(subject, value) {
+	return value.cut ? ` The ${subject} above is cut to its first ${SHOWN_LENGTH} characters.` : "";
+}
+function fieldCodecId(collection, field) {
+	const { contract } = collection.ctx.context;
+	const column = resolveFieldToColumn(contract, collection.namespaceId, collection.modelName, field);
+	return resolveColumn(contract, collection.namespaceId, collection.tableName, column)?.codecId;
+}
+function canOrder(collection, field) {
+	const codecId = fieldCodecId(collection, field);
+	return codecId !== void 0 && hasTrait(collection.ctx.context, codecId, "order");
+}
+function orderableFieldNames(collection) {
+	const model = modelOf(collection.ctx.context.contract, collection.namespaceId, collection.modelName);
+	return Object.keys(model?.fields ?? {}).filter((field) => canOrder(collection, field));
+}
+function whyNotOrderable(collection, name) {
+	const { modelName } = collection;
+	const model = modelOf(collection.ctx.context.contract, collection.namespaceId, modelName);
+	const quoted = shown(name).text;
+	if (Object.hasOwn(model?.relations ?? {}, name)) return `${quoted} is a relation of ${modelName}, not a field.`;
+	if (!Object.hasOwn(model?.fields ?? {}, name)) return `${modelName} has no field ${quoted}.`;
+	return canOrder(collection, name) ? `${quoted} is not one of the fields allowed for ordering.` : `The codec ${fieldCodecId(collection, name)} of ${modelName}.${name} cannot be ordered.`;
+}
+/**
+* An `orderBy` selector for a field named by a string, such as an order parameter of a request. `allowed` lists the fields a request may order by. A name that is not in `allowed` or not an orderable field of the collection's model, and a direction other than `asc` or `desc`, throw `ORM.ARGUMENT_INVALID`. An undefined direction is `asc`.
+*
+* ```ts
+* db.Post.orderBy(orderByField(db.Post, input.orderBy, input.direction, ['title', 'createdAt']));
+* ```
+*/
+function orderByField(collection, name, direction, allowed) {
+	const receiver = collection;
+	if (!isModelCollection(receiver)) throw ormError("ORM.ARGUMENT_INVALID", "Cannot order: orderByField was not given a collection", {
+		why: `orderByField takes the collection it orders, such as db.orm.public.Post; received ${describeReceived(receiver)}.`,
+		fix: "Pass the collection the selector is for as the first argument.",
+		meta: { argument: "collection" }
+	});
+	const { modelName } = collection;
+	const requestedName = name;
+	const requestedDirection = direction === void 0 ? "asc" : direction;
+	const allowedList = allowed;
+	if (!Array.isArray(allowedList) || allowedList.some((field) => typeof field !== "string")) throw ormError("ORM.ARGUMENT_INVALID", `Cannot order ${modelName}: the allowed fields are not a list of names`, {
+		why: `orderByField takes the list of fields a request may order by; received ${describeReceived(allowedList)}.`,
+		fix: `Pass an array of field names of ${modelName}, such as ['title', 'createdAt'].`,
+		meta: {
+			model: modelName,
+			argument: "allowed"
+		}
+	});
+	if (typeof requestedDirection !== "string") throw ormError("ORM.ARGUMENT_INVALID", `Cannot order ${modelName}: the direction is not a string`, {
+		why: `An order direction is "asc" or "desc"; received ${describeReceived(requestedDirection)}.`,
+		fix: "Pass \"asc\" or \"desc\".",
+		meta: {
+			model: modelName,
+			direction: requestedDirection
+		}
+	});
+	if (!isOrderByDirection(requestedDirection)) {
+		const shownDirection = shown(requestedDirection);
+		throw ormError("ORM.ARGUMENT_INVALID", `Cannot order ${modelName} in direction ${shownDirection.text}`, {
+			why: "An order direction is \"asc\" or \"desc\".",
+			fix: `Pass "asc" or "desc".${cutNote("direction", shownDirection)}`,
+			meta: {
+				model: modelName,
+				direction: requestedDirection
+			}
+		});
+	}
+	const orderable = orderableFieldNames(collection);
+	const names = allowedList.filter((field) => orderable.includes(field));
+	const orderByOneOf = names.length === 0 ? `Pass an allowed list that names at least one field of ${modelName} that can be ordered.` : `Order by one of: ${names.join(", ")}.`;
+	if (typeof requestedName !== "string") throw ormError("ORM.ARGUMENT_INVALID", `Cannot order ${modelName}: the field name is not a string`, {
+		why: `An order field name is a string; received ${describeReceived(requestedName)}.`,
+		fix: orderByOneOf,
+		meta: {
+			model: modelName,
+			field: requestedName
+		}
+	});
+	if (!names.includes(requestedName)) {
+		const shownName = shown(requestedName);
+		throw ormError("ORM.ARGUMENT_INVALID", `Cannot order ${modelName} by ${shownName.text}`, {
+			why: whyNotOrderable(collection, requestedName),
+			fix: `${orderByOneOf}${cutNote("name", shownName)}`,
+			meta: {
+				model: modelName,
+				field: requestedName
+			}
+		});
+	}
+	const field = blindCast(requestedName);
+	const order = requestedDirection;
+	return (row) => row[field][order]();
+}
 function normalizeWhereArg(arg, options) {
 	if (arg === void 0) return;
 	if (arg === null) throw ormError("ORM.ARGUMENT_INVALID", "WhereArg cannot be null. Pass undefined or a valid WhereExpr/ToWhereExpr payload.", { meta: { argument: "where" } });
@@ -3857,6 +4143,99 @@ function normalizeWhereArg(arg, options) {
 function isToWhereExpr(arg) {
 	return typeof arg === "object" && arg !== null && "toWhereExpr" in arg && !isWhereExpr(arg);
 }
+const CHAIN_PARTS = {
+	orderBy: {
+		noun: "an order",
+		call: "orderBy()"
+	},
+	limit: {
+		noun: "a limit",
+		call: "limit()"
+	},
+	offset: {
+		noun: "an offset",
+		call: "offset()"
+	},
+	cursor: {
+		noun: "a cursor",
+		call: "cursor()"
+	},
+	distinct: {
+		noun: "a distinct selection",
+		call: "distinct()"
+	},
+	distinctOn: {
+		noun: "a distinctOn selection",
+		call: "distinctOn()"
+	}
+};
+function presentParts(state, names) {
+	const present = names.filter((name) => {
+		const value = state[name];
+		return Array.isArray(value) ? value.length > 0 : value !== void 0;
+	});
+	return {
+		nouns: present.map((name) => CHAIN_PARTS[name].noun),
+		calls: present.map((name) => CHAIN_PARTS[name].call)
+	};
+}
+function listed(items, conjunction) {
+	const last = items.at(-1) ?? "";
+	return items.length > 1 ? `${items.slice(0, -1).join(", ")} ${conjunction} ${last}` : last;
+}
+const HIDDEN_BY_A_SCOPE = "A scope applied with apply can add one without showing it at the call site.";
+/** Throws `ORM.ARGUMENT_INVALID` when the collection has a limit, an offset, a cursor or a distinct selection, which `method`, a write of every matching row, would ignore. */
+function assertBulkWriteIgnoresNothing(state, modelName, method) {
+	const { nouns, calls } = presentParts(state, [
+		"limit",
+		"offset",
+		"cursor",
+		"distinct",
+		"distinctOn"
+	]);
+	if (nouns.length === 0) return;
+	const { limit, offset, cursor, distinct, distinctOn } = state;
+	throw ormError("ORM.ARGUMENT_INVALID", `Cannot ${method} ${modelName}: the collection has ${listed(nouns, "and")}`, {
+		why: `${method} changes every row that matches the filter. The statement it runs cannot apply ${listed(nouns, "or")}, so it would change more rows than the chain asks for. ${HIDDEN_BY_A_SCOPE}`,
+		fix: `Remove ${listed(calls, "and")} before ${method}, or read the rows first and change them by their ids.`,
+		meta: {
+			model: modelName,
+			method,
+			limit,
+			offset,
+			cursor,
+			distinct,
+			distinctOn
+		}
+	});
+}
+/** Throws `ORM.ARGUMENT_INVALID` when the collection has an order, a limit, an offset, a cursor or a distinct selection, which an update with a relation callback would ignore. */
+function assertRelationUpdateIgnoresNothing(state, modelName) {
+	const { nouns, calls } = presentParts(state, [
+		"orderBy",
+		"limit",
+		"offset",
+		"cursor",
+		"distinct",
+		"distinctOn"
+	]);
+	if (nouns.length === 0) return;
+	const { orderBy, limit, offset, cursor, distinct, distinctOn } = state;
+	throw ormError("ORM.ARGUMENT_INVALID", `Cannot update ${modelName} with a relation mutation: the collection has ${listed(nouns, "and")}`, {
+		why: `An update that changes a relation finds its row by the filter alone. It would ignore ${listed(nouns, "and")}, and could change another row than first() returns. ${HIDDEN_BY_A_SCOPE}`,
+		fix: `Remove ${listed(calls, "and")} before update, or filter to the one row, such as by its id.`,
+		meta: {
+			model: modelName,
+			method: "update",
+			ordered: orderBy !== void 0 && orderBy.length > 0,
+			limit,
+			offset,
+			cursor,
+			distinct,
+			distinctOn
+		}
+	});
+}
 function applyCreateDefaults(ctx, namespaceId, tableName, rows, defaultValueCache = /* @__PURE__ */ new Map()) {
 	for (const row of rows) {
 		const applied = ctx.context.applyMutationDefaults({
@@ -3975,25 +4354,57 @@ var CollectionBase = class CollectionBase {
 		if (!filter) return blindCast(this);
 		return this.#cloneSelf({ filters: [...this.state.filters, filter] });
 	}
-	/**
-	* Call `fn` with this collection and return its result.
-	*/
 	apply(fn) {
 		return fn(this);
 	}
-	variant(variantName) {
-		const model = modelOf(this.contract, this.namespaceId, this.modelName);
-		const discriminator = model?.discriminator;
-		const variants = model?.variants;
-		if (!discriminator || !variants) return blindCast(this);
-		const variantEntry = variants[variantName];
-		if (!variantEntry) return blindCast(this);
-		const columnName = resolveFieldToColumn(this.contract, this.namespaceId, this.modelName, discriminator.field);
-		const filter = BinaryExpr.eq(ColumnRef.of(this.tableName, columnName), LiteralExpr.of(variantEntry.value));
-		const filtersWithoutPreviousVariant = this.state.variantName ? this.state.filters.filter((f) => !(f instanceof BinaryExpr && f.left instanceof ColumnRef && f.left.column === columnName && f.left.table === this.tableName)) : this.state.filters;
+	/**
+	* Define a scope for this collection's model, such as a shared `select` and `include`. The body is typed once, against the model's plain collection. The scope accepts any collection of the model that `select` and `variant` have not narrowed.
+	*
+	* ```ts
+	* const summary = db.Post.scope((posts) => posts.select('id', 'title').include('user'));
+	* db.User.include('posts', (posts) => posts.apply(summary));
+	* ```
+	*/
+	scope(body) {
+		assertScopeBody(body);
+		const source = {
+			modelName: this.modelName,
+			namespaceId: this.namespaceId
+		};
+		return (collection) => {
+			assertModelScopeReceiver(source, collection);
+			return body(blindCast(collection));
+		};
+	}
+	variant(value) {
+		const polyInfo = resolvePolymorphismInfo(this.contract, this.namespaceId, this.modelName);
+		const selectedVariantName = this.state.variantName;
+		if (selectedVariantName !== void 0) {
+			const selectedValue = polyInfo?.variants.get(selectedVariantName)?.value;
+			throw ormError("ORM.OPERATION_UNSUPPORTED", `variant("${value}") cannot be called on model "${this.modelName}" because variant("${selectedValue}") is already selected; call variant() on the base collection instead`, { meta: {
+				method: "variant",
+				model: this.modelName,
+				variant: selectedVariantName,
+				selectedValue,
+				reason: "variant-already-selected"
+			} });
+		}
+		const variantInfo = polyInfo?.variantsByValue.get(value);
+		if (!polyInfo || !variantInfo) {
+			const declaredValues = [...polyInfo?.variantsByValue.keys() ?? []];
+			throw ormError("ORM.ARGUMENT_INVALID", declaredValues.length === 0 ? `variant("${value}") cannot narrow model "${this.modelName}": it declares no discriminator values` : `variant("${value}") cannot narrow model "${this.modelName}": the declared discriminator values are ${declaredValues.map((declared) => `"${declared}"`).join(", ")}`, { meta: {
+				method: "variant",
+				argument: "value",
+				model: this.modelName,
+				value,
+				declaredValues
+			} });
+		}
+		const columnName = polyInfo.discriminatorColumn;
+		const filter = BinaryExpr.eq(ColumnRef.of(this.tableName, columnName), LiteralExpr.of(variantInfo.value));
 		return this.#cloneWithRow({
-			filters: [...filtersWithoutPreviousVariant, filter],
-			variantName
+			filters: [...this.state.filters, filter],
+			variantName: variantInfo.modelName
 		});
 	}
 	include(relationName, refineFn) {
@@ -4533,6 +4944,7 @@ var CollectionBase = class CollectionBase {
 		assertReturningCapability(this.contract, "update()");
 		const annotationsMap = this.#collectAnnotationsFromMeta(configure, "write", "update");
 		if (hasNestedMutationCallbacks(this.contract, this.namespaceId, this.modelName, blindCast(data))) {
+			assertRelationUpdateIgnoresNothing(this.state, this.modelName);
 			const updatedRow = await executeNestedUpdateMutation({
 				context: this.ctx.context,
 				runtime: this.ctx.runtime,
@@ -4553,6 +4965,7 @@ var CollectionBase = class CollectionBase {
 		});
 	}
 	updateAll(data, configure) {
+		assertBulkWriteIgnoresNothing(this.state, this.modelName, "updateAll");
 		return this.#updateAllWithAnnotations(data, this.#collectAnnotationsFromMeta(configure, "write", "updateAll"));
 	}
 	#updateAllWithAnnotations(data, annotationsMap) {
@@ -4580,6 +4993,7 @@ var CollectionBase = class CollectionBase {
 		});
 	}
 	async updateAndCount(data, configure) {
+		assertBulkWriteIgnoresNothing(this.state, this.modelName, "updateAndCount");
 		const mappedData = mapModelDataToStorageRow(this.contract, this.namespaceId, this.modelName, data);
 		if (Object.keys(mappedData).length === 0) return 0;
 		applyUpdateDefaults(this.ctx, this.namespaceId, this.tableName, mappedData);
@@ -4594,10 +5008,15 @@ var CollectionBase = class CollectionBase {
 			const scoped = this.#withRuntime(scope);
 			const identityWhere = await scoped.#findFirstMatchingRowIdentityWhere();
 			if (!identityWhere) return null;
-			return (await scoped.#clone({ filters: [identityWhere] }).#executeDeleteReturning(annotationsMap).toArray())[0] ?? null;
+			return (await scoped.#clone({
+				filters: [identityWhere],
+				limit: void 0,
+				offset: void 0
+			}).#executeDeleteReturning(annotationsMap).toArray())[0] ?? null;
 		});
 	}
 	deleteAll(configure) {
+		assertBulkWriteIgnoresNothing(this.state, this.modelName, "deleteAll");
 		return this.#deleteAllWithAnnotations(this.#collectAnnotationsFromMeta(configure, "write", "deleteAll"));
 	}
 	#deleteAllWithAnnotations(annotationsMap) {
@@ -4656,6 +5075,7 @@ var CollectionBase = class CollectionBase {
 		return new AsyncIterableResult(generator());
 	}
 	async deleteAndCount(configure) {
+		assertBulkWriteIgnoresNothing(this.state, this.modelName, "deleteAndCount");
 		const annotationsMap = this.#collectAnnotationsFromMeta(configure, "write", "deleteAndCount");
 		const compiled = mergeAnnotations(compileDeleteCount(this.contract, this.namespaceId, this.tableName, this.state.filters, this.state.variantName, this.modelName), annotationsMap);
 		return (await this.ctx.runtime.execute(compiled)).affectedRows;
@@ -4707,6 +5127,8 @@ var CollectionBase = class CollectionBase {
 			model: this.modelName,
 			table: this.tableName
 		} });
+		checkLimitOffset("limit", this.state.limit);
+		if (this.state.limit === 0) return null;
 		const firstRow = await this.#clone({
 			selectedFields: [...identityColumns],
 			includes: []
@@ -4920,8 +5342,8 @@ function orm(options) {
 	}
 	return new Proxy({}, { get(_target, prop) {
 		if (typeof prop !== "string") return;
-		if (!Object.hasOwn(contract.domain.namespaces, prop)) return;
-		return namespaceFacet(prop);
+		if (Object.hasOwn(contract.domain.namespaces, prop)) return namespaceFacet(prop);
+		return prop === "scope" ? defineFieldScope : void 0;
 	} });
 }
 function createCollectionRegistry(contract, collections) {
@@ -4968,6 +5390,6 @@ function createPreparedRowQuery(description, statement) {
 	} });
 }
 //#endregion
-export { Collection, GroupedCollection, all, and, createModelAccessor, createPreparedRowQuery, emptyState, not, or, orm, prepareQuery };
+export { Collection, GroupedCollection, all, and, createModelAccessor, createPreparedRowQuery, emptyState, not, or, orderByField, orm, prepareQuery };
 
 //# sourceMappingURL=orm-client.mjs.map