[API Proposal]: Generate d.ts file from JSExport attributes

[yamachu]

Background and motivation

JSExport Attribute can make .NET static methods accessible to JavaScript side.

However, access to such methods requires the correct namespace, class name, and method name, and may result in access to invalid objects.

By outputting d.ts when generating JavaScript Interop source, it is possible to type exported objects, which will improve the development experience.

API Proposal

dotnet.d.ts

declare type APIType = {
    runMain: (mainAssemblyName: string, args: string[]) => Promise<number>;
    runMainAndExit: (mainAssemblyName: string, args: string[]) => Promise<number>;
    setEnvironmentVariable: (name: string, value: string) => void;
-   getAssemblyExports(assemblyName: string): Promise<any>;
+   getAssemblyExports<T = any>(assemblyName: string): Promise<T>;

dotnet.g.d.ts

import "@microsoft/dotnet-runtime";

declare module "@microsoft/dotnet-runtime" {
    interface AssemblyExports {
        MyClass: {
            Greeting: () => void;
        }
    }
}

API Usage

main.mts

import { dotnet, AssemblyExports } from "@microsoft/dotnet-runtime";

const { getAssemblyExports } = await dotnet
    .withDiagnosticTracing(false)
    .create();

const config = getConfig();
const exports = await getAssemblyExports<AssemblyExports>(config.mainAssemblyName);
const text = exports.MyClass.Greeting();
console.log(text);

wasmconsole.csproj

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net7.0</TargetFramework>
    <RuntimeIdentifier>browser-wasm</RuntimeIdentifier>
    <WasmMainJSPath>main.mjs</WasmMainJSPath>
    <OutputType>Exe</OutputType>
    <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
    <JSInteropTypeDefinitionOutputDir>./types</JSInteropTypeDefinitionOutputDir>
  </PropertyGroup>

  <ItemGroup>
    <CompilerVisibleProperty Include="JSInteropTypeDefinitionOutputDir" />
  </ItemGroup>
</Project>

Alternative Designs

PoC: https://github.com/yamachu/NetWebAssemblyTSTypeGenerator

Risks

• It may not work well in JSDoc
• It will not work if the package.json does not contain a runtime dependency

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

Tagging subscribers to 'arch-wasm': @lewing
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

JSExport Attribute can make .NET static methods accessible to JavaScript side.

However, access to such methods requires the correct namespace, class name, and method name, and may result in access to invalid objects.

By outputting d.ts when generating JavaScript Interop source, it is possible to type exported objects, which will improve the development experience.

API Proposal

dotnet.d.ts

declare type APIType = {
    runMain: (mainAssemblyName: string, args: string[]) => Promise<number>;
    runMainAndExit: (mainAssemblyName: string, args: string[]) => Promise<number>;
    setEnvironmentVariable: (name: string, value: string) => void;
-   getAssemblyExports(assemblyName: string): Promise<any>;
+   getAssemblyExports<T = any>(assemblyName: string): Promise<T>;

dotnet.g.d.ts

import "@microsoft/dotnet-runtime";

declare module "@microsoft/dotnet-runtime" {
    interface AssemblyExports {
        MyClass: {
            Greeting: () => void;
        }
    }
}

API Usage

main.mts

import { dotnet, AssemblyExports } from "@microsoft/dotnet-runtime";

const { getAssemblyExports } = await dotnet
    .withDiagnosticTracing(false)
    .create();

const config = getConfig();
const exports = await getAssemblyExports<AssemblyExports>(config.mainAssemblyName);
const text = exports.MyClass.Greeting();
console.log(text);

wasmconsole.csproj

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net7.0</TargetFramework>
    <RuntimeIdentifier>browser-wasm</RuntimeIdentifier>
    <WasmMainJSPath>main.mjs</WasmMainJSPath>
    <OutputType>Exe</OutputType>
    <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
    <JSInteropTypeDefinitionOutputDir>./types</JSInteropTypeDefinitionOutputDir>
  </PropertyGroup>

  <ItemGroup>
    <CompilerVisibleProperty Include="JSInteropTypeDefinitionOutputDir" />
  </ItemGroup>
</Project>

Alternative Designs

PoC: https://github.com/yamachu/NetWebAssemblyTSTypeGenerator

Risks

• It may not work well in JSDoc
• It will not work if the package.json does not contain a runtime dependency

Author:	yamachu
Assignees:	-
Labels:	api-suggestion, arch-wasm, area-System.Runtime.InteropServices.JavaScript
Milestone:	-

[jkoritzinsky]

I/O in a generator is unsupported, so this needs to wait for dotnet/roslyn#57608 to be doable in a supported fashion.

[pavelsavara]

Does this usage work as is ?

const exports:AssemblyExports = await getAssemblyExports(config.mainAssemblyName);

I'm not sure that the TypeScript definitions generator need to be part of the runtime.
I think that 3rd party generator is a good choice.

[Thaina]

On the flipside. Are there any way or plan to generate C# wrapper over javascript package from its d.ts ?

So we could write C# wasm with any existing npm package that provide d.ts

[pavelsavara]

The JS interop only supports static functions and limited set of marshaled argument types.
It would not be able to automatically wrap any sufficiently complex .d.ts

[Thaina]

@pavelsavara Isn't all the type of js can be reference in C# as JSObject ?

And then we make a class as a wrapper of JSObject and make a property for each of field they have. Given that we also able to convert Promise to Task I don't see anything we cannot convert

Could you please give me an example of what impossible to generate right now?

[pavelsavara]

Yes, you can generate wrapper class around the JSObject. Let's say you want to have WebSocket instance and you would generate C# class for it. Which part of the interop pipeline would create the instance of WebSocket C# proxy ?

Now let's say that we have TypeScript definition of WebSocket.send(). You can see that there are multiple types of the data parameter. This is not easy to do in strongly typed language. It's doable when there is somebody who would make design decisions about the type mapping. But I believe it's not practical to do it in automated generator. Especially when there are more than one dynamically typed parameter, it leads to exponential number of strongly typed method signatures.

Even if somebody would really want to try to do it, I still think that it's not something we need to do in the runtime repo.
It could be 3rd party generator, nuget. Ideally FOSS.

[Thaina]

@pavelsavara I kind of thinking that this feature should be native to wasm and/or blazor build system. And it was not ideal that we could not decouple wasm and blazor from runtime repo

It would be very convenient for dotnet wasm compiler to able to import existing package in npm into C# so we could utilize every critical 3rd party package in the web world that will only written as npm package