@pitlane/content 0.1.0

package/dist/types-xSR1WTBq.d.mts

@@ -0,0 +1,238 @@
+import { Handle, RemixNode } from "remix/ui";
+//#region src/types.d.ts
+/**
+ * Standard Schema v1, declared here rather than depended on.
+ *
+ * The specification is frozen at version 1 and the interface is the whole of
+ * it, so a dependency would buy nothing this comment does not. Any conforming
+ * schema — `remix/data-schema`, Zod, Valibot, ArkType — satisfies it
+ * structurally.
+ *
+ * @see https://standardschema.dev
+ */
+interface StandardSchemaV1<Output = unknown> {
+  readonly "~standard": {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (value: unknown) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+    readonly types?: {
+      readonly output: Output;
+    } | undefined;
+  };
+}
+/** The result of validating a value against a {@link StandardSchemaV1}. */
+type StandardSchemaResult<Output> = {
+  readonly value: Output;
+  readonly issues?: undefined;
+} | {
+  readonly issues: readonly StandardSchemaIssue[];
+};
+/** One validation failure, with the path into the input that produced it. */
+interface StandardSchemaIssue {
+  readonly message: string;
+  readonly path?: readonly (PropertyKey | {
+    readonly key: PropertyKey;
+  })[] | undefined;
+}
+/** The output type a schema produces. */
+type InferSchema<S> = S extends StandardSchemaV1<infer Output> ? Output : never;
+/**
+ * A resolved pointer from one entry to another, produced by
+ * `c.reference(collection)`.
+ *
+ * The `collection` type parameter is what stops a `Reference<"blog">` reaching
+ * `content.authors.getEntry`.
+ */
+interface Reference<C extends string> {
+  collection: C;
+  id: string;
+}
+/** A reusable check, shaped as `remix/data-schema`'s `Check` is. */
+interface SchemaCheck<Output> {
+  check: (value: Output) => boolean;
+  message?: string;
+  code?: string;
+  values?: Record<string, unknown>;
+}
+/** Where a value sits in the input being validated, and how it is being parsed. */
+interface RunContext {
+  path: NonNullable<StandardSchemaIssue["path"]>;
+  options?: unknown;
+}
+/**
+ * The surface `remix/data-schema`'s combinators require of a schema they hold.
+ *
+ * `s.object`, `s.array`, and `s.optional` call `~run` rather than the Standard
+ * Schema `validate`, so a bare Standard Schema does not compose inside them and
+ * a reference that does not compose is not worth having. Declared here rather
+ * than imported: one type import would make Remix a requirement of reading a
+ * JSON file. Any schema satisfying it is accepted, whoever built it.
+ */
+interface ChainableSchema<Input, Output> {
+  readonly "~standard": {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (value: unknown) => StandardSchemaResult<Output>;
+    readonly types?: {
+      readonly input: Input;
+      readonly output: Output;
+    } | undefined;
+  };
+  "~run": (value: unknown, context: RunContext) => StandardSchemaResult<Output>;
+  pipe: (...checks: SchemaCheck<Output>[]) => ChainableSchema<Input, Output>;
+  refine: (predicate: (value: Output) => boolean, message?: string) => ChainableSchema<Input, Output>;
+  transform: <Next>(transformer: (value: Output) => Next) => ChainableSchema<Input, Next>;
+}
+/** The schema `c.reference(collection)` returns. */
+type ReferenceSchema<C extends string> = ChainableSchema<string, Reference<C>>;
+/** A heading collected from a Markdown or MDX document. */
+interface Heading {
+  depth: number;
+  slug: string;
+  text: string;
+}
+/** What `entry.render()` resolves to. */
+interface RenderedEntry {
+  Content: (handle: Handle<Record<string, unknown>>) => () => RemixNode;
+  headings: Heading[];
+}
+/** One entry of a collection, as a caller sees it. */
+interface Entry<Data> {
+  id: string;
+  collection: string;
+  data: Data;
+  filePath?: string;
+  render(): Promise<RenderedEntry>;
+}
+/**
+ * One entry of `collection`, named the way an application thinks of it:
+ * `CollectionEntry<typeof content.blog>`.
+ *
+ * {@link Entry} is keyed by the shape of the data, which is what the query
+ * methods resolve to and all this package needs internally. An application
+ * has the collection rather than the shape, and pulling one out of the other
+ * is a conditional type every consumer would otherwise write for itself.
+ */
+type CollectionEntry<C> = C extends Collection<string, infer Data> ? Entry<Data> : never;
+/** The query surface of one collection. */
+interface Collection<Name extends string, Data> {
+  getCollection(filter?: (entry: Entry<Data>) => unknown): Promise<Entry<Data>[]>;
+  getEntry(id: string | Reference<Name>): Promise<Entry<Data> | undefined>;
+}
+/** The raw source of an entry's document, before anything renders it. */
+interface EntryBody {
+  format: "md" | "mdx";
+  source: string;
+}
+/** What a {@link ContentLoader} writes into the store for one entry. */
+interface LoadedEntry {
+  id: string;
+  data: unknown;
+  filePath?: string;
+  body?: EntryBody;
+}
+/** What a {@link LiveLoader} returns for one entry. */
+interface LiveEntry<Data = Record<string, unknown>> {
+  id: string;
+  data: Data;
+  body?: EntryBody;
+}
+/** What a loader is handed to read its source and validate what it found. */
+interface LoaderContext {
+  collection: string;
+  /**
+   * The project root a relative path resolves against.
+   *
+   * `process.cwd()` at runtime, and the Vite root under `contentLayer()`, which is
+   * what keeps a collection pointing at the same files when the build runs
+   * from somewhere else.
+   */
+  root: string;
+  parseData<D>(input: {
+    id: string;
+    data: unknown;
+    filePath?: string;
+  }): Promise<D>;
+  store: {
+    set(entry: LoadedEntry): void;
+  };
+}
+/**
+ * A loader that resolves a whole collection by filling a store.
+ *
+ * Its shape is the claim that one execution produces the complete answer, which
+ * is what lets `contentLayer()` run it during the build and inline the result.
+ */
+interface ContentLoader {
+  name: string;
+  load(context: LoaderContext): Promise<void> | void;
+  watchedPaths?(): string[];
+}
+/**
+ * A loader that answers one query at a time.
+ *
+ * There is no store to fill and so nothing to serialize: the only way to get
+ * entries out of it is to ask, which means asking on every read.
+ */
+interface LiveLoader<Data = Record<string, unknown>> {
+  name: string;
+  loadCollection(): Promise<LiveEntry<Data>[]>;
+  loadEntry(id: string): Promise<LiveEntry<Data> | undefined>;
+}
+/**
+ * Either kind of loader.
+ *
+ * A `LiveLoader`'s own `Data` parameter is for whoever writes it; a collection
+ * accepts any of them, because what a loader hands back is unvalidated until
+ * `parseData` has seen it.
+ */
+type Loader = ContentLoader | LiveLoader<unknown>;
+/** What `c.collection({ loader, schema })` returns. */
+interface CollectionDefinition<S extends StandardSchemaV1 = StandardSchemaV1> {
+  loader: Loader;
+  schema: S;
+}
+/** The builder `createContent` hands to its callback. */
+interface ContentBuilder {
+  collection<S extends StandardSchemaV1>(input: {
+    loader: Loader;
+    schema: S;
+  }): CollectionDefinition<S>;
+  reference<C extends string>(collection: C): ReferenceSchema<C>;
+}
+/** The object `createContent` returns: one {@link Collection} per key. */
+type Content<T extends Record<string, CollectionDefinition>> = { [K in keyof T]: Collection<K & string, InferSchema<T[K]["schema"]>>; };
+/** How `contentLayer()` spells an entry's body in the manifest it emits. */
+type PrebuiltBody = {
+  format: "md";
+  html: string;
+  headings?: unknown;
+} | {
+  format: "mdx";
+  module: Record<string, unknown>;
+};
+/** One entry in the manifest `contentLayer()` emits. */
+interface PrebuiltEntry {
+  id: string;
+  data: unknown;
+  filePath?: string;
+  body?: PrebuiltBody;
+}
+/**
+ * The manifest `contentLayer()` emits, keyed by collection name.
+ *
+ * A collection missing from it was not prebuilt, and its absence is what tells
+ * the runtime to use the loader.
+ */
+type PrebuiltCollections = Record<string, PrebuiltEntry[]>;
+/** Options handed to a `loaders.glob` `generateId` function. */
+interface GenerateIdOptions {
+  /** The matched path, relative to `base`. */
+  entry: string;
+  /** The directory the pattern resolved against. */
+  base: string;
+  /** The parsed data of the entry, for an id derived from frontmatter. */
+  data: Record<string, unknown>;
+}
+//#endregion
+export { Reference as _, ContentBuilder as a, EntryBody as c, LiveEntry as d, LiveLoader as f, PrebuiltCollections as g, LoaderContext as h, Content as i, GenerateIdOptions as l, Loader as m, CollectionDefinition as n, ContentLoader as o, LoadedEntry as p, CollectionEntry as r, Entry as s, Collection as t, Heading as u, RenderedEntry as v };

package/dist/vite.d.mts

@@ -0,0 +1,18 @@
+import { Plugin } from "vite";
+//#region src/vite.d.ts
+/**
+ * Resolves content collections during the build and inlines them.
+ *
+ * `entry` names the module that declares the collections, and defaults to
+ * `app/content.ts`. It is an ordinary application module rather than a
+ * configuration file this plugin owns; being told which module it is is the
+ * whole of the configuration.
+ *
+ * The result is a host with no filesystem serving the collections the
+ * application declared, with no change to the declarations.
+ */
+declare function contentLayer(options?: {
+  entry?: string;
+}): Plugin;
+//#endregion
+export { contentLayer };

package/dist/vite.mjs

@@ -0,0 +1,262 @@
+import { closePrebuild, openPrebuild } from "./prebuild.mjs";
+import { BODY_PREFIX, manifestModule } from "./codegen.mjs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRunnableDevEnvironment, createServer } from "vite";
+//#region src/vite.ts
+const MANIFEST_OWNER = "@pitlane/content";
+const MANIFEST_SPECIFIER = `${MANIFEST_OWNER}/internal/manifest`;
+const VIRTUAL_MANIFEST = "\0pitlane-content/manifest";
+/**
+* Resolves content collections during the build and inlines them.
+*
+* `entry` names the module that declares the collections, and defaults to
+* `app/content.ts`. It is an ordinary application module rather than a
+* configuration file this plugin owns; being told which module it is is the
+* whole of the configuration.
+*
+* The result is a host with no filesystem serving the collections the
+* application declared, with no change to the declarations.
+*/
+function contentLayer(options) {
+	let entry = options?.entry ?? "app/content.ts";
+	let root = process.cwd();
+	let collections = {};
+	let bodies = /* @__PURE__ */ new Map();
+	let watched = [];
+	let resolution = {};
+	let server;
+	let pending;
+	let queue = Promise.resolve();
+	async function prebuild(warn) {
+		let loaded = await inPrebuildServer(root, entry, resolution, (paths) => {
+			watched = [.../* @__PURE__ */ new Set([...watched, ...paths])];
+			for (let path of watched) server?.watcher.add(path);
+		});
+		collections = loaded.collections;
+		watched = loaded.watched;
+		for (let path of watched) server?.watcher.add(path);
+		for (let name of loaded.configuredSatteri) warn(`Collection "${name}" configures loader options.satteri, but contentLayer() prebuilt it, so vite-plugin-satteri renders it and those options do nothing. Move the plugins into satteri() in your Vite config, or drop contentLayer() for this collection.`);
+	}
+	/**
+	* Prebuilds once, and again only after a content change invalidated it.
+	*
+	* Runs strictly one at a time. Prebuild mode is a process-global handshake
+	* with `createContent`, so a second run overlapping the first would close
+	* the channel underneath it and leave the loaders resolving against the
+	* wrong root.
+	*/
+	function ready(warn) {
+		let run = () => prebuild(warn);
+		pending ??= queue = queue.then(run, run);
+		return pending;
+	}
+	return {
+		name: "pitlane-content",
+		enforce: "post",
+		/**
+		* Two ways the runtime can end up with the manifest the package ships
+		* — the one that registers nothing — instead of the one emitted below.
+		*
+		* A server build externalizes its dependencies, so the package has to
+		* be bundled for the replacement to reach the runtime at all. In dev
+		* nothing is bundled, but the dependency optimizer pre-bundles an
+		* installed dependency before any plugin runs, inlining the shipped
+		* manifest where `load` can no longer replace it. Excluding the
+		* package is what keeps the two paths agreeing.
+		*/
+		config() {
+			return {
+				environments: { ssr: {
+					optimizeDeps: { exclude: [MANIFEST_OWNER] },
+					resolve: { noExternal: [MANIFEST_OWNER] }
+				} },
+				optimizeDeps: { exclude: [MANIFEST_OWNER] },
+				ssr: { noExternal: [MANIFEST_OWNER] }
+			};
+		},
+		configResolved(config) {
+			root = config.root;
+			resolution = {
+				alias: config.resolve.alias,
+				dedupe: config.resolve.dedupe,
+				extensions: config.resolve.extensions,
+				mainFields: config.resolve.mainFields,
+				preserveSymlinks: config.resolve.preserveSymlinks
+			};
+		},
+		async buildStart() {
+			if (this.environment.config.command === "build") await ready((message) => this.warn(message));
+		},
+		configureServer(created) {
+			server = created;
+			created.watcher.on("all", async (_event, changed) => {
+				if (!isWatched(watched, changed)) return;
+				pending = void 0;
+				try {
+					await ready((message) => created.config.logger.warn(message));
+				} catch (error) {
+					created.config.logger.error(String(error));
+				}
+				invalidate(created, entry);
+				created.hot.send({ type: "full-reload" });
+			});
+		},
+		async resolveId(source, importer) {
+			if (source === MANIFEST_SPECIFIER) return VIRTUAL_MANIFEST;
+			if (source.startsWith("\0pitlane-content/entry/")) return source;
+			if (importer?.startsWith("\0pitlane-content/entry/") && source.startsWith(".")) {
+				let filePath = bodies.get(importer)?.filePath;
+				if (filePath === void 0) return void 0;
+				let from = resolve(root, filePath);
+				return await this.resolve(resolve(dirname(from), source), from, { skipSelf: true });
+			}
+		},
+		/**
+		* Catches the one misconfiguration that would otherwise surface as a
+		* JavaScript tokenizer error on a virtual path.
+		*
+		* A body module's id ends in `.md` or `.mdx` and its contents are raw
+		* Markdown. If it reaches here unchanged, no plugin claimed it, and the
+		* bundler is about to parse prose as JavaScript. Every other
+		* misconfiguration in this package names its own fix; this one sits on
+		* the documented adoption path, so it gets the same treatment.
+		*/
+		transform(code, id) {
+			if (!id.startsWith("\0pitlane-content/entry/") || code !== bodies.get(id)?.source) return void 0;
+			throw new Error(`Nothing compiled the Markdown in "${id.slice(BODY_PREFIX.length)}". Add vite-plugin-satteri to your Vite config, before remix():
+  satteri({ mdx: { jsxImportSource: "remix/ui" }, mdastPlugins: [headings()] })`);
+		},
+		async load(id) {
+			if (id === VIRTUAL_MANIFEST || isManifestModule(id)) {
+				await ready((message) => this.warn(message));
+				return manifestModule(collections, bodies, await markdownHeadings(collections));
+			}
+			if (id.startsWith("\0pitlane-content/entry/")) {
+				await ready((message) => this.warn(message));
+				return bodies.get(id)?.source;
+			}
+		}
+	};
+}
+/**
+* The heading list for every Markdown entry, measured the way the runtime
+* measures it.
+*
+* `vite-plugin-satteri` compiles a `.md` body to an HTML string and exports
+* nothing else, so the list has to be taken here or the prebuilt path has none
+* at all. MDX needs no such help: it compiles to a module that exports its own.
+*/
+async function markdownHeadings(collections) {
+	let measured = /* @__PURE__ */ new Map();
+	let markdown = Object.entries(collections).flatMap(([collection, loaded]) => loaded.filter((entry) => entry.body?.format === "md").map((entry) => ({
+		collection,
+		entry
+	})));
+	if (markdown.length === 0) return measured;
+	let [satteri, { headings }] = await Promise.all([import("satteri"), import("./satteri.mjs")]);
+	for (let { collection, entry } of markdown) {
+		let data = (await satteri.markdownToHtml(entry.body.source, {
+			features: { frontmatter: true },
+			mdastPlugins: [headings()]
+		})).data;
+		measured.set(`${BODY_PREFIX}${collection}/${entry.id}.md`, data.headings);
+	}
+	return measured;
+}
+function isWatched(watched, changed) {
+	let path = posix(changed);
+	return watched.some((base) => path === posix(base) || path.startsWith(`${posix(base)}/`));
+}
+function posix(path) {
+	return path.replace(/\\/g, "/");
+}
+/**
+* Whether a resolved id is this package's manifest module.
+*
+* Located relative to this module rather than matched by name: the plugin and
+* the manifest ship side by side, in `src` during development and in `dist`
+* once packed, so one relative lookup identifies it exactly. A suffix match
+* either misses the workspace link Vite resolves through or claims an
+* application's own `content/src/manifest.ts`.
+*/
+const MANIFEST_PATHS = new Set(["./manifest.ts", "./manifest.mjs"].map((name) => posix(fileURLToPath(new URL(name, import.meta.url)))));
+function isManifestModule(id) {
+	return MANIFEST_PATHS.has(posix(id).split("?")[0] ?? "");
+}
+/**
+* Invalidates the manifest, the body modules, and every module that imported
+* them, so the next request re-evaluates the collections rather than reusing
+* the entries the previous prebuild produced.
+*/
+function invalidate(server, entry) {
+	let entryPath = posix(entry).replace(/^\/+/, "");
+	for (let environment of Object.values(server.environments)) {
+		let graph = environment.moduleGraph;
+		let stale = [...graph.idToModuleMap.values()].filter((node) => {
+			let id = posix(node.id ?? "");
+			return isEmitted(id) || id.endsWith(`/${entryPath}`);
+		});
+		let seen = new Set(stale);
+		while (stale.length > 0) {
+			let node = stale.pop();
+			graph.invalidateModule(node);
+			for (let importer of node.importers) {
+				if (seen.has(importer)) continue;
+				seen.add(importer);
+				stale.push(importer);
+			}
+		}
+	}
+}
+function isEmitted(id) {
+	return id === VIRTUAL_MANIFEST || id.startsWith("\0pitlane-content/entry/") || isManifestModule(id);
+}
+/**
+* Runs the content entry through Vite's own module runner, so TypeScript,
+* aliases, and `vite.config.ts` resolution all apply.
+*
+* Declarations register deferred work. The plugin awaits it after module
+* evaluation, with the filesystem available, before reading the manifest.
+* Live loaders register no population work and stay untouched.
+*/
+async function inPrebuildServer(root, entry, resolution, onWatched) {
+	let server = await createServer({
+		root,
+		configFile: false,
+		logLevel: "silent",
+		resolve: resolution,
+		server: {
+			middlewareMode: true,
+			watch: null
+		},
+		environments: { ssr: { dev: { createEnvironment: (name, config) => createRunnableDevEnvironment(name, config) } } }
+	});
+	try {
+		return await execute(server, root, entry, onWatched);
+	} finally {
+		await server.close();
+	}
+}
+async function execute(server, root, entry, onWatched) {
+	let recorded = openPrebuild(root);
+	try {
+		await server.ssrLoadModule(entry.startsWith("/") ? entry : `/${entry}`);
+		for (let populate of recorded.tasks) await populate();
+	} catch (error) {
+		let cause = error instanceof Error ? error.message : String(error);
+		throw new Error(`Failed to load the content entry "${entry}" in ${root}: ${cause}`, { cause: error });
+	} finally {
+		onWatched([...recorded.watched]);
+		closePrebuild();
+	}
+	let collections = {};
+	for (let [name, entries] of recorded.collections) collections[name] = entries;
+	return {
+		collections,
+		watched: [...recorded.watched],
+		configuredSatteri: [...recorded.configuredSatteri]
+	};
+}
+//#endregion
+export { contentLayer };

package/package.json

@@ -0,0 +1,104 @@
+{
+    "name": "@pitlane/content",
+    "version": "0.1.0",
+    "description": "createContent() — schema-validated, cross-referenced Markdown, MDX, and data collections for Remix 3, queryable at runtime and prebuildable into the bundle.",
+    "keywords": [
+        "content",
+        "content-collections",
+        "markdown",
+        "mdx",
+        "pitlane",
+        "remix",
+        "satteri"
+    ],
+    "homepage": "https://pitlane.tools/package/content/",
+    "bugs": {
+        "url": "https://github.com/pitlane-tools/pitlane/issues"
+    },
+    "license": "MIT",
+    "author": "Mark Malstrom <mark@malstrom.me>",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/pitlane-tools/pitlane.git",
+        "directory": "packages/content"
+    },
+    "files": [
+        "dist",
+        "CHANGELOG.md"
+    ],
+    "type": "module",
+    "types": "./dist/index.d.mts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.mts",
+            "import": "./dist/index.mjs"
+        },
+        "./loaders": {
+            "types": "./dist/loaders.d.mts",
+            "import": "./dist/loaders.mjs"
+        },
+        "./satteri": {
+            "types": "./dist/satteri.d.mts",
+            "import": "./dist/satteri.mjs"
+        },
+        "./vite": {
+            "types": "./dist/vite.d.mts",
+            "import": "./dist/vite.mjs"
+        },
+        "./hot": {
+            "types": "./dist/hot.d.mts",
+            "import": "./dist/hot.mjs"
+        },
+        "./internal/manifest": {
+            "types": "./dist/manifest.d.mts",
+            "import": "./dist/manifest.mjs"
+        },
+        "./internal/prebuild": {
+            "types": "./dist/prebuild.d.mts",
+            "import": "./dist/prebuild.mjs"
+        },
+        "./internal/codegen": {
+            "types": "./dist/codegen.d.mts",
+            "import": "./dist/codegen.mjs"
+        },
+        "./internal/mdx": {
+            "types": "./dist/mdx.d.mts",
+            "import": "./dist/mdx.mjs"
+        }
+    },
+    "scripts": {
+        "prepublishOnly": "vp run build"
+    },
+    "dependencies": {
+        "es-module-lexer": "^2.3.1",
+        "yaml": "^2.8.1"
+    },
+    "devDependencies": {
+        "@types/node": "^25.5.0",
+        "remix": "3.0.0-rc.2",
+        "satteri": "^0.10.5",
+        "typescript": "^7.0.2",
+        "vite": "^8.1.5",
+        "vite-plugin-satteri": "^0.3.5",
+        "vite-plus": "^0.2.6"
+    },
+    "peerDependencies": {
+        "remix": "^3.0.0-rc.1",
+        "satteri": "^0.10.5",
+        "vite": ">=8.0.0"
+    },
+    "peerDependenciesMeta": {
+        "remix": {
+            "optional": true
+        },
+        "satteri": {
+            "optional": true
+        },
+        "vite": {
+            "optional": true
+        }
+    },
+    "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+    }
+}