content-query 0.3.0 → 0.5.0

package/dist/collection-types-CsQtGw7_.d.mts

@@ -0,0 +1,119 @@
+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";
+//#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 = {
+  code: ContentErrorCode;
+  message: string;
+  operation?: string;
+  collection?: string;
+  id?: string;
+  source?: string;
+  path?: readonly PropertyKey[];
+  /** The custom payload being resolved or loaded. */
+  payload?: string;
+  /** The payload's variant combination, with keys in sorted order. */
+  variant?: Readonly<Record<string, string>>;
+  issues?: readonly unknown[];
+  cause?: unknown;
+};
+/** A contextual library failure; inspect code and diagnostics instead of message text. */
+declare class ContentError extends Error {
+  /** Recognizes contextual errors across preparation and separately bundled loader modules. */
+  static [Symbol.hasInstance](value: unknown): boolean;
+  readonly code: ContentErrorCode;
+  readonly operation?: string;
+  readonly collection?: string;
+  readonly id?: string;
+  readonly source?: string;
+  readonly path?: readonly PropertyKey[];
+  readonly payload?: string;
+  readonly variant?: Readonly<Record<string, string>>;
+  readonly issues?: readonly unknown[];
+  readonly diagnostics: readonly ContentDiagnostic[];
+  /** Creates one failure or a grouped report preserving individual causes and issues. */
+  constructor(options: ContentDiagnostic & {
+    diagnostics?: readonly ContentDiagnostic[];
+  });
+}
+//#endregion
+//#region src/collection/registry-types.d.ts
+type Scalar = string | number | bigint | boolean | Date;
+type Element<Value> = NonNullable<Value> extends readonly (infer Item)[] ? NonNullable<Item> : NonNullable<Value>;
+type Compatible<Left, Right> = NonNullable<Left> extends readonly unknown[] ? NonNullable<Right> extends readonly unknown[] ? false : ScalarCompatible<Left, Right> : ScalarCompatible<Left, Right>;
+type ScalarCompatible<Left, Right> = [Element<Left> | Element<Right>] extends [Scalar] ? [Element<Left>] extends [never] ? true : [Element<Right>] extends [never] ? true : [Extract<Element<Left>, Element<Right>> | Extract<Element<Right>, Element<Left>>] extends [never] ? false : true : false;
+type CheckRelation<Registry extends CollectionRegistry, Name extends keyof Registry, Link extends Relationship> = Link["collection"] extends keyof Registry ? Link["from"] extends keyof QueryData<Registry[Name]> ? Link["to"] extends keyof QueryData<Registry[Link["collection"]]> ? Compatible<QueryData<Registry[Name]>[Link["from"]], QueryData<Registry[Link["collection"]]>[Link["to"]]> extends true ? never : "incompatible-relationship-fields" : "unknown-target-field" : "unknown-source-field" : "unknown-target-collection";
+/** Registry-level relationship checks require the complete inferred collection map. */
+type InvalidRelationships<Registry extends CollectionRegistry> = { [Name in keyof Registry]: { [Link in keyof RelationshipsOf<Registry[Name]>]: RelationshipsOf<Registry[Name]>[Link] extends Relationship ? CheckRelation<Registry, Name, RelationshipsOf<Registry[Name]>[Link]> : "invalid-relationship"; }[keyof RelationshipsOf<Registry[Name]>]; }[keyof Registry];
+//#endregion
+//#region src/runtime/collection-types.d.ts
+declare const collectionType: unique symbol;
+/**
+ * The registry a query scope sees: only the loaded collections, each marked so it offers only the
+ * relationships into loaded collections.
+ */
+type LoadedRegistry<Registry extends CollectionRegistry, Loaded extends keyof Registry & string> = { [Name in Loaded]: Registry[Name] & LoadedMarker<Loaded>; };
+/** The members that start a fluent query; terminals such as `all()` follow one of them. */
+type FluentMember = MembersOf<"fluent">;
+/** The relational members, apart from `count`, which both styles share. */
+type RelationalMember = "findMany" | "findFirst" | "paginate";
+/** Every member before `queryStyle` gating. */
+type CollectionMethods<Registry extends CollectionRegistry, Name extends keyof Registry & string> = Pick<Query<Registry, Name>, FluentMember & keyof Query<Registry, Name>> & RelationalCollectionQueries<Registry, Name>;
+/**
+ * Members outside the allowed style. Calls report the message as the required `this` type,
+ * whatever arguments they pass.
+ */
+type DisabledMembers<Name extends string, Style extends QueryStyle> = { readonly [Member in Exclude<FluentMember | RelationalMember, MembersOf<Style>>]: (this: QueryStyleDisabled<Name, Member & QueryStyleMember, Style>, ...arguments_: readonly unknown[]) => never; };
+/** `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()`. */
+  count(): Promise<number>;
+} : {
+  /** Counts matching entries before pagination, like the fluent `count()` terminal. */
+  count(options?: RelationalCountOptions<Registry, Name>): Promise<number>;
+};
+/** Reads the collections a collection handle loads. */
+type LoadedOf<Handle> = Handle extends {
+  readonly [collectionType]: {
+    loaded: infer Loaded;
+  };
+} ? Loaded : never;
+/** Any collection handle, as `using()` accepts it. */
+type AnyCollection = {
+  readonly [collectionType]: {
+    loaded: string;
+  };
+};
+/**
+ * One collection's query API, as its generated entry exports it.
+ *
+ * Queries load only this collection and the collections passed to `using()`. Relationships into
+ * any other collection are type errors here and `invalid-query` errors at runtime. `Style` narrows
+ * the members to the `queryStyle` exported by content-query.config; the default allows both.
+ *
+ * @typeParam Registry - The configured collection registry.
+ * @typeParam Name - The queried collection.
+ * @typeParam Style - The allowed query style.
+ * @typeParam Loaded - The collections this handle loads, including `Name`.
+ */
+type Collection<Registry extends CollectionRegistry, Name extends keyof Registry & string, Style extends QueryStyle = QueryStyle, Loaded extends keyof Registry & string = Name> = InvalidRelationships<Registry> extends never ? Pick<CollectionMethods<LoadedRegistry<Registry, Loaded | Name>, Name>, Extract<FluentMember | RelationalMember, MembersOf<Style>>> & DisabledMembers<Name, Style> & CountMember<LoadedRegistry<Registry, Loaded | Name>, Name, Style> & {
+  /**
+   * Supplies other collections, so this collection's queries can follow relationships
+   * into them. Nested relationships need each collection they reach.
+   *
+   * @param collections - Collections imported from their own entries.
+   * @returns A handle over this collection that also loads the supplied collections.
+   */
+  using<const Supplied extends readonly AnyCollection[]>(...collections: Supplied): Collection<Registry, Name, Style, Loaded | (LoadedOf<Supplied[number]> & keyof Registry & string)>;
+  readonly [collectionType]: {
+    readonly name: Name;
+    readonly loaded: Loaded | Name;
+  };
+} : {
+  readonly invalidRelationships: InvalidRelationships<Registry>;
+};
+/** One handle per collection, keyed by collection name, each loading only its own collection. */
+type CollectionHandles<Registry extends CollectionRegistry, Style extends QueryStyle = QueryStyle> = { readonly [Name in keyof Registry & string]: Collection<Registry, Name, Style>; };
+//#endregion
+export { InvalidRelationships as a, ContentErrorCode as c, LoadedRegistry as i, Collection as n, ContentDiagnostic as o, CollectionHandles as r, ContentError as s, AnyCollection as t };

package/dist/computed.d.mts

@@ -1,5 +1,5 @@
-import { m as MaybePromise } from "./types-FmUJ3cH1.mjs";
-import { a as ComputedContext } from "./types-BC8gVJ6u.mjs";
+import { g as MaybePromise } from "./descriptor-bcPa6XLk.mjs";
+import { a as ComputedContext } from "./types-Dz1vTXa2.mjs";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/computed/text.d.ts
 /** The syntax removed before computing text-derived fields; literal text preserves all characters. */

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

@@ -149,4 +149,20 @@ type LoaderSource<Value> = Value extends {
   readonly [loaderSourceType]?: infer Source;
 } ? Source : unknown;
 //#endregion
-export { FileSource as a, LoaderContext as c, LoaderWatcher as d, MetaStore as f, FileEntrySource as i, LoaderLogger as l, MaybePromise as m, DataEntry as n, Loader as o, RecordLoader as p, DataStore as r, LoaderConfig as s, BodyLoader as t, LoaderSource as u };
+//#region src/loaders/descriptor.d.ts
+type GlobOptions = {
+  pattern: string | string[];
+  base?: string | URL;
+  generateId?: (context: {
+    entry: string;
+    base: URL;
+    data: Record<string, unknown>;
+  }) => string;
+  retainBody?: boolean;
+  deferRender?: boolean;
+};
+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 };

package/dist/{diagnostics-Cu94mZhl.mjs → diagnostics-DmUZtrJ6.mjs}

@@ -1,4 +1,4 @@
-import { t as ContentError } from "./errors-C2iuBM0G.mjs";
+import { t as ContentError } from "./errors-Bfd0R4_P.mjs";
 import { o as encode, r as decode } from "./values-BbTV4QT-.mjs";
 //#region src/runtime/diagnostics.ts
 /** Transports Error nodes as records while preserving the supported diagnostic value graph. */
@@ -59,6 +59,8 @@ function serializeContentError(error) {
 		id: error.id,
 		source: error.source,
 		path: error.path,
+		payload: error.payload,
+		variant: error.variant,
 		issues: error.issues,
 		cause: error.cause,
 		diagnostics: error.diagnostics

package/dist/{errors-C2iuBM0G.mjs → errors-Bfd0R4_P.mjs}

@@ -12,6 +12,8 @@ var ContentError = class extends Error {
 	id;
 	source;
 	path;
+	payload;
+	variant;
 	issues;
 	diagnostics;
 	/** Creates one failure or a grouped report preserving individual causes and issues. */
@@ -25,10 +27,23 @@ var ContentError = class extends Error {
 		this.id = options.id;
 		this.source = options.source;
 		this.path = options.path;
+		this.payload = options.payload;
+		this.variant = options.variant;
 		this.issues = options.issues;
 		this.diagnostics = options.diagnostics ?? [{ ...options }];
 	}
 };
+/**
+* Formats a payload and its variant as a readable identity, such as `detail[locale=en-US]`.
+*
+* @param payload - The payload name.
+* @param variant - The variant combination; keys are listed in sorted order.
+* @returns The payload name, followed by its variant pairs when it has any.
+*/
+function payloadIdentity(payload, variant = {}) {
+	const pairs = Object.keys(variant).sort().map((key) => `${key}=${variant[key]}`);
+	return pairs.length ? `${payload}[${pairs.join(",")}]` : payload;
+}
 /** Rejects invalid query structure before any execution or payload access. */
 function invalidQuery(message) {
 	throw new ContentError({
@@ -69,4 +84,4 @@ function withContext(cause, context) {
 	})));
 }
 //#endregion
-export { invalidQuery as a, groupDiagnostics as i, contentError as n, withContext as o, describeCause as r, ContentError as t };
+export { invalidQuery as a, groupDiagnostics as i, contentError as n, payloadIdentity as o, describeCause as r, withContext as s, ContentError as t };

package/dist/file-DSOcdFj0.mjs

@@ -0,0 +1,81 @@
+import { a as recordData, f as builtinPath, i as parseData, o as populateStore, p as builtinSymbol, r as coerceIdentity } from "./glob-BXJuwy_p.mjs";
+import { i as groupDiagnostics, n as contentError, r as describeCause, t as ContentError } from "./errors-Bfd0R4_P.mjs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+//#region src/loaders/file.ts
+/** Declares a multi-entry data file with typed source paths and record keys, plus an optional parser. */
+function file(filename, options = {}) {
+	if (typeof filename !== "string" || !filename) throw new TypeError("file() requires a filename.");
+	const descriptor = {
+		kind: "file",
+		filename,
+		options
+	};
+	return {
+		[builtinSymbol]: descriptor,
+		name: "content-query/file",
+		async load(context) {
+			const entries = await loadFile(descriptor, fileURLToPath(context.config.root), context.signal ?? new AbortController().signal);
+			await populateStore(context, entries);
+		}
+	};
+}
+/** Captures a complete multi-entry data source without applying collection validation. */
+async function loadFile(descriptor, root, signal) {
+	const resolved = builtinPath(descriptor, root);
+	let parsed;
+	try {
+		const text = await readFile(resolved, {
+			encoding: "utf8",
+			signal
+		});
+		parsed = descriptor.options.parser ? await descriptor.options.parser(text) : parseData(text, resolved);
+	} catch (cause) {
+		signal.throwIfAborted();
+		throw contentError(cause, {
+			code: "source-error",
+			source: resolved,
+			message: `Could not load "${descriptor.filename}": ${describeCause(cause)}`,
+			cause
+		});
+	}
+	const array = Array.isArray(parsed);
+	if (!array && (!parsed || typeof parsed !== "object")) throw new ContentError({
+		code: "source-error",
+		source: resolved,
+		message: `"${descriptor.filename}" must parse to an array or keyed record.`
+	});
+	const diagnostics = [];
+	const entries = Object.entries(parsed).flatMap(([key, value]) => {
+		if (!array && key === "$schema" && typeof value === "string") return [];
+		const source = `${resolved}#${key}`;
+		try {
+			const data = recordData(value);
+			const identity = array ? data.id ?? data.slug : key;
+			if (identity == null || coerceIdentity(identity) === "") throw new Error("Array entries require a nonempty id or slug.");
+			const { id: _transportId, ...metadata } = data;
+			return [{
+				id: coerceIdentity(identity),
+				data: metadata,
+				source: array ? source : `${resolved}#${coerceIdentity(identity)}`,
+				sourceData: {
+					filePath: path.relative(root, resolved).split(path.sep).join("/"),
+					key
+				}
+			}];
+		} catch (cause) {
+			diagnostics.push({
+				code: "source-error",
+				source,
+				message: `Invalid entry "${key}" in "${descriptor.filename}": ${describeCause(cause)}`,
+				cause
+			});
+			return [];
+		}
+	});
+	if (diagnostics.length) throw groupDiagnostics(diagnostics);
+	return entries;
+}
+//#endregion
+export { loadFile as n, file as t };

package/dist/{glob-Bv0dpvCQ.mjs → glob-BXJuwy_p.mjs}

@@ -1,5 +1,5 @@
-import { n as normalizeSnapshot, o as builtinPath, s as builtinSymbol } from "./validation-D_XdE1pF.mjs";
-import { i as groupDiagnostics, n as contentError, r as describeCause, t as ContentError } from "./errors-C2iuBM0G.mjs";
+import { i as groupDiagnostics, n as contentError, r as describeCause, t as ContentError } from "./errors-Bfd0R4_P.mjs";
+import { i as detach } from "./values-BbTV4QT-.mjs";
 import { n as slug } from "./github-slugger-BMgR_Q0I.mjs";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
@@ -8,6 +8,85 @@ import { glob } from "tinyglobby";
 import matter from "gray-matter";
 import { parse } from "yaml";
 import { parse as parse$1 } from "smol-toml";
+//#region src/loaders/descriptor.ts
+const builtinSymbol = Symbol.for("content-query.builtin-loader");
+/** Finds library-owned loader settings without depending on module instance identity. */
+function builtinLoader(loader) {
+	return loader[builtinSymbol];
+}
+/** Resolves a loader's watch root from the application root, including file URLs. */
+function builtinPath(descriptor, root) {
+	if (descriptor.kind === "file") return path.resolve(root, descriptor.filename);
+	return descriptor.options.base instanceof URL ? path.resolve(fileURLToPath(descriptor.options.base)) : path.resolve(root, descriptor.options.base ?? ".");
+}
+//#endregion
+//#region src/preparation/validation.ts
+/** Checks records independently from validation-provider schema introspection. */
+function isRecord(value) {
+	return !!value && typeof value === "object" && !Array.isArray(value) && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+}
+/** Validates one result, retaining structured provider issues and their original detail. */
+async function validate(schema, value, context) {
+	if (!schema) return value;
+	try {
+		const result = await schema["~standard"].validate(value);
+		if (result.issues) {
+			const firstPath = result.issues[0]?.path?.map((segment) => typeof segment === "object" ? segment.key : segment);
+			throw new ContentError({
+				...context,
+				code: "validation-error",
+				message: result.issues.map((issue) => issue.message).join("; "),
+				issues: result.issues,
+				path: [...context.path ?? [], ...firstPath ?? []]
+			});
+		}
+		return result.value;
+	} catch (cause) {
+		throw contentError(cause, {
+			...context,
+			code: "validation-error",
+			message: "Schema validation failed."
+		});
+	}
+}
+/** Checks loader transport structure and rejects duplicate snapshot/upsert identities. */
+function normalizeSnapshot(entries, collection) {
+	if (!Array.isArray(entries)) throw new ContentError({
+		code: "source-error",
+		collection,
+		message: "load() must return an array of structured entries."
+	});
+	const snapshot = /* @__PURE__ */ new Map();
+	for (const entry of entries) {
+		if (!entry || typeof entry.id !== "string" || !entry.id || !isRecord(entry.data) || entry.body !== void 0 && typeof entry.body !== "string" || entry.source !== void 0 && typeof entry.source !== "string") throw new ContentError({
+			code: "source-error",
+			collection,
+			id: entry && typeof entry === "object" && typeof entry.id === "string" ? entry.id : void 0,
+			source: entry && typeof entry === "object" && typeof entry.source === "string" ? entry.source : void 0,
+			message: "Invalid structured loader entry."
+		});
+		if (snapshot.has(entry.id)) throw new ContentError({
+			code: "duplicate-id",
+			collection,
+			id: entry.id,
+			source: entry.source,
+			message: `Duplicate entry ID "${entry.id}".`
+		});
+		snapshot.set(entry.id, entry);
+	}
+	return snapshot;
+}
+/** Validates supplied rendering data and normalizes omitted headings. */
+function renderedPayload(entry) {
+	if (entry.rendered === void 0) return;
+	const rendered = entry.rendered;
+	if (!rendered || typeof rendered.html !== "string" || rendered.metadata !== void 0 && (!isRecord(rendered.metadata) || rendered.metadata.headings !== void 0 && (!Array.isArray(rendered.metadata.headings) || rendered.metadata.headings.some((heading) => !heading || !Number.isInteger(heading.depth) || heading.depth < 1 || heading.depth > 6 || typeof heading.slug !== "string" || typeof heading.text !== "string")))) throw new Error("Invalid supplied HTML/headings payload.");
+	return {
+		html: rendered.html,
+		headings: detach(rendered.metadata?.headings ?? [])
+	};
+}
+//#endregion
 //#region src/loaders/populate.ts
 /** Validates a complete built-in source before replacing its collection store. */
 async function populateStore(context, entries) {
@@ -67,15 +146,24 @@ function glob$1(options) {
 		}
 	};
 }
-/** Captures complete matching Markdown and data sources before deployment. */
-async function loadGlob(descriptor, root, signal) {
+/**
+* Captures complete matching Markdown and data sources before deployment.
+*
+* @param descriptor - The glob loader's options.
+* @param root - The project root that relative bases and source paths use.
+* @param signal - Cancels outstanding reads.
+* @param options - `warnEmpty: false` skips the warning when nothing matches, for callers where an
+* empty result is expected, such as resolvers' `files.glob()`.
+* @returns Loader entries in sorted path order.
+*/
+async function loadGlob(descriptor, root, signal, { warnEmpty = true } = {}) {
 	const resolved = builtinPath(descriptor, root);
 	const entries = await glob(descriptor.options.pattern, {
 		cwd: resolved,
 		onlyFiles: true,
 		dot: false
 	});
-	if (entries.length === 0) console.warn(`[content-query] No content matched ${JSON.stringify(descriptor.options.pattern)} in ${resolved}.`);
+	if (entries.length === 0 && warnEmpty) console.warn(`[content-query] No content matched ${JSON.stringify(descriptor.options.pattern)} in ${resolved}.`);
 	const base = pathToFileURL(`${resolved}${path.sep}`);
 	entries.sort();
 	const results = [];
@@ -156,4 +244,4 @@ async function loadEntry(descriptor, entry, filename, base, signal) {
 	};
 }
 //#endregion
-export { populateStore as a, recordData as i, coerceIdentity as n, parseData as r, glob$1 as t };
+export { recordData as a, normalizeSnapshot as c, builtinLoader as d, builtinPath as f, parseData as i, renderedPayload as l, loadGlob as n, populateStore as o, builtinSymbol as p, coerceIdentity as r, isRecord as s, glob$1 as t, validate as u };

package/dist/index.d.mts

@@ -1,7 +1,7 @@
-import { a as FileSource, c as LoaderContext, d as LoaderWatcher, f as MetaStore, i as FileEntrySource, l as LoaderLogger, m as MaybePromise, n as DataEntry, o as Loader, p as RecordLoader, r as DataStore, s as LoaderConfig, t as BodyLoader, u as LoaderSource } from "./types-FmUJ3cH1.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-bcPa6XLk.mjs";
 import { n as ContentRenderResult, r as RenderedContent, t as ContentHeading } from "./types-Dh-Sydyw.mjs";
-import { a as ComputedContext, c as Relationship, d as SchemaOutput, i as CollectionRegistry, n as BuiltinPayloads, o as PayloadsOf, r as CollectionDefinition, s as QueryData, t as BuiltinPayloadMarker, u as Schema } from "./types-BC8gVJ6u.mjs";
-import { n as GlobOptions } from "./descriptor-BUPT2J7X.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 { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/collection/source.d.ts
 type CollectionSource = string | ({
@@ -15,7 +15,35 @@ type CollectionSource = string | ({
 type RecordSource = Extract<CollectionSource, object> & {
   type: "json" | "yaml" | "toml";
 };
-type CollectionFields<SourceSchema extends Schema | undefined, ComputedSchemas extends Record<string, Schema>, Relationships extends Record<string, Relationship>, Source> = {
+/** Variant values are typed `string`, so inference never depends on declaration order. */
+type VariantRecord<Keys> = { [Key in keyof Keys]: string; };
+/** Metadata plus computed fields, as payload enumerators and resolvers receive them. */
+type PayloadData$1<SourceSchema extends Schema | undefined, ComputedSchemas extends Record<string, Schema>> = SchemaOutput<NoInfer<SourceSchema>> & { [Field in keyof NoInfer<ComputedSchemas>]: SchemaOutput<NoInfer<ComputedSchemas>[Field]>; };
+/**
+ * Custom payload declarations. Schemas and variant keys are inferred through separate mapped
+ * types, so resolvers are contextually typed without annotations. Variant values are data field
+ * names or fixed lists rather than callbacks: TypeScript cannot infer keys from an object whose
+ * values are all unannotated callbacks.
+ */
+type PayloadDeclarations<SourceSchema extends Schema | undefined, ComputedSchemas extends Record<string, Schema>, PayloadSchemas extends Record<string, Schema>, PayloadVariants extends Record<string, unknown>, Source> = { [Name in keyof PayloadSchemas]: {
+  schema: PayloadSchemas[Name];
+}; } & { [Name in keyof PayloadVariants]: {
+  variants?: { [Key in keyof PayloadVariants[Name]]: VariantValues<PayloadData$1<SourceSchema, ComputedSchemas>>; };
+  combinations?(context: VariantContext<PayloadData$1<SourceSchema, ComputedSchemas>, Source> & {
+    variants: Readonly<{ [Key in keyof NoInfer<PayloadVariants>[Name]]: readonly string[]; }>;
+  }): Iterable<VariantRecord<NoInfer<PayloadVariants>[Name]>> | PromiseLike<Iterable<VariantRecord<NoInfer<PayloadVariants>[Name]>>>;
+  resolve(context: PayloadContext<PayloadData$1<SourceSchema, ComputedSchemas>, Source, VariantRecord<NoInfer<PayloadVariants>[Name]>>): unknown;
+  /** Set to `false` to resolve again in every revision. */
+  cache?: boolean;
+}; } & ReservedPayloadNames<NoInfer<PayloadSchemas>>;
+/**
+ * Rejects underscore payload names, which built-ins own. A conditional keeps declaration inference
+ * intact, unlike a key-remapped mapped type.
+ */
+type ReservedPayloadNames<PayloadSchemas> = Extract<keyof PayloadSchemas, `_${string}`> extends never ? unknown : {
+  "Custom payload names cannot start with an underscore": Extract<keyof PayloadSchemas, `_${string}`>;
+};
+type CollectionFields<SourceSchema extends Schema | undefined, ComputedSchemas extends Record<string, Schema>, Relationships extends Record<string, Relationship>, PayloadSchemas extends Record<string, Schema>, PayloadVariants extends Record<string, unknown>, Source> = {
   schema?: SourceSchema;
   computed?: { [Name in keyof ComputedSchemas]: {
     schema: ComputedSchemas[Name];
@@ -26,16 +54,27 @@ type CollectionFields<SourceSchema extends Schema | undefined, ComputedSchemas e
       id: string;
     } & { [Field in keyof ComputedSchemas]: SchemaOutput<ComputedSchemas[Field]>; }) & string;
   }; };
+  /** Directories, relative to the project root, that resolvers' `files` helpers may also read. */
+  sharedFiles?: readonly string[];
+  /**
+   * The singular name in generated types, such as `"Category"` for `ContentCategory`. Defaults to
+   * the export name without one trailing `s`, so `jobs` generates `ContentJob`.
+   */
+  typeName?: string;
+  /** Named per-entry data resolved during preparation and loaded only when a query requests it. */
+  payloads?: PayloadDeclarations<SourceSchema, ComputedSchemas, PayloadSchemas, PayloadVariants, Source>;
 };
-type Definition<SourceSchema extends Schema | undefined, ComputedSchemas extends Record<string, Schema>, Relationships extends Record<string, Relationship>, ContentLoader extends Loader> = ({
+type Definition<SourceSchema extends Schema | undefined, ComputedSchemas extends Record<string, Schema>, Relationships extends Record<string, Relationship>, PayloadSchemas extends Record<string, Schema>, PayloadVariants extends Record<string, unknown>, ContentLoader extends Loader> = ({
   source: CollectionSource;
   loader?: never;
-} & CollectionFields<SourceSchema, ComputedSchemas, Relationships, FileSource>) | ({
+} & CollectionFields<SourceSchema, ComputedSchemas, Relationships, PayloadSchemas, PayloadVariants, FileSource>) | ({
   loader: ContentLoader;
   source?: never;
-} & CollectionFields<SourceSchema, ComputedSchemas, Relationships, LoaderSource<NoInfer<ContentLoader>>>);
+} & CollectionFields<SourceSchema, ComputedSchemas, Relationships, PayloadSchemas, PayloadVariants, LoaderSource<NoInfer<ContentLoader>>>);
+/** Records each declared payload's validated value type and variant record. */
+type PayloadMarker<PayloadSchemas extends Record<string, Schema>, PayloadVariants extends Record<string, unknown>> = CustomPayloadMarker<{ [Name in keyof PayloadSchemas & string]: CustomPayload<SchemaOutput<PayloadSchemas[Name]>, VariantRecord<PayloadVariants[Name & keyof PayloadVariants]>>; }>;
 /** Normalizes either declaration form into a definition with a native loader. */
-declare function collectionOf<SourceSchema extends StandardSchemaV1<unknown, Record<string, unknown>> | undefined, ComputedSchemas extends Record<string, Schema>, Relationships extends Record<string, Relationship>, ContentLoader extends Loader>(definition: Definition<SourceSchema, ComputedSchemas, Relationships, ContentLoader>): {
+declare function collectionOf<SourceSchema extends StandardSchemaV1<unknown, Record<string, unknown>> | undefined, ComputedSchemas extends Record<string, Schema>, Relationships extends Record<string, Relationship>, PayloadSchemas extends Record<string, Schema>, PayloadVariants extends Record<string, unknown>, ContentLoader extends Loader>(definition: Definition<SourceSchema, ComputedSchemas, Relationships, PayloadSchemas, PayloadVariants, ContentLoader>): {
   loader: ContentLoader | Loader<FileSource>;
   schema: SourceSchema;
   computed: { [Name in keyof ComputedSchemas]: {
@@ -47,6 +86,15 @@ declare function collectionOf<SourceSchema extends StandardSchemaV1<unknown, Rec
   }; };
   relationships: Relationships;
   source: CollectionSource;
+  /** Directories, relative to the project root, that resolvers' `files` helpers may also read. */
+  sharedFiles?: readonly string[];
+  /**
+   * The singular name in generated types, such as `"Category"` for `ContentCategory`. Defaults to
+   * the export name without one trailing `s`, so `jobs` generates `ContentJob`.
+   */
+  typeName?: string;
+  /** Named per-entry data resolved during preparation and loaded only when a query requests it. */
+  payloads?: PayloadDeclarations<SourceSchema, ComputedSchemas, PayloadSchemas, PayloadVariants, FileSource> | undefined;
 } | {
   loader: ContentLoader | Loader<FileSource>;
   schema: SourceSchema;
@@ -59,21 +107,31 @@ declare function collectionOf<SourceSchema extends StandardSchemaV1<unknown, Rec
   }; };
   relationships: Relationships;
   source?: never;
+  /** Directories, relative to the project root, that resolvers' `files` helpers may also read. */
+  sharedFiles?: readonly string[];
+  /**
+   * The singular name in generated types, such as `"Category"` for `ContentCategory`. Defaults to
+   * the export name without one trailing `s`, so `jobs` generates `ContentJob`.
+   */
+  typeName?: string;
+  /** Named per-entry data resolved during preparation and loaded only when a query requests it. */
+  payloads?: PayloadDeclarations<SourceSchema, ComputedSchemas, PayloadSchemas, PayloadVariants, LoaderSource<NoInfer<ContentLoader>>> | undefined;
 };
-type Defined<SourceSchema extends StandardSchemaV1<unknown, Record<string, unknown>> | undefined, ComputedSchemas extends Record<string, Schema>, Relationships extends Record<string, Relationship>, ContentLoader extends Loader> = ReturnType<typeof collectionOf<SourceSchema, ComputedSchemas, Relationships, ContentLoader>>;
+type Defined<SourceSchema extends StandardSchemaV1<unknown, Record<string, unknown>> | undefined, ComputedSchemas extends Record<string, Schema>, Relationships extends Record<string, Relationship>, PayloadSchemas extends Record<string, Schema>, PayloadVariants extends Record<string, unknown>, ContentLoader extends Loader> = ReturnType<typeof collectionOf<SourceSchema, ComputedSchemas, Relationships, PayloadSchemas, PayloadVariants, ContentLoader>> & PayloadMarker<PayloadSchemas, PayloadVariants>;
 /**
- * Declares fields with inferred schema data and optional loader source metadata, plus relationships.
- * JSON, YAML, and TOML sources carry no built-in `_body` or `_rendered` payloads.
+ * Declares fields with inferred schema data and optional loader source metadata, plus
+ * relationships and custom payloads. JSON, YAML, and TOML sources carry no built-in `_body` or
+ * `_rendered` payloads.
  */
-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> = {}>(definition: {
+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> = {}>(definition: {
   source: RecordSource;
   loader?: never;
-} & CollectionFields<SourceSchema, ComputedSchemas, Relationships, FileSource>): Defined<SourceSchema, ComputedSchemas, Relationships, Loader> & BuiltinPayloadMarker<never>;
+} & CollectionFields<SourceSchema, ComputedSchemas, Relationships, PayloadSchemas, PayloadVariants, FileSource>): Defined<SourceSchema, ComputedSchemas, Relationships, PayloadSchemas, PayloadVariants, Loader> & BuiltinPayloadMarker<never>;
 /**
- * Declares fields with inferred schema data and optional loader source metadata, plus relationships.
- * Record loaders such as `file()` carry no built-in `_body` or `_rendered` payloads, and body
- * loaders carry `_body` without `_rendered`.
+ * Declares fields with inferred schema data and optional loader source metadata, plus
+ * relationships and custom payloads. Record loaders such as `file()` carry no built-in `_body` or
+ * `_rendered` payloads, and body loaders carry `_body` without `_rendered`.
  */
-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 ContentLoader extends Loader = Loader>(definition: Definition<SourceSchema, ComputedSchemas, Relationships, ContentLoader>): Defined<SourceSchema, ComputedSchemas, Relationships, ContentLoader> & BuiltinPayloadMarker<[ContentLoader] extends [RecordLoader] ? never : [ContentLoader] extends [BodyLoader] ? "_body" : keyof BuiltinPayloads>;
+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, FileEntrySource, FileSource, Loader, LoaderConfig, LoaderContext, LoaderLogger, LoaderSource, LoaderWatcher, MaybePromise, MetaStore, PayloadsOf, QueryData, RecordLoader, Relationship, RenderedContent };
+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 };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { t as glob } from "./glob-Bv0dpvCQ.mjs";
+import { t as glob } from "./glob-BXJuwy_p.mjs";
 import { t as assertServerOnly } from "./server-only-CIJUlyL-.mjs";
 //#region src/collection/source.ts
 const patterns = {