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.
Files changed (2) hide show
  1. package/README.md +75 -37
  2. package/package.json +13 -2
package/README.md CHANGED
@@ -1,13 +1,22 @@
1
1
  # `foldkit-mirror`
2
2
 
3
- A Foldkit Model slice kept in the URL or a key-value store. The Model is the
4
- only truth; a mirror names a slice of it and keeps an external keyed string
5
- store in step: the slice is written to the store whenever it changes, and read
6
- back into the Model on navigation or cold load. The URL query string and
7
- Effect's `KeyValueStore` are the two stores.
8
-
9
- A mirror is not an owner. It is last-write-wins to a dumb store with no log,
10
- which is what separates it from
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
- const Message = defineMessageUnion({ ...Mirror.messages, UrlChanged: { href: Schema.String }, … })
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 preferences and the draft across sessions.
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
- scope: userId,
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
- ```ts
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): Update.Return<Model, Message, KeyValueStore> {
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.href) }
65
- …
89
+ return { model: Filters.reduce(model, message.url) }
66
90
  }
67
91
  }
68
92
 
69
- const subscriptions = Subscription.make<Model, Message, KeyValueStore>()(() => ({
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
- `update` stays the only reducer. The slice is field refs straight from
76
- `App.fields`, or a writable projection over them (`Projection.pick`,
77
- `Projection.compose`), the same object `foldkit-sync` replicates. The URL comes
78
- in through the `onUrlChange` the runtime already has for routing
79
- (`Filters.reduce` takes a Foldkit `Url` or an href); the store comes in
80
- through one `MirrorRestored` case spread from `Mirror.messages`
81
- (`Prefs.reduce` takes that Message). Each mirror's `subscriptions` is one
82
- Subscription entry, keyed `<name>.mirror`, that writes the store when the
83
- encoded slice changes. Links are `Filters.href(model, { page: 2 })`, the
84
- mirrored keys applied to the current URL. An application built without
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`; a
170
- Foldkit router's `route.query(schema)` composes with it when they name
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.0",
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.0"
41
+ "foldkit-surface": "0.1.1"
31
42
  },
32
43
  "peerDependencies": {
33
44
  "effect": "^4.0.0-rc.112",