@phreshos/client 0.1.15 → 0.1.16

package/README.md

@@ -148,6 +148,16 @@ representation on this desktop. Local reads and updates have no events and do
 not change Server state. `current.window` is only convenient access to the
 executing Client's canonical Window; it has no additional authority.
 
+A Client may uninstall only its own Program. The operation is an async
+generator so a declared Server cleanup command remains observable without a
+fixed answer timeout:
+
+```ts
+for await (const chunk of program.uninstall()) {
+  console.log(chunk.stream, chunk.text)
+}
+```
+
 A Program may converge its Clients on one named Process without a manual
 `find()`/`create()` race:
 

package/dist/domain.js

@@ -59,9 +59,20 @@ class ProgramHandle extends ProgramBase {
         const answer = await wire.request(["installed"]);
         return answer[0];
     }
-    async uninstall(everything = false) { await wire.request(["uninstall", undefined, everything]); }
+    async *uninstall(everything = false) {
+        for await (const value of wire.stream(["uninstall", undefined, everything])) {
+            yield programCommandChunk(value);
+        }
+    }
     async forget() { await wire.request(["forget"]); }
 }
+function programCommandChunk(value) {
+    const chunk = value;
+    if (!chunk || (chunk.stream !== "stdout" && chunk.stream !== "stderr") || typeof chunk.text !== "string") {
+        throw new Error("The desktop returned an invalid Program command chunk");
+    }
+    return Object.freeze({ stream: chunk.stream, text: chunk.text });
+}
 function declaration(record) {
     return Object.freeze({
         start: record.start

package/dist/wire.d.ts

@@ -8,6 +8,7 @@ type TrafficKind = "publish" | "ask" | "answer";
 declare class Wire {
     private readonly parent;
     private readonly pending;
+    private readonly streams;
     private readonly subscribers;
     private readonly every;
     private readonly impossible;
@@ -15,6 +16,8 @@ declare class Wire {
     constructor();
     send(route: string, ...values: unknown[]): void;
     request(values: unknown[], timeout?: number, transfer?: Transferable[]): Promise<unknown>;
+    /** Opens one long-running desktop operation and yields its ordered values. */
+    stream(values: unknown[], timeout?: number): AsyncIterableIterator<unknown>;
     /** Requests a value while treating the caller's deadline as an absent answer. */
     requestOrNull(values: unknown[], timeout: number): Promise<unknown | null>;
     requestWithin(values: unknown[], deadline: Deadline, transfer?: Transferable[]): Promise<unknown>;
@@ -40,6 +43,7 @@ declare class Wire {
     private unregister;
     private deliver;
     private settle;
+    private receiveStream;
 }
 declare const wire: Wire;
 export default wire;

package/dist/wire.js

@@ -6,6 +6,7 @@ import { deserialize, serialize } from "./messagepack.js";
 class Wire {
     parent = window.parent === window ? null : window.parent;
     pending = new Map();
+    streams = new Map();
     subscribers = new Map();
     every = new Map();
     impossible = new Map();
@@ -40,6 +41,10 @@ class Wire {
                 this.settle(values[1], values.at(-1));
                 return;
             }
+            if (values[0] === "stream" && typeof values[1] === "string" && typeof values[2] === "string") {
+                this.receiveStream(values[1], values[2], values[3]);
+                return;
+            }
             this.deliver(route, values);
         });
     }
@@ -49,6 +54,46 @@ class Wire {
     request(values, timeout = defaultTimeout, transfer = []) {
         return this.question("end-host", values, timeout, transfer);
     }
+    /** Opens one long-running desktop operation and yields its ordered values. */
+    stream(values, timeout = defaultTimeout) {
+        const wire = this;
+        return (async function* () {
+            const question = `client:${crypto.randomUUID()}:${crypto.randomUUID()}`;
+            const state = {
+                queue: [],
+                opened: false,
+                ended: false,
+                failure: null,
+                wake: null,
+                timer: setTimeout(() => {
+                    state.failure = new Error(`Answer timeout ${timeout}ms`);
+                    state.wake?.();
+                    state.wake = null;
+                }, timeout)
+            };
+            wire.send("boundary", "expect", question);
+            wire.streams.set(question, state);
+            wire.send("end-host", "stream", question, ...values);
+            try {
+                while (true) {
+                    if (state.queue.length) {
+                        yield state.queue.shift();
+                        continue;
+                    }
+                    if (state.failure)
+                        throw state.failure;
+                    if (state.ended)
+                        return;
+                    await new Promise(resolve => { state.wake = resolve; });
+                }
+            }
+            finally {
+                clearTimeout(state.timer);
+                wire.streams.delete(question);
+                wire.send("boundary", "forget", question);
+            }
+        })();
+    }
     /** Requests a value while treating the caller's deadline as an absent answer. */
     requestOrNull(values, timeout) {
         return this.question("end-host", values, timeout, [], timeout, true);
@@ -261,6 +306,38 @@ class Wire {
         else
             pending.reject(new Error("The boundary returned an invalid outcome"));
     }
+    receiveStream(question, operation, value) {
+        const stream = this.streams.get(question);
+        if (!stream || stream.ended || stream.failure)
+            return;
+        if (operation === "open") {
+            if (stream.opened)
+                return;
+            stream.opened = true;
+            clearTimeout(stream.timer);
+        }
+        else if (!stream.opened)
+            stream.failure = new Error("The boundary produced a stream value before opening the stream");
+        else if (operation === "data") {
+            if (stream.queue.length >= maximumStreamQueue)
+                stream.failure = new Error(`Host stream queue exceeded its capacity of ${maximumStreamQueue}`);
+            else
+                stream.queue.push(value);
+        }
+        else if (operation === "answer") {
+            const outcome = value;
+            if (outcome?.success === true)
+                stream.ended = true;
+            else if (outcome?.success === false && typeof outcome.error === "string")
+                stream.failure = new Error(outcome.error);
+            else
+                stream.failure = new Error("The boundary returned an invalid stream outcome");
+        }
+        else
+            stream.failure = new Error(`The boundary returned an invalid stream operation "${operation}"`);
+        stream.wake?.();
+        stream.wake = null;
+    }
 }
 function invoke(handler, values) {
     Promise.resolve().then(() => handler(...values)).catch(error => queueMicrotask(() => { throw error; }));
@@ -305,6 +382,7 @@ function nativeAttachments(value, transfer) {
     visit(value);
     return attachments;
 }
+const maximumStreamQueue = 256;
 const wire = new Wire();
 captureClientOutput(wire);
 export default wire;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/client",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "The SDK used by a Program's client endpoint.",
   "type": "module",
   "main": "dist/main.js",
@@ -53,7 +53,7 @@
     "@msgpack/msgpack": "^3.1.3"
   },
   "devDependencies": {
-    "@phreshos/core": "^0.1.12",
+    "@phreshos/core": "^0.1.13",
     "typescript": "^6.0.3"
   }
 }