tessl/npm-sql-formatter

Format whitespace in a SQL query to make it more readable with support for multiple SQL dialects

—

Pending

Overview

Eval results

Files

Configuration Options

Name: tessl/npm-sql-formatter
Author: tessl

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

Capabilities

Format Options Interface

Main configuration interface for customizing SQL formatting behavior.

interface FormatOptions {
  tabWidth: number;
  useTabs: boolean;
  keywordCase: KeywordCase;
  identifierCase: IdentifierCase;
  dataTypeCase: DataTypeCase;
  functionCase: FunctionCase;
  indentStyle: IndentStyle;
  logicalOperatorNewline: LogicalOperatorNewline;
  expressionWidth: number;
  linesBetweenQueries: number;
  denseOperators: boolean;
  newlineBeforeSemicolon: boolean;
  params?: ParamItems | string[];
  paramTypes?: ParamTypes;
}

Default Values:

const defaultOptions: FormatOptions = {
  tabWidth: 2,
  useTabs: false,
  keywordCase: 'preserve',
  identifierCase: 'preserve',
  dataTypeCase: 'preserve',
  functionCase: 'preserve',
  indentStyle: 'standard',
  logicalOperatorNewline: 'before',
  expressionWidth: 50,
  linesBetweenQueries: 1,
  denseOperators: false,
  newlineBeforeSemicolon: false,
};

Indentation Options

Control indentation style and spacing.

interface IndentationOptions {
  /** Number of spaces for each indentation level (default: 2) */
  tabWidth: number;
  /** Use tabs instead of spaces for indentation (default: false) */
  useTabs: boolean;
  /** Indentation style for different SQL elements */
  indentStyle: IndentStyle;
}

type IndentStyle = "standard" | "tabularLeft" | "tabularRight";

Usage Examples:

import { format } from "sql-formatter";

// Standard indentation with 4 spaces
const result = format(query, {
  tabWidth: 4,
  useTabs: false,
  indentStyle: "standard"
});

// Tabular left-aligned style
const result = format(query, {
  indentStyle: "tabularLeft"
});

Case Transformation Options

Control casing of different SQL elements.

type KeywordCase = "preserve" | "upper" | "lower";
type IdentifierCase = KeywordCase;
type DataTypeCase = KeywordCase;  
type FunctionCase = KeywordCase;

interface CaseOptions {
  /** Casing for SQL keywords like SELECT, FROM (default: "preserve") */
  keywordCase: KeywordCase;
  /** Casing for identifiers like table and column names (default: "preserve") */
  identifierCase: IdentifierCase;
  /** Casing for data types like VARCHAR, INTEGER (default: "preserve") */
  dataTypeCase: DataTypeCase;
  /** Casing for function names like COUNT, MAX (default: "preserve") */
  functionCase: FunctionCase;
}

Usage Examples:

import { format } from "sql-formatter";

// Uppercase keywords, lowercase identifiers
const result = format("select user_id, count(*) from users", {
  keywordCase: "upper",
  identifierCase: "lower",
  functionCase: "upper"
});
// Result:
// SELECT
//   user_id,
//   COUNT(*)
// FROM
//   users

Layout and Spacing Options

Control query layout, line breaks, and operator formatting.

interface LayoutOptions {
  /** Placement of logical operators like AND, OR */
  logicalOperatorNewline: LogicalOperatorNewline;
  /** Maximum width for expressions before wrapping */
  expressionWidth: number;
  /** Number of blank lines between separate queries */
  linesBetweenQueries: number;
  /** Use compact spacing around operators */
  denseOperators: boolean;
  /** Place semicolon on new line */
  newlineBeforeSemicolon: boolean;
}

type LogicalOperatorNewline = "before" | "after";

Usage Examples:

import { format } from "sql-formatter";

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

// Dense operators and custom expression width
const result = format(query, {
  denseOperators: true,
  expressionWidth: 80,
  linesBetweenQueries: 2
});

Parameter Configuration

Configuration for parameter placeholder replacement.

interface ParameterOptions {
  /** Parameter values for replacement */
  params?: ParamItems | string[];
  /** Configuration for parameter placeholder types */
  paramTypes?: ParamTypes;
}

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

interface ParamTypes {
  /** Enable positional "?" parameters */
  positional?: boolean;
  /** Prefixes for numbered parameters like :1, $2 */
  numbered?: ("?" | ":" | "$")[];
  /** Prefixes for named parameters like :name, @var */
  named?: (":" | "@" | "$")[];
  /** Prefixes for quoted parameters like :"name" */
  quoted?: (":" | "@" | "$")[];
  /** Custom parameter definitions */
  custom?: CustomParameter[];
}

interface CustomParameter {
  /** Regex pattern for matching the parameter */
  regex: string;
  /** Function to extract parameter name from match */
  key?: (text: string) => string;
}

Usage Examples:

import { format } from "sql-formatter";

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

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

// Custom parameter types
const result = format("SELECT * FROM users WHERE id = #{userId}", {
  paramTypes: {
    custom: [{
      regex: "#{\\w+}",
      key: (text) => text.slice(2, -1) // Remove #{ and }
    }]
  },
  params: { userId: "123" }
});

Configuration Validation

The configuration system validates options and provides helpful error messages.

class ConfigError extends Error {}

/**
 * Validates configuration options and throws ConfigError for invalid values
 */
function validateConfig(cfg: FormatOptions): FormatOptions;

Common Configuration Errors:

Invalid expressionWidth (must be positive number)
Invalid parameter configuration
Removed/deprecated options

Usage Examples:

import { format, ConfigError } from "sql-formatter";

try {
  const result = format(query, {
    expressionWidth: -10 // Invalid
  });
} catch (error) {
  if (error instanceof ConfigError) {
    console.error("Configuration error:", error.message);
  }
}

Install with Tessl CLI