littlewing 2.1.0 → 2.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Gabriel Vaquer <brielov@icloud.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,400 @@
+# littlewing
+
+A minimal, high-performance multi-type expression language for JavaScript. Seven types, zero compromise, built for the browser.
+
+```typescript
+import { evaluate, defaultContext } from "littlewing";
+
+// Arithmetic
+evaluate("2 + 3 * 4"); // → 14
+
+// Strings
+evaluate('"hello" + " world"'); // → "hello world"
+
+// Variables and conditionals
+evaluate('price = 100; if price > 50 then "expensive" else "cheap"'); // → "expensive"
+
+// Date arithmetic
+evaluate("DIFFERENCE_IN_DAYS(TODAY(), DATE(2025, 12, 31))", defaultContext);
+
+// Array comprehensions
+evaluate("for x in 1..=5 then x ^ 2"); // → [1, 4, 9, 16, 25]
+
+// Reduce with accumulator
+evaluate("for x in [1, 2, 3, 4] into sum = 0 then sum + x"); // → 10
+
+// Pipe operator — chain values through functions
+evaluate("-5 |> ABS(?) |> STR(?)", defaultContext); // → "5"
+```
+
+## Features
+
+- **Seven types** — Numbers, strings, booleans, dates (`Temporal.PlainDate`), times (`Temporal.PlainTime`), datetimes (`Temporal.PlainDateTime`), and homogeneous arrays
+- **No implicit coercion** — Explicit type conversion via `STR()`, `NUM()`, etc.
+- **Strict boolean logic** — `!`, `&&`, `||`, and `if` conditions require booleans
+- **Control flow** — `if/then/else` expressions and `for/in/then` comprehensions with optional `when` guard and `into` accumulator
+- **Bracket indexing** — `arr[0]`, `str[-1]`, with chaining (`matrix[0][1]`)
+- **Pipe operator** — `x |> FUN(?) |> OTHER(?, 1)` chains values through function calls
+- **Range expressions** — `1..5` (exclusive), `1..=5` (inclusive)
+- **Deep equality** — `[1, 2] == [1, 2]` → `true`; cross-type `==` → `false`
+- **85 built-in functions** — Math, string, array, date, time, and datetime operations
+- **O(n) performance** — Linear time parsing and execution
+- **Safe evaluation** — Tree-walk interpreter, no code generation
+- **Extensible** — Add custom functions and variables via context
+- **Type-safe** — Full TypeScript support with strict types
+- **Zero runtime dependencies** — Requires global `Temporal` API (native or polyfill)
+
+## Installation
+
+```bash
+npm install littlewing
+```
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import { evaluate } from "littlewing";
+
+// Arithmetic
+evaluate("2 + 3 * 4"); // → 14
+evaluate("2 ^ 10"); // → 1024
+
+// Strings
+evaluate('"hello" + " world"'); // → "hello world"
+
+// Booleans (comparisons return boolean, not 1/0)
+evaluate("5 > 3"); // → true
+evaluate("!(5 > 10)"); // → true
+
+// Variables
+evaluate("x = 10; y = 20; x + y"); // → 30
+
+// Conditionals (condition must be boolean, else is required)
+evaluate('age = 21; if age >= 18 then "adult" else "minor"'); // → "adult"
+
+// Arrays and indexing
+evaluate("[10, 20, 30][-1]"); // → 30
+evaluate("[1, 2] + [3, 4]"); // → [1, 2, 3, 4]
+
+// Ranges
+evaluate("1..=5"); // → [1, 2, 3, 4, 5]
+
+// For comprehensions (map, filter, reduce)
+evaluate("for x in 1..=5 then x * 2"); // → [2, 4, 6, 8, 10]
+evaluate("for x in 1..=10 when x % 2 == 0 then x"); // → [2, 4, 6, 8, 10]
+evaluate("for x in [1, 2, 3] into sum = 0 then sum + x"); // → 6
+
+// Pipe operator
+evaluate("-42 |> ABS(?)", defaultContext); // → 42
+evaluate("150 |> CLAMP(?, 0, 100)", defaultContext); // → 100
+evaluate("-3 |> ABS(?) |> STR(?)", defaultContext); // → "3"
+```
+
+### With Built-in Functions
+
+```typescript
+import { evaluate, defaultContext } from "littlewing";
+
+// Math
+evaluate("ABS(-42)", defaultContext); // → 42
+evaluate("ROUND(3.7)", defaultContext); // → 4
+
+// Type conversion
+evaluate('NUM("42")', defaultContext); // → 42
+evaluate("STR(42)", defaultContext); // → "42"
+
+// String functions
+evaluate('STR_UPPER("hello")', defaultContext); // → "HELLO"
+evaluate('STR_SPLIT("a,b,c", ",")', defaultContext); // → ["a", "b", "c"]
+
+// Array functions
+evaluate("ARR_SORT([3, 1, 2])", defaultContext); // → [1, 2, 3]
+evaluate("ARR_SUM([10, 20, 30])", defaultContext); // → 60
+evaluate('ARR_JOIN(["a", "b", "c"], "-")', defaultContext); // → "a-b-c"
+
+// Date functions
+evaluate("TODAY()", defaultContext); // → Temporal.PlainDate
+evaluate("ADD_DAYS(TODAY(), 7)", defaultContext); // → 7 days from now
+evaluate("IS_WEEKEND(TODAY())", defaultContext); // → true or false
+
+// Time functions
+evaluate("TIME(14, 30, 0)", defaultContext); // → Temporal.PlainTime
+evaluate("ADD_HOURS(TIME(10, 0, 0), 3)", defaultContext); // → 13:00:00
+
+// DateTime functions
+evaluate("NOW()", defaultContext); // → Temporal.PlainDateTime
+evaluate("TO_DATE(NOW())", defaultContext); // → today's date
+```
+
+### Custom Functions and Variables
+
+```typescript
+import { evaluate, assertNumber, assertString } from "littlewing";
+
+const context = {
+	functions: {
+		FAHRENHEIT: (celsius) => {
+			assertNumber(celsius, "FAHRENHEIT");
+			return (celsius * 9) / 5 + 32;
+		},
+		DISCOUNT: (price, percent) => {
+			assertNumber(price, "DISCOUNT", "price");
+			assertNumber(percent, "DISCOUNT", "percent");
+			return price * (1 - percent / 100);
+		},
+	},
+	variables: {
+		pi: 3.14159,
+		taxRate: 0.08,
+	},
+};
+
+evaluate("FAHRENHEIT(20)", context); // → 68
+evaluate("DISCOUNT(100, 15)", context); // → 85
+evaluate("100 * (1 + taxRate)", context); // → 108
+```
+
+The assertion helpers (`assertNumber`, `assertString`, `assertBoolean`, `assertArray`, `assertDate`, `assertTime`, `assertDateTime`, `assertDateOrDateTime`, `assertTimeOrDateTime`) are the same ones used by the built-in standard library. They throw `TypeError` with consistent messages on type mismatch.
+
+### External Variables Override Script Defaults
+
+```typescript
+const formula = "multiplier = 2; value = 100; value * multiplier";
+
+evaluate(formula); // → 200
+evaluate(formula, { variables: { multiplier: 3 } }); // → 300
+evaluate(formula, { variables: { value: 50 } }); // → 100
+```
+
+## Language Reference
+
+For complete language documentation including all operators, control flow, and built-in functions, see [LANGUAGE.md](./LANGUAGE.md).
+
+## API
+
+### Main Functions
+
+#### `evaluate(input: string | ASTNode, context?: ExecutionContext): RuntimeValue`
+
+Evaluate an expression or AST and return the result.
+
+```typescript
+evaluate("2 + 2"); // → 4
+
+// Evaluate pre-parsed AST (parse once, evaluate many)
+const ast = parse("price * quantity");
+evaluate(ast, { variables: { price: 10, quantity: 5 } }); // → 50
+evaluate(ast, { variables: { price: 20, quantity: 3 } }); // → 60
+```
+
+#### `evaluateScope(input: string | ASTNode, context?: ExecutionContext): Record<string, RuntimeValue>`
+
+Evaluate and return all assigned variables as a record.
+
+```typescript
+evaluateScope("x = 10; y = x * 2"); // → { x: 10, y: 20 }
+```
+
+#### `parse(source: string): ASTNode`
+
+Parse source into an Abstract Syntax Tree without evaluating.
+
+```typescript
+const ast = parse("2 + 3 * 4");
+evaluate(ast); // → 14
+```
+
+#### `generate(node: ASTNode): string`
+
+Convert AST back to source code (preserves comments).
+
+```typescript
+generate(parse("2 + 3 * 4")); // → "2 + 3 * 4"
+```
+
+#### `optimize(node: ASTNode, externalVariables?: ReadonlySet<string>): ASTNode`
+
+Optimize an AST with constant folding, constant propagation, and dead code elimination.
+
+```typescript
+const ast = parse("2 + 3 * 4");
+optimize(ast); // → NumberLiteral(14)
+
+// With external variables: propagates internal constants while preserving external ones
+const ast2 = parse("x = 5; y = 10; x + y");
+optimize(ast2, new Set(["x"])); // Propagates y=10, keeps x as external
+```
+
+#### `extractInputVariables(ast: ASTNode): string[]`
+
+Extract variable names assigned to constant values (useful for building UIs with input controls).
+
+```typescript
+const ast = parse("price = 100; tax = price * 0.08");
+extractInputVariables(ast); // → ["price"]
+```
+
+### AST Visitor Pattern
+
+#### `visit<T>(node: ASTNode, visitor: Visitor<T>): T`
+
+Exhaustively visit every node in an AST. All 16 node types must be handled.
+
+```typescript
+import { visit, parse } from "littlewing";
+
+const count = visit(parse("2 + 3"), {
+	Program: (n, recurse) => n.statements.reduce((s, stmt) => s + recurse(stmt), 0),
+	NumberLiteral: () => 1,
+	StringLiteral: () => 1,
+	BooleanLiteral: () => 1,
+	ArrayLiteral: (n, recurse) => 1 + n.elements.reduce((s, el) => s + recurse(el), 0),
+	Identifier: () => 1,
+	BinaryOp: (n, recurse) => 1 + recurse(n.left) + recurse(n.right),
+	UnaryOp: (n, recurse) => 1 + recurse(n.argument),
+	Assignment: (n, recurse) => 1 + recurse(n.value),
+	FunctionCall: (n, recurse) => 1 + n.args.reduce((s, arg) => s + recurse(arg), 0),
+	IfExpression: (n, recurse) =>
+		1 + recurse(n.condition) + recurse(n.consequent) + recurse(n.alternate),
+	ForExpression: (n, recurse) =>
+		1 + recurse(n.iterable) + (n.guard ? recurse(n.guard) : 0) + recurse(n.body),
+	IndexAccess: (n, recurse) => 1 + recurse(n.object) + recurse(n.index),
+	RangeExpression: (n, recurse) => 1 + recurse(n.start) + recurse(n.end),
+	PipeExpression: (n, recurse) =>
+		1 + recurse(n.value) + n.args.reduce((s, arg) => s + recurse(arg), 0),
+	Placeholder: () => 1,
+});
+```
+
+#### `visitPartial<T>(node, visitor, defaultHandler): T`
+
+Visit only specific node types with a fallback for unhandled types.
+
+### AST Builder Functions
+
+The `ast` namespace provides builder functions for constructing AST nodes:
+
+```typescript
+import { ast, generate } from "littlewing";
+
+generate(ast.add(ast.number(2), ast.number(3))); // → "2 + 3"
+generate(ast.ifExpr(ast.boolean(true), ast.number(1), ast.number(0))); // → "if true then 1 else 0"
+generate(
+	ast.forExpr(
+		"x",
+		ast.identifier("arr"),
+		null,
+		null,
+		ast.multiply(ast.identifier("x"), ast.number(2)),
+	),
+);
+// → "for x in arr then x * 2"
+```
+
+**Available builders:**
+
+- Core: `program()`, `number()`, `string()`, `boolean()`, `array()`, `identifier()`, `binaryOp()`, `unaryOp()`, `functionCall()`, `assign()`, `ifExpr()`, `forExpr()`, `indexAccess()`, `rangeExpr()`, `pipeExpr()`, `placeholder()`
+- Arithmetic: `add()`, `subtract()`, `multiply()`, `divide()`, `modulo()`, `exponentiate()`, `negate()`
+- Comparison: `equals()`, `notEquals()`, `lessThan()`, `greaterThan()`, `lessEqual()`, `greaterEqual()`
+- Logical: `logicalAnd()`, `logicalOr()`, `logicalNot()`
+
+### ExecutionContext
+
+```typescript
+interface ExecutionContext {
+	functions?: Record<string, (...args: RuntimeValue[]) => RuntimeValue>;
+	variables?: Record<string, RuntimeValue>;
+}
+
+type RuntimeValue =
+	| number
+	| string
+	| boolean
+	| Temporal.PlainDate
+	| Temporal.PlainTime
+	| Temporal.PlainDateTime
+	| readonly RuntimeValue[];
+```
+
+### Default Context Functions
+
+The `defaultContext` includes **82 built-in functions**:
+
+**Core (8):** `STR`, `NUM`, `TYPE`, `LEN`, `SLICE`, `CONTAINS`, `REVERSE`, `INDEX_OF`
+
+**Math (14):** `ABS`, `CEIL`, `FLOOR`, `ROUND`, `SQRT`, `MIN`, `MAX`, `CLAMP`, `SIN`, `COS`, `TAN`, `LOG`, `LOG10`, `EXP`
+
+**String (8):** `STR_UPPER`, `STR_LOWER`, `STR_TRIM`, `STR_SPLIT`, `STR_REPLACE`, `STR_STARTS_WITH`, `STR_ENDS_WITH`, `STR_REPEAT`
+
+**Array (7):** `ARR_SORT`, `ARR_UNIQUE`, `ARR_FLAT`, `ARR_JOIN`, `ARR_SUM`, `ARR_MIN`, `ARR_MAX`
+
+**Date (25):** `TODAY`, `DATE`, `YEAR`, `MONTH`, `DAY`, `WEEKDAY`, `DAY_OF_YEAR`, `QUARTER`, `ADD_DAYS`, `ADD_MONTHS`, `ADD_YEARS`, `DIFFERENCE_IN_DAYS`, `DIFFERENCE_IN_WEEKS`, `DIFFERENCE_IN_MONTHS`, `DIFFERENCE_IN_YEARS`, `START_OF_MONTH`, `END_OF_MONTH`, `START_OF_YEAR`, `END_OF_YEAR`, `START_OF_WEEK`, `START_OF_QUARTER`, `IS_SAME_DAY`, `IS_WEEKEND`, `IS_LEAP_YEAR`, `AGE`
+
+**Time (13):** `TIME`, `NOW_TIME`, `HOUR`, `MINUTE`, `SECOND`, `MILLISECOND`, `ADD_HOURS`, `ADD_MINUTES`, `ADD_SECONDS`, `DIFFERENCE_IN_HOURS`, `DIFFERENCE_IN_MINUTES`, `DIFFERENCE_IN_SECONDS`, `IS_SAME_TIME`
+
+**DateTime (7):** `DATETIME`, `NOW`, `TO_DATE`, `TO_TIME`, `COMBINE`, `START_OF_DAY`, `END_OF_DAY`
+
+**Temporal type support:** Date functions accept both `PlainDate` and `PlainDateTime` (preserving type). Time functions accept both `PlainTime` and `PlainDateTime`. Difference functions require both arguments to be the same type.
+
+## Performance Optimization
+
+### Parse Once, Evaluate Many
+
+For expressions executed multiple times, parse once and reuse the AST:
+
+```typescript
+import { evaluate, parse } from "littlewing";
+
+const formula = parse("price * quantity * (1 - discount)");
+
+evaluate(formula, { variables: { price: 10, quantity: 5, discount: 0.1 } }); // → 45
+evaluate(formula, { variables: { price: 20, quantity: 3, discount: 0.15 } }); // → 51
+```
+
+## Use Cases
+
+- **User-defined formulas** — Let users write safe expressions
+- **Business rules** — Express logic without `eval()` or `new Function()`
+- **Financial calculators** — Compound interest, loan payments, etc.
+- **Date arithmetic** — Deadlines, scheduling, date calculations
+- **Data transformations** — Map, filter, and reduce arrays
+- **Configuration expressions** — Dynamic config values
+
+## Why Littlewing?
+
+### The Problem
+
+Your app needs to evaluate user-provided formulas or dynamic expressions. Using `eval()` is a security risk. Writing a parser is complex. Embedding a full scripting language is overkill.
+
+### The Solution
+
+Littlewing provides just enough: expressions with multiple types, variables, and functions. It's safe (no code execution), fast (linear time), and type-safe (no implicit coercion).
+
+### What Makes It Different
+
+1. **Multi-type with strict semantics** — Seven types, no implicit coercion, no surprises
+2. **External variables override** — Scripts have defaults, runtime provides overrides
+3. **Full Temporal support** — First-class `PlainDate`, `PlainTime`, and `PlainDateTime`
+4. **Deep equality** — Arrays and dates compare by value
+5. **O(n) everything** — Predictable performance at any scale
+
+## Development
+
+```bash
+bun install     # Install dependencies
+bun test        # Run tests
+bun run build   # Build
+bun run --cwd packages/littlewing dev   # Watch mode
+```
+
+For detailed development docs, see [CLAUDE.md](./CLAUDE.md).
+
+## License
+
+MIT
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md).

package/dist/index.d.ts

@@ -320,6 +320,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;
@@ -357,31 +374,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 +414,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 +431,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 +475,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 +562,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 +627,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 +642,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 +662,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 +680,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.
@@ -825,4 +834,4 @@ declare function visit<T>(node: ASTNode, visitor: Visitor<T>): T;
 * @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 { visitPartial, 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, 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, ParseError, Operator, NumberLiteral, NodeKind, IndexAccess, IfExpression, Identifier2 as Identifier, FunctionCall, ForExpression, ExecutionContext, BooleanLiteral, BinaryOp, Assignment, ArrayLiteral, ASTNodeBase, ASTNode };

package/dist/index.js

@@ -413,6 +413,31 @@ function containsExternalReference(node, boundVars) {
 function containsVariableReference(node) {
   return containsExternalReference(node, new Set);
 }
+// src/errors.ts
+class ParseError extends Error {
+  start;
+  end;
+  name = "ParseError";
+  constructor(message, start, end) {
+    super(message);
+    this.start = start;
+    this.end = end;
+  }
+}
+function toLineColumn(source, offset) {
+  let line = 1;
+  let column = 1;
+  const clamped = Math.min(offset, source.length);
+  for (let i = 0;i < clamped; i++) {
+    if (source.charCodeAt(i) === 10) {
+      line++;
+      column = 1;
+    } else {
+      column++;
+    }
+  }
+  return { line, column };
+}
 // src/lexer.ts
 var KEYWORDS = new Map([
   ["if", 28 /* If */],
@@ -594,7 +619,7 @@ function nextToken(cursor) {
         }
         return [18 /* DotDot */, start, cursor.pos];
       }
-      throw new Error(`Unexpected character '${String.fromCharCode(ch)}' at position ${start}`);
+      throw new ParseError(`Unexpected character '${String.fromCharCode(ch)}'`, start, cursor.pos);
     case 44:
       advance(cursor);
       return [25 /* Comma */, start, cursor.pos];
@@ -607,7 +632,7 @@ function nextToken(cursor) {
         advance(cursor);
         return [16 /* And */, start, cursor.pos];
       }
-      throw new Error(`Unexpected character '${String.fromCharCode(ch)}' at position ${start}`);
+      throw new ParseError(`Unexpected character '${String.fromCharCode(ch)}'`, start, cursor.pos);
     case 124:
       advance(cursor);
       if (peek(cursor) === 124) {
@@ -618,12 +643,13 @@ function nextToken(cursor) {
         advance(cursor);
         return [26 /* Pipe */, start, cursor.pos];
       }
-      throw new Error(`Unexpected character '${String.fromCharCode(ch)}' at position ${start}`);
+      throw new ParseError(`Unexpected character '${String.fromCharCode(ch)}'`, start, cursor.pos);
     case 63:
       advance(cursor);
       return [27 /* Question */, start, cursor.pos];
     default:
-      throw new Error(`Unexpected character '${String.fromCharCode(ch)}' at position ${start}`);
+      advance(cursor);
+      throw new ParseError(`Unexpected character '${String.fromCharCode(ch)}'`, start, cursor.pos);
   }
 }
 function lexString(cursor) {
@@ -640,7 +666,7 @@ function lexString(cursor) {
       cursor.pos++;
     }
   }
-  throw new Error(`Unterminated string at position ${start}`);
+  throw new ParseError("Unterminated string", start, cursor.pos);
 }
 function lexNumber(cursor) {
   const start = cursor.pos;
@@ -1230,13 +1256,13 @@ function parse(source) {
     statements.push(parseExpression(state, 0));
   }
   if (statements.length === 0) {
-    throw new Error("Empty program");
+    throw new ParseError("Empty program", 0, 0);
   }
   const annotated = attachComments(source, statements, statementOffsets, cursor.comments);
   if (annotated.statements.length === 1 && !annotated.programTrailing) {
     const stmt = annotated.statements[0];
     if (stmt === undefined) {
-      throw new Error("Unexpected empty statements array");
+      throw new ParseError("Unexpected empty statements array", 0, 0);
     }
     return stmt;
   }
@@ -1346,7 +1372,7 @@ function parseExpression(state, minPrecedence) {
       advance2(state);
       const index = parseExpression(state, 0);
       if (peekKind(state) !== 23 /* RBracket */) {
-        throw new Error("Expected closing bracket");
+        throw new ParseError("Expected closing bracket", state.currentToken[1], state.currentToken[2]);
       }
       advance2(state);
       left = indexAccess(left, index);
@@ -1377,7 +1403,7 @@ function parsePrefix(state) {
     advance2(state);
     const expr = parseExpression(state, 0);
     if (peekKind(state) !== 21 /* RParen */) {
-      throw new Error("Expected closing parenthesis");
+      throw new ParseError("Expected closing parenthesis", state.currentToken[1], state.currentToken[2]);
     }
     advance2(state);
     return expr;
@@ -1393,7 +1419,7 @@ function parsePrefix(state) {
       }
     }
     if (peekKind(state) !== 23 /* RBracket */) {
-      throw new Error("Expected closing bracket");
+      throw new ParseError("Expected closing bracket", state.currentToken[1], state.currentToken[2]);
     }
     advance2(state);
     return array(elements);
@@ -1402,12 +1428,12 @@ function parsePrefix(state) {
     advance2(state);
     const condition = parseExpression(state, 0);
     if (peekKind(state) !== 29 /* Then */) {
-      throw new Error('Expected "then" in if expression');
+      throw new ParseError('Expected "then" in if expression', state.currentToken[1], state.currentToken[2]);
     }
     advance2(state);
     const consequent = parseExpression(state, 0);
     if (peekKind(state) !== 30 /* Else */) {
-      throw new Error('Expected "else" in if expression');
+      throw new ParseError('Expected "else" in if expression', state.currentToken[1], state.currentToken[2]);
     }
     advance2(state);
     const alternate = parseExpression(state, 0);
@@ -1416,12 +1442,12 @@ function parsePrefix(state) {
   if (tokenKind === 31 /* For */) {
     advance2(state);
     if (peekKind(state) !== 1 /* Identifier */) {
-      throw new Error('Expected identifier after "for"');
+      throw new ParseError('Expected identifier after "for"', state.currentToken[1], state.currentToken[2]);
     }
     const variableName = readText(state.cursor, state.currentToken);
     advance2(state);
     if (peekKind(state) !== 32 /* In */) {
-      throw new Error('Expected "in" in for expression');
+      throw new ParseError('Expected "in" in for expression', state.currentToken[1], state.currentToken[2]);
     }
     advance2(state);
     const iterable = parseExpression(state, 0);
@@ -1434,19 +1460,19 @@ function parsePrefix(state) {
     if (peekKind(state) === 34 /* Into */) {
       advance2(state);
       if (peekKind(state) !== 1 /* Identifier */) {
-        throw new Error('Expected identifier after "into"');
+        throw new ParseError('Expected identifier after "into"', state.currentToken[1], state.currentToken[2]);
       }
       const accName = readText(state.cursor, state.currentToken);
       advance2(state);
       if (peekKind(state) !== 24 /* Eq */) {
-        throw new Error('Expected "=" after accumulator name');
+        throw new ParseError('Expected "=" after accumulator name', state.currentToken[1], state.currentToken[2]);
       }
       advance2(state);
       const initial = parseExpression(state, 0);
       accumulator = { name: accName, initial };
     }
     if (peekKind(state) !== 29 /* Then */) {
-      throw new Error('Expected "then" in for expression');
+      throw new ParseError('Expected "then" in for expression', state.currentToken[1], state.currentToken[2]);
     }
     advance2(state);
     const body = parseExpression(state, 0);
@@ -1478,7 +1504,7 @@ function parsePrefix(state) {
       advance2(state);
       const args = parseFunctionArguments(state);
       if (peekKind(state) !== 21 /* RParen */) {
-        throw new Error("Expected closing parenthesis");
+        throw new ParseError("Expected closing parenthesis", state.currentToken[1], state.currentToken[2]);
       }
       advance2(state);
       return functionCall(name, args);
@@ -1487,13 +1513,13 @@ function parsePrefix(state) {
   }
   const token = state.currentToken;
   const tokenText = readText(state.cursor, token);
-  throw new Error(`Unexpected token: ${tokenText}`);
+  throw new ParseError(`Unexpected token: ${tokenText}`, token[1], token[2]);
 }
 function parseInfix(state, left, precedence) {
   const tokenKind = peekKind(state);
   if (tokenKind === 24 /* Eq */) {
     if (left.kind !== 2 /* Identifier */) {
-      throw new Error("Invalid assignment target");
+      throw new ParseError("Invalid assignment target", state.currentToken[1], state.currentToken[2]);
     }
     const identName = left.name;
     advance2(state);
@@ -1509,17 +1535,17 @@ function parseInfix(state, left, precedence) {
   if (tokenKind === 26 /* Pipe */) {
     advance2(state);
     if (peekKind(state) !== 1 /* Identifier */) {
-      throw new Error("Expected function name after |>");
+      throw new ParseError("Expected function name after |>", state.currentToken[1], state.currentToken[2]);
     }
     const name = readText(state.cursor, state.currentToken);
     advance2(state);
     if (peekKind(state) !== 20 /* LParen */) {
-      throw new Error("Expected ( after function name in pipe expression");
+      throw new ParseError("Expected ( after function name in pipe expression", state.currentToken[1], state.currentToken[2]);
     }
     advance2(state);
     const args = parsePipeArguments(state);
     if (peekKind(state) !== 21 /* RParen */) {
-      throw new Error("Expected closing parenthesis");
+      throw new ParseError("Expected closing parenthesis", state.currentToken[1], state.currentToken[2]);
     }
     advance2(state);
     let hasPlaceholder = false;
@@ -1530,7 +1556,7 @@ function parseInfix(state, left, precedence) {
       }
     }
     if (!hasPlaceholder) {
-      throw new Error("Pipe expression requires at least one ? placeholder");
+      throw new ParseError("Pipe expression requires at least one ? placeholder", state.currentToken[1], state.currentToken[2]);
     }
     return pipeExpr(left, name, args);
   }
@@ -1541,7 +1567,7 @@ function parseInfix(state, left, precedence) {
     const right = parseExpression(state, isRightAssociative ? precedence : precedence + 1);
     return binaryOp(left, operator, right);
   }
-  throw new Error("Unexpected token in infix position");
+  throw new ParseError("Unexpected token in infix position", state.currentToken[1], state.currentToken[2]);
 }
 function parseFunctionArguments(state) {
   if (peekKind(state) === 21 /* RParen */) {
@@ -2296,52 +2322,11 @@ __export(exports_array, {
   ARR_UNIQUE: () => ARR_UNIQUE,
   ARR_SUM: () => ARR_SUM,
   ARR_SORT: () => ARR_SORT,
-  ARR_SLICE: () => ARR_SLICE,
-  ARR_REVERSE: () => ARR_REVERSE,
-  ARR_PUSH: () => ARR_PUSH,
   ARR_MIN: () => ARR_MIN,
   ARR_MAX: () => ARR_MAX,
-  ARR_LEN: () => ARR_LEN,
   ARR_JOIN: () => ARR_JOIN,
-  ARR_FLAT: () => ARR_FLAT,
-  ARR_CONTAINS: () => ARR_CONTAINS
+  ARR_FLAT: () => ARR_FLAT
 });
-var ARR_LEN = (a) => {
-  assertArray(a, "ARR_LEN");
-  return a.length;
-};
-var ARR_PUSH = (a, value) => {
-  assertArray(a, "ARR_PUSH");
-  if (a.length > 0) {
-    const elemType = typeOf(a[0]);
-    const valType = typeOf(value);
-    if (elemType !== valType) {
-      throw new TypeError(`ARR_PUSH: cannot push ${valType} into array<${elemType}>`);
-    }
-  }
-  return [...a, value];
-};
-var ARR_SLICE = (a, start, end) => {
-  assertArray(a, "ARR_SLICE");
-  assertNumber(start, "ARR_SLICE", "start");
-  if (end !== undefined) {
-    assertNumber(end, "ARR_SLICE", "end");
-    return a.slice(start, end);
-  }
-  return a.slice(start);
-};
-var ARR_CONTAINS = (a, value) => {
-  assertArray(a, "ARR_CONTAINS");
-  for (const elem of a) {
-    if (deepEquals(elem, value))
-      return true;
-  }
-  return false;
-};
-var ARR_REVERSE = (a) => {
-  assertArray(a, "ARR_REVERSE");
-  return [...a].reverse();
-};
 var ARR_SORT = (a) => {
   assertArray(a, "ARR_SORT");
   if (a.length <= 1)
@@ -2473,7 +2458,12 @@ var exports_core = {};
 __export(exports_core, {
   TYPE: () => TYPE,
   STR: () => STR,
-  NUM: () => NUM
+  SLICE: () => SLICE,
+  REVERSE: () => REVERSE,
+  NUM: () => NUM,
+  LEN: () => LEN,
+  INDEX_OF: () => INDEX_OF,
+  CONTAINS: () => CONTAINS
 });
 var STR = (v) => {
   if (typeof v === "string")
@@ -2504,31 +2494,81 @@ var NUM = (v) => {
 var TYPE = (v) => {
   return typeOf(v);
 };
+function assertStringOrArray(v, context) {
+  if (typeof v !== "string" && !Array.isArray(v)) {
+    throw new TypeError(`${context} expected string or array, got ${typeOf(v)}`);
+  }
+}
+var LEN = (v) => {
+  assertStringOrArray(v, "LEN");
+  return v.length;
+};
+var SLICE = (v, start, end) => {
+  assertStringOrArray(v, "SLICE");
+  assertNumber(start, "SLICE", "start");
+  if (end !== undefined) {
+    assertNumber(end, "SLICE", "end");
+    return v.slice(start, end);
+  }
+  return v.slice(start);
+};
+var CONTAINS = (v, search) => {
+  assertStringOrArray(v, "CONTAINS");
+  if (typeof v === "string") {
+    assertString(search, "CONTAINS (search)");
+    return v.includes(search);
+  }
+  for (const elem of v) {
+    if (deepEquals(elem, search))
+      return true;
+  }
+  return false;
+};
+var REVERSE = (v) => {
+  assertStringOrArray(v, "REVERSE");
+  if (typeof v === "string") {
+    return Array.from(v).reverse().join("");
+  }
+  return [...v].reverse();
+};
+var INDEX_OF = (v, search) => {
+  assertStringOrArray(v, "INDEX_OF");
+  if (typeof v === "string") {
+    assertString(search, "INDEX_OF (search)");
+    return v.indexOf(search);
+  }
+  for (let i = 0;i < v.length; i++) {
+    if (deepEquals(v[i], search))
+      return i;
+  }
+  return -1;
+};
 
 // src/stdlib/datetime.ts
 var exports_datetime = {};
 __export(exports_datetime, {
+  YEAR: () => YEAR,
+  WEEKDAY: () => WEEKDAY,
   TODAY: () => TODAY,
   START_OF_YEAR: () => START_OF_YEAR,
   START_OF_WEEK: () => START_OF_WEEK,
   START_OF_QUARTER: () => START_OF_QUARTER,
   START_OF_MONTH: () => START_OF_MONTH,
+  QUARTER: () => QUARTER,
+  MONTH: () => MONTH,
   IS_WEEKEND: () => IS_WEEKEND,
   IS_SAME_DAY: () => IS_SAME_DAY,
   IS_LEAP_YEAR: () => IS_LEAP_YEAR,
-  GET_YEAR: () => GET_YEAR,
-  GET_WEEKDAY: () => GET_WEEKDAY,
-  GET_QUARTER: () => GET_QUARTER,
-  GET_MONTH: () => GET_MONTH,
-  GET_DAY_OF_YEAR: () => GET_DAY_OF_YEAR,
-  GET_DAY: () => GET_DAY,
   END_OF_YEAR: () => END_OF_YEAR,
   END_OF_MONTH: () => END_OF_MONTH,
   DIFFERENCE_IN_YEARS: () => DIFFERENCE_IN_YEARS,
   DIFFERENCE_IN_WEEKS: () => DIFFERENCE_IN_WEEKS,
   DIFFERENCE_IN_MONTHS: () => DIFFERENCE_IN_MONTHS,
   DIFFERENCE_IN_DAYS: () => DIFFERENCE_IN_DAYS,
+  DAY_OF_YEAR: () => DAY_OF_YEAR,
+  DAY: () => DAY,
   DATE: () => DATE,
+  AGE: () => AGE,
   ADD_YEARS: () => ADD_YEARS,
   ADD_MONTHS: () => ADD_MONTHS,
   ADD_DAYS: () => ADD_DAYS
@@ -2540,28 +2580,28 @@ var DATE = (year, month, day) => {
   assertNumber(day, "DATE", "day");
   return new Temporal.PlainDate(year, month, day);
 };
-var GET_YEAR = (date) => {
-  assertDateOrDateTime(date, "GET_YEAR");
+var YEAR = (date) => {
+  assertDateOrDateTime(date, "YEAR");
   return date.year;
 };
-var GET_MONTH = (date) => {
-  assertDateOrDateTime(date, "GET_MONTH");
+var MONTH = (date) => {
+  assertDateOrDateTime(date, "MONTH");
   return date.month;
 };
-var GET_DAY = (date) => {
-  assertDateOrDateTime(date, "GET_DAY");
+var DAY = (date) => {
+  assertDateOrDateTime(date, "DAY");
   return date.day;
 };
-var GET_WEEKDAY = (date) => {
-  assertDateOrDateTime(date, "GET_WEEKDAY");
+var WEEKDAY = (date) => {
+  assertDateOrDateTime(date, "WEEKDAY");
   return date.dayOfWeek;
 };
-var GET_DAY_OF_YEAR = (date) => {
-  assertDateOrDateTime(date, "GET_DAY_OF_YEAR");
+var DAY_OF_YEAR = (date) => {
+  assertDateOrDateTime(date, "DAY_OF_YEAR");
   return date.dayOfYear;
 };
-var GET_QUARTER = (date) => {
-  assertDateOrDateTime(date, "GET_QUARTER");
+var QUARTER = (date) => {
+  assertDateOrDateTime(date, "QUARTER");
   return Math.ceil(date.month / 3);
 };
 var ADD_DAYS = (date, days) => {
@@ -2676,6 +2716,22 @@ var IS_LEAP_YEAR = (date) => {
   assertDateOrDateTime(date, "IS_LEAP_YEAR");
   return date.inLeapYear;
 };
+var AGE = (birthDate, ...rest) => {
+  assertDateOrDateTime(birthDate, "AGE");
+  const birth = birthDate instanceof Temporal.PlainDateTime ? birthDate.toPlainDate() : birthDate;
+  let reference;
+  if (rest.length > 0) {
+    const ref = rest[0];
+    assertDateOrDateTime(ref, "AGE");
+    reference = ref instanceof Temporal.PlainDateTime ? ref.toPlainDate() : ref;
+  } else {
+    reference = Temporal.Now.plainDateISO();
+  }
+  if (Temporal.PlainDate.compare(birth, reference) > 0) {
+    throw new RangeError("AGE requires birth date to be on or before reference date");
+  }
+  return birth.until(reference, { largestUnit: "year" }).years;
+};
 
 // src/stdlib/datetimefull.ts
 var exports_datetimefull = {};
@@ -2822,19 +2878,11 @@ __export(exports_string, {
   STR_TRIM: () => STR_TRIM,
   STR_STARTS_WITH: () => STR_STARTS_WITH,
   STR_SPLIT: () => STR_SPLIT,
-  STR_SLICE: () => STR_SLICE,
   STR_REPLACE: () => STR_REPLACE,
   STR_REPEAT: () => STR_REPEAT,
   STR_LOWER: () => STR_LOWER,
-  STR_LEN: () => STR_LEN,
-  STR_INDEX_OF: () => STR_INDEX_OF,
-  STR_ENDS_WITH: () => STR_ENDS_WITH,
-  STR_CONTAINS: () => STR_CONTAINS
+  STR_ENDS_WITH: () => STR_ENDS_WITH
 });
-var STR_LEN = (s) => {
-  assertString(s, "STR_LEN");
-  return s.length;
-};
 var STR_UPPER = (s) => {
   assertString(s, "STR_UPPER");
   return s.toUpperCase();
@@ -2847,25 +2895,6 @@ var STR_TRIM = (s) => {
   assertString(s, "STR_TRIM");
   return s.trim();
 };
-var STR_SLICE = (s, start, end) => {
-  assertString(s, "STR_SLICE");
-  assertNumber(start, "STR_SLICE", "start");
-  if (end !== undefined) {
-    assertNumber(end, "STR_SLICE", "end");
-    return s.slice(start, end);
-  }
-  return s.slice(start);
-};
-var STR_CONTAINS = (s, search) => {
-  assertString(s, "STR_CONTAINS");
-  assertString(search, "STR_CONTAINS");
-  return s.includes(search);
-};
-var STR_INDEX_OF = (s, search) => {
-  assertString(s, "STR_INDEX_OF");
-  assertString(search, "STR_INDEX_OF");
-  return s.indexOf(search);
-};
 var STR_SPLIT = (s, sep) => {
   assertString(s, "STR_SPLIT");
   assertString(sep, "STR_SPLIT (separator)");
@@ -2900,12 +2929,12 @@ var STR_REPEAT = (s, count) => {
 var exports_time = {};
 __export(exports_time, {
   TIME: () => TIME,
+  SECOND: () => SECOND,
   NOW_TIME: () => NOW_TIME,
+  MINUTE: () => MINUTE,
+  MILLISECOND: () => MILLISECOND,
   IS_SAME_TIME: () => IS_SAME_TIME,
-  GET_SECOND: () => GET_SECOND,
-  GET_MINUTE: () => GET_MINUTE,
-  GET_MILLISECOND: () => GET_MILLISECOND,
-  GET_HOUR: () => GET_HOUR,
+  HOUR: () => HOUR,
   DIFFERENCE_IN_SECONDS: () => DIFFERENCE_IN_SECONDS,
   DIFFERENCE_IN_MINUTES: () => DIFFERENCE_IN_MINUTES,
   DIFFERENCE_IN_HOURS: () => DIFFERENCE_IN_HOURS,
@@ -2920,20 +2949,20 @@ var TIME = (hour, minute, second) => {
   return new Temporal.PlainTime(hour, minute, second);
 };
 var NOW_TIME = () => Temporal.Now.plainTimeISO();
-var GET_HOUR = (t) => {
-  assertTimeOrDateTime(t, "GET_HOUR");
+var HOUR = (t) => {
+  assertTimeOrDateTime(t, "HOUR");
   return t.hour;
 };
-var GET_MINUTE = (t) => {
-  assertTimeOrDateTime(t, "GET_MINUTE");
+var MINUTE = (t) => {
+  assertTimeOrDateTime(t, "MINUTE");
   return t.minute;
 };
-var GET_SECOND = (t) => {
-  assertTimeOrDateTime(t, "GET_SECOND");
+var SECOND = (t) => {
+  assertTimeOrDateTime(t, "SECOND");
   return t.second;
 };
-var GET_MILLISECOND = (t) => {
-  assertTimeOrDateTime(t, "GET_MILLISECOND");
+var MILLISECOND = (t) => {
+  assertTimeOrDateTime(t, "MILLISECOND");
   return t.millisecond;
 };
 var ADD_HOURS = (t, hours) => {
@@ -3019,6 +3048,7 @@ export {
   visitPartial,
   visit,
   typeOf,
+  toLineColumn,
   exports_time as time,
   exports_string as string,
   parse,
@@ -3060,5 +3090,6 @@ export {
   assertBoolean,
   assertArray,
   exports_array as array,
+  ParseError,
   NodeKind
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "littlewing",
-	"version": "2.1.0",
+	"version": "2.2.0",
 	"description": "A minimal, high-performance multi-type expression language with lexer, parser, and interpreter. Optimized for browsers with type-safe execution.",
 	"keywords": [
 		"calculator",
@@ -51,6 +51,7 @@
 		"test": "bun test",
 		"test:coverage": "bun test --coverage",
 		"test:watch": "bun test --watch",
+		"prepublishOnly": "cp ../../README.md ../../LICENSE .",
 		"release": "bumpp --commit --push --tag"
 	},
 	"devDependencies": {