@kronor/dtv 9.4.1 → 9.4.3
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/dist/cli/commands/definitions.js +9 -4
- package/dist/cli/definitions/generate.js +33 -0
- package/dist/cli/definitions/loadProject.js +5 -1
- package/dist/cli/definitions/resolve.js +16 -4
- package/dist/cli/definitions/run.js +36 -6
- package/dist/index.es.js +4540 -4458
- package/dist/types/dsl/migrations.d.ts +11 -3
- package/dist/types/framework/view-migrations.d.ts +3 -2
- package/dist/types/framework/view-projection.d.ts +14 -0
- package/docs/view-migrations.md +25 -9
- package/package.json +1 -1
|
@@ -70,6 +70,10 @@ export type UndecodedFilterFormStateFor<F> = F extends {
|
|
|
70
70
|
child: UndecodedFilterFormStateFor<Child>;
|
|
71
71
|
} : never;
|
|
72
72
|
type StateOf<P extends ViewProjection, Id extends keyof P['filters']> = UndecodedFilterFormStateFor<P['filters'][Id]>;
|
|
73
|
+
/** A value a filter's items offer, when the snapshot has them; any value otherwise. */
|
|
74
|
+
export type ItemValueOf<P extends ViewProjection, Id extends string> = P extends {
|
|
75
|
+
items: infer Items;
|
|
76
|
+
} ? (Id extends keyof Items ? (Items[Id] extends readonly (infer V)[] ? V : Json) : Json) : Json;
|
|
73
77
|
/** The operations of a migration from the snapshot `From` to the snapshot `To`. */
|
|
74
78
|
export interface MigrationBuilder<From extends ViewProjection, To extends ViewProjection> {
|
|
75
79
|
/** The filter got another id; it is otherwise the same. */
|
|
@@ -85,10 +89,14 @@ export interface MigrationBuilder<From extends ViewProjection, To extends ViewPr
|
|
|
85
89
|
/**
|
|
86
90
|
* Rewrite the stored values of the filter's leaves, e.g. for renamed enum values. A list
|
|
87
91
|
* (a multiselect's value) is mapped element by element. Return `DROP` to remove a value.
|
|
88
|
-
*
|
|
89
|
-
*
|
|
92
|
+
*
|
|
93
|
+
* Where the snapshots have the filter's item values, the mapping takes one of the older
|
|
94
|
+
* snapshot's (other stored values are left as they are) and returns one of the newer
|
|
95
|
+
* one's; `dtv definitions check` runs it on each. Items that are not in snapshots (they
|
|
96
|
+
* come from data) leave it to you, as do query transforms: `dtv definitions snapshot
|
|
97
|
+
* --manual` makes a revision for such a change.
|
|
90
98
|
*/
|
|
91
|
-
mapValues<Id extends FilterIdOf<From> & FilterIdOf<To>>(id: Id, map: (value:
|
|
99
|
+
mapValues<Id extends FilterIdOf<From> & FilterIdOf<To>>(id: Id, map: (value: ItemValueOf<From, Id>) => ItemValueOf<To, Id> | typeof DROP): MigrationOp;
|
|
92
100
|
/** Map each custom operator the filter no longer offers to one it does, or to `null` to clear it. */
|
|
93
101
|
mapOperators<Id extends FilterIdOf<From> & FilterIdOf<To>>(id: Id, map: {
|
|
94
102
|
[O in Exclude<OperatorsOf<From['filters'][Id]>, OperatorsOf<To['filters'][Id]>>]: OperatorsOf<To['filters'][Id]> | null;
|
|
@@ -73,8 +73,9 @@ export type MigrationProblem = {
|
|
|
73
73
|
};
|
|
74
74
|
/**
|
|
75
75
|
* What `migration` leaves uncovered: replaying its operations over the older snapshot has
|
|
76
|
-
* to give the newer one, except for filters and columns the newer one adds.
|
|
77
|
-
*
|
|
76
|
+
* to give the newer one, except for filters and columns the newer one adds. Item values are
|
|
77
|
+
* compared where both snapshots have them: what may be stored for a filter has to stay among
|
|
78
|
+
* its items, or be mapped to them. Undecided `todo`s are problems too.
|
|
78
79
|
*/
|
|
79
80
|
export declare function checkMigration(migration: ViewMigration): MigrationProblem[];
|
|
80
81
|
/** Filters reset by migrations, or that lost stored values to them (`mapValues`, `mapOperators`), where they were stored. */
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import type { Json } from './decoder';
|
|
1
2
|
import type { FilterExpr } from './filters';
|
|
2
3
|
import { type View } from './view';
|
|
3
4
|
export type ControlProjection = {
|
|
@@ -44,8 +45,21 @@ export type ViewProjection = {
|
|
|
44
45
|
readonly columns: {
|
|
45
46
|
readonly [columnId: string]: ColumnProjection;
|
|
46
47
|
};
|
|
48
|
+
/**
|
|
49
|
+
* The values of the dropdown and multiselect items of filters whose items are fixed, by
|
|
50
|
+
* filter id: what may be stored for them. Left out when no filter has any.
|
|
51
|
+
*/
|
|
52
|
+
readonly items?: {
|
|
53
|
+
readonly [filterId: string]: readonly Json[];
|
|
54
|
+
};
|
|
47
55
|
};
|
|
48
56
|
export declare function projectFilter(expression: FilterExpr): FilterProjection;
|
|
57
|
+
/**
|
|
58
|
+
* The item values of a filter's dropdowns and multiselects, without repeats; `null` when it
|
|
59
|
+
* has none, or one that cannot be written into a snapshot. Controls inside a custom operator
|
|
60
|
+
* are left out: what is stored for those holds the operator too.
|
|
61
|
+
*/
|
|
62
|
+
export declare function itemValues(expression: FilterExpr): Json[] | null;
|
|
49
63
|
/** The projection of `view`, as revision `revision` of the definition `definition`. */
|
|
50
64
|
export declare function projectView(view: View, definition: string, revision: number): ViewProjection;
|
|
51
65
|
/** Whether two projections (or parts of them) are the same. Key order does not matter. */
|
package/docs/view-migrations.md
CHANGED
|
@@ -15,8 +15,9 @@ when it reads a user's data, and `dtv definitions check` fails CI when a definit
|
|
|
15
15
|
`dtv definitions` finds the views itself: the modules `scan` in `dtv.config.ts` matches that call
|
|
16
16
|
`DTV.view`, and in them the exports that are views or return one. A factory is built with arguments
|
|
17
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
|
|
19
|
-
|
|
18
|
+
What a snapshot records does not depend on labels or initial values, and it keeps only the
|
|
19
|
+
dropdown and multiselect items that are the same in both builds (fixed ones, like yes / no options;
|
|
20
|
+
items passed in as data are left out), so for most factories that is all it takes.
|
|
20
21
|
|
|
21
22
|
1. Snapshot every view:
|
|
22
23
|
|
|
@@ -51,6 +52,15 @@ factories that is all it takes.
|
|
|
51
52
|
npx dtv definitions check
|
|
52
53
|
```
|
|
53
54
|
|
|
55
|
+
`npx dtv definitions check journal-list` checks one definition.
|
|
56
|
+
|
|
57
|
+
It checks that each view uses its own migrations, that its latest snapshot is the definition as
|
|
58
|
+
it is, and that its migrations cover every change between snapshots: replaying each migration's
|
|
59
|
+
operations over the older snapshot gives the newer one, no `todo` is left, and a `mapValues`
|
|
60
|
+
maps the older item values to newer ones. It does not run `custom` migrations, cannot tell
|
|
61
|
+
whether a `keep` is right that stored state still means the same, and does not see changes
|
|
62
|
+
the snapshots cannot (see below).
|
|
63
|
+
|
|
54
64
|
### When a factory needs help
|
|
55
65
|
|
|
56
66
|
`dtv definitions` says which factories it cannot handle alone; configure them in `dtv.config.ts`, by export
|
|
@@ -110,7 +120,8 @@ writes `m.todo(…)` with the candidates in comments. **A `todo` does not type-c
|
|
|
110
120
|
|
|
111
121
|
| Change | Written |
|
|
112
122
|
|---|---|
|
|
113
|
-
| Filter or column added; labels
|
|
123
|
+
| Filter or column added; labels or initial values changed; items added | nothing |
|
|
124
|
+
| Fixed items removed (their values may be stored) | `m.todo` (map them with `m.mapValues`, or reset) |
|
|
114
125
|
| Filter removed | `m.drop(id)` |
|
|
115
126
|
| Filter removed and exactly one added with the same definition, matching no other | `m.renameFilter(old, new)` |
|
|
116
127
|
| Filters removed and added with the same definition, but not one to one | `m.todo` for each removed one (rename or drop) |
|
|
@@ -129,7 +140,7 @@ writes `m.todo(…)` with the candidates in comments. **A `todo` does not type-c
|
|
|
129
140
|
| `m.keep(id, { because })` | The filter changed, but every stored state still fits and means the same (checked: the state types fit). |
|
|
130
141
|
| `m.reset(id)` | Stored state is dropped; the filter starts from its initial value. Users are told. |
|
|
131
142
|
| `m.drop(id)` | The filter was removed. |
|
|
132
|
-
| `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. |
|
|
143
|
+
| `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. Where the snapshots have the filter's items, `value` is one of the older items (other stored values are left as they are) and the result has to be one of the newer ones (checked by the types, and by running it). |
|
|
133
144
|
| `m.mapOperators(id, { old: 'new' \| null })` | Custom operators were removed (checked: every removed one is mapped). `null` clears what used it; users are told. |
|
|
134
145
|
| `m.custom(from, to, state => … \| RESET)` | Anything else; `state` is typed by both snapshots. |
|
|
135
146
|
| `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. |
|
|
@@ -138,9 +149,9 @@ Ids are checked against the snapshots: `m.reset('amount')` does not compile if r
|
|
|
138
149
|
|
|
139
150
|
### Changes the snapshots cannot see
|
|
140
151
|
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
revision by hand:
|
|
152
|
+
Items that come from data, query transforms and what custom filter components store are not in
|
|
153
|
+
snapshots. When stored values need to change for such a reason — status values from the database
|
|
154
|
+
renamed, a transform now reading major instead of minor units — make a revision by hand:
|
|
144
155
|
|
|
145
156
|
```sh
|
|
146
157
|
npx dtv definitions snapshot journal-list --manual "status values are lower case now"
|
|
@@ -173,8 +184,13 @@ are named in a notice.
|
|
|
173
184
|
|
|
174
185
|
## Known limits
|
|
175
186
|
|
|
176
|
-
- Snapshots do not see query transforms or what a custom filter
|
|
177
|
-
changes what a stored value means, make a `--manual`
|
|
187
|
+
- Snapshots do not see items that come from data, query transforms, or what a custom filter
|
|
188
|
+
component stores. When one of them changes what a stored value means, make a `--manual`
|
|
189
|
+
revision; nothing warns you to.
|
|
190
|
+
- Items are told apart by building a factory twice: items that come neither from its arguments nor
|
|
191
|
+
from literals (read from a module-level store, say) are taken for fixed ones.
|
|
192
|
+
- Snapshots written by dtv 9.4 have no items; `check` compares items only where a snapshot has
|
|
193
|
+
them, and the next `snapshot` adds them to the latest snapshot without a revision.
|
|
178
194
|
- Data written while a definition without a snapshot was deployed is stamped with the older revision
|
|
179
195
|
but has the newer shape. Running `check` in CI is what prevents that.
|
|
180
196
|
- Renaming a definition does not move the data of instances whose ids are derived from it
|