feat: #206 add configurable SQL formatting with formatSQL API

.gitignore

@@ -3,6 +3,7 @@
 /node_modules/
 /out/
 /esm/
+/esm-dev/
 /release/
 .history
 /docs/

README-zh_CN.md

@@ -162,6 +162,47 @@ npm install monaco-sql-languages
     });
     ```
 
+4. **SQL 格式化（可选）**
+
+    格式化依赖 [`sql-formatter`](https://github.com/sql-formatter-org/sql-formatter) 作为**可选 peer**。主入口**不要求**安装该包：只用补全/诊断时不必安装 `sql-formatter`。
+
+    仅在开启格式化，或 import 格式化 API 时再安装。应用里须 **先 import 一次** format 入口（副作用），再调用 `setupLanguageFeatures(..., { format: { enable: true } })`。未 import 就开启 format 会 **抛错**；若之后再 import format，已加载的语言会自动补偿注册。
+
+    ```bash
+    npm install sql-formatter
+    ```
+
+    必须设置 `format.enable: true` 才会注册编辑器 Format 菜单/快捷键（只传 `fallback` 无效）。**优先级：** 内置 sql-formatter → `fallback`（不可用或抛错）→ 原文。
+
+    ```typescript
+    import { KeyCode, KeyMod } from 'monaco-editor';
+    import 'monaco-sql-languages/format';
+    import { LanguageIdEnum, setupLanguageFeatures } from 'monaco-sql-languages';
+
+    setupLanguageFeatures(LanguageIdEnum.MYSQL, {
+        format: {
+            enable: true, // 注册右键 / 快捷键所必需
+            tabWidth: 4,
+            fallback: (code, languageId) => myLegacyFormat(code, languageId),
+            // 可选；默认 Ctrl/Cmd+Alt+F
+            keybindings: [KeyMod.CtrlCmd | KeyMod.Shift | KeyCode.KeyF]
+        }
+    });
+    ```
+
+    工具栏等外部 UI 请从 format 入口引入（**构建期需要**已安装 `sql-formatter`）：
+
+    ```typescript
+    import { formatEditorSQL, formatSQL } from 'monaco-sql-languages/format';
+
+    await formatEditorSQL(editor, { tabWidth: 4, fallback: myLegacyFormat });
+    const text = await formatSQL(code, LanguageIdEnum.MYSQL, { tabWidth: 4 });
+    ```
+
+    > **版本：** 使用项目中安装的 sql-formatter。peer 要求 **`>=10.7.2`**（覆盖 `hive` / `trino` 与 `tabWidth`）。现代浏览器用 v15+ 亦可；Chrome 75 请 pin `sql-formatter@10.7.2`。
+
+    默认快捷键：**Ctrl/Cmd+Alt+F**（右键 **Format**）。结果与原文相同则不写 edits。
+
 <br/>
 
 ## 代码片段

README.md

@@ -162,6 +162,47 @@ npm install monaco-sql-languages
     });
     ```
 
+4. **SQL Formatting (optional)**
+
+    Formatting uses [`sql-formatter`](https://github.com/sql-formatter-org/sql-formatter) as an **optional peer**. The main package entry does **not** require it: completion and diagnostics work without installing `sql-formatter`.
+
+    Install the peer **only** if you enable formatting or import the format API. Import the format entry **once** (side effect) **before** `setupLanguageFeatures(..., { format: { enable: true } })`. Enabling format without that import throws. If the format entry is imported later, already-loaded languages are re-registered automatically.
+
+    ```bash
+    npm install sql-formatter
+    ```
+
+    `format.enable` must be `true` to register the editor Format action (passing only `fallback` does nothing). **Priority:** built-in sql-formatter → `fallback` (unavailable or throw) → original code.
+
+    ```typescript
+    import { KeyCode, KeyMod } from 'monaco-editor';
+    import 'monaco-sql-languages/format';
+    import { LanguageIdEnum, setupLanguageFeatures } from 'monaco-sql-languages';
+
+    setupLanguageFeatures(LanguageIdEnum.MYSQL, {
+        format: {
+            enable: true, // required for the context-menu / shortcut action
+            tabWidth: 4,
+            fallback: (code, languageId) => myLegacyFormat(code, languageId),
+            // optional; default is Ctrl/Cmd+Alt+F
+            keybindings: [KeyMod.CtrlCmd | KeyMod.Shift | KeyCode.KeyF]
+        }
+    });
+    ```
+
+    Toolbar or other UI should import the format entry (this **does** require `sql-formatter` at build time):
+
+    ```typescript
+    import { formatEditorSQL, formatSQL } from 'monaco-sql-languages/format';
+
+    await formatEditorSQL(editor, { tabWidth: 4, fallback: myLegacyFormat });
+    const text = await formatSQL(code, LanguageIdEnum.MYSQL, { tabWidth: 4 });
+    ```
+
+    > **Versions:** Use the `sql-formatter` version you install. Peer requires **`>=10.7.2`** (covers `hive` / `trino` and `tabWidth`). Modern browsers may use v15+; Chrome 75: pin `sql-formatter@10.7.2`.
+
+    Editor shortcut defaults to **Ctrl/Cmd+Alt+F** (context menu **Format**). Unchanged results apply no edit.
+
 <br/>
 
 ## SQL Snippets

package.json

@@ -1,14 +1,15 @@
 {
 	"name": "monaco-sql-languages",
-	"version": "1.2.0",
+	"version": "1.2.1-beta.2",
 	"description": "SQL languages for the Monaco Editor, based on monaco-languages.",
 	"scripts": {
 		"prepublishOnly": "npm run build",
 		"build": "rm -rf ./esm && tsc -p ./tsconfig.esm.json",
+		"build:dev": "rm -rf ./esm-dev && tsc -p ./tsconfig.esm.json --outDir esm-dev",
 		"build-amd": "rm -rf ./out && tsc -p ./tsconfig.amd.json",
 		"watch-esm": "tsc -p ./tsconfig.esm.json --watch",
 		"test": "npm run build-amd && mocha ./test/all.js",
-		"dev": "node --max_old_space_size=4092 & cd website && npm run dev",
+		"dev": "npm run build:dev && node --max_old_space_size=4092 & cd website && npm run dev",
 		"prod": "rm -rf ./docs && node --max_old_space_size=4092 & cd website && npm run build",
 		"deploy": "npm run build && npm run prod && gh-pages -d docs -r git@github.com:DTStack/monaco-sql-languages.git",
 		"format": "prettier --write .",
@@ -21,6 +22,17 @@
 	"main": "esm/main.js",
 	"module": "esm/main.js",
 	"types": "esm/main.d.ts",
+	"exports": {
+		".": {
+			"types": "./esm/main.d.ts",
+			"default": "./esm/main.js"
+		},
+		"./format": {
+			"types": "./esm/format.entry.d.ts",
+			"default": "./esm/format.entry.js"
+		},
+		"./esm/*": "./esm/*"
+	},
 	"files": [
 		"esm"
 	],
@@ -58,6 +70,7 @@
 		"mocha": "^11.7.4",
 		"monaco-editor": "0.54.0",
 		"prettier": "^3.3.3",
+		"sql-formatter": "^15.8.2",
 		"pretty-quick": "^4.0.0",
 		"requirejs": "^2.3.6",
 		"simple-git-hooks": "^2.11.1",
@@ -68,7 +81,13 @@
 		"pre-commit": "npx pretty-quick --staged"
 	},
 	"peerDependencies": {
-		"monaco-editor": ">=0.37.1"
+		"monaco-editor": ">=0.37.1",
+		"sql-formatter": ">=10.7.2"
+	},
+	"peerDependenciesMeta": {
+		"sql-formatter": {
+			"optional": true
+		}
 	},
 	"engines": {
 		"node": ">=18"

src/format.entry.ts

@@ -0,0 +1,15 @@
+import { registerFormatAction } from './formatEditor';
+import { setFormatActionRegistrar } from './formatBridge';
+
+/**
+ * Optional format API entry (`monaco-sql-languages/format`).
+ * Importing this module pulls in sql-formatter and registers the built-in Format action
+ * used when `format.enable` is true.
+ */
+setFormatActionRegistrar(registerFormatAction);
+
+export { formatSQL } from './format';
+export { registerFormatAction };
+export { formatEditorSQL, type FormatTargetEditor, type TextRange } from './formatEditor';
+export type { FormatFallback } from './formatTypes';
+export type { FormatSQLOptions } from './monaco.contribution';