zod-matter 🏷️
Typesafe front matter
## Features
zod-matter is a tiny wrapper for [gray-matter](https://github.com/jonschlinkert/gray-matter/) and [Zod](https://github.com/colinhacks/zod) to parse and validate front matter with [static type inference](https://www.typescriptlang.org/play?#code/JYWwDg9gTgLgBAbzmAhlAzgUzgXzgMyghDgCIAvCAEwFoQUYZMpSAoUSWROc3AokhWptWAYwgA7dPGASwAV3gBeOAAMaG1ikUALaAC44ACWAARTBAisqDTIYBMABnsBmGo4CM7gKysNNVlYAYmNMABswiDgAd2gwqgBCVlVA8Sl4QkkYAFkGJig4FVQMTAAKVjg4WQUYABoKngA6CAAjACtMURhShAbK7Rg9KENyRukoWQBzUoBKesrKmyYRxqWyub64UVtJ6ABPFfGp2eawGGBJFDDZ+dwZ1nvWTIkcvOZVhhRGgaGnohfcox3ksvms-llAfkPjAvtsmLsoHtAs9XkCoNCvlAUBIqMRWEA).
gray-matter is a great package to parse front matter but provides [no validation or type safety](https://github.com/jonschlinkert/gray-matter/issues/69#issuecomment-454978951). This package exposes an API adding a `schema` parameter to validate front matter data using Zod. This can be particularly useful to parse & validate front matter for user generated Markdown or MDX files for example.
## Installation
Install `zod-matter` and its peer dependencies with your favorite package manager, e.g.:
```shell
pnpm add zod-matter zod gray-matter
```
## Usage
### `parse`
Extracts and parses front matter according to the given Zod schema.
```ts
import { parse } from 'zod-matter'
import { z } from 'zod'
const { data } = parse('---\nauthor: HiDeoo\n---\n# Hello world!', z.object({ author: z.string() }))
// ^? { author: string }
```
#### Parameters
- `input`: The string, buffer or object with a `content` property to parse.
- `schema`: The Zod schema to use to parse the front matter.
- `options`: Optionally, the [gray-matter options](https://github.com/jonschlinkert/gray-matter/tree/a5726b04f3167fadc764241deb545518c454eb82#options) to use.
#### Return value
A file object with the same properties of a [gray-matter file object](https://github.com/jonschlinkert/gray-matter/tree/a5726b04f3167fadc764241deb545518c454eb82#returned-object) but with a `data` property of the type inferred from the given Zod schema.
If the front matter data is invalid, a [`ZodError`](https://github.com/colinhacks/zod/tree/master#error-handling) will be thrown.
### `read`
Extracts and parses front matter from a file according to the given Zod schema.
```ts
import { read } from 'zod-matter'
import { z } from 'zod'
const { data } = read('./data/post.md', z.object({ author: z.string(), date: z.date() }))
// ^? { author: string; date: Date }
```
#### Parameters
- `path`: The path to the file to read and parse.
- `schema`: The Zod schema to use to parse the front matter.
- `options`: Optionally, the [gray-matter options](https://github.com/jonschlinkert/gray-matter/tree/a5726b04f3167fadc764241deb545518c454eb82#options) to use.
#### Return value
A file object with the same properties of a [gray-matter file object](https://github.com/jonschlinkert/gray-matter/tree/a5726b04f3167fadc764241deb545518c454eb82#returned-object) but with a `data` property of the type inferred from the given Zod schema.
If the front matter data is invalid, a [`ZodError`](https://github.com/colinhacks/zod/tree/master#error-handling) will be thrown.
### `stringify`
Stringify an object to YAML or a specified language, and append it to the given string.
```ts
import { stringify } from 'zod-matter'
import { z } from 'zod'
const content = stringify('# Hello world!', { author: 'HiDeoo' })
// ^? ---
// author: HiDeoo
// ---
// # Hello world!
```
This function is [re-exported](https://github.com/jonschlinkert/gray-matter/tree/a5726b04f3167fadc764241deb545518c454eb82#stringify) for convenience from gray-matter with the same signature.
### `test`
Checks if the given string contains a front matter.
```ts
import { test } from 'zod-matter'
import { z } from 'zod'
const containsFrontMatter = test('---\nauthor: HiDeoo\n---\n# Hello world!')
// ^? true
```
This function is [re-exported](https://github.com/jonschlinkert/gray-matter/tree/a5726b04f3167fadc764241deb545518c454eb82#test) for convenience from gray-matter with the same signature.
## License
Licensed under the MIT License, Copyright © HiDeoo.
See [LICENSE](https://github.com/HiDeoo/zod-matter/blob/main/LICENSE) for more information.
