Effect
Learn how to use Jazz from Effect v4 programs, in the browser and on the server.jazz-tools/effect exposes Jazz as an Effect v4 service. Reads and writes are
Effects with typed errors, live queries are Streams, and transactions commit or roll back together with
the Effect that runs inside them.
The bindings target Effect v4 (effect@4.0.0-rc.118 or later). Install a release next to Jazz:
pnpm add effect@^4.1. The rc tag can pull in prereleases whose packages need exact pins.
The Jazz service
Jazz.layer(config) opens a Jazz session (createJazzClient(config)) for the lifetime of the layer,
provides its session.db, and closes the session when the layer's scope closes. If you already own a
session, use Jazz.layerDb(session.db) instead.
import { Effect, Stream } from "effect";import { Jazz } from "jazz-tools/effect";import { app } from "./jazz.generated";const program = Effect.gen(function* () {const jazz = yield* Jazz;const todo = yield* jazz.insert(app.todos, { title: "Buy milk", done: false });yield* jazz.update(app.todos, todo.id, { done: true });const open = yield* jazz.all(app.todos.where({ done: false }));const first = yield* jazz.one(app.todos); // Option<Todo>});program.pipe(Effect.provide(Jazz.layer({ serverUrl: "/jazz", initial: "device" })),Effect.runPromise,);
Writes and durability
A write Effect completes once the write is applied locally, like the core API. Pass wait to also wait
until the write is durable at a tier:
const shipIt = Effect.gen(function* () {const jazz = yield* Jazz;yield* jazz.insert(app.todos, { title: "Ship it", done: false }, { wait: "global" });});
Waiting writes fail with JazzWriteRejected if the server rejects them, for example because of
permissions. Every other failure is a JazzError. Rejections of writes nobody waited for arrive on
jazz.mutationErrors, a Stream.
Live queries
jazz.stream(query) emits the complete result when it starts and again whenever it changes. Every
emission is a full snapshot, so a slow consumer only sees the newest one. The subscription is removed when
the Stream ends or its fiber is interrupted.
const logOpenCount = Effect.gen(function* () {const jazz = yield* Jazz;yield* jazz.stream(app.todos.where({ done: false })).pipe(Stream.runForEach((todos) => Effect.log(`${todos.length} open`)));});
Transactions
jazz.transaction(tx => ...) commits when the inner Effect succeeds and rolls back when it fails, dies
or is interrupted. Its typed errors pass through unchanged. Once the inner Effect has succeeded the commit
is kept, even if the fiber is interrupted while it waits for durability.
const addGroceries = Effect.gen(function* () {const jazz = yield* Jazz;yield* jazz.transaction((tx) =>Effect.gen(function* () {const project = yield* tx.insert(app.projects, { name: "Groceries" });yield* tx.insert(app.todos, { title: "Milk", done: false, projectId: project.id });}),);});
jazz.serializableTransaction also waits for the authority's verdict and fails with JazzWriteRejected on a
conflict, so it composes with Effect.retry.
On the server
jazz-tools/effect/backend wraps your app's Jazz (createJazz). JazzBackend does not provide Jazz on its own:
each handler chooses whose permissions it acts with, usually the requesting user's, as your
authenticate names them.
import { Effect } from "effect";import { Jazz, JazzBackend } from "jazz-tools/effect/backend";const listTodos = Effect.gen(function* () {const jazz = yield* Jazz;return yield* jazz.all(app.todos);});// With a request your `authenticate` can read (your session cookie):listTodos.pipe(JazzBackend.forReqUser(request));// Inside an `effect/http` handler, from the current HttpServerRequest:listTodos.pipe(JazzBackend.forCurrentReqUser());// With the backend's own authority:listTodos.pipe(JazzBackend.asAuthority);
For a user with no Jazz account yet, JazzBackend.forReqUser and forCurrentReqUser fail with a
JazzNoAccount error ({ userId, operation }, exported from jazz-tools/effect/backend), which
you can handle with Effect.catchTag("JazzNoAccount", …). createAccountFor(userId) and
withAttribution(request) are methods of the JazzBackend service, not statics:
const accountId = yield * JazzBackend.use((backend) => backend.createAccountFor(userId));
createAccountFor creates the account, or returns the existing one's id; see
Users without an account.
Provide JazzBackend.layer(createJazzOptions) once for the whole server (or
JazzBackend.layerJazz(jazz) for a Jazz you already created). Because handlers only depend on
Jazz, the same code runs in the browser against Jazz.layer(config), and in tests against an in-memory
database.