@webda/ql 4.0.0-beta.2 → 4.0.0-beta.3

package/lib/query.js

@@ -2,18 +2,99 @@ import { CharStreams, CommonTokenStream } from "antlr4ts";
 import { AbstractParseTreeVisitor, TerminalNode } from "antlr4ts/tree/index.js";
 import { WebdaQLLexer } from "./WebdaQLLexer.js";
 import { OrderFieldExpressionContext, SubExpressionContext, WebdaQLParserParser } from "./WebdaQLParserParser.js";
+import { WebdaQLError } from "./webdaql-string.js";
+/**
+ * Strip the quotes of a WebdaQL string literal and unescape its contents.
+ *
+ * Processes the inner text (between outer quotes) with these rules, applied left-to-right:
+ * - `\\` → `\` (escaped backslash)
+ * - `\` followed by the literal's quote char → the quote char (backslash-escaped quote)
+ * - the quote char doubled → one quote char (SQL-style doubled quote)
+ * - any other `\x` → `\x` kept verbatim (so LIKE's `\%` and `\_` reach likeToRegex unchanged)
+ *
+ * @param literal - the literal including its surrounding quotes
+ * @returns the literal value
+ */
+export function unescapeStringLiteral(literal) {
+    const quote = literal[0];
+    const inner = literal.substring(1, literal.length - 1);
+    let result = "";
+    for (let i = 0; i < inner.length; i++) {
+        if (inner[i] === "\\") {
+            if (i + 1 < inner.length) {
+                const next = inner[i + 1];
+                if (next === "\\") {
+                    // \\ → \
+                    result += "\\";
+                    i++;
+                }
+                else if (next === quote) {
+                    // \' or \" → ' or "
+                    result += quote;
+                    i++;
+                }
+                else {
+                    // other \x → \x (kept verbatim, e.g., \%, \_, etc.)
+                    result += "\\";
+                }
+            }
+            else {
+                // trailing backslash
+                result += "\\";
+            }
+        }
+        else if (inner[i] === quote && i + 1 < inner.length && inner[i + 1] === quote) {
+            // '' or "" → ' or "
+            result += quote;
+            i++;
+        }
+        else {
+            result += inner[i];
+        }
+    }
+    return result;
+}
+/**
+ * Prepend a condition to an existing query string using AND logic
+ *
+ * Parses both strings, merges them, and reconstructs the combined query.
+ * ORDER BY, LIMIT, and OFFSET clauses from the original query are preserved.
+ *
+ * @param query - existing query string (may include ORDER BY / LIMIT / OFFSET)
+ * @param condition - condition to prepend (filter expression only)
+ * @returns merged query string
+ *
+ * @example
+ * ```ts
+ * PrependCondition("status = 'active' ORDER BY name LIMIT 10", "age > 18")
+ * // => 'status = "active" AND age > 18 ORDER BY name LIMIT 10'
+ * ```
+ */
 export function PrependCondition(query = "", condition) {
     return new QueryValidator(query).merge(condition).toString();
 }
 /**
- * Create Expression based on the parsed token
+ * ANTLR parse tree visitor that builds an optimized Expression AST from the parsed tokens
  *
- * Expression allow to optimize and split between Query and Filter
+ * Converts the ANTLR parse tree into a flat, evaluatable expression tree.
+ * Automatically flattens nested AND/OR expressions of the same type to reduce depth.
  */
 export class ExpressionBuilder extends AbstractParseTreeVisitor {
     /**
-     * Default result for the override
-     * @returns
+     * Parsed LIMIT value, if present
+     */
+    limit;
+    /**
+     * Parsed OFFSET continuation token, if present
+     */
+    offset;
+    /**
+     * Parsed ORDER BY clauses, if present
+     */
+    orderBy;
+    /**
+     * Default result when no expression is matched (empty AND, always true)
+     * @returns an empty AND query
      */
     defaultResult() {
         // An empty AND return true
@@ -22,35 +103,37 @@ export class ExpressionBuilder extends AbstractParseTreeVisitor {
         };
     }
     /**
-     * Get offset
-     * @returns
+     * Get parsed OFFSET continuation token
+     * @returns the offset token
      */
     getOffset() {
         return this.offset;
     }
     /**
-     * Get limit
-     * @returns
+     * Get parsed LIMIT value
+     * @returns the limit value
      */
     getLimit() {
         return this.limit;
     }
     /**
-     * Read the limit
-     * @param ctx
+     * Visit a LIMIT clause and store the integer value
+     * @param ctx - the limit expression context
      */
     visitLimitExpression(ctx) {
-        this.limit = this.visitIntegerLiteral(ctx.getChild(1));
+        this.limit = this.visit(ctx.getChild(1));
     }
     /**
-     * Read the offset if provided
-     * @param ctx
+     * Visit an OFFSET clause and store the string continuation token
+     * @param ctx - the offset expression context
      */
     visitOffsetExpression(ctx) {
-        this.offset = this.visitStringLiteral(ctx.getChild(1));
+        this.offset = this.visit(ctx.getChild(1));
     }
     /**
      * Visit a order field expression
+     * @param ctx - the order field expression context
+     * @returns the parsed OrderBy
      */
     visitOrderFieldExpression(ctx) {
         return {
@@ -60,6 +143,7 @@ export class ExpressionBuilder extends AbstractParseTreeVisitor {
     }
     /**
      * Read the order by values
+     * @param ctx - the order expression context
      */
     visitOrderExpression(ctx) {
         this.orderBy = ctx.children
@@ -67,9 +151,12 @@ export class ExpressionBuilder extends AbstractParseTreeVisitor {
             .map((c) => this.visitOrderFieldExpression(c));
     }
     /**
-     * Return only AndExpression
-     * @param ctx
-     * @returns
+     * Visit the root `webdaql` rule and build the complete Query
+     *
+     * Parses filter expression, ORDER BY, LIMIT, and OFFSET clauses.
+     * Returns an empty AND expression (always true) when no filter is present.
+     * @param ctx - the webdaql parse context
+     * @returns the built Query
      */
     visitWebdaql(ctx) {
         if (ctx.childCount === 1) {
@@ -85,7 +172,7 @@ export class ExpressionBuilder extends AbstractParseTreeVisitor {
         // If the first element is a sub expression, it means we have a filter
         if (ctx.getChild(0) instanceof SubExpressionContext) {
             return {
-                filter: this.visit(ctx.getChild(0).getChild(1)) || new AndExpression([]),
+                filter: normalizeFilter(this.visit(ctx.getChild(0).getChild(1)) || new AndExpression([])),
                 limit: this.limit,
                 continuationToken: this.offset,
                 orderBy: this.orderBy
@@ -93,16 +180,21 @@ export class ExpressionBuilder extends AbstractParseTreeVisitor {
         }
         // Go down one level - if expression empty it means no expression were provided
         return {
-            filter: this.visit(ctx.getChild(0)) || new AndExpression([]),
+            filter: normalizeFilter(this.visit(ctx.getChild(0)) || new AndExpression([])),
             limit: this.limit,
             continuationToken: this.offset,
             orderBy: this.orderBy
         };
     }
     /**
-     * Simplify Logic expression and regroup them
-     * @param ctx
-     * @returns
+     * Recursively flatten nested logical expressions of the same type
+     *
+     * ANTLR produces right-recursive trees like `a AND (b AND (c AND d))`.
+     * This method flattens them into `[a, b, c, d]` so a single LogicalExpression
+     * holds all children at one level.
+     *
+     * @param ctx - an AND or OR logical expression context
+     * @returns flat array of child parse tree nodes
      */
     getComparison(ctx) {
         const res = [];
@@ -133,12 +225,16 @@ export class ExpressionBuilder extends AbstractParseTreeVisitor {
      *
      * By default the parser is doing a AND (b AND (c AND d)) creating 3 depth expressions
      * This visitor simplify to a AND b AND c AND d with only one Expression
+     * @param ctx - the AND logic expression context
+     * @returns the flattened AndExpression
      */
     visitAndLogicExpression(ctx) {
-        return new AndExpression(this.getComparison(ctx).map(c => this.visit(c)));
+        return foldLogical("AND", this.getComparison(ctx).map(c => this.visit(c)));
     }
     /**
      * Implement the BinaryComparison with all methods managed
+     * @param ctx - the binary comparison context
+     * @returns the comparison expression
      */
     visitBinaryComparisonExpression(ctx) {
         const [left, op, right] = ctx.children;
@@ -147,14 +243,16 @@ export class ExpressionBuilder extends AbstractParseTreeVisitor {
     }
     /**
      * Visit each value of the [..., ..., ...] set
+     * @param ctx - the set expression context
+     * @returns the array of values
      */
     visitSetExpression(ctx) {
         return ctx.children.filter((_i, id) => id % 2).map(c => this.visit(c));
     }
     /**
-     * a LIKE "%A?"
-     * @param ctx
-     * @returns
+     * Visit a LIKE expression (e.g. `field LIKE '%pattern_'`)
+     * @param ctx - the LIKE expression context
+     * @returns the comparison expression
      */
     visitLikeExpression(ctx) {
         const [left, _, right] = ctx.children;
@@ -163,6 +261,8 @@ export class ExpressionBuilder extends AbstractParseTreeVisitor {
     }
     /**
      * Map the a IN ['b','c']
+     * @param ctx - the IN expression context
+     * @returns the comparison expression
      */
     visitInExpression(ctx) {
         const [left, _, right] = ctx.children;
@@ -171,63 +271,148 @@ export class ExpressionBuilder extends AbstractParseTreeVisitor {
     }
     /**
      * Map the a CONTAINS 'b'
+     * @param ctx - the CONTAINS expression context
+     * @returns the comparison expression
      */
     visitContainsExpression(ctx) {
         const [left, _, right] = ctx.children;
         const value = this.visit(right);
         return new ComparisonExpression("CONTAINS", left.text, value);
     }
+    /**
+     * Map the a IS NULL
+     * @param ctx - the IS NULL expression context
+     * @returns the comparison expression
+     */
+    visitIsNullExpression(ctx) {
+        return new ComparisonExpression("IS NULL", ctx.getChild(0).text, null);
+    }
+    /**
+     * Map the a IS NOT NULL
+     * @param ctx - the IS NOT NULL expression context
+     * @returns the comparison expression
+     */
+    visitIsNotNullExpression(ctx) {
+        return new ComparisonExpression("IS NOT NULL", ctx.getChild(0).text, null);
+    }
     /**
      * Get the OrExpression, regrouping all the parameters
      *
      * By default the parser is doing a OR (b OR (c OR d)) creating 3 depth expressions
      * This visitor simplify to a OR b OR c OR d with only one Expression
+     * @param ctx - the OR logic expression context
+     * @returns the flattened OrExpression
      */
     visitOrLogicExpression(ctx) {
-        return new OrExpression(this.getComparison(ctx).map(c => this.visit(c)));
+        return foldLogical("OR", this.getComparison(ctx).map(c => this.visit(c)));
     }
     /**
-     * Read the string literal (removing the simple or double bracket)
+     * A bare atom used as an expression: only `TRUE` / `FALSE` are valid
+     * @param ctx - the atom expression context
+     * @returns the constant expression
+     * @throws {SyntaxError} for identifiers, numbers and strings
+     */
+    visitAtomExpression(ctx) {
+        const value = this.visit(ctx.getChild(0));
+        if (typeof value === "boolean") {
+            return new BooleanExpression(value);
+        }
+        throw new SyntaxError(`Expected an expression, got '${ctx.text}'`);
+    }
+    /**
+     * Read a string literal, stripping the surrounding single or double quotes
+     * @param ctx - the string literal context
+     * @returns the unquoted string value
      */
     visitStringLiteral(ctx) {
-        return ctx.text.substring(1, ctx.text.length - 1);
+        return unescapeStringLiteral(ctx.text);
     }
     /**
      * Read the boolean literal
+     * @param ctx - the boolean literal context
+     * @returns the boolean value
      */
     visitBooleanLiteral(ctx) {
         return "TRUE" === ctx.text;
     }
     /**
      * Read the number literal
+     * @param ctx - the integer literal context
+     * @returns the parsed integer value
      */
     visitIntegerLiteral(ctx) {
         return parseInt(ctx.text);
     }
+    /**
+     * Read a signed or decimal number literal
+     * @param ctx - the number literal context
+     * @returns the parsed number
+     */
+    visitNumberLiteral(ctx) {
+        return parseFloat(ctx.text);
+    }
+    /**
+     * A `?` or `:name` placeholder reaching evaluation was never bound
+     * @param ctx - the parameter context
+     * @throws {WebdaQLError} always: use `bind()` or pass the parameters to `query()`
+     */
+    visitParameter(ctx) {
+        throw new WebdaQLError(`Unbound parameter '${ctx.text}' in WebdaQL query: pass its value with the query parameters`);
+    }
 }
 /**
  * Represent the query expression or subset
  */
 export class Expression {
+    operator;
+    /** Create a new Expression.
+     * @param operator - the expression operator
+     */
     constructor(operator) {
         this.operator = operator;
     }
 }
 /**
- * Comparison expression
+ * Comparison operators that take no value
+ */
+export const UNARY_COMPARISON_OPERATORS = ["IS NULL", "IS NOT NULL"];
+/**
+ * A leaf expression comparing an object attribute against a literal value
+ *
+ * Supports dot-notation for nested attribute access (e.g. `user.profile.name`).
+ *
+ * @typeParam T - the specific comparison operator type
  */
 export class ComparisonExpression extends Expression {
     /**
-     *
-     * @param operator of the expression
-     * @param attribute of the object to read
-     * @param value
+     * Right side of the comparison
+     */
+    value;
+    /**
+     * Attribute to read from the object (split by .)
+     */
+    attribute;
+    /**
+     * @param operator - comparison operator
+     * @param attribute - dot-notation path to the object property (e.g. `"user.name"`)
+     * @param value - literal value or array of values (for IN operator) to compare against
      */
     constructor(operator, attribute, value) {
         super(operator);
         this.value = value;
         this.attribute = attribute.split(".");
     }
+    /**
+     * Convert a SQL LIKE pattern to a JavaScript RegExp
+     *
+     * - `%` matches zero or more characters
+     * - `_` matches exactly one character
+     * - `\%` and `\_` are literal percent/underscore
+     * - Common regex metacharacters are escaped
+     *
+     * @param like - SQL LIKE pattern string
+     * @returns compiled RegExp
+     */
     static likeToRegex(like) {
         return new RegExp(like
             // Prevent common regexp chars
@@ -246,10 +431,11 @@ export class ComparisonExpression extends Expression {
             .replace(/\\([^?[{(])/g, "\\\\"));
     }
     /**
-     * Read the value from the object
+     * Traverse an object using a dot-notation attribute path
      *
-     * @param target
-     * @returns
+     * @param target - object to read from
+     * @param attribute - path segments (e.g. `["user", "profile", "name"]`)
+     * @returns the resolved value, or `undefined` if any segment is missing
      */
     static getAttributeValue(target, attribute) {
         let res = target;
@@ -262,10 +448,9 @@ export class ComparisonExpression extends Expression {
      * Set the value of the attribute based on the assignment
      *
      * If used as a Set expression
-     * @param target
+     * @param target - the object to assign to
      */
     setAttributeValue(target) {
-        var _a;
         // Avoid alteration of prototype for security reason
         if (this.attribute.includes("__proto__")) {
             return;
@@ -273,7 +458,7 @@ export class ComparisonExpression extends Expression {
         if (this.operator === "=") {
             let res = target;
             for (let i = 0; res && i < this.attribute.length - 1; i++) {
-                res[_a = this.attribute[i]] ?? (res[_a] = {});
+                res[this.attribute[i]] ??= {};
                 res = res[this.attribute[i]];
             }
             res[this.attribute[this.attribute.length - 1]] = this.value;
@@ -299,6 +484,9 @@ export class ComparisonExpression extends Expression {
             case "!=":
                 return left != this.value;
             case "LIKE":
+                if (left === undefined || left === null) {
+                    return false;
+                }
                 if (typeof left === "string") {
                     // Grammar definie value as stringLiteral
                     return left.match(ComparisonExpression.likeToRegex(this.value)) !== null;
@@ -311,10 +499,18 @@ export class ComparisonExpression extends Expression {
                     return left.includes(this.value);
                 }
                 return false;
+            case "IS NULL":
+                return left === undefined || left === null;
+            case "IS NOT NULL":
+                return left !== undefined && left !== null;
         }
     }
     /**
-     * Return a string represantation of a value
+     * Serialize a value to its WebdaQL string representation
+     *
+     * Strings are double-quoted, booleans are uppercased, arrays are bracket-wrapped.
+     * @param value - the value to serialize
+     * @returns the serialized string
      */
     toStringValue(value) {
         if (Array.isArray(value)) {
@@ -322,7 +518,7 @@ export class ComparisonExpression extends Expression {
         }
         switch (typeof value) {
             case "string":
-                return `"${value}"`;
+                return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '""')}"`;
             case "boolean":
                 return value.toString().toUpperCase();
         }
@@ -330,12 +526,14 @@ export class ComparisonExpression extends Expression {
     }
     /**
      * Allow subclass to create different display
+     * @returns the attribute string
      */
     toStringAttribute() {
         return this.attribute.join(".");
     }
     /**
      * Allow subclass to create different display
+     * @returns the operator string
      */
     toStringOperator() {
         return this.operator;
@@ -344,26 +542,28 @@ export class ComparisonExpression extends Expression {
      * @override
      */
     toString() {
+        if (UNARY_COMPARISON_OPERATORS.includes(this.operator)) {
+            return `${this.toStringAttribute()} ${this.toStringOperator()}`;
+        }
         return `${this.toStringAttribute()} ${this.toStringOperator()} ${this.toStringValue(this.value)}`;
     }
 }
 /**
- * Abstract logic expression (AND|OR)
+ * Abstract base for logical expressions that combine child expressions (AND / OR)
  *
- * Could add XOR in the future
+ * @typeParam T - the literal operator type (`"AND"` or `"OR"`)
  */
 export class LogicalExpression extends Expression {
     /**
-     *
-     * @param operator
-     * @param children
+     * Child expressions combined by this logical operator
+     */
+    children = [];
+    /**
+     * @param operator - logical operator
+     * @param children - child expressions to combine
      */
     constructor(operator, children) {
         super(operator);
-        /**
-         * Contains the members of the logical expression
-         */
-        this.children = [];
         this.children = children;
     }
     /**
@@ -377,7 +577,10 @@ export class LogicalExpression extends Expression {
     }
 }
 /**
- * AND Expression implementation
+ * Logical AND expression — evaluates to `true` only if all children are `true`
+ *
+ * Uses short-circuit evaluation: returns `false` as soon as any child fails.
+ * An empty AND (no children) evaluates to `true`.
  */
 export class AndExpression extends LogicalExpression {
     /**
@@ -399,7 +602,10 @@ export class AndExpression extends LogicalExpression {
     }
 }
 /**
- * OR Expression implementation
+ * Logical OR expression — evaluates to `true` if any child is `true`
+ *
+ * Uses short-circuit evaluation: returns `true` as soon as any child passes.
+ * An empty OR (no children) evaluates to `true`.
  */
 export class OrExpression extends LogicalExpression {
     /**
@@ -421,32 +627,165 @@ export class OrExpression extends LogicalExpression {
     }
 }
 /**
+ * Constant expression from a `TRUE` / `FALSE` literal
+ *
+ * Constants are folded while the tree is built (see `foldLogical`), so this only
+ * remains when the whole filter is `FALSE`; a filter that is entirely `TRUE` is
+ * the match-everything `AndExpression([])`.
+ */
+export class BooleanExpression extends Expression {
+    /**
+     * The constant value
+     */
+    value;
+    /**
+     * @param value - the constant value
+     */
+    constructor(value) {
+        super(value ? "TRUE" : "FALSE");
+        this.value = value;
+    }
+    /**
+     * @override
+     */
+    eval(_target) {
+        return this.value;
+    }
+    /**
+     * @override
+     */
+    toString() {
+        return this.operator;
+    }
+}
+/**
+ * Build an AND / OR expression, folding `TRUE` / `FALSE` constants away
  *
+ * AND drops TRUE and is FALSE as soon as one child is FALSE; OR drops FALSE and is
+ * TRUE as soon as one child is TRUE. A constant only remains when every child was one.
+ * @param operator - the logical operator
+ * @param children - the visited child expressions
+ * @returns the folded expression
+ */
+function foldLogical(operator, children) {
+    // The constant that decides the whole expression: FALSE for AND, TRUE for OR
+    const decisive = operator === "OR";
+    const kept = [];
+    for (const child of children) {
+        if (child instanceof BooleanExpression) {
+            if (child.value === decisive) {
+                return child;
+            }
+            continue;
+        }
+        kept.push(child);
+    }
+    if (kept.length === 0) {
+        return new BooleanExpression(!decisive);
+    }
+    return operator === "AND" ? new AndExpression(kept) : new OrExpression(kept);
+}
+/**
+ * Turn a filter that is entirely `TRUE` into the match-everything expression
+ * @param filter - the top-level filter
+ * @returns the filter stores understand
+ */
+function normalizeFilter(filter) {
+    return filter instanceof BooleanExpression && filter.value ? new AndExpression([]) : filter;
+}
+/**
+ * Error listener turning lexer and parser errors into exceptions
+ *
+ * Without it, ANTLR logs the error and recovers: an unknown character was dropped,
+ * so `x = #1` was evaluated as `x = 1`.
+ *
+ * @param sql - the query, for the error message
+ * @returns the error listener
+ */
+function throwingErrorListener(sql) {
+    return {
+        syntaxError: (_recognizer, _offendingSymbol, _line, _charPositionInLine, msg, _e) => {
+            throw new SyntaxError(`${msg} (Query: ${sql})`);
+        }
+    };
+}
+/**
+ * Create a lexer and a parser for a query, both throwing on errors
+ * @param sql - the query string
+ * @returns the lexer and the parser
+ */
+function createParser(sql) {
+    const lexer = new WebdaQLLexer(CharStreams.fromString(sql || ""));
+    lexer.removeErrorListeners();
+    lexer.addErrorListener(throwingErrorListener(sql));
+    const parser = new WebdaQLParserParser(new CommonTokenStream(lexer));
+    parser.removeErrorListeners();
+    parser.addErrorListener(throwingErrorListener(sql));
+    return { lexer, parser };
+}
+/**
+ * Check a query against the WebdaQL grammar without evaluating it
+ *
+ * Unlike {@link QueryValidator}, unbound `?` / `:name` parameters are accepted, so a
+ * query can be checked before its parameters are bound.
+ *
+ * @param query - the query string
+ * @throws {SyntaxError} if the query does not follow the grammar
+ */
+export function validateSyntax(query) {
+    createParser(query).parser.webdaql();
+}
+/**
+ * Parses a WebdaQL query string and provides evaluation, merging, and serialization
+ *
+ * This is the main entry point for working with WebdaQL queries. It handles:
+ * - Parsing query strings via ANTLR into an expression AST
+ * - Evaluating objects against the parsed filter
+ * - Merging multiple queries together
+ * - Serializing back to a query string
+ *
+ * @example
+ * ```ts
+ * const validator = new QueryValidator("status = 'active' AND age > 18 LIMIT 50");
+ * validator.eval({ status: "active", age: 25 }); // true
+ * validator.getLimit(); // 50
+ * ```
  */
 export class QueryValidator {
+    sql;
+    lexer;
+    tree;
+    query;
+    builder;
+    /**
+     * Parse a WebdaQL query string
+     *
+     * @param sql - the query string to parse
+     * @param builder - expression builder to use (override for custom expression types)
+     * @throws {SyntaxError} if the query string is malformed
+     */
     constructor(sql, builder = new ExpressionBuilder()) {
         this.sql = sql;
-        this.lexer = new WebdaQLLexer(CharStreams.fromString(sql || ""));
-        const tokenStream = new CommonTokenStream(this.lexer);
-        const parser = new WebdaQLParserParser(tokenStream);
-        parser.removeErrorListeners();
-        parser.addErrorListener({
-            syntaxError: (_recognizer, _offendingSymbol, _line, _charPositionInLine, msg, _e) => {
-                throw new SyntaxError(`${msg} (Query: ${sql})`);
-            }
-        });
+        const { lexer, parser } = createParser(sql);
+        this.lexer = lexer;
         // Parse the input, where `compilationUnit` is whatever entry point you defined
         this.tree = parser.webdaql();
         this.builder = builder;
         this.query = this.builder.visit(this.tree);
     }
     /**
-     * Get offset
-     * @returns
+     * Get parsed OFFSET continuation token, or empty string if none
+     * @returns the offset token
      */
     getOffset() {
         return this.builder.getOffset() || "";
     }
+    /**
+     * Check whether the query has a non-empty filter condition
+     *
+     * An empty AND expression (no children) is considered to have no condition.
+     * @returns true if there is a filter condition
+     */
     hasCondition() {
         const filter = this.query.filter;
         const isAnd = filter instanceof AndExpression;
@@ -455,6 +794,12 @@ export class QueryValidator {
         }
         return true;
     }
+    /**
+     * Reconstruct the query string from the parsed AST
+     *
+     * Includes filter, ORDER BY, LIMIT, and OFFSET clauses.
+     * @returns the reconstructed query string
+     */
     toString() {
         let res = this.query.filter.toString();
         if (this.query.orderBy) {
@@ -468,8 +813,17 @@ export class QueryValidator {
         }
         return res.trim();
     }
+    /**
+     * Merge another query string into this query
+     *
+     * Filter expressions are combined using the specified logical operator.
+     * LIMIT, OFFSET, and ORDER BY from the merged query override existing values.
+     *
+     * @param query - query string to merge in
+     * @param type - logical operator to combine filters (`"AND"` or `"OR"`)
+     * @returns `this` for chaining
+     */
     merge(query, type = "AND") {
-        var _a;
         const adds = new QueryValidator(query);
         // Add additional conditions
         if (adds.hasCondition()) {
@@ -492,29 +846,29 @@ export class QueryValidator {
         // Add the order by if overriden
         if (adds.query.orderBy) {
             const fields = adds.query.orderBy.map(o => o.field);
-            (_a = this.query).orderBy ?? (_a.orderBy = []);
+            this.query.orderBy ??= [];
             // Remove the fields that are already in the query
             this.query.orderBy = [...adds.query.orderBy, ...this.query.orderBy.filter(o => !fields.includes(o.field))];
         }
         return this;
     }
     /**
-     * Get limit
-     * @returns
+     * Get parsed LIMIT value, defaulting to 1000
+     * @returns the limit value
      */
     getLimit() {
         return this.builder.getLimit() || 1000;
     }
     /**
-     * Get the expression by itself
-     * @returns
+     * Get the filter expression (without LIMIT / OFFSET / ORDER BY)
+     * @returns the filter expression
      */
     getExpression() {
         return this.query.filter;
     }
     /**
-     * Retrieve parsed query
-     * @returns
+     * Retrieve the full parsed query including filter, limit, offset, and orderBy
+     * @returns the full query object
      */
     getQuery() {
         return {
@@ -525,16 +879,16 @@ export class QueryValidator {
     }
     /**
      * Verify if a target fit the expression
-     * @param target
-     * @returns
+     * @param target - the object to evaluate
+     * @returns true if the target matches
      */
     eval(target) {
         return this.query.filter.eval(target);
     }
     /**
      * Display parse tree back as query
-     * @param tree
-     * @returns
+     * @param tree - the parse tree to display
+     * @returns the query string representation
      */
     displayTree(tree = this.tree) {
         let res = "";
@@ -554,20 +908,51 @@ export class QueryValidator {
     }
 }
 /**
- * For now reuse same parser
+ * A query validator that operates in assignment mode
+ *
+ * Instead of filtering objects, it assigns values to object properties.
+ * Only supports `=` (assignment) combined with `AND`. No comparisons, OR, or other operators.
+ *
+ * Protects against prototype pollution by ignoring `__proto__` attributes.
+ *
+ * @example
+ * ```ts
+ * const target: any = {};
+ * new SetterValidator('name = "John" AND age = 30').eval(target);
+ * // target = { name: "John", age: 30 }
+ * ```
+ *
+ * @throws {SyntaxError} if non-assignment operators or OR expressions are used
  */
 export class SetterValidator extends QueryValidator {
+    /**
+     * @param sql - assignment expression (e.g. `'field = "value" AND other = 10'`)
+     * @throws {SyntaxError} if the expression contains non-assignment operators
+     */
     constructor(sql) {
         super(sql);
         // Do one empty run to raise any issue with disallowed expression
         this.eval({});
     }
+    /**
+     * Apply the assignments to the target object
+     *
+     * @param target - object to assign values to (mutated in place)
+     * @returns always `true`
+     */
     eval(target) {
         if (this.query.filter) {
             this.assign(target, this.query.filter);
         }
         return true;
     }
+    /**
+     * Recursively walk the expression tree and apply assignments
+     *
+     * @param target - object to assign values to
+     * @param expression - must be an AndExpression or a `=` ComparisonExpression
+     * @throws {SyntaxError} if any non-assignment expression is encountered
+     */
     assign(target, expression) {
         if (expression instanceof AndExpression) {
             expression.children.forEach(c => this.assign(target, c));
@@ -580,15 +965,34 @@ export class SetterValidator extends QueryValidator {
         }
     }
 }
+/**
+ * A query validator that supports partial object matching
+ *
+ * In partial mode, comparisons against `undefined` attributes evaluate to `true`
+ * (the missing field is ignored). This is useful for PATCH operations where only
+ * a subset of fields is provided.
+ *
+ * @example
+ * ```ts
+ * const v = new PartialValidator("name = 'John' AND age > 18");
+ * v.eval({ name: "John" });        // true (age is undefined, skipped)
+ * v.wasPartialMatch();             // true
+ * v.eval({ name: "John" }, false); // false (strict mode, age required)
+ * ```
+ */
 export class PartialValidator extends QueryValidator {
+    /**
+     * @param query - WebdaQL query string
+     * @param builder - partial expression builder (override for customization)
+     */
     constructor(query, builder = new PartialExpressionBuilder()) {
         super(query, builder);
     }
     /**
      * Eval the query
-     * @param target
-     * @param partial
-     * @returns
+     * @param target - the object to evaluate
+     * @param partial - whether to use partial matching
+     * @returns true if the target matches
      */
     eval(target, partial = true) {
         this.builder.setPartial(partial);
@@ -597,13 +1001,28 @@ export class PartialValidator extends QueryValidator {
     }
     /**
      * Return if the result ignored some fields
-     * @returns
+     * @returns true if some fields were skipped
      */
     wasPartialMatch() {
         return this.builder.partialMatch;
     }
 }
+/**
+ * A comparison expression that treats `undefined` attributes as a match in partial mode
+ *
+ * When the builder is in partial mode and the target attribute is `undefined`,
+ * evaluation returns `true` and flags the result as a partial match.
+ *
+ * @typeParam T - the specific comparison operator type
+ */
 export class PartialComparisonExpression extends ComparisonExpression {
+    builder;
+    /**
+     * @param builder - the partial expression builder (used to read partial mode flag)
+     * @param op - comparison operator
+     * @param attribute - dot-notation attribute path
+     * @param value - value to compare against
+     */
     constructor(builder, op, attribute, value) {
         super(op, attribute, value);
         this.builder = builder;
@@ -612,8 +1031,8 @@ export class PartialComparisonExpression extends ComparisonExpression {
      * Override the eval to check if the attribute is present
      * if not and we are in partial mode, return true
      *
-     * @param target
-     * @returns
+     * @param target - the object to evaluate
+     * @returns true if the target matches
      */
     eval(target) {
         if (this.builder.partial) {
@@ -626,17 +1045,39 @@ export class PartialComparisonExpression extends ComparisonExpression {
         return super.eval(target);
     }
 }
+/**
+ * Expression builder that creates {@link PartialComparisonExpression} nodes
+ * instead of regular {@link ComparisonExpression} nodes
+ *
+ * Used by {@link PartialValidator} to support partial object matching.
+ */
 export class PartialExpressionBuilder extends ExpressionBuilder {
+    /**
+     * Whether partial mode is active (undefined attributes treated as matching)
+     */
+    partial;
+    /**
+     * Set to `true` during evaluation if any attribute was undefined and skipped
+     */
+    partialMatch;
+    /**
+     * Enable or disable partial evaluation mode
+     * @param partial - whether to enable partial mode
+     */
     setPartial(partial) {
         this.partial = partial;
     }
+    /**
+     * Set the partial match flag (reset before each evaluation)
+     * @param partial - the partial match flag value
+     */
     setPartialMatch(partial) {
         this.partialMatch = partial;
     }
     /**
-     * a LIKE "%A?"
-     * @param ctx
-     * @returns
+     * Visit a LIKE expression, returning a PartialComparisonExpression
+     * @param ctx - the LIKE expression context
+     * @returns the partial comparison expression
      */
     visitLikeExpression(ctx) {
         const [left, _, right] = ctx.children;
@@ -644,7 +1085,9 @@ export class PartialExpressionBuilder extends ExpressionBuilder {
         return new PartialComparisonExpression(this, "LIKE", left.text, value);
     }
     /**
-     * Implement the BinaryComparison with all methods managed
+     * Visit a binary comparison, returning a PartialComparisonExpression
+     * @param ctx - the binary comparison context
+     * @returns the partial comparison expression
      */
     visitBinaryComparisonExpression(ctx) {
         const [left, op, right] = ctx.children;
@@ -652,7 +1095,9 @@ export class PartialExpressionBuilder extends ExpressionBuilder {
         return new PartialComparisonExpression(this, op.text, left.text, this.visit(right));
     }
     /**
-     * Map the a IN ['b','c']
+     * Visit an IN expression, returning a PartialComparisonExpression
+     * @param ctx - the IN expression context
+     * @returns the partial comparison expression
      */
     visitInExpression(ctx) {
         const [left, _, right] = ctx.children;
@@ -660,20 +1105,46 @@ export class PartialExpressionBuilder extends ExpressionBuilder {
         return new PartialComparisonExpression(this, "IN", left.text, value);
     }
     /**
-     * Map the a CONTAINS 'b'
+     * Visit a CONTAINS expression, returning a PartialComparisonExpression
+     * @param ctx - the CONTAINS expression context
+     * @returns the partial comparison expression
      */
     visitContainsExpression(ctx) {
         const [left, _, right] = ctx.children;
         const value = this.visit(right);
         return new PartialComparisonExpression(this, "CONTAINS", left.text, value);
     }
+    /**
+     * Visit an IS NULL expression, returning a PartialComparisonExpression
+     * @param ctx - the IS NULL expression context
+     * @returns the partial comparison expression
+     */
+    visitIsNullExpression(ctx) {
+        return new PartialComparisonExpression(this, "IS NULL", ctx.getChild(0).text, null);
+    }
+    /**
+     * Visit an IS NOT NULL expression, returning a PartialComparisonExpression
+     * @param ctx - the IS NOT NULL expression context
+     * @returns the partial comparison expression
+     */
+    visitIsNotNullExpression(ctx) {
+        return new PartialComparisonExpression(this, "IS NOT NULL", ctx.getChild(0).text, null);
+    }
 }
 /**
  * Remove artifact from sanitize-html inside query
- * @param query
- * @returns
+ * @param query - the query string to unsanitize
+ * @returns the cleaned query string
  */
 export function unsanitize(query) {
     return query.replace(/&lt;/g, "<").replace(/&gt;/g, ">");
 }
+/**
+ * Parse a query string into a Query object
+ * @param query - the query string to parse
+ * @returns the parsed Query object
+ */
+export function parse(query) {
+    return new QueryValidator(query).getQuery();
+}
 //# sourceMappingURL=query.js.map