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 +21 -0
- package/README.md +242 -0
- package/dist/index.d.mts +476 -0
- package/dist/index.d.mts.map +1 -0
- package/dist/index.mjs +691 -0
- package/dist/index.mjs.map +1 -0
- package/package.json +43 -0
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.
|