foldkit-mirror 0.1.0 → 0.1.1
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/README.md +75 -37
- package/package.json +13 -2
package/README.md
CHANGED
|
@@ -1,13 +1,22 @@
|
|
|
1
1
|
# `foldkit-mirror`
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
3
|
+
Keeps part of a Foldkit Model in the URL or in a key-value store, so a filter
|
|
4
|
+
survives a shared link and a draft survives a reload. You name a slice of the
|
|
5
|
+
Model; the mirror writes it out whenever it changes and reads it back on
|
|
6
|
+
navigation or cold load. Nothing else about the application changes: the Model
|
|
7
|
+
is still the only truth, and `update` is still the only reducer.
|
|
8
|
+
|
|
9
|
+
You do not declare keys, codecs, or defaults. They are derived from the field
|
|
10
|
+
refs you point at: a key's name is the field's name, its text form comes from
|
|
11
|
+
the field's encoded type, and a value equal to the Model's initial one is left
|
|
12
|
+
out of the store entirely. The URL query string and Effect's `KeyValueStore`
|
|
13
|
+
are the two stores that ship.
|
|
14
|
+
|
|
15
|
+
**Use it when** the state is disposable, per-device, and cheap to lose: a
|
|
16
|
+
filter, a sort, a page, an open panel, a preference, an unsent draft. **Not
|
|
17
|
+
for** anything that must converge. A mirror is last-write-wins against a store
|
|
18
|
+
with no log and no ordering, so two tabs writing the same key-value document
|
|
19
|
+
simply overwrite each other. That is what separates it from
|
|
11
20
|
[`foldkit-sync`](https://github.com/doeixd/foldkit-plus/tree/main/packages/sync)
|
|
12
21
|
(an ordered durable log that converges) and from
|
|
13
22
|
[`foldkit-remote`](https://github.com/doeixd/foldkit-plus/tree/main/packages/remote)
|
|
@@ -19,12 +28,26 @@ which is what separates it from
|
|
|
19
28
|
| Filter, sort, page, search text, an open panel | the local Model | the URL (`Mirror.url`) |
|
|
20
29
|
| Preferences, a draft, a collapsed sidebar | the local Model | `KeyValueStore` (`Mirror.kv`) |
|
|
21
30
|
|
|
31
|
+
## Install
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
pnpm add foldkit-mirror
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
`foldkit` and `effect` are peer dependencies; `foldkit-surface` comes with it.
|
|
38
|
+
|
|
22
39
|
## Quick start
|
|
23
40
|
|
|
41
|
+
Declare the mirrors over the application, then wire their three seams: `reduce`
|
|
42
|
+
in `update`, `restore` in a Command, and `subscriptions` for the writes.
|
|
43
|
+
|
|
24
44
|
```ts
|
|
25
45
|
import { Schema } from 'effect'
|
|
46
|
+
import type { KeyValueStore } from 'effect/unstable/persistence'
|
|
26
47
|
import { defineMessageUnion } from 'foldkit/message'
|
|
27
48
|
import * as Subscription from 'foldkit/subscription'
|
|
49
|
+
import type * as Update from 'foldkit/update'
|
|
50
|
+
import { Url } from 'foldkit/url'
|
|
28
51
|
import { Projection, Surface } from 'foldkit-surface'
|
|
29
52
|
import { Mirror } from 'foldkit-mirror'
|
|
30
53
|
|
|
@@ -35,56 +58,61 @@ const Model = Schema.Struct({
|
|
|
35
58
|
sidebar: Schema.Literals(['open', 'closed']),
|
|
36
59
|
draft: Schema.String,
|
|
37
60
|
})
|
|
38
|
-
|
|
61
|
+
type Model = typeof Model.Type
|
|
62
|
+
|
|
63
|
+
// `Mirror.messages` contributes `MirrorRestored`, which a store mirror reduces.
|
|
64
|
+
const Message = defineMessageUnion({ ...Mirror.messages, UrlChanged: { url: Url } })
|
|
65
|
+
type Message = typeof Message.Type
|
|
66
|
+
|
|
67
|
+
const initial: Model = { filter: 'all', page: 1, q: '', sidebar: 'open', draft: '' }
|
|
39
68
|
const App = Surface.application({ Model, Message, initial, update })
|
|
40
69
|
|
|
41
70
|
// The URL shows the filters, as ?filter=…&page=…&q=…; keys default to the field names.
|
|
42
71
|
const Filters = Mirror.url(App, {
|
|
72
|
+
name: 'filters',
|
|
43
73
|
fields: [App.fields.filter, App.fields.page, App.fields.q],
|
|
44
74
|
keys: { q: { history: 'replace' } }, // the rest push a history entry
|
|
45
75
|
})
|
|
46
76
|
|
|
47
|
-
// A key-value store keeps
|
|
77
|
+
// A key-value store keeps the preference and the draft across sessions.
|
|
48
78
|
const Prefs = Mirror.kv(App, {
|
|
49
79
|
key: 'todo/prefs',
|
|
50
|
-
|
|
51
|
-
fields: [App.fields.sidebar, App.fields.draft],
|
|
80
|
+
fields: Projection.pick(App.fields.sidebar, App.fields.draft),
|
|
52
81
|
})
|
|
53
|
-
```
|
|
54
|
-
|
|
55
|
-
Wiring, in the application:
|
|
56
82
|
|
|
57
|
-
|
|
58
|
-
init: url => ({ model: Filters.reduce(initial, url), commands: [Prefs.restore] })
|
|
83
|
+
type Return = Update.Return<Model, Message, KeyValueStore.KeyValueStore>
|
|
59
84
|
|
|
60
|
-
function update(model: Model, message: Message):
|
|
85
|
+
function update(model: Model, message: Message): Return {
|
|
61
86
|
if (Mirror.reduces(message)) return { model: Prefs.reduce(model, message) }
|
|
62
87
|
switch (message._tag) {
|
|
63
88
|
case 'UrlChanged':
|
|
64
|
-
return { model: Filters.reduce(model, message.
|
|
65
|
-
…
|
|
89
|
+
return { model: Filters.reduce(model, message.url) }
|
|
66
90
|
}
|
|
67
91
|
}
|
|
68
92
|
|
|
69
|
-
|
|
93
|
+
// Cold load: the URL is reduced in, and the store is asked for the rest.
|
|
94
|
+
const init = (url: Url): Return => ({
|
|
95
|
+
model: Filters.reduce(initial, url),
|
|
96
|
+
commands: [Prefs.restore],
|
|
97
|
+
})
|
|
98
|
+
|
|
99
|
+
// The writes: one entry per mirror, keyed `<name>.mirror`.
|
|
100
|
+
const subscriptions = Subscription.make<Model, Message, KeyValueStore.KeyValueStore>()(() => ({
|
|
70
101
|
...Filters.subscriptions,
|
|
71
102
|
...Prefs.subscriptions,
|
|
72
103
|
}))
|
|
73
104
|
```
|
|
74
105
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
`
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
`initial` passes `initial` in the mirror's config; defaults are read from it.
|
|
86
|
-
Under `Sync.mount`, the `url` option (`init`, `onUrlChange`) is where the URL
|
|
87
|
-
mirror plugs in.
|
|
106
|
+
The slice is field refs straight from `App.fields`, or a writable projection
|
|
107
|
+
over them (`Projection.pick`, `Projection.compose`) — the same object
|
|
108
|
+
`foldkit-sync` replicates. The URL comes in through the `onUrlChange` the
|
|
109
|
+
runtime already has for routing; `Filters.reduce` takes a Foldkit `Url` or an
|
|
110
|
+
href. The store comes in through one `MirrorRestored` case spread from
|
|
111
|
+
`Mirror.messages`. Links are `Filters.href(model, { page: 2 })`, the mirrored
|
|
112
|
+
keys applied to the current URL. An application built without `initial` passes
|
|
113
|
+
`initial` in the mirror's config; defaults are read from it. Under
|
|
114
|
+
`foldkit-sync`'s `mount`, the `url` option (`init`, `onUrlChange`) is where the
|
|
115
|
+
URL mirror plugs in.
|
|
88
116
|
|
|
89
117
|
## What the Model being the truth gives
|
|
90
118
|
|
|
@@ -166,6 +194,16 @@ pure URL step `href` and the URL store share.
|
|
|
166
194
|
cold load the URL wins when it names the key, then the store, then the
|
|
167
195
|
initial value: `init` reduces the URL first, and `restore` applies only
|
|
168
196
|
fields still at their initial value.
|
|
169
|
-
- The URL store touches only its keys and needs a browser `location`;
|
|
170
|
-
|
|
171
|
-
different keys.
|
|
197
|
+
- The URL store touches only its keys and needs a browser `location`; it uses
|
|
198
|
+
the query string unless `location: 'hash'` says otherwise. A Foldkit router's
|
|
199
|
+
`route.query(schema)` composes with it when they name different keys.
|
|
200
|
+
|
|
201
|
+
## See also
|
|
202
|
+
|
|
203
|
+
- [Mirrored state](https://github.com/doeixd/foldkit-plus/blob/main/docs/mirror.md) — the mental model, and when a
|
|
204
|
+
mirror is the wrong tool.
|
|
205
|
+
- [The design note](https://github.com/doeixd/foldkit-plus/blob/main/docs/design/MIRROR.md) — why a mirror is not
|
|
206
|
+
an owner.
|
|
207
|
+
- [`foldkit-sync`](https://github.com/doeixd/foldkit-plus/tree/main/packages/sync) — for state that must converge instead; its mount's `url` option
|
|
208
|
+
is where a URL mirror plugs in.
|
|
209
|
+
- [`examples/todo-app`](https://github.com/doeixd/foldkit-plus/tree/main/examples/todo-app) — a linkable filter and a remembered draft.
|
package/package.json
CHANGED
|
@@ -1,9 +1,20 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "foldkit-mirror",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"description": "A Foldkit Model slice kept in the URL or a key-value store: written when the slice changes, read back on navigation or cold load.",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"foldkit",
|
|
7
|
+
"effect",
|
|
8
|
+
"url-state",
|
|
9
|
+
"query-string",
|
|
10
|
+
"key-value-store",
|
|
11
|
+
"persistence"
|
|
12
|
+
],
|
|
5
13
|
"type": "module",
|
|
6
14
|
"license": "MIT",
|
|
15
|
+
"publishConfig": {
|
|
16
|
+
"access": "public"
|
|
17
|
+
},
|
|
7
18
|
"author": "Patrick Glenn <doeixd@gmail.com>",
|
|
8
19
|
"repository": {
|
|
9
20
|
"type": "git",
|
|
@@ -27,7 +38,7 @@
|
|
|
27
38
|
"LICENSE"
|
|
28
39
|
],
|
|
29
40
|
"dependencies": {
|
|
30
|
-
"foldkit-surface": "0.1.
|
|
41
|
+
"foldkit-surface": "0.1.1"
|
|
31
42
|
},
|
|
32
43
|
"peerDependencies": {
|
|
33
44
|
"effect": "^4.0.0-rc.112",
|