@syntropika/tembra-sdk 0.2.1 → 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 +43 -17
- package/dist/authoring/types.d.ts +64 -3
- package/dist/authoring/wit.d.ts +6 -0
- package/dist/bridge/commands.d.ts +1190 -0
- package/dist/bridge/identifiers.d.ts +2 -0
- package/dist/bridge/kernel.d.ts +18 -107
- package/dist/bridge/protocol.d.ts +3 -138
- package/dist/browser.d.ts +14 -1
- package/dist/browser.js +141 -3298
- package/dist/chunks/browser-b8jamxw2.js +3399 -0
- package/dist/chunks/execution-nsqc6nrt.js +1419 -0
- package/dist/chunks/index-01zk0xqx.js +160 -0
- package/dist/chunks/index-3fjdfdfd.js +152 -0
- package/dist/chunks/index-aaymjn7v.js +787 -0
- package/dist/chunks/index-c1w7z9hx.js +356 -0
- package/dist/chunks/index-h8t0n42q.js +738 -0
- package/dist/chunks/index-hfds9mzp.js +308 -0
- package/dist/chunks/index-kr4x67wt.js +177 -0
- package/dist/chunks/index-kr6bnh34.js +117 -0
- package/dist/chunks/index-kyt9dj0a.js +1421 -0
- package/dist/chunks/index-n1wxzc9w.js +830 -0
- package/dist/chunks/index-pvac426d.js +74 -0
- package/dist/chunks/index-smyds5ce.js +3234 -0
- package/dist/chunks/index-sse8aapb.js +121 -0
- package/dist/chunks/index-v6heph77.js +643 -0
- package/dist/chunks/index-xrdvnv37.js +3448 -0
- package/dist/chunks/index-za4mg94e.js +26 -0
- package/dist/chunks/index-zkqmnjj8.js +167 -0
- package/dist/coordinator.js +9 -500
- package/dist/error.d.ts +2 -0
- package/dist/errors.d.ts +3 -0
- package/dist/guest.d.ts +173 -0
- package/dist/guest.js +26 -0
- package/dist/host.d.ts +36 -30
- package/dist/host.js +37 -3276
- package/dist/http/bytes.d.ts +8 -0
- package/dist/http/events.d.ts +7 -0
- package/dist/http.d.ts +45 -0
- package/dist/http.js +291 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +49 -862
- package/dist/infrastructure/rpc/client.d.ts +2 -1
- package/dist/infrastructure/rpc/resources.d.ts +28 -0
- package/dist/interpreter/abi.d.ts +54 -0
- package/dist/interpreter/acquire.d.ts +18 -0
- package/dist/interpreter/browser-network.d.ts +52 -0
- package/dist/interpreter/browser-port.d.ts +55 -0
- package/dist/interpreter/browser.d.ts +79 -0
- package/dist/interpreter/cli.d.ts +5 -0
- package/dist/interpreter/codec.d.ts +42 -0
- package/dist/interpreter/component/execution.d.ts +42 -0
- package/dist/interpreter/component/host.d.ts +69 -0
- package/dist/interpreter/component/instance.d.ts +40 -0
- package/dist/interpreter/component/kernel.d.ts +120 -0
- package/dist/interpreter/component/names.d.ts +5 -0
- package/dist/interpreter/component/port.d.ts +85 -0
- package/dist/interpreter/component/prepared.d.ts +97 -0
- package/dist/interpreter/component/resources.d.ts +45 -0
- package/dist/interpreter/component/revision.d.ts +87 -0
- package/dist/interpreter/component/scope.d.ts +116 -0
- package/dist/interpreter/component/streams.d.ts +28 -0
- package/dist/interpreter/component/values.d.ts +79 -0
- package/dist/interpreter/component/wasi-filesystem.d.ts +21 -0
- package/dist/interpreter/component/wasi-host.d.ts +64 -0
- package/dist/interpreter/component/wasi-http.d.ts +33 -0
- package/dist/interpreter/component/wasi-sockets.d.ts +183 -0
- package/dist/interpreter/component/wasi.d.ts +41 -0
- package/dist/interpreter/core.d.ts +64 -0
- package/dist/interpreter/fetch-http-provider.d.ts +17 -0
- package/dist/interpreter/filesystem/contract.d.ts +85 -0
- package/dist/interpreter/filesystem/memory.d.ts +3 -0
- package/dist/interpreter/filesystem/opfs.d.ts +3 -0
- package/dist/interpreter/filesystem/scope.d.ts +35 -0
- package/dist/interpreter/filesystem.d.ts +8 -0
- package/dist/interpreter/gate.d.ts +6 -0
- package/dist/interpreter/host-protocol.d.ts +100 -0
- package/dist/interpreter/http-ingress-fetch.d.ts +7 -0
- package/dist/interpreter/http-ingress.d.ts +96 -0
- package/dist/interpreter/http-provider.d.ts +85 -0
- package/dist/interpreter/io.d.ts +20 -0
- package/dist/interpreter/mobile.d.ts +149 -0
- package/dist/interpreter/native-ingress.d.ts +95 -0
- package/dist/interpreter/node-port.d.ts +25 -0
- package/dist/interpreter/node.d.ts +36 -0
- package/dist/interpreter/revision.d.ts +64 -0
- package/dist/interpreter/scope.d.ts +89 -0
- package/dist/interpreter/socket-addresses.d.ts +50 -0
- package/dist/interpreter/socket-provider.d.ts +110 -0
- package/dist/interpreter/standard-cli.d.ts +34 -0
- package/dist/interpreter/standard-codec.d.ts +96 -0
- package/dist/interpreter/standard-filesystem.d.ts +47 -0
- package/dist/interpreter/standard-host.d.ts +71 -0
- package/dist/interpreter/standard-http-values.d.ts +159 -0
- package/dist/interpreter/standard-http.d.ts +9 -0
- package/dist/interpreter/standard-ingress.d.ts +63 -0
- package/dist/interpreter/standard-sockets.d.ts +177 -0
- package/dist/interpreter/standard-streams.d.ts +218 -0
- package/dist/interpreter/standard-system.d.ts +35 -0
- package/dist/interpreter/standard-utf8.d.ts +4 -0
- package/dist/interpreter/standard.d.ts +18 -0
- package/dist/interpreter/types.d.ts +152 -0
- package/dist/interpreter/wit-shape.d.ts +92 -0
- package/dist/manager.js +5 -332
- package/dist/msgpack.js +9 -615
- package/dist/node.d.ts +8 -1
- package/dist/node.js +248 -3287
- package/dist/rpc.js +196 -699
- package/dist/runtime/adapters.d.ts +120 -0
- package/dist/runtime/adapters.js +38 -0
- package/dist/runtime/calls.d.ts +9 -3
- package/dist/runtime/lifecycle.d.ts +3 -1
- package/dist/runtime/orbs.d.ts +5 -4
- package/dist/runtime/references.d.ts +27 -1
- package/dist/runtime/reload.d.ts +5 -3
- package/dist/runtime/scopes.d.ts +1 -1
- package/dist/runtime/signals.d.ts +4 -0
- package/dist/runtime/wit-client.d.ts +38 -0
- package/dist/telemetry.js +4 -25
- package/dist/tooling/build.d.ts +2 -2
- package/dist/tooling/client-resources.d.ts +23 -0
- package/dist/tooling/client.d.ts +10 -0
- package/dist/tooling/component-glue.d.ts +17 -0
- package/dist/tooling/component.d.ts +11 -0
- package/dist/tooling/index.d.ts +3 -1
- package/dist/tooling/index.js +1155 -102
- package/dist/tooling/resolver.d.ts +4 -4
- package/dist/tooling/typecheck.d.ts +2 -1
- package/dist/tooling/types.d.ts +27 -12
- package/dist/tooling/wit.d.ts +9 -0
- package/dist/wasi/wasi-clocks-types.d.ts +2 -0
- package/dist/wasi/wasi-http-client.d.ts +5 -0
- package/dist/wasi/wasi-http-types.d.ts +285 -0
- package/dist/wasi/wasi-sockets-ip-name-lookup.d.ts +23 -0
- package/dist/wasi/wasi-sockets-types.d.ts +146 -0
- package/package.json +62 -35
- package/src/authoring/declaration.ts +1 -1
- package/src/authoring/types.ts +53 -3
- package/src/authoring/wit.ts +15 -0
- package/src/bridge/commands.ts +1105 -0
- package/src/bridge/identifiers.ts +2 -0
- package/src/bridge/kernel.ts +56 -98
- package/src/bridge/protocol.ts +3 -142
- package/src/browser.ts +90 -6
- package/src/context-key.ts +4 -7
- package/src/error.ts +1 -1
- package/src/errors.ts +7 -0
- package/src/guest.ts +327 -0
- package/src/host.ts +128 -23
- package/src/http/bytes.ts +87 -0
- package/src/http/events.ts +34 -0
- package/src/http.ts +272 -0
- package/src/index.ts +3 -0
- package/src/infrastructure/rpc/client.ts +136 -17
- package/src/infrastructure/rpc/resources.ts +123 -0
- package/src/interpreter/abi.ts +69 -0
- package/src/interpreter/acquire.ts +58 -0
- package/src/interpreter/browser-network.ts +170 -0
- package/src/interpreter/browser-port.ts +425 -0
- package/src/interpreter/browser.ts +340 -0
- package/src/interpreter/cli.ts +30 -0
- package/src/interpreter/codec.ts +298 -0
- package/src/interpreter/component/execution.ts +264 -0
- package/src/interpreter/component/host.ts +409 -0
- package/src/interpreter/component/instance.ts +138 -0
- package/src/interpreter/component/kernel.ts +611 -0
- package/src/interpreter/component/names.ts +13 -0
- package/src/interpreter/component/port.ts +598 -0
- package/src/interpreter/component/prepared.ts +194 -0
- package/src/interpreter/component/resources.ts +345 -0
- package/src/interpreter/component/revision.ts +702 -0
- package/src/interpreter/component/scope.ts +447 -0
- package/src/interpreter/component/streams.ts +180 -0
- package/src/interpreter/component/values.ts +254 -0
- package/src/interpreter/component/wasi-filesystem.ts +472 -0
- package/src/interpreter/component/wasi-host.ts +197 -0
- package/src/interpreter/component/wasi-http.ts +939 -0
- package/src/interpreter/component/wasi-sockets.ts +958 -0
- package/src/interpreter/component/wasi.ts +238 -0
- package/src/interpreter/core.ts +386 -0
- package/src/interpreter/fetch-http-provider.ts +98 -0
- package/src/interpreter/filesystem/contract.ts +138 -0
- package/src/interpreter/filesystem/memory.ts +180 -0
- package/src/interpreter/filesystem/opfs.ts +294 -0
- package/src/interpreter/filesystem/scope.ts +390 -0
- package/src/interpreter/filesystem.ts +20 -0
- package/src/interpreter/gate.ts +55 -0
- package/src/interpreter/host-protocol.ts +242 -0
- package/src/interpreter/http-ingress-fetch.ts +133 -0
- package/src/interpreter/http-ingress.ts +203 -0
- package/src/interpreter/http-provider.ts +105 -0
- package/src/interpreter/io.ts +66 -0
- package/src/interpreter/mobile.ts +385 -0
- package/src/interpreter/native-ingress.ts +550 -0
- package/src/interpreter/node-port.ts +218 -0
- package/src/interpreter/node.ts +114 -0
- package/src/interpreter/revision.ts +450 -0
- package/src/interpreter/scope.ts +453 -0
- package/src/interpreter/socket-addresses.ts +246 -0
- package/src/interpreter/socket-provider.ts +126 -0
- package/src/interpreter/standard-cli.ts +184 -0
- package/src/interpreter/standard-codec.ts +403 -0
- package/src/interpreter/standard-filesystem.ts +545 -0
- package/src/interpreter/standard-host.ts +840 -0
- package/src/interpreter/standard-http-values.ts +624 -0
- package/src/interpreter/standard-http.ts +622 -0
- package/src/interpreter/standard-ingress.ts +344 -0
- package/src/interpreter/standard-sockets.ts +847 -0
- package/src/interpreter/standard-streams.ts +710 -0
- package/src/interpreter/standard-system.ts +182 -0
- package/src/interpreter/standard-utf8.ts +72 -0
- package/src/interpreter/standard.ts +283 -0
- package/src/interpreter/types.ts +163 -0
- package/src/interpreter/wit-shape.ts +175 -0
- package/src/node.ts +43 -14
- package/src/runtime/activities.ts +6 -6
- package/src/runtime/adapters.ts +314 -0
- package/src/runtime/calls.ts +218 -56
- package/src/runtime/context.ts +7 -7
- package/src/runtime/lifecycle.ts +36 -17
- package/src/runtime/orbs.ts +81 -39
- package/src/runtime/programs.ts +16 -8
- package/src/runtime/references.ts +128 -11
- package/src/runtime/reload.ts +71 -30
- package/src/runtime/resources.ts +2 -2
- package/src/runtime/scopes.ts +17 -17
- package/src/runtime/session.ts +3 -1
- package/src/runtime/signals.ts +31 -0
- package/src/runtime/wit-client.ts +228 -0
- package/src/tooling/build.ts +152 -54
- package/src/tooling/client-resources.ts +74 -0
- package/src/tooling/client.ts +531 -0
- package/src/tooling/component-glue.ts +288 -0
- package/src/tooling/component.ts +225 -0
- package/src/tooling/index.ts +3 -7
- package/src/tooling/resolver.ts +42 -25
- package/src/tooling/typecheck.ts +59 -4
- package/src/tooling/types.ts +27 -12
- package/src/tooling/wit.ts +188 -0
- package/dist/embedded.d.ts +0 -1
- package/dist/embedded.js +0 -1
- package/src/embedded.ts +0 -293
|
@@ -0,0 +1,531 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Typed TypeScript clients of a contract's exported interfaces, for host applications.
|
|
3
|
+
*
|
|
4
|
+
* A host acquires a WIT service by name (`host.get("<orb>::<identity>", key)`) and receives an
|
|
5
|
+
* untyped `DynamicReference` whose method keys are the kebab-case WIT names. `client()` reads the
|
|
6
|
+
* contract's describe graph through `NodeContract` and writes, for each exported interface, a
|
|
7
|
+
* module the application commits: the interface's signatures in the host's value form (camelCase
|
|
8
|
+
* record fields, `{ tag, val }` variants and results, `T | null` options, plain arrays, `bigint`
|
|
9
|
+
* for 64-bit integers) and `get(scope, { orb, key })`, which acquires the reference through a
|
|
10
|
+
* `Host` or a `Context` and wraps it with camelCase methods calling the kebab-case keys. The
|
|
11
|
+
* wrapper only leaves out a context given as `undefined`: every value still crosses the same
|
|
12
|
+
* checked boundary. Each record, variant, enum and flags type the interface uses is exported under
|
|
13
|
+
* its WIT name, in its JavaScript spelling (`Point` for `point`), which the contract read from WIT
|
|
14
|
+
* answers to its `type-names` query: the describe graph keeps no type names.
|
|
15
|
+
*/
|
|
16
|
+
import { bindingName } from "../interpreter/component/names.ts";
|
|
17
|
+
import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
|
|
18
|
+
import path from "node:path";
|
|
19
|
+
import { NodeContract } from "@syntropika/tembra-engine-node";
|
|
20
|
+
import type { ReferenceBase } from "../authoring/types.ts";
|
|
21
|
+
import { HTTP_HANDLER } from "../interpreter/http-ingress.ts";
|
|
22
|
+
import { query } from "../interpreter/types.ts";
|
|
23
|
+
import { resourceNames as resourceNaming } from "./client-resources.ts";
|
|
24
|
+
|
|
25
|
+
export interface ClientOptions {
|
|
26
|
+
/** The contract's entry `.wit` file; its directory and `deps/` resolve as for `build()`. */
|
|
27
|
+
wit: string;
|
|
28
|
+
/** The world whose exported interfaces get clients; the package's only world when omitted. */
|
|
29
|
+
world?: string;
|
|
30
|
+
/** The directory of the generated modules, one `<namespace>-<package>-<interface>.ts` each. */
|
|
31
|
+
out: string;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
type WitType = string | number | null | undefined;
|
|
35
|
+
interface WitKind {
|
|
36
|
+
type?: WitType;
|
|
37
|
+
list?: WitType;
|
|
38
|
+
option?: WitType;
|
|
39
|
+
record?: { fields: { name: string; type: WitType }[] };
|
|
40
|
+
tuple?: { types: WitType[] };
|
|
41
|
+
variant?: { cases: { name: string; type?: WitType }[] };
|
|
42
|
+
enum?: { cases: { name: string }[] };
|
|
43
|
+
flags?: { flags: { name: string }[] };
|
|
44
|
+
result?: { ok?: WitType; err?: WitType };
|
|
45
|
+
handle?: { own?: number; borrow?: number };
|
|
46
|
+
[other: string]: unknown;
|
|
47
|
+
}
|
|
48
|
+
interface DescribedFunction {
|
|
49
|
+
readonly name: string;
|
|
50
|
+
readonly kind?: string | Readonly<Record<string, number>>;
|
|
51
|
+
readonly params: readonly { readonly name: string; readonly type: WitType }[];
|
|
52
|
+
readonly result?: WitType;
|
|
53
|
+
}
|
|
54
|
+
/** The parts of the contract's `describe` answer this module reads. */
|
|
55
|
+
interface Described {
|
|
56
|
+
readonly imports?: readonly { readonly binding: string; readonly contract?: string | null }[];
|
|
57
|
+
readonly exports: readonly {
|
|
58
|
+
readonly contract?: string | null;
|
|
59
|
+
readonly type_only?: boolean;
|
|
60
|
+
readonly resources?: Readonly<Record<string, number>>;
|
|
61
|
+
readonly functions?: Readonly<Record<string, DescribedFunction>>;
|
|
62
|
+
}[];
|
|
63
|
+
readonly types: readonly {
|
|
64
|
+
readonly id: number;
|
|
65
|
+
readonly definition: {
|
|
66
|
+
readonly kind: WitKind | string;
|
|
67
|
+
readonly owner?: string;
|
|
68
|
+
readonly name?: string;
|
|
69
|
+
};
|
|
70
|
+
}[];
|
|
71
|
+
readonly javascriptNames: Readonly<Record<string, string>>;
|
|
72
|
+
}
|
|
73
|
+
/**
|
|
74
|
+
* The contract's `type-names` answer: a WIT name for some ids of the describe graph, an alias's
|
|
75
|
+
* own where an interface takes a type with `use`, the interface where it is written, and its
|
|
76
|
+
* spelling alone and after the interface that declares the definition (`Point`, `APoint`).
|
|
77
|
+
*/
|
|
78
|
+
type TypeNames = readonly {
|
|
79
|
+
readonly id: number;
|
|
80
|
+
readonly name: string;
|
|
81
|
+
readonly interface?: string | null;
|
|
82
|
+
readonly javascript: string;
|
|
83
|
+
readonly qualified: string;
|
|
84
|
+
}[];
|
|
85
|
+
|
|
86
|
+
const PRIMITIVES: Readonly<Record<string, string>> = {
|
|
87
|
+
bool: "boolean",
|
|
88
|
+
u8: "number",
|
|
89
|
+
u16: "number",
|
|
90
|
+
u32: "number",
|
|
91
|
+
s8: "number",
|
|
92
|
+
s16: "number",
|
|
93
|
+
s32: "number",
|
|
94
|
+
f32: "number",
|
|
95
|
+
f64: "number",
|
|
96
|
+
u64: "bigint",
|
|
97
|
+
s64: "bigint",
|
|
98
|
+
char: "string",
|
|
99
|
+
string: "string",
|
|
100
|
+
};
|
|
101
|
+
|
|
102
|
+
/** Words that cannot name a parameter in a strict-mode module, and the trailing `context`. */
|
|
103
|
+
const RESERVED = new Set([
|
|
104
|
+
"arguments",
|
|
105
|
+
"await",
|
|
106
|
+
"break",
|
|
107
|
+
"case",
|
|
108
|
+
"catch",
|
|
109
|
+
"class",
|
|
110
|
+
"const",
|
|
111
|
+
"continue",
|
|
112
|
+
"debugger",
|
|
113
|
+
"default",
|
|
114
|
+
"delete",
|
|
115
|
+
"do",
|
|
116
|
+
"else",
|
|
117
|
+
"enum",
|
|
118
|
+
"eval",
|
|
119
|
+
"export",
|
|
120
|
+
"extends",
|
|
121
|
+
"false",
|
|
122
|
+
"finally",
|
|
123
|
+
"for",
|
|
124
|
+
"function",
|
|
125
|
+
"if",
|
|
126
|
+
"implements",
|
|
127
|
+
"import",
|
|
128
|
+
"in",
|
|
129
|
+
"instanceof",
|
|
130
|
+
"interface",
|
|
131
|
+
"let",
|
|
132
|
+
"new",
|
|
133
|
+
"null",
|
|
134
|
+
"package",
|
|
135
|
+
"private",
|
|
136
|
+
"protected",
|
|
137
|
+
"public",
|
|
138
|
+
"return",
|
|
139
|
+
"static",
|
|
140
|
+
"super",
|
|
141
|
+
"switch",
|
|
142
|
+
"this",
|
|
143
|
+
"throw",
|
|
144
|
+
"true",
|
|
145
|
+
"try",
|
|
146
|
+
"typeof",
|
|
147
|
+
"var",
|
|
148
|
+
"void",
|
|
149
|
+
"while",
|
|
150
|
+
"with",
|
|
151
|
+
"yield",
|
|
152
|
+
"context",
|
|
153
|
+
]);
|
|
154
|
+
|
|
155
|
+
/**
|
|
156
|
+
* Members every client has, which no service function may share: a reference serves its own
|
|
157
|
+
* members before the service's methods and answers `undefined` for `then`, and `then` would make
|
|
158
|
+
* the client a thenable.
|
|
159
|
+
*/
|
|
160
|
+
const MEMBERS: Readonly<Record<keyof ReferenceBase | "then" | "reference", true>> = {
|
|
161
|
+
ready: true,
|
|
162
|
+
status: true,
|
|
163
|
+
state: true,
|
|
164
|
+
release: true,
|
|
165
|
+
opaque: true,
|
|
166
|
+
then: true,
|
|
167
|
+
reference: true,
|
|
168
|
+
};
|
|
169
|
+
|
|
170
|
+
/** Types the module names itself, imported or global; an interface's type takes a `_` instead. */
|
|
171
|
+
const OWN = new Set([
|
|
172
|
+
"AcquisitionOptions",
|
|
173
|
+
"Context",
|
|
174
|
+
"DynamicReference",
|
|
175
|
+
"Promise",
|
|
176
|
+
"ReferenceBase",
|
|
177
|
+
"WitResource",
|
|
178
|
+
"WitClientSchema",
|
|
179
|
+
]);
|
|
180
|
+
|
|
181
|
+
/** Write one typed client module per exported interface; returns every module's path. */
|
|
182
|
+
export async function client(options: ClientOptions): Promise<readonly string[]> {
|
|
183
|
+
const wit = path.resolve(options.wit);
|
|
184
|
+
if (!wit.endsWith(".wit")) throw new Error("Client generation requires a .wit entry file");
|
|
185
|
+
const contract = new NodeContract(path.dirname(wit), options.world);
|
|
186
|
+
const graph = query<Described>(contract, { kind: "describe" });
|
|
187
|
+
const names = query<TypeNames>(contract, { kind: "type-names" });
|
|
188
|
+
const signatures = query<Readonly<Record<string, string>>>(contract, {
|
|
189
|
+
kind: "client-signatures",
|
|
190
|
+
});
|
|
191
|
+
const source = `${path.basename(wit)}${options.world ? `, world ${options.world}` : ""}`;
|
|
192
|
+
const out = path.resolve(options.out);
|
|
193
|
+
const modules = new Map<string, string>();
|
|
194
|
+
for (const entry of graph.exports) {
|
|
195
|
+
const identity = entry.contract;
|
|
196
|
+
if (!identity || !entry.functions || entry.type_only || identity === HTTP_HANDLER) continue;
|
|
197
|
+
const file = path.join(out, `${identity.replace(/@[^@]*$/, "").replace(/[:/]/g, "-")}.ts`);
|
|
198
|
+
if (modules.has(file))
|
|
199
|
+
throw new Error(`${identity} and another exported interface share the module ${file}`);
|
|
200
|
+
modules.set(file, clientModule(graph, names, identity, entry, source, signatures[identity]));
|
|
201
|
+
}
|
|
202
|
+
if (modules.size === 0) throw new Error(`${source} exports no interface a host can call`);
|
|
203
|
+
await mkdir(out, { recursive: true });
|
|
204
|
+
for (const [file, contents] of modules) {
|
|
205
|
+
const previous = await readFile(file, "utf8").catch((error: NodeJS.ErrnoException) => {
|
|
206
|
+
if (error.code === "ENOENT") return undefined;
|
|
207
|
+
throw error;
|
|
208
|
+
});
|
|
209
|
+
if (previous === contents) continue;
|
|
210
|
+
const temporary = `${file}.${process.pid}.tmp`;
|
|
211
|
+
await writeFile(temporary, contents);
|
|
212
|
+
await rename(temporary, file);
|
|
213
|
+
}
|
|
214
|
+
return [...modules.keys()].sort();
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
/** The module of one exported interface. */
|
|
218
|
+
function clientModule(
|
|
219
|
+
graph: Described,
|
|
220
|
+
names: TypeNames,
|
|
221
|
+
identity: string,
|
|
222
|
+
entry: Described["exports"][number],
|
|
223
|
+
source: string,
|
|
224
|
+
signature?: string,
|
|
225
|
+
): string {
|
|
226
|
+
const interfaceName = /\/([^@/]+)(?:@[^@]*)?$/.exec(identity)?.[1];
|
|
227
|
+
if (!interfaceName) throw new Error(`${identity} is not a versioned interface identity`);
|
|
228
|
+
const spelled = graph.javascriptNames[interfaceName] ?? bindingName(interfaceName, false);
|
|
229
|
+
const pascal = spelled.charAt(0).toUpperCase() + spelled.slice(1);
|
|
230
|
+
const service = OWN.has(pascal) ? `${pascal}_` : pascal;
|
|
231
|
+
const functions = Object.values(entry.functions ?? {});
|
|
232
|
+
const occupied = new Set([...OWN, service]);
|
|
233
|
+
const resourceTypes = resourceNaming(graph, entry.resources ?? {}, identity, occupied);
|
|
234
|
+
const resourceNames = resourceTypes.names;
|
|
235
|
+
const resources = resourceNames.size > 0;
|
|
236
|
+
const { render, declarations } = renderer(
|
|
237
|
+
graph,
|
|
238
|
+
names,
|
|
239
|
+
identity,
|
|
240
|
+
occupied,
|
|
241
|
+
functions.flatMap((fn) => [
|
|
242
|
+
...fn.params.filter((p) => p.name !== "self").map((p) => p.type),
|
|
243
|
+
fn.result,
|
|
244
|
+
]),
|
|
245
|
+
resourceNames,
|
|
246
|
+
);
|
|
247
|
+
const signatures: string[] = [];
|
|
248
|
+
const members: string[] = [];
|
|
249
|
+
const resourceSignatures = new Map([...resourceNames].map(([id]) => [id, [] as string[]]));
|
|
250
|
+
const used = new Map<string, Set<string>>();
|
|
251
|
+
for (const fn of functions.sort((a, b) => a.name.localeCompare(b.name))) {
|
|
252
|
+
const kind = typeof fn.kind === "object" ? Object.entries(fn.kind)[0] : undefined;
|
|
253
|
+
const receiver = kind?.[0] === "method" || kind?.[0] === "async-method";
|
|
254
|
+
const resource = kind ? resourceNames.get(resourceTypes.canonical(kind[1])) : undefined;
|
|
255
|
+
const member = fn.name.split(".").at(-1)!;
|
|
256
|
+
const method =
|
|
257
|
+
kind?.[0] === "constructor"
|
|
258
|
+
? `new${resource}`
|
|
259
|
+
: kind
|
|
260
|
+
? receiver
|
|
261
|
+
? bindingName(member, false)
|
|
262
|
+
: `${resource!.charAt(0).toLowerCase()}${resource!.slice(1)}${bindingName(member, false).charAt(0).toUpperCase()}${bindingName(member, false).slice(1)}`
|
|
263
|
+
: (graph.javascriptNames[fn.name] ?? bindingName(fn.name, false));
|
|
264
|
+
if (kind && !resource)
|
|
265
|
+
throw new Error(`${identity}: resource function has no defining resource`);
|
|
266
|
+
if (
|
|
267
|
+
Object.hasOwn(MEMBERS, fn.name) ||
|
|
268
|
+
Object.hasOwn(MEMBERS, method) ||
|
|
269
|
+
method === "resourceType"
|
|
270
|
+
)
|
|
271
|
+
throw new Error(
|
|
272
|
+
`${identity}: ${fn.name} collides with a member every client has (${Object.keys(MEMBERS).join(", ")})`,
|
|
273
|
+
);
|
|
274
|
+
const scope = receiver ? resource! : service;
|
|
275
|
+
const methodNames = used.get(scope) ?? new Set<string>();
|
|
276
|
+
if (methodNames.has(method))
|
|
277
|
+
throw new Error(`${identity}: generated method collision: ${scope}.${method}`);
|
|
278
|
+
methodNames.add(method);
|
|
279
|
+
used.set(scope, methodNames);
|
|
280
|
+
const taken = new Set<string>();
|
|
281
|
+
const params = receiver ? fn.params.slice(1) : fn.params;
|
|
282
|
+
const parameters = params.map((parameter) => {
|
|
283
|
+
let name = bindingName(parameter.name, false);
|
|
284
|
+
while (RESERVED.has(name) || taken.has(name)) name += "_";
|
|
285
|
+
taken.add(name);
|
|
286
|
+
return `${name}: ${render(parameter.type)}`;
|
|
287
|
+
});
|
|
288
|
+
parameters.push("context?: Context");
|
|
289
|
+
const result = fn.result === undefined || fn.result === null ? "void" : render(fn.result);
|
|
290
|
+
const key = method === "new" ? JSON.stringify(method) : method;
|
|
291
|
+
const declaration = ` ${key}(${parameters.join(", ")}): Promise<${result}>;`;
|
|
292
|
+
if (receiver) resourceSignatures.get(resourceTypes.canonical(kind![1]))!.push(declaration);
|
|
293
|
+
else {
|
|
294
|
+
signatures.push(declaration);
|
|
295
|
+
members.push(
|
|
296
|
+
` ${method}: (...args) => calls.call<${result}>(${JSON.stringify(fn.name)}, sent(args, ${params.length})),`,
|
|
297
|
+
);
|
|
298
|
+
}
|
|
299
|
+
}
|
|
300
|
+
const wrappers = [...resourceNames].flatMap(([id, name]) => {
|
|
301
|
+
return [
|
|
302
|
+
`/** An owned WIT resource. Release it when its work ends. */`,
|
|
303
|
+
`export interface ${name} extends WitResource {`,
|
|
304
|
+
` readonly resourceType: ${JSON.stringify(resourceTypes.nominals.get(id))};`,
|
|
305
|
+
...resourceSignatures.get(id)!,
|
|
306
|
+
`}`,
|
|
307
|
+
``,
|
|
308
|
+
];
|
|
309
|
+
});
|
|
310
|
+
const schema = [
|
|
311
|
+
`const schema = ${JSON.stringify({ identity, signature, resources: entry.resources ?? {}, functions: entry.functions, types: graph.types, javascriptNames: graph.javascriptNames, imports: (graph.imports ?? []).map(({ binding, contract }) => ({ binding, ...(contract ? { contract } : {}) })) })} satisfies WitClientSchema;`,
|
|
312
|
+
``,
|
|
313
|
+
];
|
|
314
|
+
return [
|
|
315
|
+
`// Generated by \`client\` from @syntropika/tembra-sdk/tooling: the typed client of`,
|
|
316
|
+
`// ${identity} (${source}). Regenerate it instead of editing it.`,
|
|
317
|
+
`import { witClient } from "@syntropika/tembra-sdk";`,
|
|
318
|
+
`import type {`,
|
|
319
|
+
` AcquisitionOptions,`,
|
|
320
|
+
` Context,`,
|
|
321
|
+
` DynamicReference,`,
|
|
322
|
+
` ReferenceBase,`,
|
|
323
|
+
...(resources ? [` WitResource,`] : []),
|
|
324
|
+
` WitClientSchema,`,
|
|
325
|
+
`} from "@syntropika/tembra-sdk";`,
|
|
326
|
+
``,
|
|
327
|
+
`/** The interface identity; an Orb's service is named \`<orb>::<identity>\`. */`,
|
|
328
|
+
`export const IDENTITY = ${JSON.stringify(identity)};`,
|
|
329
|
+
``,
|
|
330
|
+
...declarations(),
|
|
331
|
+
...wrappers,
|
|
332
|
+
...resourceTypes.aliases,
|
|
333
|
+
...schema,
|
|
334
|
+
`/** One object's \`${identity}\`, with the values a host sends and receives. */`,
|
|
335
|
+
`export interface ${service} {`,
|
|
336
|
+
` /** The acquired reference: its readiness, status, state and \`release()\`. */`,
|
|
337
|
+
` readonly reference: ReferenceBase;`,
|
|
338
|
+
...signatures,
|
|
339
|
+
`}`,
|
|
340
|
+
``,
|
|
341
|
+
`/** Acquire the service of \`orb\` under \`key\` through a \`Host\` or a \`Context\`. */`,
|
|
342
|
+
`export async function get(`,
|
|
343
|
+
` scope: {`,
|
|
344
|
+
` get(`,
|
|
345
|
+
` service: string,`,
|
|
346
|
+
` key: string | readonly string[],`,
|
|
347
|
+
` options?: AcquisitionOptions,`,
|
|
348
|
+
` ): Promise<DynamicReference>;`,
|
|
349
|
+
` },`,
|
|
350
|
+
` address: { orb: string; key: string | readonly string[] },`,
|
|
351
|
+
` options?: AcquisitionOptions,`,
|
|
352
|
+
`): Promise<${service}> {`,
|
|
353
|
+
` const reference = await scope.get(\`\${address.orb}::\${IDENTITY}\`, address.key, options);`,
|
|
354
|
+
` let calls;`,
|
|
355
|
+
` try { calls = witClient(reference, schema); }`,
|
|
356
|
+
` catch (error) { reference.release(); throw error; }`,
|
|
357
|
+
// Typed by its declaration, not by the async return, which also admits a `PromiseLike`: its
|
|
358
|
+
// `Object` members would leave the arguments of `toString` or `valueOf` untyped.
|
|
359
|
+
` const client: ${service} = {`,
|
|
360
|
+
` reference,`,
|
|
361
|
+
...members,
|
|
362
|
+
` };`,
|
|
363
|
+
` return client;`,
|
|
364
|
+
`}`,
|
|
365
|
+
``,
|
|
366
|
+
`/** The arguments a call sends: a trailing context given as \`undefined\` is not one of them. */`,
|
|
367
|
+
`function sent(args: readonly unknown[], count: number): readonly unknown[] {`,
|
|
368
|
+
` return args.length === count + 1 && args[count] === undefined ? args.slice(0, count) : args;`,
|
|
369
|
+
`}`,
|
|
370
|
+
``,
|
|
371
|
+
].join("\n");
|
|
372
|
+
}
|
|
373
|
+
|
|
374
|
+
/**
|
|
375
|
+
* Render WIT value types as the TypeScript of the host's value form; memoized per type id. A type
|
|
376
|
+
* the contract names renders as its name, which takes a `_` where `taken` has it;
|
|
377
|
+
* `declarations()` then answers the exported type of each one `roots` reach, in name order. The
|
|
378
|
+
* names are chosen over every type `roots` reach before any renders, so that none depends on the
|
|
379
|
+
* order the functions render in: two different types of one name are named after the interface
|
|
380
|
+
* that declares each (`APoint`, `BPoint`), and two that still share a name are refused, each
|
|
381
|
+
* named with the interface where its name is written.
|
|
382
|
+
*/
|
|
383
|
+
function renderer(
|
|
384
|
+
graph: Described,
|
|
385
|
+
names: TypeNames,
|
|
386
|
+
identity: string,
|
|
387
|
+
taken: ReadonlySet<string>,
|
|
388
|
+
roots: readonly WitType[],
|
|
389
|
+
resources: ReadonlyMap<number, string> = new Map(),
|
|
390
|
+
): { render: (type: WitType) => string; declarations: () => string[] } {
|
|
391
|
+
const kinds = new Map(graph.types.map(({ id, definition }) => [id, definition.kind]));
|
|
392
|
+
const wit = new Map(names.map((entry) => [entry.id, entry]));
|
|
393
|
+
const rendered = new Map<number, string>();
|
|
394
|
+
/** The definition an alias stands for, which a type and its aliases share. */
|
|
395
|
+
const target = (type: number): number => {
|
|
396
|
+
const kind = kinds.get(type);
|
|
397
|
+
return typeof kind === "object" && typeof kind.type === "number" ? target(kind.type) : type;
|
|
398
|
+
};
|
|
399
|
+
/** Every named type the roots reach, through the definitions of the types they reach. */
|
|
400
|
+
const reached = new Set<number>();
|
|
401
|
+
const visited = new Set<number>();
|
|
402
|
+
const reach = (type: WitType): void => {
|
|
403
|
+
if (typeof type !== "number" || visited.has(type)) return;
|
|
404
|
+
visited.add(type);
|
|
405
|
+
// A named alias renders as its own name and declares its definition's members: the type
|
|
406
|
+
// it stands for is not reached by it.
|
|
407
|
+
if (wit.has(type)) reached.add(type);
|
|
408
|
+
const kind = kinds.get(wit.has(type) ? target(type) : type);
|
|
409
|
+
if (kind === undefined || typeof kind === "string") return;
|
|
410
|
+
[
|
|
411
|
+
kind.type,
|
|
412
|
+
kind.list,
|
|
413
|
+
kind.option,
|
|
414
|
+
...(kind.record?.fields.map((field) => field.type) ?? []),
|
|
415
|
+
...(kind.tuple?.types ?? []),
|
|
416
|
+
...(kind.variant?.cases.map((item) => item.type) ?? []),
|
|
417
|
+
kind.result?.ok,
|
|
418
|
+
kind.result?.err,
|
|
419
|
+
].forEach(reach);
|
|
420
|
+
};
|
|
421
|
+
roots.forEach(reach);
|
|
422
|
+
const ordered = [...reached].sort((a, b) => a - b);
|
|
423
|
+
/** The definitions each spelling alone would name in this module. */
|
|
424
|
+
const spellings = new Map<string, Set<number>>();
|
|
425
|
+
for (const type of ordered) {
|
|
426
|
+
const { javascript } = wit.get(type)!;
|
|
427
|
+
spellings.set(javascript, (spellings.get(javascript) ?? new Set()).add(target(type)));
|
|
428
|
+
}
|
|
429
|
+
/** The name of each named type, and the type each name declares. */
|
|
430
|
+
const naming = new Map<number, string>();
|
|
431
|
+
const named = new Map<string, number>();
|
|
432
|
+
for (const type of ordered) {
|
|
433
|
+
const entry = wit.get(type)!;
|
|
434
|
+
let spelled = spellings.get(entry.javascript)!.size > 1 ? entry.qualified : entry.javascript;
|
|
435
|
+
while (taken.has(spelled)) spelled += "_";
|
|
436
|
+
const other = named.get(spelled);
|
|
437
|
+
if (other === undefined) named.set(spelled, type);
|
|
438
|
+
else if (target(other) !== target(type)) {
|
|
439
|
+
const [first, second] = [wit.get(other)!, entry]
|
|
440
|
+
.map((each) => `${each.name}${each.interface ? ` of ${each.interface}` : ""}`)
|
|
441
|
+
.sort();
|
|
442
|
+
throw new Error(`${identity}: the WIT types ${first} and ${second} both name ${spelled}`);
|
|
443
|
+
}
|
|
444
|
+
naming.set(type, spelled);
|
|
445
|
+
}
|
|
446
|
+
const refuse = (what: string): never => {
|
|
447
|
+
throw new Error(`${identity}: ${what} is outside the portable value profile`);
|
|
448
|
+
};
|
|
449
|
+
const spelling = (name: string): string => {
|
|
450
|
+
const spelled = graph.javascriptNames[name];
|
|
451
|
+
if (spelled === undefined) throw new Error(`${identity}: missing JavaScript name for ${name}`);
|
|
452
|
+
return spelled;
|
|
453
|
+
};
|
|
454
|
+
/** Whether a type renders as a union, which a list item must parenthesize. */
|
|
455
|
+
const union = (type: WitType): boolean => {
|
|
456
|
+
if (typeof type !== "number") return false;
|
|
457
|
+
const kind = kinds.get(type);
|
|
458
|
+
if (kind === undefined || typeof kind === "string" || wit.has(type)) return false;
|
|
459
|
+
if (kind.type !== undefined) return union(kind.type);
|
|
460
|
+
return (
|
|
461
|
+
kind.option !== undefined ||
|
|
462
|
+
kind.variant !== undefined ||
|
|
463
|
+
kind.result !== undefined ||
|
|
464
|
+
(kind.enum !== undefined && kind.enum.cases.length > 1)
|
|
465
|
+
);
|
|
466
|
+
};
|
|
467
|
+
const payload = (tag: string, type: WitType): string =>
|
|
468
|
+
type === null || type === undefined
|
|
469
|
+
? `{ tag: ${JSON.stringify(tag)} }`
|
|
470
|
+
: `{ tag: ${JSON.stringify(tag)}; val: ${render(type)} }`;
|
|
471
|
+
const kind = (definition: WitKind | string): string => {
|
|
472
|
+
if (typeof definition === "string") return refuse(definition);
|
|
473
|
+
if (definition.type !== undefined) return render(definition.type);
|
|
474
|
+
if (definition.handle?.own !== undefined)
|
|
475
|
+
return resources.get(target(definition.handle.own)) ?? refuse("a foreign owned resource");
|
|
476
|
+
if (definition.handle?.borrow !== undefined) return refuse("an explicit resource borrow");
|
|
477
|
+
if (definition.list !== undefined) {
|
|
478
|
+
const item = render(definition.list);
|
|
479
|
+
return union(definition.list) ? `(${item})[]` : `${item}[]`;
|
|
480
|
+
}
|
|
481
|
+
if (definition.option !== undefined) return `${render(definition.option)} | null`;
|
|
482
|
+
if (definition.record)
|
|
483
|
+
return `{ ${definition.record.fields
|
|
484
|
+
.map((field) => `${spelling(field.name)}: ${render(field.type)}`)
|
|
485
|
+
.join("; ")} }`;
|
|
486
|
+
if (definition.tuple) return `[${definition.tuple.types.map(render).join(", ")}]`;
|
|
487
|
+
if (definition.variant)
|
|
488
|
+
return definition.variant.cases.map((item) => payload(item.name, item.type)).join(" | ");
|
|
489
|
+
if (definition.enum)
|
|
490
|
+
return definition.enum.cases.map((item) => JSON.stringify(item.name)).join(" | ");
|
|
491
|
+
if (definition.flags)
|
|
492
|
+
return `{ ${definition.flags.flags
|
|
493
|
+
.map((flag) => `${spelling(flag.name)}?: boolean`)
|
|
494
|
+
.join("; ")} }`;
|
|
495
|
+
if (definition.result)
|
|
496
|
+
return `${payload("ok", definition.result.ok)} | ${payload("err", definition.result.err)}`;
|
|
497
|
+
return refuse(Object.keys(definition)[0] ?? "an unknown WIT type");
|
|
498
|
+
};
|
|
499
|
+
const render = (type: WitType): string => {
|
|
500
|
+
if (type === null || type === undefined) throw new Error(`${identity}: a type is missing`);
|
|
501
|
+
if (typeof type === "string") return PRIMITIVES[type] ?? refuse(type);
|
|
502
|
+
const resource = resources.get(target(type));
|
|
503
|
+
if (resource !== undefined) return resource;
|
|
504
|
+
const known = rendered.get(type);
|
|
505
|
+
if (known !== undefined) return known;
|
|
506
|
+
const definition = kinds.get(type);
|
|
507
|
+
if (definition === undefined) throw new Error(`${identity}: unknown WIT type ${type}`);
|
|
508
|
+
const spelled = naming.get(type);
|
|
509
|
+
if (spelled !== undefined) return spelled;
|
|
510
|
+
const text = kind(definition);
|
|
511
|
+
rendered.set(type, text);
|
|
512
|
+
return text;
|
|
513
|
+
};
|
|
514
|
+
/** One exported type per name, for each named type the roots reach. */
|
|
515
|
+
const declarations = (): string[] => {
|
|
516
|
+
const declared = new Map<string, string[]>();
|
|
517
|
+
for (const [spelled, type] of named) {
|
|
518
|
+
const definition = kinds.get(target(type)) as WitKind;
|
|
519
|
+
const what = Object.keys(definition).find((key) => definition[key] !== undefined);
|
|
520
|
+
declared.set(spelled, [
|
|
521
|
+
`/** The WIT ${what} \`${wit.get(type)!.name}\`. */`,
|
|
522
|
+
`export type ${spelled} = ${kind(definition)};`,
|
|
523
|
+
``,
|
|
524
|
+
]);
|
|
525
|
+
}
|
|
526
|
+
return [...declared]
|
|
527
|
+
.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
|
|
528
|
+
.flatMap(([, lines]) => lines);
|
|
529
|
+
};
|
|
530
|
+
return { render, declarations };
|
|
531
|
+
}
|