@quereus/quereus 1.3.1 → 2.0.0

package/dist/src/parser/parser.js

@@ -29,6 +29,13 @@ function _createLoc(startToken, endToken) {
         },
     };
 }
+/**
+ * IMPORTANT: Any changes to parsed syntax must also be reflected in the corresponding emitters:
+ *   - packages/quereus/src/emit/ast-stringify.ts          (AST-to-SQL string conversion)
+ *   - packages/quereus/src/schema/catalog.ts              (DDL generation for catalog/hashing)
+ *   - packages/quereus-store/src/common/ddl-generator.ts  (DDL generation for persistence)
+ * If only the parser is updated, SQL round-trips and persisted schemas will silently lose the new syntax.
+ */
 export class Parser {
     tokens = [];
     current = 0;
@@ -2051,15 +2058,26 @@ export class Parser {
                 this.consume(TokenType.RPAREN, "Expected ')' after module arguments.");
             }
         }
-        // Parse mutation context definitions if present
+        // Parse trailing WITH clauses (CONTEXT, TAGS) in any order
         let contextDefinitions;
-        if (this.matchKeyword('WITH')) {
+        let tags;
+        while (this.matchKeyword('WITH')) {
             if (this.matchKeyword('CONTEXT')) {
+                if (contextDefinitions) {
+                    throw this.error(this.previous(), "Duplicate WITH CONTEXT clause");
+                }
                 contextDefinitions = this.parseMutationContextDefinitions();
             }
+            else if (this.matchKeyword('TAGS')) {
+                if (tags) {
+                    throw this.error(this.previous(), "Duplicate WITH TAGS clause");
+                }
+                tags = this.parseTags();
+            }
             else {
-                // Not a WITH CONTEXT clause, backtrack
+                // Not a recognized WITH clause, backtrack
                 this.current--;
+                break;
             }
         }
         return {
@@ -2072,6 +2090,7 @@ export class Parser {
             moduleName,
             moduleArgs,
             contextDefinitions,
+            tags,
             loc: _createLoc(startToken, this.previous()),
         };
     }
@@ -2101,6 +2120,16 @@ export class Parser {
         if (this.matchKeyword('WHERE')) {
             where = this.expression();
         }
+        // Parse optional WITH TAGS
+        let tags;
+        if (this.matchKeyword('WITH')) {
+            if (this.matchKeyword('TAGS')) {
+                tags = this.parseTags();
+            }
+            else {
+                this.current--;
+            }
+        }
         return {
             type: 'createIndex',
             index,
@@ -2109,6 +2138,7 @@ export class Parser {
             columns,
             where,
             isUnique,
+            tags,
             loc: _createLoc(startToken, this.previous()),
         };
     }
@@ -2144,6 +2174,16 @@ export class Parser {
         this.consumeKeyword('AS', "Expected 'AS' before SELECT statement for CREATE VIEW.");
         const selectStartToken = this.consume(TokenType.SELECT, "Expected 'SELECT' after 'AS' in CREATE VIEW.");
         const select = this.selectStatement(selectStartToken, withClause);
+        // Parse optional WITH TAGS
+        let tags;
+        if (this.matchKeyword('WITH')) {
+            if (this.matchKeyword('TAGS')) {
+                tags = this.parseTags();
+            }
+            else {
+                this.current--;
+            }
+        }
         return {
             type: 'createView',
             view,
@@ -2151,6 +2191,7 @@ export class Parser {
             columns,
             select,
             isTemporary,
+            tags,
             loc: _createLoc(startToken, this.previous()),
         };
     }
@@ -2478,15 +2519,25 @@ export class Parser {
         else {
             this.consume(TokenType.RPAREN, "Expected ')' after table definition.");
         }
-        // Parse mutation context definitions if present (WITH CONTEXT clause)
+        // Parse trailing WITH clauses (CONTEXT, TAGS) in any order
         let contextDefinitions;
-        if (this.matchKeyword('WITH')) {
+        let tags;
+        while (this.matchKeyword('WITH')) {
             if (this.matchKeyword('CONTEXT')) {
+                if (contextDefinitions) {
+                    throw this.error(this.previous(), "Duplicate WITH CONTEXT clause");
+                }
                 contextDefinitions = this.parseMutationContextDefinitions();
             }
+            else if (this.matchKeyword('TAGS')) {
+                if (tags) {
+                    throw this.error(this.previous(), "Duplicate WITH TAGS clause");
+                }
+                tags = this.parseTags();
+            }
             else {
-                // Not a WITH CONTEXT clause, backtrack
                 this.current--;
+                break;
             }
         }
         // Build the CREATE TABLE AST node for this declared table
@@ -2499,7 +2550,8 @@ export class Parser {
             isTemporary: false,
             moduleName,
             moduleArgs,
-            contextDefinitions
+            contextDefinitions,
+            tags
         };
         return { type: 'declaredTable', tableStmt };
     }
@@ -2510,13 +2562,24 @@ export class Parser {
         this.consume(TokenType.LPAREN, "Expected '(' before index columns.");
         const columns = this.indexedColumnList();
         this.consume(TokenType.RPAREN, "Expected ')' after index columns.");
+        // Parse optional WITH TAGS
+        let tags;
+        if (this.matchKeyword('WITH')) {
+            if (this.matchKeyword('TAGS')) {
+                tags = this.parseTags();
+            }
+            else {
+                this.current--;
+            }
+        }
         const indexStmt = {
             type: 'createIndex',
             index: { type: 'identifier', name: indexName },
             table: { type: 'identifier', name: tableName },
             ifNotExists: false,
             columns,
-            isUnique: false
+            isUnique: false,
+            tags
         };
         return { type: 'declaredIndex', indexStmt };
     }
@@ -2530,13 +2593,24 @@ export class Parser {
         this.consumeKeyword('AS', "Expected AS before SELECT in view declaration.");
         const selTok = this.consume(TokenType.SELECT, "Expected SELECT after AS in view declaration.");
         const select = this.selectStatement(selTok);
+        // Parse optional WITH TAGS
+        let tags;
+        if (this.matchKeyword('WITH')) {
+            if (this.matchKeyword('TAGS')) {
+                tags = this.parseTags();
+            }
+            else {
+                this.current--;
+            }
+        }
         const viewStmt = {
             type: 'createView',
             view: { type: 'identifier', name: viewName },
             ifNotExists: false,
             columns,
             select,
-            isTemporary: false
+            isTemporary: false,
+            tags
         };
         return { type: 'declaredView', viewStmt };
     }
@@ -2842,7 +2916,17 @@ export class Parser {
             }
         }
         const constraints = this.columnConstraintList();
-        return { name, dataType, constraints };
+        // Parse optional column-level WITH TAGS
+        let tags;
+        if (this.matchKeyword('WITH')) {
+            if (this.matchKeyword('TAGS')) {
+                tags = this.parseTags();
+            }
+            else {
+                this.current--;
+            }
+        }
+        return { name, dataType, constraints, tags };
     }
     /** @internal Parses mutation context variable definitions: WITH CONTEXT (var type [NULL], ...) */
     parseMutationContextDefinitions() {
@@ -2914,6 +2998,7 @@ export class Parser {
     parseTrailingWithClauses() {
         let contextValues;
         let schemaPath;
+        let tags;
         // Keep trying to parse WITH clauses until we don't find any more
         while (this.matchKeyword('WITH')) {
             if (this.matchKeyword('CONTEXT')) {
@@ -2933,13 +3018,64 @@ export class Parser {
                 } while (this.match(TokenType.COMMA));
                 schemaPath = schemas;
             }
+            else if (this.matchKeyword('TAGS')) {
+                if (tags) {
+                    throw this.error(this.previous(), "Duplicate WITH TAGS clause");
+                }
+                tags = this.parseTags();
+            }
             else {
-                // Not a WITH CONTEXT or WITH SCHEMA clause, backtrack
+                // Not a recognized WITH clause, backtrack
                 this.current--;
                 break;
             }
         }
-        return { contextValues, schemaPath };
+        return { contextValues, schemaPath, tags };
+    }
+    /**
+     * @internal Parses a tags list: (key = value, ...)
+     * Called after the TAGS keyword has been consumed.
+     * Keys are identifiers, values are literals (string, number, boolean via TRUE/FALSE, NULL).
+     */
+    parseTags() {
+        this.consume(TokenType.LPAREN, "Expected '(' after TAGS.");
+        const tags = {};
+        if (!this.check(TokenType.RPAREN)) {
+            do {
+                const key = this.consumeIdentifier("Expected tag key identifier.");
+                this.consume(TokenType.EQUAL, `Expected '=' after tag key '${key}'.`);
+                const value = this.parseTagValue();
+                tags[key] = value;
+            } while (this.match(TokenType.COMMA));
+        }
+        this.consume(TokenType.RPAREN, "Expected ')' after tag list.");
+        return tags;
+    }
+    /** @internal Parses a tag value: string, number, TRUE, FALSE, or NULL */
+    parseTagValue() {
+        if (this.match(TokenType.STRING)) {
+            return this.previous().literal;
+        }
+        if (this.match(TokenType.INTEGER) || this.match(TokenType.FLOAT)) {
+            return this.previous().literal;
+        }
+        if (this.match(TokenType.TRUE)) {
+            return true;
+        }
+        if (this.match(TokenType.FALSE)) {
+            return false;
+        }
+        if (this.match(TokenType.NULL)) {
+            return null;
+        }
+        // Allow negative numbers
+        if (this.match(TokenType.MINUS)) {
+            if (this.match(TokenType.INTEGER) || this.match(TokenType.FLOAT)) {
+                return -this.previous().literal;
+            }
+            throw this.error(this.peek(), "Expected number after '-' in tag value.");
+        }
+        throw this.error(this.peek(), "Expected tag value (string, number, true, false, or null).");
     }
     /** @internal Parses column constraints */
     columnConstraintList() {
@@ -2971,6 +3107,7 @@ export class Parser {
             name = this.consumeIdentifier("Expected constraint name after CONSTRAINT.");
             endToken = this.previous();
         }
+        let result;
         if (this.match(TokenType.PRIMARY)) {
             this.consume(TokenType.KEY, "Expected KEY after PRIMARY.");
             const direction = this.match(TokenType.ASC) ? 'asc' : this.match(TokenType.DESC) ? 'desc' : undefined;
@@ -2978,57 +3115,48 @@ export class Parser {
                 endToken = this.previous();
             const onConflict = this.parseConflictClause();
             if (onConflict)
-                endToken = this.previous(); // Update endToken if conflict clause was parsed
+                endToken = this.previous();
             if (this.check(TokenType.AUTOINCREMENT)) {
                 throw this.error(this.peek(), 'AUTOINCREMENT is not supported. Quereus uses key-based addressing without implicit side-effects.');
             }
-            return { type: 'primaryKey', name, onConflict, direction, loc: _createLoc(startToken, endToken) };
+            result = { type: 'primaryKey', name, onConflict, direction, loc: _createLoc(startToken, endToken) };
         }
         else if (this.match(TokenType.NOT)) {
             this.consume(TokenType.NULL, "Expected NULL after NOT.");
             endToken = this.previous();
             const onConflict = this.parseConflictClause();
             if (onConflict)
-                endToken = this.previous(); // Update endToken if conflict clause was parsed
-            return { type: 'notNull', name, onConflict, loc: _createLoc(startToken, endToken) };
+                endToken = this.previous();
+            result = { type: 'notNull', name, onConflict, loc: _createLoc(startToken, endToken) };
         }
         else if (this.match(TokenType.NULL)) {
             endToken = this.previous();
             const onConflict = this.parseConflictClause();
             if (onConflict)
-                endToken = this.previous(); // Update endToken if conflict clause was parsed
-            return { type: 'null', name, onConflict, loc: _createLoc(startToken, endToken) };
+                endToken = this.previous();
+            result = { type: 'null', name, onConflict, loc: _createLoc(startToken, endToken) };
         }
         else if (this.match(TokenType.UNIQUE)) {
             endToken = this.previous();
             const onConflict = this.parseConflictClause();
             if (onConflict)
-                endToken = this.previous(); // Update endToken if conflict clause was parsed
-            return { type: 'unique', name, onConflict, loc: _createLoc(startToken, endToken) };
+                endToken = this.previous();
+            result = { type: 'unique', name, onConflict, loc: _createLoc(startToken, endToken) };
         }
         else if (this.match(TokenType.CHECK)) {
-            // --- Parse optional ON clause before parentheses --- //
             let operations;
             if (this.matchKeyword('ON')) {
                 operations = this.parseRowOpList();
             }
-            // --- End Parse ON clause --- //
             this.consume(TokenType.LPAREN, "Expected '(' after CHECK.");
             const expr = this.expression();
             endToken = this.consume(TokenType.RPAREN, "Expected ')' after CHECK expression.");
-            // No DEFERRABLE syntax supported; deferral is auto-detected by the planner
-            return {
-                type: 'check',
-                name,
-                expr,
-                operations,
-                loc: _createLoc(startToken, endToken)
-            };
+            result = { type: 'check', name, expr, operations, loc: _createLoc(startToken, endToken) };
         }
         else if (this.match(TokenType.DEFAULT)) {
             const expr = this.expression();
             endToken = this.previous();
-            return { type: 'default', name, expr, loc: _createLoc(startToken, endToken) };
+            result = { type: 'default', name, expr, loc: _createLoc(startToken, endToken) };
         }
         else if (this.match(TokenType.COLLATE)) {
             if (!this.check(TokenType.IDENTIFIER)) {
@@ -3036,12 +3164,12 @@ export class Parser {
             }
             const collation = this.getIdentifierValue(this.advance());
             endToken = this.previous();
-            return { type: 'collate', name, collation, loc: _createLoc(startToken, endToken) };
+            result = { type: 'collate', name, collation, loc: _createLoc(startToken, endToken) };
         }
         else if (this.match(TokenType.REFERENCES)) {
             const fkClause = this.foreignKeyClause();
-            endToken = this.previous(); // End token is end of FK clause
-            return { type: 'foreignKey', name, foreignKey: fkClause, loc: _createLoc(startToken, endToken) };
+            endToken = this.previous();
+            result = { type: 'foreignKey', name, foreignKey: fkClause, loc: _createLoc(startToken, endToken) };
         }
         else if (this.match(TokenType.GENERATED)) {
             this.consume(TokenType.ALWAYS, "Expected ALWAYS after GENERATED.");
@@ -3058,9 +3186,21 @@ export class Parser {
             else if (this.match(TokenType.VIRTUAL)) {
                 endToken = this.previous();
             }
-            return { type: 'generated', name, generated: { expr, stored }, loc: _createLoc(startToken, endToken) };
+            result = { type: 'generated', name, generated: { expr, stored }, loc: _createLoc(startToken, endToken) };
+        }
+        else {
+            throw this.error(this.peek(), "Expected column constraint type (PRIMARY KEY, NOT NULL, UNIQUE, CHECK, DEFAULT, COLLATE, REFERENCES, GENERATED).");
+        }
+        // Parse optional trailing WITH TAGS for the constraint
+        if (this.matchKeyword('WITH')) {
+            if (this.matchKeyword('TAGS')) {
+                result.tags = this.parseTags();
+            }
+            else {
+                this.current--;
+            }
         }
-        throw this.error(this.peek(), "Expected column constraint type (PRIMARY KEY, NOT NULL, UNIQUE, CHECK, DEFAULT, COLLATE, REFERENCES, GENERATED).");
+        return result;
     }
     /** @internal Parses a table constraint */
     tableConstraint() {
@@ -3071,6 +3211,7 @@ export class Parser {
             name = this.consumeIdentifier("Expected constraint name after CONSTRAINT.");
             endToken = this.previous();
         }
+        let result;
         if (this.match(TokenType.PRIMARY)) {
             this.consume(TokenType.KEY, "Expected KEY after PRIMARY.");
             this.consume(TokenType.LPAREN, "Expected '(' before PRIMARY KEY columns.");
@@ -3083,7 +3224,7 @@ export class Parser {
             const onConflict = this.parseConflictClause();
             if (onConflict)
                 endToken = this.previous();
-            return { type: 'primaryKey', name, columns, onConflict, loc: _createLoc(startToken, endToken) };
+            result = { type: 'primaryKey', name, columns, onConflict, loc: _createLoc(startToken, endToken) };
         }
         else if (this.match(TokenType.UNIQUE)) {
             this.consume(TokenType.LPAREN, "Expected '(' before UNIQUE columns.");
@@ -3093,26 +3234,17 @@ export class Parser {
             const onConflict = this.parseConflictClause();
             if (onConflict)
                 endToken = this.previous();
-            return { type: 'unique', name, columns, onConflict, loc: _createLoc(startToken, endToken) };
+            result = { type: 'unique', name, columns, onConflict, loc: _createLoc(startToken, endToken) };
         }
         else if (this.match(TokenType.CHECK)) {
-            // --- Parse optional ON clause before parentheses --- //
             let operations;
             if (this.matchKeyword('ON')) {
                 operations = this.parseRowOpList();
             }
-            // --- End Parse ON clause --- //
             this.consume(TokenType.LPAREN, "Expected '(' after CHECK.");
             const expr = this.expression();
             endToken = this.consume(TokenType.RPAREN, "Expected ')' after CHECK expression.");
-            // No DEFERRABLE syntax supported; deferral is auto-detected by the planner
-            return {
-                type: 'check',
-                name,
-                expr,
-                operations,
-                loc: _createLoc(startToken, endToken)
-            };
+            result = { type: 'check', name, expr, operations, loc: _createLoc(startToken, endToken) };
         }
         else if (this.match(TokenType.FOREIGN)) {
             this.consume(TokenType.KEY, "Expected KEY after FOREIGN.");
@@ -3120,10 +3252,22 @@ export class Parser {
             const columns = this.identifierList().map(name => ({ name }));
             this.consume(TokenType.RPAREN, "Expected ')' after FOREIGN KEY columns.");
             const fkClause = this.foreignKeyClause();
-            endToken = this.previous(); // End token is end of FK clause
-            return { type: 'foreignKey', name, columns, foreignKey: fkClause, loc: _createLoc(startToken, endToken) };
+            endToken = this.previous();
+            result = { type: 'foreignKey', name, columns, foreignKey: fkClause, loc: _createLoc(startToken, endToken) };
+        }
+        else {
+            throw this.error(this.peek(), "Expected table constraint type (PRIMARY KEY, UNIQUE, CHECK, FOREIGN KEY).");
+        }
+        // Parse optional trailing WITH TAGS for the constraint
+        if (this.matchKeyword('WITH')) {
+            if (this.matchKeyword('TAGS')) {
+                result.tags = this.parseTags();
+            }
+            else {
+                this.current--;
+            }
         }
-        throw this.error(this.peek(), "Expected table constraint type (PRIMARY KEY, UNIQUE, CHECK, FOREIGN KEY).");
+        return result;
     }
     /** @internal Parses a foreign key clause (REFERENCES may already be consumed by caller) */
     foreignKeyClause() {
@@ -3223,7 +3367,7 @@ export class Parser {
         }
         else if (this.match(TokenType.NO)) {
             this.consume(TokenType.ACTION, "Expected ACTION after NO.");
-            return 'noAction';
+            return 'ignore';
         }
         throw this.error(this.peek(), "Expected foreign key action (SET NULL, SET DEFAULT, CASCADE, RESTRICT, NO ACTION).");
     }