Add returning data type of `matter` #183

New issue

Open

opened 2026-04-26 10:20:43 +00:00 by nninnnin · 0 comments

nninnnin commented

2026-04-26 10:20:43 +00:00

(Migrated from github.com)

Hello! firstly, I am really appreciate for your commitment. I have a suggestion for adding a new return type for the method matter.

Background

I am using gray-matter to parse markdown files for my blog posts like below.

const { data } = matter(raw);
const frontmatter = data as PostFrontmatter;

I found the type assertion feels queit guilty to rely on these manual assertions.

Suggestion

So I suggest a additional Generic paramter D which represents Data to explicitly define the shape of their frontmatter data, providing better type safety and a much smoother development experience.

// gray-matter.d.ts

declare function matter<
  I extends matter.Input,
  O extends matter.GrayMatterOption<I, O>,
  D extends matter.ParsedData = matter.ParsedData,
>(input: I | { content: I }, options?: O): matter.GrayMatterFile<I, D>;

declare namespace matter {
  ...
  type ParsedData = Record<string, any>;
  ...
}

Example

This would support better DX with auto completion and fully backward compatible.

import matter from "./gray-matter";

const input: string = `---
title: Hello World
date: 2024-01-01
tags:
  - typescript
  - gray-matter
---
This is the main content.

This is the second paragraph.
foo: 145
`;

const result = matter<
  string,
  any,
  {
    title: string;
    date: string;
    tags: string;
    foo: number;
  }
>(input);

// data properties are narrowed and available via IntelliSense
result.data.title;
result.data.date;
result.data.tags;
result.data.foo;

Hello! firstly, I am really appreciate for your commitment. I have a suggestion for adding a new return type for the method `matter`. ## Background I am using `gray-matter` to parse markdown files for my blog posts like below. ``` const { data } = matter(raw); const frontmatter = data as PostFrontmatter; ``` I found the type assertion feels queit guilty to rely on these manual assertions. ## Suggestion So I suggest a additional Generic paramter `D` which represents `Data` to explicitly define the shape of their frontmatter data, providing better type safety and a much smoother development experience. ```ts // gray-matter.d.ts declare function matter< I extends matter.Input, O extends matter.GrayMatterOption<I, O>, D extends matter.ParsedData = matter.ParsedData, >(input: I | { content: I }, options?: O): matter.GrayMatterFile<I, D>; declare namespace matter { ... type ParsedData = Record<string, any>; ... } ``` ## Example This would support better DX with auto completion and fully backward compatible. ```ts import matter from "./gray-matter"; const input: string = `--- title: Hello World date: 2024-01-01 tags: - typescript - gray-matter --- This is the main content. This is the second paragraph. foo: 145 `; const result = matter< string, any, { title: string; date: string; tags: string; foo: number; } >(input); // data properties are narrowed and available via IntelliSense result.data.title; result.data.date; result.data.tags; result.data.foo; ```