@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,26 @@
|
|
|
1
|
+
import type { CataloguedProp } from "../catalogue.js";
|
|
2
|
+
import type { DataRegistry } from "./adapter.js";
|
|
3
|
+
import type { SourceId } from "./source.js";
|
|
4
|
+
/**
|
|
5
|
+
* What a deployment can ask about, as data.
|
|
6
|
+
*
|
|
7
|
+
* The same projection `catalogueOf` makes for primitives, and it exists for the
|
|
8
|
+
* same reason: a model asked to put someone's services on their page can only
|
|
9
|
+
* name a source it was told about, and a source it was never told about is one
|
|
10
|
+
* it can only guess at. A registry is the allowlist; the catalogue is how the
|
|
11
|
+
* allowlist gets shown to whoever is choosing.
|
|
12
|
+
*/
|
|
13
|
+
export type CataloguedSource = {
|
|
14
|
+
readonly id: SourceId;
|
|
15
|
+
/** One line, written by the source's author, about what it answers. */
|
|
16
|
+
readonly description: string;
|
|
17
|
+
/**
|
|
18
|
+
* Declared params, name-sorted. `undefined` when the declared schema is not an
|
|
19
|
+
* object schema and its keys therefore cannot be enumerated — unknown, which
|
|
20
|
+
* is not the same claim as "none".
|
|
21
|
+
*/
|
|
22
|
+
readonly params: readonly CataloguedProp[] | undefined;
|
|
23
|
+
};
|
|
24
|
+
export type DataCatalogue = readonly CataloguedSource[];
|
|
25
|
+
export declare const dataCatalogue: (registry: DataRegistry) => DataCatalogue;
|
|
26
|
+
//# sourceMappingURL=catalogue.d.ts.map
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Questions a tree asks and cannot answer itself.
|
|
3
|
+
*
|
|
4
|
+
* A node names a source, the source is resolved once per request before the render
|
|
5
|
+
* walk, and the answer — or a named reason there is none — reaches the primitive.
|
|
6
|
+
*/
|
|
7
|
+
export * from "./adapter.js";
|
|
8
|
+
export * from "./binding.js";
|
|
9
|
+
export * from "./catalogue.js";
|
|
10
|
+
export * from "./plan.js";
|
|
11
|
+
export * from "./resolution.js";
|
|
12
|
+
export * from "./resolve.js";
|
|
13
|
+
export * from "./source.js";
|
|
14
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Questions a tree asks and cannot answer itself.
|
|
3
|
+
*
|
|
4
|
+
* A node names a source, the source is resolved once per request before the render
|
|
5
|
+
* walk, and the answer — or a named reason there is none — reaches the primitive.
|
|
6
|
+
*/
|
|
7
|
+
export * from "./adapter.js";
|
|
8
|
+
export * from "./binding.js";
|
|
9
|
+
export * from "./catalogue.js";
|
|
10
|
+
export * from "./plan.js";
|
|
11
|
+
export * from "./resolution.js";
|
|
12
|
+
export * from "./resolve.js";
|
|
13
|
+
export * from "./source.js";
|
|
14
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
import type { NodeId } from "../ids.js";
|
|
2
|
+
import type { JsonObject } from "../json.js";
|
|
3
|
+
import type { LoomNode } from "../tree/node.js";
|
|
4
|
+
import type { LoomTree } from "../tree/tree.js";
|
|
5
|
+
import { type BindingError } from "./binding.js";
|
|
6
|
+
import type { BindingName, SourceId } from "./source.js";
|
|
7
|
+
/**
|
|
8
|
+
* What a tree wants to know, worked out before anything is asked.
|
|
9
|
+
*
|
|
10
|
+
* Planning is a pure function of the tree, which is the whole reason the seam is
|
|
11
|
+
* shaped this way. `renderLoomTree` is synchronous and does no IO — that is what
|
|
12
|
+
* lets it run inside a Server Component and what makes two renders of one
|
|
13
|
+
* revision agree — and resolving a binding is IO by definition. So the tree is
|
|
14
|
+
* read once, in a pass that only reads, and the asking happens outside the
|
|
15
|
+
* renderer entirely (0058).
|
|
16
|
+
*
|
|
17
|
+
* Identical questions are asked once. Hermes' `about` block bound three fields
|
|
18
|
+
* to one profile, and three round trips for one row is a cost paid on every
|
|
19
|
+
* request forever; two bindings naming the same source with the same params
|
|
20
|
+
* share a key here and therefore share an answer.
|
|
21
|
+
*/
|
|
22
|
+
/** Identifies one question. Two bindings sharing it share an answer. */
|
|
23
|
+
export type RequestKey = string;
|
|
24
|
+
export type PlannedRequest = {
|
|
25
|
+
readonly key: RequestKey;
|
|
26
|
+
readonly source: SourceId;
|
|
27
|
+
readonly params: JsonObject;
|
|
28
|
+
};
|
|
29
|
+
export type PlannedBinding = {
|
|
30
|
+
readonly nodeId: NodeId;
|
|
31
|
+
readonly name: BindingName;
|
|
32
|
+
readonly key: RequestKey;
|
|
33
|
+
};
|
|
34
|
+
/** A node whose `loom:data` could not be read at all. */
|
|
35
|
+
export type BindingProblem = {
|
|
36
|
+
readonly nodeId: NodeId;
|
|
37
|
+
readonly error: BindingError;
|
|
38
|
+
};
|
|
39
|
+
export type DataPlan = {
|
|
40
|
+
/** Deduplicated, in first-encountered order. */
|
|
41
|
+
readonly requests: readonly PlannedRequest[];
|
|
42
|
+
readonly bindings: readonly PlannedBinding[];
|
|
43
|
+
readonly problems: readonly BindingProblem[];
|
|
44
|
+
};
|
|
45
|
+
export declare const EMPTY_DATA_PLAN: DataPlan;
|
|
46
|
+
export declare const planIsEmpty: (plan: DataPlan) => boolean;
|
|
47
|
+
export declare const planTreeData: (tree: LoomTree) => DataPlan;
|
|
48
|
+
/**
|
|
49
|
+
* The same plan, for a root that is not a stored tree.
|
|
50
|
+
*
|
|
51
|
+
* Exactly the split `planSubmissionsIn` carries next door, for the reason its
|
|
52
|
+
* comment gives: the runtime needs a plan for a tree that exists only as the
|
|
53
|
+
* result of applying a delta, which is a node and never a `LoomTree`. Reading
|
|
54
|
+
* the bindings twice would be two walks that had to agree about which
|
|
55
|
+
* declarations parse, and the second one would drift.
|
|
56
|
+
*/
|
|
57
|
+
export declare const planDataIn: (root: LoomNode) => DataPlan;
|
|
58
|
+
//# sourceMappingURL=plan.d.ts.map
|
|
Binary file
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
import type { NodeId } from "../ids.js";
|
|
2
|
+
import type { JsonValue } from "../json.js";
|
|
3
|
+
import type { Result } from "../result.js";
|
|
4
|
+
import type { BindingError } from "./binding.js";
|
|
5
|
+
import type { DataUnavailable } from "./adapter.js";
|
|
6
|
+
import type { DataPlan, RequestKey } from "./plan.js";
|
|
7
|
+
import type { BindingName, SourceId } from "./source.js";
|
|
8
|
+
/**
|
|
9
|
+
* The answers, indexed the way a render walk needs them.
|
|
10
|
+
*
|
|
11
|
+
* Nothing here knows about React, and that is deliberate: the seam is asking a
|
|
12
|
+
* host questions about its own data, which is not a rendering concern. The
|
|
13
|
+
* renderer depends on this module; this module depends on nothing above it, so a
|
|
14
|
+
* host can plan and resolve a tree's data without loading the renderer at all.
|
|
15
|
+
*/
|
|
16
|
+
/**
|
|
17
|
+
* A binding either has an answer or has a named reason it does not. There is no
|
|
18
|
+
* third state, and in particular there is no way to express "empty" as a failure
|
|
19
|
+
* — a source that legitimately answers with nothing answers `ready` with an
|
|
20
|
+
* empty list. Collapsing the two is the mistake the portal spent a run undoing:
|
|
21
|
+
* a reader who takes "we could not reach your services" for "you have no
|
|
22
|
+
* services" concludes their data is gone.
|
|
23
|
+
*/
|
|
24
|
+
export type DataOutcome = {
|
|
25
|
+
readonly status: "ready";
|
|
26
|
+
readonly value: JsonValue;
|
|
27
|
+
} | {
|
|
28
|
+
readonly status: "unavailable";
|
|
29
|
+
readonly unavailable: DataUnavailable;
|
|
30
|
+
};
|
|
31
|
+
/**
|
|
32
|
+
* One node's answers, by binding name. Null-prototype for the reason
|
|
33
|
+
* `staticPrimitiveResolver` gives: binding names are identifiers and
|
|
34
|
+
* `constructor` and `valueOf` are valid ones, so a plain object would answer
|
|
35
|
+
* `loom.data.constructor` with a function off `Object.prototype`.
|
|
36
|
+
*/
|
|
37
|
+
export type NodeData = Readonly<Record<string, DataOutcome>>;
|
|
38
|
+
export declare const NO_DATA: NodeData;
|
|
39
|
+
/**
|
|
40
|
+
* One node's answers, built from a plain record.
|
|
41
|
+
*
|
|
42
|
+
* `buildDataResolution` is the only thing in the runtime that produces a
|
|
43
|
+
* `NodeData` from a plan, and everything else that needs one — a probe handed
|
|
44
|
+
* answers, a test, a fixture — was writing `Object.create(null)` and a loop.
|
|
45
|
+
* The null prototype is the whole reason this is not an object literal, and it
|
|
46
|
+
* is the kind of detail every caller gets right once and then forgets.
|
|
47
|
+
*/
|
|
48
|
+
export declare const nodeDataOf: (answers: Readonly<Record<string, DataOutcome>>) => NodeData;
|
|
49
|
+
/** What a node's data could not do, in the seam's own vocabulary. */
|
|
50
|
+
export type NodeDataProblem = {
|
|
51
|
+
readonly kind: "misdeclared";
|
|
52
|
+
readonly error: BindingError;
|
|
53
|
+
} | {
|
|
54
|
+
readonly kind: "unavailable";
|
|
55
|
+
readonly name: BindingName;
|
|
56
|
+
readonly source: SourceId;
|
|
57
|
+
readonly unavailable: DataUnavailable;
|
|
58
|
+
};
|
|
59
|
+
export interface DataResolution {
|
|
60
|
+
/**
|
|
61
|
+
* Always answers. `NO_DATA` means *this node asked for nothing* — it is not a
|
|
62
|
+
* way to say "I have no answers for you", and an implementation that uses it as
|
|
63
|
+
* one is reporting an absence as a satisfied request.
|
|
64
|
+
*
|
|
65
|
+
* The render walk holds a resolution to that: a node that declares bindings and
|
|
66
|
+
* gets `NO_DATA` with no problems beside it earns a `data-unresolved`
|
|
67
|
+
* diagnostic, because the only way to be in that state honestly is to have been
|
|
68
|
+
* built from a different tree's plan.
|
|
69
|
+
*/
|
|
70
|
+
readonly lookup: (nodeId: NodeId) => NodeData;
|
|
71
|
+
readonly problemsFor: (nodeId: NodeId) => readonly NodeDataProblem[];
|
|
72
|
+
}
|
|
73
|
+
/**
|
|
74
|
+
* The resolution of a plan that asks nothing, which is the only tree it is
|
|
75
|
+
* correct for.
|
|
76
|
+
*
|
|
77
|
+
* It exists so `resolveDataPlan` can short-circuit an empty plan, and its name
|
|
78
|
+
* makes it the obvious thing to reach for when writing a composition root that
|
|
79
|
+
* has no data — which is the one use it does not serve. Handed a tree whose nodes
|
|
80
|
+
* do bind, it answers `NO_DATA` for all of them, and every one of those bindings
|
|
81
|
+
* is reported `unresolved` by the walk rather than disappearing.
|
|
82
|
+
*/
|
|
83
|
+
export declare const EMPTY_DATA_RESOLUTION: DataResolution;
|
|
84
|
+
/**
|
|
85
|
+
* Folds a plan and its answers into the two lookups the walk uses. Separated
|
|
86
|
+
* from `resolveDataPlan` because it is pure: given the same answers it builds
|
|
87
|
+
* the same resolution, which is what makes the failure paths testable without a
|
|
88
|
+
* fake adapter for each one.
|
|
89
|
+
*/
|
|
90
|
+
export declare const buildDataResolution: (plan: DataPlan, answers: ReadonlyMap<RequestKey, Result<JsonValue, DataUnavailable>>) => DataResolution;
|
|
91
|
+
//# sourceMappingURL=resolution.d.ts.map
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
export const NO_DATA = Object.freeze(Object.create(null));
|
|
2
|
+
/**
|
|
3
|
+
* One node's answers, built from a plain record.
|
|
4
|
+
*
|
|
5
|
+
* `buildDataResolution` is the only thing in the runtime that produces a
|
|
6
|
+
* `NodeData` from a plan, and everything else that needs one — a probe handed
|
|
7
|
+
* answers, a test, a fixture — was writing `Object.create(null)` and a loop.
|
|
8
|
+
* The null prototype is the whole reason this is not an object literal, and it
|
|
9
|
+
* is the kind of detail every caller gets right once and then forgets.
|
|
10
|
+
*/
|
|
11
|
+
export const nodeDataOf = (answers) => {
|
|
12
|
+
const bag = Object.create(null);
|
|
13
|
+
for (const name of Object.keys(answers)) {
|
|
14
|
+
const outcome = answers[name];
|
|
15
|
+
if (outcome)
|
|
16
|
+
bag[name] = outcome;
|
|
17
|
+
}
|
|
18
|
+
return Object.freeze(bag);
|
|
19
|
+
};
|
|
20
|
+
const NO_PROBLEMS = Object.freeze([]);
|
|
21
|
+
/**
|
|
22
|
+
* The resolution of a plan that asks nothing, which is the only tree it is
|
|
23
|
+
* correct for.
|
|
24
|
+
*
|
|
25
|
+
* It exists so `resolveDataPlan` can short-circuit an empty plan, and its name
|
|
26
|
+
* makes it the obvious thing to reach for when writing a composition root that
|
|
27
|
+
* has no data — which is the one use it does not serve. Handed a tree whose nodes
|
|
28
|
+
* do bind, it answers `NO_DATA` for all of them, and every one of those bindings
|
|
29
|
+
* is reported `unresolved` by the walk rather than disappearing.
|
|
30
|
+
*/
|
|
31
|
+
export const EMPTY_DATA_RESOLUTION = {
|
|
32
|
+
lookup: () => NO_DATA,
|
|
33
|
+
problemsFor: () => NO_PROBLEMS,
|
|
34
|
+
};
|
|
35
|
+
/**
|
|
36
|
+
* Folds a plan and its answers into the two lookups the walk uses. Separated
|
|
37
|
+
* from `resolveDataPlan` because it is pure: given the same answers it builds
|
|
38
|
+
* the same resolution, which is what makes the failure paths testable without a
|
|
39
|
+
* fake adapter for each one.
|
|
40
|
+
*/
|
|
41
|
+
export const buildDataResolution = (plan, answers) => {
|
|
42
|
+
const data = new Map();
|
|
43
|
+
const problems = new Map();
|
|
44
|
+
const problemsOn = (nodeId) => {
|
|
45
|
+
const existing = problems.get(nodeId);
|
|
46
|
+
if (existing)
|
|
47
|
+
return existing;
|
|
48
|
+
const created = [];
|
|
49
|
+
problems.set(nodeId, created);
|
|
50
|
+
return created;
|
|
51
|
+
};
|
|
52
|
+
for (const problem of plan.problems) {
|
|
53
|
+
problemsOn(problem.nodeId).push({ kind: "misdeclared", error: problem.error });
|
|
54
|
+
}
|
|
55
|
+
const sourceOf = new Map(plan.requests.map((request) => [request.key, request.source]));
|
|
56
|
+
for (const binding of plan.bindings) {
|
|
57
|
+
const answer = answers.get(binding.key);
|
|
58
|
+
/**
|
|
59
|
+
* A planned binding with no answer is a caller that resolved a different
|
|
60
|
+
* plan than the one it is rendering. Reported as unavailable rather than
|
|
61
|
+
* ignored: a page silently missing the data it asked for is the failure
|
|
62
|
+
* mode this whole module is arranged to prevent.
|
|
63
|
+
*/
|
|
64
|
+
const outcome = !answer
|
|
65
|
+
? {
|
|
66
|
+
status: "unavailable",
|
|
67
|
+
unavailable: {
|
|
68
|
+
reason: "not-resolved",
|
|
69
|
+
detail: "the answers came from resolving a different plan than this tree",
|
|
70
|
+
},
|
|
71
|
+
}
|
|
72
|
+
: answer.ok
|
|
73
|
+
? { status: "ready", value: answer.value }
|
|
74
|
+
: { status: "unavailable", unavailable: answer.error };
|
|
75
|
+
const existing = data.get(binding.nodeId);
|
|
76
|
+
const bag = existing ?? Object.create(null);
|
|
77
|
+
if (!existing)
|
|
78
|
+
data.set(binding.nodeId, bag);
|
|
79
|
+
bag[binding.name] = outcome;
|
|
80
|
+
if (outcome.status === "unavailable") {
|
|
81
|
+
problemsOn(binding.nodeId).push({
|
|
82
|
+
kind: "unavailable",
|
|
83
|
+
name: binding.name,
|
|
84
|
+
source: sourceOf.get(binding.key) ?? binding.key,
|
|
85
|
+
unavailable: outcome.unavailable,
|
|
86
|
+
});
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
for (const bag of data.values())
|
|
90
|
+
Object.freeze(bag);
|
|
91
|
+
return {
|
|
92
|
+
lookup: (nodeId) => data.get(nodeId) ?? NO_DATA,
|
|
93
|
+
problemsFor: (nodeId) => problems.get(nodeId) ?? NO_PROBLEMS,
|
|
94
|
+
};
|
|
95
|
+
};
|
|
96
|
+
//# sourceMappingURL=resolution.js.map
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import type { JsonObject } from "../json.js";
|
|
2
|
+
import type { LoomTree } from "../tree/tree.js";
|
|
3
|
+
import type { DataRegistry } from "./adapter.js";
|
|
4
|
+
import { type DataPlan } from "./plan.js";
|
|
5
|
+
import { type DataResolution } from "./resolution.js";
|
|
6
|
+
/**
|
|
7
|
+
* The one step in serving a page that does IO.
|
|
8
|
+
*
|
|
9
|
+
* Every question in the plan is asked at once. They are independent by
|
|
10
|
+
* construction — a plan is a set of source-and-params pairs with no ordering
|
|
11
|
+
* between them — so asking them in sequence would make a page's latency the sum
|
|
12
|
+
* of its integrations rather than the slowest of them. Nothing here rejects:
|
|
13
|
+
* each entry's failure is captured against its own key, so one integration
|
|
14
|
+
* having a bad afternoon costs one region of the page rather than the page.
|
|
15
|
+
*
|
|
16
|
+
* That last sentence was not true until 13 September, and it is the reason for
|
|
17
|
+
* the ceiling (0140). `Promise.all` over a set of independent questions makes the
|
|
18
|
+
* page's latency the slowest of them — including the one that is never going to
|
|
19
|
+
* answer, which is not a latency at all. An adapter that hangs held the whole
|
|
20
|
+
* page, not its own region, and no diagnostic was ever produced for it because
|
|
21
|
+
* nothing had decided it had waited long enough.
|
|
22
|
+
*/
|
|
23
|
+
export type ResolveDataOptions = {
|
|
24
|
+
readonly registry: DataRegistry;
|
|
25
|
+
/** Passed through to every adapter — the render request's host context. */
|
|
26
|
+
readonly context?: JsonObject;
|
|
27
|
+
/**
|
|
28
|
+
* How long any one source is given, each independently of the others. Defaults
|
|
29
|
+
* to `DEFAULT_SOURCE_CEILING_MS`; there is no way to wait forever (0140).
|
|
30
|
+
*/
|
|
31
|
+
readonly ceilingMs?: number;
|
|
32
|
+
};
|
|
33
|
+
/**
|
|
34
|
+
* Ten seconds per source, which is already several times longer than a reader
|
|
35
|
+
* will wait for a page and generous for a query somebody has indexed.
|
|
36
|
+
*
|
|
37
|
+
* It is per-source rather than per-page because the questions are independent:
|
|
38
|
+
* a page holding one slow integration and five quick ones should show five
|
|
39
|
+
* regions and a diagnostic, not lose a region to whichever source was measured
|
|
40
|
+
* against a budget the others had already spent.
|
|
41
|
+
*/
|
|
42
|
+
export declare const DEFAULT_SOURCE_CEILING_MS = 10000;
|
|
43
|
+
export declare const resolveDataPlan: (plan: DataPlan, options: ResolveDataOptions) => Promise<DataResolution>;
|
|
44
|
+
/** Plan and resolve in one step, for the ordinary caller that does both. */
|
|
45
|
+
export declare const resolveTreeData: (tree: LoomTree, options: ResolveDataOptions) => Promise<DataResolution>;
|
|
46
|
+
//# sourceMappingURL=resolve.d.ts.map
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
import { ceilingOf, describeCeiling, withCeiling } from "../deadline.js";
|
|
2
|
+
import { err } from "../result.js";
|
|
3
|
+
import { planTreeData, planIsEmpty } from "./plan.js";
|
|
4
|
+
import { buildDataResolution, EMPTY_DATA_RESOLUTION, } from "./resolution.js";
|
|
5
|
+
/**
|
|
6
|
+
* Ten seconds per source, which is already several times longer than a reader
|
|
7
|
+
* will wait for a page and generous for a query somebody has indexed.
|
|
8
|
+
*
|
|
9
|
+
* It is per-source rather than per-page because the questions are independent:
|
|
10
|
+
* a page holding one slow integration and five quick ones should show five
|
|
11
|
+
* regions and a diagnostic, not lose a region to whichever source was measured
|
|
12
|
+
* against a budget the others had already spent.
|
|
13
|
+
*/
|
|
14
|
+
export const DEFAULT_SOURCE_CEILING_MS = 10_000;
|
|
15
|
+
const askOne = async (source, params, options) => {
|
|
16
|
+
const registered = options.registry.source(source);
|
|
17
|
+
if (!registered) {
|
|
18
|
+
return err({
|
|
19
|
+
reason: "no-such-source",
|
|
20
|
+
detail: `registered: ${options.registry.sources.map((entry) => entry.id).join(", ") || "none"}`,
|
|
21
|
+
});
|
|
22
|
+
}
|
|
23
|
+
const ceiling = ceilingOf(options.ceilingMs, DEFAULT_SOURCE_CEILING_MS);
|
|
24
|
+
return withCeiling(ceiling, () => err({ reason: "unavailable", detail: `no answer in ${describeCeiling(ceiling)}` }), (signal) => registered.answer(params, options.context, signal));
|
|
25
|
+
};
|
|
26
|
+
export const resolveDataPlan = async (plan, options) => {
|
|
27
|
+
if (planIsEmpty(plan))
|
|
28
|
+
return EMPTY_DATA_RESOLUTION;
|
|
29
|
+
const answered = await Promise.all(plan.requests.map(async (request) => [
|
|
30
|
+
request.key,
|
|
31
|
+
await askOne(request.source, request.params, options),
|
|
32
|
+
]));
|
|
33
|
+
return buildDataResolution(plan, new Map(answered));
|
|
34
|
+
};
|
|
35
|
+
/** Plan and resolve in one step, for the ordinary caller that does both. */
|
|
36
|
+
export const resolveTreeData = async (tree, options) => resolveDataPlan(planTreeData(tree), options);
|
|
37
|
+
//# sourceMappingURL=resolve.js.map
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
/**
|
|
3
|
+
* What a data source is, from the tree's side of the seam.
|
|
4
|
+
*
|
|
5
|
+
* A binding names a source and says nothing about where the answer comes from.
|
|
6
|
+
* This module holds that name and the shape of the answer, so a tree can ask a
|
|
7
|
+
* question no part of it knows how to answer.
|
|
8
|
+
*/
|
|
9
|
+
/**
|
|
10
|
+
* The grammar a source id has to satisfy, in words, said once.
|
|
11
|
+
*
|
|
12
|
+
* The same sentence reaches two very different readers. `describeDataRegistryError`
|
|
13
|
+
* tells a host that registered a bad id, and that reader has the code open. A
|
|
14
|
+
* misdeclared `loom:data` in a tree reaches somebody looking at a page that will
|
|
15
|
+
* not bind, through a render diagnostic — and Zod's default for a failed
|
|
16
|
+
* `.regex()` is the word `Invalid`, so the less informed reader was getting the
|
|
17
|
+
* less useful message. One constant rather than two strings, because the two
|
|
18
|
+
* drifting apart is the same defect wearing a different hat.
|
|
19
|
+
*/
|
|
20
|
+
export declare const SOURCE_ID_EXPECTATION = "expected dot-namespaced kebab-case, like \"commerce.products\"";
|
|
21
|
+
/**
|
|
22
|
+
* The identifier of a registered data source — the contract between a binding
|
|
23
|
+
* in the tree and whatever answers it.
|
|
24
|
+
*
|
|
25
|
+
* Same grammar as `PrimitiveType`, and for the same reason: a tree names a
|
|
26
|
+
* capability, a registry decides what that name reaches, and the AST stays
|
|
27
|
+
* independent of any particular host's data. `profile`, `commerce.products`.
|
|
28
|
+
*/
|
|
29
|
+
export declare const sourceIdSchema: z.ZodBranded<z.ZodString, "SourceId">;
|
|
30
|
+
export type SourceId = z.infer<typeof sourceIdSchema>;
|
|
31
|
+
/** The grammar a binding name has to satisfy, for the same reader. */
|
|
32
|
+
export declare const BINDING_NAME_EXPECTATION = "expected camelCase, like \"services\"";
|
|
33
|
+
/**
|
|
34
|
+
* The name a primitive reads an answer under — `loom.data.services`. camelCase,
|
|
35
|
+
* mirroring slot names and prop names, because it is the same kind of thing: a
|
|
36
|
+
* named region of what a primitive receives.
|
|
37
|
+
*/
|
|
38
|
+
export declare const bindingNameSchema: z.ZodBranded<z.ZodString, "BindingName">;
|
|
39
|
+
export type BindingName = z.infer<typeof bindingNameSchema>;
|
|
40
|
+
//# sourceMappingURL=source.d.ts.map
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { NAMESPACED_ID_PATTERN } from "../primitive-type.js";
|
|
3
|
+
/**
|
|
4
|
+
* What a data source is, from the tree's side of the seam.
|
|
5
|
+
*
|
|
6
|
+
* A binding names a source and says nothing about where the answer comes from.
|
|
7
|
+
* This module holds that name and the shape of the answer, so a tree can ask a
|
|
8
|
+
* question no part of it knows how to answer.
|
|
9
|
+
*/
|
|
10
|
+
/**
|
|
11
|
+
* The grammar a source id has to satisfy, in words, said once.
|
|
12
|
+
*
|
|
13
|
+
* The same sentence reaches two very different readers. `describeDataRegistryError`
|
|
14
|
+
* tells a host that registered a bad id, and that reader has the code open. A
|
|
15
|
+
* misdeclared `loom:data` in a tree reaches somebody looking at a page that will
|
|
16
|
+
* not bind, through a render diagnostic — and Zod's default for a failed
|
|
17
|
+
* `.regex()` is the word `Invalid`, so the less informed reader was getting the
|
|
18
|
+
* less useful message. One constant rather than two strings, because the two
|
|
19
|
+
* drifting apart is the same defect wearing a different hat.
|
|
20
|
+
*/
|
|
21
|
+
export const SOURCE_ID_EXPECTATION = 'expected dot-namespaced kebab-case, like "commerce.products"';
|
|
22
|
+
/**
|
|
23
|
+
* The identifier of a registered data source — the contract between a binding
|
|
24
|
+
* in the tree and whatever answers it.
|
|
25
|
+
*
|
|
26
|
+
* Same grammar as `PrimitiveType`, and for the same reason: a tree names a
|
|
27
|
+
* capability, a registry decides what that name reaches, and the AST stays
|
|
28
|
+
* independent of any particular host's data. `profile`, `commerce.products`.
|
|
29
|
+
*/
|
|
30
|
+
export const sourceIdSchema = z
|
|
31
|
+
.string()
|
|
32
|
+
.regex(NAMESPACED_ID_PATTERN, SOURCE_ID_EXPECTATION)
|
|
33
|
+
.brand();
|
|
34
|
+
/** The grammar a binding name has to satisfy, for the same reader. */
|
|
35
|
+
export const BINDING_NAME_EXPECTATION = 'expected camelCase, like "services"';
|
|
36
|
+
/**
|
|
37
|
+
* The name a primitive reads an answer under — `loom.data.services`. camelCase,
|
|
38
|
+
* mirroring slot names and prop names, because it is the same kind of thing: a
|
|
39
|
+
* named region of what a primitive receives.
|
|
40
|
+
*/
|
|
41
|
+
export const bindingNameSchema = z
|
|
42
|
+
.string()
|
|
43
|
+
.regex(/^[a-z][a-zA-Z0-9]*$/, BINDING_NAME_EXPECTATION)
|
|
44
|
+
.brand();
|
|
45
|
+
//# sourceMappingURL=source.js.map
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A ceiling on an await into somebody else's code.
|
|
3
|
+
*
|
|
4
|
+
* Loom does two things it cannot predict the duration of: it asks a model what
|
|
5
|
+
* to change, and it asks a host's adapter to answer a binding. Both are
|
|
6
|
+
* documented as *reportable* failures — `ModelClientError.unavailable` is "the
|
|
7
|
+
* service could not answer now" and `SourceFailure.unavailable` says in as many
|
|
8
|
+
* words that it covers "a timeout, a dead connection" — and neither seam could
|
|
9
|
+
* produce one, because nothing in the runtime ever stopped waiting.
|
|
10
|
+
*
|
|
11
|
+
* A call that never answers is the worst of the failure modes and the only one
|
|
12
|
+
* with no sentence: a surface shows a spinner, the log says nothing, and the
|
|
13
|
+
* thing that eventually gives up is the reader. Sandboxed deployments make it
|
|
14
|
+
* routine rather than exotic — Node's `fetch` ignores `HTTPS_PROXY`, so a
|
|
15
|
+
* request behind a proxy is not refused, it is simply never answered.
|
|
16
|
+
*
|
|
17
|
+
* So: **the runtime, not the host, decides how long it is prepared to wait**, and
|
|
18
|
+
* an expiry is an ordinary value in the vocabulary the seam already has. There is
|
|
19
|
+
* deliberately no way to switch a ceiling off. A caller that wants to wait twenty
|
|
20
|
+
* minutes names twenty minutes, which is a number a reader of the call site can
|
|
21
|
+
* see; `undefined` meaning "forever" is not.
|
|
22
|
+
*/
|
|
23
|
+
/**
|
|
24
|
+
* The ceiling a caller named, or the default when it named nothing usable.
|
|
25
|
+
*
|
|
26
|
+
* `clampLimit`'s rule, for the same reason: this value reaches a `setTimeout`,
|
|
27
|
+
* where a `NaN` fires immediately and a negative one fires immediately, and
|
|
28
|
+
* both of those turn a slow page into an instantly broken one.
|
|
29
|
+
*/
|
|
30
|
+
export declare const ceilingOf: (given: number | undefined, fallback: number) => number;
|
|
31
|
+
/** `250ms`, `10s`, `3m` — a ceiling in the unit somebody would say it in. */
|
|
32
|
+
export declare const describeCeiling: (ms: number) => string;
|
|
33
|
+
/**
|
|
34
|
+
* Runs `attempt` with a ceiling, and answers with `expired()` if it is reached
|
|
35
|
+
* first.
|
|
36
|
+
*
|
|
37
|
+
* The signal is the half that matters as much as the answer. Walking away from a
|
|
38
|
+
* promise does not stop the work behind it: without the abort, a page that gave
|
|
39
|
+
* up on an integration still holds its socket, and under load the connections a
|
|
40
|
+
* deployment leaks are the ones it already stopped waiting for. An
|
|
41
|
+
* implementation that ignores the signal still cannot delay the answer — it can
|
|
42
|
+
* only fail to release what it is holding.
|
|
43
|
+
*
|
|
44
|
+
* This never rejects for a reason `attempt` did not give it, and a rejection
|
|
45
|
+
* arriving after the race is decided never reaches Node as an unhandled one —
|
|
46
|
+
* which would take a server down for a call the runtime had already reported on.
|
|
47
|
+
*
|
|
48
|
+
* Most of that second half is `Promise.race`'s, not this module's: `race`
|
|
49
|
+
* subscribes to every promise it is handed, synchronously, so the loser already
|
|
50
|
+
* has a reaction attached by the time it settles. The explicit `catch` below
|
|
51
|
+
* therefore changes nothing about how this code behaves today, and `deadline.test.ts`
|
|
52
|
+
* says so where it would otherwise read as the test of a mechanism it cannot see.
|
|
53
|
+
* The line stays because the property is worth keeping true under an edit that
|
|
54
|
+
* replaces the race with a hand-rolled resolver, where it stops being free.
|
|
55
|
+
*/
|
|
56
|
+
export declare const withCeiling: <T>(ceilingMs: number, expired: () => T, attempt: (signal: AbortSignal) => Promise<T>) => Promise<T>;
|
|
57
|
+
//# sourceMappingURL=deadline.d.ts.map
|
package/dist/deadline.js
ADDED
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A ceiling on an await into somebody else's code.
|
|
3
|
+
*
|
|
4
|
+
* Loom does two things it cannot predict the duration of: it asks a model what
|
|
5
|
+
* to change, and it asks a host's adapter to answer a binding. Both are
|
|
6
|
+
* documented as *reportable* failures — `ModelClientError.unavailable` is "the
|
|
7
|
+
* service could not answer now" and `SourceFailure.unavailable` says in as many
|
|
8
|
+
* words that it covers "a timeout, a dead connection" — and neither seam could
|
|
9
|
+
* produce one, because nothing in the runtime ever stopped waiting.
|
|
10
|
+
*
|
|
11
|
+
* A call that never answers is the worst of the failure modes and the only one
|
|
12
|
+
* with no sentence: a surface shows a spinner, the log says nothing, and the
|
|
13
|
+
* thing that eventually gives up is the reader. Sandboxed deployments make it
|
|
14
|
+
* routine rather than exotic — Node's `fetch` ignores `HTTPS_PROXY`, so a
|
|
15
|
+
* request behind a proxy is not refused, it is simply never answered.
|
|
16
|
+
*
|
|
17
|
+
* So: **the runtime, not the host, decides how long it is prepared to wait**, and
|
|
18
|
+
* an expiry is an ordinary value in the vocabulary the seam already has. There is
|
|
19
|
+
* deliberately no way to switch a ceiling off. A caller that wants to wait twenty
|
|
20
|
+
* minutes names twenty minutes, which is a number a reader of the call site can
|
|
21
|
+
* see; `undefined` meaning "forever" is not.
|
|
22
|
+
*/
|
|
23
|
+
/**
|
|
24
|
+
* The ceiling a caller named, or the default when it named nothing usable.
|
|
25
|
+
*
|
|
26
|
+
* `clampLimit`'s rule, for the same reason: this value reaches a `setTimeout`,
|
|
27
|
+
* where a `NaN` fires immediately and a negative one fires immediately, and
|
|
28
|
+
* both of those turn a slow page into an instantly broken one.
|
|
29
|
+
*/
|
|
30
|
+
export const ceilingOf = (given, fallback) => given !== undefined && Number.isFinite(given) && given > 0 ? given : fallback;
|
|
31
|
+
/** `250ms`, `10s`, `3m` — a ceiling in the unit somebody would say it in. */
|
|
32
|
+
export const describeCeiling = (ms) => {
|
|
33
|
+
if (ms >= 60_000 && ms % 60_000 === 0)
|
|
34
|
+
return `${ms / 60_000}m`;
|
|
35
|
+
if (ms >= 1_000)
|
|
36
|
+
return `${Number((ms / 1_000).toFixed(2))}s`;
|
|
37
|
+
return `${ms}ms`;
|
|
38
|
+
};
|
|
39
|
+
/**
|
|
40
|
+
* Runs `attempt` with a ceiling, and answers with `expired()` if it is reached
|
|
41
|
+
* first.
|
|
42
|
+
*
|
|
43
|
+
* The signal is the half that matters as much as the answer. Walking away from a
|
|
44
|
+
* promise does not stop the work behind it: without the abort, a page that gave
|
|
45
|
+
* up on an integration still holds its socket, and under load the connections a
|
|
46
|
+
* deployment leaks are the ones it already stopped waiting for. An
|
|
47
|
+
* implementation that ignores the signal still cannot delay the answer — it can
|
|
48
|
+
* only fail to release what it is holding.
|
|
49
|
+
*
|
|
50
|
+
* This never rejects for a reason `attempt` did not give it, and a rejection
|
|
51
|
+
* arriving after the race is decided never reaches Node as an unhandled one —
|
|
52
|
+
* which would take a server down for a call the runtime had already reported on.
|
|
53
|
+
*
|
|
54
|
+
* Most of that second half is `Promise.race`'s, not this module's: `race`
|
|
55
|
+
* subscribes to every promise it is handed, synchronously, so the loser already
|
|
56
|
+
* has a reaction attached by the time it settles. The explicit `catch` below
|
|
57
|
+
* therefore changes nothing about how this code behaves today, and `deadline.test.ts`
|
|
58
|
+
* says so where it would otherwise read as the test of a mechanism it cannot see.
|
|
59
|
+
* The line stays because the property is worth keeping true under an edit that
|
|
60
|
+
* replaces the race with a hand-rolled resolver, where it stops being free.
|
|
61
|
+
*/
|
|
62
|
+
export const withCeiling = (ceilingMs, expired, attempt) => {
|
|
63
|
+
const controller = new AbortController();
|
|
64
|
+
let timer;
|
|
65
|
+
const reached = new Promise((resolve) => {
|
|
66
|
+
timer = setTimeout(() => {
|
|
67
|
+
controller.abort(new Error(`no answer in ${describeCeiling(ceilingMs)}`));
|
|
68
|
+
resolve(expired());
|
|
69
|
+
}, ceilingMs);
|
|
70
|
+
});
|
|
71
|
+
const answered = attempt(controller.signal);
|
|
72
|
+
/** Belt to `race`'s braces, and the module comment says which is load-bearing. */
|
|
73
|
+
answered.catch(() => undefined);
|
|
74
|
+
return Promise.race([answered, reached]).finally(() => {
|
|
75
|
+
clearTimeout(timer);
|
|
76
|
+
});
|
|
77
|
+
};
|
|
78
|
+
//# sourceMappingURL=deadline.js.map
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import type { FrameOrigin, FrameOriginRegistry } from "./origin.js";
|
|
2
|
+
/**
|
|
3
|
+
* Whose documents this deployment will frame, as a model is told it.
|
|
4
|
+
*
|
|
5
|
+
* The same projection `submissionCatalogue` makes for endpoints, and it exists
|
|
6
|
+
* for the same reason turned around. An endpoint catalogue lists the *only*
|
|
7
|
+
* things a model may name, because an address never appears in a tree. A frame
|
|
8
|
+
* URL does appear in a tree — a model picks which video — so this catalogue is
|
|
9
|
+
* not the whole of what may be written. It is the difference between a model
|
|
10
|
+
* proposing a video that renders and a model proposing one that renders a
|
|
11
|
+
* refusal, which is the difference between a good page and a wasted turn.
|
|
12
|
+
*
|
|
13
|
+
* `self` is deliberately not projected. Whether an origin is the deployment's
|
|
14
|
+
* own changes what a frame is worth to whoever runs the deployment, and nothing
|
|
15
|
+
* at all about which video belongs on the page.
|
|
16
|
+
*/
|
|
17
|
+
export type CataloguedFrameOrigin = {
|
|
18
|
+
readonly origin: FrameOrigin;
|
|
19
|
+
/** One line, written by whoever runs the deployment. */
|
|
20
|
+
readonly description: string;
|
|
21
|
+
};
|
|
22
|
+
export type FrameCatalogue = readonly CataloguedFrameOrigin[];
|
|
23
|
+
export declare const frameCatalogue: (registry: FrameOriginRegistry) => FrameCatalogue;
|
|
24
|
+
//# sourceMappingURL=catalogue.d.ts.map
|