@hdnax/sqlingo.js 0.0.1 → 0.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +124 -45
  2. package/README.npm.md +158 -0
  3. package/README.repo.md +93 -0
  4. package/dist/index.cjs +1 -1
  5. package/dist/index.cjs.map +1 -1
  6. package/dist/index.js +1 -1
  7. package/dist/index.js.map +1 -1
  8. package/package.json +9 -1
package/README.md CHANGED
@@ -1,79 +1,158 @@
1
1
  # sqlingo.js
2
2
 
3
- ![Status](https://img.shields.io/badge/status-active-brightblue)
3
+ ![Version](https://img.shields.io/badge/version-0.0.1-orange)
4
4
  ![Status](https://img.shields.io/badge/status-alpha-orange)
5
5
  ![License](https://img.shields.io/badge/license-MIT-green)
6
6
  ![SQLGlot](https://img.shields.io/badge/SQLGlot-264e95f-orange)
7
7
 
8
- A JavaScript port of [SQLGlot](https://github.com/tobymao/sqlglot), a SQL parser, transpiler, optimizer, and engine.
8
+ A JavaScript port of [SQLGlot](https://github.com/tobymao/sqlglot) (v28.10.0) — a SQL parser, transpiler, optimizer, and engine.
9
9
 
10
- Supports Typescript & CJS/ESM.
10
+ Supports TypeScript & CJS/ESM. Bundled size is around 1MB minified, gzipped.
11
11
 
12
- Bundled size is around 1MB minified, gzipped.
12
+ ## Installation
13
13
 
14
- Notice: There's currently an alternative [polyglot](https://github.com/tobilg/polyglot) library here. Check it out!
14
+ ```bash
15
+ npm install @hdnax/sqlingo.js
16
+ # or
17
+ pnpm add @hdnax/sqlingo.js
18
+ # or
19
+ yarn add @hdnax/sqlingo.js
20
+ ```
15
21
 
16
- ## Goals (& Non-goals)
22
+ Peer dependency: [`luxon`](https://www.npmjs.com/package/luxon) (^3.7.2) is required for date/time operations.
17
23
 
18
- The main goal is that sqlingo.js should be a close mirror to SQLGlot. This way, it can quickly catch up with SQLGlot bug fixes and new releases.
24
+ ## Usage
19
25
 
20
- Another goal is to stay true to Typescript convention (check [CONVENTION.md](./CONVENTION.md)).
26
+ ### Parsing
21
27
 
22
- Currently, these are non-goals:
23
- - Optimized performance.
24
- - Optimized bundle size.
25
- - Compatibility with SQLGlot (but it should be trivial to make the two compatible)
28
+ ```ts
29
+ import { parse, parseOne } from "@hdnax/sqlingo.js";
26
30
 
27
- ## Backstory
31
+ // Parse one or more SQL statements
32
+ const expressions = parse("SELECT 1; SELECT 2");
28
33
 
29
- I'm currenly maintaining [@dbml/core](https://github.com/holistics/dbml), a library that supports converting between DBML and SQL. Under the hood it uses ANTLR for parsing, and honestly it's been a mess:
30
- - `@dbml/core` is **33MB**, which is quite insane to be honest. It actually broke our CI with OOM errors.
31
- - We can't add more dialects without making the bundle even larger.
32
- - The parser is feature-incomplete and spits out user-unfriendly error messages like `No viable alternative at...`.
33
- - After all that, we only support **5 dialects**.
34
+ // Parse a single statement
35
+ const expr = parseOne("SELECT a, b FROM t WHERE a > 1");
36
+ ```
34
37
 
35
- At a hackathon, I was poking around [Dagster](https://dagster.io/) and stumbled upon SQLGlot. I thought it was amazing that there was a library like this. SQLGlot seems to be trusted by a lots of tools in the Python ecosystems.
38
+ ### Transpiling
36
39
 
37
- Since then, I was looking for an alternative in Javascript, because I want to run it on the browser. Sadly, at the time, there was none that I knew of.
40
+ ```ts
41
+ import { transpile } from "@hdnax/sqlingo.js";
38
42
 
39
- I tried running SQLGlot through [Pyodide](https://pyodide.org/) as a hack, but the runtime is way too heavy to ship anywhere that matters.
43
+ // Transpile between dialects
44
+ const [result] = transpile("SELECT EPOCH_MS(1618088028295)", {
45
+ read: "duckdb",
46
+ write: "hive",
47
+ });
48
+ // => "SELECT FROM_UNIXTIME(1618088028295 / POW(10, 3))"
49
+ ```
40
50
 
41
- Therefore, I decided to port it. At 2 weeks into my porting process, [polyglot](https://github.com/tobilg/polyglot) was announced (LOL!). However, I didn't want to waste my effort & also wanted full control - so I just continued anyways.
51
+ ### SQL Builder
42
52
 
43
- ## Development Setup
53
+ ```ts
54
+ import { select, column, condition, from } from "@hdnax/sqlingo.js";
44
55
 
45
- ### Prerequisites
56
+ const query = select(column("a"), column("b"))
57
+ .from("t")
58
+ .where(condition("a > 1"));
59
+ ```
46
60
 
47
- Make sure these are installed on your machine:
48
- - [`node`](https://nodejs.org/)@^20 - [Installation Guide](https://nodejs.org/en/download/package-manager)
49
- - [`pnpm`](https://pnpm.io/)@^10.26.1 - [Installation Guide](https://pnpm.io/installation)
61
+ ### Optimization
50
62
 
51
- ### Available Scripts
63
+ ```ts
64
+ import { optimize } from "@hdnax/sqlingo.js";
65
+ import { MappingSchema } from "@hdnax/sqlingo.js";
52
66
 
53
- ```bash
54
- pnpm test # Run tests
55
- pnpm test:ui # Run tests with UI
56
- pnpm test:coverage # Run tests with coverage
57
- pnpm build # Build the project
58
- pnpm dev # Build in watch mode
59
- pnpm typecheck # Type check without emitting
60
- pnpm lint # Lint the code
61
- pnpm lint:fix # Lint and auto-fix issues
62
- pnpm run docs # Generate documentation
67
+ const schema = new MappingSchema({
68
+ // define your schema
69
+ });
70
+
71
+ const optimized = optimize(parseOne("SELECT * FROM t"), { schema });
63
72
  ```
64
73
 
65
- ### Mirror Guide
74
+ ### Tokenizing
75
+
76
+ ```ts
77
+ import { tokenize } from "@hdnax/sqlingo.js";
78
+
79
+ const tokens = tokenize("SELECT 1", "postgres");
80
+ ```
81
+
82
+ ## Supported Dialects
83
+
84
+ Athena, BigQuery, ClickHouse, Databricks, Doris, Dremio, Drill, Druid, DuckDB, Dune, Exasol, Fabric, Hive, Materialize, MySQL, Oracle, Postgres, Presto, PRQL, Redshift, RisingWave, SingleStore, Snowflake, Solr, Spark, Spark2, SQLite, StarRocks, Tableau, Teradata, Trino, TSQL
85
+
86
+ ## Public API
66
87
 
67
- Check [CONVENTION.md](./CONVENTION.md).
88
+ The main exports from `@hdnax/sqlingo.js`:
68
89
 
69
- I have compiled our convention and lots of pitfalls there. You can use the knowledge there to allow easier debugging.
90
+ | Export | Description |
91
+ | ------------------------------------------------------------- | --------------------------------------- |
92
+ | `parse`, `parseOne` | Parse SQL strings into expression trees |
93
+ | `transpile` | Parse and generate SQL across dialects |
94
+ | `generate` | Generate SQL from an expression tree |
95
+ | `tokenize` | Tokenize a SQL string |
96
+ | `optimize` | Optimize an expression tree |
97
+ | `execute` | Execute SQL against in-memory tables |
98
+ | `Dialect`, `Dialects` | Dialect classes and enum |
99
+ | `Expression` | Base expression class |
100
+ | `select`, `from`, `column`, `condition`, `table`, `func`, ... | Expression builder helpers |
101
+ | `and`, `or`, `not` | Logical combinators |
102
+ | `union`, `intersect`, `except` | Set operations |
103
+ | `cast`, `alias`, `case_`, `subquery` | SQL clause helpers |
104
+ | `Schema`, `MappingSchema` | Schema definitions for optimizer |
105
+ | `diff` | SQL diff utility |
106
+ | `lineage` | Column lineage tracing |
107
+ | `dump`, `load` | Serialize/deserialize expression trees |
108
+
109
+ ## SQLGlot Compatibility
110
+
111
+ This package tracks [SQLGlot](https://github.com/tobymao/sqlglot) v28.10.0 (commit `264e95f`). The API surface mirrors SQLGlot's Python API, adapted to TypeScript conventions (camelCase, etc.). See [CONVENTION.md](https://github.com/huydo862003/sqlingo.js/blob/master/CONVENTION.md) for details on the mapping.
70
112
 
71
113
  ## License
72
114
 
73
- sqlingo.js is licensed under the MIT License. See [LICENSE](LICENSE) for details.
115
+ MIT. See [LICENSE](https://github.com/huydo862003/sqlingo.js/blob/master/LICENSE).
116
+
117
+ Based on [SQLGlot](https://github.com/tobymao/sqlglot) by Toby Mao (MIT). See [COPYRIGHT_NOTICE](https://github.com/huydo862003/sqlingo.js/blob/master/COPYRIGHT_NOTICE).
118
+
119
+ ## Copyright Notice
120
+
121
+ ```
122
+ This project incorporates code from the following sources:
123
+
124
+ ===============================================================================
74
125
 
75
- ## Attribution
126
+ sqlingo.js
127
+ Copyright (c) 2026 Huy DNA
128
+ Licensed under the MIT License
129
+
130
+ ===============================================================================
131
+
132
+ SQLGlot (https://github.com/tobymao/sqlglot)
133
+ Copyright (c) 2025 Toby Mao
134
+ Licensed under the MIT License
135
+
136
+ Permission is hereby granted, free of charge, to any person obtaining a copy
137
+ of this software and associated documentation files (the "Software"), to deal
138
+ in the Software without restriction, including without limitation the rights
139
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
140
+ copies of the Software, and to permit persons to whom the Software is
141
+ furnished to do so, subject to the following conditions:
142
+
143
+ The above copyright notice and this permission notice shall be included in all
144
+ copies or substantial portions of the Software.
145
+
146
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
147
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
148
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
149
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
150
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
151
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
152
+ SOFTWARE.
153
+ ```
76
154
 
77
- This project is based on [SQLGlot](https://github.com/tobymao/sqlglot) by Toby Mao, which is also licensed under the MIT License. The original SQLGlot source code is included as a submodule in this repository.
155
+ ## Links
78
156
 
79
- See [COPYRIGHT_NOTICE](COPYRIGHT_NOTICE) for full copyright information.
157
+ - [GitHub](https://github.com/huydo862003/sqlingo.js)
158
+ - [Issues](https://github.com/huydo862003/sqlingo.js/issues)
package/README.npm.md ADDED
@@ -0,0 +1,158 @@
1
+ # sqlingo.js
2
+
3
+ ![Version](https://img.shields.io/badge/version-0.0.1-orange)
4
+ ![Status](https://img.shields.io/badge/status-alpha-orange)
5
+ ![License](https://img.shields.io/badge/license-MIT-green)
6
+ ![SQLGlot](https://img.shields.io/badge/SQLGlot-264e95f-orange)
7
+
8
+ A JavaScript port of [SQLGlot](https://github.com/tobymao/sqlglot) (v28.10.0) — a SQL parser, transpiler, optimizer, and engine.
9
+
10
+ Supports TypeScript & CJS/ESM. Bundled size is around 1MB minified, gzipped.
11
+
12
+ ## Installation
13
+
14
+ ```bash
15
+ npm install @hdnax/sqlingo.js
16
+ # or
17
+ pnpm add @hdnax/sqlingo.js
18
+ # or
19
+ yarn add @hdnax/sqlingo.js
20
+ ```
21
+
22
+ Peer dependency: [`luxon`](https://www.npmjs.com/package/luxon) (^3.7.2) is required for date/time operations.
23
+
24
+ ## Usage
25
+
26
+ ### Parsing
27
+
28
+ ```ts
29
+ import { parse, parseOne } from "@hdnax/sqlingo.js";
30
+
31
+ // Parse one or more SQL statements
32
+ const expressions = parse("SELECT 1; SELECT 2");
33
+
34
+ // Parse a single statement
35
+ const expr = parseOne("SELECT a, b FROM t WHERE a > 1");
36
+ ```
37
+
38
+ ### Transpiling
39
+
40
+ ```ts
41
+ import { transpile } from "@hdnax/sqlingo.js";
42
+
43
+ // Transpile between dialects
44
+ const [result] = transpile("SELECT EPOCH_MS(1618088028295)", {
45
+ read: "duckdb",
46
+ write: "hive",
47
+ });
48
+ // => "SELECT FROM_UNIXTIME(1618088028295 / POW(10, 3))"
49
+ ```
50
+
51
+ ### SQL Builder
52
+
53
+ ```ts
54
+ import { select, column, condition, from } from "@hdnax/sqlingo.js";
55
+
56
+ const query = select(column("a"), column("b"))
57
+ .from("t")
58
+ .where(condition("a > 1"));
59
+ ```
60
+
61
+ ### Optimization
62
+
63
+ ```ts
64
+ import { optimize } from "@hdnax/sqlingo.js";
65
+ import { MappingSchema } from "@hdnax/sqlingo.js";
66
+
67
+ const schema = new MappingSchema({
68
+ // define your schema
69
+ });
70
+
71
+ const optimized = optimize(parseOne("SELECT * FROM t"), { schema });
72
+ ```
73
+
74
+ ### Tokenizing
75
+
76
+ ```ts
77
+ import { tokenize } from "@hdnax/sqlingo.js";
78
+
79
+ const tokens = tokenize("SELECT 1", "postgres");
80
+ ```
81
+
82
+ ## Supported Dialects
83
+
84
+ Athena, BigQuery, ClickHouse, Databricks, Doris, Dremio, Drill, Druid, DuckDB, Dune, Exasol, Fabric, Hive, Materialize, MySQL, Oracle, Postgres, Presto, PRQL, Redshift, RisingWave, SingleStore, Snowflake, Solr, Spark, Spark2, SQLite, StarRocks, Tableau, Teradata, Trino, TSQL
85
+
86
+ ## Public API
87
+
88
+ The main exports from `@hdnax/sqlingo.js`:
89
+
90
+ | Export | Description |
91
+ | ------------------------------------------------------------- | --------------------------------------- |
92
+ | `parse`, `parseOne` | Parse SQL strings into expression trees |
93
+ | `transpile` | Parse and generate SQL across dialects |
94
+ | `generate` | Generate SQL from an expression tree |
95
+ | `tokenize` | Tokenize a SQL string |
96
+ | `optimize` | Optimize an expression tree |
97
+ | `execute` | Execute SQL against in-memory tables |
98
+ | `Dialect`, `Dialects` | Dialect classes and enum |
99
+ | `Expression` | Base expression class |
100
+ | `select`, `from`, `column`, `condition`, `table`, `func`, ... | Expression builder helpers |
101
+ | `and`, `or`, `not` | Logical combinators |
102
+ | `union`, `intersect`, `except` | Set operations |
103
+ | `cast`, `alias`, `case_`, `subquery` | SQL clause helpers |
104
+ | `Schema`, `MappingSchema` | Schema definitions for optimizer |
105
+ | `diff` | SQL diff utility |
106
+ | `lineage` | Column lineage tracing |
107
+ | `dump`, `load` | Serialize/deserialize expression trees |
108
+
109
+ ## SQLGlot Compatibility
110
+
111
+ This package tracks [SQLGlot](https://github.com/tobymao/sqlglot) v28.10.0 (commit `264e95f`). The API surface mirrors SQLGlot's Python API, adapted to TypeScript conventions (camelCase, etc.). See [CONVENTION.md](https://github.com/huydo862003/sqlingo.js/blob/master/CONVENTION.md) for details on the mapping.
112
+
113
+ ## License
114
+
115
+ MIT. See [LICENSE](https://github.com/huydo862003/sqlingo.js/blob/master/LICENSE).
116
+
117
+ Based on [SQLGlot](https://github.com/tobymao/sqlglot) by Toby Mao (MIT). See [COPYRIGHT_NOTICE](https://github.com/huydo862003/sqlingo.js/blob/master/COPYRIGHT_NOTICE).
118
+
119
+ ## Copyright Notice
120
+
121
+ ```
122
+ This project incorporates code from the following sources:
123
+
124
+ ===============================================================================
125
+
126
+ sqlingo.js
127
+ Copyright (c) 2026 Huy DNA
128
+ Licensed under the MIT License
129
+
130
+ ===============================================================================
131
+
132
+ SQLGlot (https://github.com/tobymao/sqlglot)
133
+ Copyright (c) 2025 Toby Mao
134
+ Licensed under the MIT License
135
+
136
+ Permission is hereby granted, free of charge, to any person obtaining a copy
137
+ of this software and associated documentation files (the "Software"), to deal
138
+ in the Software without restriction, including without limitation the rights
139
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
140
+ copies of the Software, and to permit persons to whom the Software is
141
+ furnished to do so, subject to the following conditions:
142
+
143
+ The above copyright notice and this permission notice shall be included in all
144
+ copies or substantial portions of the Software.
145
+
146
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
147
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
148
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
149
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
150
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
151
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
152
+ SOFTWARE.
153
+ ```
154
+
155
+ ## Links
156
+
157
+ - [GitHub](https://github.com/huydo862003/sqlingo.js)
158
+ - [Issues](https://github.com/huydo862003/sqlingo.js/issues)
package/README.repo.md ADDED
@@ -0,0 +1,93 @@
1
+ # sqlingo.js
2
+
3
+ ![Version](https://img.shields.io/badge/version-0.0.1-orange)
4
+ ![Status](https://img.shields.io/badge/status-alpha-orange)
5
+ ![License](https://img.shields.io/badge/license-MIT-green)
6
+ ![SQLGlot](https://img.shields.io/badge/SQLGlot-264e95f-orange)
7
+
8
+ A JavaScript port of [SQLGlot](https://github.com/tobymao/sqlglot), a SQL parser, transpiler, optimizer, and engine.
9
+
10
+ Supports Typescript & CJS/ESM.
11
+
12
+ Bundled size is around 1MB minified, gzipped.
13
+
14
+ Notice: There's currently an alternative [polyglot](https://github.com/tobilg/polyglot) library here. Check it out!
15
+
16
+ ## Installation
17
+
18
+ ```bash
19
+ npm install @hdnax/sqlingo.js
20
+ # or
21
+ pnpm add @hdnax/sqlingo.js
22
+ # or
23
+ yarn add @hdnax/sqlingo.js
24
+ ```
25
+
26
+ ## Usage
27
+
28
+ See the [Usage Guide](./README.npm.md) for API documentation and examples.
29
+
30
+ ## Goals (& Non-goals)
31
+
32
+ The main goal is that sqlingo.js should be a close mirror to SQLGlot. This way, it can quickly catch up with SQLGlot bug fixes and new releases.
33
+
34
+ Another goal is to stay true to Typescript convention (check [CONVENTION.md](./CONVENTION.md)).
35
+
36
+ Currently, these are non-goals:
37
+ - Optimized performance.
38
+ - Optimized bundle size.
39
+ - Compatibility with SQLGlot (but it should be trivial to make the two compatible)
40
+
41
+ ## Backstory
42
+
43
+ I'm currenly maintaining [@dbml/core](https://github.com/holistics/dbml), a library that supports converting between DBML and SQL. Under the hood it uses ANTLR for parsing, and honestly it's been a mess:
44
+ - `@dbml/core` is **33MB**, which is quite insane to be honest. It actually broke our CI with OOM errors.
45
+ - We can't add more dialects without making the bundle even larger.
46
+ - The parser is feature-incomplete and spits out user-unfriendly error messages like `No viable alternative at...`.
47
+ - After all that, we only support **5 dialects**.
48
+
49
+ At a hackathon, I was poking around [Dagster](https://dagster.io/) and stumbled upon SQLGlot. I thought it was amazing that there was a library like this. SQLGlot seems to be trusted by a lots of tools in the Python ecosystems.
50
+
51
+ Since then, I was looking for an alternative in Javascript, because I want to run it on the browser. Sadly, at the time, there was none that I knew of.
52
+
53
+ I tried running SQLGlot through [Pyodide](https://pyodide.org/) as a hack, but the runtime is way too heavy to ship anywhere that matters.
54
+
55
+ Therefore, I decided to port it. At 2 weeks into my porting process, [polyglot](https://github.com/tobilg/polyglot) was announced (LOL!). However, I didn't want to waste my effort & also wanted full control - so I just continued anyways.
56
+
57
+ ## Development Setup
58
+
59
+ ### Prerequisites
60
+
61
+ Make sure these are installed on your machine:
62
+ - [`node`](https://nodejs.org/)@^20 - [Installation Guide](https://nodejs.org/en/download/package-manager)
63
+ - [`pnpm`](https://pnpm.io/)@^10.26.1 - [Installation Guide](https://pnpm.io/installation)
64
+
65
+ ### Available Scripts
66
+
67
+ ```bash
68
+ pnpm test # Run tests
69
+ pnpm test:ui # Run tests with UI
70
+ pnpm test:coverage # Run tests with coverage
71
+ pnpm build # Build the project
72
+ pnpm dev # Build in watch mode
73
+ pnpm typecheck # Type check without emitting
74
+ pnpm lint # Lint the code
75
+ pnpm lint:fix # Lint and auto-fix issues
76
+ pnpm run docs # Generate documentation
77
+ ```
78
+
79
+ ### Mirror Guide
80
+
81
+ Check [CONVENTION.md](./CONVENTION.md).
82
+
83
+ I have compiled our convention and lots of pitfalls there. You can use the knowledge there to allow easier debugging.
84
+
85
+ ## License
86
+
87
+ sqlingo.js is licensed under the MIT License. See [LICENSE](LICENSE) for details.
88
+
89
+ ## Attribution
90
+
91
+ This project is based on [SQLGlot](https://github.com/tobymao/sqlglot) by Toby Mao, which is also licensed under the MIT License. The original SQLGlot source code is included as a submodule in this repository.
92
+
93
+ See [COPYRIGHT_NOTICE](COPYRIGHT_NOTICE) for full copyright information.