[feat] type safe configurations?

[JounQin]

Initial checklist

• I read the support docs
• I read the contributing guide
• I agree to follow the code of conduct
• I searched issues and discussions and couldn’t find anything (or linked relevant results below)

Problem

It's not clear how to write type safe configurations like:

import validateLinks from 'remark-validate-links'

export default {
  plugins: [[validateLinks, 2]], // how to infer type of `Options` from `validateLinks` here
}

Current solutions

N/A

Proposed solutions

// @ts-check

/** @import { Config } from 'remark' */

/** @type { Config } */
export default {}

[ChristianMurphy]

I think documenting the type annotation would be great!
Maybe in the unified guides? https://unifiedjs.com/learn/

Though a caveat, the example you shared with an array in an array will not be able to strongly check plugin settings.
Getting that to type checker is tricky, see the last two attempts at getting that to work
unifiedjs/unified#92
unifiedjs/unified#96

Fresh ideas on how to make it work are welcome.
It's rather complex given plugins can have more than one settings.

[wooorm]

TS is bad at arrays, and also bad at even more complex things. I don’t think some Config type is possible.
If you want to type check things, I think you’re better off doing things like 2 satisfies Options, where each Options comes from the plugin.
Or, use PluginTuple from unified, something along the lines of PluginTuple<[Options]> on the array that you pass may work?

[remcohaszing]

Types in arrays are complex indeed. We might be able to get better results with a defineConfig function instead of a type annotation. That allows us to get inference.

import { defineConfig } from 'remark-cli'
import validateLinks from 'remark-validate-links'

export default defineConfig({
  plugins: [
    [validateLinks, 2]
  ]
})

Alternatively we can come up with an alternative plugin format. If the user passes options to a function call, we don’t have to think about its type safety. For example

// my-plugin.js
/**
 * @import { Root } from 'mdast'
 * @import { PluginObject } from 'unified'
 */

/**
 * @returns {PluginObject<Root>}
 */
export default function myPlugin(options) {
  return {
    setup(processor) {
      // Use `processor` instead of the old `this`
    },

    transform(ast, file) {
      // Old transform logic
    }
  }
}

// .remarkrc.js
import myPlugin from './my-plugin.js'

export default {
  plugins: [
    myPlugins({
      // Options go here.
    })
  ]
}

I do think it’s very important to think of backwards compatibility with existing plugins.

[wooorm]

That allows us to get inference.

How would a function call, which has some type parameter X to check a passed parameter, be better than a user applying the type X to the parameter which would be passed? Isn’t it identical?

If the user passes options to a function call, we don’t have to think about its type safety.

First off, indeed, how to differentiate between those and the regular plugins that exist?
Second, the main point of having arrays is so that users can do ['some-plugin', {some: 'options'}], as in, that these configs can exist in JSON/YAML/etc, without functions.

---

I just checked and this works and I think it’s fine?

/**
 * @import {Options} from 'remark-validate-links'
 */

import remarkValidateLinks from 'remark-validate-links'

const config = {
  plugins: [
    [remarkValidateLinks, /** @type {Options} */ ({repository: 'example/example'})],
  ]
}

export default config

[wooorm]

one important caveat with what remco proposes is that it cannot support deduplication of plugins. Which becomes a real problem with presets