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

package/lib/query.d.ts

@@ -1,76 +1,123 @@
 import { AbstractParseTreeVisitor, ParseTree } from "antlr4ts/tree/index.js";
 import { WebdaQLLexer } from "./WebdaQLLexer.js";
-import { AndLogicExpressionContext, BinaryComparisonExpressionContext, BooleanLiteralContext, ContainsExpressionContext, InExpressionContext, IntegerLiteralContext, LikeExpressionContext, LimitExpressionContext, OffsetExpressionContext, OrLogicExpressionContext, OrderExpressionContext, OrderFieldExpressionContext, SetExpressionContext, StringLiteralContext, WebdaqlContext } from "./WebdaQLParserParser.js";
+import { AndLogicExpressionContext, AtomExpressionContext, BinaryComparisonExpressionContext, BooleanLiteralContext, ContainsExpressionContext, InExpressionContext, IntegerLiteralContext, IsNotNullExpressionContext, IsNullExpressionContext, LikeExpressionContext, LimitExpressionContext, NumberLiteralContext, OffsetExpressionContext, OrLogicExpressionContext, OrderExpressionContext, OrderFieldExpressionContext, ParameterContext, SetExpressionContext, StringLiteralContext, WebdaqlContext } from "./WebdaQLParserParser.js";
 import { WebdaQLParserVisitor } from "./WebdaQLParserVisitor.js";
+/**
+ * Primitive value types supported by WebdaQL expressions
+ */
 type value = boolean | string | number;
 /**
- * Meta Query Language
+ * 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 declare function unescapeStringLiteral(literal: string): string;
+/**
+ * Represents a single ORDER BY clause field with its sort direction
  */
 export interface OrderBy {
+    /** Field name (supports dot-notation for nested attributes) */
     field: string;
+    /** Sort direction */
     direction: "ASC" | "DESC";
 }
+/**
+ * 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 declare function PrependCondition(query?: string, condition?: string): string;
 /**
- * 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 declare class ExpressionBuilder extends AbstractParseTreeVisitor<Query> implements WebdaQLParserVisitor<any> {
     /**
-     * Contain the parsed limit
+     * Parsed LIMIT value, if present
      */
     limit: number;
     /**
-     * Contain the parsed offset
+     * Parsed OFFSET continuation token, if present
      */
     offset: string;
+    /**
+     * Parsed ORDER BY clauses, if present
+     */
     orderBy: OrderBy[];
     /**
-     * Default result for the override
-     * @returns
+     * Default result when no expression is matched (empty AND, always true)
+     * @returns an empty AND query
      */
     protected defaultResult(): Query;
     /**
-     * Get offset
-     * @returns
+     * Get parsed OFFSET continuation token
+     * @returns the offset token
      */
     getOffset(): string;
     /**
-     * Get limit
-     * @returns
+     * Get parsed LIMIT value
+     * @returns the limit value
      */
     getLimit(): number;
     /**
-     * Read the limit
-     * @param ctx
+     * Visit a LIMIT clause and store the integer value
+     * @param ctx - the limit expression context
      */
     visitLimitExpression(ctx: LimitExpressionContext): void;
     /**
-     * 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: OffsetExpressionContext): void;
     /**
      * Visit a order field expression
+     * @param ctx - the order field expression context
+     * @returns the parsed OrderBy
      */
     visitOrderFieldExpression(ctx: OrderFieldExpressionContext): OrderBy;
     /**
      * Read the order by values
+     * @param ctx - the order expression context
      */
     visitOrderExpression(ctx: OrderExpressionContext): void;
     /**
-     * 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: WebdaqlContext): Query;
     /**
-     * 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: AndLogicExpressionContext | OrLogicExpressionContext): any[];
     /**
@@ -78,49 +125,98 @@ export declare class ExpressionBuilder extends AbstractParseTreeVisitor<Query> i
      *
      * 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: AndLogicExpressionContext): AndExpression;
+    visitAndLogicExpression(ctx: AndLogicExpressionContext): Expression;
     /**
      * Implement the BinaryComparison with all methods managed
+     * @param ctx - the binary comparison context
+     * @returns the comparison expression
      */
     visitBinaryComparisonExpression(ctx: BinaryComparisonExpressionContext): ComparisonExpression<ComparisonOperator>;
     /**
      * Visit each value of the [..., ..., ...] set
+     * @param ctx - the set expression context
+     * @returns the array of values
      */
     visitSetExpression(ctx: SetExpressionContext): value[];
     /**
-     * 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: LikeExpressionContext): ComparisonExpression<"LIKE">;
     /**
      * Map the a IN ['b','c']
+     * @param ctx - the IN expression context
+     * @returns the comparison expression
      */
     visitInExpression(ctx: InExpressionContext): ComparisonExpression<"IN">;
     /**
      * Map the a CONTAINS 'b'
+     * @param ctx - the CONTAINS expression context
+     * @returns the comparison expression
      */
     visitContainsExpression(ctx: ContainsExpressionContext): ComparisonExpression<"CONTAINS">;
+    /**
+     * Map the a IS NULL
+     * @param ctx - the IS NULL expression context
+     * @returns the comparison expression
+     */
+    visitIsNullExpression(ctx: IsNullExpressionContext): ComparisonExpression<"IS NULL">;
+    /**
+     * Map the a IS NOT NULL
+     * @param ctx - the IS NOT NULL expression context
+     * @returns the comparison expression
+     */
+    visitIsNotNullExpression(ctx: IsNotNullExpressionContext): ComparisonExpression<"IS NOT 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: OrLogicExpressionContext): OrExpression;
+    visitOrLogicExpression(ctx: OrLogicExpressionContext): Expression;
     /**
-     * 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: AtomExpressionContext): Expression;
+    /**
+     * Read a string literal, stripping the surrounding single or double quotes
+     * @param ctx - the string literal context
+     * @returns the unquoted string value
      */
     visitStringLiteral(ctx: StringLiteralContext): string;
     /**
      * Read the boolean literal
+     * @param ctx - the boolean literal context
+     * @returns the boolean value
      */
     visitBooleanLiteral(ctx: BooleanLiteralContext): boolean;
     /**
      * Read the number literal
+     * @param ctx - the integer literal context
+     * @returns the parsed integer value
      */
     visitIntegerLiteral(ctx: IntegerLiteralContext): number;
+    /**
+     * Read a signed or decimal number literal
+     * @param ctx - the number literal context
+     * @returns the parsed number
+     */
+    visitNumberLiteral(ctx: NumberLiteralContext): number;
+    /**
+     * 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: ParameterContext): never;
 }
 /**
  * Represent a full Query
@@ -152,6 +248,9 @@ export interface Query {
  */
 export declare abstract class Expression<T = string> {
     operator: T;
+    /** Create a new Expression.
+     * @param operator - the expression operator
+     */
     constructor(operator: T);
     /**
      * Evaluate the expression for the target object
@@ -164,9 +263,28 @@ export declare abstract class Expression<T = string> {
      */
     abstract toString(depth?: number): string;
 }
-export type ComparisonOperator = "=" | "<=" | ">=" | "<" | ">" | "!=" | "LIKE" | "IN" | "CONTAINS";
 /**
- * Comparison expression
+ * All supported comparison operators
+ *
+ * - `=` / `!=` use loose equality (`==` / `!=`)
+ * - `<`, `<=`, `>`, `>=` use standard JS comparison
+ * - `LIKE` uses SQL-style pattern matching (`%` = any chars, `_` = single char)
+ * - `IN` checks membership in a set (`field IN ['a', 'b']`)
+ * - `CONTAINS` checks if an array field contains a value (`field CONTAINS 'a'`)
+ * - `IS NULL` matches a missing, `undefined` or `null` field (`field IS NULL`)
+ * - `IS NOT NULL` matches any other value (`field IS NOT NULL`)
+ */
+export type ComparisonOperator = "=" | "<=" | ">=" | "<" | ">" | "!=" | "LIKE" | "IN" | "CONTAINS" | "IS NULL" | "IS NOT NULL";
+/**
+ * Comparison operators that take no value
+ */
+export declare const UNARY_COMPARISON_OPERATORS: readonly ComparisonOperator[];
+/**
+ * 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 declare class ComparisonExpression<T extends ComparisonOperator = ComparisonOperator> extends Expression<T> {
     /**
@@ -178,25 +296,36 @@ export declare class ComparisonExpression<T extends ComparisonOperator = Compari
      */
     attribute: string[];
     /**
-     *
-     * @param operator of the expression
-     * @param attribute of the object to read
-     * @param value
+     * @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: T, attribute: string, value: value | any[]);
+    /**
+     * 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: string): RegExp;
     /**
-     * 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: any, attribute: string[]): any;
     /**
      * 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: any): void;
     /**
@@ -204,15 +333,21 @@ export declare class ComparisonExpression<T extends ComparisonOperator = Compari
      */
     eval(target: any): boolean;
     /**
-     * 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: value | value[]): string;
     /**
      * Allow subclass to create different display
+     * @returns the attribute string
      */
     toStringAttribute(): string;
     /**
      * Allow subclass to create different display
+     * @returns the operator string
      */
     toStringOperator(): T;
     /**
@@ -221,19 +356,18 @@ export declare class ComparisonExpression<T extends ComparisonOperator = Compari
     toString(): string;
 }
 /**
- * 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 declare abstract class LogicalExpression<T> extends Expression<T> {
     /**
-     * Contains the members of the logical expression
+     * Child expressions combined by this logical operator
      */
     children: Expression[];
     /**
-     *
-     * @param operator
-     * @param children
+     * @param operator - logical operator
+     * @param children - child expressions to combine
      */
     constructor(operator: T, children: Expression[]);
     /**
@@ -242,7 +376,10 @@ export declare abstract class LogicalExpression<T> extends Expression<T> {
     toString(depth?: number): string;
 }
 /**
- * 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 declare class AndExpression extends LogicalExpression<"AND"> {
     /**
@@ -255,7 +392,10 @@ export declare class AndExpression extends LogicalExpression<"AND"> {
     eval(target: any): boolean;
 }
 /**
- * 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 declare class OrExpression extends LogicalExpression<"OR"> {
     /**
@@ -268,7 +408,55 @@ export declare class OrExpression extends LogicalExpression<"OR"> {
     eval(target: any): boolean;
 }
 /**
+ * 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 declare class BooleanExpression extends Expression<"TRUE" | "FALSE"> {
+    /**
+     * The constant value
+     */
+    value: boolean;
+    /**
+     * @param value - the constant value
+     */
+    constructor(value: boolean);
+    /**
+     * @override
+     */
+    eval(_target: any): boolean;
+    /**
+     * @override
+     */
+    toString(): string;
+}
+/**
+ * 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 declare function validateSyntax(query: string): void;
+/**
+ * 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 declare class QueryValidator {
     protected sql: string;
@@ -276,114 +464,245 @@ export declare class QueryValidator {
     protected tree: WebdaqlContext;
     protected query: Query;
     protected builder: ExpressionBuilder;
+    /**
+     * 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: string, builder?: ExpressionBuilder);
     /**
-     * Get offset
-     * @returns
+     * Get parsed OFFSET continuation token, or empty string if none
+     * @returns the offset token
      */
     getOffset(): string;
+    /**
+     * 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(): boolean;
+    /**
+     * Reconstruct the query string from the parsed AST
+     *
+     * Includes filter, ORDER BY, LIMIT, and OFFSET clauses.
+     * @returns the reconstructed query string
+     */
     toString(): string;
+    /**
+     * 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: string, type?: "OR" | "AND"): this;
     /**
-     * Get limit
-     * @returns
+     * Get parsed LIMIT value, defaulting to 1000
+     * @returns the limit value
      */
     getLimit(): number;
     /**
-     * Get the expression by itself
-     * @returns
+     * Get the filter expression (without LIMIT / OFFSET / ORDER BY)
+     * @returns the filter expression
      */
     getExpression(): Expression;
     /**
-     * Retrieve parsed query
-     * @returns
+     * Retrieve the full parsed query including filter, limit, offset, and orderBy
+     * @returns the full query object
      */
     getQuery(): Query;
     /**
      * Verify if a target fit the expression
-     * @param target
-     * @returns
+     * @param target - the object to evaluate
+     * @returns true if the target matches
      */
     eval(target: any): boolean;
     /**
      * Display parse tree back as query
-     * @param tree
-     * @returns
+     * @param tree - the parse tree to display
+     * @returns the query string representation
      */
     displayTree(tree?: ParseTree): string;
 }
 /**
- * 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 declare 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: string);
+    /**
+     * Apply the assignments to the target object
+     *
+     * @param target - object to assign values to (mutated in place)
+     * @returns always `true`
+     */
     eval(target: any): boolean;
+    /**
+     * 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: any, expression: Expression): void;
 }
+/**
+ * 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 declare class PartialValidator extends QueryValidator {
     builder: PartialExpressionBuilder;
+    /**
+     * @param query - WebdaQL query string
+     * @param builder - partial expression builder (override for customization)
+     */
     constructor(query: string, builder?: PartialExpressionBuilder);
     /**
      * 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: any, partial?: boolean): boolean;
     /**
      * Return if the result ignored some fields
-     * @returns
+     * @returns true if some fields were skipped
      */
     wasPartialMatch(): boolean;
 }
+/**
+ * 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 declare class PartialComparisonExpression<T extends ComparisonOperator = ComparisonOperator> extends ComparisonExpression<T> {
     protected builder: PartialExpressionBuilder;
+    /**
+     * @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: PartialExpressionBuilder, op: T, attribute: string, value: any);
     /**
      * 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: any): boolean;
 }
+/**
+ * Expression builder that creates {@link PartialComparisonExpression} nodes
+ * instead of regular {@link ComparisonExpression} nodes
+ *
+ * Used by {@link PartialValidator} to support partial object matching.
+ */
 export declare class PartialExpressionBuilder extends ExpressionBuilder {
     /**
-     * Enforce the partial mode
+     * Whether partial mode is active (undefined attributes treated as matching)
      */
     partial: boolean;
     /**
-     * If eval was called in partial mode
+     * Set to `true` during evaluation if any attribute was undefined and skipped
      */
     partialMatch: boolean;
+    /**
+     * Enable or disable partial evaluation mode
+     * @param partial - whether to enable partial mode
+     */
     setPartial(partial: boolean): void;
+    /**
+     * Set the partial match flag (reset before each evaluation)
+     * @param partial - the partial match flag value
+     */
     setPartialMatch(partial: boolean): void;
     /**
-     * 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: any): PartialComparisonExpression<"LIKE">;
     /**
-     * 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: any): PartialComparisonExpression<any>;
     /**
-     * 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: any): PartialComparisonExpression<"IN">;
     /**
-     * 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: any): PartialComparisonExpression<"CONTAINS">;
+    /**
+     * Visit an IS NULL expression, returning a PartialComparisonExpression
+     * @param ctx - the IS NULL expression context
+     * @returns the partial comparison expression
+     */
+    visitIsNullExpression(ctx: any): PartialComparisonExpression<"IS 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: any): PartialComparisonExpression<"IS NOT NULL">;
 }
 /**
  * Remove artifact from sanitize-html inside query
- * @param query
- * @returns
+ * @param query - the query string to unsanitize
+ * @returns the cleaned query string
  */
 export declare function unsanitize(query: string): string;
+/**
+ * Parse a query string into a Query object
+ * @param query - the query string to parse
+ * @returns the parsed Query object
+ */
+export declare function parse(query: string): Query;
 export {};
 //# sourceMappingURL=query.d.ts.map