@phreshos/client 0.1.26 → 0.1.28

package/README.md

@@ -75,17 +75,22 @@ does not read or start the Service and exposes no Service registry:
 ```ts
 const service = system.service({
   program: "counter",
-  endpoint: "server",
-  name: "state"
+  process: "main",
+  endpoint: "server"
 })
 
 await service.waitReady()
-if (await service.enabled()) await service.ask("value")
+if (await service.exists()) await service.ask("value")
 
 service.subscribe("changed", message => console.log(message))
-service.lifecycle.subscribe("disable", () => console.log("unavailable"))
+service.lifecycle.subscribe("stop", () => console.log("unavailable"))
 ```
 
+The `program` coordinate is required for a Program-local Process name. When
+`process` is an exact globally unique identity, use
+`system.service({ process, endpoint })`; that handle never retargets a
+replacement Process.
+
 A Client may traverse `Process.parent()` through any number of ancestors in
 its own Program. The first parent outside that Program is structurally hidden
 and returned as `null`; no cross-Program Process handle enters the client. If
@@ -110,6 +115,8 @@ through `context.process()`. It is the canonical Process-owned handle, so
 `context.server === (await context.process()).server`.
 Endpoint `process()` navigation is asynchronous; contextual ownership is
 requested only when navigation needs it and then retained by the SDK.
+`context.name()` returns that retained Process's Program-local name, or `null`
+when its launch was unnamed.
 
 All domain handles are canonical within this iframe's JavaScript realm. Lookup,
 navigation, event payloads, and message metadata reuse the same weakly retained

package/dist/context.d.ts

@@ -1,5 +1,5 @@
 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";
+import { 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>;
 /** One value addressed to the current Client, with a client-visible sender. */
@@ -9,7 +9,7 @@ export type ContextEvents<Events extends object> = CoreContextEvents<Events, End
 /** 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"> {
+export interface Context<Events extends object = {}> extends CoreContext<Events, Endpoint | null> {
     /** The same Server handle exposed by the executing Process. */
     readonly server: ContextServer;
     /** Presentation capability of the executing Client. */
@@ -18,6 +18,8 @@ export interface Context<Events extends object = {}> extends CoreContext<Events,
     readonly permission: Program["permission"];
     /** Returns the Process represented by this Client. */
     process(): Promise<Process>;
+    /** Returns the executing Process's Program-local name, or `null` when unnamed. */
+    name(): Promise<string | null>;
     /** Returns the accessible parent Process, or `null` when none exists. */
     parent(): Promise<Process | null>;
     /** Returns the Program that owns this Client. */

package/dist/context.js

@@ -2,7 +2,6 @@ import Deadline from "./deadline.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 { disableCurrentService, enableCurrentService, endpointService } from "./service.js";
 import { currentProgramPermission } from "./permissions.js";
 const ServerBase = Server;
 const ClientBase = Client;
@@ -21,9 +20,9 @@ class ContextServerHandle extends ServerBase {
         const answer = await wire.request(["exists", "server"]);
         return answer[0];
     }
-    async start() { await wire.request(["start-endpoint", undefined, "server"]); }
+    async start(launch = {}) { await wire.request(["start-endpoint", undefined, "server", launch]); }
     async stop() { await wire.request(["stop-endpoint", undefined, "server"]); }
-    service() { return endpointService(null, "server"); }
+    async isService() { return (await wire.request(["is-service", "server"]))[0]; }
     async waitReady(timeout) { await wire.request(["wait-ready"], timeout); }
     async ask(event, payload = undefined) {
         return this.askWithin(undefined, event, payload);
@@ -75,9 +74,9 @@ class ContextClientHandle extends ClientBase {
         const answer = await wire.request(["exists", "client"]);
         return answer[0];
     }
-    async start(overrides = {}) { await wire.request(["start-endpoint", undefined, "client", overrides]); }
+    async start(launch = {}) { await wire.request(["start-endpoint", undefined, "client", launch]); }
     async stop() { await wire.request(["stop-endpoint", undefined, "client"]); }
-    service() { return endpointService(null, "client"); }
+    async isService() { return (await wire.request(["is-service", "client"]))[0]; }
 }
 contextClient = new ContextClientHandle(owner);
 class ClientContext extends Events {
@@ -91,6 +90,7 @@ class ClientContext extends Events {
         }, null, impossible));
     }
     process() { return owner(); }
+    async name() { return (await owner()).name; }
     async parent() {
         const answer = await wire.request(["parent"]);
         return answer[0] ? process(answer[0]) : null;
@@ -104,10 +104,8 @@ class ClientContext extends Events {
         return answer[0];
     }
     async stop() { await wire.request(["stop-current"]); }
-    service() { return endpointService(null, "client"); }
+    async isService() { return contextClient.isService(); }
     publish(event, payload = undefined) { wire.send("end-host", "emit", event, payload); }
-    async enableService(name) { await enableCurrentService(name); }
-    async disableService() { await disableCurrentService(); }
 }
 async function currentAddress() {
     const identity = await wire.identity();

package/dist/domain.d.ts

@@ -6,6 +6,7 @@ export interface HandleAddress {
 }
 export interface EndpointDeclarationRecord {
     start: boolean;
+    service: boolean;
 }
 export interface ClientDeclarationRecord extends EndpointDeclarationRecord {
     title: string | null;
@@ -32,8 +33,11 @@ export interface ProcessRecord {
     program: ProgramRecord;
     options: Record<string, string>;
     startedAt: string | Date;
-    server: Record<string, never> | null;
-    client: Record<string, never> | null;
+    server: EndpointRecord | null;
+    client: EndpointRecord | null;
+}
+export interface EndpointRecord {
+    service: boolean;
 }
 export interface EndpointReference {
     kind: "server" | "client";
@@ -41,7 +45,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 +69,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. */

package/dist/domain.js

@@ -4,7 +4,6 @@ import Deadline from "./deadline.js";
 import HandleRegistry from "./handle-registry.js";
 import { area, sql, store } from "./storage.js";
 import wire from "./wire.js";
-import { endpointService } from "./service.js";
 import { currentProgramPermission } from "./permissions.js";
 const handles = new HandleRegistry();
 const ProgramBase = CoreProgram;
@@ -75,7 +74,8 @@ function programCommandChunk(value) {
 }
 function declaration(record) {
     return Object.freeze({
-        start: record.start
+        start: record.start,
+        service: record.service
     });
 }
 function clientDeclaration(record) {
@@ -219,9 +219,9 @@ class ServerHandle extends ServerBase {
         const answer = await wire.request(["exists", "server", this.owner.address]);
         return answer[0];
     }
-    async start() { await wire.request(["start-endpoint", this.owner.address, "server"]); }
+    async start(launch = {}) { await wire.request(["start-endpoint", this.owner.address, "server", launch]); }
     async stop() { await wire.request(["stop-endpoint", this.owner.address, "server"]); }
-    service() { return endpointService(this.owner.address, "server"); }
+    async isService() { return (await wire.request(["is-service", "server", this.owner.address]))[0]; }
     async waitReady(timeout) { await wire.request(["wait-ready", this.owner.address], timeout); }
     async ask(event, payload = undefined) {
         return this.askWithin(undefined, event, payload);
@@ -264,9 +264,9 @@ class ClientHandle extends ClientBase {
         const answer = await wire.request(["exists", "client", this.owner.address]);
         return answer[0];
     }
-    async start(overrides = {}) { await wire.request(["start-endpoint", this.owner.address, "client", overrides]); }
+    async start(launch = {}) { await wire.request(["start-endpoint", this.owner.address, "client", launch]); }
     async stop() { await wire.request(["stop-endpoint", this.owner.address, "client"]); }
-    service() { return endpointService(this.owner.address, "client"); }
+    async isService() { return (await wire.request(["is-service", "client", this.owner.address]))[0]; }
 }
 class WindowHandle extends Events {
     target;
@@ -421,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")
@@ -431,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 };

package/dist/main.d.ts

@@ -2,6 +2,6 @@ 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 ContextCapture, type ContextEvents, type ContextMessage, type ContextServer } from "./context.js";
-export { ClientService, ServerService, Service, type ServiceKey, type ServiceLifecycle, type ServiceLifecycleEvents } from "@phreshos/core";
+export { ClientService, ServerService, Service, type ServiceKey, } 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";
+export type { Askable, Capture, Captures, CaptureSubscriber, ClientLaunch, ClientDeclaration, Cleanup, DirectoryStat, EndpointDeclaration, EndpointLifecycle, EndpointLifecycleEvents, EntryStat, EventMessage, EventName, EventOptions, EventSubscriber, Exit, FileStat, Launch, ServerLaunch, 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,5 +2,5 @@ export { system } from "./system.js";
 export {} from "./pointer.js";
 export {} from "./desktop.js";
 export { context } from "./context.js";
-export { ClientService, ServerService, Service } from "@phreshos/core";
+export { ClientService, ServerService, Service, } from "@phreshos/core";
 export { Client, Endpoint, Process, Program, Server } from "./domain.js";

package/dist/service.d.ts

@@ -1,5 +1,4 @@
 import { type ClientService, type ServerService, type Service, type ServiceKey } from "@phreshos/core";
-import type { HandleAddress } from "./domain.js";
 export declare function prepareService<EventsMap extends object = {}>(key: ServiceKey & {
     endpoint: "server";
 }): ServerService<EventsMap>;
@@ -7,8 +6,3 @@ export declare function prepareService<EventsMap extends object = {}>(key: Servi
     endpoint: "client";
 }): ClientService<EventsMap>;
 export declare function prepareService(key: ServiceKey): Service;
-export declare function enableCurrentService(name: string): Promise<void>;
-export declare function disableCurrentService(): Promise<void>;
-export declare function endpointService<EventsMap extends object = {}>(target: HandleAddress | null, endpoint: "server"): Promise<ServerService<EventsMap> | null>;
-export declare function endpointService<EventsMap extends object = {}>(target: HandleAddress | null, endpoint: "client"): Promise<ClientService<EventsMap> | null>;
-export declare function endpointService(target: HandleAddress | null, endpoint: "server" | "client"): Promise<Service | null>;

package/dist/service.js

@@ -6,37 +6,43 @@ import wire from "./wire.js";
 const handles = new HandleRegistry();
 const ServerServiceBase = CoreServerService;
 const ClientServiceBase = CoreClientService;
-class ServerHandler extends ServerServiceBase {
+class ServiceHandle {
     key;
-    name;
     lifecycle;
     constructor(key) {
-        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);
     }
-    async ask(event, payload = undefined) {
-        return await this.askWithin(new Deadline(), event, payload);
-    }
-    timeout(milliseconds) {
-        return {
-            ask: (event, payload = undefined) => {
-                return this.askWithin(new Deadline(milliseconds), event, payload);
-            }
-        };
-    }
-    async enabled() {
-        const answer = await wire.request(["service-enabled", this.key]);
+    async exists() {
+        const answer = await wire.request(["service-exists", this.key]);
         return answer[0];
     }
+}
+class ServerHandler extends ServerServiceBase {
+    key;
+    lifecycle;
+    service;
+    constructor(key) {
+        super();
+        this.key = key;
+        this.service = new ServiceHandle(key);
+        this.lifecycle = this.service.lifecycle;
+        bindEvents(this, new Events(...serviceEvents(key, "events")));
+    }
+    publish(event, payload = undefined) { this.service.publish(event, payload); }
+    exists() { return this.service.exists(); }
     async waitReady(timeout) {
         await wire.request(["service-wait-ready", this.key, timeout], timeout);
     }
+    async ask(event, payload = undefined) {
+        return await this.askWithin(new Deadline(), event, payload);
+    }
+    timeout(milliseconds) {
+        return { ask: (event, payload = undefined) => (this.askWithin(new Deadline(milliseconds), event, payload)) };
+    }
     async askWithin(deadline, event, payload) {
         const identity = await wire.identity();
         const address = `client:${identity.process}:${crypto.randomUUID()}`;
@@ -52,44 +58,29 @@ class ServerHandler extends ServerServiceBase {
     }
 }
 class ClientHandler extends ClientServiceBase {
-    key;
-    name;
     lifecycle;
+    service;
     constructor(key) {
         super();
-        this.key = key;
-        this.name = key.name;
-        this.lifecycle = new Events(...serviceEvents(key, "lifecycle"));
+        this.service = new ServiceHandle(key);
+        this.lifecycle = this.service.lifecycle;
         bindEvents(this, new Events(...serviceEvents(key, "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);
-    }
+    publish(event, payload = undefined) { this.service.publish(event, payload); }
+    exists() { return this.service.exists(); }
 }
 export function prepareService(key) {
     if (!isServiceKey(key))
         throw new Error("A complete service key is required");
-    const normalized = Object.freeze({ program: key.program, endpoint: key.endpoint, name: key.name });
-    const identity = JSON.stringify([normalized.program, normalized.endpoint, normalized.name]);
-    return handles.obtain(`service:${identity}`, () => {
-        return normalized.endpoint === "server"
-            ? new ServerHandler(normalized)
-            : new ClientHandler(normalized);
+    const normalized = Object.freeze({
+        ...(key.program === undefined ? {} : { program: key.program }),
+        process: key.process,
+        endpoint: key.endpoint
     });
-}
-export async function enableCurrentService(name) {
-    await wire.request(["enable-service", name]);
-}
-export async function disableCurrentService() {
-    await wire.request(["disable-service"]);
-}
-export async function endpointService(target, endpoint) {
-    const answer = await wire.request(["endpoint-service", target, endpoint]);
-    return answer[0] ? prepareService(answer[0]) : null;
+    const identity = JSON.stringify([key.program ?? null, key.process, key.endpoint]);
+    return handles.obtain(`service:${identity}`, () => normalized.endpoint === "server"
+        ? new ServerHandler(normalized)
+        : new ClientHandler(normalized));
 }
 function serviceEvents(key, scope) {
     return [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/client",
-  "version": "0.1.26",
+  "version": "0.1.28",
   "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.26"
+    "@phreshos/core": "^0.1.29"
   },
   "dependencies": {
     "@msgpack/msgpack": "^3.1.3"
   },
   "devDependencies": {
-    "@phreshos/core": "^0.1.26",
+    "@phreshos/core": "^0.1.29",
     "typescript": "^6.0.3"
   }
 }