content-query 0.4.0 → 0.5.1

package/dist/{operators-Cwy8Kx4o.mjs → operators-D-w1-gDg.mjs}

@@ -1,5 +1,134 @@
 import { a as invalidQuery } from "./errors-Bfd0R4_P.mjs";
 import { c as isScalar, i as detach } from "./values-BbTV4QT-.mjs";
+//#region src/collection/names.ts
+/** Words that cannot name a `const` binding in an ES module, or that read as module syntax. */
+const reservedWords = new Set("arguments await break case catch class const continue debugger default delete do else enum eval export extends false finally for function if implements import in instanceof interface let new null package private protected public return static super switch this throw true try typeof var void while with yield".split(" "));
+/** Names Windows reserves for devices, in any letter case, which cannot name a directory. */
+const deviceName = /^(?:con|prn|aux|nul|com[0-9]|lpt[0-9])$/i;
+const identifier = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+/** Uppercases the first character, keeping the rest of a camelCase name. */
+function capitalize(value) {
+	return value.charAt(0).toUpperCase() + value.slice(1);
+}
+/**
+* Converts a collection name into the identifier its entry exports and its import path uses.
+* Characters that cannot appear in an identifier separate camelCase words, a leading digit gets
+* an `_` prefix, and reserved words and Windows device names get a `Collection` suffix.
+*
+* @param name - The collection's key in the `collections` registry.
+* @returns The export name, such as `blogPosts` for `blog-posts`.
+*/
+function exportNameOf(name) {
+	let converted = name.split(/[^A-Za-z0-9_$]+/).filter(Boolean).map((word, index) => index === 0 ? word : capitalize(word)).join("");
+	if (!converted) converted = "collection";
+	else if (/^[0-9]/.test(converted)) converted = `_${converted}`;
+	return reservedWords.has(converted) || deviceName.test(converted) ? `${converted}Collection` : converted;
+}
+/**
+* Derives the singular word for generated type names by dropping one trailing `s`. Names ending
+* in `ss`, such as `address`, keep it. Irregular plurals use the collection's `typeName`.
+*
+* @param exportName - The collection's export name.
+* @returns The singular form, such as `blogPost` for `blogPosts`.
+*/
+function singularOf(exportName) {
+	return exportName.length > 1 && exportName.endsWith("s") && !exportName.endsWith("ss") ? exportName.slice(0, -1) : exportName;
+}
+/**
+* Computes every collection's generated names and rejects names that would collide.
+*
+* @param registry - Collection keys with each collection's optional `typeName` override.
+* @returns The names of each collection's entry, keyed by collection name.
+* @throws An `Error` naming the conflict when two collections share an export or type name, or
+* when a `typeName` is not an identifier.
+*/
+function collectionNames(registry) {
+	const names = /* @__PURE__ */ new Map();
+	const exports = /* @__PURE__ */ new Map();
+	const types = /* @__PURE__ */ new Map();
+	for (const [name, definition] of Object.entries(registry)) {
+		const declared = definition?.typeName;
+		if (declared !== void 0 && (typeof declared !== "string" || !identifier.test(declared))) throw new Error(`Collection "${name}" typeName must be an identifier such as "Category"; received ${JSON.stringify(declared)}.`);
+		const exportName = exportNameOf(name);
+		const typeName = `Content${capitalize(declared ?? singularOf(exportName))}`;
+		const exported = exports.get(exportName.toLowerCase());
+		if (exported !== void 0) throw new Error(`Collections "${exported}" and "${name}" both export "${exportName}" (ignoring letter case), which their #content-query entries cannot share. Rename one of them.`);
+		const payloadTypeName = `${typeName}Payload`;
+		for (const generated of [typeName, payloadTypeName]) {
+			const typed = types.get(generated);
+			if (typed !== void 0) throw new Error(`Collections "${typed}" and "${name}" both generate the type "${generated}". Set typeName on one of them.`);
+			types.set(generated, name);
+		}
+		exports.set(exportName.toLowerCase(), name);
+		names.set(name, {
+			exportName,
+			typeName,
+			payloadTypeName
+		});
+	}
+	return names;
+}
+//#endregion
+//#region src/query/plan.ts
+/**
+* Rejects a declared relationship whose target collection this query scope has not loaded,
+* naming the collection to pass to `using()`.
+*
+* @param registry - The query scope's registry.
+* @param collection - The collection that declares the relationship.
+* @param name - The relationship, field, or filter name a query used.
+*/
+function assertAvailable(registry, collection, name) {
+	const unavailable = registry[collection]?.unavailable;
+	if (!unavailable || !Object.hasOwn(unavailable, name)) return;
+	const target = exportNameOf(unavailable[name]);
+	invalidQuery(`Relationship "${name}" targets the ${target} collection, which this query has not loaded. Pass it to using(), such as ${exportNameOf(collection)}.using(${target}).`);
+}
+/** Starts a fresh query without binding a content revision until execution. */
+function emptyPlan(collection) {
+	return {
+		collection,
+		filters: [],
+		order: [],
+		with: {}
+	};
+}
+/** Explains the explicit-selection rule wherever a scope returns rows without selecting data. */
+const NO_SELECTION_MESSAGE = "Select fields, relationships, payloads, or adjacent entries before running this query.";
+/** Explains why `paginate()` is unavailable once a query sets its own limit or offset. */
+const PAGINATE_AFTER_LIMIT_MESSAGE = "paginate() sets the limit and offset itself; remove limit and offset from this query.";
+/**
+* Returns the order a scope's entries follow: explicit clauses, then ascending ID as the final
+* tie-breaker unless ID is already sorted. Scopes without clauses sort by ascending ID, except
+* relationship scopes that preserve an authored ID array's order.
+*
+* @param plan - The scope whose order to resolve.
+* @param preserveOrder - Keeps authored order when the scope has no explicit clauses.
+* @returns The sort clauses to apply, in priority order.
+*/
+function effectiveOrder(plan, preserveOrder = false) {
+	if (!plan.order.length) return preserveOrder ? [] : [{
+		field: "id",
+		direction: "asc"
+	}];
+	const order = [...plan.order];
+	if (!order.some((sort) => sort.field === "id")) order.push({
+		field: "id",
+		direction: "asc"
+	});
+	return order;
+}
+/**
+* Checks whether a row-returning scope explicitly requests data. Nothing is implicit, not even
+* `id`: a scope must select fields, include a relationship, request a payload, or select adjacency.
+*
+* @param plan - The scope to check; `undefined` when a callback returned no builder.
+* @returns `true` when the scope requests at least one kind of data.
+*/
+function hasSelection(plan) {
+	return !!plan && (!!plan.select?.length || !!plan.adjacent || Object.keys(plan.with).length > 0 || Object.keys(plan.payloads ?? {}).length > 0);
+}
+//#endregion
 //#region src/query/operators.ts
 /** Builds a checked, backend-independent predicate instead of a per-entry callback. */
 function predicate(operator, field, value) {
@@ -139,7 +268,10 @@ function resolveRelations(registry, collection, expression) {
 		case "has": {
 			const relationships = registry[collection]?.relationships ?? {};
 			const relation = Object.hasOwn(relationships, expression.field) ? relationships[expression.field] : void 0;
-			if (!relation) invalidQuery(`Unknown relationship "${expression.field}" in has().`);
+			if (!relation) {
+				assertAvailable(registry, collection, expression.field);
+				invalidQuery(`Unknown relationship "${expression.field}" in has().`);
+			}
 			return {
 				kind: "relation",
 				collection,
@@ -256,4 +388,4 @@ function validateExpression(expression) {
 	} else invalidQuery("Invalid expression structure.");
 }
 //#endregion
-export { notIlike as C, resolveRelations as D, or as E, startsWith as O, not as S, notLike as T, isUndefined as _, arrayContainsAny as a, lte as b, eq as c, gte as d, has as f, isNull as g, isMissing as h, arrayContainsAll as i, validateExpression as k, fieldProxy as l, inArray as m, arrayContained as n, contains as o, ilike as p, arrayContains as r, endsWith as s, and as t, gt as u, like as v, notInArray as w, ne as x, lt as y };
+export { NO_SELECTION_MESSAGE as A, notIlike as C, resolveRelations as D, or as E, hasSelection as F, collectionNames as I, assertAvailable as M, effectiveOrder as N, startsWith as O, emptyPlan as P, not as S, notLike as T, isUndefined as _, arrayContainsAny as a, lte as b, eq as c, gte as d, has as f, isNull as g, isMissing as h, arrayContainsAll as i, PAGINATE_AFTER_LIMIT_MESSAGE as j, validateExpression as k, fieldProxy as l, inArray as m, arrayContained as n, contains as o, ilike as p, arrayContains as r, endsWith as s, and as t, gt as u, like as v, notInArray as w, ne as x, lt as y };

package/dist/query-style-C2FcT1f9.d.mts

@@ -0,0 +1,23 @@
+//#region src/runtime/query-style.d.ts
+/** Query APIs an application can allow through `queryStyle` in content-query.config. */
+type QueryStyle = "fluent" | "relational";
+/**
+ * Collection members that start each query style. Every other query API hangs off these members,
+ * so gating them gates payloads, relationships, and adjacency as well. `count()` without options
+ * belongs to both styles; `count(options)` takes relational options.
+ */
+declare const queryStyleMembers: {
+  readonly fluent: readonly ["select", "where", "orderBy", "limit", "offset", "with", "withPayload", "selectAdjacent"];
+  readonly relational: readonly ["findMany", "findFirst", "paginate", "count(options)"];
+};
+/** A collection member that belongs to exactly one query style. */
+type QueryStyleMember = (typeof queryStyleMembers)[QueryStyle][number];
+/** Collection members that start a query in the given style. */
+type MembersOf<Style extends QueryStyle> = (typeof queryStyleMembers)[Style][number];
+/**
+ * Describes a disabled collection member in the type error itself, for example:
+ * `posts.select is unavailable because content-query.config sets queryStyle to "relational".`
+ */
+type QueryStyleDisabled<Collection extends string, Member extends QueryStyleMember, Style extends QueryStyle> = `${Collection}.${Member} is unavailable because content-query.config sets queryStyle to "${Style}".`;
+//#endregion
+export { QueryStyleMember as i, QueryStyle as n, QueryStyleDisabled as r, MembersOf as t };

package/dist/query.d.mts

@@ -1,4 +1,4 @@
-import { _ as Where, a as RelationalWhere, c as Fields, d as QueryFields, f as RelationField, g as SelectionResult, h as Selection, i as RelationalQueryResult, l as Ordered, m as ScalarField, n as RelationalQueries, o as Adjacent, p as Scalar, r as RelationalQueryOptions, s as Field, t as RelationalCountOptions, v as Expression } from "./relational-types-C8xJtLG5.mjs";
+import { C as Selection, E as Expression, S as ScalarField, T as Where, _ as PaginateResult, a as RelationalQueryOptions, b as RelationField, c as Adjacent, d as Field, f as Fields, g as PaginateOptions, h as PageOptions, i as RelationalQueries, l as CursorOptions, m as Ordered, n as RelationalCountOptions, o as RelationalQueryResult, p as NumberedPage, r as RelationalPaginateOptions, s as RelationalWhere, u as CursorPage, w as SelectionResult, x as Scalar, y as QueryFields } from "./relational-types-PtrzENt0.mjs";
 //#region src/query/operators.d.ts
 /** Matches a scalar using strict value/date equality. */
 export declare function eq<Value>(field: ScalarField<Value>, value: NoInfer<Value>): Expression;
@@ -64,4 +64,4 @@ export declare function or(...expressions: Expression[]): Expression;
 /** Negates a predicate's boolean result. */
 export declare function not(expression: Expression): Expression;
 //#endregion
-export type { Adjacent, RelationalCountOptions as CountOptions, Expression, Field, Fields, QueryFields, RelationalQueryOptions as QueryOptions, RelationalQueryOptions, RelationField, RelationalQueries, RelationalQueryResult, RelationalWhere, Selection, SelectionResult, Where };
+export type { Adjacent, RelationalCountOptions as CountOptions, CursorOptions, CursorPage, Expression, Field, Fields, NumberedPage, PageOptions, PaginateOptions, PaginateResult, QueryFields, RelationalQueryOptions as QueryOptions, RelationalQueryOptions, RelationField, RelationalPaginateOptions, RelationalQueries, RelationalQueryResult, RelationalWhere, Selection, SelectionResult, Where };

package/dist/query.mjs

@@ -1 +1 @@
-export { t as and, n as arrayContained, r as arrayContains, i as arrayContainsAll, a as arrayContainsAny, o as contains, s as endsWith, c as eq, u as gt, d as gte, f as has, p as ilike, m as inArray, h as isMissing, g as isNull, _ as isUndefined, v as like, y as lt, b as lte, x as ne, S as not, C as notIlike, w as notInArray, T as notLike, E as or, O as startsWith } from "./operators-Cwy8Kx4o.mjs";
+export { t as and, n as arrayContained, r as arrayContains, i as arrayContainsAll, a as arrayContainsAny, o as contains, s as endsWith, c as eq, u as gt, d as gte, f as has, p as ilike, m as inArray, h as isMissing, g as isNull, _ as isUndefined, v as like, y as lt, b as lte, x as ne, S as not, C as notIlike, w as notInArray, T as notLike, E as or, O as startsWith } from "./operators-D-w1-gDg.mjs";

package/dist/{relational-types-C8xJtLG5.d.mts → relational-types-PtrzENt0.d.mts}

@@ -1,4 +1,4 @@
-import { S as VariantOf, _ as RelationshipsOf, g as Relationship, h as QueryData, i as CollectionRegistry, m as PayloadsOf } from "./types-DbFfF6JE.mjs";
+import { C as UnavailableRelationshipsOf, E as VariantOf, S as UnavailableRelationship, _ as Relationship, g as QueryData, h as PayloadsOf, i as CollectionRegistry, v as RelationshipsOf, x as SelectedData } from "./types-WOsFmNnN.mjs";
 //#region src/query/plan.d.ts
 type PredicateOperator = "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "in-array" | "not-in-array" | "contains" | "starts-with" | "ends-with" | "like" | "ilike" | "array-contains" | "array-contains-any" | "array-contains-all" | "array-contained" | "is-null" | "is-undefined" | "is-missing";
 type Expression = {
@@ -37,6 +37,26 @@ type QueryPlan = {
   adjacent?: AdjacentPlan;
   /** Payloads to attach under `_payloads` after filtering, ordering, and pagination. */
   payloads?: Readonly<Record<string, PlanPayload>>;
+  /** A root `paginate()` request; plans that carry it never set `limit` or `offset`. */
+  paginate?: PaginatePlan;
+};
+/**
+ * A page-number or cursor page request. Cursor keys are already decoded into the sort values of the
+ * boundary entry, in effective-order position, so backends never parse cursor strings.
+ */
+type PaginatePlan = {
+  mode: "page";
+  page: number;
+  size: number;
+} | {
+  mode: "cursor";
+  size: number;
+  /** `after` pages forward from `key`; `before` pages backward to it. */
+  direction: "after" | "before";
+  /** Sort values of the boundary entry; omitted to start at the first or last entry. */
+  key?: readonly unknown[];
+  /** Whether the result includes the filtered total. */
+  total: boolean;
 };
 /**
  * Selects previous and next entries. `results` finds neighbors within the scope's own filtered and
@@ -51,6 +71,8 @@ type AdjacentPlan = {
 type PlanPayload = {
   variant: Readonly<Record<string, string>>;
 };
+/** How a plan returns its results; `paginate` requires the plan's `paginate` request. */
+type QueryTerminal = "all" | "first" | "count" | "paginate";
 /** Describes a payload that queries may request, without its resolver or schema. */
 type PayloadDescriptor = {
   variants: readonly string[];
@@ -59,9 +81,18 @@ type QueryRegistry = Record<string, {
   relationships: Record<string, Relationship>;
   /** Payload names available to queries; omitted when the collection has none. */
   payloads?: Record<string, PayloadDescriptor>;
+  /**
+   * Declared relationships whose target collection this query scope has not loaded, by name, with
+   * the target collection. Queries that use one report which collection to pass to `using()`.
+   */
+  unavailable?: Record<string, string>;
+  /** The declared `typeName`, which only generated declarations read. */
+  typeName?: string;
 }>;
 /** Explains the explicit-selection rule wherever a scope returns rows without selecting data. */
 declare const NO_SELECTION_MESSAGE: "Select fields, relationships, payloads, or adjacent entries before running this query.";
+/** Explains why `paginate()` is unavailable once a query sets its own limit or offset. */
+declare const PAGINATE_AFTER_LIMIT_MESSAGE: "paginate() sets the limit and offset itself; remove limit and offset from this query.";
 //#endregion
 //#region src/query/types.d.ts
 declare const queryType: unique symbol;
@@ -82,7 +113,9 @@ type RelationField<TargetFields> = {
   readonly [relationTarget]: TargetFields;
 };
 /** Fields and relationships available to a fluent `where()` callback. */
-type QueryFields<Registry extends CollectionRegistry, Name extends keyof Registry & string> = Fields<QueryData<Registry[Name]>> & { readonly [Key in keyof RelationshipsOf<Registry[Name]> & string]-?: RelationField<QueryFields<Registry, RelatedName$1<Registry, RelationOf<Registry, Name, Key>>>>; };
+type QueryFields<Registry extends CollectionRegistry, Name extends keyof Registry & string> = Fields<QueryData<Registry[Name]>> & { readonly [Key in keyof RelationshipsOf<Registry[Name]> & string]-?: RelationField<QueryFields<Registry, RelatedName$1<Registry, RelationOf<Registry, Name, Key>>>>; } & { readonly [
+/** A relationship into a collection the query has not loaded reads as the type error. */
+Key in keyof UnavailableRelationshipsOf<Registry[Name]> & string]-?: UnavailableRelationship<Registry[Name], Key>; };
 type Scalar = string | number | bigint | boolean | Date | null | undefined;
 type ScalarField<Value> = Field$1<Value> & ([Value] extends [Scalar] ? unknown : never);
 type Ordered<Value> = NonNullable<Value> extends string ? unknown : NonNullable<Value> extends number ? unknown : NonNullable<Value> extends bigint ? unknown : NonNullable<Value> extends Date ? unknown : never;
@@ -108,28 +141,30 @@ type RelatedName$1<Registry extends CollectionRegistry, Relation extends Relatio
 /** Applies declared relationship cardinality, optional reference fields, and filtering to a result. */
 type RelationshipResult<Definition, Relation extends Relationship, Result, Filtered extends boolean = false> = Relation["type"] extends "many" ? Result[] : Result | (Filtered extends true ? null : Relation["referenceSide"] extends "from" ? Relation["from"] extends keyof QueryData<Definition> ? null extends QueryData<Definition>[Relation["from"]] ? null : undefined extends QueryData<Definition>[Relation["from"]] ? null : never : null : null);
 type RelationValue<Definition, Relation extends Relationship, Configured> = RelationshipResult<Definition, Relation, ResultOf<Configured>, FilteredOf<Configured>>;
-type Query<Registry extends CollectionRegistry, Name extends keyof Registry & string, Result = {}, Selected extends boolean = false, Many extends boolean = true, Root extends boolean = true, Filtered extends boolean = false, AllowAdjacent extends boolean = true, Pagination extends boolean = true> = QueryInfo<Result, Selected, Filtered> & {
-  select<const Keys extends readonly [keyof QueryData<Registry[Name]> & string, ...(keyof QueryData<Registry[Name]> & string)[]]>(...keys: Keys): Query<Registry, Name, { [Key in Exclude<keyof Result, keyof QueryData<Registry[Name]>> | Keys[number]]: Key extends Keys[number] ? QueryData<Registry[Name]>[Key & keyof QueryData<Registry[Name]>] : Key extends keyof Result ? Result[Key] : never; }, true, Many, Root, Filtered, AllowAdjacent, Pagination>;
-  where(configure: (fields: QueryFields<Registry, Name>) => Expression): Query<Registry, Name, Result, Selected, Many, Root, true, AllowAdjacent, Pagination>;
-  with<Key extends keyof RelationshipsOf<Registry[Name]> & string, Configured extends QueryInfo<unknown, true>>(name: Key, configure: (query: Query<Registry, RelatedName$1<Registry, RelationOf<Registry, Name, Key>>, {}, false, RelationOf<Registry, Name, Key>["type"] extends "many" ? true : false, false, false, AllowAdjacent>) => Configured): Query<Registry, Name, Result & { [Property in Key]: RelationValue<Registry[Name], RelationOf<Registry, Name, Key>, Configured>; }, true, Many, Root, Filtered, AllowAdjacent, Pagination>;
+type Query<Registry extends CollectionRegistry, Name extends keyof Registry & string, Result = {}, Selected extends boolean = false, Many extends boolean = true, Root extends boolean = true, Filtered extends boolean = false, AllowAdjacent extends boolean = true, Pagination extends boolean = true, Paged extends boolean = false> = QueryInfo<Result, Selected, Filtered> & {
+  select<const Keys extends readonly [keyof QueryData<Registry[Name]> & string, ...(keyof QueryData<Registry[Name]> & string)[]]>(...keys: Keys): Query<Registry, Name, Simplify$1<{ [Key in Exclude<keyof Result, keyof QueryData<Registry[Name]>>]: Result[Key]; } & SelectedData<QueryData<Registry[Name]>, Keys[number]>>, true, Many, Root, Filtered, AllowAdjacent, Pagination, Paged>;
+  where(configure: (fields: QueryFields<Registry, Name>) => Expression): Query<Registry, Name, Result, Selected, Many, Root, true, AllowAdjacent, Pagination, Paged>;
+  with<Key extends keyof RelationshipsOf<Registry[Name]> & string, Configured extends QueryInfo<unknown, true>>(name: Key, configure: (query: Query<Registry, RelatedName$1<Registry, RelationOf<Registry, Name, Key>>, {}, false, RelationOf<Registry, Name, Key>["type"] extends "many" ? true : false, false, false, AllowAdjacent>) => Configured): Query<Registry, Name, Result & { [Property in Key]: RelationValue<Registry[Name], RelationOf<Registry, Name, Key>, Configured>; }, true, Many, Root, Filtered, AllowAdjacent, Pagination, Paged>;
+  /** A relationship into a collection the query has not loaded reports which one to supply. */
+  with<Key extends keyof UnavailableRelationshipsOf<Registry[Name]> & string>(name: Key, configure: UnavailableRelationship<Registry[Name], Key>): never;
 } & (Many extends true ? {
-  orderBy(field: SortKey<QueryData<Registry[Name]>>, direction?: "asc" | "desc"): Query<Registry, Name, Result, Selected, Many, Root, Filtered, AllowAdjacent, Pagination>;
+  orderBy(field: SortKey<QueryData<Registry[Name]>>, direction?: "asc" | "desc"): Query<Registry, Name, Result, Selected, Many, Root, Filtered, AllowAdjacent, Pagination, Paged>;
 } : {}) & (Many extends true ? Pagination extends true ? {
-  limit(value: number): Query<Registry, Name, Result, Selected, Many, Root, Filtered, AllowAdjacent, Pagination>;
-  offset(value: number): Query<Registry, Name, Result, Selected, Many, Root, Filtered, AllowAdjacent, Pagination>;
+  limit(value: number): Query<Registry, Name, Result, Selected, Many, Root, Filtered, AllowAdjacent, Pagination, true>;
+  offset(value: number): Query<Registry, Name, Result, Selected, Many, Root, Filtered, AllowAdjacent, Pagination, true>;
 } : {} : {}) & (AllowAdjacent extends true ? {
   /** Attaches a payload under `_payloads` after filtering, ordering, and pagination. */
-  withPayload<Key extends keyof PayloadsOf<Registry[Name]> & string>(name: Key, ...variant: keyof VariantOf<Registry[Name], Key> extends never ? [] : [variant: Readonly<VariantOf<Registry[Name], Key>>]): Query<Registry, Name, WithPayload<Result, Key, PayloadsOf<Registry[Name]>[Key]>, true, Many, Root, Filtered, AllowAdjacent, Pagination>;
+  withPayload<Key extends keyof PayloadsOf<Registry[Name]> & string>(name: Key, ...variant: keyof VariantOf<Registry[Name], Key> extends never ? [] : [variant: Readonly<VariantOf<Registry[Name], Key>>]): Query<Registry, Name, WithPayload<Result, Key, PayloadsOf<Registry[Name]>[Key]>, true, Many, Root, Filtered, AllowAdjacent, Pagination, Paged>;
   /** Selects neighbor fields within this scope's filtered and ordered results. */
   selectAdjacent<const Keys extends readonly [keyof QueryData<Registry[Name]> & string, ...(keyof QueryData<Registry[Name]> & string)[]]>(...fields: Keys): Query<Registry, Name, Result & {
-    _adjacent: Adjacent<{ [Key in Keys[number]]: QueryData<Registry[Name]>[Key & keyof QueryData<Registry[Name]>]; }>;
-  }, true, Many, Root, Filtered, AllowAdjacent, Pagination>;
+    _adjacent: Adjacent<SelectedData<QueryData<Registry[Name]>, Keys[number]>>;
+  }, true, Many, Root, Filtered, AllowAdjacent, Pagination, Paged>;
   selectAdjacent<Configured extends QueryInfo<unknown, true>>(configure: (siblings: Query<Registry, Name, {}, false, true, false, false, false, false>) => Configured): Query<Registry, Name, Result & {
     _adjacent: Adjacent<ResultOf<Configured>>;
-  }, true, Many, Root, Filtered, AllowAdjacent, Pagination>;
+  }, true, Many, Root, Filtered, AllowAdjacent, Pagination, Paged>;
   selectAdjacent<const Options extends AdjacentOptions<Registry, Name>>(options: Options & CheckedOptions<Registry, Name, NoInfer<Options>, true, false, false>): Query<Registry, Name, Result & {
     _adjacent: Adjacent<SelectionResult<Registry, Name, Options["select"]>>;
-  }, true, Many, Root, Filtered, AllowAdjacent, Pagination>;
+  }, true, Many, Root, Filtered, AllowAdjacent, Pagination, Paged>;
 } : {}) & (Root extends true ? {
   all: Selected extends true ? () => Promise<Simplify$1<Result>[]> : UnselectedTerminal;
   execute: Selected extends true ? () => Promise<Simplify$1<Result>[]> : UnselectedTerminal;
@@ -139,7 +174,79 @@ type Query<Registry extends CollectionRegistry, Name extends keyof Registry & st
   count: [Result] extends [never] ? () => Promise<number> : [Result] extends [{
     _payloads: unknown;
   }] ? never : () => Promise<number>;
+  /**
+   * Returns one page from one revision: `{ page, size }` for page numbers, or
+   * `{ size, after?, before?, total? }` for cursors. Unavailable after `limit()` or `offset()`.
+   */
+  paginate: Selected extends true ? [Paged] extends [true] ? PaginateAfterLimit : Paginate<Simplify$1<Result>> : UnselectedTerminal;
+} : {});
+/** `paginate()` after `limit()` or `offset()` reports why as its required `this` type. */
+type PaginateAfterLimit = (this: typeof PAGINATE_AFTER_LIMIT_MESSAGE, ...arguments_: readonly unknown[]) => never;
+/** The `paginate()` overloads for one item type. */
+type Paginate<Item> = {
+  (options: PageOptions): Promise<NumberedPage<Item>>;
+  (options: CursorOptions & {
+    total: true;
+  }): Promise<CursorPage<Item, true>>;
+  (options: CursorOptions): Promise<CursorPage<Item>>;
+};
+/** Page-number pagination: `page` starts at 1 and `size` is the number of entries per page. */
+type PageOptions = {
+  page: number;
+  size: number;
+  after?: never;
+  before?: never;
+  total?: never;
+};
+/**
+ * Cursor pagination. `after` continues from an earlier page's `endCursor`; `before` returns the
+ * entries just before a `startCursor`. A `null` cursor starts at the first entry (`after`) or the
+ * last entry (`before`). `total: true` adds the matching total.
+ */
+type CursorOptions = {
+  size: number;
+  page?: never;
+  total?: boolean;
+} & ({
+  after?: string | null;
+  before?: never;
+} | {
+  before?: string | null;
+  after?: never;
+});
+/** Options accepted by `paginate()`. */
+type PaginateOptions = PageOptions | CursorOptions;
+/** Option names that `paginate()` reads alongside relational query options. */
+type PaginateKey = keyof PageOptions;
+/** One numbered page and where it sits among every matching entry. */
+type NumberedPage<Item> = {
+  items: Item[];
+  /** Matching entries across every page. */
+  total: number;
+  page: number;
+  /** At least 1: the first page exists even when nothing matches. */
+  pageCount: number;
+  hasNextPage: boolean;
+  hasPreviousPage: boolean;
+};
+/** One cursor page. Both cursors are `null` when the page is empty. */
+type CursorPage<Item, Total extends boolean = false> = {
+  items: Item[];
+  /** Pass as `before` for the previous page. */
+  startCursor: string | null;
+  /** Pass as `after` for the next page. */
+  endCursor: string | null;
+  hasNextPage: boolean;
+  hasPreviousPage: boolean;
+} & (Total extends true ? {
+  total: number;
 } : {});
+/** The page type `paginate()` returns for the given options. */
+type PaginateResult<Item, Options> = Options extends {
+  page: number;
+} ? NumberedPage<Item> : CursorPage<Item, Options extends {
+  total: true;
+} ? true : false>;
 type Adjacent<Entry> = {
   previous: Entry | null;
   next: Entry | null;
@@ -197,9 +304,11 @@ type Selection<Registry extends CollectionRegistry, Name extends keyof Registry
 type ObjectRelationValue<Registry extends CollectionRegistry, Name extends keyof Registry & string, Key extends keyof RelationshipsOf<Registry[Name]>, Options> = Options extends {
   select: infer Projection;
 } ? RelationValue<Registry[Name], RelationOf<Registry, Name, Key>, QueryInfo<SelectionResult<Registry, RelatedName$1<Registry, RelationOf<Registry, Name, Key>>, Projection>, true, "where" extends keyof Options ? true : false>> : never;
-type SelectionResult<Registry extends CollectionRegistry, Name extends keyof Registry & string, Projection> = { -readonly [Key in keyof Projection as Projection[Key] extends false | undefined ? never : Key]-?: Key extends "_adjacent" ? Projection[Key] extends {
+/** Data fields an object projection requests, excluding relationships and `_adjacent`. */
+type ProjectedFields<Registry extends CollectionRegistry, Name extends keyof Registry & string, Projection> = Exclude<{ [Key in keyof Projection]-?: Projection[Key] extends false | undefined ? never : Key; }[keyof Projection], "_adjacent" | keyof RelationshipsOf<Registry[Name]>> & keyof QueryData<Registry[Name]>;
+type SelectionResult<Registry extends CollectionRegistry, Name extends keyof Registry & string, Projection> = Simplify$1<{ -readonly [Key in keyof Projection as Projection[Key] extends false | undefined ? never : Key extends ProjectedFields<Registry, Name, Projection> ? never : Key]-?: Key extends "_adjacent" ? Projection[Key] extends {
   select: infer Neighbors;
-} ? Adjacent<SelectionResult<Registry, Name, Neighbors>> : never : Key extends keyof RelationshipsOf<Registry[Name]> ? ObjectRelationValue<Registry, Name, Key, Projection[Key]> : Key extends keyof QueryData<Registry[Name]> ? QueryData<Registry[Name]>[Key] : never; };
+} ? Adjacent<SelectionResult<Registry, Name, Neighbors>> : never : Key extends keyof RelationshipsOf<Registry[Name]> ? ObjectRelationValue<Registry, Name, Key, Projection[Key]> : never; } & SelectedData<QueryData<Registry[Name]>, ProjectedFields<Registry, Name, Projection>>>;
 type CheckedField<Value, Filter> = Filter extends Scalar ? Filter : { [Operator in keyof Filter]: Operator extends keyof FieldFilter$1<Value> ? Operator extends "not" ? CheckedField<Value, Filter[Operator]> : Filter[Operator] : never; };
 type CheckedWhereList$1<Data, Filters extends readonly unknown[]> = { [Index in keyof Filters]: CheckedWhere$1<Data, Filters[Index]>; };
 type CheckedWhere$1<Data, Filter> = Filter extends ((...arguments_: never[]) => unknown) ? Filter : { [Key in keyof Filter]: Key extends "AND" | "OR" | "NOT" ? Filter[Key] extends readonly unknown[] ? CheckedWhereList$1<Data, Filter[Key]> : CheckedWhere$1<Data, Filter[Key]> : Key extends keyof Data ? CheckedField<Data[Key], Filter[Key]> : never; };
@@ -289,11 +398,13 @@ type RelationalQueryOptions<Registry extends CollectionRegistry, Name extends ke
   } & RelationalQueryOptions<Registry, Name, true, false, false>);
   payloads?: PayloadOptions<Registry, Name>;
 } : {});
+/** Options accepted by relational `paginate()`: query options without limit or offset, plus a page request. */
+type RelationalPaginateOptions<Registry extends CollectionRegistry, Name extends keyof Registry & string> = RelationalQueryOptions<Registry, Name, true, true, false> & PaginateOptions;
 /** Options accepted by the root count helper, whose result ignores sorting and pagination. */
 type RelationalCountOptions<Registry extends CollectionRegistry, Name extends keyof Registry & string> = Pick<RelationalQueryOptions<Registry, Name>, "where" | "orderBy" | "offset" | "limit">;
 type ColumnResult<Data, Options> = Options extends {
   columns: infer Columns;
-} ? { -readonly [Key in keyof Columns as Columns[Key] extends true ? Key : never]-?: Key extends keyof Data ? Data[Key] : never; } : {};
+} ? SelectedData<Data, { [Key in keyof Columns]-?: Columns[Key] extends true ? Key : never; }[keyof Columns] & keyof Data> : {};
 /** Keys whose option values request something, as opposed to `false` or `undefined`. */
 type Requested<Map> = keyof { [Key in keyof Map as Map[Key] extends false | undefined ? never : Key]: unknown; };
 /** Whether options select fields, include relationships, request payloads, or select adjacency. */
@@ -331,9 +442,9 @@ type RelationalQueryResult<Registry extends CollectionRegistry, Name extends key
 type CheckedConditions<Value, Filters extends readonly unknown[]> = { [Index in keyof Filters]: CheckedCondition<Value, Filters[Index]>; };
 type CheckedCondition<Value, Filter> = Filter extends Scalar ? Filter : { [Key in keyof Filter]: Key extends "AND" | "OR" ? Filter[Key] extends readonly unknown[] ? CheckedConditions<Value, Filter[Key]> : never : Key extends "NOT" ? CheckedCondition<Value, Filter[Key]> : Key extends keyof FieldFilter<Value> ? Filter[Key] : never; };
 type CheckedWhereList<Registry extends CollectionRegistry, Name extends keyof Registry & string, Filters extends readonly unknown[]> = { [Index in keyof Filters]: CheckedWhere<Registry, Name, Filters[Index]>; };
-type CheckedWhere<Registry extends CollectionRegistry, Name extends keyof Registry & string, Filter> = { [Key in keyof Filter]: Key extends "AND" | "OR" | "NOT" ? Filter[Key] extends readonly unknown[] ? CheckedWhereList<Registry, Name, Filter[Key]> : CheckedWhere<Registry, Name, Filter[Key]> : Key extends "RAW" ? Filter[Key] : Key extends keyof RelationshipsOf<Registry[Name]> ? Filter[Key] extends boolean ? Filter[Key] : CheckedWhere<Registry, RelatedName<Registry, Name, Key>, Filter[Key]> : Key extends keyof QueryData<Registry[Name]> ? CheckedCondition<QueryData<Registry[Name]>[Key], Filter[Key]> : never; };
+type CheckedWhere<Registry extends CollectionRegistry, Name extends keyof Registry & string, Filter> = { [Key in keyof Filter]: Key extends "AND" | "OR" | "NOT" ? Filter[Key] extends readonly unknown[] ? CheckedWhereList<Registry, Name, Filter[Key]> : CheckedWhere<Registry, Name, Filter[Key]> : Key extends "RAW" ? Filter[Key] : Key extends keyof RelationshipsOf<Registry[Name]> ? Filter[Key] extends boolean ? Filter[Key] : CheckedWhere<Registry, RelatedName<Registry, Name, Key>, Filter[Key]> : Key extends keyof QueryData<Registry[Name]> ? CheckedCondition<QueryData<Registry[Name]>[Key], Filter[Key]> : UnavailableRelationship<Registry[Name], Key>; };
 /** Rejects unknown options recursively, including options supplied through inferred variables. */
-type CheckedRelationalOptions<Registry extends CollectionRegistry, Name extends keyof Registry & string, Options, Many extends boolean = true, AllowAdjacent extends boolean = true, Pagination extends boolean = true> = { [Key in keyof Options]: Key extends "columns" ? { [Column in keyof Options[Key]]: Column extends keyof QueryData<Registry[Name]> ? Options[Key][Column] : never; } : Key extends "where" ? CheckedWhere<Registry, Name, Options[Key]> : Key extends "with" ? { [Related in keyof Options[Key]]: Related extends keyof RelationshipsOf<Registry[Name]> ? Options[Key][Related] extends false | undefined ? Options[Key][Related] : CheckedRelationalOptions<Registry, RelatedName<Registry, Name, Related>, Options[Key][Related], IsMany<Registry, Name, Related>, AllowAdjacent> & SelectionRequired<Options[Key][Related]> : never; } : Key extends "adjacent" ? AllowAdjacent extends true ? CheckedRelationalOptions<Registry, Name, Omit<Options[Key], "scope">, true, false, false> & SelectionRequired<Options[Key]> & (Options[Key] extends {
+type CheckedRelationalOptions<Registry extends CollectionRegistry, Name extends keyof Registry & string, Options, Many extends boolean = true, AllowAdjacent extends boolean = true, Pagination extends boolean = true> = { [Key in keyof Options]: Key extends "columns" ? { [Column in keyof Options[Key]]: Column extends keyof QueryData<Registry[Name]> ? Options[Key][Column] : never; } : Key extends "where" ? CheckedWhere<Registry, Name, Options[Key]> : Key extends "with" ? { [Related in keyof Options[Key]]: Related extends keyof RelationshipsOf<Registry[Name]> ? Options[Key][Related] extends false | undefined ? Options[Key][Related] : CheckedRelationalOptions<Registry, RelatedName<Registry, Name, Related>, Options[Key][Related], IsMany<Registry, Name, Related>, AllowAdjacent> & SelectionRequired<Options[Key][Related]> : UnavailableRelationship<Registry[Name], Related>; } : Key extends "adjacent" ? AllowAdjacent extends true ? CheckedRelationalOptions<Registry, Name, Omit<Options[Key], "scope">, true, false, false> & SelectionRequired<Options[Key]> & (Options[Key] extends {
   scope: "results";
 } ? {
   scope: "results";
@@ -342,12 +453,19 @@ type CheckedRelationalOptions<Registry extends CollectionRegistry, Name extends
 } : {
   scope?: "collection";
 }) : never : Key extends "payloads" ? AllowAdjacent extends true ? { [Payload in keyof Options[Key]]: Payload extends keyof PayloadsOf<Registry[Name]> ? CheckedPayloadRequest<Options[Key][Payload], VariantOf<Registry[Name], Payload>> : never; } : never : Key extends "orderBy" ? Key extends keyof RelationalQueryOptions<Registry, Name, Many, AllowAdjacent, Pagination> ? { [Field in keyof Options[Key]]: Field extends keyof OrderBy<QueryData<Registry[Name]>> ? Options[Key][Field] : never; } : never : Key extends keyof RelationalQueryOptions<Registry, Name, Many, AllowAdjacent, Pagination> ? Options[Key] : never; };
-/** Typed per-collection query entry points that never expose source configuration at runtime. */
-type RelationalQueries<Registry extends CollectionRegistry> = string extends keyof Registry ? {} : { readonly [Name in keyof Registry & string]: {
+/** One collection's relational queries: `findMany`, `findFirst`, and `paginate`. */
+type RelationalCollectionQueries<Registry extends CollectionRegistry, Name extends keyof Registry & string> = {
   /** Returns matching rows with exactly the selected data. Options must select something. */
   findMany<const Options extends RelationalQueryOptions<Registry, Name>>(options: Options & CheckedRelationalOptions<Registry, Name, NoInfer<Options>> & SelectionRequired<NoInfer<Options>>): Promise<RelationalQueryResult<Registry, Name, Options>[]>;
   /** Returns the first matching row, or undefined when none matches. */
   findFirst<const Options extends RelationalQueryOptions<Registry, Name>>(options: Options & CheckedRelationalOptions<Registry, Name, NoInfer<Options>> & SelectionRequired<NoInfer<Options>>): Promise<RelationalQueryResult<Registry, Name, Options> | undefined>;
-}; };
+  /**
+   * Returns one page from one revision: `page` and `size` for page numbers, or `size` with
+   * `after`, `before`, or `total` for cursors. `limit` and `offset` are unavailable.
+   */
+  paginate<const Options extends RelationalPaginateOptions<Registry, Name>>(options: Options & CheckedRelationalOptions<Registry, Name, NoInfer<Omit<Options, PaginateKey>>, true, true, false> & SelectionRequired<NoInfer<Options>>): Promise<PaginateResult<RelationalQueryResult<Registry, Name, Options>, Options>>;
+};
+/** Typed per-collection query entry points that never expose source configuration at runtime. */
+type RelationalQueries<Registry extends CollectionRegistry> = string extends keyof Registry ? {} : { readonly [Name in keyof Registry & string]: RelationalCollectionQueries<Registry, Name>; };
 //#endregion
-export { Where as _, RelationalWhere as a, QueryRegistry as b, Fields as c, QueryFields as d, RelationField as f, SelectionResult as g, Selection as h, RelationalQueryResult as i, Ordered as l, ScalarField as m, RelationalQueries as n, Adjacent as o, Scalar as p, RelationalQueryOptions as r, Field$1 as s, RelationalCountOptions as t, Query as u, Expression as v, QueryPlan as y };
+export { Selection as C, QueryPlan as D, Expression as E, QueryRegistry as O, ScalarField as S, Where as T, PaginateResult as _, RelationalQueryOptions as a, RelationField as b, Adjacent as c, Field$1 as d, Fields as f, PaginateOptions as g, PageOptions as h, RelationalQueries as i, QueryTerminal as k, CursorOptions as l, Ordered as m, RelationalCountOptions as n, RelationalQueryResult as o, NumberedPage as p, RelationalPaginateOptions as r, RelationalWhere as s, RelationalCollectionQueries as t, CursorPage as u, Query as v, SelectionResult as w, Scalar as x, QueryFields as y };

package/dist/revision-aqGUf6YV.d.mts

@@ -0,0 +1,56 @@
+import { s as ContentError } from "./collection-types-DhIxnCSM.mjs";
+import { n as ContentRenderResult } from "./types-Dh-Sydyw.mjs";
+import { _ as Relationship } from "./types-WOsFmNnN.mjs";
+import { D as QueryPlan, O as QueryRegistry, k as QueryTerminal } from "./relational-types-PtrzENt0.mjs";
+import { n as QueryStyle } from "./query-style-C2FcT1f9.mjs";
+//#region src/runtime/revision.d.ts
+type QueryRecord = Record<string, unknown> & {
+  id: string;
+};
+/** Custom payload loaders by payload name, entry ID, and canonical variant key. */
+type CustomPayloadTable = ReadonlyMap<string, ReadonlyMap<string, ReadonlyMap<string, () => Promise<unknown>>>>;
+/** The built-in side payload shared by an entry's `_body` and `_rendered` payloads. */
+type BuiltinPayload = {
+  body?: string;
+  rendered?: ContentRenderResult;
+  markdown?: string;
+};
+type PreparedCollection = {
+  records: readonly QueryRecord[];
+  relationships: Record<string, Relationship>;
+  /** Lazy built-in payloads, present only for entries with a body or rendered output. */
+  builtins: ReadonlyMap<string, () => Promise<BuiltinPayload>>;
+  /**
+   * Lazy custom payloads by payload name, entry ID, and canonical variant key. A missing variant
+   * key means the entry has no such combination.
+   */
+  payloads?: CustomPayloadTable;
+  sources?: ReadonlyMap<string, string | undefined>;
+};
+type PreparedRevision = {
+  registry: QueryRegistry;
+  collections: Record<string, PreparedCollection>;
+  relations: Map<string, Map<string, readonly QueryRecord[]>>;
+  active: number;
+  /** Built-in payloads keyed by collection and ID; custom payloads also by name and variant. */
+  payloadCache: Map<string, Promise<unknown>>;
+  renderCache: Map<string, Promise<ContentRenderResult>>;
+  renderMarkdown?: (body: string) => Promise<ContentRenderResult>;
+  /** The only query style this revision's configuration allows; absent allows both. */
+  queryStyle?: QueryStyle;
+  execute?: (plan: QueryPlan, terminal: QueryTerminal, requests: PayloadRequest[]) => Promise<unknown>;
+};
+/** A projected row awaiting the payloads its query scope requested. */
+type PayloadRequest = {
+  target: Record<string, unknown>;
+  collection: string;
+  id: string;
+  payloads: NonNullable<QueryPlan["payloads"]>;
+};
+type ContentState = {
+  revision?: PreparedRevision;
+  registry?: QueryRegistry;
+  error?: ContentError;
+};
+//#endregion
+export { PreparedRevision as n, ContentState as t };

package/dist/runtime.d.mts

@@ -1,4 +1,4 @@
-import { a as ContentDiagnostic, o as ContentError, s as ContentErrorCode, t as Content } from "./content-CwTKqRs9.mjs";
+import { c as ContentErrorCode, i as LoadedRegistry, n as Collection, o as ContentDiagnostic, r as CollectionHandles, s as ContentError, t as AnyCollection } from "./collection-types-DhIxnCSM.mjs";
 import { n as ContentRenderResult, t as ContentHeading } from "./types-Dh-Sydyw.mjs";
-import { n as QueryStyle, r as QueryStyleDisabled } from "./query-style-eXENQJ0O.mjs";
-export { type Content, type ContentDiagnostic, ContentError, type ContentErrorCode, type ContentHeading, type ContentRenderResult, type QueryStyle, type QueryStyleDisabled };
+import { n as QueryStyle, r as QueryStyleDisabled } from "./query-style-C2FcT1f9.mjs";
+export { type AnyCollection, type Collection, type CollectionHandles, type ContentDiagnostic, ContentError, type ContentErrorCode, type ContentHeading, type ContentRenderResult, type LoadedRegistry, type QueryStyle, type QueryStyleDisabled };

package/dist/{types-DbFfF6JE.d.mts → types-WOsFmNnN.d.mts}

@@ -4,6 +4,7 @@ import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/collection/types.d.ts
 declare const builtinPayloadsType: unique symbol;
 declare const customPayloadsType: unique symbol;
+declare const loadedCollectionsType: unique symbol;
 type Schema = StandardSchemaV1;
 type SchemaOutput<Value> = Value extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<Value> : Record<string, unknown>;
 /** One file or record that a `files` helper read, shaped like a loader entry. */
@@ -127,6 +128,11 @@ type CollectionDefinition<SourceSchema extends Schema | undefined = Schema | und
   payloads?: Record<string, PayloadDeclaration>;
   /** Directories, relative to the project root, that every entry's `files` helpers may read. */
   sharedFiles?: readonly string[];
+  /**
+   * The singular name in generated types, such as `"Category"` for `ContentCategory`. Defaults to
+   * the export name without one trailing `s`.
+   */
+  typeName?: string;
 };
 type CollectionRegistry = Record<string, CollectionDefinition>;
 type EntryData<Definition> = Definition extends {
@@ -137,12 +143,56 @@ type ComputedData<Definition> = Definition extends {
 } ? { [Name in keyof Computed]: Computed[Name] extends {
   schema: infer ResultSchema;
 } ? SchemaOutput<ResultSchema> : never; } : {};
+/**
+ * An entry's ID, validated metadata, and computed fields. JSDoc comments on schema fields and
+ * computed field names carry through, so editors show them when hovering a field.
+ */
 type QueryData<Definition> = {
+  /** The entry's ID, unique within its collection. */
   id: string;
 } & EntryData<Definition> & ComputedData<Definition>;
+/** Maps `Field` without reading `Data`'s modifiers, so every key is required. */
+type PresentFields<Data, Field extends PropertyKey> = { [Key in Field]: Key extends keyof Data ? Data[Key] : never; };
+/** Flattens an intersection into one mutable object type, keeping each property's declaration. */
+type MutableObject<Value> = { -readonly [Key in keyof Value]: Value[Key]; };
+/**
+ * The shape of `Data` when a query selects `Field`. Every selected key is present and mutable,
+ * and an optional field's value includes `undefined` instead of the key being optional.
+ *
+ * Each property stays linked to its declaration in `Data`, so JSDoc comments written on schema
+ * fields show when hovering a selected field, and go to definition opens the schema.
+ */
+type SelectedData<Data, Field extends keyof Data> = MutableObject<PresentFields<Data, Field> & Pick<Data, Field>>;
+/**
+ * Type-only marker recording which collections a query scope loaded. A marked definition offers
+ * only the relationships whose target is loaded; an unmarked one offers every relationship.
+ */
+type LoadedMarker<Loaded> = {
+  readonly [loadedCollectionsType]?: Loaded;
+};
+/** The collections a marked definition's query scope loaded, or `unknown` when unmarked. */
+type LoadedOf<Definition> = Definition extends {
+  readonly [loadedCollectionsType]?: infer Loaded;
+} ? Loaded : unknown;
+/** The declared relationships, keeping only those into `Loaded` when it is not `unknown`. */
+type RelationshipsInto<Relationships, Loaded, Keep extends boolean> = unknown extends Loaded ? Keep extends true ? Relationships : {} : { [Name in keyof Relationships as (Relationships[Name] extends {
+  collection: Loaded;
+} ? Keep : Keep extends true ? false : true) extends true ? Name : never]: Relationships[Name]; };
+/** Relationships a query can follow: every declared one, or only those into loaded collections. */
 type RelationshipsOf<Definition> = Definition extends {
   relationships: infer Relationships;
-} ? Relationships : {};
+} ? RelationshipsInto<Relationships, LoadedOf<Definition>, true> : {};
+/**
+ * The type error for a declared relationship whose target collection the query has not loaded,
+ * or `never` for a name that is not such a relationship.
+ */
+type UnavailableRelationship<Definition, Name> = Name extends keyof UnavailableRelationshipsOf<Definition> ? UnavailableRelationshipsOf<Definition>[Name] extends {
+  collection: infer Target extends string;
+} ? `Relationship "${Name & string}" targets the ${Target} collection, which this query has not loaded. Pass it to using().` : never : never;
+/** Declared relationships into collections the query scope has not loaded. */
+type UnavailableRelationshipsOf<Definition> = Definition extends {
+  relationships: infer Relationships;
+} ? RelationshipsInto<Relationships, LoadedOf<Definition>, false> : {};
 /**
  * Payloads that Markdown sources, `glob()`, and custom loaders provide for every entry.
  * Built-in names start with an underscore, so they never collide with custom payloads.
@@ -178,4 +228,4 @@ type PayloadData<Definition, Name extends keyof PayloadsOf<Definition>> = Payloa
 /** The variant keys a payload request must supply; empty for built-in and single-value payloads. */
 type VariantOf<Definition, Name> = Name extends keyof CustomPayloadsOf<Definition> ? CustomPayloadsOf<Definition>[Name] extends CustomPayload<unknown, infer Variant> ? Variant : {} : {};
 //#endregion
-export { VariantValues as C, VariantOf as S, RelationshipsOf as _, ComputedContext as a, VariantContext as b, EntryFiles as c, PayloadData as d, PayloadDeclaration as f, Relationship as g, QueryData as h, CollectionRegistry as i, FileEntry as l, PayloadsOf as m, BuiltinPayloads as n, CustomPayload as o, PayloadDefinition as p, CollectionDefinition as r, CustomPayloadMarker as s, BuiltinPayloadMarker as t, PayloadContext as u, Schema as v, VariantField as x, SchemaOutput as y };
+export { UnavailableRelationshipsOf as C, VariantValues as D, VariantOf as E, UnavailableRelationship as S, VariantField as T, Relationship as _, ComputedContext as a, SchemaOutput as b, EntryFiles as c, PayloadContext as d, PayloadData as f, QueryData as g, PayloadsOf as h, CollectionRegistry as i, FileEntry as l, PayloadDefinition as m, BuiltinPayloads as n, CustomPayload as o, PayloadDeclaration as p, CollectionDefinition as r, CustomPayloadMarker as s, BuiltinPayloadMarker as t, LoadedMarker as u, RelationshipsOf as v, VariantContext as w, SelectedData as x, Schema as y };