foldkit-surface 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Patrick Glenn
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,242 @@
1
+ # `foldkit-surface`
2
+
3
+ The observation boundary for a Foldkit application. A Surface is a **pure
4
+ projection** of the Model: it declares exactly which fields a feature reads and
5
+ which Messages it may construct, and it does so from the application's existing
6
+ Schema, not a second hand-written interface.
7
+
8
+ `foldkit-surface` is the foundation under
9
+ [`foldkit-sync`](https://github.com/doeixd/foldkit-plus/tree/main/packages/sync)
10
+ and [`foldkit-remote`](https://github.com/doeixd/foldkit-plus/tree/main/packages/remote):
11
+ both consume the projection and Message-subset values this package produces.
12
+
13
+ ## Quick start
14
+
15
+ ```ts
16
+ import { Schema } from 'effect'
17
+ import { defineMessageUnion } from 'foldkit/message'
18
+ import { Projection, Surface } from 'foldkit-surface'
19
+
20
+ const Model = Schema.Struct({
21
+ todos: Schema.Array(Schema.Struct({ id: Schema.String, title: Schema.String, done: Schema.Boolean })),
22
+ selectedTodoId: Schema.NullOr(Schema.String),
23
+ })
24
+ const Message = defineMessageUnion({
25
+ CreatedTodo: { id: Schema.String, title: Schema.String },
26
+ ToggledTodo: { id: Schema.String },
27
+ SelectedTodo: { id: Schema.String },
28
+ })
29
+
30
+ const update = (model: typeof Model.Type, message: typeof Message.Type) => {
31
+ switch (message._tag) {
32
+ case 'CreatedTodo':
33
+ return { model: { ...model, todos: [...model.todos, { id: message.id, title: message.title, done: false }] } }
34
+ case 'ToggledTodo':
35
+ return { model: { ...model, todos: model.todos.map(todo => todo.id === message.id ? { ...todo, done: !todo.done } : todo) } }
36
+ case 'SelectedTodo':
37
+ return { model: { ...model, selectedTodoId: message.id } }
38
+ }
39
+ }
40
+
41
+ // A runnable application carries `initial` and `update`, so a replicator can
42
+ // derive the shared value and replay; both are optional.
43
+ const App = Surface.application({
44
+ Model,
45
+ Message,
46
+ initial: { todos: [], selectedTodoId: null },
47
+ update,
48
+ })
49
+
50
+ const TodoList = App.surface('TodoList', {
51
+ model: ({ model }) => ({ todos: model.todos, selectedTodoId: model.selectedTodoId }),
52
+ messages: [Message.ToggledTodo, Message.SelectedTodo],
53
+ })
54
+ ```
55
+
56
+ `TodoList` is a named contract: the projection a feature reads (here the two
57
+ fields, as `Projection.struct` lifts them) and the Messages it may send. It
58
+ reads purely (`Surface.read(TodoList, model)`), binds a renderer
59
+ (`Surface.view`), and is what `foldkit-remote`, `foldkit-sync`, and
60
+ `foldkit-agent` derive their work from. `Projection.pick(App.fields.todos)` is
61
+ a writable projection of the same field for a replicator.
62
+
63
+ ## Field references
64
+
65
+ `Surface.application` generates a reference tree from the Model Schema, one node
66
+ per field: `App.fields.todos`, `App.fields.someStruct.title`. Each `FieldRef`
67
+ carries its optic, codec, `get`, and `set`, plus the field name as a literal type,
68
+ so a selection can infer its own output keys without a parallel field registry.
69
+
70
+ ```ts
71
+ App.fields.todos // FieldRef<Model, Todo[], 'todos'>
72
+ App.fields.selectedTodoId // FieldRef<Model, string | null, 'selectedTodoId'>
73
+ App.fields.todosById.at('t1') // OptionalRef<Model, Option<Todo>> (dynamic key)
74
+ App.fields.todos.index(0) // OptionalRef<Model, Option<Todo>> (dynamic index)
75
+ ```
76
+
77
+ Struct fields recurse, so a nested reference such as `App.fields.todo.title` is a
78
+ `FieldRef`. Array and record access is `.index(i)` / `.at(key)`, which returns an
79
+ `OptionalRef` — a `ModelRef` with an `Option` value. Those are dynamic selections,
80
+ so `Projection.pick` (which needs a static field name) rejects them; they are useful
81
+ inside a `Projection`.
82
+
83
+ `App.model` is the same tree under its older name; prefer `App.fields`.
84
+
85
+ `Projection.pick` turns references into a writable projection — a `Schema.Struct`,
86
+ `get`, and `set`:
87
+
88
+ ```ts
89
+ const Shared = Projection.pick(App.fields.todos, App.fields.selectedTodoId)
90
+ // { schema, dependencies, get, set }
91
+ ```
92
+
93
+ A reference from a different application is rejected by a per-application owner
94
+ token, so two structurally identical Models cannot be mixed. Duplicate members
95
+ deduplicate; a conflicting definition throws.
96
+
97
+ `Projection.compose` merges disjoint writable projections, keeping each part's own
98
+ write behavior. `ModelRef.fromOptic` builds a reference from an optic you already
99
+ have.
100
+
101
+ ## Projections
102
+
103
+ A `Projection<Root, Value>` is three things: a `Model` codec for `Value`, a pure
104
+ `read(root) => Value`, and what it needs: its `dependencies` (Model paths), its
105
+ `requirements` (remote entity fields), and its `connections` (remote query
106
+ connections, with what they select of each item). Reading never performs I/O.
107
+
108
+ ```ts
109
+ Projection.struct({ todos: model.todos, selectedTodoId: model.selectedTodoId })
110
+ Projection.of(Model)({ todos: true, selectedTodoId: true }) // from the Schema
111
+ Projection.array(projection) // Projection<ReadonlyArray<Root>, ReadonlyArray<Value>>
112
+ Projection.option(projection) // Projection<Option<Root>, Option<Value>>
113
+ Projection.fromReader(codec, read) // escape hatch for a non-ModelRef value
114
+ ```
115
+
116
+ `Projection.struct` accepts `ModelRef`s and nested `Projection`s, so a Surface can
117
+ mix local fields with remote or replicated values. A nested projection
118
+ contributes its dependencies, requirements, and connections to the parent
119
+ (`Requirement.merge` and `Requirement.mergeConnections` union them).
120
+
121
+ ## Applications
122
+
123
+ `Surface.application({ Model, Message })` captures the pure references (`App.model`,
124
+ `App.Model`, `App.Message`, `App.owner`) with no transition. Use it when a
125
+ consumer needs only the reference tree.
126
+
127
+ `Surface.application({ Model, Message, initial, update })` additionally captures
128
+ the transition and returns a **Runnable** application. `update`'s Commands may
129
+ carry resources; the resource set is threaded through the returned type.
130
+
131
+ ## Message subsets
132
+
133
+ A subset selects typed variants of one application's Message union by constructor
134
+ reference:
135
+
136
+ ```ts
137
+ const TodoChanges = MessageSet.make(App, [Message.CreatedTodo, Message.ToggledTodo])
138
+ const SelectionChanges = MessageSet.make(App, [Message.SelectedTodo])
139
+ const AllChanges = MessageSet.union(TodoChanges, SelectionChanges)
140
+ ```
141
+
142
+ A subset carries the constructors, a pure codec for exactly those variants, a
143
+ `tags` set, and an `includes` guard. A constructor that is not a variant of the
144
+ application, a duplicate tag, or a subset from another application throws.
145
+ Surface does not label a subset durable, agent-visible, or presence; `Sync` and
146
+ `Agent` attach those policies to the same value.
147
+
148
+ ## Surfaces
149
+
150
+ A Surface binds a projection and the Messages a feature may use into a named,
151
+ inspectable contract. `App.surface(name, { params?, model, messages? })` is
152
+ the form to write: `params` are the fields of a `Schema.Struct` (or a schema,
153
+ kept as is), and `model` returns a Projection, or an object of Projections and
154
+ field refs that becomes `Projection.struct`.
155
+
156
+ ```ts
157
+ const TodoDetail = App.surface('TodoDetail', {
158
+ model: ({ model }) => ({ todos: model.todos, selectedTodoId: model.selectedTodoId }),
159
+ messages: [Message.ToggledTodo],
160
+ })
161
+
162
+ // A parameterized Surface may read `params`; dynamic lookups are OptionalRefs.
163
+ const ById = App.surface('ById', {
164
+ params: { id: Schema.String },
165
+ model: ({ model, params }) => ({ todo: model.todosById.at(params.id) }),
166
+ })
167
+
168
+ Surface.read(TodoDetail, root) // project purely
169
+ Surface.read(ById, root, { id: 't1' })
170
+ Surface.view(TodoDetail, render) // bind a renderer
171
+ Surface.rootView(TodoDetail, undefined, render) // bound to the app root
172
+ ```
173
+
174
+ The Surface's Model is the projected value (`{ todos; selectedTodoId }`), its
175
+ Params the fields, and its Message the union of the constructors listed; a
176
+ constructor from another application is a compile error at the constructor.
177
+ A parameterized Surface's projection is not evaluated until it has params.
178
+
179
+ `Surface.at(surface, params)` is the Surface as the Model activates it: `params`
180
+ is the value, or a function of the Model returning it (`undefined` while the
181
+ Surface is inactive, on another route say). Its `projectionOf(model)` is the
182
+ projection for those params, or `undefined`, and it carries the Surface's
183
+ `owner`; a Subscription derives what to fetch from a list of them
184
+ (`foldkit-remote`'s `Data.subscriptions`).
185
+
186
+ ### `Surface.make`, the explicit form
187
+
188
+ `Surface.make(app, name, { Params?, model, messages? })` takes the wrappers
189
+ `App.surface` lifts: `Params` as a schema and `model` returning a Projection
190
+ (`Projection.struct({ … })` for several fields). `App.surface` compiles to it.
191
+
192
+ ## Modules
193
+
194
+ A `Module` collects an application's contracts as pure data, so their
195
+ relationships can be validated and inspected without starting a runtime. Sync,
196
+ Remote, and Agent contracts carry a `contract` description; a Surface is
197
+ described in place (`Surface.contract(surface, params)` for a parameterized one).
198
+
199
+ ```ts
200
+ import { Module } from 'foldkit-surface'
201
+
202
+ const Project = Module.make(App, [BoardSurface, ProjectSync, ProjectRemote, ProjectAgent])
203
+
204
+ Module.validate(Project) // [] or findings
205
+ Module.manifest(Project) // fields, Messages, who owns each Model path, contracts
206
+ Module.toMarkdown(Project)
207
+ Module.toMermaid(Project)
208
+ ```
209
+
210
+ ```text
211
+ Model
212
+ ├── route LOCAL
213
+ ├── selectedNoteId LOCAL
214
+ ├── notes SYNC notes
215
+ └── remote REMOTE remote
216
+ ```
217
+
218
+ `validate` reports what the types cannot: a contract from another application,
219
+ a duplicate `kind:name`, two owners of overlapping Model paths, a Message
220
+ recorded by two replication contracts, and a path or Message the application
221
+ does not declare. `Module.add(module, ...more)` returns a new Module, so feature
222
+ modules can contribute their contracts independently.
223
+
224
+ ## What it owns
225
+
226
+ - Reference-based Model selection (`App.fields`, `Projection.pick`,
227
+ `Projection.compose`).
228
+ - Pure `Projection` values with their codec, reader, dependencies, and remote
229
+ requirements.
230
+ - Application scopes (`make` / `application`) and their identity token.
231
+ - Typed Message subsets (`MessageSet.make`, `MessageSet.union`).
232
+ - Named Surfaces and their renderer binding.
233
+
234
+ ## Limits
235
+
236
+ - It performs no I/O and knows nothing about transport. Fetching remote data is
237
+ [`foldkit-remote`](https://github.com/doeixd/foldkit-plus/tree/main/packages/remote);
238
+ replicating Messages is
239
+ [`foldkit-sync`](https://github.com/doeixd/foldkit-plus/tree/main/packages/sync).
240
+ - `Model` codecs are pure by construction: Foldkit Model fields carry no decoding
241
+ or encoding services.
242
+ - A projection declares dependencies and requirements but does not resolve them.