content-query 0.1.0 → 0.2.0

package/dist/{content-Dj2fQCJ5.mjs → content-N1gYshjg.mjs}

@@ -1,7 +1,7 @@
-import { a as invalidQuery, n as contentError, t as ContentError } from "./errors-C8lWyiy2.mjs";
-import { a as detachSelection, c as isScalar, i as detach, n as compareStrings, s as equal, t as compare } from "./values-B7lo_2_x.mjs";
-import { t as assertServerOnly } from "./server-only-CIE-FHx0.mjs";
-import { _ as not, t as and, x as validateExpression, y as or } from "./operators-BQpLfJlx.mjs";
+import { a as invalidQuery, n as contentError, t as ContentError } from "./errors-C2iuBM0G.mjs";
+import { a as detachSelection, c as isScalar, i as detach, n as compareStrings, s as equal, t as compare } from "./values-BbTV4QT-.mjs";
+import { t as assertServerOnly } from "./server-only-CIJUlyL-.mjs";
+import { _ as not, t as and, x as validateExpression, y as or } from "./operators-UqWUhKQJ.mjs";
 //#region src/artifacts/types.ts
 const CODEC_VERSION = "devalue-6.0.2";
 //#endregion
@@ -144,11 +144,42 @@ function isRelationship(value) {
 	].includes(String(value.referenceSide));
 }
 //#endregion
+//#region src/shared/concurrency.ts
+/**
+* Maps items through an asynchronous callback with at most `limit` callbacks in flight.
+* Results keep input order; the first rejection rejects the whole map after started work settles.
+*
+* @param items - Values to process.
+* @param limit - Maximum number of concurrent callbacks; values below one are treated as one.
+* @param callback - Asynchronous work for one item and its index.
+* @returns The callback results in input order.
+*/
+async function mapConcurrent(items, limit, callback) {
+	const results = Array.from({ length: items.length });
+	let next = 0;
+	let failure;
+	/** Claims the next unprocessed item until the list is exhausted or work has failed. */
+	async function worker() {
+		while (next < items.length && !failure) {
+			const index = next++;
+			try {
+				results[index] = await callback(items[index], index);
+			} catch (cause) {
+				failure ??= { cause };
+			}
+		}
+	}
+	const workers = Array.from({ length: Math.min(Math.max(1, limit), items.length) }, worker);
+	await Promise.all(workers);
+	if (failure) throw failure.cause;
+	return results;
+}
+//#endregion
 //#region src/query/clauses.ts
 /** Checks scalar field selection for both public query frontends without a schema field catalog. */
 function checkedFields(registry, collection, fields) {
 	const scope = registry[collection];
-	if (!scope || fields.some((field) => typeof field !== "string" || !field || field === "_adjacent" || Object.hasOwn(scope.relationships, field)) || new Set(fields).size !== fields.length) invalidQuery("Selection requires distinct prepared fields; use relationship or adjacency selection explicitly.");
+	if (!scope || fields.some((field) => typeof field !== "string" || !field || field === "_adjacent" || field === "_payloads" || Object.hasOwn(scope.relationships, field)) || new Set(fields).size !== fields.length) invalidQuery("Selection requires distinct prepared fields; use relationship or adjacency selection explicitly.");
 	return [...fields];
 }
 /** Checks one sort clause with the same cardinality and duplicate rules in either API. */
@@ -164,6 +195,35 @@ function checkedPagination(value, many) {
 	if (!many || !Number.isSafeInteger(value) || value < 0) invalidQuery("Pagination requires a nonnegative safe integer and a many-valued scope.");
 	return value;
 }
+/** Finds a payload declaration that queries may request, rejecting unknown names. */
+function payloadDescriptor(registry, collection, name) {
+	const payloads = registry[collection]?.payloads ?? {};
+	if (typeof name !== "string" || !Object.hasOwn(payloads, name)) invalidQuery(`Unknown payload "${String(name)}" for collection "${collection}".`);
+	return payloads[name];
+}
+/** Checks one payload request against the collection's payload names and variant keys. */
+function checkedPayload(registry, collection, name, request) {
+	const { variants } = payloadDescriptor(registry, collection, name);
+	if (request === true || request === void 0) {
+		if (variants.length) invalidQuery(`Payload "${name}" requires variant keys: ${variants.join(", ")}.`);
+		return { variant: {} };
+	}
+	const variant = request;
+	if (!variant || typeof variant !== "object" || Array.isArray(variant) || Object.keys(variant).length !== variants.length || variants.some((key) => !Object.hasOwn(variant, key) || typeof variant[key] !== "string")) invalidQuery(`Payload "${name}" requires exactly these string variant keys: ${variants.join(", ") || "none"}.`);
+	return { variant: Object.fromEntries([...variants].sort().map((key) => [key, variant[key]])) };
+}
+/** Compiles a payloads option into plan requests, omitting payloads set to false. */
+function checkedPayloads(registry, collection, payloads) {
+	const requested = Object.create(null);
+	for (const [name, request] of Object.entries(payloads)) {
+		if (request === false || request === void 0) {
+			payloadDescriptor(registry, collection, name);
+			continue;
+		}
+		requested[name] = checkedPayload(registry, collection, name, request);
+	}
+	return Object.keys(requested).length ? requested : void 0;
+}
 //#endregion
 //#region src/query/plan.ts
 /** Starts a fresh query without binding a content revision until execution. */
@@ -272,7 +332,10 @@ function relationalWhere(registry, collection, where) {
 	validateExpression(expression);
 	return detach(expression);
 }
-/** Compiles Drizzle-style columns/with options into the shared immutable query plan. */
+/**
+* Compiles Drizzle-style columns/with options into the shared immutable query plan.
+* Payloads are allowed wherever adjacency is, so sibling scopes never load them.
+*/
 function relationalPlan(registry, collection, options = {}, many = true, allowAdjacent = true, pagination = true) {
 	if (!Object.hasOwn(registry, collection)) invalidQuery(`Unknown collection "${collection}".`);
 	record$1(options, "Query");
@@ -282,7 +345,7 @@ function relationalPlan(registry, collection, options = {}, many = true, allowAd
 		"with",
 		...many ? ["orderBy"] : [],
 		...many && pagination ? ["limit", "offset"] : [],
-		...allowAdjacent ? ["adjacent"] : []
+		...allowAdjacent ? ["adjacent", "payloads"] : []
 	];
 	if (Object.keys(options).some((key) => !allowed.includes(key))) invalidQuery("Unknown relational query option or unsupported scope option.");
 	const plan = emptyPlan(collection);
@@ -317,6 +380,11 @@ function relationalPlan(registry, collection, options = {}, many = true, allowAd
 		for (const [field, direction] of Object.entries(options.orderBy)) plan.order = checkedOrder(plan, field, direction, many);
 	}
 	for (const key of ["limit", "offset"]) if (options[key] !== void 0) plan[key] = checkedPagination(options[key], many);
+	if (options.payloads !== void 0) {
+		record$1(options.payloads, "payloads");
+		const payloads = checkedPayloads(registry, collection, options.payloads);
+		if (payloads) plan.payloads = payloads;
+	}
 	if (options.adjacent !== void 0) plan.adjacent = options.adjacent === true ? true : relationalPlan(registry, collection, options.adjacent, true, false, false);
 	return plan;
 }
@@ -523,6 +591,13 @@ function createBuilder(registry, run, plan, many = true, root = true, scopeToken
 				[name]: nested
 			} });
 		},
+		withPayload(name, variant) {
+			if (!allowAdjacent || Object.hasOwn(plan.payloads ?? {}, name)) invalidQuery("Payloads cannot be repeated or requested in adjacent scopes.");
+			return branch({ payloads: {
+				...plan.payloads,
+				[name]: checkedPayload(registry, plan.collection, name, variant)
+			} });
+		},
 		selectAdjacent(configure) {
 			if (!allowAdjacent || plan.adjacent !== void 0) invalidQuery("Adjacency cannot be repeated or selected recursively.");
 			if (configure === void 0) return branch({ adjacent: true });
@@ -541,6 +616,7 @@ function createBuilder(registry, run, plan, many = true, root = true, scopeToken
 			if (!root) invalidQuery("Nested builders have no terminal methods.");
 			return run(plan, "all");
 		},
+		/** Executes a selected root query, matching direct await behavior. */
 		execute() {
 			if (!root) invalidQuery("Nested builders have no terminal methods.");
 			return run(plan, "all");
@@ -567,7 +643,9 @@ function createBuilder(registry, run, plan, many = true, root = true, scopeToken
 /** Defers collection validation until from(), preserving the immutable selection across reuse. */
 function createSelect(registry, run, fields) {
 	const selected = [...fields];
-	return { from(collection) {
+	return { 
+	/** Binds the current registry and prepares a reusable root query. */
+from(collection) {
 		const current = registry();
 		if (!Object.hasOwn(current, collection)) invalidQuery(`Unknown collection "${collection}".`);
 		const plan = emptyPlan(collection);
@@ -718,6 +796,7 @@ function neighborScope(plan, records, preserveOrder, scopes, revision) {
 		exclude: void 0,
 		with: {},
 		adjacent: void 0,
+		payloads: void 0,
 		limit: void 0,
 		offset: void 0
 	} : selection;
@@ -739,16 +818,20 @@ function neighborScope(plan, records, preserveOrder, scopes, revision) {
 	}
 	return scope;
 }
-/** Projects one entry and requested relationships/adjacency from one pinned revision. */
-function project(record, plan, revision, scopes, scopeRecords, preserveScopeOrder = false) {
+/**
+* Projects one entry and requested relationships/adjacency from one pinned revision.
+* Requested payloads are recorded for the caller to load after projection.
+*/
+function project(record, plan, revision, scopes, scopeRecords, requests, preserveScopeOrder = false) {
 	if (!plan.select && !plan.allFields && !plan.adjacent) invalidQuery("Row-returning queries require select().");
-	const result = detachSelection(record, plan.allFields ? Object.keys(record).filter((field) => !plan.exclude?.includes(field)) : plan.select ?? []);
+	const fields = plan.allFields ? Object.keys(record).filter((field) => !plan.exclude?.includes(field)) : plan.select ?? [];
+	const result = detachSelection(record, fields);
 	for (const [name, nested] of Object.entries(plan.with)) {
 		const relation = revision.registry[plan.collection].relationships[name];
 		if (!relation || relation.collection !== nested.collection || relation.type === "one" && (nested.limit !== void 0 || nested.offset !== void 0 || nested.order.length > 0)) invalidQuery(`Relationship "${name}" no longer matches the prepared query scope.`);
 		const candidates = revision.relations.get(relationKey(plan.collection, name))?.get(record.id) ?? [];
 		const preserveOrder = relation.referenceSide === "from" && Array.isArray(record[relation.from]);
-		const selected = pageRecords(candidates, nested, revision, preserveOrder).map((entry) => project(entry, nested, revision, scopes, candidates, preserveOrder));
+		const selected = pageRecords(candidates, nested, revision, preserveOrder).map((entry) => project(entry, nested, revision, scopes, candidates, requests, preserveOrder));
 		Object.defineProperty(result, name, {
 			value: relation.type === "many" ? selected : selected[0] ?? null,
 			enumerable: true,
@@ -763,25 +846,39 @@ function project(record, plan, revision, scopes, scopeRecords, preserveScopeOrde
 		const previous = index === void 0 ? void 0 : scope.records[index - 1];
 		const next = index === void 0 ? void 0 : scope.records[index + 1];
 		result._adjacent = {
-			previous: previous ? project(previous, scope.plan, revision, scopes, candidates) : null,
-			next: next ? project(next, scope.plan, revision, scopes, candidates) : null
+			previous: previous ? project(previous, scope.plan, revision, scopes, candidates, requests) : null,
+			next: next ? project(next, scope.plan, revision, scopes, candidates, requests) : null
 		};
 	}
+	if (plan.payloads) requests.push({
+		target: result,
+		collection: plan.collection,
+		id: record.id,
+		payloads: plan.payloads
+	});
 	return result;
 }
-/** Runs the shared JavaScript executor; future adapters can execute the same plan. */
-async function executeQuery(revision, plan, terminal) {
+/**
+* Runs the shared JavaScript executor; future adapters can execute the same plan.
+* Rows that requested payloads are appended to `requests` for loading after execution.
+*/
+async function executeQuery(revision, plan, terminal, requests = []) {
 	const collection = revision.collections[plan.collection];
 	if (!collection) invalidQuery(`Unknown collection "${plan.collection}".`);
-	if (terminal === "count") return queryCandidates(collection.records, plan).filter((record) => plan.filters.every((expression) => matches(record, expression, revision, plan.collection))).length;
+	if (terminal === "count") {
+		if (plan.payloads) invalidQuery("Counts cannot request payloads.");
+		return queryCandidates(collection.records, plan).filter((record) => plan.filters.every((expression) => matches(record, expression, revision, plan.collection))).length;
+	}
 	if (!plan.select && !plan.allFields && !plan.adjacent) invalidQuery("Row-returning queries require select().");
 	const records = pageRecords(queryCandidates(collection.records, plan), plan, revision);
 	const scopes = /* @__PURE__ */ new WeakMap();
-	return terminal === "first" ? records[0] ? project(records[0], plan, revision, scopes, collection.records) : void 0 : records.map((record) => project(record, plan, revision, scopes, collection.records));
+	return terminal === "first" ? records[0] ? project(records[0], plan, revision, scopes, collection.records, requests) : void 0 : records.map((record) => project(record, plan, revision, scopes, collection.records, requests));
 }
 //#endregion
 //#region src/runtime/content.ts
 assertServerOnly();
+/** Maximum payload loads in flight for one query. */
+const PAYLOAD_CONCURRENCY = 16;
 /** Pins the latest valid revision for an entire asynchronous operation. */
 async function pinned(state, operation) {
 	if (state.error) throw state.error;
@@ -797,38 +894,26 @@ async function pinned(state, operation) {
 		revision.active--;
 	}
 }
-const idSets = /* @__PURE__ */ new WeakMap();
-/** Indexes immutable prepared records once, so body/render lookups avoid collection scans. */
-function entryIds(records) {
-	let ids = idSets.get(records);
-	if (!ids) {
-		ids = new Set(records.map((record) => record.id));
-		idSets.set(records, ids);
-	}
-	return ids;
-}
-/** Looks up an entry and lazily loads only its revision-specific payload. */
-async function loadPayload(revision, collectionName, id) {
-	const collection = revision.collections[collectionName];
-	if (!collection || typeof collectionName !== "string" || typeof id !== "string") invalidQuery("Body/render access requires a registered collection and string ID.");
-	if (!entryIds(collection.records).has(id)) throw new ContentError({
-		code: "entry-not-found",
-		collection: collectionName,
-		id,
-		message: `Entry "${id}" does not exist in "${collectionName}".`
-	});
-	const key = JSON.stringify([collectionName, id]);
+/** Checks a decoded built-in payload before any of its values reach a query result. */
+function validBuiltinPayload(payload) {
+	if (!payload || typeof payload !== "object" || Array.isArray(payload)) return false;
+	const { body, markdown, rendered } = payload;
+	return (body === void 0 || typeof body === "string") && (markdown === void 0 || typeof markdown === "string") && (rendered === void 0 || !!rendered && typeof rendered.html === "string" && Array.isArray(rendered.headings) && rendered.headings.every((heading) => !!heading && Number.isInteger(heading.depth) && heading.depth >= 1 && heading.depth <= 6 && typeof heading.slug === "string" && typeof heading.text === "string"));
+}
+/** Lazily loads one entry's built-in payload once per revision, retrying after failures. */
+function loadBuiltin(revision, collection, id) {
+	const key = JSON.stringify([collection, id]);
 	let loaded = revision.payloadCache.get(key);
 	if (!loaded) {
 		loaded = Promise.resolve().then(async () => {
-			const payload = await (collection.payloads.get(id)?.() ?? {});
-			if (!payload || typeof payload !== "object" || Array.isArray(payload) || payload.body !== void 0 && typeof payload.body !== "string" || payload.markdown !== void 0 && typeof payload.markdown !== "string" || payload.rendered !== void 0 && (!payload.rendered || typeof payload.rendered.html !== "string" || !Array.isArray(payload.rendered.headings) || payload.rendered.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 prepared payload shape.");
+			const payload = await revision.collections[collection].builtins.get(id)?.() ?? {};
+			if (!validBuiltinPayload(payload)) throw new Error("Invalid prepared payload shape.");
 			return payload;
 		}).catch((cause) => {
 			revision.payloadCache.delete(key);
 			throw contentError(cause, {
 				code: "artifact-error",
-				collection: collectionName,
+				collection,
 				id,
 				message: "Could not load the prepared entry payload."
 			});
@@ -837,10 +922,84 @@ async function loadPayload(revision, collectionName, id) {
 	}
 	return loaded;
 }
+/** Returns supplied or eagerly compiled output, or renders captured Markdown once per revision. */
+async function renderedPayload(revision, collection, id) {
+	const payload = await loadBuiltin(revision, collection, id);
+	if (payload.rendered) return payload.rendered;
+	if (payload.markdown === void 0) throw new ContentError({
+		code: "not-renderable",
+		collection,
+		id,
+		message: "This entry has no supplied output or supported rendering path."
+	});
+	const key = JSON.stringify([collection, id]);
+	let rendered = revision.renderCache.get(key);
+	if (!rendered) {
+		rendered = Promise.resolve().then(() => {
+			if (!revision.renderMarkdown) throw new Error("Missing packaged Markdown renderer.");
+			return revision.renderMarkdown(payload.markdown);
+		}).catch((cause) => {
+			revision.renderCache.delete(key);
+			throw contentError(cause, {
+				code: "render-error",
+				collection,
+				id,
+				message: "Markdown rendering failed."
+			});
+		});
+		revision.renderCache.set(key, rendered);
+	}
+	return rendered;
+}
+/** Loads one requested payload value from the pinned revision. */
+async function loadPayload(revision, collection, id, name) {
+	if (name === "_body") return (await loadBuiltin(revision, collection, id)).body;
+	if (name === "_rendered") return renderedPayload(revision, collection, id);
+	invalidQuery(`Payload "${name}" no longer matches the prepared collection.`);
+}
+/**
+* Loads every requested payload with bounded concurrency, then attaches detached copies under
+* `_payloads`. Each distinct payload loads once; rows that share an entry get independent values.
+*/
+async function attachPayloads(revision, requests) {
+	if (!requests.length) return;
+	const loads = /* @__PURE__ */ new Map();
+	for (const request of requests) for (const name of Object.keys(request.payloads)) {
+		const key = JSON.stringify([
+			request.collection,
+			request.id,
+			name,
+			request.payloads[name]
+		]);
+		if (!loads.has(key)) loads.set(key, {
+			collection: request.collection,
+			id: request.id,
+			name
+		});
+	}
+	const keys = [...loads.keys()];
+	const values = await mapConcurrent(keys, PAYLOAD_CONCURRENCY, (key) => {
+		const { collection, id, name } = loads.get(key);
+		return loadPayload(revision, collection, id, name);
+	});
+	const loaded = new Map(keys.map((key, index) => [key, values[index]]));
+	for (const request of requests) request.target._payloads = Object.fromEntries(Object.keys(request.payloads).map((name) => [name, detach(loaded.get(JSON.stringify([
+		request.collection,
+		request.id,
+		name,
+		request.payloads[name]
+	])))]));
+}
 /** Creates the initialized runtime without importing source configuration or schemas. */
 function createRuntime(state) {
-	/** Pins both query frontends to exactly the same revision and backend executor. */
-	const run = (plan, terminal) => pinned(state, (revision) => revision.execute ? revision.execute(normalizePlan(plan), terminal) : executeQuery(revision, normalizePlan(plan), terminal));
+	/** Pins query execution and payload loading to exactly the same revision and executor. */
+	const run = (plan, terminal) => pinned(state, async (revision) => {
+		const normalized = normalizePlan(plan);
+		const requests = [];
+		const result = revision.execute ? await revision.execute(normalized, terminal, requests) : await executeQuery(revision, normalized, terminal, requests);
+		await attachPayloads(revision, requests);
+		return result;
+	});
 	/** Reads the current registry without capturing a development revision in either API. */
 	const registry = () => state.registry ?? state.revision?.registry ?? {};
 	return {
@@ -850,39 +1009,6 @@ function createRuntime(state) {
 		query: createQueryNamespace(registry, run),
 		count(collection, options = {}) {
 			return run(relationalPlan(registry(), collection, options), "count");
-		},
-		readBody(collection, id) {
-			return pinned(state, async (revision) => (await loadPayload(revision, collection, id)).body);
-		},
-		render(collection, id) {
-			return pinned(state, async (revision) => {
-				const payload = await loadPayload(revision, collection, id);
-				if (payload.rendered) return detach(payload.rendered);
-				if (payload.markdown === void 0) throw new ContentError({
-					code: "not-renderable",
-					collection,
-					id,
-					message: "This entry has no supplied output or supported rendering path."
-				});
-				const key = JSON.stringify([collection, id]);
-				let rendered = revision.renderCache.get(key);
-				if (!rendered) {
-					rendered = Promise.resolve().then(() => {
-						if (!revision.renderMarkdown) throw new Error("Missing packaged Markdown renderer.");
-						return revision.renderMarkdown(payload.markdown);
-					}).catch((cause) => {
-						revision.renderCache.delete(key);
-						throw contentError(cause, {
-							code: "render-error",
-							collection,
-							id,
-							message: "Markdown rendering failed."
-						});
-					});
-					revision.renderCache.set(key, rendered);
-				}
-				return detach(await rendered);
-			});
 		}
 	};
 }

package/dist/{descriptor-Xbo9u5eR.d.mts → descriptor-D9Th5hzk.d.mts}

@@ -1,5 +1,4 @@
-import { f as MaybePromise } from "./types-hmDOw87q.mjs";
-
+import { p as MaybePromise } from "./types-ChaNhj42.mjs";
 //#region src/loaders/descriptor.d.ts
 type GlobOptions = {
   pattern: string | string[];

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

@@ -1,5 +1,5 @@
-import { t as ContentError } from "./errors-C8lWyiy2.mjs";
-import { o as encode, r as decode } from "./values-B7lo_2_x.mjs";
+import { t as ContentError } from "./errors-C2iuBM0G.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. */
 function diagnosticGraph(value, causes, restore, seen = /* @__PURE__ */ new Map()) {
@@ -50,20 +50,21 @@ function diagnosticGraph(value, causes, restore, seen = /* @__PURE__ */ new Map(
 /** Encodes contextual development failures without reducing BigInts or structured issues to JSON. */
 function serializeContentError(error) {
 	const causes = /* @__PURE__ */ new Set();
+	const details = {
+		code: error.code,
+		message: error.message,
+		stack: error.stack,
+		operation: error.operation,
+		collection: error.collection,
+		id: error.id,
+		source: error.source,
+		path: error.path,
+		issues: error.issues,
+		cause: error.cause,
+		diagnostics: error.diagnostics
+	};
 	return encode({
-		error: diagnosticGraph({
-			code: error.code,
-			message: error.message,
-			stack: error.stack,
-			operation: error.operation,
-			collection: error.collection,
-			id: error.id,
-			source: error.source,
-			path: error.path,
-			issues: error.issues,
-			cause: error.cause,
-			diagnostics: error.diagnostics
-		}, causes, false),
+		error: diagnosticGraph(details, causes, false),
 		causes: [...causes]
 	});
 }