@adaptabletools/adaptable 23.1.0-canary.2 → 24.0.0-canary.0

package/vendor/aql/api/QueryLanguageApi.d.ts

@@ -0,0 +1,213 @@
+import { type MigrateOptions, type NormalizeOptions } from '../normalize/normalizeAst';
+import { type MigrateExpressionResult } from '../normalize/migrateExpression';
+import { type HostExpressionContext, type HostExpressionContextConfig } from '../host/createHostExpressionContext';
+import type { AqlHost } from '../host/types';
+import type { AST, AST_Function, ExpressionFunctionMap, InternalExpressionContext, Token } from '../types';
+import { type AqlValidationResult, type ValidateAqlExpressionOptions } from '../validation/validateAqlExpression';
+import { type CompileValueExpressionOptions } from '../plan/compile';
+import { type AggregationCatalogue } from '../plan/catalogue';
+import { type ValueDeltaConfig, type ValueExecutionConfig } from '../plan/execute';
+import { type ValuePlanTrace } from '../plan/trace';
+import type { CompiledValueExpression, ValueDeltaChange, ValueExecutionResult } from '../plan/types';
+import type { OperatorRegistry } from '../plan/operators';
+import type { AqlCellValueOverride } from '../host/createHostExpressionContext';
+import type { Clock } from '../store/history/clock';
+import type { HistoryReader } from '../store/history/types';
+export interface QueryLanguageValidationResult {
+    isValid: boolean;
+    errorMessage: string;
+}
+/**
+ * Per-call evaluation inputs — everything from `HostExpressionContextConfig`
+ * except `host`/`functions` (bound by the engine instance). Host extras go
+ * in `ext` and are preserved through context derivation.
+ */
+export type QueryLanguageEvaluationConfig<TExt = unknown> = Omit<HostExpressionContextConfig<TExt>, 'host' | 'functions' | 'whereClauseFunctions'>;
+export type PreparedExpressionEvaluator = (rowRef?: HostExpressionContextConfig['rowRef'], config?: QueryLanguageEvaluationConfig) => any;
+/**
+ * Collects the first argument of every node with the given type — e.g.
+ * `COL` yields the referenced column ids, `QUERY` the named-query names.
+ * Pure text → parse walk; unparseable input yields `[]`.
+ */
+export declare const getNodesFromExpression: (input: string, nodeType: string) => string[];
+export interface QueryLanguageApiConfig {
+    host: AqlHost;
+    /** Scalar pool: boolean predicates + scalar functions. */
+    scalarFunctions: ExpressionFunctionMap<any>;
+    /**
+     * Additional host-registered aggregation names that have no operator in
+     * `operatorRegistry` (rare). Names of the registry's custom operators are
+     * always known. Forwarded to `migrateExpression` so leftover paren calls
+     * (`MY_VWAP([price])`) rewrite to `AGG_CALL` the same way system
+     * aggregation-only names do.
+     */
+    customAggregatedNames?: Iterable<string>;
+    /**
+     * Aggregation operators (system + host-registered custom). Used by
+     * compile / execute / validation when the caller does not pass an
+     * override; also the source of the aggregation catalogue.
+     */
+    operatorRegistry?: OperatorRegistry;
+    /**
+     * Per-cell change history for `OBSERVABLE_CALL` evaluation. Bound to every
+     * evaluation context and value-plan execution this engine creates.
+     */
+    history?: HistoryReader;
+    /** Clock for time-volatile scalars; defaults to the system clock. */
+    clock?: Clock;
+    /** Host-registered observable names beyond the system Tier 1 set. */
+    customObservableNames?: Iterable<string>;
+}
+/**
+ * Host-bound AQL engine: parse / AST / token helpers, scalar evaluation,
+ * and value-plan compile → execute for aggregations.
+ *
+ * Hosts with richer needs (per-module pools, validation caches, custom
+ * function resolution — e.g. Adaptable's `QueryLanguageService`) compose
+ * these primitives rather than replacing them.
+ */
+export declare class QueryLanguageApi {
+    private config;
+    private readonly catalogue;
+    constructor(config: QueryLanguageApiConfig);
+    private customAggregatedNames;
+    private customObservableNames;
+    private mergeNormalizeOptions;
+    /** Execution config shared by every value-plan entry point. */
+    private baseExecutionConfig;
+    get host(): AqlHost;
+    private readonly scalarAstCache;
+    /**
+     * AST the scalar evaluator runs: the raw parse for plain scalar text
+     * (unchanged behaviour), the runtime-normalized tree when the text carries
+     * a brace call — that is what turns `CHANGE_COUNT{…}` into a
+     * `OBSERVABLE_CALL` the evaluator can read. LRU-bounded per engine.
+     */
+    private scalarAst;
+    private evaluateScalarAst;
+    /** The aggregation catalogue this engine compiles and validates against. */
+    get aggregationCatalogue(): AggregationCatalogue;
+    parse(expression: string): {
+        ast: AST;
+        evaluate: (context: InternalExpressionContext) => any;
+    };
+    getAbstractSyntaxTree(expression: string): AST;
+    getTokens(expression: string): Token[];
+    /**
+     * Contract-v2 AST: parse + runtime normalize (greenfield surface only).
+     * Leftover legacy spellings are not rewritten — use {@link migrateExpression}.
+     */
+    getNormalizedAst(expression: string, options?: NormalizeOptions): AST;
+    /** Runtime-normalizes an already-parsed AST (pure, idempotent). */
+    normalizeAbstractSyntaxTree(ast: AST, options?: NormalizeOptions): AST;
+    /** Canonical printing of an AST (the A-3 printer). */
+    printAbstractSyntaxTree(ast: AST): string;
+    /**
+     * Greenfield pretty-print: `print ∘ normalize ∘ parse`. Does not rewrite
+     * leftover legacy spellings — use {@link migrateExpression}.
+     */
+    getCanonicalExpression(expression: string, options?: NormalizeOptions): string;
+    /**
+     * Convert a (possibly legacy) expression to canonical greenfield text.
+     * This is the only supported way to accept leftover paren aggregations,
+     * `CUMUL`, legacy observable sources (`rewriteLegacyObservables`), `COL()` /
+     * `NULL()` / `$SCOPE()`.
+     */
+    migrateExpression(expression: string, options?: MigrateOptions): MigrateExpressionResult;
+    /**
+     * Structural validation: runtime-normalizes, classifies and runs the
+     * guard rails + clause/operand checks against the engine's scalar pool. Leftover legacy spellings are errors.
+     */
+    validateExpressionStructure(expression: string, options?: ValidateAqlExpressionOptions): AqlValidationResult;
+    createContext(functions: ExpressionFunctionMap<any>, config?: QueryLanguageEvaluationConfig, whereClauseFunctions?: ExpressionFunctionMap<any>): HostExpressionContext;
+    evaluateBooleanExpression(expression: string, config?: QueryLanguageEvaluationConfig): any;
+    /** Scalar and boolean expressions evaluate identically (single namespace). */
+    evaluateScalarExpression(expression: string, config?: QueryLanguageEvaluationConfig): any;
+    /**
+     * Builds the host context once and returns a function that rebinds `rowRef`
+     * (and optional per-call overrides) on each invocation. Use this for
+     * per-row loops — grid filters, calculated columns — instead of calling
+     * {@link evaluateBooleanExpression} per row.
+     *
+     * Observable calls are pure history reads and are safe here. Nested
+     * evaluation of the *same* prepared function falls back to a fresh
+     * context so `rowRef` is not clobbered.
+     */
+    prepareBooleanEvaluator(expression: string, config?: QueryLanguageEvaluationConfig): PreparedExpressionEvaluator;
+    /** Scalar and boolean expressions share a namespace; see {@link prepareBooleanEvaluator}. */
+    prepareScalarEvaluator(expression: string, config?: QueryLanguageEvaluationConfig): PreparedExpressionEvaluator;
+    /**
+     * Compiles a value expression (pure scalar, pure aggregated, mixed) to a
+     * {@link CompiledValueExpression} — pure data, no evaluation, no context
+     * capture. The expression must already be greenfield (migrate first).
+     */
+    compileValueExpression(expression: string, options?: CompileValueExpressionOptions & {
+        normalize?: NormalizeOptions;
+    }): CompiledValueExpression;
+    private readonly dependenciesCache;
+    /**
+     * What an expression depends on — columns, row set, and whether it reads
+     * history (`observable`), can change by window expiry (`windowed`) or reads
+     * the clock (`time`). Compiles once per expression text and caches.
+     */
+    getExpressionDependencies(expression: string): CompiledValueExpression['dependencies'];
+    /**
+     * Executes a compiled value plan (or compiles the expression first)
+     * against the bound host. One host pass per scan signature group; window
+     * and cumulative operators record per-row values during the scan.
+     */
+    executeValueExpression(expression: string | CompiledValueExpression, config?: QueryLanguageEvaluationConfig, execOptions?: Partial<ValueExecutionConfig> & {
+        normalize?: NormalizeOptions;
+    }): ValueExecutionResult;
+    /**
+     * Executes several compiled plans as ONE batch: aggregation plans from all
+     * expressions join a shared signature-grouped scan pool, so expressions
+     * over the same row set share a single host row pass (the computed-value
+     * store's cross-node scan grouping). Results are in input order.
+     */
+    executeValueExpressionBatch(compiledExpressions: readonly CompiledValueExpression[], config?: QueryLanguageEvaluationConfig, execOptions?: Partial<ValueExecutionConfig>): ValueExecutionResult[];
+    /**
+     * Incremental re-execution for cell changes — see
+     * {@link applyValueExpressionDelta}. `undefined` means the expression is
+     * not delta-eligible for these changes and must be re-executed.
+     */
+    applyValueExpressionDelta(compiled: CompiledValueExpression, previous: ValueExecutionResult, changes: readonly ValueDeltaChange[], config?: QueryLanguageEvaluationConfig, deltaOptions?: Partial<ValueDeltaConfig>): ValueExecutionResult | undefined;
+    /** Structured rendering of a compiled plan (tracing / support surface). */
+    describeValuePlan(compiled: CompiledValueExpression): ValuePlanTrace;
+    /**
+     * Aggregated-boolean reading of an already-executed plan. Ungrouped
+     * expressions use the outer value; a single grouped aggregation is true
+     * when any group's aggregate satisfies the outer boolean.
+     */
+    isAggregatedBooleanSatisfied(compiled: CompiledValueExpression, result: ValueExecutionResult): boolean;
+    /**
+     * Whether `rowRef` is inside any aggregation scan (WHERE / statement
+     * filter). Used as the Alert cheap-gate.
+     */
+    rowMatchesCompiledFilters(compiled: CompiledValueExpression, rowRef: unknown, options?: {
+        cellValueOverride?: AqlCellValueOverride;
+        ext?: unknown;
+    }): boolean;
+    validateBooleanExpression(expressionInput?: string): QueryLanguageValidationResult;
+    /**
+     * Why the root node of a boolean expression is not a predicate, or
+     * `undefined` when it is. `COL` and `QUERY` are returnType `any` so they
+     * can be scalar operands; as a boolean *root* the host column / named
+     * query itself must be boolean, read through `host.getColumn` and
+     * `host.namedQueries`. Hosts that orchestrate their own validation
+     * pipeline (caches, cycle checks) call this instead of re-implementing it.
+     */
+    getBooleanRootError(rootFn: AST_Function): string | undefined;
+    /**
+     * Collects the first argument of every node with the given type — e.g.
+     * `COL` yields the referenced column ids, `QUERY` the named-query names.
+     */
+    getNodesFromExpression(input: string, nodeType: string): string[];
+    getColumnsFromExpression(input?: string): string[];
+    getNamedQueryNamesFromExpression(input?: string): string[];
+}
+export declare const createQueryLanguageApi: (config: QueryLanguageApiConfig) => QueryLanguageApi;
+/** Preferred name for the host-bound engine (`QueryLanguageApi`). */
+export type AqlEngine = QueryLanguageApi;
+export declare const createAqlEngine: (config: QueryLanguageApiConfig) => QueryLanguageApi;
+//# sourceMappingURL=QueryLanguageApi.d.ts.map

package/vendor/aql/api/QueryLanguageApi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueryLanguageApi.d.ts","sourceRoot":"","sources":["../../../src/api/QueryLanguageApi.ts"],"names":[],"mappings":"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"}