@nifrajs/content 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nifra Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,18 @@
+# @nifrajs/content
+
+Typed, schema-validated content collections for nifra — Markdown + frontmatter, framework-agnostic.
+
+Part of the **[nifra](https://nifra.dev)** full-stack TypeScript framework — one core, five UI libraries, every runtime. Scaffold a new app with `bun create nifra`.
+
+## Install
+
+```sh
+bun add @nifrajs/content
+```
+
+## Docs
+
+- Reference: <https://nifra.dev/docs>
+- AI-readable: <https://nifra.dev/llms.txt>
+
+MIT

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@nifrajs/content",
+  "version": "0.1.0-alpha.1",
+  "description": "Typed, schema-validated content collections for nifra — Markdown + frontmatter, framework-agnostic.",
+  "keywords": [
+    "bun",
+    "typescript",
+    "nifra",
+    "web-framework",
+    "full-stack",
+    "edge",
+    "ssr"
+  ],
+  "type": "module",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./fs": {
+      "bun": "./src/fs.ts",
+      "types": "./src/fs.ts",
+      "default": "./src/fs.ts"
+    },
+    "./mdx": {
+      "bun": "./src/mdx.ts",
+      "types": "./src/mdx.ts",
+      "default": "./src/mdx.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "sideEffects": false,
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "marked": "^15.0.0",
+    "yaml": "^2.6.0"
+  },
+  "peerDependencies": {
+    "@mdx-js/mdx": "^3"
+  },
+  "peerDependenciesMeta": {
+    "@mdx-js/mdx": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nifrajs/nifra.git",
+    "directory": "packages/content"
+  },
+  "bugs": {
+    "url": "https://github.com/nifrajs/nifra/issues"
+  },
+  "homepage": "https://github.com/nifrajs/nifra#readme"
+}

package/src/fs.ts

@@ -0,0 +1,140 @@
+/**
+ * Filesystem-backed content collections — `defineCollection` reads a directory of Markdown files and
+ * gives you a typed, validated API over them. Build/server-time (Bun/Node/Deno); for the edge, bake the
+ * entries at build (the manifest approach `@nifrajs/web/fs` uses for routes) — tracked as a follow-up.
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs"
+import { resolve, sep } from "node:path"
+import { type Entry, type InferSchema, parseEntry, type StandardSchemaV1 } from "./index.ts"
+
+export interface CollectionConfig<S extends StandardSchemaV1> {
+  /** Directory of content files, relative to the process cwd (or absolute). */
+  readonly dir: string
+  /** Standard Schema validating each file's frontmatter. */
+  readonly schema: S
+  /** File extensions to include (default `[".md", ".markdown"]`). */
+  readonly extensions?: readonly string[]
+}
+
+/** A typed collection over a content directory. */
+export interface Collection<Frontmatter> {
+  /** Every entry in the directory (unordered — sort/filter in your loader). Throws if any file's
+   * frontmatter is invalid. */
+  all(): Promise<Array<Entry<Frontmatter>>>
+  /** One entry by slug (filename without extension), or `null` if not found. */
+  get(slug: string): Promise<Entry<Frontmatter> | null>
+}
+
+const DEFAULT_EXTENSIONS = [".md", ".markdown"] as const
+
+const slugOf = (file: string): string => file.replace(/\.[^.]+$/, "")
+
+const isSafeSlug = (slug: string): boolean =>
+  slug !== "." &&
+  slug !== ".." &&
+  !slug.includes("/") &&
+  !slug.includes("\\") &&
+  !slug.includes("\0")
+
+const assertSafeExtensions = (extensions: readonly string[]): void => {
+  for (const ext of extensions) {
+    if (!ext.startsWith(".") || ext.includes("/") || ext.includes("\\") || ext.includes("\0")) {
+      throw new Error(`@nifrajs/content: invalid extension "${ext}"`)
+    }
+  }
+}
+
+const insideRoot = (root: string, file: string): boolean =>
+  file !== root && file.startsWith(`${root}${sep}`)
+
+interface FileRecord {
+  readonly file: string
+  readonly path: string
+  readonly stamp: string
+}
+
+interface CachedEntry<Frontmatter> {
+  readonly stamp: string
+  readonly entry: Entry<Frontmatter>
+}
+
+interface CollectionSnapshot<Frontmatter> {
+  readonly signature: string
+  readonly entries: Array<Entry<Frontmatter>>
+}
+
+/**
+ * Define a content collection backed by a directory. `all()` discovers + parses every matching file;
+ * `get(slug)` loads one. Frontmatter is validated against `schema`, so entries are fully typed and a
+ * malformed file fails loudly. Reads the filesystem — use it at build time (SSG/prerender) or on a
+ * long-lived server (Bun/Node/Deno).
+ */
+export function defineCollection<S extends StandardSchemaV1>(
+  config: CollectionConfig<S>,
+): Collection<InferSchema<S>> {
+  const extensions = config.extensions ?? DEFAULT_EXTENSIONS
+  assertSafeExtensions(extensions)
+  const root = resolve(config.dir)
+  const matches = (file: string): boolean => extensions.some((ext) => file.endsWith(ext))
+  const fileCache = new Map<string, CachedEntry<InferSchema<S>>>()
+  let collectionCache: CollectionSnapshot<InferSchema<S>> | undefined
+
+  const readEntry = async (
+    path: string,
+    slug: string,
+    stamp: string,
+  ): Promise<Entry<InferSchema<S>>> => {
+    const cached = fileCache.get(path)
+    if (cached?.stamp === stamp) return cached.entry
+    const entry = await parseEntry({
+      raw: readFileSync(path, "utf8"),
+      slug,
+      schema: config.schema,
+    })
+    fileCache.set(path, { stamp, entry })
+    return entry
+  }
+
+  const listFiles = (): FileRecord[] =>
+    readdirSync(root)
+      .filter(matches)
+      .sort()
+      .map((file) => {
+        const path = resolve(root, file)
+        const stat = statSync(path)
+        return { file, path, stamp: `${stat.mtimeMs}:${stat.size}` }
+      })
+
+  return {
+    async all() {
+      const files = listFiles()
+      const signature = files.map((file) => `${file.file}\0${file.stamp}`).join("\0")
+      if (collectionCache?.signature === signature) return [...collectionCache.entries]
+
+      const entries = await Promise.all(
+        files.map((file) => readEntry(file.path, slugOf(file.file), file.stamp)),
+      )
+      collectionCache = {
+        signature,
+        entries,
+      }
+      return [...entries]
+    },
+    async get(slug) {
+      if (!isSafeSlug(slug)) return null
+
+      for (const ext of extensions) {
+        const file = resolve(root, `${slug}${ext}`)
+        if (!insideRoot(root, file)) return null
+        try {
+          const stat = statSync(file)
+          if (!stat.isFile()) continue
+          return await readEntry(file, slug, `${stat.mtimeMs}:${stat.size}`)
+        } catch {
+          // Not this extension or unreadable; try the next configured extension.
+        }
+      }
+      return null
+    },
+  }
+}

package/src/index.ts

@@ -0,0 +1,142 @@
+/**
+ * Typed content collections for nifra — the **framework-agnostic core**. Parse a Markdown file's
+ * frontmatter + body, validate the frontmatter against a Standard Schema (`@nifrajs/schema`'s `t`, zod,
+ * valibot), and render the body to HTML. Pure (no filesystem, no DOM) so it runs anywhere — pair it
+ * with `@nifrajs/content/fs`'s `defineCollection` for fs-backed discovery on Bun/Node/Deno + at build.
+ *
+ *   import { t } from "@nifrajs/schema"
+ *   import { defineCollection } from "@nifrajs/content/fs"
+ *
+ *   const blog = defineCollection({
+ *     dir: "content/blog",
+ *     schema: t.object({ title: t.string(), date: t.string(), draft: t.boolean() }),
+ *   })
+ *
+ *   // in a loader — typed + validated entries, no manual fs/frontmatter parsing:
+ *   const posts = (await blog.all()).filter((p) => !p.frontmatter.draft)
+ *   //    posts[0].frontmatter is { title: string; date: string; draft: boolean }
+ *   //    posts[0].html is the rendered Markdown
+ */
+import { marked } from "marked"
+import { parse as parseYaml } from "yaml"
+
+/** A Standard Schema issue (the subset we surface). */
+interface StandardIssue {
+  readonly message: string
+}
+
+/**
+ * Minimal [Standard Schema](https://standardschema.dev) shape — lets frontmatter validate against any
+ * compliant validator (`@nifrajs/schema`'s `t`, zod, valibot, …) without coupling `@nifrajs/content` to one.
+ */
+export interface StandardSchemaV1<Output = unknown> {
+  readonly "~standard": {
+    readonly validate: (
+      value: unknown,
+    ) =>
+      | { readonly value: Output; readonly issues?: undefined }
+      | { readonly issues: ReadonlyArray<StandardIssue> }
+      | Promise<
+          | { readonly value: Output; readonly issues?: undefined }
+          | { readonly issues: ReadonlyArray<StandardIssue> }
+        >
+  }
+}
+
+/** The validated output type of a schema. */
+export type InferSchema<S> = S extends StandardSchemaV1<infer Output> ? Output : never
+
+/** A parsed content entry: its slug, validated frontmatter, rendered HTML, and the raw Markdown body. */
+export interface Entry<Frontmatter> {
+  /** Identifier (e.g. the filename without extension). */
+  readonly slug: string
+  /** Frontmatter, validated + typed by the collection's schema. */
+  readonly frontmatter: Frontmatter
+  /** The body rendered to HTML (Markdown → HTML). */
+  readonly html: string
+  /** The raw Markdown body, with the frontmatter block stripped. */
+  readonly body: string
+}
+
+// A leading `---` … `---` YAML frontmatter block. Tolerates CRLF and an optional trailing newline.
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/
+
+/** Split a raw content string into its (unvalidated) frontmatter data + the body. No frontmatter block
+ * ⇒ `data` is `{}` and `body` is the whole input. */
+export function parseFrontmatter(raw: string): { data: unknown; body: string } {
+  const match = FRONTMATTER.exec(raw)
+  if (match === null) return { data: {}, body: raw }
+  const data = (parseYaml(match[1] ?? "") as unknown) ?? {}
+  return { data, body: raw.slice(match[0].length) }
+}
+
+export interface ParseEntryOptions<S extends StandardSchemaV1> {
+  readonly raw: string
+  readonly slug: string
+  /** Standard Schema validating the frontmatter — a typo'd/missing field throws (a build-time failure,
+   * never a broken page). */
+  readonly schema: S
+}
+
+/**
+ * Parse one content file: split + validate its frontmatter against `schema`, render its Markdown body
+ * to HTML. Throws a descriptive error (naming the slug + the issues) when the frontmatter is invalid —
+ * surface it at build/load time rather than shipping a malformed entry. Pure + edge-safe.
+ */
+export async function parseEntry<S extends StandardSchemaV1>(
+  options: ParseEntryOptions<S>,
+): Promise<Entry<InferSchema<S>>> {
+  const { data, body } = parseFrontmatter(options.raw)
+  const result = await options.schema["~standard"].validate(data)
+  if (result.issues !== undefined) {
+    const detail = result.issues.map((issue) => issue.message).join("; ")
+    throw new Error(`@nifrajs/content: invalid frontmatter in "${options.slug}": ${detail}`)
+  }
+  // `marked.parse` is sync by default but may be async with extensions — await covers both. Content is
+  // author-controlled (your own files), so raw HTML in Markdown is passed through (standard SSG
+  // behavior); sanitize yourself if a collection ever holds untrusted input.
+  const html = await marked.parse(body)
+  return { slug: options.slug, frontmatter: result.value as InferSchema<S>, html, body }
+}
+
+/**
+ * A content collection baked to plain data — fs-free, so it works at the **edge** (Workers
+ * request-time) where `defineCollection`'s `node:fs` reader can't run. Produce one at build/server time
+ * with `bakeCollection`, JSON-serialize + ship it in the bundle, then rehydrate with `fromBaked`.
+ */
+export interface BakedCollection<Frontmatter> {
+  readonly entries: ReadonlyArray<Entry<Frontmatter>>
+}
+
+/** Read-only collection surface (`all()`/`get()`) — structurally compatible with `defineCollection`'s
+ * `Collection`, but with no filesystem access. */
+export interface StaticCollection<Frontmatter> {
+  all(): Promise<ReadonlyArray<Entry<Frontmatter>>>
+  get(slug: string): Promise<Entry<Frontmatter> | null>
+}
+
+/**
+ * Bake a collection's entries to serializable data at build/server time. The collection does the
+ * filesystem read + validation (via `all()`); this just collects the already-parsed result so it can be
+ * JSON-serialized into the edge bundle. Pure — safe to import anywhere.
+ */
+export async function bakeCollection<Frontmatter>(collection: {
+  all(): Promise<ReadonlyArray<Entry<Frontmatter>>>
+}): Promise<BakedCollection<Frontmatter>> {
+  return { entries: await collection.all() }
+}
+
+/**
+ * Rehydrate a baked collection into a read-only `all()`/`get()` collection — fs-free, edge-safe. The
+ * entries were validated when baked (build output, trusted), so they're served as-is. `get` is O(1).
+ */
+export function fromBaked<Frontmatter>(
+  baked: BakedCollection<Frontmatter>,
+): StaticCollection<Frontmatter> {
+  const entries = baked.entries
+  const bySlug = new Map(entries.map((entry) => [entry.slug, entry]))
+  return {
+    all: () => Promise.resolve(entries),
+    get: (slug) => Promise.resolve(bySlug.get(slug) ?? null),
+  }
+}

package/src/mdx.ts

@@ -0,0 +1,75 @@
+/**
+ * `mdxBunPlugin` — a `Bun.build` plugin that compiles `.mdx` files (Markdown + JSX components) into
+ * components for your UI framework, so an `.mdx` file can be a nifra route or be imported like a module.
+ * Pass it to `buildClient`/`buildServer`'s `plugins`, and add `.mdx` to your route discovery.
+ *
+ *   import { buildClient } from "@nifrajs/web/build"
+ *   import { mdxBunPlugin } from "@nifrajs/content/mdx"
+ *
+ *   await buildClient({
+ *     routesDir: "./routes",
+ *     clientModule: "@nifrajs/web-react/client",
+ *     plugins: [mdxBunPlugin({ jsxImportSource: "react" })],
+ *   })
+ *
+ * MDX is JSX-oriented, so this targets the JSX family (React/Preact/Solid) via `jsxImportSource`. Needs
+ * `@mdx-js/mdx` installed (an optional peer — lazy-loaded at build time only).
+ */
+import type { BunPlugin } from "bun"
+
+export interface MdxPluginOptions {
+  /** JSX runtime source the compiled MDX imports from — `"react"` (default), `"preact"`, `"solid-js"`. */
+  readonly jsxImportSource?: string
+  /** Emit development JSX (line numbers, `jsxDEV`). Default `false`. */
+  readonly development?: boolean
+  /** Extra `@mdx-js/mdx` `compile` options — e.g. `remarkPlugins`/`rehypePlugins` (GFM, slugs, …). */
+  readonly compileOptions?: Record<string, unknown>
+  /** Advanced: override the compiler module specifier (default `"@mdx-js/mdx"`) — e.g. to use a fork. */
+  readonly moduleName?: string
+}
+
+// Non-literal specifier so tsc/consumers don't need `@mdx-js/mdx`'s types to typecheck this file — it's
+// an optional peer, imported only when the plugin actually runs (mirrors `@nifrajs/node`'s lazy `ws`).
+const MDX_MODULE = "@mdx-js/mdx"
+
+interface MdxCompiler {
+  compile(source: string, options?: Record<string, unknown>): Promise<{ toString(): string }>
+}
+
+/**
+ * Build a `Bun.build` plugin that loads `.mdx` files as compiled components. The compiled module's
+ * default export is the MDX content component; `.mdx` files may `import` and use components inline and
+ * `export const meta = …` like any route module.
+ */
+export function mdxBunPlugin(options: MdxPluginOptions = {}): BunPlugin {
+  const jsxImportSource = options.jsxImportSource ?? "react"
+  const development = options.development ?? false
+  return {
+    name: "nifra-mdx",
+    async setup(build) {
+      let compile: MdxCompiler["compile"]
+      try {
+        const mod = (await import(options.moduleName ?? MDX_MODULE)) as MdxCompiler
+        compile = mod.compile
+      } catch {
+        throw new Error(
+          "@nifrajs/content/mdx: compiling `.mdx` needs the `@mdx-js/mdx` package — install it (`bun add @mdx-js/mdx`).",
+        )
+      }
+      // Tolerate a `?query` suffix — `nifra dev` (Vite) appends an import-cache-busting query so edited
+      // `.mdx` re-SSR; strip it before reading off disk.
+      build.onLoad({ filter: /\.mdx(\?|$)/ }, async (args) => {
+        const path = args.path.split("?")[0] ?? args.path
+        const source = await Bun.file(path).text()
+        const compiled = await compile(source, {
+          jsxImportSource,
+          development,
+          ...options.compileOptions,
+        })
+        // `loader: "jsx"` — the compiled output still contains JSX; Bun applies the JSX transform with
+        // the active `jsxImportSource`. Markup is hydration-equivalent to a hand-written component.
+        return { contents: String(compiled), loader: "jsx" }
+      })
+    },
+  }
+}