@coradb/coradb-sqlsyntaxchecker-wasm 0.3.3

package/index.js

@@ -0,0 +1,529 @@
+// CoraDB-SQLSyntaxChecker-Wasm — is this valid CoraDB SQL?
+//
+// The engine's own grammar and lexer (src/parser/corasql_grammar.y and
+// corasql_lexer.l), with nothing built from what they read, compiled to
+// WebAssembly. Runs in the browser and in Node 18+, needs no server and no
+// connection, and answers exactly as the engine's parser would: accepted, or
+// where it stopped and why.
+//
+// Given the database's schema (a CoraDB schema document, see schema.json),
+// validate() also checks the names a statement uses: that its tables, views,
+// node and edge classes exist, that they have the columns it reads, that the
+// functions and procedures it calls exist and get the right number of
+// arguments, that the serials it reads exist, and that an INSERT gives each
+// row as many values as it has columns. Data types and the engine's other
+// rules are not checked: those need the database itself.
+
+import { checkNames, createdNames, indexSchema } from './schema-check.js';
+
+export { checkNames, createdNames } from './schema-check.js';
+
+/** The server settings that change how SQL is read, at the engine's defaults. */
+export const DEFAULT_SETTINGS = Object.freeze({
+  ansiQuotes: true,
+  noBackslashEscapes: true,
+  pipesAsConcat: true,
+});
+
+/** The settings to use: each one given (not undefined or null) as a boolean, the rest at the default. */
+function settingsOf(given) {
+  const s = { ...DEFAULT_SETTINGS };
+  if (given) {
+    for (const key of Object.keys(DEFAULT_SETTINGS)) {
+      if (given[key] !== undefined && given[key] !== null) s[key] = Boolean(given[key]);
+    }
+  }
+  return s;
+}
+
+/** Thrown by the proc_exit stand-in: the module ended itself, and its instance is not to be used again. */
+class ModuleExit extends Error {}
+
+/**
+ * Compile a checker from the module's bytes.
+ *
+ * The module was built against WASI for the C library's sake, but it never
+ * reads or writes anything: the six system calls it imports get do-nothing
+ * stand-ins, so it runs anywhere WebAssembly does.
+ *
+ * @param {BufferSource | WebAssembly.Module} bytes the contents of
+ *   coradb-sqlsyntaxchecker.wasm, or the module already compiled from them
+ *   (then a new checker costs only its instance)
+ * @returns {Promise<import('./index').SqlChecker>}
+ */
+export async function createSqlChecker(bytes) {
+  let memory = null;
+  const wasi = {
+    // Output is dropped, but reported as written in full: the C library
+    // retries a write until every byte is out, so "0 written" would loop.
+    fd_write: (_fd, iovs, n, written) => {
+      if (memory) {
+        const view = new DataView(memory.buffer);
+        let total = 0;
+        for (let i = 0; i < n; i += 1) total += view.getUint32(iovs + i * 8 + 4, true);
+        view.setUint32(written, total, true);
+      }
+      return 0;
+    },
+    fd_close: () => 0,
+    fd_fdstat_get: () => 0,
+    fd_read: () => 0,
+    fd_seek: () => 0,
+    proc_exit: (code) => {
+      throw new ModuleExit(`The SQL checker stopped (${code}).`);
+    },
+  };
+  const imports = { wasi_snapshot_preview1: wasi };
+  let module;
+  let instance;
+  if (bytes instanceof WebAssembly.Module) {
+    module = bytes;
+    instance = await WebAssembly.instantiate(module, imports);
+  } else {
+    ({ module, instance } = await WebAssembly.instantiate(bytes, imports));
+  }
+  let x;
+  let applied = '';
+  const builtins = new Map();
+  const start = (inst) => {
+    x = inst.exports;
+    memory = x.memory;
+    x._initialize();
+    applied = '';
+    builtins.clear();
+  };
+  start(instance);
+  /*
+   * A statement nested too deeply runs out of stack: the module's own (a
+   * WebAssembly trap) or the JavaScript engine's (a RangeError, since the
+   * module's calls use that too). Either way the instance is left as it was
+   * at that moment, its stack pointer included, so it is replaced with a new
+   * one from the same compiled module before the error is passed on: the
+   * next check starts clean.
+   */
+  const broken = (err) => err instanceof WebAssembly.RuntimeError || err instanceof RangeError || err instanceof ModuleExit;
+  const guarded = (fn) => {
+    try {
+      return fn();
+    } catch (err) {
+      if (broken(err)) {
+        start(new WebAssembly.Instance(module, imports));
+        const why = err instanceof ModuleExit ? '' : '; it may nest too deeply';
+        throw new Error(`The SQL checker could not check this statement (${err.message})${why}.`, { cause: err });
+      }
+      throw err;
+    }
+  };
+
+  const encoder = new TextEncoder();
+  const decoder = new TextDecoder();
+  const cString = (ptr) => {
+    const all = new Uint8Array(x.memory.buffer);
+    let end = ptr;
+    while (end < all.length && all[end] !== 0) end += 1;
+    return decoder.decode(all.subarray(ptr, end));
+  };
+  /** Parse once; for a statement accepted, the grammar's events too (character offsets). */
+  const parse = (sql, settings, withEvents) => guarded(() => parseOnce(sql, settings, withEvents));
+  const parseOnce = (sql, settings, withEvents) => {
+    if (typeof sql !== 'string') throw new TypeError('The SQL must be a string.');
+    const s = settingsOf(settings);
+    // The lexer would stop at a NUL and accept whatever came before it.
+    const nul = sql.indexOf('\0');
+    if (nul >= 0) {
+      return {
+        error: { ...lineColumn(sql, nul), offset: nul, length: 1, message: 'the text contains a NUL character (U+0000)', token: '' },
+        events: null,
+      };
+    }
+    const key = `${+s.ansiQuotes}${+s.noBackslashEscapes}${+s.pipesAsConcat}`;
+    if (key !== applied) {
+      x.check_set(+s.ansiQuotes, +s.noBackslashEscapes, +s.pipesAsConcat);
+      applied = key;
+    }
+    const bytesIn = encoder.encode(sql);
+    const ptr = x.check_alloc(bytesIn.length);
+    if (ptr === 0) throw new Error('The SQL checker is out of memory.');
+    let trapped = false;
+    try {
+      new Uint8Array(x.memory.buffer).set(bytesIn, ptr);
+      if (x.check_sql(ptr, bytesIn.length) !== 0) {
+        return {
+          error: locate(sql, bytesIn, !s.noBackslashEscapes, {
+            byteOffset: x.check_offset(),
+            message: cString(x.check_message()),
+            token: cString(x.check_token()),
+          }),
+          events: null,
+        };
+      }
+      if (!withEvents) return { error: null, events: null };
+      const n = x.check_event_count();
+      // Out of memory for them: the names cannot be checked, which is not "all is well".
+      if (n < 0) throw new Error('The SQL checker ran out of memory for this text: its names were not checked.');
+      const raw = new Int32Array(x.memory.buffer, x.check_events(), n * 3);
+      const toChar = byteToChar(sql, bytesIn);
+      const events = [];
+      for (let i = 0; i < n; i += 1) {
+        events.push({ kind: raw[i * 3], start: toChar(raw[i * 3 + 1]), end: toChar(raw[i * 3 + 2]) });
+      }
+      return { error: null, events };
+    } catch (err) {
+      trapped = broken(err);
+      throw err;
+    } finally {
+      // not after a trap: that instance is about to be replaced
+      if (!trapped) x.check_free(ptr);
+    }
+  };
+  const builtin = (name) => guarded(() => builtinOnce(name));
+  const builtinOnce = (name) => {
+    const key = String(name).toLowerCase();
+    if (builtins.has(key)) return builtins.get(key);
+    const b = encoder.encode(`${key}\0`);
+    const ptr = x.check_alloc(b.length);
+    if (ptr === 0) throw new Error('The SQL checker is out of memory.');
+    let r = -2;
+    let trapped = false;
+    try {
+      new Uint8Array(x.memory.buffer).set(b, ptr);
+      r = x.check_function(ptr);
+    } catch (err) {
+      trapped = broken(err);
+      throw err;
+    } finally {
+      // not after a trap: that instance is about to be replaced
+      if (!trapped) x.check_free(ptr);
+    }
+    builtins.set(key, r);
+    return r;
+  };
+
+  return {
+    check(sql, settings = DEFAULT_SETTINGS) {
+      return parse(sql, settings, false).error;
+    },
+
+    validate(sql, options) {
+      const { schema, ...settings } = options ?? {};
+      const { error, events } = parse(sql, settings, Boolean(schema));
+      if (error) {
+        return [{ kind: 'syntax', line: error.line, column: error.column, offset: error.offset, length: error.length, message: describeError(error) }];
+      }
+      if (!schema || !events) return [];
+      if (schema.format !== 'coradb-schema' || !Array.isArray(schema.objects)) {
+        throw new TypeError('validate() takes a CoraDB schema document as `schema` (format "coradb-schema").');
+      }
+      // One statement at a time, so a trigger's or a script's own rules apply
+      // to it alone. The outermost statements, in order; a statement inside
+      // another (a trigger's action) belongs to it.
+      const outer = [];
+      let reach = -1;
+      const stmts = events.filter((e) => e.kind === 1).sort((a, b) => a.start - b.start || b.end - a.end);
+      for (const st of stmts) {
+        if (st.start >= reach) {
+          outer.push({ start: st.start, end: st.end, events: [] });
+          reach = st.end;
+        }
+      }
+      // Each event to its statement, in the order the grammar reported them
+      // (checkNames reads some of them in pairs).
+      for (const e of events) {
+        let lo = 0;
+        let hi = outer.length - 1;
+        let at = -1;
+        while (lo <= hi) {
+          const mid = (lo + hi) >> 1;
+          if (outer[mid].start <= e.start) {
+            at = mid;
+            lo = mid + 1;
+          } else hi = mid - 1;
+        }
+        const st = at >= 0 ? outer[at] : null;
+        if (st && e.end <= st.end) st.events.push({ kind: e.kind, start: e.start - st.start, end: e.end - st.start });
+      }
+      const created = createdNames(outer.map((s) => sql.slice(s.start, s.end)));
+      const s = settingsOf(settings);
+      const ctx = { builtin, created, backslashEscapes: !s.noBackslashEscapes, index: indexSchema(schema) };
+      const problems = [];
+      for (const st of outer) {
+        for (const p of checkNames(sql.slice(st.start, st.end), st.events, schema, ctx)) {
+          const offset = st.start + p.start;
+          problems.push({ kind: 'name', ...lineColumn(sql, offset), offset, length: Math.max(1, p.end - p.start), message: p.message });
+        }
+      }
+      return problems;
+    },
+
+    builtin,
+  };
+}
+
+/** A byte offset into the UTF-8 form of `sql`, as a character offset. */
+function byteToChar(sql, bytes) {
+  if (bytes.length === sql.length) return (b) => b;
+  const map = new Int32Array(bytes.length + 1);
+  let b = 0;
+  for (let i = 0; i < sql.length; ) {
+    const cp = sql.codePointAt(i) ?? 0;
+    const len = cp < 0x80 ? 1 : cp < 0x800 ? 2 : cp < 0x10000 ? 3 : 4;
+    for (let k = 0; k < len; k += 1) map[b + k] = i;
+    b += len;
+    i += cp > 0xffff ? 2 : 1;
+  }
+  map[bytes.length] = sql.length;
+  return (off) => map[Math.max(0, Math.min(off, bytes.length))];
+}
+
+let compiled = null;
+
+/** The module next to this file, compiled once (retried after a failure). */
+function defaultModule() {
+  if (!compiled) {
+    compiled = readBytes(new URL('./coradb-sqlsyntaxchecker.wasm', import.meta.url))
+      .then((bytes) => WebAssembly.compile(bytes))
+      .catch((err) => {
+        compiled = null; // the next call tries again
+        throw err;
+      });
+  }
+  return compiled;
+}
+
+let loaded = null;
+
+/**
+ * The checker, loaded once.
+ *
+ * With no argument the module next to this file is used: read from disk in
+ * Node, fetched in the browser (bundlers such as Vite and webpack copy it
+ * along, since it is named with `new URL(…, import.meta.url)`). Pass a URL,
+ * a path, or the bytes to load it from somewhere else.
+ *
+ * @param {URL | string | BufferSource} [source]
+ */
+export function loadSqlChecker(source) {
+  if (source !== undefined) return readBytes(source).then(createSqlChecker);
+  if (!loaded) {
+    loaded = defaultModule()
+      .then(createSqlChecker)
+      .catch((err) => {
+        loaded = null; // the next call tries again
+        throw err;
+      });
+  }
+  return loaded;
+}
+
+/**
+ * Check SQL in one call: one statement, or a script of them separated by
+ * semicolons (the first error stops it, as it does the engine). Each call has
+ * a fresh checker, made from the module compiled once, as README recommends.
+ *
+ * @param {string} sql
+ * @param {Partial<typeof DEFAULT_SETTINGS>} [settings]
+ */
+export async function checkSql(sql, settings) {
+  return (await createSqlChecker(await defaultModule())).check(sql, settings);
+}
+
+/**
+ * Validate in one call: the syntax, and with `options.schema` the names too.
+ *
+ * @param {string} sql
+ * @param {Partial<typeof DEFAULT_SETTINGS> & { schema?: object }} [options]
+ */
+export async function validateSql(sql, options) {
+  return (await createSqlChecker(await defaultModule())).validate(sql, options);
+}
+
+const inNode = typeof process !== 'undefined' && !!process.versions?.node;
+
+/**
+ * Node's fs, reached so that browser bundlers do not try to pack it:
+ * process.getBuiltinModule where Node has it (22.3+), otherwise an import by
+ * a name only known at run time.
+ */
+async function nodeFs() {
+  const builtin = globalThis.process?.getBuiltinModule?.('node:fs/promises');
+  if (builtin) return builtin;
+  const name = 'node:fs/promises';
+  return import(/* @vite-ignore */ /* webpackIgnore: true */ name);
+}
+
+/** A path or URL, as what to read it with: a file path in Node, a URL anywhere else. */
+function where(source) {
+  if (source instanceof URL) return source;
+  const windowsPath = /^[a-z]:[\\/]/i.test(source);
+  if (!windowsPath && /^[a-z][a-z0-9+.-]*:/i.test(source)) return new URL(source);
+  if (inNode) return null; // a file path
+  return new URL(source, globalThis.location?.href);
+}
+
+async function readBytes(source) {
+  if (source instanceof ArrayBuffer || ArrayBuffer.isView(source)) return source;
+  const url = where(source);
+  if (url === null || url.protocol === 'file:') {
+    return (await nodeFs()).readFile(url ?? source);
+  }
+  const response = await fetch(url);
+  if (!response.ok) throw new Error(`The SQL checker could not be loaded from ${url} (HTTP ${response.status}).`);
+  return response.arrayBuffer();
+}
+
+// --- where the error is, and what to say about it -----------------------------
+
+/** The character offset of a byte offset into the UTF-8 form of `text`. */
+export function charOffset(text, byteOffset) {
+  let bytes = 0;
+  let i = 0;
+  while (i < text.length && bytes < byteOffset) {
+    const cp = text.codePointAt(i) ?? 0;
+    bytes += cp < 0x80 ? 1 : cp < 0x800 ? 2 : cp < 0x10000 ? 3 : 4;
+    i += cp > 0xffff ? 2 : 1;
+  }
+  return i;
+}
+
+/** 1-based line and column (in characters) of an offset. */
+function lineColumn(text, offset) {
+  let line = 1;
+  let lineStart = 0;
+  for (let i = text.indexOf('\n'); i >= 0 && i < offset; i = text.indexOf('\n', i + 1)) {
+    line += 1;
+    lineStart = i + 1;
+  }
+  return { line, column: offset - lineStart + 1 };
+}
+
+/**
+ * Where a string or quoted name that is never closed opens: the last quote
+ * the text leaves open, outside comments. With backslash escapes on
+ * (no_backslash_escapes off), a backslash in a string escapes what follows.
+ */
+function openQuote(text, backslashEscapes) {
+  const n = text.length;
+  for (let i = 0; i < n; ) {
+    const ch = text[i];
+    const next = text[i + 1];
+    if ((ch === '-' && next === '-') || (ch === '/' && next === '/')) {
+      const nl = text.indexOf('\n', i);
+      i = nl < 0 ? n : nl;
+      continue;
+    }
+    if (ch === '/' && next === '*') {
+      const close = text.indexOf('*/', i + 2);
+      i = close < 0 ? n : close + 2;
+      continue;
+    }
+    if (ch === "'" || ch === '"' || ch === '`' || ch === '[') {
+      const close = ch === '[' ? ']' : ch;
+      let j = i + 1;
+      let closed = false;
+      while (j < n) {
+        if (backslashEscapes && (ch === "'" || ch === '"') && text[j] === '\\') {
+          j += 2;
+          continue;
+        }
+        if (text[j] === close) {
+          if (close !== ']' && text[j + 1] === close) {
+            j += 2;
+            continue;
+          }
+          closed = true;
+          j += 1;
+          break;
+        }
+        j += 1;
+      }
+      if (!closed) return i;
+      i = j;
+      continue;
+    }
+    i += 1;
+  }
+  return -1;
+}
+
+/** Add where in the text the error is, in characters, and how much of it to mark. */
+function locate(sql, bytes, backslashEscapes, raw) {
+  let offset = charOffset(sql, Math.min(raw.byteOffset, bytes.length));
+  let length = Math.max(1, raw.token.length);
+  if (/unterminated/i.test(raw.message)) {
+    // The lexer only finds out at the end of the text: mark from the quote
+    // that was left open to the end of its line.
+    const quote = openQuote(sql, backslashEscapes);
+    if (quote >= 0) offset = quote;
+    const nl = sql.indexOf('\n', offset);
+    length = (nl < 0 ? sql.length : nl) - offset;
+  } else if (raw.token === '' || offset >= sql.length) {
+    // At the end of the text: the last thing there is.
+    const end = sql.replace(/\s+$/, '').length;
+    offset = Math.max(0, end - 1);
+    length = end > 0 ? 1 : 0;
+  }
+  length = Math.max(0, Math.min(length, sql.length - offset));
+  return { ...lineColumn(sql, offset), offset, length, message: raw.message, token: raw.token };
+}
+
+const TOKEN_WORDS = {
+  IdName: 'a name',
+  'end of file': 'the end of the statement',
+  'end of input': 'the end of the statement',
+  UNSIGNED_INTEGER: 'a number',
+  UNSIGNED_REAL: 'a number',
+  CHAR_STRING: 'a string',
+  NCHAR_STRING: 'a string',
+  BIT_STRING: 'a bit string',
+  HEX_STRING: 'a hex string',
+  BINARY_STRING: 'a string',
+  EUCKR_STRING: 'a string',
+  ISO_STRING: 'a string',
+  UTF8_STRING: 'a string',
+  PARAM_HEADER: 'a parameter',
+};
+
+/** One of the grammar's token names as a person would say it (DELETE_ → DELETE, IdName → a name). */
+export function tokenWords(name) {
+  if (TOKEN_WORDS[name]) return TOKEN_WORDS[name];
+  const quoted = /^'(.+)'$/.exec(name);
+  if (quoted) return quoted[1];
+  return name.replace(/_+$/, '').replace(/_/g, ' ');
+}
+
+/**
+ * The error in words: `syntax error, unexpected FROM, expecting ')'` becomes
+ * `Syntax error: unexpected "from". Expected ).`
+ *
+ * @param {import('./index').SqlSyntaxError} err
+ */
+export function describeError(err) {
+  const m = err.message;
+  if (/NUL character/.test(m)) return 'The text contains a NUL character (U+0000), which SQL cannot hold.';
+  if (/unterminated string/i.test(m)) return 'This string is never closed.';
+  if (/unterminated identifier/i.test(m)) return 'This quoted name is never closed.';
+  const typed = err.token.trim();
+  // A rule the grammar matches only to refuse (see ruleError in
+  // build/generate.mjs): the engine's own words, at the word.
+  if (/^invalid /i.test(m) && typed !== '') return `Syntax error: unexpected "${typed}" (${m}).`;
+  const parsed = /unexpected ([^,]+?)(?:, expecting (.+))?$/.exec(m);
+  if (!parsed) return m.charAt(0).toUpperCase() + m.slice(1);
+  const unexpected =
+    typed !== ''
+      ? `"${typed.length > 40 ? `${typed.slice(0, 40)}…` : typed}"`
+      : /^end of (?:file|input)$/.test(parsed[1])
+        ? 'end of the statement'
+        : tokenWords(parsed[1]);
+  let text = `Syntax error: unexpected ${unexpected}.`;
+  // "{" (the ODBC escape the grammar also allows) is never what anybody
+  // meant, and the engine's internal tokens are nobody's to type.
+  const wanted = (parsed[2] ?? '')
+    .split(' or ')
+    .filter((t) => t !== '' && t !== "'{'" && t !== "'}'" && !/__/.test(t))
+    .map(tokenWords);
+  if (wanted.length > 0) {
+    const list = wanted.length === 1 ? wanted[0] : `${wanted.slice(0, -1).join(', ')} or ${wanted[wanted.length - 1]}`;
+    text += ` Expected ${list}.`;
+  }
+  return text;
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@coradb/coradb-sqlsyntaxchecker-wasm",
+  "version": "0.3.3",
+  "description": "Offline checks for CoraDB SQL: the engine's own grammar and lexer, compiled to WebAssembly, plus the names a statement uses checked against a schema document. Browser and Node, no server needed.",
+  "keywords": [
+    "coradb",
+    "sql",
+    "syntax",
+    "parser",
+    "validator",
+    "schema",
+    "wasm"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/apsisware/CoraDB-SQLSyntaxChecker-Wasm.git"
+  },
+  "homepage": "https://github.com/apsisware/CoraDB-SQLSyntaxChecker-Wasm#readme",
+  "bugs": {
+    "url": "https://github.com/apsisware/CoraDB-SQLSyntaxChecker-Wasm/issues"
+  },
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./coradb-sqlsyntaxchecker.wasm": "./coradb-sqlsyntaxchecker.wasm",
+    "./schema.json": "./schema.json",
+    "./build-info.json": "./build-info.json"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "schema-check.js",
+    "schema.json",
+    "tools/coradbSchema.ts",
+    "coradb-sqlsyntaxchecker.wasm",
+    "build-info.json",
+    "LICENSE",
+    "NOTICE",
+    "README.md",
+    "README-schema.md",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "node build/build.mjs",
+    "test": "node --test test/coradb-sqlsyntaxchecker.test.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}