0
# Configuration Options
1

2
Comprehensive formatting configuration including indentation, casing, operators, and layout options.
3

4
## Capabilities
5

6
### Format Options Interface
7

8
Main configuration interface for customizing SQL formatting behavior.
9

10
```typescript { .api }
11
interface FormatOptions {
12
  tabWidth: number;
13
  useTabs: boolean;
14
  keywordCase: KeywordCase;
15
  identifierCase: IdentifierCase;
16
  dataTypeCase: DataTypeCase;
17
  functionCase: FunctionCase;
18
  indentStyle: IndentStyle;
19
  logicalOperatorNewline: LogicalOperatorNewline;
20
  expressionWidth: number;
21
  linesBetweenQueries: number;
22
  denseOperators: boolean;
23
  newlineBeforeSemicolon: boolean;
24
  params?: ParamItems | string[];
25
  paramTypes?: ParamTypes;
26
}
27
```
28

29
**Default Values:**
30

31
```typescript
32
const defaultOptions: FormatOptions = {
33
  tabWidth: 2,
34
  useTabs: false,
35
  keywordCase: 'preserve',
36
  identifierCase: 'preserve',
37
  dataTypeCase: 'preserve',
38
  functionCase: 'preserve',
39
  indentStyle: 'standard',
40
  logicalOperatorNewline: 'before',
41
  expressionWidth: 50,
42
  linesBetweenQueries: 1,
43
  denseOperators: false,
44
  newlineBeforeSemicolon: false,
45
};
46
```
47

48
### Indentation Options
49

50
Control indentation style and spacing.
51

52
```typescript { .api }
53
interface IndentationOptions {
54
  /** Number of spaces for each indentation level (default: 2) */
55
  tabWidth: number;
56
  /** Use tabs instead of spaces for indentation (default: false) */
57
  useTabs: boolean;
58
  /** Indentation style for different SQL elements */
59
  indentStyle: IndentStyle;
60
}
61

62
type IndentStyle = "standard" | "tabularLeft" | "tabularRight";
63
```
64

65
**Usage Examples:**
66

67
```typescript
68
import { format } from "sql-formatter";
69

70
// Standard indentation with 4 spaces
71
const result = format(query, {
72
  tabWidth: 4,
73
  useTabs: false,
74
  indentStyle: "standard"
75
});
76

77
// Tabular left-aligned style
78
const result = format(query, {
79
  indentStyle: "tabularLeft"
80
});
81
```
82

83
### Case Transformation Options
84

85
Control casing of different SQL elements.
86

87
```typescript { .api }
88
type KeywordCase = "preserve" | "upper" | "lower";
89
type IdentifierCase = KeywordCase;
90
type DataTypeCase = KeywordCase;  
91
type FunctionCase = KeywordCase;
92

93
interface CaseOptions {
94
  /** Casing for SQL keywords like SELECT, FROM (default: "preserve") */
95
  keywordCase: KeywordCase;
96
  /** Casing for identifiers like table and column names (default: "preserve") */
97
  identifierCase: IdentifierCase;
98
  /** Casing for data types like VARCHAR, INTEGER (default: "preserve") */
99
  dataTypeCase: DataTypeCase;
100
  /** Casing for function names like COUNT, MAX (default: "preserve") */
101
  functionCase: FunctionCase;
102
}
103
```
104

105
**Usage Examples:**
106

107
```typescript
108
import { format } from "sql-formatter";
109

110
// Uppercase keywords, lowercase identifiers
111
const result = format("select user_id, count(*) from users", {
112
  keywordCase: "upper",
113
  identifierCase: "lower",
114
  functionCase: "upper"
115
});
116
// Result:
117
// SELECT
118
//   user_id,
119
//   COUNT(*)
120
// FROM
121
//   users
122
```
123

124
### Layout and Spacing Options
125

126
Control query layout, line breaks, and operator formatting.
127

128
```typescript { .api }
129
interface LayoutOptions {
130
  /** Placement of logical operators like AND, OR */
131
  logicalOperatorNewline: LogicalOperatorNewline;
132
  /** Maximum width for expressions before wrapping */
133
  expressionWidth: number;
134
  /** Number of blank lines between separate queries */
135
  linesBetweenQueries: number;
136
  /** Use compact spacing around operators */
137
  denseOperators: boolean;
138
  /** Place semicolon on new line */
139
  newlineBeforeSemicolon: boolean;
140
}
141

142
type LogicalOperatorNewline = "before" | "after";
143
```
144

145
**Usage Examples:**
146

147
```typescript
148
import { format } from "sql-formatter";
149

150
// Logical operators after conditions  
151
const result = format("SELECT * FROM users WHERE active = 1 AND role = 'admin'", {
152
  logicalOperatorNewline: "after"
153
});
154

155
// Dense operators and custom expression width
156
const result = format(query, {
157
  denseOperators: true,
158
  expressionWidth: 80,
159
  linesBetweenQueries: 2
160
});
161
```
162

163
### Parameter Configuration
164

165
Configuration for parameter placeholder replacement.
166

167
```typescript { .api }
168
interface ParameterOptions {
169
  /** Parameter values for replacement */
170
  params?: ParamItems | string[];
171
  /** Configuration for parameter placeholder types */
172
  paramTypes?: ParamTypes;
173
}
174

175
type ParamItems = { [k: string]: string };
176

177
interface ParamTypes {
178
  /** Enable positional "?" parameters */
179
  positional?: boolean;
180
  /** Prefixes for numbered parameters like :1, $2 */
181
  numbered?: ("?" | ":" | "$")[];
182
  /** Prefixes for named parameters like :name, @var */
183
  named?: (":" | "@" | "$")[];
184
  /** Prefixes for quoted parameters like :"name" */
185
  quoted?: (":" | "@" | "$")[];
186
  /** Custom parameter definitions */
187
  custom?: CustomParameter[];
188
}
189

190
interface CustomParameter {
191
  /** Regex pattern for matching the parameter */
192
  regex: string;
193
  /** Function to extract parameter name from match */
194
  key?: (text: string) => string;
195
}
196
```
197

198
**Usage Examples:**
199

200
```typescript
201
import { format } from "sql-formatter";
202

203
// Positional parameters
204
const result = format("SELECT * FROM users WHERE id = ? AND role = ?", {
205
  params: ["123", "admin"]
206
});
207

208
// Named parameters
209
const result = format("SELECT * FROM users WHERE id = :userId", {
210
  params: { userId: "123" }
211
});
212

213
// Custom parameter types
214
const result = format("SELECT * FROM users WHERE id = #{userId}", {
215
  paramTypes: {
216
    custom: [{
217
      regex: "#{\\w+}",
218
      key: (text) => text.slice(2, -1) // Remove #{ and }
219
    }]
220
  },
221
  params: { userId: "123" }
222
});
223
```
224

225
## Configuration Validation
226

227
The configuration system validates options and provides helpful error messages.
228

229
```typescript { .api }
230
class ConfigError extends Error {}
231

232
/**
233
 * Validates configuration options and throws ConfigError for invalid values
234
 */
235
function validateConfig(cfg: FormatOptions): FormatOptions;
236
```
237

238
**Common Configuration Errors:**
239

240
- Invalid `expressionWidth` (must be positive number)
241
- Invalid parameter configuration
242
- Removed/deprecated options
243

244
**Usage Examples:**
245

246
```typescript
247
import { format, ConfigError } from "sql-formatter";
248

249
try {
250
  const result = format(query, {
251
    expressionWidth: -10 // Invalid
252
  });
253
} catch (error) {
254
  if (error instanceof ConfigError) {
255
    console.error("Configuration error:", error.message);
256
  }
257
}
258
```