@witchcraft/expressit 0.0.2

package/src/types/ast.ts

@@ -0,0 +1,148 @@
+import type { AnyFunction } from "@alanscodelog/utils"
+
+import type { ArrayNode } from "../ast/classes/ArrayNode.js"
+import type { ConditionNode } from "../ast/classes/ConditionNode.js"
+import type { ErrorToken } from "../ast/classes/ErrorToken.js"
+import type { ExpressionNode } from "../ast/classes/ExpressionNode.js"
+import type { GroupNode } from "../ast/classes/GroupNode.js"
+import type { ValidToken } from "../ast/classes/ValidToken.js"
+import type { VariableNode } from "../ast/classes/VariableNode.js"
+
+
+export type AddParameters<T extends AnyFunction, TExtra extends any[] = [boolean]> = (...args: [...Parameters<T>, ...TExtra]) => ReturnType<T>
+
+export enum TOKEN_TYPE {
+	VALUE = "VALUE",
+	AND = "AND",
+	OR = "OR",
+	NOT = "NOT",
+	BACKTICK = "BACKTICK",
+	SINGLEQUOTE = "SINGLEQUOTE",
+	DOUBLEQUOTE = "DOUBLEQUOTE",
+	PARENL = "PARENL",
+	PARENR = "PARENR",
+	BRACKETL = "BRACKETL",
+	BRACKETR = "BRACKETR",
+	OP_EXPANDED_SEP = "OP_EXPANDED",
+	OP_CUSTOM = "OP_CUSTOM",
+	REGEX = "REGEX",
+}
+
+/**
+ * @internal
+ * Note if the negation operator, `!`, is used as a propertyOperator, this will return the wrong type.
+ */
+export type ExtractTokenType<T extends string> =
+	T extends "`"
+	? TOKEN_TYPE.BACKTICK
+	: T extends `'`
+	? TOKEN_TYPE.SINGLEQUOTE
+	: T extends `"`
+	? TOKEN_TYPE.DOUBLEQUOTE
+	: T extends `/`
+	? TOKEN_TYPE.REGEX
+	: T extends `(`
+	? TOKEN_TYPE.PARENL
+	: T extends `)`
+	? TOKEN_TYPE.PARENR
+	: T extends `[`
+	? TOKEN_TYPE.BRACKETL
+	: T extends `]`
+	? TOKEN_TYPE.BRACKETR
+	: T extends `and`
+	? TOKEN_TYPE.AND
+	: T extends `&&`
+	? TOKEN_TYPE.AND
+	: T extends `&`
+	? TOKEN_TYPE.AND
+	: T extends `or`
+	? TOKEN_TYPE.OR
+	: T extends `||`
+	? TOKEN_TYPE.OR
+	: T extends `|`
+	? TOKEN_TYPE.OR
+	: T extends `not`
+	? TOKEN_TYPE.NOT
+	: T extends `!`
+	? TOKEN_TYPE.NOT
+	: TOKEN_TYPE.VALUE
+
+export type TokenParenTypes =
+	| TOKEN_TYPE.PARENL
+	| TOKEN_TYPE.PARENR
+export type TokenBracketTypes =
+	| TOKEN_TYPE.BRACKETL
+	| TOKEN_TYPE.BRACKETR
+
+export type TokenDelimiterTypes =
+	| TokenParenTypes
+	| TokenQuoteTypes
+	| TokenBracketTypes
+	| TOKEN_TYPE.OP_EXPANDED_SEP
+
+export type TokenQuoteTypes =
+	| TOKEN_TYPE.BACKTICK
+	| TOKEN_TYPE.SINGLEQUOTE
+	| TOKEN_TYPE.DOUBLEQUOTE
+	| TOKEN_TYPE.REGEX
+
+export type TokenBooleanTypes =
+	| TOKEN_TYPE.AND
+	| TOKEN_TYPE.OR
+
+export type TokenOperatorTypes =
+	| TokenBooleanTypes
+	| TOKEN_TYPE.NOT
+
+export type TokenPropertyOperatorTypes =
+	| TOKEN_TYPE.OP_CUSTOM
+	| TOKEN_TYPE.OP_EXPANDED_SEP
+
+
+// export type EmptyObj = Record<"start"|"end", undefined>
+export type EmptyObj = Record<any, never>
+export type FirstConstructorParam<T extends new (...args: any) => any> = ConstructorParameters<T>["0"]
+
+export type Position = {
+	start: number
+	end: number
+}
+
+export enum AST_TYPE {
+	EXPRESSION = "EXPRESSION",
+	GROUP = "GROUP",
+	ARRAY = "ARRAY",
+	CONDITION = "CONDITION",
+	VARIABLE = "VARIABLE",
+}
+
+// #region AST nodes
+
+/**
+ * For more easily typing tokens that might or might not be valid.
+ *
+ * Using @see Token does not work well in certain situations and is also more complex because it has so many generics.
+ */
+export type AnyToken<
+	TType extends TOKEN_TYPE = TOKEN_TYPE,
+> =
+	| ValidToken<TType>
+	| ErrorToken<TType>
+
+export type ParserResults = ExpressionNode | ConditionNode | GroupNode | ErrorToken<TOKEN_TYPE.VALUE>
+/* eslint-disable @typescript-eslint/naming-convention */
+
+
+export type Nodes = ExpressionNode | ConditionNode | GroupNode | VariableNode | ArrayNode
+
+/**
+ * Contains any delimiter tokens some AST nodes ( @see GroupNode and @see VariableNode ) can have.
+ *
+ * These are usually not important for evaluating an expression but are useful for syntax highlighting.
+ */
+export type NodeDelimiters<TLEFT extends TOKEN_TYPE, TRIGHT extends TOKEN_TYPE = TLEFT> = {
+	left: AnyToken<TLEFT>
+	right: AnyToken<TRIGHT>
+	/** Only exists if regexes are enabled and this is a regex value. */
+	flags?: ValidToken<TOKEN_TYPE.VALUE>
+}

package/src/types/autocomplete.ts

@@ -0,0 +1,152 @@
+import type { AnyToken, Position } from "./ast.js"
+
+import type { ValidToken } from "../ast/classes/ValidToken.js"
+
+
+/**
+ * Contains information regarding the tokens around a cursor position. Mostly for internally use by @see autosuggest.
+ *
+ * Notes:
+ *
+ * - There are no whitespace tokens because whitespace is not tokenized. `prev`, `at`, `next` properties that contain tokens are set looking only at the list of tokens extracted from the ast by @see extractTokens. This is why there is an extra `whitespace` property to tell us whether there is whitespace (i.e. a hole) between the cursor and the next/prev **valid** tokens or if it can't find any, the start/end of the input.
+ * - If next/prev are invalid tokens, note that there are cases where more invalid tokens might follow them. To get them we can use @see getSurroundingErrors or we can just find their index in the tokens list and go forward/backward as needed:
+ * ```ts
+ * let i =  tokens.findIndex(t => t === info.next)
+ * while (tokens[i] instanceof ErrorToken) {...}
+ * ```
+ *
+ * Examples:
+ *
+ * ```js
+ * aaaa| bbbb // tokens: ["aaaa", TokenError(operator), "bbbb"]
+ *     ^
+ * {
+ * 	index: 4, // cursor position
+ * 	at: undefined, // it's not inside a token
+ * 	prev: "aaaa",
+ * 	next: TokenError, // operator is missing to the right
+ * 	// closest valid tokens to either side
+ * 	valid: {
+ * 		prev: "aaaa",
+ * 		next: "bbbb",
+ * 	},
+ * 	// whether there is whitespace between the cursor and the next/prev valid tokens or start/end of input
+ * 	whitespace: {
+ * 		prev: false,
+ * 		next: true,
+ * 	}
+ * }
+ * ```
+ * ```js
+ * aaaa || bb|bb && cccc
+ *           ^
+ * {
+ * 	index: 10,
+ * 	at: "bbbb", // it's inside a token
+ * 	prev: "||",
+ * 	next: "&&",
+ * 	valid: {
+ * 		prev: "||",
+ * 		next: "&&",
+ * 	},
+ * 	whitespace: {
+ * 		prev: true,
+ * 		next: true,
+ * 	}
+ * }
+ * ```
+ */
+export type CursorInfo = {
+	index: number
+	/**
+	 * The token the cursor is inside of. By "inside", we mean the ends of the token are before/after the cursor respectively (e.g. `a|a`, but NOT `|aa` or `aa|`). This token, if defined, is always a valid token, since error tokens have no length.
+	 *
+	 * Note though that there are cases where one might be inside a variable but not inside a token because quotes are their own tokens (e.g. `"|var"` or `"var|"`).
+	 */
+	at?: ValidToken
+	/** The first token, valid or invalid, that starts at or after the index position. */
+	next?: AnyToken
+	/** The first token (going backwards), valid or invalid, that ends at or before the index position. */
+	prev?: AnyToken
+	/** Closest valid tokens. */
+	valid: {
+		/** Closest prev valid token. */
+		next?: ValidToken
+		/** Closest next valid token. */
+		prev?: ValidToken
+	}
+	/** Whether there is whitespace between the cursor and the next/prev valid tokens or start/end of the input. */
+	whitespace: {
+		/** Whether there is whitespace between the cursor and the next valid token or the end of the input. */
+		next: boolean
+		/** Whether there is whitespace between the cursor and the prev valid token or the start of the input. */
+		prev: boolean
+	}
+}
+
+export enum SUGGESTION_TYPE {
+	// can ignore whitespace requirement if replacing with quoted
+	VARIABLE = "VARIABLE",
+	ARRAY_VALUE = "ARRAY_VALUE",
+	VALUE = "VALUE",
+	PREFIX = "PREFIX",
+	BOOLEAN_WORD_OP = "BOOLEAN_WORD_OP",
+	BOOLEAN_SYMBOL_OP = "BOOLEAN_SYMBOL_OP",
+	BACKTICK = "BACKTICK",
+	DOUBLEQUOTE = "DOUBLEQUOTE",
+	SINGLEQUOTE = "SINGLEQUOTE",
+	PARENL = "PARENL",
+	PARENR = "PARENR",
+	PROPERTY = "PROPERTY",
+	EXPANDED_PROPERTY_OPERATOR = "EXPANDED_PROPERTY_OPERATOR",
+	CUSTOM_PROPERTY_OPERATOR = "CUSTOM_PROPERTY_OPERATOR",
+	PROPERTY_SEP = "PROPERTY_SEP",
+	BRAKCETR = "BRAKCETR",
+	REGEX = "REGEX",
+	REGEX_FLAGS = "REGEX_FLAGS",
+	/** This is not an oversight, I haven't figured out a fast way to detect left bracket errors. */
+	// BRAKCETL = "BRAKCETL",
+}
+
+/**
+ * A suggestion entry that describes a type of suggestion.
+ */
+export type Suggestion = {
+	type: SUGGESTION_TYPE
+	/** The range the suggestion should replace / be inserted at. */
+	range: Position
+	/** @see CursorInfo */
+	cursorInfo: CursorInfo
+	/** Tells us any additional requirements for inserting the suggestion. */
+	requires: {
+		/**
+		 * Whether the suggestions requires inserting whitespace before/after to keep the intent of the expression consistent. For example, an unquoted variable needs a space between it and a non-symbol operator.
+		 *
+		 * In the case of variables this requirement can be ignored though if you insert a quoted value.
+		 */
+		whitespace: {
+			after: boolean
+			before: boolean
+		}
+		/**
+		 * If prefixableGroups is enabled, a suggestion can be a prefix suggestion and this tells us whether `()` needs to be inserted at the end in the case it does not already exist.
+		 *
+		 * For example, a user might choose to insert a prefix in this situation `a && |` and we want the result to be `a && prefix()` because without the `()` the prefix will probably be an invalid variable name on insertion.
+		 *
+		 * The opposite happens with an existing prefix where the user might want to replace it. `a && existing|(...)`. We want the result to be `a && replacement(...)` not `a && replacement()(...)`.
+		 */
+		group: boolean
+		/** If `prefixableValues` is enabled and a value is prefixed, contains the prefix it was prefixed with. Note that the prefix is included in the range. This way you can choose to suggest/replace just the prefix, just the value or both. */
+		prefix: string | false
+	}
+	/**
+	 * Whether the suggestion was created because there was an error token there and it would fix it.
+	 */
+	isError: boolean
+}
+
+
+export type Completion = {
+	suggestion: Suggestion
+	value: string
+}

package/src/types/errors.ts

@@ -0,0 +1,40 @@
+import type { DeepPartial } from "@alanscodelog/utils"
+import type { ILexingError, IRecognitionException, IToken } from "chevrotain"
+
+import type { ParserOptions } from "./parser.js"
+
+
+export enum ERROR_CODES {
+	"PARSER_ERROR" = "PARSER.ERROR",
+	"PARSER_POSITION_ERROR" = "PARSER.POSITION",
+	"PARSER_CONFLICTING_OPTIONS_ERROR" = "PARSER.OPTIONS.CONFLICTING",
+	"PARSER_OPTION_REQUIRED_ERROR" = "PARSER.OPTIONS.CUSTOM_REQUIRED",
+}
+export type ErrorInfo<T extends keyof ErrorInfos> = ErrorInfos[T]
+export type ErrorInfos = {
+	[ERROR_CODES.PARSER_ERROR]: {
+		input: string
+		options: DeepPartial<ParserOptions> | undefined
+		// eslint-disable-next-line @typescript-eslint/naming-convention
+		"parsed options": ParserOptions
+		error: Error
+		// eslint-disable-next-line @typescript-eslint/naming-convention
+		"lexer errors": ILexingError[]
+		// eslint-disable-next-line @typescript-eslint/naming-convention
+		"lexed tokens": IToken[]
+		// eslint-disable-next-line @typescript-eslint/naming-convention
+		"parser errors": IRecognitionException[]
+	}
+	[ERROR_CODES.PARSER_POSITION_ERROR]: {
+		start?: number
+		end?: number
+	}
+	[ERROR_CODES.PARSER_CONFLICTING_OPTIONS_ERROR]: {
+		prohibited: string[]
+		invalid: string
+	}
+	[ERROR_CODES.PARSER_OPTION_REQUIRED_ERROR]: {
+		options?: (keyof ParserOptions)[]
+		requires: keyof ParserOptions
+	}
+}

package/src/types/index.ts

@@ -0,0 +1,6 @@
+/* Autogenerated Index [Types] */
+
+export * from "./ast.js"
+export * from "./autocomplete.js"
+export * from "./errors.js"
+export * from "./parser.js"