@holdenmatt/md-schema 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Holden
+
+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,75 @@
+# md-schema
+
+Typed frontmatter schemas for markdown documents.
+
+`@holdenmatt/md-schema` parses YAML frontmatter with `gray-matter` and validates it with a Zod object schema. The markdown body is returned as trimmed markdown text.
+
+## Install
+
+```sh
+npm add @holdenmatt/md-schema zod
+```
+
+## Usage
+
+```ts
+import { z } from "zod";
+import { markdownSchema } from "@holdenmatt/md-schema";
+
+const postSchema = markdownSchema(
+  z.object({
+    title: z.string(),
+    draft: z.boolean().default(false),
+    slug: z.string().transform((value) => value.toLowerCase()),
+  }),
+);
+
+const result = postSchema.parse(`---
+title: Hello
+slug: Hello-World
+---
+
+# Hello
+`);
+
+if (result.success) {
+  result.data.frontmatter.title;
+  result.data.body;
+  result.data.markdown;
+}
+```
+
+## API
+
+### `markdownSchema(frontmatterSchema)`
+
+Creates a parser for markdown documents with YAML frontmatter.
+
+- `frontmatterSchema`: a Zod object schema used to validate parsed frontmatter.
+- Returns `{ schema, parse }`.
+- `schema` is the original Zod schema.
+- `parse(markdown)` returns a safe result object and does not throw for YAML parse or Zod validation failures.
+
+Success:
+
+```ts
+{
+  success: true,
+  data: {
+    frontmatter,
+    body,
+    markdown,
+  },
+}
+```
+
+Failure:
+
+```ts
+{
+  success: false,
+  error,
+}
+```
+
+Only frontmatter is validated. The body is not parsed and is returned as trimmed markdown text.

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+import type * as z from "zod";
+/** A Zod object schema used to validate parsed YAML frontmatter. */
+export type FrontmatterSchema = z.ZodObject;
+/**
+ * Parsed markdown data returned after frontmatter validation succeeds.
+ */
+export type MarkdownSchemaData<Schema extends FrontmatterSchema> = {
+    /** Frontmatter after Zod validation. */
+    frontmatter: z.output<Schema>;
+    /** Markdown content after frontmatter, trimmed at both ends. */
+    body: string;
+    /** Original markdown input string, preserved exactly. */
+    markdown: string;
+};
+/**
+ * Safe parse result for a markdown document with typed frontmatter.
+ */
+export type MarkdownSchemaResult<Schema extends FrontmatterSchema> = {
+    success: true;
+    data: MarkdownSchemaData<Schema>;
+} | {
+    success: false;
+    error: unknown;
+};
+/**
+ * A reusable parser for markdown documents with a specific frontmatter schema.
+ */
+export type MarkdownSchema<Schema extends FrontmatterSchema> = {
+    /** Frontmatter schema used by this parser. */
+    schema: Schema;
+    /** Parse markdown text into typed frontmatter and a trimmed body. */
+    parse(markdown: string): MarkdownSchemaResult<Schema>;
+};
+/**
+ * Create a parser for markdown documents with YAML frontmatter validated by a Zod object schema.
+ *
+ * YAML parse failures and Zod validation failures are returned as safe `{ success: false }` results.
+ */
+export declare function markdownSchema<Schema extends FrontmatterSchema>(frontmatterSchema: Schema): MarkdownSchema<Schema>;

package/dist/index.js

@@ -0,0 +1,37 @@
+import matter from "gray-matter";
+/**
+ * Create a parser for markdown documents with YAML frontmatter validated by a Zod object schema.
+ *
+ * YAML parse failures and Zod validation failures are returned as safe `{ success: false }` results.
+ */
+export function markdownSchema(frontmatterSchema) {
+    return {
+        schema: frontmatterSchema,
+        parse(markdown) {
+            let file;
+            try {
+                file = matter(markdown);
+            }
+            catch (error) {
+                return { success: false, error };
+            }
+            try {
+                const result = frontmatterSchema.safeParse(file.data);
+                if (!result.success) {
+                    return { success: false, error: result.error };
+                }
+                return {
+                    success: true,
+                    data: {
+                        frontmatter: result.data,
+                        body: file.content.trim(),
+                        markdown,
+                    },
+                };
+            }
+            catch (error) {
+                return { success: false, error };
+            }
+        },
+    };
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@holdenmatt/md-schema",
+  "version": "0.1.0",
+  "description": "Typed frontmatter schemas for markdown documents",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/holdenmatt/md-schema.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepare": "tsc",
+    "test": "vitest run",
+    "lint": "oxlint",
+    "format": "oxfmt --write .",
+    "format:check": "oxfmt --check .",
+    "check": "pnpm format:check && pnpm lint && pnpm test && pnpm build"
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.1",
+    "oxfmt": "^0.56.0",
+    "oxlint": "^1.71.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "packageManager": "pnpm@10.33.0"
+}