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

package/build/index.d.ts

@@ -1,279 +1,957 @@
-/// <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.10";
+
+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;
+}
+
+declare const ErrorCodes: {
+    readonly typeCheck: "type-check";
+    readonly operatorFailure: "operator-failure";
+    readonly requestTimeout: "request-timeout";
+    readonly httpStatus: "http-status";
+    readonly invalidResponse: "invalid-response";
+    readonly graphQLErrors: "graphql-errors";
+    readonly sqlError: "sql-error";
+    readonly requestFailure: "request-failure";
+    readonly nonFiniteResult: "non-finite-result";
+    readonly escapedHandle: "escaped-handle";
+    readonly emptyAggregate: "empty-aggregate";
+    readonly missingDataPath: "missing-data-path";
+    readonly missingRequired: "missing-required";
+    readonly timeout: "timeout";
+    readonly aborted: "aborted";
+    readonly malformedNode: "malformed-node";
+    readonly unknownOperator: "unknown-operator";
+    readonly unknownFragment: "unknown-fragment";
+    readonly unknownNodeKey: "unknown-node-key";
+    readonly unrecognizedIdentifier: "unrecognized-identifier";
+    readonly positionalArity: "positional-arity";
+    readonly invalidVars: "invalid-vars";
+    readonly invalidReference: "invalid-reference";
+    readonly invalidAs: "invalid-as";
+    readonly unresolvedVar: "unresolved-var";
+    readonly unresolvedParam: "unresolved-param";
+    readonly unresolvedBinding: "unresolved-binding";
+    readonly bareVars: "bare-vars";
+    readonly varCycle: "var-cycle";
+    readonly depthCeiling: "depth-ceiling";
+    readonly maxDepthExceeded: "max-depth";
+    readonly maxNodesExceeded: "max-nodes";
+    readonly returnsMismatch: "returns-mismatch";
+    readonly operatorValidate: "operator-validate";
+    readonly uselessModifier: "useless-modifier";
+    readonly unreferencedVar: "unreferenced-var";
+    readonly shadowedVar: "shadowed-var";
+    readonly deadBinding: "dead-binding";
+    readonly fallbackMismatch: "fallback-mismatch";
+    readonly unboundToken: "unbound-token";
+    readonly unusedSubstitution: "unused-substitution";
+    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 fragmentCycle: "fragment-cycle";
+    readonly invalidOptions: "invalid-options";
 };
+type KnownErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+type FigTreeErrorCode = KnownErrorCode | (string & {});
+type KnownFallbackErrorCode = (typeof ErrorCodes)['typeCheck' | 'operatorFailure' | 'requestTimeout' | 'httpStatus' | 'invalidResponse' | 'graphQLErrors' | 'sqlError' | 'requestFailure' | 'nonFiniteResult' | 'escapedHandle' | 'emptyAggregate' | 'missingDataPath' | 'missingRequired' | 'timeout'];
+type FallbackErrorCode = KnownFallbackErrorCode | (string & {});
 
-interface HttpClient {
-    get: (req: Omit<HttpRequest, 'method'>) => Promise<unknown>;
-    post: (req: Omit<HttpRequest, 'method'>) => Promise<unknown>;
-    throwError: (err: unknown) => void;
+type Severity = 'error' | 'warning';
+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;
+interface ValidationResult {
+    valid: boolean;
+    issues: Issue[];
+}
+
+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;
     };
-    data?: Record<string, unknown>;
-    headers?: Record<string, unknown>;
-    method?: 'get' | 'post';
 }
 
-interface GraphQLConnection {
-    endpoint: string;
-    headers?: {
-        [key: string]: string;
+type TraceStatus = 'value' | 'failed' | 'fallback' | 'cancelled' | 'skipped';
+type TraceKind = 'operator' | 'fragment' | 'reference' | 'literal' | 'skeleton';
+interface TraceNode {
+    path: (string | number)[];
+    source?: {
+        fragment: string;
     };
-    httpClient?: HttpClient;
+    kind: TraceKind;
+    operator?: string;
+    ref?: string;
+    var?: string;
+    status: TraceStatus;
+    value?: unknown;
+    error?: FigTreeError;
+    events?: TraceEvent[];
+    children?: TraceNode[];
+    elapsed?: number;
+    warnings?: Issue[];
+}
+interface CacheTraceEvent {
+    type: 'cache';
+    hit: boolean;
+}
+interface RequestTraceEvent {
+    type: 'request';
+    method: string;
+    url: string;
+    headers: string[];
 }
+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;
 
-declare const operatorAliases: OperatorAliases;
+interface FallbackError {
+    code: FallbackErrorCode;
+    message: string;
+    path: (string | number)[];
+    operator?: string;
+    fragment?: string;
+    fragmentPath?: (string | number)[];
+    errorData?: Record<string, unknown>;
+}
+interface FigTreeErrorInit {
+    code: FigTreeErrorCode;
+    message: string;
+    path: (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)[];
+    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;
 
-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;
-    };
-    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;
+type BasicType = 'any' | 'string' | 'number' | 'boolean' | 'array' | 'object' | 'null' | 'integer';
+type LiteralType = {
+    literal: readonly (string | number | boolean)[];
+};
+type ExpectedType = BasicType | LiteralType | readonly BasicType[];
+interface Constraints {
+    length?: number;
+    homogeneous?: readonly BasicType[];
+    elementShape?: Record<string, TypeDeclaration>;
 }
-interface FragmentNode {
-    fragment: string;
-    parameters?: Record<string, EvaluatorNode>;
-    [key: string]: EvaluatorNode;
+interface TypeDeclaration {
+    type?: ExpectedType;
+    required?: boolean;
+    constraints?: Constraints;
 }
-interface FragmentData {
-    description?: string;
-    parameters?: FragmentParameterMetadata[];
-    textColor?: string;
-    backgroundColor?: string;
+type TypeCheckResult = {
+    ok: true;
+} | {
+    ok: false;
+    expected: string;
+    actual: string;
+};
+
+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;
+
+interface FallbackCoverage {
+    uncovered: CoverageFinding[];
+    covered: CoveredFinding[];
 }
-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 CoverageFinding {
+    path: (string | number)[];
+    code: FigTreeErrorCode;
+    message: string;
+    certainty: 'may' | 'always';
+    operator?: string;
+    parameter?: string;
+    fragment?: string;
+    fragmentPath?: (string | number)[];
+}
+interface CoveredFinding extends CoverageFinding {
+    coveredBy: (string | number)[];
+    coveredByFragmentPath?: (string | number)[];
+    givesNull?: true;
+}
+interface FallbackCoverageOptions {
+    strictNumbers?: boolean;
+}
+interface OperatorAnalysis {
+    failures?: FailureRule[];
+    external?: true;
+    output?: DeclaredOutput;
+}
+interface FailureRule {
+    code: FallbackErrorCode;
+    parameter?: string;
+    when?: Record<string, FailureTest>;
+    options?: Record<string, unknown>;
+    may?: true;
+    overflow?: true;
+}
+type FailureTest = string | number | boolean | null | {
+    type: ExpectedType;
+} | {
+    below: number;
+} | {
+    empty: true;
+} | {
+    supplied: boolean;
+} | {
+    invalid: true;
+} | {
+    some: FailureTest;
+} | {
+    not: FailureTest;
 };
-type EvaluateMethod = (expression: OperatorNode, config: FigTreeConfig) => Promise<EvaluatorOutput>;
-type ParseChildrenMethod = (expression: OperatorNode, config: FigTreeConfig) => OperatorNode;
-type OperatorReference = {
-    [key in Operator]: OperatorObject;
+type DeclaredOutput = ExpectedType | {
+    type: 'number' | 'integer';
+    min?: number;
+    max?: number;
+} | {
+    type: 'string' | 'array';
+    minLength?: number;
+} | {
+    param: string;
+} | {
+    elementOf: string;
+} | {
+    kindOf: string;
+} | {
+    arrayOf: DeclaredOutput;
+    minLength?: number;
+} | {
+    oneOf: DeclaredOutput[];
+} | {
+    typeNamedBy: string;
+} | {
+    byParam: string;
+    cases: Record<string, DeclaredOutput>;
+    otherwise?: DeclaredOutput;
+} | {
+    firstNonNull: string;
+} | {
+    sum: string;
+} | {
+    product: string;
+} | {
+    difference: [string, string];
+} | {
+    abs: string;
+} | {
+    min: string;
+} | {
+    max: string;
 };
-interface OperatorParameterMetadata {
+
+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[];
+}
+type ParameterDeclarations = Record<string, ParameterDeclaration>;
+interface OperatorDefinition<P extends ParameterDeclarations = ParameterDeclarations> {
     name: string;
+    alias?: string;
+    category: OperatorCategory;
     description: string;
-    aliases: string[];
-    required: boolean;
+    metadata?: Record<string, unknown>;
+    parameters: P;
+    positionalParams?: readonly string[];
+    timeoutParam?: string;
+    cache?: true;
+    validate?: OperatorValidate;
+    analysis?: OperatorAnalysis;
+    evaluate: (params: ResolvedParams<P>, context: OperatorContext) => unknown;
+    returns?: ExpectedType;
+}
+declare const VALIDATED_OPERATOR: unique symbol;
+interface ValidatedParameter {
     type: ExpectedType;
+    required: boolean;
     default?: unknown;
+    description?: string;
+    metadata?: Record<string, unknown>;
+    evaluation: EvaluationMode;
+    truthiness: boolean;
+    nullPolicy: NullPolicyValue | CompiledNullPolicy;
+    elementNullPolicy?: NullPolicyValue;
+    constraints?: Constraints;
+    over?: string;
+    replacesNullAt?: string[];
 }
-interface FragmentParameterMetadata {
+interface ValidatedOperatorDefinition {
+    readonly [VALIDATED_OPERATOR]: true;
     name: string;
-    type: string | string[];
-    required: boolean;
+    alias?: string;
+    category: OperatorCategory;
+    description: string;
+    metadata?: Record<string, unknown>;
+    parameters: Record<string, ValidatedParameter>;
+    positionalParams?: string[];
+    restParam: string | null;
+    resolution: ResolutionPlan;
+    deliversLazily: boolean;
+    timeoutParam: string | null;
+    cache: boolean;
+    fingerprint: string;
+    validate?: OperatorValidate;
+    analysis?: OperatorAnalysis;
+    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;
+}
+declare const parsePath: (path: string) => PathSegment[];
+declare const resolvePath: (source: unknown, path: string | PathSegment[]) => ResolveResult;
+
+declare const deepEqual: (foo: any, bar: any) => boolean;
+
+declare const NAMESPACE_TOKENS: {
+    readonly data: "data";
+    readonly d: "data";
+    readonly vars: "vars";
+    readonly v: "vars";
+    readonly params: "params";
+    readonly p: "params";
+    readonly element: "element";
+    readonly e: "element";
+    readonly index: "index";
+    readonly i: "index";
+    readonly error: "error";
+    readonly err: "error";
+};
+type ReferenceNamespace = (typeof NAMESPACE_TOKENS)[keyof typeof NAMESPACE_TOKENS];
+type ReferenceRecognition = {
+    kind: 'reference';
+    namespace: ReferenceNamespace;
+    segments: PathSegment[];
+    drill: string;
+    binding?: string;
+} | {
+    kind: 'invalid';
+    namespace: ReferenceNamespace;
+    reason: string;
+    code?: string;
+} | {
+    kind: 'unrecognized';
+} | {
+    kind: 'plain';
+};
+interface ReferenceScope {
+    bindings?: readonly string[];
+}
+
+type ObjectClass = {
+    kind: 'operator';
+} | {
+    kind: 'fragment';
+} | {
+    kind: 'shorthand';
+    key: string;
+} | {
+    kind: 'plain';
+} | {
+    kind: 'malformed';
+    message: string;
+};
+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;
 }
-interface OperatorData {
-    description: string;
-    aliases: string[];
-    parameters: OperatorParameterMetadata[];
+
+type EvaluationOptions = Omit<FigTreeOptions, 'operators' | 'fragments'>;
+type CallOptions = Pick<FigTreeOptions, 'data' | 'signal' | 'timeout' | '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]: {
+            noCache?: true;
+            fallback?: unknown;
+            [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;
+    cache?: {
+        store?: CacheStore;
+        maxSize?: number;
+        maxTime?: number;
+    };
+    trace?: boolean;
 }
-type OperatorMetadata = OperatorData & {
-    name: Operator;
-    parseChildren: ParseChildrenMethod;
+type OptionsUpdate = {
+    [Key in keyof FigTreeOptions]?: (Key extends MergedBlock ? Removable<NonNullable<FigTreeOptions[Key]>> : FigTreeOptions[Key]) | null;
 };
-type FragmentMetadata = FragmentData & {
-    name: string;
+type MergedBlock = 'fragments' | 'operatorDefaults' | 'http' | 'graphQL' | 'cache';
+type Removable<Block> = {
+    [Key in keyof Block]?: Block[Key] | null;
 };
-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 EvaluationResult {
+    result: unknown;
+    trace: TraceNode;
+}
+type NoOptions = Record<never, never>;
+type Merge<Instance, Call> = Omit<Instance, keyof Call> & Call;
+type ResultShape<O> = O extends {
+    trace: true;
+} ? EvaluationResult : unknown;
+
+interface Dependencies {
+    data: {
+        paths: string[];
+        dynamic: boolean;
     };
-    getVersion: () => string;
+    operators: string[];
+    fragments: string[];
+}
+interface ParameterInfo extends ValidatedParameter {
+    hostDefault?: unknown;
+}
+interface OperatorInfo extends Omit<ValidatedOperatorDefinition, typeof VALIDATED_OPERATOR | 'evaluate' | 'validate' | 'deliversLazily' | 'resolution' | 'fingerprint' | 'parameters'> {
+    parameters: Record<string, ParameterInfo>;
+    hasValidate: boolean;
+    hostNoCache?: true;
+    hostFallback?: unknown;
+}
+interface FragmentInfo {
+    name: string;
+    description?: string;
+    metadata?: Record<string, unknown>;
+    parameters: Record<string, FragmentParameter>;
+    returns: ExpectedType;
+    warnings: Issue[];
+    dependencies: Dependencies;
+    caches: boolean;
 }
-declare const evaluateExpression: (expression: EvaluatorNode, options?: FigTreeOptions) => Promise<EvaluatorOutput>;
 
-declare class FigTreeError extends Error {
-    operator?: Operator;
+declare class FigTree<InstanceOpts extends FigTreeOptions = NoOptions> {
+    private state;
+    private readonly results;
+    readonly version = "3.0.0-preview.10";
+    constructor(options?: InstanceOpts);
+    updateOptions(options?: OptionsUpdate): 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?: FallbackErrorCode;
     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?: FallbackErrorCode;
+    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>[]>;
+}
+
+interface HttpFailureInfo {
+    status: number;
+    statusText: string;
+    url: string;
+    response: unknown;
+}
+declare const httpFailure: (info: HttpFailureInfo) => OperatorFailure;
+declare const sqlFailure: (driver: string, error: unknown) => OperatorFailure;
+
+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;
+    noCache?: true;
+    hostDefaults?: string[];
+} | {
+    kind: 'fragmentCall';
+    vars?: NodeMap;
+    fragment: string;
+    resolved: boolean;
+    argumentsMode: 'static' | 'dynamic';
+    parameters?: NodeMap | InspectNode;
+    fallback?: InspectNode;
+    timeoutFallback?: Json;
+    noCache?: true;
+} | {
+    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' | 'cache-opt-in' | 'instance-case-insensitive' | 'values-cut' | 'fallback-converted' | 'malformed-entry' | 'unreachable-branches' | 'overridden-value' | 'discarded-expression' | 'fragment-shorthand-payload' | 'shadowed-argument' | 'unknown-argument' | '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, httpFailure, httpOperators, inspect, isFigTreeError, isOperatorFailure, isTruthy, parsePath, renderText, resolvePath, sqlFailure, sqlOperators, version };
+export type { AxiosErrorLike, AxiosLike, BasicType, CacheStore, CacheTraceEvent, CallOptions, CanonicalOptions, CategoryHintMap, CategoryHints, CompiledNullPolicy, ConditionalNullPolicy, Constraints, CoverageFinding, CoveredFinding, DeclaredOutput, Dependencies, EvaluationMode, EvaluationOptions, EvaluationResult, ExpectedType, FailureRule, FailureTest, FallbackCoverage, FallbackCoverageOptions, FallbackError, FallbackErrorCode, FetchLike, FetchResponseLike, FigTreeErrorCode, FigTreeErrorInit, FigTreeOptions, FragmentDefinition, FragmentHints, FragmentInfo, FragmentMigrationResult, FragmentParameter, FragmentParameterDeclaration, HttpClient, HttpFailureInfo, HttpRequest, InspectDependencies, InspectIssue, InspectNode, InspectReport, Issue, KeyOverwriteTraceEvent, KnownTraceEvent, LazyValue, LiteralType, Merge, MigrationIssue, MigrationResult, NameOptions, NoOptions, NullPolicy, NullPolicyValue, ObjectClass, OnlyCallOptions, OperatorAnalysis, OperatorCategory, OperatorContext, OperatorDefinition, OperatorEvaluate, OperatorFailureInit, OperatorHintMap, OperatorHints, OperatorInfo, OperatorValidate, OptionsUpdate, ParamValue, ParameterDeclaration, ParameterDeclarations, ParameterInfo, PathSegment, PerElement, PgClientLike, PositionalLayout, PositionalShape, QueryTraceEvent, ReferenceNamespace, ReferenceRecognition, ReferenceScope, 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 };