ifc-expressions 2.3.0 → 3.0.0-beta.2

package/README.md

@@ -20,8 +20,8 @@ implementation of `src/context/IfcExpressionContext`. Without such a context, th
 contain references to the model cannot be evaluated.
 
 ```ts
-import {IfcExpression} from "ifc-expression";
-import {IfcExpressionContext} from "./IfcExpressionContext";
+import { IfcExpression } from "ifc-expression";
+import { IfcExpressionContext } from "./IfcExpressionContext";
 
 const result = IfcExpression.evaluate("1 + 1"); // evaluation without context
 console.log(JSON.stringify(result));
@@ -30,11 +30,235 @@ console.log(JSON.stringify(result));
 //   result: NumericValue {
 //     value: 2
 //   }
-//}
-const ctx: IfcExpressionContext = ... ; // set to your context here
-const result2 = IfcExpression.evaluate("$element.property('width').value() * 2 ", ctx);
+// }
+const ctx: IfcExpressionContext = ...; // set to your context here
+const result2 = IfcExpression.evaluate(
+  "$element.property('width').value() * 2",
+  ctx
+);
 ```
 
+## Plain JS Value Unwrapping
+
+`IfcExpression.evaluate(...)` returns library value objects such as `NumericValue`, `StringValue`, `LogicalValue`, `ContextObjectValue`, or IFC object references.
+If you want a plain value structure for downstream code, use `IfcExpression.unwrapValue(...)` on the successful result value.
+
+```ts
+import { IfcExpression, isExprEvalSuccess } from "ifc-expression";
+
+const evaluation = IfcExpression.evaluate("$result.statusCode", ctx, {
+  builtinVariableRegistry,
+});
+
+if (isExprEvalSuccess(evaluation)) {
+  const value = IfcExpression.unwrapValue(evaluation.result);
+  // value is a Decimal here
+}
+```
+
+`unwrapValue` preserves the expression model's precision and nullability semantics:
+
+- `NumericValue` and raw JS `number` values inside client builtin objects become `Decimal`
+- `StringValue` becomes `string`
+- `BooleanValue` becomes `boolean`
+- `LogicalValue.UNKNOWN` becomes `undefined`
+- `IfcTimeStampValue` becomes `Decimal`
+- `IfcDateValue`, `IfcDateTimeValue`, `IfcTimeValue`, and `IfcDurationValue` become their canonical string representation
+- arrays are unwrapped recursively
+- client builtin objects are unwrapped recursively to plain JS object structures
+- IFC object references such as `$element` and `$property` are unwrapped to plain objects containing their addressable attributes
+
+For IFC object references, unwrapping currently includes object attributes only. It does not recursively expand nested IFC object relations such as property sets or parent/child IFC objects.
+
+## Client Builtins
+
+In addition to the built-in IFC roots `$element` and `$property`, clients can register their own reserved builtins.
+These builtins are configured at parse/compile time through `BuiltinVariableRegistry`, and their values are provided at evaluation time through `IfcExpressionContext.resolveBuiltinVariable(name)`.
+
+Client builtins support:
+
+- reserved names such as `$query`, `$result`, `$thequery`, or any other configured builtin name
+- dotted property access such as `$result.statusCode`
+- dotted function access such as `$query.matches('name')`
+- static typing of members during parse/compile time
+- protection against shadowing by ordinary identifiers
+
+Example:
+
+```ts
+import { BuiltinVariableRegistry, IfcExpression, Type } from "ifc-expression";
+
+const builtinVariableRegistry = new BuiltinVariableRegistry([
+  {
+    name: "$query",
+    type: Type.CONTEXT_OBJECT_REF,
+    members: [
+      {
+        name: "property",
+        kind: "property",
+        valueType: Type.STRING,
+      },
+      {
+        name: "matches",
+        kind: "function",
+        argumentTypes: [Type.STRING],
+        returnType: Type.BOOLEAN,
+      },
+    ],
+  },
+  {
+    name: "$result",
+    type: Type.CONTEXT_OBJECT_REF,
+    members: [
+      {
+        name: "statusCode",
+        kind: "property",
+        valueType: Type.NUMERIC,
+      },
+    ],
+  },
+]);
+
+const parseResult = IfcExpression.parse(
+  "$query.matches('name') && $result.statusCode == 200",
+  undefined,
+  {
+    builtinVariableRegistry,
+  }
+);
+```
+
+At evaluation time, the context supplies the values for those builtins:
+
+```ts
+import { IfcExpressionContext } from "ifc-expression";
+
+const ctx: IfcExpressionContext = {
+  resolveElemRef() {
+    return elementAccessor;
+  },
+  resolvePropRef() {
+    return propertyAccessor;
+  },
+  resolveBuiltinVariable(name: string) {
+    switch (name) {
+      case "query":
+        return {
+          property: "LoadBearing",
+          matches(value: string) {
+            return this.property === value;
+          },
+        };
+      case "result":
+        return {
+          statusCode: 200,
+        };
+      default:
+        return undefined;
+    }
+  },
+};
+```
+
+`CONTEXT_OBJECT_REF` is intended for client-supplied evaluation-context objects.
+`IFC_OBJECT_REF` and its subtypes remain reserved for actual objects addressable in the IFC model.
+
+## Autocomplete
+
+`ifc-expressions` exposes autocomplete through `IfcExpressionAutocomplete.complete(input, cursorOffset, options)`.
+The autocompleter is aware of builtin roots, builtin functions, typed dotted member access, and function argument help.
+
+```ts
+import {
+  BuiltinVariableRegistry,
+  IfcExpressionAutocomplete,
+  Type,
+} from "ifc-expression";
+
+const builtinVariableRegistry = new BuiltinVariableRegistry([
+  {
+    name: "$query",
+    type: Type.CONTEXT_OBJECT_REF,
+    members: [
+      {
+        name: "property",
+        kind: "property",
+        valueType: Type.STRING,
+      },
+      {
+        name: "matches",
+        kind: "function",
+        argumentTypes: [Type.STRING],
+        returnType: Type.BOOLEAN,
+      },
+    ],
+  },
+]);
+
+const completion = IfcExpressionAutocomplete.complete("$query.mat", 10, {
+  builtinVariableRegistry,
+});
+
+console.log(completion.items);
+```
+
+The returned `CompletionResult` contains:
+
+- `items`: completion items for builtin roots, builtin functions, builtin member properties, and builtin member functions
+- `replaceFrom` and `replaceTo`: the text range to replace when applying a completion
+- `activeHelp`: optional signature help for the function or member function currently being typed
+
+Each `CompletionItem` can include:
+
+- `label`: the completion label
+- `insertText`: text to insert, for example `REPLACE()`
+- `cursorOffset`: where to place the cursor after insertion
+- `argumentTypeNames`: argument types for callable member suggestions
+- `returnTypeName`: return type for typed member suggestions
+- `chainable`: whether the suggested member returns another object that can be accessed with `...`
+- `documentation`: a localized one-line description
+
+### Autocomplete Hooks
+
+The autocomplete surface is shaped by two inputs:
+
+- `builtinVariableRegistry`: supplies reserved builtin roots and the typed member tree used for dotted access completion
+- `localizer`: translates builtin, member, and function documentation plus active argument help
+
+That means the same builtin definitions you use for parsing and evaluation also drive autocomplete. If a client registers `$thequery` or `$theresult`, those exact reserved names, their typed members, and their member functions participate in completion automatically.
+
+For empty or whitespace-only expressions, you can also provide a curated starter list with `emptyExpressionStarters`. Use the same names users would type in expressions: builtin roots such as `"$result"` and builtin functions such as `"REPLACE"`.
+Unknown starter names are ignored, and if you omit this option the built-in default starter list is used.
+
+```ts
+const emptyStateCompletion = IfcExpressionAutocomplete.complete("", 0, {
+  builtinVariableRegistry,
+  emptyExpressionStarters: ["$result", "REPLACE", "$query", "TOBOOLEAN"],
+});
+
+console.log(emptyStateCompletion.items.map((item) => item.label));
+// ["$result", "REPLACE", "$query", "TOBOOLEAN"]
+```
+
+Example with localization:
+
+```ts
+const completion = IfcExpressionAutocomplete.complete("REP", 3, {
+  localizer: {
+    t(key, fallback) {
+      return translations[key] ?? fallback;
+    },
+  },
+});
+
+console.log(completion.items[0].label);
+// REPLACE
+console.log(completion.items[0].documentation);
+// e.g. "REPLACE(input, pattern, replacement): replace <pattern> in <input> with <replacement>"
+```
+
+When the cursor is inside a function call, `activeHelp` contains the current signature and the active parameter's label and documentation when available. This works for both global builtin functions and typed builtin member functions.
+
 ## Quick Reference
 
 Get the current property value:
@@ -43,7 +267,7 @@ Get the current property value:
 
 Get the name of the property set the property is in:
 
-`$property.propertySet.name()`
+`$property.propertySet().name()`
 
 Get the name of the current element:
 
@@ -63,23 +287,23 @@ The last expression can also be written as
 
 Check if property `myProp` exists in property set `myPset` in the current element:
 
-`$element.propertySet('myPset').property('myProp').exists()`
+`EXISTS($element.propertySet('myPset').property('myProp'))`
 
 Hints:
 
 - Function/Method names are case-insensitive
 - you have `+ - * / ^` for numerics
-- you have `&& || >< !` for booleans (`><`is xor)
-- you have `==  !=  >=  <=  >  <` for strings, booleans and numerics
-- you have a `.toString()` method on anything (or, equivalently, a function `toString(x)` for any `x` ).
-- you have `REPLACE`, which only knows the wildcard character `*`. (same for `MATCHES, CONTAINS`)
-- you have `REGEXREPLACE` with full js Regular Expressions (same for `REGEXMATCHES, REGEXCONTAINS`)
+- you have `&& || >< !` for booleans (`><` is xor)
+- you have `== != >= <= > <` for strings, booleans and numerics
+- you have a `.toString()` method on anything (or, equivalently, a function `toString(x)` for any `x`).
+- you have `REPLACE`, which only knows the wildcard character `*`. (same for `MATCHES`, `CONTAINS`)
+- you have `REGEXREPLACE` with full js Regular Expressions (same for `REGEXMATCHES`, `REGEXCONTAINS`)
 
 ## IFC Expression Language Syntax
 
-The project uses ANTLR4 for parsing. The grammar is in src/grammar/ifcExpression.g4.
+The project uses ANTLR4 for parsing. The grammar is in `src/grammar/IfcExpression.g4`.
 
-The result of expression evaluation is a value of type `string, numeric, boolean, ifcObjectRef`, where `ifcObjectRef` is a reference to some object in the IFC model, or a temporal type (`IfcDateTime`, `IfcDate`, `IfcTime`, `IfcDuration`, and `IfcTimeStamp`)
+The result of expression evaluation is a value of type `string`, `numeric`, `boolean`, `ifcObjectRef`, `contextObjectRef`, or a temporal type (`IfcDateTime`, `IfcDate`, `IfcTime`, `IfcDuration`, and `IfcTimeStamp`). `ifcObjectRef` is a reference to some object in the IFC model. `contextObjectRef` is a client-supplied builtin object from the evaluation context.
 
 The language allows for specifying _a single expression_. There are no control statements and there is no way
 to define custom functions or custom types.
@@ -87,7 +311,7 @@ to define custom functions or custom types.
 An expression can be
 
 - a literal, such as `'hello world'`, or `17`
-- a variable reference, such as `$property` or `$element`,(for accessing the IFC model).
+- a variable reference, such as `$property`, `$element`, or a configured client builtin such as `$query`
 
 ... or a combination of multiple expressions:
 
@@ -100,18 +324,19 @@ An expression can be
 - `string`, e.g. `'abc'` or `"abc"`: text enclosed in single or double quotes
 - `boolean`, e.g. `TRUE` or `false`: true or false, either spelled all-uppercase or all-lowercase
 - `numeric`, e.g. `1` or `3.141`: a decimal number optionally containing one period to separate integer part from fractional part
-- `array`, e.g. `[1,2,"hi there"]: an ordered list of expressions
+- `array`, e.g. `[1,2,"hi there"]`: an ordered list of expressions
+- `contextObjectRef`: a typed client builtin object configured in `BuiltinVariableRegistry`
 
 ### Operators
 
 - numeric operators
-  - '+', '-', '\*', '/': plus, minus, multiplication, division - with the ususal precedence rules and associativity
-  - '^': raise to the power or, e.g. `2^3` (= 8)
+  - `+`, `-`, `*`, `/`: plus, minus, multiplication, division - with the usual precedence rules and associativity
+  - `^`: raise to the power, e.g. `2^3` (= 8)
 - boolean operators
-  - `&&', `||`, `><`: boolean and, or, xor
+  - `&&`, `||`, `><`: boolean and, or, xor
   - `!`: boolean not
 - string operators
-  - '+': string concatenation
+  - `+`: string concatenation
 
 ### Functions
 
@@ -125,7 +350,7 @@ An expression can be
 
 #### comparison functions
 
-`equals(a,b)`, `greaterThan(a,b)`, `greaterThanOrEquals(a,b)`, `lessThan(a,b)`, `lessThanOrEqual(a,b)`",
+`equals(a,b)`, `greaterThan(a,b)`, `greaterThanOrEqual(a,b)`, `lessThan(a,b)`, `lessThanOrEqual(a,b)`
 
 #### boolean operator functions
 
@@ -135,11 +360,11 @@ An expression can be
 
 `contains(string, pattern)`, e.g. `contains('hello world', 'he*o')` returns true if the string contains the pattern. `*` matches any number of characters.
 
-`regexContains(string, regex)`, e.g. `regexContains('hello, world', 'h[aeiou]ll[aeiou]+\\\s')` returns true if the string contains the regular expression.
+`regexContains(string, regex)`, e.g. `regexContains('hello, world', 'h[aeiou]ll[aeiou]+\\s')` returns true if the string contains the regular expression.
 
 `matches(string, pattern)`, e.g. `matches('hello world', 'he*o')` returns true if the whole string matches the pattern. `*` matches any number of characters.
 
-`regexMatches(string, regex)`, e.g. `regexMatches('hello, world', 'h[aeiou]ll[aeiou]+\\\s')` returns true if the whole string matches the regular expression.
+`regexMatches(string, regex)`, e.g. `regexMatches('hello, world', 'h[aeiou]ll[aeiou]+\\s')` returns true if the whole string matches the regular expression.
 
 #### string replacement
 
@@ -149,20 +374,20 @@ An expression can be
 
 #### ifc object accessor functions
 
-`property(object: ifcPropertySetRef|ifcTypeObjectRef|ifcElementRef, name: string)`: returns an `ifcPropertyRef` or an error or an error if object has no property with that name
+`property(object: ifcPropertySetRef|ifcTypeObjectRef|ifcElementRef, name: string)`: returns an `ifcPropertyRef` or an error if object has no property with that name
 
 `propertySet(object: ifcProperty)`: returns an `ifcPropertySetRef`
 
-`propertySet(object: ifcTypeObjectRef|ifcElementRef, name: string)`: returns an `ifcPropertySetRef` or an error if the element or type has no property set with that name.
+`propertySet(object: ifcTypeObjectRef|ifcElementRef, name: string)`: returns an `ifcPropertySetRef` or an error if the element or type has no property set with that name
 
-`type(object: ifcElementRef)`: returns an `ifcTypeObjectRef` or an error.
+`type(object: ifcElementRef)`: returns an `ifcTypeObjectRef` or an error
 
-`exists(object: ifcObjectRef): boolean` check whether an object reference obtained by the above methods actually exists (suppresses the error they generate)
+`exists(object: ifcObjectRef): boolean`: checks whether an object reference obtained by the above methods actually exists (suppresses the error they generate)
 
-#### Translation and condition functions
+#### translation and condition functions
 
-`map(input, mapping: [[in, out], [in, out], ... ], default)`: finds the first `[in,out]` pair in the specified mapping where `in == input` and returns that pair's `out` value. If none is found, `default` is returned.
+`map(input, mapping: [[in, out], [in, out], ...], default)`: finds the first `[in, out]` pair in the specified mapping where `in == input` and returns that pair's `out` value. If none is found, `default` is returned.
 
 `if(condition, thenValue, elseValue)`: returns `thenValue` if `condition` is `true`, `elseValue` otherwise.
 
-`choose([[condition, out], [condition, out], ... ], default)`: finds the first `[condition, out]` pair where `condition == true` and returns its `out` value. In none is found, `default` is returned.
+`choose([[condition, out], [condition, out], ...], default)`: finds the first `[condition, out]` pair where `condition == true` and returns its `out` value. If none is found, `default` is returned.

package/dist/IfcExpression.d.ts

@@ -1,4 +1,5 @@
-import { ErrorListener, ParserRuleContext, Token } from "antlr4";
+import { ANTLRErrorListener, ParserRuleContext } from "antlr4ng";
+import Decimal from "decimal.js";
 import { ExprCompiler } from "./compiler/ExprCompiler.js";
 import { IfcExpressionErrorListener } from "./IfcExpressionErrorListener.js";
 import { isNullish, isPresent } from "./util/IfcExpressionUtils.js";
@@ -16,7 +17,7 @@ import { IfcPropertyAccessor } from "./context/IfcPropertyAccessor.js";
 import { IfcRootObjectAccessor } from "./context/IfcRootObjectAccessor.js";
 import { IfcTypeObjectAccessor } from "./context/IfcTypeObjectAccessor.js";
 import { NamedObjectAccessor } from "./context/NamedObjectAccessor.js";
-import IfcExpressionVisitor from "./gen/parser/IfcExpressionVisitor.js";
+import { IfcExpressionVisitor } from "./gen/parser/IfcExpressionVisitor.js";
 import { ObjectAccessor } from "./context/ObjectAccessor.js";
 import { IfcExpressionEvaluationException } from "./expression/IfcExpressionEvaluationException.js";
 import type { ExpressionValue } from "./value/ExpressionValue.js";
@@ -37,41 +38,38 @@ import { SimpleType } from "./type/SimpleType.js";
 import { TupleType } from "./type/TupleType.js";
 import { TypeDisjunction } from "./type/TypeDisjunction.js";
 import { Types } from "./type/Types.js";
-export { IfcElementAccessor, IfcExpressionContext, Value, StringValue, BooleanValue, LogicalValue, NumericValue, ExpressionValue, ReferenceValue, IfcDateValue, IfcDateTimeValue, IfcTimeValue, IfcDurationValue, IfcTimeStampValue, IfcPropertySetAccessor, IfcPropertyAccessor, IfcRootObjectAccessor, IfcTypeObjectAccessor, NamedObjectAccessor, ObjectAccessor, Expr, ExprCompiler, ExprKind, IfcExpressionEvaluationException, IfcExpressionErrorListener, IfcExpressionVisitor, isPresent, isNullish, ExprEvalResult, ExprEvalError, isExprEvalError, isExprEvalSuccess, ExprToTextInputLinker, ExprFacade, ArrayType, ExprType, SimpleType, TupleType, TypeDisjunction, Types, };
-export type { BoxedValueTypes };
+import { ContextObjectType } from "./type/ContextObjectType.js";
+import { BuiltinVariableRegistry } from "./builtin/BuiltinVariableRegistry.js";
+import { IfcExpressionOptions } from "./IfcExpressionOptions.js";
+import { IfcExpressionAutocomplete } from "./autocomplete/IfcExpressionAutocomplete.js";
+import type { CompletionItem, CompletionResult } from "./autocomplete/CompletionItem.js";
+import type { IfcExpressionAutocompleteOptions } from "./autocomplete/IfcExpressionAutocomplete.js";
+export { IfcElementAccessor, IfcExpressionContext, Value, StringValue, BooleanValue, LogicalValue, NumericValue, ExpressionValue, ReferenceValue, IfcDateValue, IfcDateTimeValue, IfcTimeValue, IfcDurationValue, IfcTimeStampValue, IfcPropertySetAccessor, IfcPropertyAccessor, IfcRootObjectAccessor, IfcTypeObjectAccessor, NamedObjectAccessor, ObjectAccessor, Expr, ExprCompiler, ExprKind, IfcExpressionEvaluationException, IfcExpressionErrorListener, IfcExpressionVisitor, isPresent, isNullish, ExprEvalResult, ExprEvalError, isExprEvalError, isExprEvalSuccess, ExprToTextInputLinker, ExprFacade, ArrayType, ExprType, SimpleType, TupleType, TypeDisjunction, Types, ContextObjectType, BuiltinVariableRegistry, IfcExpressionAutocomplete, };
+export type { BoxedValueTypes, IfcExpressionOptions, CompletionItem, CompletionResult, IfcExpressionAutocompleteOptions, };
+export type UnwrappedExpressionValue = string | boolean | Decimal | undefined | UnwrappedExpressionValue[] | {
+    [key: string]: UnwrappedExpressionValue;
+};
 export declare class IfcExpressionParseResult {
     private readonly _input;
     private readonly _typeManager;
     private readonly _parseTree;
-    constructor(input: string, typeManager: TypeManager, exprContext: any);
+    private readonly _builtinVariableRegistry;
+    constructor(input: string, typeManager: TypeManager, exprContext: any, builtinVariableRegistry: BuiltinVariableRegistry);
     get typeManager(): TypeManager;
     get parseTree(): ParserRuleContext;
     get input(): string;
+    get builtinVariableRegistry(): BuiltinVariableRegistry;
 }
 export declare class IfcExpression {
-    /**
-     * Parses the input and returns a parse result, which contains the parse tree, the type information per parse tree node, and the input.
-     * @param input
-     * @param errorListener
-     * @return the parse result, which can subequently be compiled into an Expr using compile().
-     */
-    static parse(input: string, errorListener?: ErrorListener<Token | number>): IfcExpressionParseResult;
-    /**
-     * Compiles the specified parseResult into an Expr.
-     * @param parseResult
-     * @return the Expression (Expr), which can be evaluated to obtain its result.
-     */
+    static parse(input: string, errorListener?: ANTLRErrorListener, options?: IfcExpressionOptions): IfcExpressionParseResult;
     static compile(parseResult: IfcExpressionParseResult): ExprFacade<ExpressionValue>;
-    /**
-     * Evaluates the specified input expression and returns the evaluation result. The parse
-     * and compile steps are done internally.
-     *
-     * @param expression: the input expression
-     * @param context: the context required for accessing the IFC model
-     * @return the result (or an error object).
-     */
-    static evaluate(expression: string, context?: IfcExpressionContext): ExprEvalResult<ExpressionValue>;
+    static evaluate(expression: string, context?: IfcExpressionContext, options?: IfcExpressionOptions): ExprEvalResult<ExpressionValue>;
     static formatError(input: string, error: ExprEvalError): string;
     private static indent;
     static evaluateExpression(expr: ExprFacade<ExpressionValue>, context?: IfcExpressionContext): ExprEvalResult<ExpressionValue>;
+    static unwrapValue(value: ExpressionValue): UnwrappedExpressionValue;
+    private static unwrapUnknownValue;
+    private static unwrapObjectAccessor;
+    private static unwrapPlainObject;
+    private static isPlainObject;
 }

package/dist/IfcExpressionErrorListener.d.ts

@@ -1,10 +1,10 @@
-import { ErrorListener, RecognitionException, Recognizer, Token } from "antlr4";
+import { BaseErrorListener, RecognitionException, Recognizer, Token } from "antlr4ng";
 import { SyntaxErrorException } from "./error/SyntaxErrorException.js";
 import { ValidationException } from "./error/ValidationException.js";
-export declare class IfcExpressionErrorListener extends ErrorListener<Token | number> {
+export declare class IfcExpressionErrorListener extends BaseErrorListener {
     private exception;
     validationException(validationException: ValidationException): void;
-    syntaxError(recognizer: Recognizer<Token | number>, offendingSymbol: Token | number, line: number, column: number, msg: string, e: RecognitionException | undefined): void;
+    syntaxError<S extends Token, T extends import("antlr4ng").ATNSimulator>(recognizer: Recognizer<T>, offendingSymbol: S | null, line: number, column: number, msg: string, e: RecognitionException | null): void;
     isErrorOccurred(): boolean;
     getException(): SyntaxErrorException | ValidationException;
 }

package/dist/IfcExpressionOptions.d.ts

@@ -0,0 +1,4 @@
+import { BuiltinVariableRegistry } from "./builtin/BuiltinVariableRegistry.js";
+export interface IfcExpressionOptions {
+    builtinVariableRegistry?: BuiltinVariableRegistry;
+}

package/dist/autocomplete/CompletionItem.d.ts

@@ -0,0 +1,24 @@
+export type CompletionItemKind = "builtinRoot" | "builtinFunction" | "builtinMemberProperty" | "builtinMemberFunction";
+export type CompletionItem = {
+    kind: CompletionItemKind;
+    label: string;
+    insertText?: string;
+    cursorOffset?: number;
+    argumentTypeNames?: Array<string>;
+    returnTypeName?: string;
+    chainable?: boolean;
+    documentation?: string;
+};
+export type ActiveHelp = {
+    label: string;
+    documentation: string;
+    activeParameterIndex?: number;
+    activeParameterLabel?: string;
+    activeParameterDocumentation?: string;
+};
+export type CompletionResult = {
+    items: Array<CompletionItem>;
+    replaceFrom: number;
+    replaceTo: number;
+    activeHelp?: ActiveHelp;
+};

package/dist/autocomplete/IfcExpressionAutocomplete.d.ts

@@ -0,0 +1,11 @@
+import { BuiltinVariableRegistry } from "../builtin/BuiltinVariableRegistry.js";
+import { CompletionResult } from "./CompletionItem.js";
+import { DocumentationLocalizer } from "../documentation/Documentation.js";
+export type IfcExpressionAutocompleteOptions = {
+    builtinVariableRegistry?: BuiltinVariableRegistry;
+    localizer?: DocumentationLocalizer;
+    emptyExpressionStarters?: Array<string>;
+};
+export declare class IfcExpressionAutocomplete {
+    static complete(input: string, cursorOffset: number, options?: IfcExpressionAutocompleteOptions): CompletionResult;
+}

package/dist/builtin/BuiltinRuntimeValueConverter.d.ts

@@ -0,0 +1,7 @@
+import { ExprType } from "../type/ExprType.js";
+import { ExpressionValue } from "../value/ExpressionValue.js";
+import { ContextObjectValue } from "../value/ContextObjectValue.js";
+export declare function toExpressionValue(value: unknown, expectedType: ExprType): ExpressionValue;
+export declare function inferExpressionValue(value: unknown, fallbackType?: ExprType): ExpressionValue;
+export declare function unwrapExpressionValue(value: ExpressionValue): unknown;
+export declare function getBuiltinMemberValue(value: ContextObjectValue, memberName: string): unknown;

package/dist/builtin/BuiltinVariableRegistry.d.ts

@@ -0,0 +1,50 @@
+import { ExprType } from "../type/ExprType.js";
+import { Expr } from "../expression/Expr.js";
+import { ArgumentDocumentation, LocalizedText } from "../documentation/Documentation.js";
+export type BuiltinPropertyDefinition = {
+    name: string;
+    kind: "property";
+    valueType: ExprType;
+    documentation?: LocalizedText;
+};
+export type BuiltinFunctionDefinition = {
+    name: string;
+    kind: "function";
+    returnType: ExprType;
+    argumentTypes: Array<ExprType>;
+    documentation?: LocalizedText;
+    argumentDocumentation?: Array<ArgumentDocumentation>;
+};
+export type BuiltinMemberDefinition = BuiltinPropertyDefinition | BuiltinFunctionDefinition;
+export declare function isBuiltinPropertyDefinition(definition: BuiltinMemberDefinition | undefined): definition is BuiltinPropertyDefinition;
+export declare function isBuiltinFunctionDefinition(definition: BuiltinMemberDefinition | undefined): definition is BuiltinFunctionDefinition;
+export type BuiltinVariableDefinition = {
+    name: string;
+    type?: ExprType;
+    documentation?: LocalizedText;
+    members?: Array<BuiltinMemberDefinition>;
+    createReferenceExpr?: () => Expr<any>;
+};
+export type RegisteredBuiltinVariableDefinition = {
+    name: string;
+    type: ExprType;
+    documentation?: LocalizedText;
+    members: Map<string, BuiltinMemberDefinition>;
+    createReferenceExpr: () => Expr<any>;
+};
+export declare class BuiltinVariableRegistry {
+    private static readonly defaultRegistry;
+    private readonly builtinVariables;
+    constructor(definitions?: Array<BuiltinVariableDefinition>);
+    static getDefaultRegistry(): BuiltinVariableRegistry;
+    static normalizeName(name: string): string;
+    static isBuiltinVariable(name: string): boolean;
+    static isReservedName(name: string): boolean;
+    static getDefinition(name: string): RegisteredBuiltinVariableDefinition | undefined;
+    isBuiltinVariable(name: string): boolean;
+    isReservedName(name: string): boolean;
+    getDefinition(name: string): RegisteredBuiltinVariableDefinition | undefined;
+    getDefinitions(): Array<RegisteredBuiltinVariableDefinition>;
+    private register;
+    private registerMembers;
+}