@bliztek/mdx-utils 1.0.0 → 2.0.0

package/README.md

@@ -88,15 +88,331 @@ Reads a directory and returns slugs (filenames without extension) of matching co
 
 Reads a file and returns its content as a UTF-8 string.
 
+## Collections
+
+For content trees with more than a flat directory of posts — game guides, docs, multi-product changelogs — use `createMdxCollection` to get a typed handle that walks the tree, parses frontmatter, and (optionally) validates against a schema.
+
+### Flat blog
+
+```ts
+import { createMdxCollection } from "@bliztek/mdx-utils/node";
+
+const posts = createMdxCollection({ root: "content/blog" });
+
+const all = await posts.getAll();
+const post = await posts.get({ slug: "my-first-post" });
+```
+
+### Typed frontmatter
+
+Pass a type parameter to make every getter return your shape:
+
+```ts
+interface PostFrontmatter {
+  title: string;
+  publishedAt: string;
+  description?: string;
+  aliases?: string[];
+  relatedSlugs?: string[];
+}
+
+const posts = createMdxCollection<PostFrontmatter>({
+  root: "content/blog",
+});
+
+const all = await posts.getAll();
+// all[0].metadata is typed as PostFrontmatter
+```
+
+If you pair the generic with `frontmatterSchema`, the schema is the runtime enforcer and the generic is the static source of truth. They should agree — the package does not infer one from the other.
+
+### Nested namespaces
+
+```ts
+// content/games/{game}/{slug}.mdx
+const guides = createMdxCollection({
+  root: "content/games",
+  namespaceDepth: 1,
+});
+
+const arkGuides = await guides.getAllByNamespace("ark");
+const specific = await guides.get({ namespace: "ark", slug: "boss-guide" });
+```
+
+Files that sit at the wrong depth throw a clear error — there is no silent coercion.
+
+### Schema validation
+
+The schema interface is structural: anything with a `parse(input): T` method works. No dependency on Zod, Valibot, or Yup.
+
+```ts
+import { z } from "zod";
+
+const schema = z.object({
+  title: z.string(),
+  publishedAt: z.string(),
+  aliases: z.array(z.string()).optional(),
+});
+
+const posts = createMdxCollection({
+  root: "content/blog",
+  frontmatterSchema: schema,
+});
+
+// In next.config.ts — fail the build if any file drifts:
+await posts.validate();
+```
+
+Or hand-rolled, no dependencies at all:
+
+```ts
+const schema = {
+  parse(input: unknown) {
+    const obj = input as Record<string, unknown>;
+    if (typeof obj.title !== "string") throw new Error("title required");
+    return obj as { title: string };
+  },
+};
+```
+
+`validate()` aggregates every issue and throws `MdxValidationError` with a structured `.issues` array, so you can render your own output instead of parsing the message string. `getAll()` never throws on schema violations — it returns the raw frontmatter, cast to your declared type. Validation is an explicit build-time gate, not a runtime foot-gun.
+
+Catching it in a build script:
+
+```ts
+import { MdxValidationError } from "@bliztek/mdx-utils/node";
+
+try {
+  await posts.validate();
+} catch (err) {
+  if (err instanceof MdxValidationError) {
+    for (const issue of err.issues) {
+      console.error(`${issue.filePath} · ${issue.path}: ${issue.message}`);
+    }
+    process.exit(1);
+  }
+  throw err;
+}
+```
+
+### Related entries
+
+Use `resolveRelated` to turn a slug list on one entry into full entries from the same namespace:
+
+```ts
+const post = await posts.get({ slug: "boss-guide" });
+const related = await posts.resolveRelated(
+  post?.namespace ?? "",
+  post?.metadata.relatedSlugs ?? [],
+);
+// related: MdxEntry[] — unknown slugs skipped with a console.warn
+```
+
+### Redirects from renamed slugs
+
+```ts
+// next.config.ts
+import { collectRedirects } from "@bliztek/mdx-utils/node";
+
+export default {
+  async redirects() {
+    return collectRedirects({
+      root: "content/games",
+      namespaceDepth: 1,
+      basePath: "/games/{namespace}/guides/{slug}",
+    });
+  },
+};
+```
+
+Any entry with an `aliases: [...]` field in its frontmatter gets one 301 per alias pointing at the current slug. Tokens `{namespace}` and `{slug}` are substituted from the entry's real location.
+
+### Composing the default frontmatter parser
+
+The built-in parser handles a minimal YAML subset (quoted/unquoted scalars, inline arrays, block arrays). For the long tail, pass a `parseFrontmatter` override — or compose on top of the default:
+
+```ts
+import {
+  createMdxCollection,
+  defaultParseFrontmatter,
+} from "@bliztek/mdx-utils/node";
+
+const posts = createMdxCollection({
+  root: "content/blog",
+  parseFrontmatter: (raw) => {
+    const base = defaultParseFrontmatter(raw);
+    // coerce numbers, parse dates, etc.
+    return base;
+  },
+});
+```
+
+Or replace it entirely with `gray-matter`:
+
+```ts
+import matter from "gray-matter";
+createMdxCollection({
+  root: "content/blog",
+  parseFrontmatter: (raw) => matter(raw).data,
+});
+```
+
+### Caching
+
+`createMdxCollection` reads and parses on the first `getAll()` and caches the result in process. Call `collection.invalidate()` to force a re-read — useful for dev-mode HMR. Production builds typically call each getter once so caching is a pure win.
+
+## Next.js App Router integration
+
+End-to-end wiring for a static blog at `app/blog/[slug]/page.tsx`:
+
+```ts
+// lib/posts.ts
+import { createMdxCollection } from "@bliztek/mdx-utils/node";
+
+export interface PostFrontmatter {
+  title: string;
+  description?: string;
+  publishedAt: string;
+}
+
+export const posts = createMdxCollection<PostFrontmatter>({
+  root: "content/blog",
+});
+```
+
+```tsx
+// app/blog/[slug]/page.tsx
+import { notFound } from "next/navigation";
+import { readMdxFile } from "@bliztek/mdx-utils/node";
+import { posts } from "@/lib/posts";
+
+export async function generateStaticParams() {
+  const all = await posts.getAll();
+  return all.map((p) => ({ slug: p.slug }));
+}
+
+export async function generateMetadata({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  const { slug } = await params;
+  const post = await posts.get({ slug });
+  if (!post) return {};
+  return {
+    title: post.metadata.title,
+    description: post.metadata.description,
+  };
+}
+
+export default async function Page({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  const { slug } = await params;
+  const post = await posts.get({ slug });
+  if (!post) notFound();
+
+  const raw = await readMdxFile(post.filePath);
+  // render `raw` with your MDX compiler of choice — see below
+  return (
+    <article>
+      <h1>{post.metadata.title}</h1>
+      <p>{post.readTime.minutes} min read</p>
+      {/* <MDXRemote source={raw} /> */}
+    </article>
+  );
+}
+```
+
+### Rendering the MDX
+
+This package deliberately does not compile MDX — that is the job of an MDX compiler, and you should pick the one that fits your runtime. Hand the `readMdxFile` output to:
+
+- **[next-mdx-remote](https://github.com/hashicorp/next-mdx-remote)** — server-component-friendly, works inside App Router
+- **[@mdx-js/mdx](https://mdxjs.com/packages/mdx/)** — lower-level, use when you want full control over the compile pipeline
+- **[@next/mdx](https://nextjs.org/docs/app/building-your-application/configuring/mdx)** — if you want file-based MDX routing instead of a collection, though this conflicts with `createMdxCollection`'s indexing model
+
+```tsx
+import { MDXRemote } from "next-mdx-remote/rsc";
+
+const raw = await readMdxFile(post.filePath);
+return <MDXRemote source={raw} />;
+```
+
+### Sitemap
+
+```ts
+// app/sitemap.ts
+import type { MetadataRoute } from "next";
+import { posts } from "@/lib/posts";
+
+export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+  const all = await posts.getAll();
+  return all.map((post) => ({
+    url: `https://example.com/blog/${post.slug}`,
+    lastModified: post.metadata.publishedAt,
+  }));
+}
+```
+
+### API
+
+#### `createMdxCollection(options)`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `root` | `string` | required | Path to the content root |
+| `namespaceDepth` | `number` | `0` | Directory segments between root and file to treat as namespace |
+| `frontmatterSchema` | `{ parse(input): T }` | — | Optional structural validator |
+| `parseFrontmatter` | `(raw) => object` | `defaultParseFrontmatter` | Frontmatter parser override |
+| `wordsPerMinute` | `number` | `238` | Override for read-time calculation |
+
+Returns `{ getAll, getAllByNamespace, get, resolveRelated, validate, invalidate }`.
+
+#### `collectRedirects(options)`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `root` | `string` | required | Path to the content root |
+| `namespaceDepth` | `number` | `0` | Same meaning as above |
+| `basePath` | `string` | required | URL template with `{namespace}`/`{slug}` tokens |
+| `permanent` | `boolean` | `true` | `true` → 301, `false` → 302 |
+| `aliasField` | `string` | `"aliases"` | Frontmatter field to read aliases from |
+
+Returns `NextRedirect[]` — compatible with Next.js `redirects()` config.
+
+### Well-known frontmatter fields
+
+The package treats these fields as well-known when present, but never requires them unless your schema does:
+
+| Field | Type | Purpose |
+|---|---|---|
+| `title` | `string` | Display title |
+| `description` | `string` | Excerpt / meta description |
+| `publishedAt` | `string` (ISO) | Used for sort order |
+| `updatedAt` | `string` (ISO) | For JSON-LD `dateModified` |
+| `aliases` | `string[]` | Consumed by `collectRedirects` |
+| `relatedSlugs` | `string[]` | Consumed by `resolveRelated` |
+
+All other fields are passed through untouched.
+
 ## Types
 
 ```ts
-type TableOfContentsEntry = { title: string; link: string };
+type TableOfContentsEntry = {
+  level: number;
+  text: string;
+  slug: string;
+  children?: TableOfContentsEntry[];
+};
 type TableOfContents = TableOfContentsEntry[];
 
 interface ReadTimeOptions { wordsPerMinute?: number }
 interface ReadTimeResult { minutes: number; words: number }
 interface GetContentSlugsOptions { extensions?: string[]; recursive?: boolean }
+interface FrontmatterSchema<T> { parse(input: unknown): T }
 ```
 
 ## Entry Points
@@ -104,7 +420,7 @@ interface GetContentSlugsOptions { extensions?: string[]; recursive?: boolean }
 | Import | Environment | Contents |
 |--------|------------|----------|
 | `@bliztek/mdx-utils` | Any (browser, edge, Node) | `calculateReadTime`, `stripMdxSyntax`, `sortByDateDescending`, types |
-| `@bliztek/mdx-utils/node` | Node.js | `getContentSlugs`, `readMdxFile` + re-exports from main |
+| `@bliztek/mdx-utils/node` | Node.js | `createMdxCollection`, `collectRedirects`, `defaultParseFrontmatter`, `MdxValidationError`, `getContentSlugs`, `readMdxFile` + re-exports from main |
 
 ## License
 

package/dist/index-is67XHX5.d.cts

@@ -0,0 +1,178 @@
+type TableOfContentsEntry = {
+    /** Heading level: 2 for h2, 3 for h3, etc. */
+    level: number;
+    /** Rendered heading text with inline markup stripped. */
+    text: string;
+    /** URL-safe anchor id. */
+    slug: string;
+    /** Nested subheadings. */
+    children?: TableOfContentsEntry[];
+};
+type TableOfContents = TableOfContentsEntry[];
+interface ReadTimeOptions {
+    /** Words per minute. Defaults to 238. */
+    wordsPerMinute?: number;
+}
+interface ReadTimeResult {
+    /** Estimated read time in minutes (minimum 1). */
+    minutes: number;
+    /** Total word count after stripping MDX/JSX syntax. */
+    words: number;
+}
+interface GetContentSlugsOptions {
+    /** File extensions to include. Defaults to `[".mdx"]`. */
+    extensions?: string[];
+    /** Recursively search subdirectories. Defaults to `false`. */
+    recursive?: boolean;
+}
+/**
+ * Structural schema interface. Any object with a `parse` method that
+ * returns the validated value (or throws) satisfies it — works for Zod,
+ * Valibot, Yup, and hand-rolled validators. No dependency added.
+ */
+interface FrontmatterSchema<T> {
+    parse(input: unknown): T;
+}
+/**
+ * A parsed MDX entry with its metadata and derived fields.
+ */
+interface MdxEntry<TFrontmatter> {
+    /** The namespace path segment(s), or "" when `namespaceDepth` is 0. */
+    namespace: string;
+    /** Filename without the `.mdx` extension. */
+    slug: string;
+    /** Parsed frontmatter, typed if a schema was provided. */
+    metadata: TFrontmatter;
+    /** Estimated read time in minutes. */
+    readTime: number;
+    /**
+     * Table of contents extracted from headings.
+     *
+     * Reserved for a future release — always `undefined` in 1.1.
+     * Consumers should treat it as optional and fall back to a
+     * client-side walker until the server-side implementation lands.
+     */
+    tableOfContents?: TableOfContents;
+    /** Absolute filesystem path. */
+    filePath: string;
+}
+interface CreateMdxCollectionOptions<TFrontmatter> {
+    /**
+     * Filesystem path to the content root. Resolved against `process.cwd()`
+     * if relative.
+     */
+    root: string;
+    /**
+     * How many directory segments between `root` and each `.mdx` file are
+     * treated as the namespace.
+     *
+     * - 0 → flat directory (`content/blog/{slug}.mdx`)
+     * - 1 → one nested dir (`content/games/{namespace}/{slug}.mdx`)
+     * - 2 → two nested dirs (`content/docs/{section}/{subsection}/{slug}.mdx`)
+     *
+     * Files whose depth doesn't match throw a walker error — there is no
+     * silent coercion.
+     *
+     * Defaults to `0`.
+     */
+    namespaceDepth?: number;
+    /**
+     * Optional schema to validate frontmatter against. Accepts anything with
+     * a `parse(input: unknown)` method, so Zod/Valibot/Yup/hand-rolled all
+     * work without adding a dependency.
+     *
+     * Note: `getAll()` does NOT throw on schema violations — it casts and
+     * returns the raw frontmatter. Call `validate()` explicitly (typically
+     * from `next.config`) to fail the build on drift.
+     */
+    frontmatterSchema?: FrontmatterSchema<TFrontmatter>;
+    /**
+     * Override the frontmatter parser. Receives the full file contents,
+     * returns a plain object. Default is `defaultParseFrontmatter`.
+     */
+    parseFrontmatter?: (raw: string) => Record<string, unknown>;
+    /** Words-per-minute override for read-time calculation. Defaults to 238. */
+    wordsPerMinute?: number;
+}
+interface MdxCollectionGetArgs {
+    /** Required when `namespaceDepth > 0`. Omit for depth-0 collections. */
+    namespace?: string;
+    slug: string;
+}
+interface MdxCollection<TFrontmatter> {
+    /**
+     * All entries in the collection. Entries with a parseable `publishedAt`
+     * are sorted descending first; the rest are appended in walk order.
+     */
+    getAll(): Promise<MdxEntry<TFrontmatter>[]>;
+    /** Entries filtered to a single namespace. */
+    getAllByNamespace(namespace: string): Promise<MdxEntry<TFrontmatter>[]>;
+    /**
+     * Fetch a single entry by namespace + slug (or just slug for depth-0
+     * collections). Returns `null` if not found.
+     */
+    get(args: MdxCollectionGetArgs): Promise<MdxEntry<TFrontmatter> | null>;
+    /**
+     * Resolve a list of related slugs within a namespace to full entries.
+     * Unknown slugs are skipped with a `console.warn`.
+     *
+     * Note: cross-namespace related content is a foreseeable future need
+     * and will require a signature change. Flagged intentionally.
+     */
+    resolveRelated(namespace: string, slugs: string[]): Promise<MdxEntry<TFrontmatter>[]>;
+    /**
+     * Validate every file against `frontmatterSchema` and throw an
+     * aggregated `MdxValidationError` if any fail. No-op when no schema
+     * is configured.
+     */
+    validate(): Promise<void>;
+    /** Drop the in-process cache so the next call re-reads the filesystem. */
+    invalidate(): void;
+}
+interface MdxValidationIssue {
+    /** Absolute path of the offending file. */
+    filePath: string;
+    /** Dotted path into the frontmatter object where validation failed. */
+    path: string;
+    /** Human-readable explanation. */
+    message: string;
+}
+interface CollectRedirectsOptions {
+    root: string;
+    namespaceDepth?: number;
+    /**
+     * URL template. Supported tokens: `{namespace}`, `{slug}`.
+     * Example: `"/games/{namespace}/guides/{slug}"`
+     */
+    basePath: string;
+    /** Defaults to `true` (301). Set `false` for 302. */
+    permanent?: boolean;
+    /** Frontmatter field to read aliases from. Defaults to `"aliases"`. */
+    aliasField?: string;
+}
+interface NextRedirect {
+    source: string;
+    destination: string;
+    permanent: boolean;
+}
+
+/**
+ * Strip MDX/markdown syntax from content, returning plain text.
+ * Removes export blocks, import statements, JSX tags, and markdown
+ * formatting characters. Useful for generating excerpts, search
+ * indexes, or OpenGraph descriptions from raw MDX.
+ */
+declare function stripMdxSyntax(content: string): string;
+/**
+ * Calculate estimated read time for MDX/markdown content.
+ * Strips export blocks, import statements, JSX tags, and markdown syntax
+ * before counting words.
+ */
+declare function calculateReadTime(content: string, options?: ReadTimeOptions): ReadTimeResult;
+/**
+ * Sort items by date in descending order (newest first).
+ * Returns a new array without mutating the original.
+ */
+declare function sortByDateDescending<T>(items: T[], getDate: (item: T) => string): T[];
+
+export { type CreateMdxCollectionOptions as C, type FrontmatterSchema as F, type GetContentSlugsOptions as G, type MdxCollection as M, type NextRedirect as N, type ReadTimeOptions as R, type TableOfContents as T, type CollectRedirectsOptions as a, type MdxValidationIssue as b, type MdxCollectionGetArgs as c, type MdxEntry as d, type ReadTimeResult as e, type TableOfContentsEntry as f, calculateReadTime as g, stripMdxSyntax as h, sortByDateDescending as s };

package/dist/index-is67XHX5.d.ts

@@ -0,0 +1,178 @@
+type TableOfContentsEntry = {
+    /** Heading level: 2 for h2, 3 for h3, etc. */
+    level: number;
+    /** Rendered heading text with inline markup stripped. */
+    text: string;
+    /** URL-safe anchor id. */
+    slug: string;
+    /** Nested subheadings. */
+    children?: TableOfContentsEntry[];
+};
+type TableOfContents = TableOfContentsEntry[];
+interface ReadTimeOptions {
+    /** Words per minute. Defaults to 238. */
+    wordsPerMinute?: number;
+}
+interface ReadTimeResult {
+    /** Estimated read time in minutes (minimum 1). */
+    minutes: number;
+    /** Total word count after stripping MDX/JSX syntax. */
+    words: number;
+}
+interface GetContentSlugsOptions {
+    /** File extensions to include. Defaults to `[".mdx"]`. */
+    extensions?: string[];
+    /** Recursively search subdirectories. Defaults to `false`. */
+    recursive?: boolean;
+}
+/**
+ * Structural schema interface. Any object with a `parse` method that
+ * returns the validated value (or throws) satisfies it — works for Zod,
+ * Valibot, Yup, and hand-rolled validators. No dependency added.
+ */
+interface FrontmatterSchema<T> {
+    parse(input: unknown): T;
+}
+/**
+ * A parsed MDX entry with its metadata and derived fields.
+ */
+interface MdxEntry<TFrontmatter> {
+    /** The namespace path segment(s), or "" when `namespaceDepth` is 0. */
+    namespace: string;
+    /** Filename without the `.mdx` extension. */
+    slug: string;
+    /** Parsed frontmatter, typed if a schema was provided. */
+    metadata: TFrontmatter;
+    /** Estimated read time in minutes. */
+    readTime: number;
+    /**
+     * Table of contents extracted from headings.
+     *
+     * Reserved for a future release — always `undefined` in 1.1.
+     * Consumers should treat it as optional and fall back to a
+     * client-side walker until the server-side implementation lands.
+     */
+    tableOfContents?: TableOfContents;
+    /** Absolute filesystem path. */
+    filePath: string;
+}
+interface CreateMdxCollectionOptions<TFrontmatter> {
+    /**
+     * Filesystem path to the content root. Resolved against `process.cwd()`
+     * if relative.
+     */
+    root: string;
+    /**
+     * How many directory segments between `root` and each `.mdx` file are
+     * treated as the namespace.
+     *
+     * - 0 → flat directory (`content/blog/{slug}.mdx`)
+     * - 1 → one nested dir (`content/games/{namespace}/{slug}.mdx`)
+     * - 2 → two nested dirs (`content/docs/{section}/{subsection}/{slug}.mdx`)
+     *
+     * Files whose depth doesn't match throw a walker error — there is no
+     * silent coercion.
+     *
+     * Defaults to `0`.
+     */
+    namespaceDepth?: number;
+    /**
+     * Optional schema to validate frontmatter against. Accepts anything with
+     * a `parse(input: unknown)` method, so Zod/Valibot/Yup/hand-rolled all
+     * work without adding a dependency.
+     *
+     * Note: `getAll()` does NOT throw on schema violations — it casts and
+     * returns the raw frontmatter. Call `validate()` explicitly (typically
+     * from `next.config`) to fail the build on drift.
+     */
+    frontmatterSchema?: FrontmatterSchema<TFrontmatter>;
+    /**
+     * Override the frontmatter parser. Receives the full file contents,
+     * returns a plain object. Default is `defaultParseFrontmatter`.
+     */
+    parseFrontmatter?: (raw: string) => Record<string, unknown>;
+    /** Words-per-minute override for read-time calculation. Defaults to 238. */
+    wordsPerMinute?: number;
+}
+interface MdxCollectionGetArgs {
+    /** Required when `namespaceDepth > 0`. Omit for depth-0 collections. */
+    namespace?: string;
+    slug: string;
+}
+interface MdxCollection<TFrontmatter> {
+    /**
+     * All entries in the collection. Entries with a parseable `publishedAt`
+     * are sorted descending first; the rest are appended in walk order.
+     */
+    getAll(): Promise<MdxEntry<TFrontmatter>[]>;
+    /** Entries filtered to a single namespace. */
+    getAllByNamespace(namespace: string): Promise<MdxEntry<TFrontmatter>[]>;
+    /**
+     * Fetch a single entry by namespace + slug (or just slug for depth-0
+     * collections). Returns `null` if not found.
+     */
+    get(args: MdxCollectionGetArgs): Promise<MdxEntry<TFrontmatter> | null>;
+    /**
+     * Resolve a list of related slugs within a namespace to full entries.
+     * Unknown slugs are skipped with a `console.warn`.
+     *
+     * Note: cross-namespace related content is a foreseeable future need
+     * and will require a signature change. Flagged intentionally.
+     */
+    resolveRelated(namespace: string, slugs: string[]): Promise<MdxEntry<TFrontmatter>[]>;
+    /**
+     * Validate every file against `frontmatterSchema` and throw an
+     * aggregated `MdxValidationError` if any fail. No-op when no schema
+     * is configured.
+     */
+    validate(): Promise<void>;
+    /** Drop the in-process cache so the next call re-reads the filesystem. */
+    invalidate(): void;
+}
+interface MdxValidationIssue {
+    /** Absolute path of the offending file. */
+    filePath: string;
+    /** Dotted path into the frontmatter object where validation failed. */
+    path: string;
+    /** Human-readable explanation. */
+    message: string;
+}
+interface CollectRedirectsOptions {
+    root: string;
+    namespaceDepth?: number;
+    /**
+     * URL template. Supported tokens: `{namespace}`, `{slug}`.
+     * Example: `"/games/{namespace}/guides/{slug}"`
+     */
+    basePath: string;
+    /** Defaults to `true` (301). Set `false` for 302. */
+    permanent?: boolean;
+    /** Frontmatter field to read aliases from. Defaults to `"aliases"`. */
+    aliasField?: string;
+}
+interface NextRedirect {
+    source: string;
+    destination: string;
+    permanent: boolean;
+}
+
+/**
+ * Strip MDX/markdown syntax from content, returning plain text.
+ * Removes export blocks, import statements, JSX tags, and markdown
+ * formatting characters. Useful for generating excerpts, search
+ * indexes, or OpenGraph descriptions from raw MDX.
+ */
+declare function stripMdxSyntax(content: string): string;
+/**
+ * Calculate estimated read time for MDX/markdown content.
+ * Strips export blocks, import statements, JSX tags, and markdown syntax
+ * before counting words.
+ */
+declare function calculateReadTime(content: string, options?: ReadTimeOptions): ReadTimeResult;
+/**
+ * Sort items by date in descending order (newest first).
+ * Returns a new array without mutating the original.
+ */
+declare function sortByDateDescending<T>(items: T[], getDate: (item: T) => string): T[];
+
+export { type CreateMdxCollectionOptions as C, type FrontmatterSchema as F, type GetContentSlugsOptions as G, type MdxCollection as M, type NextRedirect as N, type ReadTimeOptions as R, type TableOfContents as T, type CollectRedirectsOptions as a, type MdxValidationIssue as b, type MdxCollectionGetArgs as c, type MdxEntry as d, type ReadTimeResult as e, type TableOfContentsEntry as f, calculateReadTime as g, stripMdxSyntax as h, sortByDateDescending as s };