parsehouse

library0.1.1jsnpmunverified

Pure TypeScript ClickHouse SQL parser that produces a typed AST with discriminated unions, supports traversal, modification, and canonical SQL serialization. Current stable version is 0.1.1, released as an early-stage library. Key differentiators: designed specifically for ClickHouse syntax (FINAL, PREWHERE, LIMIT BY, SETTINGS), provides a structured AST with kind-based type narrowing, includes dialect configuration, and normalizes SQL output by stripping comments and whitespace. Compared to generic SQL parsers, parsehouse targets ClickHouse-specific features and TypeScript-first typing, making it suitable for building linters, validators, and refactoring tools.

database

npm install parsehouse

package ↗

INSTALL

IMPORT

SIG · PARSEHOUSE

parsehouse

databasejavascriptv0.1.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ClickHouseDialect

✓ import { ClickHouseDialect } from 'parsehouse'

✗ const { ClickHouseDialect } = require('parsehouse')

Pure ESM package; CommonJS require is not supported. Use dynamic import or ESM.

parseStatement

✓ import { parseStatement } from 'parsehouse'

✗ import parseStatement from 'parsehouse'

Named export, not default export.

toSql

✓ import { toSql } from 'parsehouse'

✗ const toSql = require('parsehouse').toSql

Named export; CommonJS require may fail due to ESM-only module.

parseSql

✓ import { parseSql } from 'parsehouse'

✗ import { parseSql } from 'parsehouse/src'

Use top-level package export, not internal paths.

parseExpr

✓ import { parseExpr } from 'parsehouse'

✗ import { parseExpression } from 'parsehouse'

Function is named parseExpr, not parseExpression.

visit

✓ import { visit } from 'parsehouse'

✗ import { traverse } from 'parsehouse'

Tree walker is called visit.

tokenize

✓ import { tokenize } from 'parsehouse'

✗ import { lex } from 'parsehouse'

Tokenization function is named tokenize.

Demonstrates parsing a ClickHouse SQL statement, inspecting AST nodes (table reference with FINAL), modifying the limit, and serializing back to canonical SQL.

import { ClickHouseDialect, parseStatement, toSql } from 'parsehouse'; const dialect = new ClickHouseDialect(); const statement = parseStatement( "SELECT user_id FROM events FINAL PREWHERE team_id = 1 LIMIT 10", { dialect }, ); if (statement.kind === 'select_statement') { const source = statement.from?.[0]; if (source?.kind === 'table_reference' && source.final) { console.log('query uses FINAL'); } statement.limit = { kind: 'limit_clause', limit: { kind: 'literal', literalType: 'number', value: 100 }, }; } console.log(toSql(statement)); // SELECT user_id FROM events FINAL PREWHERE team_id = 1 LIMIT 100

Debug

Known issues

gotchaThe package is early-stage (v0.1.1); the API and AST structure may change without major version bump.

fix

Pin to exact version and review changelog before upgrading.

affects: >=0.0.0

gotchaparseStatement throws if the input contains more than one statement. Use parseSql for multiple statements.

fix

Use parseSql instead of parseStatement when parsing scripts with semicolon-separated queries.

affects: >=0.0.0

gotchaThe package is ESM-only; CommonJS require will fail. Node.js must be configured for ES modules.

fix

Use import syntax or dynamic import; add 'type': 'module' to package.json or use .mjs extension.

affects: >=0.0.0

deprecatedCustom dialect other than ClickHouseDialect is not officially supported; the API may change.

fix

Only use ClickHouseDialect for now.

affects: >=0.0.0

gotchaAST node kinds are string literals (e.g., 'select_statement'); mistyping the kind will break type narrowing.

fix

Use the exported type guards or string constants if available; always use the exact kind value.

affects: >=0.0.0

Errors

Common errors & fixes

Cannot find module 'parsehouse' or its corresponding type declarations.

Missing TypeScript type resolution or incorrect import path.

fix

Ensure 'parsehouse' is installed: npm install parsehouse. Verify tsconfig.json includes node module resolution.

SyntaxError: Cannot use import statement outside a module

Package is ESM-only but project is CommonJS.

fix

Add 'type': 'module' to package.json, rename files to .mjs, or use dynamic import().

Require is not defined in ES module scope

Using require() in an ES module context.

fix

Use import statements instead of require().

TypeError: (0 , parsehouse_1.parseStatement) is not a function

Default import assumed but parseStatement is a named export.

fix

Use { parseStatement } in the import statement.

Upgrade

Version history

0.1.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

packageparsehouse ↗