expressionish 0.1.0 → 0.1.1

package/dist/expressionish.d.ts

@@ -0,0 +1,540 @@
+declare module "parse/base-token" {
+    import { type EvaluateOptions } from "types";
+    export interface BaseTokenOptions {
+        position: number;
+        type?: string;
+        value?: unknown;
+    }
+    export interface BaseTokenJSON {
+        position: number;
+        type: string;
+        value?: unknown;
+    }
+    export default class BaseToken {
+        position: number;
+        type: string;
+        value?: unknown;
+        constructor(options: BaseTokenOptions);
+        toJSON(): BaseTokenJSON;
+        evaluate(options: EvaluateOptions): Promise<unknown>;
+    }
+}
+declare module "types" {
+    import type BaseToken from "parse/base-token";
+    /** Result of a `tokenize()` attempt */
+    export type TokenizeResult<T = BaseToken> = [success: false] | [success: true, updatedCursor: number, result: T];
+    /** Data to be passed to variables when they are to be evaluated */
+    export type EvaluateData = Record<string | number | symbol, unknown>;
+    /** Function to call to validate a variable's arguments
+     * @throws {import("./errors.ts").ExpressionArgumentsError} If an argument or the arguments list is invalid
+    */
+    export type ArgsCheck = (
+    /** meta data passed to the evaluate() call */
+    data: EvaluateData, 
+    /** Arguments passed to the variable */
+    ...args: unknown[]) => undefined | Promise<never>;
+    /** Function to call just prior to evaluating a variable or looked up variable */
+    export type PreEval = (
+    /** Options passed to the `<root>.evaluate()` function */
+    data: EvaluateData, 
+    /** variable or lookup name */
+    variable: Variable) => undefined | Promise<never>;
+    type GeneralEvaluateFnc = (data: EvaluateData, ...args: unknown[]) => Promise<unknown>;
+    export interface GeneralVariableDefinition<T = GeneralEvaluateFnc> {
+        minArgumentsCount?: number;
+        maxArgumentsCount?: number;
+        argsCheck?: ArgsCheck;
+        preeval?: PreEval;
+        evaluate: T;
+    }
+    /** Represents a variable definition */
+    export type Variable = GeneralVariableDefinition;
+    /** Represents a Map of variables where
+     * - the key is the variable's name
+     * - the value is the variable's definition
+     */
+    export type VariableMap = Map<string, Variable>;
+    /** Represents a Lookup handler
+     * @returns {undefined | Variable} A variable declaration or undefined
+    */
+    export type LookupFnc = (data: EvaluateData, 
+    /** The variable name to look up */
+    name: string) => undefined | Variable | Promise<undefined | Variable>;
+    /** Represents a Map of Lookup handlers where
+     * * the key is the lookup variable-prefix
+     * * the value is the function to handle the lookup
+    */
+    export type LookupMap = Map<string, LookupFnc>;
+    export type LogicOperatorFnc = (data: EvaluateData, ...args: unknown[]) => boolean | Promise<boolean>;
+    export type LogicOperatorDefinition = GeneralVariableDefinition<LogicOperatorFnc>;
+    export type LogicOperatorMap = Map<string, LogicOperatorDefinition>;
+    export type ComparisonOperatorFnc = (data: EvaluateData, v1: unknown, v2?: unknown) => boolean | Promise<boolean>;
+    export type ComparisonOperatorDefinition = GeneralVariableDefinition<ComparisonOperatorFnc>;
+    export type ComparisonOperatorMap = Map<string, ComparisonOperatorDefinition>;
+    /** Options when Tokenizing an expression */
+    export interface TokenizeOptions {
+        /** The expression to tokenize */
+        expression: string;
+        /** A map of Lookup handlers available to be accessed by the expression*/
+        lookups: LookupMap;
+        /** A map of variable handlers available to be accessed by the expression */
+        variables: VariableMap;
+        /** A map of additional condition logical operators */
+        logicalOperators?: LogicOperatorMap;
+        /** A map of additional condition comparison operators */
+        comparisonOperators?: ComparisonOperatorMap;
+    }
+    /** Options when evaluating a tokenized expression */
+    export interface EvaluateOptions extends TokenizeOptions {
+        /** When true the parser will only validate syntax, variable existence and lookup existence */
+        onlyValidate?: boolean;
+        /** Function to be called just prior to evaluating any variable or lookup */
+        preeval?: PreEval;
+        /** Data to be passed into variable and/or lookup evaluators */
+        data?: EvaluateData;
+    }
+    /** Represents a small portion of an expression's text that may or may not have significance to the parser */
+    export interface GenericToken {
+        /** The position of the generic token within the expression text */
+        position: number;
+        /** The character(s) comprising the token */
+        value: string;
+    }
+}
+declare module "tojson-types" {
+    /** Base that all other Token JSON inherit from */
+    export interface BaseTokenJSON {
+        /** Token's position withing the expression text */
+        position: number;
+        /** Token Type */
+        type: string;
+        /** Value of the token */
+        value?: unknown;
+    }
+    /** Represents a Text Token */
+    export interface TextTokenJSON extends BaseTokenJSON {
+        /** The text of the token */
+        value: string;
+    }
+    /** Represets a Sequence Token */
+    export interface SequenceTokenJSON extends BaseTokenJSON {
+        /** The tokens making up the sequence */
+        value: Array<LookupTokenJSON | IfTokenJSON | VariableTokenJSON | TextTokenJSON | SequenceTokenJSON>;
+    }
+    /** Represents an Argument Token */
+    export interface ArgumentsTokenJSON<T = GroupedTokensJSON> extends BaseTokenJSON {
+        /** Arguments of the token */
+        value: Array<T>;
+    }
+    /** Represents a Lookup Token */
+    export interface LookupTokenJSON extends BaseTokenJSON {
+        /** The prefix of the variable */
+        prefix: string;
+        /** The variable to be looked up */
+        value: string;
+        /** Arguments to be passed to the looked up variable during evaluation */
+        arguments?: ArgumentsTokenJSON;
+    }
+    /** Represents a Comparison Token */
+    export interface ComparisonTokenJSON extends BaseTokenJSON {
+        /** The comparison operator */
+        value: string;
+        /** The left-hand side of the comparison */
+        left: GroupedTokensJSON;
+        /** The right-hand side of the comparison */
+        right?: GroupedTokensJSON;
+    }
+    /** Represents a Logic Token */
+    export interface LogicTokenJSON extends BaseTokenJSON {
+        /** The logic operator */
+        value: string;
+        /** Arguments to be passed to the logic operator's handler */
+        arguments: ArgumentsTokenJSON<LogicTokenJSON | ComparisonTokenJSON | GroupedTokensJSON>;
+    }
+    /** Represents an If Token */
+    export interface IfTokenJSON extends BaseTokenJSON {
+        /** The condition */
+        value: ComparisonTokenJSON | LogicTokenJSON;
+        /** Value to return when the condition is truthy */
+        whenTrue: GroupedTokensJSON;
+        /** Value to return when the condition is falsy */
+        whenFalse?: GroupedTokensJSON;
+    }
+    export interface VariableTokenJSON extends BaseTokenJSON {
+        value: string;
+        arguments?: ArgumentsTokenJSON;
+    }
+    export type GroupedTokensJSON = LookupTokenJSON | IfTokenJSON | VariableTokenJSON | TextTokenJSON | SequenceTokenJSON;
+    export type RootTokenJSON = SequenceTokenJSON | LookupTokenJSON | IfTokenJSON | VariableTokenJSON | TextTokenJSON;
+}
+declare module "parse/text/token" {
+    import BaseToken from "parse/base-token";
+    import type { TextTokenJSON } from "tojson-types";
+    export interface TextTokenOptions {
+        position: number;
+        value: string;
+    }
+    export default class TextToken extends BaseToken {
+        value: string;
+        constructor(options: TextTokenOptions);
+        toJSON(): TextTokenJSON;
+    }
+}
+declare module "parse/logic/operators" {
+    import type { LogicOperatorDefinition } from "types";
+    const _default: Map<string, LogicOperatorDefinition>;
+    export default _default;
+}
+declare module "parse/logic/token" {
+    import type { EvaluateOptions } from "types";
+    import type { LogicTokenJSON } from "tojson-types";
+    import type ArgumentsToken from "parse/arguments/token";
+    import BaseToken from "parse/base-token";
+    export interface LogicTokenOptions {
+        position: number;
+        value: string;
+        arguments: ArgumentsToken;
+    }
+    export default class LogicToken extends BaseToken {
+        value: string;
+        arguments: ArgumentsToken;
+        constructor(options: LogicTokenOptions);
+        toJSON(): LogicTokenJSON;
+        evaluate(options: EvaluateOptions): Promise<unknown>;
+    }
+}
+declare module "parse/variable/token" {
+    import type { EvaluateOptions } from "types";
+    import type { VariableTokenJSON } from "tojson-types";
+    import type ArgumentsToken from "parse/arguments/token";
+    import BaseToken from "parse/base-token";
+    export interface VariableTokenOptions {
+        position: number;
+        value: string;
+        arguments?: ArgumentsToken;
+    }
+    export default class VariableToken extends BaseToken {
+        value: string;
+        arguments?: ArgumentsToken;
+        constructor(options: VariableTokenOptions);
+        toJSON(): VariableTokenJSON;
+        evaluate(options: EvaluateOptions): Promise<unknown>;
+    }
+}
+declare module "parse/sequence-token" {
+    import type { EvaluateOptions } from "types";
+    import type { LookupTokenJSON, IfTokenJSON, VariableTokenJSON, TextTokenJSON, SequenceTokenJSON } from "tojson-types";
+    import type { default as TextToken } from "parse/text/token";
+    import type { default as LookupToken } from "parse/lookup/token";
+    import type { default as IfToken } from "parse/if/token";
+    import type { default as VariableToken } from "parse/variable/token";
+    import BaseToken from "parse/base-token";
+    export interface SequenceTokenOptions {
+        position: number;
+        value?: LookupToken | IfToken | VariableToken | TextToken | SequenceToken;
+    }
+    export default class SequenceToken extends BaseToken {
+        value: Array<LookupToken | IfToken | VariableToken | TextToken | SequenceToken>;
+        constructor(options: SequenceTokenOptions);
+        add(token: LookupToken | IfToken | VariableToken | TextToken | SequenceToken): void;
+        get unwrap(): SequenceToken | TextToken | LookupToken | IfToken | VariableToken;
+        toJSON(): SequenceTokenJSON | LookupTokenJSON | IfTokenJSON | VariableTokenJSON | TextTokenJSON;
+        evaluate(options: EvaluateOptions): Promise<unknown>;
+    }
+}
+declare module "parse/arguments/token" {
+    import type { EvaluateOptions } from "types";
+    import type { ArgumentsTokenJSON } from "tojson-types";
+    import type ComparisonToken from "parse/comparison/token";
+    import type IfToken from "parse/if/token";
+    import type LogicToken from "parse/logic/token";
+    import type LookupToken from "parse/lookup/token";
+    import type TextToken from "parse/text/token";
+    import type VariableToken from "parse/variable/token";
+    import BaseToken from "parse/base-token";
+    import SequenceToken from "parse/sequence-token";
+    export interface ArgumentsTokenOptions {
+        position: number;
+        value?: Array<LookupToken | IfToken | VariableToken | TextToken | SequenceToken | LogicToken | ComparisonToken>;
+    }
+    export default class ArgumentsToken extends BaseToken {
+        value: Array<LookupToken | IfToken | VariableToken | TextToken | SequenceToken | LogicToken | ComparisonToken>;
+        constructor(options: ArgumentsTokenOptions);
+        toJSON(): ArgumentsTokenJSON;
+        evaluate(options: EvaluateOptions): Promise<unknown[]>;
+    }
+}
+declare module "errors" {
+    /** Represents a generic error when attempting to parse an expression */
+    export class ExpressionError extends Error {
+        /** When defined: where the error was encountered within the expression text */
+        position?: number;
+        constructor(
+        /** Message to associate with the error */
+        message: string, 
+        /** Where the error was encountered within the expression text */
+        position?: number);
+        static get name(): string;
+    }
+    /** Represents an error related to the arguments list or a singular argument to be passed to a variable */
+    export class ExpressionArgumentsError extends ExpressionError {
+        /** The index of the argument in the arguments list */
+        index?: number;
+        /** The variable name the arguments list belongs to */
+        varname?: string;
+        constructor(
+        /** Message to associate with the error */
+        message: string, 
+        /** Where the error was encountered within the expression text */
+        position?: number, 
+        /** The index of the argument in the arguments list */
+        index?: number, 
+        /** The variable name the arguments list belongs to */
+        varname?: string);
+        static get name(): string;
+    }
+    /** Represents an error related to parsing a variable */
+    export class ExpressionVariableError extends ExpressionError {
+        /** The associated variable name */
+        varname?: string;
+        constructor(
+        /** Message to associate with the error */
+        message: string, 
+        /** Where the error was encountered within the expression text */
+        position?: number, 
+        /** The variable name to associate with the error */
+        varname?: string);
+        static get name(): string;
+    }
+    /** Represents a syntax error within the given expression */
+    export class ExpressionSyntaxError extends ExpressionError {
+        /** The character associated with the error */
+        character?: string;
+        constructor(
+        /** Message to associate with the error */
+        message: string, 
+        /** Where the error was encountered within the expression text */
+        position?: number, 
+        /** The character associated with the error */
+        character?: string);
+        static get name(): string;
+    }
+}
+declare module "parse/lookup/token" {
+    import type { EvaluateOptions } from "types";
+    import type { LookupTokenJSON } from "tojson-types";
+    import BaseToken from "parse/base-token";
+    import ArgumentsToken from "parse/arguments/token";
+    export interface LookupTokenOptions {
+        position: number;
+        prefix: string;
+        value: string;
+        arguments?: ArgumentsToken;
+    }
+    export default class LookupToken extends BaseToken {
+        prefix: string;
+        value: string;
+        arguments?: ArgumentsToken;
+        constructor(options: LookupTokenOptions);
+        toJSON(): LookupTokenJSON;
+        evaluate(options: EvaluateOptions): Promise<unknown>;
+    }
+}
+declare module "parse/comparison/operators" {
+    import type { ComparisonOperatorDefinition } from "types";
+    /** Comparison Operator Map */
+    const _default_1: Map<string, ComparisonOperatorDefinition>;
+    export default _default_1;
+}
+declare module "parse/comparison/token" {
+    import type { EvaluateOptions } from "types";
+    import type { ComparisonTokenJSON } from "tojson-types";
+    import type { default as TextToken } from "parse/text/token";
+    import type { default as LookupToken } from "parse/lookup/token";
+    import type { default as IfToken } from "parse/if/token";
+    import type { default as VariableToken } from "parse/variable/token";
+    import type { default as SequenceToken } from "parse/sequence-token";
+    type operand = LookupToken | IfToken | VariableToken | TextToken | SequenceToken;
+    import BaseToken from "parse/base-token";
+    export interface ComparisonTokenOptions {
+        position: number;
+        value: string;
+        left: operand;
+        right?: operand;
+    }
+    export default class ComparisonToken extends BaseToken {
+        value: string;
+        left: operand;
+        right?: operand;
+        constructor(options: ComparisonTokenOptions);
+        toJSON(): ComparisonTokenJSON;
+        evaluate(options: EvaluateOptions): Promise<unknown>;
+    }
+}
+declare module "parse/if/token" {
+    import type { EvaluateOptions } from "types";
+    import type { IfTokenJSON } from "tojson-types";
+    import type ComparisonToken from "parse/comparison/token";
+    import type LogicToken from "parse/logic/token";
+    import type LookupToken from "parse/lookup/token";
+    import type VariableToken from "parse/variable/token";
+    import type SequenceToken from "parse/sequence-token";
+    import type TextToken from "parse/text/token";
+    type ConditionToken = ComparisonToken | LogicToken;
+    type OperandToken = LookupToken | IfToken | VariableToken | TextToken | SequenceToken;
+    import BaseToken from "parse/base-token";
+    export interface IfTokenOptions {
+        position: number;
+        value: ConditionToken;
+        whenTrue: OperandToken;
+        whenFalse?: OperandToken;
+    }
+    export default class IfToken extends BaseToken {
+        value: ConditionToken;
+        whenTrue: OperandToken;
+        whenFalse?: OperandToken;
+        constructor(options: IfTokenOptions);
+        toJSON(): IfTokenJSON;
+        evaluate(options: EvaluateOptions): Promise<unknown>;
+    }
+}
+declare module "misc/split" {
+    import { type GenericToken } from "types";
+    /** Splits the input into an array of unicode-aware characters
+     * @returns {string[]} An array containing the delimited characters where each entry is a character
+    */
+    export const split: (
+    /** Input text to split into characters */
+    input: string) => string[];
+    /** Converts the input into a list of Generic tokens for further processing
+     * * Unicode multi-byte/character glyphs are treated as a singular entry
+     * * Each whitespace character is treated as a singular entry
+     * * `\` is treated as a singular entry, the following character is also treated as a singular entry regardless of what it is
+     * * \`\` is treated as a singular entry
+     * * All other ascii punctionation is treated as a singular entry
+     * * Non-unicode characters that are not whitespace or punctuation are grouped together and treated as a singular entry
+    */
+    export const tokenize: (input: string) => GenericToken[];
+}
+declare module "parse/root/token" {
+    import type { RootTokenJSON } from "tojson-types";
+    import type { TokenizeOptions, PreEval, EvaluateData, LookupMap, VariableMap, LogicOperatorMap, ComparisonOperatorMap } from "types";
+    import SequenceToken from "parse/sequence-token";
+    export type RootTokenOptions = TokenizeOptions;
+    export interface RootEvaluateOptions {
+        onlyValidate?: boolean;
+        preeval?: PreEval;
+        data?: EvaluateData;
+    }
+    export default class RootToken extends SequenceToken {
+        lookups: LookupMap;
+        variables: VariableMap;
+        expression: string;
+        logicOperators: LogicOperatorMap;
+        comparisonOperators: ComparisonOperatorMap;
+        constructor(options: RootTokenOptions);
+        toJSON(): RootTokenJSON;
+        evaluate(options?: RootEvaluateOptions): Promise<unknown>;
+    }
+}
+declare module "parse/text/escape" {
+    import type { GenericToken, TokenizeResult } from "types";
+    const _default_2: (tokens: GenericToken[], cursor: number, escapeChars?: string) => TokenizeResult<GenericToken>;
+    export default _default_2;
+}
+declare module "parse/text/quote" {
+    import type { GenericToken, TokenizeResult } from "types";
+    import TextToken from "parse/text/token";
+    const _default_3: (tokens: GenericToken[], cursor: number) => TokenizeResult<TextToken>;
+    export default _default_3;
+}
+declare module "parse/variable/tokenize" {
+    import type { GenericToken, TokenizeOptions, TokenizeResult } from "types";
+    import VariableToken from "parse/variable/token";
+    const _default_4: (tokens: GenericToken[], cursor: number, options: TokenizeOptions) => TokenizeResult<VariableToken>;
+    export default _default_4;
+}
+declare module "parse/whitespace/tokenize" {
+    import type { GenericToken, TokenizeResult } from "types";
+    /** Consumes sequential whitespace from `tokens` beginning at `cursor` */
+    const _default_5: (tokens: GenericToken[], cursor: number) => TokenizeResult<string>;
+    export default _default_5;
+}
+declare module "parse/comparison/tokenize" {
+    import type { GenericToken, TokenizeOptions, TokenizeResult } from "types";
+    import ComparisonToken from "parse/comparison/token";
+    const _default_6: (tokens: GenericToken[], cursor: number, options: TokenizeOptions) => TokenizeResult<ComparisonToken>;
+    export default _default_6;
+}
+declare module "parse/logic/tokenize" {
+    import type { GenericToken, TokenizeOptions, TokenizeResult } from "types";
+    import LogicToken from "parse/logic/token";
+    const tokenizeLogicOperator: (tokens: GenericToken[], cursor: number, options: TokenizeOptions) => TokenizeResult<LogicToken>;
+    export default tokenizeLogicOperator;
+}
+declare module "parse/if/tokenize" {
+    import type { GenericToken, TokenizeOptions, TokenizeResult } from "types";
+    import IfToken from "parse/if/token";
+    const _default_7: (tokens: GenericToken[], cursor: number, options: TokenizeOptions) => TokenizeResult<IfToken>;
+    export default _default_7;
+}
+declare module "parse/arguments/argument" {
+    import type { GenericToken, TokenizeOptions, TokenizeResult } from "types";
+    import IfToken from "parse/if/token";
+    import LookupToken from "parse/lookup/token";
+    import SequenceToken from "parse/sequence-token";
+    import TextToken from "parse/text/token";
+    import VariableToken from "parse/variable/token";
+    const _default_8: (tokens: GenericToken[], cursor: number, options: TokenizeOptions) => TokenizeResult<LookupToken | IfToken | VariableToken | TextToken | SequenceToken>;
+    export default _default_8;
+}
+declare module "parse/arguments/tokenize" {
+    import type { GenericToken, TokenizeOptions, TokenizeResult } from "types";
+    import ArgumentsToken from "parse/arguments/token";
+    const _default_9: (tokens: GenericToken[], cursor: number, options: TokenizeOptions) => TokenizeResult<ArgumentsToken>;
+    export default _default_9;
+}
+declare module "parse/lookup/tokenize" {
+    import type { GenericToken, TokenizeOptions, TokenizeResult } from "types";
+    import LookupToken from "parse/lookup/token";
+    const _default_10: (tokens: GenericToken[], cursor: number, options: TokenizeOptions) => TokenizeResult<LookupToken>;
+    export default _default_10;
+}
+declare module "parse/text/block" {
+    import type { GenericToken, TokenizeOptions, TokenizeResult } from "types";
+    import type IfToken from "parse/if/token";
+    import type LookupToken from "parse/lookup/token";
+    import type VariableToken from "parse/variable/token";
+    import SequenceToken from "parse/sequence-token";
+    import TextToken from "parse/text/token";
+    const _default_11: (tokens: GenericToken[], cursor: number, options: TokenizeOptions) => TokenizeResult<LookupToken | IfToken | VariableToken | TextToken | SequenceToken>;
+    export default _default_11;
+}
+declare module "parse/root/tokenize" {
+    import type { TokenizeOptions } from "types";
+    import RootToken from "parse/root/token";
+    const _default_12: (options: TokenizeOptions) => RootToken;
+    export default _default_12;
+}
+declare module "expressionish" {
+    import { TokenizeOptions, EvaluateOptions } from "types";
+    export { default as ArgumentsToken, ArgumentsTokenOptions } from "parse/arguments/token";
+    export { default as BaseToken, BaseTokenOptions } from "parse/base-token";
+    export { default as ComparisonToken, ComparisonTokenOptions } from "parse/comparison/token";
+    export { default as IfToken, IfTokenOptions } from "parse/if/token";
+    export { default as LogicToken, LogicTokenOptions } from "parse/logic/token";
+    export { default as LookupToken, LookupTokenOptions } from "parse/lookup/token";
+    export { default as RootToken, RootTokenOptions, RootEvaluateOptions } from "parse/root/token";
+    export { default as SequenceToken } from "parse/sequence-token";
+    export { default as TextToken, TextTokenOptions } from "parse/text/token";
+    export { default as VariableToken, VariableTokenOptions } from "parse/variable/token";
+    export { ExpressionError, ExpressionArgumentsError, ExpressionSyntaxError, ExpressionVariableError } from "errors";
+    /** Parses a string expression into a usable Expressionish-Token instance */
+    export const tokenize: (
+    /** Options to use during tokenization */
+    options: TokenizeOptions) => import("expressionish").RootToken;
+    /** Parses then evaluates expression text */
+    export const evaluate: (
+    /** Options passed to the parser and evaluator */
+    options: EvaluateOptions) => Promise<unknown>;
+}