mygo-runtime 0.1.2 → 0.1.3

package/README.md

@@ -25,6 +25,18 @@ if (isMyGo() && runtime().platform === "darwin") {
 await currentWindow.toggleMaximize();
 ```
 
+A Go method that streams values through a `*mygo.Channel[T]` parameter takes
+a `Channel` in its place:
+
+```ts
+import { Channel } from "mygo-runtime";
+
+const lines = new Channel<string>();
+const done = Shell.tail("ls -R", lines);
+for await (const line of lines) console.log(line);
+await done;
+```
+
 A Go method returning an error rejects with a `CallError` (see
 `isCallError`). Outside a MyGo window, e.g. when the dev server is opened in a
 browser, calls reject and `isMyGo()` is false.

package/dist/index.d.ts

@@ -13,7 +13,7 @@
  *
  * @module
  */
-import type { Runtime, WindowControls } from "./types";
+import type { Channel as ChannelType, Runtime, WindowControls } from "./types";
 export type { Platform, Runtime, WindowControls } from "./types";
 declare global {
     interface Window {
@@ -34,6 +34,24 @@ export declare function runtime(): Runtime;
  * with a {@link CallError}.
  */
 export declare function call<T = unknown>(method: string, ...args: unknown[]): Promise<T>;
+/**
+ * A stream of values from a Go method that takes a `*mygo.Channel[T]`.
+ * Create one, pass it to the call in place of that parameter, and iterate
+ * it or handle its values with `onmessage`:
+ *
+ * ```ts
+ * const lines = new Channel<string>();
+ * const done = Shell.tail("ping -c 3 example.com", lines);
+ * for await (const line of lines) output.append(line + "\n");
+ * await done;
+ * ```
+ *
+ * It closes when the method returns; `close()`, or breaking out of the
+ * loop, stops the method. A channel serves one call.
+ */
+export type Channel<T = unknown> = ChannelType<T>;
+/** Creates a {@link Channel}, optionally with its `onmessage` handler. */
+export declare const Channel: new <T = unknown>(onmessage?: (value: T) => void) => Channel<T>;
 /** Subscribes to a Go event by name. Returns a function that unsubscribes. */
 export declare function on<T = unknown>(name: string, listener: (payload: T) => void): () => void;
 /** Like {@link on}, but unsubscribes after the first event. */

package/dist/index.js

@@ -15,6 +15,9 @@ function call(method, ...args) {
     return Promise.reject(err);
   }
 }
+var Channel = function(onmessage) {
+  return runtime().channel(onmessage);
+};
 function on(name, listener) {
   return runtime().on(name, listener);
 }
@@ -45,6 +48,7 @@ var currentWindow = {
   setTitle: async (title) => runtime().window.setTitle(title)
 };
 export {
+  Channel,
   call,
   currentWindow,
   event,

package/dist/types.d.ts

@@ -11,10 +11,36 @@ export interface WindowControls {
     close(): Promise<void>;
     setTitle(title: string): Promise<void>;
 }
+/**
+ * A stream of values from a Go method that takes a `*mygo.Channel[T]`,
+ * passed to the call in its place. Iterate it, or handle the values with
+ * `onmessage`: values that arrive before either wait for it. The channel
+ * closes when the method returns, or calls `Close`, once its values are
+ * taken; `close()` stops the method.
+ */
+export interface Channel<T = unknown> extends AsyncIterable<T> {
+    /** Called with each value, instead of iterating. */
+    onmessage: ((value: T) => void) | null;
+    /** Called when the channel closes. */
+    onclose: (() => void) | null;
+    /** Whether the channel is closed. */
+    readonly closed: boolean;
+    /**
+     * Closes the channel, dropping values not taken yet: the Go method's
+     * `Send` fails and its context is canceled. Breaking out of a
+     * `for await` loop over the channel closes it too.
+     */
+    close(): void;
+}
 /** The runtime MyGo injects into every page as `window.mygo`. */
 export interface Runtime {
     /** Calls a bound Go method, e.g. `call("Greeter.Greet", "Ada")`. */
     call<T = unknown>(method: string, ...args: unknown[]): Promise<T>;
+    /**
+     * Creates a channel to pass to a call of a Go method that streams values
+     * through a `*mygo.Channel[T]` parameter. A channel serves one call.
+     */
+    channel<T = unknown>(onmessage?: (value: T) => void): Channel<T>;
     /** Subscribes to a Go event. Returns a function that unsubscribes. */
     on<T = unknown>(event: string, listener: (payload: T) => void): () => void;
     /** Like `on`, but unsubscribes after the first event. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mygo-runtime",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Typed access to the MyGo runtime in the pages of MyGo desktop apps",
   "keywords": [
     "mygo",