littlewing 2.1.1 → 2.3.1

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 declare namespace exports_ast {
-	export { unaryOp, subtract, string, rangeExpr, program, placeholder, pipeExpr, number, notEquals, negate, multiply, modulo, logicalOr, logicalNot, logicalAnd, lessThan, lessEqual, isUnaryOp, isStringLiteral, isRangeExpression, isProgram, isPlaceholder, isPipeExpression, isNumberLiteral, isIndexAccess, isIfExpression, isIdentifier, isFunctionCall, isForExpression, isBooleanLiteral, isBinaryOp, isAssignment, isArrayLiteral, indexAccess, ifExpr, identifier, greaterThan, greaterEqual, getNodeName, functionCall, forExpr, exponentiate, equals, divide, boolean, binaryOp, assign, array, add, UnaryOp, StringLiteral, RangeExpression, Program, Placeholder, PipeExpression, Operator, NumberLiteral, NodeKind, IndexAccess, IfExpression, Identifier2 as Identifier, FunctionCall, ForExpression, BooleanLiteral, BinaryOp, Assignment, ArrayLiteral, ASTNodeBase, ASTNode };
+	export { visit, unaryOp, subtract, string, rangeExpr, program, placeholder, pipeExpr, number, notEquals, negate, multiply, modulo, logicalOr, logicalNot, logicalAnd, lessThan, lessEqual, isUnaryOp, isStringLiteral, isRangeExpression, isProgram, isPlaceholder, isPipeExpression, isNumberLiteral, isIndexAccess, isIfExpression, isIdentifier, isFunctionCall, isForExpression, isBooleanLiteral, isBinaryOp, isAssignment, isArrayLiteral, indexAccess, ifExpr, identifier, greaterThan, greaterEqual, getNodeName, functionCall, forExpr, exponentiate, equals, divide, boolean, binaryOp, assign, array, add, Visitor, UnaryOp, StringLiteral, RangeExpression, Program, Placeholder, PipeExpression, Operator, NumberLiteral, NodeKind, IndexAccess, IfExpression, Identifier2 as Identifier, FunctionCall, ForExpression, BooleanLiteral, BinaryOp, Assignment, ArrayLiteral, ASTNodeBase, ASTNode };
 }
 /**
 * Binary operator types
@@ -172,6 +172,25 @@ interface Placeholder extends ASTNodeBase {
 * AST Node - discriminated union of all node types
 */
 type ASTNode = Program | NumberLiteral | StringLiteral | BooleanLiteral | ArrayLiteral | Identifier2 | BinaryOp | UnaryOp | FunctionCall | Assignment | IfExpression | ForExpression | IndexAccess | RangeExpression | PipeExpression | Placeholder;
+interface Visitor<T> {
+	Program: (node: Program, recurse: (child: ASTNode) => T) => T;
+	NumberLiteral: (node: NumberLiteral, recurse: (child: ASTNode) => T) => T;
+	StringLiteral: (node: StringLiteral, recurse: (child: ASTNode) => T) => T;
+	BooleanLiteral: (node: BooleanLiteral, recurse: (child: ASTNode) => T) => T;
+	ArrayLiteral: (node: ArrayLiteral, recurse: (child: ASTNode) => T) => T;
+	Identifier2: (node: Identifier2, recurse: (child: ASTNode) => T) => T;
+	BinaryOp: (node: BinaryOp, recurse: (child: ASTNode) => T) => T;
+	UnaryOp: (node: UnaryOp, recurse: (child: ASTNode) => T) => T;
+	FunctionCall: (node: FunctionCall, recurse: (child: ASTNode) => T) => T;
+	Assignment: (node: Assignment, recurse: (child: ASTNode) => T) => T;
+	IfExpression: (node: IfExpression, recurse: (child: ASTNode) => T) => T;
+	ForExpression: (node: ForExpression, recurse: (child: ASTNode) => T) => T;
+	IndexAccess: (node: IndexAccess, recurse: (child: ASTNode) => T) => T;
+	RangeExpression: (node: RangeExpression, recurse: (child: ASTNode) => T) => T;
+	PipeExpression: (node: PipeExpression, recurse: (child: ASTNode) => T) => T;
+	Placeholder: (node: Placeholder, recurse: (child: ASTNode) => T) => T;
+}
+declare function visit<T>(node: ASTNode, visitor: Visitor<T>): T;
 /**
 * Type guard functions for discriminated union narrowing
 */
@@ -206,9 +225,6 @@ declare function number(value: number): NumberLiteral;
 * Create a string literal node
 */
 declare function string(value: string): StringLiteral;
-/**
-* Create a boolean literal node
-*/
 declare function boolean(value: boolean): BooleanLiteral;
 /**
 * Create an array literal node
@@ -257,9 +273,6 @@ declare function rangeExpr(start: ASTNode, end: ASTNode, inclusive: boolean): Ra
 * Create a pipe expression node (value |> FUN(?, arg))
 */
 declare function pipeExpr(value: ASTNode, name: string, args: readonly ASTNode[]): PipeExpression;
-/**
-* Create a placeholder node (?) for use in pipe expression arguments
-*/
 declare function placeholder(): Placeholder;
 /**
 * Convenience functions for common operations
@@ -320,6 +333,23 @@ declare function extractInputVariables(ast: ASTNode): string[];
 */
 declare function extractAssignedVariables(ast: ASTNode): string[];
 /**
+* Error thrown when parsing fails. Carries byte offsets into the source string
+* so callers can display precise error locations.
+*/
+declare class ParseError extends Error {
+	readonly start: number;
+	readonly end: number;
+	readonly name = "ParseError";
+	constructor(message: string, start: number, end: number);
+}
+/**
+* Convert a byte offset into a source string to a 1-based line and column.
+*/
+declare function toLineColumn(source: string, offset: number): {
+	line: number;
+	column: number;
+};
+/**
 * Generate source code from an AST node
 */
 declare function generate(node: ASTNode): string;
@@ -337,6 +367,13 @@ interface ExecutionContext {
 	variables?: Record<string, RuntimeValue>;
 }
 /**
+* Result of evaluating source or an AST in a single pass.
+*/
+interface ExecutionResult {
+	value: RuntimeValue;
+	scope: Record<string, RuntimeValue>;
+}
+/**
 * Evaluate source code or AST with given context
 */
 declare function evaluate(input: string | ASTNode, context?: ExecutionContext): RuntimeValue;
@@ -345,6 +382,10 @@ declare function evaluate(input: string | ASTNode, context?: ExecutionContext):
 */
 declare function evaluateScope(input: string | ASTNode, context?: ExecutionContext): Record<string, RuntimeValue>;
 /**
+* Evaluate source code or AST and return both the result value and full variable scope.
+*/
+declare function evaluateWithScope(input: string | ASTNode, context?: ExecutionContext): ExecutionResult;
+/**
 * Optimize an AST using constant folding, constant propagation, and dead code elimination.
 *
 * When `externalVariables` is provided, the optimizer can safely propagate variables
@@ -357,31 +398,9 @@ declare function optimize(node: ASTNode, externalVariables?: ReadonlySet<string>
 */
 declare function parse(source: string): ASTNode;
 declare namespace array {
-	export { ARR_UNIQUE, ARR_SUM, ARR_SORT, ARR_SLICE, ARR_REVERSE, ARR_PUSH, ARR_MIN, ARR_MAX, ARR_LEN, ARR_JOIN, ARR_FLAT, ARR_CONTAINS };
+	export { ARR_UNIQUE, ARR_SUM, ARR_SORT, ARR_MIN, ARR_MAX, ARR_JOIN, ARR_FLAT };
 }
 /**
-* Get the length of an array
-*/
-declare const ARR_LEN: (a: RuntimeValue) => RuntimeValue;
-/**
-* Append a value to an array, returning a new array
-* Validates homogeneity
-*/
-declare const ARR_PUSH: (a: RuntimeValue, value: RuntimeValue) => RuntimeValue;
-/**
-* Extract a section of an array (0-based indices)
-*/
-declare const ARR_SLICE: (a: RuntimeValue, start: RuntimeValue, end?: RuntimeValue) => RuntimeValue;
-/**
-* Check if an array contains a value (using deep equality)
-* Returns boolean
-*/
-declare const ARR_CONTAINS: (a: RuntimeValue, value: RuntimeValue) => RuntimeValue;
-/**
-* Reverse an array, returning a new array
-*/
-declare const ARR_REVERSE: (a: RuntimeValue) => RuntimeValue;
-/**
 * Sort an array in ascending order, returning a new array.
 * Numbers sort numerically, strings lexicographically,
 * dates/times/datetimes by temporal comparison.
@@ -419,7 +438,7 @@ declare const ARR_MIN: (a: RuntimeValue) => RuntimeValue;
 */
 declare const ARR_MAX: (a: RuntimeValue) => RuntimeValue;
 declare namespace core {
-	export { TYPE, STR, NUM };
+	export { TYPE, STR, SLICE, REVERSE, NUM, LEN, INDEX_OF, CONTAINS };
 }
 /**
 * Convert a value to string representation
@@ -436,8 +455,33 @@ declare const NUM: (v: RuntimeValue) => RuntimeValue;
 * Returns the type name of a value as a string
 */
 declare const TYPE: (v: RuntimeValue) => RuntimeValue;
+/**
+* Get the length of a string or array
+*/
+declare const LEN: (v: RuntimeValue) => RuntimeValue;
+/**
+* Extract a section of a string or array (0-based indices)
+*/
+declare const SLICE: (v: RuntimeValue, start: RuntimeValue, end?: RuntimeValue) => RuntimeValue;
+/**
+* Check if a string contains a substring or an array contains an element.
+* For strings: both arguments must be strings (substring search).
+* For arrays: uses deep equality to find the element.
+*/
+declare const CONTAINS: (v: RuntimeValue, search: RuntimeValue) => RuntimeValue;
+/**
+* Reverse a string or array, returning a new value
+*/
+declare const REVERSE: (v: RuntimeValue) => RuntimeValue;
+/**
+* Find the first index of a substring in a string or an element in an array.
+* Returns -1 if not found.
+* For strings: both arguments must be strings.
+* For arrays: uses deep equality.
+*/
+declare const INDEX_OF: (v: RuntimeValue, search: RuntimeValue) => RuntimeValue;
 declare namespace datetime {
-	export { TODAY, START_OF_YEAR, START_OF_WEEK, START_OF_QUARTER, START_OF_MONTH, IS_WEEKEND, IS_SAME_DAY, IS_LEAP_YEAR, GET_YEAR, GET_WEEKDAY, GET_QUARTER, GET_MONTH, GET_DAY_OF_YEAR, GET_DAY, END_OF_YEAR, END_OF_MONTH, DIFFERENCE_IN_YEARS, DIFFERENCE_IN_WEEKS, DIFFERENCE_IN_MONTHS, DIFFERENCE_IN_DAYS, DATE, ADD_YEARS, ADD_MONTHS, ADD_DAYS };
+	export { YEAR, WEEKDAY, TODAY, START_OF_YEAR, START_OF_WEEK, START_OF_QUARTER, START_OF_MONTH, QUARTER, MONTH, IS_WEEKEND, IS_SAME_DAY, IS_LEAP_YEAR, END_OF_YEAR, END_OF_MONTH, DIFFERENCE_IN_YEARS, DIFFERENCE_IN_WEEKS, DIFFERENCE_IN_MONTHS, DIFFERENCE_IN_DAYS, DAY_OF_YEAR, DAY, DATE, AGE, ADD_YEARS, ADD_MONTHS, ADD_DAYS };
 }
 /**
 * Date utility functions using Temporal.PlainDate and Temporal.PlainDateTime
@@ -455,27 +499,27 @@ declare const DATE: (year: RuntimeValue, month: RuntimeValue, day: RuntimeValue)
 /**
 * Get the year from a date or datetime
 */
-declare const GET_YEAR: (date: RuntimeValue) => RuntimeValue;
+declare const YEAR: (date: RuntimeValue) => RuntimeValue;
 /**
 * Get the month from a date or datetime (1-based: 1 = January, 12 = December)
 */
-declare const GET_MONTH: (date: RuntimeValue) => RuntimeValue;
+declare const MONTH: (date: RuntimeValue) => RuntimeValue;
 /**
 * Get the day of month from a date or datetime (1-31)
 */
-declare const GET_DAY: (date: RuntimeValue) => RuntimeValue;
+declare const DAY: (date: RuntimeValue) => RuntimeValue;
 /**
 * Get the day of week from a date or datetime (1 = Monday, 7 = Sunday)
 */
-declare const GET_WEEKDAY: (date: RuntimeValue) => RuntimeValue;
+declare const WEEKDAY: (date: RuntimeValue) => RuntimeValue;
 /**
 * Get the day of year (1-366) from a date or datetime
 */
-declare const GET_DAY_OF_YEAR: (date: RuntimeValue) => RuntimeValue;
+declare const DAY_OF_YEAR: (date: RuntimeValue) => RuntimeValue;
 /**
 * Get the quarter (1-4) from a date or datetime
 */
-declare const GET_QUARTER: (date: RuntimeValue) => RuntimeValue;
+declare const QUARTER: (date: RuntimeValue) => RuntimeValue;
 /**
 * Add days to a date or datetime, returning the same type
 */
@@ -542,6 +586,12 @@ declare const IS_WEEKEND: (date: RuntimeValue) => RuntimeValue;
 * Check if a date or datetime is in a leap year
 */
 declare const IS_LEAP_YEAR: (date: RuntimeValue) => RuntimeValue;
+/**
+* Calculate age in complete years from a birth date.
+* Accepts PlainDate or PlainDateTime (only the date portion is used).
+* Optional second argument specifies the reference date (defaults to today).
+*/
+declare const AGE: (birthDate: RuntimeValue, ...rest: RuntimeValue[]) => RuntimeValue;
 declare namespace datetimefull {
 	export { TO_TIME, TO_DATE, START_OF_DAY, NOW, END_OF_DAY, DATETIME, COMBINE };
 }
@@ -601,13 +651,9 @@ declare const EXP: (x: RuntimeValue) => RuntimeValue;
 */
 declare const CLAMP: (value: RuntimeValue, min: RuntimeValue, max: RuntimeValue) => RuntimeValue;
 declare namespace string {
-	export { STR_UPPER, STR_TRIM, STR_STARTS_WITH, STR_SPLIT, STR_SLICE, STR_REPLACE, STR_REPEAT, STR_LOWER, STR_LEN, STR_INDEX_OF, STR_ENDS_WITH, STR_CONTAINS };
+	export { STR_UPPER, STR_TRIM, STR_STARTS_WITH, STR_SPLIT, STR_REPLACE, STR_REPEAT, STR_LOWER, STR_ENDS_WITH };
 }
 /**
-* Get the length of a string
-*/
-declare const STR_LEN: (s: RuntimeValue) => RuntimeValue;
-/**
 * Convert string to uppercase
 */
 declare const STR_UPPER: (s: RuntimeValue) => RuntimeValue;
@@ -620,19 +666,6 @@ declare const STR_LOWER: (s: RuntimeValue) => RuntimeValue;
 */
 declare const STR_TRIM: (s: RuntimeValue) => RuntimeValue;
 /**
-* Extract a section of a string (0-based indices)
-*/
-declare const STR_SLICE: (s: RuntimeValue, start: RuntimeValue, end?: RuntimeValue) => RuntimeValue;
-/**
-* Check if a string contains another string
-* Returns boolean
-*/
-declare const STR_CONTAINS: (s: RuntimeValue, search: RuntimeValue) => RuntimeValue;
-/**
-* Find the first index of a substring (-1 if not found)
-*/
-declare const STR_INDEX_OF: (s: RuntimeValue, search: RuntimeValue) => RuntimeValue;
-/**
 * Split a string by a separator into a string array
 */
 declare const STR_SPLIT: (s: RuntimeValue, sep: RuntimeValue) => RuntimeValue;
@@ -653,7 +686,7 @@ declare const STR_ENDS_WITH: (s: RuntimeValue, suffix: RuntimeValue) => RuntimeV
 */
 declare const STR_REPEAT: (s: RuntimeValue, count: RuntimeValue) => RuntimeValue;
 declare namespace time {
-	export { TIME, NOW_TIME, IS_SAME_TIME, GET_SECOND, GET_MINUTE, GET_MILLISECOND, GET_HOUR, DIFFERENCE_IN_SECONDS, DIFFERENCE_IN_MINUTES, DIFFERENCE_IN_HOURS, ADD_SECONDS, ADD_MINUTES, ADD_HOURS };
+	export { TIME, SECOND, NOW_TIME, MINUTE, MILLISECOND, IS_SAME_TIME, HOUR, DIFFERENCE_IN_SECONDS, DIFFERENCE_IN_MINUTES, DIFFERENCE_IN_HOURS, ADD_SECONDS, ADD_MINUTES, ADD_HOURS };
 }
 /**
 * Time utility functions using Temporal.PlainTime and Temporal.PlainDateTime
@@ -671,19 +704,19 @@ declare const NOW_TIME: () => RuntimeValue;
 /**
 * Get the hour (0-23) from a time or datetime
 */
-declare const GET_HOUR: (t: RuntimeValue) => RuntimeValue;
+declare const HOUR: (t: RuntimeValue) => RuntimeValue;
 /**
 * Get the minute (0-59) from a time or datetime
 */
-declare const GET_MINUTE: (t: RuntimeValue) => RuntimeValue;
+declare const MINUTE: (t: RuntimeValue) => RuntimeValue;
 /**
 * Get the second (0-59) from a time or datetime
 */
-declare const GET_SECOND: (t: RuntimeValue) => RuntimeValue;
+declare const SECOND: (t: RuntimeValue) => RuntimeValue;
 /**
 * Get the millisecond (0-999) from a time or datetime
 */
-declare const GET_MILLISECOND: (t: RuntimeValue) => RuntimeValue;
+declare const MILLISECOND: (t: RuntimeValue) => RuntimeValue;
 /**
 * Add hours to a time or datetime.
 * PlainTime wraps around at midnight boundaries.
@@ -764,65 +797,4 @@ declare function assertTimeOrDateTime(v: RuntimeValue, context: string): asserts
 * Assert a value is an array, throwing a TypeError if not
 */
 declare function assertArray(v: RuntimeValue, context: string): asserts v is readonly RuntimeValue[];
-/**
-* A single visitor handler: receives a narrowed node and a recurse function.
-*
-* @template N The specific AST node type this handler accepts
-* @template T The return type shared across all handlers
-*/
-type VisitorHandler<
-	N,
-	T
-> = (node: N, recurse: (n: ASTNode) => T) => T;
-/**
-* Type-safe visitor pattern for AST traversal.
-*
-* A visitor is an object with one handler per AST node type.
-* Each handler receives the narrowed node and a `recurse` function
-* for visiting child nodes with the same visitor.
-*
-* @template T The return type of visitor handlers
-*/
-type Visitor<T> = {
-	Program: VisitorHandler<Program, T>;
-	NumberLiteral: VisitorHandler<NumberLiteral, T>;
-	StringLiteral: VisitorHandler<StringLiteral, T>;
-	BooleanLiteral: VisitorHandler<BooleanLiteral, T>;
-	ArrayLiteral: VisitorHandler<ArrayLiteral, T>;
-	Identifier2: VisitorHandler<Identifier2, T>;
-	BinaryOp: VisitorHandler<BinaryOp, T>;
-	UnaryOp: VisitorHandler<UnaryOp, T>;
-	FunctionCall: VisitorHandler<FunctionCall, T>;
-	Assignment: VisitorHandler<Assignment, T>;
-	IfExpression: VisitorHandler<IfExpression, T>;
-	ForExpression: VisitorHandler<ForExpression, T>;
-	IndexAccess: VisitorHandler<IndexAccess, T>;
-	RangeExpression: VisitorHandler<RangeExpression, T>;
-	PipeExpression: VisitorHandler<PipeExpression, T>;
-	Placeholder: VisitorHandler<Placeholder, T>;
-};
-/**
-* Visit an AST node using a visitor object with type-specific handlers.
-* All node types must have handlers (exhaustive by design).
-*
-* @template T The return type of visitor handlers
-* @param node The AST node to visit
-* @param visitor Object with handlers for each node type
-* @returns The result of visiting the node
-*/
-declare function visit<T>(node: ASTNode, visitor: Visitor<T>): T;
-/**
-* Visit an AST node using a partial visitor with a default handler.
-*
-* Unlike `visit()` which requires exhaustive handlers, `visitPartial()` allows
-* you to handle only specific node types. Unhandled nodes are processed by
-* the default handler.
-*
-* @template T The return type of visitor handlers
-* @param node The AST node to visit
-* @param visitor Object with optional handlers for node types
-* @param defaultHandler Handler for unhandled node types
-* @returns The result of visiting the node
-*/
-declare function visitPartial<T>(node: ASTNode, visitor: Partial<Visitor<T>>, defaultHandler: VisitorHandler<ASTNode, T>): T;
-export { visitPartial, visit, typeOf, time, string, parse, optimize, math, isUnaryOp, isStringLiteral, isRangeExpression, isProgram, isPlaceholder, isPipeExpression, isNumberLiteral, isIndexAccess, isIfExpression, isIdentifier, isFunctionCall, isForExpression, isBooleanLiteral, isBinaryOp, isAssignment, isArrayLiteral, generate, extractInputVariables, extractAssignedVariables, evaluateScope, evaluate, defaultContext, datetimefull, datetime, core, exports_ast as ast, assertTimeOrDateTime, assertTime, assertString, assertNumber, assertDateTime, assertDateOrDateTime, assertDate, assertBoolean, assertArray, array, VisitorHandler, Visitor, UnaryOp, StringLiteral, RuntimeValue, RangeExpression, Program, Placeholder, PipeExpression, Operator, NumberLiteral, NodeKind, IndexAccess, IfExpression, Identifier2 as Identifier, FunctionCall, ForExpression, ExecutionContext, BooleanLiteral, BinaryOp, Assignment, ArrayLiteral, ASTNodeBase, ASTNode };
+export { visit, typeOf, toLineColumn, time, string, parse, optimize, math, isUnaryOp, isStringLiteral, isRangeExpression, isProgram, isPlaceholder, isPipeExpression, isNumberLiteral, isIndexAccess, isIfExpression, isIdentifier, isFunctionCall, isForExpression, isBooleanLiteral, isBinaryOp, isAssignment, isArrayLiteral, generate, extractInputVariables, extractAssignedVariables, evaluateWithScope, evaluateScope, evaluate, defaultContext, datetimefull, datetime, core, exports_ast as ast, assertTimeOrDateTime, assertTime, assertString, assertNumber, assertDateTime, assertDateOrDateTime, assertDate, assertBoolean, assertArray, array, Visitor, UnaryOp, StringLiteral, RuntimeValue, RangeExpression, Program, Placeholder, PipeExpression, ParseError, Operator, NumberLiteral, NodeKind, IndexAccess, IfExpression, Identifier2 as Identifier, FunctionCall, ForExpression, ExecutionResult, ExecutionContext, BooleanLiteral, BinaryOp, Assignment, ArrayLiteral, ASTNodeBase, ASTNode };