content-query 0.5.0 → 0.6.0

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
@@ -100,6 +106,17 @@ import type { ContentPost } from "#content-query/posts";
 type PostLink = ContentPost<"id" | "title">; // What select("id", "title") returns.
 ```
 
+To describe a field, write a JSDoc comment above it in the schema or above a computed field's name. Editors show the comment when you hover that field on `ContentPost`, on `ContentPost<"id" | "title">`, and on query results:
+
+```ts
+schema: schema.object({
+  /** The headline, also used as the page title. */
+  title: schema.string(),
+}),
+```
+
+Zod's `.describe()` and `.meta()` store descriptions at runtime only, so they don't show up in types.
+
 Type names are `Content` plus the export name, capitalized and made singular by dropping one trailing `s` (`jobs` gives `ContentJob`, `coding` gives `ContentCoding`). Set `typeName: "Category"` in `defineCollection()` for irregular plurals. Declared payloads are typed as `ContentPostPayload<"detail">`. Collection names that are not identifiers are converted for the export and import path, such as `blog-posts` to `blogPosts`; two collections that would share an export or type name fail the build.
 
 Paginate root queries in one call. `paginate({ page: 2, size: 10 })` returns `items`, `total`, `page`, `pageCount`, `hasNextPage`, and `hasPreviousPage` for numbered archive pages. `paginate({ size: 10, after: previous.endCursor })` returns cursor pages with `startCursor` and `endCursor` for "load more" lists. Both work in fluent queries and in `posts.paginate()`; see [pagination](https://github.com/yangshun/content-query/blob/main/docs/API.md#pagination).

package/dist/{build-DfoncKL8.d.mts → build-DE4ZKHZR.d.mts}

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

package/dist/{build-DWpB69_c.mjs → build-DYw3z9ju.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-txOFpidL.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";
@@ -193,6 +193,7 @@ function configTypes(directory, config) {
 * The entry type, such as `ContentJob`, is the full entry. `ContentJob<Field>` is the shape a
 * query returns when it selects `Field`: every selected key is present, and optional fields read
 * as `undefined` when missing, so query results and the type are assignable in both directions.
+* Both forms keep JSDoc comments written on schema fields and computed field names.
 *
 * @param directory - Directory that will contain the declaration file.
 * @param config - Absolute path of content-query.config.
@@ -209,7 +210,7 @@ function collectionDeclarations(directory, config, name, { exportName, typeName,
 		`/** The ${exportName} collection. Start queries here, or pass it to another collection's \`using()\` to follow relationships into it. */`,
 		`export declare const ${exportName}: import("content-query/runtime").Collection<Registry, ${key}, ConfiguredQueryStyle>;`,
 		`/** A ${exportName} entry: its ID, validated metadata, and computed fields. Pass field names, such as \`${typeName}<"id">\`, for the shape a query returns when it selects them. */`,
-		`export type ${typeName}<Field extends keyof ${data} = keyof ${data}> = keyof ${data} extends Field ? ${data} : { [Key in Field]: ${data}[Key] };`,
+		`export type ${typeName}<Field extends keyof ${data} = keyof ${data}> = keyof ${data} extends Field ? ${data} : import("content-query").SelectedData<${data}, Field>;`,
 		`/** The value of one payload that the ${exportName} collection declares. */`,
 		`export type ${payloadTypeName}<Payload extends keyof import("content-query").PayloadsOf<${definition}>> = import("content-query").PayloadData<${definition}, Payload>;`,
 		``

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-DfoncKL8.mjs";
+import { a as ContentSourceEvent, i as ContentSourceEntry, n as buildContent, o as ContentSourceSnapshot, r as ContentSession, t as BuildContentOptions } from "./build-DE4ZKHZR.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-DWpB69_c.mjs";
+export { n as buildContent } from "./build-DYw3z9ju.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-DWpB69_c.mjs";
+import { t as buildAtRoot } from "./build-DYw3z9ju.mjs";
 import { cac } from "cac";
 //#region package.json
-var version = "0.5.0";
+var version = "0.6.0";
 //#endregion
 //#region src/integrations/cli/arguments.ts
 /** Validates one path option after CAC's automatic numeric conversion. */

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

@@ -481,7 +481,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 +495,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 +509,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 +548,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 +577,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 +598,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 +609,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 +624,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 +648,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
@@ -1376,6 +1420,7 @@ function createRunner(state) {
 */
 const queryStyleMembers = {
 	fluent: [
+		"byId",
 		"select",
 		"where",
 		"orderBy",
@@ -1602,6 +1647,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-CsQtGw7_.d.mts → collection-types-Ch4YLG8t.d.mts}

@@ -1,6 +1,6 @@
-import { _ as Relationship, g as QueryData, i as CollectionRegistry, u as LoadedMarker, v as RelationshipsOf } from "./types-Dz1vTXa2.mjs";
-import { n as RelationalCountOptions, t as RelationalCollectionQueries, v as Query } from "./relational-types-CTcalUNW.mjs";
-import { i as QueryStyleMember, n as QueryStyle, r as QueryStyleDisabled, t as MembersOf } from "./query-style-C2FcT1f9.mjs";
+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 { 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,8 +58,21 @@ 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>;
+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.

package/dist/computed.d.mts

@@ -1,6 +1,55 @@
 import { g as MaybePromise } from "./descriptor-bcPa6XLk.mjs";
-import { a as ComputedContext } from "./types-Dz1vTXa2.mjs";
+import { a as ComputedContext } from "./types-WOsFmNnN.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/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 { n as ContentRenderResult, r as RenderedContent, t as ContentHeading } from "./types-Dh-Sydyw.mjs";
-import { C as VariantContext, E as VariantValues, T as VariantOf, _ 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 VariantField, y as Schema } from "./types-Dz1vTXa2.mjs";
-import { n as QueryStyle } from "./query-style-C2FcT1f9.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-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, 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, VariantValues };

package/dist/internal.d.mts

@@ -1,9 +1,9 @@
-import { n as Collection, r as CollectionHandles, s as ContentError } from "./collection-types-CsQtGw7_.mjs";
+import { n as Collection, r as CollectionHandles, s as ContentError } from "./collection-types-Ch4YLG8t.mjs";
 import { n as ContentRenderResult } from "./types-Dh-Sydyw.mjs";
-import { i as CollectionRegistry } from "./types-Dz1vTXa2.mjs";
-import { O as QueryRegistry } from "./relational-types-CTcalUNW.mjs";
-import { n as QueryStyle } from "./query-style-C2FcT1f9.mjs";
-import { n as PreparedRevision, t as ContentState } from "./revision-DBwU-aC9.mjs";
+import { i as CollectionRegistry } from "./types-WOsFmNnN.mjs";
+import { O as QueryRegistry } from "./relational-types-DnI9wR5r.mjs";
+import { n as QueryStyle } from "./query-style-k8Qd7wh5.mjs";
+import { n as PreparedRevision, t as ContentState } from "./revision-vhe9gRyk.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-txOFpidL.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/next.d.mts

@@ -1,4 +1,4 @@
-import { t as BuildContentOptions } from "./build-DfoncKL8.mjs";
+import { t as BuildContentOptions } from "./build-DE4ZKHZR.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-DWpB69_c.mjs";
+import { c as collectionDeclarations, i as resolveConfigPath, t as buildAtRoot } from "./build-DYw3z9ju.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-CTcalUNW.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-DnI9wR5r.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-CTcalUNW.d.mts → relational-types-DnI9wR5r.d.mts}

@@ -1,4 +1,4 @@
-import { S as UnavailableRelationshipsOf, T as VariantOf, _ as Relationship, g as QueryData, h as PayloadsOf, i as CollectionRegistry, v as RelationshipsOf, x as UnavailableRelationship } from "./types-Dz1vTXa2.mjs";
+import { C as UnavailableRelationshipsOf, E as VariantOf, S as UnavailableRelationship, _ as Relationship, g as QueryData, h as PayloadsOf, i as CollectionRegistry, v as RelationshipsOf, x as SelectedData } from "./types-WOsFmNnN.mjs";
 //#region src/query/plan.d.ts
 type PredicateOperator = "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "in-array" | "not-in-array" | "contains" | "starts-with" | "ends-with" | "like" | "ilike" | "array-contains" | "array-contains-any" | "array-contains-all" | "array-contained" | "is-null" | "is-undefined" | "is-missing";
 type Expression = {
@@ -142,7 +142,8 @@ type RelatedName$1<Registry extends CollectionRegistry, Relation extends Relatio
 type RelationshipResult<Definition, Relation extends Relationship, Result, Filtered extends boolean = false> = Relation["type"] extends "many" ? Result[] : Result | (Filtered extends true ? null : Relation["referenceSide"] extends "from" ? Relation["from"] extends keyof QueryData<Definition> ? null extends QueryData<Definition>[Relation["from"]] ? null : undefined extends QueryData<Definition>[Relation["from"]] ? null : never : null : null);
 type RelationValue<Definition, Relation extends Relationship, Configured> = RelationshipResult<Definition, Relation, ResultOf<Configured>, FilteredOf<Configured>>;
 type Query<Registry extends CollectionRegistry, Name extends keyof Registry & string, Result = {}, Selected extends boolean = false, Many extends boolean = true, Root extends boolean = true, Filtered extends boolean = false, AllowAdjacent extends boolean = true, Pagination extends boolean = true, 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, { [Key in Exclude<keyof Result, keyof QueryData<Registry[Name]>> | Keys[number]]: Key extends Keys[number] ? QueryData<Registry[Name]>[Key & keyof QueryData<Registry[Name]>] : Key extends keyof Result ? Result[Key] : never; }, true, Many, Root, Filtered, AllowAdjacent, Pagination, 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,33 +153,41 @@ 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<{ [Key in Keys[number]]: QueryData<Registry[Name]>[Key & keyof QueryData<Registry[Name]>]; }>;
+    _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: Readonly<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 ? {
+} : {}) & (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;
+  /**
+   * 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;
+} : {
+  /** 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;
+}) & {
   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>;
-  /**
-   * Returns one page from one revision: `{ page, size }` for page numbers, or
-   * `{ size, after?, before?, total? }` for cursors. Unavailable after `limit()` or `offset()`.
-   */
-  paginate: Selected extends true ? [Paged] extends [true] ? PaginateAfterLimit : Paginate<Simplify$1<Result>> : UnselectedTerminal;
 } : {});
 /** `paginate()` after `limit()` or `offset()` reports why as its required `this` type. */
 type PaginateAfterLimit = (this: typeof PAGINATE_AFTER_LIMIT_MESSAGE, ...arguments_: readonly unknown[]) => never;
@@ -304,9 +313,11 @@ type Selection<Registry extends CollectionRegistry, Name extends keyof Registry
 type ObjectRelationValue<Registry extends CollectionRegistry, Name extends keyof Registry & string, Key extends keyof RelationshipsOf<Registry[Name]>, Options> = Options extends {
   select: infer Projection;
 } ? RelationValue<Registry[Name], RelationOf<Registry, Name, Key>, QueryInfo<SelectionResult<Registry, RelatedName$1<Registry, RelationOf<Registry, Name, Key>>, Projection>, true, "where" extends keyof Options ? true : false>> : never;
-type SelectionResult<Registry extends CollectionRegistry, Name extends keyof Registry & string, Projection> = { -readonly [Key in keyof Projection as Projection[Key] extends false | undefined ? never : Key]-?: Key extends "_adjacent" ? Projection[Key] extends {
+/** Data fields an object projection requests, excluding relationships and `_adjacent`. */
+type ProjectedFields<Registry extends CollectionRegistry, Name extends keyof Registry & string, Projection> = Exclude<{ [Key in keyof Projection]-?: Projection[Key] extends false | undefined ? never : Key; }[keyof Projection], "_adjacent" | keyof RelationshipsOf<Registry[Name]>> & keyof QueryData<Registry[Name]>;
+type SelectionResult<Registry extends CollectionRegistry, Name extends keyof Registry & string, Projection> = Simplify$1<{ -readonly [Key in keyof Projection as Projection[Key] extends false | undefined ? never : Key extends ProjectedFields<Registry, Name, Projection> ? never : Key]-?: Key extends "_adjacent" ? Projection[Key] extends {
   select: infer Neighbors;
-} ? Adjacent<SelectionResult<Registry, Name, Neighbors>> : never : Key extends keyof RelationshipsOf<Registry[Name]> ? ObjectRelationValue<Registry, Name, Key, Projection[Key]> : Key extends keyof QueryData<Registry[Name]> ? QueryData<Registry[Name]>[Key] : never; };
+} ? Adjacent<SelectionResult<Registry, Name, Neighbors>> : never : Key extends keyof RelationshipsOf<Registry[Name]> ? ObjectRelationValue<Registry, Name, Key, Projection[Key]> : never; } & SelectedData<QueryData<Registry[Name]>, ProjectedFields<Registry, Name, Projection>>>;
 type CheckedField<Value, Filter> = Filter extends Scalar ? Filter : { [Operator in keyof Filter]: Operator extends keyof FieldFilter$1<Value> ? Operator extends "not" ? CheckedField<Value, Filter[Operator]> : Filter[Operator] : never; };
 type CheckedWhereList$1<Data, Filters extends readonly unknown[]> = { [Index in keyof Filters]: CheckedWhere$1<Data, Filters[Index]>; };
 type CheckedWhere$1<Data, Filter> = Filter extends ((...arguments_: never[]) => unknown) ? Filter : { [Key in keyof Filter]: Key extends "AND" | "OR" | "NOT" ? Filter[Key] extends readonly unknown[] ? CheckedWhereList$1<Data, Filter[Key]> : CheckedWhere$1<Data, Filter[Key]> : Key extends keyof Data ? CheckedField<Data[Key], Filter[Key]> : never; };
@@ -402,7 +413,7 @@ type RelationalPaginateOptions<Registry extends CollectionRegistry, Name extends
 type RelationalCountOptions<Registry extends CollectionRegistry, Name extends keyof Registry & string> = Pick<RelationalQueryOptions<Registry, Name>, "where" | "orderBy" | "offset" | "limit">;
 type ColumnResult<Data, Options> = Options extends {
   columns: infer Columns;
-} ? { -readonly [Key in keyof Columns as Columns[Key] extends true ? Key : never]-?: Key extends keyof Data ? Data[Key] : never; } : {};
+} ? SelectedData<Data, { [Key in keyof Columns]-?: Columns[Key] extends true ? Key : never; }[keyof Columns] & keyof Data> : {};
 /** Keys whose option values request something, as opposed to `false` or `undefined`. */
 type Requested<Map> = keyof { [Key in keyof Map as Map[Key] extends false | undefined ? never : Key]: unknown; };
 /** Whether options select fields, include relationships, request payloads, or select adjacency. */

package/dist/{revision-DBwU-aC9.d.mts → revision-vhe9gRyk.d.mts}

@@ -1,8 +1,8 @@
-import { s as ContentError } from "./collection-types-CsQtGw7_.mjs";
+import { s as ContentError } from "./collection-types-Ch4YLG8t.mjs";
 import { n as ContentRenderResult } from "./types-Dh-Sydyw.mjs";
-import { _ as Relationship } from "./types-Dz1vTXa2.mjs";
-import { D as QueryPlan, O as QueryRegistry, k as QueryTerminal } from "./relational-types-CTcalUNW.mjs";
-import { n as QueryStyle } from "./query-style-C2FcT1f9.mjs";
+import { _ as Relationship } from "./types-WOsFmNnN.mjs";
+import { D as QueryPlan, O as QueryRegistry, k as QueryTerminal } from "./relational-types-DnI9wR5r.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,4 @@
-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-CsQtGw7_.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-Ch4YLG8t.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";
+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 };

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

@@ -143,9 +143,26 @@ type ComputedData<Definition> = Definition extends {
 } ? { [Name in keyof Computed]: Computed[Name] extends {
   schema: infer ResultSchema;
 } ? SchemaOutput<ResultSchema> : never; } : {};
+/**
+ * An entry's ID, validated metadata, and computed fields. JSDoc comments on schema fields and
+ * computed field names carry through, so editors show them when hovering a field.
+ */
 type QueryData<Definition> = {
+  /** The entry's ID, unique within its collection. */
   id: string;
 } & EntryData<Definition> & ComputedData<Definition>;
+/** Maps `Field` without reading `Data`'s modifiers, so every key is required. */
+type PresentFields<Data, Field extends PropertyKey> = { [Key in Field]: Key extends keyof Data ? Data[Key] : never; };
+/** Flattens an intersection into one mutable object type, keeping each property's declaration. */
+type MutableObject<Value> = { -readonly [Key in keyof Value]: Value[Key]; };
+/**
+ * The shape of `Data` when a query selects `Field`. Every selected key is present and mutable,
+ * and an optional field's value includes `undefined` instead of the key being optional.
+ *
+ * Each property stays linked to its declaration in `Data`, so JSDoc comments written on schema
+ * fields show when hovering a selected field, and go to definition opens the schema.
+ */
+type SelectedData<Data, Field extends keyof Data> = MutableObject<PresentFields<Data, Field> & Pick<Data, Field>>;
 /**
  * Type-only marker recording which collections a query scope loaded. A marked definition offers
  * only the relationships whose target is loaded; an unmarked one offers every relationship.
@@ -211,4 +228,4 @@ type PayloadData<Definition, Name extends keyof PayloadsOf<Definition>> = Payloa
 /** The variant keys a payload request must supply; empty for built-in and single-value payloads. */
 type VariantOf<Definition, Name> = Name extends keyof CustomPayloadsOf<Definition> ? CustomPayloadsOf<Definition>[Name] extends CustomPayload<unknown, infer Variant> ? Variant : {} : {};
 //#endregion
-export { VariantContext as C, VariantValues as E, UnavailableRelationshipsOf as S, VariantOf 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, VariantField as w, UnavailableRelationship as x, Schema as y };
+export { UnavailableRelationshipsOf as C, VariantValues as D, VariantOf as E, UnavailableRelationship as S, VariantField as T, Relationship as _, ComputedContext as a, SchemaOutput as b, EntryFiles as c, PayloadContext as d, PayloadData as f, QueryData as g, PayloadsOf as h, CollectionRegistry as i, FileEntry as l, PayloadDefinition as m, BuiltinPayloads as n, CustomPayload as o, PayloadDeclaration as p, CollectionDefinition as r, CustomPayloadMarker as s, BuiltinPayloadMarker as t, LoadedMarker as u, RelationshipsOf as v, VariantContext as w, SelectedData as x, Schema as y };

package/dist/vite.d.mts

@@ -1,4 +1,4 @@
-import { a as ContentSourceEvent, o as ContentSourceSnapshot, t as BuildContentOptions } from "./build-DfoncKL8.mjs";
+import { a as ContentSourceEvent, o as ContentSourceSnapshot, t as BuildContentOptions } from "./build-DE4ZKHZR.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-DWpB69_c.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 { 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.0",
+  "version": "0.6.0",
   "description": "Typed, framework-independent content collections, queries, and rendering.",
   "homepage": "https://github.com/yangshun/content-query#readme",
   "bugs": {