Poor Man's T-SQL Formatter - NPM Package

An NPM package for the Poor Man's T-SQL Formatter JS Library.

This library is transpiled from the C# original (it's not a port in that
the JS code is never maintained independently) - so for history of changes,
issues with the library itself, etc please see https://github.com/TaoK/PoorMansTSqlFormatter.

This library exists to make it easy to include the formatter library in websites,
in random node projects or in command-line usage in node-friendly environments
(which may not be as C#-friendly / mono-friendly).

This library also has a much better (in my opionion) API than the original C# library,
hopefully I'll get around to changing the source at some point.

There is one serious consideration that might drive you to the C#/mono library or
command-line utility, however: **This JS library is about 8x slower than the C#
original**. I haven't investigated exactly why yet, but I don't hold high hopes of
this changing anytime soon. If you need to deal with large sets of files and
performance matters, you will likely want to look at the C#/mono library/project.

Please note, there is a command-line utility for node/npm also, but **it is in a
separate npm package**, poor-mans-t-sql-formatter-cli
(github: https://github.com/TaoK/poor-mans-t-sql-formatter-npm-cli)

Installation

npm install poor-mans-t-sql-formatter

Usage

This JS library exposes a very simple API to the formatter: one method, with options, returning one datastructure (with optional bits).

Example:

``
var formatterLib = require('poor-mans-t-sql-formatter');
var queryToFormat = "select 1 from somewhere WHERE someoneforgot = punctuation and [we want better] = 1";
var result = formatterLib.formatSql(queryToFormat);
console.log(result.text);
`

Options are provided in a second argument.

Example:

`
var formatterLib = require('poor-mans-t-sql-formatter');
var result = formatterLib.formatSql("select 1, 2, 3, 4 from counter", { trailingCommas: false, spaceAfterExpandedComma: true });
console.log(result.text);
`

General options:

| Option | Description | Type | Default |
| --- | --- | --- | --- |
| formattingType | `standard`, `identity` or `obfuscation` - what you'd like to do | enum | standard |
| errorOutputPrefix | Text to be included (in a comment at the top) if parsing failed and result is therefore suspect | string | (something like "--WARNING: errors during parsing") |
| includeText | Specify that the formatted SQL should be included in the result as a Text value/property | bool | true |
| includeHtml | Specify that the formatted SQL should be included in the result as HTML | bool | false |
| includeHtmlPage | Specify that the formatted SQL should be included in the result as a full HTML document | bool | false |
| includeTokenList | Specify that the Token List produced from the Tokenization phase should be included | bool | false |
| includeParseTree | Specify that the Parse Tree produced from the Parsing phase should be included | bool | false |

Standard formatter options:

| Option | Description | Type | Default |
| --- | --- | --- | --- |
| indent | The unit of indentation - typically a tab (\t) or a number of spaces | string | \t |
| maxLineWidth | Request that the formatter wrap long lines to avoid exceeding this line length | int | 999 |
| spacesPerTab | This is used to measure line length, and only applies if you use tabs | int | 4 |
| statementBreaks | How many linebreaks should be added when starting a new statement? | int | 2 |
| clauseBreaks | How many linebreaks should be added when starting a new clause within a statement? | int | 1 |
| expandCommaLists | Should comma-delimited lists (columns, group by args, etc) be broken out onto new lines? | bool | true |
| trailingCommas | When starting a new line because of a comma, should the comma be at the end of line (VS the start of the next)? | bool | true |
| spaceAfterExpandedComma | Should a space be added after the comma? (typically not if they are "trailing") | bool | false |
| expandBooleanExpressions | Should boolean operators (AND, OR) cause a linebreak? | bool | true |
| expandCaseStatements | Should CASE expressions have their WHEN and THEN expressions be broken out on new lines? | bool | true |
| expandBetweenConditions | Should BETWEEN expressions have the max argument broken out on a new line? | bool | true |
| expandInLists | Should IN() lists have each argument on a new line? | bool | false |
| breakJoinOnSections | Should the ON section of a JOIN clause be broken out onto its own line? | bool | false |
| uppercaseKeywords | Should T-SQL keywords (like SELECT, FROM) be automatically uppercased? | bool | true |
| coloring | (In HTML output, if enabled) should keywords, comments etc have distinct color classes? | bool | true |
| keywordStandardization | Should less-common T-SQL keywords be replaced with their standard counterparts? (NOTE: only safe for T-SQL!) | bool | false |

Obfuscating formatter options:

| Option | Description | Type | Default |
| --- | --- | --- | --- |
| randomizeKeywordCase | Should the case of keywords be randomized, to minimize legibility? | bool | false |
| randomizeColor | (In HTML output, if enabled) should the color of the SQL text be randomly varied? | bool | false |
| randomizeLineLengths | Should the SQL be wrapped at arbitrary intervals, to minimize legibility? | bool | false |
| preserveComments | Should comments in the code be retained (vs being stripped out)? | bool | true |
| enableKeywordSubstitution | Should keywords with synonyms use less common forms? (NOTE: only safe for T-SQL!) | bool | false |

Tests

npm test`

(please note, coverage is not yet up to scratch; the general goal is to address the same test cases as the C# library)

License

This library, like the original at https://github.com/TaoK/PoorMansTSqlFormatter, is
made freely available under the AGPL 3.0 license.

Contributing

Given that this module is mostly wrapping over the original code at
https://github.com/TaoK/PoorMansTSqlFormatter, there is little opportunity for
contributing here - but any input is of course welcome!

To produce/refresh the npm library file (index.js) just run the build.sh script.
When executed from the root of the project, it will simply collect the files from
the parent project in github and add the wrapper code defined in prefix and suffix
files.

STATUS

When it is published, I'll see if I can take care of all those trendy things like:

* CI & test tracking
* coverage tracking
* a suitable "try it out" link
* Think about restructuring the library into a "legacylib" file (using prefix/suffix build process) and a new stuff file.
* (anything else?)

Eventually, probably once the library has been published and shows some sign of interest/activity, I'll go for the bigger stuff

* look for perf opportunities. 8s is a LONG time for some simple tests!! (C# equivalent is 1s) - otherwise DOCUMENT the terrible performance...