@phreshos/client 0.1.15 → 0.1.17

package/README.md

@@ -141,13 +141,23 @@ identity is removed by the server host before the message reaches the desktop.
 The same rule applies to Client-visible traffic destinations.
 
 Client-visible Program handles can operate only within their own Program.
-They deliberately omit `install()` and `fork()`, and their storage areas never
+They deliberately omit `install()` and `fork()`, and their `Storage` values never
 expose host filesystem paths. Every Client-side Window handle exposes the same
 authoritative, subscribable Window capability and its `window.local` physical
 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/main.d.ts

@@ -5,4 +5,4 @@ export { current, type Current, type CurrentServer } from "./current.js";
 export { type Channel, type ChannelCapture, type ChannelEvents, type ChannelMessage } from "./channel.js";
 export { ClientServiceHandler, ServerServiceHandler, ServiceHandler, type ClientServiceChannel, type ServerServiceChannel, type ServiceChannel, type ServiceKey, type ServiceLifecycleEvents } from "@phreshos/core";
 export { Client, Endpoint, Process, Program, Server, type Window, type ProgramProcess, type AnswerCapture, type AnswerMessage, type AnswerObserver, type AskCapture, type AskMessage, type AskObserver, type ClientTraffic, type EndpointTraffic, type ServerTraffic, type TrafficCapture, type TrafficEvents, type TrafficMessage } from "./domain.js";
-export type { Askable, Capture, Captures, ClientDeclaration, Cleanup, DirectoryStat, EndpointDeclaration, EntryStat, EventMessage, EventName, EventObserver, EventOptions, EventSubscriber, Exit, FileStat, Launch, LaunchClient, Layer, LogKind, LogRecord, LogSource, Message, OtherStat, Outcome, PermissionDecision, Permission, Position, ProgramArea, ProgramEvents, ProgramProcessEvents, ProgramProcessExit, ProgramSql, ProgramStore, ProcessEvents, Publishable, ServedFile, Size, Subscribable, SubscribableEvents, SubscribableFallback, TimedAskable, TimedPermission, Timeoutable, Theme, ThemeEvents, ThemeProperties, Value, WritableTheme, WindowEvents, WindowGeometry, WindowLayer, WindowState, Easing, LocalWindow, LocalWindowSurface, SurfaceSettings, Transaction } from "@phreshos/core";
+export type { Askable, Capture, Captures, ClientDeclaration, Cleanup, DirectoryStat, EndpointDeclaration, EntryStat, EventMessage, EventName, EventObserver, EventOptions, EventSubscriber, Exit, FileStat, Launch, LaunchClient, Layer, LogKind, LogRecord, LogSource, Message, OtherStat, Outcome, PermissionDecision, Permission, Position, Storage, ProgramEvents, ProgramProcessEvents, ProgramProcessExit, ProgramSql, ProgramStore, ProcessEvents, Publishable, ServedFile, Size, Subscribable, SubscribableEvents, SubscribableFallback, TimedAskable, TimedPermission, Timeoutable, Theme, ThemeEvents, ThemeProperties, Value, WritableTheme, WindowEvents, WindowGeometry, WindowLayer, WindowState, Easing, LocalWindow, LocalWindowSurface, SurfaceSettings, Transaction } from "@phreshos/core";

package/dist/storage.d.ts

@@ -1,5 +1,5 @@
-import type { ProgramArea, ProgramSql, ProgramStore } from "@phreshos/core";
+import type { ProgramSql, ProgramStore, Storage } from "@phreshos/core";
 /** Client-side Program storage, structurally scoped by the iframe boundary. */
-export declare function area(which: "data" | "cache"): ProgramArea;
+export declare function area(which: "data" | "cache"): Storage;
 export declare function store(): ProgramStore;
 export declare function sql(kind: "database" | "logs"): ProgramSql;

package/dist/storage.js

@@ -38,14 +38,12 @@ export function area(which) {
         async text(...path) { return new Response(await stream(...path)).text(); },
         async json(...path) { return JSON.parse(await new Response(await stream(...path)).text()); },
         async write(...args) {
-            if (args.length < 2)
-                throw new Error("Writing takes a file name and what to write");
             await transfer("write", args.slice(0, -1), content(args.at(-1)).body);
         },
         stat: (...path) => ask("stat", ...path),
         list: (...path) => ask("list", ...path),
         delete: (...path) => ask("delete", ...path),
-        clear: () => ask("clear")
+        clear: (...path) => ask("clear", ...path)
     };
 }
 export function store() {

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.17",
   "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.14",
     "typescript": "^6.0.3"
   }
 }