rawsql-ts

A high-performance SQL parser and AST transformer written in TypeScript. Parse raw SQL into objects, manipulate query structures programmatically, and generate optimized output -- all with zero dependencies.

[!NOTE] This library is currently in beta. The API may change until the v1.0 release.

Features

• Zero dependencies -- fully self-contained and lightweight
• High-performance -- significantly faster than node-sql-parser in our parse-only benchmarks
• Browser ready -- works in browsers via CDN (unpkg / jsdelivr)
• Dynamic query building -- filtering, sorting, pagination, JSON serialization, and truthful optional-condition pruning
• CTE management -- add, remove, and manipulate CTEs programmatically
• Schema validation -- static query validation against your database schema
• Full TypeScript support -- type-safe APIs throughout

Installation

npm install rawsql-ts

Or use directly in the browser via CDN:

<script type="module">
  import { parse } from "https://unpkg.com/rawsql-ts/dist/esm/index.min.js";
</script>

Quick Start

import { DynamicQueryBuilder, SqlFormatter } from "rawsql-ts";

const baseSql = "SELECT id, name, email, created_at FROM users WHERE active = true";

const builder = new DynamicQueryBuilder();
const query = builder.buildQuery(baseSql, {
  filter: { status: "premium", created_at: { ">": "2024-01-01" } },
  sort: { created_at: { desc: true }, name: { asc: true } },
  paging: { page: 2, pageSize: 10 },
});

const formatter = new SqlFormatter();
const { formattedSql, params } = formatter.format(query);

SSSQL for Optional Conditions

When the request is "add an optional filter", rawsql-ts can keep the SQL source truthful instead of pushing you toward string-built WHERE assembly.

const sql = `
  SELECT p.product_id, p.product_name
  FROM products p
  WHERE (:brand_name IS NULL OR p.brand_name = :brand_name)
    AND (:category_name IS NULL OR EXISTS (
      SELECT 1
      FROM product_categories pc
      JOIN categories c
        ON c.category_id = pc.category_id
      WHERE pc.product_id = p.product_id
        AND c.category_name = :category_name
    ))
`;

const builder = new DynamicQueryBuilder();
const query = builder.buildQuery(sql, {
  optionalConditionParameters: {
    brand_name: null,
    category_name: "shoes",
  },
});

This SSSQL style keeps optionality visible in the SQL itself and lets rawsql-ts prune only the explicitly targeted absent branches. Use DynamicQueryBuilder filter injection first for optional predicates on columns that already exist in the current query. Reach for SSSQL when the optional filter needs a table or branch that is not already part of the query graph.

Read more:

• What Is SSSQL?
• SSSQL Optional Branch Pruning MVP
• Querybuilding Recipes

API Overview

Parsing

| Class | Description | Docs | | ------------------- | -------------------------------- | -------------------------------------------------- | | SelectQueryParser | Parse SELECT statements into AST | Guide | | InsertQueryParser | Parse INSERT statements into AST | API | | UpdateQueryParser | Parse UPDATE statements into AST | API | | DeleteQueryParser | Parse DELETE statements into AST | API |

Query Building

| Class | Description | Docs | | -------------------------- | -------------------------------------------------------------- | --------------------------------------------------------- | | DynamicQueryBuilder | All-in-one filtering, sorting, pagination, serialization, and SSSQL optional-condition pruning | Guide | | QueryBuilder | Convert SELECT queries into INSERT / UPDATE statements | API | | PostgresJsonQueryBuilder | Transform relational queries into hierarchical JSON structures | API |

Injection

| Class | Description | Docs | | ----------------------- | -------------------------------------------------------------- | ------------------------------------------------------ | | SqlParamInjector | Dynamic WHERE condition injection from parameters | API | | SqlSortInjector | Dynamic ORDER BY injection with ASC/DESC and NULLS positioning | API | | SqlPaginationInjector | Dynamic LIMIT/OFFSET injection with page-based support | API |

Formatting

| Class | Description | Docs | | -------------- | --------------------------------------------------------------------- | ----------------------------------------------- | | SqlFormatter | SQL formatting with indentation, keyword casing, and comment handling | Guide |

Analysis

| Class | Description | Docs | | --------------------------- | ----------------------------------------------------- | ---------------------------------------------------------- | | SelectableColumnCollector | Extract column references for dependency analysis | API | | SqlSchemaValidator | Validate queries against a database schema definition | API | | QueryFlowDiagramGenerator | Generate Mermaid flow diagrams from SQL queries | API |

Schema & CTE

| Class | Description | Docs | | ------------------- | ---------------------------------------------------------- | -------------------------------------------------- | | SchemaManager | Unified schema definition with type-safe format conversion | API | | SimpleSelectQuery | Programmatic CTE management (add, remove, replace) | API |

Benchmarks

This section reports parse-only benchmark results for the SQL parser. It measures AST parsing time, not SQL formatting time.

For readability, workloads are described by approximate SQL line counts, with token counts included in parentheses for technical precision. Parser cost is driven more directly by token volume than by formatting style.

Across these workloads, parsing remains fast and stable, performance remains practical, and no performance cliff was observed up to the very large case.

| Workload | rawsql-ts | node-sql-parser | |----------|----------:|----------------:| | Small query, about 8 lines (70 tokens) | 0.040 ms | 0.687 ms (17.0x) | | Medium query, about 12 lines (140 tokens) | 0.080 ms | 0.744 ms (9.3x) | | Large query, about 20 lines (230 tokens) | 0.168 ms | 1.560 ms (9.3x) | | Mid-large query, about 400-500 lines (5,000 tokens) | 4.438 ms | 36.520 ms (8.2x) | | Very large query, about 1,000+ lines (~12,000 tokens) | 8.173 ms | 54.775 ms (6.7x) |

Benchmarked on AMD Ryzen 7 7800X3D / Node.js v22.14.0 / node-sql-parser 5.4.0 (2026-03-06). The mid-large and very large cases use benchmark-only analytics-style SQL workloads that represent practical long-query classes rather than formatter scenarios. See benchmark details for full results.

Online Demo

Try rawsql-ts in your browser

License

MIT