From 3f42214833729ac89582f1df3be0595bddf2807d Mon Sep 17 00:00:00 2001 From: James Messinger Date: Sat, 29 Jun 2019 10:13:32 -0500 Subject: [PATCH 1/4] Corrected type definitions. Fixes #56 This PR corrects the TypeScript definitions to properly reflect the fact that Unified exports a CommonJS module rather than an ESM module. * Replaced incorrect `export default` syntax with `export =` * Wrapped all the TypeScript type definitions in a namespace --- types/index.d.ts | 403 ++++++++++++++++++++++++----------------------- 1 file changed, 203 insertions(+), 200 deletions(-) diff --git a/types/index.d.ts b/types/index.d.ts index 889ed68c..3fe4589c 100644 --- a/types/index.d.ts +++ b/types/index.d.ts @@ -1,219 +1,222 @@ // TypeScript Version: 3.0 -import {Node} from 'unist' +import { Node } from 'unist'; +import { VFile, VFileContents, VFileOptions } from 'vfile'; import vfile = require('vfile') -import {VFile, VFileOptions, VFileContents} from 'vfile' -export interface Processor { - /** - * @returns New unfrozen processor which is configured to function the same as its ancestor. But when the descendant processor is configured in the future it does not affect the ancestral processor. - */ - (): Processor - - /** - * Configure the processor to use a plugin and optionally configure that plugin with options. - * - * @param plugin unified plugin - * @param options Configuration for plugin] - * @returns The processor on which use is invoked - */ - use(plugin: Plugin, options?: unknown): Processor - /** - * @param preset `Object` with an optional plugins (set to list), and/or an optional settings object - */ - use(preset: Preset): Processor - /** - * @param pluginTuple pairs, plugin and options in an array - */ - use(pluginTuple: PluginTuple): Processor - /** - * @param list List of plugins, presets, and pairs - */ - use(list: PluggableList): Processor - - /** - * Parse text to a syntax tree. - * - * @param file VFile or anything which can be given to vfile() - * @returns Syntax tree representation of input. - */ - parse(file: VFileCompatible): Node - - /** - * Function handling the parsing of text to a syntax tree. - * Used in the parse phase in the process and invoked with a `string` and `VFile` representation of the document to parse. - * - * `Parser` can be a normal function in which case it must return a `Node`: the syntax tree representation of the given file. - * - * `Parser` can also be a constructor function (a function with keys in its `prototype`) in which case it’s invoked with `new`. Instances must have a parse method which is invoked without arguments and must return a `Node`. - */ - Parser: ParserFunction | typeof Parser - - /** - * Compile a syntax tree to text. - * - * @param node - * @param file `VFile` or anything which can be given to `vfile()` - * @returns String representation of the syntax tree file - */ - stringify(node: Node, file?: VFileCompatible): string - - /** - * Function handling the compilation of syntax tree to a text. - * Used in the stringify phase in the process and invoked with a `Node` and `VFile` representation of the document to stringify. - * - * `Compiler` can be a normal function in which case it must return a `string`: the text representation of the given syntax tree. - * - * `Compiler` can also be a constructor function (a function with keys in its `prototype`) in which case it’s invoked with `new`. - * Instances must have a `compile` method which is invoked without arguments and must return a `string`. - */ - Compiler: CompilerFunction | typeof Compiler - - /** - * Transform a syntax tree by applying plugins to it. - * - * @param node - * @param file `VFile` or anything which can be given to `vfile()` - * @param done Invoked when transformation is complete. - * Either invoked with an error or a syntax tree and a file. - * @returns `Promise` if `done` is not given. Rejected with an error, or resolved with the resulting syntax tree. - */ - run(node: Node): Promise - run(node: Node, file: VFileCompatible): Promise - run(node: Node, done: RunCallback): void - run(node: Node, file: VFileCompatible, done: RunCallback): void - - /** - * Transform a syntax tree by applying plugins to it. - * - * If asynchronous plugins are configured an error is thrown. +declare namespace unified { + interface Processor { + /** + * @returns New unfrozen processor which is configured to function the same as its ancestor. But when the descendant processor is configured in the future it does not affect the ancestral processor. + */ + (): Processor + + /** + * Configure the processor to use a plugin and optionally configure that plugin with options. + * + * @param plugin unified plugin + * @param options Configuration for plugin] + * @returns The processor on which use is invoked + */ + use(plugin: Plugin, options?: unknown): Processor + /** + * @param preset `Object` with an optional plugins (set to list), and/or an optional settings object + */ + use(preset: Preset): Processor + /** + * @param pluginTuple pairs, plugin and options in an array + */ + use(pluginTuple: PluginTuple): Processor + /** + * @param list List of plugins, presets, and pairs + */ + use(list: PluggableList): Processor + + /** + * Parse text to a syntax tree. + * + * @param file VFile or anything which can be given to vfile() + * @returns Syntax tree representation of input. + */ + parse(file: VFileCompatible): Node + + /** + * Function handling the parsing of text to a syntax tree. + * Used in the parse phase in the process and invoked with a `string` and `VFile` representation of the document to parse. + * + * `Parser` can be a normal function in which case it must return a `Node`: the syntax tree representation of the given file. + * + * `Parser` can also be a constructor function (a function with keys in its `prototype`) in which case it’s invoked with `new`. Instances must have a parse method which is invoked without arguments and must return a `Node`. + */ + Parser: ParserFunction | typeof Parser + + /** + * Compile a syntax tree to text. + * + * @param node + * @param file `VFile` or anything which can be given to `vfile()` + * @returns String representation of the syntax tree file + */ + stringify(node: Node, file?: VFileCompatible): string + + /** + * Function handling the compilation of syntax tree to a text. + * Used in the stringify phase in the process and invoked with a `Node` and `VFile` representation of the document to stringify. + * + * `Compiler` can be a normal function in which case it must return a `string`: the text representation of the given syntax tree. + * + * `Compiler` can also be a constructor function (a function with keys in its `prototype`) in which case it’s invoked with `new`. + * Instances must have a `compile` method which is invoked without arguments and must return a `string`. + */ + Compiler: CompilerFunction | typeof Compiler + + /** + * Transform a syntax tree by applying plugins to it. + * + * @param node + * @param file `VFile` or anything which can be given to `vfile()` + * @param done Invoked when transformation is complete. + * Either invoked with an error or a syntax tree and a file. + * @returns `Promise` if `done` is not given. Rejected with an error, or resolved with the resulting syntax tree. + */ + run(node: Node): Promise + run(node: Node, file: VFileCompatible): Promise + run(node: Node, done: RunCallback): void + run(node: Node, file: VFileCompatible, done: RunCallback): void + + /** + * Transform a syntax tree by applying plugins to it. + * + * If asynchronous plugins are configured an error is thrown. + * + * @param node + * @param file `VFile` or anything which can be given to `vfile()` + * @returns The given syntax tree. + */ + runSync(node: Node, file?: VFileCompatible): Node + + /** + * Process the given representation of a file as configured on the processor. The process invokes `parse`, `run`, and `stringify` internally. + * @param file + * @param done Invoked when the process is complete. Invoked with a fatal error, if any, and the VFile. + * @returns `Promise` if `done` is not given. + * Rejected with an error or resolved with the resulting file. + */ + process(file: VFileCompatible): Promise + process(file: VFileCompatible, done: ProcessCallback): void + + /** + * Process the given representation of a file as configured on the processor. The process invokes `parse`, `run`, and `stringify` internally. + * + * If asynchronous plugins are configured an error is thrown. + * + * @param file + * @returns Virtual file with modified contents. + */ + processSync(file: VFileCompatible): VFile + + /** + * Get or set information in an in-memory key-value store accessible to all phases of the process. + * An example is a list of HTML elements which are self-closing, which is needed when parsing, transforming, and compiling HTML. + * + * @returns key-value store object + */ + data(): {[key: string]: unknown} + /** + * @param key Identifier + * @returns If getting, the value at key + */ + data(key: string): unknown + /** + * @param value Value to set. Omit if getting key + * @returns If setting, the processor on which data is invoked + */ + data(key: string, value: any): Processor + + /** + * Freeze a processor. Frozen processors are meant to be extended and not to be configured or processed directly. + * + * Once a processor is frozen it cannot be unfrozen. New processors functioning just like it can be created by invoking the processor. + * + * It’s possible to freeze processors explicitly, by calling `.freeze()`, but `.parse()`, `.run()`, `.stringify()`, and `.process()` call `.freeze()` to freeze a processor too. + * + * @returns The processor on which freeze is invoked. + */ + freeze(): Processor + } + + type Plugin = Attacher + type Settings = { + [key: string]: unknown + } + /** + * Presets provide a potentially sharable way to configure processors. + * They can contain multiple plugins and optionally settings as well. + */ + interface Preset { + plugins?: PluggableList + settings?: Settings + } + type PluginTuple = [Plugin, Settings] + type Pluggable = Plugin | Preset | PluginTuple + type PluggableList = Pluggable[] + + /** + * An attacher is the thing passed to `use`. + * It configures the processor and in turn can receive options. + * + * Attachers can configure processors, such as by interacting with parsers and compilers, linking them to other processors, or by specifying how the syntax tree is handled. + * + * @this Processor context object is set to the invoked on processor. + * @param options Configuration + * @returns Optional. + */ + interface Attacher { + (this: Processor, options?: unknown): Transformer | void + } + + /** + * Transformers modify the syntax tree or metadata of a file. A transformer is a function which is invoked each time a file is passed through the transform phase. + * If an error occurs (either because it’s thrown, returned, rejected, or passed to `next`), the process stops. + * + * The transformation process in unified is handled by `trough`, see it’s documentation for the exact semantics of transformers. * * @param node - * @param file `VFile` or anything which can be given to `vfile()` - * @returns The given syntax tree. - */ - runSync(node: Node, file?: VFileCompatible): Node - - /** - * Process the given representation of a file as configured on the processor. The process invokes `parse`, `run`, and `stringify` internally. - * @param file - * @param done Invoked when the process is complete. Invoked with a fatal error, if any, and the VFile. - * @returns `Promise` if `done` is not given. - * Rejected with an error or resolved with the resulting file. - */ - process(file: VFileCompatible): Promise - process(file: VFileCompatible, done: ProcessCallback): void - - /** - * Process the given representation of a file as configured on the processor. The process invokes `parse`, `run`, and `stringify` internally. - * - * If asynchronous plugins are configured an error is thrown. - * * @param file - * @returns Virtual file with modified contents. - */ - processSync(file: VFileCompatible): VFile - - /** - * Get or set information in an in-memory key-value store accessible to all phases of the process. - * An example is a list of HTML elements which are self-closing, which is needed when parsing, transforming, and compiling HTML. - * - * @returns key-value store object - */ - data(): {[key: string]: unknown} - /** - * @param key Identifier - * @returns If getting, the value at key - */ - data(key: string): unknown - /** - * @param value Value to set. Omit if getting key - * @returns If setting, the processor on which data is invoked - */ - data(key: string, value: any): Processor - - /** - * Freeze a processor. Frozen processors are meant to be extended and not to be configured or processed directly. - * - * Once a processor is frozen it cannot be unfrozen. New processors functioning just like it can be created by invoking the processor. - * - * It’s possible to freeze processors explicitly, by calling `.freeze()`, but `.parse()`, `.run()`, `.stringify()`, and `.process()` call `.freeze()` to freeze a processor too. - * - * @returns The processor on which freeze is invoked. + * @param next If the signature of a transformer includes `next` (third argument), the function may finish asynchronous, and must invoke `next()`. + * @returns + * - `Error` — Can be returned to stop the process + * - `Node` — Can be returned and results in further transformations and `stringify`s to be performed on the new tree + * - `Promise` — If a promise is returned, the function is asynchronous, and must be resolved (optionally with a `Node`) or rejected (optionally with an `Error`) */ - freeze(): Processor -} + interface Transformer { + ( + node: Node, + file: VFileCompatible, + next?: (error: Error | null, tree: Node, file: VFile) => {} + ): Error | Node | Promise + } -export type Plugin = Attacher -export type Settings = { - [key: string]: unknown -} -/** - * Presets provide a potentially sharable way to configure processors. - * They can contain multiple plugins and optionally settings as well. - */ -export interface Preset { - plugins?: PluggableList - settings?: Settings -} -export type PluginTuple = [Plugin, Settings] -export type Pluggable = Plugin | Preset | PluginTuple -export type PluggableList = Pluggable[] + class Parser { + parse(file: VFileCompatible): Node + } -/** - * An attacher is the thing passed to `use`. - * It configures the processor and in turn can receive options. - * - * Attachers can configure processors, such as by interacting with parsers and compilers, linking them to other processors, or by specifying how the syntax tree is handled. - * - * @this Processor context object is set to the invoked on processor. - * @param options Configuration - * @returns Optional. - */ -export interface Attacher { - (this: Processor, options?: unknown): Transformer | void -} + type ParserFunction = (file: VFileCompatible) => Node -/** - * Transformers modify the syntax tree or metadata of a file. A transformer is a function which is invoked each time a file is passed through the transform phase. - * If an error occurs (either because it’s thrown, returned, rejected, or passed to `next`), the process stops. - * - * The transformation process in unified is handled by `trough`, see it’s documentation for the exact semantics of transformers. - * - * @param node - * @param file - * @param next If the signature of a transformer includes `next` (third argument), the function may finish asynchronous, and must invoke `next()`. - * @returns - * - `Error` — Can be returned to stop the process - * - `Node` — Can be returned and results in further transformations and `stringify`s to be performed on the new tree - * - `Promise` — If a promise is returned, the function is asynchronous, and must be resolved (optionally with a `Node`) or rejected (optionally with an `Error`) - */ -export interface Transformer { - ( - node: Node, - file: VFileCompatible, - next?: (error: Error | null, tree: Node, file: VFile) => {} - ): Error | Node | Promise -} + class Compiler { + compile(node: Node, file?: VFileCompatible): string + } + type CompilerFunction = (node: Node, file?: VFileCompatible) => string -export class Parser { - parse(file: VFileCompatible): Node -} + type RunCallback = (error: Error | null, node: Node, file: VFile) => void -export type ParserFunction = (file: VFileCompatible) => Node + type ProcessCallback = (error: Error | null, file: VFile) => void -export class Compiler { - compile(node: Node, file?: VFileCompatible): string + type VFileCompatible = VFile | VFileOptions | VFileContents } -export type CompilerFunction = (node: Node, file?: VFileCompatible) => string - -export type RunCallback = (error: Error | null, node: Node, file: VFile) => void - -export type ProcessCallback = (error: Error | null, file: VFile) => void - -export type VFileCompatible = VFile | VFileOptions | VFileContents /** * Object describing how to process text. */ -export default function unified(): Processor +declare function unified(): unified.Processor; +export = unified; From eb2ba7766ea9448b3d784546b6b175d5f5b9ccf8 Mon Sep 17 00:00:00 2001 From: James Messinger Date: Sat, 29 Jun 2019 10:31:03 -0500 Subject: [PATCH 2/4] removed semicolons --- types/index.d.ts | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/types/index.d.ts b/types/index.d.ts index 3fe4589c..03b12385 100644 --- a/types/index.d.ts +++ b/types/index.d.ts @@ -1,7 +1,7 @@ // TypeScript Version: 3.0 -import { Node } from 'unist'; -import { VFile, VFileContents, VFileOptions } from 'vfile'; +import {Node} from 'unist' +import {VFile, VFileContents, VFileOptions} from 'vfile' import vfile = require('vfile') declare namespace unified { @@ -218,5 +218,5 @@ declare namespace unified { /** * Object describing how to process text. */ -declare function unified(): unified.Processor; -export = unified; +declare function unified(): unified.Processor +export = unified From 07e47a72c753480c0366c78fbcb08337c68f4217 Mon Sep 17 00:00:00 2001 From: James Messinger Date: Sat, 29 Jun 2019 10:31:33 -0500 Subject: [PATCH 3/4] Removed the "esModuleInterop" setting, which was allowing incorrect type definitions to pass tests --- types/tsconfig.json | 1 - 1 file changed, 1 deletion(-) diff --git a/types/tsconfig.json b/types/tsconfig.json index 44ce2b21..54cfa008 100644 --- a/types/tsconfig.json +++ b/types/tsconfig.json @@ -6,7 +6,6 @@ "noImplicitThis": true, "strictNullChecks": true, "strictFunctionTypes": true, - "esModuleInterop": true, "baseUrl": ".", "paths": { "unified": ["index.d.ts"] From 896fb3f5605c426e0df12dd71c48b4f98e6789e8 Mon Sep 17 00:00:00 2001 From: James Messinger Date: Sat, 29 Jun 2019 10:32:06 -0500 Subject: [PATCH 4/4] Corrected the import syntax to use CommonJS imports rather than ESM imports --- types/unified-tests.ts | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/types/unified-tests.ts b/types/unified-tests.ts index a801efe9..35956f3d 100644 --- a/types/unified-tests.ts +++ b/types/unified-tests.ts @@ -1,12 +1,13 @@ import {Node} from 'unist' -import unified, { +import unified = require('unified') +import { Processor, Plugin, VFileCompatible, RunCallback, ProcessCallback } from 'unified' -import vfile from 'vfile' +import vfile = require('vfile') let fileValue: vfile.VFile let nodeValue: Node