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/domain and alchemy at 2.0.0-beta.86. For the architectural guide and a full reservation walkthrough, read An event-sourced domain behind Remote.

Install

bash
pnpm add foldkit-remote-domain foldkit-remote foldkit-entity effect \
  @alchemy.run/domain@2.0.0-beta.86 alchemy@2.0.0-beta.86

Requires @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.

EntryExportsRuns on
foldkit-remote-domainDomainRemote (RemoteClient layer and bindings)Browser, tests
foldkit-remote-domain/serverpageReader for SSR pre-readsRendering server
foldkit-remote-domain/lowerLower.check, Lower.write (compile Write to aggregate)Model host
foldkit-remote-domain/importedImported.mutation, describe, showAnywhere
foldkit-remote-domain/testingFixture.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:

ts
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:

ts
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.view and DomainRemote.command are pure declarations that validate field names and a numeric revision at definition time.
  • principal names the signed-in caller; the adapter refuses writes for a mismatched principal with RemotePrincipalChanged (or RemoteUnauthenticated when signed out) before touching the network.
  • denied maps middleware refusals to 'Unauthenticated' or 'Forbidden'.
  • written supplies the fields a committed command wrote so the UI stays consistent if the View has not caught up yet.