The `excerpt` function option should be a function that returns a string, but it isn't

[loqusion]

The return value is not used, at all, despite what the function's type signature would have you believe. Instead, you're expected to assign the excerpt field to its first argument like so:

function firstFourLines(input: UnspecifiedObject, options: GrayMatterOption): void {
  input.excerpt = input.content.split('\n').slice(0, 4).join(' ');
}

const { data } = graymatter(file, { excerpt: firstFourLines })

This is extremely easy to miss, and had me banging my head against the wall for hours. Hopefully this will help somebody with the foresight to check the GitHub issues.

[DarhkVoyd]

I have been at it since hours and still couldn't fix it. I believe the signature for the excerpt function is incorrect. It should be something like

excerpt?: boolean | ((file: GrayMatterFile<I>, options: O) => void)

Should I make a PR?

[loqusion]

It should be something like

excerpt?: boolean | ((file: GrayMatterFile<I>, options: O) => void)

@DarhkVoyd That would likely be the best change to make that's consistent with the real function signature. However there are a couple of flaws with the real function signature:

1. It would be more intuitive for excerpt (optional field) to be a union of:
   1. boolean — if true, the default "extract excerpt" implementation would be used
   2. Function returning a string — overrides default "extract excerpt" implementation
   3. string — for backwards compatibility (until a major version is released) since the current implementation interprets a string excerpt like excerpt_separator
2. The name GrayMatterFile is confusing since it implies some strong correlation with a file-system object but there is no correlation to speak of. It's really just an ad hoc global state dictionary being passed around between functions. And most of its fields aren't even necessary for finding excerpt.
   1. In the first place, input (i.e. the first argument of the excerpt function type) should probably be something like a string or Buffer. (This would be a backwards incompatible change which should only be made on a major release).
3. The idea of relying on argument mutability as a public interface is dubious in the majority of cases.

To be clear, the existing TypeScript annotations are fine on their own; it's the implementation that needs to match.

Should I make a PR?

Probably not. Despite numerous issues and PRs, there hasn't been a significant change to this repository in over 5 years, so you'd probably be wasting your time. I don't blame the author since lack of monetizability in open source is a serious issue and they probably have better things to do with their time.

[loqusion]

Here's a (relatively) sane wrapper for graymatter taken straight from the source code for my website:

import type { GrayMatterFile, GrayMatterOption } from 'gray-matter'
import graymatter_ from 'gray-matter'

type GrayMatterOptions = GrayMatterOption<
  string | Buffer,
  GrayMatterOption<string | Buffer, any>
>

export type ExtractExcerptFn = (
  input: string | Buffer,
  options: GrayMatterOptions,
) => string

function graymatterInputToStringOrBuffer(
  input: GrayMatterFile<string | Buffer>,
): string | Buffer {
  if (typeof input !== 'object' || input === null) {
    throw new Error(
      `Expected input to be an object; received ${JSON.stringify(input)}`,
    )
  }
  if (!('content' in input)) {
    throw new Error('Expected "content" property in input object')
  }
  return input.content
}

function saneExcerptWrapper(
  excerpt: boolean | ExtractExcerptFn | undefined,
): NonNullable<GrayMatterOptions>['excerpt'] {
  if (typeof excerpt !== 'function') {
    return excerpt
  }
  return ((input, options) => {
    ;(input as any).excerpt = (excerpt as ExtractExcerptFn)(
      graymatterInputToStringOrBuffer(input as any),
      options,
    )
  }) as typeof excerpt
}

export default function graymatter<
  I extends string | Buffer,
  O extends GrayMatterOption<I, O>,
>(input: I, options?: O): GrayMatterFile<I> {
  return graymatter_(input, {
    ...options,
    excerpt: saneExcerptWrapper(options?.excerpt),
  })
}

[DarhkVoyd]

How about if I just ignore that one line causing the whole lot this trouble.

// @ts-ignore

[loqusion]

How about if I just ignore that one line causing the whole lot this trouble.

// @ts-ignore

They're both band-aids over a gaping wound. If that's the band-aid you prefer, then that's fine. As long as you can remember that the TypeScript function signature is a lie.