@devscholar/node-ps1-dotnet-generator

TypeScript type definition generator for .NET assemblies, designed for use with @devscholar/node-ps1-dotnet.

Reflects on any .NET assembly and emits a .d.ts file so your editor provides IntelliSense and compile-time type checking when calling .NET APIs through the node-ps1-dotnet bridge.

Platform: Windows only (requires PowerShell 5.1 / .NET Framework 4.x, same as node-ps1-dotnet).

Installation

npm install --save-dev @devscholar/node-ps1-dotnet-generator

Or run without installing:

npx @devscholar/node-ps1-dotnet-generator -a System.Windows.Forms -t ./types/winforms.d.ts

CLI Usage

node-ps1-dotnet-generator -a <assembly> -t <output.d.ts> [options]

Required

| Flag | Alias | Description | |------|-------|-------------| | --assembly <name\|path> | -a | Assembly simple name (System.Windows.Forms) or path to a .dll / .exe | | --typedefs <path> | -t | Output .d.ts file path |

Options

| Flag | Alias | Description | |------|-------|-------------| | --reference <name\|path> | -r | Reference assembly needed to resolve types (repeatable) | | --module <esm\|commonjs> | -m | Also generate a JS module loader alongside the .d.ts | | --mode <mode> | | Type conversion mode: node-api-dotnet (default) or pythonnet | | --namespace <ns> | -n | Primary namespace for flat exports (auto-detected when omitted) | | --nowarn | | Suppress warnings about types that cannot be projected | | --help | -h | Show help |

Response files are supported: prefix a file path with @ and each non-empty, non-comment line is treated as an additional argument.

Examples

# System assembly by simple name
node-ps1-dotnet-generator -a System.Windows.Forms -t ./types/winforms.d.ts

# Local DLL with a reference assembly
node-ps1-dotnet-generator -a ./MyLib.dll -r System.Drawing -t ./types/mylib.d.ts

# pythonnet mode (List<T> → DotnetList<T>, Dictionary → DotnetMap)
node-ps1-dotnet-generator -a System.Windows.Forms -t ./types/winforms.d.ts --mode pythonnet

# Generate a JS module loader (ESM) alongside the .d.ts
node-ps1-dotnet-generator -a System.Windows.Forms -t ./types/winforms.d.ts --module esm

# Suppress cross-assembly warnings
node-ps1-dotnet-generator -a System.Windows.Forms -t ./types/winforms.d.ts --nowarn

# Response file (useful when the reference list is long)
node-ps1-dotnet-generator @args.txt

Using the Generated Types

Namespace proxy cast

The most common pattern — cast the dotnet(namespace) proxy to the generated module type:

import dotnet from '@devscholar/node-ps1-dotnet';
import type * as WinForms from './types/winforms';

dotnet.load('System.Windows.Forms');
const Forms = dotnet('System.Windows.Forms') as typeof WinForms;

const form = new Forms.Form();   // typed as Form
form.Text = 'Hello';             // ✓  string
form.Width = 400;                // ✓  number

const btn = new Forms.Button();
btn.Text = 'Click me';
btn.add_Click((_sender, _e) => {
    console.log('clicked');
});
form.Controls.Add(btn);
form.Show();

Module loader (with --module esm)

When --module esm is used, the generator also emits a .mjs file that loads the assembly and re-exports every type as a named export:

// types/winforms.mjs  (auto-generated)
import dotnet from '@devscholar/node-ps1-dotnet';
dotnet.load('System.Windows.Forms');
const _ns = dotnet('System.Windows.Forms');
export const Form   = _ns.Form;
export const Button = _ns.Button;
// ...

This lets you import types directly with full IntelliSense:

import { Form, Button } from './types/winforms.mjs';

const form = new Form();   // ✓ typed

Type Conversion Modes

The generator supports the same two modes as node-ps1-dotnet's typeConversionBehavior setting.

node-api-dotnet (default)

Matches node-api-dotnet's type conventions. Collections are projected as value copies.

| .NET type | TypeScript type | |-----------|----------------| | IList<T> / List<T> | T[] | | IDictionary<K,V> | Map<K, V> | | IEnumerable<T> | Iterable<T> & { map, filter, … } | | Task<T> | Promise<T> | | DateTime / DateTimeOffset | Date | | TimeSpan | number (ms) | | Guid | string | | Enum | number | | ref/out params | { result: T, paramName: ParamType } | | Stream subclass | NodeJS.Duplex |

pythonnet

Collections stay as live .NET references with a JS-friendly interface bolted on. Use this mode when dotnet.typeConversionBehavior = 'pythonnet' is set at runtime.

| .NET type | TypeScript type | |-----------|----------------| | IList<T> / List<T> | DotnetList<T> — both Add/Remove/Count and map/filter/length | | IDictionary<K,V> | DotnetMap<K,V> — both ContainsKey/Count and get/set/size |

DotnetList<T> and DotnetMap<K,V> helper interfaces are emitted at the top of the generated .d.ts.

Programmatic API

import { generate } from '@devscholar/node-ps1-dotnet-generator';
import * as fs from 'node:fs';

const { dts, js, warnings } = generate({
    assembly: 'System.Windows.Forms',
    // references: ['System.Drawing'],
    mode: 'node-api-dotnet',   // or 'pythonnet'
    module: 'esm',             // omit to skip JS loader
    nowarn: false,
});

fs.writeFileSync('./types/winforms.d.ts', dts);
if (js) fs.writeFileSync('./types/winforms.mjs', js);
for (const w of warnings) console.warn(w);

generate(options)

| Option | Type | Default | Description | |--------|------|---------|-------------| | assembly | string | (required) | Assembly name or .dll path | | references | string[] | [] | Reference assemblies | | mode | 'node-api-dotnet' \| 'pythonnet' | 'node-api-dotnet' | Type conversion mode | | module | 'esm' \| 'commonjs' | — | Generate JS loader | | primaryNamespace | string | auto-detected | Namespace for flat exports | | nowarn | boolean | false | Suppress warnings |

Returns { dts: string, js?: string, warnings: string[] }.

Lower-level exports — inspectAssembly, emitDts, emitModule — are also available for building custom tooling on top.

How It Works

1. The generator injects a C# helper class (AssemblyInspector) into the running PowerShell process using addType() from node-ps1-dotnet. This is a one-time cost.
2. A single IPC call to AssemblyInspector.Inspect(assemblyName) returns a complete JSON description of all public types in the target assembly — constructors, properties, methods, events, enums — via .NET reflection.
3. The mapper converts each .NET type string to the corresponding TypeScript type, respecting the selected conversion mode.
4. The emitter groups types by namespace and writes declare class / declare const enum / export type declarations, including extends clauses for inheritance, add_/remove_ pairs for events, and { result, out } return types for ref/out parameters.

Because all reflection happens in a single round-trip, generation is fast even for large assemblies like System.Windows.Forms (~900 exported types).

Limitations

• Windows only. The generator runs node-ps1-dotnet, which requires Windows and PowerShell 5.1.
• Declared-only members. Inherited members are not duplicated; they are expressed via extends. TypeScript resolves them transitively.
• Cross-assembly types (e.g. System.Drawing.Point referenced from System.Windows.Forms) appear as unqualified short names with a warning unless you pass --reference System.Drawing. The generated file will still parse and typecheck; those types just resolve to any.
• Pointer / unsafe types are skipped silently.

License

MIT