@kronor/dtv 9.3.0 → 9.4.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.
Files changed (38) hide show
  1. package/README.md +8 -2
  2. package/dist/cli/commands/definitions.js +76 -0
  3. package/dist/cli/config/loadConfig.js +69 -5
  4. package/dist/cli/definitions/discover.js +130 -0
  5. package/dist/cli/definitions/generate.js +258 -0
  6. package/dist/cli/definitions/loadProject.js +107 -0
  7. package/dist/cli/definitions/project.js +122 -0
  8. package/dist/cli/definitions/resolve.js +53 -0
  9. package/dist/cli/definitions/run.js +223 -0
  10. package/dist/cli/definitions/types.js +8 -0
  11. package/dist/cli/definitions/wire.js +111 -0
  12. package/dist/cli/dtv.js +2 -0
  13. package/dist/cli/typegen/runTypegen.js +4 -3
  14. package/dist/index.es.js +14103 -13451
  15. package/dist/types/components/UserPreferencesPanel.d.ts +2 -1
  16. package/dist/types/dsl/index.d.ts +1 -0
  17. package/dist/types/dsl/migrations.d.ts +114 -0
  18. package/dist/types/framework/decoder.d.ts +61 -0
  19. package/dist/types/framework/filter-form-state.d.ts +18 -2
  20. package/dist/types/framework/filter-sharing.d.ts +21 -9
  21. package/dist/types/framework/runtime.d.ts +2 -0
  22. package/dist/types/framework/saved-filters.d.ts +10 -14
  23. package/dist/types/framework/state/app-state.d.ts +8 -0
  24. package/dist/types/framework/useUserDataManager.d.ts +3 -0
  25. package/dist/types/framework/user-data-errors.d.ts +8 -0
  26. package/dist/types/framework/user-data-manager.d.ts +6 -1
  27. package/dist/types/framework/user-data-undecoded.d.ts +86 -0
  28. package/dist/types/framework/user-data.d.ts +120 -33
  29. package/dist/types/framework/user-data.migrations.d.ts +9 -8
  30. package/dist/types/framework/view-migrations.d.ts +112 -0
  31. package/dist/types/framework/view-parser.d.ts +2 -1
  32. package/dist/types/framework/view-projection.d.ts +52 -0
  33. package/dist/types/framework/view.d.ts +7 -0
  34. package/dist/types/lib/index.d.ts +4 -0
  35. package/dist/types/typegen/index.d.ts +26 -4
  36. package/docs/typegen.md +12 -0
  37. package/docs/view-migrations.md +182 -0
  38. package/package.json +1 -1
@@ -0,0 +1,182 @@
1
+ # View migrations
2
+
3
+ Users' saved filters, their persisted filter state, hidden columns, sorting and shared links are stored
4
+ against a view's definition: by filter and column ids, and in the shape of each filter's
5
+ expression. When the definition changes, what is stored has to change with it, or it is lost —
6
+ or worse, silently means something else (a reordered date range swaps its bounds; a filter now
7
+ on minor units keeps a value in major units).
8
+
9
+ DTV handles this with **view migrations**: each revision of a view definition is committed as a
10
+ snapshot, and a migration between two snapshots says what happens to stored data. DTV runs them
11
+ when it reads a user's data, and `dtv definitions check` fails CI when a definition changed without one.
12
+
13
+ ## Setup
14
+
15
+ `dtv definitions` finds the views itself: the modules `scan` in `dtv.config.ts` matches that call
16
+ `DTV.view`, and in them the exports that are views or return one. A factory is built with arguments
17
+ made up from its parameter types — twice, minimal and contrasting, to see what its arguments change.
18
+ What a snapshot records does not depend on labels, initial values or dropdown items, so for most
19
+ factories that is all it takes.
20
+
21
+ 1. Snapshot every view:
22
+
23
+ ```sh
24
+ npx dtv definitions snapshot
25
+ ```
26
+
27
+ This writes a `dtv-migrations/<definition>/` folder (`v1.snapshot.ts`, `index.ts`) next to each
28
+ view's module, and wires the view up with it:
29
+
30
+ ```ts
31
+ import journalListMigrations from './dtv-migrations/journal-list';
32
+
33
+ DTV.view({ id: 'journal-list', migrations: journalListMigrations, … })
34
+ ```
35
+
36
+ Where it cannot tell which `DTV.view` call is the view's (several calls with computed ids in one
37
+ module), or the module is not known (JSON views), it prints these lines to add instead.
38
+
39
+ Once a view imports its migrations, that import is where they are: move the folder anywhere and
40
+ update the import, and `dtv definitions` follows it.
41
+
42
+ JSON views reference them from the runtime instead: `"migrations": { "section": "viewMigrations",
43
+ "key": "journal-list" }`, with the chain under `viewMigrations` in the external runtime.
44
+
45
+ Later runs write revisions for the views that changed; views without changes are only counted
46
+ (`172 views up to date`).
47
+
48
+ 2. In CI:
49
+
50
+ ```sh
51
+ npx dtv definitions check
52
+ ```
53
+
54
+ ### When a factory needs help
55
+
56
+ `dtv definitions` says which factories it cannot handle alone; configure them in `dtv.config.ts`, by export
57
+ name (or `path/to/module.ts#name` when several modules export the name):
58
+
59
+ ```ts
60
+ definitions: {
61
+ factories: {
62
+ // Its id is computed from its arguments (`${entityLog}-history-list`): name the definition.
63
+ historyDtvView: { definition: 'history-list' },
64
+ // Its arguments change its filters, or it throws on made-up ones: give the arguments.
65
+ someDialogView: { args: [{ mode: 'dialog', items: [{ id: 1 }] }] },
66
+ },
67
+ },
68
+ ```
69
+
70
+ A factory whose arguments only add a suffix to its id (`asset-list` → `asset-list-7`) needs nothing:
71
+ the id without the suffix is the definition id, and every instance shares its migrations. Columns
72
+ that only some arguments add (e.g. an actions column for passed callbacks) all go into the snapshot.
73
+
74
+ ### Loading
75
+
76
+ The views are loaded through the project's own Vite and Vite config (aliases, styles and `?raw`
77
+ imports resolve as in the app), with dependencies bundled for SSR, and with the project's `jsdom` as
78
+ browser globals for modules that touch `window` as they load. `dtv.config.ts` is loaded without Vite:
79
+ it must not import view modules, and anything it needs only for typegen (a schema secret from the
80
+ environment) belongs in `schema` written as a function, which only `dtv typegen` calls.
81
+
82
+ `definitions` in `dtv.config.ts` also takes `viteConfig` and `migrationsDir` (where migrations go for views
83
+ whose module is not found, such as JSON views; default `dtv-migrations`). Options: `--config`,
84
+ `--vite-config`, `--migrations-dir`.
85
+
86
+ ## Changing a view
87
+
88
+ Change the definition, then run `npx dtv definitions snapshot`. For each changed view it writes the next
89
+ snapshot and a migration:
90
+
91
+ ```ts
92
+ export default DSL.defineMigration(v3, v4, m => [
93
+ // "amt" was removed and "amount" added, with the same definition.
94
+ // If "amount" is another filter that only looks the same: m.drop('amt')
95
+ m.renameFilter('amt', 'amount'),
96
+ m.drop('legacy'),
97
+ // "status": its field changed from "status" to "state".
98
+ // Same meaning: m.keep('status', { because: '…' })
99
+ // Otherwise: m.reset('status')
100
+ m.todo('status', 'its field changed from "status" to "state"; does what is stored still mean the same?'),
101
+ m.resetSort('amount'),
102
+ ]);
103
+ ```
104
+
105
+ What the diff decides alone is written out. Where a person has to decide — which of several
106
+ look-alike filters was renamed to which, whether a filter on another field still means the same — it
107
+ writes `m.todo(…)` with the candidates in comments. **A `todo` does not type-check and fails
108
+ `dtv definitions check`**: replace it with the operation you mean.
109
+
110
+ | Change | Written |
111
+ |---|---|
112
+ | Filter or column added; labels, initial values, dropdown items changed | nothing |
113
+ | Filter removed | `m.drop(id)` |
114
+ | Filter removed and exactly one added with the same definition, matching no other | `m.renameFilter(old, new)` |
115
+ | Filters removed and added with the same definition, but not one to one | `m.todo` for each removed one (rename or drop) |
116
+ | Filter removed and one added that its stored state fits, after a change | `m.todo` (`custom` rename, or drop) |
117
+ | Filter gained/lost parts, or its control changed type | `m.reset(id)` |
118
+ | Filter's comparison or field changed | `m.todo` (keep or reset) |
119
+ | Custom operators added / removed | `m.mapOperators(id, {})` / `m.todo` (map them) |
120
+ | Column removed, none added / some added | `m.dropColumn(id)` / `m.todo` (rename or drop) |
121
+ | Column sorts by another field | `m.resetSort(id)` |
122
+
123
+ ### Operations
124
+
125
+ | Operation | Use when |
126
+ |---|---|
127
+ | `m.renameFilter(from, to)` | Only the id changed (checked: both have the same definition). |
128
+ | `m.keep(id, { because })` | The filter changed, but every stored state still fits and means the same (checked: the state types fit). |
129
+ | `m.reset(id)` | Stored state is dropped; the filter starts from its initial value. Users are told. |
130
+ | `m.drop(id)` | The filter was removed. |
131
+ | `m.mapValues(id, value => …)` | Stored values change, e.g. renamed enum values. Lists are mapped element by element; return `DROP` to remove one. Users are told about removed values. |
132
+ | `m.mapOperators(id, { old: 'new' \| null })` | Custom operators were removed (checked: every removed one is mapped). `null` clears what used it; users are told. |
133
+ | `m.custom(from, to, state => … \| RESET)` | Anything else; `state` is typed by both snapshots. |
134
+ | `m.renameColumn(from, to)`, `m.dropColumn(id)`, `m.resetSort(id)` | Columns. A stored sort by what a dropped column, or one given `resetSort`, sorted by is reset. |
135
+
136
+ Ids are checked against the snapshots: `m.reset('amount')` does not compile if v3 has no `amount`.
137
+
138
+ ### Changes the snapshots cannot see
139
+
140
+ Dropdown items and query transforms are not in snapshots. When stored values need to change for
141
+ such a reason — enum values renamed, a transform now reading major instead of minor units — make a
142
+ revision by hand:
143
+
144
+ ```sh
145
+ npx dtv definitions snapshot journal-list --manual "status values are lower case now"
146
+ ```
147
+
148
+ and replace its `todo` with e.g. `m.mapValues('status', value => typeof value === 'string' ? value.toLowerCase() : value)`.
149
+
150
+ ### Renaming a view
151
+
152
+ ```sh
153
+ npx dtv definitions snapshot payment-list --renamed-from payments
154
+ ```
155
+
156
+ renames the `payments` folder (where it is), points the view's import at it, and adds a revision. Users'
157
+ data stored under `payments` is taken over by `payment-list`. Views whose ids are derived from the definition id (`${id}-credit`, …) keep their
158
+ own data, which a rename does not move.
159
+
160
+ ## At runtime
161
+
162
+ When DTV reads a user's data, each view's data is migrated from the revision it was written for to
163
+ the view's current one, and written back. Filters reset along the way, or that lost stored values,
164
+ are named in a notice.
165
+
166
+ - Data written for a newer revision than the running app knows (an old tab, a rollback) is left
167
+ untouched.
168
+ - If a view's filters differ from its latest snapshot (`dtv definitions snapshot` was not run), an
169
+ error is logged and the stored state of the changed filters is reset rather than misread. Columns
170
+ are not compared at runtime (an instance may show a column only with some arguments); `check` does.
171
+ - Shared links carry the view and revision they were made for, and are migrated too.
172
+
173
+ ## Known limits
174
+
175
+ - Snapshots do not see query transforms or what a custom filter component stores. When either
176
+ changes what a stored value means, make a `--manual` revision; nothing warns you to.
177
+ - Data written while a definition without a snapshot was deployed is stamped with the older revision
178
+ but has the newer shape. Running `check` in CI is what prevents that.
179
+ - Renaming a definition does not move the data of instances whose ids are derived from it
180
+ (`…-${orderId}`).
181
+ - View ids must be unique across all apps that share one user's data.
182
+ - Views with an id per record (one per order, say) each store their own data, which grows without bound.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kronor/dtv",
3
- "version": "9.3.0",
3
+ "version": "9.4.0",
4
4
  "description": "Schema-driven, declarative table views with advanced filtering, data fetching and AI-assisted filter generation.",
5
5
  "repository": {
6
6
  "type": "git",