@pitlane/content 0.1.0

package/dist/index.mjs

@@ -0,0 +1,313 @@
+import { n as missingRenderer, r as parseEntryData, t as ContentError } from "./parse-DoKe2tNa.mjs";
+import { t as HOT_COLLECTION } from "./symbols-DmXlrDbX.mjs";
+import { contentRoot, isPrebuilding, prebuiltManifest, recordConfiguredSatteri, recordPrebuilt, recordWatched, registerPrebuild } from "./prebuild.mjs";
+//#region src/reference.ts
+/**
+* A schema that reads an entry id and outputs a pointer into `collection`.
+*
+* Built by hand rather than with `remix/data-schema`'s `createSchema`, so that
+* reading a JSON file into a validated collection needs no framework. The
+* shape is the one `s.object`, `s.array`, and `s.optional` require of anything
+* they hold, so a reference still composes inside them like any other schema.
+*
+* It does not check that the target exists: the collection it points at may
+* not be populated yet, and populating it to check would turn reading one
+* entry into loading every collection it references. A dangling pointer
+* surfaces as `getEntry` resolving to `undefined`.
+*/
+function reference(collection) {
+	return chainable((value, context) => {
+		if (typeof value !== "string") {
+			let message = `Expected a reference id for collection "${collection}"`;
+			return { issues: [context.path.length > 0 ? {
+				message,
+				path: context.path
+			} : { message }] };
+		}
+		return { value: {
+			collection,
+			id: value
+		} };
+	});
+}
+/**
+* Wraps a validator in the chainable surface.
+*
+* `pipe` and `refine` return the schema unchanged. A reference validates a
+* fixed shape, so a check on top of it belongs on the combinator that consumes
+* the resolved entry; they exist because the type requires them and a caller
+* that chains one should get a schema back rather than `undefined`.
+*/
+function chainable(run) {
+	let schema = {
+		"~standard": {
+			version: 1,
+			vendor: "pitlane-content",
+			validate: (value) => run(value, { path: [] })
+		},
+		"~run": run,
+		pipe: () => schema,
+		refine: () => schema,
+		transform: (transformer) => chainable((value, context) => {
+			let result = run(value, context);
+			if (result.issues) return result;
+			return { value: transformer(result.value) };
+		})
+	};
+	return schema;
+}
+//#endregion
+//#region src/store.ts
+/**
+* Collects a collection's entries while its loader runs.
+*
+* An id claimed twice is a conflict rather than a merge. Two files writing one
+* entry means one of them is silently unreachable, which is worth a build
+* failure rather than a coin toss.
+*/
+function collectionStore(collection, root = "") {
+	let entries = /* @__PURE__ */ new Map();
+	function set(entry) {
+		if (entries.has(entry.id)) throw new ContentError(collection, `Duplicate entry id "${entry.id}" in collection "${collection}".`);
+		entries.set(entry.id, stored(entry, root));
+	}
+	return {
+		entries,
+		set,
+		/** Whether any entry carried runtime rendering options. */
+		configuredSatteri() {
+			return [...entries.values()].some((entry) => entry.satteri !== void 0);
+		},
+		/** The entries `contentLayer()` reads back, before it compiles any body. */
+		serializable() {
+			return [...entries.values()].map((entry) => ({
+				id: entry.id,
+				data: entry.data,
+				...entry.filePath === void 0 ? {} : { filePath: entry.filePath },
+				...entry.body === void 0 ? {} : { body: entry.body }
+			}));
+		}
+	};
+}
+/**
+* Normalizes one entry for the runtime.
+*
+* `filePath` is stored relative to the project root. Absolute would leak the
+* build machine's layout into every shipped bundle, make two machines produce
+* different artifacts from identical source, and give the field two meanings:
+* the build host's path when prebuilt, the serving host's when not.
+*/
+function stored(entry, root) {
+	let body = "body" in entry ? entry.body : void 0;
+	let raw = body && "source" in body ? body : void 0;
+	let compiled = body && !("source" in body) ? body : void 0;
+	return {
+		id: entry.id,
+		data: entry.data,
+		filePath: relativeTo(root, entry.filePath),
+		body: raw,
+		prebuilt: compiled,
+		satteri: "satteri" in entry ? entry.satteri : void 0
+	};
+}
+function relativeTo(root, filePath) {
+	if (!filePath || !root) return filePath;
+	let prefix = `${root.replace(/\\/g, "/").replace(/\/$/, "")}/`;
+	let path = filePath.replace(/\\/g, "/");
+	return path.startsWith(prefix) ? path.slice(prefix.length) : path;
+}
+//#endregion
+//#region src/content.ts
+/**
+* Declares a set of content collections.
+*
+* Returns the collection object synchronously without loading entries.
+* Reads and rendering remain asynchronous. Declaration errors throw here.
+*
+* Under `contentLayer()`, registers deferred population work. The plugin
+* awaits it after evaluating the declarations and before emitting the bundle.
+*/
+function createContent(build) {
+	let referenced = [];
+	let definitions = build({
+		collection: (input) => input,
+		reference(name) {
+			referenced.push(name);
+			return reference(name);
+		}
+	});
+	let names = Object.keys(definitions);
+	for (let name of referenced) if (!Object.hasOwn(definitions, name)) throw new Error(`Unknown collection "${name}" referenced by createContent; known collections are ${names.join(", ")}.`);
+	let manifest = prebuiltManifest();
+	let content = {};
+	for (let [name, definition] of Object.entries(definitions)) content[name] = wire(name, definition, manifest?.[name]);
+	if (isPrebuilding()) registerPrebuild(() => populateEagerly(content, definitions));
+	return content;
+}
+function wire(name, definition, entries) {
+	let loader = definition.loader;
+	if (isContentLoader(loader)) return contentCollection(name, definition.schema, loader, entries);
+	return liveCollection(name, definition.schema, loader);
+}
+function isContentLoader(loader) {
+	return "load" in loader && typeof loader.load === "function";
+}
+/**
+* A collection whose loader resolves it in one execution.
+*
+* Its entries come from the manifest when the build prebuilt them, and from the
+* loader otherwise. A successful population is memoized for the life of the
+* process and concurrent readers share one in-flight load; a failed one is not,
+* so one timed-out fetch does not leave the collection broken until a restart.
+*/
+function contentCollection(name, schema, loader, prebuiltEntries) {
+	let populated;
+	let listeners = /* @__PURE__ */ new Set();
+	function entries() {
+		if (prebuiltEntries) {
+			populated ??= Promise.resolve(fromManifest(name, prebuiltEntries));
+			return populated;
+		}
+		populated ??= runLoader(name, schema, loader).then((stored) => {
+			announce(stored);
+			return stored;
+		}).catch((error) => {
+			populated = void 0;
+			throw error;
+		});
+		return populated;
+	}
+	function announce(stored) {
+		if (listeners.size === 0) return;
+		let files = [...new Set([...stored.values()].map((entry) => entry.filePath).filter((filePath) => filePath !== void 0))];
+		for (let listener of listeners) listener(files);
+	}
+	return {
+		...queries(name, entries),
+		/**
+		* The seam `@pitlane/content/hot` reads. Prebuilt entries have no files
+		* to watch and cannot be reloaded, so that collection offers nothing.
+		*/
+		[HOT_COLLECTION]: prebuiltEntries ? void 0 : {
+			invalidate() {
+				populated = void 0;
+			},
+			onPopulated(listener) {
+				listeners.add(listener);
+				return () => listeners.delete(listener);
+			}
+		}
+	};
+}
+async function runLoader(name, schema, loader) {
+	let store = collectionStore(name, contentRoot());
+	try {
+		await loader.load({
+			collection: name,
+			root: contentRoot(),
+			parseData: (input) => parseEntryData(schema, {
+				collection: name,
+				...input
+			}, input.data),
+			store: { set: store.set }
+		});
+	} catch (error) {
+		throw annotate(name, error);
+	} finally {
+		if (isPrebuilding()) recordWatched(loader.watchedPaths?.() ?? []);
+	}
+	if (isPrebuilding()) {
+		recordPrebuilt(name, store.serializable());
+		if (store.configuredSatteri()) recordConfiguredSatteri(name);
+	}
+	return store.entries;
+}
+/**
+* A collection whose loader answers one query at a time.
+*
+* There is nothing to memoize and nothing the build can inline, so every read
+* asks the loader and validates what comes back.
+*/
+function liveCollection(name, schema, loader) {
+	async function validate(entry) {
+		return {
+			id: entry.id,
+			data: await parseEntryData(schema, {
+				collection: name,
+				id: entry.id
+			}, entry.data),
+			body: entry.body
+		};
+	}
+	return {
+		async getCollection(filter) {
+			let live = await loader.loadCollection().catch((error) => {
+				throw annotate(name, error);
+			});
+			return present(name, await Promise.all(live.map(validate)), filter);
+		},
+		async getEntry(id) {
+			let key = typeof id === "string" ? id : id.id;
+			let entry = await loader.loadEntry(key).catch((error) => {
+				throw annotate(name, error);
+			});
+			if (!entry) return void 0;
+			return view(name, await validate(entry));
+		}
+	};
+}
+function queries(name, entries) {
+	return {
+		async getCollection(filter) {
+			return present(name, [...(await entries()).values()], filter);
+		},
+		async getEntry(id) {
+			let key = typeof id === "string" ? id : id.id;
+			let entry = (await entries()).get(key);
+			return entry ? view(name, entry) : void 0;
+		}
+	};
+}
+/** Sorts by id so a prerender never depends on filesystem order, then filters. */
+function present(name, entries, filter) {
+	let views = entries.slice().sort((left, right) => left.id < right.id ? -1 : left.id > right.id ? 1 : 0).map((entry) => view(name, entry));
+	return filter ? views.filter((entry) => filter(entry)) : views;
+}
+function view(collection, entry) {
+	return {
+		id: entry.id,
+		collection,
+		data: entry.data,
+		...entry.filePath === void 0 ? {} : { filePath: entry.filePath },
+		render: async () => {
+			return await (await import("./render-U9dXN6f0.mjs").catch((cause) => {
+				throw missingRenderer(`${collection}/${entry.id}`, cause) ?? cause;
+			})).renderedEntry(collection, entry);
+		}
+	};
+}
+function fromManifest(name, entries) {
+	let store = collectionStore(name);
+	for (let entry of entries) store.set(entry);
+	return store.entries;
+}
+/**
+* Frames a loader failure with the collection, unless it already names one.
+*
+* Recognised by type rather than by a substring of the message: matching on
+* wording would couple every thrower to this function's idea of what a framed
+* message looks like, and rewording one of them would double-wrap or skip.
+*/
+function annotate(collection, error) {
+	if (error instanceof ContentError) return error;
+	return new ContentError(collection, `Failed to load collection "${collection}": ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+}
+/** Under `contentLayer()`, every `ContentLoader` collection loads before the build reads it. */
+async function populateEagerly(content, definitions) {
+	for (let [name, definition] of Object.entries(definitions)) {
+		if (!isContentLoader(definition.loader)) continue;
+		await content[name].getCollection();
+	}
+}
+//#endregion
+export { createContent };

package/dist/loaders.d.mts

@@ -0,0 +1,38 @@
+import { l as GenerateIdOptions, o as ContentLoader } from "./types-xSR1WTBq.mjs";
+import { CompileOptions } from "satteri";
+//#region src/loaders/file.d.ts
+/**
+ * Turns a file's text into whatever it holds.
+ *
+ * The return type is `unknown` rather than the object-or-array this loader
+ * actually needs, because every parser worth passing here — `@std/jsonc`, a
+ * TOML reader — is typed as returning a JSON-value union, which a narrower
+ * type rejects. `entriesOf` refuses an unusable result by name, so demanding
+ * the caller narrow first would buy a wrapper and no safety.
+ */
+type Parser = (text: string) => unknown;
+/**
+ * Reads one file holding many entries.
+ *
+ * Every entry is data rather than a document: a file of records has no body to
+ * render, so `render()` on one of these entries is a mistake and says so.
+ */
+declare function file(fileName: string, options?: {
+  parser?: Parser;
+}): ContentLoader;
+//#endregion
+//#region src/loaders/glob.d.ts
+/**
+ * Reads every file a pattern matches as one entry.
+ *
+ * `pattern` is an ordinary runtime value — computed, read from the environment,
+ * or assembled in a loop — because nothing about it is read statically.
+ */
+declare function glob(options: {
+  pattern: string | string[];
+  base?: string;
+  generateId?: (options: GenerateIdOptions) => string;
+  satteri?: CompileOptions;
+}): ContentLoader;
+//#endregion
+export { file, glob };

package/dist/loaders.mjs

@@ -0,0 +1,255 @@
+import { t as ContentError } from "./parse-DoKe2tNa.mjs";
+import { extname, resolve } from "node:path";
+import { parse } from "yaml";
+//#region src/loaders/filesystem.ts
+/**
+* `node:fs/promises`, or a diagnostic for a host that has none.
+*
+* The import is dynamic on purpose, against this repository's preference for
+* static ones: a static import of `node:fs` makes a Cloudflare Workers bundle
+* fail to *build*, which tells an author nothing. Reaching this code at all
+* means the collection was never prebuilt, so the fix is a line of Vite config
+* rather than a code change, and only a runtime error can say so.
+*
+* Only the import is guarded, and every import failure means the same thing: a
+* builtin module never touches the disk, so it either resolves or is absent.
+* The reads happen at the call site, which is what keeps an ordinary I/O
+* failure — a `base` that does not exist, a file deleted mid-read — surfacing
+* as itself rather than as a claim about the host.
+*/
+async function filesystem(collection) {
+	try {
+		return await import("node:fs/promises");
+	} catch (error) {
+		throw new ContentError(collection, `Collection "${collection}" has no prebuilt content and no filesystem to read.\nAdd contentLayer() from "@pitlane/content/vite" to your Vite config.`, { cause: error });
+	}
+}
+//#endregion
+//#region src/loaders/read.ts
+/**
+* Parses one file, naming it when the parse fails.
+*
+* Malformed frontmatter and malformed JSON are the two most likely authoring
+* mistakes here, and the parsers report a line and column relative to the
+* snippet they were handed. Without the path that is unactionable in a
+* collection of any size.
+*/
+function read(parse, text, filePath) {
+	try {
+		return parse(text);
+	} catch (error) {
+		let cause = error instanceof Error ? error.message : String(error);
+		throw new Error(`Failed to parse "${filePath}": ${cause}`, { cause: error });
+	}
+}
+//#endregion
+//#region src/loaders/file.ts
+/**
+* Reads one file holding many entries.
+*
+* Every entry is data rather than a document: a file of records has no body to
+* render, so `render()` on one of these entries is a mistake and says so.
+*/
+function file(fileName, options) {
+	let watched = [];
+	return {
+		name: "file",
+		async load(context) {
+			let filePath = resolve(context.root, fileName);
+			watched = [filePath];
+			let entries = entriesOf(read(parserFor(extname(filePath), options?.parser), await (await filesystem(context.collection)).readFile(filePath, "utf8"), filePath), filePath);
+			for (let [id, data] of entries) context.store.set({
+				id,
+				data: await context.parseData({
+					id,
+					data,
+					filePath
+				}),
+				filePath
+			});
+		},
+		watchedPaths: () => watched
+	};
+}
+function parserFor(extension, custom) {
+	if (custom) return custom;
+	if (extension === ".json") return JSON.parse;
+	if (extension === ".yaml" || extension === ".yml") return parse;
+	throw new Error(`No parser for "${extension}"; pass options.parser to loaders.file.`);
+}
+/**
+* The entries a parse result holds, refusing a result that holds none.
+*
+* `JSON.parse` and the YAML parser both answer with whatever the file says,
+* including `null` for an empty document or a bare scalar for a stray one, and
+* `Object.entries` on either of those reports a type error naming neither the
+* file nor the shape the loader wanted.
+*/
+function entriesOf(parsed, filePath) {
+	if (Array.isArray(parsed)) return fromArray(parsed, filePath);
+	if (!parsed || typeof parsed !== "object") throw new Error(`Parsing "${filePath}" produced ${parsed === null ? "null" : typeof parsed}; loaders.file needs an object whose keys are entry ids, or an array of entries each carrying an id.`);
+	return Object.entries(parsed);
+}
+/** An array's items carry their own ids, which are not part of their data. */
+function fromArray(items, filePath) {
+	return items.map((item, index) => {
+		if (!identified(item)) throw new Error(`Entry at index ${index} of "${filePath}" has no string id; every item in an array needs one to become its entry id.`);
+		let { id, ...data } = item;
+		return [id, data];
+	});
+}
+function identified(item) {
+	return !!item && typeof item === "object" && "id" in item && typeof item.id === "string";
+}
+//#endregion
+//#region src/loaders/frontmatter.ts
+/**
+* A leading `---`-fenced block, and everything after it.
+*
+* Anchored with `\A`-style intent rather than `m`: with the multiline flag,
+* `^---` matches at any line start, so an ordinary document containing two
+* thematic breaks reads as a fenced block and loses both its data and the top
+* of its body. Only a fence at position zero is frontmatter.
+*
+* Both fences must own a whole line. The opening one does by the anchor; the
+* closing one does because its preceding newline sits *inside* the data group
+* rather than being optional beside it. A value ending in `---`, or an
+* indented `---` inside a block scalar, therefore cannot close the block. The
+* group is optional only for `---\n---`, an empty block whose closing fence
+* has no data line in front of it; that branch is tried last, so a block with
+* data never loses it.
+*
+* The data match is lazy, so a `---` break after real frontmatter stays in the
+* body rather than ending the block early.
+*/
+let fenced = /^---[^\S\n]*\r?\n(?:([\s\S]*?)\r?\n)?---[^\S\n]*(?:\r?\n|$)/;
+/**
+* Splits a Markdown document's YAML frontmatter from its body.
+*
+* `@pitlane/content` parses frontmatter here rather than reading the one
+* `vite-plugin-satteri` also produces, so a prebuilt and a runtime-resolved
+* collection cannot disagree about an entry's data.
+*/
+function splitFrontmatter(text) {
+	let match = fenced.exec(text);
+	if (!match) return {
+		data: {},
+		body: text
+	};
+	return {
+		data: parse(match[1] ?? "") ?? {},
+		body: text.slice(match[0].length)
+	};
+}
+//#endregion
+//#region src/loaders/glob.ts
+/**
+* The formats `glob` reads.
+*
+* A match in any other format — including a directory a pattern happened to
+* match — is skipped silently. A pattern is an ordinary value and may be as
+* broad as its author likes, so matching a README is not a mistake worth
+* failing a build over.
+*/
+let formats = {
+	".md": (text) => markdown("md", text),
+	".mdx": (text) => markdown("mdx", text),
+	".json": (text) => ({ data: JSON.parse(text) }),
+	".yaml": (text) => ({ data: parse(text) ?? {} }),
+	".yml": (text) => ({ data: parse(text) ?? {} })
+};
+/**
+* Reads every file a pattern matches as one entry.
+*
+* `pattern` is an ordinary runtime value — computed, read from the environment,
+* or assembled in a loop — because nothing about it is read statically.
+*/
+function glob(options) {
+	let watched = [];
+	return {
+		name: "glob",
+		async load(context) {
+			let base = resolve(context.root, options.base ?? ".");
+			watched = watchedDirectories(base, options.pattern);
+			let fs = await filesystem(context.collection);
+			let matches = [];
+			for await (let match of fs.glob(options.pattern, { cwd: base })) {
+				let entry = match.replaceAll("\\", "/");
+				let extension = extname(entry);
+				let parse = formats[extension];
+				if (!parse) continue;
+				let filePath = resolve(base, entry);
+				let document = read(parse, await fs.readFile(filePath, "utf8"), filePath);
+				matches.push({
+					entry,
+					extension,
+					filePath,
+					document
+				});
+			}
+			for (let { id, filePath, document } of identify(matches, base, options.generateId)) {
+				let stored = {
+					id,
+					data: await context.parseData({
+						id,
+						data: document.data,
+						filePath
+					}),
+					filePath,
+					body: document.body,
+					satteri: options.satteri
+				};
+				context.store.set(stored);
+			}
+		},
+		watchedPaths: () => watched
+	};
+}
+/** The syntax that makes a pattern segment a glob rather than a literal name. */
+const GLOB_SYNTAX_RE = /[*?[\]{}!()]/;
+/**
+* The directories a pattern can match under, resolved against `base`.
+*
+* Watching `base` would watch the project root whenever `base` is left at its
+* default, and then every save anywhere in the project looks like a content
+* change: a whole extra Vite server and a full browser reload for editing an
+* unrelated module. A pattern's leading literal segments are the narrowest
+* directories that still contain everything it can match.
+*/
+function watchedDirectories(base, pattern) {
+	return [...new Set((Array.isArray(pattern) ? pattern : [pattern]).map((one) => resolve(base, literalPrefix(one))))];
+}
+function literalPrefix(pattern) {
+	let segments = pattern.replaceAll("\\", "/").split("/");
+	let firstGlob = segments.findIndex((segment) => GLOB_SYNTAX_RE.test(segment));
+	return segments.slice(0, firstGlob === -1 ? -1 : firstGlob).join("/");
+}
+/**
+* Pairs each match with its id, in id order.
+*
+* Sorting here is what keeps a collection from inheriting the order its
+* directories happened to be traversed in.
+*/
+function identify(matches, base, generateId) {
+	return matches.map(({ entry, extension, filePath, document }) => ({
+		id: generateId?.({
+			entry,
+			base,
+			data: document.data
+		}) ?? entry.slice(0, -extension.length),
+		filePath,
+		document
+	})).sort((left, right) => left.id < right.id ? -1 : left.id > right.id ? 1 : 0);
+}
+function markdown(format, text) {
+	let { data, body } = splitFrontmatter(text);
+	return {
+		data,
+		body: {
+			format,
+			source: body
+		}
+	};
+}
+//#endregion
+export { file, glob };

package/dist/manifest.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/manifest.mjs

@@ -0,0 +1,4 @@
+//#region src/manifest.ts
+globalThis[Symbol.for("pitlane.content.manifest")] ??= null;
+//#endregion
+export {};

package/dist/mdx.d.mts

@@ -0,0 +1,35 @@
+//#region src/mdx.d.ts
+/** One `import` statement an MDX document makes. */
+interface Import {
+  specifier: string;
+  /** Local name to exported name; `default` names the default import. */
+  bindings: Map<string, string>;
+  /** A `with { ... }` clause, for a module that needs one to load. */
+  attributes?: Record<string, string>;
+}
+/**
+ * The imports in one top-level ESM block, and what is left after removing them.
+ *
+ * The remainder matters twice over. A block holds whatever the author wrote, so
+ * an `export const` can sit beside an import and the document's body may use
+ * it; dropping the whole block would take the export with the import. And what
+ * is left is spliced back into the document, so it has to stay recognisable as
+ * ESM: a comment surviving on its own line starts a paragraph, which swallows
+ * the export that follows it.
+ *
+ * Statement boundaries come from `es-module-lexer`, the lexer Vite reads the
+ * same imports with. Deciding them here instead means reimplementing JavaScript
+ * tokenization: a quote inside a regex literal is not a string, a line starting
+ * with `import` inside a template is not a statement, `{ import: "x" }` is a
+ * property, and each of those was wrong before the lexer answered it.
+ *
+ * Anything import-shaped the lexer reports and this cannot read throws rather
+ * than being skipped: a skipped import is a component that silently renders as
+ * nothing, which is the failure this whole path exists to remove.
+ */
+declare function readEsm(block: string, where: string): Promise<{
+  imports: Import[];
+  remainder: string;
+}>;
+//#endregion
+export { readEsm };