From f86b532c87125e30cddf524f0bc2249453325359 Mon Sep 17 00:00:00 2001
From: Rene Saarsoo <nene@triin.net>
Date: Fri, 4 Nov 2022 19:32:47 +0200
Subject: [PATCH] Document the new dialect config option

---
 README.md        |  3 +-
 docs/dialect.md  | 86 ++++++++++++++++++++++++++++++++++++++++++++++++
 docs/language.md | 38 +++++++++------------
 3 files changed, 104 insertions(+), 23 deletions(-)
 create mode 100644 docs/dialect.md

diff --git a/README.md b/README.md
index 14e2eda456..1a4cfb508a 100644
--- a/README.md
+++ b/README.md
@@ -144,7 +144,8 @@ All fields are optional and all fields that are not specified will be filled wit
 
 ### Configuration options
 
-- [**`language`**](docs/language.md) the SQL dialect to use.
+- [**`language`**](docs/language.md) the SQL dialect to use (when using `format()`).
+- [**`dialect`**](docs/dialect.md) the SQL dialect to use (when using `formatDialect()` since version 12).
 - [**`tabWidth`**](docs/tabWidth.md) amount of indentation to use.
 - [**`useTabs`**](docs/useTabs.md) to use tabs for indentation.
 - [**`keywordCase`**](docs/keywordCase.md) uppercases or lowercases keywords.
diff --git a/docs/dialect.md b/docs/dialect.md
new file mode 100644
index 0000000000..2e3ed8656a
--- /dev/null
+++ b/docs/dialect.md
@@ -0,0 +1,86 @@
+# dialect
+
+Specifies the SQL dialect to use.
+
+## Usage
+
+```ts
+import { formatDialect, sqlite } from 'sql-formatter';
+
+const result = formatDialect('SELECT * FROM tbl', { dialect: sqlite });
+```
+
+**Note:** This is part of new API, introduced in version 12.
+It can only be used together with the new `formatDialect()` function,
+not with the old `format()` function.
+It also can't be used in config file of the command line tool -
+for that, use the [language][] option.
+
+## Options
+
+The following dialects can be imported from `"sql-formatter"` module:
+
+- `sql` - [Standard SQL][]
+- `bigquery` - [GCP BigQuery][]
+- `db2` - [IBM DB2][]
+- `hive` - [Apache Hive][]
+- `mariadb` - [MariaDB][]
+- `mysql` - [MySQL][]
+- `n1ql` - [Couchbase N1QL][]
+- `plsql` - [Oracle PL/SQL][]
+- `postgresql` - [PostgreSQL][]
+- `redshift` - [Amazon Redshift][]
+- `singlestoredb` - [SingleStoreDB][]
+- `snowflake` - [Snowflake][]
+- `spark` - [Spark][]
+- `sqlite` - [SQLite][]
+- `transactsql` - [SQL Server Transact-SQL][tsql]
+- `trino` - [Trino][] / [Presto][]
+
+The `sql` dialect is meant for cases where you don't know which dialect of SQL you're about to format.
+It's not an auto-detection, it just supports a subset of features common enough in many SQL implementations.
+This might or might not work for your specific dialect.
+Better to always pick something more specific if possible.
+
+## Custom dialect configuration (experimental)
+
+The `dialect` parameter can also be used to specify a custom SQL dialect configuration:
+
+```ts
+import { formatDialect, DialectOptions } from 'sql-formatter';
+
+const myDialect: DialectOptions {
+  tokenizerOptions: {
+    // See source code for examples of tokenizer config options
+    // For example: src/languages/sqlite/sqlite.formatter.ts
+  },
+  formatOptions: {
+    // ...
+  },
+};
+
+const result = formatDialect('SELECT * FROM tbl', { dialect: myDialect });
+```
+
+**NB!** This functionality is experimental and there are no stability guarantees for this API.
+The `DialectOptions` interface can (and likely will) change in non-major releases.
+You likely only want to use this if your other alternative is to fork SQL Formatter.
+
+[standard sql]: https://en.wikipedia.org/wiki/SQL:2011
+[gcp bigquery]: https://cloud.google.com/bigquery
+[ibm db2]: https://www.ibm.com/analytics/us/en/technology/db2/
+[apache hive]: https://hive.apache.org/
+[mariadb]: https://mariadb.com/
+[mysql]: https://www.mysql.com/
+[couchbase n1ql]: http://www.couchbase.com/n1ql
+[oracle pl/sql]: http://www.oracle.com/technetwork/database/features/plsql/index.html
+[postgresql]: https://www.postgresql.org/
+[presto]: https://prestodb.io/docs/current/
+[amazon redshift]: https://docs.aws.amazon.com/redshift/latest/dg/cm_chap_SQLCommandRef.html
+[singlestoredb]: https://docs.singlestore.com/managed-service/en/reference.html
+[snowflake]: https://docs.snowflake.com/en/index.html
+[spark]: https://spark.apache.org/docs/latest/api/sql/index.html
+[sqlite]: https://sqlite.org/index.html
+[trino]: https://trino.io/docs/current/
+[tsql]: https://docs.microsoft.com/en-us/sql/sql-server/
+[language]: ./language.md
diff --git a/docs/language.md b/docs/language.md
index 2f17d37231..21a5c9a667 100644
--- a/docs/language.md
+++ b/docs/language.md
@@ -2,6 +2,14 @@
 
 Specifies the SQL dialect to use.
 
+## Usage
+
+```ts
+import { format } from 'sql-formatter';
+
+const result = format('SELECT * FROM tbl', { dialect: 'sqlite' });
+```
+
 ## Options
 
 - `"sql"` - (default) [Standard SQL][]
@@ -20,36 +28,21 @@ Specifies the SQL dialect to use.
 - `"sqlite"` - [SQLite][sqlite]
 - `"transactsql"` or `"tsql"` - [SQL Server Transact-SQL][tsql]
 - `"trino"` - [Trino][] / [Presto][]
-- custom SQL dialect configuration object (see below)
 
 The default `"sql"` dialect is meant for cases where you don't know which dialect of SQL you're about to format.
 It's not an auto-detection, it just supports a subset of features common enough in many SQL implementations.
 This might or might not work for your specific dialect.
 Better to always pick something more specific if possible.
 
-### Custom dialect configuration (experimental)
+## Impact on bundle size
 
-The language parameter can also be used to specify a custom SQL dialect configuration:
-
-```ts
-import { format, DialectOptions } from 'sql-formatter';
-
-const myDialect: DialectOptions {
-  tokenizerOptions: {
-    // See source code for examples of tokenizer config options
-    // For example: src/languages/sqlite/sqlite.formatter.ts
-  },
-  formatOptions: {
-    // ...
-  },
-};
-
-const result = format('SELECT * FROM tbl', { language: myDialect });
-```
+Using the `language` option has the downside that the used dialects are determined at runtime
+and therefore they all have to be bundled when e.g. building a bundle with Webpack.
+This can result in significant overhead when you only need to format one or two dialects.
 
-**NB!** This functionality is experimental and there are no stability guarantees for this API.
-The DialectOptions interface can (and likely will) change in non-major releases.
-You likely only want to use this if your other alternative is to fork SQL Formatter.
+To solve this problem, version 12 of SQL Formatter introduces a new API,
+that allows explicitly importing the dialects.
+See docs for [dialect][] option.
 
 [standard sql]: https://en.wikipedia.org/wiki/SQL:2011
 [gcp bigquery]: https://cloud.google.com/bigquery
@@ -68,3 +61,4 @@ You likely only want to use this if your other alternative is to fork SQL Format
 [sqlite]: https://sqlite.org/index.html
 [trino]: https://trino.io/docs/current/
 [tsql]: https://docs.microsoft.com/en-us/sql/sql-server/
+[dialect]: ./dialect.md