@witchcraft/expressit 0.0.2

package/src/ast/builders/array.ts

@@ -0,0 +1,45 @@
+import type { Mutable } from "@alanscodelog/utils"
+
+import { token } from "./token.js"
+
+import { AST_TYPE, type Position, TOKEN_TYPE } from "../../types/ast.js"
+import { ArrayNode } from "../classes/ArrayNode.js"
+import type { VariableNode } from "../classes/VariableNode.js"
+
+
+export function array(
+	values: VariableNode[],
+	bracket: { left?: boolean, right?: boolean } = { right: true, left: true },
+	parenLeftPos?: Position,
+	parenRightPos?: Position
+): ArrayNode {
+	const node: Mutable<Partial<ArrayNode>> = {
+		type: AST_TYPE.ARRAY,
+		values,
+	}
+
+	node.bracket = {} as any
+
+	const start = values[0]?.start ?? parenLeftPos?.end
+	const end = values[values.length - 1]?.end ?? parenRightPos?.start ?? parenLeftPos?.end
+
+
+	parenLeftPos ??= (start !== undefined ? { start: start - 1, end: start } : undefined)
+	parenRightPos ??= (end !== undefined ? { start: end, end: end + 1 } : undefined)
+
+	// is always valid for now
+	node.bracket!.left = token(TOKEN_TYPE.BRACKETL, "[", parenLeftPos)
+
+	if (bracket?.right) {
+		node.bracket!.right = token(TOKEN_TYPE.BRACKETR, "]", parenRightPos)
+	} else {
+		if (parenRightPos) { parenRightPos.end = parenRightPos.start }
+		node.bracket!.right = token(TOKEN_TYPE.BRACKETR, undefined, parenRightPos)
+	}
+
+	node.start = node.bracket!.left?.start ?? start ?? node.bracket?.right.start
+	node.end = node.bracket?.right?.end ?? end ?? node.bracket!.left.end
+
+	const instance = new ArrayNode(node as any)
+	return instance
+}

package/src/ast/builders/condition.ts

@@ -0,0 +1,56 @@
+import { pos } from "./pos.js"
+
+import { type AnyToken, type Position, type TOKEN_TYPE } from "../../types/ast.js"
+import type { ArrayNode } from "../classes/ArrayNode.js"
+import { ConditionNode } from "../classes/ConditionNode.js"
+import type { ErrorToken } from "../classes/ErrorToken.js"
+import type { GroupNode } from "../classes/GroupNode.js"
+import type { ValidToken } from "../classes/ValidToken.js"
+import type { VariableNode } from "../classes/VariableNode.js"
+
+/**
+ * Creates a @see ConditionNode
+ *
+ * @param variable An existing @see VariableNode
+ *
+ * @param not Defaults to plain true condition. To negate it you must pass an existing "not" operator @see ValidToken which will be set as the node's operator and set the node's value to false.
+ *
+ * @param property Set the property for a property operator. A property operator must be passed if this is passed.
+ * @param propertyOperator Set the operator for a property condition. A property must have been passed. The property operator must be a valid token. There is no case where it would not be. If using an operator that is the same as a separator, if used as an operator, should be set as an operator.
+ * @param sep Pass separator tokens for expanded property conditions.
+ */
+// todo doc property operator
+export function condition(
+	value:
+	| VariableNode
+	| GroupNode
+	| ArrayNode
+	| ErrorToken<TOKEN_TYPE.VALUE>,
+	not: true | ValidToken<TOKEN_TYPE.NOT> = true,
+	property?: VariableNode | ErrorToken<TOKEN_TYPE.VALUE>,
+	propertyOperator?: AnyToken<TOKEN_TYPE.OP_CUSTOM | TOKEN_TYPE.VALUE>,
+	{ right, left }: Partial<Record<"right" | "left", ValidToken<TOKEN_TYPE.OP_EXPANDED_SEP>>> = { }
+): ConditionNode {
+	const position = pos(value satisfies Position)
+	const notStart = not === true ? undefined : not.start
+	position.start = notStart ?? property?.start ?? propertyOperator?.start ?? position.start
+
+	const node: Partial<ConstructorParameters<typeof ConditionNode>[0]> = {
+		property,
+		value,
+		propertyOperator,
+		...position,
+	}
+
+	if (not !== true) {
+		node.operator = not
+	}
+	if (right || left) {
+		node.sep = {}
+		if (right) node.sep.right = right
+		if (left) node.sep.left = left
+	}
+	const instance = new ConditionNode(node as any)
+	return instance
+}
+

package/src/ast/builders/delim.ts

@@ -0,0 +1,39 @@
+import { type } from "./type.js"
+
+import { type ExtractTokenType, TOKEN_TYPE } from "../../types/ast.js"
+
+/**
+ * Faster way, more intuitive way to generate the options for matching delimiters (e.g. quotes and parens) for functions like @see variable and @see group .
+ */
+
+export function delim<
+	TLeft extends boolean | string,
+	TRight extends boolean | string,
+	TType extends TLeft extends string
+		? ExtractTokenType<TLeft>
+		: TRight extends string
+		? ExtractTokenType<TRight>
+		: undefined,
+>(
+	left: TLeft = false as TLeft,
+	right: TRight = false as TRight,
+):
+	{
+		left: TLeft extends string ? true : TLeft
+		right: TRight extends string ? true : TRight
+	} & TType extends undefined ? {} : { type: TType } {
+	let quoteType
+	if (typeof left === "string") quoteType = type(left)
+	else if (typeof right === "string") quoteType = type(right)
+
+	const opts: any = {
+		left: left === true || (typeof left === "string" && left !== undefined),
+		right: right === true || (typeof right === "string" && right !== undefined),
+	}
+	if (quoteType !== undefined &&
+		![TOKEN_TYPE.PARENL, TOKEN_TYPE.PARENR].includes(quoteType)
+	) {
+		opts.type = quoteType
+	}
+	return opts
+}

package/src/ast/builders/error.ts

@@ -0,0 +1,22 @@
+import { type } from "./type.js"
+
+import { TOKEN_TYPE } from "../../types/ast.js"
+import { ErrorToken } from "../classes/ErrorToken.js"
+
+
+/**
+ * Creates an error token.
+ *
+ * @param expected Can be passed an array of @see ValidToken_TYPE or strings, in which case it will use @see type internally. So instead of `[TOKEN_TYPE.VALUE]` we can do `[""]` and instead of `[TOKEN_TYPE.PARENR]` we can do `[")"]`.
+ */
+export function error<T extends TOKEN_TYPE>(pos: number, expected: T[]): ErrorToken<T>
+export function error<T extends TOKEN_TYPE>(pos: number, expected_: T[]): ErrorToken<T> {
+	const expected = expected_.map(item => {
+		if (TOKEN_TYPE[item as keyof typeof TOKEN_TYPE] === undefined) {
+			return type(item)
+		} else {
+			return item
+		}
+	}) as T []
+	return new ErrorToken({ expected, start: pos, end: pos })
+}

package/src/ast/builders/expression.ts

@@ -0,0 +1,66 @@
+import { pos } from "./pos.js"
+import { token } from "./token.js"
+
+import { type AnyToken, type Position, TOKEN_TYPE, type TokenBooleanTypes } from "../../types/ast.js"
+import type { ConditionNode } from "../classes/ConditionNode.js"
+import type { ErrorToken } from "../classes/ErrorToken.js"
+import { ExpressionNode } from "../classes/ExpressionNode.js"
+import type { GroupNode } from "../classes/GroupNode.js"
+
+
+/**
+ * Creates an @see ExpressionNode, can be passed nothing for any of the tokens to automatically create error tokens.
+ *
+ * Also automatically sets the correct start/end positions from valid tokens (e.g. for start, searching left to right for a valid token and vice versa) assuming at least one is defined.
+ */
+export function expression(
+	left:
+	ConditionNode |
+	ExpressionNode |
+	GroupNode |
+	ErrorToken<TOKEN_TYPE.VALUE> |
+	undefined,
+	operator:
+	AnyToken<TokenBooleanTypes> |
+	undefined,
+	right:
+	ConditionNode |
+	ExpressionNode |
+	GroupNode |
+	ErrorToken<TOKEN_TYPE.VALUE> |
+	undefined
+): ExpressionNode {
+	const start =
+		left?.start ??
+		operator?.start ??
+		right?.start
+	const end =
+		right?.end ??
+		operator?.end ??
+		left?.end
+
+
+	const position = pos({ start, end } as Position)
+
+	if (left === undefined) {
+		left = token(TOKEN_TYPE.VALUE, undefined, { start: position.start })
+	}
+	let op!: ExpressionNode["operator"]
+	if (operator === undefined) {
+		operator = token([TOKEN_TYPE.AND, TOKEN_TYPE.OR], undefined, { start: left.end })
+	} else op = operator
+
+	if (right === undefined) {
+		right = token(TOKEN_TYPE.VALUE, undefined, { start: op.end })
+	}
+
+	const node: ConstructorParameters<typeof ExpressionNode>[0] = {
+		left,
+		operator: op,
+		right,
+		...position,
+	}
+
+	const instance = new ExpressionNode(node)
+	return instance
+}

package/src/ast/builders/group.ts

@@ -0,0 +1,79 @@
+import { token } from "./token.js"
+
+import { type Position, TOKEN_TYPE } from "../../types/ast.js"
+import type { ConditionNode } from "../classes/ConditionNode.js"
+import type { ErrorToken } from "../classes/ErrorToken.js"
+import type { ExpressionNode } from "../classes/ExpressionNode.js"
+import { GroupNode } from "../classes/GroupNode.js"
+import type { ValidToken } from "../classes/ValidToken.js"
+
+/**
+ * Creates a group.
+ *
+ * Automatically creates error tokens if missing condition or parens (not prefix because it is optional). Will look at the position of prefix if available.
+ *
+ * @param paren Use to add parens to group, usually by using @see delim . If either `right` or `left` are false or undefined, error tokens will be created. Unlike @see variable, if undefined is passed for parens, parens are created by default.
+ *
+ * The positions of the parens can be adjusted with the last two parameters by passing positions.
+ */
+
+export function group(
+	prefix:
+	| ConditionNode
+	| ValidToken<TOKEN_TYPE.NOT>
+	| undefined,
+
+	expression:
+	| ConditionNode
+	| ExpressionNode
+	| GroupNode
+	| ErrorToken<TOKEN_TYPE.VALUE>
+	| undefined,
+
+	paren: { left?: boolean, right?: boolean } = { right: true, left: true },
+	parenLeftPos?: Position,
+	parenRightPos?: Position
+): GroupNode {
+	if (expression === undefined) {
+		expression = token(TOKEN_TYPE.VALUE, undefined, prefix?.end !== undefined ? { start: prefix.end } : undefined)
+	}
+
+	const node: Partial<ConstructorParameters<typeof GroupNode>[0]> = {
+		expression,
+	}
+	if (prefix) {
+		node.prefix = prefix
+		const locToRight = node.paren?.left?.start ?? node.expression?.start ?? node.paren?.right.start
+		if (prefix.start === undefined && locToRight !== undefined) {
+			throw new Error("group builder: missing prefix location when passed expression with location")
+		}
+	}
+
+	node.paren = {} as any
+
+	const start = expression.start
+	const end = expression.end
+
+	parenLeftPos ??= (start !== undefined ? { start: start - 1, end: start } : undefined)
+	parenRightPos ??= (end !== undefined ? { start: end, end: end + 1 } : undefined)
+
+	if (paren?.left) {
+		node.paren!.left = token(TOKEN_TYPE.PARENL, "(", parenLeftPos)
+	} else {
+		if (parenLeftPos) {parenLeftPos.start = parenLeftPos.end}
+		node.paren!.left = token(TOKEN_TYPE.PARENL, undefined, parenLeftPos)
+	}
+
+	if (paren?.right) {
+		node.paren!.right = token(TOKEN_TYPE.PARENR, ")", parenRightPos)
+	} else {
+		if (parenRightPos) {parenRightPos.end = parenRightPos.start}
+		node.paren!.right = token(TOKEN_TYPE.PARENR, undefined, parenRightPos)
+	}
+
+	node.start = node.prefix?.start ?? node.paren?.left?.start ?? node.expression?.start ?? node.paren?.right.start
+	node.end = node.paren?.right?.end ?? node.expression?.end ?? node.paren?.left.end ?? node.prefix?.end
+
+	const instance = new GroupNode(node as any)
+	return instance
+}

package/src/ast/builders/index.ts

@@ -0,0 +1,13 @@
+/* Autogenerated Index */
+
+export { array } from "./array.js"
+export { condition } from "./condition.js"
+export { delim } from "./delim.js"
+export { error } from "./error.js"
+export { expression } from "./expression.js"
+export { group } from "./group.js"
+export { isFullPos } from "./isFullPos.js"
+export { pos } from "./pos.js"
+export { token } from "./token.js"
+export { type } from "./type.js"
+export { variable } from "./variable.js"

package/src/ast/builders/isFullPos.ts

@@ -0,0 +1,10 @@
+import type { Position } from "../../types/ast.js"
+
+/**
+ * @internal
+ */
+export function isFullPos(position?: Partial<Position> | any): position is Position {
+	return typeof position === "object" &&
+		position.start !== undefined &&
+		position.end !== undefined
+}

package/src/ast/builders/pos.ts

@@ -0,0 +1,57 @@
+import { isFullPos } from "./isFullPos.js"
+
+import type { AnyToken, AST_TYPE, EmptyObj, Position, TOKEN_TYPE } from "../../types/ast.js"
+import type { Node } from "../classes/Node.js"
+
+/**
+ * Can either:
+ *
+ * - Create a position from two numbers.
+ * - Extract just a position from anything with a (full) position.
+ * 	- From a partial position if `{fill:true}`.
+ */
+export function pos<TItem extends Position | Partial<Position> | EmptyObj>(
+	item: TItem,
+	opts: { fill: true }
+): TItem extends { start: number } | { end: number }
+	? Position
+	: EmptyObj
+export function pos<TItem extends Position | Partial<Position> | EmptyObj>(
+	item: TItem,
+	opts?: undefined | { fill: false }
+):
+	// not sure why this needs the AnyToken check, prob something to do with using classes
+	TItem extends Position
+	? Position
+	: TItem extends AnyToken<TOKEN_TYPE> | Position | EmptyObj
+	? Position | EmptyObj
+	: TItem extends Node<AST_TYPE> | Position | EmptyObj
+	? Position | EmptyObj
+	: EmptyObj
+export function pos(start: number, end: number): Position
+export function pos(
+	start: number | Position | Partial<Position> | EmptyObj | undefined,
+	end?: number | { fill: boolean }
+): Position | EmptyObj {
+	if (typeof start === "number") {
+		return { start, end: end as number }
+	} else {
+		const item = start
+		if (item === undefined) return {} as any
+		const fill = typeof end === "object" ? end.fill : false
+
+		if (isFullPos(item)) {
+			return { start: item.start, end: item.end }
+		} else {
+			if (fill) {
+				/* eslint-disable @typescript-eslint/no-shadow */
+				let start = item.start
+				let end = item.end
+				if (start !== undefined && end === undefined) end = start
+				if (end !== undefined && start === undefined) start = end
+				return { start: start!, end: end! }
+			}
+			return {} as any
+		}
+	}
+}

package/src/ast/builders/token.ts

@@ -0,0 +1,46 @@
+import { isArray } from "@alanscodelog/utils"
+
+import { pos } from "./pos.js"
+
+import type { AnyToken, EmptyObj, Position, TOKEN_TYPE } from "../../types/ast.js"
+import { ErrorToken } from "../classes/ErrorToken.js"
+import { ValidToken } from "../classes/ValidToken.js"
+
+
+/**
+ * Creates a @see ValidToken or of the given type with the given value. If no value is given, creates an @see ErrorToken instead.
+ *
+ * Can be passed multiple types when creating an error token to set the expected field.
+ *
+ * If the token is an error token, just `start` or `end` can be passed, and the other position will be filled to the same value.
+ */
+
+export function token<
+	TValue extends string | undefined,
+	TType extends TOKEN_TYPE = TOKEN_TYPE,
+>(
+	type: TValue extends undefined ? TType | TType[] : TType,
+	value: TValue,
+	position: Position | Partial<Position> | EmptyObj = {}
+): TValue extends undefined
+	? ErrorToken<TType>
+	: ValidToken<TType> {
+	position = pos(position, { fill: true })
+	// eslint-disable-next-line @typescript-eslint/no-shadow
+	let token: AnyToken<TType>
+	if (value !== undefined) {
+		token = new ValidToken<TType>({
+			type: type as TType,
+			value,
+			start: position.start!,
+			end: position.end!,
+		})
+	} else {
+		token = new ErrorToken<TType>({
+			expected: (isArray(type) ? type : [type]) as TType[],
+			start: position.start!,
+			end: position.end!,
+		})
+	}
+	return token as any
+}

package/src/ast/builders/type.ts

@@ -0,0 +1,32 @@
+import { type ExtractTokenType, TOKEN_TYPE } from "../../types/ast.js"
+/**
+ * Given a the string value of an operator or single delimiter token, returns the corresponding @see ValidToken_TYPE .
+ */
+export function type<T extends string>(
+	operatorSymbol: T
+): ExtractTokenType<T> {
+	switch (operatorSymbol) {
+		case "`": return TOKEN_TYPE.BACKTICK as any
+		case `'`: return TOKEN_TYPE.SINGLEQUOTE as any
+		case `"`: return TOKEN_TYPE.DOUBLEQUOTE as any
+		case `(`: return TOKEN_TYPE.PARENL as any
+		case `)`: return TOKEN_TYPE.PARENR as any
+		case `[`: return TOKEN_TYPE.BRACKETL as any
+		case `]`: return TOKEN_TYPE.BRACKETR as any
+		case `/`: return TOKEN_TYPE.REGEX as any
+		case `and`:
+		case `&&`:
+		case `&`:
+			return TOKEN_TYPE.AND as any
+		case `or`:
+		case `||`:
+		case `|`:
+			return TOKEN_TYPE.OR as any
+		case `not`:
+		case `!`:
+			return TOKEN_TYPE.NOT as any
+		default:
+			return TOKEN_TYPE.VALUE as any
+	}
+}
+

package/src/ast/builders/variable.ts

@@ -0,0 +1,89 @@
+import { pos } from "./pos.js"
+import { token } from "./token.js"
+
+import { type AnyToken, type EmptyObj, type Position, TOKEN_TYPE, type TokenQuoteTypes } from "../../types/ast.js"
+import type { ValidToken } from "../classes/ValidToken.js"
+import { VariableNode } from "../classes/VariableNode.js"
+
+
+/**
+ * Creates an @see VariableNode .
+ *
+ * @param quote Use to add quotes to the variable, usually by using @see delim . If false or undefined, no quotes are added. Otherwise at least `type` must be passed.  If one side is defined but not the other, error tokens will be created with the given type.
+ *
+ * @param position Refers to position of the value (in case it needs to be created) not the node. Quote positions are automatically calculated from this if used. If value is already a token, there's no need to pass a position, it can be extracted from the token.
+ */
+
+export function variable(
+	prefix: ValidToken<TOKEN_TYPE.VALUE> | undefined,
+	value: string | AnyToken<TOKEN_TYPE.VALUE>,
+	quote?: { type: TokenQuoteTypes, left?: boolean, right?: boolean, flags?: string },
+	position?: Position | EmptyObj
+): VariableNode {
+	if (typeof value === "string") {
+		value = token(TOKEN_TYPE.VALUE, value, position)
+	}
+
+	position = pos(value)
+
+	const node: Partial<ConstructorParameters<typeof VariableNode>[0]> = {
+		value,
+		prefix,
+	}
+
+	if (quote) {
+		node.quote = {} as any
+
+		const quoteLeftPos = position?.start !== undefined
+			? pos({ start: position.start }, { fill: true })
+			: undefined
+
+		if (quote.left) {
+			if (quoteLeftPos) quoteLeftPos.start -= 1
+			node.quote!.left = token(quote.type, quoteFromType(quote.type), quoteLeftPos)
+		} else {
+			node.quote!.left = token(quote.type, undefined, quoteLeftPos)
+		}
+
+		const quoteRightPos = position?.end !== undefined
+			? pos({ end: position.end }, { fill: true })
+			: undefined
+
+		if (quote.right) {
+			if (quoteRightPos) quoteRightPos.end += 1
+			node.quote!.right = token(quote.type, quoteFromType(quote.type), quoteRightPos)
+		} else {
+			node.quote!.right = token(quote.type, undefined, quoteRightPos)
+		}
+		if (quote.flags) {
+			const start = node.quote!.right.end // is always defined if there are flags
+			node.quote!.flags = token(TOKEN_TYPE.VALUE, quote.flags, {
+				start, end: start + quote.flags?.length,
+			})
+		}
+	}
+
+	node.start =
+		node.prefix?.start ??
+		node.quote?.left.start ??
+		node.value?.start ??
+		node.quote?.right.start
+	node.end =
+		node.quote?.flags?.end ??
+		node.quote?.right.end ??
+		node.value?.end ??
+		node.quote?.left.end
+
+	const instance = new VariableNode(node as any)
+	return instance
+}
+
+function quoteFromType(type: TokenQuoteTypes | undefined): string {
+	switch (type) {
+		case TOKEN_TYPE.BACKTICK: return "`"
+		case TOKEN_TYPE.DOUBLEQUOTE: return "\""
+		case TOKEN_TYPE.SINGLEQUOTE: return "'"
+		case TOKEN_TYPE.REGEX: return "/"
+		case undefined: return ""
+	}
+}

package/src/ast/classes/ArrayNode.ts

@@ -0,0 +1,46 @@
+import type { ConditionNode } from "./ConditionNode.js"
+import { Node } from "./Node.js"
+import { ValidToken } from "./ValidToken.js"
+import type { VariableNode } from "./VariableNode.js"
+
+import { AST_TYPE, type NodeDelimiters, type TOKEN_TYPE } from "../../types/ast.js"
+
+
+export class ArrayNode<
+	TValid extends boolean = boolean,
+> extends Node<AST_TYPE.ARRAY> {
+	readonly values: VariableNode[]
+
+	readonly bracket: NodeDelimiters<TOKEN_TYPE.BRACKETL, TOKEN_TYPE.BRACKETR>
+
+	#parent: any
+
+	#setParent: boolean = false
+
+	get parent(): ConditionNode | undefined {
+		return this.#parent
+	}
+
+	set parent(value: ConditionNode | undefined) {
+		if (this.#setParent) { throw new Error("parent property is readonly") }
+		this.#parent = value
+		this.#setParent = true
+	}
+
+	constructor({ values, bracket, start, end }: {
+		values: ArrayNode<TValid>["values"]
+		bracket: ArrayNode<TValid>["bracket"]
+		start: number
+		end: number
+	}) {
+		super(AST_TYPE.ARRAY, start, end)
+		this.values = values
+		this.bracket = bracket
+		// @ts-expect-error ignore readonly
+		this.valid = (
+			this.values.every(val => val.valid) &&
+			this.bracket.left instanceof ValidToken &&
+			this.bracket.right instanceof ValidToken
+		) as TValid
+	}
+}

package/src/ast/classes/Condition.ts

@@ -0,0 +1,22 @@
+export class Condition<TOp extends string = string, TValue = any> {
+	readonly value: TValue
+
+	readonly operator?: TOp
+
+	readonly property: string[]
+
+	readonly negate: boolean
+
+	constructor({ property, operator, value, negate }: {
+		property: Condition<TOp, TValue>["property"]
+		operator: Condition<TOp, TValue>["operator"]
+		value: Condition<TOp, TValue>["value"]
+		negate: Condition<TOp, TValue>["negate"]
+	}) {
+		this.value = value
+		this.operator = operator
+		this.property = property
+		this.negate = negate
+	}
+}
+