@voltro/content 0.53.0

package/dist/index.d.ts

@@ -0,0 +1,161 @@
+import { Schema } from 'effect';
+
+export declare const buildFeed: <A>(entries: ReadonlyArray<A>, options: BuildFeedOptions<A>) => string;
+
+export declare interface BuildFeedOptions<A> {
+    readonly title: string;
+    readonly siteUrl: string;
+    readonly description?: string;
+    /** Feed path (`/rss.xml`) — becomes the atom:link self href. */
+    readonly feedPath?: string;
+    /** Map one entry to its feed item. Return null to exclude it. */
+    readonly item: (entry: A) => FeedItemInput | null;
+}
+
+export declare interface CollectionDefinition<A = Record<string, unknown>> {
+    readonly name: string;
+    /** App-root-relative content directory (`content/posts`). */
+    readonly directory: string;
+    /** Frontmatter schema (markdown collections) or file schema (data
+     *  collections). Violations are BUILD/BOOT errors naming file + field. */
+    readonly schema: Schema.Schema<A, any, never>;
+    /** `'markdown'` (default): every `.md` under the directory, frontmatter +
+     *  rendered body. `'data'`: every `.json`, decoded whole — the
+     *  authors.json case, no render path. */
+    readonly kind?: 'markdown' | 'data';
+    readonly i18n?: CollectionLocales;
+    /** Render options for this collection's markdown bodies (link rewriting,
+     *  a code-fence hook, …) — applied wherever the SERVER renders an entry. */
+    readonly markdown?: RenderMarkdownOptions;
+}
+
+export declare interface CollectionLocales {
+    /** The locale trees this collection carries (first path segment). */
+    readonly locales: ReadonlyArray<string>;
+    /**
+     * What a missing translation does: `'fallback'` (default) serves the
+     * defaultLocale's entry under the requested locale; `'missing'` omits it
+     * (the page 404s). Incomplete translations are the normal case — decide
+     * per collection instead of improvising per page.
+     */
+    readonly missing?: 'fallback' | 'missing';
+    readonly defaultLocale: string;
+}
+
+export declare const contentArtifactPath: (collection: string, locale: string | undefined, slug?: string) => string;
+
+export declare interface ContentEntry<A = Record<string, unknown>> {
+    readonly slug: string;
+    /** The locale tree this entry came from (localized collections only). When
+     *  the missing-policy substituted the default locale's entry, `locale` is
+     *  the REQUESTED locale and `fallback` is true. */
+    readonly locale?: string;
+    readonly fallback?: boolean;
+    readonly data: A;
+    /** Markdown collections: the rendered HTML (shiki included, server-rendered). */
+    readonly html?: string;
+    readonly headings?: ReadonlyArray<ContentHeading>;
+    /** Raw markdown body (server side; omitted from client artifacts by default). */
+    readonly body?: string;
+}
+
+declare interface ContentHeading {
+    readonly depth: number;
+    readonly slug: string;
+    readonly text: string;
+}
+
+export declare const contentRoot: () => string | null;
+
+export declare const defineCollection: <A>(definition: CollectionDefinition<A>) => CollectionDefinition<A>;
+
+export declare interface FeedItemInput {
+    readonly title: string;
+    readonly link: string;
+    readonly date: string | Date;
+    readonly description?: string;
+    readonly guid?: string;
+    /** `<category>` tags on the item. */
+    readonly categories?: ReadonlyArray<string>;
+}
+
+/** Every entry of a collection (sorted by slug). Server: filesystem + render;
+ *  client: the build artifact. The `data` type is the schema's decoded type. */
+export declare const getCollection: <A = Record<string, unknown>>(name: string, options?: GetCollectionOptions) => Promise<ReadonlyArray<ContentEntry<A>>>;
+
+export declare interface GetCollectionOptions {
+    readonly locale?: string;
+}
+
+/** One entry by slug, or null. */
+export declare const getEntry: <A = Record<string, unknown>>(name: string, slug: string, options?: GetCollectionOptions) => Promise<ContentEntry<A> | null>;
+
+/** Dev watch invalidation + test seam. */
+export declare const invalidateContentCache: (collection?: string) => void;
+
+export declare const reference: (collection: string) => Schema.Schema<string>;
+
+/** Every reference field declared by a collection's schema (top level):
+ *  field name → target collection. */
+export declare const referenceFieldsOf: (definition: CollectionDefinition) => ReadonlyMap<string, string>;
+
+/**
+ * `reference('<collection>')` — a frontmatter field that names an entry of
+ * another collection by slug (`author: jane` against an `authors` data
+ * collection). Decodes as the slug string; the BUILD validates every
+ * reference against the target collection, so a dangling one is a named
+ * build error, not a runtime null. Resolve it with
+ * `getEntry(<collection>, value)`.
+ */
+export declare const ReferenceTarget: unique symbol;
+
+/** The referenced collection of one schema property, if it is a reference. */
+export declare const referenceTargetOf: (ast: {
+    readonly annotations?: Readonly<Record<symbol, unknown>>;
+}) => string | undefined;
+
+export declare const registeredCollection: (name: string) => CollectionDefinition | undefined;
+
+export declare const registeredCollections: () => ReadonlyArray<CollectionDefinition>;
+
+declare interface RenderMarkdownOptions {
+    /** Rewrite relative links (`./sibling.md`, `../other/page.md`) into route
+     *  paths. Receives the raw href; return the replacement (or the input). */
+    readonly resolveLink?: (href: string) => string;
+    /** Highlight code fences with shiki (node only; a browser call renders
+     *  plain `<pre>`). Default true. */
+    readonly highlight?: boolean;
+    /**
+     * Post-process one rendered code fence. Receives the raw code, the resolved
+     * language (first info-string token, lowercased), the FULL info string
+     * (` ```ts preview=data-table ` ⇒ `'ts preview=data-table'`), and the
+     * rendered html. Return the replacement html — e.g. append a live-demo
+     * mount point derived from the info string.
+     */
+    readonly codeFence?: (fence: {
+        readonly text: string;
+        readonly lang: string;
+        readonly info: string;
+        readonly html: string;
+    }) => string;
+}
+
+/** Test seam. */
+export declare const resetCollectionsForTest: () => void;
+
+export declare const setContentRoot: (root: string | null) => void;
+
+/** Slug from the path relative to the collection directory — nested dirs
+ *  stay in the slug, the extension is stripped, locale segment removed when
+ *  the collection is localized. */
+export declare const slugFromRelativePath: (relativePath: string) => string;
+
+/**
+ * Validate every `reference('<collection>')` field across all registered
+ * collections: each value must name an existing entry of the target
+ * collection. The BUILD calls this after loading — a dangling reference is a
+ * named build error, not a runtime null.
+ */
+export declare const validateReferences: () => Promise<void>;
+
+export { }

package/dist/index.js

@@ -0,0 +1,132 @@
+import { Schema as e } from "effect";
+//#region \0rolldown/runtime.js
+var t = Object.defineProperty, n = /* @__PURE__ */ ((e, n) => {
+	let r = {};
+	for (var i in e) t(r, i, {
+		get: e[i],
+		enumerable: !0
+	});
+	return n || t(r, Symbol.toStringTag, { value: "Module" }), r;
+})({
+	ReferenceTarget: () => u,
+	defineCollection: () => a,
+	reference: () => d,
+	referenceFieldsOf: () => p,
+	referenceTargetOf: () => f,
+	registeredCollection: () => s,
+	registeredCollections: () => o,
+	resetCollectionsForTest: () => c,
+	slugFromRelativePath: () => l
+}), r = Symbol.for("@voltro/content:collections"), i = () => {
+	let e = globalThis;
+	return e[r] ??= /* @__PURE__ */ new Map();
+}, a = (e) => {
+	let t = i().get(e.name);
+	if (t !== void 0 && t.directory !== e.directory) throw Error(`defineCollection('${e.name}') is declared twice with different directories ('${t.directory}' vs '${e.directory}') — collection names are global.`);
+	return i().set(e.name, e), e;
+}, o = () => [...i().values()], s = (e) => i().get(e), c = () => {
+	i().clear();
+}, l = (e) => e.replace(/\\/g, "/").replace(/\.(md|mdx|json)$/i, ""), u = Symbol.for("@voltro/content:reference-target"), d = (t) => e.String.annotations({ [u]: t }), f = (e) => {
+	let t = e.annotations?.[u];
+	return typeof t == "string" ? t : void 0;
+}, p = (e) => {
+	let t = /* @__PURE__ */ new Map(), n = e.schema.ast;
+	for (let e of n?.propertySignatures ?? []) {
+		let n = [e.type, ...e.type.types ?? []];
+		for (let r of n) {
+			let n = f(r);
+			n !== void 0 && typeof e.name == "string" && t.set(e.name, n);
+		}
+	}
+	return t;
+}, m = typeof globalThis.process?.versions?.node == "string", h = Symbol.for("@voltro/content:root"), g = (e) => {
+	let t = globalThis;
+	t[h] = e;
+}, _ = () => globalThis[h] ?? null, v = Symbol.for("@voltro/content:cache"), y = () => {
+	let e = globalThis;
+	return e[v] ??= /* @__PURE__ */ new Map();
+}, b = (e) => {
+	if (e === void 0) {
+		y().clear();
+		return;
+	}
+	for (let t of [...y().keys()]) (t === e || t.startsWith(`${e}|`)) && y().delete(t);
+}, x = (e, t) => {
+	let n = t === void 0 ? e.name : `${e.name}|${t}`, r = y().get(n);
+	return r === void 0 && 
+	// @vite-ignore keeps the whole render pipeline (marked + shiki grammars)
+	(r = import(
+		/* @vite-ignore */
+		"./serverLoad"
+).then(({ loadServerCollection: n }) => n(e, t)), y().set(n, r)), r;
+}, S = (e, t, n) => {
+	let r = t === void 0 ? e : `${e}.${t}`;
+	return n === void 0 ? `/assets/content/${r}/index.json` : `/assets/content/${r}/${n}.json`;
+}, C = async (e) => {
+	let t = await fetch(e);
+	return t.ok ? await t.json() : null;
+}, w = (e, t) => {
+	let n = s(e);
+	return n?.i18n === void 0 ? t : t ?? n.i18n.defaultLocale;
+}, T = async (e, t = {}) => {
+	if (m) {
+		let n = s(e);
+		if (n === void 0) throw Error(`getCollection('${e}'): no such collection is defined — export a defineCollection({ name: '${e}', … }) from a *.collection.ts.`);
+		return (await x(n, t.locale)).entries;
+	}
+	return await C(S(e, w(e, t.locale))) ?? [];
+}, E = async (e, t, n = {}) => {
+	if (m) {
+		let r = s(e);
+		if (r === void 0) throw Error(`getEntry('${e}'): no such collection is defined.`);
+		return (await x(r, n.locale)).bySlug.get(t) ?? null;
+	}
+	return await C(S(e, w(e, n.locale), t));
+}, D = async () => {
+	let { referenceFieldsOf: e, registeredCollections: t } = await Promise.resolve().then(() => n), r = [];
+	for (let n of t()) {
+		let t = e(n);
+		if (t.size === 0) continue;
+		let i = n.i18n?.locales ?? [void 0];
+		for (let e of i) {
+			let i = await T(n.name, e === void 0 ? {} : { locale: e });
+			for (let e of i) for (let [i, a] of t) {
+				let t = e.data[i];
+				typeof t == "string" && t !== "" && await E(a, t) === null && r.push(`collection '${n.name}', entry '${e.slug}': field '${i}' references '${t}' in collection '${a}' — no such entry.`);
+			}
+		}
+	}
+	if (r.length > 0) throw Error(`dangling content reference(s):\n${r.join("\n")}`);
+}, O = (e) => e.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;"), k = (e) => {
+	let t = e instanceof Date ? e : new Date(e);
+	return Number.isNaN(t.getTime()) ? String(e) : t.toUTCString();
+}, A = (e, t) => {
+	let n = t.siteUrl.replace(/\/+$/, ""), r = e.map((e) => t.item(e)).filter((e) => e !== null).sort((e, t) => new Date(t.date).getTime() - new Date(e.date).getTime()).map((e) => {
+		let t = e.link.startsWith("http") ? e.link : `${n}/${e.link.replace(/^\/+/, "")}`;
+		return [
+			"    <item>",
+			`      <title>${O(e.title)}</title>`,
+			`      <link>${O(t)}</link>`,
+			`      <guid isPermaLink="${e.guid === void 0 ? "true" : "false"}">${O(e.guid ?? t)}</guid>`,
+			`      <pubDate>${O(k(e.date))}</pubDate>`,
+			...e.description === void 0 ? [] : [`      <description>${O(e.description)}</description>`],
+			...(e.categories ?? []).map((e) => `      <category>${O(e)}</category>`),
+			"    </item>"
+		].join("\n");
+	}).join("\n");
+	return [
+		"<?xml version=\"1.0\" encoding=\"UTF-8\"?>",
+		"<rss version=\"2.0\" xmlns:atom=\"http://www.w3.org/2005/Atom\">",
+		"  <channel>",
+		`    <title>${O(t.title)}</title>`,
+		`    <link>${O(n)}</link>`,
+		...t.description === void 0 ? ["    <description></description>"] : [`    <description>${O(t.description)}</description>`],
+		`    <atom:link href="${O(`${n}${t.feedPath ?? "/rss.xml"}`)}" rel="self" type="application/rss+xml" />`,
+		...r === "" ? [] : [r],
+		"  </channel>",
+		"</rss>",
+		""
+	].join("\n");
+};
+//#endregion
+export { u as ReferenceTarget, A as buildFeed, S as contentArtifactPath, _ as contentRoot, a as defineCollection, T as getCollection, E as getEntry, b as invalidateContentCache, d as reference, p as referenceFieldsOf, f as referenceTargetOf, s as registeredCollection, o as registeredCollections, c as resetCollectionsForTest, g as setContentRoot, l as slugFromRelativePath, D as validateReferences };

package/dist/markdown.d.ts

@@ -0,0 +1,70 @@
+export declare interface ContentHeading {
+    readonly depth: number;
+    readonly slug: string;
+    readonly text: string;
+}
+
+/**
+ * Heading data (depth, slug, text) straight from markdown SOURCE — no render
+ * pass, browser-safe, sync. Slugs and dedup counters are computed by the SAME
+ * code `renderMarkdown` uses, so a TOC built from this always matches the
+ * rendered `id=` attributes.
+ */
+export declare const extractHeadings: (body: string) => ReadonlyArray<ContentHeading>;
+
+/**
+ * Highlight one raw code string to dual-theme shiki HTML — the SAME path a
+ * markdown fence takes, for callers rendering code outside markdown (a
+ * demo-source panel, say). Node only: in a browser (or when shiki is not
+ * installed) it returns an escaped plain `<pre>`.
+ */
+export declare const highlightCode: (code: string, lang: string | undefined) => Promise<string>;
+
+export declare interface ParsedFrontmatter {
+    readonly data: Readonly<Record<string, string | ReadonlyArray<string>>>;
+    readonly body: string;
+}
+
+/** `key: scalar` lines between `---` markers — the only shapes our content
+ *  needs, parsed without a YAML dependency. */
+export declare const parseFrontmatter: (source: string) => ParsedFrontmatter;
+
+export declare interface RenderedMarkdown {
+    readonly html: string;
+    readonly headings: ReadonlyArray<ContentHeading>;
+}
+
+/**
+ * Render a markdown body (GFM) to HTML with heading ids/anchors and the
+ * `headings[]` TOC data. When `highlight` (default) and running on node, code
+ * fences are shiki-highlighted with light+dark themes; the dark variant
+ * activates via the standard `.dark .shiki` / `data-theme` CSS convention
+ * shiki's dual-theme output uses.
+ */
+export declare const renderMarkdown: (body: string, options?: RenderMarkdownOptions) => Promise<RenderedMarkdown>;
+
+export declare interface RenderMarkdownOptions {
+    /** Rewrite relative links (`./sibling.md`, `../other/page.md`) into route
+     *  paths. Receives the raw href; return the replacement (or the input). */
+    readonly resolveLink?: (href: string) => string;
+    /** Highlight code fences with shiki (node only; a browser call renders
+     *  plain `<pre>`). Default true. */
+    readonly highlight?: boolean;
+    /**
+     * Post-process one rendered code fence. Receives the raw code, the resolved
+     * language (first info-string token, lowercased), the FULL info string
+     * (` ```ts preview=data-table ` ⇒ `'ts preview=data-table'`), and the
+     * rendered html. Return the replacement html — e.g. append a live-demo
+     * mount point derived from the info string.
+     */
+    readonly codeFence?: (fence: {
+        readonly text: string;
+        readonly lang: string;
+        readonly info: string;
+        readonly html: string;
+    }) => string;
+}
+
+export declare const slugifyHeading: (value: string) => string;
+
+export { }

package/dist/markdown.js

@@ -0,0 +1,118 @@
+import { marked as e } from "marked";
+//#region src/markdown.ts
+var t = typeof globalThis.process?.versions?.node == "string", n = (e) => {
+	let t = e.trim();
+	return t.startsWith("[") && t.endsWith("]") ? t.slice(1, -1).split(",").map((e) => e.trim().replace(/^['"]|['"]$/g, "")).filter((e) => e.length > 0) : t.replace(/^['"]|['"]$/g, "");
+}, r = (e) => {
+	let t = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(e);
+	if (!t) return {
+		data: {},
+		body: e
+	};
+	let [, r, i] = t, a = {};
+	for (let e of (r ?? "").split(/\r?\n/)) {
+		let t = e.indexOf(":");
+		if (t < 0) continue;
+		let r = e.slice(0, t).trim();
+		r && (a[r] = n(e.slice(t + 1)));
+	}
+	return {
+		data: a,
+		body: i ?? ""
+	};
+}, i = (e) => e.map((e) => "text" in e && typeof e.text == "string" ? e.text : "").join(""), a = (e) => e.toLowerCase().trim().replace(/<[^>]+>/g, "").replace(/[^\p{Letter}\p{Number}]+/gu, "-").replace(/^-+|-+$/g, ""), o = null, s = [
+	"ts",
+	"tsx",
+	"typescript",
+	"js",
+	"jsx",
+	"json",
+	"bash",
+	"sh",
+	"shell",
+	"css",
+	"html",
+	"sql",
+	"yaml",
+	"toml",
+	"md",
+	"mdx",
+	"diff",
+	"text",
+	"txt"
+], c = () => t ? (o ??= import("shiki").then((e) => e.createHighlighter({
+	themes: ["github-light", "github-dark-dimmed"],
+	langs: [...s]
+})).catch(() => null), o) : Promise.resolve(null), l = async (t, n = {}) => {
+	let r = [], o = /* @__PURE__ */ new Map(), l = n.highlight === !1 ? null : await c(), u = new e.Renderer();
+	if (u.heading = ({ depth: t, tokens: n }) => {
+		let s = e.Parser.parseInline(n), c = i(n), l = a(c), u = o.get(l) ?? 0;
+		o.set(l, u + 1);
+		let d = u === 0 ? l : `${l}-${u}`;
+		return r.push({
+			depth: t,
+			slug: d,
+			text: c
+		}), `<h${t} id="${d}"><a class="heading-anchor" href="#${d}" aria-hidden="true">#</a>${s}</h${t}>\n`;
+	}, n.resolveLink !== void 0) {
+		let t = n.resolveLink;
+		u.link = ({ href: n, title: r, tokens: i }) => {
+			let a = e.Parser.parseInline(i);
+			return `<a href="${t(n)}"${r ? ` title="${r}"` : ""}>${a}</a>`;
+		};
+	}
+	return u.code = ({ text: e, lang: t }) => {
+		let r = (t ?? "").trim(), i = (r.split(/\s+/)[0] ?? "").toLowerCase(), a;
+		if (l !== null && s.includes(i)) try {
+			a = l.codeToHtml(e, {
+				lang: i,
+				themes: {
+					light: "github-light",
+					dark: "github-dark-dimmed"
+				}
+			});
+		} catch {
+			a = `<pre><code>${e.replace(/&/g, "&amp;").replace(/</g, "&lt;")}</code></pre>\n`;
+		}
+		else a = `<pre><code>${e.replace(/&/g, "&amp;").replace(/</g, "&lt;")}</code></pre>\n`;
+		return n.codeFence === void 0 ? a : n.codeFence({
+			text: e,
+			lang: i,
+			info: r,
+			html: a
+		});
+	}, {
+		html: await e.parse(t, {
+			async: !0,
+			gfm: !0,
+			renderer: u
+		}),
+		headings: r
+	};
+}, u = async (e, t) => {
+	let n = await c(), r = (t ?? "").trim().split(/\s+/)[0]?.toLowerCase() ?? "";
+	if (n !== null && s.includes(r)) try {
+		return n.codeToHtml(e, {
+			lang: r,
+			themes: {
+				light: "github-light",
+				dark: "github-dark-dimmed"
+			}
+		});
+	} catch {}
+	return `<pre><code>${e.replace(/&/g, "&amp;").replace(/</g, "&lt;")}</code></pre>`;
+}, d = (t) => {
+	let n = [], r = /* @__PURE__ */ new Map();
+	for (let o of e.lexer(t)) {
+		if (o.type !== "heading") continue;
+		let e = o, t = i(e.tokens), s = a(t), c = r.get(s) ?? 0;
+		r.set(s, c + 1), n.push({
+			depth: e.depth,
+			slug: c === 0 ? s : `${s}-${c}`,
+			text: t
+		});
+	}
+	return n;
+};
+//#endregion
+export { d as extractHeadings, u as highlightCode, r as parseFrontmatter, l as renderMarkdown, a as slugifyHeading };

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@voltro/content",
+  "version": "0.53.0",
+  "description": "Content collections — file-based, schema-typed markdown content (defineCollection over content/<name>/**/*.md with effect/Schema frontmatter), an isomorphic getCollection/getEntry (server: FS + rendered HTML with node-gated shiki; client: fetches the build-emitted JSON artifacts), heading extraction, locale trees with fallback, data collections, and a generic feed builder.",
+  "keywords": [
+    "voltro",
+    "typescript",
+    "framework"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://voltro.dev",
+  "bugs": {
+    "email": "support@voltro.dev"
+  },
+  "author": {
+    "name": "Voltro UG",
+    "url": "https://voltro.dev"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./markdown": {
+      "types": "./dist/markdown.d.ts",
+      "import": "./dist/markdown.js",
+      "default": "./dist/markdown.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "dependencies": {
+    "marked": "^18.0.9"
+  },
+  "optionalDependencies": {
+    "shiki": "^4.4.3"
+  },
+  "peerDependencies": {
+    "effect": "^3.22.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}