@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,451 @@
|
|
|
1
|
+
import { NAMESPACED_ID_PATTERN, NODE_ID_PATTERN, TREE_ID_PATTERN } from "../grammar.js";
|
|
2
|
+
import { DISCLOSED_ATTRIBUTE } from "../render/disclosed.js";
|
|
3
|
+
import { LOOM_NODE_ATTRIBUTE, LOOM_REVISION_ATTRIBUTE, LOOM_TREE_ATTRIBUTE, LOOM_TYPE_ATTRIBUTE, } from "../render/editable.js";
|
|
4
|
+
import { err, ok } from "../result.js";
|
|
5
|
+
import { createSignalLedger } from "./ledger.js";
|
|
6
|
+
import { READER_SIGNAL_KINDS } from "./kinds.js";
|
|
7
|
+
import { mintViewKey } from "./view.js";
|
|
8
|
+
/**
|
|
9
|
+
* Broadcasting reader signals from a rendered Loom page.
|
|
10
|
+
*
|
|
11
|
+
* The browser half of the seam. Point it at the root element of a page rendered
|
|
12
|
+
* with `addressed: true` and it watches the nodes on that page, gathers what
|
|
13
|
+
* readers do with them, and delivers a batch every few seconds — as a DOM event
|
|
14
|
+
* anything on the page can listen for, and to a `send` function if the host
|
|
15
|
+
* gives one.
|
|
16
|
+
*
|
|
17
|
+
* **Off unless a host calls it.** The library renders no script and starts no
|
|
18
|
+
* observer on its own; a page that never calls this broadcasts nothing (0136).
|
|
19
|
+
*
|
|
20
|
+
* **Configured by the host, never by the tree.** Which kinds and which primitive
|
|
21
|
+
* types are broadcast is an argument here, not a prop a proposal could set — a
|
|
22
|
+
* model must not be able to switch measurement of readers on by writing a delta.
|
|
23
|
+
*
|
|
24
|
+
* **It reads the page, not the components.** Every fact it needs is already on
|
|
25
|
+
* the markup: identity from the addressed attributes, what a reader can aim at
|
|
26
|
+
* from the elements HTML gives targets, and a disclosure from the attribute the
|
|
27
|
+
* disclose control stamps. No primitive is instrumented, so no primitive can
|
|
28
|
+
* forget to be.
|
|
29
|
+
*
|
|
30
|
+
* **A press says which regions it was in.** A reader aims at a button, and a
|
|
31
|
+
* button is an addressed node of its own, so the node an `activated` names is
|
|
32
|
+
* the control rather than the band. The addressed elements above it go on the
|
|
33
|
+
* signal as `within`, read off the walk this was already doing — because which
|
|
34
|
+
* region a node sat in is a fact about the page at the moment of the press, and
|
|
35
|
+
* nothing downstream can recover it afterwards.
|
|
36
|
+
*
|
|
37
|
+
* **It keeps up with a page that changes.** Nodes that arrive after it started
|
|
38
|
+
* are watched and nodes that leave stop counting, so a band behind a Suspense
|
|
39
|
+
* boundary, a list that grows, and every region a proposal has just changed are
|
|
40
|
+
* measured like the rest. What it does *not* follow is the page becoming a
|
|
41
|
+
* different page: the tree and revision are read once, off the root, and every
|
|
42
|
+
* batch is filed under them. **A new root, or a new revision in the same root,
|
|
43
|
+
* is a new broadcast** — `stop()` the old one and start another, or a
|
|
44
|
+
* client-side navigation files its signals under the revision it left.
|
|
45
|
+
*/
|
|
46
|
+
/** The DOM event a batch is dispatched as, on the root element. It bubbles. */
|
|
47
|
+
/**
|
|
48
|
+
* The delivery helper travels with this entry point rather than getting one of
|
|
49
|
+
* its own.
|
|
50
|
+
*
|
|
51
|
+
* `deliver.ts` imports nothing at runtime, so it costs the same bytes reached
|
|
52
|
+
* from here as it would through a door of its own — and a host who is starting
|
|
53
|
+
* a broadcaster in a browser bundle is exactly the host who needs a `send`. One
|
|
54
|
+
* import line for the two things that are always used together.
|
|
55
|
+
*/
|
|
56
|
+
export { DEFAULT_READER_SIGNAL_PATH, deliverReaderSignals, } from "./deliver.js";
|
|
57
|
+
export const READER_SIGNALS_EVENT = "loom:signals";
|
|
58
|
+
/**
|
|
59
|
+
* What a reader can aim at, as HTML defines it. `summary` is left out on
|
|
60
|
+
* purpose: opening a `details` is reported as `disclosed`, and reporting the same
|
|
61
|
+
* click twice under two kinds would double-count the one thing a reader did.
|
|
62
|
+
*/
|
|
63
|
+
const TARGET_SELECTOR = [
|
|
64
|
+
"a[href]",
|
|
65
|
+
"button",
|
|
66
|
+
"input",
|
|
67
|
+
"select",
|
|
68
|
+
"textarea",
|
|
69
|
+
'[role="button"]',
|
|
70
|
+
'[role="link"]',
|
|
71
|
+
].join(",");
|
|
72
|
+
/**
|
|
73
|
+
* The host's `kinds` and `types`, as one question: is this kind of signal about
|
|
74
|
+
* this type of primitive wanted?
|
|
75
|
+
*/
|
|
76
|
+
const selectionOf = (kinds, types) => {
|
|
77
|
+
const enabled = new Set(kinds ?? READER_SIGNAL_KINDS);
|
|
78
|
+
const allowed = new Map(types === undefined
|
|
79
|
+
? []
|
|
80
|
+
: Array.isArray(types)
|
|
81
|
+
? READER_SIGNAL_KINDS.map((kind) => [kind, new Set(types)])
|
|
82
|
+
: READER_SIGNAL_KINDS.flatMap((kind) => {
|
|
83
|
+
const listed = types[kind];
|
|
84
|
+
return listed === undefined ? [] : [[kind, new Set(listed)]];
|
|
85
|
+
}));
|
|
86
|
+
return (kind, type) => enabled.has(kind) && (allowed.get(kind)?.has(type) ?? true);
|
|
87
|
+
};
|
|
88
|
+
const DEFAULT_FLUSH_MS = 5000;
|
|
89
|
+
/**
|
|
90
|
+
* On screen means a reader could be reading it: at least half of the element is
|
|
91
|
+
* visible, or it fills at least 30% of the viewport. The second clause is not
|
|
92
|
+
* optional — the visible fraction of an element taller than the window can never
|
|
93
|
+
* reach one half, so a long section judged by the first alone is never viewed.
|
|
94
|
+
*/
|
|
95
|
+
const isReadable = (entry) => {
|
|
96
|
+
if (!entry.isIntersecting)
|
|
97
|
+
return false;
|
|
98
|
+
const viewport = entry.rootBounds?.height ?? globalThis.innerHeight ?? 0;
|
|
99
|
+
const fills = viewport > 0 && entry.intersectionRect.height / viewport >= 0.3;
|
|
100
|
+
return entry.intersectionRatio >= 0.5 || fills;
|
|
101
|
+
};
|
|
102
|
+
const intersectionVisibility = (onChange) => {
|
|
103
|
+
const observer = new IntersectionObserver((entries) => onChange(entries.map((entry) => ({ target: entry.target, visible: isReadable(entry) }))), { threshold: [0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1] });
|
|
104
|
+
return { observe: (element) => observer.observe(element), disconnect: () => observer.disconnect() };
|
|
105
|
+
};
|
|
106
|
+
/**
|
|
107
|
+
* Recognisers built from the id grammar rather than the schemas, so the
|
|
108
|
+
* broadcaster ships no schema library to the browser. The check is the same
|
|
109
|
+
* pattern the schemas apply; the brand is a claim that pattern earns.
|
|
110
|
+
*/
|
|
111
|
+
const isNodeId = (value) => value !== null && NODE_ID_PATTERN.test(value);
|
|
112
|
+
const isTreeId = (value) => value !== null && TREE_ID_PATTERN.test(value);
|
|
113
|
+
const isPrimitiveType = (value) => value !== null && NAMESPACED_ID_PATTERN.test(value);
|
|
114
|
+
/** The identity an element carries, or `undefined` when it carries none worth trusting. */
|
|
115
|
+
const addressOf = (element) => {
|
|
116
|
+
const nodeId = element.getAttribute(LOOM_NODE_ATTRIBUTE);
|
|
117
|
+
const type = element.getAttribute(LOOM_TYPE_ATTRIBUTE);
|
|
118
|
+
return isNodeId(nodeId) && isPrimitiveType(type) ? { nodeId, type } : undefined;
|
|
119
|
+
};
|
|
120
|
+
const pageOf = (root) => {
|
|
121
|
+
const treeId = root.getAttribute(LOOM_TREE_ATTRIBUTE);
|
|
122
|
+
/**
|
|
123
|
+
* Matched as digits before it is converted. `Number(null)` and `Number("")` are
|
|
124
|
+
* both 0, so a page with no revision at all would otherwise pass as revision 0
|
|
125
|
+
* and every signal from it would be filed under a revision it never had.
|
|
126
|
+
*/
|
|
127
|
+
const written = root.getAttribute(LOOM_REVISION_ATTRIBUTE) ?? "";
|
|
128
|
+
const revision = /^\d+$/.test(written) ? Number(written) : Number.NaN;
|
|
129
|
+
return isTreeId(treeId) && Number.isSafeInteger(revision)
|
|
130
|
+
? ok({ treeId, revision })
|
|
131
|
+
: err({
|
|
132
|
+
code: "unaddressed",
|
|
133
|
+
detail: `the root element carries no ${LOOM_TREE_ATTRIBUTE} and ${LOOM_REVISION_ATTRIBUTE}; render the page with addressed: true`,
|
|
134
|
+
});
|
|
135
|
+
};
|
|
136
|
+
/** The nearest addressed element at or above `element`, without leaving the page. */
|
|
137
|
+
const nearestAddressed = (root, element) => {
|
|
138
|
+
const found = element.closest(`[${LOOM_NODE_ATTRIBUTE}]`);
|
|
139
|
+
return found !== null && root.contains(found) ? found : undefined;
|
|
140
|
+
};
|
|
141
|
+
/**
|
|
142
|
+
* The addressed elements above `element`, nearest first, stopping at the root.
|
|
143
|
+
*
|
|
144
|
+
* The same walk `nearestAddressed` already does, continued instead of stopped —
|
|
145
|
+
* so a press knows the card, the band and the page it was in rather than only
|
|
146
|
+
* the button, and nothing has to consult the tree afterwards to find out. The
|
|
147
|
+
* root itself is included when it is addressed, because a page whose root is a
|
|
148
|
+
* node is a region like any other.
|
|
149
|
+
*
|
|
150
|
+
* An element the walk cannot read an address off is skipped rather than ending
|
|
151
|
+
* the ancestry: `LOOM_NODE_ATTRIBUTE` without a readable type is markup this
|
|
152
|
+
* broadcaster does not trust, not a ceiling on what is above it.
|
|
153
|
+
*/
|
|
154
|
+
const ancestryOf = (root, element) => {
|
|
155
|
+
const found = [];
|
|
156
|
+
for (let above = element.parentElement; above !== null && root.contains(above); above = above.parentElement) {
|
|
157
|
+
const address = addressOf(above);
|
|
158
|
+
if (address !== undefined)
|
|
159
|
+
found.push(address);
|
|
160
|
+
if (above === root)
|
|
161
|
+
break;
|
|
162
|
+
}
|
|
163
|
+
return found;
|
|
164
|
+
};
|
|
165
|
+
/** A sink observes; it does not get a vote (0042). Neither a throw nor a rejection reaches the page. */
|
|
166
|
+
const deliverSafely = (send, batch) => {
|
|
167
|
+
if (send === undefined)
|
|
168
|
+
return;
|
|
169
|
+
try {
|
|
170
|
+
const pending = send(batch);
|
|
171
|
+
if (pending instanceof Promise)
|
|
172
|
+
pending.catch(() => undefined);
|
|
173
|
+
}
|
|
174
|
+
catch {
|
|
175
|
+
// Contained by design.
|
|
176
|
+
}
|
|
177
|
+
};
|
|
178
|
+
/**
|
|
179
|
+
* Start broadcasting reader signals from the page under `root`.
|
|
180
|
+
*
|
|
181
|
+
* Returns an error rather than broadcasting nothing when the page is not
|
|
182
|
+
* addressed, because a silent broadcaster on an unaddressed page is exactly the
|
|
183
|
+
* misconfiguration nobody would notice.
|
|
184
|
+
*
|
|
185
|
+
* Nodes added under `root` afterwards are picked up and nodes removed stop
|
|
186
|
+
* counting. The tree and revision are not: they are read once, here, and a page
|
|
187
|
+
* that becomes a different page — a client-side navigation, a re-render at a new
|
|
188
|
+
* revision into the same root — needs `stop()` and a new broadcast, or its
|
|
189
|
+
* signals are filed under the revision it left.
|
|
190
|
+
*/
|
|
191
|
+
export const broadcastReaderSignals = (root, options = {}) => {
|
|
192
|
+
const page = pageOf(root);
|
|
193
|
+
if (!page.ok)
|
|
194
|
+
return page;
|
|
195
|
+
const now = options.now ?? Date.now;
|
|
196
|
+
const wants = selectionOf(options.kinds, options.types);
|
|
197
|
+
const document = root.ownerDocument;
|
|
198
|
+
/**
|
|
199
|
+
* Minted once, here, and carried by every batch this broadcast sends — which
|
|
200
|
+
* is what makes the batches of one page view correlatable and two page views
|
|
201
|
+
* not (0146). A new broadcast is a new view, including the second one a
|
|
202
|
+
* client-side navigation needs, so the key cannot outlive the page it
|
|
203
|
+
* describes even by accident.
|
|
204
|
+
*/
|
|
205
|
+
const view = mintViewKey(options.random);
|
|
206
|
+
const ledger = createSignalLedger(document.visibilityState === "hidden");
|
|
207
|
+
let stopped = false;
|
|
208
|
+
const walks = options.within ?? true;
|
|
209
|
+
/**
|
|
210
|
+
* What a delegated signal says about where it happened, as the fragment its
|
|
211
|
+
* factory spreads.
|
|
212
|
+
*
|
|
213
|
+
* An empty object rather than `within: []` when the host turned the walk off,
|
|
214
|
+
* because an empty ancestry is a claim — *this node has no addressed
|
|
215
|
+
* ancestor* — and a broadcaster that was told not to look has not made it.
|
|
216
|
+
*/
|
|
217
|
+
const ancestry = (target) => walks ? { within: ancestryOf(root, target) } : {};
|
|
218
|
+
const record = (kind, signal) => (element) => {
|
|
219
|
+
const target = nearestAddressed(root, element);
|
|
220
|
+
if (target === undefined)
|
|
221
|
+
return;
|
|
222
|
+
const address = addressOf(target);
|
|
223
|
+
if (address === undefined || !wants(kind, address.type))
|
|
224
|
+
return;
|
|
225
|
+
ledger.noted(signal(address, ancestry(target)));
|
|
226
|
+
};
|
|
227
|
+
const flush = () => {
|
|
228
|
+
const drained = ledger.drain(now());
|
|
229
|
+
/**
|
|
230
|
+
* Viewed and dwelled are gathered together, because one observer serves both,
|
|
231
|
+
* and are selected here — so a host asking only for time on screen gets no
|
|
232
|
+
* `viewed`, and a type watched for one kind reports nothing for the other.
|
|
233
|
+
*/
|
|
234
|
+
const signals = drained.filter((signal) => wants(signal.kind, signal.type));
|
|
235
|
+
if (signals.length === 0)
|
|
236
|
+
return;
|
|
237
|
+
const batch = {
|
|
238
|
+
treeId: page.value.treeId,
|
|
239
|
+
revision: page.value.revision,
|
|
240
|
+
sentAt: now(),
|
|
241
|
+
view,
|
|
242
|
+
signals,
|
|
243
|
+
};
|
|
244
|
+
root.dispatchEvent(new CustomEvent(READER_SIGNALS_EVENT, { detail: batch, bubbles: true }));
|
|
245
|
+
deliverSafely(options.send, batch);
|
|
246
|
+
};
|
|
247
|
+
const watched = (type) => wants("viewed", type) || wants("dwelled", type);
|
|
248
|
+
/**
|
|
249
|
+
* Each observed element's address, read once when observing starts. The
|
|
250
|
+
* observer calls back at every threshold an element crosses — eleven times on
|
|
251
|
+
* the way into view — and reading two attributes and testing two patterns on
|
|
252
|
+
* each of those is work whose answer cannot have changed.
|
|
253
|
+
*/
|
|
254
|
+
const addresses = new WeakMap();
|
|
255
|
+
const enabled = options.kinds ?? READER_SIGNAL_KINDS;
|
|
256
|
+
const watchesTime = enabled.includes("viewed") || enabled.includes("dwelled");
|
|
257
|
+
const visibility = watchesTime
|
|
258
|
+
? (options.observeVisibility ?? intersectionVisibility)((entries) => {
|
|
259
|
+
const at = now();
|
|
260
|
+
for (const entry of entries) {
|
|
261
|
+
const address = addresses.get(entry.target);
|
|
262
|
+
if (address === undefined)
|
|
263
|
+
continue;
|
|
264
|
+
if (entry.visible)
|
|
265
|
+
ledger.entered(address, at);
|
|
266
|
+
else
|
|
267
|
+
ledger.left(address.nodeId, at);
|
|
268
|
+
}
|
|
269
|
+
})
|
|
270
|
+
: undefined;
|
|
271
|
+
/** An element and every addressed element under it, which is what a subtree arriving or leaving amounts to. */
|
|
272
|
+
const addressedWithin = (element) => [
|
|
273
|
+
element,
|
|
274
|
+
...Array.from(element.querySelectorAll(`[${LOOM_NODE_ATTRIBUTE}]`)),
|
|
275
|
+
];
|
|
276
|
+
/** Hand an element to the visibility observer, if time on screen is wanted for what it is. */
|
|
277
|
+
const watchForTime = (element) => {
|
|
278
|
+
if (visibility === undefined)
|
|
279
|
+
return;
|
|
280
|
+
const address = addressOf(element);
|
|
281
|
+
if (address === undefined || !watched(address.type))
|
|
282
|
+
return;
|
|
283
|
+
addresses.set(element, address);
|
|
284
|
+
visibility.observe(element);
|
|
285
|
+
};
|
|
286
|
+
/**
|
|
287
|
+
* A node left the page, so the stretch it was in the middle of ends here.
|
|
288
|
+
*
|
|
289
|
+
* Closed on the mutation rather than left to the visibility observer: a
|
|
290
|
+
* removed element may never be reported as having gone out of view, and a
|
|
291
|
+
* stretch that is never closed is time a reader is credited with forever.
|
|
292
|
+
*/
|
|
293
|
+
const departed = (element, at) => {
|
|
294
|
+
const address = addresses.get(element);
|
|
295
|
+
if (address !== undefined)
|
|
296
|
+
ledger.left(address.nodeId, at);
|
|
297
|
+
};
|
|
298
|
+
for (const element of addressedWithin(root))
|
|
299
|
+
watchForTime(element);
|
|
300
|
+
/**
|
|
301
|
+
* What the page grows and sheds after the broadcast started.
|
|
302
|
+
*
|
|
303
|
+
* `activated` and `disclosed` reach a node that did not exist yet on their
|
|
304
|
+
* own, because both are delegated from the root and read the nearest addressed
|
|
305
|
+
* element at the moment they happen. Time on screen is the one kind that needs
|
|
306
|
+
* each element handed to an observer, so a broadcaster that looked once
|
|
307
|
+
* reported nothing about anything rendered afterwards — a band behind a
|
|
308
|
+
* Suspense boundary, a region a client component mounts, a list that grows,
|
|
309
|
+
* **and every region a proposal has just changed.**
|
|
310
|
+
*
|
|
311
|
+
* That last one is why this is not a nicety. *Before versus after a change* is
|
|
312
|
+
* the measurement Loom exists to make, and it was the one measurement that did
|
|
313
|
+
* not work: an applied change renders after the broadcaster started, so every
|
|
314
|
+
* adapted region was invisible to `viewed` and `dwelled` while the rest of the
|
|
315
|
+
* page was counted normally. Numbers that understate only the changed bands
|
|
316
|
+
* are worse than no numbers, because they look like data.
|
|
317
|
+
*
|
|
318
|
+
* Only built when time is being watched at all: the other kinds need no help.
|
|
319
|
+
*/
|
|
320
|
+
const arrivals = visibility === undefined
|
|
321
|
+
? undefined
|
|
322
|
+
: new MutationObserver((mutations) => {
|
|
323
|
+
const at = now();
|
|
324
|
+
for (const mutation of mutations) {
|
|
325
|
+
for (const added of Array.from(mutation.addedNodes)) {
|
|
326
|
+
if (added instanceof Element)
|
|
327
|
+
for (const element of addressedWithin(added))
|
|
328
|
+
watchForTime(element);
|
|
329
|
+
}
|
|
330
|
+
for (const gone of Array.from(mutation.removedNodes)) {
|
|
331
|
+
if (gone instanceof Element)
|
|
332
|
+
for (const element of addressedWithin(gone))
|
|
333
|
+
departed(element, at);
|
|
334
|
+
}
|
|
335
|
+
}
|
|
336
|
+
});
|
|
337
|
+
const onActivated = record("activated", (address, within) => ({
|
|
338
|
+
kind: "activated",
|
|
339
|
+
...address,
|
|
340
|
+
at: now(),
|
|
341
|
+
...within,
|
|
342
|
+
}));
|
|
343
|
+
const onClick = (event) => {
|
|
344
|
+
const control = event.target instanceof Element ? event.target.closest(TARGET_SELECTOR) : null;
|
|
345
|
+
if (control === null || !root.contains(control))
|
|
346
|
+
return;
|
|
347
|
+
/** A disclose control reports as `disclosed`, for the same reason `summary` is left out above. */
|
|
348
|
+
if (control.hasAttribute(DISCLOSED_ATTRIBUTE))
|
|
349
|
+
return;
|
|
350
|
+
onActivated(control);
|
|
351
|
+
};
|
|
352
|
+
/**
|
|
353
|
+
* The last state each `details` was seen in, so only a change is reported.
|
|
354
|
+
*
|
|
355
|
+
* A browser fires `toggle` for a `details` that was *authored* open, as the
|
|
356
|
+
* page loads — nobody opened it. Snapshotting every one when broadcasting
|
|
357
|
+
* starts, and reporting a toggle only when it disagrees with the snapshot, is
|
|
358
|
+
* what keeps a page's own markup from reading as a reader's action. One added
|
|
359
|
+
* to the page later has no snapshot, and its first toggle is taken at its word.
|
|
360
|
+
*/
|
|
361
|
+
const lastOpen = new WeakMap(Array.from(root.querySelectorAll("details")).map((details) => [details, details.open]));
|
|
362
|
+
const onToggle = (event) => {
|
|
363
|
+
const details = event.target;
|
|
364
|
+
if (!(details instanceof HTMLDetailsElement))
|
|
365
|
+
return;
|
|
366
|
+
if (lastOpen.get(details) === details.open)
|
|
367
|
+
return;
|
|
368
|
+
lastOpen.set(details, details.open);
|
|
369
|
+
record("disclosed", (address, within) => ({
|
|
370
|
+
kind: "disclosed",
|
|
371
|
+
...address,
|
|
372
|
+
open: details.open,
|
|
373
|
+
at: now(),
|
|
374
|
+
...within,
|
|
375
|
+
}))(details);
|
|
376
|
+
};
|
|
377
|
+
const disclosures = new MutationObserver((mutations) => {
|
|
378
|
+
for (const mutation of mutations) {
|
|
379
|
+
if (!(mutation.target instanceof Element))
|
|
380
|
+
continue;
|
|
381
|
+
const open = mutation.target.getAttribute(DISCLOSED_ATTRIBUTE);
|
|
382
|
+
const settled = open === "true" || open === "false";
|
|
383
|
+
if (!settled || mutation.oldValue === null || mutation.oldValue === open)
|
|
384
|
+
continue;
|
|
385
|
+
record("disclosed", (address, within) => ({
|
|
386
|
+
kind: "disclosed",
|
|
387
|
+
...address,
|
|
388
|
+
open: open === "true",
|
|
389
|
+
at: now(),
|
|
390
|
+
...within,
|
|
391
|
+
}))(mutation.target);
|
|
392
|
+
}
|
|
393
|
+
});
|
|
394
|
+
/**
|
|
395
|
+
* The batch timer runs only while the page is visible. A hidden page gathers
|
|
396
|
+
* nothing — the ledger has stopped counting — so a timer ticking in a
|
|
397
|
+
* background tab would wake the page every few seconds to find that out.
|
|
398
|
+
*/
|
|
399
|
+
const flushEveryMs = options.flushEveryMs ?? DEFAULT_FLUSH_MS;
|
|
400
|
+
let timer;
|
|
401
|
+
const startTimer = () => {
|
|
402
|
+
if (timer === undefined)
|
|
403
|
+
timer = setInterval(flush, flushEveryMs);
|
|
404
|
+
};
|
|
405
|
+
const stopTimer = () => {
|
|
406
|
+
if (timer !== undefined)
|
|
407
|
+
clearInterval(timer);
|
|
408
|
+
timer = undefined;
|
|
409
|
+
};
|
|
410
|
+
const onVisibility = () => {
|
|
411
|
+
if (document.visibilityState === "hidden") {
|
|
412
|
+
ledger.hid(now());
|
|
413
|
+
flush();
|
|
414
|
+
stopTimer();
|
|
415
|
+
}
|
|
416
|
+
else {
|
|
417
|
+
ledger.showed(now());
|
|
418
|
+
startTimer();
|
|
419
|
+
}
|
|
420
|
+
};
|
|
421
|
+
const onPageHide = () => flush();
|
|
422
|
+
root.addEventListener("click", onClick);
|
|
423
|
+
root.addEventListener("toggle", onToggle, true);
|
|
424
|
+
disclosures.observe(root, {
|
|
425
|
+
attributes: true,
|
|
426
|
+
attributeFilter: [DISCLOSED_ATTRIBUTE],
|
|
427
|
+
attributeOldValue: true,
|
|
428
|
+
subtree: true,
|
|
429
|
+
});
|
|
430
|
+
arrivals?.observe(root, { childList: true, subtree: true });
|
|
431
|
+
document.addEventListener("visibilitychange", onVisibility);
|
|
432
|
+
document.defaultView?.addEventListener("pagehide", onPageHide);
|
|
433
|
+
if (document.visibilityState !== "hidden")
|
|
434
|
+
startTimer();
|
|
435
|
+
const stop = () => {
|
|
436
|
+
if (stopped)
|
|
437
|
+
return;
|
|
438
|
+
stopped = true;
|
|
439
|
+
flush();
|
|
440
|
+
stopTimer();
|
|
441
|
+
visibility?.disconnect();
|
|
442
|
+
disclosures.disconnect();
|
|
443
|
+
arrivals?.disconnect();
|
|
444
|
+
root.removeEventListener("click", onClick);
|
|
445
|
+
root.removeEventListener("toggle", onToggle, true);
|
|
446
|
+
document.removeEventListener("visibilitychange", onVisibility);
|
|
447
|
+
document.defaultView?.removeEventListener("pagehide", onPageHide);
|
|
448
|
+
};
|
|
449
|
+
return ok({ flush, stop });
|
|
450
|
+
};
|
|
451
|
+
//# sourceMappingURL=broadcast.js.map
|
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { type Clock } from "../runtime/events.js";
|
|
3
|
+
import type { ReaderSignalJournal, ReaderSignalStoreError, ReceivedBatch } from "./journal.js";
|
|
4
|
+
import { type FunnelPair } from "./rollup.js";
|
|
5
|
+
import type { ReaderTallyStore } from "./tally.js";
|
|
6
|
+
/**
|
|
7
|
+
* The one operation that empties the buffer.
|
|
8
|
+
*
|
|
9
|
+
* `journal.ts` can hold batches, `rollup.ts` can fold them and `tally.ts` can
|
|
10
|
+
* keep what the fold produced — and until this module existed nothing joined
|
|
11
|
+
* the three, so a deployment with signals switched on accumulated the largest
|
|
12
|
+
* table it owns and counted none of it.
|
|
13
|
+
*
|
|
14
|
+
* **Counting and forgetting are one call, and that is the design rather than a
|
|
15
|
+
* convenience.** A rollup reports *what this window added* (0147), so a batch
|
|
16
|
+
* counted twice is counted twice forever: there is no idempotence to fall back
|
|
17
|
+
* on and no way to notice afterwards, because the wrong number looks exactly
|
|
18
|
+
* like a busy afternoon. The only defence that does not need durable bookkeeping
|
|
19
|
+
* is for the set of batches rolled up and the set forgotten to be the same set,
|
|
20
|
+
* decided once, in one place. That is this file, and it is why there is no
|
|
21
|
+
* exported `applyReaderSignalRetention` beside it — a function that can forget
|
|
22
|
+
* without counting is the data-loss bug, and one that can count without
|
|
23
|
+
* forgetting is the double-count bug.
|
|
24
|
+
*
|
|
25
|
+
* Nothing schedules it, for the reason nothing schedules telemetry's retention
|
|
26
|
+
* or `auditSnapshot`: when a deployment forgets is an operational choice, and a
|
|
27
|
+
* framework that quietly deleted a host's data on a timer it chose would be
|
|
28
|
+
* making it. A host calls this from a cron route, a deploy hook, or by hand.
|
|
29
|
+
*
|
|
30
|
+
* **One run at a time, and the caller is what makes that true.** Two runs over
|
|
31
|
+
* the same ripe prefix both roll it up and both apply; applying is additive
|
|
32
|
+
* (0147), so the counters double and the buffer empties once, leaving nothing
|
|
33
|
+
* behind that could say what happened. Nothing here can prevent it — a journal
|
|
34
|
+
* and a store are two handles with no shared transaction between them — so
|
|
35
|
+
* serialising belongs to whatever schedules this. `apps/loom/scripts/
|
|
36
|
+
* signals-collect.ts` does it with a Postgres advisory lock, which is the
|
|
37
|
+
* cheapest thing that works for a cron that overruns its own interval.
|
|
38
|
+
*/
|
|
39
|
+
/**
|
|
40
|
+
* The window is the age a batch reaches before it is counted and dropped, and
|
|
41
|
+
* it is two arguments pulling opposite ways.
|
|
42
|
+
*
|
|
43
|
+
* **Longer is more accurate.** `views` and `reached` count distinct page views,
|
|
44
|
+
* distinctness does not add up, and a page view whose batches straddle two
|
|
45
|
+
* windows is counted in both — the over-count 0147 accepts. `tally.ts` already
|
|
46
|
+
* states the remedy in its own words: *a deployment that wants the bound small
|
|
47
|
+
* makes the rollup window long relative to a page view.* This is that number.
|
|
48
|
+
*
|
|
49
|
+
* **Shorter is more anonymous.** The raw window is the entire mechanism by
|
|
50
|
+
* which a view key stops existing (0146). The key is opaque, random and
|
|
51
|
+
* correlates nothing outside the buffer, but it correlates that, and the
|
|
52
|
+
* argument for it rests on how briefly it lives.
|
|
53
|
+
*
|
|
54
|
+
* An hour is long against a page view and short against a day, which is why it
|
|
55
|
+
* is the default rather than a constant: rule 5 of `docs/signals.md` makes the
|
|
56
|
+
* number a deployment's.
|
|
57
|
+
*/
|
|
58
|
+
export declare const DEFAULT_READER_SIGNAL_WINDOW_MS: number;
|
|
59
|
+
/**
|
|
60
|
+
* A minute, and the floor is not a style choice.
|
|
61
|
+
*
|
|
62
|
+
* Under a minute every page view straddles a boundary, so `views` stops being
|
|
63
|
+
* an approximation and becomes a count of flushes — a number about the network
|
|
64
|
+
* rather than about readers. It also refuses the ordinary way a window is
|
|
65
|
+
* written wrongly, which is a units mistake: `windowMs: 60` reads as an hour
|
|
66
|
+
* and means a minute and a tenth of a second.
|
|
67
|
+
*/
|
|
68
|
+
export declare const MIN_READER_SIGNAL_WINDOW_MS: number;
|
|
69
|
+
export declare const readerSignalWindowSchema: z.ZodObject<{
|
|
70
|
+
windowMs: z.ZodNumber;
|
|
71
|
+
}, "strip", z.ZodTypeAny, {
|
|
72
|
+
windowMs: number;
|
|
73
|
+
}, {
|
|
74
|
+
windowMs: number;
|
|
75
|
+
}>;
|
|
76
|
+
export type ReaderSignalWindow = z.infer<typeof readerSignalWindowSchema>;
|
|
77
|
+
/**
|
|
78
|
+
* How much of the buffer one run will look at.
|
|
79
|
+
*
|
|
80
|
+
* Incremental for telemetry retention's reason: a first run against a buffer
|
|
81
|
+
* nothing has ever drained does a bounded amount of work and the next run does
|
|
82
|
+
* more, so the operation is safe to schedule without knowing how far behind it
|
|
83
|
+
* is. `more` on the outcome is how a caller learns there was another run's
|
|
84
|
+
* worth waiting.
|
|
85
|
+
*/
|
|
86
|
+
export declare const DEFAULT_COLLECTION_SCAN = 5000;
|
|
87
|
+
export declare const MAX_COLLECTION_SCAN = 50000;
|
|
88
|
+
export type CollectionRequest = {
|
|
89
|
+
readonly windowMs?: number;
|
|
90
|
+
/**
|
|
91
|
+
* The funnels this deployment asks about. Absent means none — a pair is a
|
|
92
|
+
* question somebody wrote down, and rollup does not invent questions.
|
|
93
|
+
*
|
|
94
|
+
* A pair added later applies to windows collected after it, never to the ones
|
|
95
|
+
* already folded, because the batches those answers came from are gone. That
|
|
96
|
+
* is the price of aggregates being the durable artefact and it is worth
|
|
97
|
+
* knowing before a deployment waits a day for a number it will not get.
|
|
98
|
+
*/
|
|
99
|
+
readonly pairs?: readonly FunnelPair[];
|
|
100
|
+
readonly clock?: Clock;
|
|
101
|
+
readonly scanLimit?: number;
|
|
102
|
+
};
|
|
103
|
+
/**
|
|
104
|
+
* What one run may take, as a pure function of batches and an instant.
|
|
105
|
+
*
|
|
106
|
+
* The cut is the **first** batch young enough to keep, not every old one: the
|
|
107
|
+
* buffer forgets a prefix or nothing, exactly as the journals do, because a
|
|
108
|
+
* hole would make `seq` — an opaque increasing position — start meaning
|
|
109
|
+
* something a reader could misread. `receivedAt` is what it measures, never
|
|
110
|
+
* `sentAt`, which is a number a page said.
|
|
111
|
+
*/
|
|
112
|
+
export type CollectionPlan = {
|
|
113
|
+
/** Old enough to count, in ascending `seq`. */
|
|
114
|
+
readonly ripe: readonly ReceivedBatch[];
|
|
115
|
+
/** The position to forget below, once the counters are durable. `null` when nothing is ripe. */
|
|
116
|
+
readonly before: number | null;
|
|
117
|
+
/** Seen by this scan and too young. A floor rather than a total — the scan stops at the first. */
|
|
118
|
+
readonly waiting: number;
|
|
119
|
+
};
|
|
120
|
+
export declare const collectionPlanOf: (scanned: readonly ReceivedBatch[], horizon: string) => CollectionPlan;
|
|
121
|
+
export declare const horizonOf: (configured: ReaderSignalWindow, now: string) => string | null;
|
|
122
|
+
/** The half of the outcome a caller shows or logs, with nothing in it about a reader. */
|
|
123
|
+
export type CollectionSummary = {
|
|
124
|
+
readonly counted: number;
|
|
125
|
+
readonly tallies: number;
|
|
126
|
+
readonly funnels: number;
|
|
127
|
+
/** Distinct page views the window held. */
|
|
128
|
+
readonly views: number;
|
|
129
|
+
/**
|
|
130
|
+
* Batches that carried no view key, whose occurrences counted and whose views
|
|
131
|
+
* did not. A rate shown without saying which denominator it used is the
|
|
132
|
+
* failure mode here, so the number travels with the run that produced it.
|
|
133
|
+
*/
|
|
134
|
+
readonly uncorrelated: number;
|
|
135
|
+
};
|
|
136
|
+
export type CollectionOutcome = {
|
|
137
|
+
readonly outcome: "collected";
|
|
138
|
+
readonly summary: CollectionSummary;
|
|
139
|
+
/** Rows the buffer removed. Below `counted` only if something else pruned first. */
|
|
140
|
+
readonly removed: number;
|
|
141
|
+
/** The scan filled its limit with ripe batches, so another run has work now. */
|
|
142
|
+
readonly more: boolean;
|
|
143
|
+
}
|
|
144
|
+
/** Nothing is old enough yet, which is the ordinary answer on a quiet deployment. */
|
|
145
|
+
| {
|
|
146
|
+
readonly outcome: "nothing-ripe";
|
|
147
|
+
readonly waiting: number;
|
|
148
|
+
}
|
|
149
|
+
/**
|
|
150
|
+
* The counters took the window and the buffer would not drop it.
|
|
151
|
+
*
|
|
152
|
+
* Its own outcome because it is the one state that gets worse if it is
|
|
153
|
+
* ignored: the batches are durable in the counters and still in the buffer,
|
|
154
|
+
* so the next run counts them again. An operator seeing this prunes below the
|
|
155
|
+
* reported position by hand, or fixes the buffer before the next run.
|
|
156
|
+
*/
|
|
157
|
+
| {
|
|
158
|
+
readonly outcome: "counted-not-forgotten";
|
|
159
|
+
readonly summary: CollectionSummary;
|
|
160
|
+
readonly before: number;
|
|
161
|
+
readonly error: ReaderSignalStoreError;
|
|
162
|
+
}
|
|
163
|
+
/** The window was not usable. Nothing was read, counted or deleted. */
|
|
164
|
+
| {
|
|
165
|
+
readonly outcome: "refused";
|
|
166
|
+
readonly reason: string;
|
|
167
|
+
}
|
|
168
|
+
/** Read or write failed before anything became durable. Nothing was deleted. */
|
|
169
|
+
| {
|
|
170
|
+
readonly outcome: "unavailable";
|
|
171
|
+
readonly error: ReaderSignalStoreError;
|
|
172
|
+
};
|
|
173
|
+
/**
|
|
174
|
+
* Count a window of the buffer into the durable counters, then drop it.
|
|
175
|
+
*
|
|
176
|
+
* The order is the safe one and the reverse is a data-loss bug that looks like
|
|
177
|
+
* a feature working: aggregates first, the buffer second. What that leaves is
|
|
178
|
+
* `counted-not-forgotten`, which is visible and recoverable — the opposite
|
|
179
|
+
* order's failure is neither.
|
|
180
|
+
*/
|
|
181
|
+
export declare const collectReaderSignals: (journal: ReaderSignalJournal, store: ReaderTallyStore, request?: CollectionRequest) => Promise<CollectionOutcome>;
|
|
182
|
+
/** One line for an operator, because an outcome nobody can read is one nobody acts on. */
|
|
183
|
+
export declare const describeCollection: (outcome: CollectionOutcome) => string;
|
|
184
|
+
//# sourceMappingURL=collect.d.ts.map
|