littlewing 0.2.0 → 0.3.1

package/README.md

@@ -8,7 +8,7 @@ A minimal, high-performance arithmetic expression language with a complete lexer
 - 📦 **Tiny Bundle** - 3.61 KB gzipped, zero dependencies
 - 🌐 **Browser Ready** - 100% ESM, no Node.js APIs
 - 🔒 **Type-Safe** - Strict TypeScript with full type coverage
-- ✅ **Thoroughly Tested** - 71 tests, 97.66% coverage
+- ✅ **Thoroughly Tested** - 106 tests, 97.66% coverage
 - 📐 **Math Expressions** - Numbers, dates, operators, functions, variables
 - 🎯 **Clean API** - Intuitive dual API (class-based + functional)
 - 📝 **Well Documented** - Complete JSDoc and examples
@@ -183,6 +183,24 @@ const ast = parseSource("2 + 3 * 4");
 // Returns: BinaryOp(+, NumberLiteral(2), BinaryOp(*, ...))
 ```
 
+#### `generate(node: ASTNode): string`
+
+Convert an AST node back to source code. Intelligently adds parentheses only when necessary to preserve semantics.
+
+```typescript
+import { generate, ast } from "littlewing";
+
+// From AST builders
+const expr = ast.multiply(ast.add(ast.number(2), ast.number(3)), ast.number(4));
+generate(expr); // → "(2 + 3) * 4"
+
+// Round-trip: parse → generate → parse
+const code = "2 + 3 * 4";
+const tree = parseSource(code);
+const regenerated = generate(tree); // → "2 + 3 * 4"
+parseSource(regenerated); // Same AST structure
+```
+
 ### Classes
 
 #### `Lexer`
@@ -219,6 +237,17 @@ const executor = new Executor(context);
 const result = executor.execute(ast);
 ```
 
+#### `CodeGenerator`
+
+Convert AST nodes back to source code. Handles operator precedence and associativity automatically.
+
+```typescript
+import { CodeGenerator } from "littlewing";
+
+const generator = new CodeGenerator();
+const code = generator.generate(ast);
+```
+
 ### AST Builders
 
 The `ast` namespace provides convenient functions for building AST nodes:
@@ -256,37 +285,6 @@ import { defaultContext } from "littlewing";
 (milliseconds, seconds, minutes, hours, days);
 ```
 
-## Type Definitions
-
-### ExecutionContext
-
-```typescript
-interface ExecutionContext {
-	functions?: Record<string, (...args: any[]) => number | Date>;
-	variables?: Record<string, number | Date>;
-}
-```
-
-### RuntimeValue
-
-```typescript
-type RuntimeValue = number | Date | unknown;
-```
-
-### ASTNode
-
-```typescript
-type ASTNode =
-	| Program
-	| NumberLiteral
-	| StringLiteral
-	| Identifier
-	| BinaryOp
-	| UnaryOp
-	| FunctionCall
-	| Assignment;
-```
-
 ## Examples
 
 ### Calculator
@@ -362,14 +360,14 @@ execute("kilometers(5)", context); // → 8.0467
 
 ### Bundle Size
 
-- Raw: 16.70 KB
-- Gzipped: **3.61 KB**
+- Raw: 21.06 KB
+- Gzipped: **4.26 KB**
 - Zero dependencies
 
 ### Test Coverage
 
-- 71 comprehensive tests
-- 97.66% code coverage
+- 106 comprehensive tests
+- 95.99% code coverage
 - All edge cases handled
 
 ## Type Safety
@@ -408,7 +406,3 @@ MIT
 ## Contributing
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
-
----
-
-Made with ❤️ by the littlewing team

package/dist/index.d.ts

@@ -176,6 +176,67 @@ declare function exponentiate(left: ASTNode, right: ASTNode): BinaryOp;
 */
 declare function negate(argument: ASTNode): UnaryOp;
 /**
+* CodeGenerator - converts AST nodes back to source code
+*/
+declare class CodeGenerator {
+	/**
+	* Generate source code from an AST node
+	*/
+	generate(node: ASTNode): string;
+	/**
+	* Generate code for a program (multiple statements)
+	*/
+	private generateProgram;
+	/**
+	* Generate code for a number literal
+	*/
+	private generateNumberLiteral;
+	/**
+	* Generate code for a string literal
+	*/
+	private generateStringLiteral;
+	/**
+	* Generate code for an identifier
+	*/
+	private generateIdentifier;
+	/**
+	* Generate code for a binary operation
+	*/
+	private generateBinaryOp;
+	/**
+	* Generate code for a unary operation
+	*/
+	private generateUnaryOp;
+	/**
+	* Generate code for a function call
+	*/
+	private generateFunctionCall;
+	/**
+	* Generate code for a variable assignment
+	*/
+	private generateAssignment;
+	/**
+	* Check if left operand needs parentheses based on operator precedence
+	* - For left-associative operators: parens only if strictly lower precedence
+	* - For right-associative operators (^): parens if lower or equal precedence
+	*/
+	private needsParensLeft;
+	/**
+	* Check if right operand needs parentheses based on operator precedence and associativity
+	* - For right-associative operators (^): parens if strictly lower precedence
+	* - For left-associative operators: parens if lower or equal precedence
+	*/
+	private needsParensRight;
+	/**
+	* Get precedence of an operator (higher number = higher precedence)
+	*/
+	private getPrecedence;
+}
+/**
+* Generate source code from an AST node
+*/
+declare function generate(node: ASTNode): string;
+/**
 * Default execution context with common Math functions and date utilities
 * Users can use this as-is or spread it into their own context
 *
@@ -368,4 +429,4 @@ declare class Parser {
 * Parse source code string into AST
 */
 declare function parseSource(source: string): ASTNode;
-export { parseSource, isUnaryOp, isStringLiteral, isProgram, isNumberLiteral, isIdentifier, isFunctionCall, isBinaryOp, isAssignment, execute, defaultContext, exports_ast as ast, TokenType, Token, RuntimeValue, Parser, Lexer, Executor, ExecutionContext, ASTNode };
+export { parseSource, isUnaryOp, isStringLiteral, isProgram, isNumberLiteral, isIdentifier, isFunctionCall, isBinaryOp, isAssignment, generate, execute, defaultContext, exports_ast as ast, TokenType, Token, RuntimeValue, Parser, Lexer, Executor, ExecutionContext, CodeGenerator, ASTNode };

package/dist/index.js

@@ -89,31 +89,6 @@ function exponentiate(left, right) {
 function negate(argument) {
   return unaryOp(argument);
 }
-// src/defaults.ts
-var defaultContext = {
-  functions: {
-    abs: Math.abs,
-    ceil: Math.ceil,
-    floor: Math.floor,
-    round: Math.round,
-    sqrt: Math.sqrt,
-    min: Math.min,
-    max: Math.max,
-    sin: Math.sin,
-    cos: Math.cos,
-    tan: Math.tan,
-    log: Math.log,
-    log10: Math.log10,
-    exp: Math.exp,
-    now: () => new Date,
-    date: (...args) => new Date(...args),
-    milliseconds: (ms) => ms,
-    seconds: (s) => s * 1000,
-    minutes: (m) => m * 60 * 1000,
-    hours: (h) => h * 60 * 60 * 1000,
-    days: (d) => d * 24 * 60 * 60 * 1000
-  }
-};
 // src/types.ts
 var TokenType;
 ((TokenType2) => {
@@ -157,6 +132,127 @@ function isProgram(node) {
   return node.type === "Program";
 }
 
+// src/codegen.ts
+class CodeGenerator {
+  generate(node) {
+    if (isProgram(node))
+      return this.generateProgram(node);
+    if (isNumberLiteral(node))
+      return this.generateNumberLiteral(node);
+    if (isStringLiteral(node))
+      return this.generateStringLiteral(node);
+    if (isIdentifier(node))
+      return this.generateIdentifier(node);
+    if (isBinaryOp(node))
+      return this.generateBinaryOp(node);
+    if (isUnaryOp(node))
+      return this.generateUnaryOp(node);
+    if (isFunctionCall(node))
+      return this.generateFunctionCall(node);
+    if (isAssignment(node))
+      return this.generateAssignment(node);
+    throw new Error(`Unknown node type`);
+  }
+  generateProgram(node) {
+    return node.statements.map((stmt) => this.generate(stmt)).join("; ");
+  }
+  generateNumberLiteral(node) {
+    return String(node.value);
+  }
+  generateStringLiteral(node) {
+    return `'${node.value}'`;
+  }
+  generateIdentifier(node) {
+    return node.name;
+  }
+  generateBinaryOp(node) {
+    const left = this.generate(node.left);
+    const right = this.generate(node.right);
+    const leftNeedsParens = this.needsParensLeft(node.left, node.operator);
+    const leftCode = leftNeedsParens ? `(${left})` : left;
+    const rightNeedsParens = this.needsParensRight(node.right, node.operator);
+    const rightCode = rightNeedsParens ? `(${right})` : right;
+    return `${leftCode} ${node.operator} ${rightCode}`;
+  }
+  generateUnaryOp(node) {
+    const arg = this.generate(node.argument);
+    const needsParens = isBinaryOp(node.argument) || isAssignment(node.argument);
+    const argCode = needsParens ? `(${arg})` : arg;
+    return `-${argCode}`;
+  }
+  generateFunctionCall(node) {
+    const args = node.arguments.map((arg) => this.generate(arg)).join(", ");
+    return `${node.name}(${args})`;
+  }
+  generateAssignment(node) {
+    const value = this.generate(node.value);
+    return `${node.name} = ${value}`;
+  }
+  needsParensLeft(node, operator) {
+    if (!isBinaryOp(node))
+      return false;
+    const nodePrecedence = this.getPrecedence(node.operator);
+    const operatorPrecedence = this.getPrecedence(operator);
+    if (operator === "^") {
+      return nodePrecedence <= operatorPrecedence;
+    }
+    return nodePrecedence < operatorPrecedence;
+  }
+  needsParensRight(node, operator) {
+    if (!isBinaryOp(node))
+      return false;
+    const nodePrecedence = this.getPrecedence(node.operator);
+    const operatorPrecedence = this.getPrecedence(operator);
+    if (operator === "^") {
+      return nodePrecedence < operatorPrecedence;
+    }
+    return nodePrecedence <= operatorPrecedence;
+  }
+  getPrecedence(operator) {
+    switch (operator) {
+      case "^":
+        return 4;
+      case "*":
+      case "/":
+      case "%":
+        return 3;
+      case "+":
+      case "-":
+        return 2;
+      default:
+        return 0;
+    }
+  }
+}
+function generate(node) {
+  const generator = new CodeGenerator;
+  return generator.generate(node);
+}
+// src/defaults.ts
+var defaultContext = {
+  functions: {
+    abs: Math.abs,
+    ceil: Math.ceil,
+    floor: Math.floor,
+    round: Math.round,
+    sqrt: Math.sqrt,
+    min: Math.min,
+    max: Math.max,
+    sin: Math.sin,
+    cos: Math.cos,
+    tan: Math.tan,
+    log: Math.log,
+    log10: Math.log10,
+    exp: Math.exp,
+    now: () => new Date,
+    date: (...args) => new Date(...args),
+    milliseconds: (ms) => ms,
+    seconds: (s) => s * 1000,
+    minutes: (m) => m * 60 * 1000,
+    hours: (h) => h * 60 * 60 * 1000,
+    days: (d) => d * 24 * 60 * 60 * 1000
+  }
+};
 // src/lexer.ts
 class Lexer {
   source;
@@ -692,11 +788,13 @@ export {
   isFunctionCall,
   isBinaryOp,
   isAssignment,
+  generate,
   execute,
   defaultContext,
   exports_ast as ast,
   TokenType,
   Parser,
   Lexer,
-  Executor
+  Executor,
+  CodeGenerator
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "littlewing",
-	"version": "0.2.0",
+	"version": "0.3.1",
 	"description": "A minimal, high-performance arithmetic expression language with lexer, parser, and executor. Optimized for browsers with zero dependencies and type-safe execution.",
 	"keywords": [
 		"arithmetic",