content-query 0.6.0 → 0.6.1

package/dist/{build-DYw3z9ju.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-txOFpidL.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-DE4ZKHZR.d.mts → build-MlsJ12d8.d.mts}

@@ -1,7 +1,7 @@
-import { a as InvalidRelationships, r as CollectionHandles, s as ContentError } from "./collection-types-Ch4YLG8t.mjs";
-import { i as CollectionRegistry } from "./types-WOsFmNnN.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-vhe9gRyk.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-DE4ZKHZR.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-DYw3z9ju.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-DYw3z9ju.mjs";
+import { t as buildAtRoot } from "./build-CfxMqm_9.mjs";
 import { cac } from "cac";
 //#region package.json
-var version = "0.6.0";
+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-txOFpidL.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) {
@@ -1319,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,
@@ -1357,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
@@ -1380,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([

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

@@ -1,5 +1,6 @@
-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-DnI9wR5r.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";
@@ -73,11 +74,8 @@ type HandleStarters<Registry extends CollectionRegistry, Name extends keyof Regi
 };
 /** Every member before `queryStyle` gating. */
 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. 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; };
+/** 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,5 +1,5 @@
-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. */

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,6 +1,6 @@
-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 { 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
@@ -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-Ch4YLG8t.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-DnI9wR5r.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-vhe9gRyk.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-txOFpidL.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-DE4ZKHZR.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-DYw3z9ju.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.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-DnI9wR5r.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-DnI9wR5r.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,7 +154,7 @@ 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> & {
   /** 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>;
@@ -160,7 +174,7 @@ type Query<Registry extends CollectionRegistry, Name extends keyof Registry & st
   }, 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: Readonly<VariantOf<Registry[Name], Key>>]): Query<Registry, Name, WithPayload<Result, Key, PayloadsOf<Registry[Name]>[Key]>, true, Many, Root, Filtered, AllowAdjacent, Pagination, Paged>;
+  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>>;
@@ -169,28 +183,26 @@ type Query<Registry extends CollectionRegistry, Name extends keyof Registry & st
     _adjacent: Adjacent<SelectionResult<Registry, Name, Options["select"]>>;
   }, true, Many, Root, Filtered, AllowAdjacent, Pagination, Paged>;
 } : {}) & (Root extends true ? (Many 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;
+  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()`.
    */
-  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<Simplify$1<Result> | undefined> : UnselectedTerminal;
-  then: Selected extends true ? Promise<Simplify$1<Result> | undefined>["then"] : UnselectedThen;
+  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<Simplify$1<Result> | undefined> : UnselectedTerminal;
+  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;
-  }] ? never : () => Promise<number>;
+  }] ? 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>>;
@@ -373,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-vhe9gRyk.d.mts → revision-C7GpzihD.d.mts}

@@ -1,7 +1,7 @@
-import { s as ContentError } from "./collection-types-Ch4YLG8t.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-DnI9wR5r.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> & {

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-Ch4YLG8t.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-k8Qd7wh5.mjs";
-export { type AnyCollection, type Collection, type CollectionHandles, type ContentDiagnostic, ContentError, type ContentErrorCode, type ContentHeading, type ContentRenderResult, type LoadedRegistry, type QueryStyle, type QueryStyleDisabled };
+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-DE4ZKHZR.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-DYw3z9ju.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.6.0",
+  "version": "0.6.1",
   "description": "Typed, framework-independent content collections, queries, and rendering.",
   "homepage": "https://github.com/yangshun/content-query#readme",
   "bugs": {