@bliztek/mdx-utils 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Bliztek, LLC
+
+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,111 @@
+# @bliztek/mdx-utils
+
+Zero-dependency MDX content utilities for read time calculation and file discovery.
+
+## Installation
+
+```bash
+npm install @bliztek/mdx-utils
+```
+
+## Usage
+
+### Pure Utilities (any JS environment)
+
+```ts
+import {
+  calculateReadTime,
+  sortByDateDescending,
+  stripMdxSyntax,
+} from "@bliztek/mdx-utils";
+
+// Calculate read time from raw MDX content
+const { minutes, words } = calculateReadTime(mdxContent);
+// => { minutes: 5, words: 1190 }
+
+// Custom words per minute
+const { minutes } = calculateReadTime(technicalDoc, { wordsPerMinute: 150 });
+
+// Strip MDX syntax for excerpts, search indexes, or OG descriptions
+const plainText = stripMdxSyntax(mdxContent);
+
+// Sort items by date (newest first)
+const sorted = sortByDateDescending(posts, (post) => post.date);
+```
+
+### Node.js Utilities
+
+```ts
+import { getContentSlugs, readMdxFile } from "@bliztek/mdx-utils/node";
+
+// Get all MDX slugs from a directory
+const slugs = await getContentSlugs("./content/blog");
+// => ["my-first-post", "another-post"]
+
+// Include .md files too
+const all = await getContentSlugs("./content", {
+  extensions: [".mdx", ".md"],
+});
+
+// Recursively search nested directories
+const nested = await getContentSlugs("./content/blog", { recursive: true });
+// => ["my-first-post", "2024/year-in-review"]
+
+// Read an MDX file
+const content = await readMdxFile("./content/blog/my-first-post.mdx");
+```
+
+## API
+
+### `calculateReadTime(content, options?)`
+
+Calculates estimated read time for MDX/markdown content. Strips export blocks, import statements, JSX tags, and markdown syntax before counting words.
+
+Returns `{ minutes: number, words: number }` — minutes is always at least 1.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `wordsPerMinute` | `number` | `238` | Reading speed to use for calculation |
+
+### `stripMdxSyntax(content)`
+
+Strips 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.
+
+### `sortByDateDescending(items, getDate)`
+
+Sorts items by date in descending order (newest first). Returns a new array without mutating the original. The `getDate` callback should return a date string parseable by `new Date()`.
+
+### `getContentSlugs(dirPath, options?)`
+
+Reads a directory and returns slugs (filenames without extension) of matching content files. When `recursive` is true, slugs from subdirectories include their relative path (e.g., `"2024/my-post"`).
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `extensions` | `string[]` | `[".mdx"]` | File extensions to include |
+| `recursive` | `boolean` | `false` | Search subdirectories |
+
+### `readMdxFile(filePath)`
+
+Reads a file and returns its content as a UTF-8 string.
+
+## Types
+
+```ts
+type TableOfContentsEntry = { title: string; link: string };
+type TableOfContents = TableOfContentsEntry[];
+
+interface ReadTimeOptions { wordsPerMinute?: number }
+interface ReadTimeResult { minutes: number; words: number }
+interface GetContentSlugsOptions { extensions?: string[]; recursive?: boolean }
+```
+
+## Entry Points
+
+| 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 |
+
+## License
+
+MIT

package/dist/chunk-2WOYQBZW.js

@@ -0,0 +1,25 @@
+// src/index.ts
+var DEFAULT_WPM = 238;
+function stripMdxSyntax(content) {
+  return content.replace(/^export\s+const\s+\w+\s*=\s*[\s\S]*?^};?\s*$/gm, "").replace(/^import\s.*$/gm, "").replace(/```[\s\S]*?```/g, "").replace(/<[^>]+>/g, "").replace(/[#*`~\[\](){}|>]/g, "").replace(/\s+/g, " ").trim();
+}
+function calculateReadTime(content, options) {
+  const wpm = options?.wordsPerMinute ?? DEFAULT_WPM;
+  const text = stripMdxSyntax(content);
+  const words = text ? text.split(/\s+/).length : 0;
+  return {
+    minutes: Math.max(1, Math.ceil(words / wpm)),
+    words
+  };
+}
+function sortByDateDescending(items, getDate) {
+  return [...items].sort(
+    (a, b) => new Date(getDate(b)).getTime() - new Date(getDate(a)).getTime()
+  );
+}
+
+export {
+  stripMdxSyntax,
+  calculateReadTime,
+  sortByDateDescending
+};

package/dist/index.cjs

@@ -0,0 +1,51 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  calculateReadTime: () => calculateReadTime,
+  sortByDateDescending: () => sortByDateDescending,
+  stripMdxSyntax: () => stripMdxSyntax
+});
+module.exports = __toCommonJS(index_exports);
+var DEFAULT_WPM = 238;
+function stripMdxSyntax(content) {
+  return content.replace(/^export\s+const\s+\w+\s*=\s*[\s\S]*?^};?\s*$/gm, "").replace(/^import\s.*$/gm, "").replace(/```[\s\S]*?```/g, "").replace(/<[^>]+>/g, "").replace(/[#*`~\[\](){}|>]/g, "").replace(/\s+/g, " ").trim();
+}
+function calculateReadTime(content, options) {
+  const wpm = options?.wordsPerMinute ?? DEFAULT_WPM;
+  const text = stripMdxSyntax(content);
+  const words = text ? text.split(/\s+/).length : 0;
+  return {
+    minutes: Math.max(1, Math.ceil(words / wpm)),
+    words
+  };
+}
+function sortByDateDescending(items, getDate) {
+  return [...items].sort(
+    (a, b) => new Date(getDate(b)).getTime() - new Date(getDate(a)).getTime()
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  calculateReadTime,
+  sortByDateDescending,
+  stripMdxSyntax
+});

package/dist/index.d.cts

@@ -0,0 +1,42 @@
+type TableOfContentsEntry = {
+    title: string;
+    link: string;
+};
+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;
+}
+
+/**
+ * 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 GetContentSlugsOptions, type ReadTimeOptions, type ReadTimeResult, type TableOfContents, type TableOfContentsEntry, calculateReadTime, sortByDateDescending, stripMdxSyntax };

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+type TableOfContentsEntry = {
+    title: string;
+    link: string;
+};
+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;
+}
+
+/**
+ * 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 GetContentSlugsOptions, type ReadTimeOptions, type ReadTimeResult, type TableOfContents, type TableOfContentsEntry, calculateReadTime, sortByDateDescending, stripMdxSyntax };

package/dist/index.js

@@ -0,0 +1,10 @@
+import {
+  calculateReadTime,
+  sortByDateDescending,
+  stripMdxSyntax
+} from "./chunk-2WOYQBZW.js";
+export {
+  calculateReadTime,
+  sortByDateDescending,
+  stripMdxSyntax
+};

package/dist/node.cjs

@@ -0,0 +1,91 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/node.ts
+var node_exports = {};
+__export(node_exports, {
+  calculateReadTime: () => calculateReadTime,
+  getContentSlugs: () => getContentSlugs,
+  readMdxFile: () => readMdxFile,
+  sortByDateDescending: () => sortByDateDescending,
+  stripMdxSyntax: () => stripMdxSyntax
+});
+module.exports = __toCommonJS(node_exports);
+var import_promises = require("fs/promises");
+var import_path = __toESM(require("path"), 1);
+
+// src/index.ts
+var DEFAULT_WPM = 238;
+function stripMdxSyntax(content) {
+  return content.replace(/^export\s+const\s+\w+\s*=\s*[\s\S]*?^};?\s*$/gm, "").replace(/^import\s.*$/gm, "").replace(/```[\s\S]*?```/g, "").replace(/<[^>]+>/g, "").replace(/[#*`~\[\](){}|>]/g, "").replace(/\s+/g, " ").trim();
+}
+function calculateReadTime(content, options) {
+  const wpm = options?.wordsPerMinute ?? DEFAULT_WPM;
+  const text = stripMdxSyntax(content);
+  const words = text ? text.split(/\s+/).length : 0;
+  return {
+    minutes: Math.max(1, Math.ceil(words / wpm)),
+    words
+  };
+}
+function sortByDateDescending(items, getDate) {
+  return [...items].sort(
+    (a, b) => new Date(getDate(b)).getTime() - new Date(getDate(a)).getTime()
+  );
+}
+
+// src/node.ts
+var DEFAULT_EXTENSIONS = [".mdx"];
+async function getContentSlugs(dirPath, options) {
+  const extensions = options?.extensions ?? DEFAULT_EXTENSIONS;
+  const recursive = options?.recursive ?? false;
+  const dirents = await (0, import_promises.readdir)(dirPath, {
+    withFileTypes: true,
+    recursive
+  });
+  return dirents.filter(
+    (dirent) => !dirent.isDirectory() && extensions.some((ext) => dirent.name.endsWith(ext))
+  ).map((dirent) => {
+    const slug = dirent.name.substring(0, dirent.name.lastIndexOf("."));
+    if (!recursive || !dirent.parentPath) return slug;
+    const relativePath = import_path.default.relative(dirPath, dirent.parentPath);
+    return relativePath ? import_path.default.join(relativePath, slug) : slug;
+  });
+}
+async function readMdxFile(filePath) {
+  return (0, import_promises.readFile)(filePath, "utf-8");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  calculateReadTime,
+  getContentSlugs,
+  readMdxFile,
+  sortByDateDescending,
+  stripMdxSyntax
+});

package/dist/node.d.cts

@@ -0,0 +1,18 @@
+import { GetContentSlugsOptions } from './index.cjs';
+export { ReadTimeOptions, ReadTimeResult, TableOfContents, TableOfContentsEntry, calculateReadTime, sortByDateDescending, stripMdxSyntax } from './index.cjs';
+
+/**
+ * Get all content file slugs from a directory.
+ * Returns filenames without their extension.
+ *
+ * @param dirPath - Directory to scan
+ * @param options.extensions - File extensions to include (default: `[".mdx"]`)
+ * @param options.recursive - Recursively search subdirectories (default: `false`)
+ */
+declare function getContentSlugs(dirPath: string, options?: GetContentSlugsOptions): Promise<string[]>;
+/**
+ * Read the raw content of a file as a UTF-8 string.
+ */
+declare function readMdxFile(filePath: string): Promise<string>;
+
+export { GetContentSlugsOptions, getContentSlugs, readMdxFile };

package/dist/node.d.ts

@@ -0,0 +1,18 @@
+import { GetContentSlugsOptions } from './index.js';
+export { ReadTimeOptions, ReadTimeResult, TableOfContents, TableOfContentsEntry, calculateReadTime, sortByDateDescending, stripMdxSyntax } from './index.js';
+
+/**
+ * Get all content file slugs from a directory.
+ * Returns filenames without their extension.
+ *
+ * @param dirPath - Directory to scan
+ * @param options.extensions - File extensions to include (default: `[".mdx"]`)
+ * @param options.recursive - Recursively search subdirectories (default: `false`)
+ */
+declare function getContentSlugs(dirPath: string, options?: GetContentSlugsOptions): Promise<string[]>;
+/**
+ * Read the raw content of a file as a UTF-8 string.
+ */
+declare function readMdxFile(filePath: string): Promise<string>;
+
+export { GetContentSlugsOptions, getContentSlugs, readMdxFile };

package/dist/node.js

@@ -0,0 +1,36 @@
+import {
+  calculateReadTime,
+  sortByDateDescending,
+  stripMdxSyntax
+} from "./chunk-2WOYQBZW.js";
+
+// src/node.ts
+import { readdir, readFile } from "fs/promises";
+import path from "path";
+var DEFAULT_EXTENSIONS = [".mdx"];
+async function getContentSlugs(dirPath, options) {
+  const extensions = options?.extensions ?? DEFAULT_EXTENSIONS;
+  const recursive = options?.recursive ?? false;
+  const dirents = await readdir(dirPath, {
+    withFileTypes: true,
+    recursive
+  });
+  return dirents.filter(
+    (dirent) => !dirent.isDirectory() && extensions.some((ext) => dirent.name.endsWith(ext))
+  ).map((dirent) => {
+    const slug = dirent.name.substring(0, dirent.name.lastIndexOf("."));
+    if (!recursive || !dirent.parentPath) return slug;
+    const relativePath = path.relative(dirPath, dirent.parentPath);
+    return relativePath ? path.join(relativePath, slug) : slug;
+  });
+}
+async function readMdxFile(filePath) {
+  return readFile(filePath, "utf-8");
+}
+export {
+  calculateReadTime,
+  getContentSlugs,
+  readMdxFile,
+  sortByDateDescending,
+  stripMdxSyntax
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@bliztek/mdx-utils",
+  "version": "1.0.0",
+  "description": "Zero-dependency MDX content utilities for read time calculation and file discovery",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js",
+      "require": "./dist/node.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mdx",
+    "markdown",
+    "read-time",
+    "reading-time",
+    "blog",
+    "utilities",
+    "content"
+  ],
+  "author": "Bliztek, LLC",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bliztek/mdx-utils.git"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.3",
+    "tsup": "^8.4.0",
+    "typescript": "^5.9.3"
+  }
+}