From c33a6406b83566328e61a71e39fd38be8ef87659 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Fri, 5 Jul 2024 17:29:27 +0200 Subject: [PATCH] Refactor to use `@import`s --- dev/index.d.ts | 100 +++++++++++++++++++++++++++++---- dev/lib/directive-container.js | 6 +- dev/lib/directive-leaf.js | 5 +- dev/lib/directive-text.js | 6 +- dev/lib/factory-attributes.js | 5 +- dev/lib/factory-label.js | 5 +- dev/lib/factory-name.js | 5 +- dev/lib/html.js | 75 ++++++------------------- dev/lib/syntax.js | 2 +- package.json | 23 +++++++- readme.md | 9 ++- test/index.js | 5 +- 12 files changed, 141 insertions(+), 105 deletions(-) diff --git a/dev/index.d.ts b/dev/index.d.ts index c067855..b5bac9f 100644 --- a/dev/index.d.ts +++ b/dev/index.d.ts @@ -1,14 +1,95 @@ -import type {Attribute, Directive} from './lib/html.js' +import type {CompileContext} from 'micromark-util-types' export {directive} from './lib/syntax.js' -export { - directiveHtml, - type Directive, - type Handle, - type HtmlOptions -} from './lib/html.js' +export {directiveHtml} from './lib/html.js' +/** + * Internal tuple representing an attribute. + */ +type AttributeTuple = [key: string, value: string] + +/** + * Directive attribute. + */ +interface Attributes { + /** + * Key to value. + */ + [key: string]: string +} + +/** + * Structure representing a directive. + */ +export interface Directive { + /** + * Private :) + */ + _fenceCount?: number | undefined + /** + * Object w/ HTML attributes. + */ + attributes?: Attributes | undefined + /** + * Compiled HTML content inside container directive. + */ + content?: string | undefined + /** + * Compiled HTML content that was in `[brackets]`. + */ + label?: string | undefined + /** + * Name of directive. + */ + name: string + /** + * Kind. + */ + type: 'containerDirective' | 'leafDirective' | 'textDirective' +} + +/** + * Handle a directive. + * + * @param this + * Current context. + * @param directive + * Directive. + * @returns + * Signal whether the directive was handled. + * + * Yield `false` to let the fallback (a special handle for `'*'`) handle it. + */ +export type Handle = ( + this: CompileContext, + directive: Directive +) => boolean | undefined + +/** + * Configuration. + * + * > πŸ‘‰ **Note**: the special field `'*'` can be used to specify a fallback + * > handle to handle all otherwise unhandled directives. + */ +export interface HtmlOptions { + [name: string]: Handle +} + +/** + * Augment types. + */ declare module 'micromark-util-types' { + /** + * Compile data. + */ + interface CompileData { + directiveAttributes?: Array + directiveStack?: Array + } + + /** + * Token types. + */ interface TokenTypeMap { directiveContainer: 'directiveContainer' directiveContainerAttributes: 'directiveContainerAttributes' @@ -72,9 +153,4 @@ declare module 'micromark-util-types' { directiveTextMarker: 'directiveTextMarker' directiveTextName: 'directiveTextName' } - - interface CompileData { - directiveAttributes?: Attribute[] - directiveStack?: Directive[] - } } diff --git a/dev/lib/directive-container.js b/dev/lib/directive-container.js index ca4f540..76114c3 100644 --- a/dev/lib/directive-container.js +++ b/dev/lib/directive-container.js @@ -1,9 +1,5 @@ /** - * @typedef {import('micromark-util-types').Construct} Construct - * @typedef {import('micromark-util-types').State} State - * @typedef {import('micromark-util-types').Token} Token - * @typedef {import('micromark-util-types').TokenizeContext} TokenizeContext - * @typedef {import('micromark-util-types').Tokenizer} Tokenizer + * @import {Construct, State, Token, TokenizeContext, Tokenizer} from 'micromark-util-types' */ import {ok as assert} from 'devlop' diff --git a/dev/lib/directive-leaf.js b/dev/lib/directive-leaf.js index 26acc87..cdab758 100644 --- a/dev/lib/directive-leaf.js +++ b/dev/lib/directive-leaf.js @@ -1,8 +1,5 @@ /** - * @typedef {import('micromark-util-types').Construct} Construct - * @typedef {import('micromark-util-types').State} State - * @typedef {import('micromark-util-types').TokenizeContext} TokenizeContext - * @typedef {import('micromark-util-types').Tokenizer} Tokenizer + * @import {Construct, State, TokenizeContext, Tokenizer} from 'micromark-util-types' */ import {ok as assert} from 'devlop' diff --git a/dev/lib/directive-text.js b/dev/lib/directive-text.js index bbf1aad..38f9260 100644 --- a/dev/lib/directive-text.js +++ b/dev/lib/directive-text.js @@ -1,9 +1,5 @@ /** - * @typedef {import('micromark-util-types').Construct} Construct - * @typedef {import('micromark-util-types').Previous} Previous - * @typedef {import('micromark-util-types').State} State - * @typedef {import('micromark-util-types').TokenizeContext} TokenizeContext - * @typedef {import('micromark-util-types').Tokenizer} Tokenizer + * @import {Construct, Previous, State, TokenizeContext, Tokenizer} from 'micromark-util-types' */ import {ok as assert} from 'devlop' diff --git a/dev/lib/factory-attributes.js b/dev/lib/factory-attributes.js index 01f5065..472c963 100644 --- a/dev/lib/factory-attributes.js +++ b/dev/lib/factory-attributes.js @@ -1,8 +1,5 @@ /** - * @typedef {import('micromark-util-types').Code} Code - * @typedef {import('micromark-util-types').Effects} Effects - * @typedef {import('micromark-util-types').State} State - * @typedef {import('micromark-util-types').TokenType} TokenType + * @import {Code, Effects, State, TokenType} from 'micromark-util-types' */ import {ok as assert} from 'devlop' diff --git a/dev/lib/factory-label.js b/dev/lib/factory-label.js index c8a434d..3e795a2 100644 --- a/dev/lib/factory-label.js +++ b/dev/lib/factory-label.js @@ -1,8 +1,5 @@ /** - * @typedef {import('micromark-util-types').Effects} Effects - * @typedef {import('micromark-util-types').State} State - * @typedef {import('micromark-util-types').Token} Token - * @typedef {import('micromark-util-types').TokenType} TokenType + * @import {Code, Effects, State, Token, TokenType} from 'micromark-util-types' */ import {ok as assert} from 'devlop' diff --git a/dev/lib/factory-name.js b/dev/lib/factory-name.js index bab07a4..97acae1 100644 --- a/dev/lib/factory-name.js +++ b/dev/lib/factory-name.js @@ -1,8 +1,5 @@ /** - * @typedef {import('micromark-util-types').Effects} Effects - * @typedef {import('micromark-util-types').State} State - * @typedef {import('micromark-util-types').TokenizeContext} TokenizeContext - * @typedef {import('micromark-util-types').TokenType} TokenType + * @import {Code, Effects, State, TokenizeContext, TokenType} from 'micromark-util-types' */ import {asciiAlpha, asciiAlphanumeric} from 'micromark-util-character' diff --git a/dev/lib/html.js b/dev/lib/html.js index b81c89c..14c60e5 100644 --- a/dev/lib/html.js +++ b/dev/lib/html.js @@ -1,49 +1,6 @@ /** - * @typedef {import('micromark-util-types').CompileContext} CompileContext - * @typedef {import('micromark-util-types').Handle} _Handle - * @typedef {import('micromark-util-types').HtmlExtension} HtmlExtension - */ - -/** - * @typedef {[string, string]} Attribute - * Internal tuple representing an attribute. - */ - -/** - * @typedef {Record} HtmlOptions - * Configuration. - * - * > πŸ‘‰ **Note**: the special field `'*'` can be used to specify a fallback - * > handle to handle all otherwise unhandled directives. - * - * @callback Handle - * Handle a directive. - * @param {CompileContext} this - * Current context. - * @param {Directive} directive - * Directive. - * @returns {boolean | undefined} - * Signal whether the directive was handled. - * - * Yield `false` to let the fallback (a special handle for `'*'`) handle it. - * - * @typedef Directive - * Structure representing a directive. - * @property {DirectiveType} type - * Kind. - * @property {string} name - * Name of directive. - * @property {string | undefined} [label] - * Compiled HTML content that was in `[brackets]`. - * @property {Record | undefined} [attributes] - * Object w/ HTML attributes. - * @property {string | undefined} [content] - * Compiled HTML content inside container directive. - * @property {number | undefined} [_fenceCount] - * Private :) - * - * @typedef {'containerDirective' | 'leafDirective' | 'textDirective'} DirectiveType - * Kind. + * @import {Directive, HtmlOptions} from 'micromark-extension-directive' + * @import {CompileContext, Handle as MicromarkHandle, HtmlExtension} from 'micromark-util-types' */ import {ok as assert} from 'devlop' @@ -120,7 +77,7 @@ export function directiveHtml(options) { /** * @this {CompileContext} - * @param {DirectiveType} type + * @param {Directive['type']} type */ function enter(type) { let stack = this.getData('directiveStack') @@ -130,7 +87,7 @@ export function directiveHtml(options) { /** * @this {CompileContext} - * @type {_Handle} + * @type {MicromarkHandle} */ function exitName(token) { const stack = this.getData('directiveStack') @@ -140,7 +97,7 @@ export function directiveHtml(options) { /** * @this {CompileContext} - * @type {_Handle} + * @type {MicromarkHandle} */ function enterLabel() { this.buffer() @@ -148,7 +105,7 @@ export function directiveHtml(options) { /** * @this {CompileContext} - * @type {_Handle} + * @type {MicromarkHandle} */ function exitLabel() { const data = this.resume() @@ -159,7 +116,7 @@ export function directiveHtml(options) { /** * @this {CompileContext} - * @type {_Handle} + * @type {MicromarkHandle} */ function enterAttributes() { this.buffer() @@ -168,7 +125,7 @@ export function directiveHtml(options) { /** * @this {CompileContext} - * @type {_Handle} + * @type {MicromarkHandle} */ function exitAttributeIdValue(token) { const attributes = this.getData('directiveAttributes') @@ -183,7 +140,7 @@ export function directiveHtml(options) { /** * @this {CompileContext} - * @type {_Handle} + * @type {MicromarkHandle} */ function exitAttributeClassValue(token) { const attributes = this.getData('directiveAttributes') @@ -199,7 +156,7 @@ export function directiveHtml(options) { /** * @this {CompileContext} - * @type {_Handle} + * @type {MicromarkHandle} */ function exitAttributeName(token) { // Attribute names in CommonMark are significantly limited, so character @@ -212,7 +169,7 @@ export function directiveHtml(options) { /** * @this {CompileContext} - * @type {_Handle} + * @type {MicromarkHandle} */ function exitAttributeValue(token) { const attributes = this.getData('directiveAttributes') @@ -225,14 +182,14 @@ export function directiveHtml(options) { /** * @this {CompileContext} - * @type {_Handle} + * @type {MicromarkHandle} */ function exitAttributes() { const stack = this.getData('directiveStack') assert(stack, 'expected directive stack') const attributes = this.getData('directiveAttributes') assert(attributes, 'expected attributes') - /** @type {Directive['attributes']} */ + /** @type {Record} */ const cleaned = {} let index = -1 @@ -253,7 +210,7 @@ export function directiveHtml(options) { /** * @this {CompileContext} - * @type {_Handle} + * @type {MicromarkHandle} */ function exitContainerContent() { const data = this.resume() @@ -264,7 +221,7 @@ export function directiveHtml(options) { /** * @this {CompileContext} - * @type {_Handle} + * @type {MicromarkHandle} */ function exitContainerFence() { const stack = this.getData('directiveStack') @@ -277,7 +234,7 @@ export function directiveHtml(options) { /** * @this {CompileContext} - * @type {_Handle} + * @type {MicromarkHandle} */ function exit() { const stack = this.getData('directiveStack') diff --git a/dev/lib/syntax.js b/dev/lib/syntax.js index 1c1843d..627fc19 100644 --- a/dev/lib/syntax.js +++ b/dev/lib/syntax.js @@ -1,5 +1,5 @@ /** - * @typedef {import('micromark-util-types').Extension} Extension + * @import {Extension} from 'micromark-util-types' */ import {codes} from 'micromark-util-symbol' diff --git a/package.json b/package.json index cc6d07b..d057efe 100644 --- a/package.json +++ b/package.json @@ -90,10 +90,29 @@ "overrides": [ { "files": [ - "**/*.ts" + "**/*.d.ts" ], "rules": { - "@typescript-eslint/consistent-type-definitions": "off" + "@typescript-eslint/array-type": [ + "error", + { + "default": "generic" + } + ], + "@typescript-eslint/ban-types": [ + "error", + { + "extendDefaults": true + } + ], + "@typescript-eslint/consistent-indexed-object-style": [ + "error", + "index-signature" + ], + "@typescript-eslint/consistent-type-definitions": [ + "error", + "interface" + ] } } ], diff --git a/readme.md b/readme.md index 7e69d9f..f333822 100644 --- a/readme.md +++ b/readme.md @@ -90,6 +90,11 @@ A lovely language know as :abbr[HTML]{title="HyperText Markup Language"}. …and our module `example.js` looks as follows: ```js +/** + * @import {Handle} from 'micromark-extension-directive' + * @import {CompileContext} from 'micromark-util-types' + */ + import fs from 'node:fs/promises' import {micromark} from 'micromark' import {directive, directiveHtml} from 'micromark-extension-directive' @@ -102,8 +107,8 @@ const output = micromark(await fs.readFile('example.md'), { console.log(output) /** - * @this {import('micromark-util-types').CompileContext} - * @type {import('micromark-extension-directive').Handle} + * @this {CompileContext} + * @type {Handle} * @returns {undefined} */ function abbr(d) { diff --git a/test/index.js b/test/index.js index fd6baf6..648ef29 100644 --- a/test/index.js +++ b/test/index.js @@ -1,7 +1,6 @@ /** - * @typedef {import('micromark-util-types').CompileContext} CompileContext - * @typedef {import('micromark-extension-directive').HtmlOptions} HtmlOptions - * @typedef {import('micromark-extension-directive').Handle} Handle + * @import {Handle, HtmlOptions} from 'micromark-extension-directive' + * @import {CompileContext} from 'micromark-util-types' */ import assert from 'node:assert/strict'