janela 0.5.0 → 0.6.0

package/runtime/types.ts

@@ -73,64 +73,6 @@ export interface WindowConfig {
   height: number;
 }
 
-export interface JanelaApp {
-  handle: number;
-  names: string[];
-  handlers: CommandHandler[];
-  /** Register a named command, callable from the page as janela.invoke(name, args). */
-  command: (name: string, h: CommandHandler) => void;
-  /** Register a command that answers later; see AsyncCommandHandler. */
-  commandAsync: (name: string, h: AsyncCommandHandler) => void;
-  /** Run fn on the next turn of the host loop — the way to slice long work. */
-  defer: (fn: () => void) => void;
-  /** Run fn after at least ms. The host loop's timer; scriptc's setTimeout
-   *  cannot fire while the window is open (its loop is parked inside run()). */
-  sleep: (ms: number, fn: () => void) => void;
-  /**
-   * Read a file without blocking the window. The syscall runs on a shim
-   * worker thread; the callback lands on the UI thread on a later turn.
-   * Prefer this over node:fs readFileSync inside a command — that one blocks
-   * the loop, and with it the whole window.
-   */
-  readFileAsync: (path: string, cb: FsCallback) => void;
-  /** Write a file without blocking the window; cb(null) on success. */
-  writeFileAsync: (
-    path: string,
-    data: string,
-    cb: (err: string | null) => void,
-  ) => void;
-  /**
-   * Show the native "open" dialog. `cb` gets the chosen paths, or null if the
-   * user cancelled. The modal runs on a later turn of the UI thread, so
-   * calling this from inside a command does not block that command's reply —
-   * pair it with commandAsync when the page is waiting for the result.
-   */
-  openFileDialog: (
-    options: OpenDialogOptions,
-    cb: (paths: string[] | null, err?: string) => void,
-  ) => void;
-  /** Show the native "save" dialog; cb gets the path, or null on cancel. */
-  saveFileDialog: (
-    options: SaveDialogOptions,
-    cb: (path: string | null, err?: string) => void,
-  ) => void;
-  /** Change the window title at any time, not just at startup. */
-  setTitle: (title: string) => void;
-  /**
-   * Resize the window. `hint` is webview's sizing hint: 0 none, 1 minimum,
-   * 2 maximum, 3 fixed.
-   */
-  setSize: (width: number, height: number, hint?: number) => void;
-  /** Enter or leave fullscreen. */
-  setFullscreen: (on: boolean) => void;
-  /** Fire an event into the page; the payload is delivered as a value. */
-  emit: (event: string, payload: unknown) => void;
-  /** Close the window and make run() return. */
-  quit: () => void;
-  /** Show the page and block until the window closes. Returns the run status. */
-  run: (html: string) => number;
-}
-
 // ---------------------------------------------------------------------------
 // Typed IPC contract
 // ---------------------------------------------------------------------------
@@ -188,64 +130,3 @@ export function defineCommands<M extends CommandShapes>(): Commands<M> {
 export function defineEvents<E>(): Events<E> {
   return {};
 }
-
-/**
- * Register a command against the contract. `args` is inferred from the
- * contract, and the return type is checked against it, so the handler is
- * written once with no casts.
- *
- * ```ts
- * on(app, commands, "add", (args) => args.a + args.b);
- * ```
- */
-export function on<M extends CommandShapes, K extends keyof M & string>(
-  app: JanelaApp,
-  _commands: Commands<M>,
-  name: K,
-  handler: (args: M[K]["args"]) => M[K]["result"],
-): void {
-  app.command(name, (args: unknown) => handler(args as M[K]["args"]));
-}
-
-/**
- * Register a command that answers on a later turn. `resolve` takes the
- * contract's result type; see AsyncCommandHandler for the timing rules.
- */
-export function onAsync<M extends CommandShapes, K extends keyof M & string>(
-  app: JanelaApp,
-  _commands: Commands<M>,
-  name: K,
-  handler: (
-    args: M[K]["args"],
-    resolve: (value: M[K]["result"]) => void,
-    reject: (reason: unknown) => void,
-  ) => void,
-): void {
-  app.commandAsync(
-    name,
-    (args: unknown, resolve: (value: unknown) => void, reject: (reason: unknown) => void) => {
-      handler(
-        args as M[K]["args"],
-        (value: M[K]["result"]) => resolve(value),
-        reject,
-      );
-    },
-  );
-}
-
-/**
- * Emit a declared event. The name must exist in the contract and the payload
- * must match its type.
- *
- * ```ts
- * emit(app, events, "added", 42);
- * ```
- */
-export function emit<E, K extends keyof E & string>(
-  app: JanelaApp,
-  _events: Events<E>,
-  name: K,
-  payload: E[K],
-): void {
-  app.emit(name, payload);
-}

package/templates/react/files/src-host/main.ts

@@ -12,56 +12,55 @@
 //     an `undefined` argument lowers to a zero-parameter function and fails
 //     to compile.
 
-import {
-  defineCommands,
-  defineEvents,
-  emit,
-  on,
-  onAsync,
-  type JanelaApp,
-} from "janela/host";
+import { defineCommands, defineEvents, type JanelaApp } from "janela/host";
 
-export const commands = defineCommands<{
+/** Every command this app answers. Declared once; the page checks against it. */
+export type AppCommands = {
   add: { args: { a: number; b: number }; result: number };
   greet: { args: { name: string }; result: string };
   log: { args: string; result: null };
   wait: { args: { ms: number }; result: string };
   quit: { args: null; result: null };
-}>();
+};
 
-export const events = defineEvents<{
+/** Every event this app emits, and what each one carries. */
+export type AppEvents = {
   added: number;
-}>();
+};
+
+export const commands = defineCommands<AppCommands>();
+export const events = defineEvents<AppEvents>();
 
 /** The contract the page imports with `import type { App } from "../src-host/main"`. */
 export type App = { commands: typeof commands; events: typeof events };
 
-export function setup(app: JanelaApp): void {
-  // `args` is inferred from the contract, and the return type is checked
-  // against it — no casts, and no way to drift from what the page expects.
-  on(app, commands, "add", (args) => {
+// Typing the app with the contract is what makes `app.command` checked: the
+// name must be one of the declared ones, `args` is inferred from it, and the
+// return value has to match. Same for `app.emit`.
+export function setup(app: JanelaApp<AppCommands, AppEvents>): void {
+  app.command("add", (args) => {
     const sum = args.a + args.b;
-    emit(app, events, "added", sum);
+    app.emit("added", sum);
     return sum;
   });
 
-  on(app, commands, "greet", (args) => {
+  app.command("greet", (args) => {
     return "Hello, " + args.name + " — from the native TS binary";
   });
 
-  on(app, commands, "log", (args) => {
+  app.command("log", (args) => {
     console.log("[host] page says:", args);
     return null;
   });
 
   // An async command: answers later, without freezing the window.
-  onAsync(app, commands, "wait", (args, resolve) => {
+  app.commandAsync("wait", (args, resolve) => {
     app.sleep(args.ms, () => {
       resolve("waited " + args.ms + "ms without blocking the UI");
     });
   });
 
-  on(app, commands, "quit", (_args) => {
+  app.command("quit", (_args) => {
     app.quit();
     return null;
   });

package/templates/solid/files/src-host/main.ts

@@ -12,56 +12,55 @@
 //     an `undefined` argument lowers to a zero-parameter function and fails
 //     to compile.
 
-import {
-  defineCommands,
-  defineEvents,
-  emit,
-  on,
-  onAsync,
-  type JanelaApp,
-} from "janela/host";
+import { defineCommands, defineEvents, type JanelaApp } from "janela/host";
 
-export const commands = defineCommands<{
+/** Every command this app answers. Declared once; the page checks against it. */
+export type AppCommands = {
   add: { args: { a: number; b: number }; result: number };
   greet: { args: { name: string }; result: string };
   log: { args: string; result: null };
   wait: { args: { ms: number }; result: string };
   quit: { args: null; result: null };
-}>();
+};
 
-export const events = defineEvents<{
+/** Every event this app emits, and what each one carries. */
+export type AppEvents = {
   added: number;
-}>();
+};
+
+export const commands = defineCommands<AppCommands>();
+export const events = defineEvents<AppEvents>();
 
 /** The contract the page imports with `import type { App } from "../src-host/main"`. */
 export type App = { commands: typeof commands; events: typeof events };
 
-export function setup(app: JanelaApp): void {
-  // `args` is inferred from the contract, and the return type is checked
-  // against it — no casts, and no way to drift from what the page expects.
-  on(app, commands, "add", (args) => {
+// Typing the app with the contract is what makes `app.command` checked: the
+// name must be one of the declared ones, `args` is inferred from it, and the
+// return value has to match. Same for `app.emit`.
+export function setup(app: JanelaApp<AppCommands, AppEvents>): void {
+  app.command("add", (args) => {
     const sum = args.a + args.b;
-    emit(app, events, "added", sum);
+    app.emit("added", sum);
     return sum;
   });
 
-  on(app, commands, "greet", (args) => {
+  app.command("greet", (args) => {
     return "Hello, " + args.name + " — from the native TS binary";
   });
 
-  on(app, commands, "log", (args) => {
+  app.command("log", (args) => {
     console.log("[host] page says:", args);
     return null;
   });
 
   // An async command: answers later, without freezing the window.
-  onAsync(app, commands, "wait", (args, resolve) => {
+  app.commandAsync("wait", (args, resolve) => {
     app.sleep(args.ms, () => {
       resolve("waited " + args.ms + "ms without blocking the UI");
     });
   });
 
-  on(app, commands, "quit", (_args) => {
+  app.command("quit", (_args) => {
     app.quit();
     return null;
   });

package/templates/svelte/files/src-host/main.ts

@@ -12,56 +12,55 @@
 //     an `undefined` argument lowers to a zero-parameter function and fails
 //     to compile.
 
-import {
-  defineCommands,
-  defineEvents,
-  emit,
-  on,
-  onAsync,
-  type JanelaApp,
-} from "janela/host";
+import { defineCommands, defineEvents, type JanelaApp } from "janela/host";
 
-export const commands = defineCommands<{
+/** Every command this app answers. Declared once; the page checks against it. */
+export type AppCommands = {
   add: { args: { a: number; b: number }; result: number };
   greet: { args: { name: string }; result: string };
   log: { args: string; result: null };
   wait: { args: { ms: number }; result: string };
   quit: { args: null; result: null };
-}>();
+};
 
-export const events = defineEvents<{
+/** Every event this app emits, and what each one carries. */
+export type AppEvents = {
   added: number;
-}>();
+};
+
+export const commands = defineCommands<AppCommands>();
+export const events = defineEvents<AppEvents>();
 
 /** The contract the page imports with `import type { App } from "../src-host/main"`. */
 export type App = { commands: typeof commands; events: typeof events };
 
-export function setup(app: JanelaApp): void {
-  // `args` is inferred from the contract, and the return type is checked
-  // against it — no casts, and no way to drift from what the page expects.
-  on(app, commands, "add", (args) => {
+// Typing the app with the contract is what makes `app.command` checked: the
+// name must be one of the declared ones, `args` is inferred from it, and the
+// return value has to match. Same for `app.emit`.
+export function setup(app: JanelaApp<AppCommands, AppEvents>): void {
+  app.command("add", (args) => {
     const sum = args.a + args.b;
-    emit(app, events, "added", sum);
+    app.emit("added", sum);
     return sum;
   });
 
-  on(app, commands, "greet", (args) => {
+  app.command("greet", (args) => {
     return "Hello, " + args.name + " — from the native TS binary";
   });
 
-  on(app, commands, "log", (args) => {
+  app.command("log", (args) => {
     console.log("[host] page says:", args);
     return null;
   });
 
   // An async command: answers later, without freezing the window.
-  onAsync(app, commands, "wait", (args, resolve) => {
+  app.commandAsync("wait", (args, resolve) => {
     app.sleep(args.ms, () => {
       resolve("waited " + args.ms + "ms without blocking the UI");
     });
   });
 
-  on(app, commands, "quit", (_args) => {
+  app.command("quit", (_args) => {
     app.quit();
     return null;
   });

package/templates/vue/files/src-host/main.ts

@@ -12,56 +12,55 @@
 //     an `undefined` argument lowers to a zero-parameter function and fails
 //     to compile.
 
-import {
-  defineCommands,
-  defineEvents,
-  emit,
-  on,
-  onAsync,
-  type JanelaApp,
-} from "janela/host";
+import { defineCommands, defineEvents, type JanelaApp } from "janela/host";
 
-export const commands = defineCommands<{
+/** Every command this app answers. Declared once; the page checks against it. */
+export type AppCommands = {
   add: { args: { a: number; b: number }; result: number };
   greet: { args: { name: string }; result: string };
   log: { args: string; result: null };
   wait: { args: { ms: number }; result: string };
   quit: { args: null; result: null };
-}>();
+};
 
-export const events = defineEvents<{
+/** Every event this app emits, and what each one carries. */
+export type AppEvents = {
   added: number;
-}>();
+};
+
+export const commands = defineCommands<AppCommands>();
+export const events = defineEvents<AppEvents>();
 
 /** The contract the page imports with `import type { App } from "../src-host/main"`. */
 export type App = { commands: typeof commands; events: typeof events };
 
-export function setup(app: JanelaApp): void {
-  // `args` is inferred from the contract, and the return type is checked
-  // against it — no casts, and no way to drift from what the page expects.
-  on(app, commands, "add", (args) => {
+// Typing the app with the contract is what makes `app.command` checked: the
+// name must be one of the declared ones, `args` is inferred from it, and the
+// return value has to match. Same for `app.emit`.
+export function setup(app: JanelaApp<AppCommands, AppEvents>): void {
+  app.command("add", (args) => {
     const sum = args.a + args.b;
-    emit(app, events, "added", sum);
+    app.emit("added", sum);
     return sum;
   });
 
-  on(app, commands, "greet", (args) => {
+  app.command("greet", (args) => {
     return "Hello, " + args.name + " — from the native TS binary";
   });
 
-  on(app, commands, "log", (args) => {
+  app.command("log", (args) => {
     console.log("[host] page says:", args);
     return null;
   });
 
   // An async command: answers later, without freezing the window.
-  onAsync(app, commands, "wait", (args, resolve) => {
+  app.commandAsync("wait", (args, resolve) => {
     app.sleep(args.ms, () => {
       resolve("waited " + args.ms + "ms without blocking the UI");
     });
   });
 
-  on(app, commands, "quit", (_args) => {
+  app.command("quit", (_args) => {
     app.quit();
     return null;
   });