content-query 0.5.1 → 0.6.1

package/README.md

@@ -78,6 +78,12 @@ An entry imports only its own collection's data, so a route that imports `posts`
 
 Queries return only the data they select, not even `id` implicitly. A query must select fields, include a relationship, request a payload, or select adjacent entries; otherwise it fails to type-check and throws an `invalid-query` error. Counts need no selection.
 
+Later `select()` calls add fields, so a shared builder such as `const postLink = posts.select("id", "title")` can become `postLink.select("publishedAt")` where a page needs more. For detail pages, `posts.byId(id)` starts a query for one entry, and awaiting it returns that entry or `undefined`:
+
+```ts
+const post = await posts.byId("hello").select("title").withPayload("_rendered");
+```
+
 To follow a relationship, pass its target collection to `using()`. Nothing related loads implicitly:
 
 ```ts

package/dist/{build-CIw4yWs9.mjs → build-CfxMqm_9.mjs}

@@ -4,7 +4,7 @@ import { i as detach, l as valuePath, o as encode } from "./values-BbTV4QT-.mjs"
 import { t as assertServerOnly } from "./server-only-CIJUlyL-.mjs";
 import { n as loadFile } from "./file-DSOcdFj0.mjs";
 import { I as collectionNames } from "./operators-D-w1-gDg.mjs";
-import { a as variantKey, c as CODEC_VERSION, i as isQueryStyle, n as createCollections, o as isRelationship, s as prepareRelationships } from "./collection-Cb5eWGnv.mjs";
+import { a as variantKey, c as CODEC_VERSION, i as isQueryStyle, n as createCollections, o as isRelationship, s as prepareRelationships } from "./collection-DYeLLOXP.mjs";
 import { t as renderMarkdown } from "./markdown-CHvBBJNa.mjs";
 import { access, link, mkdir, readFile, readdir, realpath, rm, rmdir, stat, writeFile } from "node:fs/promises";
 import path from "node:path";

package/dist/{build-Aoi7Unm0.d.mts → build-MlsJ12d8.d.mts}

@@ -1,7 +1,7 @@
-import { a as InvalidRelationships, r as CollectionHandles, s as ContentError } from "./collection-types-DhIxnCSM.mjs";
-import { i as CollectionRegistry } from "./types-WOsFmNnN.mjs";
-import { n as QueryStyle } from "./query-style-C2FcT1f9.mjs";
-import "./revision-aqGUf6YV.mjs";
+import { a as InvalidRelationships, r as CollectionHandles, s as ContentError } from "./collection-types-BjSEeKN-.mjs";
+import { i as CollectionRegistry } from "./types-B_p8k_g6.mjs";
+import { n as QueryStyle } from "./query-style-k8Qd7wh5.mjs";
+import "./revision-C7GpzihD.mjs";
 //#region src/preparation/session.d.ts
 /** A local source captured by a successfully prepared content revision. */
 type ContentSourceEntry = Readonly<{

package/dist/build.d.mts

@@ -1,2 +1,2 @@
-import { a as ContentSourceEvent, i as ContentSourceEntry, n as buildContent, o as ContentSourceSnapshot, r as ContentSession, t as BuildContentOptions } from "./build-Aoi7Unm0.mjs";
+import { a as ContentSourceEvent, i as ContentSourceEntry, n as buildContent, o as ContentSourceSnapshot, r as ContentSession, t as BuildContentOptions } from "./build-MlsJ12d8.mjs";
 export { type BuildContentOptions, type ContentSession, type ContentSourceEntry, type ContentSourceEvent, type ContentSourceSnapshot, buildContent };

package/dist/build.mjs

@@ -1 +1 @@
-export { n as buildContent } from "./build-CIw4yWs9.mjs";
+export { n as buildContent } from "./build-CfxMqm_9.mjs";

package/dist/cli.mjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import { o as payloadIdentity, t as ContentError } from "./errors-Bfd0R4_P.mjs";
-import { t as buildAtRoot } from "./build-CIw4yWs9.mjs";
+import { t as buildAtRoot } from "./build-CfxMqm_9.mjs";
 import { cac } from "cac";
 //#region package.json
-var version = "0.5.1";
+var version = "0.6.1";
 //#endregion
 //#region src/integrations/cli/arguments.ts
 /** Validates one path option after CAC's automatic numeric conversion. */

package/dist/{collection-Cb5eWGnv.mjs → collection-DYeLLOXP.mjs}

@@ -320,8 +320,28 @@ function checkedPayload(registry, collection, name, request) {
 		return { variant: {} };
 	}
 	const variant = request;
-	if (!variant || typeof variant !== "object" || Array.isArray(variant) || Object.keys(variant).length !== variants.length || variants.some((key) => !Object.hasOwn(variant, key) || typeof variant[key] !== "string")) invalidQuery(`Payload "${name}" requires exactly these string variant keys: ${variants.join(", ") || "none"}.`);
-	return { variant: Object.fromEntries([...variants].sort().map((key) => [key, variant[key]])) };
+	if (!variant || typeof variant !== "object" || Array.isArray(variant) || Object.keys(variant).length !== variants.length || variants.some((key) => !Object.hasOwn(variant, key) || !isVariantValue(variant[key]))) invalidQuery(`Payload "${name}" requires exactly these variant keys, each a string or a nonempty array of strings: ${variants.join(", ") || "none"}.`);
+	let combinations = [{}];
+	for (const key of Object.keys(variant)) {
+		const values = [variant[key]].flat();
+		combinations = combinations.flatMap((partial) => values.map((value) => ({
+			...partial,
+			[key]: value
+		})));
+	}
+	const sorted = [...variants].sort();
+	const [first, ...fallbacks] = new Map(combinations.map((combination) => {
+		const canonical = Object.fromEntries(sorted.map((key) => [key, combination[key]]));
+		return [JSON.stringify(canonical), canonical];
+	})).values();
+	return fallbacks.length ? {
+		variant: first,
+		fallbacks
+	} : { variant: first };
+}
+/** Checks one variant key's request: a value, or a nonempty list of values to try in order. */
+function isVariantValue(value) {
+	return typeof value === "string" || Array.isArray(value) && value.length > 0 && value.every((item) => typeof item === "string");
 }
 /** Compiles a payloads option into plan requests, omitting payloads set to false. */
 function checkedPayloads(registry, collection, payloads) {
@@ -481,7 +501,10 @@ function objectPlan(registry, collection, options, many = true, allowAdjacent =
 //#region src/query/builder.ts
 const planSymbol = Symbol("content-query.query-plan");
 const scopeSymbol = Symbol("content-query.query-scope");
-/** Creates immutable root or relationship builders over one backend-independent plan. */
+/**
+* Creates immutable root or relationship builders over one backend-independent plan. A root
+* builder that is not `many` is a `byId()` query, which returns one entry or `undefined`.
+*/
 function createBuilder(registry, run, plan, many = true, root = true, scopeToken = {}, allowAdjacent = true, allowPagination = true) {
 	const scope = registry[plan.collection];
 	if (!scope) invalidQuery(`Unknown collection "${plan.collection}".`);
@@ -492,9 +515,12 @@ function createBuilder(registry, run, plan, many = true, root = true, scopeToken
 	const builder = {
 		[planSymbol]: plan,
 		[scopeSymbol]: scopeToken,
+		/** Selects fields, adding to earlier selections; a field selected again is kept once. */
 		select(...fields) {
-			if (plan.select || fields.length === 0) invalidQuery("select() requires distinct prepared fields and can be called once per scope.");
-			return branch({ select: checkedFields(registry, plan.collection, fields) });
+			if (fields.length === 0) invalidQuery("select() requires at least one prepared field.");
+			const checked = checkedFields(registry, plan.collection, fields);
+			const earlier = plan.select ?? [];
+			return branch({ select: [...earlier, ...checked.filter((field) => !earlier.includes(field))] });
 		},
 		where(configure) {
 			if (typeof configure !== "function") invalidQuery("where() requires a configuration callback.");
@@ -503,6 +529,7 @@ function createBuilder(registry, run, plan, many = true, root = true, scopeToken
 			return branch({ filters: [...plan.filters, detach(resolveRelations(registry, plan.collection, expression))] });
 		},
 		orderBy(field, direction = "asc") {
+			assertList("orderBy()");
 			return branch({ order: checkedOrder(plan, field, direction, many) });
 		},
 		limit(value) {
@@ -541,6 +568,7 @@ function createBuilder(registry, run, plan, many = true, root = true, scopeToken
 			if (!allowAdjacent || plan.adjacent !== void 0) invalidQuery("Adjacency cannot be repeated or selected recursively.");
 			const [configure] = arguments_;
 			if (configure === void 0 || typeof configure === "string") {
+				assertList("Results-scope selectAdjacent()");
 				if (!arguments_.length || arguments_.some((field) => typeof field !== "string")) invalidQuery("selectAdjacent() requires neighbor fields, such as selectAdjacent(\"id\"), or a sibling query.");
 				const selection = {
 					...emptyPlan(plan.collection),
@@ -569,11 +597,12 @@ function createBuilder(registry, run, plan, many = true, root = true, scopeToken
 			} });
 		},
 		all() {
+			assertList("all()");
 			return rows("all");
 		},
 		/** Executes a selected root query, matching direct await behavior. */
 		execute() {
-			return rows("all");
+			return rows(many ? "all" : "first");
 		},
 		first() {
 			return rows("first");
@@ -589,6 +618,7 @@ function createBuilder(registry, run, plan, many = true, root = true, scopeToken
 		*/
 		paginate(options) {
 			if (!root) invalidQuery("Nested builders have no terminal methods.");
+			assertList("paginate()");
 			if (!hasSelection(plan)) invalidQuery(NO_SELECTION_MESSAGE);
 			return run({
 				...plan,
@@ -599,7 +629,7 @@ function createBuilder(registry, run, plan, many = true, root = true, scopeToken
 	if (root) Object.defineProperty(builder, "then", { value: (fulfilled, rejected) => {
 		let result;
 		try {
-			result = rows("all");
+			result = rows(many ? "all" : "first");
 		} catch (cause) {
 			result = Promise.reject(cause);
 		}
@@ -614,8 +644,13 @@ function createBuilder(registry, run, plan, many = true, root = true, scopeToken
 		if (!hasSelection(plan)) invalidQuery(NO_SELECTION_MESSAGE);
 		return run(plan, terminal);
 	}
+	/** Rejects a list-only clause or terminal on a `byId()` query, which returns one entry. */
+	function assertList(member) {
+		if (root && !many) invalidQuery(`${member} is unavailable after byId(), which returns one entry.`);
+	}
 	/** Checks pagination before creating an independent branch. */
 	function pagination(key, value) {
+		assertList(`${key}()`);
 		if (!allowPagination || plan[key] !== void 0) invalidQuery("Pagination requires a nonnegative safe integer, one call per clause, and a many-valued scope.");
 		return branch({ [key]: checkedPagination(value, many) });
 	}
@@ -633,9 +668,38 @@ function createBuilder(registry, run, plan, many = true, root = true, scopeToken
 * @returns An immutable, reusable root builder.
 */
 function createFrom(registry, run, collection) {
+	return createBuilder(currentRegistry(registry, collection), run, emptyPlan(collection));
+}
+/**
+* Starts a fluent query for the entry with one ID. The builder returns that entry or `undefined`
+* when awaited, offers no ordering, pagination, `all()`, or results-scope adjacency, and still
+* selects nothing until the query requests data.
+*
+* @param registry - Reads the current query registry, so development builders bind the latest one.
+* @param run - Executes a plan against one pinned revision.
+* @param collection - The collection to query.
+* @param id - The entry's ID.
+* @returns An immutable, reusable single-entry root builder.
+*/
+function createById(registry, run, collection, id) {
+	const current = currentRegistry(registry, collection);
+	if (typeof id !== "string") invalidQuery("byId() requires an entry ID string.");
+	const filter = {
+		kind: "predicate",
+		operator: "eq",
+		field: "id",
+		value: id
+	};
+	return createBuilder(current, run, {
+		...emptyPlan(collection),
+		filters: [filter]
+	}, false);
+}
+/** Reads the registry a new root query binds, rejecting unknown collections. */
+function currentRegistry(registry, collection) {
 	const current = registry();
 	if (typeof collection !== "string" || !Object.hasOwn(current, collection)) invalidQuery(`Unknown collection "${String(collection)}".`);
-	return createBuilder(current, run, emptyPlan(collection));
+	return current;
 }
 //#endregion
 //#region src/query/relational.ts
@@ -1275,20 +1339,29 @@ async function renderedPayload(revision, collection, id) {
 	}
 	return rendered;
 }
-/** Lazily loads one custom payload variant once per revision, retrying after failures. */
-function loadCustom(revision, collection, id, name, variant) {
+/**
+* Lazily loads one custom payload variant once per revision, retrying after failures. The request's
+* combinations are tried in order, and only the first one the entry has is loaded.
+*/
+function loadCustom(revision, collection, id, name, request) {
 	const entries = revision.collections[collection].payloads?.get(name);
 	if (!entries) invalidQuery(`Payload "${name}" no longer matches the prepared collection.`);
-	const load = entries.get(id)?.get(variantKey(variant));
-	if (!load) return Promise.reject(new ContentError({
-		code: "variant-not-found",
-		operation: "query",
-		collection,
-		id,
-		payload: name,
-		variant,
-		message: `Entry "${id}" has no ${payloadIdentity(name, variant)} payload.`
-	}));
+	const candidates = [request.variant, ...request.fallbacks ?? []];
+	const variants = entries.get(id);
+	const variant = candidates.find((candidate) => variants?.has(variantKey(candidate)));
+	const load = variant && variants.get(variantKey(variant));
+	if (!variant || !load) {
+		const tried = candidates.map((candidate) => payloadIdentity(name, candidate));
+		return Promise.reject(new ContentError({
+			code: "variant-not-found",
+			operation: "query",
+			collection,
+			id,
+			payload: name,
+			variant: request.variant,
+			message: tried.length === 1 ? `Entry "${id}" has no ${tried[0]} payload.` : `Entry "${id}" has none of the ${tried.join(", ")} payloads.`
+		}));
+	}
 	const key = JSON.stringify([
 		collection,
 		id,
@@ -1313,10 +1386,10 @@ function loadCustom(revision, collection, id, name, variant) {
 	return loaded;
 }
 /** Loads one requested payload value from the pinned revision. */
-async function loadPayload(revision, collection, id, name, variant) {
+async function loadPayload(revision, collection, id, name, request) {
 	if (name === "_body") return (await loadBuiltin(revision, collection, id)).body;
 	if (name === "_rendered") return renderedPayload(revision, collection, id);
-	return loadCustom(revision, collection, id, name, variant);
+	return loadCustom(revision, collection, id, name, request);
 }
 /**
 * Loads every requested payload with bounded concurrency, then attaches detached copies under
@@ -1336,13 +1409,13 @@ async function attachPayloads(revision, requests) {
 			collection: request.collection,
 			id: request.id,
 			name,
-			variant: request.payloads[name].variant
+			request: request.payloads[name]
 		});
 	}
 	const keys = [...loads.keys()];
 	const values = await mapConcurrent(keys, PAYLOAD_CONCURRENCY, (key) => {
-		const { collection, id, name, variant } = loads.get(key);
-		return loadPayload(revision, collection, id, name, variant);
+		const { collection, id, name, request } = loads.get(key);
+		return loadPayload(revision, collection, id, name, request);
 	});
 	const loaded = new Map(keys.map((key, index) => [key, values[index]]));
 	for (const request of requests) request.target._payloads = Object.fromEntries(Object.keys(request.payloads).map((name) => [name, detach(loaded.get(JSON.stringify([
@@ -1376,6 +1449,7 @@ function createRunner(state) {
 */
 const queryStyleMembers = {
 	fluent: [
+		"byId",
 		"select",
 		"where",
 		"orderBy",
@@ -1602,6 +1676,7 @@ function createCollection(primary, supplied = []) {
 	};
 	for (const member of queryStyleMembers.fluent) handle[member] = (...arguments_) => {
 		allow(member);
+		if (member === "byId") return createById(registry, run, name, arguments_[0]);
 		return createFrom(registry, run, name)[member](...arguments_);
 	};
 	handleSources.set(handle, sources);

package/dist/{collection-types-DhIxnCSM.d.mts → collection-types-BjSEeKN-.d.mts}

@@ -1,6 +1,7 @@
-import { _ as Relationship, g as QueryData, i as CollectionRegistry, u as LoadedMarker, v as RelationshipsOf } from "./types-WOsFmNnN.mjs";
-import { n as RelationalCountOptions, t as RelationalCollectionQueries, v as Query } from "./relational-types-PtrzENt0.mjs";
-import { i as QueryStyleMember, n as QueryStyle, r as QueryStyleDisabled, t as MembersOf } from "./query-style-C2FcT1f9.mjs";
+import { _ as Unavailable } from "./descriptor-BseHJvUB.mjs";
+import { _ as Relationship, g as QueryData, i as CollectionRegistry, u as LoadedMarker, v as RelationshipsOf } from "./types-B_p8k_g6.mjs";
+import { n as RelationalCountOptions, t as RelationalCollectionQueries, v as Query } from "./relational-types-Bh34u01H.mjs";
+import { i as QueryStyleMember, n as QueryStyle, r as QueryStyleDisabled, t as MembersOf } from "./query-style-k8Qd7wh5.mjs";
 //#region src/shared/errors.d.ts
 type ContentErrorCode = "variant-not-found" | "not-renderable" | "source-error" | "validation-error" | "duplicate-id" | "invalid-reference" | "invalid-query" | "invalid-cursor" | "artifact-error" | "render-error";
 type ContentDiagnostic = {
@@ -58,13 +59,23 @@ type LoadedRegistry<Registry extends CollectionRegistry, Loaded extends keyof Re
 type FluentMember = MembersOf<"fluent">;
 /** The relational members, apart from `count`, which both styles share. */
 type RelationalMember = "findMany" | "findFirst" | "paginate";
+/** Fluent starters that only a collection handle offers, not a query builder. */
+type HandleStarters<Registry extends CollectionRegistry, Name extends keyof Registry & string> = {
+  /**
+   * Starts a query for the entry with this ID. Select its data as usual; awaiting the query, or
+   * calling `first()` or `execute()`, returns the entry or `undefined`. Later `where()` filters
+   * also apply. Lookups use the collection's ID index.
+   *
+   * @param id - The entry's ID.
+   * @returns A single-entry root query, without ordering, pagination, `all()`, or results-scope
+   * adjacency.
+   */
+  byId(id: string): Query<Registry, Name, {}, false, false>;
+};
 /** Every member before `queryStyle` gating. */
-type CollectionMethods<Registry extends CollectionRegistry, Name extends keyof Registry & string> = Pick<Query<Registry, Name>, FluentMember & keyof Query<Registry, Name>> & RelationalCollectionQueries<Registry, Name>;
-/**
- * Members outside the allowed style. Calls report the message as the required `this` type,
- * whatever arguments they pass.
- */
-type DisabledMembers<Name extends string, Style extends QueryStyle> = { readonly [Member in Exclude<FluentMember | RelationalMember, MembersOf<Style>>]: (this: QueryStyleDisabled<Name, Member & QueryStyleMember, Style>, ...arguments_: readonly unknown[]) => never; };
+type CollectionMethods<Registry extends CollectionRegistry, Name extends keyof Registry & string> = Pick<Query<Registry, Name>, FluentMember & keyof Query<Registry, Name>> & HandleStarters<Registry, Name> & RelationalCollectionQueries<Registry, Name>;
+/** Members outside the allowed style. They are not callable, and their type gives the message. */
+type DisabledMembers<Name extends string, Style extends QueryStyle> = { readonly [Member in Exclude<FluentMember | RelationalMember, MembersOf<Style>>]: Unavailable<QueryStyleDisabled<Name, Member & QueryStyleMember, Style>>; };
 /** `count()` counts every entry in both styles; options take relational filters. */
 type CountMember<Registry extends CollectionRegistry, Name extends keyof Registry & string, Style extends QueryStyle> = [Style] extends ["fluent"] ? {
   /** Counts every entry. Count filtered entries with `where(...).count()`. */

package/dist/computed.d.mts

@@ -1,6 +1,55 @@
-import { g as MaybePromise } from "./descriptor-bcPa6XLk.mjs";
-import { a as ComputedContext } from "./types-WOsFmNnN.mjs";
+import { g as MaybePromise } from "./descriptor-BseHJvUB.mjs";
+import { a as ComputedContext } from "./types-B_p8k_g6.mjs";
 import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/computed/fields.d.ts
+/** Result schemas for computed fields that one resolver call fills, keyed by field name. */
+type ComputedFieldSchemas = Record<string, StandardSchemaV1>;
+/**
+ * The object a shared resolver returns: one value per field, checked by that field's schema.
+ * Fields whose schema accepts `undefined` may be omitted.
+ */
+type ComputedFieldValues<Fields extends ComputedFieldSchemas> = { [Key in keyof Fields as undefined extends StandardSchemaV1.InferInput<Fields[Key]> ? never : Key]: StandardSchemaV1.InferInput<Fields[Key]>; } & { [Key in keyof Fields as undefined extends StandardSchemaV1.InferInput<Fields[Key]> ? Key : never]?: StandardSchemaV1.InferInput<Fields[Key]>; };
+/** Declares several computed fields and the one resolver that returns all of their values. */
+type ComputedFieldsOptions<Fields extends ComputedFieldSchemas, Data = Record<string, unknown>, Source = unknown> = {
+  /**
+   * Each field's result schema, keyed by field name. A JSDoc comment on a key documents that
+   * field in entry types and query results.
+   */
+  fields: Fields;
+  /**
+   * Returns every field's value for one entry. It runs once per entry each time the entry is
+   * prepared, however many fields it fills; files it reads through `files` are tracked as usual.
+   * Annotate the context, such as `(context: ComputedContext<Post>)`, to type `data`.
+   */
+  resolve(this: void, context: ComputedContext<Data, Source>): MaybePromise<ComputedFieldValues<Fields>>;
+};
+/** The computed field definitions that {@link computedFields} returns, one per declared field. */
+type ComputedFieldDefinitions<Fields extends ComputedFieldSchemas, Data = Record<string, unknown>, Source = unknown> = { [Key in keyof Fields]: {
+  schema: Fields[Key];
+  resolve(context: ComputedContext<Data, Source>): Promise<unknown>;
+}; };
+/**
+ * Creates computed fields that share one resolver call per entry, for values that come from the
+ * same expensive read, such as several properties of one JSON file beside the entry. Spread the
+ * result into `computed`; each field is validated by its own schema and is selected, filtered, and
+ * sorted like any other computed field.
+ *
+ * @example
+ * ```ts
+ * computed: {
+ *   ...computedFields({
+ *     fields: { title: schema.string(), description: schema.string() },
+ *     resolve: async ({ files }) => JSON.parse(await files.text("info/en-US.json")),
+ *   }),
+ * }
+ * ```
+ *
+ * @param options - The fields' result schemas and the resolver that returns their values.
+ * @returns One computed field definition per key of `options.fields`.
+ * @throws TypeError - When `fields` declares no schemas or `resolve` is not a function.
+ */
+export declare function computedFields<const Fields extends ComputedFieldSchemas, Data = Record<string, unknown>, Source = unknown>(options: ComputedFieldsOptions<Fields, Data, Source>): ComputedFieldDefinitions<Fields, Data, Source>;
+//#endregion
 //#region src/computed/text.d.ts
 /** The syntax removed before computing text-derived fields; literal text preserves all characters. */
 type TextFormat = "markdown" | "text" | "html";
@@ -40,4 +89,4 @@ export declare function excerpt<Data = Record<string, unknown>, Source = unknown
   resolve(context: ComputedContext<Data, Source>): Promise<string>;
 };
 //#endregion
-export type { ExcerptOptions, ReadingTimeOptions, TextFormat, TextOptions };
+export type { ComputedFieldDefinitions, ComputedFieldSchemas, ComputedFieldValues, ComputedFieldsOptions, ExcerptOptions, ReadingTimeOptions, TextFormat, TextOptions };

package/dist/computed.mjs

@@ -3,6 +3,63 @@ import { n as number, r as string } from "./schema-C5Str-E8.mjs";
 import { t as src_default } from "./dist-C7_FOzY_.mjs";
 import getReadingTime from "reading-time";
 import { Parser } from "htmlparser2";
+//#region src/computed/fields.ts
+assertServerOnly();
+/**
+* Creates computed fields that share one resolver call per entry, for values that come from the
+* same expensive read, such as several properties of one JSON file beside the entry. Spread the
+* result into `computed`; each field is validated by its own schema and is selected, filtered, and
+* sorted like any other computed field.
+*
+* @example
+* ```ts
+* computed: {
+*   ...computedFields({
+*     fields: { title: schema.string(), description: schema.string() },
+*     resolve: async ({ files }) => JSON.parse(await files.text("info/en-US.json")),
+*   }),
+* }
+* ```
+*
+* @param options - The fields' result schemas and the resolver that returns their values.
+* @returns One computed field definition per key of `options.fields`.
+* @throws TypeError - When `fields` declares no schemas or `resolve` is not a function.
+*/
+function computedFields(options) {
+	const { fields, resolve } = options ?? {};
+	if (!fields || typeof fields !== "object" || Array.isArray(fields)) throw new TypeError("computedFields() fields must be an object of result schemas.");
+	const entries = Object.entries(fields);
+	if (!entries.length || entries.some(([, schema]) => !isSchema(schema))) throw new TypeError("computedFields() fields must declare at least one field, each with a Standard Schema.");
+	if (typeof resolve !== "function") throw new TypeError("computedFields() resolve must be a function.");
+	const resolutions = /* @__PURE__ */ new WeakMap();
+	/** Resolves every field's value once for the entry being prepared. */
+	function values(context) {
+		let pending = resolutions.get(context.files);
+		if (!pending) {
+			pending = (async () => {
+				context.signal.throwIfAborted();
+				const result = await resolve(context);
+				if (!result || typeof result !== "object" || Array.isArray(result)) throw new TypeError("computedFields() resolve must return an object with a value for each field.");
+				return result;
+			})();
+			resolutions.set(context.files, pending);
+		}
+		return pending;
+	}
+	return Object.fromEntries(entries.map(([name, schema]) => [name, {
+		schema,
+		/** Reads this field's value from the entry's shared resolution. */
+		async resolve(context) {
+			const result = await values(context);
+			return Object.hasOwn(result, name) ? result[name] : void 0;
+		}
+	}]));
+}
+/** Checks for a Standard Schema V1 validator. */
+function isSchema(value) {
+	return (typeof value === "object" || typeof value === "function") && value !== null && "~standard" in value;
+}
+//#endregion
 //#region src/computed/plain-text.ts
 const markdown = new src_default({ html: true });
 const ignoredElements = /* @__PURE__ */ new Set([
@@ -136,4 +193,4 @@ function excerpt(options = {}) {
 	return textField(string(), options, (text) => truncate(text, maxLength));
 }
 //#endregion
-export { excerpt, readingTime, wordCount };
+export { computedFields, excerpt, readingTime, wordCount };

package/dist/{descriptor-bcPa6XLk.d.mts → descriptor-BseHJvUB.d.mts}

@@ -1,6 +1,12 @@
 import { r as RenderedContent } from "./types-Dh-Sydyw.mjs";
 //#region src/shared/types.d.ts
 type MaybePromise<Value> = Value | Promise<Value>;
+/**
+ * The type of a member that a query or configuration does not allow. It has no call signatures,
+ * so calling the member fails with the reason near the start of the error:
+ * `This expression is not callable. Type 'Unavailable<"…">' has no call signatures.`
+ */
+type Unavailable<Reason extends string> = { readonly [Key in Reason]: never; };
 //#endregion
 //#region src/loaders/types.d.ts
 declare const loaderSourceType: unique symbol;
@@ -165,4 +171,4 @@ type FileOptions = {
   parser?: (text: string) => MaybePromise<unknown>;
 };
 //#endregion
-export { DataStore as a, Loader as c, LoaderLogger as d, LoaderSource as f, MaybePromise as g, RecordLoader as h, DataEntry as i, LoaderConfig as l, MetaStore as m, GlobOptions as n, FileEntrySource as o, LoaderWatcher as p, BodyLoader as r, FileSource as s, FileOptions as t, LoaderContext as u };
+export { Unavailable as _, DataStore as a, Loader as c, LoaderLogger as d, LoaderSource as f, MaybePromise as g, RecordLoader as h, DataEntry as i, LoaderConfig as l, MetaStore as m, GlobOptions as n, FileEntrySource as o, LoaderWatcher as p, BodyLoader as r, FileSource as s, FileOptions as t, LoaderContext as u };

package/dist/index.d.mts

@@ -1,7 +1,7 @@
-import { a as DataStore, c as Loader, d as LoaderLogger, f as LoaderSource, g as MaybePromise, h as RecordLoader, i as DataEntry, l as LoaderConfig, m as MetaStore, n as GlobOptions, o as FileEntrySource, p as LoaderWatcher, r as BodyLoader, s as FileSource, u as LoaderContext } from "./descriptor-bcPa6XLk.mjs";
+import { a as DataStore, c as Loader, d as LoaderLogger, f as LoaderSource, g as MaybePromise, h as RecordLoader, i as DataEntry, l as LoaderConfig, m as MetaStore, n as GlobOptions, o as FileEntrySource, p as LoaderWatcher, r as BodyLoader, s as FileSource, u as LoaderContext } from "./descriptor-BseHJvUB.mjs";
 import { n as ContentRenderResult, r as RenderedContent, t as ContentHeading } from "./types-Dh-Sydyw.mjs";
-import { D as VariantValues, E as VariantOf, T as VariantField, _ as Relationship, a as ComputedContext, b as SchemaOutput, c as EntryFiles, d as PayloadContext, f as PayloadData, g as QueryData, h as PayloadsOf, i as CollectionRegistry, l as FileEntry, m as PayloadDefinition, n as BuiltinPayloads, o as CustomPayload, p as PayloadDeclaration, r as CollectionDefinition, s as CustomPayloadMarker, t as BuiltinPayloadMarker, w as VariantContext, x as SelectedData, y as Schema } from "./types-WOsFmNnN.mjs";
-import { n as QueryStyle } from "./query-style-C2FcT1f9.mjs";
+import { D as VariantRequest, E as VariantOf, O as VariantValues, T as VariantField, _ as Relationship, a as ComputedContext, b as SchemaOutput, c as EntryFiles, d as PayloadContext, f as PayloadData, g as QueryData, h as PayloadsOf, i as CollectionRegistry, l as FileEntry, m as PayloadDefinition, n as BuiltinPayloads, o as CustomPayload, p as PayloadDeclaration, r as CollectionDefinition, s as CustomPayloadMarker, t as BuiltinPayloadMarker, w as VariantContext, x as SelectedData, y as Schema } from "./types-B_p8k_g6.mjs";
+import { n as QueryStyle } from "./query-style-k8Qd7wh5.mjs";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/collection/source.d.ts
 type CollectionSource = string | ({
@@ -134,4 +134,4 @@ export declare function defineCollection<const SourceSchema extends StandardSche
  */
 export declare function defineCollection<const SourceSchema extends StandardSchemaV1<unknown, Record<string, unknown>> | undefined = undefined, const ComputedSchemas extends Record<string, Schema> = {}, const Relationships extends Record<string, Relationship> = {}, const PayloadSchemas extends Record<string, Schema> = {}, const PayloadVariants extends Record<string, unknown> = {}, const ContentLoader extends Loader = Loader>(definition: Definition<SourceSchema, ComputedSchemas, Relationships, PayloadSchemas, PayloadVariants, ContentLoader>): Defined<SourceSchema, ComputedSchemas, Relationships, PayloadSchemas, PayloadVariants, ContentLoader> & BuiltinPayloadMarker<[ContentLoader] extends [RecordLoader] ? never : [ContentLoader] extends [BodyLoader] ? "_body" : keyof BuiltinPayloads>;
 //#endregion
-export type { BodyLoader, BuiltinPayloads, CollectionDefinition, CollectionRegistry, CollectionSource, ComputedContext, ContentHeading, ContentRenderResult, DataEntry, DataStore, EntryFiles, FileEntry, FileEntrySource, FileSource, Loader, LoaderConfig, LoaderContext, LoaderLogger, LoaderSource, LoaderWatcher, MaybePromise, MetaStore, PayloadContext, PayloadData, PayloadDeclaration, PayloadDefinition, PayloadsOf, QueryData, QueryStyle, RecordLoader, Relationship, RenderedContent, SelectedData, VariantContext, VariantField, VariantOf, VariantValues };
+export type { BodyLoader, BuiltinPayloads, CollectionDefinition, CollectionRegistry, CollectionSource, ComputedContext, ContentHeading, ContentRenderResult, DataEntry, DataStore, EntryFiles, FileEntry, FileEntrySource, FileSource, Loader, LoaderConfig, LoaderContext, LoaderLogger, LoaderSource, LoaderWatcher, MaybePromise, MetaStore, PayloadContext, PayloadData, PayloadDeclaration, PayloadDefinition, PayloadsOf, QueryData, QueryStyle, RecordLoader, Relationship, RenderedContent, SelectedData, VariantContext, VariantField, VariantOf, VariantRequest, VariantValues };

package/dist/internal.d.mts

@@ -1,9 +1,9 @@
-import { n as Collection, r as CollectionHandles, s as ContentError } from "./collection-types-DhIxnCSM.mjs";
+import { n as Collection, r as CollectionHandles, s as ContentError } from "./collection-types-BjSEeKN-.mjs";
 import { n as ContentRenderResult } from "./types-Dh-Sydyw.mjs";
-import { i as CollectionRegistry } from "./types-WOsFmNnN.mjs";
-import { O as QueryRegistry } from "./relational-types-PtrzENt0.mjs";
-import { n as QueryStyle } from "./query-style-C2FcT1f9.mjs";
-import { n as PreparedRevision, t as ContentState } from "./revision-aqGUf6YV.mjs";
+import { i as CollectionRegistry } from "./types-B_p8k_g6.mjs";
+import { O as QueryRegistry } from "./relational-types-Bh34u01H.mjs";
+import { n as QueryStyle } from "./query-style-k8Qd7wh5.mjs";
+import { n as PreparedRevision, t as ContentState } from "./revision-C7GpzihD.mjs";
 //#region src/artifacts/types.d.ts
 type ArtifactManifest = {
   version: number;

package/dist/internal.mjs

@@ -1,6 +1,6 @@
 import { t as ContentError } from "./errors-Bfd0R4_P.mjs";
 import { r as decode } from "./values-BbTV4QT-.mjs";
-import { i as isQueryStyle, n as createCollections, r as createLiveCollection, t as createCollection } from "./collection-Cb5eWGnv.mjs";
+import { i as isQueryStyle, n as createCollections, r as createLiveCollection, t as createCollection } from "./collection-DYeLLOXP.mjs";
 import { t as restoreContentError } from "./diagnostics-DmUZtrJ6.mjs";
 //#region src/artifacts/runtime.ts
 /** Checks that a value is a plain record before reading generated payload tables from it. */

package/dist/loaders.d.mts

@@ -1,4 +1,4 @@
-import { a as DataStore, c as Loader, d as LoaderLogger, f as LoaderSource, h as RecordLoader, i as DataEntry, l as LoaderConfig, m as MetaStore, n as GlobOptions, o as FileEntrySource, p as LoaderWatcher, r as BodyLoader, s as FileSource, t as FileOptions, u as LoaderContext } from "./descriptor-bcPa6XLk.mjs";
+import { a as DataStore, c as Loader, d as LoaderLogger, f as LoaderSource, h as RecordLoader, i as DataEntry, l as LoaderConfig, m as MetaStore, n as GlobOptions, o as FileEntrySource, p as LoaderWatcher, r as BodyLoader, s as FileSource, t as FileOptions, u as LoaderContext } from "./descriptor-BseHJvUB.mjs";
 //#region src/loaders/file.d.ts
 /** Declares a multi-entry data file with typed source paths and record keys, plus an optional parser. */
 export declare function file(filename: string, options?: FileOptions): RecordLoader<FileEntrySource>;

package/dist/next.d.mts

@@ -1,4 +1,4 @@
-import { t as BuildContentOptions } from "./build-Aoi7Unm0.mjs";
+import { t as BuildContentOptions } from "./build-MlsJ12d8.mjs";
 import { NextConfig } from "next";
 //#region src/integrations/next/plugin.d.ts
 /** Content locations for Next.js; the adapter chooses generated storage and the watch lifecycle. */

package/dist/next.mjs

@@ -1,5 +1,5 @@
 import { I as collectionNames } from "./operators-D-w1-gDg.mjs";
-import { c as collectionDeclarations, i as resolveConfigPath, t as buildAtRoot } from "./build-CIw4yWs9.mjs";
+import { c as collectionDeclarations, i as resolveConfigPath, t as buildAtRoot } from "./build-CfxMqm_9.mjs";
 import { n as serializeContentError } from "./diagnostics-DmUZtrJ6.mjs";
 import path from "node:path";
 import { randomUUID } from "node:crypto";

package/dist/{query-style-C2FcT1f9.d.mts → query-style-k8Qd7wh5.d.mts}

@@ -7,7 +7,7 @@ type QueryStyle = "fluent" | "relational";
  * belongs to both styles; `count(options)` takes relational options.
  */
 declare const queryStyleMembers: {
-  readonly fluent: readonly ["select", "where", "orderBy", "limit", "offset", "with", "withPayload", "selectAdjacent"];
+  readonly fluent: readonly ["byId", "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. */

package/dist/query.d.mts

@@ -1,4 +1,4 @@
-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";
+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-Bh34u01H.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;

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

@@ -1,4 +1,5 @@
-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";
+import { _ as Unavailable } from "./descriptor-BseHJvUB.mjs";
+import { C as UnavailableRelationshipsOf, D as VariantRequest, 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-B_p8k_g6.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 = {
@@ -67,9 +68,13 @@ type AdjacentPlan = {
   scope: "results" | "collection";
   plan: QueryPlan;
 };
-/** One requested payload; variant keys are empty for payloads without variants. */
+/**
+ * One requested payload; variant keys are empty for payloads without variants. `fallbacks` lists
+ * further combinations to try, in order, when the entry lacks `variant`.
+ */
 type PlanPayload = {
   variant: Readonly<Record<string, string>>;
+  fallbacks?: readonly Readonly<Record<string, string>>[];
 };
 /** How a plan returns its results; `paginate` requires the plan's `paginate` request. */
 type QueryTerminal = "all" | "first" | "count" | "paginate";
@@ -96,8 +101,6 @@ declare const PAGINATE_AFTER_LIMIT_MESSAGE: "paginate() sets the limit and offse
 //#endregion
 //#region src/query/types.d.ts
 declare const queryType: unique symbol;
-/** Running an unselected query reports the explicit-selection rule as its required `this` type. */
-type UnselectedTerminal = (this: typeof NO_SELECTION_MESSAGE, ...arguments_: readonly unknown[]) => never;
 /** A `then` that cannot resolve a value, so awaiting an unselected query fails to compile. */
 type UnselectedThen = (selectBeforeAwaiting: typeof NO_SELECTION_MESSAGE) => never;
 declare const fieldType: unique symbol;
@@ -127,12 +130,23 @@ type QueryInfo<Result = unknown, Selected extends boolean = boolean, Filtered ex
     filtered: Filtered;
   };
 };
-type Simplify$1<Value> = { [Key in keyof Value]: Value[Key]; };
-/** Adds one requested payload to a result's `_payloads`, keeping earlier requests. */
-type WithPayload<Result, Key extends PropertyKey, Value> = Omit<Result, "_payloads"> & {
-  _payloads: Simplify$1<(Result extends {
-    _payloads: infer Existing;
-  } ? Existing : {}) & { [Name in Key]: Value; }>;
+/**
+ * Flattens an intersection into one object type, keeping each property's declaration. The
+ * conditional resolves to a mapped type that no alias owns, so TypeScript compares two rows by
+ * their properties instead of by the collection definitions in their type arguments. Comparing
+ * those definitions computes variances deep inside schema libraries such as Zod, which can exceed
+ * the instantiation limit when `Promise.all()` or `Awaited` infers a query's result.
+ */
+type Simplify$1<Value> = Value extends (infer Shape) ? { [Key in keyof Shape]: Shape[Key]; } : never;
+/** One returned entry: the accumulated result, flattened, with its `_payloads` flattened too. */
+type Row<Result> = Result extends (infer Shape) ? { [Key in keyof Shape]: Key extends "_payloads" ? Simplify$1<Shape[Key]> : Shape[Key]; } : never;
+/**
+ * Adds one requested payload under `_payloads`. Intersecting with earlier requests merges their
+ * `_payloads` objects; {@link Row} flattens them when the query returns. Unlike `Omit`, this adds
+ * no type that later calls must re-evaluate, so long chains stay cheap to check.
+ */
+type WithPayload<Result, Key extends PropertyKey, Value> = Result & {
+  _payloads: { [Name in Key]: Value; };
 };
 type ResultOf<Configured> = Configured extends QueryInfo<infer Result> ? Result : never;
 type FilteredOf<Configured> = Configured extends QueryInfo<unknown, boolean, infer Filtered> ? Filtered : false;
@@ -140,9 +154,10 @@ type RelationOf<Registry extends CollectionRegistry, Name extends keyof Registry
 type RelatedName$1<Registry extends CollectionRegistry, Relation extends Relationship> = Relation["collection"] & keyof Registry & string;
 /** 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 RelationValue<Definition, Relation extends Relationship, Configured> = RelationshipResult<Definition, Relation, Row<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, 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>;
+  /** Selects fields, adding to fields that earlier `select()` calls on this scope selected. */
+  select<const Keys extends readonly [keyof QueryData<Registry[Name]> & string, ...(keyof QueryData<Registry[Name]> & string)[]]>(...keys: Keys): Query<Registry, Name, Simplify$1<Result & 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. */
@@ -152,36 +167,42 @@ type Query<Registry extends CollectionRegistry, Name extends keyof Registry & st
 } : {}) & (Many extends true ? Pagination extends true ? {
   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, Paged>;
+} : {} : {}) & (AllowAdjacent extends true ? [Root, Many] extends [true, false] ? {} : {
   /** 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<SelectedData<QueryData<Registry[Name]>, Keys[number]>>;
   }, true, Many, Root, Filtered, AllowAdjacent, Pagination, Paged>;
+} : {}) & (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: VariantRequest<VariantOf<Registry[Name], Key>>]): Query<Registry, Name, WithPayload<Result, Key, PayloadsOf<Registry[Name]>[Key]>, true, Many, Root, Filtered, AllowAdjacent, Pagination, Paged>;
+  /** Selects neighbors from an independent sibling scope. */
   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, 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, Paged>;
-} : {}) & (Root extends true ? {
-  all: Selected extends true ? () => Promise<Simplify$1<Result>[]> : UnselectedTerminal;
-  execute: Selected extends true ? () => Promise<Simplify$1<Result>[]> : UnselectedTerminal;
-  then: Selected extends true ? Promise<Simplify$1<Result>[]>["then"] : UnselectedThen;
-  first: Selected extends true ? () => Promise<Simplify$1<Result> | undefined> : UnselectedTerminal;
-  /** Counts matching entries without a selection; unavailable once payloads are requested. */
-  count: [Result] extends [never] ? () => Promise<number> : [Result] extends [{
-    _payloads: unknown;
-  }] ? never : () => Promise<number>;
+} : {}) & (Root extends true ? (Many extends true ? {
+  all: Selected extends true ? () => Promise<Row<Result>[]> : Unavailable<typeof NO_SELECTION_MESSAGE>;
+  execute: Selected extends true ? () => Promise<Row<Result>[]> : Unavailable<typeof NO_SELECTION_MESSAGE>;
+  then: Selected extends true ? Promise<Row<Result>[]>["then"] : UnselectedThen;
   /**
    * Returns one page from one revision: `{ page, size }` for page numbers, or
-   * `{ size, after?, before?, total? }` for cursors. Unavailable after `limit()` or `offset()`.
+   * `{ 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: Selected extends true ? [Paged] extends [true] ? Unavailable<typeof PAGINATE_AFTER_LIMIT_MESSAGE> : Paginate<Row<Result>> : Unavailable<typeof NO_SELECTION_MESSAGE>;
+} : {
+  /** Runs a `byId()` query, matching direct await: the entry, or `undefined`. */
+  execute: Selected extends true ? () => Promise<Row<Result> | undefined> : Unavailable<typeof NO_SELECTION_MESSAGE>;
+  then: Selected extends true ? Promise<Row<Result> | undefined>["then"] : UnselectedThen;
+}) & {
+  first: Selected extends true ? () => Promise<Row<Result> | undefined> : Unavailable<typeof NO_SELECTION_MESSAGE>;
+  /** Counts matching entries without a selection; unavailable once payloads are requested. */
+  count: [Result] extends [never] ? () => Promise<number> : [Result] extends [{
+    _payloads: unknown;
+  }] ? Unavailable<"Counts cannot request payloads; count without withPayload()."> : () => Promise<number>;
 } : {});
-/** `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>>;
@@ -364,12 +385,15 @@ type RelationalWhere<Registry extends CollectionRegistry, Name extends keyof Reg
   NOT?: RelationalWhere<Registry, Name> | readonly RelationalWhere<Registry, Name>[];
   RAW?: (fields: Fields<QueryData<Registry[Name]>>) => Expression;
 };
-/** Requests one payload: `true` without variants, or a record giving every variant key. */
-type PayloadRequest<Variant> = keyof Variant extends never ? true : Readonly<Variant>;
+/**
+ * Requests one payload: `true` without variants, or a record giving every variant key a value or
+ * a nonempty list of values to try in order.
+ */
+type PayloadRequest<Variant> = keyof Variant extends never ? true : VariantRequest<Variant>;
 /** Payloads to attach under `_payloads`; payloads set to false are omitted. */
 type PayloadOptions<Registry extends CollectionRegistry, Name extends keyof Registry & string> = { [Key in keyof PayloadsOf<Registry[Name]>]?: false | PayloadRequest<VariantOf<Registry[Name], Key>>; };
 /** Rejects variant keys a payload does not declare, including through inferred variables. */
-type CheckedPayloadRequest<Request, Variant> = Request extends boolean ? Request : { [Key in keyof Request]: Key extends keyof Variant ? string : never; };
+type CheckedPayloadRequest<Request, Variant> = Request extends boolean ? Request : { [Key in keyof Request]: Key extends keyof Variant ? string | readonly [string, ...string[]] : never; };
 /**
  * Collection-scoped metadata queries with Drizzle-style columns, relationships, and filters.
  * Nothing is selected implicitly, not even `id`: list fields in `columns`, include relationships

package/dist/{revision-aqGUf6YV.d.mts → revision-C7GpzihD.d.mts}

@@ -1,8 +1,8 @@
-import { s as ContentError } from "./collection-types-DhIxnCSM.mjs";
+import { s as ContentError } from "./collection-types-BjSEeKN-.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";
+import { _ as Relationship } from "./types-B_p8k_g6.mjs";
+import { D as QueryPlan, O as QueryRegistry, k as QueryTerminal } from "./relational-types-Bh34u01H.mjs";
+import { n as QueryStyle } from "./query-style-k8Qd7wh5.mjs";
 //#region src/runtime/revision.d.ts
 type QueryRecord = Record<string, unknown> & {
   id: string;

package/dist/runtime.d.mts

@@ -1,4 +1,5 @@
-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 { c as ContentErrorCode, i as LoadedRegistry, n as Collection, o as ContentDiagnostic, r as CollectionHandles, s as ContentError, t as AnyCollection } from "./collection-types-BjSEeKN-.mjs";
+import { _ as Unavailable } from "./descriptor-BseHJvUB.mjs";
 import { n as ContentRenderResult, t as ContentHeading } from "./types-Dh-Sydyw.mjs";
-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 };
+import { n as QueryStyle, r as QueryStyleDisabled } from "./query-style-k8Qd7wh5.mjs";
+export { type AnyCollection, type Collection, type CollectionHandles, type ContentDiagnostic, ContentError, type ContentErrorCode, type ContentHeading, type ContentRenderResult, type LoadedRegistry, type QueryStyle, type QueryStyleDisabled, type Unavailable };

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

@@ -1,4 +1,4 @@
-import { c as Loader, n as GlobOptions, t as FileOptions } from "./descriptor-bcPa6XLk.mjs";
+import { c as Loader, n as GlobOptions, t as FileOptions } from "./descriptor-BseHJvUB.mjs";
 import { n as ContentRenderResult, r as RenderedContent } from "./types-Dh-Sydyw.mjs";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/collection/types.d.ts
@@ -227,5 +227,11 @@ type PayloadsOf<Definition> = (Definition extends {
 type PayloadData<Definition, Name extends keyof PayloadsOf<Definition>> = PayloadsOf<Definition>[Name];
 /** 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 : {} : {};
+/**
+ * How a query requests a payload variant: each key gives one value, or a nonempty list of values
+ * to try in order, such as `{ locale: ["fr-FR", "en-US"] }`. The query returns the first
+ * combination the entry has; with lists for several keys, earlier keys change slowest.
+ */
+type VariantRequest<Variant> = { readonly [Key in keyof Variant]: Variant[Key] | readonly [Variant[Key], ...Variant[Key][]]; };
 //#endregion
-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 };
+export { UnavailableRelationshipsOf as C, VariantRequest as D, VariantOf as E, VariantValues as O, 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 };

package/dist/vite.d.mts

@@ -1,4 +1,4 @@
-import { a as ContentSourceEvent, o as ContentSourceSnapshot, t as BuildContentOptions } from "./build-Aoi7Unm0.mjs";
+import { a as ContentSourceEvent, o as ContentSourceSnapshot, t as BuildContentOptions } from "./build-MlsJ12d8.mjs";
 import { Plugin } from "vite";
 //#region src/integrations/vite/plugin.d.ts
 /** Public, format-neutral hooks for integrations sharing this plugin's preparation session. */

package/dist/vite.mjs

@@ -1,5 +1,5 @@
 import { I as collectionNames } from "./operators-D-w1-gDg.mjs";
-import { a as sessionInternals, i as resolveConfigPath, l as virtualDeclarations, o as withinDirectory, r as configCandidates, s as writeChanged, t as buildAtRoot, u as revisionModules } from "./build-CIw4yWs9.mjs";
+import { a as sessionInternals, i as resolveConfigPath, l as virtualDeclarations, o as withinDirectory, r as configCandidates, s as writeChanged, t as buildAtRoot, u as revisionModules } from "./build-CfxMqm_9.mjs";
 import { n as serializeContentError } from "./diagnostics-DmUZtrJ6.mjs";
 import { createRequire } from "node:module";
 import path from "node:path";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "content-query",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "description": "Typed, framework-independent content collections, queries, and rendering.",
   "homepage": "https://github.com/yangshun/content-query#readme",
   "bugs": {