@libdbm/libcel-ts 1.0.2-rc.0

package/dist/index.d.ts

@@ -0,0 +1,740 @@
+/**
+ * Converts the given value to a boolean using common truthiness rules.
+ *
+ * Numbers are true if non-zero. Strings are true if non-empty.
+ * Collections/maps are true if non-empty. Null is false.
+ *
+ * @param value The value to interpret
+ * @returns The boolean interpretation
+ */
+export declare function asBool(value: any): boolean;
+
+/**
+ * Converts the given value to a double (number).
+ *
+ * Accepted inputs: number, string parsable as number
+ *
+ * @param value The value to convert
+ * @returns The converted number value
+ * @throws Error if the value cannot be converted
+ */
+declare function asDouble(value: any): number;
+
+/**
+ * Converts the given value to a signed integer (number).
+ *
+ * Accepted inputs: number, string (parsed as integer), boolean (true=1, false=0)
+ *
+ * @param value The value to convert
+ * @returns The converted integer value
+ * @throws Error if the value cannot be converted
+ */
+declare function asInt(value: any): number;
+
+/**
+ * Converts the given value to its string representation.
+ *
+ * Returns the literal string "null" for null/undefined values.
+ *
+ * @param value The value to stringify
+ * @returns The string representation
+ */
+declare function asString(value: any): string;
+
+/**
+ * Converts the given value to an unsigned integer.
+ *
+ * Negative inputs are not allowed and will result in an exception.
+ *
+ * @param value The value to convert
+ * @returns The non-negative integer value
+ * @throws Error if the value is negative or cannot be converted
+ */
+declare function asUInt(value: any): number;
+
+/**
+ * Binary operation expression (+, -, *, /, etc.).
+ */
+export declare class Binary implements Expression {
+    readonly op: BinaryOp;
+    readonly left: Expression;
+    readonly right: Expression;
+    constructor(op: BinaryOp, left: Expression, right: Expression);
+    accept<T>(visitor: Visitor<T>): T;
+}
+
+/**
+ * Binary operators in CEL expressions.
+ */
+export declare enum BinaryOp {
+    /** Addition (+) or string/list concatenation */
+    ADD = "ADD",
+    /** Subtraction (-) */
+    SUBTRACT = "SUBTRACT",
+    /** Multiplication (*) or string/list repetition */
+    MULTIPLY = "MULTIPLY",
+    /** Division (/) */
+    DIVIDE = "DIVIDE",
+    /** Modulo (%) */
+    MODULO = "MODULO",
+    /** Equality (==) */
+    EQUAL = "EQUAL",
+    /** Inequality (!=) */
+    NOT_EQUAL = "NOT_EQUAL",
+    /** Less than (<) */
+    LESS = "LESS",
+    /** Less than or equal (<=) */
+    LESS_EQUAL = "LESS_EQUAL",
+    /** Greater than (>) */
+    GREATER = "GREATER",
+    /** Greater than or equal (>=) */
+    GREATER_EQUAL = "GREATER_EQUAL",
+    /** Membership test (in) */
+    IN = "IN",
+    /** Logical AND (&&) */
+    LOGICAL_AND = "LOGICAL_AND",
+    /** Logical OR (||) */
+    LOGICAL_OR = "LOGICAL_OR"
+}
+
+/**
+ * Function or method call expression.
+ */
+export declare class Call implements Expression {
+    readonly target: Expression | null;
+    readonly functionName: string;
+    readonly args: Expression[];
+    readonly isMacro: boolean;
+    constructor(target: Expression | null, functionName: string, args: Expression[], isMacro?: boolean);
+    accept<T>(visitor: Visitor<T>): T;
+}
+
+/**
+ * The main entry point for evaluating CEL expressions.
+ *
+ * The CEL class provides methods to compile and evaluate CEL expressions.
+ * It supports all standard CEL operators, functions, and macros.
+ *
+ * @example
+ * ```typescript
+ * const cel = new CEL();
+ * const result = cel.eval('x * 2 + y', { x: 10, y: 5 });
+ * console.log(result); // 25
+ * ```
+ */
+export declare class CEL {
+    private readonly functions;
+    /**
+     * Creates a new CEL evaluator with the standard function library.
+     */
+    constructor();
+    /**
+     * Creates a new CEL evaluator.
+     *
+     * @param functions Optional custom function library. If not provided, the standard
+     *                  CEL function library will be used.
+     */
+    constructor(functions?: Functions | null);
+    /**
+     * Compiles a CEL expression using the provided function library.
+     *
+     * This static convenience method avoids the need to instantiate CEL when
+     * callers just need to compile once.
+     *
+     * @param expression The CEL expression to compile
+     * @param functions The function library to use when compiling the program
+     * @returns A compiled Program using the provided functions
+     * @throws ParseError if the expression is invalid
+     *
+     * @example
+     * ```typescript
+     * const program = CEL.compile('x + y', new StandardFunctions());
+     * ```
+     */
+    static compile(expression: string, functions: Functions): Program;
+    /**
+     * Evaluates a CEL expression with the given variables using the provided function library.
+     *
+     * This static convenience method avoids the need to instantiate CEL when callers
+     * just need to evaluate an expression once.
+     *
+     * @param expression The CEL expression to evaluate
+     * @param functions The function library to use when evaluating the expression
+     * @param variables A map of variable names to their values
+     * @returns The result of evaluating the expression
+     * @throws ParseError if the expression is invalid
+     * @throws EvaluationError if an error occurs during evaluation
+     *
+     * @example
+     * ```typescript
+     * const result = CEL.eval('x * 2', new StandardFunctions(), { x: 5 });
+     * ```
+     */
+    static eval(expression: string, functions: Functions, variables: Record<string, any>): any;
+    /**
+     * Compiles a CEL expression into a reusable program.
+     *
+     * This method parses the expression and returns a Program that can be evaluated
+     * multiple times with different variables. This is more efficient than calling
+     * eval() repeatedly with the same expression.
+     *
+     * @param expression The CEL expression to compile
+     * @returns A compiled program
+     * @throws ParseError if the expression is invalid
+     *
+     * @example
+     * ```typescript
+     * const program = cel.compile('price * quantity');
+     * const result1 = program.evaluate({ price: 10, quantity: 5 });
+     * const result2 = program.evaluate({ price: 20, quantity: 3 });
+     * ```
+     */
+    compile(expression: string): Program;
+    /**
+     * Evaluates a CEL expression with the given variables.
+     *
+     * This is a convenience method that compiles and evaluates the expression in one step.
+     * For better performance when evaluating the same expression multiple times, use
+     * compile() to create a reusable Program.
+     *
+     * @param expression The CEL expression to evaluate
+     * @param variables A map of variable names to their values
+     * @returns The result of evaluating the expression
+     * @throws ParseError if the expression is invalid
+     * @throws EvaluationError if an error occurs during evaluation
+     *
+     * @example
+     * ```typescript
+     * const result = cel.eval('user.age >= 18', {
+     *   user: { name: 'Alice', age: 25 }
+     * });
+     * ```
+     */
+    eval(expression: string, variables?: Record<string, any>): any;
+}
+
+/**
+ * Compares two values using a common set of rules.
+ *
+ * Supported comparisons: numbers (by numeric value), strings (lexicographically),
+ * booleans, arrays (lexicographically).
+ *
+ * @param a The first value
+ * @param b The second value
+ * @returns A negative number, zero, or a positive number as a is less than, equal to, or greater than b
+ * @throws Error if the values cannot be compared
+ */
+declare function compare(a: any, b: any): number;
+
+/**
+ * Comprehension expression for advanced iteration constructs.
+ */
+export declare class Comprehension implements Expression {
+    readonly variable: string;
+    readonly range: Expression;
+    readonly accumulator: string;
+    readonly initializer: Expression;
+    readonly condition: Expression;
+    readonly step: Expression;
+    readonly result: Expression;
+    constructor(variable: string, range: Expression, accumulator: string, initializer: Expression, condition: Expression, step: Expression, result: Expression);
+    accept<T>(visitor: Visitor<T>): T;
+}
+
+/**
+ * Conditional (ternary) expression (condition ? then : otherwise).
+ */
+export declare class Conditional implements Expression {
+    readonly condition: Expression;
+    readonly thenExpr: Expression;
+    readonly otherwiseExpr: Expression;
+    constructor(condition: Expression, thenExpr: Expression, otherwiseExpr: Expression);
+    accept<T>(visitor: Visitor<T>): T;
+}
+
+/**
+ * Helper for array contains with deep equality.
+ *
+ * @param array The array to search
+ * @param value The value to find
+ * @returns true if the array contains the value (using deep equality)
+ */
+declare function containsInArray(array: any[], value: any): boolean;
+
+/**
+ * Deep equality check for CEL values.
+ *
+ * @param left First value
+ * @param right Second value
+ * @returns true if values are deeply equal
+ */
+declare function deepEquals(left: any, right: any): boolean;
+
+/**
+ * Exception thrown during CEL expression evaluation.
+ */
+export declare class EvaluationError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * Base interface for all CEL expression nodes in the Abstract Syntax Tree.
+ * Uses the Visitor pattern to enable different operations on expressions.
+ */
+export declare interface Expression {
+    /**
+     * Accepts a visitor to perform operations on this expression node.
+     *
+     * @template T The return type of the visitor's visit operations
+     * @param visitor The visitor that will operate on this expression node
+     * @returns The result of the visitor's visit operation
+     */
+    accept<T>(visitor: Visitor<T>): T;
+}
+
+/**
+ * Field initializer in a struct literal.
+ */
+export declare class FieldInitializer {
+    readonly field: string;
+    readonly value: Expression;
+    constructor(field: string, value: Expression);
+}
+
+/**
+ * Interface for providing functions to CEL expressions.
+ *
+ * Implement this interface to provide custom functions that can be called
+ * from CEL expressions. The StandardFunctions class provides all standard
+ * CEL functions and can be extended for custom functionality.
+ *
+ * @example
+ * ```typescript
+ * class MyFunctions extends StandardFunctions {
+ *   callFunction(name: string, args: any[]): any {
+ *     if (name === 'customFunc') {
+ *       return myCustomImplementation(args);
+ *     }
+ *     return super.callFunction(name, args);
+ *   }
+ * }
+ * ```
+ */
+export declare interface Functions {
+    /**
+     * Calls a global function by name.
+     *
+     * @param name The name of the function to call
+     * @param args The arguments to pass to the function
+     * @returns The result of the function call
+     * @throws Error if the function is not found or if the arguments are invalid
+     */
+    callFunction(name: string, args: any[]): any;
+    /**
+     * Calls a method on a target object.
+     *
+     * @param target The object to call the method on
+     * @param method The name of the method to call
+     * @param args The arguments to pass to the method
+     * @returns The result of the method call
+     * @throws Error if the method is not found or if the arguments are invalid
+     */
+    callMethod(target: any, method: string, args: any[]): any;
+}
+
+/**
+ * Checks whether a map contains the given field name.
+ *
+ * @param target The map-like object to check (must be an object to return true/false)
+ * @param field The field/key to look for (must be a string)
+ * @returns true if target is a Map/object and contains the given key; false otherwise
+ */
+declare function has(target: any, field: any): boolean;
+
+/**
+ * Identifier expression (variable reference).
+ */
+export declare class Identifier implements Expression {
+    readonly name: string;
+    constructor(name: string);
+    accept<T>(visitor: Visitor<T>): T;
+}
+
+/**
+ * Index expression for array/map access (operand[index]).
+ */
+export declare class Index implements Expression {
+    readonly operand: Expression;
+    readonly index: Expression;
+    constructor(operand: Expression, index: Expression);
+    accept<T>(visitor: Visitor<T>): T;
+}
+
+/**
+ * Interpreter for evaluating CEL expressions.
+ *
+ * Implements the Visitor pattern to traverse and evaluate the AST produced by the parser.
+ * Supports all CEL operations including macros, type conversions, and complex expressions.
+ */
+export declare class Interpreter implements Visitor<any> {
+    private readonly variables;
+    private readonly functions;
+    /**
+     * Constructs an interpreter with the specified variables and functions.
+     *
+     * @param variables A map of variable names to their values. If null, an empty object is used.
+     * @param functions An instance of Functions to handle function calls. If null, StandardFunctions is used.
+     */
+    constructor(variables?: Record<string, any> | null, functions?: Functions | null);
+    /**
+     * Evaluates a CEL expression and returns its result.
+     *
+     * @param expr The expression to evaluate
+     * @returns The result of the evaluation
+     * @throws EvaluationError if evaluation fails
+     */
+    evaluate(expr: Expression): any;
+    visitLiteral(expr: Literal): any;
+    visitIdentifier(expr: Identifier): any;
+    visitSelect(expr: Select): any;
+    visitCall(expr: Call): any;
+    private evaluateMacro;
+    visitList(expr: ListExpression): any;
+    visitMap(expr: MapExpression): any;
+    visitStruct(expr: Struct): any;
+    visitComprehension(expr: Comprehension): any;
+    visitUnary(expr: Unary): any;
+    visitBinary(expr: Binary): any;
+    visitConditional(expr: Conditional): any;
+    visitIndex(expr: Index): any;
+}
+
+/**
+ * List literal expression ([1, 2, 3]).
+ */
+export declare class ListExpression implements Expression {
+    readonly elements: Expression[];
+    constructor(elements: Expression[]);
+    accept<T>(visitor: Visitor<T>): T;
+}
+
+/**
+ * Literal value expression (null, boolean, number, string, bytes).
+ */
+export declare class Literal implements Expression {
+    readonly value: any;
+    readonly literalType: LiteralType;
+    constructor(value: any, literalType: LiteralType);
+    accept<T>(visitor: Visitor<T>): T;
+}
+
+/**
+ * Types of literal values in CEL.
+ */
+export declare enum LiteralType {
+    NULL_VALUE = "NULL_VALUE",
+    BOOL = "BOOL",
+    INT = "INT",
+    UINT = "UINT",
+    DOUBLE = "DOUBLE",
+    STRING = "STRING",
+    BYTES = "BYTES"
+}
+
+/**
+ * Map entry (key-value pair in a map literal).
+ */
+export declare class MapEntry {
+    readonly key: Expression;
+    readonly value: Expression;
+    constructor(key: Expression, value: Expression);
+}
+
+/**
+ * Map literal expression ({key: value}).
+ */
+export declare class MapExpression implements Expression {
+    readonly entries: MapEntry[];
+    constructor(entries: MapEntry[]);
+    accept<T>(visitor: Visitor<T>): T;
+}
+
+/**
+ * Tests whether the given regular expression matches any part of the text.
+ *
+ * Uses RegExp pattern matching with find semantics.
+ *
+ * @param text The input text
+ * @param pattern The regular expression pattern
+ * @returns true if the pattern matches anywhere in the text; false otherwise
+ * @throws Error if the pattern is invalid
+ */
+declare function matches(text: string, pattern: string): boolean;
+
+/**
+ * Returns the maximum element from a non-empty array of values.
+ *
+ * Comparison rules follow compare(). All elements must be mutually comparable.
+ *
+ * @param values A non-empty array of values
+ * @returns The maximum value in the array
+ * @throws Error if the array is empty or values are not comparable
+ */
+declare function max(values: any[]): any;
+
+/**
+ * Returns the minimum element from a non-empty array of values.
+ *
+ * Comparison rules follow compare(). All elements must be mutually comparable.
+ *
+ * @param values A non-empty array of values
+ * @returns The minimum value in the array
+ * @throws Error if the array is empty or values are not comparable
+ */
+declare function min(values: any[]): any;
+
+/**
+ * ParseError is thrown when the lexer or parser encounters invalid syntax.
+ */
+export declare class ParseError extends Error {
+    readonly line: number;
+    readonly column: number;
+    constructor(message: string, line: number, column: number);
+}
+
+/**
+ * Recursive descent parser for CEL (Common Expression Language).
+ * Parses CEL expressions into an Abstract Syntax Tree (AST).
+ */
+export declare class Parser {
+    private readonly lexer;
+    private current;
+    constructor(input: string);
+    /**
+     * Parse a CEL expression from the input string.
+     * @returns The parsed Expression AST node
+     * @throws ParseError if the input contains syntax errors
+     */
+    parse(): Expression;
+    private parseExpr;
+    private parseConditionalOr;
+    private parseConditionalAnd;
+    private parseRelation;
+    private parseAddition;
+    private parseMultiplication;
+    private parseUnary;
+    private parseMember;
+    private parsePrimary;
+    private parseListLiteral;
+    private parseMapOrStructLiteral;
+    private parseExprList;
+    private parseMapInits;
+    private parseMapInit;
+    private parseFieldInits;
+    private parseFieldInit;
+    private parseQualifiedIdent;
+    private parseLiteral;
+    private parseIntLiteral;
+    private parseUintLiteral;
+    private parseStringLiteral;
+    private parseBytesLiteral;
+    private unescapeString;
+    private isLiteralToken;
+    private isRelationalOp;
+    private toBinaryOp;
+    private match;
+    private expect;
+    private expectIdentifier;
+    private advance;
+    private peekAhead;
+    private isQualifiedStructLiteral;
+}
+
+/**
+ * A compiled CEL program that can be evaluated multiple times.
+ *
+ * A Program represents a parsed CEL expression that can be efficiently evaluated
+ * with different sets of variables. This is more efficient than parsing the
+ * expression each time it needs to be evaluated.
+ *
+ * Programs are created using CEL.compile() and should be reused when the same
+ * expression needs to be evaluated multiple times.
+ *
+ * @example
+ * ```typescript
+ * const program = cel.compile('price * quantity');
+ * const result1 = program.evaluate({ price: 10, quantity: 5 });
+ * const result2 = program.evaluate({ price: 20, quantity: 3 });
+ * ```
+ */
+export declare class Program {
+    private readonly ast;
+    private readonly functions;
+    /**
+     * Creates a new compiled program.
+     *
+     * This constructor is typically called by CEL.compile() and should not be used directly.
+     *
+     * @param ast The abstract syntax tree of the compiled expression
+     * @param functions The function library to use for evaluation
+     */
+    constructor(ast: Expression, functions: Functions);
+    /**
+     * Evaluates the compiled program with the given variables.
+     *
+     * @param variables A map of variable names to their values
+     * @returns The result of evaluating the expression
+     * @throws EvaluationError if an error occurs during evaluation
+     *
+     * @example
+     * ```typescript
+     * const result = program.evaluate({
+     *   x: 10,
+     *   y: 20,
+     *   items: [1, 2, 3]
+     * });
+     * ```
+     */
+    evaluate(variables?: Record<string, any>): any;
+}
+
+/**
+ * Field selection expression (operand.field).
+ */
+export declare class Select implements Expression {
+    readonly operand: Expression | null;
+    readonly field: string;
+    readonly isTest: boolean;
+    constructor(operand: Expression | null, field: string, isTest?: boolean);
+    accept<T>(visitor: Visitor<T>): T;
+}
+
+/**
+ * Utility helper methods for libcel.
+ * Methods are exported so library users can call them directly.
+ */
+/**
+ * Returns the size/length of the given value.
+ *
+ * Supported types:
+ * - String: number of characters
+ * - Array: number of elements
+ * - Map/Record: number of entries
+ * - null: 0
+ *
+ * @param value The value whose size should be computed; may be null
+ * @returns The size for supported types, or 0 for null
+ * @throws Error if the value type is unsupported
+ */
+declare function sizeOf(value: any): number;
+
+/**
+ * Standard CEL function library implementation.
+ *
+ * Provides all built-in CEL functions including:
+ * - Type conversions: int(), double(), string(), bool()
+ * - Type checking: type()
+ * - Collection operations: size(), has()
+ * - String operations: contains(), startsWith(), endsWith(), matches()
+ * - Math operations: max(), min()
+ *
+ * This class can be extended to add custom functions while retaining
+ * all standard CEL functionality.
+ */
+export declare class StandardFunctions implements Functions {
+    callFunction(name: string, args: any[]): any;
+    callMethod(target: any, method: string, args: any[]): any;
+    /**
+     * Attempts to call a native JavaScript method on the target object.
+     *
+     * @param target The object to call the method on
+     * @param name The method name
+     * @param args The arguments
+     * @returns The result of the method call
+     * @throws Error if the method doesn't exist or call fails
+     */
+    private callNativeMethod;
+}
+
+/**
+ * Struct literal expression (Type{field: value}).
+ */
+export declare class Struct implements Expression {
+    readonly typeName: string | null;
+    readonly fields: FieldInitializer[];
+    constructor(typeName: string | null, fields: FieldInitializer[]);
+    accept<T>(visitor: Visitor<T>): T;
+}
+
+/**
+ * Returns a simple type name for the given value.
+ *
+ * Possible results: "null", "bool", "int", "double", "string", "list", "map", or "unknown"
+ *
+ * @param value The value whose type is to be described
+ * @returns The simple type name
+ */
+declare function typeOf(value: any): string;
+
+/**
+ * Unary operation expression (!, -).
+ */
+export declare class Unary implements Expression {
+    readonly op: UnaryOp;
+    readonly operand: Expression;
+    constructor(op: UnaryOp, operand: Expression);
+    accept<T>(visitor: Visitor<T>): T;
+}
+
+/**
+ * Unary operators in CEL expressions.
+ */
+export declare enum UnaryOp {
+    /** Logical NOT (!) */
+    NOT = "NOT",
+    /** Numeric negation (-) */
+    NEGATE = "NEGATE"
+}
+
+declare namespace Utilities {
+    export {
+        sizeOf,
+        asInt,
+        asUInt,
+        asDouble,
+        asString,
+        asBool,
+        typeOf,
+        has,
+        matches,
+        max,
+        min,
+        compare,
+        deepEquals,
+        containsInArray
+    }
+}
+export { Utilities }
+
+/**
+ * Visitor interface for traversing and operating on CEL expression nodes.
+ * Implements the Visitor pattern for AST traversal.
+ *
+ * @template T The return type of visit operations
+ */
+export declare interface Visitor<T> {
+    visitLiteral(expr: Literal): T;
+    visitIdentifier(expr: Identifier): T;
+    visitSelect(expr: Select): T;
+    visitIndex(expr: Index): T;
+    visitCall(expr: Call): T;
+    visitList(expr: ListExpression): T;
+    visitMap(expr: MapExpression): T;
+    visitStruct(expr: Struct): T;
+    visitComprehension(expr: Comprehension): T;
+    visitUnary(expr: Unary): T;
+    visitBinary(expr: Binary): T;
+    visitConditional(expr: Conditional): T;
+}
+
+export { }