jsii-reflect

What is jsii-reflect?

The jsii-reflect package is a library for reflecting on jsii-based libraries. It allows you to inspect the structure of jsii modules, including classes, interfaces, enums, and other types. This can be useful for generating documentation, performing static analysis, or building tools that need to understand the structure of jsii modules.

What are jsii-reflect's main functionalities?

Loading Assemblies

This feature allows you to load a jsii assembly from a specified path. The assembly object can then be used to inspect the types and other metadata defined in the assembly.

const reflect = require('jsii-reflect');
const assembly = new reflect.Assembly(new reflect.TypeSystem(), 'path/to/assembly');

Inspecting Classes

This feature allows you to inspect the classes defined in a jsii assembly. You can list the classes and their methods, properties, and other members.

const classes = assembly.classes;
classes.forEach(cls => {
  console.log(`Class: ${cls.name}`);
  cls.methods.forEach(method => {
    console.log(`  Method: ${method.name}`);
  });
});

Inspecting Interfaces

This feature allows you to inspect the interfaces defined in a jsii assembly. You can list the interfaces and their methods, properties, and other members.

const interfaces = assembly.interfaces;
interfaces.forEach(iface => {
  console.log(`Interface: ${iface.name}`);
  iface.methods.forEach(method => {
    console.log(`  Method: ${method.name}`);
  });
});

Inspecting Enums

This feature allows you to inspect the enums defined in a jsii assembly. You can list the enums and their members.

const enums = assembly.enums;
enums.forEach(enumType => {
  console.log(`Enum: ${enumType.name}`);
  enumType.members.forEach(member => {
    console.log(`  Member: ${member.name}`);
  });
});

Other packages similar to jsii-reflect

typescript

The TypeScript package provides a compiler and language services for TypeScript. It allows you to perform static analysis and reflection on TypeScript code, similar to how jsii-reflect allows you to reflect on jsii modules. However, TypeScript is more general-purpose and not specific to jsii.

ts-morph

The ts-morph package is a TypeScript wrapper for the TypeScript compiler API. It provides a higher-level API for working with TypeScript projects, including reflection and code generation. Like jsii-reflect, it allows you to inspect the structure of TypeScript code, but it is not specific to jsii.

typedoc

The TypeDoc package generates documentation for TypeScript projects. It uses the TypeScript compiler API to inspect the structure of TypeScript code and generate documentation. While it is not a reflection library per se, it performs similar tasks to jsii-reflect in terms of inspecting code structure.

README

jsii-reflect: strongly-type reflection library and tools for jsii

jsii-reflect providers a reflection API for jsii type systems. It consumes .jsii manifest files (either directly or by traversing a closure of npm modules) and creates an in-memory object model that allows exploring the type system via a strongly-typed API.

Installation

Install the npm module:

$ npm i jsii-reflect

Import the TypeSystem class:

import { TypeSystem } from 'jsii-reflect';

Loading Assemblies

Create a TypeSystem:

const typesystem = new TypeSystem();

Now, we want to load assemblies into the type system via the typesystem.load() method.

You can either pass in a path to a .jsii file, in which case you will have to eventually load the .jsii files of all the dependencies.

typesystem.load('jsii-calc/.jsii');
typesystem.load('jsii-calc-lib/.jsii');
typesystem.load('jsii-calc-base/.jsii');
typesystem.load('jsii-calc-base-of-base/.jsii');

Or, you can point load to an npm module's directory, in which case the loader will transitively load all dependent modules:

// will automatically bring in all dependencies
typesystem.load('jsii-calc');

Reflecting on the Type System

Now that your TypeSystem is loaded with assemblies, you can use the APIs to query and reflect on the types.

For example:

const calc = typesystem.findClass('jsii-calc.Calculator');

const actual = new Array<string>();
calc.getMethods(/* inherited */ true).forEach(method => {
  actual.push(`${method.name} from ${method.parentType.name}`);
});

expect(actual).toEqual([
  "typeName from Base",
  "toString from Value",
  "toString from Operation",
  "toString from CompositeOperation",
  "add from Calculator",
  "mul from Calculator",
  "neg from Calculator",
  "pow from Calculator",
  "readUnionValue from Calculator"
]);

jsii-tree

jsii-tree is a command-line tool which can be used to print an ASCII tree of a jsii type system:

$ jsii-tree jsii-calc
assemblies
 ├─┬ jsii-calc
 │ └─┬ types
 │   ├── AbstractClass class
 │   ├── AbstractClassBase class
 │   ├── AbstractClassReturner class
 │   ├── Add class
 │   ├── AllTypes class
 │   ├── AllowedMethodNames class
 │   ├── AsyncVirtualMethods class
 │   ├── BinaryOperation class
 │   ├── Calculator class
 │   ├── ClassWithMutableObjectLiteralProperty class
 │   ├── ClassWithPrivateConstructorAndAutomaticProperties class
 │   ├── DefaultedConstructorArgument class
 │   ├── Base class
 │   ├── Derived class
 │   ├── DoNotOverridePrivates class
 │   ├── DoNotRecognizeAnyAsOptional class
 │   ├── DontComplainAboutVariadicAfterOptional class
 │   ├── DoubleTrouble class
 │   ├── ExportedBaseClass class
 │   ├── GiveMeStructs class
 │   ├── GreetingAugmenter class
 │   ├── Foo class
 │   ├── JSObjectLiteralForInterface class
 │   ├── JSObjectLiteralToNative class
 │   ├── JSObjectLiteralToNativeClass class
 │   ├── JavaReservedWords class
 │   ├── JsiiAgent class
 │   ├── Multiply class
 │   ├── Negate class
 │   ├── NodeStandardLibrary class
 │   ├── NullShouldBeTreatedAsUndefined class
 │   ├── NumberGenerator class
 │   ├── ObjectRefsInCollections class
 │   ├── OptionalConstructorArgument class
 │   ├── OverrideReturnsObject class
 │   ├── Polymorphism class
 │   ├── Power class
 │   ├── ReferenceEnumFromScopedPackage class
 │   ├── ReturnsPrivateImplementationOfInterface class
 │   ├── RuntimeTypeChecking class
 │   ├── Statics class
 │   ├── Sum class
 │   ├── SyncVirtualMethods class
 │   ├── Thrower class
 │   ├── UnaryOperation class
 │   ├── UseBundledDependency class
 │   ├── UseCalcBase class
 │   ├── UsesInterfaceWithProperties class
 │   ├── VariadicMethod class
 │   ├── VirtualMethodPlayground class
 │   ├── CompositeOperation class
 │   ├── CalculatorProps interface
 │   ├── DerivedStruct interface
 │   ├── IFriendlier interface
 │   ├── IFriendlyRandomGenerator interface
 │   ├── IInterfaceThatShouldNotBeADataType interface
 │   ├── IInterfaceWithMethods interface
 │   ├── IInterfaceWithOptionalMethodArguments interface
 │   ├── IPrivatelyImplemented interface
 │   ├── IRandomNumberGenerator interface
 │   ├── IReturnsNumber interface
 │   ├── ImplictBaseOfBase interface
 │   ├── IInterfaceImplementedByAbstractClass interface
 │   ├── Hello interface
 │   ├── Hello interface
 │   ├── InterfaceWithProperties interface
 │   ├── InterfaceWithPropertiesExtension interface
 │   ├── LoadBalancedFargateServiceProps interface
 │   ├── MutableObjectLiteral interface
 │   ├── NullShouldBeTreatedAsUndefinedData interface
 │   ├── UnionProperties interface
 │   ├── AllTypesEnum enum
 │   ├── StringEnum enum
 │   └── CompositionStringStyle enum
 ├─┬ @scope/jsii-calc-base
 │ └─┬ types
 │   ├── Base class
 │   └── BaseProps interface
 ├─┬ @scope/jsii-calc-base-of-base
 │ └─┬ types
 │   ├── Very class
 │   └── VeryBaseProps interface
 └─┬ @scope/jsii-calc-lib
   └─┬ types
     ├── Number class
     ├── Operation class
     ├── Value class
     ├── IDoublable interface
     ├── IFriendly interface
     ├── MyFirstStruct interface
     ├── StructWithOnlyOptionals interface
     └── EnumFromScopedModule enum

See jsii-tree --help for options.

License

Distributed under the Apache License, Version 2.0.

See LICENSE and NOTICE for more information.

Changelog

1.105.0 (2024-11-14)

Features

• pacmak: support jsii-rosetta 5.6 (#4698) (7464a59)

Bug Fixes

• rosetta: python identifiers mishandle identifier translations with capital letters (#4644) (e573aab)