quill-matter 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Quill
+
+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,175 @@
+# Quill Matter
+
+A TypeScript library for parsing YAML, JSON, and TOML front matter from Markdown files — powered by a Rust WASM core.
+
+Supports **Bun** ≥ 1.0 and **Deno** ≥ 2.0.
+
+## Features
+
+- **YAML / JSON / TOML** — Auto-detects format from delimiters and content
+- **Rust WASM core** — High-performance parsing via WebAssembly
+- **File Helpers** — `readFrontMatter()` reads local files (Bun/Deno) or fetches URLs
+- **Type-safe** — Discriminated unions force correct error handling
+- **Schema validation** — Optional [Valibot](https://valibot.dev) integration
+- **Sync + Async** — `parseFrontMatter()` and `parseFrontMatterSync()` APIs
+- **Stringify** — Convert data back to front matter Markdown
+- **CLI** — Parse, extract, detect, and validate from the command line
+
+## Installation
+
+```bash
+# Bun
+bun add quill-matter
+
+# Deno
+deno add jsr:@quill/quill-matter
+```
+
+## Quick Start
+
+```typescript
+// Bun
+import { readFrontMatter } from "quill-matter";
+
+// Deno
+import { readFrontMatter } from "@quill/quill-matter";
+
+// Works in Bun and Deno
+const result = await readFrontMatter("post.md");
+
+if (result.isEmpty) {
+  console.log("No front matter found");
+} else if (result.error) {
+  console.error("Parse failed:", result.error.message);
+} else {
+  // Safe to access data after checks
+  console.log(result.data.title);
+  console.log(result.content);
+}
+```
+
+## Usage
+
+### Reading Files & URLs
+
+The `readFrontMatter` helper abstracts away runtime differences.
+
+```typescript
+import { readFrontMatter } from "quill-matter";
+
+// Local file (Bun / Deno)
+const post = await readFrontMatter("./content/post.md");
+
+// Remote URL (Fetch)
+const remote = await readFrontMatter("https://example.com/post.md");
+```
+
+### Manual Parsing
+
+If you already have the string content:
+
+```typescript
+import { parseFrontMatter } from "quill-matter";
+
+const result = await parseFrontMatter(`---
+title: Hello World
+tags:
+  - typescript
+  - rust
+---
+# My Blog Post`);
+
+if (!result.isEmpty && !result.error) {
+  console.log(result.data.title); // "Hello World"
+}
+```
+
+### Type Safety (`ParseResult` Union)
+
+The return type `ParseResult<T>` is a discriminated union. You **must** narrow the type by checking `isEmpty` and `error` before accessing `data`.
+
+```typescript
+const result = await parseFrontMatter<PostMeta>(source);
+
+// ❌ Error: Property 'title' does not exist (could be empty or error)
+console.log(result.data.title);
+
+// ✅ Correct usage
+if (!result.isEmpty && !result.error) {
+  console.log(result.data.title); // typed as PostMeta
+}
+```
+
+### Schema Validation
+
+```typescript
+import * as v from "valibot";
+
+const result = await parseFrontMatter(source, {
+  schema: v.object({
+    title: v.string(),
+    draft: v.optional(v.boolean(), false),
+  }),
+});
+// result.data is typed & validated
+```
+
+### Synchronous API
+
+```typescript
+import { initWasm, parseFrontMatterSync } from "quill-matter";
+
+await initWasm(); // call once at startup
+const result = parseFrontMatterSync(source);
+```
+
+### CLI
+
+The CLI is runtime-agnostic and works with `bun` or `deno`.
+
+```bash
+# Parse to JSON
+quill-matter parse post.md --pretty
+
+# Detect format
+quill-matter detect post.md
+
+# Validate against schema (requires custom script, CLI only validates syntax)
+quill-matter validate post.md
+```
+
+## API Reference
+
+| Function | Description |
+|----------|-------------|
+| `readFrontMatter(path, options?)` | Read file/URL and parse front matter. |
+| `readFrontMatterMany(paths, options?)` | Read multiple files/URLs in parallel. |
+| `parseFrontMatter(source, options?)` | Async parse string. Lazily loads WASM. |
+| `parseFrontMatterSync(source, options?)` | Sync parse string. Requires `initWasm()`. |
+| `hasFrontMatter(source, delimiters?)` | Zero-cost check (no WASM). |
+| `stringifyFrontMatter(data, content)` | Async stringify to Markdown. |
+| `extractFrontMatter(source)` | Extract raw front matter block. |
+
+### `ParseOptions`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `schema` | `GenericSchema` | — | Valibot schema for validation |
+| `format` | `"yaml" \| "json" \| "toml"` | auto | Override auto-detection |
+| `strict` | `boolean` | `true` | Set `false` to return errors instead of throwing |
+| `excerpt` | `boolean \| ExcerptOptions` | `false` | Extract excerpt from content |
+
+## Security
+
+- **Prototype Pollution** — `__proto__`, `prototype` keys are stripped.
+- **Input Size** — Max 1MB input enforced.
+- **Error Leakage** — Internal paths/stack traces are sanitized in non-strict mode.
+
+## Development
+
+```bash
+bun install
+bun run build:wasm
+bun run test      # Run tests (Vitest)
+bun run test:deno # Run Deno tests
+```

package/cli/index.ts

@@ -0,0 +1,214 @@
+#!/usr/bin/env bun
+
+import { detectFormat, extractFrontMatter, initWasm, parseFrontMatterSync } from "../src/index.js";
+import type { DelimiterPair, FrontMatterFormat } from "../src/types.js";
+
+// ---------------------------------------------------------------------------
+// Runtime detection & Polyfills
+// ---------------------------------------------------------------------------
+
+declare const Bun: { argv: string[]; file(path: string): { text(): Promise<string> } } | undefined;
+declare const Deno:
+  | { args: string[]; readTextFile(path: string): Promise<string>; exit(code?: number): never }
+  | undefined;
+
+function getArgs(): string[] {
+  if (typeof Bun !== "undefined") return Bun.argv.slice(2);
+  if (typeof Deno !== "undefined") return Deno.args;
+  throw new Error("Unsupported runtime — use Bun or Deno.");
+}
+
+function exit(code = 0): never {
+  if (typeof Deno !== "undefined") Deno.exit(code);
+  process.exit(code); // Bun supports process.exit
+}
+
+// ---------------------------------------------------------------------------
+// Args Parser (Minimal — no external dependencies)
+// ---------------------------------------------------------------------------
+
+interface ParsedArgs {
+  values: {
+    help?: boolean;
+    format?: string;
+    json?: boolean;
+    pretty?: boolean;
+    delimiter?: string;
+  };
+  positionals: string[];
+}
+
+function parseCliArgs(args: string[]): ParsedArgs {
+  const values: ParsedArgs["values"] = {};
+  const positionals: string[] = [];
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === "-h" || arg === "--help") {
+      values.help = true;
+    } else if (arg === "-f" || arg === "--format") {
+      values.format = args[++i];
+    } else if (arg === "-j" || arg === "--json") {
+      values.json = true;
+    } else if (arg === "-p" || arg === "--pretty") {
+      values.pretty = true;
+    } else if (arg === "-d" || arg === "--delimiter") {
+      values.delimiter = args[++i];
+    } else if (arg.startsWith("-")) {
+      die(`unknown option: ${arg}`);
+    } else {
+      positionals.push(arg);
+    }
+  }
+  return { values, positionals };
+}
+
+// ---------------------------------------------------------------------------
+// Help
+// ---------------------------------------------------------------------------
+
+const HELP = `
+quill-matter — Parse YAML, JSON, and TOML front matter from Markdown files
+
+Usage:
+  quill-matter <command> <file> [options]
+
+Commands:
+  parse      Parse front matter and output as JSON
+  extract    Output raw extracted front matter (unparsed)
+  detect     Detect and print the front matter format
+  validate   Parse and validate front matter (exits 1 on error)
+
+Options:
+  -f, --format <fmt>       Force format: yaml | json | toml
+  -d, --delimiter <delim>  Custom delimiter (e.g. "~~~" or "<!--,-->")
+  -j, --json               Output as compact JSON (default)
+  -p, --pretty             Pretty-print JSON output
+  -h, --help               Show this help message
+
+Examples:
+  quill-matter parse README.md
+  quill-matter parse README.md --pretty
+  quill-matter detect post.md
+  quill-matter extract post.mdx -d "~~~"
+  quill-matter parse post.md -f toml
+`.trim();
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function die(message: string, code = 1): never {
+  console.error(`error: ${message}`);
+  exit(code);
+}
+
+async function readInput(path?: string): Promise<string> {
+  if (!path) die("no file specified — run with --help for usage");
+
+  try {
+    if (typeof Bun !== "undefined") {
+      // Bun.file() handles absolute/relative paths automatically
+      const file = Bun.file(path);
+      try {
+        return await file.text();
+      } catch {
+        throw new Error("File not found");
+      }
+    }
+    if (typeof Deno !== "undefined") {
+      return await Deno.readTextFile(path);
+    }
+  } catch {
+    die(`could not read file: ${path}`);
+  }
+  throw new Error("Unsupported runtime");
+}
+
+function parseDelimiter(raw?: string): DelimiterPair[] | undefined {
+  if (!raw) return undefined;
+  if (raw.includes(",")) {
+    const [open, close] = raw.split(",", 2);
+    return [{ open: open.trim(), close: close.trim() }];
+  }
+  return [{ open: raw, close: raw }];
+}
+
+function output(data: unknown, pretty?: boolean): void {
+  console.log(pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data));
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const args = getArgs();
+  const { values, positionals } = parseCliArgs(args);
+
+  if (values.help || positionals.length === 0) {
+    console.log(HELP);
+    exit(0);
+  }
+
+  const [command, filePath] = positionals;
+  const source = await readInput(filePath);
+  const delimiters = parseDelimiter(values.delimiter);
+  const VALID_FORMATS = ["yaml", "json", "toml"];
+  const format: FrontMatterFormat | undefined = values.format
+    ? VALID_FORMATS.includes(values.format)
+      ? (values.format as FrontMatterFormat)
+      : die(`invalid format: "${values.format}"`)
+    : undefined;
+
+  switch (command) {
+    case "parse": {
+      await initWasm();
+      const result = parseFrontMatterSync(source, { format, delimiters });
+      output(
+        {
+          data: result.data,
+          format: result.format,
+          isEmpty: result.isEmpty,
+        },
+        values.pretty,
+      );
+      break;
+    }
+
+    case "extract": {
+      const extraction = extractFrontMatter(source, delimiters);
+      if (!extraction) die("no front matter found");
+      console.log(extraction.rawData);
+      break;
+    }
+
+    case "detect": {
+      const extraction = extractFrontMatter(source, delimiters);
+      if (!extraction) die("no front matter found");
+      const detected = format ?? detectFormat(extraction.rawData, extraction.delimiter);
+      console.log(detected);
+      break;
+    }
+
+    case "validate": {
+      await initWasm();
+      try {
+        const result = parseFrontMatterSync(source, { format, delimiters });
+        output({ valid: true, format: result.format, data: result.data }, values.pretty);
+      } catch (err) {
+        output({ valid: false, error: String(err) }, values.pretty);
+        exit(1);
+      }
+      break;
+    }
+
+    default:
+      die(`unknown command: ${command}`);
+  }
+}
+
+main().catch((err) => {
+  die(String(err));
+});

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "quill-matter",
+  "version": "0.1.0",
+  "description": "Parse YAML, JSON, and TOML front matter from Markdown files — powered by Rust WASM",
+  "type": "module",
+  "bin": {
+    "quill-matter": "./cli/index.ts"
+  },
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "deno": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./extractor": {
+      "bun": "./src/extractor.ts",
+      "deno": "./src/extractor.ts",
+      "default": "./src/extractor.ts"
+    },
+    "./detector": {
+      "bun": "./src/detector.ts",
+      "deno": "./src/detector.ts",
+      "default": "./src/detector.ts"
+    },
+    "./validator": {
+      "bun": "./src/validator.ts",
+      "deno": "./src/validator.ts",
+      "default": "./src/validator.ts"
+    }
+  },
+  "files": [
+    "src/",
+    "pkg/",
+    "cli/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.0",
+    "deno": ">=2.0"
+  },
+  "scripts": {
+    "build:wasm": "wasm-pack build crates/parser-wasm --target bundler --out-dir ../../pkg --release",
+    "test": "vitest run",
+    "test:deno": "deno test --allow-read --allow-write tests/deno.test.ts",
+    "test:watch": "vitest",
+    "bench": "vitest bench",
+    "lint": "biome check .",
+    "format": "biome format --write .",
+    "clean": "rimraf crates/parser-wasm/target pkg",
+    "clean:all": "rimraf crates/parser-wasm/target pkg node_modules"
+  },
+  "keywords": [
+    "markdown",
+    "frontmatter",
+    "front-matter",
+    "yaml",
+    "json",
+    "toml",
+    "wasm",
+    "parser"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/murelux/quill-matter.git"
+  },
+  "homepage": "https://github.com/murelux/quill-matter#readme",
+  "bugs": {
+    "url": "https://github.com/murelux/quill-matter/issues"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.0",
+    "@types/bun": "^1.3.9",
+    "rimraf": "^6.1.2",
+    "tinybench": "^3.0.0",
+    "valibot": "^1.0.0",
+    "vite-plugin-wasm": "^3.5.0",
+    "vitest": "^4.0.0",
+    "wasm-pack": "^0.14.0"
+  },
+  "peerDependencies": {
+    "valibot": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "valibot": {
+      "optional": true
+    }
+  }
+}

package/src/detector.ts

@@ -0,0 +1,53 @@
+import type { DelimiterPair, FrontMatterFormat } from "./types.js";
+
+/** @internal Result of format detection that may include pre-parsed JSON data. */
+export interface DetectionResult {
+  format: FrontMatterFormat;
+  /** Pre-parsed JSON data, present only when format is "json". Avoids double parsing. */
+  preparsedData?: unknown;
+}
+
+/**
+ * Detect the front matter format from the raw content and delimiter pair.
+ *
+ * -  `+++` delimiters → TOML
+ * -  Content starts with `{` → JSON
+ * -  Anything else → YAML (default)
+ */
+export function detectFormat(rawData: string, delimiter: DelimiterPair): FrontMatterFormat {
+  return detectFormatWithPreparsed(rawData, delimiter).format;
+}
+
+/**
+ * Detect the format and optionally return pre-parsed JSON data.
+ *
+ * Used internally by the main pipeline so JSON front matter is only
+ * parsed once (by the native `JSON.parse`) rather than being parsed
+ * again through the WASM layer.
+ *
+ * @internal
+ */
+export function detectFormatWithPreparsed(
+  rawData: string,
+  delimiter: DelimiterPair,
+): DetectionResult {
+  // TOML uses +++ delimiters by convention.
+  if (delimiter.open === "+++") {
+    return { format: "toml" };
+  }
+
+  // JSON detection: content starts with `{` or `[` and is valid JSON.
+  // A simple `startsWith("{")` heuristic would misidentify YAML flow
+  // mappings (e.g. `{key: value}`) as JSON, so we probe with JSON.parse.
+  const trimmed = rawData.trimStart();
+  if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+    try {
+      const preparsedData = JSON.parse(trimmed);
+      return { format: "json", preparsedData };
+    } catch {
+      // Not valid JSON — fall through to YAML default.
+    }
+  }
+
+  return { format: "yaml" };
+}

package/src/excerpt.ts

@@ -0,0 +1,63 @@
+import type { ExcerptOptions } from "./types.js";
+
+/** Default excerpt separator. */
+const DEFAULT_SEPARATOR = "<!-- more -->";
+
+/**
+ * Extract an excerpt from markdown content.
+ *
+ * If the separator is found, returns everything before it.
+ * Otherwise, returns the first paragraph.
+ *
+ * @param content - The markdown content (after front matter).
+ * @param options - Excerpt extraction options.
+ * @returns The extracted excerpt, or undefined if content is empty.
+ */
+export function extractExcerpt(
+  content: string,
+  options?: ExcerptOptions | boolean,
+): string | undefined {
+  if (!content || content.trim().length === 0) {
+    return undefined;
+  }
+
+  const separator =
+    typeof options === "object" && options.separator ? options.separator : DEFAULT_SEPARATOR;
+
+  const trimmed = content.trim();
+
+  // Try to find the separator
+  const separatorIndex = trimmed.indexOf(separator);
+  if (separatorIndex !== -1) {
+    const excerpt = trimmed.slice(0, separatorIndex).trim();
+    return excerpt.length > 0 ? excerpt : undefined;
+  }
+
+  // Fallback: extract first paragraph
+  // A paragraph is text separated by blank lines
+  const paragraphs = trimmed.split(/\n\s*\n/);
+  const firstParagraph = paragraphs[0]?.trim();
+
+  // Skip if first "paragraph" is a heading alone
+  if (firstParagraph && !isHeadingOnly(firstParagraph)) {
+    return firstParagraph;
+  }
+
+  // If first is heading, try second paragraph
+  if (paragraphs.length > 1) {
+    const secondParagraph = paragraphs[1]?.trim();
+    if (secondParagraph && !isHeadingOnly(secondParagraph)) {
+      return secondParagraph;
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Check if text is only a markdown heading.
+ */
+function isHeadingOnly(text: string): boolean {
+  const lines = text.split("\n").filter((line) => line.trim().length > 0);
+  return lines.length === 1 && /^#{1,6}\s+/.test(lines[0]);
+}