# sql-formatter-compact

**Repository Path**: GuojcData/sql-formatter-compact

## Basic Information

- **Project Name**: sql-formatter-compact
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-20
- **Last Updated**: 2026-02-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# @guojc1/sql-formatter-compact

这是一个基于经典 [sql-formatter-org/sql-formatter](https://github.com/sql-formatter-org/sql-formatter) 深度定制的分支版本。它专门为了满足**极度紧凑、具有强迫症级别代码洁癖**的 SQL 排版需求而诞生。

> 🇬🇧 [English version (README.md)](./README.md)

相比原版，它新增了以下核心能力和修复：

## 🌟 核心特性升级 (Compact Features)

1. **相对顶格对齐 (Relative Flush-Left)**:

   - 彻底解决了原版中 `WHERE`, `AND`, `OR`, `FROM`, `JOIN` 等关键字及其内容总是会向右产生多级无脑缩进的问题。
   - 现在，这些关键字及其后的内容会**根据它们当前所在的括号层级（例如在多层嵌套的子查询中）实现完美的绝对靠左对齐**，从而让你的 SQL 看起来像是一张结构分明的工程图纸。

2. **完美的逗号前置支持 (`commaPosition: 'before'`)**:

   - 提供了将多字段查询时的逗号统一放置于行首的配置。
   - **核心修复**：彻底解决了原版在逗号换行时，会将字段后附带的行内注释 (`-- 注释`) 意外截断或导致多余换行的致命 Bug。你的注释将永远死死咬在字段的末尾。
   - 修复了行首逗号与字段之间多余的空格。

3. **去除冗余换行 (`newlineAfterClause: false`)**:

   - 原版格式化器常常会在 `FROM`, `WHERE` 等关键词后强制加入一个生硬的换行符（如 `FROM \n table_name`）。
   - 本工具允许你关闭这一特性，让诸如 `from dwd.dwd_proj_info_d_a t1` 这样的短句保持在一行内紧凑输出，仅保留 `SELECT` 等必要的独立换行。

4. **修复了 `WITH` 语句的双重缩进**:
   - 修正了在 `WITH cte AS (...)` 结构中，原版逻辑给 CTE 内容施加了两级额外缩进的过度排版问题。现在内部只会有标准的 1 级嵌套缩进。

---

5. **局部代码块格式化豁免**:

   - 如果你的代码中有某些不想被工具格式化的特殊 SQL（例如特定的注释排版或对齐），你可以在代码前后包裹魔术注释：

   ```sql
   /* sql-formatter-compact-disable */
   SELECT    a,
             b
   FROM      table_name;
   /* sql-formatter-compact-enable */
   ```

   - 包含在这对注释内部的所有内容将保持原样，原封不动地输出。

6. **复杂函数与 `CASE` 语句的单行化支持**:
   - 原版格式化器对于包含 `CASE WHEN` 等子句的函数调用（如 `date(concat(..., case when ...))`），会因为底层硬编码的新行符而永远被炸碎成几十行。
   - 本定制版重构了 `CASE` 与逻辑操作符的内联渲染引擎。你现在只需通过调大 `expressionWidth`（最大表达式长度）配置项，就能让这些复杂又冗长的行内函数在一行内清爽展示。

## 📦 安装 (Installation)

你可以直接全局安装作为 CLI 工具，或者在 Node.js 项目中安装作为依赖：

```bash
npm install -g @guojc1/sql-formatter-compact
# 或者
yarn add @guojc1/sql-formatter-compact
```

## 🚀 使用示例 (Node.js)

```javascript
import { format } from '@guojc1/sql-formatter-compact';

const sql = 'SELECT a, b, c FROM my_table WHERE a = 1 AND b = 2';

const formattedSql = format(sql, {
  language: 'hive', // 支持 15+ 种 SQL 方言
  keywordCase: 'lower', // 关键字强制全小写
  commaPosition: 'before', // 🌟 逗号前置
  newlineAfterClause: false, // 🌟 关键词后紧跟内容，不换行
  tabWidth: 2, // 缩进 2 个空格
});

console.log(formattedSql);
```

## ⚙️ 完整的配置项 (Configuration Options)

`format(sql, options)` 函数接受第二个参数对象，支持以下完整的原版与定制配置项：

- **`language`**：要使用的 SQL 方言名称（默认：`sql`）。
- **`commaPosition`**：`'before' | 'after'`。控制多字段时逗号是放在字段前还是字段后（✨ 本版新增）。
- **`newlineAfterClause`**：`boolean`。是否在 `FROM`, `WHERE` 等核心子句后强制换行。设为 `false` 可实现极致紧凑排版（✨ 本版新增）。
- **`tabWidth`**：用于缩进的空格数（默认：`2`）。
- **`useTabs`**：是否使用制表符（Tab）进行缩进。
- **`keywordCase`**：将关键字转为大写或小写：`preserve` (保留), `upper` (大写), `lower` (小写)。
- **`dataTypeCase`**：将数据类型转为大写或小写。
- **`functionCase`**：将函数名转为大写或小写。
- **`identifierCase`**：将标识符（表名/字段名）转为大写或小写（实验性功能）。
- **`logicalOperatorNewline`**：布尔运算符 (`AND`, `OR`, `XOR`) 的换行位置：`before` (之前) 或 `after` (之后)。
- **`expressionWidth`**：括号内表达式的最大字符宽度限制，超过此宽度将强制换行。
- **`linesBetweenQueries`**：多个独立查询语句之间保留的空行数。
- **`denseOperators`**：是否紧密排列操作符（去除 `=` `>` 等前后的空格）。
- **`newlineBeforeSemicolon`**：是否将分号放置在单独的换行上。
- **`params`**：用于占位符替换的值集合。

## 🗄️ 支持的 SQL 方言 (Supported Dialects)

支持多达 15 种以上的 SQL 方言。你可以在 `language` 配置项中传入以下标识符：

- `sql` (Standard SQL)
- `bigquery` (Google BigQuery)
- `clickhouse` (ClickHouse)
- `db2` (IBM DB2)
- `duckdb` (DuckDB)
- `hive` (Apache Hive)
- `mariadb` (MariaDB)
- `mysql` (MySQL)
- `postgresql` (PostgreSQL)
- `redshift` (Amazon Redshift)
- `snowflake` (Snowflake)
- `spark` (Spark SQL)
- `sqlite` (SQLite)
- `tidb` (TiDB)
- `transactsql` (SQL Server T-SQL)
- `trino` (Trino / Presto)

## 💻 命令行使用 (CLI Usage)

全局安装后，你可以使用 `sql-formatter` 命令直接在终端中格式化文件。

```bash
# 格式化文件并覆盖写入
# 格式化文件并覆盖写入 (原地修改)
sql-formatter-compact --fix "./src/**/*.sql"

# 使用配置文件格式化
sql-formatter-compact -c ./sqlfmt.json --fix "./src/**/*.sql"
```

你可以创建一个类似 `.sql-formatter-compact.json` (默认会自动搜寻) 或 `sqlfmt.json` 的配置文件来指定格式化参数：

```json
{
  "language": "spark",
  "tabWidth": 4,
  "keywordCase": "upper",
  "commaPosition": "before",
  "newlineAfterClause": false
}
```

## 🌐 浏览器端使用 (Without NPM)

如果你不使用构建工具 (Webpack/Rollup 等)，可以克隆本项目后运行 `yarn build`，然后直接在 HTML 的 `<script>` 标签中引入 `/dist/sql-formatter.min.js` 文件。
这会在全局注册 `window.sqlFormatter` 变量。

---

### 开源声明与致谢

本项目基于 MIT 协议。
核心的 AST 词法分析器与多数方言解析能力由原 [sql-formatter](https://github.com/sql-formatter-org/sql-formatter) 开源社区的杰出贡献者们提供，特此致谢。