@jam-overture/loom 0.1.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/LICENSE +21 -0
- package/README.md +743 -0
- package/dist/catalogue.d.ts +70 -0
- package/dist/catalogue.js +88 -0
- package/dist/cli/args.d.ts +17 -0
- package/dist/cli/args.js +83 -0
- package/dist/cli/filesystem.d.ts +15 -0
- package/dist/cli/filesystem.js +31 -0
- package/dist/cli/index.d.ts +12 -0
- package/dist/cli/index.js +12 -0
- package/dist/cli/main.d.ts +3 -0
- package/dist/cli/main.js +30 -0
- package/dist/cli/namespace.d.ts +40 -0
- package/dist/cli/namespace.js +40 -0
- package/dist/cli/plan.d.ts +84 -0
- package/dist/cli/plan.js +113 -0
- package/dist/cli/run.d.ts +17 -0
- package/dist/cli/run.js +75 -0
- package/dist/cli/templates.d.ts +43 -0
- package/dist/cli/templates.js +134 -0
- package/dist/closed-set.d.ts +34 -0
- package/dist/closed-set.js +34 -0
- package/dist/data/adapter.d.ts +123 -0
- package/dist/data/adapter.js +91 -0
- package/dist/data/binding.d.ts +48 -0
- package/dist/data/binding.js +39 -0
- package/dist/data/catalogue.d.ts +26 -0
- package/dist/data/catalogue.js +6 -0
- package/dist/data/index.d.ts +14 -0
- package/dist/data/index.js +14 -0
- package/dist/data/plan.d.ts +58 -0
- package/dist/data/plan.js +0 -0
- package/dist/data/resolution.d.ts +91 -0
- package/dist/data/resolution.js +96 -0
- package/dist/data/resolve.d.ts +46 -0
- package/dist/data/resolve.js +37 -0
- package/dist/data/source.d.ts +40 -0
- package/dist/data/source.js +45 -0
- package/dist/deadline.d.ts +57 -0
- package/dist/deadline.js +78 -0
- package/dist/frame/catalogue.d.ts +24 -0
- package/dist/frame/catalogue.js +5 -0
- package/dist/frame/index.d.ts +12 -0
- package/dist/frame/index.js +12 -0
- package/dist/frame/origin.d.ts +87 -0
- package/dist/frame/origin.js +114 -0
- package/dist/frame/resolution.d.ts +85 -0
- package/dist/frame/resolution.js +79 -0
- package/dist/grammar.d.ts +26 -0
- package/dist/grammar.js +28 -0
- package/dist/ids.d.ts +57 -0
- package/dist/ids.js +104 -0
- package/dist/index.d.ts +26 -0
- package/dist/index.js +26 -0
- package/dist/interactivity.d.ts +50 -0
- package/dist/interactivity.js +22 -0
- package/dist/interpretation/anthropic.d.ts +22 -0
- package/dist/interpretation/anthropic.js +76 -0
- package/dist/interpretation/client.d.ts +83 -0
- package/dist/interpretation/client.js +2 -0
- package/dist/interpretation/draft.d.ts +234 -0
- package/dist/interpretation/draft.js +84 -0
- package/dist/interpretation/index.d.ts +15 -0
- package/dist/interpretation/index.js +15 -0
- package/dist/interpretation/interpreter.d.ts +62 -0
- package/dist/interpretation/interpreter.js +151 -0
- package/dist/interpretation/materialize.d.ts +42 -0
- package/dist/interpretation/materialize.js +107 -0
- package/dist/interpretation/prompt.d.ts +229 -0
- package/dist/interpretation/prompt.js +285 -0
- package/dist/interpretation/render.d.ts +76 -0
- package/dist/interpretation/render.js +272 -0
- package/dist/interpretation/schema.d.ts +49 -0
- package/dist/interpretation/schema.js +131 -0
- package/dist/json.d.ts +35 -0
- package/dist/json.js +11 -0
- package/dist/paging.d.ts +60 -0
- package/dist/paging.js +49 -0
- package/dist/primitive-type.d.ts +32 -0
- package/dist/primitive-type.js +39 -0
- package/dist/render/addressing.d.ts +59 -0
- package/dist/render/addressing.js +60 -0
- package/dist/render/anchor.d.ts +105 -0
- package/dist/render/anchor.js +84 -0
- package/dist/render/behaviour-adjust.d.ts +62 -0
- package/dist/render/behaviour-adjust.js +78 -0
- package/dist/render/behaviour-copy.d.ts +53 -0
- package/dist/render/behaviour-copy.js +75 -0
- package/dist/render/behaviour-disclose.d.ts +74 -0
- package/dist/render/behaviour-disclose.js +77 -0
- package/dist/render/behaviour-present.d.ts +123 -0
- package/dist/render/behaviour-present.js +173 -0
- package/dist/render/behaviour.d.ts +243 -0
- package/dist/render/behaviour.js +284 -0
- package/dist/render/control.d.ts +81 -0
- package/dist/render/control.js +80 -0
- package/dist/render/decorative.d.ts +62 -0
- package/dist/render/decorative.js +2 -0
- package/dist/render/diagnostics.d.ts +260 -0
- package/dist/render/diagnostics.js +61 -0
- package/dist/render/disclosed.d.ts +37 -0
- package/dist/render/disclosed.js +37 -0
- package/dist/render/editable.d.ts +34 -0
- package/dist/render/editable.js +35 -0
- package/dist/render/frame.d.ts +42 -0
- package/dist/render/frame.js +31 -0
- package/dist/render/index.d.ts +35 -0
- package/dist/render/index.js +35 -0
- package/dist/render/inline-variables.d.ts +77 -0
- package/dist/render/inline-variables.js +220 -0
- package/dist/render/presented.d.ts +82 -0
- package/dist/render/presented.js +82 -0
- package/dist/render/primitive.d.ts +228 -0
- package/dist/render/primitive.js +36 -0
- package/dist/render/props.d.ts +48 -0
- package/dist/render/props.js +2 -0
- package/dist/render/reads.d.ts +73 -0
- package/dist/render/reads.js +45 -0
- package/dist/render/render.d.ts +164 -0
- package/dist/render/render.js +571 -0
- package/dist/render/request.d.ts +111 -0
- package/dist/render/request.js +60 -0
- package/dist/render/text.d.ts +91 -0
- package/dist/render/text.js +44 -0
- package/dist/render/theme.d.ts +61 -0
- package/dist/render/theme.js +52 -0
- package/dist/reserved-props.d.ts +35 -0
- package/dist/reserved-props.js +45 -0
- package/dist/result.d.ts +27 -0
- package/dist/result.js +30 -0
- package/dist/role.d.ts +71 -0
- package/dist/role.js +22 -0
- package/dist/runtime/analysis.d.ts +149 -0
- package/dist/runtime/analysis.js +187 -0
- package/dist/runtime/assessment.d.ts +35 -0
- package/dist/runtime/assessment.js +13 -0
- package/dist/runtime/disposition.d.ts +102 -0
- package/dist/runtime/disposition.js +59 -0
- package/dist/runtime/events.d.ts +187 -0
- package/dist/runtime/events.js +7 -0
- package/dist/runtime/gate.d.ts +43 -0
- package/dist/runtime/gate.js +169 -0
- package/dist/runtime/index.d.ts +27 -0
- package/dist/runtime/index.js +27 -0
- package/dist/runtime/intent.d.ts +60 -0
- package/dist/runtime/intent.js +36 -0
- package/dist/runtime/interpreter.d.ts +117 -0
- package/dist/runtime/interpreter.js +46 -0
- package/dist/runtime/inverse-interpreter.d.ts +90 -0
- package/dist/runtime/inverse-interpreter.js +56 -0
- package/dist/runtime/inverse.d.ts +87 -0
- package/dist/runtime/inverse.js +48 -0
- package/dist/runtime/narration.d.ts +24 -0
- package/dist/runtime/narration.js +36 -0
- package/dist/runtime/nesting.d.ts +31 -0
- package/dist/runtime/nesting.js +46 -0
- package/dist/runtime/pipeline.d.ts +124 -0
- package/dist/runtime/pipeline.js +178 -0
- package/dist/runtime/policy-fingerprint.d.ts +29 -0
- package/dist/runtime/policy-fingerprint.js +119 -0
- package/dist/runtime/policy-source.d.ts +42 -0
- package/dist/runtime/policy-source.js +8 -0
- package/dist/runtime/policy.d.ts +156 -0
- package/dist/runtime/policy.js +107 -0
- package/dist/runtime/proposal.d.ts +423 -0
- package/dist/runtime/proposal.js +109 -0
- package/dist/runtime/redirection.d.ts +53 -0
- package/dist/runtime/redirection.js +38 -0
- package/dist/runtime/repointing.d.ts +71 -0
- package/dist/runtime/repointing.js +0 -0
- package/dist/runtime/reversibility.d.ts +36 -0
- package/dist/runtime/reversibility.js +39 -0
- package/dist/runtime/stake-level.d.ts +33 -0
- package/dist/runtime/stake-level.js +58 -0
- package/dist/runtime/stakes.d.ts +47 -0
- package/dist/runtime/stakes.js +305 -0
- package/dist/runtime/vocabulary.d.ts +122 -0
- package/dist/runtime/vocabulary.js +87 -0
- package/dist/sdk/audit.d.ts +195 -0
- package/dist/sdk/audit.js +128 -0
- package/dist/sdk/catalogue.d.ts +37 -0
- package/dist/sdk/catalogue.js +16 -0
- package/dist/sdk/conformance.d.ts +342 -0
- package/dist/sdk/conformance.js +494 -0
- package/dist/sdk/copy.d.ts +105 -0
- package/dist/sdk/copy.js +90 -0
- package/dist/sdk/definition.d.ts +242 -0
- package/dist/sdk/definition.js +64 -0
- package/dist/sdk/index.d.ts +19 -0
- package/dist/sdk/index.js +19 -0
- package/dist/sdk/interactivity.d.ts +29 -0
- package/dist/sdk/interactivity.js +34 -0
- package/dist/sdk/pairings.d.ts +124 -0
- package/dist/sdk/pairings.js +81 -0
- package/dist/sdk/registry.d.ts +162 -0
- package/dist/sdk/registry.js +329 -0
- package/dist/sdk/selection.d.ts +46 -0
- package/dist/sdk/selection.js +24 -0
- package/dist/sdk/text.d.ts +100 -0
- package/dist/sdk/text.js +105 -0
- package/dist/sdk/vocabulary.d.ts +39 -0
- package/dist/sdk/vocabulary.js +36 -0
- package/dist/signals/broadcast.d.ts +134 -0
- package/dist/signals/broadcast.js +451 -0
- package/dist/signals/collect.d.ts +184 -0
- package/dist/signals/collect.js +196 -0
- package/dist/signals/deliver.d.ts +64 -0
- package/dist/signals/deliver.js +85 -0
- package/dist/signals/fold.d.ts +112 -0
- package/dist/signals/fold.js +76 -0
- package/dist/signals/index.d.ts +31 -0
- package/dist/signals/index.js +31 -0
- package/dist/signals/ingest.d.ts +51 -0
- package/dist/signals/ingest.js +70 -0
- package/dist/signals/intake.d.ts +149 -0
- package/dist/signals/intake.js +154 -0
- package/dist/signals/journal.d.ts +94 -0
- package/dist/signals/journal.js +11 -0
- package/dist/signals/kinds.d.ts +22 -0
- package/dist/signals/kinds.js +22 -0
- package/dist/signals/ledger.d.ts +46 -0
- package/dist/signals/ledger.js +81 -0
- package/dist/signals/memory.d.ts +17 -0
- package/dist/signals/memory.js +99 -0
- package/dist/signals/migrate.d.ts +27 -0
- package/dist/signals/migrate.js +78 -0
- package/dist/signals/postgres.d.ts +7 -0
- package/dist/signals/postgres.js +295 -0
- package/dist/signals/rollup.d.ts +142 -0
- package/dist/signals/rollup.js +0 -0
- package/dist/signals/schema.d.ts +534 -0
- package/dist/signals/schema.js +92 -0
- package/dist/signals/signal.d.ts +381 -0
- package/dist/signals/signal.js +150 -0
- package/dist/signals/tally.d.ts +70 -0
- package/dist/signals/tally.js +2 -0
- package/dist/signals/view.d.ts +51 -0
- package/dist/signals/view.js +54 -0
- package/dist/store/attribution.d.ts +125 -0
- package/dist/store/attribution.js +116 -0
- package/dist/store/database.d.ts +14 -0
- package/dist/store/database.js +2 -0
- package/dist/store/driver.d.ts +29 -0
- package/dist/store/driver.js +39 -0
- package/dist/store/errors.d.ts +56 -0
- package/dist/store/errors.js +37 -0
- package/dist/store/index.d.ts +16 -0
- package/dist/store/index.js +16 -0
- package/dist/store/memory.d.ts +3 -0
- package/dist/store/memory.js +115 -0
- package/dist/store/migrate.d.ts +54 -0
- package/dist/store/migrate.js +122 -0
- package/dist/store/postgres-holds.d.ts +4 -0
- package/dist/store/postgres-holds.js +192 -0
- package/dist/store/postgres.d.ts +8 -0
- package/dist/store/postgres.js +262 -0
- package/dist/store/replay.d.ts +94 -0
- package/dist/store/replay.js +82 -0
- package/dist/store/revert.d.ts +116 -0
- package/dist/store/revert.js +243 -0
- package/dist/store/schema.d.ts +371 -0
- package/dist/store/schema.js +78 -0
- package/dist/store/source.d.ts +23 -0
- package/dist/store/source.js +37 -0
- package/dist/store/store.d.ts +231 -0
- package/dist/store/store.js +52 -0
- package/dist/store/undone.d.ts +18 -0
- package/dist/store/undone.js +89 -0
- package/dist/submit/catalogue.d.ts +20 -0
- package/dist/submit/catalogue.js +5 -0
- package/dist/submit/declaration.d.ts +39 -0
- package/dist/submit/declaration.js +30 -0
- package/dist/submit/endpoint.d.ts +131 -0
- package/dist/submit/endpoint.js +160 -0
- package/dist/submit/index.d.ts +13 -0
- package/dist/submit/index.js +13 -0
- package/dist/submit/plan.d.ts +49 -0
- package/dist/submit/plan.js +47 -0
- package/dist/submit/resolution.d.ts +61 -0
- package/dist/submit/resolution.js +64 -0
- package/dist/submit/resolve.d.ts +45 -0
- package/dist/submit/resolve.js +36 -0
- package/dist/telemetry/calibration.d.ts +132 -0
- package/dist/telemetry/calibration.js +151 -0
- package/dist/telemetry/episode.d.ts +140 -0
- package/dist/telemetry/episode.js +272 -0
- package/dist/telemetry/event.d.ts +2310 -0
- package/dist/telemetry/event.js +405 -0
- package/dist/telemetry/index.d.ts +15 -0
- package/dist/telemetry/index.js +15 -0
- package/dist/telemetry/journal.d.ts +116 -0
- package/dist/telemetry/journal.js +11 -0
- package/dist/telemetry/memory.d.ts +24 -0
- package/dist/telemetry/memory.js +75 -0
- package/dist/telemetry/migrate.d.ts +26 -0
- package/dist/telemetry/migrate.js +40 -0
- package/dist/telemetry/postgres.d.ts +6 -0
- package/dist/telemetry/postgres.js +139 -0
- package/dist/telemetry/retention.d.ts +131 -0
- package/dist/telemetry/retention.js +217 -0
- package/dist/telemetry/schema.d.ts +113 -0
- package/dist/telemetry/schema.js +33 -0
- package/dist/telemetry/sink.d.ts +42 -0
- package/dist/telemetry/sink.js +61 -0
- package/dist/testing/contracts.d.ts +34 -0
- package/dist/testing/contracts.js +34 -0
- package/dist/testing/definitions.d.ts +15 -0
- package/dist/testing/definitions.js +48 -0
- package/dist/testing/doubles.d.ts +94 -0
- package/dist/testing/doubles.js +141 -0
- package/dist/testing/episode-harness.d.ts +49 -0
- package/dist/testing/episode-harness.js +65 -0
- package/dist/testing/filesystem.d.ts +17 -0
- package/dist/testing/filesystem.js +17 -0
- package/dist/testing/fixtures.d.ts +57 -0
- package/dist/testing/fixtures.js +84 -0
- package/dist/testing/hold-contract.d.ts +19 -0
- package/dist/testing/hold-contract.js +374 -0
- package/dist/testing/index.d.ts +41 -0
- package/dist/testing/index.js +41 -0
- package/dist/testing/journal-contract.d.ts +17 -0
- package/dist/testing/journal-contract.js +353 -0
- package/dist/testing/model-replies.d.ts +34 -0
- package/dist/testing/model-replies.js +101 -0
- package/dist/testing/primitives.d.ts +7 -0
- package/dist/testing/primitives.js +29 -0
- package/dist/testing/reader-signal-contract.d.ts +38 -0
- package/dist/testing/reader-signal-contract.js +318 -0
- package/dist/testing/row-security.d.ts +17 -0
- package/dist/testing/row-security.js +21 -0
- package/dist/testing/store-contract.d.ts +25 -0
- package/dist/testing/store-contract.js +500 -0
- package/dist/theme/apply.d.ts +17 -0
- package/dist/theme/apply.js +60 -0
- package/dist/theme/contrast.d.ts +197 -0
- package/dist/theme/contrast.js +259 -0
- package/dist/theme/derive.d.ts +77 -0
- package/dist/theme/derive.js +167 -0
- package/dist/theme/faces.d.ts +73 -0
- package/dist/theme/faces.js +119 -0
- package/dist/theme/font-packs.d.ts +25 -0
- package/dist/theme/font-packs.js +257 -0
- package/dist/theme/index.d.ts +20 -0
- package/dist/theme/index.js +20 -0
- package/dist/theme/lab.d.ts +30 -0
- package/dist/theme/lab.js +46 -0
- package/dist/theme/library.d.ts +114 -0
- package/dist/theme/library.js +300 -0
- package/dist/theme/measure.d.ts +144 -0
- package/dist/theme/measure.js +145 -0
- package/dist/theme/palettes.d.ts +64 -0
- package/dist/theme/palettes.js +497 -0
- package/dist/theme/registry.d.ts +59 -0
- package/dist/theme/registry.js +60 -0
- package/dist/theme/separation.d.ts +177 -0
- package/dist/theme/separation.js +203 -0
- package/dist/theme/style-presets.d.ts +60 -0
- package/dist/theme/style-presets.js +124 -0
- package/dist/theme/theme.d.ts +253 -0
- package/dist/theme/theme.js +171 -0
- package/dist/tree/apply.d.ts +16 -0
- package/dist/tree/apply.js +104 -0
- package/dist/tree/builders.d.ts +19 -0
- package/dist/tree/builders.js +20 -0
- package/dist/tree/compare.d.ts +68 -0
- package/dist/tree/compare.js +75 -0
- package/dist/tree/configuration.d.ts +25 -0
- package/dist/tree/configuration.js +108 -0
- package/dist/tree/delta.d.ts +288 -0
- package/dist/tree/delta.js +88 -0
- package/dist/tree/errors.d.ts +69 -0
- package/dist/tree/errors.js +34 -0
- package/dist/tree/identity.d.ts +117 -0
- package/dist/tree/identity.js +145 -0
- package/dist/tree/index.d.ts +21 -0
- package/dist/tree/index.js +21 -0
- package/dist/tree/inverse.d.ts +24 -0
- package/dist/tree/inverse.js +112 -0
- package/dist/tree/mutation.d.ts +18 -0
- package/dist/tree/mutation.js +49 -0
- package/dist/tree/naming.d.ts +4 -0
- package/dist/tree/naming.js +35 -0
- package/dist/tree/navigation.d.ts +38 -0
- package/dist/tree/navigation.js +83 -0
- package/dist/tree/node.d.ts +103 -0
- package/dist/tree/node.js +46 -0
- package/dist/tree/outline.d.ts +28 -0
- package/dist/tree/outline.js +10 -0
- package/dist/tree/tree.d.ts +83 -0
- package/dist/tree/tree.js +62 -0
- package/dist/write/commit.d.ts +124 -0
- package/dist/write/commit.js +234 -0
- package/dist/write/held.d.ts +674 -0
- package/dist/write/held.js +185 -0
- package/dist/write/index.d.ts +11 -0
- package/dist/write/index.js +11 -0
- package/dist/write/liveness.d.ts +132 -0
- package/dist/write/liveness.js +91 -0
- package/dist/write/revert.d.ts +79 -0
- package/dist/write/revert.js +134 -0
- package/package.json +160 -0
|
@@ -0,0 +1,196 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { clampLimit } from "../paging.js";
|
|
3
|
+
import { systemClock } from "../runtime/events.js";
|
|
4
|
+
import { rollUp } from "./rollup.js";
|
|
5
|
+
/**
|
|
6
|
+
* The one operation that empties the buffer.
|
|
7
|
+
*
|
|
8
|
+
* `journal.ts` can hold batches, `rollup.ts` can fold them and `tally.ts` can
|
|
9
|
+
* keep what the fold produced — and until this module existed nothing joined
|
|
10
|
+
* the three, so a deployment with signals switched on accumulated the largest
|
|
11
|
+
* table it owns and counted none of it.
|
|
12
|
+
*
|
|
13
|
+
* **Counting and forgetting are one call, and that is the design rather than a
|
|
14
|
+
* convenience.** A rollup reports *what this window added* (0147), so a batch
|
|
15
|
+
* counted twice is counted twice forever: there is no idempotence to fall back
|
|
16
|
+
* on and no way to notice afterwards, because the wrong number looks exactly
|
|
17
|
+
* like a busy afternoon. The only defence that does not need durable bookkeeping
|
|
18
|
+
* is for the set of batches rolled up and the set forgotten to be the same set,
|
|
19
|
+
* decided once, in one place. That is this file, and it is why there is no
|
|
20
|
+
* exported `applyReaderSignalRetention` beside it — a function that can forget
|
|
21
|
+
* without counting is the data-loss bug, and one that can count without
|
|
22
|
+
* forgetting is the double-count bug.
|
|
23
|
+
*
|
|
24
|
+
* Nothing schedules it, for the reason nothing schedules telemetry's retention
|
|
25
|
+
* or `auditSnapshot`: when a deployment forgets is an operational choice, and a
|
|
26
|
+
* framework that quietly deleted a host's data on a timer it chose would be
|
|
27
|
+
* making it. A host calls this from a cron route, a deploy hook, or by hand.
|
|
28
|
+
*
|
|
29
|
+
* **One run at a time, and the caller is what makes that true.** Two runs over
|
|
30
|
+
* the same ripe prefix both roll it up and both apply; applying is additive
|
|
31
|
+
* (0147), so the counters double and the buffer empties once, leaving nothing
|
|
32
|
+
* behind that could say what happened. Nothing here can prevent it — a journal
|
|
33
|
+
* and a store are two handles with no shared transaction between them — so
|
|
34
|
+
* serialising belongs to whatever schedules this. `apps/loom/scripts/
|
|
35
|
+
* signals-collect.ts` does it with a Postgres advisory lock, which is the
|
|
36
|
+
* cheapest thing that works for a cron that overruns its own interval.
|
|
37
|
+
*/
|
|
38
|
+
/**
|
|
39
|
+
* The window is the age a batch reaches before it is counted and dropped, and
|
|
40
|
+
* it is two arguments pulling opposite ways.
|
|
41
|
+
*
|
|
42
|
+
* **Longer is more accurate.** `views` and `reached` count distinct page views,
|
|
43
|
+
* distinctness does not add up, and a page view whose batches straddle two
|
|
44
|
+
* windows is counted in both — the over-count 0147 accepts. `tally.ts` already
|
|
45
|
+
* states the remedy in its own words: *a deployment that wants the bound small
|
|
46
|
+
* makes the rollup window long relative to a page view.* This is that number.
|
|
47
|
+
*
|
|
48
|
+
* **Shorter is more anonymous.** The raw window is the entire mechanism by
|
|
49
|
+
* which a view key stops existing (0146). The key is opaque, random and
|
|
50
|
+
* correlates nothing outside the buffer, but it correlates that, and the
|
|
51
|
+
* argument for it rests on how briefly it lives.
|
|
52
|
+
*
|
|
53
|
+
* An hour is long against a page view and short against a day, which is why it
|
|
54
|
+
* is the default rather than a constant: rule 5 of `docs/signals.md` makes the
|
|
55
|
+
* number a deployment's.
|
|
56
|
+
*/
|
|
57
|
+
export const DEFAULT_READER_SIGNAL_WINDOW_MS = 60 * 60 * 1000;
|
|
58
|
+
/**
|
|
59
|
+
* A minute, and the floor is not a style choice.
|
|
60
|
+
*
|
|
61
|
+
* Under a minute every page view straddles a boundary, so `views` stops being
|
|
62
|
+
* an approximation and becomes a count of flushes — a number about the network
|
|
63
|
+
* rather than about readers. It also refuses the ordinary way a window is
|
|
64
|
+
* written wrongly, which is a units mistake: `windowMs: 60` reads as an hour
|
|
65
|
+
* and means a minute and a tenth of a second.
|
|
66
|
+
*/
|
|
67
|
+
export const MIN_READER_SIGNAL_WINDOW_MS = 60 * 1000;
|
|
68
|
+
export const readerSignalWindowSchema = z.object({
|
|
69
|
+
windowMs: z.number().int().min(MIN_READER_SIGNAL_WINDOW_MS),
|
|
70
|
+
});
|
|
71
|
+
/**
|
|
72
|
+
* How much of the buffer one run will look at.
|
|
73
|
+
*
|
|
74
|
+
* Incremental for telemetry retention's reason: a first run against a buffer
|
|
75
|
+
* nothing has ever drained does a bounded amount of work and the next run does
|
|
76
|
+
* more, so the operation is safe to schedule without knowing how far behind it
|
|
77
|
+
* is. `more` on the outcome is how a caller learns there was another run's
|
|
78
|
+
* worth waiting.
|
|
79
|
+
*/
|
|
80
|
+
export const DEFAULT_COLLECTION_SCAN = 5_000;
|
|
81
|
+
export const MAX_COLLECTION_SCAN = 50_000;
|
|
82
|
+
/** Read in pages like every other log walk (0026), so memory is bounded by the page. */
|
|
83
|
+
const SCAN_PAGE = 500;
|
|
84
|
+
export const collectionPlanOf = (scanned, horizon) => {
|
|
85
|
+
const ceiling = scanned.findIndex((batch) => batch.receivedAt >= horizon);
|
|
86
|
+
const ripe = ceiling === -1 ? scanned : scanned.slice(0, ceiling);
|
|
87
|
+
const last = ripe.at(-1);
|
|
88
|
+
return {
|
|
89
|
+
ripe,
|
|
90
|
+
before: last === undefined ? null : last.seq + 1,
|
|
91
|
+
waiting: scanned.length - ripe.length,
|
|
92
|
+
};
|
|
93
|
+
};
|
|
94
|
+
export const horizonOf = (configured, now) => {
|
|
95
|
+
const instant = Date.parse(now);
|
|
96
|
+
return Number.isFinite(instant) ? new Date(instant - configured.windowMs).toISOString() : null;
|
|
97
|
+
};
|
|
98
|
+
/**
|
|
99
|
+
* The oldest end of the buffer, forward, stopping at the horizon.
|
|
100
|
+
*
|
|
101
|
+
* Every batch from the horizon on is too young to count, and `collectionPlanOf`
|
|
102
|
+
* needs only the first of them to know where the ripe prefix ends — so reading
|
|
103
|
+
* further would be reading the busiest part of the table to throw it away.
|
|
104
|
+
*/
|
|
105
|
+
const scanFrom = async (journal, horizon, scanLimit) => {
|
|
106
|
+
const collected = [];
|
|
107
|
+
let cursor;
|
|
108
|
+
while (collected.length < scanLimit) {
|
|
109
|
+
const page = await journal.read({
|
|
110
|
+
direction: "newer",
|
|
111
|
+
limit: Math.min(SCAN_PAGE, scanLimit - collected.length),
|
|
112
|
+
...(cursor ? { cursor } : {}),
|
|
113
|
+
});
|
|
114
|
+
if (!page.ok)
|
|
115
|
+
return { ok: false, error: page.error };
|
|
116
|
+
collected.push(...page.value.batches);
|
|
117
|
+
if (page.value.batches.some((batch) => batch.receivedAt >= horizon)) {
|
|
118
|
+
return { ok: true, batches: collected, full: false };
|
|
119
|
+
}
|
|
120
|
+
if (page.value.newer === null)
|
|
121
|
+
return { ok: true, batches: collected, full: false };
|
|
122
|
+
cursor = page.value.newer;
|
|
123
|
+
}
|
|
124
|
+
return { ok: true, batches: collected, full: true };
|
|
125
|
+
};
|
|
126
|
+
/**
|
|
127
|
+
* Count a window of the buffer into the durable counters, then drop it.
|
|
128
|
+
*
|
|
129
|
+
* The order is the safe one and the reverse is a data-loss bug that looks like
|
|
130
|
+
* a feature working: aggregates first, the buffer second. What that leaves is
|
|
131
|
+
* `counted-not-forgotten`, which is visible and recoverable — the opposite
|
|
132
|
+
* order's failure is neither.
|
|
133
|
+
*/
|
|
134
|
+
export const collectReaderSignals = async (journal, store, request = {}) => {
|
|
135
|
+
/** Named for what it is rather than `window`, which is a global this package's sibling touches. */
|
|
136
|
+
const configured = readerSignalWindowSchema.safeParse({
|
|
137
|
+
windowMs: request.windowMs ?? DEFAULT_READER_SIGNAL_WINDOW_MS,
|
|
138
|
+
});
|
|
139
|
+
if (!configured.success) {
|
|
140
|
+
return { outcome: "refused", reason: configured.error.issues[0]?.message ?? "invalid window" };
|
|
141
|
+
}
|
|
142
|
+
const now = (request.clock ?? systemClock).now();
|
|
143
|
+
const horizon = horizonOf(configured.data, now);
|
|
144
|
+
if (horizon === null)
|
|
145
|
+
return { outcome: "refused", reason: `the clock read "${now}"` };
|
|
146
|
+
const scanned = await scanFrom(journal, horizon, clampLimit(request.scanLimit, { fallback: DEFAULT_COLLECTION_SCAN, max: MAX_COLLECTION_SCAN }));
|
|
147
|
+
if (!scanned.ok)
|
|
148
|
+
return { outcome: "unavailable", error: scanned.error };
|
|
149
|
+
const plan = collectionPlanOf(scanned.batches, horizon);
|
|
150
|
+
if (plan.before === null)
|
|
151
|
+
return { outcome: "nothing-ripe", waiting: plan.waiting };
|
|
152
|
+
const rollup = rollUp(plan.ripe, { ...(request.pairs ? { pairs: request.pairs } : {}) });
|
|
153
|
+
const summary = {
|
|
154
|
+
counted: plan.ripe.length,
|
|
155
|
+
tallies: rollup.tallies.length,
|
|
156
|
+
funnels: rollup.funnels.length,
|
|
157
|
+
views: rollup.views,
|
|
158
|
+
uncorrelated: rollup.uncorrelated,
|
|
159
|
+
};
|
|
160
|
+
const applied = await store.apply(rollup, now);
|
|
161
|
+
if (!applied.ok)
|
|
162
|
+
return { outcome: "unavailable", error: applied.error };
|
|
163
|
+
const forgotten = await journal.forget({ before: plan.before });
|
|
164
|
+
if (!forgotten.ok) {
|
|
165
|
+
return {
|
|
166
|
+
outcome: "counted-not-forgotten",
|
|
167
|
+
summary,
|
|
168
|
+
before: plan.before,
|
|
169
|
+
error: forgotten.error,
|
|
170
|
+
};
|
|
171
|
+
}
|
|
172
|
+
return {
|
|
173
|
+
outcome: "collected",
|
|
174
|
+
summary,
|
|
175
|
+
removed: forgotten.value.removed,
|
|
176
|
+
more: scanned.full,
|
|
177
|
+
};
|
|
178
|
+
};
|
|
179
|
+
const batches = (count) => `${count} ${count === 1 ? "batch" : "batches"}`;
|
|
180
|
+
const uncorrelated = (summary) => summary.uncorrelated === 0 ? "" : `, ${summary.uncorrelated} with no view key`;
|
|
181
|
+
/** One line for an operator, because an outcome nobody can read is one nobody acts on. */
|
|
182
|
+
export const describeCollection = (outcome) => {
|
|
183
|
+
switch (outcome.outcome) {
|
|
184
|
+
case "collected":
|
|
185
|
+
return `counted ${batches(outcome.summary.counted)} into ${outcome.summary.tallies} ${outcome.summary.tallies === 1 ? "tally" : "tallies"} over ${outcome.summary.views} ${outcome.summary.views === 1 ? "view" : "views"}${uncorrelated(outcome.summary)}, and forgot ${outcome.removed}${outcome.more ? " — more is waiting" : ""}`;
|
|
186
|
+
case "nothing-ripe":
|
|
187
|
+
return `nothing old enough to count${outcome.waiting === 0 ? "" : `, ${batches(outcome.waiting)} waiting`}`;
|
|
188
|
+
case "counted-not-forgotten":
|
|
189
|
+
return `counted ${batches(outcome.summary.counted)} and could not forget them, so the next run counts them again unless the buffer is pruned below ${outcome.before}: ${outcome.error.detail}`;
|
|
190
|
+
case "refused":
|
|
191
|
+
return `collection refused: ${outcome.reason}`;
|
|
192
|
+
case "unavailable":
|
|
193
|
+
return `collection could not run: ${outcome.error.detail}`;
|
|
194
|
+
}
|
|
195
|
+
};
|
|
196
|
+
//# sourceMappingURL=collect.js.map
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
import type { ReaderSignalBatch } from "./signal.js";
|
|
2
|
+
/**
|
|
3
|
+
* Getting a batch off the page.
|
|
4
|
+
*
|
|
5
|
+
* `broadcastReaderSignals` takes a `send` and does not care what it does, which
|
|
6
|
+
* is right — a sink observes and does not get a vote (0042), and a broadcaster
|
|
7
|
+
* that knew about URLs would be a broadcaster a test had to stub a network for.
|
|
8
|
+
* What that leaves is every host writing the same fifteen lines, and the two
|
|
9
|
+
* that exist in this repository are both written for a page that draws the
|
|
10
|
+
* batch rather than posts it. This is the `send` for the ordinary case.
|
|
11
|
+
*
|
|
12
|
+
* **It imports nothing at runtime.** The batch arrives as a type, which is
|
|
13
|
+
* erased, so this module costs a browser bundle its own bytes and no schema —
|
|
14
|
+
* the same property `view.ts` has and for the same reason (0136).
|
|
15
|
+
*
|
|
16
|
+
* **`sendBeacon` first, `fetch` second, and neither ever throws.** A beacon
|
|
17
|
+
* survives the page being closed, which is exactly when the last batch of a
|
|
18
|
+
* page view is sent and exactly when a `fetch` is cancelled. It can also refuse
|
|
19
|
+
* — the browser caps what it will hold in flight — and a refusal is reported by
|
|
20
|
+
* a `false` return rather than an exception, which is easy to write past. When
|
|
21
|
+
* it refuses, the batch is worth one `fetch` with `keepalive`, which is the
|
|
22
|
+
* same guarantee by another road.
|
|
23
|
+
*/
|
|
24
|
+
/**
|
|
25
|
+
* Where a delivery goes when the host has no opinion.
|
|
26
|
+
*
|
|
27
|
+
* A path rather than a URL, and relative, so it is same-origin by construction.
|
|
28
|
+
* That is not only tidiness: `sendBeacon` cannot preflight, so a cross-origin
|
|
29
|
+
* beacon carrying `application/json` is refused by the browser before it is
|
|
30
|
+
* sent. A deployment that wants to collect signals on another origin has to
|
|
31
|
+
* serve CORS from it and will find out here.
|
|
32
|
+
*
|
|
33
|
+
* It is a default and not a constant the receiver shares. The endpoint's
|
|
34
|
+
* address is a deployment's choice — a host may serve it anywhere, and this is
|
|
35
|
+
* what the host who does not care gets.
|
|
36
|
+
*/
|
|
37
|
+
export declare const DEFAULT_READER_SIGNAL_PATH = "/api/reader-signals";
|
|
38
|
+
/** `navigator.sendBeacon`, narrowed to what this uses. `false` means it would not take it. */
|
|
39
|
+
export type SendBeacon = (url: string, body: Blob) => boolean;
|
|
40
|
+
/** The fallback. Called only when a beacon was unavailable or refused the batch. */
|
|
41
|
+
export type PostBatch = (url: string, body: string) => void;
|
|
42
|
+
export type DeliverOptions = {
|
|
43
|
+
/** Where to post. {@link DEFAULT_READER_SIGNAL_PATH} when absent. */
|
|
44
|
+
readonly url?: string;
|
|
45
|
+
/** The browser's, when absent. A test passes its own. */
|
|
46
|
+
readonly beacon?: SendBeacon | null;
|
|
47
|
+
/** `fetch` with `keepalive`, when absent. */
|
|
48
|
+
readonly post?: PostBatch;
|
|
49
|
+
};
|
|
50
|
+
/**
|
|
51
|
+
* A `send` for `broadcastReaderSignals` that posts each batch.
|
|
52
|
+
*
|
|
53
|
+
* ```ts
|
|
54
|
+
* broadcastReaderSignals(root, { send: deliverReaderSignals() })
|
|
55
|
+
* ```
|
|
56
|
+
*
|
|
57
|
+
* Nothing about the response is read, and nothing about it could be useful: the
|
|
58
|
+
* page has no retry to attempt and no reader to tell. A refused batch is a
|
|
59
|
+
* counter that will not be incremented, which is the correct failure for a
|
|
60
|
+
* sink — the alternative is a page whose behaviour depends on whether anybody
|
|
61
|
+
* is measuring it.
|
|
62
|
+
*/
|
|
63
|
+
export declare const deliverReaderSignals: (options?: DeliverOptions) => ((batch: ReaderSignalBatch) => void);
|
|
64
|
+
//# sourceMappingURL=deliver.d.ts.map
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Getting a batch off the page.
|
|
3
|
+
*
|
|
4
|
+
* `broadcastReaderSignals` takes a `send` and does not care what it does, which
|
|
5
|
+
* is right — a sink observes and does not get a vote (0042), and a broadcaster
|
|
6
|
+
* that knew about URLs would be a broadcaster a test had to stub a network for.
|
|
7
|
+
* What that leaves is every host writing the same fifteen lines, and the two
|
|
8
|
+
* that exist in this repository are both written for a page that draws the
|
|
9
|
+
* batch rather than posts it. This is the `send` for the ordinary case.
|
|
10
|
+
*
|
|
11
|
+
* **It imports nothing at runtime.** The batch arrives as a type, which is
|
|
12
|
+
* erased, so this module costs a browser bundle its own bytes and no schema —
|
|
13
|
+
* the same property `view.ts` has and for the same reason (0136).
|
|
14
|
+
*
|
|
15
|
+
* **`sendBeacon` first, `fetch` second, and neither ever throws.** A beacon
|
|
16
|
+
* survives the page being closed, which is exactly when the last batch of a
|
|
17
|
+
* page view is sent and exactly when a `fetch` is cancelled. It can also refuse
|
|
18
|
+
* — the browser caps what it will hold in flight — and a refusal is reported by
|
|
19
|
+
* a `false` return rather than an exception, which is easy to write past. When
|
|
20
|
+
* it refuses, the batch is worth one `fetch` with `keepalive`, which is the
|
|
21
|
+
* same guarantee by another road.
|
|
22
|
+
*/
|
|
23
|
+
/**
|
|
24
|
+
* Where a delivery goes when the host has no opinion.
|
|
25
|
+
*
|
|
26
|
+
* A path rather than a URL, and relative, so it is same-origin by construction.
|
|
27
|
+
* That is not only tidiness: `sendBeacon` cannot preflight, so a cross-origin
|
|
28
|
+
* beacon carrying `application/json` is refused by the browser before it is
|
|
29
|
+
* sent. A deployment that wants to collect signals on another origin has to
|
|
30
|
+
* serve CORS from it and will find out here.
|
|
31
|
+
*
|
|
32
|
+
* It is a default and not a constant the receiver shares. The endpoint's
|
|
33
|
+
* address is a deployment's choice — a host may serve it anywhere, and this is
|
|
34
|
+
* what the host who does not care gets.
|
|
35
|
+
*/
|
|
36
|
+
export const DEFAULT_READER_SIGNAL_PATH = "/api/reader-signals";
|
|
37
|
+
const browserBeacon = () => {
|
|
38
|
+
const sender = globalThis.navigator;
|
|
39
|
+
return typeof sender?.sendBeacon === "function" ? (url, body) => sender.sendBeacon(url, body) : null;
|
|
40
|
+
};
|
|
41
|
+
/**
|
|
42
|
+
* `keepalive` is what makes this survive the page it was sent from. Rejections
|
|
43
|
+
* are swallowed here rather than left to the broadcaster's containment, so that
|
|
44
|
+
* a host calling this directly gets the same promise the broadcaster does.
|
|
45
|
+
*/
|
|
46
|
+
const fetchPost = (url, body) => {
|
|
47
|
+
void globalThis
|
|
48
|
+
.fetch(url, {
|
|
49
|
+
method: "POST",
|
|
50
|
+
keepalive: true,
|
|
51
|
+
headers: { "content-type": "application/json" },
|
|
52
|
+
body,
|
|
53
|
+
})
|
|
54
|
+
.catch(() => undefined);
|
|
55
|
+
};
|
|
56
|
+
/**
|
|
57
|
+
* A `send` for `broadcastReaderSignals` that posts each batch.
|
|
58
|
+
*
|
|
59
|
+
* ```ts
|
|
60
|
+
* broadcastReaderSignals(root, { send: deliverReaderSignals() })
|
|
61
|
+
* ```
|
|
62
|
+
*
|
|
63
|
+
* Nothing about the response is read, and nothing about it could be useful: the
|
|
64
|
+
* page has no retry to attempt and no reader to tell. A refused batch is a
|
|
65
|
+
* counter that will not be incremented, which is the correct failure for a
|
|
66
|
+
* sink — the alternative is a page whose behaviour depends on whether anybody
|
|
67
|
+
* is measuring it.
|
|
68
|
+
*/
|
|
69
|
+
export const deliverReaderSignals = (options = {}) => {
|
|
70
|
+
const url = options.url ?? DEFAULT_READER_SIGNAL_PATH;
|
|
71
|
+
const post = options.post ?? fetchPost;
|
|
72
|
+
return (batch) => {
|
|
73
|
+
const body = JSON.stringify(batch);
|
|
74
|
+
try {
|
|
75
|
+
const beacon = options.beacon === undefined ? browserBeacon() : options.beacon;
|
|
76
|
+
if (beacon !== null && beacon(url, new Blob([body], { type: "application/json" })))
|
|
77
|
+
return;
|
|
78
|
+
post(url, body);
|
|
79
|
+
}
|
|
80
|
+
catch {
|
|
81
|
+
// A sink does not get a vote (0042).
|
|
82
|
+
}
|
|
83
|
+
};
|
|
84
|
+
};
|
|
85
|
+
//# sourceMappingURL=deliver.js.map
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
import type { NodeId } from "../ids.js";
|
|
2
|
+
import type { PrimitiveType } from "../primitive-type.js";
|
|
3
|
+
import type { ReaderSignalBatch } from "./signal.js";
|
|
4
|
+
/**
|
|
5
|
+
* Batches folded into what a node was read like: time on screen, whether it was
|
|
6
|
+
* reached, what readers did in it.
|
|
7
|
+
*
|
|
8
|
+
* This is the live arithmetic — one accumulator, fed a batch at a time, held by
|
|
9
|
+
* whatever is watching. `rollup.ts` answers the other question, *what happened
|
|
10
|
+
* across many views*, and the two are separate because they have different
|
|
11
|
+
* inputs: a fold sees the batches of one page as they arrive and knows nothing
|
|
12
|
+
* about views, while rollup sees a window of stored batches from many views and
|
|
13
|
+
* cannot be fed one at a time.
|
|
14
|
+
*
|
|
15
|
+
* It exists as a framework module because it had already been written twice —
|
|
16
|
+
* `prototypes/ski-apparel/readings.mjs` is the working reference, and the
|
|
17
|
+
* portal's view and any demo rail would each have grown their own. Arithmetic
|
|
18
|
+
* rendered twice is arithmetic that drifts, and the version that drifts is
|
|
19
|
+
* always the one nobody is looking at.
|
|
20
|
+
*
|
|
21
|
+
* **Labels are not here.** The prototype's fold also turns node ids into
|
|
22
|
+
* section names and builds a feed of lines, using a legend that only that page
|
|
23
|
+
* has. Naming a node is a property of the page, not of the signals, so it stays
|
|
24
|
+
* with whoever has the legend. What is left is the part that is the same
|
|
25
|
+
* everywhere.
|
|
26
|
+
*
|
|
27
|
+
* Pure, and safe in a browser: no package, no schema, no clock.
|
|
28
|
+
*/
|
|
29
|
+
/**
|
|
30
|
+
* What a set of batches says about each node they mention.
|
|
31
|
+
*
|
|
32
|
+
* Keyed by node id rather than held as a list because folding is a hot path in
|
|
33
|
+
* a page that is still being read — a list would be a scan per signal, and the
|
|
34
|
+
* ledger this replaces was quadratic once already.
|
|
35
|
+
*/
|
|
36
|
+
export type ReaderReadings = {
|
|
37
|
+
/** Total time on screen. Summed across batches, because `dwelled` is per-batch. */
|
|
38
|
+
readonly dwellMs: Readonly<Record<NodeId, number>>;
|
|
39
|
+
/** Nodes that came into view at all. `viewed` fires once per node per page view. */
|
|
40
|
+
readonly reached: Readonly<Record<NodeId, true>>;
|
|
41
|
+
/**
|
|
42
|
+
* Times the node itself was used — a link followed, a button pressed, a field
|
|
43
|
+
* filled.
|
|
44
|
+
*
|
|
45
|
+
* It is the node the signal names, which is the nearest addressed element to
|
|
46
|
+
* what a reader aimed at. In the starter library that is the control, so a
|
|
47
|
+
* band's count here is zero however busy the band was; `engagements` is the
|
|
48
|
+
* number that is about the band.
|
|
49
|
+
*/
|
|
50
|
+
readonly activations: Readonly<Record<NodeId, number>>;
|
|
51
|
+
readonly opens: Readonly<Record<NodeId, number>>;
|
|
52
|
+
readonly closes: Readonly<Record<NodeId, number>>;
|
|
53
|
+
/**
|
|
54
|
+
* Times a reader used something *inside* the node — pressed, followed, filled,
|
|
55
|
+
* opened or closed, at any depth.
|
|
56
|
+
*
|
|
57
|
+
* The regions' number. Read off the ancestry a delegated signal carries, so a
|
|
58
|
+
* batch whose senders did not walk contributes nothing rather than a guess.
|
|
59
|
+
* Strictly inside, so a control's own use is in `activations` and never here,
|
|
60
|
+
* and a subtree total is the addition.
|
|
61
|
+
*
|
|
62
|
+
* Occurrences rather than readers, because a fold is one page view: *how many
|
|
63
|
+
* of the people reading this used something in the band* is a question about
|
|
64
|
+
* many views, and it is `ReaderTally.engaged`.
|
|
65
|
+
*/
|
|
66
|
+
readonly engagements: Readonly<Record<NodeId, number>>;
|
|
67
|
+
/**
|
|
68
|
+
* What each node is, as its signals reported it. Kept because a consumer
|
|
69
|
+
* holding only readings would otherwise have to go back to the tree to render
|
|
70
|
+
* a row, and the signals already say.
|
|
71
|
+
*
|
|
72
|
+
* A region named only as somewhere a press happened inside is in here too, so
|
|
73
|
+
* it gets a row rather than being a number with no name.
|
|
74
|
+
*/
|
|
75
|
+
readonly types: Readonly<Record<NodeId, PrimitiveType>>;
|
|
76
|
+
readonly batches: number;
|
|
77
|
+
readonly signals: number;
|
|
78
|
+
};
|
|
79
|
+
export declare const EMPTY_READINGS: ReaderReadings;
|
|
80
|
+
/**
|
|
81
|
+
* One more batch, folded in.
|
|
82
|
+
*
|
|
83
|
+
* The batch's tree and revision are not checked against anything, because a
|
|
84
|
+
* reading is about one page and the caller is the one holding it. Folding two
|
|
85
|
+
* revisions into one accumulator is a caller's mistake and it is the caller who
|
|
86
|
+
* can see it — `rollup.ts` is the module that keeps revisions apart, because it
|
|
87
|
+
* is the one that is handed a mixture.
|
|
88
|
+
*/
|
|
89
|
+
export declare const foldReaderSignals: (readings: ReaderReadings, batch: ReaderSignalBatch) => ReaderReadings;
|
|
90
|
+
export declare const readingsOf: (batches: readonly ReaderSignalBatch[]) => ReaderReadings;
|
|
91
|
+
/** One node's line, as something rendering a table wants it. */
|
|
92
|
+
export type NodeReading = {
|
|
93
|
+
readonly nodeId: NodeId;
|
|
94
|
+
readonly type: PrimitiveType;
|
|
95
|
+
readonly dwellMs: number;
|
|
96
|
+
readonly reached: boolean;
|
|
97
|
+
readonly activations: number;
|
|
98
|
+
readonly opens: number;
|
|
99
|
+
readonly closes: number;
|
|
100
|
+
/** Times a reader used something inside it, at any depth. */
|
|
101
|
+
readonly engagements: number;
|
|
102
|
+
};
|
|
103
|
+
/**
|
|
104
|
+
* Readings as rows, longest on screen first.
|
|
105
|
+
*
|
|
106
|
+
* The order is a default rather than a claim: a caller with a legend almost
|
|
107
|
+
* always wants the page's own order instead, which it can produce because every
|
|
108
|
+
* row names its node. What a caller without one wants is the interesting end
|
|
109
|
+
* first.
|
|
110
|
+
*/
|
|
111
|
+
export declare const nodeReadingsOf: (readings: ReaderReadings) => readonly NodeReading[];
|
|
112
|
+
//# sourceMappingURL=fold.d.ts.map
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
export const EMPTY_READINGS = {
|
|
2
|
+
dwellMs: {},
|
|
3
|
+
reached: {},
|
|
4
|
+
activations: {},
|
|
5
|
+
opens: {},
|
|
6
|
+
closes: {},
|
|
7
|
+
engagements: {},
|
|
8
|
+
types: {},
|
|
9
|
+
batches: 0,
|
|
10
|
+
signals: 0,
|
|
11
|
+
};
|
|
12
|
+
const bumped = (counts, nodeId, by) => ({ ...counts, [nodeId]: (counts[nodeId] ?? 0) + by });
|
|
13
|
+
/**
|
|
14
|
+
* The regions a delegated signal says it happened inside, and their types, which
|
|
15
|
+
* a reading knows exactly as it knows the node's own.
|
|
16
|
+
*/
|
|
17
|
+
const withinOf = (signal) => (signal.kind === "activated" || signal.kind === "disclosed") && signal.within !== undefined
|
|
18
|
+
? signal.within
|
|
19
|
+
: [];
|
|
20
|
+
/** Every node a signal mentions is one this reading now knows the type of. */
|
|
21
|
+
const foldSignal = (readings, signal) => {
|
|
22
|
+
const { nodeId } = signal;
|
|
23
|
+
const within = withinOf(signal);
|
|
24
|
+
return {
|
|
25
|
+
...readings,
|
|
26
|
+
engagements: within.reduce((counts, region) => bumped(counts, region.nodeId, 1), readings.engagements),
|
|
27
|
+
dwellMs: signal.kind === "dwelled" ? bumped(readings.dwellMs, nodeId, signal.ms) : readings.dwellMs,
|
|
28
|
+
reached: signal.kind === "viewed" ? { ...readings.reached, [nodeId]: true } : readings.reached,
|
|
29
|
+
activations: signal.kind === "activated" ? bumped(readings.activations, nodeId, 1) : readings.activations,
|
|
30
|
+
opens: signal.kind === "disclosed" && signal.open ? bumped(readings.opens, nodeId, 1) : readings.opens,
|
|
31
|
+
closes: signal.kind === "disclosed" && !signal.open ? bumped(readings.closes, nodeId, 1) : readings.closes,
|
|
32
|
+
types: {
|
|
33
|
+
...readings.types,
|
|
34
|
+
...Object.fromEntries(within.map((region) => [region.nodeId, region.type])),
|
|
35
|
+
[nodeId]: signal.type,
|
|
36
|
+
},
|
|
37
|
+
};
|
|
38
|
+
};
|
|
39
|
+
/**
|
|
40
|
+
* One more batch, folded in.
|
|
41
|
+
*
|
|
42
|
+
* The batch's tree and revision are not checked against anything, because a
|
|
43
|
+
* reading is about one page and the caller is the one holding it. Folding two
|
|
44
|
+
* revisions into one accumulator is a caller's mistake and it is the caller who
|
|
45
|
+
* can see it — `rollup.ts` is the module that keeps revisions apart, because it
|
|
46
|
+
* is the one that is handed a mixture.
|
|
47
|
+
*/
|
|
48
|
+
export const foldReaderSignals = (readings, batch) => {
|
|
49
|
+
const folded = batch.signals.reduce(foldSignal, readings);
|
|
50
|
+
return { ...folded, batches: readings.batches + 1, signals: readings.signals + batch.signals.length };
|
|
51
|
+
};
|
|
52
|
+
export const readingsOf = (batches) => batches.reduce(foldReaderSignals, EMPTY_READINGS);
|
|
53
|
+
/**
|
|
54
|
+
* Readings as rows, longest on screen first.
|
|
55
|
+
*
|
|
56
|
+
* The order is a default rather than a claim: a caller with a legend almost
|
|
57
|
+
* always wants the page's own order instead, which it can produce because every
|
|
58
|
+
* row names its node. What a caller without one wants is the interesting end
|
|
59
|
+
* first.
|
|
60
|
+
*/
|
|
61
|
+
export const nodeReadingsOf = (readings) => Object.keys(readings.types)
|
|
62
|
+
.map((key) => {
|
|
63
|
+
const nodeId = key;
|
|
64
|
+
return {
|
|
65
|
+
nodeId,
|
|
66
|
+
type: readings.types[nodeId],
|
|
67
|
+
dwellMs: readings.dwellMs[nodeId] ?? 0,
|
|
68
|
+
reached: readings.reached[nodeId] === true,
|
|
69
|
+
activations: readings.activations[nodeId] ?? 0,
|
|
70
|
+
opens: readings.opens[nodeId] ?? 0,
|
|
71
|
+
closes: readings.closes[nodeId] ?? 0,
|
|
72
|
+
engagements: readings.engagements[nodeId] ?? 0,
|
|
73
|
+
};
|
|
74
|
+
})
|
|
75
|
+
.sort((first, second) => second.dwellMs - first.dwellMs);
|
|
76
|
+
//# sourceMappingURL=fold.js.map
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Reader signals: what a published page may say about how it is being read,
|
|
3
|
+
* and what a deployment does with it once it has been said.
|
|
4
|
+
*
|
|
5
|
+
* The vocabulary and its parser are safe to import anywhere. The broadcaster
|
|
6
|
+
* touches the DOM only when it is called, so this entry point also loads on a
|
|
7
|
+
* server that merely parses batches (0136).
|
|
8
|
+
*
|
|
9
|
+
* **In a browser bundle, import the broadcaster from
|
|
10
|
+
* `@jam-overture/loom/signals/broadcast` instead.** This entry also carries the
|
|
11
|
+
* schemas, and a bundler cannot leave the schema library out once it is
|
|
12
|
+
* imported — about 60 KB of it, against a broadcaster of about 5 KB.
|
|
13
|
+
*
|
|
14
|
+
* **Postgres is not re-exported here.** It reaches Drizzle and a database
|
|
15
|
+
* driver, and a route handler that only ingests should not load either;
|
|
16
|
+
* `@jam-overture/loom/signals/postgres` is where a deployment picks it up, exactly
|
|
17
|
+
* as the store and the journal do it.
|
|
18
|
+
*/
|
|
19
|
+
export * from "./broadcast.js";
|
|
20
|
+
export * from "./collect.js";
|
|
21
|
+
export * from "./deliver.js";
|
|
22
|
+
export * from "./fold.js";
|
|
23
|
+
export * from "./ingest.js";
|
|
24
|
+
export * from "./intake.js";
|
|
25
|
+
export * from "./journal.js";
|
|
26
|
+
export * from "./memory.js";
|
|
27
|
+
export * from "./rollup.js";
|
|
28
|
+
export * from "./signal.js";
|
|
29
|
+
export * from "./tally.js";
|
|
30
|
+
export * from "./view.js";
|
|
31
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Reader signals: what a published page may say about how it is being read,
|
|
3
|
+
* and what a deployment does with it once it has been said.
|
|
4
|
+
*
|
|
5
|
+
* The vocabulary and its parser are safe to import anywhere. The broadcaster
|
|
6
|
+
* touches the DOM only when it is called, so this entry point also loads on a
|
|
7
|
+
* server that merely parses batches (0136).
|
|
8
|
+
*
|
|
9
|
+
* **In a browser bundle, import the broadcaster from
|
|
10
|
+
* `@jam-overture/loom/signals/broadcast` instead.** This entry also carries the
|
|
11
|
+
* schemas, and a bundler cannot leave the schema library out once it is
|
|
12
|
+
* imported — about 60 KB of it, against a broadcaster of about 5 KB.
|
|
13
|
+
*
|
|
14
|
+
* **Postgres is not re-exported here.** It reaches Drizzle and a database
|
|
15
|
+
* driver, and a route handler that only ingests should not load either;
|
|
16
|
+
* `@jam-overture/loom/signals/postgres` is where a deployment picks it up, exactly
|
|
17
|
+
* as the store and the journal do it.
|
|
18
|
+
*/
|
|
19
|
+
export * from "./broadcast.js";
|
|
20
|
+
export * from "./collect.js";
|
|
21
|
+
export * from "./deliver.js";
|
|
22
|
+
export * from "./fold.js";
|
|
23
|
+
export * from "./ingest.js";
|
|
24
|
+
export * from "./intake.js";
|
|
25
|
+
export * from "./journal.js";
|
|
26
|
+
export * from "./memory.js";
|
|
27
|
+
export * from "./rollup.js";
|
|
28
|
+
export * from "./signal.js";
|
|
29
|
+
export * from "./tally.js";
|
|
30
|
+
export * from "./view.js";
|
|
31
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
import { type Result } from "../result.js";
|
|
2
|
+
import type { ReaderSignalJournal, ReaderSignalStoreError } from "./journal.js";
|
|
3
|
+
import { type ReaderSignalParseError } from "./signal.js";
|
|
4
|
+
/**
|
|
5
|
+
* The doorway a browser's batches come through.
|
|
6
|
+
*
|
|
7
|
+
* A page is not a trusted author. Everything that arrives here is parsed before
|
|
8
|
+
* it is kept — the shape, the kinds, the tree id's grammar, and the view key's
|
|
9
|
+
* thirty-two characters of nothing — because the alternative is a database
|
|
10
|
+
* column a visitor can write anything into, including the visitor id that 0146
|
|
11
|
+
* exists to refuse.
|
|
12
|
+
*
|
|
13
|
+
* The route handler that serves this is a surface's, not the framework's. What
|
|
14
|
+
* the framework owns is this function: unknown in, a counted outcome or a
|
|
15
|
+
* typed refusal out, no throw either way.
|
|
16
|
+
*/
|
|
17
|
+
/**
|
|
18
|
+
* How many batches one delivery may carry.
|
|
19
|
+
*
|
|
20
|
+
* A broadcaster sends one at a time, so anything above a handful is a retry
|
|
21
|
+
* queue draining after an outage, and that is worth allowing. What it is not
|
|
22
|
+
* worth is unbounded: the parse is the expensive part and an endpoint that will
|
|
23
|
+
* parse as many batches as a body can hold is an endpoint that can be made to
|
|
24
|
+
* spend a minute on one request.
|
|
25
|
+
*/
|
|
26
|
+
export declare const MAX_BATCHES_PER_DELIVERY = 50;
|
|
27
|
+
export type IngestOutcome = {
|
|
28
|
+
readonly batches: number;
|
|
29
|
+
readonly signals: number;
|
|
30
|
+
};
|
|
31
|
+
export type IngestError = {
|
|
32
|
+
readonly code: "invalid-delivery";
|
|
33
|
+
/** Which batch of the delivery, so a sender with one bad batch can be told which. */
|
|
34
|
+
readonly index: number;
|
|
35
|
+
readonly issues: ReaderSignalParseError["issues"];
|
|
36
|
+
} | {
|
|
37
|
+
readonly code: "too-many";
|
|
38
|
+
readonly limit: number;
|
|
39
|
+
readonly given: number;
|
|
40
|
+
} | ReaderSignalStoreError;
|
|
41
|
+
export declare const describeIngestError: (error: IngestError) => string;
|
|
42
|
+
/**
|
|
43
|
+
* Parse a delivery and keep it.
|
|
44
|
+
*
|
|
45
|
+
* **Nothing is kept unless all of it parses.** A partial accept would mean a
|
|
46
|
+
* sender's retry either duplicates what was taken or drops what was not, and
|
|
47
|
+
* neither is something a browser can be asked to work out. It also means the
|
|
48
|
+
* refusal is actionable: one index, one reason.
|
|
49
|
+
*/
|
|
50
|
+
export declare const ingestReaderSignals: (journal: ReaderSignalJournal, input: unknown) => Promise<Result<IngestOutcome, IngestError>>;
|
|
51
|
+
//# sourceMappingURL=ingest.d.ts.map
|