@witchcraft/expressit 0.0.2

package/src/ast/classes/ConditionNode.ts

@@ -0,0 +1,141 @@
+import type { ArrayNode } from "./ArrayNode.js"
+import type { ErrorToken } from "./ErrorToken.js"
+import type { ExpressionNode } from "./ExpressionNode.js"
+import type { GroupNode } from "./GroupNode.js"
+import { Node } from "./Node.js"
+import { ValidToken } from "./ValidToken.js"
+import { VariableNode } from "./VariableNode.js"
+
+import { type AnyToken, AST_TYPE, type TOKEN_TYPE } from "../../types/ast.js"
+
+
+/**
+ * A condition is composed of a `variable`, @see Variable , and, if it's negated, a "not" `operator` token, @see 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 class ConditionNode<
+	TValid extends boolean = boolean,
+	TOperator extends
+		ValidToken<TOKEN_TYPE.NOT> | undefined =
+		ValidToken<TOKEN_TYPE.NOT> | undefined,
+> 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.
+	 */
+	readonly value:
+	| VariableNode<TValid>
+	| ArrayNode<TValid>
+	| GroupNode<TValid>
+	| (TValid extends false ? ErrorToken<TOKEN_TYPE.VALUE> : never)
+
+	/**
+	 * If the condition was negated, contains the "not" token, @see ValidToken , the condition was negated with.
+	 */
+	readonly 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 @see ParserOptions for more details.
+	 */
+	readonly property?: VariableNode | (TValid extends false ? ErrorToken<TOKEN_TYPE.VALUE> : 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 @see ParserOptions for more details.
+	 */
+	readonly 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 @see ParserOptions for more details.
+	 */
+	readonly sep?: {
+		left?: AnyToken<TOKEN_TYPE.OP_EXPANDED_SEP>
+		right?: AnyToken<TOKEN_TYPE.OP_EXPANDED_SEP>
+	}
+
+	#parent: any
+
+	#setParent: boolean = false
+
+	get parent(): GroupNode |
+	ExpressionNode |
+	undefined {
+		return this.#parent
+	}
+
+	set parent(value: GroupNode |
+	ExpressionNode |
+	undefined
+	) {
+		if (this.#setParent) {throw new Error("parent property is readonly")}
+		this.#parent = value
+		this.#setParent = true
+	}
+
+	constructor({ property, propertyOperator, sep, value, start, end, operator }: {
+		operator?: TOperator
+		property?: ConditionNode<TValid>["property"]
+		propertyOperator?: ConditionNode<TValid>["propertyOperator"]
+		sep?: ConditionNode<TValid>["sep"]
+		value: ConditionNode<TValid>["value"]
+		start: number
+		end: number
+	}) {
+		super(AST_TYPE.CONDITION, start, end)
+		this.value = value
+		this.operator = operator
+		this.property = property
+		this.propertyOperator = propertyOperator
+		this.sep = sep
+		this.operator = operator
+		// @ts-expect-error ignore readonly
+		this.valid = ((
+			this.operator === undefined ||
+			this.operator instanceof ValidToken
+		) &&
+			this.value instanceof Node &&
+			this.value.valid
+		) && (
+			(
+				this.property === undefined &&
+				this.propertyOperator === undefined &&
+				this.sep === undefined
+			) || (
+				this.property instanceof VariableNode &&
+				(
+					this.propertyOperator instanceof ValidToken ||
+					(
+						this.sep?.left instanceof ValidToken &&
+						(
+							this.sep.right === undefined ||
+							this.sep?.right instanceof ValidToken
+						)
+					)
+				)
+			)
+
+		) as TValid
+	}
+}
+

package/src/ast/classes/ErrorToken.ts

@@ -0,0 +1,49 @@
+import type { ConditionNode } from "./ConditionNode.js"
+import type { ExpressionNode } from "./ExpressionNode.js"
+import type { GroupNode } from "./GroupNode.js"
+import { Token } from "./Token.js"
+import type { VariableNode } from "./VariableNode.js"
+
+import type { TOKEN_TYPE } from "../../types/ast.js"
+
+/**
+ * The class 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 class ErrorToken<
+	TExpected extends TOKEN_TYPE = TOKEN_TYPE,
+> extends Token<false, never, never, TExpected[]> {
+	readonly expected: TExpected[]
+
+	#parent: any
+
+	get parent(): VariableNode |
+	GroupNode |
+	ExpressionNode |
+	ConditionNode {
+		return this.#parent
+	}
+
+	set parent(value: VariableNode |
+	GroupNode |
+	ExpressionNode |
+	ConditionNode
+	) {
+		if (this.#parent) {throw new Error("parent property is readonly")}
+		this.#parent = value
+	}
+
+	constructor({ expected, start, end }: {
+		expected: TExpected[]
+		start: number
+		end: number
+	}) {
+		super(start, end)
+		this.expected = expected
+	}
+}

package/src/ast/classes/Expression.ts

@@ -0,0 +1,26 @@
+import type { Condition } from "./Condition.js"
+
+import type { TokenBooleanTypes } from "../../types/ast.js"
+
+
+export class Expression<TType extends string = string, TValue = any> {
+	readonly left:
+	| Expression<TType, TValue>
+	| Condition<TType, TValue>
+
+	readonly right:
+	| Expression<TType, TValue>
+	| Condition<TType, TValue>
+
+	readonly operator: TokenBooleanTypes
+
+	constructor({ operator, left, right }: {
+		operator: Expression<TType, TValue>["operator"]
+		right: Expression<TType, TValue>["right"]
+		left: Expression<TType, TValue>["left"]
+	}) {
+		this.operator = operator
+		this.right = right
+		this.left = left
+	}
+}

package/src/ast/classes/ExpressionNode.ts

@@ -0,0 +1,62 @@
+import type { ConditionNode } from "./ConditionNode.js"
+import type { ErrorToken } from "./ErrorToken.js"
+import type { GroupNode } from "./GroupNode.js"
+import { Node } from "./Node.js"
+import { ValidToken } from "./ValidToken.js"
+
+import { type AnyToken, AST_TYPE, type TOKEN_TYPE, type TokenBooleanTypes } from "../../types/ast.js"
+
+
+export class ExpressionNode<
+	TValid extends boolean = boolean,
+>
+	extends Node<AST_TYPE.EXPRESSION> {
+	readonly operator: AnyToken<TokenBooleanTypes>
+
+	readonly left:
+	| ExpressionNode<TValid>
+	| ConditionNode<TValid>
+	| GroupNode<TValid>
+	| (TValid extends false ? ErrorToken<TOKEN_TYPE.VALUE> : never)
+
+	readonly right:
+	| ExpressionNode<TValid>
+	| ConditionNode<TValid>
+	| GroupNode<TValid>
+	| (TValid extends false ? ErrorToken<TOKEN_TYPE.VALUE> : never)
+
+	#parent: any
+
+	#setParent: boolean = false
+
+	get parent(): GroupNode | undefined {
+		return this.#parent
+	}
+
+	set parent(value: GroupNode | undefined) {
+		if (this.#setParent) {throw new Error("parent property is readonly")}
+		this.#parent = value
+		this.#setParent = true
+	}
+
+	constructor({ operator, left, right, start, end }: {
+		operator: ExpressionNode<TValid>["operator"]
+		right: ExpressionNode<TValid>["right"]
+		left: ExpressionNode<TValid>["left"]
+		start: number
+		end: number
+	}) {
+		super(AST_TYPE.EXPRESSION, start, end)
+		this.operator = operator
+		this.right = right
+		this.left = left
+		// @ts-expect-error ignore readonly
+		this.valid = (
+			this.operator instanceof ValidToken &&
+			this.left instanceof Node &&
+			this.left.valid &&
+			this.right instanceof Node &&
+			this.right.valid
+		) as TValid
+	}
+}

package/src/ast/classes/GroupNode.ts

@@ -0,0 +1,127 @@
+import type { ConditionNode } from "./ConditionNode.js"
+import type { ErrorToken } from "./ErrorToken.js"
+import type { ExpressionNode } from "./ExpressionNode.js"
+import { Node } from "./Node.js"
+import { ValidToken } from "./ValidToken.js"
+
+import { AST_TYPE, type NodeDelimiters, type TOKEN_TYPE } from "../../types/ast.js"
+
+
+/**
+ * A node that symbolizes a parenthesized expression (might be negated), and if `prefixableGroups` is enabled, a prefixed expression @see 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 class 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**, @see ValidToken .
+	 *
+	 * If `prefixableGroups` is enabled and the group is prefixed by a **condition**, this will be an @see ConditionNode.
+	 *
+	 * **Careful:** `!(a)` here this would not be a **condition** since it's just a regular negation.
+	 *
+	 * See examples at @see GroupNode .
+	 */
+	readonly prefix: TPrefix
+
+	expression:
+	| ConditionNode<TValid>
+	| GroupNode<TValid>
+	| ExpressionNode<TValid>
+	| (TValid extends false ? ErrorToken<TOKEN_TYPE.VALUE> : never)
+
+	/**
+	 * The parenthesis tokens, @see ValidToken . These will always be defined (although not necessarily with valid tokens).
+	 */
+	readonly paren: NodeDelimiters<TOKEN_TYPE.PARENL, TOKEN_TYPE.PARENR>
+
+	#parent: any
+
+	#setParent: boolean = false
+
+	get parent(): ExpressionNode | undefined {
+		return this.#parent
+	}
+
+	set parent(value: ExpressionNode | undefined) {
+		if (this.#setParent) {throw new Error("parent property is readonly")}
+		this.#parent = value
+		this.#setParent = true
+	}
+
+	constructor({ prefix, expression, paren, start, end }: {
+		prefix: TPrefix
+		expression: GroupNode<TValid>["expression"]
+		paren: GroupNode<TValid>["paren"]
+		start: number
+		end: number
+	}) {
+		super(AST_TYPE.GROUP, start, end)
+		this.prefix = prefix
+		this.expression = expression
+		this.paren = paren
+		// @ts-expect-error ignore readonly
+		this.valid = (
+			(
+				this.prefix === undefined ||
+				this.prefix instanceof ValidToken ||
+				(
+					this.prefix instanceof Node &&
+					this.prefix.valid
+				)
+			) &&
+			this.expression instanceof Node &&
+			this.expression.valid &&
+			(
+				this.paren === undefined ||
+				(
+					this.paren.left instanceof ValidToken &&
+					this.paren.right instanceof ValidToken
+				)
+			)
+		) as TValid
+	}
+}
+

package/src/ast/classes/Node.ts

@@ -0,0 +1,47 @@
+import type { ArrayNode } from "./ArrayNode.js"
+import type { ConditionNode } from "./ConditionNode.js"
+import type { ExpressionNode } from "./ExpressionNode.js"
+import type { GroupNode } from "./GroupNode.js"
+
+import { BooleanParserLibraryError } from "../../helpers/errors.js"
+import type { AST_TYPE } from "../../types/ast.js"
+import { ERROR_CODES } from "../../types/errors.js"
+
+/**
+ * The base AST node class all node types extend from. Can be used to check if an object is an ast node.
+ * ```ts
+ * if (group.prefix instanceof Node) {
+ * 	//...
+ * }
+ * ```
+ */
+export class Node<
+	TType extends AST_TYPE = AST_TYPE,
+	TValid extends boolean = boolean,
+> {
+	readonly type: TType
+
+	readonly start: number
+
+	readonly end: number
+
+	readonly valid!: TValid
+
+	get parent():
+	ConditionNode |
+	GroupNode |
+	ExpressionNode |
+	ArrayNode |
+	undefined {
+		return undefined as any
+	}
+
+	constructor(type: TType, start: number, end: number) {
+		this.type = type
+		if (start === undefined || end === undefined) {
+			throw new BooleanParserLibraryError(ERROR_CODES.PARSER_POSITION_ERROR, { start, end })
+		}
+		this.start = start
+		this.end = end
+	}
+}

package/src/ast/classes/Token.ts

@@ -0,0 +1,59 @@
+import type { ArrayNode } from "./ArrayNode.js"
+import type { ConditionNode } from "./ConditionNode.js"
+import type { ExpressionNode } from "./ExpressionNode.js"
+import type { GroupNode } from "./GroupNode.js"
+import type { VariableNode } from "./VariableNode.js"
+
+import { BooleanParserLibraryError } from "../../helpers/errors.js"
+import type { TOKEN_TYPE } from "../../types/ast.js"
+import { ERROR_CODES } from "../../types/errors.js"
+
+/**
+ * The base class from which @see ValidToken and @see ErrorToken extend.
+ *
+ * Mostly for internal use, and I would suggest using @see AnyToken instead of this for typing things, but can be used to check whether an object is a token:
+ * ```ts
+ * if (group.prefix instanceof Token) {
+ * 	//...
+ * }
+ * ```
+ * Only really takes care of setting the start/end position.
+ */
+export class Token<
+	TValid extends boolean = boolean,
+	TType extends
+		TValid extends true ? TOKEN_TYPE : never =
+		TValid extends true ? TOKEN_TYPE : never,
+	TValue extends
+		TValid extends true ? string : never =
+		TValid extends true ? string : never,
+	TExpected extends
+		TValid extends false ? TOKEN_TYPE[] : never =
+		TValid extends false ? TOKEN_TYPE[] : never,
+> {
+	readonly type!: TType
+
+	readonly value!: TValue
+
+	readonly expected!: TExpected
+
+	readonly start!: number
+
+	readonly end!: number
+
+	get parent(): VariableNode |
+	GroupNode |
+	ExpressionNode |
+	ArrayNode |
+	ConditionNode {
+		return undefined as any
+	}
+
+	constructor(start: number, end: number) {
+		if (start === undefined || end === undefined) {
+			throw new BooleanParserLibraryError(ERROR_CODES.PARSER_POSITION_ERROR, { start, end })
+		}
+		this.start = start
+		this.end = end
+	}
+}

package/src/ast/classes/ValidToken.ts

@@ -0,0 +1,56 @@
+import type { ArrayNode } from "./ArrayNode.js"
+import type { ConditionNode } from "./ConditionNode.js"
+import type { ExpressionNode } from "./ExpressionNode.js"
+import type { GroupNode } from "./GroupNode.js"
+import { Token } from "./Token.js"
+import type { VariableNode } from "./VariableNode.js"
+
+import type { TOKEN_TYPE } from "../../types/ast.js"
+
+
+/**
+ * The class for all *valid* tokens.
+ *
+ * Valid tokens always have a value, even if it might be an empty string.
+ */
+export class ValidToken<
+	TType extends TOKEN_TYPE = TOKEN_TYPE,
+> extends Token<true, TType, string, never> {
+	readonly type: TType
+
+	readonly value: string
+
+	#parent: any
+
+	get parent():
+	| VariableNode
+	| GroupNode
+	| ExpressionNode
+	| ConditionNode
+	| ArrayNode {
+		return this.#parent
+	}
+
+	set parent(value:
+	| VariableNode
+	| GroupNode
+	| ExpressionNode
+	| ConditionNode
+	| ArrayNode
+	) {
+		if (this.#parent) {throw new Error("parent property is readonly")}
+		this.#parent = value
+	}
+
+	constructor({ type, value, start, end }: {
+		type: TType
+		value: string
+		start: number
+		end: number
+	}
+	) {
+		super(start, end)
+		this.type = type
+		this.value = value
+	}
+}

package/src/ast/classes/VariableNode.ts

@@ -0,0 +1,67 @@
+import type { ArrayNode } from "./ArrayNode.js"
+import type { ConditionNode } from "./ConditionNode.js"
+import type { ErrorToken } from "./ErrorToken.js"
+import { Node } from "./Node.js"
+import { ValidToken } from "./ValidToken.js"
+
+import { type AnyToken, AST_TYPE, type NodeDelimiters, type TOKEN_TYPE, type TokenQuoteTypes } from "../../types/ast.js"
+
+/**
+ * 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 @see 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 ValidToken . While they will always be of the same quote type, one might be valid while the other might not (@see 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. @see evaluate will take care of unescaping when needed.
+ *
+ * If `prefixableStrings` is true, the `prefix` property might contain a value token.
+ */
+export class VariableNode<
+	TValid extends boolean = boolean,
+> extends Node<AST_TYPE.VARIABLE, TValid> {
+	readonly value: TValid extends boolean
+		? AnyToken<TOKEN_TYPE.VALUE>
+		: TValid extends true
+		? ValidToken<TOKEN_TYPE.VALUE>
+	: ErrorToken<TOKEN_TYPE.VALUE>
+
+	readonly prefix?: ValidToken<TOKEN_TYPE.VALUE> // todo
+
+	readonly quote?: NodeDelimiters<TokenQuoteTypes, TokenQuoteTypes>
+
+	#parent: any
+
+	#setParent: boolean = false
+
+	get parent(): ConditionNode | ArrayNode | undefined {
+		return this.#parent
+	}
+
+	set parent(value: ConditionNode | ArrayNode | undefined) {
+		if (this.#setParent) {throw new Error("parent property is readonly")}
+		this.#parent = value
+		this.#setParent = true
+	}
+
+	constructor({ prefix, value, quote, start, end }: {
+		prefix?: VariableNode<TValid>["prefix"]
+		value: VariableNode<TValid>["value"]
+		quote?: VariableNode<TValid>["quote"]
+		start: number
+		end: number
+	}) {
+		super(AST_TYPE.VARIABLE, start, end)
+		this.prefix = prefix
+		this.value = value
+		this.quote = quote
+		// @ts-expect-error ignore readonly
+		this.valid = (this.value instanceof ValidToken && (
+			this.quote === undefined ||
+			(
+				this.quote.left instanceof ValidToken &&
+				this.quote.right instanceof ValidToken
+			)
+		)) as TValid
+	}
+}

package/src/ast/classes/index.ts

@@ -0,0 +1,13 @@
+/* Autogenerated Index */
+
+export { ArrayNode } from "./ArrayNode.js"
+export { Condition } from "./Condition.js"
+export { ConditionNode } from "./ConditionNode.js"
+export { ErrorToken } from "./ErrorToken.js"
+export { Expression } from "./Expression.js"
+export { ExpressionNode } from "./ExpressionNode.js"
+export { GroupNode } from "./GroupNode.js"
+export { Node } from "./Node.js"
+export { Token } from "./Token.js"
+export { ValidToken } from "./ValidToken.js"
+export { VariableNode } from "./VariableNode.js"