@microsoft/dynwinrt-codegen 0.1.0-preview.1 → 0.1.0-preview.2

package/README.md

@@ -0,0 +1,87 @@
+# @microsoft/dynwinrt-codegen
+
+**Generate typed JavaScript + TypeScript bindings for any Windows Runtime (WinRT) API from `.winmd` metadata.**
+
+Pair this with the [`@microsoft/dynwinrt`](https://www.npmjs.com/package/@microsoft/dynwinrt) runtime to call modern Windows APIs (WinAppSDK, Windows AI, notifications, storage, networking, …) **directly from JavaScript / TypeScript** — full IntelliSense, no native build step, no C# projection, no per-Windows-version recompile.
+
+## Why use this?
+
+Until now, the choices for calling a Windows API from Node.js or Electron were:
+
+- **Write a C++ `node-addon-api` addon** — needs `node-gyp`, MSVC, Python, the right Windows SDK, and a CI matrix per Electron version.
+- **Write a C# addon via `node-api-dotnet`** — needs the .NET SDK, a `csproj` build step, and a hand-maintained C# wrapper for every API surface.
+- **Wait for an official projection** — Windows ships `.winmd` metadata months before a JavaScript-friendly projection appears.
+
+`dynwinrt-codegen` reads the same `.winmd` metadata the Windows SDK already ships and emits **typed JavaScript + `.d.ts` wrappers** that call WinRT through [`@microsoft/dynwinrt`](https://www.npmjs.com/package/@microsoft/dynwinrt) at runtime. There is no native build in your Electron / Node project. You generate the bindings once, commit them (or regenerate on demand), and import them like any other module:
+
+```ts
+import { LanguageModel, LanguageModelOptions } from './bindings/winrt';
+const model = await LanguageModel.createAsync();
+```
+
+You get IntelliSense in your IDE, type errors at `tsc` time, and the underlying COM call dispatched dynamically at runtime — no MSBuild involved.
+
+The trade-off: `dynwinrt-codegen` is designed for **data-style WinRT APIs** (AI, storage, notifications, networking, globalization, …) and skips XAML / WinUI namespaces, which need composable-class aggregation patterns the codegen doesn't implement. For everything else, this is the easiest path from JavaScript to native Windows.
+
+## CLI usage
+
+```bash
+npm install -D @microsoft/dynwinrt-codegen @microsoft/dynwinrt
+
+# A single class (auto-detects the Windows SDK winmd)
+npx dynwinrt-codegen generate \
+  --namespace Windows.Foundation \
+  --class-name Uri \
+  --output ./generated
+
+# An entire namespace
+npx dynwinrt-codegen generate \
+  --namespace Windows.Web.Http \
+  --output ./generated
+
+# A custom .winmd (e.g., a WinAppSDK NuGet package or your own SDK)
+npx dynwinrt-codegen generate \
+  --winmd "C:\path\to\Microsoft.WindowsAppSDK.AI.winmd" \
+  --output ./generated
+```
+
+### Flags
+
+| Flag | Description |
+|---|---|
+| `--winmd PATH[;PATH...]` | Path to `.winmd` file(s) (auto-detects Windows SDK if omitted) |
+| `--folder PATH` | Directory containing `.winmd` files |
+| `--namespace NAMESPACE` | WinRT namespace to generate (omit for all non-`Windows.*` namespaces) |
+| `--class-name CLASS` | Specific class (transitively pulls in dependencies) |
+| `--ref PATH` | Additional `.winmd` files for type resolution only (no code emitted) |
+| `--lang js` | Target language (currently `js` only) |
+| `--output DIR` | Output directory (default `./generated`) |
+| `--dry-run` | Validate input, don't write files |
+
+## What gets generated
+
+For each WinRT class, the codegen emits:
+
+- **A typed wrapper class** with properties and methods using camelCase JS conventions
+- **A factory** (`.create(...)`, `.createInstance(...)`) for activation
+- **An interface registration** (`DynWinRtType.registerInterface()`) wired to the COM vtable
+- **`IAsyncOperation<T>` awaitables** with `.progress(cb)` for streaming results
+- **Generic collections** (`IVector<T>`, `IMap<K,V>`, `IIterable<T>`)
+- **Structs** with `pack`/`unpack` helpers
+- **Enums** (`Object.freeze`'d in JS, `enum` in `.d.ts`)
+- **Delegate types** (IID + parameter signatures) for event handlers
+- **An `index.js` + `index.d.ts`** re-exporting every emitted symbol from one place
+
+## Platform
+
+- **Windows only** (x64 / arm64) — the binary is built per architecture and selected automatically by the npm install
+- The generated bindings depend on [`@microsoft/dynwinrt`](https://www.npmjs.com/package/@microsoft/dynwinrt) at runtime
+
+## Links
+
+- 📦 [`@microsoft/dynwinrt`](https://www.npmjs.com/package/@microsoft/dynwinrt) — the runtime the generated code targets
+- 🐛 [Source on GitHub](https://github.com/microsoft/dynwinrt) — issues, contributions, internal design docs
+
+## License
+
+[MIT](https://github.com/microsoft/dynwinrt/blob/main/LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":  "@microsoft/dynwinrt-codegen",
-    "version":  "0.1.0-preview.1",
+    "version":  "0.1.0-preview.2",
     "description":  "Generate typed bindings from WinRT metadata (.winmd) files for use with @microsoft/dynwinrt",
     "license":  "MIT",
     "repository":  {
@@ -24,7 +24,8 @@
     "files":  [
                   "bin/",
                   "cli.js",
-                  "LICENSE"
+                  "LICENSE",
+                  "README.md"
               ],
     "dependencies":  {