@mojir/lits 2.1.32 → 2.1.34

package/README.md

@@ -1,6 +1,6 @@
 # Lits
 
-Lits is a lexically scoped pure functional language with algebraic notation. It combines the power of functional programming with an intuitive, readable syntax.
+Lits is a lexically scoped pure functional language with algebraic notation. It combines the power of functional programming with an intuitive, readable syntax that makes complex operations simple and expressive.
 
 Try it in the [Lits Playground](https://mojir.github.io/lits/).
 
@@ -10,50 +10,80 @@ Try it in the [Lits Playground](https://mojir.github.io/lits/).
 - **JavaScript interoperability** - JavaScript values and functions can easily be exposed in Lits
 - **First-class functions** - Functions are treated as values that can be passed to other functions
 - **Algebraic notation** - All operators can be used as functions, and functions that take two parameters can be used as operators
-- **Clojure-inspired functions** - Most core functions are inspired by Clojure
 - **Comprehensive standard library** - Rich set of functions for collections, math, strings, and more
 - **Structural equality** - Objects are compared by value, not by reference
 - **Destructuring** - Extract values from complex data structures with ease
+- **Lexical scoping** - Variables are scoped to their defining context
 
 ## Installation
 
-*[Add installation instructions here]*
+### As a Library
+
+```bash
+npm install @mojir/lits
+```
+
+### CLI Tool
+
+Install globally to use the Lits command-line interface:
+
+```bash
+npm install --global @mojir/lits
+```
+
+#### CLI Usage
+
+```bash
+# Start an interactive REPL session
+$ lits
+
+# Evaluate Lits code directly
+$ lits -e "5 + 3"
+$ lits -e "[1, 2, 3, 4] filter odd? map inc"
+
+# Run a Lits file
+$ lits -f script.lits
+$ lits -f examples/factorial.lits
+
+# Get help
+$ lits --help
+```
+
+The REPL provides an interactive environment where you can experiment with Lits code, test functions, and explore the language features in real-time.
 
 ## Quick Start
 
 Here's a simple example to get you started:
 
-```
+```lits
 // Defining a function
-function square(x)
-  x * x
-end;
+let square = x -> x * x;
 
 // Using the function
-let result := square(5);
+let result = square(5);
 // => 25
 
 // Using function as an operator
-let squares := [1, 2, 3, 4, 5] map square;
+let squares = [1, 2, 3, 4, 5] map square;
 // => [1, 4, 9, 16, 25]
 
 // Using operator as a function
-let sum := +([1, 2, 3, 4, 5]);
+let sum = +([1, 2, 3, 4, 5]);
 // => 15
 ```
 
-## Syntax
+## Basic Syntax
 
-### Basic Data Types
+### Data Types
 
-```
+```lits
 // Numbers
-42       // integer
-3.14     // float
-0xFFFF   // hexadecimal
-0b1100   // binary
-0o77     // octal
--2.3e-2  // scientific notation
+42          // integer
+3.14        // float
+0xFFFF      // hexadecimal
+0b1100      // binary
+0o77        // octal
+-2.3e-2     // scientific notation
 
 // Strings
 "Hello, world!"
@@ -69,356 +99,661 @@ null
 [1, 2, 3, 4]
 
 // Objects
-{ name := "John", age := 30 }
+{ name: "John", age: 30 }
+
+// Regular expressions
+#"pattern"
 ```
 
-### Builtin Number Symbols
+### Mathematical Constants
 
-Lits provides a set of predefined mathematical constants that can be used directly in your code:
+Lits provides predefined mathematical constants:
 
-```
-// Mathematical constants
+```lits
 PI    // => 3.141592653589793
 π     // => 3.141592653589793 (Unicode alternative)
--PI   // => -3.141592653589793
--π    // => -3.141592653589793
-
 E     // => 2.718281828459045 (Euler's number)
 ε     // => 2.718281828459045 (Unicode alternative)
--E    // => -2.718281828459045
--ε    // => -2.718281828459045
-
 PHI   // => 1.618033988749895 (Golden ratio)
 φ     // => 1.618033988749895 (Unicode alternative)
--PHI  // => -1.618033988749895
--φ    // => -1.618033988749895
 
 // Infinity values
 POSITIVE_INFINITY // => Infinity
 ∞     // => Infinity (Unicode alternative)
 NEGATIVE_INFINITY // => -Infinity
--∞    // => -Infinity (Unicode alternative)
 
-// Integer limits
+// Integer and float limits
 MAX_SAFE_INTEGER  // => 9007199254740991
 MIN_SAFE_INTEGER  // => -9007199254740991
-
-// Floating point limits
-MAX_VALUE  // => 1.7976931348623157e+308
-MIN_VALUE  // => 5e-324
+MAX_VALUE         // => 1.7976931348623157e+308
+MIN_VALUE         // => 5e-324
 
 // Not a Number
 NaN  // => NaN
 ```
 
-These constants can be used anywhere a number value is expected and help make mathematical code more readable and elegant.
+## Special Expressions
 
 ### Variable Binding
 
-```
-// Let expression
-let x := 10;
+#### Let
+
+```lits
+// Simple binding
+let x = 10;
 // => 10
 
 // Variables are immutable
-let x := 20; // Error: x is already defined
+let x = 20; // Error: x is already defined
 
-// But can be shadowed in inner scopes
-let y := do
-  let x := 20;
+// Shadowing in inner scopes
+let y = {
+  let x = 20;
   x
-end;
+};
 // => 20, outer x is still 10
 ```
 
-### Functions
+#### Destructuring
+
+```lits
+// Object destructuring
+let { name, age } = { name: "John", age: 30 };
+// name => "John", age => 30
 
+// Array destructuring
+let [first, second] = [1, 2, 3, 4];
+// first => 1, second => 2
+
+// With default values
+let { name = "Unknown", age = 0 } = { name: "John" };
+// name => "John", age => 0
+
+// Rest patterns
+let [head, ...tail] = [1, 2, 3, 4];
+// head => 1, tail => [2, 3, 4]
+
+// Destructuring in function parameters
+let displayPerson = ({name, age}) ->
+  name ++ " is " ++ str(age) ++ " years old";
+
+displayPerson({ name: "John", age: 30 });
+// => "John is 30 years old"
 ```
-// Standard function definition
-function add(a, b)
-  a + b
-end;
 
-// Lambda functions
-let add := (a, b) -> a + b;
+### Functions
+
+#### Lambda Functions
+
+```lits
+// Multi-parameter lambda
+let add = (a, b) -> a + b;
 
-// Short form with positional arguments
-let add := -> $1 + $2;
+// Single parameter (parentheses optional)
+let square = x -> x * x;
 
-// Single argument short form
-let cube := x -> x ** 3;
-let fourth := -> $ ** 4;
+// No parameters
+let constant = () -> 42;
+
+// Positional arguments
+let add = -> $1 + $2;
+
+// Single positional argument
+let square = -> $ * $;
+
+// Self-reference for recursion
+let factorial = n ->
+  if n <= 1 then
+    1
+  else
+    n * self(n - 1)
+  end;
 ```
 
 ### Control Flow
 
-```
+#### If/Unless
+
+```lits
 // If expression
 if x > 10 then
   "large"
 else
   "small"
-end;
+end
 // => "large" (if x > 10) or "small" (if x <= 10)
 
-// Unless expression (reversed if)
+// If without else returns null
+if false then "never" end
+// => null
+
+// Unless (inverted if)
 unless x > 10 then
   "small"
 else
   "large"
-end;
+end
 // => "small" (if x <= 10) or "large" (if x > 10)
+```
+
+#### Cond
+
+```lits
+// Multi-branch conditional
+cond
+  case x < 5 then "small"
+  case x < 10 then "medium"
+  case x < 15 then "large"
+end ?? "extra large"
+// Tests conditions sequentially, returns first truthy match
+```
 
-// Switch expression
+#### Switch
+
+```lits
+// Switch on value
 switch x
   case 0 then "zero"
   case 1 then "one"
   case 2 then "two"
-end;
-// => "zero" (if x = 0), "one" (if x = 1), "two" (if x = 2), or null (otherwise)
+end
+// => "zero" (if x = 0), "one" (if x = 1), etc., or null if no match
+```
 
-// Cond expression
-cond
-  case val < 5 then "S"
-  case val < 10 then "M"
-  case val < 15 then "L"
-end ?? "No match";
-// => "S" (if val < 5), "M" (if 5 <= val < 10), "L" (if 10 <= val < 15), or "No match" (otherwise)
+### Loops and Iteration
+
+#### For Comprehensions
+
+```lits
+// Simple iteration
+for (x in [1, 2, 3, 4]) -> x * 2
+// => [2, 4, 6, 8]
+
+// With filtering
+for (x in [1, 2, 3, 4] when odd?(x)) -> x * 2
+// => [2, 6]
+
+// With while condition
+for (x in [1, 2, 3, 4] while x < 3) -> x * 2
+// => [2, 4]
+
+// With let bindings
+for (x in [1, 2, 3] let doubled = x * 2) -> doubled + 1
+// => [3, 5, 7]
+
+// Multiple iterators
+for (x in [1, 2], y in [10, 20]) -> x + y
+// => [11, 21, 12, 22]
 
-// Try/catch
+// Object iteration
+for ([key, value] in { a: 1, b: 2 }) -> key ++ ":" ++ str(value)
+// => ["a:1", "b:2"]
+```
+
+#### Doseq (Side Effects)
+
+```lits
+// For side effects only (returns null)
+doseq (x in [1, 2, 3]) -> write!(x)
+// Prints: 1 2 3, returns null
+```
+
+#### Loop (Tail Recursion)
+
+```lits
+// Loop with recur for tail recursion
+loop (n = 5, acc = 1) -> {
+  if zero?(n) then
+    acc
+  else
+    recur(n - 1, acc * n)
+  end
+}
+// => 120 (factorial of 5)
+```
+
+### Error Handling
+
+#### Try/Catch
+
+```lits
+// Basic try/catch
+try
+  riskyOperation()
+catch
+  "Something went wrong"
+end
+
+// With error binding
 try
   riskyOperation()
 catch (error)
   "Error: " ++ error.message
-end;
-// => result of riskyOperation() or error message if an exception occurs
+end
 ```
 
-### List Comprehension
+#### Throw
+
+```lits
+// Throwing errors
+throw("Custom error message")
 
+// In context
+let divide = (a, b) ->
+  if zero?(b) then
+    throw("Division by zero")
+  else
+    a / b
+  end;
 ```
-// Simple for comprehension
-for
-  each x of [0, 1, 2, 3, 4, 5], let y := x * 3, while even?(y)
-do
-  y
-end;
-// => [0, 6, 12]
 
-// Multiple generators
-for (
-  each x of [1, 2, 3]
-  each y of [1, 2, 3], when x <= y
-  z of [1, 2, 3]
-)
-  [x, y, z]
-end;
-// => [[1, 1, 1], [1, 1, 2], [1, 1, 3], [1, 2, 1], [1, 2, 2], [1, 2, 3], [1, 3, 1], [1, 3, 2], [1, 3, 3], 
-//     [2, 2, 1], [2, 2, 2], [2, 2, 3], [2, 3, 1], [2, 3, 2], [2, 3, 3], 
-//     [3, 3, 1], [3, 3, 2], [3, 3, 3]]
+### Logical Operators
+
+#### And/Or
+
+```lits
+// Logical AND (short-circuit)
+true && "second value"   // => "second value"
+false && "never reached" // => false
+
+// Logical OR (short-circuit)
+false || "default value" // => "default value"
+true || "never reached"  // => true
+
+// Multiple arguments
+&&(true, true, "all true") // => "all true"
+||(false, false, "found")  // => "found"
 ```
 
-### Destructuring
+#### Null Coalescing
 
+```lits
+// Null coalescing operator
+null ?? "default"     // => "default"
+undefined ?? "default" // => "default"
+0 ?? "default"        // => 0 (only null/undefined are coalesced)
+false ?? "default"    // => false
+"" ?? "default"       // => ""
 ```
-// Object destructuring
-let { name, age } := { name := "John", age := 30 };
-// name => "John"
-// age => 30
 
-// Array destructuring
-let [nbr1, nbr2] := [1, 2, 3, 4];
-// nbr1 => 1
-// nbr2 => 2
+### Blocks
 
-// Destructuring in function parameters
-function displayPerson({name, age})
-  name ++ " is " ++ str(age) ++ " years old"
-end;
+```lits
+// Block expressions
+{
+  let a = 1 + 2 + 3;
+  let b = x -> x * x;
+  b(a)
+}
+// => 36 (returns value of last expression)
+```
 
-displayPerson({ name := "John", age := 30 });
-// => "John is 30 years old"
+### Arrays and Objects
+
+#### Array Construction
+
+```lits
+// Array literal
+[1, 2, 3, 4]
+
+// Array function
+array(1, 2, 3, 4)
+
+// With spread
+[1, 2, ...[3, 4, 5], 6]
+// => [1, 2, 3, 4, 5, 6]
+```
+
+#### Object Construction
+
+```lits
+// Object literal
+{ name: "John", age: 30 }
+
+// Object function
+object("name", "John", "age", 30)
+
+// With spread
+let defaults = { type: "Person", active: true };
+{
+  ...defaults,
+  name: "John",
+  age: 30
+}
+// => { type: "Person", active: true, name: "John", age: 30 }
+```
+
+### Recursion
+
+#### Recur
+
+```lits
+// Tail recursion with recur
+let countdown = n -> {
+  write!(n);
+  if pos?(n) then
+    recur(n - 1)
+  end
+};
+
+countdown(3)
+// Prints: 3 2 1 0
 ```
 
 ## Operators and Functions
 
-### Function Usage vs Operator Usage
+### Algebraic Notation
 
 All functions that take two parameters can be used as operators:
 
-```
+```lits
 // As a function
-max(5, 10);
-// => 10
+max(5, 10)    // => 10
 
 // As an operator
-5 max 10;
-// => 10
+5 max 10      // => 10
 ```
 
 All operators can be used as functions:
 
-```
+```lits
 // As an operator
-5 + 3;
-// => 8
+5 + 3         // => 8
 
 // As a function
-+(5, 3);
-// => 8
-```
++(5, 3)       // => 8
 
-### Parameter Order
+// Partial application with underscore placeholder
+let add5 = +(5, _);
+add5(3)       // => 8
 
-Unlike Clojure, Lits favors subject-first parameter order:
+// Multiple placeholders
+let subtractAndDivide = /(-(_, _), 2);
+subtractAndDivide(10, 3)  // => 3.5 (10 - 3 = 7, then 7 / 2 = 3.5)
 
-```
-// Lits
-filter([1, 2, 3, 4], odd?);
-// => [1, 3]
+// Single placeholder in different positions
+let subtract = -(_, 2);
+subtract(10)  // => 8
 
-// Equivalent Clojure
-// (filter odd? [1 2 3 4])
+let divide = /(10, _);
+divide(2)     // => 5
 ```
 
-This makes operator usage more readable:
+### Parameter Order
 
-```
-[1, 2, 3, 4] filter odd?;
-// => [1, 3]
-```
+Lits favors subject-first parameter order for better operator chaining:
 
-## Built-in Functions
+```lits
+// Function style
+filter([1, 2, 3, 4], odd?)  // => [1, 3]
+
+// Operator style (more readable)
+[1, 2, 3, 4] filter odd?    // => [1, 3]
 
-Lits comes with a comprehensive standard library of functions organized into categories:
+// Chaining
+[1, 2, 3, 4, 5, 6]
+  filter odd?
+  map square
+  reduce +
+// => 35
+```
 
-### Collection Functions
-`count`, `get`, `get-in`, `contains?`, `assoc`, `assoc-in`, `++`, `not-empty`, `every?`, `not-every?`, `any?`, `not-any?`, `update`, `update-in`
+### Pipe Operator
 
-### Array Functions
-`array`, `range`, `repeat`, `flatten`, `mapcat`
+The pipe operator `|>` passes the result of the left expression as the first argument to the right function:
 
-### Sequence Functions
-`nth`, `push`, `pop`, `unshift`, `shift`, `slice`, `splice`, `reductions`, `reduce`, `reduce-right`, `map`, `filter`, `position`, `index-of`, `last-index-of`, `some`, `reverse`, `first`, `second`, `last`, `rest`, `next`, `take`, `take-last`, `take-while`, `drop`, `drop-last`, `drop-while`, `sort`, `sort-by`, `distinct`, `remove`, `remove-at`, `split-at`, `split-with`, `frequencies`, `group-by`, `partition`, `partition-all`, `partition-by`, `starts-with?`, `ends-with?`, `interleave`, `interpose`
+```lits
+// Without pipe operator
+reduce(map(filter([1, 2, 3, 4, 5, 6], odd?), square), +)
 
-### Math Functions
-`+`, `-`, `*`, `/`, `mod`, `%`, `quot`, `inc`, `dec`, `√`, `∛`, `**`, `round`, `trunc`, `floor`, `ceil`, `min`, `max`, `abs`, `sign`, `log`, `log2`, `log10`, `sin`, `cos`, `tan`, `asin`, `acos`, `atan`, `sinh`, `cosh`, `tanh`, `asinh`, `acosh`, `atanh`
+// With pipe operator (much more readable)
+[1, 2, 3, 4, 5, 6]
+  |> filter(_, odd?)
+  |> map(_, square)
+  |> reduce(_, +)
+// => 35
 
-### Functional Programming
-`apply`, `identity`, `partial`, `comp`, `constantly`, `juxt`, `complement`, `every-pred`, `some-pred`, `fnull`
+// Simple transformations
+"hello world"
+  |> upper-case
+  |> split(_, " ")
+  |> reverse
+  |> join(_, "-")
+// => "WORLD-HELLO"
 
-### Object Functions
-`dissoc`, `object`, `keys`, `vals`, `entries`, `find`, `merge`, `merge-with`, `zipmap`, `select-keys`
+// Mathematical operations
+10
+  |> +(_, 5)
+  |> *(_, 2)
+  |> /(_, 3)
+// => 10 (10 + 5 = 15, 15 * 2 = 30, 30 / 3 = 10)
 
-### String Functions
-`string-repeat`, `str`, `number`, `lower-case`, `upper-case`, `trim`, `trim-left`, `trim-right`, `pad-left`, `pad-right`, `split`, `split-lines`, `template`, `to-char-code`, `from-char-code`, `encode-base64`, `decode-base64`, `encode-uri-component`, `decode-uri-component`, `join`, `capitalize`, `blank?`
+// Data processing pipeline
+{ numbers: [1, 2, 3, 4, 5], multiplier: 3 }
+  |> get(_, "numbers")
+  |> filter(_, even?)
+  |> map(_, *(_, 3))
+  |> reduce(_, +)
+// => 18 (even numbers [2, 4] -> [6, 12] -> sum = 18)
+```
 
-### Predicates
-`boolean?`, `null?`, `number?`, `string?`, `function?`, `integer?`, `array?`, `object?`, `coll?`, `seq?`, `regexp?`, `zero?`, `pos?`, `neg?`, `even?`, `odd?`, `finite?`, `nan?`, `negative-infinity?`, `positive-infinity?`, `false?`, `true?`, `empty?`, `not-empty?`
+## Built-in Functions
 
-### Regular Expressions
-`regexp`, `match`, `replace`, `replace-all`
+Lits comes with a comprehensive standard library of functions for:
 
-### Bitwise Operations
-`<<`, `>>`, `>>>`, `~`, `&`, `bit-and-not`, `|`, `^`, `bit-flip`, `bit-clear`, `bit-set`, `bit-test`
+- **Arithmetic and Math**: Basic operations, trigonometry, logarithms, rounding
+- **Collections**: Working with arrays and objects (get, assoc, merge, etc.)
+- **Sequences**: Filtering, mapping, reducing, sorting, and transforming data
+- **Strings**: Manipulation, formatting, encoding, and pattern matching
+- **Predicates**: Type checking and condition testing functions
+- **Functional Programming**: Function composition, partial application, and utilities
+- **Regular Expressions**: Pattern matching and text processing
+- **Bitwise Operations**: Low-level bit manipulation
+- **Assertions**: Testing and validation utilities
 
-### Assertions
-`assert`, `assert=`, `assert!=`, `assert-gt`, `assert-lt`, `assert-gte`, `assert-lte`, `assert-true`, `assert-false`, `assert-truthy`, `assert-falsy`, `assert-null`, `assert-throws`, `assert-throws-error`, `assert-not-throws`
+For a complete reference of all available functions with examples, visit the [Lits Playground](https://mojir.github.io/lits/) where you can explore the interactive documentation and try functions in real-time.
 
 ## Modules and Exports
 
-You can export definitions to make them available to other modules:
+```lits
+// Export variables and functions
+export let PI = 3.14159;
+export let square = x -> x * x;
 
+// Exported values become available to other modules
 ```
-// Exporting variables
-export let magic-number := 42;
-// => 42
 
-// Exporting functions
-export function square(x)
-  x * x
-end;
-```
+## Examples
 
-## API
+### Factorial
 
-Lits provides a JavaScript API for embedding:
+```lits
+let factorial = n ->
+  if n <= 1 then
+    1
+  else
+    n * self(n - 1)
+  end;
 
-```javascript
-interface Lits {
-  getRuntimeInfo: () => LitsRuntimeInfo
-  run: (program: string, params?: ContextParams & FilePathParams) => unknown
-  context: (programOrAst: string | Ast, params?: ContextParams & FilePathParams) => Context
-  getUndefinedSymbols: (programOrAst: string | Ast, params: ContextParams) => Set<string>
-  tokenize: (program: string, tokenizeParams: FilePathParams & MinifyParams) => TokenStream
-  parse: (tokenStream: TokenStream) => Ast
-  evaluate: (ast: Ast, params: ContextParams) => unknown
-  transformSymbols: (tokenStream: TokenStream, transformer: (symbol: string) => string) => TokenStream
-  untokenize: (tokenStream: TokenStream) => string
-  apply: (fn: LitsFunction, fnParams: unknown[], params: ContextParams) => unknown
-}
+factorial(5)  // => 120
 ```
 
-## Examples
+### Array Processing
 
-### Factorial Function
+```lits
+let numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
 
-```
-function factorial(n)
-  if n <= 1 then
-    1
-  else
-    n * factorial(n - 1)
-  end
-end;
+// Get even numbers squared
+let evenSquares = numbers
+  filter even?
+  map square;
+// => [4, 16, 36, 64, 100]
 
-factorial(5);
-// => 120
+// Sum of odd numbers
+let oddSum = numbers
+  filter odd?
+  reduce +;
+// => 25
 ```
 
-### Fibonacci Sequence
+### Object Manipulation
+
+```lits
+let person = { name: "John", age: 30, city: "New York" };
 
+// Update age
+let older = assoc(person, "age", 31);
+
+// Add new field
+let withJob = assoc(older, "job", "Developer");
+
+// Using pipe operator for chaining
+let updated = person
+  |> assoc(_, "age", 31)
+  |> assoc(_, "job", "Developer");
 ```
-function fib(n)
-  if n < 2 then
-    n
-  else
-    fib(n - 1) + fib(n - 2)
-  end
-end;
 
-// Generate the first 10 Fibonacci numbers
-range(10) map fib;
-// => [0, 1, 1, 2, 3, 5, 8, 13, 21, 34]
+### Pattern Matching Examples
+
+#### Switch (for matching against a single value)
+
+```lits
+let gradeToLetter = grade ->
+  switch grade
+    case 90 then "A"
+    case 80 then "B" 
+    case 70 then "C"
+    case 60 then "D"
+  end ?? "F";
+
+gradeToLetter(80)  // => "B"
+gradeToLetter(55)  // => "F"
+
+// HTTP status code handling
+let statusMessage = code ->
+  switch code
+    case 200 then "OK"
+    case 404 then "Not Found"
+    case 500 then "Internal Server Error"
+  end ?? "Unknown Status";
 ```
 
-### Working with Collections
+#### Cond (for testing different conditions)
+
+```lits
+let describe = x ->
+  cond
+    case null?(x) then "nothing"
+    case number?(x) then "a number: " ++ str(x)
+    case string?(x) then "text: " ++ x
+    case array?(x) then "list of " ++ str(count(x)) ++ " items"
+  end ?? "unknown type";
+
+describe(42)     // => "a number: 42"
+describe([1,2,3]) // => "list of 3 items"
 
+// Grade ranges
+let gradeToLetter = score ->
+  cond
+    case score >= 90 then "A"
+    case score >= 80 then "B"
+    case score >= 70 then "C"
+    case score >= 60 then "D"
+  end ?? "F";
+
+gradeToLetter(85)  // => "B"
+gradeToLetter(55)  // => "F"
 ```
-let people := [
-  { name := "Alice", age := 25 },
-  { name := "Bob", age := 30 },
-  { name := "Charlie", age := 35 },
-  { name := "Diana", age := 40 }
-];
 
-// Get all names
-people map (p -> p.name);
-// => ["Alice", "Bob", "Charlie", "Diana"]
+## JavaScript Interoperability
 
-// Get people older than 30
-people filter (p -> p.age > 30);
-// => [{ name := "Charlie", age := 35 }, { name := "Diana", age := 40 }]
+Lits provides a comprehensive JavaScript API for embedding and integration:
 
-// Calculate average age
-(people map (p -> p.age) reduce +) / count(people);
-// => 32.5
+```javascript
+import { Lits } from 'lits';
+
+// Create a Lits instance
+const lits = new Lits();
+
+// Run Lits code
+const result = lits.run('+(5, 3)');
+console.log(result); // 8
+
+// Pass JavaScript values to Lits
+const result2 = lits.run('name ++ " is " ++ str(age)', {
+  values: {
+    name: "John",
+    age: 30
+  }
+});
+console.log(result2); // "John is 30"
+
+// Expose JavaScript functions to Lits
+const result3 = lits.run('myAlert("Hello from Lits!")', {
+  jsFunctions: {
+    myAlert: {
+      fn: (message) => console.log(`Alert: ${message}`),
+      arity: { min: 1, max: 1 }
+    }
+  }
+});
+
+// Parse and evaluate separately for better performance
+const tokens = lits.tokenize('+(5, 3)');
+const ast = lits.parse(tokens);
+const result4 = lits.evaluate(ast, {});
+```
+
+### Lits Class Methods
+
+```typescript
+interface Lits {
+  // Execute Lits code directly
+  run(program: string, params?: ContextParams & FilePathParams): unknown
+  
+  // Get execution context after running code
+  context(programOrAst: string | Ast, params?: ContextParams & FilePathParams): Context
+  
+  // Find undefined symbols in code
+  getUndefinedSymbols(programOrAst: string | Ast, params?: ContextParams): Set<string>
+  
+  // Parse pipeline
+  tokenize(program: string, params?: FilePathParams & MinifyParams): TokenStream
+  parse(tokenStream: TokenStream): Ast
+  evaluate(ast: Ast, params: ContextParams): unknown
+  
+  // Apply Lits function with JavaScript arguments
+  apply(fn: LitsFunction, fnParams: unknown[], params?: ContextParams): unknown
+  
+  // Utility methods
+  transformSymbols(tokenStream: TokenStream, transformer: (symbol: string) => string): TokenStream
+  untokenize(tokenStream: TokenStream): string
+  getRuntimeInfo(): LitsRuntimeInfo
+}
 ```
 
-## Contributing
+### Context Parameters
+
+```typescript
+interface ContextParams {
+  globalContext?: Context          // Global variable context
+  contexts?: Context[]             // Additional context layers
+  values?: Record<string, unknown> // JavaScript values to expose
+  jsFunctions?: Record<string, JsFunction> // JavaScript functions to expose
+  globalModuleScope?: boolean      // Module scoping behavior
+}
+
+interface JsFunction {
+  fn: (...args: any[]) => unknown // The JavaScript function
+  arity?: Arity                   // Function arity constraints
+  docString?: string              // Documentation
+}
+```
 
-*[Add contribution guidelines here]*
+## Learn More
 
-## License
+- Try Lits in the [online playground](https://mojir.github.io/lits/)
+- Explore the comprehensive function reference
+- Check out more complex examples in the documentation
 
-*[Add license information here]*
+Lits combines the elegance of functional programming with practical syntax, making it perfect for data transformation, mathematical computation, and any scenario where immutability and expressiveness are valued.