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

loqusion commented

2024-01-14 06:41:14 +00:00

(Migrated from github.com)

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.

The return value is not used, _[at](https://github.com/jonschlinkert/gray-matter/blob/ce67a86dba419381db0dd01cc84e2d30a1d1e6a5/lib/excerpt.js#L13C13-L13C13) [all](https://github.com/jonschlinkert/gray-matter/blob/ce67a86dba419381db0dd01cc84e2d30a1d1e6a5/index.js#L125)_, despite what the function's type signature [would have you believe](https://github.com/jonschlinkert/gray-matter/blob/ce67a86dba419381db0dd01cc84e2d30a1d1e6a5/gray-matter.d.ts#L29). Instead, you're expected to assign the `excerpt` field to its first argument like so: ```typescript 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 commented

2024-02-04 11:38:18 +00:00

(Migrated from github.com)

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?

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 ```typescript excerpt?: boolean | ((file: GrayMatterFile<I>, options: O) => void) ``` Should I make a PR?

loqusion commented

2024-02-04 20:12:10 +00:00

(Migrated from github.com)

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:

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
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).
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.

> It should be something like > > ```typescript > 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](https://github.com/jonschlinkert/gray-matter/blob/ce67a86dba419381db0dd01cc84e2d30a1d1e6a5/lib/excerpt.js#L25-L29) 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](https://en.wikipedia.org/wiki/Inode) 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](https://github.com/jonschlinkert/gray-matter/blob/ce67a86dba419381db0dd01cc84e2d30a1d1e6a5/gray-matter.d.ts#L40-L46) 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`](https://nodejs.org/api/buffer.html). (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 commented

2024-02-04 21:32:27 +00:00

(Migrated from github.com)

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),
  })
}

Here's a (relatively) sane wrapper for `graymatter` taken straight from the source code for [my website](https://loqusion.dev/): ```typescript 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 commented

2024-02-05 06:39:35 +00:00

(Migrated from github.com)

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

// @ts-ignore

How about if I just ignore that one line causing the whole lot this trouble. ```ts // @ts-ignore ```

loqusion commented

2024-02-05 06:43:00 +00:00

(Migrated from github.com)

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.

> How about if I just ignore that one line causing the whole lot this trouble. > > ```ts > > // @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.

🚀 1

Rows
Columns

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

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