@kazurolabs/psql-explorer 0.1.0 → 0.3.1

package/dist/explorer/cypher-parse.js

@@ -0,0 +1,478 @@
+// A small, read only subset of Cypher (the query language of Neo4j): MATCH patterns, WHERE, and
+// RETURN with aggregates, ORDER BY, SKIP and LIMIT. This turns the text into a syntax tree; cypher.ts
+// resolves it against a database's tables and foreign keys.
+export class CypherError extends Error {
+    position;
+    constructor(message, 
+    // Where in the query it went wrong, as a character offset.
+    position) {
+        super(position === undefined ? message : `${message} (at character ${position + 1})`);
+        this.position = position;
+    }
+}
+export const AGGREGATES = ['count', 'sum', 'avg', 'min', 'max', 'collect'];
+export const SCALARS = [
+    'lower',
+    'tolower',
+    'upper',
+    'toupper',
+    'coalesce',
+    'abs',
+];
+const TWO = ['<>', '<=', '>=', '=~', '!='];
+const ONE = '()[]{},:.-<>=*|;';
+function tokenize(source) {
+    const tokens = [];
+    let i = 0;
+    while (i < source.length) {
+        const char = source[i];
+        if (/\s/.test(char)) {
+            i++;
+            continue;
+        }
+        if (source.startsWith('//', i)) {
+            while (i < source.length && source[i] !== '\n')
+                i++;
+            continue;
+        }
+        if (source.startsWith('/*', i)) {
+            const close = source.indexOf('*/', i + 2);
+            if (close < 0)
+                throw new CypherError('this comment is never closed', i);
+            i = close + 2;
+            continue;
+        }
+        const at = i;
+        if (char === "'" || char === '"') {
+            let value = '';
+            i++;
+            for (;;) {
+                const next = source[i];
+                if (next === undefined)
+                    throw new CypherError('this string is never closed', at);
+                i++;
+                if (next === char) {
+                    // A doubled quote is a quote, as in SQL.
+                    if (source[i] !== char)
+                        break;
+                    value += char;
+                    i++;
+                    continue;
+                }
+                if (next === '\\') {
+                    const escaped = source[i++];
+                    if (escaped === undefined)
+                        throw new CypherError('this string is never closed', at);
+                    value += escaped === 'n' ? '\n' : escaped === 't' ? '\t' : escaped;
+                }
+                else
+                    value += next;
+            }
+            tokens.push({ kind: 'string', text: source.slice(at, i), value, at, end: i });
+            continue;
+        }
+        if (char === '`') {
+            let value = '';
+            i++;
+            for (;;) {
+                const next = source[i];
+                if (next === undefined)
+                    throw new CypherError('this name is never closed', at);
+                i++;
+                if (next === '`') {
+                    if (source[i] === '`') {
+                        value += '`';
+                        i++;
+                        continue;
+                    }
+                    break;
+                }
+                value += next;
+            }
+            if (!value)
+                throw new CypherError('a name in backticks cannot be empty', at);
+            tokens.push({ kind: 'quoted', text: value, at, end: i });
+            continue;
+        }
+        const number = /^\d+(\.\d+)?([eE][+-]?\d+)?/.exec(source.slice(i));
+        if (number) {
+            i += number[0].length;
+            tokens.push({ kind: 'number', text: number[0], value: Number(number[0]), at, end: i });
+            continue;
+        }
+        const word = /^[\p{L}_][\p{L}\p{N}_]*/u.exec(source.slice(i));
+        if (word) {
+            i += word[0].length;
+            tokens.push({ kind: 'word', text: word[0], at, end: i });
+            continue;
+        }
+        const pair = source.slice(i, i + 2);
+        if (TWO.includes(pair)) {
+            i += 2;
+            tokens.push({ kind: 'punct', text: pair === '!=' ? '<>' : pair, at, end: i });
+            continue;
+        }
+        if (ONE.includes(char)) {
+            i++;
+            tokens.push({ kind: 'punct', text: char, at, end: i });
+            continue;
+        }
+        if (char === '$')
+            throw new CypherError('parameters ($name) are not supported', at);
+        throw new CypherError(`unexpected "${char}"`, at);
+    }
+    tokens.push({ kind: 'end', text: '', at: source.length, end: source.length });
+    return tokens;
+}
+const UNSUPPORTED_CLAUSES = {
+    optional: 'OPTIONAL MATCH',
+    with: 'WITH',
+    unwind: 'UNWIND',
+    union: 'UNION',
+    call: 'CALL',
+    create: 'CREATE',
+    merge: 'MERGE',
+    delete: 'DELETE',
+    detach: 'DELETE',
+    set: 'SET',
+    remove: 'REMOVE',
+    foreach: 'FOREACH',
+};
+class Parser {
+    source;
+    tokens;
+    at = 0;
+    constructor(source, tokens) {
+        this.source = source;
+        this.tokens = tokens;
+    }
+    get token() {
+        return this.tokens[this.at];
+    }
+    describe(token) {
+        return token.kind === 'end' ? 'the end of the query' : `"${token.text}"`;
+    }
+    fail(message, token = this.token) {
+        throw new CypherError(message, token.at);
+    }
+    word(...names) {
+        const token = this.token;
+        return token.kind === 'word' && names.includes(token.text.toLowerCase());
+    }
+    punct(text) {
+        return this.token.kind === 'punct' && this.token.text === text;
+    }
+    acceptWord(name) {
+        if (!this.word(name))
+            return false;
+        this.at++;
+        return true;
+    }
+    acceptPunct(text) {
+        if (!this.punct(text))
+            return false;
+        this.at++;
+        return true;
+    }
+    expectPunct(text, what = `"${text}"`) {
+        if (!this.acceptPunct(text))
+            this.fail(`expected ${what} but found ${this.describe(this.token)}`);
+    }
+    expectWord(name) {
+        if (!this.acceptWord(name)) {
+            this.fail(`expected ${name.toUpperCase()} but found ${this.describe(this.token)}`);
+        }
+    }
+    /** A name: a word, or anything in backticks. */
+    name(what) {
+        const token = this.token;
+        if (token.kind !== 'word' && token.kind !== 'quoted') {
+            this.fail(`expected ${what} but found ${this.describe(token)}`);
+        }
+        this.at++;
+        return token.text;
+    }
+    integer(what) {
+        const token = this.token;
+        if (token.kind !== 'number' || !Number.isInteger(token.value)) {
+            this.fail(`${what} must be a whole number`);
+        }
+        this.at++;
+        return token.value;
+    }
+    parse() {
+        const patterns = [];
+        const where = [];
+        while (this.word('match')) {
+            this.at++;
+            do
+                patterns.push(this.pattern());
+            while (this.acceptPunct(','));
+            if (this.acceptWord('where'))
+                where.push(this.expression(false));
+        }
+        if (patterns.length === 0) {
+            const first = this.token;
+            const unsupported = first.kind === 'word' ? UNSUPPORTED_CLAUSES[first.text.toLowerCase()] : null;
+            if (unsupported)
+                this.fail(`${unsupported} is not supported: queries are read only, MATCH ... RETURN`);
+            this.fail(`a query starts with MATCH, not ${this.describe(first)}`);
+        }
+        const unsupported = this.token.kind === 'word' ? UNSUPPORTED_CLAUSES[this.token.text.toLowerCase()] : null;
+        if (unsupported)
+            this.fail(`${unsupported} is not supported: queries are read only, MATCH ... RETURN`);
+        if (!this.word('return'))
+            this.fail(`expected RETURN but found ${this.describe(this.token)}`);
+        this.at++;
+        const distinct = this.acceptWord('distinct');
+        let returns = null;
+        if (this.acceptPunct('*')) {
+            if (this.punct(','))
+                this.fail('RETURN * cannot be combined with other items');
+        }
+        else {
+            returns = [];
+            do
+                returns.push(this.returnItem());
+            while (this.acceptPunct(','));
+        }
+        const orderBy = [];
+        if (this.acceptWord('order')) {
+            this.expectWord('by');
+            do {
+                const start = this.token;
+                const expr = this.expression(true);
+                const text = this.source.slice(start.at, this.tokens[this.at - 1].end);
+                const descending = this.acceptWord('desc') || this.acceptWord('descending');
+                if (!descending && !this.acceptWord('asc'))
+                    this.acceptWord('ascending');
+                orderBy.push({ expr, text, descending });
+            } while (this.acceptPunct(','));
+        }
+        const skip = this.acceptWord('skip') ? this.integer('SKIP') : undefined;
+        const limit = this.acceptWord('limit') ? this.integer('LIMIT') : undefined;
+        this.acceptPunct(';');
+        if (this.token.kind !== 'end') {
+            const next = this.token;
+            const clause = next.kind === 'word' ? UNSUPPORTED_CLAUSES[next.text.toLowerCase()] : null;
+            this.fail(clause ? `${clause} is not supported` : `unexpected ${this.describe(next)}`);
+        }
+        return { patterns, where, distinct, returns, orderBy, skip, limit };
+    }
+    returnItem() {
+        const start = this.token;
+        const expr = this.expression(true);
+        const text = this.source.slice(start.at, this.tokens[this.at - 1].end);
+        const alias = this.acceptWord('as') ? this.name('a name after AS') : undefined;
+        return { expr, text, alias };
+    }
+    pattern() {
+        if (this.token.kind === 'word' && this.tokens[this.at + 1]?.text === '=') {
+            this.fail('naming a whole path (p = ...) is not supported');
+        }
+        const nodes = [this.nodePattern()];
+        const relationships = [];
+        while (this.punct('-') || this.punct('<')) {
+            relationships.push(this.relationship());
+            nodes.push(this.nodePattern());
+        }
+        return { nodes, relationships };
+    }
+    nodePattern() {
+        const at = this.token.at;
+        this.expectPunct('(', 'a node such as "(c:Customer)"');
+        let variable;
+        let label;
+        if (this.token.kind === 'word' || this.token.kind === 'quoted')
+            variable = this.name('a name');
+        if (this.acceptPunct(':')) {
+            label = this.name('a table name after ":"');
+            // schema.table
+            if (this.acceptPunct('.'))
+                label += `.${this.name('a table name')}`;
+            if (this.punct(':'))
+                this.fail('a node has one label: the table it is a row of');
+        }
+        const properties = [];
+        if (this.acceptPunct('{')) {
+            if (!this.punct('}')) {
+                do {
+                    const keyAt = this.token.at;
+                    const column = this.name('a column name');
+                    this.expectPunct(':');
+                    properties.push({ column, value: this.literal(), at: keyAt });
+                } while (this.acceptPunct(','));
+            }
+            this.expectPunct('}');
+        }
+        this.expectPunct(')', '")" to close the node');
+        return { variable, label, properties, at };
+    }
+    relationship() {
+        const at = this.token.at;
+        const left = this.acceptPunct('<');
+        this.expectPunct('-');
+        let hint;
+        if (this.acceptPunct('[')) {
+            if (this.token.kind === 'word' || this.token.kind === 'quoted') {
+                this.fail('a relationship cannot be named: it is a foreign key, not a row', this.token);
+            }
+            if (this.acceptPunct(':')) {
+                hint = this.name('a foreign key, column or table name after ":"');
+                if (this.punct('|') || this.punct(':')) {
+                    this.fail('a relationship has one type: a foreign key, column or table name');
+                }
+            }
+            if (this.punct('*')) {
+                this.fail('paths of any length are not supported: write the nodes along the way');
+            }
+            if (this.punct('{'))
+                this.fail('relationships have no properties');
+            this.expectPunct(']', '"]" to close the relationship');
+        }
+        this.expectPunct('-');
+        const right = this.acceptPunct('>');
+        if (left && right)
+            this.fail('a relationship points one way: use <- or ->, not <->', this.tokens[this.at - 1]);
+        return { direction: left ? 'in' : right ? 'out' : 'any', hint, at };
+    }
+    literal() {
+        const negative = this.acceptPunct('-');
+        const token = this.token;
+        if (token.kind === 'number') {
+            this.at++;
+            return negative ? -token.value : token.value;
+        }
+        if (negative)
+            this.fail('expected a number after "-"');
+        if (token.kind === 'string') {
+            this.at++;
+            return token.value;
+        }
+        if (this.acceptWord('true'))
+            return true;
+        if (this.acceptWord('false'))
+            return false;
+        if (this.acceptWord('null'))
+            return null;
+        return this.fail(`expected a value (a string, number, true, false or null) but found ${this.describe(token)}`);
+    }
+    /** `aggregates` is whether a function such as count(...) may appear (in RETURN and ORDER BY). */
+    expression(aggregates) {
+        return this.or(aggregates);
+    }
+    or(aggregates) {
+        let left = this.and(aggregates);
+        while (this.acceptWord('or'))
+            left = { kind: 'logic', op: 'or', left, right: this.and(aggregates) };
+        return left;
+    }
+    and(aggregates) {
+        let left = this.not(aggregates);
+        while (this.acceptWord('and'))
+            left = { kind: 'logic', op: 'and', left, right: this.not(aggregates) };
+        return left;
+    }
+    not(aggregates) {
+        if (this.acceptWord('not'))
+            return { kind: 'not', operand: this.not(aggregates) };
+        return this.comparison(aggregates);
+    }
+    comparison(aggregates) {
+        const left = this.primary(aggregates);
+        const token = this.token;
+        if (token.kind === 'punct' && ['=', '<>', '<', '<=', '>', '>=', '=~'].includes(token.text)) {
+            this.at++;
+            return { kind: 'compare', op: token.text, left, right: this.primary(aggregates) };
+        }
+        if (this.acceptWord('is')) {
+            const negated = this.acceptWord('not');
+            this.expectWord('null');
+            return { kind: 'null', operand: left, negated };
+        }
+        if (this.acceptWord('in')) {
+            this.expectPunct('[', 'a list such as [1, 2]');
+            const list = [];
+            if (!this.punct(']')) {
+                do
+                    list.push(this.primary(aggregates));
+                while (this.acceptPunct(','));
+            }
+            this.expectPunct(']');
+            return { kind: 'in', operand: left, list };
+        }
+        if (this.word('starts', 'ends')) {
+            const op = this.token.text.toLowerCase() === 'starts' ? 'starts' : 'ends';
+            this.at++;
+            this.expectWord('with');
+            return { kind: 'compare', op, left, right: this.primary(aggregates) };
+        }
+        if (this.acceptWord('contains'))
+            return { kind: 'compare', op: 'contains', left, right: this.primary(aggregates) };
+        return left;
+    }
+    primary(aggregates) {
+        const token = this.token;
+        if (this.acceptPunct('(')) {
+            const inner = this.expression(aggregates);
+            this.expectPunct(')');
+            return inner;
+        }
+        if (token.kind === 'string' || token.kind === 'number' || this.punct('-')) {
+            return { kind: 'literal', value: this.literal() };
+        }
+        if (token.kind === 'word') {
+            const lower = token.text.toLowerCase();
+            if (lower === 'true' || lower === 'false' || lower === 'null') {
+                return { kind: 'literal', value: this.literal() };
+            }
+        }
+        if (token.kind === 'word' || token.kind === 'quoted') {
+            this.at++;
+            if (token.kind === 'word' && this.punct('('))
+                return this.call(token, aggregates);
+            if (this.acceptPunct('.')) {
+                return {
+                    kind: 'property',
+                    variable: token.text,
+                    column: this.name('a column name'),
+                    at: token.at,
+                };
+            }
+            return { kind: 'variable', name: token.text, at: token.at };
+        }
+        return this.fail(`expected a value but found ${this.describe(token)}`);
+    }
+    call(token, aggregates) {
+        const name = token.text.toLowerCase();
+        const aggregate = AGGREGATES.includes(name);
+        if (!aggregate && !SCALARS.includes(name)) {
+            this.fail(`unknown function ${token.text}(): try ${[...AGGREGATES, 'toLower', 'toUpper', 'coalesce'].join(', ')}`, token);
+        }
+        if (aggregate && !aggregates)
+            this.fail(`${token.text}() can only be used in RETURN and ORDER BY`, token);
+        this.expectPunct('(');
+        let star = false;
+        const args = [];
+        const distinct = aggregate && this.acceptWord('distinct');
+        if (this.acceptPunct('*')) {
+            if (name !== 'count')
+                this.fail(`only count(*) takes *`, token);
+            star = true;
+        }
+        else if (!this.punct(')')) {
+            do
+                args.push(this.expression(false));
+            while (this.acceptPunct(','));
+        }
+        this.expectPunct(')');
+        if (!star && args.length === 0)
+            this.fail(`${token.text}() needs an argument`, token);
+        return { kind: 'call', name, distinct, star, args, at: token.at };
+    }
+}
+export function parseCypher(source) {
+    if (!source.trim())
+        throw new CypherError('write a query, e.g. MATCH (c:Customer) RETURN c LIMIT 25');
+    return new Parser(source, tokenize(source)).parse();
+}