@phreshos/client 0.1.25 → 0.1.27

package/README.md

@@ -80,7 +80,10 @@ const service = system.service({
 })
 
 await service.waitReady()
-if (await service.enabled()) await service.channel.ask("value")
+if (await service.enabled()) await service.ask("value")
+
+service.subscribe("changed", message => console.log(message))
+service.lifecycle.subscribe("disable", () => console.log("unavailable"))
 ```
 
 A Client may traverse `Process.parent()` through any number of ancestors in
@@ -98,8 +101,8 @@ into the endpoint. Identity, Theme, Process, Window, readiness, lifecycle, and
 application values enter only in response to an explicit request or a live
 registration made by Program code.
 
-`Context` combines navigation into the executing Client's Process with its
-Channel. The paired Server is explicitly named as
+`Context` combines communication with navigation into the executing Client's
+Process. The paired Server is explicitly named as
 `context.server`; its publishing, asking, existence, readiness, start, and stop
 operations never masquerade as properties of `context`. `context.stop()` stops
 the executing Client, while complete Process exit remains available only
@@ -131,11 +134,12 @@ them. These are the same domain classes used by the Server SDK, so
 `ClientTraffic`, is a type-only capability owned by Client and has no
 independent `instanceof` identity.
 
-The executing Client's Channel is composed directly into `context`. Its
+The executing Client's communication belongs directly to `context`. Its
 subscription tools receive events addressed to this Client, while `publish()`
-emits outward from this Client without choosing a destination. Existence,
-readiness, and lifecycle operations belong to `context.server`,
-`context.stop()`, or an explicit Endpoint handle.
+emits outward from this Client without choosing a destination. Existence and
+readiness belong to `context.server`; the current Client stops through
+`context.stop()`, and explicit Endpoint handles expose their own
+`endpoint.lifecycle` subscriptions.
 
 An Endpoint handle is also a selective source: `endpoint.subscribe()` follows
 destinationless events emitted by that Endpoint. Its `traffic` property remains

package/dist/context.d.ts

@@ -1,9 +1,15 @@
-import { type Channel } from "./channel.js";
-import { Client, Server, type Process, type Program, type Window } from "./domain.js";
+import type { Context as CoreContext, ContextCapture as CoreContextCapture, ContextEvents as CoreContextEvents, ContextMessage as CoreContextMessage } from "@phreshos/core";
+import { Client, Server, type Endpoint, type Process, type Program, type Window } from "./domain.js";
 /** The executing Process's canonical Server handle. */
 export type ContextServer<Events extends object = {}> = Server<Events>;
-/** Client runtime context: its inbound Channel, owner hierarchy, and paired Server. */
-export interface Context<Events extends object = {}> extends Channel<Events>, Pick<Client, "service"> {
+/** One value addressed to the current Client, with a client-visible sender. */
+export type ContextMessage<Payload = unknown> = CoreContextMessage<Payload, Endpoint | null>;
+/** Applies the client-visible sender envelope to known Context events. */
+export type ContextEvents<Events extends object> = CoreContextEvents<Events, Endpoint | null>;
+/** Every event observable through the current Client Context. */
+export type ContextCapture<Events extends object = {}> = CoreContextCapture<Events, Endpoint | null>;
+/** Client runtime context: inbound communication, owner hierarchy, and paired Server. */
+export interface Context<Events extends object = {}> extends CoreContext<Events, Endpoint | null>, Pick<Client, "service"> {
     /** The same Server handle exposed by the executing Process. */
     readonly server: ContextServer;
     /** Presentation capability of the executing Client. */

package/dist/context.js

@@ -1,14 +1,15 @@
-import { channel } from "./channel.js";
 import Deadline from "./deadline.js";
-import { Client, Server, ServerTrafficHandle, TrafficHandle, bindEvents, endpointEvents, process, program, window as windowHandle } from "./domain.js";
+import { Client, Server, ServerTrafficHandle, TrafficHandle, bindEvents, endpointLifecycle, endpointEvents, process, program, visibleEndpoint, window as windowHandle } from "./domain.js";
+import Events from "./events.js";
 import wire from "./wire.js";
-import { endpointService } from "./service.js";
+import { disableCurrentService, enableCurrentService, endpointService } from "./service.js";
 import { currentProgramPermission } from "./permissions.js";
 const ServerBase = Server;
 const ClientBase = Client;
 class ContextServerHandle extends ServerBase {
     owner;
     traffic = new ServerTrafficHandle(null, "server");
+    lifecycle = endpointLifecycle(currentAddress, "server");
     constructor(owner) {
         super();
         this.owner = owner;
@@ -57,10 +58,8 @@ contextServer = new ContextServerHandle(owner);
 class ContextClientHandle extends ClientBase {
     owner;
     traffic = new TrafficHandle(null, "client");
-    window = windowHandle(async () => {
-        const identity = await wire.identity();
-        return { identity: identity.process, reference: identity.reference };
-    });
+    lifecycle = endpointLifecycle(currentAddress, "client");
+    window = windowHandle(currentAddress);
     constructor(owner) {
         super();
         this.owner = owner;
@@ -81,12 +80,15 @@ class ContextClientHandle extends ClientBase {
     service() { return endpointService(null, "client"); }
 }
 contextClient = new ContextClientHandle(owner);
-class ClientContext {
+class ClientContext extends Events {
     server = contextServer;
     window = contextClient.window;
     permission = currentProgramPermission;
     constructor() {
-        bindChannel(this, channel);
+        super((event, listener, impossible) => wire.on("end-end", event, value => listener(contextMessage(value)), null, impossible), (listener, impossible) => wire.onAll("end-end", (event, value) => {
+            if (typeof event === "string")
+                listener(event, contextMessage(value));
+        }, null, impossible));
     }
     process() { return owner(); }
     async parent() {
@@ -103,17 +105,17 @@ class ClientContext {
     }
     async stop() { await wire.request(["stop-current"]); }
     service() { return endpointService(null, "client"); }
+    publish(event, payload = undefined) { wire.send("end-host", "emit", event, payload); }
+    async enableService(name) { await enableCurrentService(name); }
+    async disableService() { await disableCurrentService(); }
 }
-function bindChannel(target, source) {
-    Object.assign(target, {
-        publish: source.publish.bind(source),
-        subscribe: source.subscribe.bind(source),
-        waitFor: source.waitFor.bind(source),
-        events: source.events.bind(source),
-        observe: source.observe.bind(source),
-        enableService: source.enableService.bind(source),
-        disableService: source.disableService.bind(source)
-    });
+async function currentAddress() {
+    const identity = await wire.identity();
+    return { identity: identity.process, reference: identity.reference };
+}
+function contextMessage(value) {
+    const raw = value;
+    return { from: visibleEndpoint(raw.from), payload: raw.payload };
 }
 /** Inbound events, owner hierarchy, and paired Server for this Client runtime. */
 export const context = new ClientContext();

package/dist/domain.d.ts

@@ -1,4 +1,4 @@
-import { Client as CoreClient, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer, type AnswerCapture as CoreAnswerCapture, type AnswerMessage as CoreAnswerMessage, type AnswerObserver as CoreAnswerObserver, type AskCapture as CoreAskCapture, type AskMessage as CoreAskMessage, type AskObserver as CoreAskObserver, type Cleanup, type ClientTraffic as CoreClientTraffic, type ClientDeclaration, type EndpointTraffic as CoreEndpointTraffic, type Exit, type Launch, type LocalWindow, type Permission, type Position, type ProgramProcess as CoreProgramProcess, type ServerTraffic as CoreServerTraffic, type Size, type TrafficMessage as CoreTrafficMessage, type TrafficCapture as CoreTrafficCapture, type TrafficEvents as CoreTrafficEvents, type Window as CoreWindow, type WindowState } from "@phreshos/core";
+import { Client as CoreClient, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer, type AnswerCapture as CoreAnswerCapture, type AnswerMessage as CoreAnswerMessage, type AnswerSubscriber as CoreAnswerSubscriber, type AskCapture as CoreAskCapture, type AskMessage as CoreAskMessage, type AskSubscriber as CoreAskSubscriber, type Cleanup, type ClientTraffic as CoreClientTraffic, type ClientDeclaration, type EndpointTraffic as CoreEndpointTraffic, type Exit, type EventOptions, type Launch, type LocalWindow, type Outcome, type Permission, type Position, type ProgramProcess as CoreProgramProcess, type ServerTraffic as CoreServerTraffic, type Size, type TrafficMessage as CoreTrafficMessage, type TrafficCapture as CoreTrafficCapture, type TrafficEvents as CoreTrafficEvents, type Window as CoreWindow, type WindowState } from "@phreshos/core";
 import Events from "./events.js";
 export interface HandleAddress {
     identity: string;
@@ -41,7 +41,7 @@ export interface EndpointReference {
 }
 export type WindowRecord = WindowState;
 /** Program handle visible inside a structurally isolated Client. */
-export type Program<Events extends object = {}> = Omit<CoreProgram<Events>, "process"> & {
+export type Program = Omit<CoreProgram, "process"> & {
     /** Effective permission decisions owned by this Program. */
     readonly permission: Permission;
     /** Operations and lifecycle observation for this Program's Processes. */
@@ -65,7 +65,7 @@ export type ProgramProcess = Omit<CoreProgramProcess, "list" | "first" | "last"
     }>): Promise<Process>;
 };
 /** Process handle visible inside a structurally isolated Client. */
-export type Process<Events extends object = {}> = Omit<CoreProcess<Events>, "server" | "client" | "program" | "parent"> & {
+export type Process = Omit<CoreProcess, "server" | "client" | "program" | "parent"> & {
     /** Permanent handle to this Process's Server. */
     readonly server: Server;
     /** Permanent handle to this Process's Client. */
@@ -86,13 +86,13 @@ export type AskMessage<Payload = unknown> = CoreAskMessage<Payload, Server | nul
 /** One question observable in client-visible Endpoint traffic. */
 export type AskCapture<Payload = unknown> = CoreAskCapture<Payload, Server | null>;
 /** Callback that observes questions sent by a client-visible Endpoint. */
-export type AskObserver<Payload = unknown> = CoreAskObserver<Payload, Server | null>;
+export type AskSubscriber<Payload = unknown> = CoreAskSubscriber<Payload, Server | null>;
 /** Answer with an Endpoint destination hidden when it crosses the Client boundary. */
 export type AnswerMessage<Result = unknown> = CoreAnswerMessage<Result, Endpoint | null>;
 /** One answer observable in client-visible Server traffic. */
 export type AnswerCapture<Result = unknown> = CoreAnswerCapture<Result, Endpoint | null>;
 /** Callback that observes answers sent by a client-visible Server. */
-export type AnswerObserver<Result = unknown> = CoreAnswerObserver<Result, Endpoint | null>;
+export type AnswerSubscriber<Result = unknown> = CoreAnswerSubscriber<Result, Endpoint | null>;
 /** Directed communication originating from one client-visible Endpoint. */
 export type EndpointTraffic<Events extends object = {}> = CoreEndpointTraffic<Events, Endpoint | null, Server | null>;
 /** Directed communication originating from one client-visible Server. */
@@ -131,15 +131,35 @@ export declare class TrafficHandle extends Events {
     protected readonly target: HandleAddress | null;
     protected readonly kind: "server" | "client";
     constructor(target: HandleAddress | null, kind: "server" | "client");
-    observeAsks(observer: (capture: AskCapture) => unknown): Cleanup;
+    subscribeAsks(subscriber: (capture: AskCapture) => unknown): Cleanup;
+    asks(options?: EventOptions): AsyncIterableIterator<Readonly<{
+        event: string;
+        questionId: string;
+        message: Readonly<{
+            to: Server<{}> | null;
+            payload: unknown;
+        }>;
+    }>>;
+    private followAsks;
 }
 export declare class ServerTrafficHandle extends TrafficHandle {
-    observeAnswers(observer: (capture: AnswerCapture) => unknown): Cleanup;
+    subscribeAnswers(subscriber: (capture: AnswerCapture) => unknown): Cleanup;
+    answers(options?: EventOptions): AsyncIterableIterator<Readonly<{
+        event: string;
+        questionId: string;
+        message: Readonly<{
+            to: Endpoint<{}> | null;
+            outcome: Outcome<unknown>;
+        }>;
+    }>>;
+    private followAnswers;
 }
 type WindowTarget = () => Promise<HandleAddress>;
 export declare function scoped(route: string, subject: string | null, convert: (event: string, values: unknown[]) => unknown): Events;
 /** Destinationless events originating from one Endpoint handle. */
 export declare function endpointEvents(target: HandleAddress | null, half: "server" | "client"): Events;
+/** Start and stop transitions belonging directly to one permanent Endpoint. */
+export declare function endpointLifecycle(target: WindowTarget, half: "server" | "client"): Events;
 export declare function exit(code: unknown, signal: unknown): Exit;
 export declare function trafficMessage(value: unknown): TrafficMessage;
 export declare function bindEvents(target: object, events: Events): void;

package/dist/domain.js

@@ -1,5 +1,5 @@
 import { Client as CoreClient, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer } from "@phreshos/core";
-import Events from "./events.js";
+import Events, { stream } from "./events.js";
 import Deadline from "./deadline.js";
 import HandleRegistry from "./handle-registry.js";
 import { area, sql, store } from "./storage.js";
@@ -165,38 +165,52 @@ export class TrafficHandle extends Events {
     target;
     kind;
     constructor(target, kind) {
-        super((event, listener, impossible) => wire.observe(target, kind, "publish", event, value => listener(trafficMessage(value)), impossible), observer => wire.observe(target, kind, "publish", null, (event, value) => {
+        super((event, listener, impossible) => wire.observe(target, kind, "publish", event, value => listener(trafficMessage(value)), impossible), (listener, impossible) => wire.observe(target, kind, "publish", null, (event, value) => {
             if (typeof event === "string")
-                observer(event, trafficMessage(value));
-        }));
+                listener(event, trafficMessage(value));
+        }, impossible));
         this.target = target;
         this.kind = kind;
     }
-    observeAsks(observer) {
+    subscribeAsks(subscriber) {
+        return this.followAsks(subscriber);
+    }
+    asks(options) {
+        return stream((subscriber, impossible) => this.followAsks(subscriber, impossible), options);
+    }
+    followAsks(subscriber, impossible) {
         return wire.observe(this.target, this.kind, "ask", null, (event, questionId, value) => {
             if (typeof event !== "string" || typeof questionId !== "string")
                 return;
-            observer({ event, questionId, message: trafficMessage(value) });
-        });
+            subscriber({ event, questionId, message: trafficMessage(value) });
+        }, impossible);
     }
 }
 export class ServerTrafficHandle extends TrafficHandle {
-    observeAnswers(observer) {
+    subscribeAnswers(subscriber) {
+        return this.followAnswers(subscriber);
+    }
+    answers(options) {
+        return stream((subscriber, impossible) => this.followAnswers(subscriber, impossible), options);
+    }
+    followAnswers(subscriber, impossible) {
         return wire.observe(this.target, "server", "answer", null, (event, questionId, value) => {
             if (typeof event !== "string" || typeof questionId !== "string")
                 return;
             const raw = value;
-            observer({ event, questionId, message: { to: visibleEndpoint(raw.to), outcome: raw.outcome } });
-        });
+            subscriber({ event, questionId, message: { to: visibleEndpoint(raw.to), outcome: raw.outcome } });
+        }, impossible);
     }
 }
 class ServerHandle extends ServerBase {
     owner;
     traffic;
+    lifecycle;
     constructor(owner) {
         super();
         this.owner = owner;
         this.traffic = new ServerTrafficHandle(owner.address, "server");
+        this.lifecycle = endpointLifecycle(() => Promise.resolve(owner.address), "server");
         bindEvents(this, endpointEvents(owner.address, "server"));
     }
     async process() { return this.owner; }
@@ -234,11 +248,13 @@ class ServerHandle extends ServerBase {
 class ClientHandle extends ClientBase {
     owner;
     traffic;
+    lifecycle;
     window;
     constructor(owner) {
         super();
         this.owner = owner;
         this.traffic = new TrafficHandle(owner.address, "client");
+        this.lifecycle = endpointLifecycle(() => Promise.resolve(owner.address), "client");
         this.window = window(async () => owner.address);
         bindEvents(this, endpointEvents(owner.address, "client"));
     }
@@ -328,13 +344,13 @@ function deferredScoped(route, target, convert) {
                     listener(convert(event, message));
             }, subject, impossible), impossible);
         },
-        observer => deferred(target, subject => wire.onAll(route, (event, ...values) => {
+        (listener, impossible) => deferred(target, subject => wire.onAll(route, (event, ...values) => {
             if (typeof event !== "string" || !windowEvent(event))
                 return;
             const message = unscoped(subject, values);
             if (message)
-                observer(event, convert(event, message));
-        }, subject))
+                listener(event, convert(event, message));
+        }, subject, impossible), impossible)
     ];
 }
 function windowEvent(event) {
@@ -363,20 +379,41 @@ export function scoped(route, subject, convert) {
         const message = unscoped(subject, values);
         if (message)
             listener(convert(event, message));
-    }, subject, impossible), observer => wire.onAll(route, (event, ...values) => {
+    }, subject, impossible), (listener, impossible) => wire.onAll(route, (event, ...values) => {
         if (typeof event !== "string")
             return;
         const message = unscoped(subject, values);
         if (message)
-            observer(event, convert(event, message));
-    }, subject));
+            listener(event, convert(event, message));
+    }, subject, impossible));
 }
 /** Destinationless events originating from one Endpoint handle. */
 export function endpointEvents(target, half) {
-    return new Events((event, listener, impossible) => wire.follow(target, half, event, listener, impossible), observer => wire.follow(target, half, null, (event, payload) => {
+    return new Events((event, listener, impossible) => wire.follow(target, half, event, listener, impossible), (listener, impossible) => wire.follow(target, half, null, (event, payload) => {
         if (typeof event === "string")
-            observer(event, payload);
-    }));
+            listener(event, payload);
+    }, impossible));
+}
+/** Start and stop transitions belonging directly to one permanent Endpoint. */
+export function endpointLifecycle(target, half) {
+    return new Events((event, listener, impossible) => deferred(target, subject => wire.on("process-host", endpointLifecycleEvent(event), (...values) => {
+        const message = unscoped(subject, values);
+        if (message?.[1] === half)
+            listener(undefined);
+    }, subject, impossible), impossible), (listener, impossible) => deferred(target, subject => wire.onAll("process-host", (event, ...values) => {
+        if (event !== "endpointStart" && event !== "endpointStop")
+            return;
+        const message = unscoped(subject, values);
+        if (message?.[1] === half)
+            listener(event === "endpointStart" ? "start" : "stop", undefined);
+    }, subject, impossible), impossible));
+}
+function endpointLifecycleEvent(event) {
+    if (event === "start")
+        return "endpointStart";
+    if (event === "stop")
+        return "endpointStop";
+    return event;
 }
 function unscoped(subject, values) {
     if (subject === null)
@@ -384,8 +421,6 @@ function unscoped(subject, values) {
     return values[0] === subject ? values.slice(1) : null;
 }
 function programProcessEvent(event, values) {
-    if (event === "endpointStart" || event === "endpointStop")
-        return lifecycleEndpoint(values[0], values[1]);
     if (event === "create")
         return process(values[0]);
     if (event === "exit")
@@ -394,24 +429,14 @@ function programProcessEvent(event, values) {
 }
 function programEvent(event, values) {
     if (event === "uninstall")
-        return { everythingRemoved: values[0] === true };
+        return values[0] === true;
     return undefined;
 }
 function processEvent(event, values) {
-    if (event === "endpointStart" || event === "endpointStop")
-        return lifecycleEndpoint(values[0], values[1]);
     if (event === "exit")
         return exit(values[0], values[1]);
     return undefined;
 }
-function lifecycleEndpoint(record, kind) {
-    const owner = process(record);
-    if (kind === "server")
-        return owner.server;
-    if (kind === "client")
-        return owner.client;
-    throw new Error("The system returned an invalid Endpoint lifecycle event");
-}
 export function exit(code, signal) {
     const namedSignal = stringOrNull(signal);
     return { status: namedSignal === null ? "exited" : "signaled", code: numberOrNull(code), signal: namedSignal };
@@ -426,8 +451,7 @@ export function bindEvents(target, events) {
     Object.assign(target, {
         subscribe: events.subscribe.bind(events),
         waitFor: events.waitFor.bind(events),
-        events: events.events.bind(events),
-        observe: events.observe.bind(events)
+        events: events.events.bind(events)
     });
 }
 export function program(record) {

package/dist/events.d.ts

@@ -2,15 +2,19 @@ import type { Capture, Cleanup, EventOptions } from "@phreshos/core";
 export declare const defaultTimeout = 10000;
 type Failure = (error: Error) => void;
 type Listener = (message: unknown) => unknown;
-type Observer = (event: string, message: unknown) => unknown;
+type EveryListener = (event: string, message: unknown) => unknown;
+type Register<Message> = (listener: (message: Message) => unknown, impossible?: Failure) => Cleanup;
 /** SDK-owned waits, queues and callbacks over boundary forwarding state. */
 export default class Events {
     private readonly listen;
     private readonly listenAll;
-    constructor(listen: (event: string, listener: Listener, impossible?: Failure) => Cleanup, listenAll: (observer: Observer) => Cleanup);
+    constructor(listen: (event: string, listener: Listener, impossible?: Failure) => Cleanup, listenAll: (listener: EveryListener, impossible?: Failure) => Cleanup);
     subscribe(event: string, subscriber: Listener): Cleanup;
+    subscribe(subscriber: (capture: Capture<string, unknown>) => unknown): Cleanup;
     waitFor(event: string, timeout?: number): Promise<unknown>;
     events(event: string, options?: EventOptions): AsyncIterableIterator<unknown>;
-    observe(observer: (capture: Capture<string, unknown>) => unknown): Cleanup;
+    events(options?: EventOptions): AsyncIterableIterator<Capture<string, unknown>>;
 }
+/** Converts one persistent registration into a bounded asynchronous iterator. */
+export declare function stream<Message>(register: Register<Message>, options?: EventOptions): AsyncIterableIterator<Message>;
 export {};

package/dist/events.js

@@ -7,8 +7,10 @@ export default class Events {
         this.listen = listen;
         this.listenAll = listenAll;
     }
-    subscribe(event, subscriber) {
-        return this.listen(event, subscriber);
+    subscribe(eventOrSubscriber, subscriber) {
+        if (typeof eventOrSubscriber === "string")
+            return this.listen(eventOrSubscriber, subscriber);
+        return this.listenAll((event, message) => eventOrSubscriber({ event, message }));
     }
     waitFor(event, timeout = defaultTimeout) {
         return new Promise((resolve, reject) => {
@@ -26,58 +28,63 @@ export default class Events {
             stop = this.listen(event, message => finish(() => resolve(message)), error => finish(() => reject(error)));
         });
     }
-    events(event, options = {}) {
-        const capacity = options.capacity ?? 64;
-        if (capacity !== Infinity && (!Number.isInteger(capacity) || capacity < 0)) {
-            throw new Error("An event queue capacity must be a non-negative integer or Infinity");
+    events(eventOrOptions = {}, namedOptions = {}) {
+        if (typeof eventOrOptions === "string") {
+            return stream((listener, impossible) => this.listen(eventOrOptions, listener, impossible), namedOptions);
         }
-        const listen = this.listen;
-        return (async function* () {
-            const queue = [];
-            let ended = false;
-            let failure = null;
-            let wake = null;
-            const stop = listen(event, message => {
-                if (ended || failure)
-                    return;
-                if (queue.length >= capacity)
-                    failure = new Error(`Event queue exceeded its capacity of ${capacity}`);
-                else
-                    queue.push(message);
-                wake?.();
-                wake = null;
-            }, error => {
-                if (ended || failure)
-                    return;
-                failure = error;
-                wake?.();
-                wake = null;
-            });
-            const abort = () => {
-                ended = true;
-                wake?.();
-                wake = null;
-            };
-            options.signal?.addEventListener("abort", abort, { once: true });
-            try {
-                while (!ended) {
-                    if (queue.length) {
-                        yield queue.shift();
-                        continue;
-                    }
-                    if (failure)
-                        throw failure;
-                    await new Promise(resolve => { wake = resolve; });
-                }
-            }
-            finally {
-                ended = true;
-                stop();
-                options.signal?.removeEventListener("abort", abort);
-            }
-        })();
+        return stream((listener, impossible) => this.listenAll((event, message) => listener({ event, message }), impossible), eventOrOptions);
     }
-    observe(observer) {
-        return this.listenAll((event, message) => observer({ event, message }));
+}
+/** Converts one persistent registration into a bounded asynchronous iterator. */
+export function stream(register, options = {}) {
+    const capacity = options.capacity ?? 64;
+    if (capacity !== Infinity && (!Number.isInteger(capacity) || capacity < 0)) {
+        throw new Error("An event queue capacity must be a non-negative integer or Infinity");
     }
+    return (async function* () {
+        const queue = [];
+        let ended = false;
+        let failure = null;
+        let wake = null;
+        const stop = register(message => {
+            if (ended || failure)
+                return;
+            if (queue.length >= capacity)
+                failure = new Error(`Event queue exceeded its capacity of ${capacity}`);
+            else
+                queue.push(message);
+            wake?.();
+            wake = null;
+        }, error => {
+            if (ended || failure)
+                return;
+            failure = error;
+            wake?.();
+            wake = null;
+        });
+        const abort = () => {
+            ended = true;
+            wake?.();
+            wake = null;
+        };
+        options.signal?.addEventListener("abort", abort, { once: true });
+        if (options.signal?.aborted)
+            abort();
+        try {
+            while (!ended) {
+                if (queue.length) {
+                    yield queue.shift();
+                    continue;
+                }
+                if (failure)
+                    throw failure;
+                await new Promise(resolve => { wake = resolve; });
+            }
+        }
+        finally {
+            ended = true;
+            stop();
+            options.signal?.removeEventListener("abort", abort);
+        }
+    })();
 }

package/dist/main.d.ts

@@ -1,8 +1,7 @@
 export { system, type System } from "./system.js";
 export { type SystemPointer, type PointerEvents, type PointerPosition } from "./pointer.js";
 export { type DesktopEvents, type DesktopSize, type SystemDesktop } from "./desktop.js";
-export { context, type Context, type ContextServer } from "./context.js";
-export { type Channel, type ChannelCapture, type ChannelEvents, type ChannelMessage } from "./channel.js";
-export { ClientService, ServerService, Service, 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, Storage, ProgramEvents, ProgramProcessEvents, ProgramProcessExit, ProgramSql, ProgramStore, ProcessEvents, Publishable, SystemUploads, Upload, Size, Subscribable, SubscribableEvents, SubscribableFallback, TimedAskable, TimedPermission, Timeoutable, Appearance, AppearanceEvents, AppearanceSource, AppearanceSurface, AnimationsPreference, DesktopPreferences, DesktopPreferencesEvents, DesktopPreferencesUpdate, SystemDesktopPreferences, ThemedValue, Theme, ThemePreference, Value, WindowEvents, WindowGeometry, WindowLayer, WindowState, Easing, LocalWindow, LocalWindowSurface, VisibilityTransition, Transaction } from "@phreshos/core";
+export { context, type Context, type ContextCapture, type ContextEvents, type ContextMessage, type ContextServer } from "./context.js";
+export { ClientService, ServerService, Service, type ServiceKey, type ServiceLifecycle, type ServiceLifecycleEvents } from "@phreshos/core";
+export { Client, Endpoint, Process, Program, Server, type Window, type ProgramProcess, type AnswerCapture, type AnswerMessage, type AnswerSubscriber, type AskCapture, type AskMessage, type AskSubscriber, type ClientTraffic, type EndpointTraffic, type ServerTraffic, type TrafficCapture, type TrafficEvents, type TrafficMessage } from "./domain.js";
+export type { Askable, Capture, Captures, CaptureSubscriber, ClientDeclaration, Cleanup, DirectoryStat, EndpointDeclaration, EndpointLifecycle, EndpointLifecycleEvents, EntryStat, EventMessage, EventName, EventOptions, EventSubscriber, Exit, FileStat, Launch, LaunchClient, Layer, LogKind, LogRecord, LogSource, Message, OtherStat, Outcome, PermissionDecision, Permission, Position, Storage, ProgramEvents, ProgramProcessEvents, ProgramProcessExit, ProgramSql, ProgramStore, ProcessEvents, Publishable, SystemUploads, Upload, Size, Subscribable, SubscribableEvents, SubscribableFallback, TimedAskable, TimedPermission, Timeoutable, Appearance, AppearanceEvents, AppearanceSource, AppearanceSurface, AnimationsPreference, DesktopPreferences, DesktopPreferencesEvents, DesktopPreferencesUpdate, SystemDesktopPreferences, ThemedValue, Theme, ThemePreference, Value, WindowEvents, WindowGeometry, WindowLayer, WindowState, Easing, LocalWindow, LocalWindowSurface, VisibilityTransition, Transaction } from "@phreshos/core";

package/dist/main.js

@@ -2,6 +2,5 @@ export { system } from "./system.js";
 export {} from "./pointer.js";
 export {} from "./desktop.js";
 export { context } from "./context.js";
-export {} from "./channel.js";
 export { ClientService, ServerService, Service } from "@phreshos/core";
 export { Client, Endpoint, Process, Program, Server } from "./domain.js";

package/dist/service.js

@@ -6,11 +6,16 @@ import wire from "./wire.js";
 const handles = new HandleRegistry();
 const ServerServiceBase = CoreServerService;
 const ClientServiceBase = CoreClientService;
-class ServerChannelHandle extends Events {
+class ServerHandler extends ServerServiceBase {
     key;
+    name;
+    lifecycle;
     constructor(key) {
-        super(...serviceEvents(key, "channel"));
+        super();
         this.key = key;
+        this.name = key.name;
+        this.lifecycle = new Events(...serviceEvents(key, "lifecycle"));
+        bindEvents(this, new Events(...serviceEvents(key, "events")));
     }
     publish(event, payload = undefined) {
         wire.send("end-host", "service-send", this.key, event, payload);
@@ -25,6 +30,13 @@ class ServerChannelHandle extends Events {
             }
         };
     }
+    async enabled() {
+        const answer = await wire.request(["service-enabled", this.key]);
+        return answer[0];
+    }
+    async waitReady(timeout) {
+        await wire.request(["service-wait-ready", this.key, timeout], timeout);
+    }
     async askWithin(deadline, event, payload) {
         const identity = await wire.identity();
         const address = `client:${identity.process}:${crypto.randomUUID()}`;
@@ -39,40 +51,16 @@ class ServerChannelHandle extends Events {
         }
     }
 }
-class ClientChannelHandle extends Events {
-    constructor(key) {
-        super(...serviceEvents(key, "channel"));
-    }
-}
-class ServerHandler extends ServerServiceBase {
-    key;
-    name;
-    channel;
-    constructor(key) {
-        super();
-        this.key = key;
-        this.name = key.name;
-        this.channel = new ServerChannelHandle(key);
-        bindEvents(this, new Events(...serviceEvents(key, "lifecycle")));
-    }
-    async enabled() {
-        const answer = await wire.request(["service-enabled", this.key]);
-        return answer[0];
-    }
-    async waitReady(timeout) {
-        await wire.request(["service-wait-ready", this.key, timeout], timeout);
-    }
-}
 class ClientHandler extends ClientServiceBase {
     key;
     name;
-    channel;
+    lifecycle;
     constructor(key) {
         super();
         this.key = key;
         this.name = key.name;
-        this.channel = new ClientChannelHandle(key);
-        bindEvents(this, new Events(...serviceEvents(key, "lifecycle")));
+        this.lifecycle = new Events(...serviceEvents(key, "lifecycle"));
+        bindEvents(this, new Events(...serviceEvents(key, "events")));
     }
     async enabled() {
         const answer = await wire.request(["service-enabled", this.key]);
@@ -106,9 +94,9 @@ export async function endpointService(target, endpoint) {
 function serviceEvents(key, scope) {
     return [
         (event, listener) => wire.followService(key, scope, event, listener),
-        (observer) => wire.followService(key, scope, null, (event, payload) => {
+        (listener) => wire.followService(key, scope, null, (event, payload) => {
             if (typeof event === "string")
-                observer(event, payload);
+                listener(event, payload);
         })
     ];
 }
@@ -116,7 +104,6 @@ function bindEvents(target, events) {
     Object.assign(target, {
         subscribe: events.subscribe.bind(events),
         waitFor: events.waitFor.bind(events),
-        events: events.events.bind(events),
-        observe: events.observe.bind(events)
+        events: events.events.bind(events)
     });
 }

package/dist/wire.d.ts

@@ -32,12 +32,12 @@ declare class Wire {
     expectWithin(question: string, deadline: Deadline): Promise<unknown>;
     forget(question: string): void;
     on(route: string, event: string, handler: Handler, subject?: string | null, impossible?: Failure): Cleanup;
-    onAll(route: string, handler: Handler, subject?: string | null): Cleanup;
+    onAll(route: string, handler: Handler, subject?: string | null, impossible?: Failure): Cleanup;
     observe(target: HandleAddress | null, half: "server" | "client", kind: TrafficKind, event: string | null, handler: Handler, impossible?: Failure): Cleanup;
     /** Follow destinationless events emitted by one Endpoint. */
     follow(target: HandleAddress | null, half: "server" | "client", event: string | null, handler: Handler, impossible?: Failure): Cleanup;
     /** Follow one exact service lifecycle or application event route. */
-    followService(key: ServiceKey, scope: "lifecycle" | "channel", event: string | null, handler: Handler): Cleanup;
+    followService(key: ServiceKey, scope: "lifecycle" | "events", event: string | null, handler: Handler): Cleanup;
     samplePointer(movementX: number, movementY: number): void;
     private register;
     private unregister;

package/dist/wire.js

@@ -221,11 +221,11 @@ class Wire {
             this.unregister(subscription);
         });
     }
-    onAll(route, handler, subject = null) {
+    onAll(route, handler, subject = null, impossible) {
         const handlers = this.every.get(route) ?? new Set();
         handlers.add(handler);
         this.every.set(route, handlers);
-        const subscription = this.register("publish", route, null, subject);
+        const subscription = this.register("publish", route, null, subject, impossible);
         return once(() => {
             handlers.delete(handler);
             if (!handlers.size)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/client",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "description": "The SDK used by a Program's client endpoint.",
   "type": "module",
   "main": "dist/main.js",
@@ -47,13 +47,13 @@
     "prepack": "node --run build"
   },
   "peerDependencies": {
-    "@phreshos/core": "^0.1.24"
+    "@phreshos/core": "^0.1.27"
   },
   "dependencies": {
     "@msgpack/msgpack": "^3.1.3"
   },
   "devDependencies": {
-    "@phreshos/core": "^0.1.24",
+    "@phreshos/core": "^0.1.27",
     "typescript": "^6.0.3"
   }
 }

package/dist/channel.d.ts

@@ -1,12 +0,0 @@
-import type { Channel as CoreChannel, ChannelCapture as CoreChannelCapture, ChannelEvents as CoreChannelEvents, ChannelMessage as CoreChannelMessage } from "@phreshos/core";
-import { type Endpoint } from "./domain.js";
-/** One value addressed to the current Client, with a client-visible sender. */
-export type ChannelMessage<Payload = unknown> = CoreChannelMessage<Payload, Endpoint | null>;
-/** Applies the client-visible sender envelope to known Channel events. */
-export type ChannelEvents<Events extends object> = CoreChannelEvents<Events, Endpoint | null>;
-/** Every event observable through the current Client's Channel. */
-export type ChannelCapture<Events extends object = {}> = CoreChannelCapture<Events, Endpoint | null>;
-/** Events explicitly accepted by the current Client. */
-export interface Channel<Events extends object = {}> extends CoreChannel<Events, Endpoint | null> {
-}
-export declare const channel: Channel;

package/dist/channel.js

@@ -1,22 +0,0 @@
-import { visibleEndpoint } from "./domain.js";
-import Events from "./events.js";
-import wire from "./wire.js";
-import { disableCurrentService, enableCurrentService } from "./service.js";
-class ClientChannel extends Events {
-    constructor() {
-        super((event, listener, impossible) => wire.on("end-end", event, value => listener(message(value)), null, impossible), observer => wire.onAll("end-end", (event, value) => {
-            if (typeof event === "string")
-                observer(event, message(value));
-        }));
-    }
-    publish(event, payload = undefined) {
-        wire.send("end-host", "emit", event, payload);
-    }
-    async enableService(name) { await enableCurrentService(name); }
-    async disableService() { await disableCurrentService(); }
-}
-function message(value) {
-    const raw = value;
-    return { from: visibleEndpoint(raw.from), payload: raw.payload };
-}
-export const channel = new ClientChannel();