@questdb/sql-parser 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changelog
+
+## 0.1.0 - 2026.02.19
+- Initial release

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025 QuestDB
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,228 @@
+# @questdb/sql-parser
+
+An SQL parser for [QuestDB](https://questdb.io/) syntax, built with [Chevrotain](https://chevrotain.io/). Parses SQL into a fully typed AST, converts AST back to SQL, and provides context-aware autocomplete — all in a single package.
+
+## Features
+
+- **Complete QuestDB SQL coverage** — 45 statement types including SELECT, INSERT, UPDATE, CREATE TABLE, ALTER TABLE, GRANT/REVOKE, COPY, PIVOT, and more
+- **QuestDB-specific syntax** — `SAMPLE BY`, `LATEST ON`, `ASOF JOIN`, `LT JOIN`, `SPLICE JOIN`, `WINDOW JOIN`, implicit SELECT, duration literals, geohash types
+- **Lossless round-trip** — parse SQL to AST and convert back with `toSql()`. Verified against 1,726 real-world queries from QuestDB documentation with full round-trip coverage
+- **Context-aware autocomplete** — schema-driven suggestions for tables, columns, keywords, functions, and operators at any cursor position
+- **Fully typed** — complete TypeScript type definitions for the entire AST
+- **Single dependency** — only Chevrotain at runtime
+
+
+## Quick Start
+
+### Parse SQL to AST
+
+```typescript
+import { parseToAst } from "@questdb/sql-parser";
+
+const result = parseToAst("SELECT * FROM trades WHERE symbol = 'BTC-USD'");
+
+if (result.errors.length === 0) {
+  console.log(result.ast[0]);
+  // {
+  //   type: "select",
+  //   columns: [{ type: "star" }],
+  //   from: [{ type: "tableRef", table: { type: "qualifiedName", parts: ["trades"] } }],
+  //   where: {
+  //     type: "binary", operator: "=",
+  //     left: { type: "column", name: { type: "qualifiedName", parts: ["symbol"] } },
+  //     right: { type: "literal", value: "BTC-USD", literalType: "string" }
+  //   }
+  // }
+}
+```
+
+### Convert AST back to SQL
+
+```typescript
+import { parseToAst, toSql } from "@questdb/sql-parser";
+
+const result = parseToAst("SELECT avg(price) FROM trades SAMPLE BY 1h FILL(PREV)");
+const sql = toSql(result.ast);
+// "SELECT avg(price) FROM trades SAMPLE BY 1h FILL(PREV)"
+```
+
+### Parse a single statement
+
+```typescript
+import { parseOne } from "@questdb/sql-parser";
+
+const stmt = parseOne("INSERT INTO trades VALUES (now(), 'BTC', 42000.50)");
+console.log(stmt.type); // "insert"
+```
+
+### Parse multiple statements
+
+```typescript
+import { parseStatements } from "@questdb/sql-parser";
+
+const statements = parseStatements(`
+  SELECT * FROM trades
+  INSERT INTO logs VALUES (1)
+  CREATE TABLE orders (id LONG, ts TIMESTAMP) TIMESTAMP(ts) PARTITION BY DAY WAL
+`);
+
+console.log(statements.length); // 3
+```
+
+### Autocomplete
+
+```typescript
+import { createAutocompleteProvider } from "@questdb/sql-parser";
+
+const provider = createAutocompleteProvider({
+  tables: [
+    { name: "trades", designatedTimestamp: "ts" },
+    { name: "orders" },
+  ],
+  columns: {
+    trades: [
+      { name: "ts", type: "TIMESTAMP" },
+      { name: "symbol", type: "SYMBOL" },
+      { name: "price", type: "DOUBLE" },
+    ],
+    orders: [
+      { name: "id", type: "LONG" },
+      { name: "created_at", type: "TIMESTAMP" },
+    ],
+  },
+});
+
+const suggestions = provider.getSuggestions("SELECT * FROM t", 16);
+// [{ label: "trades", kind: "Table", insertText: "trades", ... }, ...]
+```
+
+## Supported Statements
+
+| Category               | Statements                                                                                                                                 |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Query**              | `SELECT`, implicit SELECT, `PIVOT`, `EXPLAIN`                                                                                              |
+| **DML**                | `INSERT`, `INSERT ATOMIC`, `INSERT BATCH`, `UPDATE`                                                                                        |
+| **DDL**                | `CREATE TABLE`, `ALTER TABLE`, `DROP TABLE`, `TRUNCATE TABLE`, `RENAME TABLE`                                                              |
+| **Views**              | `CREATE VIEW`, `ALTER VIEW`, `DROP VIEW`, `COMPILE VIEW`                                                                                   |
+| **Materialized Views** | `CREATE MATERIALIZED VIEW`, `ALTER MATERIALIZED VIEW`, `DROP MATERIALIZED VIEW`, `REFRESH MATERIALIZED VIEW`                               |
+| **Access Control**     | `CREATE/ALTER/DROP USER`, `CREATE/ALTER/DROP GROUP`, `CREATE/ALTER/DROP SERVICE ACCOUNT`, `ADD/REMOVE USER`, `ASSUME/EXIT SERVICE ACCOUNT` |
+| **Permissions**        | `GRANT`, `REVOKE`, `GRANT/REVOKE ASSUME SERVICE ACCOUNT`                                                                                   |
+| **Operations**         | `COPY FROM/TO`, `BACKUP`, `VACUUM TABLE`, `REINDEX TABLE`, `CANCEL QUERY`, `CHECKPOINT`, `SNAPSHOT`                                        |
+| **WAL**                | `RESUME WAL`, `SET TYPE WAL`                                                                                                               |
+| **Introspection**      | `SHOW TABLES/COLUMNS/PARTITIONS/CREATE TABLE/PARAMETERS/...`                                                                               |
+
+## QuestDB-Specific Syntax
+
+The parser handles QuestDB extensions that standard SQL parsers don't support:
+
+```sql
+-- Time-series sampling
+SELECT avg(price) FROM trades SAMPLE BY 1h FILL(PREV) ALIGN TO CALENDAR
+
+-- Latest value per partition
+SELECT * FROM trades LATEST ON ts PARTITION BY symbol
+
+-- Time-ordered joins
+SELECT * FROM trades ASOF JOIN quotes ON (symbol)
+SELECT * FROM trades LT JOIN quotes ON (symbol) TOLERANCE 5s
+SELECT * FROM a WINDOW JOIN b ON a.ts = b.ts
+  RANGE BETWEEN 1h PRECEDING AND CURRENT ROW FOLLOWING
+
+-- Implicit SELECT (table name without SELECT * FROM)
+trades WHERE symbol = 'BTC-USD'
+
+-- Duration literals
+SELECT * FROM trades WHERE ts > now() - 2d
+
+-- Geohash literals and types
+CREATE TABLE geo (pos GEOHASH(8c), area GEOHASH(4b))
+
+-- Array subscripts and slices
+SELECT arr[2:], data[1:3] FROM t
+
+-- WAL tables with deduplication and TTL
+CREATE TABLE trades (ts TIMESTAMP, price DOUBLE)
+  TIMESTAMP(ts) PARTITION BY DAY WAL
+  DEDUP UPSERT KEYS(ts)
+  TTL 30 DAYS
+```
+
+## Architecture
+
+```
+SQL String
+    |
+    v
+ Lexer (tokenize)
+    |
+    v
+ Tokens
+    |
+    v
+ Parser (Chevrotain CstParser)
+    |
+    v
+ Concrete Syntax Tree (CST)
+    |
+    v
+ Visitor (CST -> AST)
+    |
+    v
+ AST  -----> toSql() -----> SQL String
+```
+
+The parser uses Chevrotain's [CST pattern](https://chevrotain.io/docs/guide/concrete_syntax_tree.html): the parser produces a lossless CST, then a visitor transforms it into a clean, typed AST. The `toSql()` function serializes any AST back to valid SQL.
+
+## API Reference
+
+### High-Level API
+
+| Function               | Description                                                       |
+| ---------------------- | ----------------------------------------------------------------- |
+| `parseToAst(sql)`      | Parse SQL string into `{ ast: Statement[], errors: Error[] }`     |
+| `parseOne(sql)`        | Parse a single statement, throws on errors or multiple statements |
+| `parseStatements(sql)` | Parse multiple statements, throws on errors                       |
+| `toSql(ast)`           | Convert `Statement[]` back to a SQL string                        |
+
+### Low-Level API
+
+| Function        | Description                                               |
+| --------------- | --------------------------------------------------------- |
+| `tokenize(sql)` | Tokenize SQL into Chevrotain tokens                       |
+| `parse(sql)`    | Parse SQL to CST with lex/parse errors                    |
+| `visitor`       | Chevrotain CST visitor instance for CST-to-AST conversion |
+
+### Autocomplete API
+
+| Function                             | Description                                                  |
+| ------------------------------------ | ------------------------------------------------------------ |
+| `createAutocompleteProvider(schema)` | Create a provider with `getSuggestions(query, cursorOffset)` |
+| `getContentAssist(sql, offset)`      | Low-level: get valid tokens at cursor position               |
+
+### Grammar Exports
+
+Arrays of keywords, functions, data types, operators, and constants for syntax highlighting integration:
+
+```typescript
+import { keywords, functions, dataTypes, operators, constants } from "@questdb/sql-parser/grammar";
+```
+
+## Development
+
+```bash
+yarn                # Install dependencies
+yarn build          # Compile TypeScript (tsup + tsc)
+yarn test           # Run all tests (6,100+ tests)
+yarn test:watch     # Run tests in watch mode
+yarn typecheck      # Type-check without emitting
+yarn lint           # Run ESLint
+yarn lint:fix       # Auto-fix lint issues
+yarn generate:cst   # Regenerate CST type definitions from parser grammar
+yarn clean          # Remove dist/ and coverage/
+```
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for the full development workflow guide — how to add keywords, statement types, modify autocomplete, and more.
+
+## License
+
+Apache-2.0

package/dist/autocomplete/content-assist.d.ts

@@ -0,0 +1,52 @@
+import { type ILexingError, IToken, TokenType } from "chevrotain";
+/**
+ * A table reference found in the SQL query
+ */
+export interface TableRef {
+    /** The table name */
+    table: string;
+    /** Optional alias */
+    alias?: string;
+}
+/**
+ * Result from content assist analysis
+ */
+export interface ContentAssistResult {
+    /** Token types that are syntactically valid at the cursor position */
+    nextTokenTypes: TokenType[];
+    /** Tables/aliases found in the query (for column suggestions) */
+    tablesInScope: TableRef[];
+    /** Columns from CTEs, keyed by CTE name (lowercase) */
+    cteColumns: Record<string, {
+        name: string;
+        type: string;
+    }[]>;
+    /** The tokens before the cursor */
+    tokensBefore: IToken[];
+    /** Whether the cursor is in the middle of a word (partial token being typed) */
+    isMidWord: boolean;
+    /** Any lexer errors */
+    lexErrors: ILexingError[];
+    /**
+     * When the cursor is after a qualified reference (e.g., "t1." or "trades."),
+     * this contains the qualifier name (e.g., "t1" or "trades"). The provider
+     * should resolve this against tablesInScope aliases/names to filter columns.
+     */
+    qualifiedTableRef?: string;
+}
+/**
+ * Get content assist suggestions for a SQL string at a given cursor position
+ *
+ * @param fullSql - The complete SQL string
+ * @param cursorOffset - The cursor position (0-indexed character offset)
+ * @returns Content assist result with next valid tokens and tables in scope
+ */
+export declare function getContentAssist(fullSql: string, cursorOffset: number): ContentAssistResult;
+/**
+ * Simplified version that just returns next valid token names
+ */
+export declare function getNextValidTokens(sql: string): string[];
+/**
+ * Check if a token type is expected at the current position
+ */
+export declare function isTokenExpected(sql: string, tokenName: string): boolean;

package/dist/autocomplete/index.d.ts

@@ -0,0 +1,5 @@
+export { createAutocompleteProvider } from "./provider";
+export type { AutocompleteProvider, Suggestion, SchemaInfo, TableInfo, ColumnInfo, } from "./types";
+export { SuggestionKind, SuggestionPriority } from "./types";
+export { IDENTIFIER_TOKENS, IDENTIFIER_KEYWORD_TOKENS, SKIP_TOKENS, tokenNameToKeyword, isIdentifierToken, shouldSkipToken, } from "./token-classification";
+export { buildSuggestions } from "./suggestion-builder";

package/dist/autocomplete/provider.d.ts

@@ -0,0 +1,20 @@
+import type { AutocompleteProvider, SchemaInfo } from "./types";
+/**
+ * Create an autocomplete provider with the given schema
+ *
+ * @param schema - Schema information (tables and columns)
+ * @returns AutocompleteProvider instance
+ *
+ * @example
+ * ```typescript
+ * const provider = createAutocompleteProvider({
+ *   tables: [{ name: "trades" }],
+ *   columns: { trades: [{ name: "symbol", type: "STRING" }] },
+ * });
+ *
+ * // Get suggestions after "SELECT "
+ * const suggestions = provider.getSuggestions("SELECT  FROM trades", 7);
+ * // suggestions will include "symbol" column from trades
+ * ```
+ */
+export declare function createAutocompleteProvider(schema: SchemaInfo): AutocompleteProvider;

package/dist/autocomplete/suggestion-builder.d.ts

@@ -0,0 +1,16 @@
+import { TokenType } from "chevrotain";
+import { Suggestion, SchemaInfo } from "./types";
+import type { TableRef } from "./content-assist";
+/**
+ * Build suggestions from parser's nextTokenTypes
+ *
+ * @param tokenTypes - Valid next tokens from parser.computeContentAssist()
+ * @param schema - Schema information (tables, columns)
+ * @param tablesInScope - Tables found in the query
+ * @returns Array of suggestions
+ */
+export declare function buildSuggestions(tokenTypes: TokenType[], schema: SchemaInfo, tablesInScope: TableRef[], options?: {
+    includeColumns?: boolean;
+    includeTables?: boolean;
+    isMidWord?: boolean;
+}): Suggestion[];

package/dist/autocomplete/token-classification.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Token types that represent actual identifiers
+ */
+export declare const IDENTIFIER_TOKENS: Set<string>;
+/**
+ * Keywords that can be used as identifiers in the grammar.
+ *
+ * These are tokens that appear as alternatives in the parser's `identifier` rule.
+ * When these appear in nextTokenTypes, it means an identifier/column is expected,
+ * so we should suggest columns and tables, not these keywords.
+ *
+ * Derived from IDENTIFIER_KEYWORD_NAMES in tokens.ts — single source of truth.
+ */
+export declare const IDENTIFIER_KEYWORD_TOKENS: Set<string>;
+/**
+ * Expression-continuation operators that are valid after any expression but
+ * should be deprioritized so clause-level keywords (ASC, DESC, LIMIT, etc.)
+ * appear first in the suggestion list.
+ */
+export declare const EXPRESSION_OPERATORS: Set<string>;
+/**
+ * Punctuation tokens — worth suggesting in fallback (e.g., "(" after "VALUES (1), ")
+ */
+export declare const PUNCTUATION_TOKENS: Set<string>;
+/**
+ * Token types that should NOT be suggested (internal/structural tokens)
+ */
+export declare const SKIP_TOKENS: Set<string>;
+/**
+ * Operator map for converting token names to display strings
+ */
+export declare const OPERATOR_MAP: Record<string, string>;
+/**
+ * Convert a token type name to a keyword string for display
+ * e.g., "Table" → "TABLE", "DataPageSize" → "DATA_PAGE_SIZE"
+ */
+export declare function tokenNameToKeyword(name: string): string;
+/**
+ * Check if a token represents an identifier context
+ */
+export declare function isIdentifierToken(tokenName: string): boolean;
+/**
+ * Check if a token should be skipped in suggestions
+ */
+export declare function shouldSkipToken(tokenName: string): boolean;

package/dist/autocomplete/types.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Kind of suggestion - maps to Monaco CompletionItemKind in the UI
+ */
+export declare enum SuggestionKind {
+    Keyword = "keyword",
+    Function = "function",
+    Table = "table",
+    Column = "column",
+    Operator = "operator",
+    DataType = "dataType"
+}
+/**
+ * Priority for sorting suggestions
+ */
+export declare enum SuggestionPriority {
+    High = 1,
+    Medium = 2,
+    MediumLow = 3,
+    Low = 4
+}
+/**
+ * A generic autocomplete suggestion
+ */
+export interface Suggestion {
+    /** Display label */
+    label: string;
+    /** Kind of suggestion */
+    kind: SuggestionKind;
+    /** Text to insert when selected */
+    insertText: string;
+    /** Text used for filtering (optional, defaults to label) */
+    filterText?: string;
+    /** Sort priority (lower = higher priority) */
+    priority: SuggestionPriority;
+    /** Additional detail text shown inline after label (e.g., " (trades)") */
+    detail?: string;
+    /** Description text shown on the right side (e.g., "DOUBLE") */
+    description?: string;
+}
+/**
+ * Column information for schema-aware suggestions
+ */
+export interface ColumnInfo {
+    /** Column name */
+    name: string;
+    /** Column data type (e.g., "STRING", "DOUBLE", "TIMESTAMP") */
+    type: string;
+}
+/**
+ * Table information for schema-aware suggestions
+ */
+export interface TableInfo {
+    /** Table name */
+    name: string;
+    /** Designated timestamp column (if any) */
+    designatedTimestamp?: string;
+}
+/**
+ * Schema information passed to the autocomplete provider
+ */
+export interface SchemaInfo {
+    /** Available tables */
+    tables: TableInfo[];
+    /** Columns indexed by table name (lowercase) */
+    columns: Record<string, ColumnInfo[]>;
+}
+/**
+ * Autocomplete provider interface
+ */
+export interface AutocompleteProvider {
+    /**
+     * Get suggestions for a SQL query at the given cursor position
+     * @param query - The SQL query string
+     * @param cursorOffset - Cursor position (0-indexed character offset)
+     * @returns Array of suggestions
+     */
+    getSuggestions(query: string, cursorOffset: number): Suggestion[];
+}

package/dist/grammar/constants.d.ts

@@ -0,0 +1 @@
+export declare const constants: string[];

package/dist/grammar/dataTypes.d.ts

@@ -0,0 +1 @@
+export declare const dataTypes: string[];

package/dist/grammar/functions.d.ts

@@ -0,0 +1 @@
+export declare const functions: string[];