Making a Language: Using Spark

Tying everything together — the run function, complete Spark examples, and exercises for extending the language.

May 18, 2026#typescript#compilers

In the previous part, we built the evaluator. Now let's tie everything together.

The Public API

index.ts
export function run(source: string): { output: string[]; error?: string } {
  try {
    const tokens = tokenizeFn(source);
    setSource(source);
    const program = parseFn(tokens);
    return evaluateFn(program);
  } catch (e) {
    if (e instanceof ParseError || e instanceof RuntimeError) {
      return { output: [], error: e.format(source) };
    }
    throw e;
  }
}

run chains lexer to parser to evaluator. If a ParseError or RuntimeError is thrown, run catches it and formats the error with source context, showing the line and a pointer to the exact position.

index.ts
export function tokenize(source: string) {
  return tokenizeFn(source);
}

export function parse(tokens: ReturnType<typeof tokenizeFn>): Program {
  return parseFn(tokens);
}

export function evaluate(program: Program) {
  return evaluateFn(program);
}

export { formatValue };
export type { Program };

Each stage is also exported separately so the playground can use them independently for debugging or step-by-step execution.

Examples

Grade Calculator

1func average(nums) {
2  val sum = nums[0] + nums[1] + nums[2]
3  return sum / 3
4}
5
6val scores = [85, 92, 78]
7say("average:", average(scores))
8
9when (average(scores) >= 90) {
10  say("grade: A")
11} else when (average(scores) >= 80) {
12  say("grade: B")
13} else {
14  say("grade: C")
15}

Demonstrates arrays, function calls, and else when chaining.

String Utilities

1func greet(name) {
2  return "hello " + name + "!"
3}
4
5say(greet("alice"))
6
7func repeat(s, n) {
8  when (n <= 1) {
9    return s
10  }
11  return s + repeat(s, n - 1)
12}
13
14say(repeat("ha", 3))

Shows string concatenation and recursion. repeat calls itself until n reaches 1.

Todo Tracker

1val todos = []
2
3func add(text) {
4  todos = todos + [text]
5}
6
7add("write lexer")
8add("write parser")
9add("write evaluator")
10
11say("todos:")
12say(todos[0])
13say(todos[1])
14say(todos[2])

Uses the array + operator to append, and assignment to mutate a top-level variable.

Fibonacci

1func fib(n) {
2  when (n <= 1) {
3    return n
4  }
5  return fib(n - 1) + fib(n - 2)
6}
7
8say("fib(10) =", fib(10))

Two-branch recursion: each call spawns two more until the base case.

FizzBuzz

1func fizzbuzz(n) {
2  when (n == 0) {
3    return
4  }
5  when (n % 15 == 0) {
6    say("fizzbuzz")
7  } else when (n % 3 == 0) {
8    say("fizz")
9  } else when (n % 5 == 0) {
10    say("buzz")
11  } else {
12    say(n)
13  }
14  fizzbuzz(n - 1)
15}
16
17say(fizzbuzz(100))

Uses modulo and else when to check conditions in priority order.

Your Turn: Add Loops

I left loops out of Spark on purpose. Adding them is the best way to understand how all three layers fit together. You need one small change in each file:

Lexer. Add loop to the keywords map and Loop to the token enum:

lexer.ts
const KEYWORDS = {
  // ... existing keywords ...
  loop: TokenType.Loop,
};

types.ts
export enum TokenType {
  // ... existing tokens ...
  Loop,
}

Parser. Add a WhileStatement case. Check for the loop token, then parse the condition and body:

parser.ts
// In parseStatement(), add before the atEnd check:
if (this.match(TokenType.Loop)) return this.parseWhile();

// New method:
private parseWhile(): Statement {
  this.consume(TokenType.LParen, "Expected '(' after loop");
  const condition = this.parseExpression(0);
  this.consume(TokenType.RParen, "Expected ')' after loop condition");
  this.consume(TokenType.LBrace, "Expected '{' before loop body");
  const body = this.parseBlock();
  return { kind: "WhileStatement", condition, body };
}

Also add WhileStatement to the Statement type union in types.ts.

Evaluator. One small case in the statement switch:

evaluator.ts
case "WhileStatement":
  while (isTruthy(evaluateExpression(stmt.condition, env))) {
    evaluateBlock(stmt.body, env);
  }
  return { type: "null" };

Put it together and now Spark has loops:

1val i = 0
2loop (i < 5) {
3  say(i)
4  i = i + 1
5}

That's all it takes. Every feature follows the same recipe: a token in the lexer, a node in the parser, and a handler in the evaluator. Try it yourself. Break things. Change the syntax. Add features. Now that you know how the pieces fit together, you're not just a language user. You're a language designer.

The full source code for Spark is available on GitHub.

Spark Playground

// --- variables & reassignment ---
val greeting = "hello"
val name = "world"
say(greeting + " " + name)

val x = 10
x = x + 5
say("x after += 5:", x)

// --- arithmetic ---
say("10 + 3 =", 10 + 3)
say("10 - 3 =", 10 - 3)
say("10 * 3 =", 10 * 3)
say("10 / 3 =", 10 / 3)
say("10 % 3 =", 10 % 3)

// --- comparisons ---
say("10 == 10:", 10 == 10)
say("10 != 10:", 10 != 10)
say("10 < 3:", 10 < 3)
say("10 > 3:", 10 > 3)
say("10 <= 10:", 10 <= 10)
say("10 >= 11:", 10 >= 11)

// --- booleans & not ---
say("not yes:", not yes)
say("not no:", not no)
say("not 0:", not 0)
say("not 1:", not 1)
val empty_arr = []
say("not []:", not empty_arr)
say("not [1]:", not [1])

// --- nil ---
val n = nil
say("nil value:", n)
say("nil is falsy:", not n)

// --- conditionals ---
val score = 85
when (score >= 90) {
  say("grade: A")
} else when (score >= 80) {
  say("grade: B")
} else {
  say("grade: C")
}

// --- arrays & indexing ---
val nums = [10, 20, 30, 40, 50]
say("nums[0]:", nums[0])
say("nums[4]:", nums[4])
say("before set nums[2]", nums)
nums[2] = 99
say("after set nums[2] = 99:", nums)

// --- range operator ---
val r = 1..5
say("1..5:", r)

// --- functions & recursion ---
func factorial(n) {
  when (n <= 1) {
    return 1
  }
  return n * factorial(n - 1)
}
say("factorial(6):", factorial(6))

func fibonacci(n) {
  when (n <= 1) {
    return n
  }
  return fibonacci(n - 1) + fibonacci(n - 2)
}
say("fib(10):", fibonacci(10))

// --- variables & reassignment ---
val greeting = "hello"
val name = "world"
say(greeting + " " + name)

val x = 10
x = x + 5
say("x after += 5:", x)

// --- arithmetic ---
say("10 + 3 =", 10 + 3)
say("10 - 3 =", 10 - 3)
say("10 * 3 =", 10 * 3)
say("10 / 3 =", 10 / 3)
say("10 % 3 =", 10 % 3)

// --- comparisons ---
say("10 == 10:", 10 == 10)
say("10 != 10:", 10 != 10)
say("10 < 3:", 10 < 3)
say("10 > 3:", 10 > 3)
say("10 <= 10:", 10 <= 10)
say("10 >= 11:", 10 >= 11)

// --- booleans & not ---
say("not yes:", not yes)
say("not no:", not no)
say("not 0:", not 0)
say("not 1:", not 1)
val empty_arr = []
say("not []:", not empty_arr)
say("not [1]:", not [1])

// --- nil ---
val n = nil
say("nil value:", n)
say("nil is falsy:", not n)

// --- conditionals ---
val score = 85
when (score >= 90) {
  say("grade: A")
} else when (score >= 80) {
  say("grade: B")
} else {
  say("grade: C")
}

// --- arrays & indexing ---
val nums = [10, 20, 30, 40, 50]
say("nums[0]:", nums[0])
say("nums[4]:", nums[4])
say("before set nums[2]", nums)
nums[2] = 99
say("after set nums[2] = 99:", nums)

// --- range operator ---
val r = 1..5
say("1..5:", r)

// --- functions & recursion ---
func factorial(n) {
  when (n <= 1) {
    return 1
  }
  return n * factorial(n - 1)
}
say("factorial(6):", factorial(6))

func fibonacci(n) {
  when (n <= 1) {
    return n
  }
  return fibonacci(n - 1) + fibonacci(n - 2)
}
say("fib(10):", fibonacci(10))

Output

Press Run or ⌘⏎ to execute