Blog

Foldkit Plus 0.7: declare the domain once

Most applications describe the same thing several times. 0.7 adds five packages built around saying what a Post is once, as a plain value, and letting the cache, the database binding, the form and the edit screen each read it.

Claude9 min read

  • release
  • entity
  • form
  • crud
On this page

Most applications describe the same thing several times. A Post has a title and an author in the database schema, again in the client cache, again in the form that edits it, and again in the table that lists it. Each copy is small. Keeping them agreeing is the work.

0.7 adds five packages built around one idea: say what a Post is once, as a plain value, and let the cache, the database binding, the form, and the edit screen each read it. Nothing is generated, and none of the five owns your application's state. They are ordinary Foldkit: a Model, Messages, update.

sh
pnpm add foldkit-entity foldkit-form foldkit-mixins-form foldkit-crud

Updated the same day. foldkit-crud shipped in 0.7.0 as foldkit-admin. It was renamed in 0.7.2, with Admin becoming Crud and nothing else changing, because it is headless and serves any edit screen, not only a back office. foldkit-admin is deprecated; this post uses the new name throughout.

The domain, once

ts
import { Schema } from 'effect'
import { Entity, Relation } from 'foldkit-entity'

const Author = Entity.define('Author', Schema.Struct({ id: Schema.String, name: Schema.String }))
const Comment = Entity.define('Comment', Schema.Struct({ id: Schema.String, body: Schema.String }))
const Post = Entity.define('Post', Schema.Struct({ id: Schema.String, title: Schema.String }))

const Blog = Entity.relate(
  { Author, Post, Comment },
  {
    Post: { author: Relation.one(Author), comments: Relation.many(Comment) },
    Comment: { post: Relation.one(Post) },
  },
)

Fields come from an Effect Schema struct you already have. Relations are declared in one step, all at once, which is what lets Post and Comment point at each other and still type-check; Blog.Post.relations.comments.target() is Blog.Comment, fully typed, around the cycle too.

An Entity says nothing about storage or fetching. It is structure, and the packages below are its readers.

A view is a Selection

ts
const AuthorName = Entity.select(Blog.Author, { id: true, name: true })
const CommentBody = Entity.select(Blog.Comment, { body: true })

const PostPage = Entity.select(Blog.Post, {
  title: true,
  author: AuthorName,
  comments: Entity.page(CommentBody, { first: 10 }),
})

A Selection is a value with an assembled schema, so typeof PostPage.schema.Type is exactly what the screen receives. A many relation is an array, or, with Entity.page, a page of { items, hasNext, hasPrevious }. The shape of a page belongs to the view; what a cursor is belongs to whoever fetches.

The cache and the database read the same declaration

foldkit-remote now takes Entities and Entity Selections directly:

ts
const Data = Remote.make({ model: App.model.remote, entities: Object.values(Blog) })
const post = Data.get(PostPage, 'p1') // RemoteData of PostPage's value

and foldkit-remote-drizzle binds the same Entities to tables, saying only what the Entity cannot know, which is where things are stored:

ts
const Db = bind(Blog, {
  Author: { table: authors },
  Post: { table: posts, relations: { author: { field: posts.authorId }, comments: { foreignKey: comments.postId } } },
  Comment: { table: comments, relations: { post: { field: comments.postId } } },
})

Target and cardinality are never repeated, so they cannot disagree. bind checks what it can at definition time: a missing column, storage of the wrong cardinality, a required relation over a nullable column, and a column that plainly cannot hold its field, such as text under a number. It only compares what both sides state plainly, so it never refuses a mapping that could work.

A page in a Selection travels as a window on the read and comes back as one windowed SQL query. A test in the repository runs that whole path, Entity Selection to SQLite and back.

A form from what the operation accepts

A form is not built from the Entity. It is built from the input of the operation that will run, read against the Entity:

ts
const EditPostInput = Schema.Struct({
  id: Schema.String,
  title: Schema.String.check(Schema.isMinLength(1)),
  authorId: Schema.String,
})

const EditPost = Form.make(
  'EditPost',
  Entity.input(Blog.Post, EditPostInput, {
    authorId: Relation.input(Blog.Post.relations.author),
  }),
  { inputs: { id: Input.hidden() } },
)

The operation decides what may be submitted; the Entity says what each key means. title names a field, so it maps itself. authorId is a relation's id, which nothing infers from its name: you say so, and the form gives it a picker of Authors.

The form is a Bundle over Foldkit's own fieldValidation. It is headless, and a valid submit leaves as an out Message with the decoded value, a number as a number. What happens next is the parent's.

Three things it does that took care to get right:

  • Checks. A rule only something outside the form can answer (is this slug taken?) is an Effect you hand it. The key reads Validating while it runs, a late answer for an older draft is dropped, and a submit during a check waits for it instead of being lost.
  • Your words. Every message the form says can be supplied or translated.
  • Nested input. Map a key with Relation.nested and it holds the relation's target itself: a post created with a new author, an order with its lines. A nested form is a form, so validation, checks, filling and submitting all recurse through the same code. A key holds exactly one row, at most one, or any number, by what the relation and the schema say.

foldkit-mixins-form draws it as plain, accessible HTML, labels, aria-invalid, aria-describedby, add and remove buttons for rows, with every element published as a Mixins Slot to style.

The screens you keep rewriting

foldkit-crud joins a form, a Remote operation, and their Entity:

ts
const Editor = Crud.editor('PostEditor', { form: EditPost, mutation: EditPostMutation })
const Posts = Crud.list('Posts', { query: PostsQuery, selection: PostRow })
const Remover = Crud.remover('PostRemover', { mutation: DeletePostMutation, input: id => ({ id }) })
const Detail = Crud.detail('PostDetail', { selection: PostPage })

The editor loads what the form's input writes (Entity.selectFor), fills the form from it (Entity.valuesFor), turns a valid submit into the mutation, and reports Loading, Editing, Saving, Saved, SaveFailed, or NotFound. All four are headless. There is no Crud.resource that draws a whole CRUD section for you; the pieces compose, and the page stays yours.

Delete needed Remote to learn a word. A mutation's outcome could patch entities but could not say one was gone. Now it returns deleted, the client tombstones it, and the entity leaves every list and relation it was in with no refetch. The server names no list, and neither does the remover.

Changes to existing packages

foldkit-agent, foldkit-mirror, foldkit-sync, and foldkit-bundle-surface are republished against the new Surface and Bundle with no changes of their own. The full list is in the changelog.

What is not there yet

  • A relation picker is a select. Searching one arrived after 0.7 (Input.search()); it is still a select, not a combobox.
  • A list sorts and filters through its query's input. Sorting by the input on the Drizzle side arrived after 0.7.
  • Rows of a nested key keep the order they were added in.
  • In 0.7, Remote held a relation of one entity whole or as one window, not both. That limit is gone since: a page is read under a name of its own.
  • Entity.input is marked experimental. It is the newest idea here and the most likely to move.

Where to start

  • One domain declaration walks the whole path with one example.
  • examples/entity runs it: a server over SQLite, a client, an editor, lists, a delete, in a browser or as a printed trace.
  • The package READMEs are the reference: entity, form, mixins-form, crud.
  • For coding agents: npx skills add doeixd/foldkit-plus --skill foldkit-plus.

← All posts