or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

assembly-reflection.mdassembly-specification.mdcode-generation.mdindex.mdproject-configuration.mdruntime-libraries.md
tile.json

tessl/npm-jsii

jsii allows code in any language to naturally interact with JavaScript classes, enabling polyglot libraries from a single codebase.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/jsii@1.114.x

To install, run

npx @tessl/cli install tessl/npm-jsii@1.114.0

index.mddocs/

jsii Toolchain

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.

Package Information

  • Package Name: jsii (monorepo with multiple packages)
  • Package Type: Multi-package npm monorepo
  • Language: TypeScript/JavaScript
  • Installation: Individual packages: @jsii/spec, jsii-pacmak, jsii-reflect, @jsii/runtime, etc.
  • Repository: https://github.com/aws/jsii

Core Imports

// Assembly specification interfaces
import { Assembly, TypeReference, ClassType } from '@jsii/spec';

// Runtime host for JavaScript execution
import { KernelHost } from '@jsii/runtime';

// Kernel for assembly execution
import { Kernel, api } from '@jsii/kernel';

// Code generation for target languages
import { pacmak, TargetName } from 'jsii-pacmak';

// Assembly reflection and analysis
import { TypeSystem, Assembly as ReflectAssembly } from 'jsii-reflect';

// Interactive configuration
import jsiiConfig from 'jsii-config';

Basic Usage

// Generate bindings for target languages
import { pacmak, TargetName } from 'jsii-pacmak';

await pacmak({
  assemblies: ['/path/to/assembly.jsii'],
  targets: [TargetName.PYTHON, TargetName.JAVA],
  outdir: './dist',
});

// Load and reflect on assemblies
import { TypeSystem } from 'jsii-reflect';

const typeSys = new TypeSystem();
const assembly = typeSys.loadAssembly('/path/to/assembly.jsii');

// Examine classes and interfaces
for (const cls of assembly.classes) {
  console.log(`Class: ${cls.name}`);
  for (const method of cls.ownMethods) {
    console.log(`  Method: ${method.name}`);
  }
}

Architecture

The jsii toolchain consists of several interconnected components:

  • Compiler (jsii): Compiles TypeScript to .jsii assembly files with metadata
  • Assembly Specification: Defines the schema for .jsii files containing type information
  • Runtime System: Executes jsii assemblies across different language environments
  • Code Generation: Creates native bindings for Python, Java, .NET, Go, and JavaScript
  • Reflection API: Provides programmatic access to assembly metadata
  • Configuration Tools: Interactive setup and project configuration utilities

The workflow typically follows: TypeScript source → jsii compilation → .jsii assembly → target language binding generation → runtime execution in target languages.

Capabilities

Assembly Specification

Core interfaces and types that define the .jsii assembly format, including type definitions, metadata structures, and validation schemas.

interface Assembly {
  schema: SchemaVersion;
  name: string;
  version: string;
  types?: { [fqn: string]: Type };
  dependencies?: { [name: string]: DependencyConfiguration };
  bundled?: { [name: string]: string };
  targets?: AssemblyTargets;
  metadata?: { [key: string]: any };
}

interface ClassType extends TypeBase {
  kind: TypeKind.Class;
  abstract?: boolean;
  base?: string;
  interfaces?: string[];
  initializer?: Initializer;
  properties?: Property[];
  methods?: Method[];
}

interface InterfaceType extends TypeBase {
  kind: TypeKind.Interface;
  properties?: Property[];
  methods?: Method[];
  datatype?: boolean;
}

enum TypeKind {
  Class = "class",
  Enum = "enum", 
  Interface = "interface"
}

Assembly Specification

Runtime Libraries

JavaScript runtime host and kernel system for executing jsii assemblies, with multi-language client implementations for Python, Java, .NET, and Go.

class KernelHost {
  run(): Promise<void>;
  close(): Promise<void>;
}

class Kernel {
  load(req: api.LoadRequest): api.LoadResponse;
  create(req: api.CreateRequest): api.CreateResponse;
  invoke(req: api.InvokeRequest): api.GetResponse;
  get(req: api.GetRequest): api.GetResponse;
  set(req: api.SetRequest): api.SetResponse;
}

namespace api {
  interface LoadRequest {
    name: string;
    version: string;
    tarball?: string;
  }

  interface CreateRequest {
    fqn: string;
    args?: any[];
    overrides?: Override[];
  }
}

Runtime Libraries

Code Generation

Multi-language bindings generator that creates native libraries for Python, Java, .NET, Go, and JavaScript from jsii assemblies.

function pacmak(options: PacmakOptions): Promise<void>;

interface PacmakOptions {
  assemblies: string[];
  targets: TargetName[];
  outdir: string;
  fingerprint?: boolean;
  force?: boolean;
  arguments?: { [target: string]: { [key: string]: any } };
}

enum TargetName {
  DOTNET = "dotnet",
  GO = "go", 
  JAVA = "java",
  JAVASCRIPT = "js",
  PYTHON = "python"
}

Code Generation

Assembly Reflection

Strongly-typed reflection library for analyzing and inspecting jsii assemblies, enabling tooling and code generation workflows.

class TypeSystem {
  loadAssembly(path: string): Assembly;
  tryLoadAssembly(path: string): Assembly | undefined;
  loadModule(name: string): Assembly;
  get assemblies(): Assembly[];
}

class Assembly extends ModuleLike {
  readonly name: string;
  readonly version: string;
  readonly classes: Class[];
  readonly interfaces: Interface[];
  readonly enums: Enum[];
  readonly dependencies: Dependency[];
}

class Class extends ReferenceType {
  readonly initializer?: Initializer;
  readonly abstract: boolean;
  readonly base?: Class;
  readonly interfaces: Interface[];
  readonly ownProperties: Property[];
  readonly ownMethods: Method[];
}

Assembly Reflection

Project Configuration

Interactive CLI tool for configuring jsii module settings in package.json, including target language configurations and build settings.

function jsiiConfig(): Promise<void>;

interface Config {
  projectInfo?: {
    name?: string;
    version?: string;
    description?: string;
  };
  targets?: {
    [language: string]: any;
  };
  metadata?: {
    jsii?: {
      [key: string]: any;
    };
  };
}

interface PackageJson {
  name: string;
  version: string;
  jsii?: Config;
  [key: string]: any;
}

Project Configuration

Types

// Core assembly types
type FQN = string;
type SchemaVersion = "jsii/0.10.0";

interface SourceLocation {
  filename: string;
  line: number;
  column: number;
}

interface Docs {
  summary?: string;
  remarks?: string;
  returns?: string;
  default?: string;
  deprecated?: string;
  example?: string;
  see?: string;
  since?: string;
  subclassable?: boolean;
  [key: string]: any;
}

enum Stability {
  Deprecated = "deprecated",
  Experimental = "experimental", 
  Stable = "stable",
  External = "external"
}

enum PrimitiveType {
  Date = "date",
  String = "string",
  Number = "number",
  Boolean = "boolean",
  Json = "json",
  Any = "any"
}

enum CollectionKind {
  Array = "array",
  Map = "map"
}

// Runtime communication types
interface ObjRef {
  [TOKEN_REF]: string;
  [TOKEN_INTERFACES]?: string[];
}

interface Override {
  method?: string;
  property?: string;
  cookie?: string;
}