@kronor/dtv 9.4.0 → 9.4.2

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.
@@ -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
- * Dropdown items are not part of snapshots, so this is checked by nothing but you:
89
- * `dtv definitions snapshot --manual` makes a revision for it.
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: Json) => Json | typeof DROP): MigrationOp;
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. Undecided
77
- * `todo`s are problems too.
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. */
@@ -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, initial values or dropdown items, so for most
19
- factories that is all it takes.
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
 
@@ -24,7 +25,7 @@ factories that is all it takes.
24
25
  npx dtv definitions snapshot
25
26
  ```
26
27
 
27
- This writes a `dtv-migrations/<definition>/` folder (`v1.snapshot.ts`, `index.ts`) next to each
28
+ This writes a `dtv-migrations/<definition>/` folder (`rev1.snapshot.ts`, `index.ts`) next to each
28
29
  view's module, and wires the view up with it:
29
30
 
30
31
  ```ts
@@ -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
@@ -86,10 +96,11 @@ whose module is not found, such as JSON views; default `dtv-migrations`). Option
86
96
  ## Changing a view
87
97
 
88
98
  Change the definition, then run `npx dtv definitions snapshot`. For each changed view it writes the next
89
- snapshot and a migration:
99
+ snapshot and the migration into it (`rev4.snapshot.ts` and `rev4.migration.ts`), and adds the migration
100
+ to `index.ts`:
90
101
 
91
102
  ```ts
92
- export default DSL.defineMigration(v3, v4, m => [
103
+ export default DSL.defineMigration(rev3, rev4, m => [
93
104
  // "amt" was removed and "amount" added, with the same definition.
94
105
  // If "amount" is another filter that only looks the same: m.drop('amt')
95
106
  m.renameFilter('amt', 'amount'),
@@ -109,7 +120,8 @@ writes `m.todo(…)` with the candidates in comments. **A `todo` does not type-c
109
120
 
110
121
  | Change | Written |
111
122
  |---|---|
112
- | Filter or column added; labels, initial values, dropdown items changed | nothing |
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) |
113
125
  | Filter removed | `m.drop(id)` |
114
126
  | Filter removed and exactly one added with the same definition, matching no other | `m.renameFilter(old, new)` |
115
127
  | Filters removed and added with the same definition, but not one to one | `m.todo` for each removed one (rename or drop) |
@@ -128,18 +140,18 @@ writes `m.todo(…)` with the candidates in comments. **A `todo` does not type-c
128
140
  | `m.keep(id, { because })` | The filter changed, but every stored state still fits and means the same (checked: the state types fit). |
129
141
  | `m.reset(id)` | Stored state is dropped; the filter starts from its initial value. Users are told. |
130
142
  | `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. |
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). |
132
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. |
133
145
  | `m.custom(from, to, state => … \| RESET)` | Anything else; `state` is typed by both snapshots. |
134
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. |
135
147
 
136
- Ids are checked against the snapshots: `m.reset('amount')` does not compile if v3 has no `amount`.
148
+ Ids are checked against the snapshots: `m.reset('amount')` does not compile if rev3 has no `amount`.
137
149
 
138
150
  ### Changes the snapshots cannot see
139
151
 
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:
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:
143
155
 
144
156
  ```sh
145
157
  npx dtv definitions snapshot journal-list --manual "status values are lower case now"
@@ -172,8 +184,13 @@ are named in a notice.
172
184
 
173
185
  ## Known limits
174
186
 
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.
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.
177
194
  - Data written while a definition without a snapshot was deployed is stamped with the older revision
178
195
  but has the newer shape. Running `check` in CI is what prevents that.
179
196
  - Renaming a definition does not move the data of instances whose ids are derived from it
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kronor/dtv",
3
- "version": "9.4.0",
3
+ "version": "9.4.2",
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",