0
# Core Formatting
1

2
Primary SQL formatting functionality with dialect detection and comprehensive formatting options. Handles whitespace, indentation, keyword casing, and query structure.
3

4
## Capabilities
5

6
### Format Function
7

8
Main formatting function that accepts a SQL query string and optional configuration options.
9

10
```typescript { .api }
11
/**
12
 * Format whitespace in a query to make it easier to read.
13
 * @param query - input SQL query string
14
 * @param cfg - Configuration options (see FormatOptionsWithLanguage)
15
 * @returns formatted query
16
 */
17
function format(query: string, cfg?: FormatOptionsWithLanguage): string;
18

19
type FormatOptionsWithLanguage = Partial<FormatOptions> & {
20
  language?: SqlLanguage;
21
};
22
```
23

24
**Usage Examples:**
25

26
```typescript
27
import { format } from "sql-formatter";
28

29
// Basic formatting
30
const result = format("SELECT * FROM users WHERE active=1");
31
// Output: 
32
// SELECT
33
//   *
34
// FROM
35
//   users
36
// WHERE
37
//   active = 1
38

39
// With MySQL dialect
40
const result = format("SELECT * FROM users WHERE id IN (1,2,3)", {
41
  language: "mysql",
42
  keywordCase: "upper",
43
  indentStyle: "standard"
44
});
45

46
// With configuration options
47
const result = format("SELECT name, email FROM users ORDER BY created_at", {
48
  language: "postgresql", 
49
  tabWidth: 4,
50
  keywordCase: "upper",
51
  linesBetweenQueries: 2
52
});
53
```
54

55
### Format Dialect Function
56

57
Like format(), but requires a dialect object instead of a language string for more advanced usage.
58

59
```typescript { .api }
60
/**
61
 * Like the above format(), but language parameter is mandatory
62
 * and must be a Dialect object instead of a string.
63
 * @param query - input SQL query string
64
 * @param cfg - Configuration options with required dialect object
65
 * @returns formatted query
66
 */
67
function formatDialect(
68
  query: string, 
69
  cfg: FormatOptionsWithDialect
70
): string;
71

72
type FormatOptionsWithDialect = Partial<FormatOptions> & {
73
  dialect: DialectOptions;
74
};
75
```
76

77
**Usage Examples:**
78

79
```typescript
80
import { formatDialect, mysql } from "sql-formatter";
81

82
const result = formatDialect("SELECT * FROM products", {
83
  dialect: mysql,
84
  keywordCase: "upper",
85
  tabWidth: 2
86
});
87
```
88

89
### Supported Dialects
90

91
Array of supported SQL dialect names for use with the language parameter.
92

93
```typescript { .api }
94
/**
95
 * Array of all supported SQL dialect names
96
 */
97
const supportedDialects: string[];
98
```
99

100
The supported dialects include:
101
- `"bigquery"` - Google Cloud BigQuery
102
- `"db2"` - IBM DB2  
103
- `"db2i"` - IBM DB2i
104
- `"duckdb"` - DuckDB
105
- `"hive"` - Apache Hive
106
- `"mariadb"` - MariaDB
107
- `"mysql"` - MySQL
108
- `"n1ql"` - Couchbase N1QL
109
- `"plsql"` - Oracle PL/SQL
110
- `"postgresql"` - PostgreSQL
111
- `"redshift"` - Amazon Redshift
112
- `"spark"` - Apache Spark SQL
113
- `"sqlite"` - SQLite
114
- `"sql"` - Generic SQL (default)
115
- `"tidb"` - TiDB
116
- `"trino"` - Trino
117
- `"transactsql"` - SQL Server Transact-SQL
118
- `"tsql"` - SQL Server Transact-SQL (alias)
119
- `"singlestoredb"` - SingleStoreDB
120
- `"snowflake"` - Snowflake
121

122
**Usage Examples:**
123

124
```typescript
125
import { format, supportedDialects } from "sql-formatter";
126

127
// Check if a dialect is supported
128
if (supportedDialects.includes("mysql")) {
129
  const result = format(query, { language: "mysql" });
130
}
131

132
// List all supported dialects
133
console.log("Supported dialects:", supportedDialects);
134
```
135

136
### SQL Language Type
137

138
Union type representing all supported SQL dialects.
139

140
```typescript { .api }
141
type SqlLanguage = 
142
  | "bigquery" 
143
  | "db2" 
144
  | "db2i" 
145
  | "duckdb" 
146
  | "hive" 
147
  | "mariadb" 
148
  | "mysql" 
149
  | "n1ql" 
150
  | "plsql" 
151
  | "postgresql" 
152
  | "redshift" 
153
  | "spark" 
154
  | "sqlite" 
155
  | "sql" 
156
  | "tidb" 
157
  | "trino" 
158
  | "transactsql" 
159
  | "tsql" 
160
  | "singlestoredb" 
161
  | "snowflake";
162
```
163

164
### Configuration Types
165

166
Core configuration interfaces for format functions.
167

168
```typescript { .api }
169
interface FormatOptionsWithLanguage {
170
  language?: SqlLanguage;
171
  // ... extends Partial<FormatOptions>
172
}
173

174
interface FormatOptionsWithDialect {
175
  dialect: DialectOptions;
176
  // ... extends Partial<FormatOptions>
177
}
178
```
179

180
## Error Handling
181

182
The format functions will throw errors for invalid inputs:
183

184
- **ConfigError**: Thrown when unsupported dialect or invalid configuration is provided
185
- **Error**: Thrown when query parameter is not a string
186

187
```typescript
188
import { format, ConfigError } from "sql-formatter";
189

190
try {
191
  const result = format("SELECT * FROM users", { 
192
    language: "invalid-dialect" 
193
  });
194
} catch (error) {
195
  if (error instanceof ConfigError) {
196
    console.error("Configuration error:", error.message);
197
  }
198
}
199
```