@jam-overture/loom 0.2.0 → 0.3.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.
- package/dist/audience/compose.d.ts +112 -0
- package/dist/audience/compose.js +134 -0
- package/dist/audience/memory.d.ts +14 -0
- package/dist/audience/memory.js +71 -0
- package/dist/audience/overlay-store.d.ts +343 -0
- package/dist/audience/overlay-store.js +217 -0
- package/dist/audience/rule.d.ts +121 -0
- package/dist/audience/rule.js +78 -0
- package/dist/cli/index.d.ts +3 -4
- package/dist/cli/index.js +3 -4
- package/dist/data/adapter.d.ts +9 -1
- package/dist/data/adapter.js +2 -0
- package/dist/data/resolve.d.ts +1 -1
- package/dist/interpretation/anthropic.d.ts +1 -1
- package/dist/interpretation/anthropic.js +2 -22
- package/dist/interpretation/client.d.ts +1 -1
- package/dist/interpretation/materialize.js +67 -22
- package/dist/interpretation/openai-compatible.d.ts +36 -0
- package/dist/interpretation/openai-compatible.js +79 -0
- package/dist/interpretation/status.d.ts +19 -0
- package/dist/interpretation/status.js +26 -0
- package/dist/live/index.d.ts +73 -0
- package/dist/live/index.js +73 -0
- package/dist/live/pages.d.ts +187 -0
- package/dist/live/pages.js +161 -0
- package/dist/live/pull.d.ts +147 -0
- package/dist/live/pull.js +398 -0
- package/dist/live/pulling.d.ts +79 -0
- package/dist/live/pulling.js +117 -0
- package/dist/live/window.d.ts +129 -0
- package/dist/live/window.js +132 -0
- package/dist/render/addressed.d.ts +35 -0
- package/dist/render/addressed.js +79 -0
- package/dist/render/document-theme.d.ts +70 -0
- package/dist/render/document-theme.js +139 -0
- package/dist/render/editable.d.ts +15 -1
- package/dist/render/editable.js +13 -1
- package/dist/render/expected.d.ts +98 -0
- package/dist/render/expected.js +88 -0
- package/dist/render/index.d.ts +2 -0
- package/dist/render/index.js +2 -0
- package/dist/render/render.d.ts +11 -0
- package/dist/render/render.js +192 -46
- package/dist/render/request.d.ts +8 -1
- package/dist/render/request.js +1 -0
- package/dist/runtime/auto-apply-ceiling.d.ts +54 -0
- package/dist/runtime/auto-apply-ceiling.js +66 -0
- package/dist/runtime/gate.js +69 -10
- package/dist/runtime/index.d.ts +1 -0
- package/dist/runtime/index.js +1 -0
- package/dist/runtime/nesting.d.ts +13 -1
- package/dist/runtime/nesting.js +41 -24
- package/dist/runtime/policy-change.js +8 -2
- package/dist/runtime/policy-log.d.ts +5 -5
- package/dist/runtime/policy.d.ts +8 -6
- package/dist/runtime/policy.js +5 -2
- package/dist/runtime/repointing.js +0 -0
- package/dist/sdk/definition.d.ts +65 -6
- package/dist/sdk/definition.js +44 -0
- package/dist/sdk/registry.d.ts +17 -1
- package/dist/sdk/registry.js +39 -0
- package/dist/signals/acted.contract.d.ts +21 -0
- package/dist/signals/acted.contract.js +236 -0
- package/dist/signals/acted.d.ts +359 -0
- package/dist/signals/acted.js +135 -0
- package/dist/signals/agenda.d.ts +585 -0
- package/dist/signals/agenda.js +295 -0
- package/dist/signals/arrivals.contract.d.ts +21 -0
- package/dist/signals/arrivals.contract.js +180 -0
- package/dist/signals/arrivals.d.ts +375 -0
- package/dist/signals/arrivals.js +254 -0
- package/dist/signals/broadcast.d.ts +25 -15
- package/dist/signals/broadcast.js +209 -36
- package/dist/signals/collect.d.ts +137 -43
- package/dist/signals/collect.js +103 -36
- package/dist/signals/conversion.d.ts +348 -0
- package/dist/signals/conversion.js +235 -0
- package/dist/signals/correlated.contract.d.ts +24 -0
- package/dist/signals/correlated.contract.js +94 -0
- package/dist/signals/counters.d.ts +51 -0
- package/dist/signals/counters.js +58 -0
- package/dist/signals/deployment-change.d.ts +28 -4
- package/dist/signals/deployment-change.js +57 -16
- package/dist/signals/deployment.d.ts +18 -5
- package/dist/signals/deployment.js +37 -11
- package/dist/signals/door.d.ts +34 -12
- package/dist/signals/door.js +37 -13
- package/dist/signals/expire.d.ts +192 -0
- package/dist/signals/expire.js +213 -0
- package/dist/signals/frontier.d.ts +268 -0
- package/dist/signals/frontier.js +145 -0
- package/dist/signals/funnel-hours.contract.d.ts +21 -0
- package/dist/signals/funnel-hours.contract.js +221 -0
- package/dist/signals/funnel-hours.d.ts +293 -0
- package/dist/signals/funnel-hours.js +99 -0
- package/dist/signals/funnel.d.ts +60 -0
- package/dist/signals/funnel.js +35 -20
- package/dist/signals/health.d.ts +201 -4
- package/dist/signals/health.js +214 -2
- package/dist/signals/index.d.ts +19 -0
- package/dist/signals/index.js +19 -0
- package/dist/signals/inside.d.ts +190 -0
- package/dist/signals/inside.js +263 -0
- package/dist/signals/join.d.ts +56 -0
- package/dist/signals/join.js +60 -0
- package/dist/signals/journal.d.ts +112 -9
- package/dist/signals/kept.contract.d.ts +22 -0
- package/dist/signals/kept.contract.js +111 -0
- package/dist/signals/library-agenda-change.d.ts +324 -0
- package/dist/signals/library-agenda-change.js +199 -0
- package/dist/signals/library-agenda.d.ts +258 -0
- package/dist/signals/library-agenda.js +167 -0
- package/dist/signals/library-reach-change.d.ts +10 -0
- package/dist/signals/library-reach-change.js +11 -3
- package/dist/signals/library-senders-change.d.ts +457 -0
- package/dist/signals/library-senders-change.js +367 -0
- package/dist/signals/library-senders-reach-change.d.ts +486 -0
- package/dist/signals/library-senders-reach-change.js +538 -0
- package/dist/signals/library-senders-reach.d.ts +340 -0
- package/dist/signals/library-senders-reach.js +252 -0
- package/dist/signals/library-senders.d.ts +271 -0
- package/dist/signals/library-senders.js +180 -0
- package/dist/signals/library-word-reach-change.js +2 -6
- package/dist/signals/memory.js +142 -1
- package/dist/signals/migrate.d.ts +6 -5
- package/dist/signals/migrate.js +150 -6
- package/dist/signals/notice.d.ts +88 -33
- package/dist/signals/notice.js +38 -16
- package/dist/signals/part-pace.d.ts +378 -0
- package/dist/signals/part-pace.js +333 -0
- package/dist/signals/parts.d.ts +25 -15
- package/dist/signals/parts.js +32 -73
- package/dist/signals/postgres.js +400 -26
- package/dist/signals/region.d.ts +1 -1
- package/dist/signals/retention.d.ts +43 -21
- package/dist/signals/retention.js +25 -8
- package/dist/signals/rhythm.d.ts +302 -0
- package/dist/signals/rhythm.js +262 -0
- package/dist/signals/rollup.d.ts +127 -1
- package/dist/signals/rollup.js +211 -24
- package/dist/signals/schema.d.ts +640 -3
- package/dist/signals/schema.js +239 -3
- package/dist/signals/silences.d.ts +310 -11
- package/dist/signals/silences.js +243 -0
- package/dist/signals/subtrees.d.ts +123 -0
- package/dist/signals/subtrees.js +102 -0
- package/dist/signals/tally.d.ts +125 -4
- package/dist/signals/unread.d.ts +292 -0
- package/dist/signals/unread.js +137 -0
- package/dist/signals/window-agenda.d.ts +276 -0
- package/dist/signals/window-agenda.js +83 -0
- package/dist/signals/window-funnels.d.ts +88 -0
- package/dist/signals/window-funnels.js +47 -0
- package/dist/store/cache.d.ts +101 -0
- package/dist/store/cache.js +149 -0
- package/dist/store/history.d.ts +82 -0
- package/dist/store/history.js +36 -0
- package/dist/store/index.d.ts +11 -0
- package/dist/store/index.js +11 -0
- package/dist/store/migrate.d.ts +26 -0
- package/dist/store/migrate.js +64 -0
- package/dist/store/postgres-audience.d.ts +14 -0
- package/dist/store/postgres-audience.js +272 -0
- package/dist/store/postgres.d.ts +1 -0
- package/dist/store/postgres.js +1 -0
- package/dist/store/schema.d.ts +312 -0
- package/dist/store/schema.js +77 -0
- package/dist/store/source.d.ts +57 -1
- package/dist/store/source.js +65 -1
- package/dist/submit/resolve.d.ts +1 -1
- package/dist/telemetry/index.d.ts +1 -0
- package/dist/telemetry/index.js +1 -0
- package/dist/telemetry/journal.d.ts +32 -0
- package/dist/telemetry/memory.js +10 -1
- package/dist/telemetry/postgres.js +18 -2
- package/dist/telemetry/window.d.ts +135 -0
- package/dist/telemetry/window.js +101 -0
- package/dist/testing/audience-overlay-contract.d.ts +31 -0
- package/dist/testing/audience-overlay-contract.js +354 -0
- package/dist/testing/contracts.d.ts +1 -0
- package/dist/testing/contracts.js +1 -0
- package/dist/testing/journal-contract.js +158 -5
- package/dist/theme/contrast.d.ts +19 -14
- package/dist/theme/contrast.js +181 -17
- package/dist/tree/apply.js +13 -0
- package/dist/tree/mutation.d.ts +18 -0
- package/dist/tree/mutation.js +24 -12
- package/dist/tree/navigation.d.ts +5 -0
- package/dist/tree/navigation.js +32 -10
- package/dist/tree/outline.d.ts +7 -0
- package/dist/tree/outline.js +9 -5
- package/package.json +39 -96
- package/dist/runtime/inverse-interpreter.d.ts +0 -90
- package/dist/runtime/inverse-interpreter.js +0 -56
|
@@ -0,0 +1,293 @@
|
|
|
1
|
+
import type { AudienceId } from "../audience/audience.js";
|
|
2
|
+
import type { TreeId } from "../ids.js";
|
|
3
|
+
import { type Result } from "../result.js";
|
|
4
|
+
import { type ArrivalRange, type ArrivalSeriesOptions } from "./arrivals.js";
|
|
5
|
+
import type { ReaderSignalStoreError } from "./journal.js";
|
|
6
|
+
import { type Ratio } from "./ratios.js";
|
|
7
|
+
import type { FunnelPair } from "./rollup.js";
|
|
8
|
+
/**
|
|
9
|
+
* **A funnel, by the hour the readers in it entered it.**
|
|
10
|
+
*
|
|
11
|
+
* The funnel counters have answered *of the views that did X to this part, how
|
|
12
|
+
* many went on to do Y to that one* since §3, and
|
|
13
|
+
* [0418](../../decisions/0418-a-projects-goal-funnel-is-asked-of-the-pages-both-steps-name-and-only-of-a-window-that-begins-after-it-was-set.md)
|
|
14
|
+
* put a project's own goal steps into collection, so *Goals* reads each step's
|
|
15
|
+
* share off a durable row. **That row has no clock.** It is a revision and the
|
|
16
|
+
* two ends, summed over every window that revision was ever folded in — which
|
|
17
|
+
* is exactly the question *Goals* asks and none of the question *Page history*
|
|
18
|
+
* asks.
|
|
19
|
+
*
|
|
20
|
+
* `Loom portal` filed that gap the morning 0418 landed:
|
|
21
|
+
* [0402](../../decisions/0402-goals-can-form-a-funnel-and-each-step-after-the-first-is-a-funnel-pair-counted-inside-one-page-view.md)
|
|
22
|
+
* clause 6 scores each later step of a change's goal over **the change's own
|
|
23
|
+
* two sides** — fourteen days before the page changed and fourteen after — and
|
|
24
|
+
* a revision served for six weeks has one row for all six. Reading the whole
|
|
25
|
+
* revision as the before side is a different measurement from the one the
|
|
26
|
+
* maintainer's rules describe, so the portal drew the per-step lines from the
|
|
27
|
+
* newest kept deliveries instead, which ends at the retention window (0349)
|
|
28
|
+
* and so could never span a comparison measured a fortnight each side.
|
|
29
|
+
*
|
|
30
|
+
* This is the eighth counter and the third with a clock in its key: the same
|
|
31
|
+
* answers the fold already computes, filed under an hour.
|
|
32
|
+
*
|
|
33
|
+
* ## A distinct count can be sliced by hour exactly once
|
|
34
|
+
*
|
|
35
|
+
* [0362](../../decisions/0362-what-readers-did-is-counted-under-the-hour-they-did-it-in-as-a-seventh-counter-the-fold-writes-for-the-three-delegated-kinds.md)
|
|
36
|
+
* clause 3 refused to put the tally's `views`, `reached` and `engaged` under an
|
|
37
|
+
* hour, and the reason is arithmetic rather than taste: those are counts of
|
|
38
|
+
* **distinct page views**, filed from every delivery that reported them, so a
|
|
39
|
+
* reader whose page view crosses an hour boundary is one view in each hour and
|
|
40
|
+
* two in their sum. An hourly table of them publishes a denominator that grows
|
|
41
|
+
* with how finely it is cut.
|
|
42
|
+
*
|
|
43
|
+
* `reached` and `converted` are distinct counts too, and this table holds them
|
|
44
|
+
* anyway — because the hazard is in the *filing* and not in the counter. **A
|
|
45
|
+
* view is filed under one hour: the hour it first satisfied the pair's `from`
|
|
46
|
+
* end in this window.** The hours of a window are a partition of that window's
|
|
47
|
+
* view set rather than a slice per delivery, so they sum to the window's own
|
|
48
|
+
* answer exactly, and the sum is an invariant rather than an approximation.
|
|
49
|
+
*
|
|
50
|
+
* **Only the fold can make that assignment**, which is why this counter is
|
|
51
|
+
* written where the answers are: the view key is the thing the assignment is
|
|
52
|
+
* over, it is consumed in `rollup.ts` and it never reaches storage (0146). A
|
|
53
|
+
* second pass would also make the repeat refusal twice over a different
|
|
54
|
+
* grouping, which is what 0362 clause 5 says it costs.
|
|
55
|
+
*
|
|
56
|
+
* ## The cohort is the hour of the first end, on both numbers
|
|
57
|
+
*
|
|
58
|
+
* A reader who reached the pricing band at 10:59 and pressed at 11:02 is
|
|
59
|
+
* **one** hour's row: `reached 1, converted 1`, under ten o'clock. Filing each
|
|
60
|
+
* end under its own hour would put `converted` in an hour whose `reached` is
|
|
61
|
+
* nought — a row whose rate is infinite, in a table whose whole purpose is to
|
|
62
|
+
* be divided — and `FunnelAnswer`'s standing promise that `converted` is never
|
|
63
|
+
* above `reached` would hold for the total row and fail for its slices.
|
|
64
|
+
*
|
|
65
|
+
* So an hour here means *the readers who entered this funnel in this hour, and
|
|
66
|
+
* what became of them*. It is a cohort and not a clock on the conversion, and
|
|
67
|
+
* a surface drawing it says **when the readers arrived at the first step**.
|
|
68
|
+
*
|
|
69
|
+
* ## What it inherits, and what it does not make worse
|
|
70
|
+
*
|
|
71
|
+
* A conversion split across two collection windows is **lost** rather than
|
|
72
|
+
* doubled (0147, and `funnel.ts` at length): the window that saw the reach
|
|
73
|
+
* reports `converted 0` and the window that saw the conversion never saw the
|
|
74
|
+
* reach. The hourly rows are cut from those same per-window answers, so they
|
|
75
|
+
* carry exactly that bias and no more of it — the slicing is inside a window
|
|
76
|
+
* and adds no boundary of its own.
|
|
77
|
+
*
|
|
78
|
+
* A row exists only where somebody reached the first end, so this table is
|
|
79
|
+
* bounded by what readers did rather than by how many questions a deployment
|
|
80
|
+
* asks — the affordability property 0362 clause 4 states for the seventh
|
|
81
|
+
* counter. The total row is still written at nought, because *nobody reached
|
|
82
|
+
* this step* is an answer a deployment asked for; an hour nobody entered the
|
|
83
|
+
* funnel in is a nought a reading draws rather than a row a fold stores.
|
|
84
|
+
*
|
|
85
|
+
* Pure: no store, no clock, no DOM, and nothing a reader's browser pays for.
|
|
86
|
+
* Nothing is added to a payload, a column of the buffer, or the vocabulary.
|
|
87
|
+
*/
|
|
88
|
+
/** One funnel pair's answer for one hour of one revision. */
|
|
89
|
+
export type FunnelHourCount = {
|
|
90
|
+
readonly treeId: TreeId;
|
|
91
|
+
readonly revision: number;
|
|
92
|
+
/**
|
|
93
|
+
* The two ends, as a stored funnel answer carries them and with no scope
|
|
94
|
+
* among them: the pages a question was asked on decide which rows are
|
|
95
|
+
* written and never what one means (0418).
|
|
96
|
+
*/
|
|
97
|
+
readonly pair: FunnelPair;
|
|
98
|
+
/** The hour the readers in it entered the funnel, as the instant that hour began (UTC). */
|
|
99
|
+
readonly hour: number;
|
|
100
|
+
/** Views that satisfied `from` in this hour. */
|
|
101
|
+
readonly reached: number;
|
|
102
|
+
/** Of those, the views that satisfied `to`. Never greater than {@link FunnelHourCount.reached}. */
|
|
103
|
+
readonly converted: number;
|
|
104
|
+
};
|
|
105
|
+
/** One hour's row as the store keeps it. See `StoredTally.audienceId` (0284). */
|
|
106
|
+
export type StoredFunnelHour = FunnelHourCount & {
|
|
107
|
+
readonly audienceId: AudienceId;
|
|
108
|
+
readonly updatedAt: string;
|
|
109
|
+
};
|
|
110
|
+
/**
|
|
111
|
+
* What a ranged read of this counter hands back, which is the shape
|
|
112
|
+
* `StoredArrivals` and `StoredActed` have and for the same two reasons.
|
|
113
|
+
*/
|
|
114
|
+
export type StoredFunnelHours = {
|
|
115
|
+
/** Every row in the range, in no particular order. */
|
|
116
|
+
readonly hours: readonly StoredFunnelHour[];
|
|
117
|
+
/**
|
|
118
|
+
* The first hour this scope ever counted a reach in, whatever range was asked
|
|
119
|
+
* for.
|
|
120
|
+
*
|
|
121
|
+
* Absent means *nothing has ever been counted here*, which is a different
|
|
122
|
+
* sentence from *nobody entered this funnel in the range you asked about*
|
|
123
|
+
* (0309, 0347). It narrows with the request, so a step set this afternoon
|
|
124
|
+
* says it has been measurable since this afternoon rather than drawing a
|
|
125
|
+
* year of noughts behind it.
|
|
126
|
+
*/
|
|
127
|
+
readonly begins?: number;
|
|
128
|
+
};
|
|
129
|
+
/** One hour of a range, which is one bar and one cohort. */
|
|
130
|
+
export type FunnelHour = {
|
|
131
|
+
/** The instant the hour began (UTC). */
|
|
132
|
+
readonly hour: number;
|
|
133
|
+
/** Views that entered the funnel in it. */
|
|
134
|
+
readonly reached: number;
|
|
135
|
+
/** Of those, the ones that converted — in this hour's cohort, not in this hour. */
|
|
136
|
+
readonly converted: number;
|
|
137
|
+
/**
|
|
138
|
+
* Whether this hour is over and inside the range.
|
|
139
|
+
*
|
|
140
|
+
* False on the hour in progress, and false where the range cuts the hour
|
|
141
|
+
* short, so a surface does not draw the clock as a fall.
|
|
142
|
+
*/
|
|
143
|
+
readonly whole: boolean;
|
|
144
|
+
};
|
|
145
|
+
/**
|
|
146
|
+
* A funnel over a range, by hour, for one pair.
|
|
147
|
+
*
|
|
148
|
+
* One pair per series, and that is a correctness rule rather than a
|
|
149
|
+
* convenience: `reached` counts distinct page views, so two pairs sharing a
|
|
150
|
+
* `from` end both hold the same view in their own rows, and a series that
|
|
151
|
+
* summed across pairs would count that reader once per question asked about
|
|
152
|
+
* them. {@link funnelHourSeriesOf} therefore takes the pair it is of and
|
|
153
|
+
* **ignores** every other row it was handed.
|
|
154
|
+
*/
|
|
155
|
+
export type FunnelHourSeries = {
|
|
156
|
+
readonly range: ArrivalRange;
|
|
157
|
+
/** The pair this series is of, as the caller named it. */
|
|
158
|
+
readonly pair: FunnelPair;
|
|
159
|
+
/**
|
|
160
|
+
* One entry per hour, ascending, from the later of the range's first hour and
|
|
161
|
+
* the hour counting began. Dense: an hour nobody entered the funnel in is
|
|
162
|
+
* nought in both numbers and is present.
|
|
163
|
+
*/
|
|
164
|
+
readonly hours: readonly FunnelHour[];
|
|
165
|
+
/** Views that entered the funnel inside the range, which is the sum of the hours. */
|
|
166
|
+
readonly reached: number;
|
|
167
|
+
/** Of those, the ones that converted. Never greater than {@link FunnelHourSeries.reached}. */
|
|
168
|
+
readonly converted: number;
|
|
169
|
+
/**
|
|
170
|
+
* `converted ÷ reached` over the range, or `null` where nothing reached the
|
|
171
|
+
* first end.
|
|
172
|
+
*
|
|
173
|
+
* `null` is *the question has no answer here* rather than *the answer is
|
|
174
|
+
* nought*, which is the rule `PairReach.rate` already holds for the total
|
|
175
|
+
* row. A floor rather than an estimate wherever a conversion could have been
|
|
176
|
+
* split across two collection windows (0147).
|
|
177
|
+
*/
|
|
178
|
+
readonly rate: number | null;
|
|
179
|
+
/** The first hour this scope ever counted, carried through from the store. */
|
|
180
|
+
readonly begins?: number;
|
|
181
|
+
/** Whether the range starts before counting did, so the series is shorter than asked for. */
|
|
182
|
+
readonly clipped: boolean;
|
|
183
|
+
};
|
|
184
|
+
/**
|
|
185
|
+
* The hours of a range for one pair, as the counter answers for them.
|
|
186
|
+
*
|
|
187
|
+
* Rows of **this** pair are summed into their hour, so a scope holding several
|
|
188
|
+
* revisions, pages or audiences adds — a page view belongs to one revision of
|
|
189
|
+
* one page served to one audience, so the view sets being added are disjoint
|
|
190
|
+
* and the distinctness holds. Rows of any other pair are ignored, for the
|
|
191
|
+
* reason {@link FunnelHourSeries} gives.
|
|
192
|
+
*
|
|
193
|
+
* Rows outside the range are ignored rather than refused, exactly as
|
|
194
|
+
* `arrivalSeriesOf` ignores them: a wider read is what
|
|
195
|
+
* {@link funnelHourChangeOf} narrows twice.
|
|
196
|
+
*/
|
|
197
|
+
export declare const funnelHourSeriesOf: (stored: StoredFunnelHours, pair: FunnelPair, range: ArrivalRange, options?: ArrivalSeriesOptions) => FunnelHourSeries;
|
|
198
|
+
/**
|
|
199
|
+
* A funnel over a range against the same funnel over the period before it.
|
|
200
|
+
*
|
|
201
|
+
* The two sides a change is scored over (0402 clause 6), and the figure that is
|
|
202
|
+
* a lie if the earlier period is one the deployment was not counting through.
|
|
203
|
+
*/
|
|
204
|
+
export type FunnelHourChange = {
|
|
205
|
+
readonly range: ArrivalRange;
|
|
206
|
+
/** The equal-length period before, which is `arrivalRangeBefore` (0356). */
|
|
207
|
+
readonly before: ArrivalRange;
|
|
208
|
+
readonly pair: FunnelPair;
|
|
209
|
+
readonly reached: number;
|
|
210
|
+
readonly converted: number;
|
|
211
|
+
/** The later side's rate, on {@link FunnelHourSeries.rate}'s terms. */
|
|
212
|
+
readonly rate: number | null;
|
|
213
|
+
/**
|
|
214
|
+
* What the earlier period held, or `null` where counting had not begun when
|
|
215
|
+
* it started.
|
|
216
|
+
*
|
|
217
|
+
* `null` is not nought, and the difference is the whole of these three
|
|
218
|
+
* fields: a deployment that upgraded on Tuesday had no counter before
|
|
219
|
+
* Tuesday and no missing readers either. All three are `null` together,
|
|
220
|
+
* except {@link FunnelHourChange.wasRate}, which is also `null` where nobody
|
|
221
|
+
* reached the first end in the earlier period.
|
|
222
|
+
*/
|
|
223
|
+
readonly wasReached: number | null;
|
|
224
|
+
readonly wasConverted: number | null;
|
|
225
|
+
readonly wasRate: number | null;
|
|
226
|
+
/**
|
|
227
|
+
* The later rate over the earlier rate, or why there is none (`ratios.ts`).
|
|
228
|
+
*
|
|
229
|
+
* **Of the two rates and not of the two conversion counts**, because a change
|
|
230
|
+
* is scored on the share and not on the traffic: a page that converted twice
|
|
231
|
+
* as many readers out of three times as many is a step that got worse, and a
|
|
232
|
+
* quotient of counts says it improved. A surface wanting the counts compared
|
|
233
|
+
* has both sides in hand.
|
|
234
|
+
*/
|
|
235
|
+
readonly ratio: Ratio;
|
|
236
|
+
};
|
|
237
|
+
/**
|
|
238
|
+
* Both sides and the quotient, from one read spanning both periods.
|
|
239
|
+
*
|
|
240
|
+
* The read has to span both, which is what {@link readReaderFunnelHours} is
|
|
241
|
+
* for: the obvious caller reads the range on the screen and reports an earlier
|
|
242
|
+
* period that is empty **because it was not read** (0356).
|
|
243
|
+
*/
|
|
244
|
+
export declare const funnelHourChangeOf: (stored: StoredFunnelHours, pair: FunnelPair, range: ArrivalRange, options?: ArrivalSeriesOptions) => FunnelHourChange;
|
|
245
|
+
/** What a surface asks for: a range, the pair, the narrowing and the clock. */
|
|
246
|
+
export type FunnelHourReadingRequest = {
|
|
247
|
+
readonly range: ArrivalRange;
|
|
248
|
+
/**
|
|
249
|
+
* The funnel this is about.
|
|
250
|
+
*
|
|
251
|
+
* Required, unlike every other narrowing here, for the reason
|
|
252
|
+
* {@link FunnelHourSeries} gives: a figure summed across pairs counts one
|
|
253
|
+
* reader once per question asked about them. The store is narrowed to the
|
|
254
|
+
* pair's ends as well as the reading, so a deployment asking fifty questions
|
|
255
|
+
* reads the rows of one.
|
|
256
|
+
*/
|
|
257
|
+
readonly pair: FunnelPair;
|
|
258
|
+
/** Absent reads every tree the handle can see, which is the scope rule (0020). */
|
|
259
|
+
readonly treeId?: TreeId;
|
|
260
|
+
/** Absent reads every audience (0284), whose counts then add. */
|
|
261
|
+
readonly audience?: AudienceId | undefined;
|
|
262
|
+
/** Absent reads every revision, whose counts then add — which is what a step wants. */
|
|
263
|
+
readonly revision?: number;
|
|
264
|
+
/** Now, where the caller has it, so the hour in progress is marked as one. */
|
|
265
|
+
readonly now?: number;
|
|
266
|
+
};
|
|
267
|
+
/** The chart and the two sides beside it, from one read. */
|
|
268
|
+
export type FunnelHourReading = {
|
|
269
|
+
readonly series: FunnelHourSeries;
|
|
270
|
+
readonly change: FunnelHourChange;
|
|
271
|
+
};
|
|
272
|
+
/** The one method of the counter handle a reading of this needs. */
|
|
273
|
+
export type FunnelHourCounterHandle = {
|
|
274
|
+
readonly funnelHours: (request?: {
|
|
275
|
+
readonly treeId?: TreeId;
|
|
276
|
+
readonly audience?: AudienceId | undefined;
|
|
277
|
+
readonly revision?: number;
|
|
278
|
+
readonly pair?: FunnelPair;
|
|
279
|
+
readonly from?: number;
|
|
280
|
+
readonly to?: number;
|
|
281
|
+
}) => Promise<Result<StoredFunnelHours, ReaderSignalStoreError>>;
|
|
282
|
+
};
|
|
283
|
+
/**
|
|
284
|
+
* The chart, the range's figures and the period before it, in one call against
|
|
285
|
+
* a counter handle.
|
|
286
|
+
*
|
|
287
|
+
* It exists for the reason `readReaderActed` does: the composition has a wrong
|
|
288
|
+
* version that type-checks, and it reads as *every conversion you have is new*
|
|
289
|
+
* on a screen whose store holds the right answer. The handle is narrowed to the
|
|
290
|
+
* one method, so a reading cannot reach a counter it was not asked about.
|
|
291
|
+
*/
|
|
292
|
+
export declare const readReaderFunnelHours: (store: FunnelHourCounterHandle, request: FunnelHourReadingRequest) => Promise<Result<FunnelHourReading, ReaderSignalStoreError>>;
|
|
293
|
+
//# sourceMappingURL=funnel-hours.d.ts.map
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
import { ok } from "../result.js";
|
|
2
|
+
import { arrivalRangeBefore, hourlySeriesOf, } from "./arrivals.js";
|
|
3
|
+
import { funnelPairKey } from "./funnel.js";
|
|
4
|
+
import { ratioOf } from "./ratios.js";
|
|
5
|
+
const rateOf = (reached, converted) => reached === 0 ? null : converted / reached;
|
|
6
|
+
/**
|
|
7
|
+
* The hours of a range for one pair, as the counter answers for them.
|
|
8
|
+
*
|
|
9
|
+
* Rows of **this** pair are summed into their hour, so a scope holding several
|
|
10
|
+
* revisions, pages or audiences adds — a page view belongs to one revision of
|
|
11
|
+
* one page served to one audience, so the view sets being added are disjoint
|
|
12
|
+
* and the distinctness holds. Rows of any other pair are ignored, for the
|
|
13
|
+
* reason {@link FunnelHourSeries} gives.
|
|
14
|
+
*
|
|
15
|
+
* Rows outside the range are ignored rather than refused, exactly as
|
|
16
|
+
* `arrivalSeriesOf` ignores them: a wider read is what
|
|
17
|
+
* {@link funnelHourChangeOf} narrows twice.
|
|
18
|
+
*/
|
|
19
|
+
export const funnelHourSeriesOf = (stored, pair, range, options = {}) => {
|
|
20
|
+
const asked = funnelPairKey(pair);
|
|
21
|
+
const mine = stored.hours.filter((row) => funnelPairKey(row.pair) === asked);
|
|
22
|
+
const reaching = hourlySeriesOf(mine, stored.begins, range, (row) => row.reached, options);
|
|
23
|
+
const converting = hourlySeriesOf(mine, stored.begins, range, (row) => row.converted, options);
|
|
24
|
+
return {
|
|
25
|
+
range,
|
|
26
|
+
pair,
|
|
27
|
+
/**
|
|
28
|
+
* Two fills over one row set, zipped by position: both are dense over the
|
|
29
|
+
* same hours in the same order, because `hourlySeriesOf` draws its buckets
|
|
30
|
+
* from the range and the beginning rather than from the rows. A lookup by
|
|
31
|
+
* hour would be the same answer and a second rule about what an hour is.
|
|
32
|
+
*/
|
|
33
|
+
hours: reaching.hours.map((bucket, at) => ({
|
|
34
|
+
hour: bucket.hour,
|
|
35
|
+
reached: bucket.count,
|
|
36
|
+
converted: converting.hours[at]?.count ?? 0,
|
|
37
|
+
whole: bucket.whole,
|
|
38
|
+
})),
|
|
39
|
+
reached: reaching.total,
|
|
40
|
+
converted: converting.total,
|
|
41
|
+
rate: rateOf(reaching.total, converting.total),
|
|
42
|
+
...(stored.begins === undefined ? {} : { begins: stored.begins }),
|
|
43
|
+
clipped: reaching.clipped,
|
|
44
|
+
};
|
|
45
|
+
};
|
|
46
|
+
/**
|
|
47
|
+
* Both sides and the quotient, from one read spanning both periods.
|
|
48
|
+
*
|
|
49
|
+
* The read has to span both, which is what {@link readReaderFunnelHours} is
|
|
50
|
+
* for: the obvious caller reads the range on the screen and reports an earlier
|
|
51
|
+
* period that is empty **because it was not read** (0356).
|
|
52
|
+
*/
|
|
53
|
+
export const funnelHourChangeOf = (stored, pair, range, options = {}) => {
|
|
54
|
+
const before = arrivalRangeBefore(range);
|
|
55
|
+
const now = funnelHourSeriesOf(stored, pair, range, options);
|
|
56
|
+
const earlier = funnelHourSeriesOf(stored, pair, before, options);
|
|
57
|
+
const measured = stored.begins !== undefined && stored.begins <= before.from;
|
|
58
|
+
const wasReached = measured ? earlier.reached : null;
|
|
59
|
+
const wasConverted = measured ? earlier.converted : null;
|
|
60
|
+
const wasRate = measured ? earlier.rate : null;
|
|
61
|
+
return {
|
|
62
|
+
range,
|
|
63
|
+
before,
|
|
64
|
+
pair,
|
|
65
|
+
reached: now.reached,
|
|
66
|
+
converted: now.converted,
|
|
67
|
+
rate: now.rate,
|
|
68
|
+
wasReached,
|
|
69
|
+
wasConverted,
|
|
70
|
+
wasRate,
|
|
71
|
+
ratio: ratioOf(wasRate, now.rate),
|
|
72
|
+
};
|
|
73
|
+
};
|
|
74
|
+
/**
|
|
75
|
+
* The chart, the range's figures and the period before it, in one call against
|
|
76
|
+
* a counter handle.
|
|
77
|
+
*
|
|
78
|
+
* It exists for the reason `readReaderActed` does: the composition has a wrong
|
|
79
|
+
* version that type-checks, and it reads as *every conversion you have is new*
|
|
80
|
+
* on a screen whose store holds the right answer. The handle is narrowed to the
|
|
81
|
+
* one method, so a reading cannot reach a counter it was not asked about.
|
|
82
|
+
*/
|
|
83
|
+
export const readReaderFunnelHours = async (store, request) => {
|
|
84
|
+
const { range, now, pair, ...narrowing } = request;
|
|
85
|
+
const read = await store.funnelHours({
|
|
86
|
+
...narrowing,
|
|
87
|
+
pair,
|
|
88
|
+
from: arrivalRangeBefore(range).from,
|
|
89
|
+
to: range.to,
|
|
90
|
+
});
|
|
91
|
+
if (!read.ok)
|
|
92
|
+
return read;
|
|
93
|
+
const options = now === undefined ? {} : { now };
|
|
94
|
+
return ok({
|
|
95
|
+
series: funnelHourSeriesOf(read.value, pair, range, options),
|
|
96
|
+
change: funnelHourChangeOf(read.value, pair, range, options),
|
|
97
|
+
});
|
|
98
|
+
};
|
|
99
|
+
//# sourceMappingURL=funnel-hours.js.map
|
package/dist/signals/funnel.d.ts
CHANGED
|
@@ -252,6 +252,55 @@ export type FunnelShare = {
|
|
|
252
252
|
*/
|
|
253
253
|
readonly atMostReaders: number | null;
|
|
254
254
|
};
|
|
255
|
+
/**
|
|
256
|
+
* The readers one pair loses between its two ends, on the scale its page's door
|
|
257
|
+
* counts in, as the interval the straddle leaves it in.
|
|
258
|
+
*
|
|
259
|
+
* An order of conversions ranks pages on this loss
|
|
260
|
+
* ([0333](../../decisions/0333-a-deployments-conversions-are-a-third-order-ranked-on-the-loss-between-the-two-ends.md)),
|
|
261
|
+
* and the figure it ranks on is {@link PairLeak.atMost} — which is a ceiling and
|
|
262
|
+
* not an estimate. `reached` and `converted` are both generous under a straddle
|
|
263
|
+
* and the straddle very nearly divides out of their ratio, but what does not
|
|
264
|
+
* divide out is the conversion a straddle **splits across two windows and
|
|
265
|
+
* loses** (0147): the pair reports `reached 1, converted 0` for a visit that
|
|
266
|
+
* converted, so the loss between the two ends is overstated by exactly the
|
|
267
|
+
* conversions that went missing. Scaling the subtraction by the door corrects
|
|
268
|
+
* how many page views were counted twice and cannot put back a conversion that
|
|
269
|
+
* was never counted once.
|
|
270
|
+
*
|
|
271
|
+
* So the loss has a floor as well, and both ends come off bounds this reading
|
|
272
|
+
* already publishes. The true rate is between {@link PairReach.rate} and
|
|
273
|
+
* {@link PairReach.rateAtMost}, so the readers who reached the first end — put
|
|
274
|
+
* on the door's scale once, by the one rule `door.ts` holds — are taken at each
|
|
275
|
+
* of those two rates. The ceiling is `reached − converted` on the door's scale,
|
|
276
|
+
* which is the key an order of conversions ranks on, arrived at as the same
|
|
277
|
+
* expression as the floor so that the two cannot fail to meet.
|
|
278
|
+
*
|
|
279
|
+
* The two ends meet wherever {@link FunnelReach.exact} — nobody's visit spanned
|
|
280
|
+
* two windows, so there is nothing to divide out and nothing to have been lost.
|
|
281
|
+
* They open apart as a deployment's rollup window shortens relative to how long
|
|
282
|
+
* its readers stay, which is the same fact `rateAtMost` was built to make
|
|
283
|
+
* readable (0147).
|
|
284
|
+
*
|
|
285
|
+
* **Neither end is a count of people and neither is rounded into one.** A
|
|
286
|
+
* surface that rounds them is saying how precise it thinks they are.
|
|
287
|
+
*/
|
|
288
|
+
export type PairLeak = {
|
|
289
|
+
/**
|
|
290
|
+
* The least it could be: the readers who reached the first end, at the most
|
|
291
|
+
* the true rate could be, on the door's scale.
|
|
292
|
+
*
|
|
293
|
+
* Never above {@link PairLeak.atMost} and never below nought. This is the
|
|
294
|
+
* figure a straddle cannot manufacture — a page carrying it is losing at
|
|
295
|
+
* least this many readers however short the deployment's rollup window is.
|
|
296
|
+
*/
|
|
297
|
+
readonly atLeast: number;
|
|
298
|
+
/**
|
|
299
|
+
* The most it could be: `reached − converted` on the door's scale, which is
|
|
300
|
+
* the key an order of conversions is on (0333).
|
|
301
|
+
*/
|
|
302
|
+
readonly atMost: number;
|
|
303
|
+
};
|
|
255
304
|
/** One pair of a revision, as stored and as a share of the readers there were. */
|
|
256
305
|
export type PairReach = {
|
|
257
306
|
readonly pair: FunnelPair;
|
|
@@ -336,6 +385,17 @@ export type PairReach = {
|
|
|
336
385
|
* and `null` wherever {@link PairReach.rate} is.
|
|
337
386
|
*/
|
|
338
387
|
readonly rateAtMost: number | null;
|
|
388
|
+
/**
|
|
389
|
+
* The readers this pair loses between its two ends, bounded and on the door's
|
|
390
|
+
* scale, or `null` where there is no such loss to put a scale on.
|
|
391
|
+
*
|
|
392
|
+
* `null` on the same terms as {@link PairReach.rateAtMost} — there is no
|
|
393
|
+
* question, or nobody reached its first end, or the door cannot scale this
|
|
394
|
+
* revision — and `null` too where {@link PairReach.unreconciled}, because a
|
|
395
|
+
* count above the page views there were to hold it has no sound scale even
|
|
396
|
+
* though its rate stands.
|
|
397
|
+
*/
|
|
398
|
+
readonly leak: PairLeak | null;
|
|
339
399
|
/**
|
|
340
400
|
* Of the readers who arrived, the share that got to the first end.
|
|
341
401
|
*
|
package/dist/signals/funnel.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { everyMemberOf } from "../closed-set.js";
|
|
2
2
|
import { audienceScopeOf, audiencesIn } from "./audiences.js";
|
|
3
|
+
import { atDoorScale, doorOf } from "./door.js";
|
|
3
4
|
import { pageViewsFor } from "./page-views.js";
|
|
4
5
|
export const FUNNEL_STAGES = everyMemberOf()([
|
|
5
6
|
"before",
|
|
@@ -33,21 +34,6 @@ const NOTHING_SHARED = {
|
|
|
33
34
|
readers: null,
|
|
34
35
|
atMostReaders: null,
|
|
35
36
|
};
|
|
36
|
-
const NOTHING_MEASURED = {
|
|
37
|
-
opened: 0,
|
|
38
|
-
appearances: 0,
|
|
39
|
-
drift: 0,
|
|
40
|
-
pending: 0,
|
|
41
|
-
inflation: null,
|
|
42
|
-
updatedAt: null,
|
|
43
|
-
};
|
|
44
|
-
const silenceOf = (opened, appearances) => {
|
|
45
|
-
if (opened === 0)
|
|
46
|
-
return "unopened";
|
|
47
|
-
if (appearances === 0)
|
|
48
|
-
return "uncounted";
|
|
49
|
-
return null;
|
|
50
|
-
};
|
|
51
37
|
const endKey = (end) => `${end.nodeId} ${end.kind}`;
|
|
52
38
|
/**
|
|
53
39
|
* What makes two funnel rows the same question: the two nodes a deployment
|
|
@@ -94,6 +80,26 @@ const shareOf = (count, of, drawable) => {
|
|
|
94
80
|
* reason: it only has to keep the division defined.
|
|
95
81
|
*/
|
|
96
82
|
const rateCeilingOf = (reached, converted, drift) => Math.min(1, (converted + drift) / Math.max(1, reached - drift));
|
|
83
|
+
/**
|
|
84
|
+
* The readers a pair loses between its two ends, at each end of the rate's own
|
|
85
|
+
* interval, on the scale the page's door counts in.
|
|
86
|
+
*
|
|
87
|
+
* **Both ends are one expression over two rates**, which is the whole of why
|
|
88
|
+
* they can be compared: the reach is put on the door's scale once and then taken
|
|
89
|
+
* at each bound of the rate. Spelling the ceiling as the loss instead —
|
|
90
|
+
* `atDoorScale(reached − converted)`, which is the same number — is the shape
|
|
91
|
+
* that looks more direct and is wrong, because at a drift of nought
|
|
92
|
+
* `reached × (1 − converted ÷ reached)` and `reached − converted` differ in the
|
|
93
|
+
* last place for three readers out of three and one conversion. A floor four
|
|
94
|
+
* hundred-quadrillionths above its own ceiling is a floor that is not one.
|
|
95
|
+
*
|
|
96
|
+
* Only ever called where the door can scale, which is what `drawable` means at
|
|
97
|
+
* the call site.
|
|
98
|
+
*/
|
|
99
|
+
const leakOf = (reached, rate, rateAtMost, of) => {
|
|
100
|
+
const atDoor = atDoorScale(reached, of);
|
|
101
|
+
return { atLeast: atDoor * (1 - rateAtMost), atMost: atDoor * (1 - rate) };
|
|
102
|
+
};
|
|
97
103
|
const standingIn = (parts, end) => parts.has(end.nodeId) ? "present" : "absent";
|
|
98
104
|
const reachOf = (row, of, silenced, ends) => {
|
|
99
105
|
const { reached, converted } = row;
|
|
@@ -109,6 +115,8 @@ const reachOf = (row, of, silenced, ends) => {
|
|
|
109
115
|
const bothAsked = fromAsked && ends.to === "present";
|
|
110
116
|
const lost = of.appearances - reached;
|
|
111
117
|
const between = reached - converted;
|
|
118
|
+
const rate = bothAsked && reached > 0 ? converted / reached : null;
|
|
119
|
+
const rateAtMost = bothAsked && !silenced && reached > 0 ? rateCeilingOf(reached, converted, of.drift) : null;
|
|
112
120
|
return {
|
|
113
121
|
pair: row.pair,
|
|
114
122
|
reached,
|
|
@@ -117,8 +125,14 @@ const reachOf = (row, of, silenced, ends) => {
|
|
|
117
125
|
ends,
|
|
118
126
|
stale: !bothAsked,
|
|
119
127
|
orphaned: (!fromAsked && reached > 0) || (ends.to === "absent" && converted > 0),
|
|
120
|
-
rate
|
|
121
|
-
rateAtMost
|
|
128
|
+
rate,
|
|
129
|
+
rateAtMost,
|
|
130
|
+
/**
|
|
131
|
+
* Under `drawable` the two rates are null together — a silence is the only
|
|
132
|
+
* thing the ceiling withholds for that the floor does not — so the second
|
|
133
|
+
* check is the narrowing and not a second case.
|
|
134
|
+
*/
|
|
135
|
+
leak: drawable && rate !== null && rateAtMost !== null ? leakOf(reached, rate, rateAtMost, of) : null,
|
|
122
136
|
entry: shareOf(reached, of, drawable && fromAsked),
|
|
123
137
|
conversion: shareOf(converted, of, drawable && bothAsked),
|
|
124
138
|
lostBefore: drawable && fromAsked ? lost / of.appearances : null,
|
|
@@ -150,9 +164,10 @@ export const funnelReachOf = (reading, funnels, rows) => {
|
|
|
150
164
|
audienceId: reading.audienceId,
|
|
151
165
|
};
|
|
152
166
|
const { measured, foreign, duplicated } = pageViewsFor(where, rows);
|
|
153
|
-
const
|
|
154
|
-
const
|
|
155
|
-
const
|
|
167
|
+
const of = doorOf(measured);
|
|
168
|
+
const { opened, appearances, drift, pending } = of;
|
|
169
|
+
const silence = of.silence;
|
|
170
|
+
const { inflation, updatedAt } = measured ?? { inflation: null, updatedAt: null };
|
|
156
171
|
const here = funnels.filter((row) => row.treeId === where.treeId && row.revision === where.revision);
|
|
157
172
|
/**
|
|
158
173
|
* A funnel pair is asked of a page, and a page served in two forms answers
|