tessl/npm-jsii

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

jsii Toolchain

Name: tessl/npm-jsii
Author: tessl

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;
}