Develop, test, debug, and deploy KurrentDB projections.

KurrentDB projections are server-side JavaScript that derive new streams and state from existing events. Gaffer uses the same JS engine as KurrentDB itself, so what you debug locally behaves like what runs in production.

Install

CLI:

npm i -g @kurrent/gaffer

VS Code extension - install KurrentDB Gaffer for run/debug from gaffer.toml, breakpoint debugging, deploy status and history right in the editor, and an auto-registered MCP server.

Test library:

npm i -D @kurrent/projections-testing

Quick start

Run a projection from the CLI:

gaffer dev order-count --fixture happy

Or test it from your existing test suite:

import { createProjection } from "@kurrent/projections-testing";

const projection = createProjection<{ count: number }>(`
  fromAll().when({
    $init: () => ({ count: 0 }),
    OrderPlaced: (s) => ({ count: s.count + 1 }),
  });
`, { engineVersion: 2 });

for (const { state } of projection.run(events)) {
  // assert on state at each step
}

See the demo project for a complete example with fixtures, errors, partitioned state, and bi-state projections.

Deploy

When a projection works locally, point an environment in gaffer.toml at your cluster and converge it:

gaffer deploy --env staging

Deploy plans first (create, update, or skip per projection) and applies only what you confirm. From there, gaffer status, gaffer diff, and gaffer history track what's running against what's in the repo, and gaffer rollback steps back to any earlier version. See the deploy walkthrough.

Packages

Component	Package	License
CLI	@kurrent/gaffer	Kurrent License v1
VS Code extension	kurrent-io.gaffer-vscode	Kurrent License v1
Test library	@kurrent/projections-testing	Apache 2.0
JS bindings	@kurrent/gaffer-runtime	Kurrent License v1
Go bindings	github.com/kurrent-io/gaffer/bindings/go	Kurrent License v1

Per-component LICENSE files live in each directory. See LICENSE_CONTRIBUTIONS.md for the license map and NOTICE.md for third-party attribution.

Communities

• Kurrent community
• Discuss
• Discord (Kurrent)
• Discord (ddd-cqrs-es)

Contributing

See CONTRIBUTING.md for development setup and conventions. Bugs go to Issues; feature requests and questions to Discussions.