@verevoir/aigency-work 0.0.0-stage → 0.2.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/CHANGELOG.md +85 -0
- package/LICENSE +201 -0
- package/README.md +23 -2
- package/dist/asf-board.d.ts +29 -0
- package/dist/asf-board.js +826 -0
- package/dist/board.d.ts +428 -0
- package/dist/board.js +6 -0
- package/dist/card.d.ts +94 -0
- package/dist/card.js +89 -0
- package/dist/in-memory-board.d.ts +16 -0
- package/dist/in-memory-board.js +160 -0
- package/dist/in-memory-store.d.ts +26 -0
- package/dist/in-memory-store.js +79 -0
- package/dist/index.d.ts +22 -0
- package/dist/index.js +15 -0
- package/dist/move-card.d.ts +141 -0
- package/dist/move-card.js +104 -0
- package/dist/multiplexer.d.ts +55 -0
- package/dist/multiplexer.js +54 -0
- package/dist/notion-board.d.ts +47 -0
- package/dist/notion-board.js +733 -0
- package/dist/payload-board.d.ts +50 -0
- package/dist/payload-board.js +225 -0
- package/dist/payload.d.ts +55 -0
- package/dist/payload.js +151 -0
- package/dist/schema-change.d.ts +78 -0
- package/dist/schema-change.js +0 -0
- package/dist/store-board.d.ts +33 -0
- package/dist/store-board.js +426 -0
- package/dist/store.d.ts +105 -0
- package/dist/store.js +13 -0
- package/package.json +45 -4
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
import type { CardSource, CardSink } from './board.js';
|
|
2
|
+
export interface PayloadBoard extends CardSource, CardSink {
|
|
3
|
+
/**
|
|
4
|
+
* Makes every subsequent `get`, `list` and `writeState` call report
|
|
5
|
+
* `unreachable` with this reason (for `createCard` and `annotate` too), regardless of what is stored —
|
|
6
|
+
* reachability is checked independently of content, never inferred
|
|
7
|
+
* from it. Mirrors `InMemoryBoard.setUnreachable`.
|
|
8
|
+
*/
|
|
9
|
+
setUnreachable(reason: string): void;
|
|
10
|
+
/** Undoes `setUnreachable`. */
|
|
11
|
+
setReachable(): void;
|
|
12
|
+
/**
|
|
13
|
+
* Puts a raw payload directly into the board, for setting up a
|
|
14
|
+
* scenario — stored exactly as given, unparsed and unvalidated. A real
|
|
15
|
+
* tracker does not validate on your behalf either; validation is what
|
|
16
|
+
* `get` and `list` apply on the way out, never something this board
|
|
17
|
+
* does on the way in. That is what makes it possible to seed a payload
|
|
18
|
+
* that will not parse: this method has to accept it, or there would be
|
|
19
|
+
* no way to exercise the outcome it exists to test.
|
|
20
|
+
*
|
|
21
|
+
* `id` is the key the board answers to — independent of whatever `id`
|
|
22
|
+
* field, valid or not, the payload itself carries. See
|
|
23
|
+
* `UnparseableRecord` for why that independence matters.
|
|
24
|
+
*/
|
|
25
|
+
putPayload(id: string, payload: unknown): void;
|
|
26
|
+
/**
|
|
27
|
+
* Returns exactly what is stored under `id` right now — no parsing,
|
|
28
|
+
* no stripping, no rendering. The counterpart to `putPayload`: that
|
|
29
|
+
* seeds the raw state a scenario starts from, this reads the raw
|
|
30
|
+
* state a scenario ends in. Needed because `get`/`list` always strip
|
|
31
|
+
* `revision` (see `stripRevision` below) — a regression that let a
|
|
32
|
+
* write re-render one into storage would be invisible through them
|
|
33
|
+
* regardless, so a test proving "never re-emitted" has to look here,
|
|
34
|
+
* not through `get`.
|
|
35
|
+
*/
|
|
36
|
+
peekPayload(id: string): unknown;
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* The reason given for any write that supplies `expectedRevision` —
|
|
40
|
+
* exported so a test can assert against the exact string this board
|
|
41
|
+
* produces, rather than a loose substring match standing in for "names
|
|
42
|
+
* it". The outcome itself is `unsupported`, not `refused`: this board
|
|
43
|
+
* was reached and understood the request, it simply has no
|
|
44
|
+
* compare-and-set primitive underneath it to honour the guard with.
|
|
45
|
+
*/
|
|
46
|
+
export declare const EXPECTED_REVISION_UNSUPPORTED_REASON = "expectedRevision is not supported by PayloadBoard: it has no compare-and-set primitive over its backing payload store";
|
|
47
|
+
export declare function createPayloadBoard(initial?: readonly {
|
|
48
|
+
readonly id: string;
|
|
49
|
+
readonly payload: unknown;
|
|
50
|
+
}[]): PayloadBoard;
|
|
@@ -0,0 +1,225 @@
|
|
|
1
|
+
// A `CardSource` and `CardSink` backed by raw payloads rather than parsed
|
|
2
|
+
// `Card`s. `in-memory-board.ts` is a fake of a tracker that has already
|
|
3
|
+
// been parsed — every card it holds arrived through `put`, already a
|
|
4
|
+
// valid `Card`. A real tracker never hands over anything already parsed;
|
|
5
|
+
// parsing is the step this boundary applies on the way in, not a
|
|
6
|
+
// precondition the tracker meets for it. `PayloadBoard` is what stands in
|
|
7
|
+
// for that: a store of whatever a tracker actually returns, with parsing
|
|
8
|
+
// happening on every read and rendering happening on every write, exactly
|
|
9
|
+
// where they happen against a real one.
|
|
10
|
+
//
|
|
11
|
+
// Why this board does not support `expectedRevision`
|
|
12
|
+
// -----------------------------------------------------
|
|
13
|
+
// `StoreBoard` can honour an optimistic-concurrency guard (see `board.ts`'s
|
|
14
|
+
// `WriteOptions`) honestly because it sits over `Store`'s own
|
|
15
|
+
// compare-and-set: a revision bumped in the same `replace` call that
|
|
16
|
+
// applies a change is a real guard, backed by a real atomic primitive.
|
|
17
|
+
// `PayloadBoard` has no such primitive underneath it — `payloads` is a
|
|
18
|
+
// plain `Map`, written to directly, with nothing resembling a
|
|
19
|
+
// conditional write at all. A side counter that merely increments on
|
|
20
|
+
// every accepted write, with nothing beneath it that could ever actually
|
|
21
|
+
// lose a race, is not a guard; it is a guard-shaped placeholder that
|
|
22
|
+
// would always either match or not match exactly once, telling a caller
|
|
23
|
+
// nothing true about contention. Rather than pretend, this board omits
|
|
24
|
+
// `Card.revision` entirely — it is simply never set — and answers ANY
|
|
25
|
+
// write that supplies `expectedRevision` with the `unsupported`
|
|
26
|
+
// outcome (see `board.ts`'s `WriteResult` doc), naming explicitly that
|
|
27
|
+
// the guard is not supported here, never the unrelated `refused`. A
|
|
28
|
+
// caller that actually needs optimistic concurrency over raw payloads
|
|
29
|
+
// needs a board backed by something with a real conditional write, which
|
|
30
|
+
// is exactly the gap `StoreBoard` exists to fill.
|
|
31
|
+
//
|
|
32
|
+
// "Never set" means never set, even on the way IN. A payload that
|
|
33
|
+
// already carries a *string* `revision` key — written by some other
|
|
34
|
+
// adapter, or left over from a test fixture — has it stripped on every
|
|
35
|
+
// read and never re-emitted on any write; see `stripRevision` below,
|
|
36
|
+
// which only strips the known `Card.revision` field a string revision
|
|
37
|
+
// becomes. A *non-string* `revision` is a different case entirely:
|
|
38
|
+
// `payload.ts` treats it as mistyped and carries it through
|
|
39
|
+
// `unknownFields`, exactly like any other key this boundary does not
|
|
40
|
+
// recognise — `stripRevision` has nothing to strip there, so it rides
|
|
41
|
+
// along and is re-emitted on every write the same as every other
|
|
42
|
+
// unrecognised key, never faked as a real guard either way.
|
|
43
|
+
// `payload.ts`'s `parseCardPayload`/`renderCardPayload` round-trip
|
|
44
|
+
// `revision` generically, because they are shared with boards that DO
|
|
45
|
+
// have a real compare-and-set primitive underneath them — this board is
|
|
46
|
+
// not one of them, and must not let that generic round-tripping leak a
|
|
47
|
+
// fake, never-moving revision through regardless of what a stored
|
|
48
|
+
// payload happens to contain.
|
|
49
|
+
import { parseCardPayload, renderCardPayload } from './payload.js';
|
|
50
|
+
function formatProblems(problems) {
|
|
51
|
+
return problems.map((problem) => `${problem.field}: ${problem.message}`).join('; ');
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* Strips any `revision` a card carries before this board hands it to a
|
|
55
|
+
* caller, or stores it — see this file's header. Without this,
|
|
56
|
+
* `payload.ts`'s generic round-tripping of `revision` would let one
|
|
57
|
+
* leak through here even though this board has no compare-and-set
|
|
58
|
+
* primitive to make it genuine.
|
|
59
|
+
*/
|
|
60
|
+
function stripRevision(card) {
|
|
61
|
+
if (card.revision === undefined) {
|
|
62
|
+
return card;
|
|
63
|
+
}
|
|
64
|
+
return {
|
|
65
|
+
id: card.id,
|
|
66
|
+
state: card.state,
|
|
67
|
+
reference: card.reference,
|
|
68
|
+
source: card.source,
|
|
69
|
+
unknownFields: card.unknownFields,
|
|
70
|
+
...(card.properties !== undefined ? { properties: card.properties } : {}),
|
|
71
|
+
};
|
|
72
|
+
}
|
|
73
|
+
/**
|
|
74
|
+
* The reason given for any write that supplies `expectedRevision` —
|
|
75
|
+
* exported so a test can assert against the exact string this board
|
|
76
|
+
* produces, rather than a loose substring match standing in for "names
|
|
77
|
+
* it". The outcome itself is `unsupported`, not `refused`: this board
|
|
78
|
+
* was reached and understood the request, it simply has no
|
|
79
|
+
* compare-and-set primitive underneath it to honour the guard with.
|
|
80
|
+
*/
|
|
81
|
+
export const EXPECTED_REVISION_UNSUPPORTED_REASON = 'expectedRevision is not supported by PayloadBoard: it has no compare-and-set primitive over its backing payload store';
|
|
82
|
+
export function createPayloadBoard(initial = []) {
|
|
83
|
+
const payloads = new Map();
|
|
84
|
+
for (const { id, payload } of initial) {
|
|
85
|
+
payloads.set(id, payload);
|
|
86
|
+
}
|
|
87
|
+
let unreachableReason;
|
|
88
|
+
return {
|
|
89
|
+
async get(id) {
|
|
90
|
+
if (unreachableReason !== undefined) {
|
|
91
|
+
return { outcome: 'unreachable', reason: unreachableReason };
|
|
92
|
+
}
|
|
93
|
+
const payload = payloads.get(id);
|
|
94
|
+
if (payload === undefined) {
|
|
95
|
+
return { outcome: 'absent' };
|
|
96
|
+
}
|
|
97
|
+
const parsed = parseCardPayload(payload);
|
|
98
|
+
if (parsed.ok) {
|
|
99
|
+
return { outcome: 'found', card: stripRevision(parsed.card) };
|
|
100
|
+
}
|
|
101
|
+
return { outcome: 'unparseable', id, problems: parsed.problems };
|
|
102
|
+
},
|
|
103
|
+
async list() {
|
|
104
|
+
if (unreachableReason !== undefined) {
|
|
105
|
+
return { outcome: 'unreachable', reason: unreachableReason };
|
|
106
|
+
}
|
|
107
|
+
if (payloads.size === 0) {
|
|
108
|
+
return { outcome: 'empty' };
|
|
109
|
+
}
|
|
110
|
+
const cards = [];
|
|
111
|
+
const unparseable = [];
|
|
112
|
+
for (const [id, payload] of payloads) {
|
|
113
|
+
const parsed = parseCardPayload(payload);
|
|
114
|
+
if (parsed.ok) {
|
|
115
|
+
cards.push(stripRevision(parsed.card));
|
|
116
|
+
}
|
|
117
|
+
else {
|
|
118
|
+
unparseable.push({ id, problems: parsed.problems });
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
// No index here either — this board enumerates its `payloads` map
|
|
122
|
+
// directly, so there is nothing that could name an id the map
|
|
123
|
+
// itself does not also hold.
|
|
124
|
+
return { outcome: 'cards', cards, unparseable, danglingIds: [] };
|
|
125
|
+
},
|
|
126
|
+
async writeState(id, state, options) {
|
|
127
|
+
if (unreachableReason !== undefined) {
|
|
128
|
+
return { outcome: 'unreachable', reason: unreachableReason };
|
|
129
|
+
}
|
|
130
|
+
const payload = payloads.get(id);
|
|
131
|
+
if (payload === undefined) {
|
|
132
|
+
return { outcome: 'refused', reason: `no card with id ${id}` };
|
|
133
|
+
}
|
|
134
|
+
if (options?.expectedRevision !== undefined) {
|
|
135
|
+
return { outcome: 'unsupported', id, reason: EXPECTED_REVISION_UNSUPPORTED_REASON };
|
|
136
|
+
}
|
|
137
|
+
const parsed = parseCardPayload(payload);
|
|
138
|
+
if (!parsed.ok) {
|
|
139
|
+
// The sink does not need to understand a payload to change one
|
|
140
|
+
// field of it — a blind `{ ...payload, state }` would work
|
|
141
|
+
// whether or not `payload` parses. It is refused anyway. Writing
|
|
142
|
+
// blind to a record nobody can read does not fix the record;
|
|
143
|
+
// it produces a *second* problem — a state that silently
|
|
144
|
+
// changed underneath a payload still nobody can read — on top
|
|
145
|
+
// of the first, and does so by a path that bypasses every check
|
|
146
|
+
// this boundary applies everywhere else it touches a payload.
|
|
147
|
+
// `refused` is the right outcome, not `unreachable`: the board
|
|
148
|
+
// was reached, and it read the record — it is declining an
|
|
149
|
+
// action it knows would be unsafe, which is exactly what
|
|
150
|
+
// `refused` means elsewhere in this boundary (see `board.ts`).
|
|
151
|
+
return {
|
|
152
|
+
outcome: 'refused',
|
|
153
|
+
reason: `stored payload for ${id} does not parse as a card, so its state cannot be safely written: ${formatProblems(parsed.problems)}`,
|
|
154
|
+
};
|
|
155
|
+
}
|
|
156
|
+
const updated = { ...stripRevision(parsed.card), state };
|
|
157
|
+
payloads.set(id, renderCardPayload(updated));
|
|
158
|
+
return { outcome: 'applied' };
|
|
159
|
+
},
|
|
160
|
+
async createCard(card) {
|
|
161
|
+
if (unreachableReason !== undefined) {
|
|
162
|
+
return { outcome: 'unreachable', reason: unreachableReason };
|
|
163
|
+
}
|
|
164
|
+
// A broken record still occupies its id, so occupancy is checked on
|
|
165
|
+
// the raw payload, not on whether it parses.
|
|
166
|
+
if (payloads.get(card.id) !== undefined) {
|
|
167
|
+
return { outcome: 'refused', reason: `card ${card.id} already exists` };
|
|
168
|
+
}
|
|
169
|
+
payloads.set(card.id, renderCardPayload(stripRevision(card)));
|
|
170
|
+
return { outcome: 'applied' };
|
|
171
|
+
},
|
|
172
|
+
async annotate(id, patch, options) {
|
|
173
|
+
if (unreachableReason !== undefined) {
|
|
174
|
+
return { outcome: 'unreachable', reason: unreachableReason };
|
|
175
|
+
}
|
|
176
|
+
const payload = payloads.get(id);
|
|
177
|
+
if (payload === undefined) {
|
|
178
|
+
return { outcome: 'refused', reason: `no card with id ${id}` };
|
|
179
|
+
}
|
|
180
|
+
if (options?.expectedRevision !== undefined) {
|
|
181
|
+
return { outcome: 'unsupported', id, reason: EXPECTED_REVISION_UNSUPPORTED_REASON };
|
|
182
|
+
}
|
|
183
|
+
const parsed = parseCardPayload(payload);
|
|
184
|
+
if (!parsed.ok) {
|
|
185
|
+
return {
|
|
186
|
+
outcome: 'refused',
|
|
187
|
+
reason: `stored payload for ${id} does not parse as a card, so its properties cannot be safely annotated: ${formatProblems(parsed.problems)}`,
|
|
188
|
+
};
|
|
189
|
+
}
|
|
190
|
+
// A `properties` value that is not a flat string record never
|
|
191
|
+
// becomes `Card.properties` — `parseCardPayload` keeps it whole,
|
|
192
|
+
// unchanged, in `unknownFields.properties` instead (see
|
|
193
|
+
// `payload.ts`). Rendering a brand-new known `properties` field
|
|
194
|
+
// over that card would apply AFTER `unknownFields` is spread (see
|
|
195
|
+
// `renderCardPayload`), silently overwriting the tracker's own
|
|
196
|
+
// shape with annotate's patch — the one write this board can make
|
|
197
|
+
// that a caller could never undo by reading it back. Refused
|
|
198
|
+
// instead, exactly as an unparseable payload already is above.
|
|
199
|
+
if (parsed.card.unknownFields.properties !== undefined) {
|
|
200
|
+
return {
|
|
201
|
+
outcome: 'refused',
|
|
202
|
+
reason: `card ${id}'s properties are a tracker-shaped object, not a flat string bag; annotate would overwrite them`,
|
|
203
|
+
};
|
|
204
|
+
}
|
|
205
|
+
const updated = {
|
|
206
|
+
...stripRevision(parsed.card),
|
|
207
|
+
properties: { ...parsed.card.properties, ...patch.properties },
|
|
208
|
+
};
|
|
209
|
+
payloads.set(id, renderCardPayload(updated));
|
|
210
|
+
return { outcome: 'applied' };
|
|
211
|
+
},
|
|
212
|
+
setUnreachable(reason) {
|
|
213
|
+
unreachableReason = reason;
|
|
214
|
+
},
|
|
215
|
+
setReachable() {
|
|
216
|
+
unreachableReason = undefined;
|
|
217
|
+
},
|
|
218
|
+
putPayload(id, payload) {
|
|
219
|
+
payloads.set(id, payload);
|
|
220
|
+
},
|
|
221
|
+
peekPayload(id) {
|
|
222
|
+
return payloads.get(id);
|
|
223
|
+
},
|
|
224
|
+
};
|
|
225
|
+
}
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
import type { Card, ParseResult } from './card.js';
|
|
2
|
+
/**
|
|
3
|
+
* Turns a raw tracker payload into a `Card`, or refuses it.
|
|
4
|
+
*
|
|
5
|
+
* Recognition is by key name only, never by shape: a key named `id`,
|
|
6
|
+
* `state`, `reference`, `source`, `revision` or `properties` is treated
|
|
7
|
+
* as that known field — except `revision` and `properties`, which have a
|
|
8
|
+
* documented exception below: when present but not the shape they are
|
|
9
|
+
* supposed to be, they are not malformed instances of the known field at
|
|
10
|
+
* all, so they are bucketed into `unknownFields` instead of refusing the
|
|
11
|
+
* whole payload for a problem confined to one optional key. `id`,
|
|
12
|
+
* `state`, `reference` and `source` have no such exception — a malformed
|
|
13
|
+
* one, an `id` that is a number, say, is refused, never silently
|
|
14
|
+
* bucketed into `unknownFields`. Silently demoting a malformed known
|
|
15
|
+
* field into the bag would make a broken card look, from the bag's
|
|
16
|
+
* contents alone, like an ordinary card carrying one harmless extra
|
|
17
|
+
* property — a worse outcome than a refusal, and the same reasoning
|
|
18
|
+
* `parseCard` already applies by reporting every problem rather than
|
|
19
|
+
* stopping at the first. The refusal for one of those four fields is
|
|
20
|
+
* produced by `parseCard` itself, below, under that field's own name —
|
|
21
|
+
* this function does not duplicate that check, it only makes sure the
|
|
22
|
+
* field is never bucketed away from it.
|
|
23
|
+
*
|
|
24
|
+
* Every other key — anything not named above — goes into
|
|
25
|
+
* `unknownFields`, whole and unchanged. Not inspected, not normalised,
|
|
26
|
+
* not coerced. That carrying, unwitnessed until now, is the property
|
|
27
|
+
* under test: a field nobody wrote code for must survive a round trip
|
|
28
|
+
* through `parseCardPayload` and `renderCardPayload`.
|
|
29
|
+
*/
|
|
30
|
+
export declare function parseCardPayload(payload: unknown): ParseResult;
|
|
31
|
+
/**
|
|
32
|
+
* Turns a `Card` back into a payload to hand to a tracker.
|
|
33
|
+
*
|
|
34
|
+
* `unknownFields` is spread first, and the known fields are applied
|
|
35
|
+
* over it — not the other way round. That order is the answer to a
|
|
36
|
+
* question this file has to settle: if a caller has put something into
|
|
37
|
+
* `unknownFields` under a key that collides with a known field's name
|
|
38
|
+
* (nothing stops them; the bag's type is `Record<string, unknown>`), which
|
|
39
|
+
* value goes out on the wire? The validated, typed field wins. An
|
|
40
|
+
* unvalidated stray value sitting in the bag silently overriding, say,
|
|
41
|
+
* `id` on the outbound payload would let a caller smuggle an unchecked
|
|
42
|
+
* value into a slot this boundary actually validates, through the one
|
|
43
|
+
* field that is explicitly not supposed to be able to affect it.
|
|
44
|
+
*
|
|
45
|
+
* `revision` and `properties` are included only when the card actually
|
|
46
|
+
* carries them — a card with neither renders with exactly the four
|
|
47
|
+
* required keys on top of `unknownFields`, the same shape this function
|
|
48
|
+
* always produced before either field existed.
|
|
49
|
+
*
|
|
50
|
+
* A card that was never parsed — built by hand, with an empty bag —
|
|
51
|
+
* renders with no extra keys at all: spreading an empty object
|
|
52
|
+
* contributes nothing, so the payload is exactly
|
|
53
|
+
* `{id, state, reference, source}`, four keys, nothing more.
|
|
54
|
+
*/
|
|
55
|
+
export declare function renderCardPayload(card: Card): Record<string, unknown>;
|
package/dist/payload.js
ADDED
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
// The adapter shape that makes `unknownFields` real.
|
|
2
|
+
//
|
|
3
|
+
// `components.md`'s one design statement for this boundary is "unknown
|
|
4
|
+
// fields carried through rather than dropped" — `Card.unknownFields`
|
|
5
|
+
// exists because of it, but nothing in `card.ts` puts anything into that
|
|
6
|
+
// bag or takes anything out of it: `parseCard` validates a payload that
|
|
7
|
+
// already has its fields separated into the known slots plus a bag
|
|
8
|
+
// someone else built. This file is the someone else: turning a raw
|
|
9
|
+
// payload a tracker actually hands over — a flat object with the known
|
|
10
|
+
// fields sitting alongside everything else at the same level — into a
|
|
11
|
+
// `Card`, and turning a `Card` back into such a payload.
|
|
12
|
+
import { isStringRecord, parseCard } from './card.js';
|
|
13
|
+
/**
|
|
14
|
+
* `id`/`state`/`reference`/`source`/`unknownFields` are required on
|
|
15
|
+
* every `Card`; `revision`/`properties` are optional, carried through
|
|
16
|
+
* the same way when present — seven fields in total, but `unknownFields`
|
|
17
|
+
* is a `Card` field, not a payload key, so it is not one of the six
|
|
18
|
+
* names below. A key by one of these six names is never routed to
|
|
19
|
+
* `unknownFields` merely for being unrecognised — the usual reason a key
|
|
20
|
+
* ends up there. `revision` and `properties` are still the two
|
|
21
|
+
* exceptions documented on `parseCardPayload` below: when either is
|
|
22
|
+
* present but not the shape it is supposed to be, it IS bucketed into
|
|
23
|
+
* `unknownFields`, not because the key is unrecognised but because a
|
|
24
|
+
* malformed instance of one of these two optional fields is treated as
|
|
25
|
+
* simply not being that field, rather than as a reason to refuse the
|
|
26
|
+
* whole payload. Missing that bucketing here for `revision`/`properties`
|
|
27
|
+
* was a real bug, not a cosmetic gap: a board's `annotate` computing an
|
|
28
|
+
* updated `Card` with a new `properties` bag, then handing it to
|
|
29
|
+
* `renderCardPayload`, had that bag silently dropped on the way back
|
|
30
|
+
* onto the wire — the patch applied in memory and then vanished, because
|
|
31
|
+
* nothing in the rendered payload carried it for the next `get` to
|
|
32
|
+
* recover.
|
|
33
|
+
*/
|
|
34
|
+
const KNOWN_KEYS = ['id', 'state', 'reference', 'source', 'revision', 'properties'];
|
|
35
|
+
function isPlainObject(value) {
|
|
36
|
+
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* Turns a raw tracker payload into a `Card`, or refuses it.
|
|
40
|
+
*
|
|
41
|
+
* Recognition is by key name only, never by shape: a key named `id`,
|
|
42
|
+
* `state`, `reference`, `source`, `revision` or `properties` is treated
|
|
43
|
+
* as that known field — except `revision` and `properties`, which have a
|
|
44
|
+
* documented exception below: when present but not the shape they are
|
|
45
|
+
* supposed to be, they are not malformed instances of the known field at
|
|
46
|
+
* all, so they are bucketed into `unknownFields` instead of refusing the
|
|
47
|
+
* whole payload for a problem confined to one optional key. `id`,
|
|
48
|
+
* `state`, `reference` and `source` have no such exception — a malformed
|
|
49
|
+
* one, an `id` that is a number, say, is refused, never silently
|
|
50
|
+
* bucketed into `unknownFields`. Silently demoting a malformed known
|
|
51
|
+
* field into the bag would make a broken card look, from the bag's
|
|
52
|
+
* contents alone, like an ordinary card carrying one harmless extra
|
|
53
|
+
* property — a worse outcome than a refusal, and the same reasoning
|
|
54
|
+
* `parseCard` already applies by reporting every problem rather than
|
|
55
|
+
* stopping at the first. The refusal for one of those four fields is
|
|
56
|
+
* produced by `parseCard` itself, below, under that field's own name —
|
|
57
|
+
* this function does not duplicate that check, it only makes sure the
|
|
58
|
+
* field is never bucketed away from it.
|
|
59
|
+
*
|
|
60
|
+
* Every other key — anything not named above — goes into
|
|
61
|
+
* `unknownFields`, whole and unchanged. Not inspected, not normalised,
|
|
62
|
+
* not coerced. That carrying, unwitnessed until now, is the property
|
|
63
|
+
* under test: a field nobody wrote code for must survive a round trip
|
|
64
|
+
* through `parseCardPayload` and `renderCardPayload`.
|
|
65
|
+
*/
|
|
66
|
+
export function parseCardPayload(payload) {
|
|
67
|
+
if (!isPlainObject(payload)) {
|
|
68
|
+
// Let parseCard produce the one correctly-worded refusal for a
|
|
69
|
+
// non-object payload, rather than a second copy of that message here.
|
|
70
|
+
return parseCard(payload);
|
|
71
|
+
}
|
|
72
|
+
// `properties` is only ever treated as this boundary's own known
|
|
73
|
+
// field when its value genuinely is a flat string-to-string bag (see
|
|
74
|
+
// `card.ts`'s `isStringRecord`) — the documented contract. Any other
|
|
75
|
+
// shape — a plain object that happens to be named `properties` but
|
|
76
|
+
// holds something else (Notion's nested `{select: {...}}` page
|
|
77
|
+
// shape, a number), or a value that is not even an object at all
|
|
78
|
+
// (`null`, an array, a string, a number) — is not a malformed
|
|
79
|
+
// instance of this field; it simply is not this field, and is
|
|
80
|
+
// carried through whole in `unknownFields` like any other key this
|
|
81
|
+
// boundary does not recognise — never refused, never silently
|
|
82
|
+
// re-typed into a shape it does not have.
|
|
83
|
+
const rawProperties = payload.properties;
|
|
84
|
+
const propertiesIsMistyped = rawProperties !== undefined && !isStringRecord(rawProperties);
|
|
85
|
+
// A `revision` that is present but not a string is not a malformed
|
|
86
|
+
// instance of the known field either — it simply is not this field,
|
|
87
|
+
// exactly like a tracker-shaped `properties` above. It is carried
|
|
88
|
+
// through whole in `unknownFields` rather than taken to `parseCard`,
|
|
89
|
+
// which would refuse the entire payload for a problem confined to one
|
|
90
|
+
// optional key.
|
|
91
|
+
const rawRevision = payload.revision;
|
|
92
|
+
const revisionIsMistyped = rawRevision !== undefined && typeof rawRevision !== 'string';
|
|
93
|
+
const unknownFields = {};
|
|
94
|
+
for (const [key, value] of Object.entries(payload)) {
|
|
95
|
+
if (key === 'properties' && propertiesIsMistyped) {
|
|
96
|
+
unknownFields[key] = value;
|
|
97
|
+
continue;
|
|
98
|
+
}
|
|
99
|
+
if (key === 'revision' && revisionIsMistyped) {
|
|
100
|
+
unknownFields[key] = value;
|
|
101
|
+
continue;
|
|
102
|
+
}
|
|
103
|
+
if (!KNOWN_KEYS.includes(key)) {
|
|
104
|
+
unknownFields[key] = value;
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
return parseCard({
|
|
108
|
+
id: payload.id,
|
|
109
|
+
state: payload.state,
|
|
110
|
+
reference: payload.reference,
|
|
111
|
+
source: payload.source,
|
|
112
|
+
unknownFields,
|
|
113
|
+
...(rawRevision !== undefined && !revisionIsMistyped ? { revision: rawRevision } : {}),
|
|
114
|
+
...(rawProperties !== undefined && !propertiesIsMistyped ? { properties: rawProperties } : {}),
|
|
115
|
+
});
|
|
116
|
+
}
|
|
117
|
+
/**
|
|
118
|
+
* Turns a `Card` back into a payload to hand to a tracker.
|
|
119
|
+
*
|
|
120
|
+
* `unknownFields` is spread first, and the known fields are applied
|
|
121
|
+
* over it — not the other way round. That order is the answer to a
|
|
122
|
+
* question this file has to settle: if a caller has put something into
|
|
123
|
+
* `unknownFields` under a key that collides with a known field's name
|
|
124
|
+
* (nothing stops them; the bag's type is `Record<string, unknown>`), which
|
|
125
|
+
* value goes out on the wire? The validated, typed field wins. An
|
|
126
|
+
* unvalidated stray value sitting in the bag silently overriding, say,
|
|
127
|
+
* `id` on the outbound payload would let a caller smuggle an unchecked
|
|
128
|
+
* value into a slot this boundary actually validates, through the one
|
|
129
|
+
* field that is explicitly not supposed to be able to affect it.
|
|
130
|
+
*
|
|
131
|
+
* `revision` and `properties` are included only when the card actually
|
|
132
|
+
* carries them — a card with neither renders with exactly the four
|
|
133
|
+
* required keys on top of `unknownFields`, the same shape this function
|
|
134
|
+
* always produced before either field existed.
|
|
135
|
+
*
|
|
136
|
+
* A card that was never parsed — built by hand, with an empty bag —
|
|
137
|
+
* renders with no extra keys at all: spreading an empty object
|
|
138
|
+
* contributes nothing, so the payload is exactly
|
|
139
|
+
* `{id, state, reference, source}`, four keys, nothing more.
|
|
140
|
+
*/
|
|
141
|
+
export function renderCardPayload(card) {
|
|
142
|
+
return {
|
|
143
|
+
...card.unknownFields,
|
|
144
|
+
id: card.id,
|
|
145
|
+
state: card.state,
|
|
146
|
+
reference: card.reference,
|
|
147
|
+
source: card.source,
|
|
148
|
+
...(card.revision !== undefined ? { revision: card.revision } : {}),
|
|
149
|
+
...(card.properties !== undefined ? { properties: card.properties } : {}),
|
|
150
|
+
};
|
|
151
|
+
}
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
import type { Card } from './card.js';
|
|
2
|
+
import type { UnparseableRecord } from './board.js';
|
|
3
|
+
/**
|
|
4
|
+
* The `cards`/`unparseable` split `list()` already returns when its
|
|
5
|
+
* outcome is `'cards'` — accepted directly, rather than the two arrays
|
|
6
|
+
* separately, so there is exactly one way to call this and no way to
|
|
7
|
+
* pass an `unparseable` set alongside a `totalRecords` that does not
|
|
8
|
+
* agree with it. A `ListResult` whose outcome is `'cards'` already has
|
|
9
|
+
* this shape; passing it straight through is the whole call.
|
|
10
|
+
*/
|
|
11
|
+
export interface UnparseableListing {
|
|
12
|
+
readonly cards: readonly Card[];
|
|
13
|
+
readonly unparseable: readonly UnparseableRecord[];
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* Every distinct (field, message) pair found among the unparseable
|
|
17
|
+
* records, and which records produced it. Always the full breakdown —
|
|
18
|
+
* every group, not just the one (if any) that crossed the threshold
|
|
19
|
+
* below — because a caller with a different tolerance than this file's
|
|
20
|
+
* cannot recompute a verdict from a verdict; they can only recompute one
|
|
21
|
+
* from the counts. See `assessUnparseable`'s doc comment for why the
|
|
22
|
+
* threshold this file applies is not the only defensible one.
|
|
23
|
+
*/
|
|
24
|
+
export interface SchemaChangeGroup {
|
|
25
|
+
readonly field: string;
|
|
26
|
+
readonly message: string;
|
|
27
|
+
readonly count: number;
|
|
28
|
+
readonly ids: readonly string[];
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* `noEvidence` is deliberately not the same outcome as `isolated` with an
|
|
32
|
+
* empty `groups` array, even though the two are indistinguishable by
|
|
33
|
+
* their practical consequence — a caller acts on neither. They are kept
|
|
34
|
+
* apart for the same reason `absent` and `unreachable` are kept apart on
|
|
35
|
+
* `GetResult` (`board.ts`): "nothing to assess" and "assessed, and found
|
|
36
|
+
* nothing clustered" are different facts about how much evidence this
|
|
37
|
+
* function actually looked at, and collapsing them would let `isolated`
|
|
38
|
+
* be read as a claim ("I checked, and it's fine") in a case where there
|
|
39
|
+
* was nothing to check at all. An empty unparseable set is the case that
|
|
40
|
+
* would otherwise divide by zero computing a ratio against zero broken
|
|
41
|
+
* records — `noEvidence` is returned before that division is ever
|
|
42
|
+
* attempted, not after it produces `NaN`.
|
|
43
|
+
*
|
|
44
|
+
* `schemaChange`'s four fields — `field`, `message`, `count`,
|
|
45
|
+
* `totalRecords` — are the answer to "is this one problem or many?"
|
|
46
|
+
* that a boolean cannot give: which field, what it said, how many
|
|
47
|
+
* records, out of how many examined. `groups` still rides alongside it,
|
|
48
|
+
* carrying every other cluster found, however small — a board can have
|
|
49
|
+
* one dominant schema change and a handful of unrelated single-record
|
|
50
|
+
* problems at the same time, and both facts are worth having in one
|
|
51
|
+
* answer.
|
|
52
|
+
*/
|
|
53
|
+
export type SchemaChangeAssessment = {
|
|
54
|
+
readonly outcome: 'noEvidence';
|
|
55
|
+
} | {
|
|
56
|
+
readonly outcome: 'isolated';
|
|
57
|
+
readonly totalRecords: number;
|
|
58
|
+
readonly groups: readonly SchemaChangeGroup[];
|
|
59
|
+
} | {
|
|
60
|
+
readonly outcome: 'schemaChange';
|
|
61
|
+
readonly totalRecords: number;
|
|
62
|
+
readonly field: string;
|
|
63
|
+
readonly message: string;
|
|
64
|
+
readonly count: number;
|
|
65
|
+
readonly groups: readonly SchemaChangeGroup[];
|
|
66
|
+
};
|
|
67
|
+
/**
|
|
68
|
+
* Groups a listing's unparseable records by (field, message) and asks
|
|
69
|
+
* whether any one group looks like a schema change rather than a
|
|
70
|
+
* coincidence of unrelated data problems.
|
|
71
|
+
*
|
|
72
|
+
* Grouping, not counting: a record with two problems contributes to two
|
|
73
|
+
* groups, because it genuinely has two independent things wrong with it
|
|
74
|
+
* — the same discipline `parseCard` already applies by reporting every
|
|
75
|
+
* problem rather than the first (see `card.ts`), carried through here
|
|
76
|
+
* rather than collapsed by picking one problem per record to group by.
|
|
77
|
+
*/
|
|
78
|
+
export declare function assessUnparseable(listing: UnparseableListing): SchemaChangeAssessment;
|
|
Binary file
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import type { Card } from './card.js';
|
|
2
|
+
import type { CardSource, CardSink, WriteResult, WriteOptions, AnnotatePatch } from './board.js';
|
|
3
|
+
import type { Store } from './store.js';
|
|
4
|
+
/**
|
|
5
|
+
* The reserved key under which this board keeps the list of every card
|
|
6
|
+
* id it has created — an ordinary value in the same store, not a
|
|
7
|
+
* capability the store itself has to provide. Exported for tests that
|
|
8
|
+
* need to construct a scenario this board's own operations do not
|
|
9
|
+
* produce (a dangling index entry) by writing to the store directly;
|
|
10
|
+
* not part of `StoreBoard`'s own public surface.
|
|
11
|
+
*/
|
|
12
|
+
export declare const INDEX_KEY = "index";
|
|
13
|
+
export interface StoreBoard extends CardSource, CardSink {
|
|
14
|
+
/**
|
|
15
|
+
* Creates a new card, seeded with revision `'1'`, and folds its id
|
|
16
|
+
* into the index `list()` reads. The real write path onto a
|
|
17
|
+
* store-backed board — unlike `InMemoryBoard.put`/
|
|
18
|
+
* `PayloadBoard.putPayload`, which exist purely to seed a fake for a
|
|
19
|
+
* test because those boards are otherwise constructed complete via an
|
|
20
|
+
* `initial` array. A store is not constructed; it already exists,
|
|
21
|
+
* persists, and is connected to. This is how a card actually comes to
|
|
22
|
+
* exist on it, in production, not only in a test.
|
|
23
|
+
*/
|
|
24
|
+
createCard(card: Card): Promise<WriteResult>;
|
|
25
|
+
/**
|
|
26
|
+
* Patches a card's `properties` without touching `state`, via a
|
|
27
|
+
* read-check-replace retried under the same bound `writeState` uses —
|
|
28
|
+
* no index involvement, since `properties` carries no identity the
|
|
29
|
+
* index needs to track.
|
|
30
|
+
*/
|
|
31
|
+
annotate(id: string, patch: AnnotatePatch, options?: WriteOptions): Promise<WriteResult>;
|
|
32
|
+
}
|
|
33
|
+
export declare function createStoreBoard(store: Store<unknown>): StoreBoard;
|