lite-matter 0.0.1

package/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

package/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish to NPM
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+          
+      - name: Install dependencies
+        run: npm install
+        
+      - name: Build package
+        run: npm run build
+        
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present docmd.io
+
+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,85 @@
+# lite-matter
+
+**The Minimalist, Zero-Bloat YAML Frontmatter Extractor for Modern JavaScript.**
+
+`lite-matter` is a high-performance, single-pass frontmatter extraction engine. It provides the same metadata isolation interface as legacy libraries like `gray-matter` without the inclusion of heavy, non-standard dependencies or legacy string-handling wrappers.
+
+## Technical Specifications
+
+- **Runtime**: Node.js (ESM), Browser (Modern), Deno, Cloudflare Workers.
+- **Language**: Core logic written in modern TypeScript.
+- **Dependency**: Powered by the modern `yaml` parser for spec-compliant parsing.
+- **Distribution**: Pure ES Module (ESM).
+
+## The Problem: The Legacy Complexity Gap
+
+Legacy libraries like `gray-matter` were built for an older era of the JavaScript ecosystem. They often include complex, non-standard frontmatter support (e.g., CoffeeScript, TOML, and CSV delimiters) and heavy string-processing logic that increases CPU and bundle overhead in modern static site generators and CMS engines.
+
+`lite-matter` is a modern, laser-focused alternative. It is built strictly for the **standard triple-dash YAML frontmatter format** (the industry-standard across Markdown, GitHub, and major CMS architectures).
+
+### Technical Limitations & Design Scope
+
+To maintain its minimalism, `lite-matter` purposely restricts its feature set:
+
+1.  **Format Restriction**: Strictly supports YAML triple-dash (`---`) frontmatter. It does not support TOML (`+++`), CoffeeScript, or other legacy metadata formats found in `gray-matter`.
+2.  **No Delimiter Customization**: Delimiters are hardcoded to the industry-standard `---` to optimize regex isolation performance.
+3.  **Strict ESM**: Built specifically for modern ESM toolchains.
+4.  **No In-memory Cache**: For consistency, `lite-matter` performs a fresh parse on every invocation. If high-frequency parsing of the same file is required, results should be cached at the application layer.
+
+*   **Optimal Performance**: Uses a pinpoint regex scan to isolate the YAML block, passing it directly to the performance-optimized `yaml` library.
+*   **Reduced Footprint**: Does not bundle unnecessary non-standard parsers for legacy formats.
+*   **Secure & Robust**: Provides safe, fault-tolerant YAML parsing with clean error handling and graceful fallbacks.
+*   **Modern Support**: Written in TypeScript and exported as native ESM for a superior developer experience in modern toolchains.
+*   **Exact Drop-In Compatibility**: Supports the identical `matter(content)` API expected by millions of developers.
+
+## Installation
+
+```bash
+npm install lite-matter
+```
+
+## Quick Start
+
+```javascript
+import matter from 'lite-matter';
+
+const markdown = `---
+title: Understanding lite-matter
+date: 2026-04-04
+status: draft
+---
+# Content Start
+This is the body of the markdown file.`;
+
+const { data, content } = matter(markdown);
+
+console.log(data);
+// Output: { title: "Understanding lite-matter", date: "2026-04-04", status: "draft" }
+
+console.log(content.trim());
+// Output: "# Content Start\nThis is the body of the markdown file."
+```
+
+## Comparisons
+
+| Feature | gray-matter | lite-matter |
+| :--- | :--- | :--- |
+| **Logic** | Multi-parser | **Pinpoint YAML** |
+| **Parsing** | Bulky strings | **Single-pass scan** |
+| **Standard** | Triple-dash (+++, TOML, etc.) | **Standard Triple-dash YAML** |
+| **Weight (approx)**| ~100KB+ | **<1KB logic** |
+
+## API Reference
+
+### `matter(str)`
+
+**Arguments:**
+- `str` (string): The raw source string incorporating the frontmatter block.
+
+**Returns:**
+- `data` (object): A parsed JavaScript object from the YAML block.
+- `content` (string): The remaining source string (stripped of frontmatter).
+
+## License
+
+MIT - Developed under the docmd ecosystem by [Ghazi](https://mgks.dev).

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export interface MatterResult {
+    data: Record<string, any>;
+    content: string;
+}
+/**
+ * Extracts and parses YAML frontmatter from a string.
+ * Mimics the API of `gray-matter` for easy drop-in replacement.
+ */
+export declare function matter(str: string): MatterResult;
+export default matter;

package/dist/index.js

@@ -0,0 +1,25 @@
+import { parse } from 'yaml';
+/**
+ * Extracts and parses YAML frontmatter from a string.
+ * Mimics the API of `gray-matter` for easy drop-in replacement.
+ */
+export function matter(str) {
+    // Regex matches frontmatter bounded by --- only at the very start of the string
+    const regex = /^(?:---[\r\n]+)([\s\S]*?)(?:[\r\n]+---(?:[\r\n]+|$))/;
+    const match = str.match(regex);
+    if (!match) {
+        return { data: {}, content: str };
+    }
+    const yamlStr = match[1];
+    const content = str.slice(match[0].length);
+    try {
+        const data = parse(yamlStr) || {};
+        return { data, content };
+    }
+    catch (err) {
+        // Return empty data but successfully parse the rest of the text if YAML fails
+        return { data: {}, content: str };
+    }
+}
+// Fallback default export for total compatibility
+export default matter;

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "lite-matter",
+  "version": "0.0.1",
+  "description": "Ultra lightweight, zero-bloat frontmatter extractor.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc"
+  },
+  "dependencies": {
+    "yaml": "^2.4.2"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "keywords": [
+    "frontmatter",
+    "gray-matter",
+    "yaml",
+    "markdown",
+    "minimal",
+    "typescript",
+    "javascript",
+    "nodejs",
+    "browser",
+    "docmd"
+  ],
+  "author": {
+    "name": "Ghazi",
+    "url": "https://mgks.dev"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/docmd-io/docmd.git",
+    "directory": "lite-matter"
+  },
+  "bugs": {
+    "url": "https://github.com/docmd-io/docmd/issues"
+  },
+  "homepage": "https://docmd.io",
+  "funding": "https://github.com/sponsors/mgks",
+  "license": "MIT"
+}

package/src/index.ts

@@ -0,0 +1,34 @@
+import { parse } from 'yaml';
+
+export interface MatterResult {
+  data: Record<string, any>;
+  content: string;
+}
+
+/**
+ * Extracts and parses YAML frontmatter from a string.
+ * Mimics the API of `gray-matter` for easy drop-in replacement.
+ */
+export function matter(str: string): MatterResult {
+  // Regex matches frontmatter bounded by --- only at the very start of the string
+  const regex = /^(?:---[\r\n]+)([\s\S]*?)(?:[\r\n]+---(?:[\r\n]+|$))/;
+  const match = str.match(regex);
+
+  if (!match) {
+    return { data: {}, content: str };
+  }
+
+  const yamlStr = match[1];
+  const content = str.slice(match[0].length);
+
+  try {
+    const data = parse(yamlStr) || {};
+    return { data, content };
+  } catch (err) {
+    // Return empty data but successfully parse the rest of the text if YAML fails
+    return { data: {}, content: str };
+  }
+}
+
+// Fallback default export for total compatibility
+export default matter;

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "node16",
+    "strict": true,
+    "declaration": true,
+    "outDir": "dist",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"]
+}