sqlglot-ts

0.1.5 verified Fri May 01 auth: no javascript

TypeScript port of SQLGlot — a SQL parser and transpiler with browser-first design and zero runtime dependencies. Current version 0.1.5 is an early release; DuckDB dialect is thoroughly tested against Python SQLGlot's suite (500+ test cases), while other included dialects (PostgreSQL, BigQuery, Snowflake, etc.) have partial coverage. Unique differentiator: unbundled ESM modules allow tree-shaking per dialect, keeping bundle sizes small (core ~80KB gzipped, plus ~20–40KB per dialect). Unlike alternatives (e.g., node-sql-parser, moo-based parsers), sqlglot-ts emphasizes transpilation between dialects and full AST traversal.

Common errors

error Cannot find module 'sqlglot-ts/dialects/duckdb' or its corresponding type declarations. ↓

cause Missing or misconfigured TypeScript module resolution; deep imports may not be recognized.

fix

Ensure tsconfig.json includes 'moduleResolution': 'node16' or 'nodenext' and 'allowImportingTsExtensions': false.

error Error: Dialect 'duckdb' not registered. Did you import a dialect module? ↓

cause Dialect side-effect import missing before calling parse/transpile functions.

fix

Add import 'sqlglot-ts/dialects/duckdb' at the top of your file before any sqlglot-ts usage.

error TypeError: ast.walk is not a function ↓

cause ast is not a proper Expression object; likely parseOne() returned an error object due to invalid SQL.

fix

Check ast.errors after parseOne() to validate; handle invalid SQL gracefully.

error Cannot read properties of undefined (reading 'generate') ↓

cause Dialect class not imported or incorrectly imported. generate is a static method on dialect classes.

fix

Import the dialect class: import { Postgres } from 'sqlglot-ts/dialects' then use Postgres.generate(ast).

Warnings

breaking Dialect side-effect imports must precede any parsing/transpilation calls. ↓

fix Add import 'sqlglot-ts/dialects/your-dialect' at top of file before usage.

gotcha parseOne() does not throw on invalid SQL; returns a partial AST with errors attached. ↓

fix Check ast.errors after parsing to detect syntax errors.

deprecated Direct import of dialect classes from 'sqlglot-ts/dialects' is preferred over 'sqlglot-ts/dialects/duckdb' side-effect imports for type access. ↓

fix Use import { DuckDB } from 'sqlglot-ts/dialects' when you need the class; retain side-effect imports for registration.

gotcha transpileOne() returns a string; transpile() returns an array of strings. Mixing them up causes type errors. ↓

fix Use transpileOne for single statement input; for multi-statement SQL, use transpile() and handle the array.

breaking Node.js >=18 required; engine restriction enforced. ↓

fix Upgrade to Node.js 18 or later.

gotcha Browser bundlers may tree-shake dialect registrations if imports are not recognized as side effects. ↓

fix Configure your bundler (e.g., Vite: module.rules) to treat 'sqlglot-ts/dialects/*' as side-effectful.

Install

npm install sqlglot-ts

yarn add sqlglot-ts

pnpm add sqlglot-ts

Imports

parseOne
wrong
```
const { parseOne } = require('sqlglot-ts')
```
correct
```
import { parseOne } from 'sqlglot-ts'
```
ESM-only; CommonJS require() fails in Node < 22 or without experimental VM modules.

transpileOne

wrong

import { transpileOne } from 'sqlglot-ts'; transpileOne(sql, { read: 'duckdb', write: 'postgres' })

correct

import { transpileOne } from 'sqlglot-ts'; import 'sqlglot-ts/dialects/duckdb'; import 'sqlglot-ts/dialects/postgres'

Dialects must be imported as side effects before calling transpileOne; otherwise the default standard SQL dialect is used, leading to unexpected results.

DuckDB
wrong
```
import { DuckDB } from 'sqlglot-ts'
```
correct
```
import { DuckDB } from 'sqlglot-ts/dialects'
```
Dialect classes are exported from 'sqlglot-ts/dialects', not the main package. Importing from 'sqlglot-ts' only yields core functions.
exp
wrong
```
import { Column } from 'sqlglot-ts'
```
correct
```
import * as exp from 'sqlglot-ts/expressions'
```
Expression types and classes are under 'sqlglot-ts/expressions'; re-exports from main package are not available.

Quickstart

Parses a DuckDB-specific SQL statement and transpiles it to PostgreSQL, demonstrating dialect imports and transpilation.

import { parseOne, transpileOne } from 'sqlglot-ts';
import 'sqlglot-ts/dialects/duckdb';
import 'sqlglot-ts/dialects/postgres';
const ast = parseOne('SELECT TRY_CAST(x AS INT)');
console.log(ast.sql());
const result = transpileOne('SELECT TRY_CAST(x AS INT)', { read: 'duckdb', write: 'postgres' });
console.log(result);