fig-tree-evaluator 2.23.2 → 3.0.0-preview.2

package/build/index.d.ts

@@ -1,279 +1,822 @@
-/// <reference types="node" />
-import { Client } from 'pg';
-import { Database } from 'sqlite';
-import { AxiosStatic } from 'axios';
-import { RequestInfo, RequestInit, Response } from 'node-fetch';
-export { dequal } from 'dequal/lite';
-
-interface CacheOptions {
-    maxSize?: number;
-    maxTime?: number;
-}
-interface Store {
-    [key: string]: {
-        result: EvaluatorOutput;
-        timestamp: number;
-    };
+declare const version = "3.0.0-preview.2";
+
+interface HttpRequest {
+    url: string;
+    method: 'get' | 'post';
+    headers: Record<string, string>;
+    body?: unknown;
+    signal: AbortSignal;
 }
-declare class FigTreeCache {
-    private store;
-    private queue;
-    private maxSize;
-    private maxTime;
-    constructor(options?: CacheOptions);
-    useCache: (shouldUseCache: boolean, action: UnknownFunction, ...args: unknown[]) => Promise<EvaluatorOutput>;
-    getMax: () => number;
-    setMax: (size: number) => void;
-    getMaxTime: () => number;
-    setMaxTime: (time: number) => void;
-    getCache: () => Store;
-    setCache: (cache: Store) => Store;
-    private resizeCache;
-}
-
-interface QueryInput {
-    query: string;
-    values?: (string | number | boolean)[] | object;
-    single?: boolean;
-    flatten?: boolean;
-}
-type QueryOutput = Exclude<EvaluatorOutput, undefined>;
-interface SQLConnection {
-    query: (input: QueryInput) => Promise<QueryOutput>;
-}
-
-type BasicType = 'any' | 'string' | 'boolean' | 'number' | 'array' | 'object' | 'null' | 'undefined';
-type LiteralType = {
-    literal: (string | undefined)[];
-};
-type ExpectedType = BasicType | LiteralType | BasicType[];
-type TypeCheckInput = {
-    name?: string;
-    value: unknown;
-    expectedType: ExpectedType;
+interface HttpClient {
+    request(req: HttpRequest): Promise<unknown>;
+}
+interface SqlRequest {
+    text: string;
+    values?: unknown[] | Record<string, unknown>;
+    signal?: AbortSignal;
+}
+interface SqlConnection {
+    query(req: SqlRequest): Promise<Record<string, unknown>[]>;
+}
+interface CacheStore {
+    get(key: string): unknown | Promise<unknown>;
+    set(key: string, value: unknown): void;
+    delete(key: string): void;
+    clear(): void;
+}
+
+type FigTreeErrorCode = string;
+declare const ErrorCodes: {
+    readonly unknownOperator: "unknown-operator";
+    readonly typeCheck: "type-check";
+    readonly operatorFailure: "operator-failure";
+    readonly timeout: "timeout";
+    readonly requestTimeout: "request-timeout";
+    readonly aborted: "aborted";
+    readonly unknownNodeKey: "unknown-node-key";
+    readonly unresolvedVar: "unresolved-var";
+    readonly unrecognizedIdentifier: "unrecognized-identifier";
+    readonly depthCeiling: "depth-ceiling";
+    readonly nonFiniteResult: "non-finite-result";
+    readonly escapedHandle: "escaped-handle";
+    readonly emptyAggregate: "empty-aggregate";
+    readonly malformedNode: "malformed-node";
+    readonly unknownFragment: "unknown-fragment";
+    readonly positionalArity: "positional-arity";
+    readonly invalidVars: "invalid-vars";
+    readonly invalidReference: "invalid-reference";
+    readonly uselessModifier: "useless-modifier";
+    readonly unreferencedVar: "unreferenced-var";
+    readonly missingRequired: "missing-required";
+    readonly unresolvedParam: "unresolved-param";
+    readonly unresolvedBinding: "unresolved-binding";
+    readonly deadBinding: "dead-binding";
+    readonly invalidAs: "invalid-as";
+    readonly maxDepthExceeded: "max-depth";
+    readonly maxNodesExceeded: "max-nodes";
+    readonly returnsMismatch: "returns-mismatch";
+    readonly operatorValidate: "operator-validate";
+    readonly missingDataPath: "missing-data-path";
+    readonly shadowedVar: "shadowed-var";
+    readonly varCycle: "var-cycle";
+    readonly bareVars: "bare-vars";
+    readonly fragmentCycle: "fragment-cycle";
+    readonly unboundToken: "unbound-token";
+    readonly unusedSubstitution: "unused-substitution";
+    readonly tokenRenumber: "token-renumber";
+    readonly inertReferenceToken: "inert-reference-token";
+    readonly invalidDefinition: "invalid-definition";
+    readonly invalidName: "invalid-name";
+    readonly reservedName: "reserved-name";
+    readonly invalidNullPolicy: "invalid-null-policy";
+    readonly duplicateOperator: "duplicate-operator";
+    readonly invalidOptions: "invalid-options";
 };
 
-interface HttpClient {
-    get: (req: Omit<HttpRequest, 'method'>) => Promise<unknown>;
-    post: (req: Omit<HttpRequest, 'method'>) => Promise<unknown>;
-    throwError: (err: unknown) => void;
+type Severity = 'error' | 'warning' | 'hint';
+interface Issue {
+    severity: Severity;
+    code: FigTreeErrorCode;
+    message: string;
+    path: (string | number)[];
+    operator?: string;
+    fragment?: string;
+    parameter?: string;
+    suggestion?: string;
 }
-interface HttpRequest {
-    url: string;
-    params?: {
-        [key: string]: string;
-    };
-    data?: Record<string, unknown>;
-    headers?: Record<string, unknown>;
-    method?: 'get' | 'post';
+interface ValidationResult {
+    valid: boolean;
+    issues: Issue[];
+    timeoutShielded: boolean;
 }
 
-interface GraphQLConnection {
-    endpoint: string;
-    headers?: {
-        [key: string]: string;
+declare const LAZY_HANDLE: unique symbol;
+interface LazyValue<T = unknown> {
+    readonly [LAZY_HANDLE]: true;
+    evaluate(): Promise<T>;
+}
+interface Settlement {
+    index: number;
+    ok: boolean;
+    value?: unknown;
+    error?: unknown;
+}
+type SettlementStream = AsyncIterable<Settlement> & {
+    readonly [LAZY_HANDLE]: true;
+    length: number;
+};
+interface PerElement<T = unknown> {
+    readonly [LAZY_HANDLE]: true;
+    evaluate(index: number): Promise<T>;
+    settle(): SettlementStream;
+}
+type TraceEvent = {
+    type: string;
+    [key: string]: unknown;
+};
+interface OperatorContext {
+    signal: AbortSignal;
+    options: Readonly<EvaluationOptions>;
+    cache: {
+        memo<T>(key: unknown, fn: () => Promise<T>): Promise<T>;
+    };
+    trace: {
+        note(event: TraceEvent): void;
     };
-    httpClient?: HttpClient;
 }
 
-declare const operatorAliases: OperatorAliases;
-
-declare const Operators: readonly ["AND", "OR", "EQUAL", "NOT_EQUAL", "PLUS", "SUBTRACT", "MULTIPLY", "DIVIDE", "GREATER_THAN", "LESS_THAN", "CONDITIONAL", "REGEX", "OBJECT_PROPERTIES", "STRING_SUBSTITUTION", "SPLIT", "COUNT", "GET", "POST", "SQL", "GRAPHQL", "BUILD_OBJECT", "MATCH", "CUSTOM_FUNCTIONS", "PASSTHRU"];
-type Operator = (typeof Operators)[number];
-type OperatorAlias = keyof typeof operatorAliases;
-type OperatorAliases = Record<string, Operator>;
-type Fragments = Record<string, Fragment>;
-type UnknownFunction = (...args: any[]) => EvaluatorOutput;
-interface FigTreeOptions {
-    data?: Record<string, unknown>;
-    objects?: Record<string, unknown>;
-    functions?: Record<string, UnknownFunction | FunctionDefinition>;
-    fragments?: Fragments;
-    httpClient?: HttpClient;
-    graphQLConnection?: GraphQLConnection;
-    sqlConnection?: SQLConnection;
-    baseEndpoint?: string;
-    headers?: {
-        [key: string]: string;
-    };
-    returnErrorAsString?: boolean;
-    nullEqualsUndefined?: boolean;
-    caseInsensitive?: boolean;
-    allowJSONStringInput?: boolean;
-    noShorthand?: boolean;
-    skipRuntimeTypeCheck?: boolean;
-    evaluateFullObject?: boolean;
-    excludeOperators?: OperatorAlias[];
-    useCache?: boolean;
-    maxCacheSize?: number;
-    maxCacheTime?: number;
-    supportDeprecatedValueNodes?: boolean;
-}
-interface FigTreeConfig {
-    options: FigTreeOptions;
-    operators: OperatorReference;
-    operatorAliases: OperatorAliases;
-    typeChecker: (...args: TypeCheckInput[] | [TypeCheckInput[]]) => void;
-    resolvedAliasNodes: {
-        [key: string]: EvaluatorOutput;
+type TraceStatus = 'value' | 'failed' | 'fallback' | 'cancelled' | 'skipped';
+type TraceKind = 'operator' | 'fragment' | 'reference' | 'literal' | 'skeleton';
+interface TraceNode {
+    path: (string | number)[];
+    source?: {
+        fragment: string;
     };
-    cache: FigTreeCache;
-    httpClient?: HttpClient;
-    graphQLClient?: HttpClient;
-}
-type OutputType = 'string' | 'number' | 'boolean' | 'bool' | 'array';
-interface OperatorNode {
-    operator: OperatorAlias;
-    outputType?: OutputType;
-    children?: EvaluatorNode[];
-    fallback?: EvaluatorNode;
-    useCache?: boolean;
-    [key: string]: EvaluatorNode;
+    kind: TraceKind;
+    operator?: string;
+    ref?: string;
+    var?: string;
+    status: TraceStatus;
+    value?: unknown;
+    error?: FigTreeError;
+    events?: TraceEvent[];
+    children?: TraceNode[];
+    elapsed?: number;
+    warnings?: Issue[];
 }
-interface FragmentNode {
-    fragment: string;
-    parameters?: Record<string, EvaluatorNode>;
-    [key: string]: EvaluatorNode;
+interface CacheTraceEvent {
+    type: 'cache';
+    hit: boolean;
 }
-interface FragmentData {
-    description?: string;
-    parameters?: FragmentParameterMetadata[];
-    textColor?: string;
-    backgroundColor?: string;
+interface RequestTraceEvent {
+    type: 'request';
+    method: string;
+    url: string;
+    headers: string[];
 }
-interface FunctionDefinition {
-    function: UnknownFunction;
-    description?: string;
-    argsDefault?: unknown[];
-    inputDefault?: unknown;
-    textColor?: string;
-    backgroundColor?: string;
-}
-type Fragment = (EvaluatorNode & {
-    metadata?: FragmentData;
-}) | null;
-type EvaluatorOutput = string | boolean | number | object | null | undefined | Array<EvaluatorOutput>;
-type EvaluatorNode = OperatorNode | FragmentNode | EvaluatorOutput;
-type OperatorObject = {
-    propertyAliases: Record<string, string>;
-    operatorData: OperatorData;
-    evaluate: EvaluateMethod;
-    parseChildren: ParseChildrenMethod;
+interface QueryTraceEvent {
+    type: 'query';
+    text: string;
+}
+interface RenderTraceEvent {
+    type: 'render';
+    token: string;
+    rendered: 'literal' | 'placeholder' | 'empty' | 'gap-closed';
+}
+interface KeyOverwriteTraceEvent {
+    type: 'key-overwrite';
+    key: string;
+}
+interface ShieldedFallbackTraceEvent {
+    type: 'shielded-fallback';
+}
+type KnownTraceEvent = CacheTraceEvent | RequestTraceEvent | QueryTraceEvent | RenderTraceEvent | KeyOverwriteTraceEvent | ShieldedFallbackTraceEvent;
+
+interface FigTreeErrorInit {
+    code: FigTreeErrorCode;
+    message: string;
+    path: (string | number)[];
+    holePath?: (string | number)[];
+    operator?: string;
+    fragment?: string;
+    fragmentPath?: (string | number)[];
+    errorData?: Record<string, unknown>;
+    related?: FigTreeError[];
+    cause?: unknown;
+    issues?: Issue[];
+    trace?: TraceNode;
+}
+declare class FigTreeError extends Error {
+    code: FigTreeErrorCode;
+    path: (string | number)[];
+    holePath?: (string | number)[];
+    operator?: string;
+    fragment?: string;
+    fragmentPath?: (string | number)[];
+    errorData?: Record<string, unknown>;
+    related?: FigTreeError[];
+    cause?: unknown;
+    issues?: Issue[];
+    trace?: TraceNode;
+    constructor(init: FigTreeErrorInit);
+    prettyPrint(): string;
+}
+declare const isFigTreeError: (input: unknown) => input is FigTreeError;
+
+type BasicType = 'any' | 'string' | 'number' | 'boolean' | 'array' | 'object' | 'null' | 'integer';
+type LiteralType = {
+    literal: readonly (string | number | boolean)[];
 };
-type EvaluateMethod = (expression: OperatorNode, config: FigTreeConfig) => Promise<EvaluatorOutput>;
-type ParseChildrenMethod = (expression: OperatorNode, config: FigTreeConfig) => OperatorNode;
-type OperatorReference = {
-    [key in Operator]: OperatorObject;
+type ExpectedType = BasicType | LiteralType | readonly BasicType[];
+interface Constraints {
+    length?: number;
+    homogeneous?: readonly BasicType[];
+    elementShape?: Record<string, TypeDeclaration>;
+}
+interface TypeDeclaration {
+    type?: ExpectedType;
+    required?: boolean;
+    constraints?: Constraints;
+}
+type TypeCheckResult = {
+    ok: true;
+} | {
+    ok: false;
+    expected: string;
+    actual: string;
 };
-interface OperatorParameterMetadata {
-    name: string;
-    description: string;
-    aliases: string[];
-    required: boolean;
-    type: ExpectedType;
+
+declare const validateHelpers: Readonly<{
+    parsePath: (path: string) => PathSegment[];
+    resolvePath: (source: unknown, path: string | PathSegment[]) => ResolveResult;
+    checkType: (value: unknown, expected: ExpectedType) => TypeCheckResult;
+    checkConstraints: (value: unknown, constraints: Constraints) => TypeCheckResult;
+    describeType: (value: unknown) => string;
+    renderText: (value: unknown) => string;
+    isTruthy: (value: unknown) => boolean;
+}>;
+type ValidateHelpers = typeof validateHelpers;
+
+type TypeOf<T> = T extends 'string' ? string : T extends 'number' | 'integer' ? number : T extends 'boolean' ? boolean : T extends 'array' ? unknown[] : T extends 'object' ? Record<string, unknown> : T extends 'null' ? null : T extends 'any' ? unknown : T extends {
+    literal: readonly (infer M)[];
+} ? M : T extends readonly (infer B)[] ? TypeOf<B> : unknown;
+type DeclaredType<P> = P extends {
+    type: infer T;
+} ? T : 'any';
+type KeepsNull<P> = P extends {
+    nullPolicy: 'value';
+} ? true : P extends {
+    nullPolicy: NullPolicyValue;
+} ? false : P extends {
+    nullPolicy: (...args: any) => any;
+} ? true : false;
+type Delivered<P> = KeepsNull<P> extends true ? TypeOf<DeclaredType<P>> : Exclude<TypeOf<DeclaredType<P>>, null>;
+type Truthy<P> = P extends {
+    type: 'array';
+} ? boolean[] : P extends {
+    type: 'object';
+} ? Record<string, boolean> : boolean;
+type ParamValue<P> = P extends {
+    evaluation: 'structural';
+} ? TypeOf<DeclaredType<P>> : P extends {
+    evaluation: 'race';
+} ? SettlementStream : P extends {
+    evaluation: 'lazyElements';
+} ? LazyValue[] : P extends {
+    evaluation: 'lazyEntries';
+} ? Record<string, LazyValue> : P extends {
+    evaluation: 'perElement';
+} ? PerElement<P extends {
+    truthiness: true;
+} ? boolean : Delivered<P>> : P extends {
+    evaluation: 'lazy';
+} ? LazyValue<Delivered<P>> : P extends {
+    truthiness: true;
+} ? Truthy<P> : Delivered<P>;
+type IsHolder<P> = P extends {
+    replacesNullAt: readonly string[];
+} ? true : false;
+type IsOptional<P> = P extends {
+    default: unknown;
+} ? false : P extends {
+    required: false;
+} ? true : false;
+type BodyKeys<D> = {
+    [K in keyof D]: IsHolder<D[K]> extends true ? never : K;
+}[keyof D];
+type OptionalKeys<D> = {
+    [K in BodyKeys<D>]: IsOptional<D[K]> extends true ? K : never;
+}[BodyKeys<D>];
+type RequiredKeys<D> = Exclude<BodyKeys<D>, OptionalKeys<D>>;
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type ResolvedParams<D extends ParameterDeclarations = ParameterDeclarations> = Simplify<{
+    [K in RequiredKeys<D>]: ParamValue<D[K]>;
+} & {
+    [K in OptionalKeys<D>]?: ParamValue<D[K]>;
+}>;
+
+type EvaluationMode = 'eager' | 'race' | 'lazy' | 'lazyElements' | 'lazyEntries' | 'perElement' | 'structural';
+declare const OPERATOR_CATEGORIES: readonly ["logic", "comparison", "math", "string", "array", "data", "io", "other"];
+type OperatorCategory = (typeof OPERATOR_CATEGORIES)[number];
+type NullPolicyValue = 'propagate' | 'value';
+type ConditionalNullPolicy = (selectorValue: any) => NullPolicyValue;
+type NullPolicy = NullPolicyValue | ConditionalNullPolicy;
+interface CompiledNullPolicy {
+    selector: string;
+    table: {
+        value: string | number | boolean;
+        policy: NullPolicyValue;
+    }[];
+}
+declare const EvaluationData: unique symbol;
+type OperatorEvaluate = (params: Record<string, unknown>, context: OperatorContext) => unknown;
+interface ValidateFinding {
+    severity: Severity;
+    message: string;
+    parameter?: string;
+}
+type OperatorValidate = (literalParams: Record<string, unknown>, helpers: ValidateHelpers) => ValidateFinding[];
+interface ParameterDeclaration extends TypeDeclaration {
     default?: unknown;
+    description?: string;
+    metadata?: Record<string, unknown>;
+    evaluation?: EvaluationMode;
+    over?: string;
+    truthiness?: boolean;
+    nullPolicy?: NullPolicy;
+    elementNullPolicy?: NullPolicyValue;
+    replacesNullAt?: readonly string[];
 }
-interface FragmentParameterMetadata {
+type ParameterDeclarations = Record<string, ParameterDeclaration>;
+interface OperatorDefinition<P extends ParameterDeclarations = ParameterDeclarations> {
     name: string;
-    type: string | string[];
+    alias?: string;
+    category: OperatorCategory;
+    description: string;
+    metadata?: Record<string, unknown>;
+    parameters: P;
+    positionalParams?: readonly string[];
+    timeoutParam?: string;
+    useCache?: boolean;
+    cache?: 'auto' | 'manual';
+    validate?: OperatorValidate;
+    evaluate: (params: ResolvedParams<P>, context: OperatorContext) => unknown;
+    returns?: ExpectedType;
+}
+declare const VALIDATED_OPERATOR: unique symbol;
+interface ValidatedParameter {
+    type: ExpectedType;
     required: boolean;
-    description?: string;
     default?: unknown;
+    description?: string;
+    metadata?: Record<string, unknown>;
+    evaluation: EvaluationMode;
+    truthiness: boolean;
+    nullPolicy: NullPolicyValue | CompiledNullPolicy;
+    elementNullPolicy?: NullPolicyValue;
+    constraints?: Constraints;
+    over?: string;
+    replacesNullAt?: string[];
 }
-interface OperatorData {
+interface ValidatedOperatorDefinition {
+    readonly [VALIDATED_OPERATOR]: true;
+    name: string;
+    alias?: string;
+    category: OperatorCategory;
     description: string;
-    aliases: string[];
-    parameters: OperatorParameterMetadata[];
+    metadata?: Record<string, unknown>;
+    parameters: Record<string, ValidatedParameter>;
+    positionalParams?: string[];
+    restParam: string | null;
+    resolution: ResolutionPlan;
+    deliversLazily: boolean;
+    timeoutParam: string | null;
+    useCache: boolean;
+    cache: 'auto' | 'manual';
+    fingerprint: string;
+    validate?: OperatorValidate;
+    evaluate: OperatorEvaluate;
+    returns: ExpectedType;
+}
+type DeclarationEntry = readonly [name: string, declared: ValidatedParameter];
+interface ResolutionPlan {
+    readonly entries: readonly DeclarationEntry[];
+    readonly whole: readonly DeclarationEntry[];
+    readonly perElement: readonly DeclarationEntry[];
+}
+
+declare const isTruthy: (value: unknown) => boolean;
+
+declare const compareValues: (a: number | string, b: number | string) => -1 | 0 | 1;
+
+declare const ARRAY = "<array>";
+declare const OBJECT = "<object>";
+declare const renderText: (value: unknown) => string;
+
+declare const WILDCARD: unique symbol;
+type Wildcard = typeof WILDCARD;
+type PathSegment = string | number | Wildcard;
+interface ResolveResult {
+    found: boolean;
+    value: unknown;
 }
-type OperatorMetadata = OperatorData & {
-    name: Operator;
-    parseChildren: ParseChildrenMethod;
+declare const parsePath: (path: string) => PathSegment[];
+declare const resolvePath: (source: unknown, path: string | PathSegment[]) => ResolveResult;
+
+declare const deepEqual: (foo: any, bar: any) => boolean;
+
+type ReferenceNamespace = 'data' | 'vars' | 'params' | 'element' | 'index';
+
+type ReferenceRecognition = {
+    kind: 'reference';
+    namespace: ReferenceNamespace;
+    segments: PathSegment[];
+    drill: string;
+} | {
+    kind: 'invalid';
+    namespace: ReferenceNamespace;
+    reason: string;
+    code?: string;
+} | {
+    kind: 'unrecognized';
+} | {
+    kind: 'plain';
 };
-type FragmentMetadata = FragmentData & {
-    name: string;
+
+type ObjectClass = {
+    kind: 'operator';
+} | {
+    kind: 'fragment';
+} | {
+    kind: 'shorthand';
+    key: string;
+} | {
+    kind: 'plain';
+} | {
+    kind: 'malformed';
+    message: string;
 };
-type CustomFunctionMetadata = {
-    name: string;
-    numRequiredArgs: number;
-} & Omit<FunctionDefinition, 'function'>;
-
-declare class FigTreeEvaluator {
-    private options;
-    private operators;
-    private operatorAliases;
-    private cache;
-    private graphQLClient?;
-    private httpClient?;
-    constructor(options?: FigTreeOptions);
-    private typeChecker;
-    evaluate(expression: EvaluatorNode, options?: FigTreeOptions): Promise<EvaluatorOutput>;
-    isFigTreeExpression(expression: EvaluatorNode): boolean;
-    getOptions(): FigTreeOptions;
-    updateOptions(options: FigTreeOptions): void;
-    getCache: () => Store;
-    setCache: (cache: Store) => Store;
-    getOperators(): readonly OperatorMetadata[];
-    getFragments(): readonly FragmentMetadata[];
-    getCustomFunctions(): readonly CustomFunctionMetadata[];
-    getConfig(): {
-        options: FigTreeOptions;
-        operators: OperatorReference;
-        operatorAliases: OperatorAliases;
-        typeChecker: (...args: TypeCheckInput[] | [TypeCheckInput[]]) => void;
-        resolvedAliasNodes: {};
-        cache: FigTreeCache;
-        graphQLClient: HttpClient | undefined;
-        httpClient: HttpClient | undefined;
+interface PositionalShape {
+    positionalParams?: readonly string[];
+    restParam: string | null;
+}
+interface PositionalLayout {
+    bound: number;
+    restAt: number | null;
+}
+
+interface FragmentParameterDeclaration extends TypeDeclaration {
+    default?: unknown;
+    description?: string;
+    metadata?: Record<string, unknown>;
+}
+interface FragmentDefinition {
+    expression: unknown;
+    parameters?: Record<string, FragmentParameterDeclaration>;
+    description?: string;
+    metadata?: Record<string, unknown>;
+}
+interface FragmentParameter {
+    type: ExpectedType;
+    required: boolean;
+    default?: unknown;
+    description?: string;
+    metadata?: Record<string, unknown>;
+    constraints?: Constraints;
+}
+
+type EvaluationOptions = Omit<FigTreeOptions, 'operators' | 'fragments'>;
+type CallOptions = Pick<FigTreeOptions, 'data' | 'signal' | 'timeout' | 'mode' | 'trace'>;
+type OnlyCallOptions<CallOpts> = CallOpts & {
+    [Key in Exclude<keyof CallOpts, keyof CallOptions>]: never;
+};
+interface FigTreeOptions {
+    data?: Record<string, unknown>;
+    fragments?: Record<string, FragmentDefinition>;
+    operators?: (ValidatedOperatorDefinition | ValidatedOperatorDefinition[])[];
+    operatorDefaults?: {
+        [operator: string]: {
+            [param: string]: unknown;
+        };
+    };
+    http?: {
+        baseEndpoint?: string;
+        headers?: Record<string, string>;
+    };
+    graphQL?: {
+        endpoint?: string;
+        headers?: Record<string, string>;
+    };
+    strictDataPaths?: boolean;
+    maxDepth?: number;
+    maxNodes?: number;
+    timeout?: number;
+    signal?: AbortSignal;
+    useCache?: boolean;
+    cache?: {
+        store?: CacheStore;
+        maxSize?: number;
+        maxTime?: number;
     };
-    getVersion: () => string;
+    runtimeTypeCheck?: boolean;
+    mode?: 'throw' | 'report';
+    trace?: boolean;
 }
-declare const evaluateExpression: (expression: EvaluatorNode, options?: FigTreeOptions) => Promise<EvaluatorOutput>;
+interface EvaluationResult {
+    result: unknown;
+    errors: FigTreeError[];
+    trace?: TraceNode;
+}
+type NoOptions = Record<never, never>;
+type Merge<Instance, Call> = Omit<Instance, keyof Call> & Call;
+type ResultShape<O> = O extends {
+    mode: 'report';
+} | {
+    trace: true;
+} ? EvaluationResult : unknown;
 
-declare class FigTreeError extends Error {
-    operator?: Operator;
+interface Dependencies {
+    data: {
+        paths: string[];
+        dynamic: boolean;
+    };
+    operators: string[];
+    fragments: string[];
+}
+interface ParameterInfo extends ValidatedParameter {
+    instanceDefault?: unknown;
+}
+interface OperatorInfo extends Omit<ValidatedOperatorDefinition, typeof VALIDATED_OPERATOR | 'evaluate' | 'validate' | 'deliversLazily' | 'resolution' | 'fingerprint' | 'parameters'> {
+    parameters: Record<string, ParameterInfo>;
+    hasValidate: boolean;
+    instanceUseCache?: boolean;
+    instanceFallback?: unknown;
+}
+interface FragmentInfo {
+    name: string;
+    description?: string;
+    metadata?: Record<string, unknown>;
+    parameters: Record<string, FragmentParameter>;
+    returns: ExpectedType;
+    warnings: Issue[];
+    dependencies: Dependencies;
+}
+
+declare class FigTree<InstanceOpts extends FigTreeOptions = NoOptions> {
+    private state;
+    private readonly results;
+    readonly version = "3.0.0-preview.2";
+    constructor(options?: InstanceOpts);
+    updateOptions(options?: FigTreeOptions): void;
+    clearCache(): void;
+    getOptions(): EvaluationOptions;
+    getOperators(): OperatorInfo[];
+    getFragments(): FragmentInfo[];
+    validate(expression: unknown, options?: CallOptions): ValidationResult;
+    getDependencies(expression: unknown): Dependencies;
+    isEvaluable(expression: unknown): boolean;
+    evaluate<CallOpts extends CallOptions = NoOptions>(expression: unknown, options?: OnlyCallOptions<CallOpts>): Promise<ResultShape<Merge<InstanceOpts, CallOpts>>>;
+    compile(expression: unknown): CompiledExpression<InstanceOpts>;
+}
+declare class CompiledExpression<InstanceOpts extends FigTreeOptions = NoOptions> {
+    #private;
+    private constructor();
+    get expression(): unknown;
+    get issues(): readonly Issue[];
+    get hasErrors(): boolean;
+    evaluate<CallOpts extends CallOptions = NoOptions>(options?: OnlyCallOptions<CallOpts>): Promise<ResultShape<Merge<InstanceOpts, CallOpts>>>;
+    getDependencies(): Dependencies;
+}
+
+declare function defineOperator(definition: ValidatedOperatorDefinition): ValidatedOperatorDefinition;
+declare function defineOperator<const P extends ParameterDeclarations>(definition: OperatorDefinition<P>): ValidatedOperatorDefinition;
+
+declare const coreOperators: ValidatedOperatorDefinition[];
+
+interface OperatorFailureInit {
+    code?: string;
     errorData?: Record<string, unknown>;
-    expression?: EvaluatorNode;
-    prettyPrint: string;
-    constructor(error: Error & {
-        errorData?: Record<string, unknown>;
-    }, operator?: Operator, name?: string, expression?: EvaluatorNode);
 }
-declare const isFigTreeError: (input: unknown) => input is FigTreeError;
+declare class OperatorFailure extends Error {
+    code?: string;
+    errorData?: Record<string, unknown>;
+    constructor(message: string, init?: OperatorFailureInit);
+}
+declare const isOperatorFailure: (input: unknown) => input is OperatorFailure;
 
-declare const SQLNodePostgres: (client: Client) => {
-    query: ({ query, values }: QueryInput) => Promise<QueryOutput>;
-};
-declare const SQLite: (db: Database) => {
-    query: ({ query, values }: QueryInput) => Promise<any[]>;
-};
+declare const httpOperators: (client?: HttpClient) => ValidatedOperatorDefinition[];
+declare const sqlOperators: (connection: SqlConnection) => ValidatedOperatorDefinition[];
 
-type Fetch = (input: URL | string | RequestInfo, init?: RequestInit | undefined) => Promise<Response>;
-declare const AxiosClient: (axios: AxiosStatic) => {
-    get: (req: Omit<HttpRequest, 'method'>) => Promise<any>;
-    post: (req: Omit<HttpRequest, 'method'>) => Promise<any>;
-    throwError: (err: unknown) => never;
-};
-declare const FetchClient: (fetch: Fetch) => {
-    get: (req: Omit<HttpRequest, 'method'>) => Promise<any>;
-    post: (req: Omit<HttpRequest, 'method'>) => Promise<any>;
-    throwError: (err: unknown) => never;
+type FetchLike = (input: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+}) => Promise<FetchResponseLike>;
+interface FetchResponseLike {
+    ok: boolean;
+    status: number;
+    statusText: string;
+    url: string;
+    text(): Promise<string>;
+}
+interface AxiosLike {
+    (config: {
+        url: string;
+        method: 'get' | 'post';
+        headers?: Record<string, string>;
+        data?: unknown;
+        signal?: AbortSignal;
+    }): Promise<{
+        data: unknown;
+        status: number;
+        statusText: string;
+    }>;
+    isAxiosError(payload: unknown): payload is AxiosErrorLike;
+}
+interface AxiosErrorLike {
+    message: string;
+    config?: {
+        url?: string;
+    };
+    response?: {
+        status: number;
+        statusText: string;
+        data: unknown;
+    };
+}
+declare class FetchClient implements HttpClient {
+    private readonly supplied?;
+    constructor(fetchImpl?: FetchLike);
+    request: (req: HttpRequest) => Promise<unknown>;
+}
+declare class AxiosClient implements HttpClient {
+    private readonly axios;
+    constructor(axios: AxiosLike);
+    request: (req: HttpRequest) => Promise<unknown>;
+}
+
+interface PgClientLike {
+    query(config: {
+        text: string;
+        values?: unknown[];
+    }): Promise<{
+        rows: Record<string, unknown>[];
+    }>;
+}
+interface SqliteDatabaseLike {
+    all(sql: string, params?: unknown[] | Record<string, unknown>): Promise<Record<string, unknown>[]>;
+}
+declare class PostgresConnection implements SqlConnection {
+    private readonly client;
+    constructor(client: PgClientLike);
+    query: (req: SqlRequest) => Promise<Record<string, unknown>[]>;
+}
+declare class SQLiteConnection implements SqlConnection {
+    private readonly db;
+    constructor(db: SqliteDatabaseLike);
+    query: (req: SqlRequest) => Promise<Record<string, unknown>[]>;
+}
+
+type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
 };
+type Path = (string | number)[];
 
-declare const preProcessShorthand: (expression: EvaluatorNode, fragments: Fragments | undefined, functionNames: string[], useShorthand?: boolean) => EvaluatorNode | FragmentNode;
+type NodeMap = Record<string, InspectNode>;
+type InspectNode = {
+    order: number;
+    path: Path;
+} & ({
+    kind: 'constant';
+    value: Json;
+} | {
+    kind: 'reference';
+    reference: string;
+    authored: string;
+    binding?: string;
+} | {
+    kind: 'operator';
+    vars?: NodeMap;
+    operator: string;
+    params: NodeMap;
+    fallback?: InspectNode;
+    timeoutFallback?: Json;
+    useCache?: boolean;
+    instanceDefaults?: string[];
+} | {
+    kind: 'fragmentCall';
+    vars?: NodeMap;
+    fragment: string;
+    resolved: boolean;
+    argumentsMode: 'static' | 'dynamic';
+    parameters?: NodeMap | InspectNode;
+    fallback?: InspectNode;
+    timeoutFallback?: Json;
+} | {
+    kind: 'skeleton';
+    vars?: NodeMap;
+    shape: Json;
+    holes: {
+        at: Path;
+        node: InspectNode;
+    }[];
+} | {
+    kind: 'elements';
+    elements: InspectNode[];
+} | {
+    kind: 'entries';
+    vars?: NodeMap;
+    entries: NodeMap;
+} | {
+    kind: 'invalid';
+    raw: Json;
+});
 
-declare const isOperatorNode: (input: EvaluatorNode) => input is OperatorNode;
-declare const isFragmentNode: (input: EvaluatorNode) => input is FragmentNode;
-declare const standardiseOperatorName: (name: string) => string;
-declare const truncateString: (string: string, length?: number) => string;
-declare const isAliasString: (value: string) => boolean;
-declare const isObject: (input: unknown) => input is object;
-declare const isFigTreeExpression: (expression: EvaluatorNode) => boolean;
+type InspectIssue = Issue & {
+    order?: number;
+};
+interface InspectDependencies {
+    dataPaths: string[];
+    dynamic: boolean;
+    operators: string[];
+    fragments: string[];
+}
+interface InspectReport {
+    version: string;
+    expression: Json;
+    options: Record<string, Json>;
+    canonicalForm: InspectNode;
+    issues: InspectIssue[];
+    timeoutShielded: boolean;
+    nodeCount: number;
+    maxDepth: number;
+    dependencies: InspectDependencies;
+    own: {
+        nodeCount: number;
+        maxDepth: number;
+        dependencies: InspectDependencies;
+    };
+}
+declare const inspect: <InstanceOpts extends FigTreeOptions>(compiled: CompiledExpression<InstanceOpts>, options?: CallOptions) => InspectReport;
 
-declare const convertV1ToV2: (expression: EvaluatorNode, figTree: FigTreeEvaluator) => string | number | boolean | Record<string, unknown> | null | undefined;
-declare const isV1Node: (node: EvaluatorNode) => node is OperatorNode;
+interface OperatorHints {
+    displayName: string;
+    docUrl: string;
+    backgroundColor: string;
+    textColor: string;
+    seeds?: {
+        [parameter: string]: unknown;
+    };
+}
+type FragmentHints = Omit<OperatorHints, 'docUrl'> & {
+    docUrl?: string;
+};
+interface CategoryHints {
+    displayName: string;
+    order: number;
+    backgroundColor: string;
+    textColor: string;
+}
+type OperatorHintMap = {
+    [operator: string]: OperatorHints;
+};
+type CategoryHintMap = {
+    [category in OperatorCategory]: CategoryHints;
+};
+type TypeSeeds = {
+    [type in BasicType]: unknown;
+};
 
-declare const convertToShorthand: (expression: EvaluatorNode, figTree: FigTreeEvaluator, arrayThreshold?: number) => EvaluatorNode;
+interface MigrationIssue {
+    code: 'split-trailing-empty' | 'remainder-sign' | 'template-numbering' | 'named-token-source' | 'response-collapse' | 'computed-delimiter' | 'computed-branches' | 'graphql-relative-url' | 'output-type' | 'missing-data-fallback' | 'unprefixed-parameter' | 'instance-case-insensitive' | 'values-cut' | 'fallback-converted' | 'malformed-entry' | 'unreachable-branches' | 'overridden-value' | 'discarded-expression' | 'fragment-shorthand-payload' | 'shadowed-argument' | 'unknown-argument' | 'fragment-use-cache' | 'name-renamed' | 'unknown-parameter-type' | 'default-outside-type' | 'unused-output-type' | 'deciding-value' | 'drilled-substitution-token' | 'number-mapping' | 'template-escape' | 'computed-dollar-template' | 'custom-function-call' | 'computed-function-name' | 'computed-arguments' | 'body-override' | 'computed-fragment-name' | 'replaced-output-type' | 'computed-children' | 'unknown-operator' | 'unconvertible-input';
+    tag: 'non-convertible' | 'intentional-semantic-change' | 'lossy-default';
+    path: (string | number)[];
+    message: string;
+}
+interface MigrationResult {
+    expression: unknown;
+    issues: MigrationIssue[];
+}
+interface FragmentMigrationResult {
+    fragments: Record<string, FragmentDefinition>;
+    issues: MigrationIssue[];
+}
+interface V2Options {
+    fragments?: Record<string, unknown>;
+    functions?: readonly string[] | Record<string, unknown>;
+    evaluateFullObject?: boolean;
+    noShorthand?: boolean;
+    caseInsensitive?: boolean;
+    useCache?: boolean;
+}
 
-declare const convertFromShorthand: (expression: EvaluatorNode, figTree: FigTreeEvaluator) => EvaluatorNode;
+interface Registry {
+    getOperators(): readonly {
+        name: string;
+        alias?: string;
+        positionalParams?: readonly string[];
+        restParam: string | null;
+    }[];
+    getFragments(): readonly {
+        name: string;
+    }[];
+}
+type Spelling = 'preserve' | 'canonical' | 'alias';
+interface NameOptions {
+    referenceNames?: Spelling;
+}
+interface CanonicalOptions extends NameOptions {
+    operatorNames?: Spelling;
+    referencesAsGet?: boolean;
+}
+interface ShorthandOptions extends NameOptions {
+    operatorNames?: Spelling;
+    arguments?: 'positional' | 'named';
+    getAsReference?: boolean;
+}
 
-export { AxiosClient, type BasicType, type CustomFunctionMetadata, type EvaluatorNode, type EvaluatorOutput, type ExpectedType, FetchClient, type FigTreeConfig, FigTreeError, FigTreeEvaluator, type FigTreeOptions, type Fragment, type FragmentMetadata, type FragmentNode, type FragmentParameterMetadata, type Fragments, type FunctionDefinition, type GraphQLConnection, type LiteralType, type Operator, type OperatorAlias, type OperatorData, type OperatorMetadata, type OperatorNode, type OperatorParameterMetadata, type OutputType, SQLNodePostgres, SQLite, type UnknownFunction, convertFromShorthand, convertToShorthand, convertV1ToV2, evaluateExpression, isAliasString, isFigTreeError, isFigTreeExpression, isFragmentNode, isObject, isOperatorNode, isV1Node, preProcessShorthand, standardiseOperatorName, truncateString };
+export { ARRAY, AxiosClient, CompiledExpression, ErrorCodes, EvaluationData, FetchClient, FigTree, FigTreeError, OBJECT, OPERATOR_CATEGORIES, OperatorFailure, PostgresConnection, SQLiteConnection, WILDCARD, compareValues, coreOperators, deepEqual, defineOperator, httpOperators, inspect, isFigTreeError, isOperatorFailure, isTruthy, parsePath, renderText, resolvePath, sqlOperators, version };
+export type { AxiosErrorLike, AxiosLike, BasicType, CacheStore, CacheTraceEvent, CallOptions, CanonicalOptions, CategoryHintMap, CategoryHints, CompiledNullPolicy, ConditionalNullPolicy, Constraints, Dependencies, EvaluationMode, EvaluationOptions, EvaluationResult, ExpectedType, FetchLike, FetchResponseLike, FigTreeErrorCode, FigTreeErrorInit, FigTreeOptions, FragmentDefinition, FragmentHints, FragmentInfo, FragmentMigrationResult, FragmentParameter, FragmentParameterDeclaration, HttpClient, HttpRequest, InspectDependencies, InspectIssue, InspectNode, InspectReport, Issue, KeyOverwriteTraceEvent, KnownTraceEvent, LazyValue, LiteralType, Merge, MigrationIssue, MigrationResult, NameOptions, NoOptions, NullPolicy, NullPolicyValue, ObjectClass, OnlyCallOptions, OperatorCategory, OperatorContext, OperatorDefinition, OperatorEvaluate, OperatorFailureInit, OperatorHintMap, OperatorHints, OperatorInfo, OperatorValidate, ParamValue, ParameterDeclaration, ParameterDeclarations, ParameterInfo, PathSegment, PerElement, PgClientLike, PositionalLayout, PositionalShape, QueryTraceEvent, ReferenceNamespace, ReferenceRecognition, Registry, RenderTraceEvent, RequestTraceEvent, ResolveResult, ResolvedParams, ResultShape, Settlement, SettlementStream, Severity, ShieldedFallbackTraceEvent, ShorthandOptions, Spelling, SqlConnection, SqlRequest, SqliteDatabaseLike, TraceEvent, TraceKind, TraceNode, TraceStatus, TypeCheckResult, TypeDeclaration, TypeOf, TypeSeeds, V2Options, ValidateFinding, ValidateHelpers, ValidatedOperatorDefinition, ValidatedParameter, ValidationResult, Wildcard };