Feature: Add <BUILTIN_MODULES> Special Word

README.md

@@ -21,7 +21,7 @@ Since then more critical features & fixes have been added, and the options have
 
 [We welcome contributions!](./CONTRIBUTING.md)
 
-**Table of Contents**
+## Table of Contents
 
 - [Sample](#sample)
   - [Input](#input)
@@ -177,9 +177,10 @@ unsortable. This can be used for edge-cases, such as when you have a named impor
 
 Next, the plugin sorts the _local imports_ and _third party imports_ using [natural sort algorithm](https://en.wikipedia.org/wiki/Natural_sort_order).
 
-In the end, the plugin returns final imports with _third party imports_ on top and _local imports_ at the end.
+In the end, the plugin returns final imports with _nodejs built-in modules_, followed by _third party imports_ and subsequent _local imports_ at the end.
 
-The _third party imports_ position (it's top by default) can be overridden using the `<THIRD_PARTY_MODULES>` special word in the `importOrder`.
+- The _nodejs built-in modules_ position (it's 1st by default) can be overridden using the `<BUILTIN_MODULES>` special word in the `importOrder`
+- The _third party imports_ position (it's 2nd by default) can be overridden using the `<THIRD_PARTY_MODULES>` special word in the `importOrder`.
 
 ### Options
 
@@ -193,14 +194,20 @@ The main way to control the import order and formatting, `importOrder` is a coll
 
 ```js
 [
-    // node.js built-ins are always first
-    '<THIRD_PARTY_MODULES>', // Non-relative imports
+    '<BUILTIN_MODULES>', // Built-in modules are always grouped. If you don't configure this special word, it will be injected.
+    '<THIRD_PARTY_MODULES>', // Imports not matched by other special words or regexps -- if you don't configure this special word, it will be injected.
     '^[.]', // relative imports
 ],
 ```
 
 By default, this plugin sorts as documented on the line above, with Node.js built-in modules at the top, followed by non-relative imports, and lastly any relative import starting with a `.` character.
 
+Available Special Words:
+
+- `<BUILTIN_MODULES>` - All _nodejs built-in modules_ will be grouped here, and is injected at the top if it's not present.
+- `<THIRD_PARTY_MODULES>` - All imports not targeted by another regex will end up here, so this will be injected if not present in `options.importOrder`
+- `<TYPES>` - Not active by default, this allows you to group all type-imports, or target them with a regex (`<TYPES>^[.]` targets imports of types from local files).
+
 Here are some common ways to configure `importOrder`:
 
 ##### 1. Put specific dependencies at the top
@@ -240,11 +247,9 @@ import styles from './global.css';
 If you want to group your imports into "chunks" with blank lines between, you can add empty strings like this:
 
 ```json
-"importOrder": ["", "<THIRD_PARTY_MODULES>", "", "^[.]",]
+"importOrder": ["<BUILT_IN_MODULES>", "", "<THIRD_PARTY_MODULES>", "", "^[.]",]
 ```
 
-(Note the empty string at the start, to add a blank line after node.js built-ins)
-
 e.g.:
 
 ```ts

src/constants.ts

@@ -23,11 +23,14 @@ export const mergeableImportFlavors = [
     importFlavorType,
 ] as const;
 
-/*
- * Used to mark the position between RegExps,
- * where the not matched imports should be placed
+export const BUILTIN_MODULES_REGEX_STR = `^(?:node:)?(?:${builtinModules.join(
+    '|',
+)})$`;
+
+export const BUILTIN_MODULES_SPECIAL_WORD = '<BUILTIN_MODULES>';
+/**
+ * Used to mark not otherwise matched imports should be placed
  */
-export const BUILTIN_MODULES = `^(?:node:)?(?:${builtinModules.join('|')})$`;
 export const THIRD_PARTY_MODULES_SPECIAL_WORD = '<THIRD_PARTY_MODULES>';
 export const TYPES_SPECIAL_WORD = '<TYPES>';
 

src/index.ts

@@ -4,7 +4,10 @@ import { parsers as flowParsers } from 'prettier/parser-flow';
 import { parsers as htmlParsers } from 'prettier/parser-html';
 import { parsers as typescriptParsers } from 'prettier/parser-typescript';
 
-import { THIRD_PARTY_MODULES_SPECIAL_WORD } from './constants';
+import {
+    BUILTIN_MODULES_SPECIAL_WORD,
+    THIRD_PARTY_MODULES_SPECIAL_WORD,
+} from './constants';
 import { defaultPreprocessor } from './preprocessors/default';
 import { vuePreprocessor } from './preprocessors/vue';
 import type { PrettierOptions } from './types';
@@ -29,7 +32,7 @@ export const options: Record<
         default: [
             {
                 value: [
-                    // node.js built-ins are always first
+                    BUILTIN_MODULES_SPECIAL_WORD,
                     THIRD_PARTY_MODULES_SPECIAL_WORD, // Everything not matching relative imports
                     '^[.]', // relative imports
                 ],

src/utils/get-comment-registry.ts

@@ -4,7 +4,6 @@ import {
     type ImportDeclaration,
 } from '@babel/types';
 
-import { newLineNode } from '../constants';
 import { ImportOrLine, ImportRelated, SomeSpecifier } from '../types';
 
 const SpecifierTypes = [

src/utils/get-import-nodes-matched-group.ts

@@ -5,13 +5,24 @@ import {
     TYPES_SPECIAL_WORD,
 } from '../constants';
 
+const regexCache = new Map<string, RegExp>();
+const cachedRegExp = (regExp: string) => {
+    if (regexCache.has(regExp)) {
+        return regexCache.get(regExp)!;
+    }
+    // Strip <TYPES> when creating regexp
+    const result = new RegExp(regExp.replace(TYPES_SPECIAL_WORD, ''));
+    regexCache.set(regExp, result);
+    return result;
+};
+
 /**
  * Get the regexp group to keep the import nodes.
  *
  * This comes near the end of processing, after import declaration nodes have been combined or exploded.
  *
  * @param node
- * @param importOrder
+ * @param importOrder a list of [regexp or special-word] groups (no separators)
  */
 export const getImportNodesMatchedGroup = (
     node: ImportDeclaration,
@@ -23,8 +34,7 @@ export const getImportNodesMatchedGroup = (
     const groupWithRegExp = importOrder
         .map((group) => ({
             group,
-            // Strip <TYPES> when creating regexp
-            regExp: new RegExp(group.replace(TYPES_SPECIAL_WORD, '')),
+            regExp: cachedRegExp(group),
         }))
         // Remove explicit bare <TYPES> group, we'll deal with that at the end similar to third party modules
         .filter(({ group }) => group !== TYPES_SPECIAL_WORD);

src/utils/get-sorted-nodes-by-import-order.ts

@@ -1,12 +1,9 @@
-import {
-    BUILTIN_MODULES,
-    newLineNode,
-    THIRD_PARTY_MODULES_SPECIAL_WORD,
-} from '../constants';
+import { newLineNode, THIRD_PARTY_MODULES_SPECIAL_WORD } from '../constants';
 import type { GetSortedNodes, ImportGroups, ImportOrLine } from '../types';
 import { getImportNodesMatchedGroup } from './get-import-nodes-matched-group';
 import { getSortedImportSpecifiers } from './get-sorted-import-specifiers';
 import { getSortedNodesGroup } from './get-sorted-nodes-group';
+import { normalizeImportOrderOption } from './normalize-import-order-options';
 
 /**
  * This function returns the given nodes, sorted in the order as indicated by
@@ -19,17 +16,11 @@ export const getSortedNodesByImportOrder: GetSortedNodes = (
     originalNodes,
     options,
 ) => {
-    let { importOrder } = options;
+    // This normalization is safe even if the option is already correct.
+    const importOrder = normalizeImportOrderOption(options.importOrder);
 
     const finalNodes: ImportOrLine[] = [];
 
-    if (!importOrder.includes(THIRD_PARTY_MODULES_SPECIAL_WORD)) {
-        importOrder = [THIRD_PARTY_MODULES_SPECIAL_WORD, ...importOrder];
-    }
-
-    // Opinionated decision: builtin modules should always be first
-    importOrder = [BUILTIN_MODULES, ...importOrder];
-
     const importOrderGroups = importOrder.reduce<ImportGroups>(
         (groups, regexp) =>
             // Don't create a new group for explicit import separators

src/utils/normalize-import-order-options.ts

@@ -0,0 +1,33 @@
+import {
+    BUILTIN_MODULES_REGEX_STR,
+    BUILTIN_MODULES_SPECIAL_WORD,
+    THIRD_PARTY_MODULES_SPECIAL_WORD,
+} from '../constants';
+import { PrettierOptions } from '../types';
+
+export function normalizeImportOrderOption(
+    importOrder: PrettierOptions['importOrder'],
+) {
+    // THIRD_PARTY_MODULES_SPECIAL_WORD is magic because "everything not matched by other groups goes here"
+    // So it must always be present.
+    if (!importOrder.includes(THIRD_PARTY_MODULES_SPECIAL_WORD)) {
+        importOrder = [THIRD_PARTY_MODULES_SPECIAL_WORD, ...importOrder];
+    }
+
+    // Opinionated Decision: NodeJS Builtin modules should always be separate from third party modules
+    // Users may want to add their own separators around them or insert other modules above them though
+    if (
+        !(
+            importOrder.includes(BUILTIN_MODULES_SPECIAL_WORD) ||
+            importOrder.includes(BUILTIN_MODULES_REGEX_STR)
+        )
+    ) {
+        importOrder = [BUILTIN_MODULES_SPECIAL_WORD, ...importOrder];
+    }
+
+    importOrder = importOrder.map((g) =>
+        g === BUILTIN_MODULES_SPECIAL_WORD ? BUILTIN_MODULES_REGEX_STR : g,
+    );
+
+    return importOrder;
+}

tests/ImportOrderBuiltinModulesToCustom/__snapshots__/ppsi.spec.ts.snap

@@ -0,0 +1,20 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`exercise-custom-builtin-modules-spacing.ts - typescript-verify > exercise-custom-builtin-modules-spacing.ts 1`] = `
+// Top-of-file-comment
+import path from "path"
+import b from 'b';
+import foo from './foo';
+import thirdParty from 'third-party';
+import fs from "node:fs"
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+// Top-of-file-comment
+import b from "b";
+import thirdParty from "third-party";
+
+import fs from "node:fs";
+import path from "path";
+
+import foo from "./foo";
+
+`;

tests/ImportOrderBuiltinModulesToCustom/exercise-custom-builtin-modules-spacing.ts

@@ -0,0 +1,6 @@
+// Top-of-file-comment
+import path from "path"
+import b from 'b';
+import foo from './foo';
+import thirdParty from 'third-party';
+import fs from "node:fs"

tests/ImportOrderBuiltinModulesToCustom/ppsi.spec.ts

@@ -0,0 +1,5 @@
+import {run_spec} from '../../test-setup/run_spec';
+
+run_spec(__dirname, ['typescript'], {
+    importOrder: ['<THIRD_PARTY_MODULES>','','<BUILTIN_MODULES>','','^[./]'],
+});

tests/ImportOrderBuiltinModulesToTop/__snapshots__/ppsi.spec.ts.snap

@@ -3,7 +3,10 @@
 exports[`relative-import-with-builtin-substring.ts - typescript-verify > relative-import-with-builtin-substring.ts 1`] = `
 import foo from './constants/foo';
 import thirdParty from 'third-party';
+import fs from "fs"
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+import fs from "fs";
+
 import thirdParty from "third-party";
 import foo from "./constants/foo";
 

tests/ImportOrderBuiltinModulesToTop/ppsi.spec.ts

@@ -1,5 +1,5 @@
 import {run_spec} from '../../test-setup/run_spec';
 
 run_spec(__dirname, ['typescript'], {
-    importOrder: ['^[./]'],
+    importOrder: ['','<THIRD_PARTY_MODULES>','^[./]'],
 });

tests/ImportOrderBuiltinModulesToTop/relative-import-with-builtin-substring.ts

@@ -1,2 +1,3 @@
 import foo from './constants/foo';
 import thirdParty from 'third-party';
+import fs from "fs"