content-query 0.4.0 → 0.5.0

package/README.md

@@ -9,6 +9,7 @@ Use it with your existing framework. Your application owns its routes, layouts,
 - **Typed schemas.** Validate metadata with bundled schema builders or any Standard Schema V1 provider, with inferred TypeScript types.
 - **Flexible sources.** Load local files, use Astro-compatible content loaders, or write your own loader.
 - **Queries and relationships.** Select fields, filter, sort, paginate, and load related entries with validated references.
+- **Per-collection entries.** Import each collection from its own generated module with named types such as `ContentPost`, so a route bundles and traces only the collections it uses.
 - **Markdown rendering.** Request HTML, headings, and syntax highlighting as query payloads, loaded only when a query asks for them.
 - **Custom payloads.** Declare schema-validated per-entry data, optionally by variant such as locale, resolved during the build from tracked related files, and loaded only when a query names it. Development edits re-resolve only the variants whose files changed.
 - **Optional MDX companion.** [`@content-query/mdx`](https://github.com/yangshun/content-query/tree/main/packages/mdx) supplies React islands and ordinary React document modules with Vite SSR. Core has no MDX or React dependency.
@@ -45,55 +46,65 @@ Add Markdown files with `title` frontmatter under `content/posts/`, then build:
 npx content-query build
 ```
 
-Query the generated module from server code:
+Each collection gets its own generated entry, which exports the collection under its name. Query it from server code:
 
 ```ts
-import { content } from "./.content-query/server.js";
+import { posts } from "./.content-query/collections/posts/server.js";
 import { eq } from "content-query/query";
 
-const posts = await content
-  .from("posts")
+const summaries = await posts
   .select("id", "title")
   .where((fields) => eq(fields.draft, false))
   .orderBy("title");
 
-const post = await content.query.posts.findFirst({
-  where: { id: posts[0]!.id },
+const post = await posts.findFirst({
+  where: { id: summaries[0]!.id },
   payloads: { _rendered: true },
 });
 const { html, headings } = post!._payloads._rendered;
 ```
 
+Built-in payloads are `_body` and `_rendered`. JSON, YAML, and TOML sources and `file()` collections have none, and a custom `BodyLoader` offers only `_body`. A query for a missing entry returns `undefined`.
+
+An entry imports only its own collection's data, so a route that imports `posts` never bundles or traces another collection. With Vite, import from `content-query:collections/posts`. Elsewhere, such as in Next.js, map the entries in `package.json` to import `{ posts }` from `#content-query/posts` at any directory depth:
+
+```json
+{
+  "imports": {
+    "#content-query/*": "./.content-query/collections/*/server.js"
+  }
+}
+```
+
 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.
 
-Add `.content-query/` to `.gitignore`. Follow the quick start for a complete walkthrough, or choose a framework example below.
+To follow a relationship, pass its target collection to `using()`. Nothing related loads implicitly:
+
+```ts
+import { authors } from "#content-query/authors";
+import { posts } from "#content-query/posts";
 
-## Migrating to 0.4
+const withAuthors = await posts.using(authors).findMany({
+  columns: { title: true },
+  with: { author: { columns: { name: true } } },
+});
+```
 
-Version 0.4.0 starts fluent queries from the collection and selects no data implicitly:
+A relationship whose target was not supplied is a type error and throws `invalid-query`. Nested relationships need every collection they reach, such as `posts.using(authors, publishers)`. Self-relationships need nothing.
 
-| 0.3                                           | 0.4                                                                                |
-| --------------------------------------------- | ---------------------------------------------------------------------------------- |
-| `content.select("id", "title").from("posts")` | `content.from("posts").select("id", "title")`                                      |
-| `content.select().from("posts")`              | `content.from("posts").select(...)` listing the fields used                        |
-| `findMany()` or `findMany({ where })`         | Add `columns: { field: true }` for each field used                                 |
-| `columns: { draft: false }`                   | List the included fields with `true`                                               |
-| `with: { author: true }`                      | `with: { author: { columns: { name: true } } }`                                    |
-| `adjacent: true` or `.selectAdjacent()`       | `adjacent: { scope: "results", columns: { id: true } }` or `.selectAdjacent("id")` |
+Each entry also exports the collection's types. `ContentPost` is a full entry; pass the selected fields to type query results, such as props for a list component:
 
-Results include `id` only when it is selected. Queries that request only payloads, such as `findFirst({ where: { id }, payloads: { _rendered: true } })`, need no columns.
+```ts
+import type { ContentPost } from "#content-query/posts";
 
-## Migrating to 0.2
+type PostLink = ContentPost<"id" | "title">; // What select("id", "title") returns.
+```
 
-Version 0.2.0 removes `content.readBody()` and `content.render()`. Request bodies and rendered output as payloads in the query that loads the entry:
+Type names are `Content` plus the export name, capitalized and made singular by dropping one trailing `s` (`jobs` gives `ContentJob`, `coding` gives `ContentCoding`). Set `typeName: "Category"` in `defineCollection()` for irregular plurals. Declared payloads are typed as `ContentPostPayload<"detail">`. Collection names that are not identifiers are converted for the export and import path, such as `blog-posts` to `blogPosts`; two collections that would share an export or type name fail the build.
 
-| 0.1                                   | 0.2                                                                                                            |
-| ------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| `await content.readBody("posts", id)` | `(await content.query.posts.findFirst({ where: { id }, payloads: { _body: true } }))?._payloads._body`         |
-| `await content.render("posts", id)`   | `(await content.query.posts.findFirst({ where: { id }, payloads: { _rendered: true } }))?._payloads._rendered` |
-| Fluent queries                        | Add `.withPayload("_rendered")` or `.withPayload("_body")` before the terminal.                                |
+Paginate root queries in one call. `paginate({ page: 2, size: 10 })` returns `items`, `total`, `page`, `pageCount`, `hasNextPage`, and `hasPreviousPage` for numbered archive pages. `paginate({ size: 10, after: previous.endCursor })` returns cursor pages with `startCursor` and `endCursor` for "load more" lists. Both work in fluent queries and in `posts.paginate()`; see [pagination](https://github.com/yangshun/content-query/blob/main/docs/API.md#pagination).
 
-Built-in payload names start with an underscore: `_body` and `_rendered`. A query for a missing entry returns `undefined` instead of rejecting with `entry-not-found`, which no longer exists. JSON, YAML, and TOML sources and `file()` collections offer no payloads, and custom loaders typed as `BodyLoader` offer only `_body`. Rebuild generated content after upgrading; 0.1 artifacts are rejected.
+Add `.content-query/` to `.gitignore`. Follow the quick start for a complete walkthrough, or choose a framework example below.
 
 ## Documentation
 
@@ -104,7 +115,7 @@ Built-in payload names start with an underscore: `_body` and `_rendered`. A quer
 
 The Vite integration supports Vite 8, and the Next.js integration supports Next.js 15 and 16. Both integrations are optional; standalone builds and queries require neither framework.
 
-To allow only one query API, export `queryStyle` from the config: `export const queryStyle = "relational";` keeps `content.query` and `content.count()`, and `"fluent"` keeps `content.from()`. Generated types report the disabled API in the editor, and the runtime throws an `invalid-query` error for it. See [query style](https://github.com/yangshun/content-query/blob/main/docs/API.md#query-style).
+To allow only one query API, export `queryStyle` from the config: `export const queryStyle = "relational";` keeps `posts.findMany()`, `findFirst()`, `paginate()`, and `count(options)`, and `"fluent"` keeps `posts.select()` and the other fluent starters. `count()` without options works in both. Generated types report the disabled API in the editor, and the runtime throws an `invalid-query` error for it. See [query style](https://github.com/yangshun/content-query/blob/main/docs/API.md#query-style).
 
 Pass `contentQuery()` directly to Vite or Vite+'s `plugins` array. No `Plugin` type cast is needed; workspace consumers share the pinned toolchain versions in the dependency catalog.
 

package/dist/{build-CcqIpkes.mjs → build-DWpB69_c.mjs}

@@ -3,7 +3,8 @@ import { i as groupDiagnostics, n as contentError, o as payloadIdentity, r as de
 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 { a as isRelationship, i as variantKey, n as createRuntime, o as prepareRelationships, r as isQueryStyle, s as CODEC_VERSION } from "./content-BXrgP7nL.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 { 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";
@@ -19,7 +20,13 @@ import picomatch from "picomatch";
 function digest(value) {
 	return createHash("sha256").update(JSON.stringify(value)).digest("hex");
 }
-/** Maps collection names to distinct safe directory names without changing public identities. */
+/**
+* Maps collection and payload names to distinct safe directory names without changing public
+* identities. Names that are not portable directory names are base64url-encoded behind `~`.
+*
+* @param name - The collection or payload name.
+* @returns The directory name under `collections/` or a collection's `payloads/`.
+*/
 function directoryName(name) {
 	return /^[a-zA-Z][a-zA-Z0-9_-]*$/.test(name) && !/^(?:con|prn|aux|nul|com[0-9]|lpt[0-9])$/i.test(name) ? name : `~${Buffer.from(name).toString("base64url")}`;
 }
@@ -30,20 +37,43 @@ function compactJson(source) {
 	const compressed = JSON.stringify(gzipSync(source, { level: 1 }).toString("base64"));
 	return compressed.length < bytes * .9 ? compressed : void 0;
 }
-/** Creates portable ESM; build integrations can batch payload sources before a strict bundler runs. */
-async function revisionModules(revision, { payloadChunkBytes = 0 } = {}) {
+/** Picks a module-local binding that cannot shadow the entry's export name. */
+function binding(base, exportName) {
+	return base === exportName ? `${base}_` : base;
+}
+/**
+* Creates one collection's entry, which exports the collection's query handle under its export
+* name and imports only that collection's modules.
+*/
+function collectionEntry$1(manifest, name, exportName, index, renderer) {
+	const runtime = binding("runtime", exportName);
+	const data = binding("data", exportName);
+	const render = renderer ? `, body => import("content-query/internal/markdown").then(module => module.renderMarkdown(body))` : "";
+	return `import * as ${runtime} from "content-query/internal";\nimport ${data} from ${JSON.stringify(`./${index}`)};\nexport const ${exportName} = ${runtime}.createArtifactCollection(JSON.parse(${JSON.stringify(JSON.stringify(manifest))}), ${JSON.stringify(name)}, ${data}${render});\n`;
+}
+/**
+* Creates portable ESM; build integrations can batch payload sources before a strict bundler runs.
+*
+* Each collection gets `collections/<export name>/server.js`, which exports its query handle and
+* imports only that collection's modules, so a bundle that imports it never references the
+* modules of another collection.
+*
+* @param revision - The prepared revision to publish.
+* @param options - `payloadChunkBytes` batches payload modules for bundlers. `preparedEntry`
+* also emits `prepared-server.js`, which exports the whole revision for development facades.
+* @returns Module sources keyed by path relative to the output directory.
+*/
+async function revisionModules(revision, { payloadChunkBytes = 0, preparedEntry = false } = {}) {
 	const modules = /* @__PURE__ */ new Map();
-	const manifest = {
-		version: 2,
-		codec: CODEC_VERSION,
-		collections: revision.registry,
-		...revision.queryStyle ? { queryStyle: revision.queryStyle } : {}
-	};
-	const imports = [];
-	const names = [];
-	let needsRenderer = false;
+	const names = collectionNames(revision.registry);
+	/** Each collection's index module, for the optional prepared entry. */
+	const indexes = [];
+	let anyMarkdown = false;
 	for (const [name, collection] of Object.entries(revision.collections)) {
-		const directory = `collections/${directoryName(name)}`;
+		const { exportName } = names.get(name);
+		const directory = `collections/${exportName}`;
+		/** Whether the collection captured Markdown, which the packaged renderer renders on demand. */
+		let markdown = false;
 		const payloads = [];
 		const chunks = [];
 		let batch = [];
@@ -67,7 +97,7 @@ async function revisionModules(revision, { payloadChunkBytes = 0 } = {}) {
 		for (const [id, load] of collection.builtins) {
 			const payload = await load();
 			const encoded = encode(payload);
-			needsRenderer ||= payload.markdown !== void 0;
+			markdown ||= payload.markdown !== void 0;
 			if (payloadChunkBytes) {
 				const bytes = Buffer.byteLength(`[${JSON.stringify(id)}]: ${JSON.stringify(encoded)},\n`);
 				if (batchBytes && batchBytes + bytes > payloadChunkBytes) flushBatch();
@@ -114,53 +144,91 @@ async function revisionModules(revision, { payloadChunkBytes = 0 } = {}) {
 		const code = `${loaders}export default { records: ${compressedRecords ? `decodeCompressed(${compressedRecords})` : recordSource}, builtins: ${loading}${custom.length ? `, payloads: {\n${custom.join(",\n")}\n}` : ""} };\n`;
 		const index = `index-${digest(code)}.js`;
 		modules.set(`${directory}/${index}`, code);
-		modules.set(`${directory}/index.js`, `export { default } from ${JSON.stringify(`./${index}`)};\n`);
-		const binding = `collection${imports.length}`;
-		imports.push(`import ${binding} from ${JSON.stringify(`./${directory}/${index}`)};`);
-		names.push(`[${JSON.stringify(name)}]: ${binding}`);
+		const descriptor = revision.registry[name];
+		const manifest = {
+			version: 3,
+			codec: CODEC_VERSION,
+			collections: { [name]: {
+				relationships: descriptor.relationships,
+				...descriptor.payloads ? { payloads: descriptor.payloads } : {}
+			} },
+			...revision.queryStyle ? { queryStyle: revision.queryStyle } : {}
+		};
+		modules.set(`${directory}/server.js`, collectionEntry$1(manifest, name, exportName, index, markdown));
+		indexes.push([name, `./${directory}/${index}`]);
+		anyMarkdown ||= markdown;
+	}
+	if (preparedEntry) {
+		const manifest = {
+			version: 3,
+			codec: CODEC_VERSION,
+			collections: Object.fromEntries(Object.entries(revision.registry).map(([name, { relationships, payloads }]) => [name, {
+				relationships,
+				...payloads ? { payloads } : {}
+			}])),
+			...revision.queryStyle ? { queryStyle: revision.queryStyle } : {}
+		};
+		const render = anyMarkdown ? `, body => import("content-query/internal/markdown").then(module => module.renderMarkdown(body))` : "";
+		modules.set("prepared-server.js", `import { createArtifactRevision } from "content-query/internal";\n${indexes.map(([, specifier], index) => `import collection${index} from ${JSON.stringify(specifier)};`).join("\n")}\nexport const revision = createArtifactRevision(JSON.parse(${JSON.stringify(JSON.stringify(manifest))}), { ${indexes.map(([name], index) => `[${JSON.stringify(name)}]: collection${index}`).join(", ")} }${render});\nexport const registry = revision.registry;\nexport const error = undefined;\n`);
 	}
-	modules.set("manifest.js", `export default JSON.parse(${JSON.stringify(JSON.stringify(manifest))});\n`);
-	const renderer = needsRenderer ? `, body => import("content-query/internal/markdown").then(module => module.renderMarkdown(body))` : "";
-	modules.set("server.js", `import { createArtifactRuntime } from "content-query/internal";\n${imports.join("\n")}\nexport const content = createArtifactRuntime(JSON.parse(${JSON.stringify(JSON.stringify(manifest))}), { ${names.join(", ")} }${renderer});\n`);
 	return modules;
 }
 //#endregion
 //#region src/artifacts/declarations.ts
+/** Declares the config-bound `Registry` and `ConfiguredQueryStyle` aliases for one directory. */
+function configTypes(directory, config) {
+	let relative = path.relative(directory, config).replace(/\\/g, "/");
+	if (!relative.startsWith(".")) relative = `./${relative}`;
+	const source = JSON.stringify(relative);
+	return [`type Registry = typeof import(${source}).collections;`, `type ConfiguredQueryStyle = typeof import(${source}) extends { queryStyle: infer Style extends import("content-query/runtime").QueryStyle } ? Style : import("content-query/runtime").QueryStyle;`];
+}
 /**
-* Generates type-only consumer bindings without loading schemas or adding runtime imports.
+* Generates type-only bindings for one collection entry without loading schemas or adding runtime
+* imports.
 *
 * The registry and the optional `queryStyle` both come from the config module's types, so a
-* literal `export const queryStyle = "relational"` narrows `content` without a rebuild. A missing
+* literal `export const queryStyle = "relational"` narrows the export without a rebuild. A missing
 * export, or one typed as the whole `QueryStyle` union, allows both query styles.
 *
+* The entry type, such as `ContentJob`, is the full entry. `ContentJob<Field>` is the shape a
+* query returns when it selects `Field`: every selected key is present, and optional fields read
+* as `undefined` when missing, so query results and the type are assignable in both directions.
+*
 * @param directory - Directory that will contain the declaration file.
 * @param config - Absolute path of content-query.config.
-* @returns Declaration source for `server.d.ts`.
+* @param name - The collection's name in the registry.
+* @param names - The collection's generated export and type names.
+* @returns Declaration source for the entry's `server.d.ts`.
 */
-function contentDeclarations(directory, config) {
-	let relative = path.relative(directory, config).replace(/\\/g, "/");
-	if (!relative.startsWith(".")) relative = `./${relative}`;
-	const source = JSON.stringify(relative);
+function collectionDeclarations(directory, config, name, { exportName, typeName, payloadTypeName }) {
+	const key = JSON.stringify(name);
+	const definition = `Registry[${key}]`;
+	const data = `import("content-query").QueryData<${definition}>`;
 	return [
-		`type Registry = typeof import(${source}).collections;`,
-		`type ConfiguredQueryStyle = typeof import(${source}) extends { queryStyle: infer Style extends import("content-query/runtime").QueryStyle } ? Style : import("content-query/runtime").QueryStyle;`,
-		`export type CollectionKey = keyof Registry & string;`,
-		`export type CollectionData<Name extends CollectionKey> = import("content-query").QueryData<Registry[Name]>;`,
-		`export type Collections = { [Name in CollectionKey]: CollectionData<Name> };`,
-		`export type CollectionPayload<Name extends CollectionKey, Payload extends keyof import("content-query").PayloadsOf<Registry[Name]>> = import("content-query").PayloadData<Registry[Name], Payload>;`,
-		`export declare const content: import("content-query/runtime").Content<Registry, ConfiguredQueryStyle>;`,
+		...configTypes(directory, config),
+		`/** The ${exportName} collection. Start queries here, or pass it to another collection's \`using()\` to follow relationships into it. */`,
+		`export declare const ${exportName}: import("content-query/runtime").Collection<Registry, ${key}, ConfiguredQueryStyle>;`,
+		`/** A ${exportName} entry: its ID, validated metadata, and computed fields. Pass field names, such as \`${typeName}<"id">\`, for the shape a query returns when it selects them. */`,
+		`export type ${typeName}<Field extends keyof ${data} = keyof ${data}> = keyof ${data} extends Field ? ${data} : { [Key in Field]: ${data}[Key] };`,
+		`/** The value of one payload that the ${exportName} collection declares. */`,
+		`export type ${payloadTypeName}<Payload extends keyof import("content-query").PayloadsOf<${definition}>> = import("content-query").PayloadData<${definition}, Payload>;`,
 		``
 	].join("\n");
 }
 /**
-* Declares project-bound virtual server types and the framework-neutral development bridge.
+* Declares project-bound virtual collection modules and the framework-neutral development bridge.
 *
 * @param directory - Directory that will contain the declaration file.
 * @param config - Absolute path of content-query.config.
-* @returns Declaration source for the `content-query:server` and `content-query:client` modules.
+* @param names - Every collection's generated names, keyed by collection name.
+* @returns Declaration source for the `content-query:collections/<export name>` and
+* `content-query:client` modules, plus the type-only `content-query:collections` module, whose
+* `CollectionKey` names every collection for integrations that accept a collection name.
 */
-function virtualDeclarations(directory, config) {
-	return `declare module "content-query:server" {\n${contentDeclarations(directory, config).replace("export declare const", "export const")}\n}\ndeclare module "content-query:client" {\n  export function onContentUpdate(callback: () => void | Promise<void>): () => void;\n}\n`;
+function virtualDeclarations(directory, config, names) {
+	const collections = [...names].map(([name, generated]) => `declare module "content-query:collections/${generated.exportName}" {\n${collectionDeclarations(directory, config, name, generated).replace("export declare const", "export const")}}\n`);
+	const keys = `declare module "content-query:collections" {\n${configTypes(directory, config)[0]}\n/** Names of the configured collections, for integrations that accept a collection name. Types only: import collections from their own modules. */\nexport type CollectionKey = keyof Registry & string;\n}\n`;
+	return `${collections.join("")}${keys}declare module "content-query:client" {\n  export function onContentUpdate(callback: () => void | Promise<void>): () => void;\n}\n`;
 }
 //#endregion
 //#region src/artifacts/write.ts
@@ -213,6 +281,8 @@ async function writeImmutable(filename, source) {
 	}
 }
 const immutableModule = /\/(?:entries\/[a-f0-9]{64}|payloads\/[^/]+\/[a-f0-9]{64}|index-[a-f0-9]{64})\.js$/;
+/** Matches each collection's entry, which imports the collection's other modules. */
+const collectionEntry = /^collections\/[^/]+\/server\.js$/;
 /** Lists one directory's entries, treating a missing directory or a file as empty. */
 async function entriesOf(directory) {
 	try {
@@ -250,20 +320,35 @@ async function pruneArtifacts(outDir, modules) {
 		const payloadDirectories = await entriesOf(payloads);
 		const candidates = [...(await entriesOf(owned)).map((name) => `collections/${directory}/${name}`), ...(await entriesOf(entries)).map((name) => `collections/${directory}/entries/${name}`)];
 		for (const payload of payloadDirectories) candidates.push(...(await entriesOf(path.join(payloads, payload))).map((name) => `collections/${directory}/payloads/${payload}/${name}`));
-		for (const filename of candidates) if ((immutableModule.test(`/${filename}`) || filename.endsWith(`/${directory}/index.js`)) && !modules.has(filename)) await rm(path.join(outDir, filename), { force: true });
+		for (const filename of candidates) {
+			const generated = immutableModule.test(`/${filename}`) || filename.endsWith(`/${directory}/server.js`);
+			const declarations = filename.endsWith(`/${directory}/server.d.ts`) && !modules.has(filename.replace(/\.d\.ts$/, ".js"));
+			if (generated && !modules.has(filename) || declarations) await rm(path.join(outDir, filename), { force: true });
+		}
 		await removeIfEmpty(entries);
 		for (const payload of payloadDirectories) await removeIfEmpty(path.join(payloads, payload));
 		await removeIfEmpty(payloads);
 		await removeIfEmpty(owned);
 	}
 }
-/** Stages modules with bounded I/O before atomically switching the public server entry. */
+/**
+* Stages modules with bounded I/O before switching each collection's public entry.
+*
+* @param revision - The prepared revision to publish.
+* @param outDir - The generated output directory.
+* @param config - Absolute path of content-query.config, which declarations import types from.
+* @param options - `signal` cancels the write; `prune` removes superseded modules.
+*/
 async function writeArtifacts(revision, outDir, config, { signal, prune = false } = {}) {
 	const modules = await revisionModules(revision);
+	const names = collectionNames(revision.registry);
 	await writeChanged(path.join(outDir, "package.json"), "{\"type\":\"module\",\"private\":true}\n");
-	await writeChanged(path.join(outDir, "server.d.ts"), contentDeclarations(outDir, config));
-	await writeChanged(path.join(outDir, "types.d.ts"), virtualDeclarations(outDir, config));
-	const staged = [...modules].filter(([filename]) => filename !== "server.js");
+	await writeChanged(path.join(outDir, "types.d.ts"), virtualDeclarations(outDir, config, names));
+	for (const [name, generated] of names) {
+		const directory = path.join(outDir, "collections", generated.exportName);
+		await writeChanged(path.join(directory, "server.d.ts"), collectionDeclarations(directory, config, name, generated));
+	}
+	const staged = [...modules].filter(([filename]) => !collectionEntry.test(filename));
 	const directories = new Set(staged.map(([filename]) => path.dirname(path.join(outDir, filename))));
 	await Promise.all([...directories].map(async (directory) => mkdir(directory, { recursive: true })));
 	const pending = staged.values();
@@ -275,7 +360,7 @@ async function writeArtifacts(revision, outDir, config, { signal, prune = false
 		}
 	}))).find((outcome) => outcome.status === "rejected");
 	if (failure?.status === "rejected") throw failure.reason;
-	await writeChanged(path.join(outDir, "server.js"), modules.get("server.js"), signal);
+	for (const [filename, code] of modules) if (collectionEntry.test(filename)) await writeChanged(path.join(outDir, filename), code, signal);
 	if (prune) await pruneArtifacts(outDir, modules);
 }
 //#endregion
@@ -319,7 +404,8 @@ function queryRegistry(registry) {
 		payloads: {
 			...hasBuiltinPayloads(definition) ? builtinPayloads : {},
 			...customPayloads(definition)
-		}
+		},
+		...definition.typeName === void 0 ? {} : { typeName: definition.typeName }
 	}]));
 }
 //#endregion
@@ -872,6 +958,7 @@ async function loadRegistry(config) {
 	const registry = imported.collections;
 	if (!registry || typeof registry !== "object" || Array.isArray(registry)) throw new Error("content-query.config must export a collections registry.");
 	for (const [name, definition] of Object.entries(registry)) if (!name || !definition || typeof definition !== "object" || !("loader" in definition) || !definition.loader || typeof definition.loader !== "object" || !("name" in definition.loader) || typeof definition.loader.name !== "string" || !definition.loader.name || !("load" in definition.loader) || typeof definition.loader.load !== "function") throw new Error(`Collection "${name}" requires a named loader object with load(context).`);
+	collectionNames(registry);
 	return {
 		registry,
 		dependencies,
@@ -1626,8 +1713,8 @@ function sessionInternals(session) {
 * Creates a preparation session with ordered source commands and atomic revision publication.
 *
 * @param options - Root, configuration, watch, and publication settings.
-* @returns A session whose `content` is typed by `Style`; each published revision carries the
-* configured `queryStyle`, which the runtime enforces.
+* @returns A session whose `collections` are typed by `Style`; each published revision carries
+* the configured `queryStyle`, which the runtime enforces.
 */
 async function createSession(options) {
 	options = {
@@ -1996,7 +2083,7 @@ async function createSession(options) {
 		});
 	}
 	const session = {
-		content: createRuntime(state),
+		collections: createCollections(state),
 		sources,
 		subscribe(listener) {
 			if (disposed) throw new Error("Content session has been disposed.");
@@ -2160,4 +2247,4 @@ async function buildAtRoot(root, options, change) {
 	});
 }
 //#endregion
-export { sessionInternals as a, contentDeclarations as c, resolveConfigPath as i, virtualDeclarations as l, buildContent as n, withinDirectory as o, configCandidates as r, writeChanged as s, buildAtRoot as t, revisionModules as u };
+export { sessionInternals as a, collectionDeclarations as c, resolveConfigPath as i, virtualDeclarations as l, buildContent as n, withinDirectory as o, configCandidates as r, writeChanged as s, buildAtRoot as t, revisionModules as u };

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

@@ -1,6 +1,7 @@
-import { i as InvalidRelationships, o as ContentError, t as Content } from "./content-CwTKqRs9.mjs";
-import { i as CollectionRegistry } from "./types-DbFfF6JE.mjs";
-import { n as QueryStyle } from "./query-style-eXENQJ0O.mjs";
+import { a as InvalidRelationships, r as CollectionHandles, s as ContentError } from "./collection-types-CsQtGw7_.mjs";
+import { i as CollectionRegistry } from "./types-Dz1vTXa2.mjs";
+import { n as QueryStyle } from "./query-style-C2FcT1f9.mjs";
+import "./revision-DBwU-aC9.mjs";
 //#region src/preparation/session.d.ts
 /** A local source captured by a successfully prepared content revision. */
 type ContentSourceEntry = Readonly<{
@@ -22,8 +23,12 @@ type ContentSourceEvent = {
   error: ContentError;
 };
 type ContentSession<Registry extends CollectionRegistry = {}, Style extends QueryStyle = QueryStyle> = {
-  /** Root query APIs are typed by `Style`; the configured `queryStyle` is enforced at runtime. */
-  content: Content<Registry, Style>;
+  /**
+   * One query handle per collection, keyed by collection name, like the generated entries export.
+   * Each loads only its own collection; pass others to `using()` to follow relationships. Members
+   * are typed by `Style`; the configured `queryStyle` is enforced at runtime.
+   */
+  collections: CollectionHandles<Registry, Style>;
   /** Reads the latest successful source snapshot; current preparation errors are rethrown. */
   sources(): ContentSourceSnapshot;
   /** Observes subsequent publications and failures; returns an idempotent unsubscribe function. */

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