Expose types for config options (#41)

Ported from trivago/prettier-plugin-sort-imports#173 & trivago/prettier-plugin-sort-imports#180

We'll likely be deprecating many of these options in the future, but for now, we may as well expose their types and give them some nice docs.

Co-authored-by: Nutthapat Pongtanyavichai <[email protected]>

README.md

@@ -112,7 +112,10 @@ yarn add --dev @ianvs/prettier-plugin-sort-imports
 
 Add your preferred settings in your prettier config file.
 
-```javascript
+```ts
+// @ts-check
+
+/** @type {import("@ianvs/prettier-plugin-sort-imports").PrettierConfig} */
 module.exports = {
   "printWidth": 80,
   "tabWidth": 4,

package.json

@@ -4,6 +4,7 @@
     "version": "3.5.2",
     "description": "A prettier plugins to sort imports in provided RegEx order",
     "main": "lib/src/index.js",
+    "types": "types/index.d.ts",
     "repository": {
         "url": "https://github.com/ianvs/prettier-plugin-sort-imports",
         "type": "git"

src/types.ts

@@ -1,6 +1,7 @@
 import { ExpressionStatement, ImportDeclaration } from '@babel/types';
 import { RequiredOptions } from 'prettier';
 
+import { PluginConfig } from '../types';
 import {
     chunkTypeOther,
     chunkTypeUnsortable,
@@ -10,18 +11,9 @@ import {
     importFlavorValue,
 } from './constants';
 
-export interface PrettierOptions extends RequiredOptions {
-    importOrder: string[];
-    importOrderCaseInsensitive: boolean;
-    importOrderBuiltinModulesToTop: boolean;
-    importOrderGroupNamespaceSpecifiers: boolean;
-    importOrderMergeDuplicateImports: boolean;
-    importOrderCombineTypeAndValueImports: boolean;
-    importOrderSeparation: boolean;
-    importOrderSortSpecifiers: boolean;
-    // should be of type ParserPlugin from '@babel/parser' but prettier does not support nested arrays in options
-    importOrderParserPlugins: string[];
-}
+export interface PrettierOptions
+    extends Required<PluginConfig>,
+        RequiredOptions {}
 
 export type ChunkType = typeof chunkTypeOther | typeof chunkTypeUnsortable;
 export type FlavorType =

types/index.d.ts

@@ -0,0 +1,139 @@
+import { ParserPlugin } from '@babel/parser';
+import { Config } from 'prettier';
+
+export type ImportOrderParserPlugin =
+    | Extract<ParserPlugin, string>
+    | `[${string},${string}]`;
+
+export interface PluginConfig {
+    /**
+     * A collection of Regular expressions in string format.
+     *
+     * ```json
+     * "importOrder": ["^@core/(.*)$", "^@server/(.*)$", "^@ui/(.*)$", "^[./]"],
+     * ```
+     *
+     * _Default:_ `[]`
+     *
+     * By default, this plugin will not move any imports.
+     * To separate third party from relative imports, use `["^[./]"]`.
+     * This will become the default in the next major version.
+     *
+     * The plugin moves the third party imports to the top which are not part of the `importOrder` list.
+     * To move the third party imports at desired place,
+     * you can use `<THIRD_PARTY_MODULES>` to assign third party imports to the appropriate position:
+     *
+     * ```json
+     * "importOrder": ["^@core/(.*)$", "<THIRD_PARTY_MODULES>", "^@server/(.*)$", "^@ui/(.*)$", "^[./]"],
+     * ```
+     */
+    importOrder?: string[];
+
+    /**
+     * A boolean value to enable case-insensitivity in the sorting algorithm
+     * used to order imports within each match group.
+     *
+     * For example, when false (or not specified):
+     *
+     * ```js
+     * import ExampleView from './ExampleView';
+     * import ExamplesList from './ExamplesList';
+     * ```
+     *
+     * compared with `"importOrderCaseInsensitive": true`:
+     *
+     * ```js
+     * import ExamplesList from './ExamplesList';
+     * import ExampleView from './ExampleView';
+     * ```
+     *
+     * @default false
+     */
+    importOrderCaseInsensitive?: boolean;
+
+    /**
+     * A boolean value to enable sorting of node builtins
+     * to the top of all import groups.
+     *
+     * @ref https://nodejs.org/api/module.html#modulebuiltinmodules
+     * @default false
+     */
+    importOrderBuiltinModulesToTop?: boolean;
+
+    /**
+     * A boolean value to enable or disable sorting the namespace specifiers to the top of the import group.
+     *
+     * @default false
+     */
+    importOrderGroupNamespaceSpecifiers?: boolean;
+
+    /**
+     * When `true`, multiple import statements from the same module will be combined into a single import.
+     *
+     * @default false
+     */
+    importOrderMergeDuplicateImports?: boolean;
+
+    /**
+     * A boolean value to control merging `import type` expressions into `import {…}`.
+     *
+     * ```diff
+     * - import type { C1 } from 'c';
+     * - import { C2 } from 'c';
+     * + import { type C1, C2 } from "c";
+     *
+     * - import { D1 } from 'd';
+     * - import type { D2 } from 'd';
+     * + import { D1, type D2 } from "d";
+     *
+     * - import type { A1 } from 'a';
+     * - import type { A2 } from 'a';
+     * + import type { A1, A2 } from "a";
+     * ```
+     *
+     * @default false
+     */
+    importOrderCombineTypeAndValueImports?: boolean;
+
+    /**
+     * A boolean value to enable or disable the new line separation between sorted import declarations group.
+     * The separation takes place according to the `importOrder`.
+     *
+     * @default false
+     */
+    importOrderSeparation?: boolean;
+
+    /**
+     * A boolean value to enable or disable sorting of the specifiers in an import declarations.
+     *
+     * @default false
+     */
+    importOrderSortSpecifiers?: boolean;
+
+    /**
+     * A collection of plugins for babel parser. The plugin passes this list to babel parser, so it can understand the syntaxes
+     * used in the file being formatted. The plugin uses prettier itself to figure out the parser it needs to use but if that fails,
+     * you can use this field to enforce the usage of the plugins' babel parser needs.
+     *
+     * **To pass the plugins to babel parser**:
+     *
+     * ```
+     * "importOrderParserPlugins" : ["classProperties", "decorators-legacy"]
+     * ```
+     *
+     * **To pass the options to the babel parser plugins**: Since prettier options are limited to string, you can pass plugins
+     * with options as a JSON string of the plugin array:
+     * `"[\"plugin-name\", { \"pluginOption\": true }]"`.
+     *
+     * ```
+     * "importOrderParserPlugins" : ["classProperties", "[\"decorators\", { \"decoratorsBeforeExport\": true }]"]
+     * ```
+     *
+     * **To disable default plugins for babel parser, pass an empty array**:
+     *
+     * @default ["typescript", "jsx"]
+     */
+    importOrderParserPlugins?: ImportOrderParserPlugin[];
+}
+
+export type PrettierConfig = PluginConfig & Config;