quill-matter 0.1.0

package/src/sanitizer.ts

@@ -0,0 +1,50 @@
+/**
+ * Sanitize parsed objects by stripping keys that could trigger
+ * **prototype pollution** when the consumer merges or spreads the data
+ * into other objects.
+ *
+ * Targets: `__proto__`, `prototype`.
+ *
+ * Note: `constructor` is intentionally NOT stripped because it is a
+ * legitimate data key (e.g. `constructor: "Builder Pattern"`).  The
+ * `constructor.prototype.x` attack chain is already neutralised by
+ * stripping `prototype`.
+ *
+ * @param obj - The parsed value (object, array, or primitive).
+ * @returns A deep clone with dangerous keys removed.
+ */
+
+const DANGEROUS_KEYS = new Set(["__proto__", "prototype"]);
+
+/**
+ * Check if an object tree contains any dangerous keys.
+ * Returns `true` if no sanitization is needed (fast path).
+ */
+function isSafe(obj: unknown): boolean {
+  if (obj === null || typeof obj !== "object") return true;
+  if (Array.isArray(obj)) return obj.every(isSafe);
+  for (const key of Object.keys(obj as Record<string, unknown>)) {
+    if (DANGEROUS_KEYS.has(key)) return false;
+  }
+  return Object.values(obj as Record<string, unknown>).every(isSafe);
+}
+
+export function sanitizeKeys(obj: unknown): unknown {
+  if (obj === null || typeof obj !== "object") return obj;
+  // Fast path: skip deep clone if no dangerous keys exist.
+  if (isSafe(obj)) return obj;
+  return sanitizeDeep(obj);
+}
+
+function sanitizeDeep(obj: unknown): unknown {
+  if (obj === null || typeof obj !== "object") return obj;
+  if (Array.isArray(obj)) return obj.map(sanitizeDeep);
+
+  const clean: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {
+    if (!DANGEROUS_KEYS.has(key)) {
+      clean[key] = sanitizeDeep(value);
+    }
+  }
+  return clean;
+}

package/src/stringify.ts

@@ -0,0 +1,151 @@
+import type { DelimiterPair, FrontMatterFormat, StringifyOptions } from "./types.js";
+import { FrontMatterError } from "./types.js";
+import type { WasmParsers } from "./wasm-loader.js";
+import { getWasmParsers, getWasmParsersSync } from "./wasm-loader.js";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const FORMAT_DELIMITERS: Record<FrontMatterFormat, DelimiterPair> = {
+  yaml: { open: "---", close: "---" },
+  json: { open: "---", close: "---" },
+  toml: { open: "+++", close: "+++" },
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Stringify data and content into a Markdown string with front matter.
+ *
+ * @param data - The front matter data object.
+ * @param content - The Markdown content (without front matter).
+ * @param options - Stringify options (format, delimiter).
+ * @returns A complete Markdown string with front matter.
+ *
+ * @example
+ * ```ts
+ * import { stringifyFrontMatter } from "quill-matter";
+ *
+ * const markdown = await stringifyFrontMatter(
+ *   { title: "Hello", tags: ["a", "b"] },
+ *   "# Content here"
+ * );
+ * // ---
+ * // title: Hello
+ * // tags:
+ * //   - a
+ * //   - b
+ * // ---
+ * // # Content here
+ * ```
+ */
+export async function stringifyFrontMatter(
+  data: Record<string, unknown>,
+  content: string,
+  options?: StringifyOptions,
+): Promise<string> {
+  // Skip front matter block entirely when data is empty.
+  if (data === null || typeof data !== "object" || Array.isArray(data)) {
+    throw new FrontMatterError(
+      `Expected a plain object for front matter data, got ${Array.isArray(data) ? "array" : typeof data}`,
+    );
+  }
+  if (Object.keys(data).length === 0) {
+    return content;
+  }
+
+  const format = options?.format ?? "yaml";
+  const delimiter = options?.delimiter ?? FORMAT_DELIMITERS[format];
+
+  const wasm = await getWasmParsers();
+  const serialized = stringifyData(wasm, data, format);
+
+  return assembleMarkdown(serialized, content, delimiter);
+}
+
+/**
+ * Stringify data and content synchronously.
+ *
+ * **Requires** `await initWasm()` to have been called first.
+ *
+ * @throws {Error} if WASM module is not initialized.
+ */
+export function stringifyFrontMatterSync(
+  data: Record<string, unknown>,
+  content: string,
+  options?: StringifyOptions,
+): string {
+  // Skip front matter block entirely when data is empty.
+  if (data === null || typeof data !== "object" || Array.isArray(data)) {
+    throw new FrontMatterError(
+      `Expected a plain object for front matter data, got ${Array.isArray(data) ? "array" : typeof data}`,
+    );
+  }
+  if (Object.keys(data).length === 0) {
+    return content;
+  }
+
+  const format = options?.format ?? "yaml";
+  const delimiter = options?.delimiter ?? FORMAT_DELIMITERS[format];
+
+  const wasm = getWasmParsersSync();
+  const serialized = stringifyData(wasm, data, format);
+
+  return assembleMarkdown(serialized, content, delimiter);
+}
+
+// ---------------------------------------------------------------------------
+// Internal
+// ---------------------------------------------------------------------------
+
+/** Maximum allowed output size in bytes (1 MB), consistent with parse limits. */
+const MAX_OUTPUT_SIZE = 1_048_576;
+
+const encoder = new TextEncoder();
+
+function stringifyData(
+  wasm: WasmParsers,
+  data: Record<string, unknown>,
+  format: FrontMatterFormat,
+): string {
+  let result: string;
+  switch (format) {
+    case "yaml":
+      result = wasm.stringify_yaml(data);
+      break;
+    case "json":
+      result = wasm.stringify_json(data);
+      break;
+    case "toml":
+      result = wasm.stringify_toml(data);
+      break;
+    default:
+      throw new FrontMatterError(`Unknown format: ${format}`);
+  }
+
+  // Guard against unbounded output — mirrors the parse-side 1 MB byte limit.
+  const size = encoder.encode(result).byteLength;
+  if (size > MAX_OUTPUT_SIZE) {
+    throw new FrontMatterError(
+      `Serialized front matter too large: ${size} bytes (max: ${MAX_OUTPUT_SIZE})`,
+    );
+  }
+
+  return result;
+}
+
+function assembleMarkdown(frontMatter: string, content: string, delimiter: DelimiterPair): string {
+  const trimmedFM = frontMatter.trim();
+
+  // Build the final markdown — preserve original content whitespace.
+  const parts = [delimiter.open, trimmedFM, delimiter.close];
+
+  if (content.length > 0) {
+    parts.push(content);
+  }
+
+  return `${parts.join("\n")}\n`;
+}

package/src/types.ts

@@ -0,0 +1,166 @@
+/** Supported front matter formats. */
+export type FrontMatterFormat = "yaml" | "json" | "toml";
+
+/** A pair of opening/closing delimiters. */
+export interface DelimiterPair {
+  open: string;
+  close: string;
+}
+
+/** Built-in delimiters. */
+export const DEFAULT_DELIMITERS: readonly DelimiterPair[] = [
+  { open: "---", close: "---" },
+  { open: "---", close: "..." },
+  { open: "+++", close: "+++" },
+] as const;
+
+/** Options for excerpt extraction. */
+export interface ExcerptOptions {
+  /** Separator string to look for. @default "<!-- more -->" */
+  separator?: string;
+}
+
+/**
+ * Result returned by the main `parseFrontMatter` function.
+ *
+ * This is a **discriminated union** — narrow on `isEmpty` or `error`
+ * before accessing typed `data` to avoid runtime errors.
+ *
+ * @example
+ * ```ts
+ * const result = await parseFrontMatter<PostMeta>(source);
+ * if (!result.isEmpty && !result.error) {
+ *   console.log(result.data.title); // ✅ safely typed as PostMeta
+ * }
+ * ```
+ */
+export type ParseResult<T = Record<string, unknown>> =
+  | ParseResultSuccess<T>
+  | ParseResultEmpty
+  | ParseResultError;
+
+/** Successful parse — `data` is fully typed as `T`. */
+export interface ParseResultSuccess<T = Record<string, unknown>> {
+  /** Parsed front matter data. */
+  data: T;
+  /** Markdown content after the front matter block. */
+  content: string;
+  /** Detected (or overridden) format of the front matter. */
+  format: FrontMatterFormat;
+  /** Whether the front matter block was empty / absent. */
+  isEmpty: false;
+  /** Never present on success. */
+  error?: undefined;
+  /** Extracted excerpt (when `excerpt` option is enabled). */
+  excerpt?: string;
+  /** Raw (unparsed) front matter text between delimiters. */
+  rawData: string;
+}
+
+/** Empty or absent front matter — `data` is `{}`. */
+export interface ParseResultEmpty {
+  /** Empty object — no front matter data was found. */
+  data: Record<string, never>;
+  /** The full source content (no front matter to strip). */
+  content: string;
+  /** Default or overridden format. */
+  format: FrontMatterFormat;
+  /** Always `true` when front matter is empty or absent. */
+  isEmpty: true;
+  /** Never present on empty result. */
+  error?: undefined;
+  /** Extracted excerpt (when `excerpt` option is enabled). */
+  excerpt?: string;
+  /** Absent when isEmpty is true. */
+  rawData?: undefined;
+}
+
+/** Parse error (when `strict: false`) — `data` is `{}`. */
+export interface ParseResultError {
+  /** Empty object — parse failed. */
+  data: Record<string, never>;
+  /** Markdown content after the front matter block. */
+  content: string;
+  /** Detected (or overridden) format. */
+  format: FrontMatterFormat;
+  /** Always `false` — front matter was present but parsing failed. */
+  isEmpty: false;
+  /** The parse error. */
+  error: FrontMatterError;
+  /** Extracted excerpt (when `excerpt` option is enabled). */
+  excerpt?: string;
+  /** Raw (unparsed) front matter text between delimiters. */
+  rawData: string;
+}
+
+/** Intermediate result from the extraction step — before parsing. */
+export interface ExtractionResult {
+  /** Raw text between the delimiters (unparsed). */
+  rawData: string;
+  /** Markdown body after the closing delimiter. */
+  content: string;
+  /** Delimiter pair used. */
+  delimiter: DelimiterPair;
+}
+
+/** Adapter interface every parser must implement. */
+export interface ParserAdapter {
+  /** Parse a raw front matter string into a JS object. */
+  parse(input: string): unknown;
+}
+
+/** Options for `stringifyFrontMatter`. */
+export interface StringifyOptions {
+  /** Output format. @default "yaml" */
+  format?: FrontMatterFormat;
+  /** Custom delimiter pair. Defaults based on format: `---` for yaml/json, `+++` for toml. */
+  delimiter?: DelimiterPair;
+}
+
+// ---------------------------------------------------------------------------
+// Error classes
+// ---------------------------------------------------------------------------
+
+/** Base error for all quill-matter errors. */
+export class FrontMatterError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "FrontMatterError";
+  }
+}
+
+/** Thrown when the front matter block cannot be extracted (e.g. unclosed delimiter). */
+export class ExtractionError extends FrontMatterError {
+  constructor(message: string) {
+    super(message);
+    this.name = "ExtractionError";
+  }
+}
+
+/** Thrown when the raw data fails to parse in the detected format. */
+export class ParseError extends FrontMatterError {
+  public readonly format: FrontMatterFormat;
+  /** Line number where the error occurred (1-based), if available. */
+  public readonly line?: number;
+  /** Column number where the error occurred (1-based), if available. */
+  public readonly column?: number;
+
+  constructor(message: string, format: FrontMatterFormat, line?: number, column?: number) {
+    super(message);
+    this.name = "ParseError";
+    this.format = format;
+    this.line = line;
+    this.column = column;
+  }
+}
+
+/** Thrown when Valibot schema validation fails. */
+export class ValidationError extends FrontMatterError {
+  public readonly issues: unknown[];
+
+  constructor(message: string, issues: unknown[]) {
+    super(message);
+    this.name = "ValidationError";
+    this.issues = issues;
+  }
+}

package/src/validator.ts

@@ -0,0 +1,28 @@
+import * as v from "valibot";
+import { ValidationError } from "./types.js";
+
+/**
+ * Validate `data` against a Valibot schema.
+ *
+ * @param data  - The parsed front matter object.
+ * @param schema - A Valibot `GenericSchema` to validate against.
+ * @returns The validated (and potentially transformed) data.
+ * @throws {ValidationError} if validation fails.
+ */
+export function validate<T>(data: unknown, schema: v.GenericSchema<unknown, T>): T {
+  const result = v.safeParse(schema, data);
+
+  if (result.success) {
+    return result.output;
+  }
+
+  const issues = result.issues.map((issue) => ({
+    message: issue.message,
+    path: issue.path?.map((p) => p.key).join("."),
+  }));
+
+  throw new ValidationError(
+    `Front matter validation failed: ${issues.map((i) => i.message).join("; ")}`,
+    issues,
+  );
+}

package/src/wasm-loader.ts

@@ -0,0 +1,166 @@
+/**
+ * Lazy WASM module loader.
+ *
+ * Supports two loading modes:
+ *  1. **Bundler** (Vitest, Vite, Cloudflare Workers) — `import("../pkg/quill_matter_wasm.js")`
+ *  2. **Direct** (Bun, Deno) — manually instantiate the WASM binary
+ *
+ * The module is loaded once and cached for subsequent calls.
+ *
+ * No `node:*` imports — uses only web-standard APIs (`URL`, `fetch`)
+ * and runtime-specific file APIs (`Deno.readFile`, `Bun.file`).
+ */
+
+// Type declarations for runtime-specific globals
+declare const Deno:
+  | {
+      readFile(path: string | URL): Promise<Uint8Array>;
+    }
+  | undefined;
+
+declare const Bun:
+  | {
+      file(path: string | URL): { arrayBuffer(): Promise<ArrayBuffer> };
+    }
+  | undefined;
+
+// biome-ignore lint/suspicious/noExplicitAny: WASM module shape is dynamic
+let wasmModule: any | null = null;
+let initPromise: Promise<WasmParsers> | null = null;
+
+export interface WasmParsers {
+  parse_yaml(input: string): unknown;
+  parse_json(input: string): unknown;
+  parse_toml(input: string): unknown;
+  stringify_yaml(value: unknown): string;
+  stringify_json(value: unknown): string;
+  stringify_toml(value: unknown): string;
+}
+
+/**
+ * Initialise and return the WASM parser module (async).
+ *
+ * The module is loaded lazily on first call and cached thereafter.
+ * Concurrent calls are deduplicated via a shared promise.
+ */
+export async function getWasmParsers(): Promise<WasmParsers> {
+  if (wasmModule) {
+    return wasmModule as WasmParsers;
+  }
+
+  if (initPromise) {
+    return initPromise;
+  }
+
+  initPromise = loadWasm().catch((err) => {
+    initPromise = null; // allow retry on next call
+    throw new Error("Failed to load WASM module", { cause: err });
+  });
+
+  return initPromise;
+}
+
+/**
+ * Return the cached WASM module synchronously.
+ *
+ * @throws {Error} if `initWasm()` has not been called yet.
+ */
+export function getWasmParsersSync(): WasmParsers {
+  if (!wasmModule) {
+    throw new Error(
+      "WASM not initialized — call `await initWasm()` before using synchronous APIs.",
+    );
+  }
+  return wasmModule as WasmParsers;
+}
+
+/**
+ * Eagerly pre-initialise the WASM module so the first `parseFrontMatter()`
+ * call does not pay the loading cost.
+ *
+ * Calling this is **optional** for the async API but **required** before
+ * using `parseFrontMatterSync()`.
+ *
+ * ```ts
+ * import { initWasm } from "quill-matter";
+ * await initWasm();
+ * ```
+ */
+export async function initWasm(): Promise<void> {
+  await getWasmParsers();
+}
+
+/**
+ * Reset the cached module — useful for testing.
+ * @internal
+ */
+export function _resetWasmCache(): void {
+  wasmModule = null;
+  initPromise = null;
+}
+
+// ---------------------------------------------------------------------------
+// Internal
+// ---------------------------------------------------------------------------
+
+/**
+ * Read WASM file with runtime detection (Deno, Bun).
+ * Uses web-standard `URL` objects — no `node:path` or `node:url` needed.
+ */
+async function readWasmFile(url: URL): Promise<ArrayBuffer> {
+  // Deno
+  if (typeof Deno !== "undefined") {
+    const bytes = await Deno.readFile(url);
+    return (bytes.buffer as ArrayBuffer).slice(
+      bytes.byteOffset,
+      bytes.byteOffset + bytes.byteLength,
+    );
+  }
+
+  // Bun
+  if (typeof Bun !== "undefined") {
+    return Bun.file(url).arrayBuffer();
+  }
+
+  // Fallback: fetch (works in environments with file:// fetch support)
+  const response = await fetch(url);
+  return response.arrayBuffer();
+}
+
+async function loadWasm(): Promise<WasmParsers> {
+  try {
+    // Bundler-friendly import (works in Vitest, Vite, Cloudflare Workers, etc.)
+    // @ts-ignore — wasm-bindgen generated, typed via WasmParsers interface
+    const mod = await import("../pkg/quill_matter_wasm.js");
+    wasmModule = mod;
+    return mod as WasmParsers;
+  } catch {
+    // Fallback: manually load the WASM binary (Bun, Deno)
+    return loadWasmDirect();
+  }
+}
+
+async function loadWasmDirect(): Promise<WasmParsers> {
+  // @ts-ignore — wasm-bindgen generated, typed via WasmParsers interface
+  const bgModule = await import("../pkg/quill_matter_wasm_bg.js");
+
+  // Resolve the .wasm path using web-standard `URL` constructor.
+  // Works in Bun, Deno, and any environment with `import.meta.url`.
+  const wasmUrl = new URL("../pkg/quill_matter_wasm_bg.wasm", import.meta.url);
+  const wasmBytes = await readWasmFile(wasmUrl);
+
+  const wasmImports = {
+    "./quill_matter_wasm_bg.js": bgModule,
+  };
+
+  const { instance } = await WebAssembly.instantiate(wasmBytes, wasmImports);
+  bgModule.__wbg_set_wasm(instance.exports);
+
+  // Call the init function for externref table
+  if (typeof instance.exports.__wbindgen_start === "function") {
+    (instance.exports.__wbindgen_start as () => void)();
+  }
+
+  wasmModule = bgModule;
+  return bgModule as WasmParsers;
+}