Update to use named exports via / /async /promise /sync, simplify references via self-referencing, refine examples.

Author: DavidAnson

Diff for: README.md

@@ -312,42 +312,41 @@ alternate formats.
 
 ### Linting
 
-Standard asynchronous API:
+Asynchronous API via `import { lint } from "markdownlint/async"`:
 
 ```javascript
 /**
  * Lint specified Markdown files.
  *
- * @param {Options} options Configuration options.
+ * @param {Options | null} options Configuration options.
  * @param {LintCallback} callback Callback (err, result) function.
  * @returns {void}
  */
-function markdownlint(options, callback) { ... }
+function lint(options, callback) { ... }
 ```
 
-Synchronous API (for build scripts, etc.):
+Synchronous API via `import { lint } from "markdownlint/sync"`:
 
 ```javascript
 /**
- * Lint specified Markdown files synchronously.
+ * Lint specified Markdown files.
  *
- * @param {Options} options Configuration options.
+ * @param {Options | null} options Configuration options.
  * @returns {LintResults} Results object.
  */
-function markdownlint.sync(options) { ... }
+function lint(options) { ... }
 ```
 
-Promise API (in the `promises` namespace like Node.js's
-[`fs` Promises API](https://nodejs.org/api/fs.html#fs_fs_promises_api)):
+Promise API via `import { lint } from "markdownlint/promise"`:
 
 ```javascript
 /**
  * Lint specified Markdown files.
  *
- * @param {Options} options Configuration options.
+ * @param {Options | null} options Configuration options.
  * @returns {Promise<LintResults>} Results object.
  */
-function markdownlint(options) { ... }
+function lint(options) { ... }
 ```
 
 #### options
@@ -669,7 +668,7 @@ By default, configuration files are parsed as JSON (and named
 `.markdownlint.json`). Custom parsers can be provided to handle other formats
 like JSONC, YAML, and TOML.
 
-Asynchronous API:
+Asynchronous API via `import { readConfig } from "markdownlint/async"`:
 
 ```javascript
 /**
@@ -684,22 +683,21 @@ Asynchronous API:
 function readConfig(file, parsers, fs, callback) { ... }
 ```
 
-Synchronous API:
+Synchronous API via `import { readConfig } from "markdownlint/sync"`:
 
 ```javascript
 /**
- * Read specified configuration file synchronously.
+ * Read specified configuration file.
  *
  * @param {string} file Configuration file name.
  * @param {ConfigurationParser[]} [parsers] Parsing function(s).
  * @param {Object} [fs] File system implementation.
  * @returns {Configuration} Configuration object.
  */
-function readConfigSync(file, parsers, fs) { ... }
+function readConfig(file, parsers, fs) { ... }
 ```
 
-Promise API (in the `promises` namespace like Node.js's
-[`fs` Promises API](https://nodejs.org/api/fs.html#fs_promises_api)):
+Promise API via `import { readConfig } from "markdownlint/promise"`:
 
 ```javascript
 /**
@@ -772,7 +770,8 @@ Configuration object.
 
 Rules that can be fixed automatically include a `fixInfo` property which is
 outlined in the [documentation for custom rules](doc/CustomRules.md#authoring).
-To apply fixes consistently, the `applyFix`/`applyFixes` methods may be used:
+To apply fixes consistently, the `applyFix`/`applyFixes` methods may be used via
+`import { applyFix, applyFixes } from "markdownlint"`:
 
 ```javascript
 /**
@@ -798,18 +797,19 @@ function applyFixes(input, errors) { ... }
 Invoking `applyFixes` with the results of a call to lint can be done like so:
 
 ```javascript
-import markdownlint from "markdownlint";
+import { applyFixes } from "markdownlint";
+import { lint as lintSync } from "markdownlint/sync";
 
-const fixResults = markdownlint.sync({ "strings": { "content": original } });
-const fixed = markdownlint.applyFixes(original, fixResults.content);
+const results = lintSync({ "strings": { "content": original } });
+const fixed = applyFixes(original, results.content);
 ```
 
 ## Usage
 
-Invoke `markdownlint` and use the `result` object's `toString` method:
+Invoke `lint` and use the `result` object's `toString` method:
 
 ```javascript
-import markdownlint from "markdownlint";
+import { lint as lintAsync } from "markdownlint/async";
 
 const options = {
   "files": [ "good.md", "bad.md" ],
@@ -819,9 +819,9 @@ const options = {
   }
 };
 
-markdownlint(options, function callback(err, result) {
-  if (!err) {
-    console.log(result.toString());
+lintAsync(options, function callback(error, results) {
+  if (!error && results) {
+    console.log(results.toString());
   }
 });
 ```
@@ -839,21 +839,22 @@ bad.md: 3: MD018/no-missing-space-atx No space after hash on atx style heading [
 bad.md: 1: MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading [Context: "#bad.md"]
 ```
 
-Or invoke `markdownlint.sync` for a synchronous call:
+Or as a synchronous call:
 
 ```javascript
-const result = markdownlint.sync(options);
-console.log(result.toString());
+import { lint as lintSync } from "markdownlint/sync";
+
+const results = lintSync(options);
+console.log(results.toString());
 ```
 
-To examine the `result` object directly:
+To examine the `result` object directly via a `Promise`-based call:
 
 ```javascript
-markdownlint(options, function callback(err, result) {
-  if (!err) {
-    console.dir(result, { "colors": true, "depth": null });
-  }
-});
+import { lint as lintPromise } from "markdownlint/promise";
+
+const results = await lintPromise(options);
+console.dir(results, { "colors": true, "depth": null });
 ```
 
 Output:
@@ -910,7 +911,7 @@ Generate normal and minified scripts with:
 npm run build-demo
 ```
 
-Then reference the `markdownlint` script:
+Then reference the `markdownlint-browser` script:
 
 ```html
 <script src="demo/markdownlint-browser.min.js"></script>
@@ -924,7 +925,8 @@ const options = {
     "content": "Some Markdown to lint."
   }
 };
-const results = window.markdownlint.markdownlint.sync(options).toString();
+
+const results = globalThis.markdownlint.lintSync(options).toString();
 ```
 
 ## Examples

Diff for: demo/browser-exports.mjs

@@ -1,6 +1,7 @@
 // @ts-check
 
-export { default as markdownlint } from "../lib/markdownlint.mjs";
+export { applyFixes, getVersion } from "markdownlint";
+export { lint as lintSync } from "markdownlint/sync";
 export { compile, parse, postprocess, preprocess } from "micromark";
 export { directive, directiveHtml } from "micromark-extension-directive";
 export { gfmAutolinkLiteral, gfmAutolinkLiteralHtml } from "micromark-extension-gfm-autolink-literal";

Diff for: demo/default.js

@@ -3,8 +3,8 @@
 (function main() {
   // Dependencies
   var markdownit = globalThis.markdownit;
-  var markdownlint = globalThis.markdownlint.markdownlint;
-  var micromark = globalThis.markdownlint;
+  var markdownlint = globalThis.markdownlint;
+  var micromark = markdownlint;
 
   // DOM elements
   var markdown = document.getElementById("markdown");
@@ -112,7 +112,7 @@
       },
       "handleRuleFailures": true
     };
-    allLintErrors = markdownlint.sync(options).content;
+    allLintErrors = markdownlint.lintSync(options).content;
     violations.innerHTML = allLintErrors.map(function mapResult(result) {
       var ruleName = result.ruleNames.slice(0, 2).join(" / ");
       return "<em><a href='#line' target='" + result.lineNumber + "'>" +

Diff for: doc/CustomRules.md

@@ -160,8 +160,8 @@ implementation that is resolved when the rule completes. (The value passed to
 reported via the `onError` function just like for synchronous rules.
 
 **Note**: Asynchronous rules cannot be referenced in a synchronous calling
-context (i.e., `markdownlint.sync(...)`). Attempting to do so throws an
-exception.
+context (i.e., `import { lint } from "markdownlint/sync"`). Attempting to do so
+throws an exception.
 
 ## Examples
 

Diff for: eslint.config.mjs

@@ -149,7 +149,7 @@ export default [
     ],
     "rules": {
       "no-console": "off",
-      "no-shadow": "off"
+      "no-constant-condition": "off"
     }
   },
   {

Diff for: example/Gruntfile.cjs

@@ -13,8 +13,8 @@ module.exports = function wrapper(grunt) {
 
   grunt.registerMultiTask("markdownlint", function task() {
     const done = this.async();
-    import("markdownlint").then(({ "default": markdownlint }) => {
-      markdownlint(
+    import("markdownlint/async").then(({ lint }) => {
+      lint(
         { "files": this.filesSrc },
         function callback(err, result) {
           const resultString = err || ((result || "").toString());

Diff for: example/gulpfile.cjs

@@ -9,8 +9,8 @@ const through2 = require("through2");
 gulp.task("markdownlint", function task() {
   return gulp.src("*.md", { "read": false })
     .pipe(through2.obj(function obj(file, enc, next) {
-      import("markdownlint").then(({ "default": markdownlint }) => {
-        markdownlint(
+      import("markdownlint/async").then(({ lint }) => {
+        lint(
           { "files": [ file.relative ] },
           function callback(err, result) {
             const resultString = (result || "").toString();

Diff for: example/standalone.mjs

@@ -1,6 +1,9 @@
 // @ts-check
 
-import markdownlint from "markdownlint";
+import { applyFixes } from "markdownlint";
+import { lint as lintAsync } from "markdownlint/async";
+import { lint as lintPromise } from "markdownlint/promise";
+import { lint as lintSync } from "markdownlint/sync";
 
 const options = {
   "files": [ "good.md", "bad.md" ],
@@ -10,27 +13,39 @@ const options = {
   }
 };
 
-// Makes a synchronous call, using result.toString for pretty formatting
-const result = markdownlint.sync(options);
-console.log(result.toString());
+if (true) {
 
-// Makes an asynchronous call
-markdownlint(options, function callback(err, result) {
-  if (!err) {
-    // @ts-ignore
-    console.log(result.toString());
-  }
-});
+  // Makes a synchronous call, uses result.toString for pretty formatting
+  const results = lintSync(options);
+  console.log(results.toString());
 
-// Displays the result object directly
-markdownlint(options, function callback(err, result) {
-  if (!err) {
-    console.dir(result, { "colors": true, "depth": null });
-  }
-});
+}
+
+if (true) {
+
+  // Makes an asynchronous call, uses result.toString for pretty formatting
+  lintAsync(options, function callback(error, results) {
+    if (!error && results) {
+      console.log(results.toString());
+    }
+  });
+
+}
+
+if (true) {
+
+  // Makes a Promise-based asynchronous call, displays the result object directly
+  const results = await lintPromise(options);
+  console.dir(results, { "colors": true, "depth": null });
+
+}
+
+if (true) {
+
+  // Fixes all supported violations in Markdown content
+  const original = "# Heading";
+  const results = lintSync({ "strings": { "content": original } });
+  const fixed = applyFixes(original, results.content);
+  console.log(fixed);
 
-// Fixes all supported violations in Markdown content
-const original = "# Heading";
-const fixResults = markdownlint.sync({ "strings": { "content": original } });
-const fixed = markdownlint.applyFixes(original, fixResults.content);
-console.log(fixed);
+}