@piqit/resolvers 0.0.2

package/src/frontmatter.ts

@@ -0,0 +1,269 @@
+/**
+ * YAML Frontmatter Extraction
+ *
+ * Optimized frontmatter parsing that reads only what's needed.
+ */
+
+// =============================================================================
+// Frontmatter Parsing
+// =============================================================================
+
+/**
+ * Regex to match YAML frontmatter block at the start of content.
+ * Matches --- at start, captures content, ends with ---
+ */
+const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---/
+
+/**
+ * Parse YAML frontmatter from content string.
+ *
+ * Uses a simple YAML parser that handles common cases:
+ * - key: value
+ * - key: "quoted value"
+ * - key: 'quoted value'
+ * - key: [array, items]
+ * - Multi-line values with proper indentation
+ *
+ * @param content - The file content (or just the frontmatter portion)
+ * @returns The parsed frontmatter object, or null if not found
+ */
+export function parseFrontmatter(content: string): Record<string, unknown> | null {
+  const match = FRONTMATTER_REGEX.exec(content)
+  if (!match) return null
+
+  const yaml = match[1]
+  return parseSimpleYaml(yaml)
+}
+
+/**
+ * Extract just the frontmatter portion from content.
+ * Returns the raw YAML string without the --- delimiters.
+ *
+ * @param content - The file content
+ * @returns The YAML content, or null if no frontmatter
+ */
+export function extractFrontmatterString(content: string): string | null {
+  const match = FRONTMATTER_REGEX.exec(content)
+  return match ? match[1] : null
+}
+
+/**
+ * Get the byte offset where frontmatter ends (after closing ---).
+ * Returns 0 if no frontmatter found.
+ *
+ * @param content - The file content
+ * @returns Byte offset after frontmatter, or 0
+ */
+export function getFrontmatterEndOffset(content: string): number {
+  const match = FRONTMATTER_REGEX.exec(content)
+  if (!match) return 0
+  return match[0].length
+}
+
+// =============================================================================
+// Simple YAML Parser
+// =============================================================================
+
+/**
+ * Parse simple YAML into an object.
+ * Handles the common patterns found in markdown frontmatter.
+ */
+function parseSimpleYaml(yaml: string): Record<string, unknown> {
+  const result: Record<string, unknown> = {}
+  const lines = yaml.split(/\r?\n/)
+
+  let currentKey: string | null = null
+  let currentValue: string[] = []
+  let inMultiline = false
+  let inBlockArray = false
+  let blockArrayItems: unknown[] = []
+  let multilineIndent = 0
+
+  function commitValue() {
+    if (currentKey) {
+      if (inBlockArray) {
+        // Commit block array
+        result[currentKey] = blockArrayItems
+        blockArrayItems = []
+        inBlockArray = false
+      } else if (currentValue.length === 1) {
+        result[currentKey] = parseYamlValue(currentValue[0])
+      } else if (currentValue.length > 1) {
+        result[currentKey] = currentValue.join("\n")
+      }
+    }
+    currentKey = null
+    currentValue = []
+    inMultiline = false
+  }
+
+  for (const line of lines) {
+    // Check for block array item (- value)
+    const arrayItemMatch = line.match(/^(\s+)-\s+(.*)$/)
+    if (arrayItemMatch && currentKey && (inBlockArray || (inMultiline && currentValue.length === 0))) {
+      inBlockArray = true
+      inMultiline = false
+      const itemValue = arrayItemMatch[2].trim()
+      blockArrayItems.push(parseYamlValue(itemValue))
+      continue
+    }
+
+    // Check for key: value pattern
+    const keyMatch = line.match(/^([a-zA-Z_][a-zA-Z0-9_-]*)\s*:\s*(.*)$/)
+
+    if (keyMatch && !inMultiline) {
+      // Commit previous key-value
+      commitValue()
+
+      currentKey = keyMatch[1]
+      const valueStr = keyMatch[2].trim()
+
+      if (valueStr === "" || valueStr === "|" || valueStr === ">") {
+        // Multiline value or block array starts on next line
+        inMultiline = true
+        multilineIndent = 0
+      } else {
+        currentValue = [valueStr]
+      }
+    } else if (inMultiline && currentKey && !inBlockArray) {
+      // Continuation of multiline value
+      if (line.trim() === "") {
+        currentValue.push("")
+      } else {
+        const indent = line.search(/\S/)
+        if (indent > 0) {
+          if (multilineIndent === 0) {
+            multilineIndent = indent
+          }
+          currentValue.push(line.slice(multilineIndent))
+        } else {
+          // No indent means new key or end of multiline
+          commitValue()
+          // Re-process this line
+          const reKeyMatch = line.match(/^([a-zA-Z_][a-zA-Z0-9_-]*)\s*:\s*(.*)$/)
+          if (reKeyMatch) {
+            currentKey = reKeyMatch[1]
+            const valueStr = reKeyMatch[2].trim()
+            if (valueStr === "" || valueStr === "|" || valueStr === ">") {
+              inMultiline = true
+              multilineIndent = 0
+            } else {
+              currentValue = [valueStr]
+            }
+          }
+        }
+      }
+    } else if (currentKey && line.trim() === "") {
+      // Empty line after value - keep going
+    } else if (!currentKey && line.trim() !== "") {
+      // New key-value
+      const newKeyMatch = line.match(/^([a-zA-Z_][a-zA-Z0-9_-]*)\s*:\s*(.*)$/)
+      if (newKeyMatch) {
+        currentKey = newKeyMatch[1]
+        const valueStr = newKeyMatch[2].trim()
+        if (valueStr === "" || valueStr === "|" || valueStr === ">") {
+          inMultiline = true
+          multilineIndent = 0
+        } else {
+          currentValue = [valueStr]
+        }
+      }
+    }
+  }
+
+  // Commit final value
+  commitValue()
+
+  return result
+}
+
+/**
+ * Parse a single YAML value.
+ */
+function parseYamlValue(value: string): unknown {
+  // Remove quotes
+  if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+    return value.slice(1, -1)
+  }
+
+  // Check for array
+  if (value.startsWith("[") && value.endsWith("]")) {
+    const inner = value.slice(1, -1)
+    if (inner.trim() === "") return []
+    return inner.split(",").map((item) => parseYamlValue(item.trim()))
+  }
+
+  // Check for booleans
+  if (value === "true") return true
+  if (value === "false") return false
+
+  // Check for null
+  if (value === "null" || value === "~") return null
+
+  // Check for numbers
+  const num = Number(value)
+  if (!isNaN(num) && value !== "") return num
+
+  // Check for dates (ISO format)
+  if (/^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2})?/.test(value)) {
+    const date = new Date(value)
+    if (!isNaN(date.getTime())) return date.toISOString()
+  }
+
+  return value
+}
+
+// =============================================================================
+// Optimized File Reading
+// =============================================================================
+
+/**
+ * Read only the frontmatter from a file, optimized for large files.
+ *
+ * Reads incrementally until we find the closing ---, avoiding reading
+ * the entire file into memory.
+ *
+ * @param path - Path to the markdown file
+ * @param maxBytes - Maximum bytes to read looking for frontmatter (default 8KB)
+ * @returns The parsed frontmatter, or null if not found
+ */
+export async function readFrontmatter(
+  path: string,
+  maxBytes = 8192
+): Promise<Record<string, unknown> | null> {
+  try {
+    const file = Bun.file(path)
+    const size = file.size
+
+    // Read up to maxBytes or file size
+    const bytesToRead = Math.min(maxBytes, size)
+    const buffer = await file.slice(0, bytesToRead).text()
+
+    return parseFrontmatter(buffer)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Read frontmatter and return the offset where body starts.
+ * Useful when you need both frontmatter and body.
+ *
+ * @param path - Path to the markdown file
+ * @returns Object with frontmatter and body start offset
+ */
+export async function readFrontmatterWithOffset(
+  path: string
+): Promise<{ frontmatter: Record<string, unknown> | null; bodyOffset: number }> {
+  try {
+    const file = Bun.file(path)
+    const content = await file.text()
+
+    const frontmatter = parseFrontmatter(content)
+    const bodyOffset = getFrontmatterEndOffset(content)
+
+    return { frontmatter, bodyOffset }
+  } catch {
+    return { frontmatter: null, bodyOffset: 0 }
+  }
+}

package/src/index.ts

@@ -0,0 +1,65 @@
+/**
+ * @piqit/resolvers - Resolver implementations for piq v2
+ *
+ * Provides resolvers for querying structured content:
+ * - fileMarkdown: Query markdown files from filesystem (Node.js/Bun)
+ * - staticContent: Query pre-compiled content (Edge/Workers)
+ *
+ * @packageDocumentation
+ */
+
+// =============================================================================
+// Filesystem Resolver (Node.js/Bun only)
+// =============================================================================
+
+export { fileMarkdown } from "./file-markdown"
+export type { FileMarkdownOptions, FileMarkdownResult } from "./file-markdown"
+
+// =============================================================================
+// Static Content Resolver (Edge/Workers compatible)
+// =============================================================================
+
+export { staticContent, staticResolver } from "./static"
+
+// =============================================================================
+// Path Pattern Utilities
+// =============================================================================
+
+export { compilePattern, createParamsSchema } from "./path-pattern"
+export type {
+  CompiledPattern,
+  ExtractParams,
+  PathParams,
+} from "./path-pattern"
+
+// =============================================================================
+// Frontmatter Utilities
+// =============================================================================
+
+export {
+  parseFrontmatter,
+  extractFrontmatterString,
+  getFrontmatterEndOffset,
+  readFrontmatter,
+  readFrontmatterWithOffset,
+} from "./frontmatter"
+
+// =============================================================================
+// Markdown Utilities
+// =============================================================================
+
+export {
+  parseMarkdownBody,
+  extractHeadings,
+  slugify,
+  markdownToHtml,
+  readMarkdownBody,
+  readParsedBody,
+} from "./markdown"
+
+export type {
+  BodyOptions,
+  BodyResult,
+  BodyShape,
+  Heading,
+} from "./markdown"

package/src/markdown.ts

@@ -0,0 +1,262 @@
+/**
+ * Markdown Body Parsing
+ *
+ * Parses markdown body content to extract:
+ * - Raw markdown text
+ * - HTML (basic conversion)
+ * - Headings with slugs
+ */
+
+import { getFrontmatterEndOffset } from "./frontmatter"
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Options for parsing markdown body.
+ */
+export interface BodyOptions {
+  /** Include raw markdown text */
+  raw?: boolean
+  /** Include HTML conversion */
+  html?: boolean
+  /** Extract headings with depth and slugs */
+  headings?: boolean
+}
+
+/**
+ * A heading extracted from markdown.
+ */
+export interface Heading {
+  /** Heading depth (1-6) */
+  depth: number
+  /** Heading text content */
+  text: string
+  /** URL-safe slug */
+  slug: string
+}
+
+/**
+ * Result of parsing markdown body.
+ */
+export interface BodyResult {
+  /** Raw markdown text (if requested) */
+  raw?: string
+  /** HTML content (if requested) */
+  html?: string
+  /** Extracted headings (if requested) */
+  headings?: Heading[]
+}
+
+/**
+ * Type-level shape of body result based on options.
+ */
+export type BodyShape<T extends BodyOptions> = {
+  [K in keyof T as T[K] extends true ? K : never]: K extends "raw"
+    ? string
+    : K extends "html"
+      ? string
+      : K extends "headings"
+        ? Heading[]
+        : never
+}
+
+// =============================================================================
+// Markdown Parsing
+// =============================================================================
+
+/**
+ * Parse markdown body content.
+ *
+ * @param content - The full file content (including frontmatter if present)
+ * @param options - What to extract from the markdown
+ * @returns The requested body parts
+ */
+export function parseMarkdownBody(content: string, options: BodyOptions): BodyResult {
+  // Strip frontmatter if present
+  const bodyOffset = getFrontmatterEndOffset(content)
+  const rawBody = content.slice(bodyOffset).replace(/^[\r\n]+/, "")
+
+  const result: BodyResult = {}
+
+  if (options.raw) {
+    result.raw = rawBody
+  }
+
+  if (options.html) {
+    result.html = markdownToHtml(rawBody)
+  }
+
+  if (options.headings) {
+    result.headings = extractHeadings(rawBody)
+  }
+
+  return result
+}
+
+// =============================================================================
+// Heading Extraction
+// =============================================================================
+
+/**
+ * Regex to match ATX-style headings (# Heading).
+ */
+const HEADING_REGEX = /^(#{1,6})\s+(.+)$/gm
+
+/**
+ * Extract headings from markdown text.
+ *
+ * @param markdown - The raw markdown content
+ * @returns Array of headings with depth, text, and slug
+ */
+export function extractHeadings(markdown: string): Heading[] {
+  const headings: Heading[] = []
+  let match: RegExpExecArray | null
+
+  const regex = new RegExp(HEADING_REGEX.source, "gm")
+  while ((match = regex.exec(markdown)) !== null) {
+    const depth = match[1].length
+    const text = match[2].trim()
+    const slug = slugify(text)
+
+    headings.push({ depth, text, slug })
+  }
+
+  return headings
+}
+
+/**
+ * Convert text to a URL-safe slug.
+ *
+ * @param text - The text to slugify
+ * @returns A URL-safe slug
+ */
+export function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^\w\s-]/g, "") // Remove non-word chars
+    .replace(/\s+/g, "-") // Replace spaces with dashes
+    .replace(/--+/g, "-") // Replace multiple dashes
+    .replace(/^-|-$/g, "") // Trim dashes from ends
+}
+
+// =============================================================================
+// Basic Markdown to HTML
+// =============================================================================
+
+/**
+ * Convert markdown to HTML.
+ *
+ * This is a basic implementation that handles common patterns.
+ * For production use, consider using a proper markdown parser.
+ *
+ * @param markdown - The raw markdown content
+ * @returns HTML string
+ */
+export function markdownToHtml(markdown: string): string {
+  let html = markdown
+
+  // Escape HTML entities first
+  html = html
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+
+  // Headings (must be on their own line)
+  html = html.replace(/^######\s+(.+)$/gm, "<h6>$1</h6>")
+  html = html.replace(/^#####\s+(.+)$/gm, "<h5>$1</h5>")
+  html = html.replace(/^####\s+(.+)$/gm, "<h4>$1</h4>")
+  html = html.replace(/^###\s+(.+)$/gm, "<h3>$1</h3>")
+  html = html.replace(/^##\s+(.+)$/gm, "<h2>$1</h2>")
+  html = html.replace(/^#\s+(.+)$/gm, "<h1>$1</h1>")
+
+  // Code blocks (fenced)
+  html = html.replace(/```(\w*)\n([\s\S]*?)```/g, (_match, _lang, code) => {
+    return `<pre><code>${code.trim()}</code></pre>`
+  })
+
+  // Inline code
+  html = html.replace(/`([^`]+)`/g, "<code>$1</code>")
+
+  // Bold
+  html = html.replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>")
+  html = html.replace(/__([^_]+)__/g, "<strong>$1</strong>")
+
+  // Italic
+  html = html.replace(/\*([^*]+)\*/g, "<em>$1</em>")
+  html = html.replace(/_([^_]+)_/g, "<em>$1</em>")
+
+  // Links
+  html = html.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>')
+
+  // Images
+  html = html.replace(/!\[([^\]]*)\]\(([^)]+)\)/g, '<img src="$2" alt="$1">')
+
+  // Horizontal rules
+  html = html.replace(/^---+$/gm, "<hr>")
+  html = html.replace(/^\*\*\*+$/gm, "<hr>")
+
+  // Unordered lists (simplified)
+  html = html.replace(/^[-*+]\s+(.+)$/gm, "<li>$1</li>")
+
+  // Ordered lists (simplified)
+  html = html.replace(/^\d+\.\s+(.+)$/gm, "<li>$1</li>")
+
+  // Wrap consecutive <li> in <ul> or <ol>
+  html = html.replace(/((?:<li>.*<\/li>\n?)+)/g, "<ul>\n$1</ul>\n")
+
+  // Blockquotes
+  html = html.replace(/^>\s+(.+)$/gm, "<blockquote>$1</blockquote>")
+
+  // Paragraphs (wrap remaining text blocks)
+  // Split by double newlines and wrap non-block elements
+  const blocks = html.split(/\n\n+/)
+  html = blocks
+    .map((block) => {
+      const trimmed = block.trim()
+      if (!trimmed) return ""
+      // Don't wrap if already a block element
+      if (
+        /^<(h[1-6]|ul|ol|li|pre|blockquote|hr|p)/.test(trimmed) ||
+        /^<\/?(h[1-6]|ul|ol|li|pre|blockquote)>$/.test(trimmed)
+      ) {
+        return trimmed
+      }
+      return `<p>${trimmed.replace(/\n/g, "<br>")}</p>`
+    })
+    .filter(Boolean)
+    .join("\n")
+
+  return html
+}
+
+// =============================================================================
+// File Reading Utilities
+// =============================================================================
+
+/**
+ * Read just the markdown body from a file (skipping frontmatter).
+ *
+ * @param path - Path to the markdown file
+ * @returns The raw markdown body
+ */
+export async function readMarkdownBody(path: string): Promise<string> {
+  const file = Bun.file(path)
+  const content = await file.text()
+  const bodyOffset = getFrontmatterEndOffset(content)
+  return content.slice(bodyOffset).replace(/^\r?\n/, "")
+}
+
+/**
+ * Read and parse markdown body from a file.
+ *
+ * @param path - Path to the markdown file
+ * @param options - What to extract from the markdown
+ * @returns The requested body parts
+ */
+export async function readParsedBody(path: string, options: BodyOptions): Promise<BodyResult> {
+  const file = Bun.file(path)
+  const content = await file.text()
+  return parseMarkdownBody(content, options)
+}