@phreshos/server 0.1.12 → 0.1.13

package/README.md

@@ -154,6 +154,26 @@ and their Endpoint declarations. `program.server?.hasService()` identifies a
 declared Service capability, while `await program.server?.docs()` reads its
 installed policy and API documentation before the Endpoint starts.
 
+Server-side Service handles can create their dedicated providing Process and
+wait for readiness without reproducing Program-specific launch rules:
+
+```ts
+await serverService.createAndWaitReady()
+await clientService.createAndWaitReady({ minimize: true })
+```
+
+Both readiness operations accept an optional timeout directly and expose an
+immutable timed view. A direct argument on the timed view takes precedence:
+
+```ts
+await service.waitReady(10_000)
+await service.timeout(5_000).waitReady()
+await service.timeout(5_000).waitReady(10_000)
+```
+
+The System owns the single deadline across Process creation, Endpoint startup,
+and Service readiness. The creation capability exists only in the Server SDK.
+
 `program.icon()` requests a guaranteed PNG `Blob` in `small`, `medium`, or
 `large` form without exposing the Program's source path or the system's private
 asset-hosting address. Omitting the size selects `medium`.

package/dist/domain.d.ts

@@ -1,6 +1,7 @@
 import { Client as CoreClient, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer, type AnswerCapture, type AskCapture, type Cleanup, type ClientDeclaration, type Exit, type Launch, type Position, type ProgramPermission, type ProgramProcess as CoreProgramProcess, type ProgramArea as CoreProgramArea, type Size, type TrafficMessage, type Window as CoreWindow, type WindowState } from "@phreshos/core";
 import Events from "./events.js";
 import { type ProgramStartup } from "./startup.js";
+import { type ClientServiceHandler, type ServerServiceHandler } from "./service.js";
 export interface HandleAddress {
     identity: string;
     reference: string;
@@ -104,6 +105,8 @@ export interface Endpoint<Events extends object = {}> extends CoreEndpoint<Event
 export interface Server<Events extends object = {}> extends CoreServer<Events> {
     /** Returns the Process that owns this Server. */
     process(): Promise<Process>;
+    /** Returns the Service currently exposed by this Server Endpoint. */
+    service<ServiceEvents extends object = {}>(): Promise<ServerServiceHandler<ServiceEvents> | null>;
 }
 /** Server-visible Client handle. */
 export interface Client<Events extends object = {}> extends CoreClient<Events> {
@@ -111,6 +114,8 @@ export interface Client<Events extends object = {}> extends CoreClient<Events> {
     readonly window: Window;
     /** Returns the Process that owns this Client. */
     process(): Promise<Process>;
+    /** Returns the Service currently exposed by this Client Endpoint. */
+    service<ServiceEvents extends object = {}>(): Promise<ClientServiceHandler<ServiceEvents> | null>;
 }
 /** Server-visible Client-owned Window capability. */
 export type Window = CoreWindow;

package/dist/host.d.ts

@@ -1,4 +1,5 @@
-import type { DesktopWallpaper, Exit, FileWallpaper, Layer, Position, ServedFile, ClientServiceHandler, ServerServiceHandler, ServiceKey, Size, Subscribable, ThemeProperties, WritableTheme } from "@phreshos/core";
+import type { DesktopWallpaper, Exit, FileWallpaper, Layer, Position, ServedFile, ServiceKey, Size, Subscribable, ThemeProperties, WritableTheme } from "@phreshos/core";
+import type { ClientServiceHandler, ServerServiceHandler } from "./service.js";
 import { type Client, type Process, type Program, type Server } from "./domain.js";
 /** Resolved production description for a Program's Server. */
 export type ServerDescription = Readonly<{

package/dist/main.d.ts

@@ -2,6 +2,7 @@ export { host, type Host, type HostProcess, type HostProgram, type ClientDescrip
 export { current, type Current, type CurrentClient } from "./current.js";
 export { type Answerer, type Channel } from "./channel.js";
 export { type ProgramStartup } from "./startup.js";
-export { ClientServiceHandler, ServerServiceHandler, ServiceHandler, type ClientServiceChannel, type ServerServiceChannel, type ServiceChannel, type ServiceKey, type ServiceLifecycleEvents } from "@phreshos/core";
+export { ClientServiceHandler, ServerServiceHandler, type TimedClientServiceHandler, type TimedServerServiceHandler } from "./service.js";
+export { ServiceHandler, type ClientServiceChannel, type ServerServiceChannel, type ServiceChannel, type ServiceKey, type ServiceLifecycleEvents } from "@phreshos/core";
 export { Client, Endpoint, Process, Program, Server, type Window, type ProgramArea, type ProgramProcess } from "./domain.js";
 export type { AnswerCapture, AnswerMessage, AnswerObserver, Askable, AskCapture, AskMessage, AskObserver, Capture, Captures, ChannelCapture, ChannelEvents, ChannelMessage, ClientTraffic, ClientDeclaration, Cleanup, DirectoryStat, EndpointDeclaration, EndpointTraffic, EntryStat, EventMessage, EventName, EventObserver, EventOptions, EventSubscriber, Exit, FileStat, Launch, LaunchClient, Layer, LogKind, LogRecord, LogSource, Message, OtherStat, Outcome, Position, ProgramEvents, ProgramPermission, ProgramProcessEvents, ProgramProcessExit, ProgramSql, ProgramStore, ProcessEvents, Publishable, ServedFile, ServerTraffic, Size, Subscribable, SubscribableEvents, SubscribableFallback, TimedAskable, TrafficCapture, TrafficEvents, TrafficMessage, Value, Theme, ThemeEvents, ThemeProperties, WallpaperLaunch, FileWallpaper, DesktopWallpaper, WritableTheme, WindowEvents, WindowGeometry, WindowLayer, WindowState } from "@phreshos/core";

package/dist/main.js

@@ -2,5 +2,6 @@ export { host } from "./host.js";
 export { current } from "./current.js";
 export {} from "./channel.js";
 export {} from "./startup.js";
-export { ClientServiceHandler, ServerServiceHandler, ServiceHandler } from "@phreshos/core";
+export { ClientServiceHandler, ServerServiceHandler } from "./service.js";
+export { ServiceHandler } from "@phreshos/core";
 export { Client, Endpoint, Process, Program, Server } from "./domain.js";

package/dist/service.d.ts

@@ -1,5 +1,31 @@
-import { type ClientServiceHandler, type ServerServiceHandler, type ServiceHandler, type ServiceKey } from "@phreshos/core";
+import { ClientServiceHandler as CoreClientServiceHandler, ServerServiceHandler as CoreServerServiceHandler, type LaunchClient, type ServiceHandler, type ServiceKey, type Timeoutable } from "@phreshos/core";
 import type { HandleAddress } from "./domain.js";
+/** Timed view of a Server Endpoint Service available through the Server SDK. */
+export interface TimedServerServiceHandler {
+    waitReady(timeout?: number): Promise<void>;
+    createAndWaitReady(timeout?: number): Promise<void>;
+}
+/** Timed view of a Client Endpoint Service available through the Server SDK. */
+export interface TimedClientServiceHandler {
+    waitReady(timeout?: number): Promise<void>;
+    createAndWaitReady(client?: LaunchClient, timeout?: number): Promise<void>;
+}
+/** Server-SDK handle for a Service provided by a Server Endpoint. */
+export declare class ServerServiceHandler<Events extends object = {}> extends CoreServerServiceHandler<Events> {
+    protected constructor();
+}
+export interface ServerServiceHandler<Events extends object = {}> extends Timeoutable<TimedServerServiceHandler> {
+    createAndWaitReady(timeout?: number): Promise<void>;
+    timeout(milliseconds: number): TimedServerServiceHandler;
+}
+/** Server-SDK handle for a Service provided by a Client Endpoint. */
+export declare class ClientServiceHandler<Events extends object = {}> extends CoreClientServiceHandler<Events> {
+    protected constructor();
+}
+export interface ClientServiceHandler<Events extends object = {}> extends Timeoutable<TimedClientServiceHandler> {
+    createAndWaitReady(client?: LaunchClient, timeout?: number): Promise<void>;
+    timeout(milliseconds: number): TimedClientServiceHandler;
+}
 export declare function prepareService<EventsMap extends object = {}>(key: ServiceKey & {
     endpoint: "server";
 }): ServerServiceHandler<EventsMap>;

package/dist/service.js

@@ -5,8 +5,14 @@ import Events from "./events.js";
 import HandleRegistry from "./handle-registry.js";
 import wire from "./wire.js";
 const handles = new HandleRegistry();
-const ServerServiceBase = CoreServerServiceHandler;
-const ClientServiceBase = CoreClientServiceHandler;
+/** Server-SDK handle for a Service provided by a Server Endpoint. */
+export class ServerServiceHandler extends CoreServerServiceHandler {
+    constructor() { super(); }
+}
+/** Server-SDK handle for a Service provided by a Client Endpoint. */
+export class ClientServiceHandler extends CoreClientServiceHandler {
+    constructor() { super(); }
+}
 class ServerChannelHandle extends Events {
     key;
     constructor(key) {
@@ -45,7 +51,7 @@ class ClientChannelHandle extends Events {
         super(...serviceEvents(key, "channel"));
     }
 }
-class ServerHandler extends ServerServiceBase {
+class ServerHandler extends ServerServiceHandler {
     key;
     name;
     channel;
@@ -63,8 +69,17 @@ class ServerHandler extends ServerServiceBase {
     async waitReady(timeout) {
         await wire.request(["service-wait-ready", this.key, timeout], timeout);
     }
+    async createAndWaitReady(timeout) {
+        await wire.request(["service-create-and-wait-ready", this.key, undefined, timeout], timeout);
+    }
+    timeout(milliseconds) {
+        return Object.freeze({
+            waitReady: (timeout) => this.waitReady(timeout ?? milliseconds),
+            createAndWaitReady: (timeout) => this.createAndWaitReady(timeout ?? milliseconds)
+        });
+    }
 }
-class ClientHandler extends ClientServiceBase {
+class ClientHandler extends ClientServiceHandler {
     key;
     name;
     channel;
@@ -82,6 +97,17 @@ class ClientHandler extends ClientServiceBase {
     async waitReady(timeout) {
         await wire.request(["service-wait-ready", this.key, timeout], timeout);
     }
+    async createAndWaitReady(client, timeout) {
+        await wire.request(["service-create-and-wait-ready", this.key, client, timeout], timeout);
+    }
+    timeout(milliseconds) {
+        return Object.freeze({
+            waitReady: (timeout) => this.waitReady(timeout ?? milliseconds),
+            createAndWaitReady: (client, timeout) => {
+                return this.createAndWaitReady(client, timeout ?? milliseconds);
+            }
+        });
+    }
 }
 export function prepareService(key) {
     if (!isServiceKey(key))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/server",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "The SDK used by a Program's server endpoint.",
   "type": "module",
   "main": "dist/main.js",