content-query 0.5.1 → 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

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

@@ -1,7 +1,7 @@
-import { a as InvalidRelationships, r as CollectionHandles, s as ContentError } from "./collection-types-DhIxnCSM.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-C2FcT1f9.mjs";
-import "./revision-aqGUf6YV.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-CIw4yWs9.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";

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-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-CIw4yWs9.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-CIw4yWs9.mjs";
+import { t as buildAtRoot } from "./build-DYw3z9ju.mjs";
 import { cac } from "cac";
 //#region package.json
-var version = "0.5.1";
+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-DhIxnCSM.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-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 { 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-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 { 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 { n as QueryStyle } from "./query-style-k8Qd7wh5.mjs";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/collection/source.d.ts
 type CollectionSource = string | ({

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-Ch4YLG8t.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 { 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-Aoi7Unm0.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-CIw4yWs9.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-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-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-PtrzENt0.d.mts → relational-types-DnI9wR5r.d.mts}

@@ -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, 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,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<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;

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

@@ -1,8 +1,8 @@
-import { s as ContentError } from "./collection-types-DhIxnCSM.mjs";
+import { s as ContentError } from "./collection-types-Ch4YLG8t.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 { 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-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-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/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-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-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-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.1",
+  "version": "0.6.0",
   "description": "Typed, framework-independent content collections, queries, and rendering.",
   "homepage": "https://github.com/yangshun/content-query#readme",
   "bugs": {