██████╗ ███████╗███╗   ██╗███████╗
██╔══██╗██╔════╝████╗  ██║╚══███╔╝
██████╔╝█████╗  ██╔██╗ ██║  ███╔╝
██╔══██╗██╔══╝  ██║╚██╗██║ ███╔╝  
██████╔╝███████╗██║ ╚████║███████╗
╚═════╝ ╚══════╝╚═╝  ╚═══╝╚══════╝

benz

benz is a small, focused, in-memory graph query execution engine written in TypeScript.

It implements a lazy, interpreter-driven execution model inspired by real database engines and graph traversal systems.

This is not a database server. This is the core execution engine databases are built on.

---

What it implements

• Directed graph with index-free adjacency

• Vertices owning both incoming and outgoing edges

• Lazy, pull-based query execution (Volcano model)

• Explicit interpreter with a program counter

• Gremlin-style traversal using execution tokens

• Composable pipetypes:

  • vertex
  • in
  • out
  • filter
  • unique
  • take

• Deterministic, resumable queries

• Query plan inspection via explain()

No external runtime dependencies.

---

How to run

Run the demo

From the repository root:

npm install
npm run demo

You should see output demonstrating:

• Graph structure validation (vertices and edges)
• Query plans printed via explain()
• Lazy execution producing results on first run
• Empty results on subsequent runs

This confirms that queries are stateful and consumed lazily.

---

Example query

Query the owner of a performance car variant:

vertex("911 GT3 RS")
→ out("variant-of")
→ out("variant-of")
→ out("model-of")
→ out("owned-by")
→ take(1)

This query:

• Starts execution from the last operator
• Pulls data backward through the pipeline
• Stops immediately after producing one result

Calling run() again returns an empty result.

This is intentional.

---

Explain a query

Every query can be inspected before execution:

query.explain()

Example output:

BENZ QUERY PLAN

0 | vertex("911 GT3 RS")
1 | out("variant-of")
2 | out("variant-of")
3 | out("model-of")
4 | out("owned-by")
5 | take(1)

Execution model

• Lazy, pull-based
• Interpreter-driven
• Gremlin pipeline

No optimizer magic. Nothing hidden.

---

Mental model

• Vertices store edges directly
• Edges are pointers, not lookups
• Gremlins move through the graph
• Pipetypes transform gremlins
• Control flows backward, data flows forward

If this engine makes sense to you, SQL execution plans stop feeling opaque.

---

Run tests

From the repository root:

npm run build

This type-checks the entire engine and demo.

---

Why this exists

benz exists to make execution models concrete.

It is designed for:

• learning
• experimentation
• building higher-level systems on top

---

Status

benz is complete as a core engine.

Future work belongs on top of it, not inside it:

• persistence layers
• planners and optimizers
• aliases and macros

---