Repository navigation
Expand file tree
/
Copy pathprotocol-host.ts
More file actions
112 lines (106 loc) · 6.58 KB
/
Copy pathprotocol-host.ts
File metadata and controls
112 lines (106 loc) · 6.58 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
/**
* [#25467 E1] The host: what a body moved out of `ObjectStackProtocolImplementation`
* reaches the class through.
*
* Ruling E (6537939895) moves the class's members out of `protocol.ts` a whole
* section at a time (E2). A moved body is an exported function whose first
* parameter is `host`, and it differs from the method body it was by exactly one
* closed set of rewrites, checked by `scripts/host-split.mjs`:
*
* - `this.<member>` → `host.<member>`;
* - a private static `ObjectStackProtocolImplementation.<fn>(…)` → `host.<fn>(…)`;
* - `this.constructor` → `host`.
*
* The method stays on the class with its docblock and signature, so the published
* `.d.ts` keeps it, and its body becomes `return <fn>(protocolHost(this), …)`.
*
* ## The host is one object per protocol instance
*
* {@link ProtocolHost} lists every class member some moved body reads, each typed
* AS that member (`ObjectStackProtocolImplementation['x']`, or
* `(typeof ObjectStackProtocolImplementation)['x']` for a static), so a change to
* a member's signature on the class is a change here, and naming a member the
* class does not have is a compile error. A moved function takes the `Pick` of
* exactly the members its body reads.
*
* The object is built by the class itself, in its static block in `protocol.ts`:
* only code inside the class body can read its private members, and a static
* block adds no member to the class, so the published `.d.ts` does not move.
* There:
*
* - a METHOD is a closure that calls it on the instance at call time
* (`(...a) => protocol.x(...a)`), never a bound or copied function, so a
* method replaced on the instance or its prototype afterwards (a test double,
* a spy) is still the one a moved body reaches;
* - a FIELD is a getter that reads the instance's field when it is read, and a
* setter too when a moved body assigns it, so a moved body sees and makes the
* same writes the method body did;
* - a private STATIC method is a closure to the static.
*
* The census of read seams (`scripts/check-durability-degradation-log-level.mjs`,
* `HOST_SPLIT`) and the two by-path pins (`protocol.read-verb-canonical-fold`,
* `protocol.lookup-artifact-item-call-sites`) read a moved body through this
* shape: a `host.x(…)` call resolves to the class method `x`, and a stub
* `return fn(protocolHost(this), …)` to `fn`'s body.
*/
import type { ObjectStackProtocolImplementation } from './protocol.js';
/**
* Every `ObjectStackProtocolImplementation` member a moved body reads, sorted by
* name. `scripts/host-split.mjs move` adds the entries a move needs, here and in
* the class's static block.
*/
export interface ProtocolHost {
readonly artifactLockLayerAt: ObjectStackProtocolImplementation['artifactLockLayerAt'];
readonly baseServesBundleMember: ObjectStackProtocolImplementation['baseServesBundleMember'];
readonly convertStoredItem: ObjectStackProtocolImplementation['convertStoredItem'];
readonly declinesStoredRow: ObjectStackProtocolImplementation['declinesStoredRow'];
readonly disabledActionsOf: ObjectStackProtocolImplementation['disabledActionsOf'];
readonly engine: ObjectStackProtocolImplementation['engine'];
readonly environmentId: ObjectStackProtocolImplementation['environmentId'];
readonly expandStoredViewContainers: ObjectStackProtocolImplementation['expandStoredViewContainers'];
readonly findEnvironmentRows: ObjectStackProtocolImplementation['findEnvironmentRows'];
readonly flowRegistrationsOf: ObjectStackProtocolImplementation['flowRegistrationsOf'];
readonly foldObjectExtendersFromRegistry: ObjectStackProtocolImplementation['foldObjectExtendersFromRegistry'];
readonly getServicesRegistry: ObjectStackProtocolImplementation['getServicesRegistry'];
readonly governServedObject: ObjectStackProtocolImplementation['governServedObject'];
readonly hydrateOverlayIntoRegistry: ObjectStackProtocolImplementation['hydrateOverlayIntoRegistry'];
readonly isStoredEntryOfDeclinedName: ObjectStackProtocolImplementation['isStoredEntryOfDeclinedName'];
readonly isUnservedSealedOverlay: ObjectStackProtocolImplementation['isUnservedSealedOverlay'];
readonly isWritablePackage: ObjectStackProtocolImplementation['isWritablePackage'];
readonly lookupArtifactItem: ObjectStackProtocolImplementation['lookupArtifactItem'];
readonly namesWithOwnStoredRow: ObjectStackProtocolImplementation['namesWithOwnStoredRow'];
readonly overrideWriteVerdict: ObjectStackProtocolImplementation['overrideWriteVerdict'];
readonly packagedArtifactOwner: ObjectStackProtocolImplementation['packagedArtifactOwner'];
readonly packagedBaseRefusal: ObjectStackProtocolImplementation['packagedBaseRefusal'];
readonly readActiveOverlayRows: ObjectStackProtocolImplementation['readActiveOverlayRows'];
readonly readFlattenedMetaItems: ObjectStackProtocolImplementation['readFlattenedMetaItems'];
readonly rethrowUnlessMetadataStoreUnprovisioned: ObjectStackProtocolImplementation['rethrowUnlessMetadataStoreUnprovisioned'];
readonly shippedArtifactsOf: ObjectStackProtocolImplementation['shippedArtifactsOf'];
readonly shippingPackagesOf: ObjectStackProtocolImplementation['shippingPackagesOf'];
readonly shipsBundleName: ObjectStackProtocolImplementation['shipsBundleName'];
readonly storedFlowBindingAgrees: ObjectStackProtocolImplementation['storedFlowBindingAgrees'];
readonly storedOverlayEntries: ObjectStackProtocolImplementation['storedOverlayEntries'];
readonly uninstalledNamedBaseRefusal: ObjectStackProtocolImplementation['uninstalledNamedBaseRefusal'];
}
const hosts = new WeakMap<ObjectStackProtocolImplementation, ProtocolHost>();
let build: ((protocol: ObjectStackProtocolImplementation) => ProtocolHost) | undefined;
/**
* Called once, from `ObjectStackProtocolImplementation`'s static block: the one
* place that can read the class's private members to build a host.
*/
export function installProtocolHost(factory: (protocol: ObjectStackProtocolImplementation) => ProtocolHost): void {
build = factory;
}
/** The host of one protocol instance, built on first use and kept for the instance's life. */
export function protocolHost(protocol: ObjectStackProtocolImplementation): ProtocolHost {
let host = hosts.get(protocol);
if (host === undefined) {
if (build === undefined) {
throw new Error('protocolHost: ObjectStackProtocolImplementation has not installed its host factory');
}
host = build(protocol);
hosts.set(protocol, host);
}
return host;
}