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
```