simplematter 1.0.0

package/LICENSE.md

@@ -0,0 +1,18 @@
+# MIT License
+
+Copyright © 2026 Remco Haszing
+
+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,124 @@
+# simplematter
+
+[![github actions](https://github.com/remcohaszing/simplematter/actions/workflows/ci.yaml/badge.svg)](https://github.com/remcohaszing/simplematter/actions/workflows/ci.yaml)
+[![codecov](https://codecov.io/gh/remcohaszing/simplematter/branch/main/graph/badge.svg)](https://codecov.io/gh/remcohaszing/simplematter)
+[![npm version](https://img.shields.io/npm/v/simplematter)](https://www.npmjs.com/package/simplematter)
+[![npm downloads](https://img.shields.io/npm/dm/simplematter)](https://www.npmjs.com/package/simplematter)
+
+A simple frontmatter parser.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+- [API](#api)
+  - [`simplematter(content[, parsers])`](#simplemattercontent-parsers)
+- [Examples](#examples)
+  - [Modify YAML frontmatter](#modify-yaml-frontmatter)
+  - [Get raw frontmatter](#get-raw-frontmatter)
+- [Compatibility](#compatibility)
+- [License](#license)
+
+## Installation
+
+```sh
+npm install simplematter
+```
+
+## Usage
+
+The `simplematter` function parses frontmatter data from a string. It supports both the `---` and
+the `+++` fences. The `---` fence is typically used for YAML data, the `+++` fence for TOML.
+
+```js
+import { simplematter } from 'simplematter'
+
+const [frontmatter, document] = simplematter(
+  `---
+title: This could be the document title.
+---
+
+Rest of document
+`
+)
+
+console.log(frontmatter)
+console.log(document)
+```
+
+## API
+
+### `simplematter(content[, parsers])`
+
+Parse frontmatter data.
+
+#### Arguments
+
+- `content` (`string`) — The string from which to parse frontmatter data.
+- `parsers` (`object`, optional) — The parsers to use. It has the following keys:
+  - `yaml` — A parser for YAML content. This is used to parse content from the `---` fence. By
+    default the [`yaml`](https://eemeli.org/yaml/) package is used.
+  - `toml` — A parser for TOML content. This is used to parse content from the `+++` fence. By
+    default the [`smol-toml`](https://github.com/squirrelchat/smol-toml) package is used.
+
+## Examples
+
+### Modify YAML frontmatter
+
+You can modify YAML frontmatter data while preserving most of the original YAML using the
+[`parseDocument`](https://eemeli.org/yaml/#parsing-documents) function exposed by `yaml`.
+
+```ts
+import { simplematter } from 'simplematter'
+import { Document, isDocument, parseDocument } from 'yaml'
+
+const [frontmatter, content] = simplematter(
+  `---
+# This comment is preserved.
+title: This could be the document title.
+---
+
+Rest of the document.
+`,
+  { yaml: parseDocument }
+)
+
+const yamlDocument = isDocument(frontmatter) ? frontmatter : new Document()
+yamlDocument.set('modified', new Date().toISOString().slice(0, 10))
+
+const result = `---\n${frontmatter}---\n\n${content}`
+
+console.log(result)
+```
+
+### Get raw frontmatter
+
+You can get the raw frontmatter string by returning the input from your parser function.
+
+```ts
+import { simplematter } from 'simplematter'
+
+function identity<Input>(input: Input): Input {
+  return input
+}
+
+const [frontmatter] = simplematter(
+  `---
+title: This could be the document title.
+---
+
+Rest of the document.
+`,
+  { toml: identity, yaml: identity }
+)
+
+console.log(frontmatter)
+```
+
+## Compatibility
+
+This project is compatible with Node.js 22 or greater.
+
+## License
+
+[MIT](LICENSE.md) © [Remco Haszing](https://github.com/remcohaszing)

package/lib/simplematter.js

@@ -0,0 +1,89 @@
+import { parse as toml } from 'smol-toml'
+import { parse as yaml } from 'yaml'
+
+/**
+ * @typedef simplematter.Parsers
+ * @property {((frontmatter: string) => unknown) | undefined} [toml]
+ *   A parser for TOML content. This is used to parse content from the `+++` fence. By default the
+ *   [`yaml`](https://eemeli.org/yaml/) package is used.
+ * @property {((frontmatter: string) => unknown) | undefined} [yaml]
+ *   A parser for YAML content. This is used to parse content from the `---` fence. By default the
+ *   [`smol-toml`](https://github.com/squirrelchat/smol-toml) package is used.
+ */
+
+const nonWhitespaceRegex = /\S/
+
+/**
+ * Check whether the content from a line starting at an index is trailing space.
+ *
+ * @param {string} content
+ *   The content whose characters to check.
+ * @param {number} start
+ *   The start index of the characters to check.
+ * @returns {number}
+ *   The index of the newline character that ends the line whitespace, -1 otherwise.
+ */
+function findTrailingSpaceEnd(content, start) {
+  for (let index = start; index < content.length; index += 1) {
+    const char = content[index]
+
+    if (char === '\n') {
+      return index
+    }
+
+    if (nonWhitespaceRegex.test(char)) {
+      return -1
+    }
+  }
+
+  // The fence is the end of the document. There’s no trailing newline.
+  return content.length
+}
+
+/** @type {Required<simplematter.Parsers>} */
+const defaultParsers = {
+  toml,
+  yaml
+}
+
+/**
+ * Parse frontmatter data.
+ *
+ * @param {string} content
+ *   The string from which to parse frontmatter data.
+ * @param {simplematter.Parsers | undefined} [parsers]
+ *   The parsers to use.
+ * @returns {[data: unknown, document: string]}
+ *   A tuple which consists of the parsed frontmatter data and the rest of the document.
+ */
+export function simplematter(content, parsers) {
+  const openFence = content.slice(0, 3)
+  const openSpaceEnd = findTrailingSpaceEnd(content, 3)
+  let closeFenceStart = openSpaceEnd + 1
+
+  /** @type {number} */
+  let closeSpaceEnd
+
+  if (openSpaceEnd === -1 || (openFence !== '---' && openFence !== '+++')) {
+    return [undefined, content]
+  }
+
+  do {
+    closeFenceStart = content.indexOf(openFence, closeFenceStart + 3)
+
+    // We’ve reached the end of the content, but we didn’t find a closing fence.
+    if (closeFenceStart === -1) {
+      return [undefined, content]
+    }
+
+    closeSpaceEnd = findTrailingSpaceEnd(content, closeFenceStart + 3)
+  } while (closeSpaceEnd === -1 || content[closeFenceStart - 1] !== '\n')
+
+  const key = openFence === '+++' ? 'toml' : 'yaml'
+  const parser = parsers?.[key] || defaultParsers[key]
+
+  return [
+    parser(content.slice(openSpaceEnd + 1, closeFenceStart)),
+    content.slice(closeSpaceEnd).trimStart()
+  ]
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "simplematter",
+  "version": "1.0.0",
+  "description": "A simple frontmatter parser",
+  "keywords": [
+    "frontmatter",
+    "front-matter",
+    "graymatter",
+    "gray-matter",
+    "greymatter",
+    "grey-matter",
+    "matter"
+  ],
+  "homepage": "https://github.com/remcohaszing/simplematter#readme",
+  "bugs": "https://github.com/remcohaszing/simplematter/issues",
+  "repository": "remcohaszing/simplematter",
+  "funding": "https://github.com/sponsors/remcohaszing",
+  "license": "MIT",
+  "author": "Remco Haszing <remcohaszing@gmail.com>",
+  "type": "module",
+  "exports": {
+    "types": "./types/simplematter.d.ts",
+    "default": "./lib/simplematter.js"
+  },
+  "sideEffects": false,
+  "files": [
+    "lib",
+    "types"
+  ],
+  "scripts": {
+    "prepack": "tsc --build",
+    "test": "c8 node --test"
+  },
+  "dependencies": {
+    "smol-toml": "^1.0.0",
+    "yaml": "^2.0.0"
+  },
+  "devDependencies": {
+    "@remcohaszing/eslint": "^13.0.0",
+    "c8": "^10.0.0",
+    "prettier": "^3.0.0",
+    "remark-cli": "^12.0.0",
+    "remark-preset-remcohaszing": "^3.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/types/simplematter.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Parse frontmatter data.
+ *
+ * @param {string} content
+ *   The string from which to parse frontmatter data.
+ * @param {simplematter.Parsers | undefined} [parsers]
+ *   The parsers to use.
+ * @returns {[data: unknown, document: string]}
+ *   A tuple which consists of the parsed frontmatter data and the rest of the document.
+ */
+export function simplematter(content: string, parsers?: simplematter.Parsers | undefined): [data: unknown, document: string];
+export namespace simplematter {
+    type Parsers = {
+        /**
+         * A parser for TOML content. This is used to parse content from the `+++` fence. By default the
+         * [`yaml`](https://eemeli.org/yaml/) package is used.
+         */
+        toml?: ((frontmatter: string) => unknown) | undefined;
+        /**
+         * A parser for YAML content. This is used to parse content from the `---` fence. By default the
+         * [`smol-toml`](https://github.com/squirrelchat/smol-toml) package is used.
+         */
+        yaml?: ((frontmatter: string) => unknown) | undefined;
+    };
+}
+//# sourceMappingURL=simplematter.d.ts.map

package/types/simplematter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"simplematter.d.ts","sourceRoot":"","sources":["../lib/simplematter.js"],"names":[],"mappings":"AAgDA;;;;;;;;;GASG;AACH,sCAPW,MAAM,YAEN,YAAY,CAAC,OAAO,GAAG,SAAS,GAE9B,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,CAiC7C;;;;;;;eAnFa,CAAC,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,SAAS;;;;;eAG9C,CAAC,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,SAAS"}