littlewing 1.0.0 → 1.1.0

package/README.md

@@ -260,17 +260,27 @@ const ast = parse("x = 5; x + 10");
 
 // Count all identifiers in an AST
 const count = visit(ast, {
-	Program: (n, recurse) =>
-		n.statements.reduce((sum, stmt) => sum + recurse(stmt), 0),
+	// Tuple: [kind, statements]
+	Program: (n, recurse) => {
+		const statements = n[1];
+		return statements.reduce((sum, stmt) => sum + recurse(stmt), 0);
+	},
 	NumberLiteral: () => 0,
 	Identifier: () => 1,
-	BinaryOp: (n, recurse) => recurse(n.left) + recurse(n.right),
-	UnaryOp: (n, recurse) => recurse(n.argument),
-	Assignment: (n, recurse) => 1 + recurse(n.value),
-	FunctionCall: (n, recurse) =>
-		1 + n.arguments.reduce((sum, arg) => sum + recurse(arg), 0),
+	// Tuple: [kind, left, operator, right]
+	BinaryOp: (n, recurse) => recurse(n[1]) + recurse(n[3]),
+	// Tuple: [kind, operator, argument]
+	UnaryOp: (n, recurse) => recurse(n[2]),
+	// Tuple: [kind, name, value]
+	Assignment: (n, recurse) => 1 + recurse(n[2]),
+	// Tuple: [kind, name, arguments]
+	FunctionCall: (n, recurse) => {
+		const args = n[2];
+		return 1 + args.reduce((sum, arg) => sum + recurse(arg), 0);
+	},
+	// Tuple: [kind, condition, consequent, alternate]
 	ConditionalExpression: (n, recurse) =>
-		recurse(n.condition) + recurse(n.consequent) + recurse(n.alternate),
+		recurse(n[1]) + recurse(n[2]) + recurse(n[3]),
 }); // → 3 (x appears 3 times)
 ```
 
@@ -287,18 +297,24 @@ const ast = parse("x = 5; y = x + 10; y * 2");
 const result = visitPartial(
 	ast,
 	{
+		// Tuple: [kind, statements]
 		Program: (n, recurse) => {
-			for (const stmt of n.statements) {
+			const statements = n[1];
+			for (const stmt of statements) {
 				const found = recurse(stmt);
 				if (found !== undefined) return found;
 			}
 			return undefined;
 		},
+		// Tuple: [kind, name, value]
 		Assignment: (n, recurse) => {
-			if (n.name === "y") return n; // Found it!
-			return recurse(n.value); // Keep searching
+			const name = n[1];
+			const value = n[2];
+			if (name === "y") return n; // Found it!
+			return recurse(value); // Keep searching
 		},
-		BinaryOp: (n, recurse) => recurse(n.left) ?? recurse(n.right),
+		// Tuple: [kind, left, operator, right]
+		BinaryOp: (n, recurse) => recurse(n[1]) ?? recurse(n[3]),
 	},
 	() => undefined,
 ); // → Assignment node for "y = x + 10"
@@ -313,22 +329,29 @@ import { visit, parse, ast } from "littlewing";
 
 // Double all numeric literals
 const transformed = visit<ASTNode>(parse("2 + 3 * 4"), {
-	Program: (n, recurse) =>
-		ast.program(n.statements.map((stmt) => recurse(stmt))),
-	NumberLiteral: (n) => ast.number(n.value * 2),
+	// Tuple: [kind, statements]
+	Program: (n, recurse) => {
+		const statements = n[1];
+		return ast.program(statements.map((stmt) => recurse(stmt)));
+	},
+	// Tuple: [kind, value]
+	NumberLiteral: (n) => ast.number(n[1] * 2),
 	Identifier: (n) => n,
-	BinaryOp: (n, recurse) =>
-		ast.binaryOp(recurse(n.left), n.operator, recurse(n.right)),
-	UnaryOp: (n, recurse) => ast.unaryOp(n.operator, recurse(n.argument)),
-	Assignment: (n, recurse) => ast.assignment(n.name, recurse(n.value)),
-	FunctionCall: (n, recurse) =>
-		ast.functionCall(n.name, n.arguments.map(recurse)),
+	// Tuple: [kind, left, operator, right]
+	BinaryOp: (n, recurse) => ast.binaryOp(recurse(n[1]), n[2], recurse(n[3])),
+	// Tuple: [kind, operator, argument]
+	UnaryOp: (n, recurse) => ast.unaryOp(n[1], recurse(n[2])),
+	// Tuple: [kind, name, value]
+	Assignment: (n, recurse) => ast.assign(n[1], recurse(n[2])),
+	// Tuple: [kind, name, arguments]
+	FunctionCall: (n, recurse) => {
+		const name = n[1];
+		const args = n[2];
+		return ast.functionCall(name, args.map(recurse));
+	},
+	// Tuple: [kind, condition, consequent, alternate]
 	ConditionalExpression: (n, recurse) =>
-		ast.conditional(
-			recurse(n.condition),
-			recurse(n.consequent),
-			recurse(n.alternate),
-		),
+		ast.conditional(recurse(n[1]), recurse(n[2]), recurse(n[3])),
 });
 
 generate(transformed); // → "4 + 6 * 8"

package/dist/index.d.ts

@@ -1,168 +1,87 @@
-/**
-* Runtime value type - only numbers
-*/
-type RuntimeValue = number;
+declare namespace exports_ast {
+	export { unaryOp, subtract, program, number, notEquals, negate, multiply, modulo, logicalOr, logicalNot, logicalAnd, lessThan, lessEqual, isUnaryOp, isProgram, isNumberLiteral, isIdentifier, isFunctionCall, isConditionalExpression, isBinaryOp, isAssignment, identifier, greaterThan, greaterEqual, getNodeName, functionCall, exponentiate, equals, divide, conditional, binaryOp, assign, add, UnaryOp, Program, Operator, NumberLiteral, NodeKind, Identifier, FunctionCall, ConditionalExpression, BinaryOp, Assignment, ASTNode };
+}
 /**
 * Binary operator types
 */
 type Operator = "+" | "-" | "*" | "/" | "%" | "^" | "==" | "!=" | "<" | ">" | "<=" | ">=" | "&&" | "||";
 /**
-* Execution context providing global functions and variables
-* Functions must accept zero or more number arguments and return a number
-* Variables must be numbers
-*/
-interface ExecutionContext {
-	functions?: Record<string, (...args: RuntimeValue[]) => RuntimeValue>;
-	variables?: Record<string, RuntimeValue>;
-}
-/**
-* Token types for lexer output
-*/
-declare enum TokenType {
-	NUMBER = "NUMBER",
-	IDENTIFIER = "IDENTIFIER",
-	PLUS = "PLUS",
-	MINUS = "MINUS",
-	STAR = "STAR",
-	SLASH = "SLASH",
-	PERCENT = "PERCENT",
-	CARET = "CARET",
-	EXCLAMATION = "EXCLAMATION",
-	DOUBLE_EQUALS = "DOUBLE_EQUALS",
-	NOT_EQUALS = "NOT_EQUALS",
-	LESS_THAN = "LESS_THAN",
-	GREATER_THAN = "GREATER_THAN",
-	LESS_EQUAL = "LESS_EQUAL",
-	GREATER_EQUAL = "GREATER_EQUAL",
-	LOGICAL_AND = "LOGICAL_AND",
-	LOGICAL_OR = "LOGICAL_OR",
-	LPAREN = "LPAREN",
-	RPAREN = "RPAREN",
-	EQUALS = "EQUALS",
-	COMMA = "COMMA",
-	QUESTION = "QUESTION",
-	COLON = "COLON",
-	EOF = "EOF"
+* AST Node kind discriminator (const enum for zero-cost abstraction)
+*/
+declare const enum NodeKind {
+	Program = 0,
+	NumberLiteral = 1,
+	Identifier = 2,
+	BinaryOp = 3,
+	UnaryOp = 4,
+	FunctionCall = 5,
+	Assignment = 6,
+	ConditionalExpression = 7
 }
 /**
-* Token produced by lexer
-*/
-interface Token {
-	type: TokenType;
-	value: string | number;
-	position: number;
-}
-/**
-* AST Node - base type
-*/
-type ASTNode = Program | NumberLiteral | Identifier | BinaryOp | UnaryOp | FunctionCall | Assignment | ConditionalExpression;
-/**
 * Program node (multiple statements)
+* Tuple: [kind, statements]
 */
-interface Program {
-	type: "Program";
-	statements: ASTNode[];
-}
+type Program = readonly [kind: NodeKind.Program, statements: readonly ASTNode[]];
 /**
 * Number literal (123, 45.67)
+* Tuple: [kind, value]
 */
-interface NumberLiteral {
-	type: "NumberLiteral";
-	value: number;
-}
+type NumberLiteral = readonly [kind: NodeKind.NumberLiteral, value: number];
 /**
 * Identifier (variable or function name)
+* Tuple: [kind, name]
 */
-interface Identifier {
-	type: "Identifier";
-	name: string;
-}
+type Identifier = readonly [kind: NodeKind.Identifier, name: string];
 /**
 * Binary operation (a + b, x * y, etc.)
+* Tuple: [kind, left, operator, right]
+* Note: left-to-right reading order
 */
-interface BinaryOp {
-	type: "BinaryOp";
-	left: ASTNode;
-	operator: Operator;
-	right: ASTNode;
-}
+type BinaryOp = readonly [kind: NodeKind.BinaryOp, left: ASTNode, operator: Operator, right: ASTNode];
 /**
 * Unary operation (-x, !x, etc.)
+* Tuple: [kind, operator, argument]
 */
-interface UnaryOp {
-	type: "UnaryOp";
-	operator: "-" | "!";
-	argument: ASTNode;
-}
+type UnaryOp = readonly [kind: NodeKind.UnaryOp, operator: "-" | "!", argument: ASTNode];
 /**
-* Function call (now(), abs(-5), etc.)
+* Function call (NOW(), MAX(a, b), etc.)
+* Tuple: [kind, name, arguments]
 */
-interface FunctionCall {
-	type: "FunctionCall";
-	name: string;
-	arguments: ASTNode[];
-}
+type FunctionCall = readonly [kind: NodeKind.FunctionCall, name: string, arguments: readonly ASTNode[]];
 /**
 * Variable assignment (x = 5)
+* Tuple: [kind, name, value]
 */
-interface Assignment {
-	type: "Assignment";
-	name: string;
-	value: ASTNode;
-}
+type Assignment = readonly [kind: NodeKind.Assignment, name: string, value: ASTNode];
 /**
 * Conditional expression (ternary operator: condition ? consequent : alternate)
 * Returns consequent if condition !== 0, otherwise returns alternate
+* Tuple: [kind, condition, consequent, alternate]
 */
-interface ConditionalExpression {
-	type: "ConditionalExpression";
-	condition: ASTNode;
-	consequent: ASTNode;
-	alternate: ASTNode;
-}
+type ConditionalExpression = readonly [kind: NodeKind.ConditionalExpression, condition: ASTNode, consequent: ASTNode, alternate: ASTNode];
+/**
+* AST Node - discriminated union of all node types
+*/
+type ASTNode = Program | NumberLiteral | Identifier | BinaryOp | UnaryOp | FunctionCall | Assignment | ConditionalExpression;
 /**
 * Type guard functions for discriminated union narrowing
 */
+declare function isProgram(node: ASTNode): node is Program;
 declare function isNumberLiteral(node: ASTNode): node is NumberLiteral;
 declare function isIdentifier(node: ASTNode): node is Identifier;
 declare function isBinaryOp(node: ASTNode): node is BinaryOp;
 declare function isUnaryOp(node: ASTNode): node is UnaryOp;
 declare function isFunctionCall(node: ASTNode): node is FunctionCall;
 declare function isAssignment(node: ASTNode): node is Assignment;
-declare function isProgram(node: ASTNode): node is Program;
 declare function isConditionalExpression(node: ASTNode): node is ConditionalExpression;
 /**
-* Extracts input variables from an AST.
-*
-* Input variables are those whose values can be determined without knowing
-* the values of other variables in the script. This includes:
-* - Literals (10, -5, 3.14)
-* - Unary minus of literals (-10)
-* - Constant expressions (2 + 3, -5 * 2)
-* - Function calls with constant arguments (MAX(10, 20), NOW())
-*
-* Computed variables (those that reference other variables) are excluded.
-*
-* @param ast - The AST to analyze (can be a single statement or Program node)
-* @returns Array of input variable names
-*
-* @example
-* ```typescript
-* const ast = parse('price = 100; tax = price * 0.08')
-* extractInputVariables(ast) // ['price']
-* ```
-*/
-declare function extractInputVariables(ast: ASTNode): string[];
-declare namespace exports_ast {
-	export { unaryOp, subtract, program, number, notEquals, negate, multiply, modulo, logicalOr, logicalNot, logicalAnd, lessThan, lessEqual, identifier, greaterThan, greaterEqual, functionCall, exponentiate, equals, divide, conditional, binaryOp, assign, add };
-}
-/**
 * Builder functions for creating AST nodes manually
 */
 /**
 * Create a program node
 */
-declare function program(statements: ASTNode[]): Program;
+declare function program(statements: readonly ASTNode[]): Program;
 /**
 * Create a number literal node
 */
@@ -182,7 +101,7 @@ declare function unaryOp(operator: "-" | "!", argument: ASTNode): UnaryOp;
 /**
 * Create a function call node
 */
-declare function functionCall(name: string, args?: ASTNode[]): FunctionCall;
+declare function functionCall(name: string, args?: readonly ASTNode[]): FunctionCall;
 /**
 * Create a variable assignment node
 */
@@ -264,41 +183,33 @@ declare function logicalAnd(left: ASTNode, right: ASTNode): BinaryOp;
 * Create a logical OR operation (||)
 */
 declare function logicalOr(left: ASTNode, right: ASTNode): BinaryOp;
+declare function getNodeName(node: ASTNode): string;
 /**
-* Generate source code from an AST node
-*/
-declare function generate(node: ASTNode): string;
-/**
-* Default execution context with common Math functions and date/time utilities
-* Users can use this as-is or spread it into their own context
-*
-* All functions use UPPERCASE naming convention to avoid collisions with user variables.
-* All date-related functions work with timestamps (milliseconds since Unix epoch)
-* to maintain the language's numbers-only type system.
+* Extracts input variables from an AST.
 *
-* @example
-* // Use as-is
-* execute('ABS(-5)', defaultContext)
+* Input variables are those whose values can be determined without knowing
+* the values of other variables in the script. This includes:
+* - Literals (10, -5, 3.14)
+* - Unary minus of literals (-10)
+* - Constant expressions (2 + 3, -5 * 2)
+* - Function calls with constant arguments (MAX(10, 20), NOW())
 *
-* @example
-* // Spread into custom context
-* execute('NOW() + FROM_MINUTES(5)', {
-*   ...defaultContext,
-*   variables: { customVar: 42 }
-* })
+* Computed variables (those that reference other variables) are excluded.
 *
-* @example
-* // Work with timestamps
-* const result = execute('NOW() + FROM_DAYS(7)', defaultContext)
-* const futureDate = new Date(result) // Convert back to Date if needed
+* @param ast - The AST to analyze (can be a single statement or Program node)
+* @returns Array of input variable names
 *
 * @example
-* // Calculate time differences
-* const ts1 = Date.now()
-* const ts2 = ts1 + 1000 * 60 * 60 * 3 // 3 hours later
-* execute('DIFFERENCE_IN_HOURS(ts1, ts2)', { ...defaultContext, variables: { ts1, ts2 } })
+* ```typescript
+* const ast = parse('price = 100; tax = price * 0.08')
+* extractInputVariables(ast) // ['price']
+* ```
 */
-declare const defaultContext: ExecutionContext;
+declare function extractInputVariables(ast: ASTNode): string[];
+/**
+* Generate source code from an AST node
+*/
+declare function generate(node: ASTNode): string;
 /**
 * Options for customizing the humanization output
 */
@@ -363,9 +274,23 @@ interface HumanizeOptions {
 */
 declare function humanize(node: ASTNode, options?: HumanizeOptions): string;
 /**
+* Runtime value type - only numbers
+*/
+type RuntimeValue = number;
+/**
+* Execution context providing global functions and variables
+* Functions must accept zero or more number arguments and return a number
+* Variables must be numbers
+*/
+interface ExecutionContext {
+	functions?: Record<string, (...args: RuntimeValue[]) => RuntimeValue>;
+	variables?: Record<string, RuntimeValue>;
+}
+/**
 * Evaluate source code or AST with given context
 * @param input - Either a source code string or an AST node
 * @param context - Optional execution context with variables and functions
+* @returns The evaluated result
 */
 declare function evaluate(input: string | ASTNode, context?: ExecutionContext): RuntimeValue;
 /**
@@ -395,12 +320,257 @@ declare function evaluate(input: string | ASTNode, context?: ExecutionContext):
 declare function optimize(node: ASTNode): ASTNode;
 /**
 * Parse source code string into AST
-* Convenience function that creates lexer and parser
+* Implements Pratt parsing (top-down operator precedence)
+* Uses lazy lexing - calls lexer on-demand instead of receiving all tokens upfront
 *
 * @param source - The source code to parse
 * @returns Parsed AST
 */
 declare function parse(source: string): ASTNode;
+declare namespace exports_datetime {
+	export { START_OF_YEAR, START_OF_WEEK, START_OF_QUARTER, START_OF_MONTH, START_OF_DAY, NOW, IS_WEEKEND, IS_SAME_DAY, IS_LEAP_YEAR, GET_YEAR, GET_WEEKDAY, GET_SECOND, GET_QUARTER, GET_MONTH, GET_MINUTE, GET_MILLISECOND, GET_HOUR, GET_DAY_OF_YEAR, GET_DAY, FROM_YEARS, FROM_WEEKS, FROM_MONTHS, FROM_DAYS, END_OF_YEAR, END_OF_MONTH, END_OF_DAY, DIFFERENCE_IN_YEARS, DIFFERENCE_IN_WEEKS, DIFFERENCE_IN_SECONDS, DIFFERENCE_IN_MONTHS, DIFFERENCE_IN_MINUTES, DIFFERENCE_IN_HOURS, DIFFERENCE_IN_DAYS, DATE, ADD_YEARS, ADD_MONTHS, ADD_DAYS };
+}
+/**
+* Date utility functions for working with timestamps
+* All functions work with milliseconds since Unix epoch (numbers only)
+*
+* IMPORTANT: All functions use local timezone to match the user's context.
+* In a browser, this reflects the user's timezone. On a server, this reflects
+* the server's configured timezone. This ensures date calculations align with
+* the user's calendar expectations.
+*/
+/**
+* Get current timestamp (milliseconds since Unix epoch)
+*/
+declare const NOW: () => RuntimeValue;
+/**
+* Create timestamp from date components (local timezone)
+* Year is required, all other parameters default to minimum values
+* Month is 1-based (1 = January, 12 = December)
+* All parameters are interpreted in local timezone
+*/
+declare const DATE: (year: RuntimeValue, month?: number, day?: number, hour?: number, minute?: number, second?: number) => RuntimeValue;
+/**
+* Convert days to milliseconds
+*/
+declare const FROM_DAYS: (d: RuntimeValue) => RuntimeValue;
+/**
+* Convert weeks to milliseconds
+*/
+declare const FROM_WEEKS: (w: RuntimeValue) => RuntimeValue;
+/**
+* Convert months to milliseconds (approximate: 30 days per month)
+* WARNING: This is an approximation. Not all months have 30 days.
+* For accurate month arithmetic, use ADD_MONTHS() instead.
+*/
+declare const FROM_MONTHS: (months: RuntimeValue) => RuntimeValue;
+/**
+* Convert years to milliseconds (approximate: 365 days per year)
+* WARNING: This is an approximation. Leap years have 366 days.
+* For accurate year arithmetic, use ADD_YEARS() instead.
+*/
+declare const FROM_YEARS: (years: RuntimeValue) => RuntimeValue;
+/**
+* Get the year from a timestamp (local timezone)
+*/
+declare const GET_YEAR: (timestamp: RuntimeValue) => RuntimeValue;
+/**
+* Get the month from a timestamp (1-based: 1 = January, 12 = December, local timezone)
+*/
+declare const GET_MONTH: (timestamp: RuntimeValue) => RuntimeValue;
+/**
+* Get the day of month from a timestamp (1-31, local timezone)
+*/
+declare const GET_DAY: (timestamp: RuntimeValue) => RuntimeValue;
+/**
+* Get the hour from a timestamp (0-23, local timezone)
+*/
+declare const GET_HOUR: (timestamp: RuntimeValue) => RuntimeValue;
+/**
+* Get the minute from a timestamp (0-59, local timezone)
+*/
+declare const GET_MINUTE: (timestamp: RuntimeValue) => RuntimeValue;
+/**
+* Get the second from a timestamp (0-59, local timezone)
+*/
+declare const GET_SECOND: (timestamp: RuntimeValue) => RuntimeValue;
+/**
+* Get the millisecond component from a timestamp (0-999, local timezone)
+*/
+declare const GET_MILLISECOND: (timestamp: RuntimeValue) => RuntimeValue;
+/**
+* Get the day of week from a timestamp (0 = Sunday, 6 = Saturday, local timezone)
+*/
+declare const GET_WEEKDAY: (timestamp: RuntimeValue) => RuntimeValue;
+/**
+* Get the day of year (1-366) from a timestamp (local timezone)
+* January 1st = 1, December 31st = 365 or 366 (leap year)
+*/
+declare const GET_DAY_OF_YEAR: (timestamp: RuntimeValue) => RuntimeValue;
+/**
+* Get the quarter (1-4) from a timestamp (local timezone)
+*/
+declare const GET_QUARTER: (timestamp: RuntimeValue) => RuntimeValue;
+/**
+* Get the absolute difference between two timestamps in seconds (whole seconds)
+*/
+declare const DIFFERENCE_IN_SECONDS: (ts1: RuntimeValue, ts2: RuntimeValue) => RuntimeValue;
+/**
+* Get the absolute difference between two timestamps in minutes (whole minutes)
+*/
+declare const DIFFERENCE_IN_MINUTES: (ts1: RuntimeValue, ts2: RuntimeValue) => RuntimeValue;
+/**
+* Get the absolute difference between two timestamps in hours (whole hours)
+*/
+declare const DIFFERENCE_IN_HOURS: (ts1: RuntimeValue, ts2: RuntimeValue) => RuntimeValue;
+/**
+* Get the difference in calendar days between two timestamps
+* Counts the number of calendar day boundaries crossed, not 24-hour periods
+* Example: Nov 7 at 11:59 PM to Nov 8 at 12:01 AM = 1 day (different calendar days)
+*/
+declare const DIFFERENCE_IN_DAYS: (ts1: RuntimeValue, ts2: RuntimeValue) => RuntimeValue;
+/**
+* Get the difference in calendar weeks between two timestamps
+* Counts the number of week boundaries crossed (based on calendar days)
+*/
+declare const DIFFERENCE_IN_WEEKS: (ts1: RuntimeValue, ts2: RuntimeValue) => RuntimeValue;
+/**
+* Get the number of full calendar months between two timestamps (local timezone)
+* Counts complete months where the same day-of-month has been reached
+*
+* Examples:
+*   Jan 15 → Feb 14 = 0 months (Feb 15 not reached yet)
+*   Jan 15 → Feb 15 = 1 month
+*   Jan 31 → Feb 28 = 0 months (Feb 31 doesn't exist)
+*   Jan 31 → Mar 31 = 2 months
+*/
+declare const DIFFERENCE_IN_MONTHS: (ts1: RuntimeValue, ts2: RuntimeValue) => RuntimeValue;
+/**
+* Get the number of full calendar years between two timestamps (local timezone)
+* Counts complete years where the same month and day have been reached
+*
+* Examples:
+*   Jan 15, 2020 → Jan 14, 2021 = 0 years (Jan 15 not reached)
+*   Jan 15, 2020 → Jan 15, 2021 = 1 year
+*   Feb 29, 2020 → Feb 28, 2021 = 0 years (Feb 29 doesn't exist)
+*   Feb 29, 2020 → Mar 1, 2021 = 1 year
+*/
+declare const DIFFERENCE_IN_YEARS: (ts1: RuntimeValue, ts2: RuntimeValue) => RuntimeValue;
+/**
+* Get the start of day (00:00:00.000 local time) for a given timestamp
+*/
+declare const START_OF_DAY: (timestamp: RuntimeValue) => RuntimeValue;
+/**
+* Get the end of day (23:59:59.999 local time) for a given timestamp
+*/
+declare const END_OF_DAY: (timestamp: RuntimeValue) => RuntimeValue;
+/**
+* Get the start of week (Sunday at 00:00:00.000 local time) for a given timestamp
+*/
+declare const START_OF_WEEK: (timestamp: RuntimeValue) => RuntimeValue;
+/**
+* Get the start of month (1st day at 00:00:00.000 local time) for a given timestamp
+*/
+declare const START_OF_MONTH: (timestamp: RuntimeValue) => RuntimeValue;
+/**
+* Get the end of month (last day at 23:59:59.999 local time) for a given timestamp
+*/
+declare const END_OF_MONTH: (timestamp: RuntimeValue) => RuntimeValue;
+/**
+* Get the start of year (Jan 1st at 00:00:00.000 local time) for a given timestamp
+*/
+declare const START_OF_YEAR: (timestamp: RuntimeValue) => RuntimeValue;
+/**
+* Get the end of year (Dec 31st at 23:59:59.999 local time) for a given timestamp
+*/
+declare const END_OF_YEAR: (timestamp: RuntimeValue) => RuntimeValue;
+/**
+* Add days to a timestamp (local timezone)
+*/
+declare const ADD_DAYS: (timestamp: RuntimeValue, days: RuntimeValue) => RuntimeValue;
+/**
+* Add months to a timestamp (handles variable month lengths correctly, local timezone)
+*/
+declare const ADD_MONTHS: (timestamp: RuntimeValue, months: RuntimeValue) => RuntimeValue;
+/**
+* Add years to a timestamp (local timezone)
+*/
+declare const ADD_YEARS: (timestamp: RuntimeValue, years: RuntimeValue) => RuntimeValue;
+/**
+* Check if two timestamps are on the same calendar day (local timezone)
+* Returns 1 if true, 0 if false
+*/
+declare const IS_SAME_DAY: (ts1: RuntimeValue, ts2: RuntimeValue) => RuntimeValue;
+/**
+* Check if timestamp falls on a weekend (Saturday or Sunday, local timezone)
+* Returns 1 if true, 0 if false
+*/
+declare const IS_WEEKEND: (timestamp: RuntimeValue) => RuntimeValue;
+/**
+* Check if timestamp is in a leap year (local timezone)
+* Returns 1 if true, 0 if false
+*/
+declare const IS_LEAP_YEAR: (timestamp: RuntimeValue) => RuntimeValue;
+/**
+* Get the start of quarter for a given timestamp (local timezone)
+*/
+declare const START_OF_QUARTER: (timestamp: RuntimeValue) => RuntimeValue;
+declare namespace exports_math {
+	export { TAN, SQRT, SIN, ROUND, MIN, MAX, LOG10, LOG, FLOOR, EXP, COS, CLAMP, CEIL, ABS };
+}
+/**
+* Math utility functions
+* All functions work with numbers only
+*/
+/**
+* Constrain a value between a minimum and maximum
+* @example CLAMP(value, 0, 100) - Clamps value between 0 and 100
+*/
+declare const CLAMP: (value: RuntimeValue, min: RuntimeValue, max: RuntimeValue) => RuntimeValue;
+declare const ABS: (x: RuntimeValue) => RuntimeValue;
+declare const CEIL: (x: RuntimeValue) => RuntimeValue;
+declare const FLOOR: (x: RuntimeValue) => RuntimeValue;
+declare const ROUND: (x: RuntimeValue) => RuntimeValue;
+declare const SQRT: (x: RuntimeValue) => RuntimeValue;
+declare const MIN: (...values: RuntimeValue[]) => RuntimeValue;
+declare const MAX: (...values: RuntimeValue[]) => RuntimeValue;
+declare const SIN: (x: RuntimeValue) => RuntimeValue;
+declare const COS: (x: RuntimeValue) => RuntimeValue;
+declare const TAN: (x: RuntimeValue) => RuntimeValue;
+declare const LOG: (x: RuntimeValue) => RuntimeValue;
+declare const LOG10: (x: RuntimeValue) => RuntimeValue;
+declare const EXP: (x: RuntimeValue) => RuntimeValue;
+/**
+* Default execution context with standard library functions
+* Users can use this as-is or spread it into their own context
+*
+* All functions use UPPERCASE naming convention to avoid collisions with user variables.
+* All date-related functions work with timestamps (milliseconds since Unix epoch)
+* to maintain the language's numbers-only type system.
+*
+* @example
+* // Use as-is
+* execute('ABS(-5)', defaultContext)
+*
+* @example
+* // Spread into custom context
+* execute('NOW() + FROM_MINUTES(5)', {
+*   ...defaultContext,
+*   variables: { customVar: 42 }
+* })
+*
+* @example
+* // Work with timestamps
+* const result = execute('NOW() + FROM_DAYS(7)', defaultContext)
+* const futureDate = new Date(result) // Convert back to Date if needed
+*
+* @example
+* // Calculate time differences
+* const ts1 = Date.now()
+* const ts2 = ts1 + 1000 * 60 * 60 * 3 // 3 hours later
+* execute('DIFFERENCE_IN_HOURS(ts1, ts2)', { ...defaultContext, variables: { ts1, ts2 } })
+*/
+declare const defaultContext: ExecutionContext;
 /**
 * Type-safe visitor pattern for AST traversal.
 *
@@ -593,4 +763,4 @@ declare function visit<T>(node: ASTNode, visitor: Visitor<T>): T;
 * )
 */
 declare function visitPartial<T>(node: ASTNode, visitor: Partial<Visitor<T>>, defaultHandler: (node: ASTNode, recurse: (n: ASTNode) => T) => T): T;
-export { visitPartial, visit, parse, optimize, isUnaryOp, isProgram, isNumberLiteral, isIdentifier, isFunctionCall, isConditionalExpression, isBinaryOp, isAssignment, humanize, generate, extractInputVariables, evaluate, defaultContext, exports_ast as ast, Visitor, UnaryOp, TokenType, Token, RuntimeValue, Program, Operator, NumberLiteral, Identifier, HumanizeOptions, FunctionCall, ExecutionContext, ConditionalExpression, BinaryOp, Assignment, ASTNode };
+export { visitPartial, visit, parse, optimize, exports_math as math, isUnaryOp, isProgram, isNumberLiteral, isIdentifier, isFunctionCall, isConditionalExpression, isBinaryOp, isAssignment, humanize, generate, extractInputVariables, evaluate, defaultContext, exports_datetime as datetime, exports_ast as ast, Visitor, UnaryOp, RuntimeValue, Program, Operator, NumberLiteral, NodeKind, Identifier, HumanizeOptions, FunctionCall, ExecutionContext, ConditionalExpression, BinaryOp, Assignment, ASTNode };