@jam-overture/loom 0.1.0 → 0.2.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/README.md +3 -1
- package/dist/application/application.d.ts +109 -0
- package/dist/application/application.js +97 -0
- package/dist/application/memory.d.ts +20 -0
- package/dist/application/memory.js +79 -0
- package/dist/application/store.d.ts +101 -0
- package/dist/application/store.js +25 -0
- package/dist/audience/audience.d.ts +36 -0
- package/dist/audience/audience.js +41 -0
- package/dist/cli/templates.js +19 -0
- package/dist/data/plan.js +0 -0
- package/dist/data/resolution.d.ts +23 -1
- package/dist/data/resolve.d.ts +30 -3
- package/dist/data/resolve.js +11 -3
- package/dist/ids.d.ts +10 -0
- package/dist/ids.js +11 -1
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -0
- package/dist/patch.d.ts +54 -0
- package/dist/patch.js +44 -0
- package/dist/project/closing.d.ts +51 -0
- package/dist/project/closing.js +53 -0
- package/dist/project/memory.d.ts +20 -0
- package/dist/project/memory.js +97 -0
- package/dist/project/project.d.ts +90 -0
- package/dist/project/project.js +91 -0
- package/dist/project/store.d.ts +135 -0
- package/dist/project/store.js +41 -0
- package/dist/registered.d.ts +64 -0
- package/dist/registered.js +118 -0
- package/dist/render/behaviour-adjust.d.ts +11 -19
- package/dist/render/behaviour-adjust.js +75 -21
- package/dist/render/behaviour-present.d.ts +8 -0
- package/dist/render/behaviour-present.js +57 -6
- package/dist/render/behaviour.d.ts +98 -17
- package/dist/render/behaviour.js +91 -26
- package/dist/render/control-name.d.ts +68 -0
- package/dist/render/control-name.js +37 -0
- package/dist/render/diagnostics.d.ts +72 -0
- package/dist/render/diagnostics.js +7 -0
- package/dist/render/index.d.ts +2 -0
- package/dist/render/index.js +2 -0
- package/dist/render/reads.d.ts +11 -0
- package/dist/render/reads.js +12 -1
- package/dist/render/render.js +102 -7
- package/dist/render/slots.d.ts +52 -0
- package/dist/render/slots.js +24 -0
- package/dist/render/theme.d.ts +54 -1
- package/dist/render/theme.js +23 -1
- package/dist/render/unshown.d.ts +152 -0
- package/dist/render/unshown.js +80 -0
- package/dist/runtime/analysis.d.ts +94 -9
- package/dist/runtime/analysis.js +54 -9
- package/dist/runtime/assessment.d.ts +36 -2
- package/dist/runtime/assessment.js +27 -2
- package/dist/runtime/checks.d.ts +148 -0
- package/dist/runtime/checks.js +112 -0
- package/dist/runtime/disposition.d.ts +96 -0
- package/dist/runtime/disposition.js +46 -0
- package/dist/runtime/gate.js +22 -0
- package/dist/runtime/index.d.ts +3 -0
- package/dist/runtime/index.js +3 -0
- package/dist/runtime/irreversibility.d.ts +64 -0
- package/dist/runtime/irreversibility.js +45 -0
- package/dist/runtime/pipeline.d.ts +43 -0
- package/dist/runtime/pipeline.js +10 -2
- package/dist/runtime/policy-change.d.ts +93 -0
- package/dist/runtime/policy-change.js +299 -0
- package/dist/runtime/policy-log.d.ts +406 -0
- package/dist/runtime/policy-log.js +285 -0
- package/dist/runtime/reversibility.d.ts +11 -9
- package/dist/runtime/stakes.d.ts +129 -1
- package/dist/runtime/stakes.js +240 -26
- package/dist/runtime/vocabulary.d.ts +164 -7
- package/dist/runtime/vocabulary.js +181 -8
- package/dist/sdk/audit.d.ts +174 -3
- package/dist/sdk/audit.js +176 -17
- package/dist/sdk/catalogue.d.ts +9 -1
- package/dist/sdk/conformance.d.ts +37 -3
- package/dist/sdk/conformance.js +25 -4
- package/dist/sdk/definition.d.ts +65 -0
- package/dist/sdk/definition.js +22 -0
- package/dist/sdk/registry.d.ts +29 -2
- package/dist/sdk/registry.js +63 -1
- package/dist/signals/action-change.d.ts +507 -0
- package/dist/signals/action-change.js +265 -0
- package/dist/signals/action.d.ts +331 -0
- package/dist/signals/action.js +182 -0
- package/dist/signals/applied-window.contract.d.ts +23 -0
- package/dist/signals/applied-window.contract.js +160 -0
- package/dist/signals/arriving.d.ts +210 -0
- package/dist/signals/arriving.js +133 -0
- package/dist/signals/audiences.d.ts +528 -0
- package/dist/signals/audiences.js +255 -0
- package/dist/signals/broadcast.d.ts +8 -2
- package/dist/signals/broadcast.js +58 -8
- package/dist/signals/change.d.ts +378 -0
- package/dist/signals/change.js +327 -0
- package/dist/signals/collect.d.ts +41 -0
- package/dist/signals/collect.js +88 -7
- package/dist/signals/copy-change.d.ts +553 -0
- package/dist/signals/copy-change.js +377 -0
- package/dist/signals/copy.d.ts +337 -0
- package/dist/signals/copy.js +211 -0
- package/dist/signals/counters.d.ts +46 -0
- package/dist/signals/counters.js +102 -0
- package/dist/signals/deliver.d.ts +23 -4
- package/dist/signals/deliver.js +34 -6
- package/dist/signals/deployment-change.d.ts +371 -0
- package/dist/signals/deployment-change.js +268 -0
- package/dist/signals/deployment.d.ts +265 -0
- package/dist/signals/deployment.js +152 -0
- package/dist/signals/door.d.ts +92 -0
- package/dist/signals/door.js +53 -0
- package/dist/signals/fold.d.ts +10 -0
- package/dist/signals/fold.js +5 -1
- package/dist/signals/form-action.d.ts +302 -0
- package/dist/signals/form-action.js +169 -0
- package/dist/signals/form-copy.d.ts +523 -0
- package/dist/signals/form-copy.js +346 -0
- package/dist/signals/forms.d.ts +247 -0
- package/dist/signals/forms.js +147 -0
- package/dist/signals/funnel-change.d.ts +548 -0
- package/dist/signals/funnel-change.js +361 -0
- package/dist/signals/funnel.d.ts +532 -0
- package/dist/signals/funnel.js +216 -0
- package/dist/signals/health.d.ts +497 -0
- package/dist/signals/health.js +361 -0
- package/dist/signals/index.d.ts +41 -0
- package/dist/signals/index.js +41 -0
- package/dist/signals/ingest.d.ts +56 -1
- package/dist/signals/ingest.js +91 -1
- package/dist/signals/journal.d.ts +11 -0
- package/dist/signals/kinds.d.ts +8 -6
- package/dist/signals/kinds.js +14 -6
- package/dist/signals/library-action.d.ts +430 -0
- package/dist/signals/library-action.js +336 -0
- package/dist/signals/library-change.d.ts +477 -0
- package/dist/signals/library-change.js +335 -0
- package/dist/signals/library-copy-change.d.ts +498 -0
- package/dist/signals/library-copy-change.js +476 -0
- package/dist/signals/library-pace.d.ts +319 -0
- package/dist/signals/library-pace.js +305 -0
- package/dist/signals/library-reach-change.d.ts +636 -0
- package/dist/signals/library-reach-change.js +534 -0
- package/dist/signals/library-reach.d.ts +377 -0
- package/dist/signals/library-reach.js +227 -0
- package/dist/signals/library-word-reach-change.d.ts +567 -0
- package/dist/signals/library-word-reach-change.js +568 -0
- package/dist/signals/library.d.ts +306 -0
- package/dist/signals/library.js +178 -0
- package/dist/signals/memory.d.ts +9 -0
- package/dist/signals/memory.js +105 -14
- package/dist/signals/migrate.d.ts +17 -2
- package/dist/signals/migrate.js +122 -5
- package/dist/signals/notice.d.ts +334 -0
- package/dist/signals/notice.js +228 -0
- package/dist/signals/pace-change.d.ts +501 -0
- package/dist/signals/pace-change.js +310 -0
- package/dist/signals/pace.d.ts +296 -0
- package/dist/signals/pace.js +291 -0
- package/dist/signals/page-views.d.ts +365 -0
- package/dist/signals/page-views.js +218 -0
- package/dist/signals/parts.d.ts +344 -0
- package/dist/signals/parts.js +273 -0
- package/dist/signals/postgres.d.ts +16 -2
- package/dist/signals/postgres.js +390 -87
- package/dist/signals/progress.d.ts +212 -0
- package/dist/signals/progress.js +150 -0
- package/dist/signals/ratios.d.ts +108 -0
- package/dist/signals/ratios.js +40 -0
- package/dist/signals/reach.d.ts +309 -0
- package/dist/signals/reach.js +93 -0
- package/dist/signals/readable.d.ts +34 -0
- package/dist/signals/readable.js +34 -0
- package/dist/signals/readership.d.ts +381 -0
- package/dist/signals/readership.js +308 -0
- package/dist/signals/region-pages.d.ts +173 -0
- package/dist/signals/region-pages.js +62 -0
- package/dist/signals/region.d.ts +287 -0
- package/dist/signals/region.js +198 -0
- package/dist/signals/retention.d.ts +141 -0
- package/dist/signals/retention.js +58 -0
- package/dist/signals/rollup.d.ts +67 -3
- package/dist/signals/rollup.js +0 -0
- package/dist/signals/schema.d.ts +432 -1
- package/dist/signals/schema.js +157 -3
- package/dist/signals/signal.d.ts +237 -11
- package/dist/signals/signal.js +70 -10
- package/dist/signals/silence-census.d.ts +205 -0
- package/dist/signals/silence-census.js +87 -0
- package/dist/signals/silences.d.ts +848 -0
- package/dist/signals/silences.js +753 -0
- package/dist/signals/tally.d.ts +140 -11
- package/dist/signals/window-figures.d.ts +148 -0
- package/dist/signals/window-figures.js +42 -0
- package/dist/signals/window.d.ts +866 -0
- package/dist/signals/window.js +693 -0
- package/dist/signals/words.d.ts +24 -0
- package/dist/signals/words.js +24 -0
- package/dist/store/index.d.ts +19 -0
- package/dist/store/index.js +19 -0
- package/dist/store/memory.d.ts +2 -1
- package/dist/store/memory.js +48 -12
- package/dist/store/migrate.d.ts +80 -0
- package/dist/store/migrate.js +259 -7
- package/dist/store/postgres-applications.d.ts +4 -0
- package/dist/store/postgres-applications.js +197 -0
- package/dist/store/postgres-holds.d.ts +10 -1
- package/dist/store/postgres-holds.js +116 -101
- package/dist/store/postgres-policy-log.d.ts +14 -0
- package/dist/store/postgres-policy-log.js +240 -0
- package/dist/store/postgres-projects.d.ts +4 -0
- package/dist/store/postgres-projects.js +217 -0
- package/dist/store/postgres.d.ts +16 -1
- package/dist/store/postgres.js +59 -9
- package/dist/store/replay.d.ts +102 -1
- package/dist/store/replay.js +190 -19
- package/dist/store/reseed.d.ts +238 -0
- package/dist/store/reseed.js +308 -0
- package/dist/store/schema.d.ts +450 -2
- package/dist/store/schema.js +141 -5
- package/dist/store/store.d.ts +29 -6
- package/dist/submit/resolve.js +2 -1
- package/dist/telemetry/calibration.d.ts +25 -0
- package/dist/telemetry/calibration.js +27 -1
- package/dist/telemetry/event.d.ts +391 -33
- package/dist/telemetry/event.js +84 -20
- package/dist/telemetry/index.d.ts +1 -0
- package/dist/telemetry/index.js +1 -0
- package/dist/telemetry/journal.d.ts +72 -3
- package/dist/telemetry/journal.js +9 -0
- package/dist/telemetry/lookup.d.ts +27 -0
- package/dist/telemetry/lookup.js +18 -0
- package/dist/telemetry/memory.js +23 -0
- package/dist/telemetry/migrate.js +22 -1
- package/dist/telemetry/postgres.d.ts +10 -1
- package/dist/telemetry/postgres.js +172 -90
- package/dist/telemetry/remeasure.d.ts +78 -0
- package/dist/telemetry/remeasure.js +83 -0
- package/dist/telemetry/retention.d.ts +2 -2
- package/dist/telemetry/schema.d.ts +17 -0
- package/dist/telemetry/schema.js +27 -1
- package/dist/telemetry/sink.d.ts +2 -2
- package/dist/testing/application-contract.d.ts +14 -0
- package/dist/testing/application-contract.js +270 -0
- package/dist/testing/contracts.d.ts +12 -7
- package/dist/testing/contracts.js +12 -7
- package/dist/testing/definitions.d.ts +78 -0
- package/dist/testing/definitions.js +134 -9
- package/dist/testing/doubles.d.ts +103 -0
- package/dist/testing/doubles.js +143 -0
- package/dist/testing/index.d.ts +2 -2
- package/dist/testing/index.js +2 -2
- package/dist/testing/journal-contract.js +140 -2
- package/dist/testing/model-contract.d.ts +110 -0
- package/dist/testing/model-contract.js +150 -0
- package/dist/testing/policy-log-contract.d.ts +26 -0
- package/dist/testing/policy-log-contract.js +344 -0
- package/dist/testing/project-contract.d.ts +14 -0
- package/dist/testing/project-contract.js +266 -0
- package/dist/testing/reader-signal-contract.d.ts +27 -2
- package/dist/testing/reader-signal-contract.js +475 -5
- package/dist/testing/store-contract.d.ts +7 -1
- package/dist/testing/store-contract.js +84 -3
- package/dist/theme/apply.d.ts +20 -1
- package/dist/theme/apply.js +5 -3
- package/dist/theme/derive.d.ts +22 -0
- package/dist/theme/derive.js +54 -1
- package/dist/theme/library.js +1 -1
- package/dist/theme/measure.d.ts +34 -0
- package/dist/theme/measure.js +30 -1
- package/dist/theme/palettes.js +7 -7
- package/dist/theme/ramp.d.ts +64 -0
- package/dist/theme/ramp.js +114 -0
- package/dist/theme/registry.d.ts +9 -0
- package/dist/theme/registry.js +11 -1
- package/dist/theme/separation.d.ts +97 -3
- package/dist/theme/separation.js +75 -0
- package/dist/tree/compare.d.ts +9 -0
- package/dist/tree/compare.js +18 -0
- package/dist/write/computed.d.ts +60 -0
- package/dist/write/computed.js +61 -0
- package/dist/write/held.d.ts +59 -0
- package/dist/write/index.d.ts +5 -2
- package/dist/write/index.js +5 -2
- package/dist/write/reseed.d.ts +151 -0
- package/dist/write/reseed.js +184 -0
- package/dist/write/revert.js +2 -16
- package/package.json +98 -19
|
@@ -0,0 +1,309 @@
|
|
|
1
|
+
import type { NodeId, TreeId } from "../ids.js";
|
|
2
|
+
import type { PrimitiveType } from "../primitive-type.js";
|
|
3
|
+
import type { PrimitiveRole } from "../role.js";
|
|
4
|
+
import { type StoredPageViews } from "./page-views.js";
|
|
5
|
+
import type { PageReading, PartStanding } from "./parts.js";
|
|
6
|
+
/**
|
|
7
|
+
* How far into a page readers get, as a share of the readers there were.
|
|
8
|
+
*
|
|
9
|
+
* Every figure a reader screen will show is a rate, and this subsystem has
|
|
10
|
+
* carried its numerator and its denominator in two places that never met. A
|
|
11
|
+
* part's `reached` is distinct page views that saw it, added across rollup
|
|
12
|
+
* windows, so a visit that straddled a boundary is counted twice and nobody
|
|
13
|
+
* could say how often that happened. A page's openings are counted once at the
|
|
14
|
+
* door, are exact, and add across windows, revisions and months. A reading
|
|
15
|
+
* joined the first to the tree and used the largest row it could find as a
|
|
16
|
+
* floor on how many readers there were; the exact number was one row away and
|
|
17
|
+
* nothing fetched it.
|
|
18
|
+
*
|
|
19
|
+
* **This is that join, and what it buys is an honest rate where there was a
|
|
20
|
+
* count nobody could qualify.** *About two hundred of the three hundred and
|
|
21
|
+
* twenty readers who arrived got as far as the pricing band* is the sentence,
|
|
22
|
+
* and the arithmetic that makes it sayable is a division nobody had to collect
|
|
23
|
+
* anything for: it is the fifth thing taken out of the server-side join rather
|
|
24
|
+
* than off the wire. Nothing is added to a payload, a browser, a column, a
|
|
25
|
+
* store or the vocabulary.
|
|
26
|
+
*
|
|
27
|
+
* ## Two denominators, because they fail in opposite directions
|
|
28
|
+
*
|
|
29
|
+
* `appearances` is the same page views as the rollups counted them — once per
|
|
30
|
+
* window each appeared in — so it carries the straddle over-count that a
|
|
31
|
+
* part's `reached` carries, and dividing one by the other very nearly cancels
|
|
32
|
+
* it. That is the argument the fall between two siblings is built on
|
|
33
|
+
* ([0221](../../decisions/0221-where-reading-stops-is-a-fall-between-two-siblings-and-a-ratio-of-two-counts-off-one-row-set.md)),
|
|
34
|
+
* one level up: a part against its page rather than a part against its
|
|
35
|
+
* neighbour.
|
|
36
|
+
*
|
|
37
|
+
* `opened` is exact, and dividing by it gives something stronger than an
|
|
38
|
+
* estimate and narrower in use: a **ceiling**. A part's `reached` is at least
|
|
39
|
+
* the number of readers who really reached it, and the openings are a count of
|
|
40
|
+
* readers that cannot be inflated by a window boundary, so the true share
|
|
41
|
+
* cannot be above `reached ÷ opened`. The ratio can honestly sit above 1 —
|
|
42
|
+
* which is why it is not the figure a stop is reported as — and when it does,
|
|
43
|
+
* the ceiling says nothing and the fact that it says nothing is itself the
|
|
44
|
+
* answer.
|
|
45
|
+
*
|
|
46
|
+
* **The gap between the estimate and the ceiling is the straddle**, which is
|
|
47
|
+
* the measurement
|
|
48
|
+
* [0219](../../decisions/0219-a-page-view-is-counted-once-at-the-door-and-the-over-count-in-the-node-counters-is-a-measurement.md)
|
|
49
|
+
* published and nothing had used yet. It closes to nothing on a deployment
|
|
50
|
+
* whose rollup window is long enough that nobody's visit spans two — and that
|
|
51
|
+
* is the first time the one control a deployment has over this error can be
|
|
52
|
+
* checked against a number after it is turned.
|
|
53
|
+
*
|
|
54
|
+
* ## What it refuses to say
|
|
55
|
+
*
|
|
56
|
+
* A share of readers is three divisions away from a profile of one, so the
|
|
57
|
+
* things not here are worth naming. There is no page-level total of the
|
|
58
|
+
* readers who got anywhere: one reader who reached four bands is in four rows,
|
|
59
|
+
* and adding them counts them four times. There is no ranking, because where a
|
|
60
|
+
* page loses readers is a question about two siblings and is answered
|
|
61
|
+
* elsewhere. And a projection onto the exact denominator is withheld whenever
|
|
62
|
+
* the collection is behind, because applying the rate of the page views that
|
|
63
|
+
* have been folded to the page views that have not is a guess about readers
|
|
64
|
+
* nobody has counted yet.
|
|
65
|
+
*
|
|
66
|
+
* Pure. It is handed a reading and the page-view rows, and reaches no store, no
|
|
67
|
+
* clock and no DOM; it adds nothing to the broadcaster's import graph.
|
|
68
|
+
*/
|
|
69
|
+
/**
|
|
70
|
+
* Why a share of readers cannot be given at all.
|
|
71
|
+
*
|
|
72
|
+
* Each one is a state of the deployment rather than of the page, so it is
|
|
73
|
+
* reported once for the reading instead of on every part — and each is a
|
|
74
|
+
* different sentence, which is the reason there are three rather than a null.
|
|
75
|
+
*/
|
|
76
|
+
export type ReachSilence =
|
|
77
|
+
/**
|
|
78
|
+
* No page-view row for this tree and revision.
|
|
79
|
+
*
|
|
80
|
+
* Either the counter has never been written for it — a deployment whose
|
|
81
|
+
* intake predates the column, or one whose rows have expired — or the caller
|
|
82
|
+
* read the rows for something else. The counters are still a floor on how
|
|
83
|
+
* many readers there were, which is what a reading reported before this
|
|
84
|
+
* join existed, so a surface has something to fall back to and should say
|
|
85
|
+
* which it is showing.
|
|
86
|
+
*/
|
|
87
|
+
"unmeasured"
|
|
88
|
+
/**
|
|
89
|
+
* The row is there and nothing in it says a page view ever began.
|
|
90
|
+
*
|
|
91
|
+
* Two deployments look like this and the second is the one worth catching.
|
|
92
|
+
* If no rollup has counted an appearance either, nobody has read this
|
|
93
|
+
* revision and there is nothing to divide. If appearances have been counted,
|
|
94
|
+
* **the senders are not marking their openings** — a page running a
|
|
95
|
+
* broadcaster from before the marker shipped, or one whose opening delivery
|
|
96
|
+
* is being lost — and every rate on the screen has no denominator while the
|
|
97
|
+
* counters look healthy. That is a diagnosis nothing else in this subsystem
|
|
98
|
+
* offers.
|
|
99
|
+
*/
|
|
100
|
+
| "unopened"
|
|
101
|
+
/**
|
|
102
|
+
* Readers arrived and no rollup has folded a window yet.
|
|
103
|
+
*
|
|
104
|
+
* Everything is `pending`. It is what the first minutes of a deployment look
|
|
105
|
+
* like, and what a stalled collection looks like for ever, and the two are
|
|
106
|
+
* told apart by whether the number moves.
|
|
107
|
+
*/
|
|
108
|
+
| "uncounted";
|
|
109
|
+
export declare const REACH_SILENCES: readonly ReachSilence[];
|
|
110
|
+
/** One line per silence, for a surface putting the reading in front of a person. */
|
|
111
|
+
export declare const describeReachSilence: (silence: ReachSilence) => string;
|
|
112
|
+
/**
|
|
113
|
+
* How far one part of a page got, against the readers there were.
|
|
114
|
+
*
|
|
115
|
+
* The identity and the standing are carried over from the reading rather than
|
|
116
|
+
* re-derived, so a surface drawing this never has to hold two lists side by
|
|
117
|
+
* side and match them up by id.
|
|
118
|
+
*/
|
|
119
|
+
export type PartReach = {
|
|
120
|
+
readonly nodeId: NodeId;
|
|
121
|
+
readonly type: PrimitiveType;
|
|
122
|
+
/** What part it plays, or `null` where its type declared none (0114). */
|
|
123
|
+
readonly role: PrimitiveRole | null;
|
|
124
|
+
/** 0 at the root, as the reading's outline gives it. */
|
|
125
|
+
readonly depth: number;
|
|
126
|
+
readonly standing: PartStanding;
|
|
127
|
+
/**
|
|
128
|
+
* Distinct page views that saw it, exactly as stored: added across rollup
|
|
129
|
+
* windows and therefore generous (0147).
|
|
130
|
+
*
|
|
131
|
+
* Published beside the shares rather than hidden behind them, because it is
|
|
132
|
+
* the only figure here that is not a division and the one to fall back to
|
|
133
|
+
* when the pair cannot be reconciled.
|
|
134
|
+
*/
|
|
135
|
+
readonly reached: number;
|
|
136
|
+
/**
|
|
137
|
+
* The share of page views that got this far, as the rollups counted both
|
|
138
|
+
* ends: `reached ÷ appearances`.
|
|
139
|
+
*
|
|
140
|
+
* The straddle over-count is in the numerator and the denominator and very
|
|
141
|
+
* nearly divides out, which is what makes this the figure to show. It is an
|
|
142
|
+
* estimate and not a bound, and the direction it leans is worth knowing: a
|
|
143
|
+
* reader who stayed long enough to span two windows is counted twice on both
|
|
144
|
+
* sides, and a reader who stays longer is likelier to have got deep into the
|
|
145
|
+
* page — so for a part near the bottom this reads a little generous.
|
|
146
|
+
*
|
|
147
|
+
* **Its denominator is the page views that have been counted, which is not
|
|
148
|
+
* every reader who arrived.** While openings are pending the two are
|
|
149
|
+
* different populations, so this can sit above
|
|
150
|
+
* {@link PartReach.atMost} — that is not a contradiction and the pending
|
|
151
|
+
* figure is the explanation.
|
|
152
|
+
*
|
|
153
|
+
* `null` under a silence.
|
|
154
|
+
*/
|
|
155
|
+
readonly share: number | null;
|
|
156
|
+
/**
|
|
157
|
+
* The most the share could be: `reached ÷ opened`, never above 1.
|
|
158
|
+
*
|
|
159
|
+
* A ceiling rather than an estimate. The openings are a count of readers that
|
|
160
|
+
* no window boundary can inflate, and `reached` is at least the number of
|
|
161
|
+
* readers who really got here, so the true share is at or below this.
|
|
162
|
+
*
|
|
163
|
+
* **For a part nearly everybody reaches it is 1 and says nothing**, and that
|
|
164
|
+
* is the ordinary state rather than a fault: a root is in the viewport of
|
|
165
|
+
* every page view, so where any visit spanned two windows its `reached` is
|
|
166
|
+
* above the openings on its own. The estimate is the figure with information
|
|
167
|
+
* in it there; this is the one that bounds a part further down.
|
|
168
|
+
*
|
|
169
|
+
* `null` under a silence.
|
|
170
|
+
*/
|
|
171
|
+
readonly atMost: number | null;
|
|
172
|
+
/**
|
|
173
|
+
* The share applied to the exact count of readers who arrived — the number a
|
|
174
|
+
* sentence can say out loud.
|
|
175
|
+
*
|
|
176
|
+
* Deliberately not rounded: it is a magnitude and not a census, and a surface
|
|
177
|
+
* that rounds it is saying how precise it thinks it is.
|
|
178
|
+
*
|
|
179
|
+
* **One division of two whole numbers, not the share multiplied back up.**
|
|
180
|
+
* The two are the same arithmetic in exact numbers and not in a float —
|
|
181
|
+
* seven readers out of a hundred, times a hundred, is seven and a
|
|
182
|
+
* quadrillionth, which is above the most readers who could have got there and
|
|
183
|
+
* would make this figure break its own ceiling.
|
|
184
|
+
*
|
|
185
|
+
* Withheld in three states rather than given as a number nobody could stand
|
|
186
|
+
* behind: under a silence; whenever the collection is behind, because
|
|
187
|
+
* openings a rollup has not reached yet are readers whose reading nobody has
|
|
188
|
+
* counted and projecting the folded rate onto them would answer a question
|
|
189
|
+
* about people who were never measured; and where the two counters cannot be
|
|
190
|
+
* reconciled, because a count of people above the number of people who
|
|
191
|
+
* arrived is the one figure a screen must never show.
|
|
192
|
+
*/
|
|
193
|
+
readonly readers: number | null;
|
|
194
|
+
/**
|
|
195
|
+
* The most readers who could have got here: the smaller of `reached` and the
|
|
196
|
+
* openings, which is a whole number of real page views either way.
|
|
197
|
+
*
|
|
198
|
+
* `null` under a silence. Where {@link PartReach.readers} is given it is
|
|
199
|
+
* never above this.
|
|
200
|
+
*/
|
|
201
|
+
readonly atMostReaders: number | null;
|
|
202
|
+
/**
|
|
203
|
+
* More reach than there were page views to be reached in, so the share sits
|
|
204
|
+
* above 1 and no figure here can be drawn.
|
|
205
|
+
*
|
|
206
|
+
* Reach is counted out of the same windows as the appearances it is divided
|
|
207
|
+
* by, and a view that reached a part in a window is a view that appeared in
|
|
208
|
+
* it — so rows written by the same rollups cannot produce this. Two things
|
|
209
|
+
* can. **Node counters older than the page-view column**, added up over
|
|
210
|
+
* windows whose appearances were never kept, which is what an upgraded
|
|
211
|
+
* deployment's first reading looks like. Or a caller who concatenated two
|
|
212
|
+
* reads of the counters instead of letting the store add them, which the
|
|
213
|
+
* reading upstream reports as a duplicated node.
|
|
214
|
+
*
|
|
215
|
+
* It is not the ordinary straddle: `reached` above the *openings* is
|
|
216
|
+
* expected, and is what {@link PartReach.atMost} being 1 means.
|
|
217
|
+
*
|
|
218
|
+
* A surface should show `reached` and say it cannot yet be put as a share.
|
|
219
|
+
*/
|
|
220
|
+
readonly unreconciled: boolean;
|
|
221
|
+
};
|
|
222
|
+
/**
|
|
223
|
+
* A window of counters, read against the exact number of readers that window
|
|
224
|
+
* had.
|
|
225
|
+
*
|
|
226
|
+
* The page-view figures are the ones a reading of that counter alone would
|
|
227
|
+
* give, carried here so that a surface drawing shares has the arithmetic behind
|
|
228
|
+
* them on the same object and does not have to pair two readings up by hand.
|
|
229
|
+
*/
|
|
230
|
+
export type PageReach = {
|
|
231
|
+
readonly treeId: TreeId;
|
|
232
|
+
readonly revision: number;
|
|
233
|
+
/** Page views that began on this revision. Exact, and addable (0219). */
|
|
234
|
+
readonly opened: number;
|
|
235
|
+
/** The same page views as the rollups counted them: once per window each appeared in. */
|
|
236
|
+
readonly appearances: number;
|
|
237
|
+
/** Appearances in excess of openings — the straddle, measured. Never negative. */
|
|
238
|
+
readonly drift: number;
|
|
239
|
+
/** Openings whose reading no rollup has folded yet. The other sign of the same subtraction. */
|
|
240
|
+
readonly pending: number;
|
|
241
|
+
/** `drift ÷ opened`: how generous every distinct count here is. `null` when nothing opened. */
|
|
242
|
+
readonly inflation: number | null;
|
|
243
|
+
/** When the page-view row last moved, or `null` where there is no row. */
|
|
244
|
+
readonly updatedAt: string | null;
|
|
245
|
+
/**
|
|
246
|
+
* The floor the counters give on their own: the largest `views` any one row
|
|
247
|
+
* reports.
|
|
248
|
+
*
|
|
249
|
+
* What a reading had to use as a denominator before there was an exact one,
|
|
250
|
+
* kept so that a deployment can see the difference the join made rather than
|
|
251
|
+
* being told it was wrong. Against an honest sender it sits at or below the
|
|
252
|
+
* openings plus the straddle.
|
|
253
|
+
*/
|
|
254
|
+
readonly countedViews: number;
|
|
255
|
+
/**
|
|
256
|
+
* Set where no share can be given, and the reason. `null` where they can.
|
|
257
|
+
*/
|
|
258
|
+
readonly silence: ReachSilence | null;
|
|
259
|
+
/**
|
|
260
|
+
* Nobody's visit spanned two windows, so there is nothing to divide out: the
|
|
261
|
+
* estimate and the ceiling are the same number and the shares are exact.
|
|
262
|
+
*
|
|
263
|
+
* False under a silence, and false while any opening is pending.
|
|
264
|
+
*/
|
|
265
|
+
readonly exact: boolean;
|
|
266
|
+
/** Every part of the revision, in reading order, as the reading had them. */
|
|
267
|
+
readonly parts: readonly PartReach[];
|
|
268
|
+
/**
|
|
269
|
+
* The parts whose reach could not be reconciled with the openings.
|
|
270
|
+
*
|
|
271
|
+
* Empty is the healthy state. A non-empty list on a deployment whose drift is
|
|
272
|
+
* nought is not a straddle and not a lie: it is node counters older than the
|
|
273
|
+
* column they are being divided by.
|
|
274
|
+
*/
|
|
275
|
+
readonly unreconciled: readonly NodeId[];
|
|
276
|
+
/**
|
|
277
|
+
* Page-view rows handed in for another tree or another revision, and ignored.
|
|
278
|
+
*
|
|
279
|
+
* Dividing one revision's counters by another's readers is the mistake that
|
|
280
|
+
* would make every rate here quietly wrong, so this filters rather than
|
|
281
|
+
* trusts its caller — and says how much it dropped, because a caller who
|
|
282
|
+
* passed a whole store's rows and one who passed the wrong revision's look
|
|
283
|
+
* identical from the inside.
|
|
284
|
+
*/
|
|
285
|
+
readonly foreign: number;
|
|
286
|
+
/**
|
|
287
|
+
* Rows for this tree and revision beyond the first, where every one after it
|
|
288
|
+
* was ignored.
|
|
289
|
+
*
|
|
290
|
+
* A store keeps one row per revision, so this cannot happen from one read —
|
|
291
|
+
* it happens when a caller concatenates two reads. Adding them is wrong,
|
|
292
|
+
* because the openings are already a total and would double; taking the last
|
|
293
|
+
* is wrong, because it is not the truer one. So the first row stands and the
|
|
294
|
+
* fact is reported.
|
|
295
|
+
*/
|
|
296
|
+
readonly duplicated: number;
|
|
297
|
+
};
|
|
298
|
+
/**
|
|
299
|
+
* Read a window's counters against the readers that window had.
|
|
300
|
+
*
|
|
301
|
+
* The reading names the tree and the revision it was built for, so the rows are
|
|
302
|
+
* filtered to it here rather than being trusted: there is no way to ask this
|
|
303
|
+
* question about a revision without holding the revision, which is the property
|
|
304
|
+
* the join upstream has and this one keeps.
|
|
305
|
+
*
|
|
306
|
+
* Linear in the parts and in the rows, with one pass over each.
|
|
307
|
+
*/
|
|
308
|
+
export declare const pageReachOf: (reading: PageReading, rows: readonly StoredPageViews[]) => PageReach;
|
|
309
|
+
//# sourceMappingURL=reach.d.ts.map
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
import { everyMemberOf } from "../closed-set.js";
|
|
2
|
+
import { pageViewsFor } from "./page-views.js";
|
|
3
|
+
export const REACH_SILENCES = everyMemberOf()([
|
|
4
|
+
"unmeasured",
|
|
5
|
+
"unopened",
|
|
6
|
+
"uncounted",
|
|
7
|
+
]);
|
|
8
|
+
/** One line per silence, for a surface putting the reading in front of a person. */
|
|
9
|
+
export const describeReachSilence = (silence) => {
|
|
10
|
+
switch (silence) {
|
|
11
|
+
case "unmeasured":
|
|
12
|
+
return "no page views have been counted for this version of the page";
|
|
13
|
+
case "unopened":
|
|
14
|
+
return "nothing has said a page view began, so there is no number to divide by";
|
|
15
|
+
case "uncounted":
|
|
16
|
+
return "readers have arrived and no window of their reading has been counted yet";
|
|
17
|
+
}
|
|
18
|
+
};
|
|
19
|
+
const NOTHING_MEASURED = {
|
|
20
|
+
opened: 0,
|
|
21
|
+
appearances: 0,
|
|
22
|
+
drift: 0,
|
|
23
|
+
pending: 0,
|
|
24
|
+
inflation: null,
|
|
25
|
+
updatedAt: null,
|
|
26
|
+
};
|
|
27
|
+
const silenceOf = (opened, appearances) => {
|
|
28
|
+
if (opened === 0)
|
|
29
|
+
return "unopened";
|
|
30
|
+
if (appearances === 0)
|
|
31
|
+
return "uncounted";
|
|
32
|
+
return null;
|
|
33
|
+
};
|
|
34
|
+
/**
|
|
35
|
+
* Read a window's counters against the readers that window had.
|
|
36
|
+
*
|
|
37
|
+
* The reading names the tree and the revision it was built for, so the rows are
|
|
38
|
+
* filtered to it here rather than being trusted: there is no way to ask this
|
|
39
|
+
* question about a revision without holding the revision, which is the property
|
|
40
|
+
* the join upstream has and this one keeps.
|
|
41
|
+
*
|
|
42
|
+
* Linear in the parts and in the rows, with one pass over each.
|
|
43
|
+
*/
|
|
44
|
+
export const pageReachOf = (reading, rows) => {
|
|
45
|
+
/**
|
|
46
|
+
* The row this revision's counters are divided by, picked by the one rule
|
|
47
|
+
* that knows which row belongs to which reading (`pageViewsFor`). The rule is
|
|
48
|
+
* shared rather than written here because it is also what a consumer of the
|
|
49
|
+
* pace reading needs, and the matching is the part of this join that fails
|
|
50
|
+
* quietly when it is got wrong.
|
|
51
|
+
*/
|
|
52
|
+
const { measured, foreign, duplicated } = pageViewsFor(reading, rows);
|
|
53
|
+
const { opened, appearances, drift, pending, inflation, updatedAt } = measured ?? NOTHING_MEASURED;
|
|
54
|
+
const silence = measured === null ? "unmeasured" : silenceOf(opened, appearances);
|
|
55
|
+
const exact = silence === null && appearances === opened;
|
|
56
|
+
const parts = reading.parts.map((part) => {
|
|
57
|
+
const reached = part.counters?.reached ?? 0;
|
|
58
|
+
const unreconciled = silence === null && reached > appearances;
|
|
59
|
+
const share = silence === null ? reached / appearances : null;
|
|
60
|
+
const atMost = silence === null ? Math.min(1, reached / opened) : null;
|
|
61
|
+
return {
|
|
62
|
+
nodeId: part.nodeId,
|
|
63
|
+
type: part.type,
|
|
64
|
+
role: part.role,
|
|
65
|
+
depth: part.depth,
|
|
66
|
+
standing: part.standing,
|
|
67
|
+
reached,
|
|
68
|
+
share,
|
|
69
|
+
atMost,
|
|
70
|
+
readers: share === null || pending > 0 || unreconciled ? null : (reached * opened) / appearances,
|
|
71
|
+
atMostReaders: silence === null ? Math.min(reached, opened) : null,
|
|
72
|
+
unreconciled,
|
|
73
|
+
};
|
|
74
|
+
});
|
|
75
|
+
return {
|
|
76
|
+
treeId: reading.treeId,
|
|
77
|
+
revision: reading.revision,
|
|
78
|
+
opened,
|
|
79
|
+
appearances,
|
|
80
|
+
drift,
|
|
81
|
+
pending,
|
|
82
|
+
inflation,
|
|
83
|
+
updatedAt,
|
|
84
|
+
countedViews: reading.views,
|
|
85
|
+
silence,
|
|
86
|
+
exact,
|
|
87
|
+
parts,
|
|
88
|
+
unreconciled: parts.filter((part) => part.unreconciled).map((part) => part.nodeId),
|
|
89
|
+
foreign,
|
|
90
|
+
duplicated,
|
|
91
|
+
};
|
|
92
|
+
};
|
|
93
|
+
//# sourceMappingURL=reach.js.map
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What *on screen* means, as the two numbers that decide it.
|
|
3
|
+
*
|
|
4
|
+
* `viewed` and `dwelled` are the two kinds a browser produces by watching, and
|
|
5
|
+
* what they are watching for is one rule: enough of an element is showing that a
|
|
6
|
+
* reader could be reading it. The rule is applied in `broadcast.ts`, where the
|
|
7
|
+
* intersection observer is; the numbers are here because they are the whole of
|
|
8
|
+
* what those two kinds **mean**, and a page that explains either of them should
|
|
9
|
+
* be able to say so without typing a number beside the noun it counts.
|
|
10
|
+
*
|
|
11
|
+
* They are published for that reason and no other. Nothing configures them: a
|
|
12
|
+
* deployment that could set its own would have counters whose meaning differed
|
|
13
|
+
* from every other deployment's while the column names stayed the same, and
|
|
14
|
+
* changing them at all changes what every counter already stored meant when it
|
|
15
|
+
* was written. They are a documented promise rather than a threshold to tune.
|
|
16
|
+
*
|
|
17
|
+
* **Deliberately not in the broadcaster's own module.** A name that a browser
|
|
18
|
+
* entry point exports survives minification, and two exported names cost every
|
|
19
|
+
* reader of every page about 77 bytes to serve a sentence on a documentation
|
|
20
|
+
* site. Imported into `broadcast.ts` and re-exported from `@jam-overture/loom/signals`
|
|
21
|
+
* instead, the browser pays for the two numbers and not for what they are
|
|
22
|
+
* called (rule 4 of `docs/signals.md`).
|
|
23
|
+
*/
|
|
24
|
+
/** At least this much of the element is visible. */
|
|
25
|
+
export declare const READABLE_VISIBLE_FRACTION = 0.5;
|
|
26
|
+
/**
|
|
27
|
+
* Or the element fills at least this much of the window.
|
|
28
|
+
*
|
|
29
|
+
* Not optional and not a softening: the visible fraction of an element taller
|
|
30
|
+
* than the window can never reach {@link READABLE_VISIBLE_FRACTION}, so a long
|
|
31
|
+
* section judged by that clause alone would never be viewed at all.
|
|
32
|
+
*/
|
|
33
|
+
export declare const READABLE_VIEWPORT_FRACTION = 0.3;
|
|
34
|
+
//# sourceMappingURL=readable.d.ts.map
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What *on screen* means, as the two numbers that decide it.
|
|
3
|
+
*
|
|
4
|
+
* `viewed` and `dwelled` are the two kinds a browser produces by watching, and
|
|
5
|
+
* what they are watching for is one rule: enough of an element is showing that a
|
|
6
|
+
* reader could be reading it. The rule is applied in `broadcast.ts`, where the
|
|
7
|
+
* intersection observer is; the numbers are here because they are the whole of
|
|
8
|
+
* what those two kinds **mean**, and a page that explains either of them should
|
|
9
|
+
* be able to say so without typing a number beside the noun it counts.
|
|
10
|
+
*
|
|
11
|
+
* They are published for that reason and no other. Nothing configures them: a
|
|
12
|
+
* deployment that could set its own would have counters whose meaning differed
|
|
13
|
+
* from every other deployment's while the column names stayed the same, and
|
|
14
|
+
* changing them at all changes what every counter already stored meant when it
|
|
15
|
+
* was written. They are a documented promise rather than a threshold to tune.
|
|
16
|
+
*
|
|
17
|
+
* **Deliberately not in the broadcaster's own module.** A name that a browser
|
|
18
|
+
* entry point exports survives minification, and two exported names cost every
|
|
19
|
+
* reader of every page about 77 bytes to serve a sentence on a documentation
|
|
20
|
+
* site. Imported into `broadcast.ts` and re-exported from `@jam-overture/loom/signals`
|
|
21
|
+
* instead, the browser pays for the two numbers and not for what they are
|
|
22
|
+
* called (rule 4 of `docs/signals.md`).
|
|
23
|
+
*/
|
|
24
|
+
/** At least this much of the element is visible. */
|
|
25
|
+
export const READABLE_VISIBLE_FRACTION = 0.5;
|
|
26
|
+
/**
|
|
27
|
+
* Or the element fills at least this much of the window.
|
|
28
|
+
*
|
|
29
|
+
* Not optional and not a softening: the visible fraction of an element taller
|
|
30
|
+
* than the window can never reach {@link READABLE_VISIBLE_FRACTION}, so a long
|
|
31
|
+
* section judged by that clause alone would never be viewed at all.
|
|
32
|
+
*/
|
|
33
|
+
export const READABLE_VIEWPORT_FRACTION = 0.3;
|
|
34
|
+
//# sourceMappingURL=readable.js.map
|