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

Core Formatting

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

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

Capabilities

Format Function

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

/**
 * Format whitespace in a query to make it easier to read.
 * @param query - input SQL query string
 * @param cfg - Configuration options (see FormatOptionsWithLanguage)
 * @returns formatted query
 */
function format(query: string, cfg?: FormatOptionsWithLanguage): string;

type FormatOptionsWithLanguage = Partial<FormatOptions> & {
  language?: SqlLanguage;
};

Usage Examples:

import { format } from "sql-formatter";

// Basic formatting
const result = format("SELECT * FROM users WHERE active=1");
// Output: 
// SELECT
//   *
// FROM
//   users
// WHERE
//   active = 1

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

// With configuration options
const result = format("SELECT name, email FROM users ORDER BY created_at", {
  language: "postgresql", 
  tabWidth: 4,
  keywordCase: "upper",
  linesBetweenQueries: 2
});

Format Dialect Function

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

/**
 * Like the above format(), but language parameter is mandatory
 * and must be a Dialect object instead of a string.
 * @param query - input SQL query string
 * @param cfg - Configuration options with required dialect object
 * @returns formatted query
 */
function formatDialect(
  query: string, 
  cfg: FormatOptionsWithDialect
): string;

type FormatOptionsWithDialect = Partial<FormatOptions> & {
  dialect: DialectOptions;
};

Usage Examples:

import { formatDialect, mysql } from "sql-formatter";

const result = formatDialect("SELECT * FROM products", {
  dialect: mysql,
  keywordCase: "upper",
  tabWidth: 2
});

Supported Dialects

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

/**
 * Array of all supported SQL dialect names
 */
const supportedDialects: string[];

The supported dialects include:

"bigquery" - Google Cloud BigQuery
"db2" - IBM DB2
"db2i" - IBM DB2i
"duckdb" - DuckDB
"hive" - Apache Hive
"mariadb" - MariaDB
"mysql" - MySQL
"n1ql" - Couchbase N1QL
"plsql" - Oracle PL/SQL
"postgresql" - PostgreSQL
"redshift" - Amazon Redshift
"spark" - Apache Spark SQL
"sqlite" - SQLite
"sql" - Generic SQL (default)
"tidb" - TiDB
"trino" - Trino
"transactsql" - SQL Server Transact-SQL
"tsql" - SQL Server Transact-SQL (alias)
"singlestoredb" - SingleStoreDB
"snowflake" - Snowflake

Usage Examples:

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

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

// List all supported dialects
console.log("Supported dialects:", supportedDialects);

SQL Language Type

Union type representing all supported SQL dialects.

type SqlLanguage = 
  | "bigquery" 
  | "db2" 
  | "db2i" 
  | "duckdb" 
  | "hive" 
  | "mariadb" 
  | "mysql" 
  | "n1ql" 
  | "plsql" 
  | "postgresql" 
  | "redshift" 
  | "spark" 
  | "sqlite" 
  | "sql" 
  | "tidb" 
  | "trino" 
  | "transactsql" 
  | "tsql" 
  | "singlestoredb" 
  | "snowflake";

Configuration Types

Core configuration interfaces for format functions.

interface FormatOptionsWithLanguage {
  language?: SqlLanguage;
  // ... extends Partial<FormatOptions>
}

interface FormatOptionsWithDialect {
  dialect: DialectOptions;
  // ... extends Partial<FormatOptions>
}

Error Handling

The format functions will throw errors for invalid inputs:

ConfigError: Thrown when unsupported dialect or invalid configuration is provided
Error: Thrown when query parameter is not a string

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

try {
  const result = format("SELECT * FROM users", { 
    language: "invalid-dialect" 
  });
} catch (error) {
  if (error instanceof ConfigError) {
    console.error("Configuration error:", error.message);
  }
}

Install with Tessl CLI