@jam-overture/loom 0.1.0 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +3 -1
- package/dist/application/application.d.ts +109 -0
- package/dist/application/application.js +97 -0
- package/dist/application/memory.d.ts +20 -0
- package/dist/application/memory.js +79 -0
- package/dist/application/store.d.ts +101 -0
- package/dist/application/store.js +25 -0
- package/dist/audience/audience.d.ts +36 -0
- package/dist/audience/audience.js +41 -0
- package/dist/audience/compose.d.ts +112 -0
- package/dist/audience/compose.js +134 -0
- package/dist/audience/memory.d.ts +14 -0
- package/dist/audience/memory.js +71 -0
- package/dist/audience/overlay-store.d.ts +343 -0
- package/dist/audience/overlay-store.js +217 -0
- package/dist/audience/rule.d.ts +121 -0
- package/dist/audience/rule.js +78 -0
- package/dist/cli/index.d.ts +3 -4
- package/dist/cli/index.js +3 -4
- package/dist/cli/templates.js +19 -0
- package/dist/data/adapter.d.ts +9 -1
- package/dist/data/adapter.js +2 -0
- package/dist/data/plan.js +0 -0
- package/dist/data/resolution.d.ts +23 -1
- package/dist/data/resolve.d.ts +31 -4
- package/dist/data/resolve.js +11 -3
- package/dist/ids.d.ts +10 -0
- package/dist/ids.js +11 -1
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -0
- package/dist/interpretation/anthropic.d.ts +1 -1
- package/dist/interpretation/anthropic.js +2 -22
- package/dist/interpretation/client.d.ts +1 -1
- package/dist/interpretation/materialize.js +67 -22
- package/dist/interpretation/openai-compatible.d.ts +36 -0
- package/dist/interpretation/openai-compatible.js +79 -0
- package/dist/interpretation/status.d.ts +19 -0
- package/dist/interpretation/status.js +26 -0
- package/dist/live/index.d.ts +73 -0
- package/dist/live/index.js +73 -0
- package/dist/live/pages.d.ts +187 -0
- package/dist/live/pages.js +161 -0
- package/dist/live/pull.d.ts +147 -0
- package/dist/live/pull.js +398 -0
- package/dist/live/pulling.d.ts +79 -0
- package/dist/live/pulling.js +117 -0
- package/dist/live/window.d.ts +129 -0
- package/dist/live/window.js +132 -0
- package/dist/patch.d.ts +54 -0
- package/dist/patch.js +44 -0
- package/dist/project/closing.d.ts +51 -0
- package/dist/project/closing.js +53 -0
- package/dist/project/memory.d.ts +20 -0
- package/dist/project/memory.js +97 -0
- package/dist/project/project.d.ts +90 -0
- package/dist/project/project.js +91 -0
- package/dist/project/store.d.ts +135 -0
- package/dist/project/store.js +41 -0
- package/dist/registered.d.ts +64 -0
- package/dist/registered.js +118 -0
- package/dist/render/addressed.d.ts +35 -0
- package/dist/render/addressed.js +79 -0
- package/dist/render/behaviour-adjust.d.ts +11 -19
- package/dist/render/behaviour-adjust.js +75 -21
- package/dist/render/behaviour-present.d.ts +8 -0
- package/dist/render/behaviour-present.js +57 -6
- package/dist/render/behaviour.d.ts +98 -17
- package/dist/render/behaviour.js +91 -26
- package/dist/render/control-name.d.ts +68 -0
- package/dist/render/control-name.js +37 -0
- package/dist/render/diagnostics.d.ts +72 -0
- package/dist/render/diagnostics.js +7 -0
- package/dist/render/document-theme.d.ts +70 -0
- package/dist/render/document-theme.js +139 -0
- package/dist/render/editable.d.ts +15 -1
- package/dist/render/editable.js +13 -1
- package/dist/render/expected.d.ts +98 -0
- package/dist/render/expected.js +88 -0
- package/dist/render/index.d.ts +4 -0
- package/dist/render/index.js +4 -0
- package/dist/render/reads.d.ts +11 -0
- package/dist/render/reads.js +12 -1
- package/dist/render/render.d.ts +11 -0
- package/dist/render/render.js +294 -53
- package/dist/render/request.d.ts +8 -1
- package/dist/render/request.js +1 -0
- package/dist/render/slots.d.ts +52 -0
- package/dist/render/slots.js +24 -0
- package/dist/render/theme.d.ts +54 -1
- package/dist/render/theme.js +23 -1
- package/dist/render/unshown.d.ts +152 -0
- package/dist/render/unshown.js +80 -0
- package/dist/runtime/analysis.d.ts +94 -9
- package/dist/runtime/analysis.js +54 -9
- package/dist/runtime/assessment.d.ts +36 -2
- package/dist/runtime/assessment.js +27 -2
- package/dist/runtime/auto-apply-ceiling.d.ts +54 -0
- package/dist/runtime/auto-apply-ceiling.js +66 -0
- package/dist/runtime/checks.d.ts +148 -0
- package/dist/runtime/checks.js +112 -0
- package/dist/runtime/disposition.d.ts +96 -0
- package/dist/runtime/disposition.js +46 -0
- package/dist/runtime/gate.js +91 -10
- package/dist/runtime/index.d.ts +4 -0
- package/dist/runtime/index.js +4 -0
- package/dist/runtime/irreversibility.d.ts +64 -0
- package/dist/runtime/irreversibility.js +45 -0
- package/dist/runtime/nesting.d.ts +13 -1
- package/dist/runtime/nesting.js +41 -24
- package/dist/runtime/pipeline.d.ts +43 -0
- package/dist/runtime/pipeline.js +10 -2
- package/dist/runtime/policy-change.d.ts +93 -0
- package/dist/runtime/policy-change.js +305 -0
- package/dist/runtime/policy-log.d.ts +406 -0
- package/dist/runtime/policy-log.js +285 -0
- package/dist/runtime/policy.d.ts +8 -6
- package/dist/runtime/policy.js +5 -2
- package/dist/runtime/repointing.js +0 -0
- package/dist/runtime/reversibility.d.ts +11 -9
- package/dist/runtime/stakes.d.ts +129 -1
- package/dist/runtime/stakes.js +240 -26
- package/dist/runtime/vocabulary.d.ts +164 -7
- package/dist/runtime/vocabulary.js +181 -8
- package/dist/sdk/audit.d.ts +174 -3
- package/dist/sdk/audit.js +176 -17
- package/dist/sdk/catalogue.d.ts +9 -1
- package/dist/sdk/conformance.d.ts +37 -3
- package/dist/sdk/conformance.js +25 -4
- package/dist/sdk/definition.d.ts +129 -5
- package/dist/sdk/definition.js +66 -0
- package/dist/sdk/registry.d.ts +45 -2
- package/dist/sdk/registry.js +102 -1
- package/dist/signals/acted.contract.d.ts +21 -0
- package/dist/signals/acted.contract.js +236 -0
- package/dist/signals/acted.d.ts +359 -0
- package/dist/signals/acted.js +135 -0
- package/dist/signals/action-change.d.ts +507 -0
- package/dist/signals/action-change.js +265 -0
- package/dist/signals/action.d.ts +331 -0
- package/dist/signals/action.js +182 -0
- package/dist/signals/agenda.d.ts +585 -0
- package/dist/signals/agenda.js +295 -0
- package/dist/signals/applied-window.contract.d.ts +23 -0
- package/dist/signals/applied-window.contract.js +160 -0
- package/dist/signals/arrivals.contract.d.ts +21 -0
- package/dist/signals/arrivals.contract.js +180 -0
- package/dist/signals/arrivals.d.ts +375 -0
- package/dist/signals/arrivals.js +254 -0
- package/dist/signals/arriving.d.ts +210 -0
- package/dist/signals/arriving.js +133 -0
- package/dist/signals/audiences.d.ts +528 -0
- package/dist/signals/audiences.js +255 -0
- package/dist/signals/broadcast.d.ts +33 -17
- package/dist/signals/broadcast.js +255 -32
- package/dist/signals/change.d.ts +378 -0
- package/dist/signals/change.js +327 -0
- package/dist/signals/collect.d.ts +169 -34
- package/dist/signals/collect.js +186 -38
- package/dist/signals/conversion.d.ts +348 -0
- package/dist/signals/conversion.js +235 -0
- package/dist/signals/copy-change.d.ts +553 -0
- package/dist/signals/copy-change.js +377 -0
- package/dist/signals/copy.d.ts +337 -0
- package/dist/signals/copy.js +211 -0
- package/dist/signals/correlated.contract.d.ts +24 -0
- package/dist/signals/correlated.contract.js +94 -0
- package/dist/signals/counters.d.ts +97 -0
- package/dist/signals/counters.js +160 -0
- package/dist/signals/deliver.d.ts +23 -4
- package/dist/signals/deliver.js +34 -6
- package/dist/signals/deployment-change.d.ts +395 -0
- package/dist/signals/deployment-change.js +309 -0
- package/dist/signals/deployment.d.ts +278 -0
- package/dist/signals/deployment.js +178 -0
- package/dist/signals/door.d.ts +114 -0
- package/dist/signals/door.js +77 -0
- package/dist/signals/expire.d.ts +192 -0
- package/dist/signals/expire.js +213 -0
- package/dist/signals/fold.d.ts +10 -0
- package/dist/signals/fold.js +5 -1
- package/dist/signals/form-action.d.ts +302 -0
- package/dist/signals/form-action.js +169 -0
- package/dist/signals/form-copy.d.ts +523 -0
- package/dist/signals/form-copy.js +346 -0
- package/dist/signals/forms.d.ts +247 -0
- package/dist/signals/forms.js +147 -0
- package/dist/signals/frontier.d.ts +268 -0
- package/dist/signals/frontier.js +145 -0
- package/dist/signals/funnel-change.d.ts +548 -0
- package/dist/signals/funnel-change.js +361 -0
- package/dist/signals/funnel-hours.contract.d.ts +21 -0
- package/dist/signals/funnel-hours.contract.js +221 -0
- package/dist/signals/funnel-hours.d.ts +293 -0
- package/dist/signals/funnel-hours.js +99 -0
- package/dist/signals/funnel.d.ts +592 -0
- package/dist/signals/funnel.js +231 -0
- package/dist/signals/health.d.ts +694 -0
- package/dist/signals/health.js +573 -0
- package/dist/signals/index.d.ts +60 -0
- package/dist/signals/index.js +60 -0
- package/dist/signals/ingest.d.ts +56 -1
- package/dist/signals/ingest.js +91 -1
- package/dist/signals/inside.d.ts +190 -0
- package/dist/signals/inside.js +263 -0
- package/dist/signals/join.d.ts +56 -0
- package/dist/signals/join.js +60 -0
- package/dist/signals/journal.d.ts +123 -9
- package/dist/signals/kept.contract.d.ts +22 -0
- package/dist/signals/kept.contract.js +111 -0
- package/dist/signals/kinds.d.ts +8 -6
- package/dist/signals/kinds.js +14 -6
- package/dist/signals/library-action.d.ts +430 -0
- package/dist/signals/library-action.js +336 -0
- package/dist/signals/library-agenda-change.d.ts +324 -0
- package/dist/signals/library-agenda-change.js +199 -0
- package/dist/signals/library-agenda.d.ts +258 -0
- package/dist/signals/library-agenda.js +167 -0
- package/dist/signals/library-change.d.ts +477 -0
- package/dist/signals/library-change.js +335 -0
- package/dist/signals/library-copy-change.d.ts +498 -0
- package/dist/signals/library-copy-change.js +476 -0
- package/dist/signals/library-pace.d.ts +319 -0
- package/dist/signals/library-pace.js +305 -0
- package/dist/signals/library-reach-change.d.ts +646 -0
- package/dist/signals/library-reach-change.js +542 -0
- package/dist/signals/library-reach.d.ts +377 -0
- package/dist/signals/library-reach.js +227 -0
- package/dist/signals/library-senders-change.d.ts +457 -0
- package/dist/signals/library-senders-change.js +367 -0
- package/dist/signals/library-senders-reach-change.d.ts +486 -0
- package/dist/signals/library-senders-reach-change.js +538 -0
- package/dist/signals/library-senders-reach.d.ts +340 -0
- package/dist/signals/library-senders-reach.js +252 -0
- package/dist/signals/library-senders.d.ts +271 -0
- package/dist/signals/library-senders.js +180 -0
- package/dist/signals/library-word-reach-change.d.ts +567 -0
- package/dist/signals/library-word-reach-change.js +564 -0
- package/dist/signals/library.d.ts +306 -0
- package/dist/signals/library.js +178 -0
- package/dist/signals/memory.d.ts +9 -0
- package/dist/signals/memory.js +246 -14
- package/dist/signals/migrate.d.ts +20 -4
- package/dist/signals/migrate.js +269 -8
- package/dist/signals/notice.d.ts +389 -0
- package/dist/signals/notice.js +250 -0
- package/dist/signals/pace-change.d.ts +501 -0
- package/dist/signals/pace-change.js +310 -0
- package/dist/signals/pace.d.ts +296 -0
- package/dist/signals/pace.js +291 -0
- package/dist/signals/page-views.d.ts +365 -0
- package/dist/signals/page-views.js +218 -0
- package/dist/signals/part-pace.d.ts +378 -0
- package/dist/signals/part-pace.js +333 -0
- package/dist/signals/parts.d.ts +354 -0
- package/dist/signals/parts.js +232 -0
- package/dist/signals/postgres.d.ts +16 -2
- package/dist/signals/postgres.js +753 -76
- package/dist/signals/progress.d.ts +212 -0
- package/dist/signals/progress.js +150 -0
- package/dist/signals/ratios.d.ts +108 -0
- package/dist/signals/ratios.js +40 -0
- package/dist/signals/reach.d.ts +309 -0
- package/dist/signals/reach.js +93 -0
- package/dist/signals/readable.d.ts +34 -0
- package/dist/signals/readable.js +34 -0
- package/dist/signals/readership.d.ts +381 -0
- package/dist/signals/readership.js +308 -0
- package/dist/signals/region-pages.d.ts +173 -0
- package/dist/signals/region-pages.js +62 -0
- package/dist/signals/region.d.ts +287 -0
- package/dist/signals/region.js +198 -0
- package/dist/signals/retention.d.ts +163 -0
- package/dist/signals/retention.js +75 -0
- package/dist/signals/rhythm.d.ts +302 -0
- package/dist/signals/rhythm.js +262 -0
- package/dist/signals/rollup.d.ts +194 -4
- package/dist/signals/rollup.js +0 -0
- package/dist/signals/schema.d.ts +1069 -1
- package/dist/signals/schema.js +393 -3
- package/dist/signals/signal.d.ts +237 -11
- package/dist/signals/signal.js +70 -10
- package/dist/signals/silence-census.d.ts +205 -0
- package/dist/signals/silence-census.js +87 -0
- package/dist/signals/silences.d.ts +1147 -0
- package/dist/signals/silences.js +996 -0
- package/dist/signals/subtrees.d.ts +123 -0
- package/dist/signals/subtrees.js +102 -0
- package/dist/signals/tally.d.ts +262 -12
- package/dist/signals/unread.d.ts +292 -0
- package/dist/signals/unread.js +137 -0
- package/dist/signals/window-agenda.d.ts +276 -0
- package/dist/signals/window-agenda.js +83 -0
- package/dist/signals/window-figures.d.ts +148 -0
- package/dist/signals/window-figures.js +42 -0
- package/dist/signals/window-funnels.d.ts +88 -0
- package/dist/signals/window-funnels.js +47 -0
- package/dist/signals/window.d.ts +866 -0
- package/dist/signals/window.js +693 -0
- package/dist/signals/words.d.ts +24 -0
- package/dist/signals/words.js +24 -0
- package/dist/store/cache.d.ts +101 -0
- package/dist/store/cache.js +149 -0
- package/dist/store/history.d.ts +82 -0
- package/dist/store/history.js +36 -0
- package/dist/store/index.d.ts +30 -0
- package/dist/store/index.js +30 -0
- package/dist/store/memory.d.ts +2 -1
- package/dist/store/memory.js +48 -12
- package/dist/store/migrate.d.ts +106 -0
- package/dist/store/migrate.js +323 -7
- package/dist/store/postgres-applications.d.ts +4 -0
- package/dist/store/postgres-applications.js +197 -0
- package/dist/store/postgres-audience.d.ts +14 -0
- package/dist/store/postgres-audience.js +272 -0
- package/dist/store/postgres-holds.d.ts +10 -1
- package/dist/store/postgres-holds.js +116 -101
- package/dist/store/postgres-policy-log.d.ts +14 -0
- package/dist/store/postgres-policy-log.js +240 -0
- package/dist/store/postgres-projects.d.ts +4 -0
- package/dist/store/postgres-projects.js +217 -0
- package/dist/store/postgres.d.ts +17 -1
- package/dist/store/postgres.js +60 -9
- package/dist/store/replay.d.ts +102 -1
- package/dist/store/replay.js +190 -19
- package/dist/store/reseed.d.ts +238 -0
- package/dist/store/reseed.js +308 -0
- package/dist/store/schema.d.ts +762 -2
- package/dist/store/schema.js +218 -5
- package/dist/store/source.d.ts +57 -1
- package/dist/store/source.js +65 -1
- package/dist/store/store.d.ts +29 -6
- package/dist/submit/resolve.d.ts +1 -1
- package/dist/submit/resolve.js +2 -1
- package/dist/telemetry/calibration.d.ts +25 -0
- package/dist/telemetry/calibration.js +27 -1
- package/dist/telemetry/event.d.ts +391 -33
- package/dist/telemetry/event.js +84 -20
- package/dist/telemetry/index.d.ts +2 -0
- package/dist/telemetry/index.js +2 -0
- package/dist/telemetry/journal.d.ts +104 -3
- package/dist/telemetry/journal.js +9 -0
- package/dist/telemetry/lookup.d.ts +27 -0
- package/dist/telemetry/lookup.js +18 -0
- package/dist/telemetry/memory.js +33 -1
- package/dist/telemetry/migrate.js +22 -1
- package/dist/telemetry/postgres.d.ts +10 -1
- package/dist/telemetry/postgres.js +188 -90
- package/dist/telemetry/remeasure.d.ts +78 -0
- package/dist/telemetry/remeasure.js +83 -0
- package/dist/telemetry/retention.d.ts +2 -2
- package/dist/telemetry/schema.d.ts +17 -0
- package/dist/telemetry/schema.js +27 -1
- package/dist/telemetry/sink.d.ts +2 -2
- package/dist/telemetry/window.d.ts +135 -0
- package/dist/telemetry/window.js +101 -0
- package/dist/testing/application-contract.d.ts +14 -0
- package/dist/testing/application-contract.js +270 -0
- package/dist/testing/audience-overlay-contract.d.ts +31 -0
- package/dist/testing/audience-overlay-contract.js +354 -0
- package/dist/testing/contracts.d.ts +13 -7
- package/dist/testing/contracts.js +13 -7
- package/dist/testing/definitions.d.ts +78 -0
- package/dist/testing/definitions.js +134 -9
- package/dist/testing/doubles.d.ts +103 -0
- package/dist/testing/doubles.js +143 -0
- package/dist/testing/index.d.ts +2 -2
- package/dist/testing/index.js +2 -2
- package/dist/testing/journal-contract.js +297 -6
- package/dist/testing/model-contract.d.ts +110 -0
- package/dist/testing/model-contract.js +150 -0
- package/dist/testing/policy-log-contract.d.ts +26 -0
- package/dist/testing/policy-log-contract.js +344 -0
- package/dist/testing/project-contract.d.ts +14 -0
- package/dist/testing/project-contract.js +266 -0
- package/dist/testing/reader-signal-contract.d.ts +27 -2
- package/dist/testing/reader-signal-contract.js +475 -5
- package/dist/testing/store-contract.d.ts +7 -1
- package/dist/testing/store-contract.js +84 -3
- package/dist/theme/apply.d.ts +20 -1
- package/dist/theme/apply.js +5 -3
- package/dist/theme/contrast.d.ts +19 -14
- package/dist/theme/contrast.js +181 -17
- package/dist/theme/derive.d.ts +22 -0
- package/dist/theme/derive.js +54 -1
- package/dist/theme/library.js +1 -1
- package/dist/theme/measure.d.ts +34 -0
- package/dist/theme/measure.js +30 -1
- package/dist/theme/palettes.js +7 -7
- package/dist/theme/ramp.d.ts +64 -0
- package/dist/theme/ramp.js +114 -0
- package/dist/theme/registry.d.ts +9 -0
- package/dist/theme/registry.js +11 -1
- package/dist/theme/separation.d.ts +97 -3
- package/dist/theme/separation.js +75 -0
- package/dist/tree/apply.js +13 -0
- package/dist/tree/compare.d.ts +9 -0
- package/dist/tree/compare.js +18 -0
- package/dist/tree/mutation.d.ts +18 -0
- package/dist/tree/mutation.js +24 -12
- package/dist/tree/navigation.d.ts +5 -0
- package/dist/tree/navigation.js +32 -10
- package/dist/tree/outline.d.ts +7 -0
- package/dist/tree/outline.js +9 -5
- package/dist/write/computed.d.ts +60 -0
- package/dist/write/computed.js +61 -0
- package/dist/write/held.d.ts +59 -0
- package/dist/write/index.d.ts +5 -2
- package/dist/write/index.js +5 -2
- package/dist/write/reseed.d.ts +151 -0
- package/dist/write/reseed.js +184 -0
- package/dist/write/revert.js +2 -16
- package/package.json +25 -3
- package/dist/runtime/inverse-interpreter.d.ts +0 -90
- package/dist/runtime/inverse-interpreter.js +0 -56
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Custody of the two things a deployment needs to serve one page to more than
|
|
3
|
+
* one audience: the **rules** that sort readers, and the **form** each audience
|
|
4
|
+
* earns.
|
|
5
|
+
*
|
|
6
|
+
* [0359](../../decisions/0359-an-audience-rule-is-a-conjunction-of-scalar-clauses-and-a-composed-page-is-a-projection-of-a-revision.md)
|
|
7
|
+
* clause 6 left this out on purpose — *`composingTreeSourceFromStore` takes an
|
|
8
|
+
* `AudienceOverlaySource`, a seam and not a table* — so the composition could
|
|
9
|
+
* be built, tested and reviewed without a schema change under it. This is the
|
|
10
|
+
* table the seam was waiting for, and it is 0263's store dimension.
|
|
11
|
+
*
|
|
12
|
+
* **The rules are a log and the forms are rows, and the asymmetry is the
|
|
13
|
+
* decision in this file.** A rule decides which readers get which form, so
|
|
14
|
+
* editing one changes what every reader in that audience sees — without
|
|
15
|
+
* touching the page, its delta, or its log. Kept as a mutable row, that change
|
|
16
|
+
* would leave **no record anywhere**: the one thing Loom exists to make
|
|
17
|
+
* impossible. So a rule list is appended to, attributed and dense, exactly as
|
|
18
|
+
* the policy log is and for the same reason (0200). A form is a document being
|
|
19
|
+
* worked on; its history is the proposal that produced it, and a second log of
|
|
20
|
+
* every keystroke on it would be a record of drafting rather than of deciding.
|
|
21
|
+
*
|
|
22
|
+
* Nothing here evaluates a rule. `rule.ts` does that, in the customer's own
|
|
23
|
+
* process, over a context that never leaves it (0262) — this module only keeps
|
|
24
|
+
* what that evaluation is handed.
|
|
25
|
+
*/
|
|
26
|
+
import { z } from "zod";
|
|
27
|
+
import { treeIdSchema } from "../ids.js";
|
|
28
|
+
import { clampLimit } from "../paging.js";
|
|
29
|
+
import { err, mapResult, ok } from "../result.js";
|
|
30
|
+
import { treeDeltaSchema } from "../tree/delta.js";
|
|
31
|
+
import { audienceIdSchema } from "./audience.js";
|
|
32
|
+
import { audienceRuleSchema } from "./rule.js";
|
|
33
|
+
const audienceRuleRevisionSchema = z.object({
|
|
34
|
+
treeId: treeIdSchema,
|
|
35
|
+
revision: z.number().int().positive(),
|
|
36
|
+
/**
|
|
37
|
+
* Empty is a real state and the one a page reaches by having its last rule
|
|
38
|
+
* removed: *this page is served to everybody the same way, and somebody
|
|
39
|
+
* decided that*. The alternative spelling — delete the row — is the spelling
|
|
40
|
+
* that cannot be attributed.
|
|
41
|
+
*/
|
|
42
|
+
rules: z.array(audienceRuleSchema),
|
|
43
|
+
actor: z.string().min(1),
|
|
44
|
+
recordedAt: z.string().datetime(),
|
|
45
|
+
});
|
|
46
|
+
const audienceFormWithdrawalSchema = z.object({
|
|
47
|
+
actor: z.string().min(1),
|
|
48
|
+
at: z.string().datetime(),
|
|
49
|
+
});
|
|
50
|
+
const storedAudienceFormSchema = z.object({
|
|
51
|
+
treeId: treeIdSchema,
|
|
52
|
+
audienceId: audienceIdSchema,
|
|
53
|
+
delta: treeDeltaSchema,
|
|
54
|
+
actor: z.string().min(1),
|
|
55
|
+
authoredAt: z.string().datetime(),
|
|
56
|
+
/**
|
|
57
|
+
* `.optional()` rather than `.nullable()`, because the two backends spell
|
|
58
|
+
* *not withdrawn* differently — a `Map` holds no key, a column holds `NULL` —
|
|
59
|
+
* and the shape the contract compares is the one neither of them can skew.
|
|
60
|
+
* The Postgres reader maps its `NULL` to absent at the row, so only one
|
|
61
|
+
* spelling reaches here.
|
|
62
|
+
*/
|
|
63
|
+
withdrawn: audienceFormWithdrawalSchema.optional(),
|
|
64
|
+
});
|
|
65
|
+
export const describeAudienceOverlayError = (error) => {
|
|
66
|
+
switch (error.code) {
|
|
67
|
+
case "out-of-date":
|
|
68
|
+
return `${error.treeId}'s rules moved on: this edit is of revision ${error.expected}, the current one is ${error.current}`;
|
|
69
|
+
case "tree-mismatch":
|
|
70
|
+
return `a form for ${error.treeId} cannot carry a delta for ${error.delta}`;
|
|
71
|
+
case "unreadable":
|
|
72
|
+
return `${error.treeId}'s stored audience overlay did not parse: ${error.detail}`;
|
|
73
|
+
case "unavailable":
|
|
74
|
+
return `storage is unavailable: ${error.detail}`;
|
|
75
|
+
}
|
|
76
|
+
};
|
|
77
|
+
/**
|
|
78
|
+
* A row on the way out, checked rather than cast — the boundary every stored
|
|
79
|
+
* shape in this repository crosses the same way. These two outlive the code
|
|
80
|
+
* that wrote them by more than most: a rule is edited rarely and read on every
|
|
81
|
+
* request for as long as the page is published.
|
|
82
|
+
*/
|
|
83
|
+
export const parseAudienceRuleRevision = (row, treeId) => {
|
|
84
|
+
const parsed = audienceRuleRevisionSchema.safeParse(row);
|
|
85
|
+
return parsed.success
|
|
86
|
+
? ok(parsed.data)
|
|
87
|
+
: err({
|
|
88
|
+
code: "unreadable",
|
|
89
|
+
treeId,
|
|
90
|
+
detail: parsed.error.issues[0]?.message ?? "invalid",
|
|
91
|
+
});
|
|
92
|
+
};
|
|
93
|
+
export const parseStoredAudienceForm = (row, treeId) => {
|
|
94
|
+
const parsed = storedAudienceFormSchema.safeParse(row);
|
|
95
|
+
/**
|
|
96
|
+
* `withdrawn` is restated rather than spread through, because the schema's
|
|
97
|
+
* `.optional()` makes it an absent key and `StoredAudienceForm` makes it a
|
|
98
|
+
* present one holding `undefined`. Under `exactOptionalPropertyTypes` those
|
|
99
|
+
* are two different types, and the one every reader of a form tests with
|
|
100
|
+
* `=== undefined` is this one.
|
|
101
|
+
*/
|
|
102
|
+
return parsed.success
|
|
103
|
+
? ok({ ...parsed.data, withdrawn: parsed.data.withdrawn })
|
|
104
|
+
: err({
|
|
105
|
+
code: "unreadable",
|
|
106
|
+
treeId,
|
|
107
|
+
detail: parsed.error.issues[0]?.message ?? "invalid",
|
|
108
|
+
});
|
|
109
|
+
};
|
|
110
|
+
/**
|
|
111
|
+
* How much of a page's rule history one read answers.
|
|
112
|
+
*
|
|
113
|
+
* Bounded, because every read in this store is (0025's rule, as `store.ts`
|
|
114
|
+
* states it: *no caller can ask a store for everything it holds, whether by
|
|
115
|
+
* naming a large limit or by naming none*). Unpaged, which `ProjectStore.list`
|
|
116
|
+
* already is: a page's rules are edited rarely, the newest edits are the ones a
|
|
117
|
+
* screen shows, and a cursor is machinery that would be written now and first
|
|
118
|
+
* exercised by nobody. **Reaching past the limit is not offered** — the rows are
|
|
119
|
+
* there, and the read that walks them is for whoever first needs it.
|
|
120
|
+
*/
|
|
121
|
+
export const DEFAULT_AUDIENCE_RULE_HISTORY_LIMIT = 25;
|
|
122
|
+
export const MAX_AUDIENCE_RULE_HISTORY_LIMIT = 100;
|
|
123
|
+
export const clampAudienceRuleHistoryLimit = (limit) => clampLimit(limit, {
|
|
124
|
+
fallback: DEFAULT_AUDIENCE_RULE_HISTORY_LIMIT,
|
|
125
|
+
max: MAX_AUDIENCE_RULE_HISTORY_LIMIT,
|
|
126
|
+
});
|
|
127
|
+
/**
|
|
128
|
+
* Whether two rule lists say the same thing.
|
|
129
|
+
*
|
|
130
|
+
* **Order-sensitive, and that is the point**: 0359 clause 3 makes the order the
|
|
131
|
+
* precedence, so two lists holding the same rules in a different order are two
|
|
132
|
+
* different deployments and recording the second one is an edit. Compared by
|
|
133
|
+
* `JSON.stringify` rather than field by field because a rule is a closed JSON
|
|
134
|
+
* shape — `audienceRuleSchema` admits nothing a stringify would miss — and the
|
|
135
|
+
* alternative is a deep-equality walk that grows a case every time a clause
|
|
136
|
+
* does.
|
|
137
|
+
*/
|
|
138
|
+
const sameRules = (held, offered) => JSON.stringify(held) === JSON.stringify(offered);
|
|
139
|
+
/**
|
|
140
|
+
* What a `record` call should do, given the head it would append after.
|
|
141
|
+
*
|
|
142
|
+
* Shared rather than written per backend, for the reason `recordOutcomeOf` is:
|
|
143
|
+
* the staleness check and *what counts as unchanged* are the contract, not an
|
|
144
|
+
* implementation detail, so two backends cannot disagree about whether a save
|
|
145
|
+
* with nothing in it is an edit.
|
|
146
|
+
*/
|
|
147
|
+
export const audienceRulesOutcomeOf = (treeId, request, head) => {
|
|
148
|
+
const current = head?.revision ?? 0;
|
|
149
|
+
if (request.expectedRevision !== undefined && request.expectedRevision !== current) {
|
|
150
|
+
return err({
|
|
151
|
+
code: "out-of-date",
|
|
152
|
+
treeId,
|
|
153
|
+
expected: request.expectedRevision,
|
|
154
|
+
current,
|
|
155
|
+
});
|
|
156
|
+
}
|
|
157
|
+
if (head !== undefined && sameRules(head.rules, request.rules)) {
|
|
158
|
+
return ok({ outcome: "unchanged", revision: head });
|
|
159
|
+
}
|
|
160
|
+
/**
|
|
161
|
+
* Parsed rather than assembled, so a revision this store would accept and the
|
|
162
|
+
* database would refuse cannot be told apart by which one you used. It is also
|
|
163
|
+
* where an actor nobody named and a stamp that is not an instant are refused —
|
|
164
|
+
* both are caller-supplied strings, and both are load-bearing on a record of
|
|
165
|
+
* who changed who sees what.
|
|
166
|
+
*/
|
|
167
|
+
return mapResult(parseAudienceRuleRevision({
|
|
168
|
+
treeId,
|
|
169
|
+
revision: current + 1,
|
|
170
|
+
rules: request.rules,
|
|
171
|
+
actor: request.actor,
|
|
172
|
+
recordedAt: request.recordedAt,
|
|
173
|
+
}, treeId), (revision) => ({ outcome: "recorded", revision }));
|
|
174
|
+
};
|
|
175
|
+
/**
|
|
176
|
+
* The overlay a reader of the two halves assembles, shared so the backends
|
|
177
|
+
* cannot disagree about what *whole* means.
|
|
178
|
+
*/
|
|
179
|
+
export const audienceOverlayOf = (head, forms) => ({ rules: head?.rules ?? [], forms });
|
|
180
|
+
/**
|
|
181
|
+
* The forms the render path is given: every row that has not been withdrawn,
|
|
182
|
+
* without its attribution.
|
|
183
|
+
*
|
|
184
|
+
* **Shared for the reason `audienceRulesOutcomeOf` is.** Which rows compose is
|
|
185
|
+
* the contract and not an implementation detail, and a backend that answered a
|
|
186
|
+
* withdrawn form would serve a segment a change somebody undid — the exact
|
|
187
|
+
* fault 0403 exists to close, arriving as a disagreement between two stores
|
|
188
|
+
* that are each green against their own expectations.
|
|
189
|
+
*/
|
|
190
|
+
export const servedFormsOf = (stored) => stored
|
|
191
|
+
.filter((form) => form.withdrawn === undefined)
|
|
192
|
+
.map(({ audienceId, delta }) => ({ audienceId, delta }));
|
|
193
|
+
/**
|
|
194
|
+
* The listing a screen gets: **every** row, withdrawn ones included, with the
|
|
195
|
+
* deltas left behind (0376).
|
|
196
|
+
*/
|
|
197
|
+
export const audienceFormListingsOf = (stored) => stored.map(({ audienceId, delta, actor, authoredAt, withdrawn }) => ({
|
|
198
|
+
audienceId,
|
|
199
|
+
baseRevision: delta.baseRevision,
|
|
200
|
+
actor,
|
|
201
|
+
authoredAt,
|
|
202
|
+
withdrawn,
|
|
203
|
+
}));
|
|
204
|
+
/**
|
|
205
|
+
* The row a withdrawal leaves, given the one it found.
|
|
206
|
+
*
|
|
207
|
+
* Shared so neither backend can decide on its own that a withdrawal also
|
|
208
|
+
* rewrites `actor` or `authoredAt`. It does not: those two say who authored the
|
|
209
|
+
* form, and overwriting them with the person who withdrew it would lose the
|
|
210
|
+
* attribution 0376 clause 1 keeps — and make *who wrote this* unanswerable the
|
|
211
|
+
* moment somebody took it out of service.
|
|
212
|
+
*/
|
|
213
|
+
export const withdrawnFormOf = (held, request) => ({
|
|
214
|
+
...held,
|
|
215
|
+
withdrawn: { actor: request.actor, at: request.withdrawnAt },
|
|
216
|
+
});
|
|
217
|
+
//# sourceMappingURL=overlay-store.js.map
|
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Which audiences a reader is in, decided in the customer's own process.
|
|
3
|
+
*
|
|
4
|
+
* [0263](../../decisions/0263-a-page-is-a-base-tree-and-the-deltas-an-audience-earns.md)
|
|
5
|
+
* clause 1 says an audience is a **predicate over the opaque render context**,
|
|
6
|
+
* and clause 4 says the match happens in the data plane, per request, with
|
|
7
|
+
* nothing about the reader leaving it. This module is that predicate and that
|
|
8
|
+
* match, and it is the half of an audience `audience.ts` deliberately does not
|
|
9
|
+
* hold.
|
|
10
|
+
*
|
|
11
|
+
* **It does not contradict 0284, and the distinction is the whole design.**
|
|
12
|
+
* That record says the predicate *lives in the control plane's rules* and that
|
|
13
|
+
* *no column holds a rule, an expression, a context key or a matched value* —
|
|
14
|
+
* both of which are about where a rule is **authored and stored**. A rule is
|
|
15
|
+
* written in the portal and kept there; it is **shipped** to the customer's app
|
|
16
|
+
* and **evaluated** there, beside the base tree, which is the only place it can
|
|
17
|
+
* be evaluated without a request to Loom in front of every page view (0262).
|
|
18
|
+
* Nothing here stores a rule and nothing here learns what one means: a rule
|
|
19
|
+
* arrives as data, is read once, and answers a list of ids.
|
|
20
|
+
*
|
|
21
|
+
* So the control plane says *what `aud_eu` is*; this says *whether this reader
|
|
22
|
+
* is in it*; and `audience.ts` says *what the id looks like once both are done*.
|
|
23
|
+
*/
|
|
24
|
+
import { z } from "zod";
|
|
25
|
+
import type { JsonObject } from "../json.js";
|
|
26
|
+
import { type AudienceId } from "./audience.js";
|
|
27
|
+
/**
|
|
28
|
+
* The values a clause may compare against.
|
|
29
|
+
*
|
|
30
|
+
* JSON's scalars and no more. A context key holding an object or an array never
|
|
31
|
+
* matches — stated here rather than left to `===`, which would answer `false`
|
|
32
|
+
* for two structurally equal objects and look like a rule that does not work
|
|
33
|
+
* rather than one that was never offered. A host with structure in its context
|
|
34
|
+
* flattens it into keys, which is what a rule can read.
|
|
35
|
+
*/
|
|
36
|
+
export type AudienceValue = string | number | boolean | null;
|
|
37
|
+
/**
|
|
38
|
+
* One context key, and the values of it this clause accepts.
|
|
39
|
+
*
|
|
40
|
+
* `anyOf` rather than a single value because *locale is one of en-GB, en-IE* is
|
|
41
|
+
* the ordinary case and the alternative is one audience per locale, each with
|
|
42
|
+
* its own copy of the same delta — the maintenance failure 0263 rejected a tree
|
|
43
|
+
* per variant over, arriving one level down.
|
|
44
|
+
*/
|
|
45
|
+
export type AudienceClause = {
|
|
46
|
+
readonly key: string;
|
|
47
|
+
/** Non-empty: a clause accepting nothing is a rule that can never match. */
|
|
48
|
+
readonly anyOf: readonly AudienceValue[];
|
|
49
|
+
};
|
|
50
|
+
export declare const audienceClauseSchema: z.ZodObject<{
|
|
51
|
+
key: z.ZodString;
|
|
52
|
+
anyOf: z.ZodArray<z.ZodType<AudienceValue, z.ZodTypeDef, AudienceValue>, "many">;
|
|
53
|
+
}, "strip", z.ZodTypeAny, {
|
|
54
|
+
key: string;
|
|
55
|
+
anyOf: AudienceValue[];
|
|
56
|
+
}, {
|
|
57
|
+
key: string;
|
|
58
|
+
anyOf: AudienceValue[];
|
|
59
|
+
}>;
|
|
60
|
+
/**
|
|
61
|
+
* An audience, and what puts a reader in it.
|
|
62
|
+
*
|
|
63
|
+
* The clauses are a **conjunction** and there is no `or` at this level, because
|
|
64
|
+
* two rules both matching is already the answer to *or* — `audiencesFor`
|
|
65
|
+
* returns every audience that matched, and a reader in two audiences earns both
|
|
66
|
+
* deltas. A rule language with its own `or` would be a second way to say what
|
|
67
|
+
* the list of rules already says, and a third to maintain.
|
|
68
|
+
*
|
|
69
|
+
* **At least one clause.** A rule matching every reader is `aud_everyone`,
|
|
70
|
+
* which the base tree already serves by being the base; a second way to say
|
|
71
|
+
* *everyone* is a delta that silently applies to a deployment that thought it
|
|
72
|
+
* had none.
|
|
73
|
+
*/
|
|
74
|
+
export type AudienceRule = {
|
|
75
|
+
readonly audienceId: AudienceId;
|
|
76
|
+
readonly clauses: readonly AudienceClause[];
|
|
77
|
+
};
|
|
78
|
+
export declare const audienceRuleSchema: z.ZodObject<{
|
|
79
|
+
audienceId: z.ZodBranded<z.ZodString, "AudienceId">;
|
|
80
|
+
clauses: z.ZodArray<z.ZodObject<{
|
|
81
|
+
key: z.ZodString;
|
|
82
|
+
anyOf: z.ZodArray<z.ZodType<AudienceValue, z.ZodTypeDef, AudienceValue>, "many">;
|
|
83
|
+
}, "strip", z.ZodTypeAny, {
|
|
84
|
+
key: string;
|
|
85
|
+
anyOf: AudienceValue[];
|
|
86
|
+
}, {
|
|
87
|
+
key: string;
|
|
88
|
+
anyOf: AudienceValue[];
|
|
89
|
+
}>, "many">;
|
|
90
|
+
}, "strip", z.ZodTypeAny, {
|
|
91
|
+
audienceId: string & z.BRAND<"AudienceId">;
|
|
92
|
+
clauses: {
|
|
93
|
+
key: string;
|
|
94
|
+
anyOf: AudienceValue[];
|
|
95
|
+
}[];
|
|
96
|
+
}, {
|
|
97
|
+
audienceId: string;
|
|
98
|
+
clauses: {
|
|
99
|
+
key: string;
|
|
100
|
+
anyOf: AudienceValue[];
|
|
101
|
+
}[];
|
|
102
|
+
}>;
|
|
103
|
+
export declare const ruleMatches: (rule: AudienceRule, context: JsonObject) => boolean;
|
|
104
|
+
/**
|
|
105
|
+
* Every audience this reader is in, in the order the rules were given.
|
|
106
|
+
*
|
|
107
|
+
* **The order is the deployment's and it is load-bearing**, because two deltas
|
|
108
|
+
* reaching the same node resolve by the order they are applied in — so it must
|
|
109
|
+
* be something a deployment sets and reads back, rather than something a map's
|
|
110
|
+
* iteration or an id's spelling decides.
|
|
111
|
+
*
|
|
112
|
+
* An audience named by two matching rules appears **once, at its first
|
|
113
|
+
* position**. Its delta is one delta; applying it twice would double whatever
|
|
114
|
+
* it inserted, and the only reason two rules name one audience is that the
|
|
115
|
+
* deployment wrote two ways into the same group.
|
|
116
|
+
*
|
|
117
|
+
* A reader with no context is in no audience, which is the same answer as a
|
|
118
|
+
* context nothing matches: the base tree, unchanged.
|
|
119
|
+
*/
|
|
120
|
+
export declare const audiencesFor: (rules: readonly AudienceRule[], context: JsonObject | undefined) => readonly AudienceId[];
|
|
121
|
+
//# sourceMappingURL=rule.d.ts.map
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Which audiences a reader is in, decided in the customer's own process.
|
|
3
|
+
*
|
|
4
|
+
* [0263](../../decisions/0263-a-page-is-a-base-tree-and-the-deltas-an-audience-earns.md)
|
|
5
|
+
* clause 1 says an audience is a **predicate over the opaque render context**,
|
|
6
|
+
* and clause 4 says the match happens in the data plane, per request, with
|
|
7
|
+
* nothing about the reader leaving it. This module is that predicate and that
|
|
8
|
+
* match, and it is the half of an audience `audience.ts` deliberately does not
|
|
9
|
+
* hold.
|
|
10
|
+
*
|
|
11
|
+
* **It does not contradict 0284, and the distinction is the whole design.**
|
|
12
|
+
* That record says the predicate *lives in the control plane's rules* and that
|
|
13
|
+
* *no column holds a rule, an expression, a context key or a matched value* —
|
|
14
|
+
* both of which are about where a rule is **authored and stored**. A rule is
|
|
15
|
+
* written in the portal and kept there; it is **shipped** to the customer's app
|
|
16
|
+
* and **evaluated** there, beside the base tree, which is the only place it can
|
|
17
|
+
* be evaluated without a request to Loom in front of every page view (0262).
|
|
18
|
+
* Nothing here stores a rule and nothing here learns what one means: a rule
|
|
19
|
+
* arrives as data, is read once, and answers a list of ids.
|
|
20
|
+
*
|
|
21
|
+
* So the control plane says *what `aud_eu` is*; this says *whether this reader
|
|
22
|
+
* is in it*; and `audience.ts` says *what the id looks like once both are done*.
|
|
23
|
+
*/
|
|
24
|
+
import { z } from "zod";
|
|
25
|
+
import { audienceIdSchema } from "./audience.js";
|
|
26
|
+
const audienceValueSchema = z.union([
|
|
27
|
+
z.string(),
|
|
28
|
+
z.number().finite(),
|
|
29
|
+
z.boolean(),
|
|
30
|
+
z.null(),
|
|
31
|
+
]);
|
|
32
|
+
export const audienceClauseSchema = z.object({
|
|
33
|
+
key: z.string().min(1),
|
|
34
|
+
anyOf: z.array(audienceValueSchema).min(1),
|
|
35
|
+
});
|
|
36
|
+
export const audienceRuleSchema = z.object({
|
|
37
|
+
audienceId: audienceIdSchema,
|
|
38
|
+
clauses: z.array(audienceClauseSchema).min(1),
|
|
39
|
+
});
|
|
40
|
+
const scalar = (value) => value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean"
|
|
41
|
+
? value
|
|
42
|
+
: undefined;
|
|
43
|
+
/**
|
|
44
|
+
* Whether one clause is satisfied by the context.
|
|
45
|
+
*
|
|
46
|
+
* An absent key does not match, and neither does a key holding structure. Both
|
|
47
|
+
* are *this reader is not in this audience* rather than an error: a context is
|
|
48
|
+
* the host's to shape and a rule is written against the shape the host says it
|
|
49
|
+
* has, so a mismatch is a rule that does not apply rather than a request that
|
|
50
|
+
* cannot be served.
|
|
51
|
+
*/
|
|
52
|
+
const clauseMatches = (clause, context) => {
|
|
53
|
+
const value = scalar(context[clause.key]);
|
|
54
|
+
return value === undefined ? false : clause.anyOf.includes(value);
|
|
55
|
+
};
|
|
56
|
+
export const ruleMatches = (rule, context) => rule.clauses.every((clause) => clauseMatches(clause, context));
|
|
57
|
+
/**
|
|
58
|
+
* Every audience this reader is in, in the order the rules were given.
|
|
59
|
+
*
|
|
60
|
+
* **The order is the deployment's and it is load-bearing**, because two deltas
|
|
61
|
+
* reaching the same node resolve by the order they are applied in — so it must
|
|
62
|
+
* be something a deployment sets and reads back, rather than something a map's
|
|
63
|
+
* iteration or an id's spelling decides.
|
|
64
|
+
*
|
|
65
|
+
* An audience named by two matching rules appears **once, at its first
|
|
66
|
+
* position**. Its delta is one delta; applying it twice would double whatever
|
|
67
|
+
* it inserted, and the only reason two rules name one audience is that the
|
|
68
|
+
* deployment wrote two ways into the same group.
|
|
69
|
+
*
|
|
70
|
+
* A reader with no context is in no audience, which is the same answer as a
|
|
71
|
+
* context nothing matches: the base tree, unchanged.
|
|
72
|
+
*/
|
|
73
|
+
export const audiencesFor = (rules, context) => {
|
|
74
|
+
if (context === undefined)
|
|
75
|
+
return [];
|
|
76
|
+
return [...new Set(rules.filter((rule) => ruleMatches(rule, context)).map((rule) => rule.audienceId))];
|
|
77
|
+
};
|
|
78
|
+
//# sourceMappingURL=rule.js.map
|
package/dist/cli/index.d.ts
CHANGED
|
@@ -1,8 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* The commands `loom` runs
|
|
3
|
-
*
|
|
4
|
-
*
|
|
5
|
-
* same runtime a server would use.
|
|
2
|
+
* The commands `loom` runs: scaffolding a new project, and adding a primitive
|
|
3
|
+
* to one. `parseArguments` takes `init`, `add primitive` and `--help`, and
|
|
4
|
+
* nothing here drives a proposal from the terminal.
|
|
6
5
|
*/
|
|
7
6
|
export * from "./args.js";
|
|
8
7
|
export * from "./filesystem.js";
|
package/dist/cli/index.js
CHANGED
|
@@ -1,8 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* The commands `loom` runs
|
|
3
|
-
*
|
|
4
|
-
*
|
|
5
|
-
* same runtime a server would use.
|
|
2
|
+
* The commands `loom` runs: scaffolding a new project, and adding a primitive
|
|
3
|
+
* to one. `parseArguments` takes `init`, `add primitive` and `--help`, and
|
|
4
|
+
* nothing here drives a proposal from the terminal.
|
|
6
5
|
*/
|
|
7
6
|
export * from "./args.js";
|
|
8
7
|
export * from "./filesystem.js";
|
package/dist/cli/templates.js
CHANGED
|
@@ -117,6 +117,25 @@ describe("the primitive registry", () => {
|
|
|
117
117
|
expect(audit.notProbeable, describeRegistryAudit(audit)).toEqual([])
|
|
118
118
|
})
|
|
119
119
|
|
|
120
|
+
/**
|
|
121
|
+
* The audit probes from the empty props bag, which the schema of a primitive
|
|
122
|
+
* requiring anything refuses. That is fine for one that hands its props
|
|
123
|
+
* straight to React and not for one that reads them — \`name.toUpperCase()\`
|
|
124
|
+
* on a prop nobody passed throws, and nothing above can judge a component
|
|
125
|
+
* that was never successfully called.
|
|
126
|
+
*
|
|
127
|
+
* The fix is not to loosen the schema. Hand the audit a props bag it accepts:
|
|
128
|
+
*
|
|
129
|
+
* \`\`\`ts
|
|
130
|
+
* auditRegistry(registry, { props: new Map([["your.primitive", [{ name: "Example" }]]]) })
|
|
131
|
+
* \`\`\`
|
|
132
|
+
*/
|
|
133
|
+
it("has no primitives the audit could not configure", () => {
|
|
134
|
+
const audit = auditRegistry(registry)
|
|
135
|
+
|
|
136
|
+
expect(audit.notConfigured, describeRegistryAudit(audit)).toEqual([])
|
|
137
|
+
})
|
|
138
|
+
|
|
120
139
|
/**
|
|
121
140
|
* The one that stops a page rather than a portal: a component that throws on a
|
|
122
141
|
* value its own schema accepts is one a tree the validator *accepted* can take
|
package/dist/data/adapter.d.ts
CHANGED
|
@@ -48,6 +48,14 @@ export interface DataAdapter<TParams = JsonObject, TAnswer extends JsonValue = J
|
|
|
48
48
|
* be told about and a diagnostic says out loud; none of them is an exception
|
|
49
49
|
* anyone catches.
|
|
50
50
|
*
|
|
51
|
+
* `invalid-answer` and `unreadable-answer` are the other pair, and the two
|
|
52
|
+
* schemas behind them are why. An answer is refused by the **source's** own
|
|
53
|
+
* declaration, which is a claim about a host's database; or it satisfies that
|
|
54
|
+
* and is refused by the **primitive's**, which is a claim about what can go on a
|
|
55
|
+
* page (0180). The first is fixed by whoever owns the data and the second by
|
|
56
|
+
* whoever bound this node to that source, so a reader holding one code knows
|
|
57
|
+
* which file to open.
|
|
58
|
+
*
|
|
51
59
|
* `no-such-source` and `not-resolved` are the pair worth keeping apart, and they
|
|
52
60
|
* were one code until 12 September. An unregistered source is fixed in the
|
|
53
61
|
* registry by whoever owns the data; a binding nothing resolved is fixed in the
|
|
@@ -58,7 +66,7 @@ export interface DataAdapter<TParams = JsonObject, TAnswer extends JsonValue = J
|
|
|
58
66
|
* counting reasons.
|
|
59
67
|
*/
|
|
60
68
|
export type DataUnavailable = {
|
|
61
|
-
readonly reason: "no-such-source" | "not-resolved" | "invalid-params" | "invalid-answer" | "adapter-threw" | SourceFailure["code"];
|
|
69
|
+
readonly reason: "no-such-source" | "not-resolved" | "invalid-params" | "invalid-answer" | "unreadable-answer" | "adapter-threw" | SourceFailure["code"];
|
|
62
70
|
readonly detail: string;
|
|
63
71
|
};
|
|
64
72
|
export declare const describeDataUnavailable: (unavailable: DataUnavailable) => string;
|
package/dist/data/adapter.js
CHANGED
|
@@ -11,6 +11,8 @@ export const describeDataUnavailable = (unavailable) => {
|
|
|
11
11
|
return `the params in the tree are not what the source accepts — ${unavailable.detail}`;
|
|
12
12
|
case "invalid-answer":
|
|
13
13
|
return `the source answered with something its own schema refuses — ${unavailable.detail}`;
|
|
14
|
+
case "unreadable-answer":
|
|
15
|
+
return `the source answered, and the primitive reading it says that is not a shape it can draw — ${unavailable.detail}`;
|
|
14
16
|
case "adapter-threw":
|
|
15
17
|
return `the source threw instead of answering — ${unavailable.detail}`;
|
|
16
18
|
case "unavailable":
|
package/dist/data/plan.js
CHANGED
|
Binary file
|
|
@@ -46,6 +46,28 @@ export declare const NO_DATA: NodeData;
|
|
|
46
46
|
* is the kind of detail every caller gets right once and then forgets.
|
|
47
47
|
*/
|
|
48
48
|
export declare const nodeDataOf: (answers: Readonly<Record<string, DataOutcome>>) => NodeData;
|
|
49
|
+
/**
|
|
50
|
+
* One planned request's answer: what a source gave back, or the named reason
|
|
51
|
+
* there is none.
|
|
52
|
+
*
|
|
53
|
+
* Named rather than left as its structure because it is half of a seam a host
|
|
54
|
+
* has to carry, and a loader cannot write `Result<JsonValue, DataUnavailable>`
|
|
55
|
+
* into its own return type without reaching past the entry points it is meant
|
|
56
|
+
* to use.
|
|
57
|
+
*/
|
|
58
|
+
export type DataAnswer = Result<JsonValue, DataUnavailable>;
|
|
59
|
+
/**
|
|
60
|
+
* Every answer a resolution was built from, as plain data.
|
|
61
|
+
*
|
|
62
|
+
* Pairs and not a `ReadonlyMap`, because the only reason to publish these is
|
|
63
|
+
* that they travel. `JSON.stringify` turns a `Map` into `{}` and says nothing
|
|
64
|
+
* about it, so a host that serialised one would send an empty object, rebuild a
|
|
65
|
+
* resolution that answers nothing, and get a page of `data-unresolved`
|
|
66
|
+
* diagnostics with no hint that the answers were lost in transit rather than
|
|
67
|
+
* never fetched. An array of pairs is the shape every boundary already carries,
|
|
68
|
+
* and `new Map(answers)` is what `buildDataResolution` takes (0281).
|
|
69
|
+
*/
|
|
70
|
+
export type DataAnswers = readonly (readonly [RequestKey, DataAnswer])[];
|
|
49
71
|
/** What a node's data could not do, in the seam's own vocabulary. */
|
|
50
72
|
export type NodeDataProblem = {
|
|
51
73
|
readonly kind: "misdeclared";
|
|
@@ -87,5 +109,5 @@ export declare const EMPTY_DATA_RESOLUTION: DataResolution;
|
|
|
87
109
|
* the same resolution, which is what makes the failure paths testable without a
|
|
88
110
|
* fake adapter for each one.
|
|
89
111
|
*/
|
|
90
|
-
export declare const buildDataResolution: (plan: DataPlan, answers: ReadonlyMap<RequestKey,
|
|
112
|
+
export declare const buildDataResolution: (plan: DataPlan, answers: ReadonlyMap<RequestKey, DataAnswer>) => DataResolution;
|
|
91
113
|
//# sourceMappingURL=resolution.d.ts.map
|
package/dist/data/resolve.d.ts
CHANGED
|
@@ -2,7 +2,7 @@ import type { JsonObject } from "../json.js";
|
|
|
2
2
|
import type { LoomTree } from "../tree/tree.js";
|
|
3
3
|
import type { DataRegistry } from "./adapter.js";
|
|
4
4
|
import { type DataPlan } from "./plan.js";
|
|
5
|
-
import { type DataResolution } from "./resolution.js";
|
|
5
|
+
import { type DataAnswers, type DataResolution } from "./resolution.js";
|
|
6
6
|
/**
|
|
7
7
|
* The one step in serving a page that does IO.
|
|
8
8
|
*
|
|
@@ -23,7 +23,7 @@ import { type DataResolution } from "./resolution.js";
|
|
|
23
23
|
export type ResolveDataOptions = {
|
|
24
24
|
readonly registry: DataRegistry;
|
|
25
25
|
/** Passed through to every adapter — the render request's host context. */
|
|
26
|
-
readonly context?: JsonObject;
|
|
26
|
+
readonly context?: JsonObject | undefined;
|
|
27
27
|
/**
|
|
28
28
|
* How long any one source is given, each independently of the others. Defaults
|
|
29
29
|
* to `DEFAULT_SOURCE_CEILING_MS`; there is no way to wait forever (0140).
|
|
@@ -40,7 +40,34 @@ export type ResolveDataOptions = {
|
|
|
40
40
|
* against a budget the others had already spent.
|
|
41
41
|
*/
|
|
42
42
|
export declare const DEFAULT_SOURCE_CEILING_MS = 10000;
|
|
43
|
-
|
|
43
|
+
/**
|
|
44
|
+
* A resolution, and the answers it was built from.
|
|
45
|
+
*
|
|
46
|
+
* It *is* a `DataResolution`, so a caller that only renders reads nothing new
|
|
47
|
+
* and changes nothing. The extra field is for the host that fetches in one
|
|
48
|
+
* place and renders in another — the arrangement every React framework pushes a
|
|
49
|
+
* host towards, and the one this package could not serve: a resolution is two
|
|
50
|
+
* closures, and a closure cannot cross from a server component to a client one.
|
|
51
|
+
* The answers can, so the far side rebuilds from them:
|
|
52
|
+
*
|
|
53
|
+
* ```ts
|
|
54
|
+
* // where the fetching happens
|
|
55
|
+
* const { answers } = await resolveTreeData(tree, { registry })
|
|
56
|
+
* // wherever the walk happens, given the same tree
|
|
57
|
+
* const data = buildDataResolution(planTreeData(tree), new Map(answers))
|
|
58
|
+
* ```
|
|
59
|
+
*
|
|
60
|
+
* Re-planning rather than carrying the resolution is what keeps the one thing a
|
|
61
|
+
* caller must not get wrong inside the package: *which requests were asked*.
|
|
62
|
+
* Read off the plan it is a guess, and the obvious guess is wrong — a node whose
|
|
63
|
+
* declaration could not be read at all appears in `plan.problems` and never in
|
|
64
|
+
* `plan.bindings`, so a carrier built from the bindings drops exactly the nodes
|
|
65
|
+
* whose diagnostics matter most (0281).
|
|
66
|
+
*/
|
|
67
|
+
export interface ResolvedData extends DataResolution {
|
|
68
|
+
readonly answers: DataAnswers;
|
|
69
|
+
}
|
|
70
|
+
export declare const resolveDataPlan: (plan: DataPlan, options: ResolveDataOptions) => Promise<ResolvedData>;
|
|
44
71
|
/** Plan and resolve in one step, for the ordinary caller that does both. */
|
|
45
|
-
export declare const resolveTreeData: (tree: LoomTree, options: ResolveDataOptions) => Promise<
|
|
72
|
+
export declare const resolveTreeData: (tree: LoomTree, options: ResolveDataOptions) => Promise<ResolvedData>;
|
|
46
73
|
//# sourceMappingURL=resolve.d.ts.map
|
package/dist/data/resolve.js
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { ceilingOf, describeCeiling, withCeiling } from "../deadline.js";
|
|
2
|
+
import { describeRegistered } from "../registered.js";
|
|
2
3
|
import { err } from "../result.js";
|
|
3
4
|
import { planTreeData, planIsEmpty } from "./plan.js";
|
|
4
5
|
import { buildDataResolution, EMPTY_DATA_RESOLUTION, } from "./resolution.js";
|
|
@@ -17,20 +18,27 @@ const askOne = async (source, params, options) => {
|
|
|
17
18
|
if (!registered) {
|
|
18
19
|
return err({
|
|
19
20
|
reason: "no-such-source",
|
|
20
|
-
detail: `registered: ${options.registry.sources.map((entry) => entry.id)
|
|
21
|
+
detail: `registered: ${describeRegistered(source, options.registry.sources.map((entry) => entry.id))}`,
|
|
21
22
|
});
|
|
22
23
|
}
|
|
23
24
|
const ceiling = ceilingOf(options.ceilingMs, DEFAULT_SOURCE_CEILING_MS);
|
|
24
25
|
return withCeiling(ceiling, () => err({ reason: "unavailable", detail: `no answer in ${describeCeiling(ceiling)}` }), (signal) => registered.answer(params, options.context, signal));
|
|
25
26
|
};
|
|
27
|
+
const NO_ANSWERS = Object.freeze([]);
|
|
28
|
+
/** The resolution of a plan that asks nothing, which asked nothing. */
|
|
29
|
+
const EMPTY_RESOLVED_DATA = Object.freeze({
|
|
30
|
+
...EMPTY_DATA_RESOLUTION,
|
|
31
|
+
answers: NO_ANSWERS,
|
|
32
|
+
});
|
|
26
33
|
export const resolveDataPlan = async (plan, options) => {
|
|
27
34
|
if (planIsEmpty(plan))
|
|
28
|
-
return
|
|
35
|
+
return EMPTY_RESOLVED_DATA;
|
|
29
36
|
const answered = await Promise.all(plan.requests.map(async (request) => [
|
|
30
37
|
request.key,
|
|
31
38
|
await askOne(request.source, request.params, options),
|
|
32
39
|
]));
|
|
33
|
-
|
|
40
|
+
const answers = Object.freeze(answered);
|
|
41
|
+
return { ...buildDataResolution(plan, new Map(answers)), answers };
|
|
34
42
|
};
|
|
35
43
|
/** Plan and resolve in one step, for the ordinary caller that does both. */
|
|
36
44
|
export const resolveTreeData = async (tree, options) => resolveDataPlan(planTreeData(tree), options);
|
package/dist/ids.d.ts
CHANGED
|
@@ -39,6 +39,16 @@ export interface IdFactory {
|
|
|
39
39
|
readonly intentId: () => IntentId;
|
|
40
40
|
readonly proposalId: () => ProposalId;
|
|
41
41
|
}
|
|
42
|
+
/**
|
|
43
|
+
* The body of a random id, which is the part after the prefix.
|
|
44
|
+
*
|
|
45
|
+
* Exported because an application id and a project id are minted outside this
|
|
46
|
+
* module — by the control plane when somebody registers, rather than by an
|
|
47
|
+
* `IdFactory` during a render — and the alternative was either widening that
|
|
48
|
+
* interface with two members no renderer calls, or a second copy of this that
|
|
49
|
+
* drifts.
|
|
50
|
+
*/
|
|
51
|
+
export declare const randomIdBody: () => string;
|
|
42
52
|
export declare const randomIdFactory: IdFactory;
|
|
43
53
|
/**
|
|
44
54
|
* Deterministic ids for tests and for replaying a recorded session. Counters
|