Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 13 additions & 6 deletions docs/server/features/projections/custom.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,11 @@ fromStream('account-1')
.outputState()
```

::: tip
Kurrent's [gaffer](https://gaffer.kurrent.io) tooling runs projections like this one on your machine and
deploys them to a server.
:::

## Projections API

Below, you can find the JavaScript API for user defined projections.
Expand Down Expand Up @@ -111,9 +116,8 @@ handler. The event provided through the handler contains the following propertie

## Debugging

User projections have a bonus that debugging is easier
via any browser that ships with debugging capabilities. The screenshots in this document show the use of
Chrome, but we have tested debugging with all major browsers including Firefox, Edge and Safari.
A projection can log from inside a handler, and you can step through one before it goes anywhere near a
server. Both are covered below.

### Logging from a projection

Expand Down Expand Up @@ -178,10 +182,13 @@ V2 is a parallel-partitioned engine with an incompatible checkpoint format and a
Before selecting it, read [Projections Engine V2](./engine-v2.md) — in particular, V2 does not emit
`outputState()` result streams and does not support `trackemittedstreams`.

### Debugging projections
### Stepping through a projection

To develop and debug projections, use [Gaffer](https://github.com/kurrent-io/gaffer) — a standalone tool
for authoring, running, and stepping through KurrentDB projections.
The [gaffer](https://gaffer.kurrent.io) command line runs a projection on your machine with a debugger
attached, against a file of sample events or against one of your databases, so you can set breakpoints,
step through a handler and inspect the state as it changes without deploying anything. The
[VS Code extension](https://gaffer.kurrent.io/extension/vs-code/) drives it from the editor, and any
DAP-aware editor can attach to it.

## Configuring projections

Expand Down
18 changes: 16 additions & 2 deletions docs/server/features/projections/intro.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,8 +48,8 @@ meet the criteria. The output of all queries is a stream, you can listen to this
There are two types of projections in KurrentDB:

- [Built in (system) projections](system.md)
- [User-defined JavaScript projections](custom.md) which you create via the API or the admin
UI
- [User-defined JavaScript projections](custom.md), which you write yourself and create through the
API, a client library, or the embedded UI

## Engine versions

Expand All @@ -58,6 +58,20 @@ KurrentDB ships two projection execution engines. V1 is the default. V2 is opt-i
checkpoint format and omits some V1 features (notably `outputState()` result streams and
`trackemittedstreams`). See [Projections Engine V2](./engine-v2.md).

## Tooling

Kurrent maintains tooling for developing user-defined projections:

- **[gaffer](https://gaffer.kurrent.io)**, a command-line tool, runs a projection on your machine against
a file of sample events or subscribed to one of your databases. It deploys the projection to a server
when you are ready, and can run it with a debugger attached so you can step through a handler and watch
the state change. See [Your first projection](https://gaffer.kurrent.io/getting-started/first-projection/).
- **[The VS Code extension](https://gaffer.kurrent.io/extension/vs-code/)** drives the same runs and
breakpoints from the editor, and shows which of your projections are deployed where. Other DAP-aware
editors can attach to the debugger too.
- **[The testing library](https://gaffer.kurrent.io/testing/nodejs/)** feeds events to a projection from
a JavaScript test suite and hands back the state at each step for your tests to assert on.

## Performance impact

Keep in mind that all projections emit events as a reaction to events that they process. We call this effect _write amplification_
Expand Down
Loading