littlewing 0.5.3 → 0.7.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 declare namespace exports_ast {
-	export { unaryOp, subtract, number, nullishAssign, notEquals, negate, multiply, modulo, logicalOr, logicalAnd, lessThan, lessEqual, identifier, greaterThan, greaterEqual, functionCall, exponentiate, equals, divide, conditional, binaryOp, assign, add };
+	export { unaryOp, subtract, program, number, notEquals, negate, multiply, modulo, logicalOr, logicalAnd, lessThan, lessEqual, identifier, greaterThan, greaterEqual, functionCall, exponentiate, equals, divide, conditional, binaryOp, assign, add };
 }
 /**
 * Runtime value type - only numbers
@@ -44,7 +44,6 @@ declare enum TokenType {
 	COMMA = "COMMA",
 	QUESTION = "QUESTION",
 	COLON = "COLON",
-	NULLISH_ASSIGN = "NULLISH_ASSIGN",
 	EOF = "EOF"
 }
 /**
@@ -58,7 +57,7 @@ interface Token {
 /**
 * AST Node - base type
 */
-type ASTNode = Program | NumberLiteral | Identifier | BinaryOp | UnaryOp | FunctionCall | Assignment | ConditionalExpression | NullishAssignment;
+type ASTNode = Program | NumberLiteral | Identifier | BinaryOp | UnaryOp | FunctionCall | Assignment | ConditionalExpression;
 /**
 * Program node (multiple statements)
 */
@@ -124,16 +123,6 @@ interface ConditionalExpression {
 	alternate: ASTNode;
 }
 /**
-* Nullish assignment (x ??= 5)
-* Assigns value only if variable is undefined (not provided in context)
-* Used for providing defaults for external variables
-*/
-interface NullishAssignment {
-	type: "NullishAssignment";
-	name: string;
-	value: ASTNode;
-}
-/**
 * Type guard functions for discriminated union narrowing
 */
 declare function isNumberLiteral(node: ASTNode): node is NumberLiteral;
@@ -144,11 +133,14 @@ 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;
-declare function isNullishAssignment(node: ASTNode): node is NullishAssignment;
 /**
 * Builder functions for creating AST nodes manually
 */
 /**
+* Create a program node
+*/
+declare function program(statements: ASTNode[]): Program;
+/**
 * Create a number literal node
 */
 declare function number(value: number): NumberLiteral;
@@ -173,11 +165,6 @@ declare function functionCall(name: string, args?: ASTNode[]): FunctionCall;
 */
 declare function assign(name: string, value: ASTNode): Assignment;
 /**
-* Create a nullish assignment node (x ??= 5)
-* Assigns only if variable is undefined
-*/
-declare function nullishAssign(name: string, value: ASTNode): NullishAssignment;
-/**
 * Create a conditional expression node (ternary operator)
 */
 declare function conditional(condition: ASTNode, consequent: ASTNode, alternate: ASTNode): ConditionalExpression;
@@ -287,10 +274,6 @@ declare class CodeGenerator {
 	*/
 	private generateAssignment;
 	/**
-	* Generate code for a nullish assignment
-	*/
-	private generateNullishAssignment;
-	/**
 	* Generate code for a conditional expression (ternary operator)
 	*/
 	private generateConditionalExpression;
@@ -311,36 +294,227 @@ declare class CodeGenerator {
 * Generate source code from an AST node
 */
 declare function generate(node: ASTNode): string;
+declare namespace exports_date_utils {
+	export { TO_UNIX_SECONDS, START_OF_YEAR, START_OF_WEEK, START_OF_QUARTER, START_OF_MONTH, START_OF_DAY, NOW, IS_WEEKEND, IS_SAME_DAY, IS_LEAP_YEAR, IS_BEFORE, IS_AFTER, 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_UNIX_SECONDS, FROM_SECONDS, FROM_MONTHS, FROM_MINUTES, FROM_HOURS, FROM_DAYS, END_OF_YEAR, END_OF_MONTH, END_OF_DAY, DIFFERENCE_IN_WEEKS, DIFFERENCE_IN_SECONDS, 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)
+*/
+/**
+* Get current timestamp (milliseconds since Unix epoch)
+*/
+declare const NOW: () => number;
+/**
+* Create timestamp from date components
+* Year is required, all other parameters default to minimum values
+* Month is 1-based (1 = January, 12 = December)
+*/
+declare const DATE: (year: number, month?: number, day?: number, hour?: number, minute?: number, second?: number) => number;
+/**
+* Convert seconds to milliseconds
+*/
+declare const FROM_SECONDS: (s: number) => number;
+/**
+* Convert minutes to milliseconds
+*/
+declare const FROM_MINUTES: (m: number) => number;
+/**
+* Convert hours to milliseconds
+*/
+declare const FROM_HOURS: (h: number) => number;
+/**
+* Convert days to milliseconds
+*/
+declare const FROM_DAYS: (d: number) => number;
+/**
+* Convert weeks to milliseconds
+*/
+declare const FROM_WEEKS: (w: number) => number;
+/**
+* Convert months to milliseconds (approximate: 30 days per month)
+*/
+declare const FROM_MONTHS: (months: number) => number;
+/**
+* Convert years to milliseconds (approximate: 365 days per year)
+*/
+declare const FROM_YEARS: (years: number) => number;
+/**
+* Get the year from a timestamp
+*/
+declare const GET_YEAR: (timestamp: number) => number;
+/**
+* Get the month from a timestamp (1-based: 1 = January, 12 = December)
+*/
+declare const GET_MONTH: (timestamp: number) => number;
+/**
+* Get the day of month from a timestamp (1-31)
+*/
+declare const GET_DAY: (timestamp: number) => number;
+/**
+* Get the hour from a timestamp (0-23)
+*/
+declare const GET_HOUR: (timestamp: number) => number;
+/**
+* Get the minute from a timestamp (0-59)
+*/
+declare const GET_MINUTE: (timestamp: number) => number;
+/**
+* Get the second from a timestamp (0-59)
+*/
+declare const GET_SECOND: (timestamp: number) => number;
+/**
+* Get the millisecond component from a timestamp (0-999)
+*/
+declare const GET_MILLISECOND: (timestamp: number) => number;
+/**
+* Get the day of week from a timestamp (0 = Sunday, 6 = Saturday)
+*/
+declare const GET_WEEKDAY: (timestamp: number) => number;
+/**
+* Get the day of year (1-366) from a timestamp
+*/
+declare const GET_DAY_OF_YEAR: (timestamp: number) => number;
+/**
+* Get the quarter (1-4) from a timestamp
+*/
+declare const GET_QUARTER: (timestamp: number) => number;
+/**
+* Get the absolute difference between two timestamps in seconds
+*/
+declare const DIFFERENCE_IN_SECONDS: (ts1: number, ts2: number) => number;
+/**
+* Get the absolute difference between two timestamps in minutes
+*/
+declare const DIFFERENCE_IN_MINUTES: (ts1: number, ts2: number) => number;
 /**
-* Default execution context with common Math functions and timestamp utilities
+* Get the absolute difference between two timestamps in hours
+*/
+declare const DIFFERENCE_IN_HOURS: (ts1: number, ts2: number) => number;
+/**
+* Get the absolute difference between two timestamps in days
+*/
+declare const DIFFERENCE_IN_DAYS: (ts1: number, ts2: number) => number;
+/**
+* Get the absolute difference between two timestamps in weeks
+*/
+declare const DIFFERENCE_IN_WEEKS: (ts1: number, ts2: number) => number;
+/**
+* Get the start of day (00:00:00.000) for a given timestamp
+*/
+declare const START_OF_DAY: (timestamp: number) => number;
+/**
+* Get the end of day (23:59:59.999) for a given timestamp
+*/
+declare const END_OF_DAY: (timestamp: number) => number;
+/**
+* Get the start of week (Sunday at 00:00:00.000) for a given timestamp
+*/
+declare const START_OF_WEEK: (timestamp: number) => number;
+/**
+* Get the start of month (1st day at 00:00:00.000) for a given timestamp
+*/
+declare const START_OF_MONTH: (timestamp: number) => number;
+/**
+* Get the end of month (last day at 23:59:59.999) for a given timestamp
+*/
+declare const END_OF_MONTH: (timestamp: number) => number;
+/**
+* Get the start of year (Jan 1st at 00:00:00.000) for a given timestamp
+*/
+declare const START_OF_YEAR: (timestamp: number) => number;
+/**
+* Get the end of year (Dec 31st at 23:59:59.999) for a given timestamp
+*/
+declare const END_OF_YEAR: (timestamp: number) => number;
+/**
+* Add days to a timestamp
+*/
+declare const ADD_DAYS: (timestamp: number, days: number) => number;
+/**
+* Add months to a timestamp (handles variable month lengths correctly)
+*/
+declare const ADD_MONTHS: (timestamp: number, months: number) => number;
+/**
+* Add years to a timestamp
+*/
+declare const ADD_YEARS: (timestamp: number, years: number) => number;
+/**
+* Check if ts1 is before ts2
+* Returns 1 if true, 0 if false
+*/
+declare const IS_BEFORE: (ts1: number, ts2: number) => number;
+/**
+* Check if ts1 is after ts2
+* Returns 1 if true, 0 if false
+*/
+declare const IS_AFTER: (ts1: number, ts2: number) => number;
+/**
+* Check if two timestamps are on the same calendar day
+* Returns 1 if true, 0 if false
+*/
+declare const IS_SAME_DAY: (ts1: number, ts2: number) => number;
+/**
+* Check if timestamp falls on a weekend (Saturday or Sunday)
+* Returns 1 if true, 0 if false
+*/
+declare const IS_WEEKEND: (timestamp: number) => number;
+/**
+* Check if timestamp is in a leap year
+* Returns 1 if true, 0 if false
+*/
+declare const IS_LEAP_YEAR: (timestamp: number) => number;
+/**
+* Get the start of quarter for a given timestamp
+*/
+declare const START_OF_QUARTER: (timestamp: number) => number;
+/**
+* Convert millisecond timestamp to Unix seconds
+*/
+declare const TO_UNIX_SECONDS: (timestamp: number) => number;
+/**
+* Convert Unix seconds to millisecond timestamp
+*/
+declare const FROM_UNIX_SECONDS: (seconds: number) => number;
+/**
+* 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.
 *
 * @example
 * // Use as-is
-* execute('abs(-5)', defaultContext)
+* execute('ABS(-5)', defaultContext)
 *
 * @example
 * // Spread into custom context
-* execute('now() + minutes(5)', {
+* execute('NOW() + FROM_MINUTES(5)', {
 *   ...defaultContext,
 *   variables: { customVar: 42 }
 * })
 *
 * @example
 * // Work with timestamps
-* const result = execute('now() + days(7)', defaultContext)
+* 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;
 /**
 * Executor - evaluates an AST with given context
+* Uses a tree-walk interpreter with O(n) execution time where n is the number of AST nodes
 */
 declare class Executor {
 	private context;
 	private variables;
+	private externalVariables;
 	constructor(context?: ExecutionContext);
 	/**
 	* Execute an AST node and return the result
@@ -372,15 +546,11 @@ declare class Executor {
 	private executeFunctionCall;
 	/**
 	* Execute a variable assignment
+	* External variables (from context) take precedence over script assignments
+	* This allows scripts to define defaults that can be overridden at runtime
 	*/
 	private executeAssignment;
 	/**
-	* Execute a nullish assignment (??=)
-	* Only assigns if the variable is undefined (not in variables map)
-	* Returns the existing value if defined, otherwise evaluates and assigns the value
-	*/
-	private executeNullishAssignment;
-	/**
 	* Execute a conditional expression (ternary operator)
 	* Returns consequent if condition !== 0, otherwise returns alternate
 	*/
@@ -392,10 +562,12 @@ declare class Executor {
 declare function execute(source: string, context?: ExecutionContext): RuntimeValue;
 /**
 * Lexer - converts source code into tokens
+* Implements a single-pass O(n) tokenization algorithm
 */
 declare class Lexer {
 	private source;
 	private position;
+	private length;
 	constructor(source: string);
 	/**
 	* Tokenize the entire source and return all tokens
@@ -419,23 +591,11 @@ declare class Lexer {
 	*/
 	private readIdentifier;
 	/**
-	* Get character at position
-	*/
-	private getCharAt;
-	/**
-	* Peek at the next character without consuming it
-	*/
-	private peek;
-	/**
-	* Peek ahead n positions without consuming
-	*/
-	private peekAhead;
-	/**
-	* Check if character is a digit
+	* Check if character is a digit (0-9)
 	*/
 	private isDigit;
 	/**
-	* Check if character is a letter
+	* Check if character is a letter (a-z, A-Z)
 	*/
 	private isLetter;
 	/**
@@ -444,25 +604,25 @@ declare class Lexer {
 	private isWhitespace;
 }
 /**
-* Optimize an AST using a theoretically optimal O(n) algorithm.
+* Optimize an AST using constant folding and expression simplification.
+*
+* This optimizer performs LOCAL, SAFE optimizations that preserve program semantics:
+* - Constant folding: Evaluates arithmetic with literal operands at compile-time
+* - Function argument pre-evaluation: Simplifies expressions passed to functions
+* - Conditional folding: Evaluates ternary with constant condition
 *
-* This optimizer implements a single-pass data-flow analysis algorithm that:
-* 1. Builds a dependency graph of all variables and expressions
-* 2. Performs constant propagation via forward data-flow analysis
-* 3. Eliminates dead code via backward reachability analysis
-* 4. Evaluates expressions in a single topological pass
+* Optimizations that are NOT performed (because they're unsafe with context variables):
+* - Variable propagation: Variables can be overridden by ExecutionContext
+* - Dead code elimination: Cannot determine if variables are "dead" without knowing context
+* - Cross-statement analysis: Each statement may affect external state
 *
 * Time complexity: O(n) where n is the number of AST nodes
-* Space complexity: O(n) for the dependency graph
+* Space complexity: O(d) where d is the max depth (recursion stack)
 *
 * Algorithm properties:
 * - Sound: Preserves program semantics exactly
-* - Complete: Finds all optimization opportunities
-* - Optimal: No redundant traversals or recomputation
-*
-* Based on classical compiler optimization theory:
-* - Cytron et al. "Efficiently Computing Static Single Assignment Form" (1991)
-* - Wegman & Zadeck "Constant Propagation with Conditional Branches" (1991)
+* - Safe: No assumptions about variable values or liveness
+* - Local: Only optimizes within individual expressions
 *
 * @param node - The AST node to optimize
 * @returns Optimized AST node
@@ -470,6 +630,7 @@ declare class Lexer {
 declare function optimize(node: ASTNode): ASTNode;
 /**
 * Parser using Pratt parsing (top-down operator precedence)
+* Implements an efficient O(n) parsing algorithm
 */
 declare class Parser {
 	private tokens;
@@ -477,11 +638,12 @@ declare class Parser {
 	constructor(tokens: Token[]);
 	/**
 	* Parse tokens into an AST
-	* Supports multiple statements separated by semicolons
+	* Supports multiple statements separated by semicolons or newlines
 	*/
 	parse(): ASTNode;
 	/**
 	* Parse an expression with Pratt parsing (precedence climbing)
+	* This is the core of the parser - handles infix operators with proper precedence
 	*/
 	private parseExpression;
 	/**
@@ -496,15 +658,15 @@ declare class Parser {
 	* Get unary operator precedence
 	* Returns 6 which is higher than add/sub (6) but lower than exponentiation (8)
 	* This means: -2^2 parses as -(2^2) = -4, not (-2)^2 = 4
-	* This matches the behavior of Python, Ruby, and most languages
+	* Matches the behavior of Python, Ruby, and most languages
 	*/
 	private getUnaryPrecedence;
 	/**
-	* Check if token is a binary operator
+	* Check if token is a binary operator (O(1) Set lookup)
 	*/
 	private isBinaryOperator;
 	/**
-	* Get current token
+	* Get current token without advancing
 	*/
 	private peek;
 	/**
@@ -514,9 +676,10 @@ declare class Parser {
 }
 /**
 * Parse source code string into AST
+* Convenience function that creates lexer and parser
 *
 * @param source - The source code to parse
 * @returns Parsed AST
 */
 declare function parseSource(source: string): ASTNode;
-export { parseSource, optimize, isUnaryOp, isProgram, isNumberLiteral, isNullishAssignment, isIdentifier, isFunctionCall, isConditionalExpression, isBinaryOp, isAssignment, generate, execute, defaultContext, exports_ast as ast, TokenType, Token, RuntimeValue, Parser, Lexer, Executor, ExecutionContext, CodeGenerator, ASTNode };
+export { parseSource, optimize, isUnaryOp, isProgram, isNumberLiteral, isIdentifier, isFunctionCall, isConditionalExpression, isBinaryOp, isAssignment, generate, execute, defaultContext, exports_date_utils as dateUtils, exports_ast as ast, UnaryOp, TokenType, Token, RuntimeValue, Program, Parser, Operator, NumberLiteral, Lexer, Identifier, FunctionCall, Executor, ExecutionContext, ConditionalExpression, CodeGenerator, BinaryOp, Assignment, ASTNode };