Dukat

Dukat is a converter that transforms TypeScript definition files (.d.ts) into Kotlin declarations.

Requirements:

• Runtime: JRE 1.6 or higher.
• Compatibility: Generates Kotlin files compatible with Kotlin 1.1+. The generated declarations are tested against the latest stable Kotlin compiler version.

You can install the latest stable version of Dukat globally using npm. If you require the latest development snapshot (the current state of the master branch), install the dukat@next version.

# Install stable version
npm install -g dukat

# Install snapshot/dev version
npm install -g dukat@next

To build the project from the cloned repository, use the Gradle wrapper.

Note for Windows users: Before cloning, ensure you set git config core.autocrlf true to handle line endings correctly.

1. Clone the repository.
2. Run the build command.
3. (Optional) Run unit tests.

# 1. Clone (Windows users: git config core.autocrlf true)
git clone <project-url>

# 2. Build
./gradlew build

# 3. Run tests (optional)
./gradlew test -Pdukat.test.failure.always

Dukat is a command-line tool used to convert TypeScript declarations (.d.ts, .d.mts), TypeScript sources (.ts), JavaScript declarations (.js), and Web IDL (.idl, .webidl) into Kotlin declarations.

Basic usage pattern:

dukat [<options>] <d.ts files>

Note: In a single execution, you must provide either only TypeScript declaration files or only IDL files. You cannot mix them in one pass.

dukat <options> <d.ts files>

The following options are available when running the dukat command:

Dukat requires a Java Runtime Environment (JRE) to function. If you encounter errors related to Java, check the following:

1. JAVA_HOME is invalid: If the JAVA_HOME environment variable is set, ensure it points to a valid Java installation directory. Dukat looks for the executable at $JAVA_HOME/bin/java.
2. java not found: If JAVA_HOME is not set, the java command must be available in your system's PATH.

Error Messages:

• ERROR: Your "JAVA_HOME" environment variable points to an invalid directory.
• ERROR: "java" is not callable from commandline and no "JAVA_HOME" environment variable is set.

Run the dukat command followed by the path to your .d.ts files. You can provide several options to control the output package name, module annotations, and destination directory.

dukat [<options>] <d.ts files>

The DescriptorContext class is used to manage the lifecycle and lookup of Kotlin declaration descriptors (classes, methods, properties, type aliases, etc.) during the Dukat process. It maintains a registry of descriptors and handles the resolution of names within a specific package context.

Key responsibilities include:

• Registering and resolving class descriptors, methods, and properties.
• Managing type aliases and type parameters.
• Handling standard library configuration via stdlibModule.
• Tracking delegated parents and type parameter constraints.

// Example of initializing a context with a specific stdlib path
val context = DescriptorContext("path/to/stdlib")

// Accessing the standard library module
val stdlib = context.stdlibModule

The JsStdlibConfigContext class is used to initialize a Kotlin compiler environment specifically configured to access the JavaScript standard library descriptors.

When using this class, you can access:

• environment: A KotlinCoreEnvironment configured for JS.
• stdlibModule: The ModuleDescriptor for the <kotlin> special module.
• generateJSConfig(): A method to retrieve a JsConfig object containing the project and configuration details.

Important: You must call destroy() when finished to release the underlying resources via the internal Disposer.

// Assuming stdLib is a path to the library
val context = JsStdlibConfigContext("path/to/stdlib")

try {
    val jsConfig = context.generateJSConfig()
    val stdlib = context.stdlibModule
    // Use the descriptors...
} finally {
    context.destroy()
}

You can register type aliases using registerTypeAlias and retrieve them via getTypeAlias (by name) or getTypeAliasDescriptorByConstructor (by the underlying TypeConstructor).

// Register a type alias
context.registerTypeAlias(aliasName, typeAliasDescriptor)

// Retrieve by name
val alias = context.getTypeAlias(aliasName)

// Retrieve by constructor
val aliasByConstructor = context.getTypeAliasDescriptorByConstructor(typeConstructor)

When initializing DescriptorContext(stdLib), the stdlibModule property lazily creates a JsStdlibConfigContext using the provided stdLib path. To clean up resources, call destroyConfigContext().

val context = DescriptorContext("path/to/js/stdlib")
// stdlibModule triggers the creation of JsStdlibConfigContext
val module = context.stdlibModule

// Clean up
context.destroyConfigContext()

Use registerDescriptor to add a ClassDescriptor to the current package context. You can then retrieve it using getDescriptor by providing its fully qualified name (NameEntity).

// Registering a class descriptor
context.registerDescriptor(classNameEntity, classDescriptor)

// Retrieving a class descriptor
val descriptor = context.getDescriptor(classNameEntity)