janela 0.5.0 → 0.7.0

package/README.md

@@ -138,24 +138,25 @@ framework templates' default.
 
 ```ts
 // src-host/main.ts
-import { defineCommands, defineEvents, emit, on, onAsync, type JanelaApp } from "janela/host";
+import type { JanelaApp } from "janela/host";
 
-export const commands = defineCommands<{
+export type AppCommands = {
   add:   { args: { a: number; b: number }; result: number };
   greet: { args: { name: string };         result: string };
   wait:  { args: { ms: number };           result: string };
-}>();
-
-export const events = defineEvents<{ added: number }>();
+};
+export type AppEvents = { added: number };
 
-export type App = { commands: typeof commands; events: typeof events };
+/** The app, carrying its contract. This is what the page imports. */
+export type App = JanelaApp<AppCommands, AppEvents>;
 
-export function setup(app: JanelaApp): void {
-  on(app, commands, "add", (args) => {      // args inferred: { a: number; b: number }
-    emit(app, events, "added", args.a + args.b);
+// Typing the app with the contract is what makes the methods below checked.
+export function setup(app: App): void {
+  app.command("add", (args) => {            // args inferred: { a: number; b: number }
+    app.emit("added", args.a + args.b);     // event name and payload checked
     return args.a + args.b;                 // return type checked against the contract
   });
-  onAsync(app, commands, "wait", (args, resolve) => {
+  app.commandAsync("wait", (args, resolve) => {
     app.sleep(args.ms, () => resolve("waited " + args.ms + "ms"));
   });
 }
@@ -309,6 +310,73 @@ nested modal loop would otherwise re-enter the host loop underneath a live TS
 frame; [docs/native-shell.md](../../docs/native-shell.md) has the details, the
 per-platform table, and the Windows GUI-subsystem note.
 
+## Migrating from 0.6.x
+
+The contract lives entirely in the types now, so the runtime tokens are gone.
+Name the app instead of wrapping its two tables:
+
+```ts
+// before (0.6.x)
+import { defineCommands, defineEvents, type JanelaApp } from "janela/host";
+
+export const commands = defineCommands<AppCommands>();
+export const events = defineEvents<AppEvents>();
+export type App = { commands: typeof commands; events: typeof events };
+
+export function setup(app: JanelaApp<AppCommands, AppEvents>): void { … }
+
+// after (0.7.x)
+import type { JanelaApp } from "janela/host";
+
+export type App = JanelaApp<AppCommands, AppEvents>;
+
+export function setup(app: App): void { … }
+```
+
+`AppCommands` and `AppEvents` are unchanged, and so is every page: the
+frontend still writes `createClient<App>()` and `client.invoke(...)`, because
+`createClient` reads the contract off either shape.
+
+`defineCommands` and `defineEvents` still exist and still work — they are
+`@deprecated` no-ops that only ever carried types — so a 0.6.x project keeps
+compiling and running untouched.
+
+## Migrating from 0.5.x
+
+The contract now rides on the app itself, so the standalone registrars are no
+longer needed. Type the app with your contract and call its methods:
+
+```ts
+// before (0.5.x)
+export function setup(app: JanelaApp): void {
+  on(app, commands, "add", (args) => args.a + args.b);
+  onAsync(app, commands, "wait", (args, resolve) => { … });
+  emit(app, events, "added", 42);
+}
+
+// after (0.6.x)
+export function setup(app: JanelaApp<AppCommands, AppEvents>): void {
+  app.command("add", (args) => args.a + args.b);
+  app.commandAsync("wait", (args, resolve) => { … });
+  app.emit("added", 42);
+}
+```
+
+Declare each contract as a named type and hand both to the app (0.7.x drops
+the `defineCommands` / `defineEvents` tokens entirely — see above):
+
+```ts
+export type AppCommands = { add: { args: { a: number; b: number }; result: number } };
+export type AppEvents = { added: number };
+export type App = JanelaApp<AppCommands, AppEvents>;
+```
+
+`on`, `onAsync` and `emit` still work — they are `@deprecated` one-line
+wrappers now — so 0.5.x code keeps compiling. The page side is unchanged:
+`createClient<App>()` and `client.invoke(...)` are exactly as before. An app
+with no contract needs no change at all: `setup(app: JanelaApp)` still gets an
+untyped `app.command(name, handler)`.
+
 ## Migrating from 0.4.x
 
 Nothing breaks: `app.command`, `app.emit`, and the untyped `invoke` / `listen`
@@ -318,9 +386,11 @@ Two things are new:
 
 - `listen()` (and the injected `janela.listen`) now **return a disposer**.
   Previously they returned nothing, so existing code is unaffected.
-- The **typed contract** — `defineCommands` / `defineEvents` on the host,
+- The **typed contract** — a contract-typed app on the host,
   `createClient<App>()` on the page. The framework templates now scaffold with
-  it. See [The typed contract](#the-typed-contract).
+  it. See [The typed contract](#the-typed-contract). (0.4.x shipped this with
+  `defineCommands` / `defineEvents` tokens; 0.7.x replaced them with the `App`
+  type alias below, and the tokens are deprecated but still work.)
 
 To adopt it in an existing app, declare what the host already exposes and swap
 the registrations:
@@ -333,12 +403,13 @@ app.command("add", (args) => {
 });
 
 // after
-export const commands = defineCommands<{
+export type AppCommands = {
   add: { args: { a: number; b: number }; result: number };
-}>();
-export type App = { commands: typeof commands; events: typeof events };
+};
+export type AppEvents = { added: number };
+export type App = JanelaApp<AppCommands, AppEvents>;
 
-on(app, commands, "add", (args) => args.a + args.b);   // args inferred, no cast
+app.command("add", (args) => args.a + args.b);   // args inferred, no cast
 ```
 
 then on the page, replace `invoke<number>("add", …)` with

package/api/index.d.ts

@@ -6,6 +6,7 @@
  * parse.
  */
 
+import type { JanelaApp } from "../runtime/janela";
 import type { CommandShapes, Commands, Events } from "../runtime/types";
 
 /** Removes a subscription created by `listen` / `client.on`. */
@@ -50,17 +51,36 @@ export declare function listen<T = unknown>(
 // Typed contract
 // ---------------------------------------------------------------------------
 
-/** Anything shaped like a host contract module's exported `App` type. */
+/**
+ * Anything shaped like a host contract module's exported `App` type.
+ *
+ * @deprecated The `{ commands, events }` wrapper of 0.5.x/0.6.x. Export
+ * `type App = JanelaApp<AppCommands, AppEvents>` instead.
+ */
 export interface Contract {
   commands: Commands<CommandShapes>;
   events: Events<unknown>;
 }
 
-/** The command table declared by a contract. */
-export type CommandsOf<A> = A extends { commands: Commands<infer M> } ? M : never;
+/**
+ * The command table declared by a contract.
+ *
+ * Reads the contract off a `JanelaApp<C, E>` — what a host's `App` type is
+ * from 0.7.0 — and falls back to the 0.5.x/0.6.x `{ commands, events }`
+ * wrapper, so a project written against either shape keeps checking.
+ */
+export type CommandsOf<A> = A extends JanelaApp<infer M, infer _E>
+  ? M
+  : A extends { commands: Commands<infer M> }
+    ? M
+    : never;
 
-/** The event table declared by a contract. */
-export type EventsOf<A> = A extends { events: Events<infer E> } ? E : never;
+/** The event table declared by a contract; see CommandsOf for the two shapes. */
+export type EventsOf<A> = A extends JanelaApp<infer _M, infer E>
+  ? E
+  : A extends { events: Events<infer E> }
+    ? E
+    : never;
 
 /**
  * A client bound to a host contract: command names, argument shapes, result
@@ -89,7 +109,7 @@ export interface JanelaClient<A> {
  * Build a client checked against a host's contract.
  *
  * ```ts
- * import type { App } from "../src-host/main";
+ * import type { App } from "../src-host/main";   // App = JanelaApp<Cmds, Evts>
  * const client = createClient<App>();
  * const sum = await client.invoke("add", { a: 2, b: 40 });   // number
  * const off = client.on("added", (v) => console.log(v));      // v: number

package/bin/janela.mjs

@@ -516,10 +516,18 @@ function build(root, { devUrl = null, gui = true } = {}) {
     join(buildDir, "entry.ts"),
     `// Generated by janela — do not edit.\n` +
       `import { createApp } from "./janela";\n` +
+      `import type { CommandShapes, JanelaApp } from "./janela";\n` +
       `import { WINDOW } from "./config";\n` +
       `import { INDEX_HTML } from "./frontend";\n` +
       `import { setup } from "./main";\n\n` +
-      `const app = createApp(WINDOW);\n` +
+      `// The app's type parameters are read back off setup()'s own signature,\n` +
+      `// so a contract-typed setup(app: JanelaApp<App>) and a plain\n` +
+      `// setup(app: JanelaApp) each get an app instantiated to match. scriptc\n` +
+      `// monomorphises generic classes, so the right instantiation must be\n` +
+      `// CONSTRUCTED here - no cast can bridge JanelaApp<A> and JanelaApp<B>.\n` +
+      `type CmdsOf<F> = F extends (app: JanelaApp<infer C, infer _E>) => void ? C : CommandShapes;\n` +
+      `type EvtsOf<F> = F extends (app: JanelaApp<infer _C, infer E>) => void ? E : Record<string, unknown>;\n\n` +
+      `const app = createApp<CmdsOf<typeof setup>, EvtsOf<typeof setup>>(WINDOW);\n` +
       `setup(app);\n` +
       `const rc = app.run(INDEX_HTML) + 0;\n` +
       `console.log("[janela] run returned", rc);\n`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "janela",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Desktop apps in pure TypeScript, compiled to native. No Rust, no Node, no Electron.",
   "type": "module",
   "bin": {
@@ -13,7 +13,7 @@
       "default": "./api/index.js"
     },
     "./host": {
-      "types": "./runtime/types.ts"
+      "types": "./runtime/janela.ts"
     },
     "./global": {
       "types": "./api/global.d.ts"