diff --git a/.gitignore b/.gitignore index b957bb5..a136532 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,4 @@ node_modules/ /lib/ /index.js yarn.lock +!dev/index.d.ts diff --git a/dev/index.d.ts b/dev/index.d.ts new file mode 100644 index 0000000..b52a5c2 --- /dev/null +++ b/dev/index.d.ts @@ -0,0 +1,100 @@ +export {frontmatterHtml} from './lib/html.js' +export {frontmatter} from './lib/syntax.js' +export {toMatters} from './lib/to-matters.js' + +/** + * Sequence. + * + * Depending on how this structure is used, it reflects a marker or a fence. + */ +export interface Info { + /** + * Closing. + */ + close: string + /** + * Opening. + */ + open: string +} + +/** + * Fence configuration. + */ +interface FenceFields { + /** + * Complete fences. + * + * This can be used when fences contain different characters or lengths + * other than 3. + * Pass `open` and `close` to interface to specify different characters for opening and + * closing fences. + */ + fence: Info | string + /** + * If `fence` is set, `marker` must not be set. + */ + marker?: never +} + +/** + * Marker configuration. + */ +interface MarkerFields { + /** + * Character repeated 3 times, used as complete fences. + * + * For example the character `'-'` will result in `'---'` being used as the + * fence + * Pass `open` and `close` to specify different characters for opening and + * closing fences. + */ + marker: Info | string + /** + * If `marker` is set, `fence` must not be set. + */ + fence?: never +} + +/** + * Fields describing a kind of matter. + */ +interface MatterFields { + /** + * Node type to tokenize as. + */ + type: string + /** + * Whether matter can be found anywhere in the document, normally, only matter + * at the start of the document is recognized. + * + * > πŸ‘‰ **Note**: using this is a terrible idea. + * > It’s called frontmatter, not matter-in-the-middle or so. + * > This makes your markdown less portable. + */ + anywhere?: boolean | null | undefined +} + +/** + * Fields describing a kind of matter. + * + * > πŸ‘‰ **Note**: using `anywhere` is a terrible idea. + * > It’s called frontmatter, not matter-in-the-middle or so. + * > This makes your markdown less portable. + * + * > πŸ‘‰ **Note**: `marker` and `fence` are mutually exclusive. + * > If `marker` is set, `fence` must not be set, and vice versa. + */ +export type Matter = + | (MatterFields & FenceFields) + | (MatterFields & MarkerFields) + +/** + * Configuration. + */ +export type Options = Matter | Preset | Array + +/** + * Known name of a frontmatter style. + */ +export type Preset = 'toml' | 'yaml' diff --git a/dev/index.js b/dev/index.js index c5ecadd..f34cad4 100644 --- a/dev/index.js +++ b/dev/index.js @@ -1,13 +1,4 @@ -/** - * @typedef {import('./lib/to-matters.js').Info} Info - * @typedef {import('./lib/to-matters.js').Matter} Matter - * @typedef {import('./lib/to-matters.js').Options} Options - * @typedef {import('./lib/to-matters.js').Preset} Preset - */ - +// Note: types exposed from `index.d.ts`. export {frontmatter} from './lib/syntax.js' export {frontmatterHtml} from './lib/html.js' export {toMatters} from './lib/to-matters.js' - -// Note: we don’t have an `index.d.ts` in this extension because all token -// types are dynamic in JS diff --git a/dev/lib/html.js b/dev/lib/html.js index b52a8fa..abc3b0b 100644 --- a/dev/lib/html.js +++ b/dev/lib/html.js @@ -1,9 +1,6 @@ /** - * @typedef {import('micromark-util-types').CompileContext} CompileContext - * @typedef {import('micromark-util-types').Handle} Handle - * @typedef {import('micromark-util-types').HtmlExtension} HtmlExtension - * @typedef {import('micromark-util-types').TokenType} TokenType - * @typedef {import('./to-matters.js').Options} Options + * @import {Options} from 'micromark-extension-frontmatter' + * @import {CompileContext, Handle, HtmlExtension, TokenType} from 'micromark-util-types' */ import {toMatters} from './to-matters.js' diff --git a/dev/lib/syntax.js b/dev/lib/syntax.js index 9a6411f..bfbcd53 100644 --- a/dev/lib/syntax.js +++ b/dev/lib/syntax.js @@ -1,15 +1,6 @@ /** - * @typedef {import('micromark-util-types').Construct} Construct - * @typedef {import('micromark-util-types').ConstructRecord} ConstructRecord - * @typedef {import('micromark-util-types').Extension} Extension - * @typedef {import('micromark-util-types').State} State - * @typedef {import('micromark-util-types').TokenType} TokenType - * @typedef {import('micromark-util-types').TokenizeContext} TokenizeContext - * @typedef {import('micromark-util-types').Tokenizer} Tokenizer - * - * @typedef {import('./to-matters.js').Info} Info - * @typedef {import('./to-matters.js').Matter} Matter - * @typedef {import('./to-matters.js').Options} Options + * @import {Info, Matter, Options} from 'micromark-extension-frontmatter' + * @import {Construct, ConstructRecord, Extension, State, TokenType, TokenizeContext, Tokenizer} from 'micromark-util-types' */ import {markdownLineEnding, markdownSpace} from 'micromark-util-character' diff --git a/dev/lib/to-matters.js b/dev/lib/to-matters.js index 55f795f..44ddab5 100644 --- a/dev/lib/to-matters.js +++ b/dev/lib/to-matters.js @@ -1,64 +1,5 @@ /** - * @typedef {'toml' | 'yaml'} Preset - * Known name of a frontmatter style. - * - * @typedef Info - * Sequence. - * - * Depending on how this structure is used, it reflects a marker or a fence. - * @property {string} close - * Closing. - * @property {string} open - * Opening. - * - * @typedef MatterProps - * Fields describing a kind of matter. - * @property {string} type - * Node type to tokenize as. - * @property {boolean | null | undefined} [anywhere=false] - * Whether matter can be found anywhere in the document, normally, only matter - * at the start of the document is recognized. - * - * > πŸ‘‰ **Note**: using this is a terrible idea. - * > It’s called frontmatter, not matter-in-the-middle or so. - * > This makes your markdown less portable. - * - * @typedef MarkerProps - * Marker configuration. - * @property {Info | string} marker - * Character repeated 3 times, used as complete fences. - * - * For example the character `'-'` will result in `'---'` being used as the - * fence - * Pass `open` and `close` to specify different characters for opening and - * closing fences. - * @property {never} [fence] - * If `marker` is set, `fence` must not be set. - * - * @typedef FenceProps - * Fence configuration. - * @property {Info | string} fence - * Complete fences. - * - * This can be used when fences contain different characters or lengths - * other than 3. - * Pass `open` and `close` to interface to specify different characters for opening and - * closing fences. - * @property {never} [marker] - * If `fence` is set, `marker` must not be set. - * - * @typedef {(MatterProps & FenceProps) | (MatterProps & MarkerProps)} Matter - * Fields describing a kind of matter. - * - * > πŸ‘‰ **Note**: using `anywhere` is a terrible idea. - * > It’s called frontmatter, not matter-in-the-middle or so. - * > This makes your markdown less portable. - * - * > πŸ‘‰ **Note**: `marker` and `fence` are mutually exclusive. - * > If `marker` is set, `fence` must not be set, and vice versa. - * - * @typedef {Matter | Preset | Array} Options - * Configuration. + * @import {Matter, Options, Preset} from 'micromark-extension-frontmatter' */ import {fault} from 'fault' diff --git a/package.json b/package.json index cff9558..dab8b81 100644 --- a/package.json +++ b/package.json @@ -83,6 +83,31 @@ "strict": true }, "xo": { + "overrides": [ + { + "files": [ + "**/*.d.ts" + ], + "rules": { + "@typescript-eslint/array-type": [ + "error", + { + "default": "generic" + } + ], + "@typescript-eslint/ban-types": [ + "error", + { + "extendDefaults": true + } + ], + "@typescript-eslint/consistent-type-definitions": [ + "error", + "interface" + ] + } + } + ], "prettier": true, "rules": { "unicorn/no-this-assignment": "off", diff --git a/test/index.js b/test/index.js index 06af15b..92b2498 100644 --- a/test/index.js +++ b/test/index.js @@ -1,5 +1,5 @@ /** - * @typedef {import('micromark-extension-frontmatter').Options} Options + * @import {Options} from 'micromark-extension-frontmatter' */ import assert from 'node:assert/strict' diff --git a/tsconfig.json b/tsconfig.json index 241c4e6..e82ed5a 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -11,5 +11,5 @@ "target": "es2022" }, "exclude": ["coverage/", "lib/", "node_modules/", "index.js"], - "include": ["**/*.js"] + "include": ["**/*.js", "dev/index.d.ts"] }