iTranslated by AI

The content below is an AI-generated translation. This is an experimental feature, and may contain errors. View original article
📊

Learning KurrentDB Projections with a Household Account Book: Always-On Server-Side Computation in Rust and TypeScript

に公開
2026/02/24

Introduction

In my previous article, I built a household account book CLI using Event Sourcing, but every time I checked the balance, I had to re-read and recalculate all events.

income alice 100000 salary
income alice 50000 bonus
expense alice 30000 food lunch
expense alice 25000 food dinner
...
balance alice  ← Reads all events here and calculates (slow)

As the number of events increases, it gets slower.
That's painful.

KurrentDB has a feature called Projection, a mechanism to constantly run JavaScript on the server side and store the aggregated results.
By using this, I can fetch the results instantly with get_state.

In this article, I will introduce how to add Projections to the Event Sourcing household account book CLI and implement balance tracking, category aggregation, and budget-exceeding alerts.

Overview

Before:
  income/expense → Append to KurrentDB
  balance        → Re-read all events and calculate (slow)

After:
  income/expense → Append to KurrentDB
  balance        → Projection constantly calculates in the background → Get instantly with get_state (fast)
  stats          → Category-based aggregation and summary are provided by Projection
  alert          → Projection emits to a separate stream when the budget is exceeded → Monitored via subscribe

Projection executes JavaScript using KurrentDB's built-in V8 engine.
It is limited to JavaScript, not SQL or a custom DSL.
I have documented my investigation in VERIFY_QUERY.md and the verification results in VERIFY_RESULT.md within this branch.

I adopted a structure where I write in TypeScript with type safety, compile it to ES5, and embed it into the Rust binary using include_str!().

projections/*.ts → tsc → projections/dist/*.js → include_str!() → Rust binary

Environment

# Cargo.toml
[dependencies]
kurrentdb = "1.0.0"
clap = { version = "4", features = ["derive"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
tokio = { version = "1", features = ["full"] }
# docker-compose.yml
services:
  kurrentdb:
    image: eventstore/eventstore:23.10.2-alpha-arm64v8
    container_name: kurrentdb
    ports:
      - "2113:2113"
    environment:
      - EVENTSTORE_INSECURE=true
      - EVENTSTORE_RUN_PROJECTIONS=All
      - EVENTSTORE_START_STANDARD_PROJECTIONS=true
    volumes:
      - kurrentdb-data:/var/lib/eventstore

volumes:
  kurrentdb-data:

EVENTSTORE_START_STANDARD_PROJECTIONS=true is the key point.
To use fromCategory(), KurrentDB's standard projections (like $by_category) must be running.

Writing Projections in TypeScript

types.d.ts — Creating type definitions from scratch

KurrentDB does not officially provide TypeScript type definitions for Projections (Issue #1805).
Since fromCategory() and emit() are functions provided globally by KurrentDB's V8 engine, you need to declare them yourself.

interface ProjectionEvent<T> {
  body: T
  bodyRaw: string
  streamId: string
  eventType: string
  sequenceNumber: number
  metadataRaw: Record<string, unknown>
  isJson: boolean
  partition: string
}

interface WhenHandlers<S> {
  $init?: () => S
  $any?: (state: S, event: ProjectionEvent<unknown>) => void
  [eventType: string]: ((state: S, event: ProjectionEvent<any>) => void) | (() => S) | undefined
}

interface ProjectionBuilder<S = unknown> {
  when(handlers: WhenHandlers<S>): ProjectionChain
  foreachStream(): { when(handlers: WhenHandlers<S>): ProjectionChain }
  outputState(): void
}

interface ProjectionChain {
  outputState(): ProjectionChain
  transformBy(handler: (state: any) => any): ProjectionChain
  filterBy(handler: (state: any) => boolean): ProjectionChain
}

declare function fromAll(): ProjectionBuilder<any>
declare function fromCategory(name: string): ProjectionBuilder<any>
declare function fromStream(name: string): ProjectionBuilder<any>
declare function fromStreams(streams: string[]): ProjectionBuilder<any>
declare function emit(streamId: string, eventType: string, eventBody: unknown, metadata?: unknown): void
declare function linkTo(streamId: string, event: unknown, metadata?: unknown): void
declare function log(message: string): void

The return value of fromCategory() is set to ProjectionBuilder<any>.
If it were <unknown>, the state type of the handler passed to when() would mismatch and cause an error.

tsconfig.json

{
  "compilerOptions": {
    "target": "ES5",
    "module": "none",
    "strict": true,
    "outDir": "dist",
    "rootDir": ".",
    "declaration": false,
    "sourceMap": false
  },
  "include": ["*.ts"],
  "exclude": ["node_modules"]
}

I set module: "none" because Projections do not have a module system.
You can use fromCategory() and similar functions in the global scope.

balance.ts — Account-based Balance

interface BalanceState {
  balance: number
  total_income: number
  total_expense: number
  event_count: number
}

interface IncomeEvent {
  amount: number
  description: string
}

interface ExpenseEvent {
  amount: number
  category: string
  description: string
}

fromCategory('account')
  .foreachStream()
  .when({
    $init(): BalanceState {
      return { balance: 0, total_income: 0, total_expense: 0, event_count: 0 }
    },
    income(s: BalanceState, e: ProjectionEvent<IncomeEvent>) {
      s.balance += e.body.amount
      s.total_income += e.body.amount
      s.event_count += 1
    },
    expense(s: BalanceState, e: ProjectionEvent<ExpenseEvent>) {
      s.balance -= e.body.amount
      s.total_expense += e.body.amount
      s.event_count += 1
    }
  })
  .outputState()

There are several important points:

  • fromCategory('account') — Targets events in streams named account-*
  • .foreachStream() — Maintains an independent state for each stream (separate balances for alice and bob)
  • $init() — Initial value for the state
  • income / expense — Handlers corresponding to the event type name. Ensure these match the first argument of EventData::json("income", ...) in Rust
  • .outputState() — Enables fetching the state via the get_state API

category.ts — Expense Aggregation by Category

interface CategoryEntry {
  total: number
  count: number
}

interface CategoryState {
  categories: Record<string, CategoryEntry>
}

interface ExpenseEvent {
  amount: number
  category: string
  description: string
}

fromCategory('account')
  .when({
    $init(): CategoryState {
      return { categories: {} }
    },
    expense(s: CategoryState, e: ProjectionEvent<ExpenseEvent>) {
      var cat = e.body.category
      if (!s.categories[cat]) {
        s.categories[cat] = { total: 0, count: 0 }
      }
      s.categories[cat].total += e.body.amount
      s.categories[cat].count += 1
    }
  })
  .outputState()

The difference from balance.ts is the absence of .foreachStream(). This aggregates expenses across all accounts.

alert.ts — Budget Exceeded Alert

interface AlertTotals {
  totals: Record<string, number>
}

interface ExpenseEvent {
  amount: number
  category: string
  description: string
}

fromCategory('account')
  .when({
    $init(): AlertTotals {
      return { totals: {} }
    },
    expense(s: AlertTotals, e: ProjectionEvent<ExpenseEvent>) {
      var cat = e.body.category
      if (!s.totals[cat]) s.totals[cat] = 0
      s.totals[cat] += e.body.amount

      if (s.totals[cat] > 50000) {
        var account = e.streamId.replace('account-', '')
        emit('alert-' + account, 'BudgetExceeded', {
          category: cat,
          total: s.totals[cat],
          triggered_by: e.body.amount,
          account: account
        })
      }
    }
  })

This is the most interesting part. We use emit() to write events into a new stream called alert-{account}. It turns out that a Projection can not only "create Read Models" but also "generate derived events."

Note that there is no .outputState() here. The purpose of this Projection is to generate events via emit, and it does not need to expose its state.

summary.ts — Global Account Summary

interface SummaryState {
  total_income: number
  total_expense: number
  net: number
  accounts: Record<string, number>
}

interface IncomeEvent {
  amount: number
  description: string
}

interface ExpenseEvent {
  amount: number
  category: string
  description: string
}

fromCategory('account')
  .when({
    $init(): SummaryState {
      return { total_income: 0, total_expense: 0, net: 0, accounts: {} }
    },
    income(s: SummaryState, e: ProjectionEvent<IncomeEvent>) {
      if (!s.accounts[e.streamId]) s.accounts[e.streamId] = 0
      s.accounts[e.streamId] += e.body.amount
      s.total_income += e.body.amount
      s.net += e.body.amount
    },
    expense(s: SummaryState, e: ProjectionEvent<ExpenseEvent>) {
      if (!s.accounts[e.streamId]) s.accounts[e.streamId] = 0
      s.accounts[e.streamId] -= e.body.amount
      s.total_expense += e.body.amount
      s.net -= e.body.amount
    }
  })
  .outputState()

The accounts map keeps track of the balance for each account. e.streamId contains the actual stream name of the event (e.g., account-alice).

Building

cd projections
npm install --save-dev typescript
npx tsc
ls dist/
# balance.js  category.js  alert.js  summary.js

Implementation in Rust

src/projections.rs — JS Embedding and State Types

use serde::Deserialize;
use std::collections::HashMap;

pub const BALANCE_JS: &str = include_str!("../projections/dist/balance.js");
pub const CATEGORY_JS: &str = include_str!("../projections/dist/category.js");
pub const ALERT_JS: &str = include_str!("../projections/dist/alert.js");
pub const SUMMARY_JS: &str = include_str!("../projections/dist/summary.js");

pub const BALANCE_NAME: &str = "account-balance";
pub const CATEGORY_NAME: &str = "category-expense";
pub const ALERT_NAME: &str = "budget-alert";
pub const SUMMARY_NAME: &str = "account-summary";

pub const ALL_PROJECTIONS: &[(&str, &str, bool)] = &[
    (BALANCE_NAME, BALANCE_JS, false),
    (CATEGORY_NAME, CATEGORY_JS, false),
    (ALERT_NAME, ALERT_JS, true),
    (SUMMARY_NAME, SUMMARY_JS, false),
];

#[derive(Debug, Deserialize)]
pub struct BalanceState {
    pub balance: f64,
    pub total_income: f64,
    pub total_expense: f64,
    pub event_count: f64,
}

#[derive(Debug, Deserialize)]
pub struct CategoryEntry {
    pub total: f64,
    pub count: f64,
}

#[derive(Debug, Deserialize)]
pub struct CategoryState {
    pub categories: HashMap<String, CategoryEntry>,
}

#[derive(Debug, Deserialize)]
pub struct SummaryState {
    pub total_income: f64,
    pub total_expense: f64,
    pub net: f64,
    pub accounts: HashMap<String, f64>,
}

#[derive(Debug, Deserialize)]
pub struct BudgetExceededEvent {
    pub category: String,
    pub total: f64,
    pub triggered_by: f64,
    pub account: String,
}

include_str!() loads the file at compile time, so npx tsc must be run before cargo build.

The third bool in ALL_PROJECTIONS is the emit flag. Only the alert projection is set to true.

Registering Projections

use kurrentdb::{Client, CreateProjectionOptions, ProjectionClient};
use crate::projections::ALL_PROJECTIONS;

pub async fn run(client: &Client) -> Result<(), Box<dyn std::error::Error>> {
    let proj_client = ProjectionClient::from(client.clone());

    for &(name, query, emit) in ALL_PROJECTIONS {
        let options = CreateProjectionOptions::default()
            .emit(emit)
            .track_emitted_streams(emit);
        match proj_client.create(name, query.to_string(), &options).await {
            Ok(()) => println!("  ✓ {}", name),
            Err(e) => {
                let msg = e.to_string();
                if msg.contains("Conflict") || msg.contains("already exists") {
                    println!("  - {} (already exists)", name);
                } else {
                    eprintln!("  ✗ {} : {}", name, e);
                }
            }
        }
    }

    println!("\nprojection setup complete.");
    Ok(())
}

ProjectionClient::from(client.clone()) can be used to convert from Client. It shares the internal gRPC connection, so no new connection is created.

Projections that use emit() require CreateProjectionOptions::default().emit(true).track_emitted_streams(true). If you forget this, the emit operations will be ignored.

Rewriting the balance Command to use get_state

Before (Reading all events again):

let mut read = client.read_stream(stream, &options).await?;
while let Some(event) = read.next().await? {
    // apply each event one by one...
}

After (Projection's get_state):

use kurrentdb::{Client, GetStateProjectionOptions, ProjectionClient};
use crate::projections::{BalanceState, BALANCE_NAME};

pub async fn run(client: &Client, account: &str) -> Result<(), Box<dyn std::error::Error>> {
    let proj_client = ProjectionClient::from(client.clone());
    let stream = format!("account-{}", account);
    let options = GetStateProjectionOptions::default().partition(stream);

    let state: BalanceState = proj_client
        .get_state::<_, BalanceState>(BALANCE_NAME, &options)
        .await??;

    if state.event_count == 0.0 {
        println!("No events found.");
        return Ok(());
    }

    println!("{}: {} ({} events)", account, format_amount_f64(state.balance), state.event_count as u64);
    println!("  income:  {:>9}", format_amount_f64(state.total_income));
    println!("  expense: {:>9}", format_amount_f64(state.total_expense));

    Ok(())
}

await?? — This is a double ? operator. Since the return value of get_state() is Result<serde_json::Result<T>>, the outer part handles gRPC errors and the inner part handles JSON deserialization errors.

.partition("account-alice") is mandatory for Projections using foreachStream(). It specifies which stream's state to retrieve.

Alert Monitoring

use kurrentdb::{Client, StreamPosition, SubscribeToStreamOptions};
use crate::projections::BudgetExceededEvent;

pub async fn run(client: &Client, account: &str) -> Result<(), Box<dyn std::error::Error>> {
    let stream = format!("alert-{}", account);

    println!("watching alerts for {}... (Ctrl+C to stop)", account);

    let options = SubscribeToStreamOptions::default().start_from(StreamPosition::Start);
    let mut subscription = client.subscribe_to_stream(stream, &options).await;

    loop {
        let event = subscription.next().await?;
        let recorded = event.get_original_event();
        let alert = recorded.as_json::<BudgetExceededEvent>()?;

        println!(
            "[ALERT] {} - category '{}' exceeded budget: {} (triggered by +{})",
            alert.account, alert.category,
            format_amount_f64(alert.total), format_amount_f64(alert.triggered_by),
        );
    }
}

We do not use ProjectionClient here. The stream created by alert.ts using emit() is a normal stream, so you can subscribe to it using the standard Client.

Trying it out

# Start KurrentDB
docker compose up -d

# TypeScript build → Rust build
cd projections && npx tsc && cd ..
cargo build

# Register Projections
cargo r -- projection setup
#   ✓ account-balance
#   ✓ category-expense
#   ✓ budget-alert
#   ✓ account-summary

# Check Projection status
cargo r -- projection status
# NAME                 STATUS        PROGRESS
# ------------------------------------------
# account-balance      Running       100.0%
# category-expense     Running       100.0%
# budget-alert         Running       100.0%
# account-summary      Running       100.0%

# Insert test data
cargo r -- income alice 100000 salary
cargo r -- expense alice 30000 food lunch
cargo r -- expense alice 25000 food dinner

# Check balance (returns instantly)
cargo r -- balance alice
# alice: 45,000 (3 events)
#   income:   100,000
#   expense:   55,000

# Category aggregation
cargo r -- stats category
# CATEGORY           TOTAL  COUNT
# -----------------------------------
# food              55,000      2

# Global summary
cargo r -- stats summary
# === Account Summary ===
#
#   income:       100,000
#   expense:       55,000
#   net:           45,000
#
# ACCOUNT                    BALANCE
# ---------------------------------------
# alice                       45,000

Let's test the alert functionality. Open two terminals.

# Terminal A
cargo r -- alert watch alice
# watching alerts for alice... (Ctrl+C to stop)
# [ALERT] alice - category 'food' exceeded budget: 55,000 (triggered by +25,000)

The food category already reached 55,000 with the first two events, so the past alert is displayed immediately.

# Terminal B
cargo r -- expense alice 10000 food snack

A new alert will appear in Terminal A.

[ALERT] alice - category 'food' exceeded budget: 65,000 (triggered by +10,000)

Troubleshooting Points

I struggled with these a few times during implementation, so I'm sharing them.

1. All JavaScript numbers are f64

Your Rust Deserialize types will crash if you use u64. Even for fields that look like integers, such as event_count, use f64.

2. Relationship between foreachStream() and partition

Using .foreachStream() gives each stream its own independent state. When retrieving via get_state(), specify the stream using .partition("account-alice"). If you don't use foreachStream(), there is only one global state, so partitioning is unnecessary.

3. Apple Silicon and V8

If you run the amd64 image of KurrentDB via Rosetta, emit() will not function. Please use the arm64 native eventstore/eventstore:23.10.2-alpha-arm64v8 image. Note that outputState() works fine on amd64, making the silent failure of emit() particularly tricky.

4. emit() requires explicit activation

If you forget CreateProjectionOptions::default().emit(true), the projection will appear to run normally, but the destination stream for emit will be empty.

5. include_str!() is evaluated at compile time

When you modify TypeScript code, you must run npx tsc followed by cargo build. Running only cargo build will embed the old JavaScript code.

6. No official types.d.ts

Although it is requested in Issue #1805, it is not yet supported. You have to create it yourself.

Conclusion

Thanks to Projections, we shifted from "reading all events again to calculate" to "obtaining data instantly via get_state." The speed of the balance command remains constant regardless of how many events are added.

While the structure of writing Projections in TypeScript, compiling to ES5, and embedding into Rust is unique, there is a sense of security in being able to write type-safe Projections.

Deriving events via emit() expands the possibilities of Event Sourcing. While this was a budget alert, it could also be used to build dashboards by streaming aggregation results to separate streams.

However, while writing queries in the familiar JS/TS environment is nice, from an operational perspective, one might want to quickly run SELECT SUM(amount) FROM expenses WHERE category = 'food' to find out the food expenses from last month. Since get_state in KurrentDB only returns pre-defined Projection results, it is not suitable for ad-hoc aggregations. If you project the results into an RDB like PostgreSQL, you can leverage the advantages of Event Sourcing while still using SQL for flexible aggregation. I'd like to try that next.

Discussion