Feedback for new APIs

[azu]

This discussion welcome to feedback for textlint's new APIs.
Feedback is welcome, especially from users who use textlint as a module, as it will need to be changed in the future.

textlint 12.3.0 support a rule that is written as ECMAScript Modules.

• https://github.com/textlint/textlint/releases/tag/v12.3.0

require can not load ESM, we need to use import() for loading ESM modules.
Current TextLintCore/TextFixEngine/TextLintEngine use require to load modules.
As a result, TextLintCore/TextFixEngine/TextLintEngine can not support ESM without Breaking Changes.

Old APIs and New APIs

We have introduced new API like createLinter for supporting Async APIs.
v13 continue to support current TextlintCore, TextLintEngine and TextFixEngine for backward compatible.
However, These API will be retired in the future.

• textlint v13 roadmap #902

New createLinter and loadTextlintrc supports ESM rules/plugins.
textlint modules user should use these instead of TextlintCore, TextLintEngine and TextFixEngine.

ℹ️ Timeline:

• textlint v12.3.0 support old APIs(deprecated) and new APIs
  • use old APIs as default
• textlint v13.0.0 support old APIs(deprecated) and new APIs
  • use new APIs as default
  • textlint v13 roadmap #902
• textlint v14? drop to support old APIs

API	Description	Behavior	Target Platform	Prev Status	Next Status
cli	Command LIne Interface	Async	Node.js	✅	✅ (Use createLinter and loadTextlintrc internally)
textlint	TextLintCore alias	Async	Node.js/CommonJS	❌ Deprecated	❌ Deprecated
TextLintCore	Old API. It is Procedural API. Lint Only Single File. Recommended to use @texltint/kernel module instead of It.	Async	Node.js/CommonJS	❌ Deprecated	❌ Deprecated
TextLintEngine	Lint Engine API. It load .textlintrc automaticaly	◉ Loading is Sync ◉ Linting is Async	Node.js/CommonJS	✅ Recommended	❌ Deprecated
TextFixEngine	Fix Engine API. It load .textlintrc automaticaly	◉ Loading is Sync ◉ Fixing is Async	Node.js/CommonJS	✅ Recommended	❌ Deprecated
createLinter/loadTextlintrc	Support Async APIs.	◉ Loading is Async ◉ Linting/Fixing is Async	Node.js/CommonJS and ESM	None	✅ Recommended

New APIs

textlint v12.3.0 introduce new APIs.
textlint will drop support old APIs(textlint, TextLintEngine, TextFixEngine, and TextLintCore) in the future.

📝 old APIs can not support ECMAScript modules, new APIs support ECMAScript modules.

• createLinter: create linter instance
  • lintFiles(files): Promise<TextlintResult[]>: lint files and return linter messages
  • lintText(text, filePath): Promise<TextlintResult> lint text with virtual filePath and return linter messages
  • fixFiles(files): Promise<TextlintFixResult[]> lint text and return fixer messages
  • fixText(text, filePath): Promise<TextlintFixResult> lint text with virtual filePath and return fixer messages
    • fixFiles and fixText does not modify files
• loadTextlintrc: load .textlintrc config file and return a descriptor object
• loadLinerFormatter and loadFixerFormatter: load formatter

Examples

Lint files and output to console.

import { createLinter, loadTextlintrc, loadLinterFormatter } from "textlint";
// descriptor is a structure object for linter
// It includes rules, plugins, and options
const descriptor = await loadTextlintrc();
const linter = createLinter({
    descriptor
});
const results = await linter.lintFiles(["*.md"]);
// textlint has two types formatter sets for linter and fixer
const formatter = await loadLinterFormatter({ formatterName: "stylish" })
const output = formatter.format(results);
console.log(output);

Fix text and get the fixed text.

import { createLinter, loadTextlintrc, loadFixerFormatter } from "textlint";
// descriptor is a structure object for linter
// It includes rules, plugins, and options
const descriptor = await loadTextlintrc();
const linter = createLinter({
    descriptor
});
const result = await linter.fixText("TODO: fix me");
console.log(result.output); // fixed result

Add custom rules and plugins.
If you not want to load .textlintrc, you can use just @textlint/kernel.

import { createLinter, loadTextlintrc } from "textlint";
import { TextlintKernelDescriptor } from "@textlint/kernel";
import { moduleInterop } from "@textlint/module-interop";
// Create a descriptor for custom rules and plugins
const customDescriptor = new TextlintKernelDescriptor({
    rules: [
        {
            ruleId: "custom-rule",
            rule: moduleInterop((await import("./custom-plugin")).default)
        }
    ],
    plugins: [
        {
            pluginId: "custom-plugin",
            plugin: moduleInterop((await import("./custom-plugin")).default)
        }
    ]
});
const textlintrcDescriptor = await loadTextlintrc();
const linter = createLinter({
    // merge customDescriptor and textlintrcDescriptor
    // if same ruleId or pluginId, customDescriptor is used.
    descriptor: customDescriptor.concat(textlintrcDescriptor)
});
const result = await linter.lintText("TODO: fix me");
console.log(result);

Get lintable file extensions.
textlintrcDescriptor.availableExtensions provide a list of supported file extensions.

import { createLinter, loadTextlintrc } from "textlint";
const textlintrcDescriptor = await loadTextlintrc();
const availableExtensions = textlintrcDescriptor.availableExtensions;
console.log(availableExtensions); // => [".md", ".txt"]

For more details, see https://textlint.github.io/docs/use-as-modules.html

Notes

Probably, You can replace TextlintCore, TextLintEngine and TextFixEngine with new APIs.
If there are missing parts, please report me.

[azu]

I mention to textlint package user.

markuplint cc @YusukeHirao @JounQin

• https://github.com/markuplint/markuplint/blob/67ebfc5a3bb6aa23124ba0455012749389b5ab8a/packages/%40markuplint/rule-textlint/src/verify.ts

vscode-textlint cc @taichi

• https://github.com/taichi/vscode-textlint/blob/7f73c80084c8c80b91ec59612746ac717ae41785/packages/textlint-server/src/server.ts#L77-L94

[azu]

@taichi I've created a PR
taichi/vscode-textlint#63

[azu]

We have released textlint v13!

• Release v13.0.0 · textlint/textlint
• textlint v13.0.0 · textlint

textlint v13 use new APIs by default.
Old API is still exists, but these will be removed in next major updates.

[azu]

I've rewritten html plugin as Pure ESM.

• Release v1.0.0 · textlint/textlint-plugin-html