@witchcraft/expressit 0.1.2 → 0.2.0

package/src/types/ast.ts

@@ -1,6 +1,5 @@
 import type { AnyFunction } from "@alanscodelog/utils/types"
 
-import type { ArrayNode, ConditionNode, ErrorToken, ExpressionNode, GroupNode, ValidToken, VariableNode } from "../ast/classes/index.js"
 
 export type AddParameters<T extends AnyFunction, TExtra extends any[] = [boolean]> = (...args: [...Parameters<T>, ...TExtra]) => ReturnType<T>
 
@@ -94,7 +93,8 @@ export type TokenPropertyOperatorTypes =
 
 // 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 FirstParam<T extends AnyFunction> = Parameters<T>["0"]
+
 
 export type Position = {
 	start: number
@@ -103,33 +103,198 @@ export type Position = {
 
 export enum AST_TYPE {
 	EXPRESSION = "EXPRESSION",
+	NORMALIZED_EXPRESSION = "NORMALIZED_EXPRESSION",
 	GROUP = "GROUP",
 	ARRAY = "ARRAY",
 	CONDITION = "CONDITION",
+	NORMALIZED_CONDITION = "NORMALIZED_CONDITION",
 	VARIABLE = "VARIABLE",
 }
-
 // #region AST nodes
 
+
+export type RawNode<T extends Node> = Omit<T, "valid" | "type" | "isNode">
+
+
+/**
+ * The base type from which {@link ValidToken} and {@link ErrorToken} extend.
+ *
+ * Mostly for internal use, and I would suggest using {@link AnyToken} instead of this for typing things.
+ *
+ */
+export interface BaseToken {
+	isToken: true
+	start: number
+	end: number
+}
+/**
+ * Valid tokens always have a value, even if it might be an empty string.
+ */
+export interface ValidToken<TType extends TOKEN_TYPE = TOKEN_TYPE> extends BaseToken {
+	valid: true
+	type: TType
+	value: string
+}
+/**
+ * The type for invalid recovery tokens.
+ *
+ * Unlike valid tokens, error tokens:
+ *
+ * - Have no value.
+ *
+ * - Contain an extra property, `expected` with an array of tokens *that would have fixed the issue* (NOT every possible token that could be there).
+ *
+ * - The start end positions will always be equal. An invalid token has no length.
+ */
+export interface ErrorToken extends BaseToken {
+	type?: undefined
+	value?: undefined
+	valid: false
+	expected: TOKEN_TYPE[]
+}
+
 /**
  * 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.
+ * Using {@link 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>
+	| ErrorToken
 
-export type ParserResults = ExpressionNode | ConditionNode | GroupNode | ErrorToken<TOKEN_TYPE.VALUE>
+export type RawToken<T extends AnyToken> = Omit<T, "isToken" | "valid">
+
+export type ParserResults = ExpressionNode | ConditionNode | GroupNode | ErrorToken
 /* eslint-disable @typescript-eslint/naming-convention */
 
 
+/**
+ * The base AST type all node types extend from.
+ */
+
+export interface Node<
+	TType extends AST_TYPE = AST_TYPE,
+	TValid extends boolean = boolean,
+> {
+	isNode: true
+	type: TType
+	start: number
+	end: number
+	valid: TValid
+}
+
+
+/**
+ * A node that symbolizes a parenthesized expression (might be negated), and if `prefixableGroups` is enabled, a prefixed expression {@link ParserOptions} .
+ *
+ * ```txt
+ * (a || b)
+ *  |----| ExpressionNode
+ * |------| GroupNode
+ *
+ * !(a || b)
+ * ^ prefix: "not" Token
+ *   |----| ExpressionNode
+ * |-------| GroupNode
+ * ```
+ *
+ * If `prefixableGroups` is enabled:
+ * ```txt
+ * prefix(a || b)
+ * |----| prefix: ConditionNode
+ *        |----| ExpressionNode
+ * |------------| GroupNode
+ *
+ * !prefix(a || b)
+ * |-----| prefix: ConditionNode
+ *         |----| ExpressionNode
+ * |-------------| GroupNode
+ *
+ * !(a || b)
+ * ^ prefix: STILL a "not" Token
+ * ```
+ */
+export interface GroupNode<
+	TValid extends boolean = boolean,
+	TPrefixable extends boolean = true,
+	TPrefix extends
+		TPrefixable extends true
+			? ConditionNode<TValid> |
+			ValidToken<TOKEN_TYPE.NOT> |
+			undefined
+			: ValidToken<TOKEN_TYPE.NOT> |
+			undefined =
+		TPrefixable extends true
+			? ConditionNode<TValid> |
+			ValidToken<TOKEN_TYPE.NOT> |
+			undefined
+			: ValidToken<TOKEN_TYPE.NOT>,
+> extends Node<AST_TYPE.GROUP> {
+	/**
+	 * If the condition is negated this will contain a "not" **token**, {@link ValidToken} .
+	 *
+	 * If `prefixableGroups` is enabled and the group is prefixed by a **condition**, this will be an {@link ConditionNode}.
+	 *
+	 * **Careful:** `!(a)` here this would not be a **condition** since it's just a regular negation.
+	 *
+	 * See examples at {@link GroupNode} .
+	 */
+	prefix: TPrefix
+	expression:
+	| ConditionNode<TValid>
+	| GroupNode<TValid>
+	| ExpressionNode<TValid>
+	| (TValid extends false ? ErrorToken : never)
+	/**
+	 * The parenthesis tokens, {@link ValidToken} . These will always be defined (although not necessarily with valid tokens).
+	 */
+	paren: NodeDelimiters<TOKEN_TYPE.PARENL, TOKEN_TYPE.PARENR>
+}
+
+
+/**
+ * A variable represents **just** a string value (NOT it's boolean value).
+ *
+ * The parser will never return just a variable, they are always wrapped in an {@link ConditionNode} to give them a boolean value.
+ *
+ * A variable might or might not be quoted. If it is, the `quote` property will contain the quote tokens, see {@link ValidToken} . While they will always be of the same quote type, one might be valid while the other might not (see {@link ErrorToken}).
+ *
+ * `value` will contain the string value of the variable. The text is not processed and might still contain escaped characters (even if unquoted!) that need to be removed to get the intended value. This is so that the position of the node is accurate. {@link evaluate} will take care of unescaping when needed.
+ *
+ * If `prefixableStrings` is true, the `prefix` property might contain a value token.
+ */
+
+export interface VariableNode<TValid extends boolean = boolean> extends Node<AST_TYPE.VARIABLE, TValid> {
+	value: TValid extends boolean
+		? AnyToken<TOKEN_TYPE.VALUE>
+		: TValid extends true
+		? ValidToken<TOKEN_TYPE.VALUE>
+	: ErrorToken
+	prefix?: ValidToken<TOKEN_TYPE.VALUE> // todo
+	quote?: NodeDelimiters<TokenQuoteTypes, TokenQuoteTypes>
+}
+
+export interface ExpressionNode<TValid extends boolean = boolean> extends Node<AST_TYPE.EXPRESSION> {
+	operator: AnyToken<TokenBooleanTypes>
+	left:
+	| ExpressionNode<TValid>
+	| ConditionNode<TValid>
+	| GroupNode<TValid>
+	| (TValid extends false ? ErrorToken : never)
+	right:
+	| ExpressionNode<TValid>
+	| ConditionNode<TValid>
+	| GroupNode<TValid>
+	| (TValid extends false ? ErrorToken : never)
+}
+
+
 export type Nodes = ExpressionNode | ConditionNode | GroupNode | VariableNode | ArrayNode
 
 /**
- * Contains any delimiter tokens some AST nodes ( @see GroupNode and @see VariableNode ) can have.
+ * Contains any delimiter tokens some AST nodes ( {@link GroupNode} and {@link VariableNode} ) can have.
  *
  * These are usually not important for evaluating an expression but are useful for syntax highlighting.
  */
@@ -139,3 +304,123 @@ export type NodeDelimiters<TLEFT extends TOKEN_TYPE, TRIGHT extends TOKEN_TYPE =
 	/** Only exists if regexes are enabled and this is a regex value. */
 	flags?: ValidToken<TOKEN_TYPE.VALUE>
 }
+
+
+export interface ArrayNode<TValid extends boolean = boolean> extends Node<AST_TYPE.ARRAY> {
+	values: VariableNode[]
+	bracket: NodeDelimiters<TOKEN_TYPE.BRACKETL, TOKEN_TYPE.BRACKETR>
+	valid: TValid
+}
+
+
+/**
+ * A condition is composed of a {@link Variable} , and, if it's negated, a "not" `operator` token, see {@link ValidToken}.
+ *
+ * The `value` property refers to the boolean value of the condition (not to the string value of the variable). See the `operator` property.
+ *
+ */
+export interface ConditionNode<
+	TValid extends boolean = boolean,
+> extends Node<AST_TYPE.CONDITION> {
+	/**
+	 * Contains a value node which could be a variable, an array node (if enabled), or a group.
+	 *
+	 * Might be an error in cases like:
+	 * - just passing a negation operator
+	 * - if condition property operators are used and you have an input like just `[SEP]`, `op[SEP]`, `prop[SEP]op[SEP]`, `[CUSTOM OP]`, or `prop[CUSTOM OP]` where the variable is missing.
+	 */
+	value:
+	| VariableNode<TValid>
+	| ArrayNode<TValid>
+	| GroupNode<TValid>
+	| (TValid extends false ? ErrorToken : never)
+	/**
+	 * If the condition was negated, contains the "not" token, {@link ValidToken} , the condition was negated with.
+	 */
+	operator?: ValidToken<TOKEN_TYPE.NOT>
+	/**
+	 * If condition property operators are used, this will contain the property (as a variable), or an error token if it was missing (but some separator or operator was passed).
+	 *
+	 * While the property is a variable and can be a quoted variable, it cannot be a prefixed variable string.
+	 *
+	 * See the corresponding {@link ParserOptions} for more details.
+	 */
+	property?: VariableNode | (TValid extends false ? ErrorToken : never)
+	/**
+	 * If condition property operators are used, this will contain the operator.
+	 *
+	 * If a "short" form was used, this will contain an `OP_CUSTOM` type token, and the condition's `sep` will always be undefined.
+	 *
+	 * If a "long/expanded" form was used, this will contain a `VALUE` type token, and at least one of condition's `sep` tokens will be defined.
+	 *
+	 * See the corresponding {@link ParserOptions} for more details.
+	 */
+	propertyOperator?: AnyToken<TOKEN_TYPE.OP_CUSTOM | TOKEN_TYPE.VALUE>
+	/**
+	 * If "long/expanded" form condition property operators are used, this will contain the separators, otherwise it is undefined.
+	 *
+	 * If it's defined, either both side will be valid tokens, or only the left, while the right might be undefined or an error token.
+	 *
+	 * This is because given a string like `[SEP]val` which would produce an error like `[MISSING PROPERTY ERROR][SEP]var`, the separator is always interpreted as being the left one. And even if we have a situation like `op[SEP]var`, it is always interpreted by the parser as `prop[SEP]var`.
+	 *
+	 * Why might the right be undefined instead of an error token? This is because we don't need a separator between the operator and a group, `prop[SEP]op(group)`, but we do between a variable in cases like `prop[SEP]op"var"` which would produce an error token on the right side (we could parse this but it just looks inconsistent).
+	 *
+	 * See the corresponding {@link ParserOptions} for more details.
+	 */
+	sep?: {
+		left?: AnyToken<TOKEN_TYPE.OP_EXPANDED_SEP>
+		right?: AnyToken<TOKEN_TYPE.OP_EXPANDED_SEP>
+	}
+}
+
+export interface NormalizedCondition<
+	TOp extends string = string,
+	TValue = any,
+> {
+	type: AST_TYPE.NORMALIZED_CONDITION
+	value: TValue
+	operator?: TOp
+	property: string[]
+	negate: boolean
+}
+
+
+export interface NormalizedExpression<TType extends string = string, TValue = any> {
+	type: AST_TYPE.NORMALIZED_EXPRESSION
+	left:
+	| NormalizedExpression<TType, TValue>
+	| NormalizedCondition<TType, TValue>
+	right:
+	| NormalizedExpression<TType, TValue>
+	| NormalizedCondition<TType, TValue>
+	operator: TokenBooleanTypes
+}
+
+export type ParentTypes<T extends Node | BaseToken | undefined> =
+	T extends ValidToken
+	?
+	| VariableNode
+	| GroupNode
+	| ExpressionNode
+	| ArrayNode
+	| ConditionNode
+	: T extends ErrorToken
+	? VariableNode
+	| GroupNode
+	| ExpressionNode
+	| ArrayNode
+	| ConditionNode
+	: T extends GroupNode
+	? ExpressionNode | GroupNode | undefined
+	: T extends VariableNode
+	? ConditionNode | ArrayNode | undefined
+	: T extends ExpressionNode
+	? GroupNode | ExpressionNode | undefined
+	: T extends ArrayNode
+	? ConditionNode | undefined
+	: T extends ConditionNode | ExpressionNode
+	? GroupNode | undefined
+	: T extends undefined
+	? undefined
+	: never
+

package/src/types/autocomplete.ts

@@ -1,15 +1,13 @@
-import type { AnyToken, Position } from "./ast.js"
-
-import type { ValidToken } from "../ast/classes/ValidToken.js"
+import type { AnyToken, Position, ValidToken } from "./ast.js"
 
 
 /**
- * Contains information regarding the tokens around a cursor position. Mostly for internally use by @see autosuggest.
+ * Contains information regarding the tokens around a cursor position. Mostly for internally use by {@link 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:
+ * - 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 {@link 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 {@link 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) {...}
@@ -115,7 +113,7 @@ export type Suggestion = {
 	type: SUGGESTION_TYPE
 	/** The range the suggestion should replace / be inserted at. */
 	range: Position
-	/** @see CursorInfo */
+	/** {@link CursorInfo} */
 	cursorInfo: CursorInfo
 	/** Tells us any additional requirements for inserting the suggestion. */
 	requires: {

package/src/types/parser.ts

@@ -1,12 +1,7 @@
 import type { DeepRequired, MakeRequired } from "@alanscodelog/utils/types"
 
-import type { Position, TOKEN_TYPE } from "./ast.js"
+import type { ArrayNode, ConditionNode, NormalizedCondition, Position, TOKEN_TYPE, ValidToken, VariableNode } from "./ast.js"
 
-import type { ArrayNode } from "../ast/classes/ArrayNode.js"
-import type { Condition } from "../ast/classes/Condition.js"
-import type { ConditionNode } from "../ast/classes/ConditionNode.js"
-import type { ValidToken } from "../ast/classes/ValidToken.js"
-import type { VariableNode } from "../ast/classes/VariableNode.js"
 
 // #partially-synced
 export type FullParserOptions<T extends {} = {}> = MakeRequired<
@@ -31,14 +26,14 @@ export type ParserOptions<T extends {} = {}> = {
 	 * ```js
 	 * category.subcategory.(variable1 || variable2 && !variable3)
 	 * ```
-	 * returns an @see GroupNode whose prefix is a value token with the value `category.subcategory.`
+	 * returns an {@link GroupNode} whose prefix is a value token with the value `category.subcategory.`
 	 *
-	 * This prefix can later be applied by utility functions when evaluating the expression or extracting information from it. The default @see PrefixApplier appends the prefix name to every variable inside the group, so the above would expand into something like:
+	 * This prefix can later be applied by utility functions when evaluating the expression or extracting information from it. The default {@link PrefixApplier} appends the prefix name to every variable inside the group, so the above would expand into something like:
 	 * ```js
 	 * category.subcategory.variable1 || category.subcategory.variable2 || !category.subcategory.variable3
 	 * ```
 	 *
-	 * @see UtilityOptions["prefixApplier"] for more examples and details on how to customize the behavior.
+	 * {@link UtilityOptions}["prefixApplier"] for more examples and details on how to customize the behavior.
 	 */
 	prefixableGroups?: boolean
 	/**
@@ -61,11 +56,11 @@ export type ParserOptions<T extends {} = {}> = {
 	 * title:contains(value)
 	 * ```
 	 *
-	 * The information for these types of conditions are stored in a @see ConditionNode 's `property`, `propertyOperator`, and `sep` properties.
+	 * The information for these types of conditions are stored in a {@link ConditionNode} 's `property`, `propertyOperator`, and `sep` properties.
 	 *
 	 * The separator can only be one character long and is added to the list of characters that need to be escaped.
 	 *
-	 * The property is always a @see VariableNode and can be a quoted variable, but it can never be a prefixed string (if using `prefixableStrings`).
+	 * The property is always a {@link VariableNode} and can be a quoted variable, but it can never be a prefixed string (if using `prefixableStrings`).
 	 * ```
 	 */
 	expandedPropertySeparator?: string
@@ -96,7 +91,7 @@ export type ParserOptions<T extends {} = {}> = {
 	 * title:(prefix(a OR B)) // title:prefix.a OR title:prefix.b
 	 * ```
 	 *
-	 * Like expanded property operators, these are stored in the @see ConditionNode 's `property`, `propertyOperator` properties. `sep` is not used, not even if the the same operator as the `expandedPropertySeparator` is used. This is what is meant by these types of operators taking priority. If used in this short style, it will always be interpreted as a `propertyOperator`.
+	 * Like expanded property operators, these are stored in the {@link ConditionNode} 's `property`, `propertyOperator` properties. `sep` is not used, not even if the the same operator as the `expandedPropertySeparator` is used. This is what is meant by these types of operators taking priority. If used in this short style, it will always be interpreted as a `propertyOperator`.
 	 *
 	 */
 	customPropertyOperators?: string[]
@@ -191,9 +186,9 @@ export type ParserOptions<T extends {} = {}> = {
 	 */
 	keywords?: KeywordOptions
 	/**
-	 * If prefixableGroups is true, this allows you to control how a prefix is applied for any methods that need to apply them (e.g. @see extractVariables @see evaluate).
+	 * If prefixableGroups is true, this allows you to control how a prefix is applied for any methods that need to apply them (e.g. {@link extractVariables} {@link evaluate}).
 	 *
-	 * The default @see PrefixApplier function just appends the prefix.
+	 * The default {@link PrefixApplier} function just appends the prefix.
 	 *
 	 * So for example:
 	 *
@@ -268,7 +263,7 @@ export type ParserOptions<T extends {} = {}> = {
 	/**
 	 * When evaluating an ast against a context, this function determines whether a context value satisfies a condition.
 	 *
-	 * Given a partial {@link Condition} instance (negate property is not passed) and the contextValue (as extracted using {@link Condition.property}), it should return whether the values are equal.
+	 * Given a partial {@link NormalizedCondition} instance (negate property is not passed) and the contextValue (as extracted using {@link NormalizedCondition.property}), it should return whether the values are equal.
 	 *
 	 * It is also passed the context itself for cases where there is no property and you might want to check the value against all properties of the context.
 	 *
@@ -293,7 +288,7 @@ export type ParserOptions<T extends {} = {}> = {
 	/**
 	 * When {@link Parser.normalize normalizing} an ast, this function is needed to determine what exactly the value and operator of the condition is and whether it should be negated when evaluating.
 	 *
-	 * Given a query object it should return the values of the `value`, `operator`, and `negate` properties that will be assigned to {@link Condition}.
+	 * Given a query object it should return the values of the `value`, `operator`, and `negate` properties that will be assigned to {@link NormalizedCondition}.
 	 *
 	 * You can think of the query object as a simplified version of the condition node. See {@link ValueQuery} for details on each property.
 	 *
@@ -348,7 +343,7 @@ export type ParserOptions<T extends {} = {}> = {
 	 */
 	conditionNormalizer?: ConditionNormalizer
 	/**
-	 * Similar to the valueComparer but for validating the ast before it's evaluated using @see Parser["validate"] (e.g. for syntax highlighting purposes). For the moment the ast must be valid (without syntax errors) to be validated.
+	 * Similar to the valueComparer but for validating the ast before it's evaluated using {@link Parser}["validate"] (e.g. for syntax highlighting purposes). For the moment the ast must be valid (without syntax errors) to be validated.
 	 *
 	 * The only difference is nothing is actually evaluated (even though the values are available to the function\*) and the query contains the actual nodes/tokens for certain properties to make extracting positions easier.
 	 *
@@ -445,23 +440,23 @@ export type ValueQuery
 		isExpanded: boolean
 	}
 
-/** @see ParserOptions["valueValidator"] */
+/** {@link ParserOptions}["valueValidator"] */
 export type ValidationQuery = Omit<ValueQuery, "value" | "operator" | "prefix" | "regexFlags" | "property"> & {
 	value?: VariableNode | ArrayNode
 	operator?: ValidToken<TOKEN_TYPE.VALUE | TOKEN_TYPE.OP_CUSTOM>
 	prefix?: ValidToken<TOKEN_TYPE.VALUE>
 	regexFlags?: ValidToken<TOKEN_TYPE.VALUE>
 	property: VariableNode[]
-	/** The property as would be passed to the @see ParserOptions["valueComparer"] function (i.e. joined as a string using the @see ParseOptions["prefixApplier"] ) */
+	/** The property as would be passed to the {@link ParserOptions}["valueComparer"] function (i.e. joined as a string using the {@link ParseOptions}["prefixApplier"] ) */
 	propertyName?: string
-	/** The property keys, as parsed by @see ParserOptions["keysParser"] */
+	/** The property keys, as parsed by {@link ParserOptions}["keysParser"] */
 	propertyKeys: string[]
 	/**
 	 * Contains a list of all the wrapping group prefix nodes.
 	 */
 	prefixes?: VariableNode[]
 }
-export type ValueComparer = (condition: Omit<Condition, "negate">, contextValue: any, context: any) => boolean
+export type ValueComparer = (condition: Omit<NormalizedCondition, "negate">, contextValue: any, context: any) => boolean
 export type ConditionNormalizer = (query: ValueQuery) => { value: any, operator: any, negate: boolean }
 export type ValueValidator<T = Record<string, any>> = (contextValue: any | undefined, query: ValidationQuery, context?: Record<string, any>) => (Position & T)[] | undefined | void
 // export type PrefixValidator<T> = (prefixes: VariableNode[], last: VariableNode) => (Position & T)[]
@@ -469,7 +464,7 @@ export type KeyParser = (key: string) => string[]
 export type PrefixApplier = (prefix: string, variable: string) => string
 
 export type KeywordEntry = {
-	/** See @see ParserOptions["KeywordOptions"] */
+	/** See {@link ParserOptions}["KeywordOptions"] */
 	isSymbol: boolean
 	value: string
 }

package/src/utils/extractTokens.ts

@@ -1,31 +1,27 @@
 import { unreachable } from "@alanscodelog/utils/unreachable.js"
 
-import { ArrayNode } from "../ast/classes/ArrayNode.js"
-import { ConditionNode } from "../ast/classes/ConditionNode.js"
-import { ErrorToken } from "../ast/classes/ErrorToken.js"
-import { ExpressionNode } from "../ast/classes/ExpressionNode.js"
-import { GroupNode } from "../ast/classes/GroupNode.js"
-import { Node } from "../ast/classes/Node.js"
-import { VariableNode } from "../ast/classes/VariableNode.js"
-import type { AnyToken, AST_TYPE } from "../types/ast.js"
+import { isNode } from "./isNode.js"
+import { isToken } from "./isToken.js"
+
+import { type AnyToken, AST_TYPE, type ErrorToken, type Nodes } from "../types/ast.js"
 
 
 /**
  * Extract a list of all the tokens (which might or might not be valid).
  */
-export function extractTokens(ast: Node<AST_TYPE> | ErrorToken): AnyToken[] {
-	if (ast instanceof ErrorToken) {
+export function extractTokens(ast: ErrorToken | Nodes): AnyToken[] {
+	if (isToken(ast) && !ast.valid) {
 		return [ast]
 	}
-	if (ast instanceof VariableNode) {
+	if (ast.type === AST_TYPE.VARIABLE) {
 		const prefix = ast.prefix ? [ast.prefix] : []
 		const quoteR = ast.quote ? [ast.quote.right] : []
 		const quoteL = ast.quote ? [ast.quote.left] : []
 		const quoteFlags = ast.quote?.flags ? [ast.quote.flags] : []
 		return [...prefix, ...quoteL, ast.value, ...quoteR, ...quoteFlags]
 	}
-	if (ast instanceof ConditionNode) {
-		const value = ast.value instanceof Node
+	if (ast.type === AST_TYPE.CONDITION) {
+		const value = isNode(ast.value)
 			? extractTokens(ast.value)
 			: [ast.value]
 		const operator = ast.operator ? [ast.operator] : []
@@ -35,30 +31,30 @@ export function extractTokens(ast: Node<AST_TYPE> | ErrorToken): AnyToken[] {
 		const sepR = ast.sep?.right ? [ast.sep.right] : []
 		return [...operator, ...property, ...sepL, ...propertyOperator, ...sepR, ...value]
 	}
-	if (ast instanceof GroupNode) {
+	if (ast.type === AST_TYPE.GROUP) {
 		const prefix = ast.prefix ?
-			ast.prefix instanceof Node
+			isNode(ast.prefix)
 				? extractTokens(ast.prefix)
 				: [ast.prefix]
 			: []
 		const parenL = ast.paren ? [ast.paren.left] : []
 		const parenR = ast.paren ? [ast.paren.right] : []
-		const expression = ast.expression instanceof Node
+		const expression = isNode(ast.expression)
 				? extractTokens(ast.expression)
 				: [ast.expression]
 		return [...prefix, ...parenL, ...expression, ...parenR]
 	}
-	if (ast instanceof ArrayNode) {
+	if (ast.type === AST_TYPE.ARRAY) {
 		const values = ast.values.map(val => extractTokens(val))
 		return [ast.bracket.left, ...values.flat(), ast.bracket.right]
 	}
 
-	if (ast instanceof ExpressionNode) {
-		const right = ast.right instanceof Node
+	if (ast.type === AST_TYPE.EXPRESSION) {
+		const right = isNode(ast.right)
 			? extractTokens(ast.right)
 			: [ast.right] as AnyToken[]
 
-		const left = ast.left instanceof Node
+		const left = isNode(ast.left)
 			? extractTokens(ast.left)
 			: [ast.left] as AnyToken[]
 		return [...left, ast.operator, ...right]

package/src/utils/generateParentsMap.ts

@@ -0,0 +1,60 @@
+import { type AddParameters } from "@alanscodelog/utils/types"
+
+import { isNode } from "./isNode.js"
+
+import { type AnyToken, AST_TYPE, type Nodes, } from "../types/ast.js"
+
+/**
+ * Creates a map like Map<Node, Parent>, for easily accessing parents of nodes.
+ *
+ * This is done like this to avoid having circular structures in the ast.
+ *
+ * To get a properly typed parent, use {@link getParent} which you will need to pass a generated map.
+ */
+export function generateParentsMap(ast: Nodes | AnyToken): Map<Nodes | AnyToken, Nodes> {
+	// eslint-disable-next-line prefer-rest-params
+	const recursiveMap = arguments[1] as Map<any, any>
+	const map = recursiveMap ?? new Map<any, any>()
+	const self: AddParameters<typeof generateParentsMap, [Map<any, any>]> = generateParentsMap
+	if (ast.type === AST_TYPE.VARIABLE) {
+		if (ast.prefix) map.set(ast.prefix, ast)
+		if (ast.quote?.left) map.set(ast.quote.left, ast)
+		if (ast.quote?.right) map.set(ast.quote.right, ast)
+		if (ast.quote?.flags) map.set(ast.quote.flags, ast)
+		map.set(ast.value, ast)
+	} else if (ast.type === AST_TYPE.CONDITION) {
+		if (ast.operator) map.set(ast.operator, ast)
+		if (ast.property) {
+			map.set(ast.property, ast)
+			if (isNode(ast.property)) self(ast.property, map)
+		}
+		if (ast.propertyOperator) map.set(ast.propertyOperator, ast)
+		if (ast.sep?.left) map.set(ast.sep.left, ast)
+		if (ast.sep?.right) map.set(ast.sep.right, ast)
+		map.set(ast.value, ast)
+		if (isNode(ast.value)) self(ast.value, map)
+	} else if (ast.type === AST_TYPE.EXPRESSION) {
+		if (ast.operator) map.set(ast.operator, ast)
+		map.set(ast.right, ast)
+		if (isNode(ast.right)) self(ast.right, map)
+		map.set(ast.left, ast)
+		if (isNode(ast.left)) self(ast.left, map)
+	} else if (ast.type === AST_TYPE.GROUP) {
+		if (ast.prefix) {
+			map.set(ast.prefix, ast)
+			if (isNode(ast.prefix)) self(ast.prefix, map)
+		}
+		if (ast.paren?.left) map.set(ast.paren.left, ast)
+		if (ast.paren?.right) map.set(ast.paren.right, ast)
+		map.set(ast.expression, ast)
+		if (isNode(ast.expression)) self(ast.expression, map)
+	} else if (ast.type === AST_TYPE.ARRAY) {
+		if (ast.bracket.left) map.set(ast.bracket.left, ast)
+		if (ast.bracket.right) map.set(ast.bracket.right, ast)
+		for (const val of ast.values) {
+			map.set(val, ast)
+			if (isNode(val)) self(val, map)
+		}
+	}
+	return map as any
+}