0
# jsii Toolchain
1
2
jsii allows code in any language to naturally interact with JavaScript classes, enabling polyglot libraries from a single codebase. It provides a complete toolchain for building cross-language libraries that work seamlessly across TypeScript/JavaScript, Python, Java, .NET, and Go.
3
4
## Package Information
5
6
- **Package Name**: jsii (monorepo with multiple packages)
7
- **Package Type**: Multi-package npm monorepo
8
- **Language**: TypeScript/JavaScript
9
- **Installation**: Individual packages: `@jsii/spec`, `jsii-pacmak`, `jsii-reflect`, `@jsii/runtime`, etc.
10
- **Repository**: https://github.com/aws/jsii
11
12
## Core Imports
13
14
```typescript
15
// Assembly specification interfaces
16
import { Assembly, TypeReference, ClassType } from '@jsii/spec';
17
18
// Runtime host for JavaScript execution
19
import { KernelHost } from '@jsii/runtime';
20
21
// Kernel for assembly execution
22
import { Kernel, api } from '@jsii/kernel';
23
24
// Code generation for target languages
25
import { pacmak, TargetName } from 'jsii-pacmak';
26
27
// Assembly reflection and analysis
28
import { TypeSystem, Assembly as ReflectAssembly } from 'jsii-reflect';
29
30
// Interactive configuration
31
import jsiiConfig from 'jsii-config';
32
```
33
34
## Basic Usage
35
36
```typescript
37
// Generate bindings for target languages
38
import { pacmak, TargetName } from 'jsii-pacmak';
39
40
await pacmak({
41
assemblies: ['/path/to/assembly.jsii'],
42
targets: [TargetName.PYTHON, TargetName.JAVA],
43
outdir: './dist',
44
});
45
46
// Load and reflect on assemblies
47
import { TypeSystem } from 'jsii-reflect';
48
49
const typeSys = new TypeSystem();
50
const assembly = typeSys.loadAssembly('/path/to/assembly.jsii');
51
52
// Examine classes and interfaces
53
for (const cls of assembly.classes) {
54
console.log(`Class: ${cls.name}`);
55
for (const method of cls.ownMethods) {
56
console.log(` Method: ${method.name}`);
57
}
58
}
59
```
60
61
## Architecture
62
63
The jsii toolchain consists of several interconnected components:
64
65
- **Compiler (jsii)**: Compiles TypeScript to .jsii assembly files with metadata
66
- **Assembly Specification**: Defines the schema for .jsii files containing type information
67
- **Runtime System**: Executes jsii assemblies across different language environments
68
- **Code Generation**: Creates native bindings for Python, Java, .NET, Go, and JavaScript
69
- **Reflection API**: Provides programmatic access to assembly metadata
70
- **Configuration Tools**: Interactive setup and project configuration utilities
71
72
The workflow typically follows: TypeScript source → jsii compilation → .jsii assembly → target language binding generation → runtime execution in target languages.
73
74
## Capabilities
75
76
### Assembly Specification
77
78
Core interfaces and types that define the .jsii assembly format, including type definitions, metadata structures, and validation schemas.
79
80
```typescript { .api }
81
interface Assembly {
82
schema: SchemaVersion;
83
name: string;
84
version: string;
85
types?: { [fqn: string]: Type };
86
dependencies?: { [name: string]: DependencyConfiguration };
87
bundled?: { [name: string]: string };
88
targets?: AssemblyTargets;
89
metadata?: { [key: string]: any };
90
}
91
92
interface ClassType extends TypeBase {
93
kind: TypeKind.Class;
94
abstract?: boolean;
95
base?: string;
96
interfaces?: string[];
97
initializer?: Initializer;
98
properties?: Property[];
99
methods?: Method[];
100
}
101
102
interface InterfaceType extends TypeBase {
103
kind: TypeKind.Interface;
104
properties?: Property[];
105
methods?: Method[];
106
datatype?: boolean;
107
}
108
109
enum TypeKind {
110
Class = "class",
111
Enum = "enum",
112
Interface = "interface"
113
}
114
```
115
116
[Assembly Specification](./assembly-specification.md)
117
118
### Runtime Libraries
119
120
JavaScript runtime host and kernel system for executing jsii assemblies, with multi-language client implementations for Python, Java, .NET, and Go.
121
122
```typescript { .api }
123
class KernelHost {
124
run(): Promise<void>;
125
close(): Promise<void>;
126
}
127
128
class Kernel {
129
load(req: api.LoadRequest): api.LoadResponse;
130
create(req: api.CreateRequest): api.CreateResponse;
131
invoke(req: api.InvokeRequest): api.GetResponse;
132
get(req: api.GetRequest): api.GetResponse;
133
set(req: api.SetRequest): api.SetResponse;
134
}
135
136
namespace api {
137
interface LoadRequest {
138
name: string;
139
version: string;
140
tarball?: string;
141
}
142
143
interface CreateRequest {
144
fqn: string;
145
args?: any[];
146
overrides?: Override[];
147
}
148
}
149
```
150
151
[Runtime Libraries](./runtime-libraries.md)
152
153
### Code Generation
154
155
Multi-language bindings generator that creates native libraries for Python, Java, .NET, Go, and JavaScript from jsii assemblies.
156
157
```typescript { .api }
158
function pacmak(options: PacmakOptions): Promise<void>;
159
160
interface PacmakOptions {
161
assemblies: string[];
162
targets: TargetName[];
163
outdir: string;
164
fingerprint?: boolean;
165
force?: boolean;
166
arguments?: { [target: string]: { [key: string]: any } };
167
}
168
169
enum TargetName {
170
DOTNET = "dotnet",
171
GO = "go",
172
JAVA = "java",
173
JAVASCRIPT = "js",
174
PYTHON = "python"
175
}
176
```
177
178
[Code Generation](./code-generation.md)
179
180
### Assembly Reflection
181
182
Strongly-typed reflection library for analyzing and inspecting jsii assemblies, enabling tooling and code generation workflows.
183
184
```typescript { .api }
185
class TypeSystem {
186
loadAssembly(path: string): Assembly;
187
tryLoadAssembly(path: string): Assembly | undefined;
188
loadModule(name: string): Assembly;
189
get assemblies(): Assembly[];
190
}
191
192
class Assembly extends ModuleLike {
193
readonly name: string;
194
readonly version: string;
195
readonly classes: Class[];
196
readonly interfaces: Interface[];
197
readonly enums: Enum[];
198
readonly dependencies: Dependency[];
199
}
200
201
class Class extends ReferenceType {
202
readonly initializer?: Initializer;
203
readonly abstract: boolean;
204
readonly base?: Class;
205
readonly interfaces: Interface[];
206
readonly ownProperties: Property[];
207
readonly ownMethods: Method[];
208
}
209
```
210
211
[Assembly Reflection](./assembly-reflection.md)
212
213
### Project Configuration
214
215
Interactive CLI tool for configuring jsii module settings in package.json, including target language configurations and build settings.
216
217
```typescript { .api }
218
function jsiiConfig(): Promise<void>;
219
220
interface Config {
221
projectInfo?: {
222
name?: string;
223
version?: string;
224
description?: string;
225
};
226
targets?: {
227
[language: string]: any;
228
};
229
metadata?: {
230
jsii?: {
231
[key: string]: any;
232
};
233
};
234
}
235
236
interface PackageJson {
237
name: string;
238
version: string;
239
jsii?: Config;
240
[key: string]: any;
241
}
242
```
243
244
[Project Configuration](./project-configuration.md)
245
246
## Types
247
248
```typescript { .api }
249
// Core assembly types
250
type FQN = string;
251
type SchemaVersion = "jsii/0.10.0";
252
253
interface SourceLocation {
254
filename: string;
255
line: number;
256
column: number;
257
}
258
259
interface Docs {
260
summary?: string;
261
remarks?: string;
262
returns?: string;
263
default?: string;
264
deprecated?: string;
265
example?: string;
266
see?: string;
267
since?: string;
268
subclassable?: boolean;
269
[key: string]: any;
270
}
271
272
enum Stability {
273
Deprecated = "deprecated",
274
Experimental = "experimental",
275
Stable = "stable",
276
External = "external"
277
}
278
279
enum PrimitiveType {
280
Date = "date",
281
String = "string",
282
Number = "number",
283
Boolean = "boolean",
284
Json = "json",
285
Any = "any"
286
}
287
288
enum CollectionKind {
289
Array = "array",
290
Map = "map"
291
}
292
293
// Runtime communication types
294
interface ObjRef {
295
[TOKEN_REF]: string;
296
[TOKEN_INTERFACES]?: string[];
297
}
298
299
interface Override {
300
method?: string;
301
property?: string;
302
cookie?: string;
303
}
304
```