@coradb/coradb-sqlsyntaxchecker-wasm 0.3.3

package/README.md

@@ -0,0 +1,318 @@
+# CoraDB-SQLSyntaxChecker-Wasm
+
+Is this valid CoraDB SQL? An offline check that uses **the engine's own
+grammar and lexer** (`corasql_grammar.y`, `corasql_lexer.l`), compiled to
+WebAssembly. It runs in the browser and in Node 18+, needs no server and no
+database connection, and answers as the engine's parser would: accepted, or
+where it stopped and why.
+
+Given the database's schema — a JSON document read from its catalog — it also
+checks the names a statement uses: tables, views, node and edge classes,
+columns, functions and procedures (and how many arguments they get), serials,
+and how many values each INSERT row has.
+
+The npm package is `@coradb/coradb-sqlsyntaxchecker-wasm` (public, in the `coradb` organization). It has no dependencies.
+
+- [Install](#install)
+- [Quick start](#quick-start)
+- [Checking syntax](#checking-syntax)
+- [Checking names against a schema](#checking-names-against-a-schema)
+- [Server settings](#server-settings)
+- [Errors and problems](#errors-and-problems)
+- [In the browser](#in-the-browser)
+- [Without npm, or without JavaScript](#without-npm-or-without-javascript)
+- [API](#api)
+- [Limits](#limits)
+- [Rebuilding from the engine source](#rebuilding-from-the-engine-source)
+
+## Install
+
+From npm:
+
+```bash
+npm install @coradb/coradb-sqlsyntaxchecker-wasm
+```
+
+From a release (https://github.com/apsisware/CoraDB-SQLSyntaxChecker-Wasm/releases),
+by its URL or from a copy kept with your project:
+
+```bash
+npm install https://github.com/apsisware/CoraDB-SQLSyntaxChecker-Wasm/releases/download/v<version>/coradb-coradb-sqlsyntaxchecker-wasm-<version>.tgz
+npm install ./vendor/coradb-coradb-sqlsyntaxchecker-wasm-<version>.tgz
+```
+
+From a clone of the repository, to use it as it is while it changes:
+
+```bash
+npm install ../CoraDB-SQLSyntaxChecker-Wasm
+```
+
+| How | When |
+|---|---|
+| npm | The usual way: normal version upgrades. |
+| Release URL | Any machine with internet access; the version stays fixed until the URL changes. |
+| `.tgz` in the project (`vendor/`) | No network needed; commit the file with the project. |
+| A clone's folder | Both projects on one machine, changes seen at once. |
+| Git: `npm install git+https://github.com/apsisware/CoraDB-SQLSyntaxChecker-Wasm.git#v<version>` | Versions by tag, without the release file. |
+
+## Quick start
+
+```js
+import { checkSql, validateSql, describeError } from '@coradb/coradb-sqlsyntaxchecker-wasm';
+
+const err = await checkSql('select a, from t');
+if (err) console.log(err.line, err.column, describeError(err));
+// 1 11 Syntax error: unexpected "from".
+
+const problems = await validateSql('select nmae from customers', { schema });
+// [{ kind: 'name', line: 1, column: 8, offset: 7, length: 4,
+//    message: 'customers has no column named nmae.' }]
+```
+
+`checkSql` and `validateSql` compile the module once and use a fresh checker
+for each call.
+
+## Checking syntax
+
+`check()` takes one statement, or a script of statements separated by
+semicolons; the first error stops it, as it does the engine. It returns `null`
+when the text is valid. A typical statement takes a fraction of a millisecond.
+
+For many checks, compile the module once and make a checker per check (or
+per request). A new checker from a compiled module costs about a millisecond:
+
+```js
+import { readFile } from 'node:fs/promises';
+import { createSqlChecker } from '@coradb/coradb-sqlsyntaxchecker-wasm';
+
+const file = new URL(import.meta.resolve('@coradb/coradb-sqlsyntaxchecker-wasm/coradb-sqlsyntaxchecker.wasm'));
+const module = await WebAssembly.compile(await readFile(file));
+
+async function validate(sql, options) {
+  const checker = await createSqlChecker(module);
+  return checker.validate(sql, options);
+}
+```
+
+A checker can also be kept and reused (`loadSqlChecker()` returns one, made
+once). A fresh one per check is recommended because a checker is a
+WebAssembly instance whose memory lives on from one check to the next: a fresh
+instance guarantees nothing carries over. (Up to 0.2.0 a stack too small for
+some graph queries did damage that memory; that cause was fixed in 0.2.1.)
+
+**Statements nested too deeply** (about 290 levels of parentheses, or a MATCH
+of more than about 1,500 patterns) run out of stack. `check()` and
+`validate()` then throw an `Error` ("The SQL checker could not check this
+statement…"): the statement is neither accepted nor rejected. The checker
+replaces its instance and goes on working. Deeper still (about 1,000 levels),
+the parser itself refuses with "memory exhausted", as the engine does.
+
+## Checking names against a schema
+
+`validate(sql, { schema })` returns every problem in the text: its first
+syntax error, if it has one; otherwise each name the schema does not have.
+
+```js
+const schema = JSON.parse(await readFile('shop-schema.json', 'utf8'));
+const checker = await loadSqlChecker();
+for (const p of checker.validate(sqlText, { schema })) {
+  console.log(`line ${p.line}, column ${p.column}: ${p.message}`);
+}
+```
+
+What it reports:
+
+- a table, view, node or edge class that does not exist; a MATCH label of the
+  wrong kind (an edge used as a node);
+- a column a table does not have, or one that two tables of the query have
+  (ambiguous);
+- a table or alias in `t.column` that the query does not have;
+- a function or procedure that does not exist; a built-in or stored function
+  given the wrong number of arguments (the built-ins' counts come from the
+  engine's own parser); a procedure used where a value is needed;
+- a serial in `name.NEXT_VALUE` that does not exist;
+- an INSERT column that does not exist, and a row with the wrong number of
+  values.
+
+It lets through anything it cannot be sure of: a derived table's columns,
+system catalog classes (`db_*`), names the same script creates (`CREATE TABLE
+x; SELECT … FROM x`), a trigger's statements (OBJ, NEW, OLD), and any part of
+the schema the document leaves out — without `procedures`, function names are
+not checked; without `serials`, serials are not. The one exception: without
+`synonyms`, a table name is looked up among the objects only.
+
+Without `schema`, `validate()` checks only the syntax.
+
+### The schema document
+
+**[README-schema.md](README-schema.md) documents it field by field.**
+`schema.json` (JSON Schema, draft 2020-12) defines it for validators, and
+`index.d.ts` has it as TypeScript types (`CoraDbSchema`). In short:
+
+```json
+{
+  "format": "coradb-schema",
+  "version": 1,
+  "database": "shop",
+  "objects": [
+    { "name": "orders", "owner": "dba", "kind": "table",
+      "columns": [ { "name": "id", "type": "INTEGER" }, { "name": "total", "type": "NUMERIC" } ] }
+  ],
+  "procedures": [ { "name": "calc_tax", "kind": "function", "returns": "NUMERIC",
+                    "params": [ { "name": "amount", "type": "NUMERIC", "mode": "IN" } ] } ],
+  "serials": [ { "name": "order_no" } ],
+  "synonyms": []
+}
+```
+
+Object kinds are `table`, `view`, `node` and `edge`. Names are matched
+without regard to case. A missing list or field means "not known"; an empty
+list means "there are none".
+
+**Making one:** `tools/coradbSchema.ts` reads it from a live database's
+catalog. Copy it into your server; it works with any driver, given a function
+that runs a query and returns its rows as objects:
+
+```ts
+import { readCoraDbSchema } from './coradbSchema';
+
+const schema = await readCoraDbSchema(async (sql) => rowsAsObjects(await conn.query(sql)));
+```
+
+It reads only the catalog — no table data — and can take a moment on a large
+database: read it once and keep it until the schema changes. The same
+document can be given to an AI as a description of the database.
+
+## Server settings
+
+Three server parameters change how SQL is read. The checker uses the
+engine's defaults (all on); pass the server's own when they differ:
+
+```js
+checker.check(sql, { ansiQuotes: true, noBackslashEscapes: false, pipesAsConcat: true });
+checker.validate(sql, { schema, noBackslashEscapes: false });
+```
+
+| Option | Server parameter | Default |
+|---|---|---|
+| `ansiQuotes` | `ansi_quotes`: `"…"` quotes a name, not a string | `true` |
+| `noBackslashEscapes` | `no_backslash_escapes`: a backslash in a string is just a backslash | `true` |
+| `pipesAsConcat` | `pipes_as_concat`: `\|\|` joins strings rather than meaning OR | `true` |
+
+A setting left out, `undefined` or `null` keeps the default.
+
+## Errors and problems
+
+`check()` returns `null` or the first syntax error:
+
+| Field | |
+|---|---|
+| `line`, `column` | 1-based, in characters |
+| `offset`, `length` | the part of the text to mark, in characters: the token, or an open quote to the end of its line |
+| `token` | the text the parser stopped at; `''` at the end of the text |
+| `message` | the parser's own words, e.g. `syntax error, unexpected FROM, expecting ')'` |
+
+`describeError(err)` puts it in words for people: `Syntax error: unexpected
+"from". Expected ).`, `Syntax error: unexpected end of the statement.`, or
+`This string is never closed.`
+
+`validate()` returns a list of problems, `[]` when all is well. Each has
+`kind` (`'syntax'` or `'name'`), `line`, `column`, `offset`, `length` and
+`message` (already in words).
+
+## In the browser
+
+`loadSqlChecker()`, `checkSql()` and `validateSql()` fetch the module from
+next to `index.js`. Vite and webpack 5 copy it into the build on their own,
+since it is named with `new URL('./coradb-sqlsyntaxchecker.wasm',
+import.meta.url)`. To serve it from somewhere else, pass its URL or its bytes:
+
+```js
+const checker = await loadSqlChecker('/assets/coradb-sqlsyntaxchecker.wasm');
+const other = await createSqlChecker(await (await fetch(url)).arrayBuffer());
+```
+
+With Vite, the module's URL can also be imported:
+`import wasmUrl from '@coradb/coradb-sqlsyntaxchecker-wasm/coradb-sqlsyntaxchecker.wasm?url'`.
+When the package is linked from a folder outside the project, add that folder
+to `server.fs.allow` in `vite.config` so `npm run dev` may serve it.
+
+The module uses WebAssembly exception handling, which every current browser
+supports.
+
+## Without npm, or without JavaScript
+
+**Plain web pages, Electron, any web server:** copy `index.js`,
+`schema-check.js` and `coradb-sqlsyntaxchecker.wasm` into one folder of the
+app and import it as a module. Ship `LICENSE` and `NOTICE` with them.
+
+```html
+<script type="module">
+  import { checkSql, describeError } from './coradb-sqlsyntaxchecker/index.js';
+
+  const err = await checkSql('select a, from t');
+  if (err) console.log(err.line, err.column, describeError(err));
+</script>
+```
+
+**Java, .NET, Python, Go…:** nothing ready-made. Either run the `.wasm` in a
+WebAssembly runtime that supports exception handling (check yours does), or
+compile the generated C sources (grammar, lexer and `build/check.c`) as a
+native library for JNI, P/Invoke or ctypes. The module's exports are listed
+at the top of `build/check.c`.
+
+## API
+
+| Export | |
+|---|---|
+| `checkSql(sql, settings?)` | `Promise<SqlSyntaxError \| null>`: one call, a fresh checker. |
+| `validateSql(sql, options?)` | `Promise<SqlProblem[]>`: one call, a fresh checker; `options` = settings plus `schema`. |
+| `loadSqlChecker(source?)` | `Promise<SqlChecker>`: the checker made once from the module next to `index.js`; with `source` (URL, path or bytes), a new one from there. |
+| `createSqlChecker(bytes)` | `Promise<SqlChecker>` from the module's bytes, or from a compiled `WebAssembly.Module`. |
+| `checker.check(sql, settings?)` | `SqlSyntaxError \| null`. |
+| `checker.validate(sql, options?)` | `SqlProblem[]`. |
+| `checker.builtin(name)` | A built-in function's allowed argument counts: bit *n* for *n* arguments, bit 30 for 30 or more; `-1` when the engine checks them some other way; `-2` when there is no such built-in. |
+| `describeError(err)` | The error in words. |
+| `tokenWords(name)` | A grammar token as a person would say it (`IdName` → `a name`). |
+| `charOffset(text, byteOffset)` | A byte offset into the UTF-8 text, in characters. |
+| `checkNames`, `createdNames` | The name checks on their own (used by `validate()`). |
+| `DEFAULT_SETTINGS` | The engine's defaults. |
+
+Also exported as files: `@coradb/coradb-sqlsyntaxchecker-wasm/coradb-sqlsyntaxchecker.wasm`,
+`…/schema.json` and `…/build-info.json` (what the module was built from).
+TypeScript types are in `index.d.ts`.
+
+## Limits
+
+- **PL/CSQL bodies** (`CREATE PROCEDURE … AS BEGIN … END`) are not read by
+  this grammar: the engine compiles them separately. Leave them out of what
+  you check. Java procedures (`AS LANGUAGE JAVA …`) check normally.
+- Data types are not checked, nor the engine's other rules after parsing
+  (limits, invalid combinations, permissions): those need the database. The
+  names are only as current as the schema document.
+- A NUL character (U+0000) in the text is reported as an error where it is:
+  the lexer would stop reading there.
+- Name checks need memory in proportion to the text. If the module runs out,
+  `validate()` throws rather than report nothing.
+
+## Rebuilding from the engine source
+
+When the engine's grammar or lexer changes, in a clone of this repository:
+
+```bash
+npm run build -- <path to tesseractdb-develop\src\parser>
+npm test
+```
+
+It needs bison 3.8 and flex 2.6.4 (on Windows `win_bison` and `win_flex` from
+winflexbison; or set `BISON` and `FLEX`), and the WASI SDK
+(https://github.com/WebAssembly/wasi-sdk/releases, 25.0) with
+`WASI_SDK_PATH` set to where it was unpacked. With those versions the build
+reproduces the published module byte for byte. `build-info.json` records the
+engine version, the source and the SHA-256 of its grammar and lexer, the stack
+size and the WASI SDK version. How the engine's sources become the module is
+described at the top of `build/generate.mjs`.
+
+## License
+
+MIT. See `LICENSE` and `NOTICE`.

package/build-info.json

@@ -0,0 +1,11 @@
+{
+  "builtAt": "2026-10-30T16:46:50.511Z",
+  "source": "tesseractdb-develop\\src\\parser",
+  "engineVersion": "1.0.1",
+  "grammarSha256": "31de8ab1860a938b0274d287a6f3bed0fc4e80f3cdcb31f0f07a1c9f1f6cf655",
+  "lexerSha256": "eb85dd08d4d02e53d2776ed37563dee095da9c028a8dcfc6a2b2031932e767bc",
+  "tokens": 646,
+  "hints": 33,
+  "stackSize": 4194304,
+  "wasiSdk": "25.0"
+}

package/index.d.ts

@@ -0,0 +1,234 @@
+/**
+ * Server settings that change how SQL is read. Each defaults to the engine's
+ * own default (true); a setting left out, undefined or null keeps it.
+ */
+export interface CheckSettings {
+  /** `"…"` quotes a name, not a string (ansi_quotes). */
+  ansiQuotes: boolean;
+  /** A backslash in a string is just a backslash (no_backslash_escapes). */
+  noBackslashEscapes: boolean;
+  /** `||` joins strings rather than meaning OR (pipes_as_concat). */
+  pipesAsConcat: boolean;
+}
+
+export declare const DEFAULT_SETTINGS: Readonly<CheckSettings>;
+
+/** Where the parser stopped, and why. */
+export interface SqlSyntaxError {
+  /** 1-based line in the text checked. */
+  line: number;
+  /** 1-based column, in characters. */
+  column: number;
+  /** Where the error is in the string, in characters (0-based). */
+  offset: number;
+  /** How many characters to mark from `offset`: the token, or an open quote to the end of its line. */
+  length: number;
+  /** What the parser said, e.g. `syntax error, unexpected FROM, expecting ')'`. */
+  message: string;
+  /** The text of the token it stopped at; '' at the end of the text. */
+  token: string;
+}
+
+/**
+ * Keeping one checker for many checks works, but a fresh checker per check
+ * (createSqlChecker with bytes read once, ~2 ms) is recommended: see README,
+ * "Create a fresh checker for every check".
+ *
+ * check() and validate() throw an Error when a statement nests too deeply for
+ * the module's stack; the checker replaces its instance and goes on working.
+ * validate() also throws when the module runs out of memory for a text's names
+ * (it never answers "all is well" for names it could not check).
+ *
+ * A text that contains a NUL character (U+0000) is refused at that character.
+ */
+export interface SqlChecker {
+  /**
+   * null when the engine's parser accepts `sql` — one statement, or several
+   * separated by semicolons; otherwise the first error.
+   */
+  check(sql: string, settings?: Partial<CheckSettings>): SqlSyntaxError | null;
+  /**
+   * Every problem in `sql`: its first syntax error, if it has one; otherwise,
+   * given `schema`, each name the schema does not have — a table, view, node
+   * or edge class, a column, a function or procedure (or the wrong number of
+   * arguments to one), a serial — and each INSERT row with the wrong number
+   * of values. Without `schema`, only the syntax is checked. [] when all is well.
+   */
+  validate(sql: string, options?: ValidateOptions): SqlProblem[];
+  /**
+   * A built-in function's allowed argument counts: a bit per count (bit 30:
+   * 30 or more); -1 when the engine checks them some other way; -2 when there
+   * is no built-in function of that name.
+   */
+  builtin(name: string): number;
+}
+
+export interface ValidateOptions extends Partial<CheckSettings> {
+  /** The database's schema: what the names are looked up in. */
+  schema?: CoraDbSchema;
+}
+
+/** One problem found by validate(). */
+export interface SqlProblem {
+  /** `syntax`: the parser stopped here. `name`: the schema does not have what is named, or a call or row does not fit. */
+  kind: 'syntax' | 'name';
+  /** 1-based. */
+  line: number;
+  /** 1-based, in characters. */
+  column: number;
+  /** In characters, 0-based. */
+  offset: number;
+  /** How many characters to mark from `offset`. */
+  length: number;
+  /** In words, e.g. `customers has no column named nmae.` */
+  message: string;
+}
+
+/**
+ * Compile a checker from the bytes of coradb-sqlsyntaxchecker.wasm, or make one
+ * from the module already compiled from them (`WebAssembly.compile(bytes)`):
+ * then a new checker costs only its instance.
+ */
+export declare function createSqlChecker(bytes: BufferSource | WebAssembly.Module): Promise<SqlChecker>;
+
+/**
+ * The checker, loaded once from the coradb-sqlsyntaxchecker.wasm next to this module (read
+ * from disk in Node, fetched in the browser), or from `source` when given.
+ */
+export declare function loadSqlChecker(source?: URL | string | BufferSource): Promise<SqlChecker>;
+
+/** Check in one call, with the module next to this one: a fresh checker each call, the module compiled once. */
+export declare function checkSql(sql: string, settings?: Partial<CheckSettings>): Promise<SqlSyntaxError | null>;
+
+/** Validate in one call, with the module next to this one: a fresh checker each call, the module compiled once. */
+export declare function validateSql(sql: string, options?: ValidateOptions): Promise<SqlProblem[]>;
+
+/** The error in words: `Syntax error: unexpected "from". Expected ).` */
+export declare function describeError(err: SqlSyntaxError): string;
+
+/** The character offset of a byte offset into the UTF-8 form of `text`. */
+export declare function charOffset(text: string, byteOffset: number): number;
+
+/** One of the grammar's token names as a person would say it (DELETE_ → DELETE, IdName → a name). */
+export declare function tokenWords(name: string): string;
+
+/** Where each name, query and call is in one statement, as the grammar reports it (character offsets). */
+export interface ParseEvent {
+  kind: number;
+  start: number;
+  end: number;
+}
+
+/** The name checks on their own, for one statement the grammar accepted. */
+export declare function checkNames(
+  sql: string,
+  events: ParseEvent[],
+  schema: CoraDbSchema,
+  ctx: {
+    builtin: (name: string) => number;
+    created?: ReadonlySet<string>;
+    /** no_backslash_escapes is off: a backslash in a string escapes what follows (for counting values and arguments). */
+    backslashEscapes?: boolean;
+  },
+): { start: number; end: number; message: string }[];
+
+/** Lower-cased names a script creates, renames or changes (CREATE TABLE x, RENAME a TO b…). */
+export declare function createdNames(statements: string[]): Set<string>;
+
+// --- the schema document (see schema.json) --------------------------------------
+
+/**
+ * A CoraDB database's schema, read from its catalog: objects, their columns,
+ * keys and comments, stored procedures and functions, serials and synonyms.
+ * Any part may be missing: a missing list or field means "not known", never
+ * "there are none" — with one exception: without `synonyms`, a table name is
+ * looked up among the objects only (see README-schema.md).
+ */
+export interface CoraDbSchema {
+  format: 'coradb-schema';
+  version: 1;
+  database?: string;
+  objects: SchemaObject[];
+  procedures?: SchemaProcedure[];
+  serials?: SchemaSerial[];
+  synonyms?: SchemaSynonym[];
+}
+
+export type SchemaObjectKind = 'table' | 'view' | 'node' | 'edge';
+
+export interface SchemaObject {
+  name: string;
+  owner?: string;
+  kind: SchemaObjectKind;
+  comment?: string | null;
+  /** Parent classes (CREATE … UNDER), as `owner.name` or `name`; their columns are inherited. */
+  under?: string[];
+  /** In table order. Missing when not known: then any column is taken. */
+  columns?: SchemaColumn[];
+  primaryKey?: string[];
+  unique?: { name: string; columns: string[] }[];
+  foreignKeys?: SchemaForeignKey[];
+  /** Secondary indexes, unique ones included; not the primary or foreign keys. */
+  indexes?: SchemaIndex[];
+  /** Views only: the SELECT that defines it. */
+  definition?: string;
+}
+
+export interface SchemaColumn {
+  name: string;
+  /** As CoraDB names it: INTEGER, VARCHAR, NUMERIC, DATETIME, ENUM, SET… */
+  type: string;
+  length?: number;
+  precision?: number;
+  scale?: number;
+  /** ENUM: the values it allows. */
+  values?: string[];
+  /** SET, MULTISET, LIST: the type of the elements. */
+  elementType?: string;
+  nullable?: boolean;
+  /** The default as SQL text, e.g. `'RO'` or `SYS_DATETIME`. */
+  default?: string | null;
+  autoIncrement?: boolean;
+  comment?: string | null;
+}
+
+export interface SchemaForeignKey {
+  name: string;
+  columns: string[];
+  /** `owner.name`, or `name` when the owner is not known. */
+  references: string;
+  refColumns: string[];
+  onDelete?: string;
+  onUpdate?: string;
+}
+
+export interface SchemaIndex {
+  name: string;
+  columns: string[];
+  unique: boolean;
+  comment?: string | null;
+}
+
+export interface SchemaProcedure {
+  name: string;
+  owner?: string;
+  kind: 'procedure' | 'function';
+  /** Functions only. */
+  returns?: string;
+  comment?: string | null;
+  params?: { name: string; type: string; mode: 'IN' | 'OUT' | 'INOUT'; comment?: string | null }[];
+}
+
+export interface SchemaSerial {
+  name: string;
+  owner?: string;
+  comment?: string | null;
+}
+
+export interface SchemaSynonym {
+  name: string;
+  owner?: string;
+  /** `owner.name` of what it stands for. */
+  target: string;
+  comment?: string | null;
+}