v0.1 · experimental

Leave React one feature at a time.

Move a feature's state and side effects into a Foldkit Program. React keeps rendering it until you swap the view.

$ npm install react-foldkit
export const Model = Schema.Struct({
	items: Schema.Array(Product),
	status: Status,
})
export type Model = typeof Model.Type

export const Message = defineMessageUnion({
	ClickedAdd: { product: Product },
	ClickedSave: {},
	CompletedSaveCart: { items: Schema.Array(Product) },
})
export type Message = typeof Message.Type

// Saving is a side effect, so it runs as a Command.
export const SaveCart = Command.define("SaveCart", {
	args: { items: Schema.Array(Product) },
	messages: [Message.CompletedSaveCart],
	execute: ({ items }) => Api.saveCart(items).pipe(Effect.as(Message.CompletedSaveCart({ items }))),
})

const update = (model: Model, message: Message) =>
	Message.match<Update.Return<Model, Message>>(message, {
		ClickedAdd: ({ product }) => ({
			model: modifyFields(model, {
				items: Array.append(product),
				status: () => "Unsaved",
			}),
		}),
		ClickedSave: () => ({
			model: modifyFields(model, { status: () => "Saving" }),
			commands: [SaveCart({ items: model.items })],
		}),
		// Items added during the save weren't in this request, so the cart stays unsaved.
		CompletedSaveCart: ({ items }) =>
			Equal.equals(items, model.items) ? { model: modifyFields(model, { status: () => "Saved" }) } : { model },
	})

export const initialModel: Model = { items: [], status: "Unsaved" }

const init = () => ({ model: initialModel })

export const cart = Program.make({ Model, Message, init, update })

The cart's state and side effects. Both views run this Program.

Your logic moves first.

Wrap one feature in a Program. Its state and side effects leave React, and every view keeps rendering.

Store

Search

Cart

Checkout

Profile

Start with the cart. Its state and side effects move into a Program.

Move checkout when you're ready. Search and profile don't notice.

Every view still renders in React, until you swap it.

Then the view.

With the cart's logic in a Program, its React view is a thin layer. Rewrite it as a Foldkit view, and keep the Program as it is.

React viewcart.tsx
export function CartView() {
	const items = Cart.useModel((model) => model.items)
	const status = Cart.useModel((model) => model.status)
	const send = Cart.useSend()

	return (
		<section className="shop">
			<ul>
				{products.map((product) => (
					<li key={product.name}>
						<span>{product.name}</span>
						<span>€{product.price}</span>
						<button
							aria-label={`Add ${product.name}`}
							onClick={() => send.ClickedAdd({ product })}
						>
							Add
						</button>
					</li>
				))}
			</ul>
			<footer>
				<p>
					{items.length} in cart · €{totalOf(items)}
				</p>
				<button
					disabled={status === "Saving" || items.length === 0}
					onClick={() => send.ClickedSave()}
				>
					{saveLabel(status)}
				</button>
			</footer>
		</section>
	)
}
Foldkit viewview.ts
export const view = (model: Model, h: HtmlBuilder<Message>): Html =>
	h.section(
		[h.Class("shop")],
		[
			h.ul(
				[],
				Array.map(products, (product) =>
					h.keyed("li")(
						product.name,
						[],
						[
							h.span([], [product.name]),
							h.span([], [`€${product.price}`]),
							h.button(
								[h.AriaLabel(`Add ${product.name}`), h.OnClick(Message.ClickedAdd({ product }))],
								["Add"]
							),
						]
					)
				)
			),
			h.footer(
				[],
				[
					h.p([], [`${model.items.length} in cart · €${totalOf(model.items)}`]),
					h.button(
						[
							h.Disabled(model.status === "Saving" || Array.isReadonlyArrayEmpty(model.items)),
							h.OnClick(Message.ClickedSave()),
						],
						[saveLabel(model.status)]
					),
				]
			),
		]
	)

Tested the same way.

Scene tests run on React views and on Foldkit views. When the cart moves, its test changes one import.

cart.test.tsx

-import { Command, click, expect, given, role, scene } from "react-foldkit/scene"

+import { Command, click, expect, given, role, scene } from "foldkit/scene"

import { Message, SaveCart, cart, initialModel } from "./program"

Start with one feature.

Install React Foldkit, wrap one feature in a Program, and keep shipping.

$ npm install react-foldkit

React Foldkit is experimental, and built to be left behind. Read the limitations before you adopt it.