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.
pnpm add foldkit-entity foldkit-form foldkit-mixins-form foldkit-crudUpdated the same day.
foldkit-crudshipped in 0.7.0 asfoldkit-admin. It was renamed in 0.7.2, withAdminbecomingCrudand nothing else changing, because it is headless and serves any edit screen, not only a back office.foldkit-adminis deprecated; this post uses the new name throughout.
The domain, once
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
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:
const Data = Remote.make({ model: App.model.remote, entities: Object.values(Blog) })
const post = Data.get(PostPage, 'p1') // RemoteData of PostPage's valueand foldkit-remote-drizzle binds the same Entities to tables, saying only what
the Entity cannot know, which is where things are stored:
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:
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
Validatingwhile 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.nestedand 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:
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-remote0.4.0. Takes Entities and Entity Selections. Mutations can delete.Data.mutation(model, requestId)reads a mutation's outcome, errors included, from the Model. Behaviour change: a read the server answers without an id it was asked for now readsNotFoundinstead of stayingLoadingforever.foldkit-remote-server0.4.0.MutationOutcome.deleted.foldkit-remote-drizzle0.4.0.bind, above.foldkit-surface0.3.0. Its opaque metadata moved tofoldkit-metadata, which Surface re-exports, so Entities and Surfaces annotate the same way.foldkit-bundle0.2.0.Bundle.withViewgives a Bundle a view after the fact, which is how a headless form gains its drawn one.foldkit-primitives0.2.0. Sturdier platform detection,distanceToEndon the virtual list, and a denied device request keeps the last device list.
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 aselect, 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.inputis 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/entityruns 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.