@libdbm/libcel-ts 1.0.2 → 2.0.0

package/dist/index.d.ts

@@ -1,56 +1,81 @@
 /**
- * Converts the given value to a boolean using common truthiness rules.
+ * Returns the absolute value, preserving the numeric type.
  *
- * Numbers are true if non-zero. Strings are true if non-empty.
- * Collections/maps are true if non-empty. Null is false.
+ * @throws EvaluationError if the value is the minimum int, whose magnitude is not representable
+ */
+declare function abs(value: unknown): bigint | number;
+
+/** Returns the bitwise AND of two ints. */
+declare function and(left: unknown, right: unknown): bigint;
+
+/**
+ * Error thrown when a function receives an argument it cannot accept.
  *
- * @param value The value to interpret
- * @returns The boolean interpretation
+ * This is the analogue of Java's IllegalArgumentException: wrong arity, an
+ * unsupported type, an out-of-range index or an unparsable literal. The logical
+ * operators absorb this error alongside EvaluationError.
  */
-export declare function asBool(value: any): boolean;
+export declare class ArgumentError extends Error {
+    constructor(message: string);
+}
 
 /**
- * Converts the given value to a double (number).
+ * Converts the given value to a boolean using common truthiness rules.
  *
- * Accepted inputs: number, string parsable as number
+ * Numbers are true if non-zero. Strings are true if non-empty. Collections and
+ * maps are true if non-empty. Null is false.
+ */
+export declare function asBool(value: unknown): boolean;
+
+/**
+ * Converts the given value to bytes, encoding a string as UTF-8.
  *
- * @param value The value to convert
- * @returns The converted number value
- * @throws Error if the value cannot be converted
+ * @throws ArgumentError if the value cannot be converted
  */
-declare function asDouble(value: any): number;
+declare function asBytes(value: unknown): Uint8Array;
 
 /**
- * Converts the given value to a signed integer (number).
+ * Converts the given value to a double.
  *
- * Accepted inputs: number, string (parsed as integer), boolean (true=1, false=0)
+ * Accepted inputs: number, bigint, and string parsable as a decimal number.
  *
- * @param value The value to convert
- * @returns The converted integer value
- * @throws Error if the value cannot be converted
+ * @throws ArgumentError if the value cannot be converted
  */
-declare function asInt(value: any): number;
+declare function asDouble(value: unknown): number;
 
 /**
- * Converts the given value to its string representation.
+ * Converts the given value to a Duration: a Duration is returned as is and a
+ * string is parsed.
  *
- * Returns the literal string "null" for null/undefined values.
+ * @throws ArgumentError if the value cannot be converted
+ */
+declare function asDuration(value: unknown): Duration;
+
+/**
+ * Converts the given value to a signed 64-bit integer.
  *
- * @param value The value to stringify
- * @returns The string representation
+ * Accepted inputs: bigint, number (truncated toward zero), string holding a
+ * decimal integer, boolean (true = 1), and Timestamp (epoch seconds).
+ *
+ * @throws ArgumentError if the value cannot be converted
  */
-declare function asString(value: any): string;
+declare function asInt(value: unknown): bigint;
 
 /**
- * Converts the given value to an unsigned integer.
+ * Converts the given value to its string representation.
  *
- * Negative inputs are not allowed and will result in an exception.
+ * Returns "null" for null, decodes bytes as UTF-8, renders a Duration in the
+ * CEL form ("3600s"), a Timestamp in RFC 3339, a double the way Java does
+ * ("1.0", "1.0E10") and a Type as its bare name.
+ */
+declare function asString(value: unknown): string;
+
+/**
+ * Converts the given value to an unsigned 64-bit integer.
  *
- * @param value The value to convert
- * @returns The non-negative integer value
- * @throws Error if the value is negative or cannot be converted
+ * @throws ArgumentError if the value is negative or cannot be converted
  */
-declare function asUInt(value: any): number;
+declare function asUInt(value: unknown): bigint;
 
 /**
  * Binary operation expression (+, -, *, /, etc.).
@@ -97,6 +122,20 @@ export declare enum BinaryOp {
     LOGICAL_OR = "LOGICAL_OR"
 }
 
+/**
+ * Orders two byte arrays lexicographically, then by length.
+ *
+ * Mirrors Java's `Arrays.compare(byte[], byte[])`, which compares each byte as a
+ * signed value.
+ */
+export declare function bytesCompare(left: Uint8Array, right: Uint8Array): number;
+
+/** Compares two byte arrays by content. */
+export declare function bytesEqual(left: Uint8Array, right: Uint8Array): boolean;
+
+/** Renders bytes as lowercase hexadecimal, two digits per byte. */
+export declare function bytesToHex(bytes: Uint8Array): string;
+
 /**
  * Function or method call expression.
  */
@@ -109,6 +148,14 @@ export declare class Call implements Expression {
     accept<T>(visitor: Visitor<T>): T;
 }
 
+/**
+ * Returns a string that is equal for two values exactly when CEL equality holds.
+ */
+export declare function canonicalKey(value: unknown): string;
+
+/** Returns the smallest double not less than the value. */
+declare function ceil(value: unknown): number;
+
 /**
  * The main entry point for evaluating CEL expressions.
  *
@@ -170,7 +217,7 @@ export declare class CEL {
      * const result = CEL.eval('x * 2', new StandardFunctions(), { x: 5 });
      * ```
      */
-    static eval(expression: string, functions: Functions, variables: Record<string, any>): any;
+    static eval(expression: string, functions: Functions, variables: Record<string, unknown> | Map<string, unknown>): unknown;
     /**
      * Compiles a CEL expression into a reusable program.
      *
@@ -210,21 +257,72 @@ export declare class CEL {
      * });
      * ```
      */
-    eval(expression: string, variables?: Record<string, any>): any;
+    eval(expression: string, variables?: Record<string, unknown> | Map<string, unknown>): unknown;
 }
 
+/**
+ * Returns the character at the given index as a single character string, or an
+ * empty string at the end.
+ *
+ * @throws ArgumentError if the index is out of range
+ */
+declare function charAt(value: string, index: bigint): string;
+
+/**
+ * Verifies that an integer result fits in 64 bits.
+ *
+ * @param value The result of an integer operation
+ * @returns The value unchanged
+ * @throws EvaluationError if the value is outside the signed 64-bit range
+ */
+export declare function checkInt64(value: bigint): bigint;
+
+/** The broken-down civil fields of an instant in some zone. */
+declare interface CivilFields {
+    year: bigint;
+    /** Month of year, 1-12. */
+    month: number;
+    /** Day of month, 1-31. */
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+    /** Day of week where Sunday is 0. */
+    weekday: number;
+    /** Day of year, 1-366. */
+    dayOfYear: number;
+}
+
+/**
+ * Returns the proleptic Gregorian date for a count of days since 1970-01-01.
+ */
+export declare function civilFromDays(days: bigint): {
+    year: bigint;
+    month: number;
+    day: number;
+};
+
+declare namespace Codecs {
+    export {
+        encode,
+        decode,
+        text
+    }
+}
+export { Codecs }
+
+/** Counts the Unicode code points in a string. */
+declare function codePointCount(value: string): number;
+
 /**
  * Compares two values using a common set of rules.
  *
- * Supported comparisons: numbers (by numeric value), strings (lexicographically),
- * booleans, arrays (lexicographically).
+ * Supported comparisons: numbers (exactly, across int and double), strings (by
+ * UTF-16 code unit), booleans, timestamps, durations and bytes.
  *
- * @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
+ * @throws ArgumentError if the values cannot be compared
  */
-declare function compare(a: any, b: any): number;
+declare function compare(a: unknown, b: unknown): number;
 
 /**
  * Comprehension expression for advanced iteration constructs.
@@ -241,6 +339,9 @@ export declare class Comprehension implements Expression {
     accept<T>(visitor: Visitor<T>): T;
 }
 
+/** Concatenates two byte arrays. */
+export declare function concatBytes(left: Uint8Array, right: Uint8Array): Uint8Array;
+
 /**
  * Conditional (ternary) expression (condition ? then : otherwise).
  */
@@ -253,25 +354,154 @@ export declare class Conditional implements Expression {
 }
 
 /**
- * Helper for array contains with deep equality.
+ * Reports whether the map holds the given key, comparing keys the way CEL compares values.
  *
- * @param array The array to search
- * @param value The value to find
- * @returns true if the array contains the value (using deep equality)
+ * An integer key therefore matches a double probe of the same value, so
+ * membership, indexing and presence tests all agree.
+ */
+declare function contains(map: Map<unknown, unknown>, key: unknown): boolean;
+
+/** Reports whether the list contains the value, using deep equality. */
+declare function contains_2(values: unknown[], value: unknown): boolean;
+
+/** Reports whether every element of the subset appears in the values. */
+declare function contains_3(values: unknown[], subset: unknown[]): boolean;
+
+/**
+ * Reports whether the array contains the value under CEL equality.
  */
-declare function containsInArray(array: any[], value: any): boolean;
+declare function containsInArray(array: unknown[], value: unknown): boolean;
+
+/** Returns the day of month (1-31) for the timestamp, in the zone or UTC. */
+declare function dateOf(value: unknown, zone?: unknown): bigint;
 
 /**
- * Deep equality check for CEL values.
+ * Returns the number of days since 1970-01-01 for a proleptic Gregorian date.
  *
- * @param left First value
- * @param right Second value
- * @returns true if values are deeply equal
+ * @param year The year (may be zero or negative)
+ * @param month The month, 1-12
+ * @param day The day of month, 1-31
  */
-declare function deepEquals(left: any, right: any): boolean;
+export declare function daysFromCivil(year: bigint, month: number, day: number): bigint;
 
 /**
- * Exception thrown during CEL expression evaluation.
+ * Decodes standard base64 text into bytes.
+ *
+ * Only the standard alphabet is accepted; padding is optional but must be
+ * well formed when present.
+ *
+ * @throws ArgumentError if the text is not valid base64
+ */
+declare function decode(value: unknown): Uint8Array;
+
+/**
+ * Deep equality check for CEL values. Alias of {@link equals}.
+ */
+declare const deepEquals: typeof equals;
+
+/** Removes duplicate elements under CEL equality, preserving first appearance order. */
+declare function distinct(values: unknown[]): unknown[];
+
+/**
+ * A CEL duration with nanosecond precision.
+ *
+ * Follows the java.time convention: `nanos` is always in `0..999_999_999` and the
+ * sign is carried by `seconds`, so -1.5s is `{ seconds: -2n, nanos: 500_000_000 }`.
+ */
+export declare class Duration {
+    readonly seconds: bigint;
+    readonly nanos: number;
+    /** The largest number of seconds a duration may span, per the CEL specification. */
+    static readonly SPAN = 315576000000n;
+    static readonly ZERO: Duration;
+    private constructor();
+    /**
+     * Creates a duration from seconds and a nanosecond adjustment, normalising the
+     * adjustment into the seconds.
+     */
+    static ofSeconds(seconds: bigint, nanoAdjustment?: bigint): Duration;
+    static ofNanos(nanos: bigint): Duration;
+    static ofMillis(millis: bigint): Duration;
+    static ofMinutes(minutes: bigint): Duration;
+    static ofHours(hours: bigint): Duration;
+    /**
+     * Parses a CEL duration literal such as `"300ms"`, `"-1.5h"` or `"2h45m"`.
+     *
+     * Units are `ns`, `us`, `µs`, `ms`, `s`, `m` and `h`. The value is accumulated
+     * exactly and rounded half up to the nearest nanosecond.
+     *
+     * @throws ArgumentError if the format is invalid or the span exceeds ±10 000 years
+     */
+    static parse(text: string): Duration;
+    /** Reports whether the value is a Duration. */
+    static isDuration(value: unknown): value is Duration;
+    isNegative(): boolean;
+    isZero(): boolean;
+    negated(): Duration;
+    plus(other: Duration): Duration;
+    minus(other: Duration): Duration;
+    /** The total length in nanoseconds. */
+    toNanos(): bigint;
+    /** The whole number of milliseconds, truncated toward zero. */
+    toMillis(): bigint;
+    /** The whole number of seconds, truncated toward negative infinity (the seconds field). */
+    toSeconds(): bigint;
+    /** The whole number of minutes, truncated toward zero. */
+    toMinutes(): bigint;
+    /** The whole number of hours, truncated toward zero. */
+    toHours(): bigint;
+    compareTo(other: Duration): number;
+    equals(other: unknown): boolean;
+    /**
+     * Renders the duration the way the CEL specification does: a seconds count with
+     * an `s` suffix, for example `"3600s"`, `"1.5s"` or `"-90s"`.
+     */
+    toString(): string;
+}
+
+/**
+ * Parses a CEL duration string such as "300ms", "-1.5h" or "2h45m".
+ *
+ * @throws ArgumentError if the format or unit is invalid
+ */
+declare function duration(value: string): Duration;
+
+/**
+ * Encodes bytes, or a string as UTF-8, in standard base64 with padding.
+ *
+ * @throws ArgumentError if the value cannot be converted to bytes
+ */
+declare function encode(value: unknown): string;
+
+/**
+ * Compares two values for deep equality.
+ *
+ * Lists and maps are compared element by element, numbers are compared
+ * numerically across int and double, bytes by content, and NaN is never equal
+ * to anything.
+ */
+declare function equals(left: unknown, right: unknown): boolean;
+
+/** Reports whether the two lists contain the same elements, ignoring order and duplicates. */
+declare function equivalent(left: unknown[], right: unknown[]): boolean;
+
+/**
+ * Escapes the string for inclusion in a CEL string literal, without the
+ * enclosing quotes.
+ */
+declare function escape_2(value: string): string;
+
+/**
+ * Escapes bytes for inclusion in a CEL bytes literal, without the enclosing
+ * quotes.
+ */
+declare function escapeBytes(value: Uint8Array): string;
+
+/**
+ * Error thrown by the interpreter when an expression cannot be evaluated.
+ *
+ * Covers undefined variables, type mismatches in operators, division by zero,
+ * integer overflow and evaluation limits.
  */
 export declare class EvaluationError extends Error {
     constructor(message: string);
@@ -292,6 +522,27 @@ export declare interface Expression {
     accept<T>(visitor: Visitor<T>): T;
 }
 
+/**
+ * Returns the first match of the pattern, or null when there is none.
+ *
+ * If the pattern declares a capture group, the first group is returned instead of
+ * the whole match.
+ *
+ * @throws ArgumentError if the pattern is invalid or declares more than one group
+ */
+declare function extract(value: string, pattern: string): string | null;
+
+/**
+ * Returns every match of the pattern in the given text.
+ *
+ * If the pattern declares a capture group, the first group of each match is
+ * returned instead of the whole match; matches where the group did not
+ * participate are skipped.
+ *
+ * @throws ArgumentError if the pattern is invalid or declares more than one group
+ */
+declare function extractAll(value: string, pattern: string): string[];
+
 /**
  * Field initializer in a struct literal.
  */
@@ -301,6 +552,48 @@ export declare class FieldInitializer {
     constructor(field: string, value: Expression);
 }
 
+/**
+ * Breaks a count of seconds since the epoch into civil fields in the given zone.
+ *
+ * @param seconds Seconds since 1970-01-01T00:00:00Z
+ * @param zone An IANA zone identifier, or null for UTC
+ */
+export declare function fieldsOf(seconds: bigint, zone: unknown): CivilFields;
+
+/**
+ * Returns the first element.
+ *
+ * @throws ArgumentError if the list is empty
+ */
+declare function first(values: unknown[]): unknown;
+
+/**
+ * Renders a double with the given number of fractional digits, rounding half up
+ * on its shortest decimal representation the way Java's
+ * `BigDecimal.valueOf(d).setScale(p, HALF_UP)` does.
+ */
+declare function fixed(value: number, precision: number): string;
+
+/**
+ * Flattens nested lists to the requested depth.
+ *
+ * @throws ArgumentError if the depth is less than 1
+ */
+declare function flatten(values: unknown[], depth?: bigint): unknown[];
+
+/** Returns the largest double not greater than the value. */
+declare function floor(value: unknown): number;
+
+/**
+ * Formats a string using the CEL format verbs.
+ *
+ * Supported verbs are %s, %d, %f, %e, %b, %o, %x, %X and %%, each accepting an
+ * optional precision such as %.3f.
+ *
+ * @throws ArgumentError if a verb is unknown or the argument count does not match
+ */
+declare function format(template: string, args: unknown[]): string;
+
 /**
  * Interface for providing functions to CEL expressions.
  *
@@ -330,6 +623,18 @@ export declare interface Functions {
      * @throws Error if the function is not found or if the arguments are invalid
      */
     callFunction(name: string, args: any[]): any;
+    /**
+     * Reports whether this library provides a qualified global function with the given name.
+     *
+     * The interpreter uses this to resolve namespaced calls such as `math.greatest(1, 2)`,
+     * which would otherwise be parsed as a field selection followed by a method call. Only
+     * names that are not shadowed by a bound variable are ever tested. Implementations that
+     * omit this method provide no namespaced functions.
+     *
+     * @param name The qualified function name, for example "math.greatest"
+     * @returns true if the name should be dispatched to callFunction
+     */
+    knows?(name: string): boolean;
     /**
      * Calls a method on a target object.
      *
@@ -343,13 +648,24 @@ export declare interface Functions {
 }
 
 /**
- * Checks whether a map contains the given field name.
+ * Returns the largest of the given values; a single list argument is spread.
+ *
+ * @throws ArgumentError if no values are given or they are not comparable
+ */
+declare function greatest(values: unknown[]): unknown;
+
+/** Counts the capture groups a pattern declares. */
+declare function groupCount(pattern: string): number;
+
+/**
+ * Checks whether a map contains the given key.
  *
- * @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
+ * @returns true if target is a map and contains the key under CEL equality; false otherwise
  */
-declare function has(target: any, field: any): boolean;
+declare function has(target: unknown, field: unknown): boolean;
+
+/** Returns the hour of day for a timestamp, or the whole number of hours in a duration. */
+declare function hoursOf(value: unknown, zone?: unknown): bigint;
 
 /**
  * Identifier expression (variable reference).
@@ -370,45 +686,189 @@ export declare class Index implements Expression {
     accept<T>(visitor: Visitor<T>): T;
 }
 
+/**
+ * Returns the index of the first occurrence of a substring at or after the
+ * offset, or -1 when absent.
+ *
+ * @throws ArgumentError if the offset is out of range
+ */
+declare function indexOf(value: string, search: string, start?: bigint): bigint;
+
+/** Largest signed 64-bit integer. */
+export declare const INT64_MAX: bigint;
+
+/** Smallest signed 64-bit integer. */
+export declare const INT64_MIN: bigint;
+
 /**
  * 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.
+ *
+ * Variables are normalised into the CEL value model on construction: integer-valued
+ * numbers become `bigint`, plain objects become `Map`, and `Date` becomes `Timestamp`.
+ *
+ * Note: an Interpreter is not safe to share between concurrent evaluations; the
+ * variable scope is mutated while macros run.
  */
-export declare class Interpreter implements Visitor<any> {
+export declare class Interpreter implements Visitor<unknown> {
     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.
+     * @param variables Variable bindings as a plain object or Map. If null, no variables are bound.
+     * @param functions The function library. If null, StandardFunctions is used.
      */
-    constructor(variables?: Record<string, any> | null, functions?: Functions | null);
+    constructor(variables?: Record<string, unknown> | Map<string, unknown> | 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;
+    evaluate(expr: Expression): unknown;
+    visitLiteral(expr: Literal): unknown;
+    visitIdentifier(expr: Identifier): unknown;
+    visitSelect(expr: Select): unknown;
+    visitCall(expr: Call): unknown;
+    private knows;
+    private qualify;
+    private root;
     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;
+    private test;
+    visitList(expr: ListExpression): unknown;
+    visitMap(expr: MapExpression): unknown;
+    visitStruct(expr: Struct): unknown;
+    visitComprehension(expr: Comprehension): unknown;
+    visitUnary(expr: Unary): unknown;
+    visitBinary(expr: Binary): unknown;
+    private combine;
+    private attempt;
+    visitConditional(expr: Conditional): unknown;
+    visitIndex(expr: Index): unknown;
+    private repetitions;
+    private arithmetic;
+    private compare;
 }
 
+/** Reports whether the two lists share at least one element. */
+declare function intersects(left: unknown[], right: unknown[]): boolean;
+
+/**
+ * Helpers for the CEL bytes type, represented as Uint8Array.
+ */
+/** Reports whether the value is a CEL bytes value. */
+export declare function isBytes(value: unknown): value is Uint8Array;
+
+/** Reports whether the value is a CEL double (a number). */
+export declare function isDouble(value: unknown): value is number;
+
+/** Reports whether the value is neither NaN nor infinite. */
+declare function isFinite_2(value: unknown): boolean;
+
+/** Reports whether the value is positive or negative infinity. */
+declare function isInf(value: unknown): boolean;
+
+/** Reports whether the value is a CEL int (a bigint). */
+export declare function isInt(value: unknown): value is bigint;
+
+/** Reports whether the value is a CEL map (a Map, or a plain object not yet normalised). */
+declare function isMap(value: unknown): value is Map<unknown, unknown>;
+
+/** Reports whether the value is NaN. */
+declare function isNaN_2(value: unknown): boolean;
+
+/** Reports whether the value is a CEL int or double. */
+export declare function isNumeric(value: unknown): value is bigint | number;
+
+/** Reports whether the value is a plain object (not a class instance). */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+
+/**
+ * Renders a double the way Java's `Double.toString` does.
+ *
+ * Values with magnitude in [1e-3, 1e7) print in plain decimal notation with at
+ * least one fractional digit (`1.0`, `3.14`); everything else prints in
+ * computerised scientific notation (`1.0E10`, `1.234E-5`).
+ */
+export declare function javaDoubleToString(value: number): string;
+
+/**
+ * Joins a list of strings with the given separator.
+ *
+ * @throws ArgumentError if any element is not a string
+ */
+declare function join(values: unknown[], separator: string): string;
+
+/** A map from CEL values to arbitrary values, keyed by CEL equality. */
+export declare class KeyMap<V> {
+    private readonly entries;
+    set(key: unknown, value: V): void;
+    get(key: unknown): V | undefined;
+    has(key: unknown): boolean;
+    get size(): number;
+}
+
+/** A set of CEL values keyed by CEL equality. */
+export declare class KeySet {
+    private readonly keys;
+    /** Adds the value; returns true if it was not already present. */
+    add(value: unknown): boolean;
+    has(value: unknown): boolean;
+    get size(): number;
+}
+
+/**
+ * Returns the last element.
+ *
+ * @throws ArgumentError if the list is empty
+ */
+declare function last(values: unknown[]): unknown;
+
+/**
+ * Returns the index of the last occurrence of a substring, searching backwards
+ * from the offset when one is given, or -1 when absent.
+ *
+ * @throws ArgumentError if the offset is out of range
+ */
+declare function lastIndexOf(value: string, search: string, start?: bigint): bigint;
+
+/**
+ * Returns the smallest of the given values; a single list argument is spread.
+ *
+ * @throws ArgumentError if no values are given or they are not comparable
+ */
+declare function least(values: unknown[]): unknown;
+
+/**
+ * Shifts an int left by the given number of bits, wrapping at 64 bits.
+ *
+ * @throws ArgumentError if the count is negative
+ */
+declare function left(value: unknown, count: unknown): bigint;
+
+/**
+ * The largest collection or string an expression may generate.
+ *
+ * CEL evaluates untrusted input, so operations whose size is controlled by the
+ * expression itself refuse to allocate beyond this ceiling rather than exhausting
+ * the heap.
+ */
+declare const LIMIT = 1000000;
+
+/**
+ * Refuses a result that would exceed {@link LIMIT}.
+ *
+ * Bounding each operation's output, and not only its inputs, is what stops two
+ * separately legal values from being combined into one that exhausts the heap.
+ *
+ * @param size The size the operation is about to produce
+ * @param what The operation being bounded, named in the error message
+ * @throws EvaluationError if the size exceeds the limit
+ */
+declare function limit(size: number | bigint, what: string): void;
+
 /**
  * List literal expression ([1, 2, 3]).
  */
@@ -418,6 +878,21 @@ export declare class ListExpression implements Expression {
     accept<T>(visitor: Visitor<T>): T;
 }
 
+declare namespace Lists {
+    export {
+        distinct,
+        flatten,
+        reverse_2 as reverse,
+        slice,
+        sort,
+        first,
+        last,
+        range,
+        contains_2 as contains
+    }
+}
+export { Lists }
+
 /**
  * Literal value expression (null, boolean, number, string, bytes).
  */
@@ -441,6 +916,9 @@ export declare enum LiteralType {
     BYTES = "BYTES"
 }
 
+/** Lowercases the ASCII letters of the string, leaving other characters untouched. */
+declare function lower(value: string): string;
+
 /**
  * Map entry (key-value pair in a map literal).
  */
@@ -462,36 +940,111 @@ export declare class MapExpression implements Expression {
 /**
  * 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
+ * @throws ArgumentError if the pattern is invalid
  */
 declare function matches(text: string, pattern: string): boolean;
 
+declare namespace Maths {
+    export {
+        greatest,
+        least,
+        abs,
+        ceil,
+        floor,
+        round,
+        trunc,
+        sign,
+        sqrt,
+        isNaN_2 as isNaN,
+        isInf,
+        isFinite_2 as isFinite,
+        and,
+        or,
+        xor,
+        not,
+        left,
+        right
+    }
+}
+export { Maths }
+
+/**
+ * Returns the maximum element from a non-empty list of values.
+ *
+ * @throws ArgumentError if the list is empty or values are not comparable
+ */
+declare function max(values: unknown[]): unknown;
+
+/** Returns the millisecond for a timestamp, or the whole number of milliseconds in a duration. */
+declare function millisecondsOf(value: unknown, zone?: unknown): bigint;
+
+/**
+ * Returns the minimum element from a non-empty list of values.
+ *
+ * @throws ArgumentError if the list is empty or values are not comparable
+ */
+declare function min(values: unknown[]): unknown;
+
+/** Returns the minute for a timestamp, or the whole number of minutes in a duration. */
+declare function minutesOf(value: unknown, zone?: unknown): bigint;
+
+/** Returns the zero-based month (0-11) for the timestamp, in the zone or UTC. */
+declare function monthOf(value: unknown, zone?: unknown): bigint;
+
 /**
- * Returns the maximum element from a non-empty array of values.
+ * Converts a JavaScript value into the CEL value model.
+ *
+ * Applied to variables entering `Program.evaluate()` and to the results of
+ * custom functions, so that every code path inside the interpreter sees exactly
+ * one representation per CEL type:
+ *
+ * - `undefined` becomes `null`
+ * - integer-valued numbers become `bigint` (CEL int); other numbers stay doubles
+ * - `Date` becomes `Timestamp`
+ * - arrays are copied with normalised elements
+ * - `Map` instances are copied with normalised keys and values
+ * - plain objects become `Map<string, unknown>`
+ * - `bigint`, `string`, `boolean`, `Uint8Array`, `Timestamp`, `Duration` and `Type`
+ *   pass through; other class instances are left as they are
  *
- * Comparison rules follow compare(). All elements must be mutually comparable.
+ * @throws ArgumentError if the value contains a cycle
+ */
+export declare function normalize(value: unknown): unknown;
+
+/**
+ * Converts a value returned by a function into the CEL value model.
  *
- * @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
+ * Like {@link normalize}, except that numbers are left as doubles: a function
+ * returning a JavaScript number has produced a CEL double, and one that wants to
+ * return an int returns a `bigint`.
  */
-declare function max(values: any[]): any;
+export declare function normalizeResult(value: unknown): unknown;
+
+/** Returns the bitwise complement of an int. */
+declare function not(value: unknown): bigint;
+
+/**
+ * Returns the UTF-16 offset of the given code point index, or -1 when the index
+ * exceeds the number of code points.
+ */
+declare function offsetByCodePoints(value: string, index: number): number;
+
+/** Returns the bitwise OR of two ints. */
+declare function or(left: unknown, right: unknown): bigint;
 
 /**
- * Returns the minimum element from a non-empty array of values.
+ * Orders two numbers exactly, without the precision loss of a double conversion.
  *
- * Comparison rules follow compare(). All elements must be mutually comparable.
+ * Two ints compare as integers and two doubles as doubles. A mixed pair is
+ * compared exactly, so an int above the range a double can represent is not
+ * mistaken for the double it would round to.
  *
- * @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
+ * @returns A negative number, zero, or a positive number
  */
-declare function min(values: any[]): any;
+export declare function order(left: bigint | number, right: bigint | number): number;
+
+/** Returns the zero-based day of year for the timestamp. */
+declare function ordinalOf(value: unknown, zone?: unknown): bigint;
 
 /**
  * ParseError is thrown when the lexer or parser encounters invalid syntax.
@@ -509,6 +1062,7 @@ export declare class ParseError extends Error {
 export declare class Parser {
     private readonly lexer;
     private current;
+    private depth;
     constructor(input: string);
     /**
      * Parse a CEL expression from the input string.
@@ -525,6 +1079,7 @@ export declare class Parser {
     private parseUnary;
     private parseMember;
     private parsePrimary;
+    private test;
     private parseListLiteral;
     private parseMapOrStructLiteral;
     private parseExprList;
@@ -536,8 +1091,18 @@ export declare class Parser {
     private parseLiteral;
     private parseIntLiteral;
     private parseUintLiteral;
+    private checkRange;
     private parseStringLiteral;
     private parseBytesLiteral;
+    /**
+     * Decodes the escapes of a bytes literal.
+     *
+     * Character escapes and plain text accumulate in a pending buffer that is
+     * UTF-8 encoded when flushed, while \xHH and octal escapes write a raw byte.
+     */
+    private unescapeBytes;
+    private simpleEscape;
+    private isOctal;
     private unescapeString;
     private isLiteralToken;
     private isRelationalOp;
@@ -550,6 +1115,79 @@ export declare class Parser {
     private isQualifiedStructLiteral;
 }
 
+/**
+ * Renders an expression tree back into CEL source text.
+ *
+ * The compact form is a single line that parses back into an equivalent tree,
+ * with parentheses only where operator precedence requires them. The pretty form
+ * breaks lists, maps, structs, argument lists and logical chains across lines
+ * once they no longer fit within the configured width.
+ *
+ * Expressions built by the parser always round-trip. A {@link Comprehension},
+ * which the parser never produces, is rendered in a diagnostic form that is not
+ * valid CEL.
+ *
+ * @example
+ * ```typescript
+ * const expr = new Parser('a + (b * c)').parse();
+ * Printer.print(expr);                          // 'a + b * c'
+ * Printer.print(expr, PrinterOptions.pretty()); // same, it fits on one line
+ * ```
+ */
+export declare class Printer implements Visitor<string> {
+    private readonly options;
+    private level;
+    private constructor();
+    /**
+     * Renders the given expression as CEL source.
+     *
+     * @param expr The expression to render
+     * @param options The rendering options; compact by default
+     * @returns The rendered text
+     */
+    static print(expr: Expression, options?: PrinterOptions): string;
+    private static precedence;
+    private static spelling;
+    private static decimal;
+    private text;
+    private render;
+    private nested;
+    visitLiteral(expr: Literal): string;
+    visitIdentifier(expr: Identifier): string;
+    visitSelect(expr: Select): string;
+    visitCall(expr: Call): string;
+    visitList(expr: ListExpression): string;
+    visitMap(expr: MapExpression): string;
+    visitStruct(expr: Struct): string;
+    visitComprehension(expr: Comprehension): string;
+    visitUnary(expr: Unary): string;
+    visitBinary(expr: Binary): string;
+    visitConditional(expr: Conditional): string;
+    visitIndex(expr: Index): string;
+    private parts;
+    private group;
+    private pad;
+}
+
+/**
+ * Rendering options for {@link Printer}.
+ */
+export declare class PrinterOptions {
+    readonly wrap: boolean;
+    readonly indent: number;
+    readonly width: number;
+    /**
+     * @param wrap Whether to break long constructs across lines
+     * @param indent The number of spaces per indentation level
+     * @param width The maximum line width before a construct is broken
+     */
+    constructor(wrap: boolean, indent: number, width: number);
+    /** Options for a single line rendering. */
+    static compact(): PrinterOptions;
+    /** Options for a multi-line rendering indented by two spaces at a width of 100. */
+    static pretty(): PrinterOptions;
+}
+
 /**
  * A compiled CEL program that can be evaluated multiple times.
  *
@@ -595,9 +1233,64 @@ export declare class Program {
      * });
      * ```
      */
-    evaluate(variables?: Record<string, any>): any;
+    evaluate(variables?: Record<string, unknown> | Map<string, unknown>): unknown;
 }
 
+/** Returns the string as a quoted CEL string literal, including the double quotes. */
+declare function quote(value: string): string;
+
+/**
+ * Returns the integers from zero up to, but not including, the given bound.
+ *
+ * @param count The exclusive upper bound; negative values yield an empty list
+ * @throws EvaluationError if the count exceeds the evaluation limit
+ */
+declare function range(count: bigint): bigint[];
+
+declare namespace Regexes {
+    export {
+        groupCount,
+        replace_2 as replace,
+        extract,
+        extractAll
+    }
+}
+export { Regexes }
+
+/**
+ * Replaces occurrences of a literal substring.
+ *
+ * @param limit The maximum number of replacements, or -1 for all
+ */
+declare function replace(value: string, from: string, to: string, limit?: bigint): string;
+
+/**
+ * Replaces matches of the pattern with the given replacement.
+ *
+ * @param limit The maximum number of replacements, or -1 for all
+ * @throws ArgumentError if the pattern or a group reference is invalid
+ */
+declare function replace_2(value: string, pattern: string, replacement: string, limit?: bigint): string;
+
+/** Reverses the string, preserving surrogate pairs. */
+declare function reverse(value: string): string;
+
+/** Returns the elements in reverse order. */
+declare function reverse_2(values: unknown[]): unknown[];
+
+/**
+ * Shifts an int right by the given number of bits, without sign extension.
+ *
+ * @throws ArgumentError if the count is negative
+ */
+declare function right(value: unknown, count: unknown): bigint;
+
+/** Rounds to the nearest double, with ties rounding away from zero. */
+declare function round(value: unknown): number;
+
+/** Returns the second for a timestamp, or the whole number of seconds in a duration. */
+declare function secondsOf(value: unknown, zone?: unknown): bigint;
+
 /**
  * Field selection expression (operand.field).
  */
@@ -610,52 +1303,121 @@ export declare class Select implements Expression {
 }
 
 /**
- * Utility helper methods for libcel.
- * Methods are exported so library users can call them directly.
+ * Returns the value stored under the given key, comparing keys the way CEL compares values.
+ *
+ * @returns The matching value, or undefined when no key matches
  */
+declare function select(map: Map<unknown, unknown>, key: unknown): unknown;
+
+declare namespace Sets {
+    export {
+        contains_3 as contains,
+        equivalent,
+        intersects
+    }
+}
+export { Sets }
+
+/** Returns -1, 0 or 1 by sign, preserving the numeric type. */
+declare function sign(value: unknown): bigint | number;
+
 /**
  * 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
+ * Strings are measured in Unicode code points; bytes, lists and maps by their
+ * element count; null is 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
+ * @throws ArgumentError if the value type is unsupported
  */
-declare function sizeOf(value: any): number;
+declare function sizeOf(value: unknown): bigint;
+
+/**
+ * Returns the elements between the given indices.
+ *
+ * @throws ArgumentError if the range is invalid
+ */
+declare function slice(values: unknown[], start: bigint, end: bigint): unknown[];
+
+/**
+ * Sorts the list using the standard CEL ordering.
+ *
+ * @throws ArgumentError if the elements are not mutually comparable
+ */
+declare function sort(values: unknown[]): unknown[];
+
+/** The largest number of seconds a duration may span, per the CEL specification. */
+declare const SPAN = 315576000000n;
+
+/**
+ * Splits a string around occurrences of a literal separator, following Java's
+ * `String.split` limit semantics: a positive limit caps the number of parts with
+ * the last part holding the unsplit remainder, and a negative limit keeps trailing
+ * empty strings.
+ *
+ * @param limit The maximum number of parts, or -1 for no limit
+ */
+declare function split(value: string, separator: string, limit?: bigint): string[];
+
+/** Returns the square root as a double. */
+declare function sqrt(value: unknown): number;
 
 /**
  * Standard CEL function library implementation.
  *
  * Provides all built-in CEL functions including:
- * - Type conversions: int(), double(), string(), bool()
+ * - Type conversions: int(), uint(), double(), string(), bool(), bytes(), dyn()
  * - Type checking: type()
  * - Collection operations: size(), has()
  * - String operations: contains(), startsWith(), endsWith(), matches()
+ * - Date/time: timestamp(), duration() and the getXxx() accessors
  * - 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;
+    knows(name: string): boolean;
+    callFunction(name: string, args: unknown[]): unknown;
+    callMethod(target: unknown, method: string, args: unknown[]): unknown;
+    /**
+     * Dispatches a namespaced function such as `math.abs`.
+     *
+     * @throws ArgumentError if the name is unknown
+     */
+    protected callQualified(name: string, args: unknown[]): unknown;
     /**
      * 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
+     * This is the last resort after every named method, the analogue of the Java
+     * library's reflective method call.
+     *
+     * @throws ArgumentError if the method doesn't exist
+     * @throws EvaluationError if the call fails
      */
     private callNativeMethod;
 }
 
+declare namespace Strings {
+    export {
+        charAt,
+        indexOf,
+        lastIndexOf,
+        lower,
+        upper,
+        substring,
+        reverse,
+        replace,
+        split,
+        join,
+        format,
+        fixed,
+        escape_2 as escape,
+        quote,
+        escapeBytes
+    }
+}
+export { Strings }
+
 /**
  * Struct literal expression (Type{field: value}).
  */
@@ -667,14 +1429,162 @@ export declare class Struct implements Expression {
 }
 
 /**
- * Returns a simple type name for the given value.
+ * Returns the substring between the given code point indices, or from the start
+ * index to the end.
+ *
+ * @throws ArgumentError if the range is invalid
+ */
+declare function substring(value: string, start: bigint, end?: bigint): string;
+
+/**
+ * Decodes base64 text into a UTF-8 string.
+ *
+ * @throws ArgumentError if the text is not valid base64
+ */
+declare function text(value: string): string;
+
+/**
+ * A CEL timestamp: an instant on the UTC time line with nanosecond precision.
+ *
+ * `nanos` is always in `0..999_999_999`; `seconds` counts from
+ * 1970-01-01T00:00:00Z and may be negative.
+ */
+export declare class Timestamp {
+    readonly seconds: bigint;
+    readonly nanos: number;
+    /** Epoch second of the smallest supported instant (java.time.Instant.MIN). */
+    static readonly MIN_SECONDS = -31557014167219200n;
+    /** Epoch second of the largest supported instant (java.time.Instant.MAX). */
+    static readonly MAX_SECONDS = 31556889864403199n;
+    private constructor();
+    /**
+     * Creates a timestamp from epoch seconds and a nanosecond adjustment.
+     *
+     * @throws ArgumentError if the instant is outside the supported range
+     */
+    static ofEpochSeconds(seconds: bigint, nanoAdjustment?: bigint): Timestamp;
+    /** Creates a timestamp from epoch milliseconds. */
+    static ofEpochMillis(millis: bigint): Timestamp;
+    /** Converts a JavaScript Date. */
+    static fromDate(date: Date): Timestamp;
+    /** The current instant, at millisecond resolution. */
+    static now(): Timestamp;
+    /**
+     * Parses an RFC 3339 timestamp such as `2024-01-01T00:00:00Z` or
+     * `2024-01-01T01:00:00.5+01:00`.
+     *
+     * @throws ArgumentError if the text is not a valid timestamp
+     */
+    static parse(text: string): Timestamp;
+    /** Reports whether the value is a Timestamp. */
+    static isTimestamp(value: unknown): value is Timestamp;
+    /** Converts to a JavaScript Date, truncating to milliseconds. */
+    toDate(): Date;
+    /**
+     * Adds a duration.
+     *
+     * @throws EvaluationError if the result is outside the supported range
+     */
+    plus(duration: Duration): Timestamp;
+    /**
+     * Subtracts a duration.
+     *
+     * @throws EvaluationError if the result is outside the supported range
+     */
+    minus(duration: Duration): Timestamp;
+    private shift;
+    /** The duration from this instant to another (`other - this`). */
+    until(other: Timestamp): Duration;
+    compareTo(other: Timestamp): number;
+    equals(other: unknown): boolean;
+    /**
+     * Renders the instant in ISO-8601 form, the way java.time.Instant does:
+     * `2024-03-05T14:30:45.250Z`, with the fraction shown in groups of three
+     * digits only as far as needed.
+     */
+    toString(): string;
+}
+
+/**
+ * Parses or provides a Timestamp from the given value.
  *
- * Possible results: "null", "bool", "int", "double", "string", "list", "map", or "unknown"
+ * Accepted inputs: null returns the current time, a string is parsed as RFC 3339,
+ * a bigint is treated as epoch seconds, and a Date or Timestamp is converted.
  *
- * @param value The value whose type is to be described
- * @returns The simple type name
+ * @throws ArgumentError if the input type or format is invalid
  */
-declare function typeOf(value: any): string;
+declare function timestamp(value: unknown): Timestamp;
+
+/** Truncates toward zero. */
+declare function trunc(value: unknown): number;
+
+/**
+ * Converts a double to a 64-bit integer the way Java's `Number.longValue()` does:
+ * truncation toward zero, NaN becomes zero, and out-of-range values saturate.
+ */
+export declare function truncateToInt64(value: number): bigint;
+
+/**
+ * A CEL type value, as returned by the `type()` function.
+ *
+ * Type values are interned, compare equal by name and are bound as identifiers,
+ * so the specification form `type(42) == int` holds. They render as their bare
+ * name, so `string(type(42))` is `"int"`.
+ */
+export declare class Type {
+    readonly name: string;
+    /** The type of a null value. */
+    static readonly NULL: Type;
+    /** The boolean type. */
+    static readonly BOOL: Type;
+    /** The signed integer type. */
+    static readonly INT: Type;
+    /** The unsigned integer type. */
+    static readonly UINT: Type;
+    /** The double precision floating point type. */
+    static readonly DOUBLE: Type;
+    /** The string type. */
+    static readonly STRING: Type;
+    /** The bytes type. */
+    static readonly BYTES: Type;
+    /** The list type. */
+    static readonly LIST: Type;
+    /** The map type. */
+    static readonly MAP: Type;
+    /** The timestamp type. */
+    static readonly TIMESTAMP: Type;
+    /** The duration type. */
+    static readonly DURATION: Type;
+    /** The type of a type value. */
+    static readonly TYPE: Type;
+    /** The type of a value this library does not recognise. */
+    static readonly UNKNOWN: Type;
+    private static readonly BY_NAME;
+    private constructor();
+    /**
+     * Returns the type with the given name, or null when the name does not denote a CEL type.
+     *
+     * Used to resolve bare type names such as `int` when they appear as identifiers.
+     * `unknown` is deliberately not resolvable.
+     *
+     * @param name The candidate type name
+     * @returns The matching type, or null
+     */
+    static of(name: string): Type | null;
+    /**
+     * Reports whether the value is a Type.
+     */
+    static isType(value: unknown): value is Type;
+    equals(other: unknown): boolean;
+    toString(): string;
+}
+
+/**
+ * Returns the CEL type of the given value.
+ *
+ * @returns The type value, or Type.UNKNOWN for a value this library does not recognise
+ */
+declare function typeOf(value: unknown): Type;
 
 /**
  * Unary operation expression (!, -).
@@ -696,22 +1606,57 @@ export declare enum UnaryOp {
     NEGATE = "NEGATE"
 }
 
+/** Uppercases the ASCII letters of the string, leaving other characters untouched. */
+declare function upper(value: string): string;
+
+/** Breaks a count of seconds since the epoch into UTC civil fields. */
+export declare function utcFields(seconds: bigint): CivilFields;
+
+/** Decodes UTF-8 bytes into a string, replacing malformed sequences. */
+export declare function utf8Decode(bytes: Uint8Array): string;
+
+/** Encodes a string as UTF-8. */
+export declare function utf8Encode(text: string): Uint8Array;
+
 declare namespace Utilities {
     export {
+        limit,
+        isMap,
+        codePointCount,
+        offsetByCodePoints,
         sizeOf,
         asInt,
         asUInt,
         asDouble,
         asString,
+        asBytes,
         asBool,
         typeOf,
         has,
+        contains,
+        select,
         matches,
+        timestamp,
+        duration,
+        asDuration,
+        dateOf,
+        monthOf,
+        yearOf,
+        hoursOf,
+        minutesOf,
+        secondsOf,
+        millisecondsOf,
+        weekdayOf,
+        ordinalOf,
         max,
         min,
+        equals,
         compare,
-        deepEquals,
-        containsInArray
+        containsInArray,
+        order,
+        LIMIT,
+        SPAN,
+        deepEquals
     }
 }
 export { Utilities }
@@ -737,4 +1682,13 @@ export declare interface Visitor<T> {
     visitConditional(expr: Conditional): T;
 }
 
+/** Returns the day of week for the timestamp, where Sunday is 0. */
+declare function weekdayOf(value: unknown, zone?: unknown): bigint;
+
+/** Returns the bitwise exclusive OR of two ints. */
+declare function xor(left: unknown, right: unknown): bigint;
+
+/** Returns the year for the timestamp, in the zone or UTC. */
+declare function yearOf(value: unknown, zone?: unknown): bigint;
+
 export { }