Remote / foldkit-remote-domain
remote-domain
If your backend is an event-sourced Alchemy Domain server, your page needs to send Commands to Aggregates and read materialized Views without maintaining a second copy of every row or losing optimistic updates while a View catches up.
foldkit-remote-domain provides a RemoteClient layer (DomainRemote.layer) backed directly by an Alchemy Domain Api client. Your Foldkit page reads and writes through foldkit-remote just as it would against a SQL server—with normalized caching, optimistic predictions, and structured refusals—while the Domain model remains the single authority.
Experimental: Pinned to
@alchemy.run/domainandalchemyat2.0.0-beta.86. For the architectural guide and a full reservation walkthrough, read An event-sourced domain behind Remote.
Install
pnpm add foldkit-remote-domain foldkit-remote foldkit-entity effect \
@alchemy.run/domain@2.0.0-beta.86 alchemy@2.0.0-beta.86Requires @alchemy.run/domain@2.0.0-beta.86, alchemy@2.0.0-beta.86, and effect >= 4.1.4. Add foldkit-guard when lowering guarded writes.
| Entry | Exports | Runs on |
|---|---|---|
foldkit-remote-domain | DomainRemote (RemoteClient layer and bindings) | Browser, tests |
foldkit-remote-domain/server | pageReader for SSR pre-reads | Rendering server |
foldkit-remote-domain/lower | Lower.check, Lower.write (compile Write to aggregate) | Model host |
foldkit-remote-domain/imported | Imported.mutation, describe, show | Anywhere |
foldkit-remote-domain/testing | Fixture.make (in-memory model as RemoteClient) | Tests |
A first View and command
Define your Alchemy Domain model as usual—an Event, Command, Aggregate, View, Model, and Api:
import * as Domain from '@alchemy.run/domain'
import { Effect, Option, Schema } from 'effect'
import { Entity } from 'foldkit-entity'
import { Mutation } from 'foldkit-remote'
import { DomainRemote } from 'foldkit-remote-domain'
class Renamed extends Domain.Event('Renamed', { name: Schema.String, revision: Schema.Int }) {}
class Rename extends Domain.Command('Rename', {
target: Schema.String,
input: { name: Schema.String },
events: [Renamed],
}) {}
class Note extends Domain.Aggregate('Note', {
id: Schema.String,
state: Schema.Struct({ name: Schema.String, revision: Schema.Int }),
initial: { name: '', revision: 0 },
commands: [Rename],
decide: {
Rename: (state, command) => [new Renamed({ name: command.name, revision: state.revision + 1 })],
},
evolve: { Renamed: (_, event) => ({ name: event.name, revision: event.revision }) },
}) {}
class NoteRow extends Domain.View('NoteRow', {
from: [Note],
key: Note,
state: Schema.Struct({ name: Schema.String, revision: Schema.Int }),
initial: { name: '', revision: 0 },
evolve: { Renamed: (_, event) => ({ name: event.name, revision: event.revision }) },
}) {}
class Notes extends Domain.Model('Notes', { aggregates: [Note], views: [NoteRow] }) {}
class NotesApi extends Domain.Api('NotesApi', {
model: Notes,
commands: ['Rename'],
views: ['NoteRow'],
}) {}Now bind a Foldkit Entity and Mutation to that Api and build a RemoteClient layer:
const NoteEntity = Entity.define(
'Note',
Schema.Struct({ id: Schema.String, name: Schema.String, revision: Schema.Number }),
)
const RenameNote = Mutation.make('RenameNote', {
Input: { id: Schema.String, name: Schema.String },
Output: {},
})
const NoteReads = DomainRemote.view(NoteEntity, NotesApi, 'NoteRow', { revision: 'revision' })
const RenameBinding = DomainRemote.command(RenameNote, NotesApi, 'Rename', {
entity: NoteEntity,
target: input => input.id,
input: input => ({ name: input.name }),
written: (_reply, input) => ({ name: input.name }),
})
const client = DomainRemote.layer(NotesApi, {
views: [NoteReads],
commands: [RenameBinding],
principal: Effect.succeed(Option.some('ada')),
denied: () => 'Unauthenticated',
})Provide NotesApi.layerClientHttp(url) in the browser (or NotesApi.layerClientInProcess on the server) alongside client, and Remote.make uses it like any other RemoteClient:
DomainRemote.viewandDomainRemote.commandare pure declarations that validate field names and a numericrevisionat definition time.principalnames the signed-in caller; the adapter refuses writes for a mismatched principal withRemotePrincipalChanged(orRemoteUnauthenticatedwhen signed out) before touching the network.deniedmaps middleware refusals to'Unauthenticated'or'Forbidden'.writtensupplies the fields a committed command wrote so the UI stays consistent if the View has not caught up yet.