On this pageParent-Owned Changes

Informing Submodels

Parent-Owned Changes

Preserve Child Ownership

A Submodel sometimes needs to react to a change it does not own. The URL may change, a server may push new data, or a sibling field may establish a new constraint. The parent observes that change, but the child still owns the state transition it causes.

Export an inform* helper from the child. The helper runs an internal child Message through update and returns the next child Model and Commands. The parent folds that helper with Update.foldChild, so it never imports or constructs the internal Message.

Choose Inform or Reflect

Use inform* when the child must derive a transition or return Commands. Use a silent reflect* helper when the child only needs to conform one of its values to an external source.

Routing Example

The example below uses routing. A People Submodel owns its search input, results, and recent searches. The root owns the Route. When the URL resolves to a People Route, the root calls People.informRouteChanged.

Prerequisite

This page builds on the Submodels pattern. Read that first if the Got*Message wrapping convention is unfamiliar.

The Child

Keep the Message Private

People declares an internal ChangedRoute Message carrying only PeopleRoute, the part of the application Route that the feature understands.

Update copies the route query into the input, records it in recent searches, and returns FetchPeople for the new results.

Expose a Public Helper

informRouteChanged is the public entry point. It calls update(model, ChangedRoute({ route })), keeping the Message constructor private.

Child informRouteChanged helper

import { Option, Schema, String } from 'effect'
import { type Update } from 'foldkit'
import { defineMessageUnion } from 'foldkit/message'
import { modifyFields } from 'foldkit/struct'

import { PeopleRoute } from './route'

// MESSAGE

const Person = Schema.Struct({
  id: Schema.Number,
  name: Schema.String,
  role: Schema.String,
})

export const Message = defineMessageUnion({
  ChangedSearchInput: { value: Schema.String },
  SubmittedSearch: {},
  ChangedRoute: { route: PeopleRoute },
  SucceededFetchPeople: {
    query: Schema.String,
    people: Schema.Array(Person),
  },
})
export type Message = typeof Message.Type

// UPDATE

export const update = (model: Model, message: Message) =>
  Message.match<Update.Return<Model, Message>>(message, {
    ChangedSearchInput: ({ value }) => ({
      model: modifyFields(model, { searchInput: () => value }),
    }),

    SubmittedSearch: () => ({
      model,
      commands: [
        PushSearchUrl({
          searchText: Option.liftPredicate(
            model.searchInput,
            String.isNonEmpty,
          ),
        }),
      ],
    }),

    ChangedRoute: ({ route }) => {
      const searchText = Option.getOrElse(route.searchText, () => '')
      return {
        model: modifyFields(model, {
          searchInput: () => searchText,
          searchHistory: searchHistory =>
            addSearchToHistory(searchHistory, searchText),
          results: () => SearchLoading(),
        }),
        commands: [FetchPeople({ searchText })],
      }
    },

    SucceededFetchPeople: ({ query, people }) => ({
      model: modifyFields(model, {
        results: () => SearchLoaded({ query, people }),
      }),
    }),
  })

export const informRouteChanged = (model: Model, route: PeopleRoute) =>
  update(model, Message.ChangedRoute({ route }))

Not an OutMessage

ChangedRoute moves from parent to child through an inform* helper. An OutMessage moves a fact from child to parent.

The Parent

Define the Parent Folds

The root defines one fold for regular People Messages and another for informRouteChanged. Both folds use the same read, write, and toParentMessage boundary. The ChangedUrl handler stores the next Route, then composes the relevant child step with Update.combine.

Parent route fold

import { Match, Option } from 'effect'
import { Update } from 'foldkit'
import { modifyFields } from 'foldkit/struct'

import { People } from './page'

const foldPeople = Update.foldChild({
  update: People.update,
  read: (model: Model) => Option.some(model.peoplePage),
  write: (model, nextPeoplePage) =>
    modifyFields(model, { peoplePage: () => nextPeoplePage }),
  toParentMessage: message => Message.GotPeopleMessage({ message }),
})

const foldPeopleRouteChanged = Update.foldChild({
  update: People.informRouteChanged,
  read: (model: Model) => Option.some(model.peoplePage),
  write: (model, nextPeoplePage) =>
    modifyFields(model, { peoplePage: () => nextPeoplePage }),
  toParentMessage: message => Message.GotPeopleMessage({ message }),
})

const setRoute =
  (nextRoute: AppRoute): Update.Step<Model, Message> =>
  model => ({ model: modifyFields(model, { route: () => nextRoute }) })

export const update = (model: Model, message: Message) =>
  Message.match<UpdateReturn>(message, {
    ChangedUrl: ({ url }) => {
      const nextRoute = urlToAppRoute(url)

      const routeSteps = Match.value(nextRoute).pipe(
        Match.withReturnType<ReadonlyArray<Update.Step<Model, Message>>>(),
        Match.tag('People', peopleRoute => [
          foldPeopleRouteChanged(peopleRoute),
        ]),
        Match.orElse(() => []),
      )

      return Update.combine(model, [setRoute(nextRoute), ...routeSteps])
    },

    GotPeopleMessage: ({ message }) => foldPeople(model, message),
  })

Multiple Submodels

When several page Submodels react to routing, match the next Route and return the informRouteChanged step for the page that owns that Route.

Handle Cold Loads Separately

Cold loads

informRouteChanged handles later URL changes. On a cold load, root init parses the initial URL and passes the People Route to child init. See Cold Loads and the Initial Route.

Reuse the Pattern for Other Causes

The Routing example contains the complete search flow. Routing and Navigation covers the parser that produces these Routes.

The same pattern works when a Subscription or Command tells the parent about a change the child must process. The cause changes, but ownership does not.