littlewing 2.0.0 → 2.1.1

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 **85 built-in functions**:
+
+**Type Conversion (3):** `STR`, `NUM`, `TYPE`
+
+**Math (14):** `ABS`, `CEIL`, `FLOOR`, `ROUND`, `SQRT`, `MIN`, `MAX`, `CLAMP`, `SIN`, `COS`, `TAN`, `LOG`, `LOG10`, `EXP`
+
+**String (12):** `STR_LEN`, `STR_UPPER`, `STR_LOWER`, `STR_TRIM`, `STR_SLICE`, `STR_CONTAINS`, `STR_INDEX_OF`, `STR_SPLIT`, `STR_REPLACE`, `STR_STARTS_WITH`, `STR_ENDS_WITH`, `STR_REPEAT`
+
+**Array (12):** `ARR_LEN`, `ARR_PUSH`, `ARR_SLICE`, `ARR_CONTAINS`, `ARR_REVERSE`, `ARR_SORT`, `ARR_UNIQUE`, `ARR_FLAT`, `ARR_JOIN`, `ARR_SUM`, `ARR_MIN`, `ARR_MAX`
+
+**Date (24):** `TODAY`, `DATE`, `GET_YEAR`, `GET_MONTH`, `GET_DAY`, `GET_WEEKDAY`, `GET_DAY_OF_YEAR`, `GET_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`
+
+**Time (13):** `TIME`, `NOW_TIME`, `GET_HOUR`, `GET_MINUTE`, `GET_SECOND`, `GET_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

@@ -1,5 +1,5 @@
 declare namespace exports_ast {
-	export { unaryOp, subtract, string, rangeExpr, program, number, notEquals, negate, multiply, modulo, logicalOr, logicalNot, logicalAnd, lessThan, lessEqual, isUnaryOp, isStringLiteral, isRangeExpression, isProgram, 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, Operator, NumberLiteral, NodeKind, IndexAccess, IfExpression, Identifier2 as Identifier, FunctionCall, ForExpression, BooleanLiteral, BinaryOp, Assignment, ArrayLiteral, ASTNodeBase, ASTNode };
+	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 };
 }
 /**
 * Binary operator types
@@ -30,7 +30,9 @@ declare const enum NodeKind {
 	ArrayLiteral = 10,
 	ForExpression = 11,
 	IndexAccess = 12,
-	RangeExpression = 13
+	RangeExpression = 13,
+	PipeExpression = 14,
+	Placeholder = 15
 }
 /**
 * Program node (multiple statements)
@@ -151,9 +153,25 @@ interface RangeExpression extends ASTNodeBase {
 	readonly inclusive: boolean;
 }
 /**
+* Pipe expression (value |> FUN(?, arg))
+* Chains a value through a function call where ? marks the insertion point
+*/
+interface PipeExpression extends ASTNodeBase {
+	readonly kind: NodeKind.PipeExpression;
+	readonly value: ASTNode;
+	readonly name: string;
+	readonly args: readonly ASTNode[];
+}
+/**
+* Placeholder (?) used inside pipe expression arguments
+*/
+interface Placeholder extends ASTNodeBase {
+	readonly kind: NodeKind.Placeholder;
+}
+/**
 * AST Node - discriminated union of all node types
 */
-type ASTNode = Program | NumberLiteral | StringLiteral | BooleanLiteral | ArrayLiteral | Identifier2 | BinaryOp | UnaryOp | FunctionCall | Assignment | IfExpression | ForExpression | IndexAccess | RangeExpression;
+type ASTNode = Program | NumberLiteral | StringLiteral | BooleanLiteral | ArrayLiteral | Identifier2 | BinaryOp | UnaryOp | FunctionCall | Assignment | IfExpression | ForExpression | IndexAccess | RangeExpression | PipeExpression | Placeholder;
 /**
 * Type guard functions for discriminated union narrowing
 */
@@ -171,6 +189,8 @@ declare function isIfExpression(node: ASTNode): node is IfExpression;
 declare function isForExpression(node: ASTNode): node is ForExpression;
 declare function isIndexAccess(node: ASTNode): node is IndexAccess;
 declare function isRangeExpression(node: ASTNode): node is RangeExpression;
+declare function isPipeExpression(node: ASTNode): node is PipeExpression;
+declare function isPlaceholder(node: ASTNode): node is Placeholder;
 /**
 * Builder functions for creating AST nodes manually
 */
@@ -234,6 +254,14 @@ declare function indexAccess(object: ASTNode, index: ASTNode): IndexAccess;
 */
 declare function rangeExpr(start: ASTNode, end: ASTNode, inclusive: boolean): RangeExpression;
 /**
+* 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
 */
 declare function add(left: ASTNode, right: ASTNode): BinaryOp;
@@ -737,30 +765,41 @@ declare function assertTimeOrDateTime(v: RuntimeValue, context: string): asserts
 */
 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 handler functions for each AST node type.
-* Each handler receives:
-* - The node (correctly typed based on node.type)
-* - A recurse function to visit child nodes with the same visitor
+* 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: (node: Program, recurse: (n: ASTNode) => T) => T;
-	NumberLiteral: (node: NumberLiteral, recurse: (n: ASTNode) => T) => T;
-	StringLiteral: (node: StringLiteral, recurse: (n: ASTNode) => T) => T;
-	BooleanLiteral: (node: BooleanLiteral, recurse: (n: ASTNode) => T) => T;
-	ArrayLiteral: (node: ArrayLiteral, recurse: (n: ASTNode) => T) => T;
-	Identifier2: (node: Identifier2, recurse: (n: ASTNode) => T) => T;
-	BinaryOp: (node: BinaryOp, recurse: (n: ASTNode) => T) => T;
-	UnaryOp: (node: UnaryOp, recurse: (n: ASTNode) => T) => T;
-	FunctionCall: (node: FunctionCall, recurse: (n: ASTNode) => T) => T;
-	Assignment: (node: Assignment, recurse: (n: ASTNode) => T) => T;
-	IfExpression: (node: IfExpression, recurse: (n: ASTNode) => T) => T;
-	ForExpression: (node: ForExpression, recurse: (n: ASTNode) => T) => T;
-	IndexAccess: (node: IndexAccess, recurse: (n: ASTNode) => T) => T;
-	RangeExpression: (node: RangeExpression, recurse: (n: ASTNode) => T) => 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.
@@ -785,5 +824,5 @@ declare function visit<T>(node: ASTNode, visitor: Visitor<T>): T;
 * @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: (node: ASTNode, recurse: (n: ASTNode) => T) => T): T;
-export { visitPartial, visit, typeOf, time, string, parse, optimize, math, isUnaryOp, isStringLiteral, isRangeExpression, isProgram, 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, Visitor, UnaryOp, StringLiteral, RuntimeValue, RangeExpression, Program, Operator, NumberLiteral, NodeKind, IndexAccess, IfExpression, Identifier2 as Identifier, FunctionCall, ForExpression, ExecutionContext, BooleanLiteral, BinaryOp, Assignment, ArrayLiteral, ASTNodeBase, ASTNode };
+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 };

package/dist/index.js

@@ -1,11 +1,15 @@
 var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {
       get: all[name],
       enumerable: true,
       configurable: true,
-      set: (newValue) => all[name] = () => newValue
+      set: __exportSetter.bind(all, name)
     });
 };
 
@@ -17,6 +21,8 @@ __export(exports_ast, {
   string: () => string,
   rangeExpr: () => rangeExpr,
   program: () => program,
+  placeholder: () => placeholder,
+  pipeExpr: () => pipeExpr,
   number: () => number,
   notEquals: () => notEquals,
   negate: () => negate,
@@ -31,6 +37,8 @@ __export(exports_ast, {
   isStringLiteral: () => isStringLiteral,
   isRangeExpression: () => isRangeExpression,
   isProgram: () => isProgram,
+  isPlaceholder: () => isPlaceholder,
+  isPipeExpression: () => isPipeExpression,
   isNumberLiteral: () => isNumberLiteral,
   isIndexAccess: () => isIndexAccess,
   isIfExpression: () => isIfExpression,
@@ -75,6 +83,8 @@ var NodeKind;
   NodeKind2[NodeKind2["ForExpression"] = 11] = "ForExpression";
   NodeKind2[NodeKind2["IndexAccess"] = 12] = "IndexAccess";
   NodeKind2[NodeKind2["RangeExpression"] = 13] = "RangeExpression";
+  NodeKind2[NodeKind2["PipeExpression"] = 14] = "PipeExpression";
+  NodeKind2[NodeKind2["Placeholder"] = 15] = "Placeholder";
 })(NodeKind ||= {});
 function isProgram(node) {
   return node.kind === 0 /* Program */;
@@ -118,6 +128,12 @@ function isIndexAccess(node) {
 function isRangeExpression(node) {
   return node.kind === 13 /* RangeExpression */;
 }
+function isPipeExpression(node) {
+  return node.kind === 14 /* PipeExpression */;
+}
+function isPlaceholder(node) {
+  return node.kind === 15 /* Placeholder */;
+}
 function program(statements) {
   return { kind: 0 /* Program */, statements };
 }
@@ -172,6 +188,12 @@ function indexAccess(object, index) {
 function rangeExpr(start, end, inclusive) {
   return { kind: 13 /* RangeExpression */, start, end, inclusive };
 }
+function pipeExpr(value, name, args) {
+  return { kind: 14 /* PipeExpression */, value, name, args };
+}
+function placeholder() {
+  return { kind: 15 /* Placeholder */ };
+}
 function add(left, right) {
   return binaryOp(left, "+", right);
 }
@@ -250,20 +272,156 @@ function getNodeName(node) {
       return "IndexAccess";
     case 13 /* RangeExpression */:
       return "RangeExpression";
+    case 14 /* PipeExpression */:
+      return "PipeExpression";
+    case 15 /* Placeholder */:
+      return "Placeholder";
     default:
       throw new Error(`Unknown node kind: ${node.kind}`);
   }
 }
 
+// src/visitor.ts
+function visit(node, visitor) {
+  return visitPartial(node, visitor, (node2) => {
+    throw new Error(`No handler for node type: ${getNodeName(node2)}`);
+  });
+}
+function visitPartial(node, visitor, defaultHandler) {
+  const recurse = (n) => visitPartial(n, visitor, defaultHandler);
+  switch (node.kind) {
+    case 0 /* Program */:
+      return visitor.Program ? visitor.Program(node, recurse) : defaultHandler(node, recurse);
+    case 1 /* NumberLiteral */:
+      return visitor.NumberLiteral ? visitor.NumberLiteral(node, recurse) : defaultHandler(node, recurse);
+    case 8 /* StringLiteral */:
+      return visitor.StringLiteral ? visitor.StringLiteral(node, recurse) : defaultHandler(node, recurse);
+    case 9 /* BooleanLiteral */:
+      return visitor.BooleanLiteral ? visitor.BooleanLiteral(node, recurse) : defaultHandler(node, recurse);
+    case 10 /* ArrayLiteral */:
+      return visitor.ArrayLiteral ? visitor.ArrayLiteral(node, recurse) : defaultHandler(node, recurse);
+    case 2 /* Identifier */:
+      return visitor.Identifier ? visitor.Identifier(node, recurse) : defaultHandler(node, recurse);
+    case 3 /* BinaryOp */:
+      return visitor.BinaryOp ? visitor.BinaryOp(node, recurse) : defaultHandler(node, recurse);
+    case 4 /* UnaryOp */:
+      return visitor.UnaryOp ? visitor.UnaryOp(node, recurse) : defaultHandler(node, recurse);
+    case 5 /* FunctionCall */:
+      return visitor.FunctionCall ? visitor.FunctionCall(node, recurse) : defaultHandler(node, recurse);
+    case 6 /* Assignment */:
+      return visitor.Assignment ? visitor.Assignment(node, recurse) : defaultHandler(node, recurse);
+    case 7 /* IfExpression */:
+      return visitor.IfExpression ? visitor.IfExpression(node, recurse) : defaultHandler(node, recurse);
+    case 11 /* ForExpression */:
+      return visitor.ForExpression ? visitor.ForExpression(node, recurse) : defaultHandler(node, recurse);
+    case 12 /* IndexAccess */:
+      return visitor.IndexAccess ? visitor.IndexAccess(node, recurse) : defaultHandler(node, recurse);
+    case 13 /* RangeExpression */:
+      return visitor.RangeExpression ? visitor.RangeExpression(node, recurse) : defaultHandler(node, recurse);
+    case 14 /* PipeExpression */:
+      return visitor.PipeExpression ? visitor.PipeExpression(node, recurse) : defaultHandler(node, recurse);
+    case 15 /* Placeholder */:
+      return visitor.Placeholder ? visitor.Placeholder(node, recurse) : defaultHandler(node, recurse);
+  }
+}
+
+// src/analyzer.ts
+function extractInputVariables(ast) {
+  const inputVars = new Set;
+  const statements = isProgram(ast) ? ast.statements : [ast];
+  for (const statement of statements) {
+    if (isAssignment(statement)) {
+      if (!containsVariableReference(statement.value)) {
+        inputVars.add(statement.name);
+      }
+    }
+  }
+  return Array.from(inputVars);
+}
+function extractAssignedVariables(ast) {
+  const seen = new Set;
+  const names = [];
+  visitPartial(ast, {
+    Program: (n, recurse) => {
+      for (const statement of n.statements) {
+        recurse(statement);
+      }
+    },
+    Assignment: (n, recurse) => {
+      if (!seen.has(n.name)) {
+        seen.add(n.name);
+        names.push(n.name);
+      }
+      recurse(n.value);
+    },
+    IfExpression: (n, recurse) => {
+      recurse(n.condition);
+      recurse(n.consequent);
+      recurse(n.alternate);
+    },
+    ForExpression: (n, recurse) => {
+      recurse(n.iterable);
+      if (n.guard)
+        recurse(n.guard);
+      if (n.accumulator)
+        recurse(n.accumulator.initial);
+      recurse(n.body);
+    },
+    IndexAccess: (n, recurse) => {
+      recurse(n.object);
+      recurse(n.index);
+    },
+    RangeExpression: (n, recurse) => {
+      recurse(n.start);
+      recurse(n.end);
+    },
+    PipeExpression: (n, recurse) => {
+      recurse(n.value);
+      for (const arg of n.args) {
+        recurse(arg);
+      }
+    }
+  }, () => {});
+  return names;
+}
+function containsExternalReference(node, boundVars) {
+  return visit(node, {
+    Program: (n, recurse) => n.statements.some(recurse),
+    NumberLiteral: () => false,
+    StringLiteral: () => false,
+    BooleanLiteral: () => false,
+    Identifier: (n) => !boundVars.has(n.name),
+    ArrayLiteral: (n, recurse) => n.elements.some(recurse),
+    BinaryOp: (n, recurse) => recurse(n.left) || recurse(n.right),
+    UnaryOp: (n, recurse) => recurse(n.argument),
+    FunctionCall: (n, recurse) => n.args.some(recurse),
+    Assignment: (n, recurse) => recurse(n.value),
+    IfExpression: (n, recurse) => recurse(n.condition) || recurse(n.consequent) || recurse(n.alternate),
+    ForExpression: (n, recurse) => {
+      const innerBound = new Set(boundVars);
+      innerBound.add(n.variable);
+      if (n.accumulator)
+        innerBound.add(n.accumulator.name);
+      return recurse(n.iterable) || (n.guard ? containsExternalReference(n.guard, innerBound) : false) || (n.accumulator ? recurse(n.accumulator.initial) : false) || containsExternalReference(n.body, innerBound);
+    },
+    IndexAccess: (n, recurse) => recurse(n.object) || recurse(n.index),
+    RangeExpression: (n, recurse) => recurse(n.start) || recurse(n.end),
+    PipeExpression: (n, recurse) => recurse(n.value) || n.args.some(recurse),
+    Placeholder: () => false
+  });
+}
+function containsVariableReference(node) {
+  return containsExternalReference(node, new Set);
+}
 // src/lexer.ts
 var KEYWORDS = new Map([
-  ["if", 26 /* If */],
-  ["then", 27 /* Then */],
-  ["else", 28 /* Else */],
-  ["for", 29 /* For */],
-  ["in", 30 /* In */],
-  ["when", 31 /* When */],
-  ["into", 32 /* Into */]
+  ["if", 28 /* If */],
+  ["then", 29 /* Then */],
+  ["else", 30 /* Else */],
+  ["for", 31 /* For */],
+  ["in", 32 /* In */],
+  ["when", 33 /* When */],
+  ["into", 34 /* Into */]
 ]);
 function createCursor(source) {
   return {
@@ -355,7 +513,7 @@ function nextToken(cursor) {
     }
   }
   if (cursor.pos >= cursor.len) {
-    return [33 /* Eof */, cursor.pos, cursor.pos];
+    return [35 /* Eof */, cursor.pos, cursor.pos];
   }
   const start = cursor.pos;
   const ch = peek(cursor);
@@ -456,7 +614,14 @@ function nextToken(cursor) {
         advance(cursor);
         return [17 /* Or */, start, cursor.pos];
       }
+      if (peek(cursor) === 62) {
+        advance(cursor);
+        return [26 /* Pipe */, start, cursor.pos];
+      }
       throw new Error(`Unexpected character '${String.fromCharCode(ch)}' at position ${start}`);
+    case 63:
+      advance(cursor);
+      return [27 /* Question */, start, cursor.pos];
     default:
       throw new Error(`Unexpected character '${String.fromCharCode(ch)}' at position ${start}`);
   }
@@ -514,46 +679,6 @@ function lexIdentifier(cursor) {
   return [1 /* Identifier */, start, pos];
 }
 
-// src/visitor.ts
-function visit(node, visitor) {
-  return visitPartial(node, visitor, (node2) => {
-    throw new Error(`No handler for node type: ${getNodeName(node2)}`);
-  });
-}
-function visitPartial(node, visitor, defaultHandler) {
-  const recurse = (n) => visitPartial(n, visitor, defaultHandler);
-  switch (node.kind) {
-    case 0 /* Program */:
-      return visitor.Program ? visitor.Program(node, recurse) : defaultHandler(node, recurse);
-    case 1 /* NumberLiteral */:
-      return visitor.NumberLiteral ? visitor.NumberLiteral(node, recurse) : defaultHandler(node, recurse);
-    case 8 /* StringLiteral */:
-      return visitor.StringLiteral ? visitor.StringLiteral(node, recurse) : defaultHandler(node, recurse);
-    case 9 /* BooleanLiteral */:
-      return visitor.BooleanLiteral ? visitor.BooleanLiteral(node, recurse) : defaultHandler(node, recurse);
-    case 10 /* ArrayLiteral */:
-      return visitor.ArrayLiteral ? visitor.ArrayLiteral(node, recurse) : defaultHandler(node, recurse);
-    case 2 /* Identifier */:
-      return visitor.Identifier ? visitor.Identifier(node, recurse) : defaultHandler(node, recurse);
-    case 3 /* BinaryOp */:
-      return visitor.BinaryOp ? visitor.BinaryOp(node, recurse) : defaultHandler(node, recurse);
-    case 4 /* UnaryOp */:
-      return visitor.UnaryOp ? visitor.UnaryOp(node, recurse) : defaultHandler(node, recurse);
-    case 5 /* FunctionCall */:
-      return visitor.FunctionCall ? visitor.FunctionCall(node, recurse) : defaultHandler(node, recurse);
-    case 6 /* Assignment */:
-      return visitor.Assignment ? visitor.Assignment(node, recurse) : defaultHandler(node, recurse);
-    case 7 /* IfExpression */:
-      return visitor.IfExpression ? visitor.IfExpression(node, recurse) : defaultHandler(node, recurse);
-    case 11 /* ForExpression */:
-      return visitor.ForExpression ? visitor.ForExpression(node, recurse) : defaultHandler(node, recurse);
-    case 12 /* IndexAccess */:
-      return visitor.IndexAccess ? visitor.IndexAccess(node, recurse) : defaultHandler(node, recurse);
-    case 13 /* RangeExpression */:
-      return visitor.RangeExpression ? visitor.RangeExpression(node, recurse) : defaultHandler(node, recurse);
-  }
-}
-
 // src/utils.ts
 function typeOf(value) {
   if (typeof value === "number")
@@ -767,14 +892,20 @@ function resolveIndex(target, index) {
   if (!Number.isInteger(index)) {
     throw new TypeError(`Index must be an integer, got ${index}`);
   }
+  if (typeof target === "string") {
+    const codePoints = Array.from(target);
+    const len2 = codePoints.length;
+    const resolved2 = index < 0 ? len2 + index : index;
+    if (resolved2 < 0 || resolved2 >= len2) {
+      throw new RangeError(`Index ${index} out of bounds for length ${len2}`);
+    }
+    return codePoints[resolved2];
+  }
   const len = target.length;
   const resolved = index < 0 ? len + index : index;
   if (resolved < 0 || resolved >= len) {
     throw new RangeError(`Index ${index} out of bounds for length ${len}`);
   }
-  if (typeof target === "string") {
-    return target[resolved];
-  }
   return target[resolved];
 }
 function buildRange(start, end, inclusive) {
@@ -874,7 +1005,14 @@ function collectAllIdentifiers(node) {
     RangeExpression: (n, recurse) => {
       recurse(n.start);
       recurse(n.end);
-    }
+    },
+    PipeExpression: (n, recurse) => {
+      recurse(n.value);
+      for (const arg of n.args) {
+        recurse(arg);
+      }
+    },
+    Placeholder: () => {}
   });
   return identifiers;
 }
@@ -882,6 +1020,8 @@ function getTokenPrecedence(kind) {
   switch (kind) {
     case 24 /* Eq */:
       return 1;
+    case 26 /* Pipe */:
+      return 2;
     case 17 /* Or */:
       return 3;
     case 16 /* And */:
@@ -910,62 +1050,6 @@ function getTokenPrecedence(kind) {
   }
 }
 
-// src/analyzer.ts
-function extractInputVariables(ast) {
-  const inputVars = new Set;
-  const statements = isProgram(ast) ? ast.statements : [ast];
-  for (const statement of statements) {
-    if (isAssignment(statement)) {
-      if (!containsVariableReference(statement.value)) {
-        inputVars.add(statement.name);
-      }
-    }
-  }
-  return Array.from(inputVars);
-}
-function extractAssignedVariables(ast) {
-  const seen = new Set;
-  const names = [];
-  visitPartial(ast, {
-    Program: (n, recurse) => {
-      for (const statement of n.statements) {
-        recurse(statement);
-      }
-    },
-    Assignment: (n, recurse) => {
-      if (!seen.has(n.name)) {
-        seen.add(n.name);
-        names.push(n.name);
-      }
-      recurse(n.value);
-    },
-    IfExpression: (n, recurse) => {
-      recurse(n.condition);
-      recurse(n.consequent);
-      recurse(n.alternate);
-    },
-    ForExpression: (n, recurse) => {
-      recurse(n.iterable);
-      if (n.guard)
-        recurse(n.guard);
-      if (n.accumulator)
-        recurse(n.accumulator.initial);
-      recurse(n.body);
-    },
-    IndexAccess: (n, recurse) => {
-      recurse(n.object);
-      recurse(n.index);
-    },
-    RangeExpression: (n, recurse) => {
-      recurse(n.start);
-      recurse(n.end);
-    }
-  }, () => {});
-  return names;
-}
-function containsVariableReference(node) {
-  return collectAllIdentifiers(node).size > 0;
-}
 // src/codegen.ts
 function needsParens(node, operator, isLeft) {
   if (!isBinaryOp(node))
@@ -1049,15 +1133,16 @@ function generateNode(node) {
     BinaryOp: (n, recurse) => {
       const left = recurse(n.left);
       const right = recurse(n.right);
-      const leftNeedsParens = needsParens(n.left, n.operator, true) || n.operator === "^" && isUnaryOp(n.left);
+      const opPrec = getOperatorPrecedence(n.operator);
+      const leftNeedsParens = needsParens(n.left, n.operator, true) || n.operator === "^" && isUnaryOp(n.left) || isIfExpression(n.left) || isForExpression(n.left) || isAssignment(n.left) || isRangeExpression(n.left) && opPrec >= 7;
       const leftCode = leftNeedsParens ? `(${left})` : left;
-      const rightNeedsParens = needsParens(n.right, n.operator, false);
+      const rightNeedsParens = needsParens(n.right, n.operator, false) || isPipeExpression(n.right) || isAssignment(n.right) || isRangeExpression(n.right) && opPrec >= 6;
       const rightCode = rightNeedsParens ? `(${right})` : right;
       return `${leftCode} ${n.operator} ${rightCode}`;
     },
     UnaryOp: (n, recurse) => {
       const arg = recurse(n.argument);
-      const parensNeeded = isBinaryOp(n.argument) || isAssignment(n.argument);
+      const parensNeeded = isBinaryOp(n.argument) || isAssignment(n.argument) || isPipeExpression(n.argument) || isRangeExpression(n.argument);
       const argCode = parensNeeded ? `(${arg})` : arg;
       return `${n.operator}${argCode}`;
     },
@@ -1089,7 +1174,7 @@ function generateNode(node) {
     IndexAccess: (n, recurse) => {
       const object = recurse(n.object);
       const index = recurse(n.index);
-      const needsParens2 = isBinaryOp(n.object) || isUnaryOp(n.object) || isAssignment(n.object) || isRangeExpression(n.object);
+      const needsParens2 = isBinaryOp(n.object) || isUnaryOp(n.object) || isAssignment(n.object) || isRangeExpression(n.object) || isPipeExpression(n.object);
       const objectCode = needsParens2 ? `(${object})` : object;
       return `${objectCode}[${index}]`;
     },
@@ -1097,12 +1182,20 @@ function generateNode(node) {
       const start = recurse(n.start);
       const end = recurse(n.end);
       const op = n.inclusive ? "..=" : "..";
-      const startNeedsParens = isBinaryOp(n.start) || isRangeExpression(n.start);
-      const endNeedsParens = isBinaryOp(n.end) || isRangeExpression(n.end);
+      const startNeedsParens = isBinaryOp(n.start) || isRangeExpression(n.start) || isIfExpression(n.start) || isForExpression(n.start) || isAssignment(n.start);
+      const endNeedsParens = isBinaryOp(n.end) || isRangeExpression(n.end) || isPipeExpression(n.end) || isAssignment(n.end);
       const startCode = startNeedsParens ? `(${start})` : start;
       const endCode = endNeedsParens ? `(${end})` : end;
       return `${startCode}${op}${endCode}`;
-    }
+    },
+    PipeExpression: (n, recurse) => {
+      const value = recurse(n.value);
+      const argsCode = n.args.map(recurse).join(", ");
+      const valueNeedsParens = isAssignment(n.value) || isIfExpression(n.value) || isForExpression(n.value);
+      const valueCode = valueNeedsParens ? `(${value})` : value;
+      return `${valueCode} |> ${n.name}(${argsCode})`;
+    },
+    Placeholder: () => "?"
   });
 }
 // src/parser.ts
@@ -1132,7 +1225,7 @@ function parse(source) {
   };
   const statements = [];
   const statementOffsets = [];
-  while (state.currentToken[0] !== 33 /* Eof */) {
+  while (state.currentToken[0] !== 35 /* Eof */) {
     statementOffsets.push(state.currentToken[1]);
     statements.push(parseExpression(state, 0));
   }
@@ -1305,40 +1398,40 @@ function parsePrefix(state) {
     advance2(state);
     return array(elements);
   }
-  if (tokenKind === 26 /* If */) {
+  if (tokenKind === 28 /* If */) {
     advance2(state);
     const condition = parseExpression(state, 0);
-    if (peekKind(state) !== 27 /* Then */) {
+    if (peekKind(state) !== 29 /* Then */) {
       throw new Error('Expected "then" in if expression');
     }
     advance2(state);
     const consequent = parseExpression(state, 0);
-    if (peekKind(state) !== 28 /* Else */) {
+    if (peekKind(state) !== 30 /* Else */) {
       throw new Error('Expected "else" in if expression');
     }
     advance2(state);
     const alternate = parseExpression(state, 0);
     return ifExpr(condition, consequent, alternate);
   }
-  if (tokenKind === 29 /* For */) {
+  if (tokenKind === 31 /* For */) {
     advance2(state);
     if (peekKind(state) !== 1 /* Identifier */) {
       throw new Error('Expected identifier after "for"');
     }
     const variableName = readText(state.cursor, state.currentToken);
     advance2(state);
-    if (peekKind(state) !== 30 /* In */) {
+    if (peekKind(state) !== 32 /* In */) {
       throw new Error('Expected "in" in for expression');
     }
     advance2(state);
     const iterable = parseExpression(state, 0);
     let guard = null;
-    if (peekKind(state) === 31 /* When */) {
+    if (peekKind(state) === 33 /* When */) {
       advance2(state);
       guard = parseExpression(state, 0);
     }
     let accumulator = null;
-    if (peekKind(state) === 32 /* Into */) {
+    if (peekKind(state) === 34 /* Into */) {
       advance2(state);
       if (peekKind(state) !== 1 /* Identifier */) {
         throw new Error('Expected identifier after "into"');
@@ -1352,7 +1445,7 @@ function parsePrefix(state) {
       const initial = parseExpression(state, 0);
       accumulator = { name: accName, initial };
     }
-    if (peekKind(state) !== 27 /* Then */) {
+    if (peekKind(state) !== 29 /* Then */) {
       throw new Error('Expected "then" in for expression');
     }
     advance2(state);
@@ -1413,6 +1506,34 @@ function parseInfix(state, left, precedence) {
     const right = parseExpression(state, precedence + 1);
     return rangeExpr(left, right, inclusive);
   }
+  if (tokenKind === 26 /* Pipe */) {
+    advance2(state);
+    if (peekKind(state) !== 1 /* Identifier */) {
+      throw new Error("Expected function name after |>");
+    }
+    const name = readText(state.cursor, state.currentToken);
+    advance2(state);
+    if (peekKind(state) !== 20 /* LParen */) {
+      throw new Error("Expected ( after function name in pipe expression");
+    }
+    advance2(state);
+    const args = parsePipeArguments(state);
+    if (peekKind(state) !== 21 /* RParen */) {
+      throw new Error("Expected closing parenthesis");
+    }
+    advance2(state);
+    let hasPlaceholder = false;
+    for (const arg of args) {
+      if (arg.kind === 15 /* Placeholder */) {
+        hasPlaceholder = true;
+        break;
+      }
+    }
+    if (!hasPlaceholder) {
+      throw new Error("Pipe expression requires at least one ? placeholder");
+    }
+    return pipeExpr(left, name, args);
+  }
   if (isBinaryOperator(tokenKind)) {
     const operator = readText(state.cursor, state.currentToken);
     advance2(state);
@@ -1434,6 +1555,25 @@ function parseFunctionArguments(state) {
   }
   return args;
 }
+function parsePipeArguments(state) {
+  if (peekKind(state) === 21 /* RParen */) {
+    return [];
+  }
+  const args = [];
+  args.push(parsePipeArg(state));
+  while (peekKind(state) === 25 /* Comma */) {
+    advance2(state);
+    args.push(parsePipeArg(state));
+  }
+  return args;
+}
+function parsePipeArg(state) {
+  if (peekKind(state) === 27 /* Question */) {
+    advance2(state);
+    return placeholder();
+  }
+  return parseExpression(state, 0);
+}
 var UNARY_PRECEDENCE = 8;
 function isBinaryOperator(kind) {
   return BINARY_OPERATOR_TOKENS.has(kind);
@@ -1550,6 +1690,21 @@ function evaluateNode(node, context, variables, externalVariables) {
       assertNumber(end, "Range end");
       return buildRange(start, end, n.inclusive);
     },
+    PipeExpression: (n, recurse) => {
+      const pipedValue = recurse(n.value);
+      const fn = context.functions?.[n.name];
+      if (fn === undefined) {
+        throw new Error(`Undefined function: ${n.name}`);
+      }
+      if (typeof fn !== "function") {
+        throw new Error(`${n.name} is not a function`);
+      }
+      const evaluatedArgs = n.args.map((arg) => arg.kind === 15 /* Placeholder */ ? pipedValue : recurse(arg));
+      return fn(...evaluatedArgs);
+    },
+    Placeholder: () => {
+      throw new Error("Placeholder outside pipe expression");
+    },
     ForExpression: (n, recurse) => {
       const iterable = recurse(n.iterable);
       let items;
@@ -1653,7 +1808,7 @@ function eliminateDeadCode(program2) {
       continue;
     }
     if (isAssignment(stmt)) {
-      if (liveVars.has(stmt.name)) {
+      if (liveVars.has(stmt.name) || mightHaveSideEffects(stmt.value)) {
         keptIndices.push(i);
         const identifiers = collectAllIdentifiers(stmt.value);
         for (const id of identifiers) {
@@ -1687,14 +1842,37 @@ function eliminateDeadCode(program2) {
 function isLiteral(node) {
   return isNumberLiteral(node) || isStringLiteral(node) || isBooleanLiteral(node);
 }
+function mightHaveSideEffects(node) {
+  return visit(node, {
+    Program: (n, recurse) => n.statements.some(recurse),
+    NumberLiteral: () => false,
+    StringLiteral: () => false,
+    BooleanLiteral: () => false,
+    Identifier: () => false,
+    ArrayLiteral: (n, recurse) => n.elements.some(recurse),
+    BinaryOp: (n, recurse) => recurse(n.left) || recurse(n.right),
+    UnaryOp: (n, recurse) => recurse(n.argument),
+    FunctionCall: () => true,
+    PipeExpression: () => true,
+    Placeholder: () => false,
+    Assignment: () => true,
+    IfExpression: (n, recurse) => recurse(n.condition) || recurse(n.consequent) || recurse(n.alternate),
+    ForExpression: (n, recurse) => recurse(n.iterable) || (n.guard ? recurse(n.guard) : false) || (n.accumulator ? recurse(n.accumulator.initial) : false) || recurse(n.body),
+    IndexAccess: (n, recurse) => recurse(n.object) || recurse(n.index),
+    RangeExpression: (n, recurse) => recurse(n.start) || recurse(n.end)
+  });
+}
 function propagateConstants(program2, externalVariables) {
   const statements = program2.statements;
   const forLoopVars = new Set;
   for (const stmt of statements) {
     collectForLoopVars(stmt, forLoopVars);
   }
+  const allAssignmentCounts = new Map;
+  for (const stmt of statements) {
+    countAssignments(stmt, allAssignmentCounts);
+  }
   const knownValues = new Map;
-  const reassigned = new Set;
   for (const stmt of statements) {
     if (!isAssignment(stmt))
       continue;
@@ -1702,11 +1880,9 @@ function propagateConstants(program2, externalVariables) {
       continue;
     if (forLoopVars.has(stmt.name))
       continue;
-    if (knownValues.has(stmt.name) || reassigned.has(stmt.name)) {
-      knownValues.delete(stmt.name);
-      reassigned.add(stmt.name);
+    const totalCount = allAssignmentCounts.get(stmt.name) ?? 0;
+    if (totalCount > 1)
       continue;
-    }
     if (isLiteral(stmt.value)) {
       knownValues.set(stmt.name, stmt.value);
     }
@@ -1786,7 +1962,13 @@ function collectReferencedIdentifiers(node, ids) {
     RangeExpression: (n, recurse) => {
       recurse(n.start);
       recurse(n.end);
-    }
+    },
+    PipeExpression: (n, recurse) => {
+      recurse(n.value);
+      for (const a of n.args)
+        recurse(a);
+    },
+    Placeholder: () => {}
   });
 }
 function collectForLoopVars(node, vars) {
@@ -1840,7 +2022,71 @@ function collectForLoopVars(node, vars) {
     RangeExpression: (n, recurse) => {
       recurse(n.start);
       recurse(n.end);
-    }
+    },
+    PipeExpression: (n, recurse) => {
+      recurse(n.value);
+      for (const a of n.args)
+        recurse(a);
+    },
+    Placeholder: () => {}
+  });
+}
+function countAssignments(node, counts) {
+  visit(node, {
+    Program: (n, recurse) => {
+      for (const s of n.statements)
+        recurse(s);
+    },
+    NumberLiteral: () => {},
+    StringLiteral: () => {},
+    BooleanLiteral: () => {},
+    ArrayLiteral: (n, recurse) => {
+      for (const e of n.elements)
+        recurse(e);
+    },
+    Identifier: () => {},
+    BinaryOp: (n, recurse) => {
+      recurse(n.left);
+      recurse(n.right);
+    },
+    UnaryOp: (n, recurse) => {
+      recurse(n.argument);
+    },
+    FunctionCall: (n, recurse) => {
+      for (const a of n.args)
+        recurse(a);
+    },
+    Assignment: (n, recurse) => {
+      counts.set(n.name, (counts.get(n.name) ?? 0) + 1);
+      recurse(n.value);
+    },
+    IfExpression: (n, recurse) => {
+      recurse(n.condition);
+      recurse(n.consequent);
+      recurse(n.alternate);
+    },
+    ForExpression: (n, recurse) => {
+      recurse(n.iterable);
+      if (n.guard)
+        recurse(n.guard);
+      if (n.accumulator)
+        recurse(n.accumulator.initial);
+      recurse(n.body);
+    },
+    IndexAccess: (n, recurse) => {
+      recurse(n.object);
+      recurse(n.index);
+    },
+    RangeExpression: (n, recurse) => {
+      recurse(n.start);
+      recurse(n.end);
+    },
+    PipeExpression: (n, recurse) => {
+      recurse(n.value);
+      for (const a of n.args)
+        recurse(a);
+    },
+    Placeholder: () => {}
   });
 }
 function substituteIdentifiers(node, knownValues) {
@@ -1877,7 +2123,9 @@ function substituteIdentifiers(node, knownValues) {
       return preserveComments(n, forExpr(n.variable, iterable, guard, accumulator, body));
     },
     IndexAccess: (n, recurse) => preserveComments(n, indexAccess(recurse(n.object), recurse(n.index))),
-    RangeExpression: (n, recurse) => preserveComments(n, rangeExpr(recurse(n.start), recurse(n.end), n.inclusive))
+    RangeExpression: (n, recurse) => preserveComments(n, rangeExpr(recurse(n.start), recurse(n.end), n.inclusive)),
+    PipeExpression: (n, recurse) => preserveComments(n, pipeExpr(recurse(n.value), n.name, n.args.map(recurse))),
+    Placeholder: (n) => n
   });
 }
 function optimize(node, externalVariables) {
@@ -2026,6 +2274,12 @@ function fold(node) {
       }
       return preserveComments(n, rangeExpr(start, end, n.inclusive));
     },
+    PipeExpression: (n, recurse) => {
+      const value = recurse(n.value);
+      const optimizedArgs = n.args.map(recurse);
+      return preserveComments(n, pipeExpr(value, n.name, optimizedArgs));
+    },
+    Placeholder: (n) => n,
     Program: (n, recurse) => {
       const optimizedStatements = n.statements.map(recurse);
       const result = program(optimizedStatements);
@@ -2774,6 +3028,8 @@ export {
   isStringLiteral,
   isRangeExpression,
   isProgram,
+  isPlaceholder,
+  isPipeExpression,
   isNumberLiteral,
   isIndexAccess,
   isIfExpression,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "littlewing",
-	"version": "2.0.0",
+	"version": "2.1.1",
 	"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": {