@phreshos/node 0.1.4 → 0.1.6

package/dist/events.d.ts

@@ -1,6 +1,6 @@
 import type { Subscribable } from "@phreshos/core";
 type Wait = (event: string | null, signal: AbortSignal, timeout?: number) => Promise<unknown>;
-/** Adapt authoritative one-event waits into the shared Subscribable contract. */
+/** Adapts authoritative one-event waits into the shared Subscribable contract. */
 export default class Events<Definitions extends object, Fallback = never> {
     private readonly names;
     private readonly wait;
@@ -8,6 +8,6 @@ export default class Events<Definitions extends object, Fallback = never> {
     readonly subscribe: Subscribable<Definitions, Fallback>["subscribe"];
     readonly waitFor: Subscribable<Definitions, Fallback>["waitFor"];
     readonly events: Subscribable<Definitions, Fallback>["events"];
-    readonly observe: Subscribable<Definitions, Fallback>["observe"];
+    private listen;
 }
 export {};

package/dist/events.js

@@ -1,4 +1,4 @@
-/** Adapt authoritative one-event waits into the shared Subscribable contract. */
+/** Adapts authoritative one-event waits into the shared Subscribable contract. */
 export default class Events {
     names;
     wait;
@@ -6,73 +6,112 @@ export default class Events {
         this.names = names;
         this.wait = wait;
     }
-    subscribe = ((event, subscriber) => {
-        const controller = new AbortController();
-        void (async () => {
-            while (!controller.signal.aborted) {
-                try {
-                    subscriber(await this.wait(event, controller.signal, 86_400_000));
-                }
-                catch (error) {
-                    if (!controller.signal.aborted && timeout(error))
-                        continue;
-                    if (!controller.signal.aborted)
-                        controller.abort();
-                }
-            }
-        })();
-        return () => controller.abort();
+    subscribe = ((eventOrSubscriber, subscriber) => {
+        if (typeof eventOrSubscriber === "string")
+            return this.listen(eventOrSubscriber, subscriber);
+        if (this.names.length) {
+            const stops = this.names.map(event => this.listen(event, message => eventOrSubscriber({ event, message })));
+            return () => stops.forEach(stop => stop());
+        }
+        return this.listen(null, value => {
+            const capture = value;
+            if (typeof capture.event === "string")
+                eventOrSubscriber({ event: capture.event, message: capture.payload });
+        });
     });
     waitFor = ((event, timeout) => {
         return this.wait(event, new AbortController().signal, timeout);
     });
-    events = ((event, options = {}) => {
-        const wait = this.wait;
-        return (async function* () {
-            const controller = new AbortController();
-            const abort = () => controller.abort(options.signal?.reason);
-            options.signal?.addEventListener("abort", abort, { once: true });
-            try {
-                while (!controller.signal.aborted) {
-                    try {
-                        yield await wait(event, controller.signal, 86_400_000);
-                    }
-                    catch (error) {
-                        if (!controller.signal.aborted && timeout(error))
-                            continue;
-                        throw error;
-                    }
-                }
-            }
-            finally {
-                options.signal?.removeEventListener("abort", abort);
-                controller.abort();
+    events = ((eventOrOptions = {}, namedOptions = {}) => {
+        if (typeof eventOrOptions === "string") {
+            return stream((subscriber, impossible) => this.listen(eventOrOptions, subscriber, impossible), namedOptions);
+        }
+        return stream((subscriber, impossible) => {
+            if (this.names.length) {
+                const stops = this.names.map(event => this.listen(event, message => subscriber({ event, message }), impossible));
+                return () => stops.forEach(stop => stop());
             }
-        })();
+            return this.listen(null, value => {
+                const capture = value;
+                if (typeof capture.event === "string")
+                    subscriber({ event: capture.event, message: capture.payload });
+            }, impossible);
+        }, eventOrOptions);
     });
-    observe = ((observer) => {
-        if (this.names.length) {
-            const stops = this.names.map(event => this.subscribe(event, message => observer({ event, message })));
-            return () => stops.forEach(stop => stop());
-        }
+    listen(event, subscriber, impossible) {
         const controller = new AbortController();
         void (async () => {
             while (!controller.signal.aborted) {
                 try {
-                    const capture = await this.wait(null, controller.signal, 86_400_000);
-                    observer({ event: capture.event, message: capture.payload });
+                    subscriber(await this.wait(event, controller.signal, 86_400_000));
                 }
                 catch (error) {
                     if (!controller.signal.aborted && timeout(error))
                         continue;
                     if (!controller.signal.aborted)
-                        controller.abort();
+                        impossible?.(failure(error));
+                    controller.abort();
                 }
             }
         })();
         return () => controller.abort();
-    });
+    }
+}
+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);
+        }
+    })();
 }
 function timeout(error) {
     return error instanceof Error && /timeout|timed out/i.test(error.message);
 }
+function failure(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}

package/dist/main.d.ts

@@ -1,5 +1,5 @@
 export { gatewayAddress } from "./address.js";
 export { Client, ClientService, Endpoint, Process, Program, Server, ServerService, System, type ProgramProcessRunEvent, type ProgramProcessRunOptions } from "./system.js";
-export { Service, type ClientServiceChannel, type ServerServiceChannel, type ServiceChannel, type ServiceKey, type ServiceLifecycleEvents } from "@phreshos/core";
+export { Service, type ServiceKey, type ServiceLifecycle, type ServiceLifecycleEvents } from "@phreshos/core";
 export { resolveHome } from "./home.js";
 export { Project, type Manifest, type PackedProject, type ProjectMode, type ProjectOptions, type ProjectRunOptions } from "./project.js";

package/dist/system.js

@@ -153,7 +153,7 @@ class ProgramRegistry extends Events {
         const waited = value;
         if (waited.event === "uninstall") {
             const payload = waited.payload;
-            return { program: programHandle(this.system, required(payload.program)), everythingRemoved: payload.everythingRemoved === true };
+            return { program: programHandle(this.system, required(payload.program)), everything: payload.everything === true };
         }
         return programHandle(this.system, required(waited.payload));
     }
@@ -171,7 +171,7 @@ class ProgramHandle extends ProgramBase {
         this.snapshot = snapshot;
         bindEvents(this, new Events(["forget", "uninstall"], (event, signal, timeout) => transport(system).control({
             capability: "program", operation: "wait", input: { program: snapshot.identity, event, timeout }
-        }, signal).then(value => value.payload)));
+        }, signal).then(value => programEntityEvent(event, value))));
         this.reference = snapshot.reference;
         this.identity = snapshot.identity;
         this.process = new ProgramProcesses(system, this);
@@ -255,7 +255,7 @@ class ProgramProcesses extends Events {
     system;
     program;
     constructor(system, program) {
-        super(["endpointStart", "endpointStop", "create", "exit"], (event, signal, timeout) => transport(system).control({
+        super(["create", "exit"], (event, signal, timeout) => transport(system).control({
             capability: "process", operation: "wait", input: { program: program.identity, event, timeout }
         }, signal).then(value => processEvent(system, value)));
         this.system = system;
@@ -328,7 +328,7 @@ class ProgramProcesses extends Events {
 class ProcessRegistry extends Events {
     system;
     constructor(system) {
-        super(["endpointStart", "endpointStop", "create", "exit"], (event, signal, timeout) => transport(system).control({
+        super(["create", "exit"], (event, signal, timeout) => transport(system).control({
             capability: "process", operation: "wait", input: { event, timeout }
         }, signal).then(value => processEvent(system, value)));
         this.system = system;
@@ -358,9 +358,9 @@ class ProcessHandle extends ProcessBase {
         super();
         this.system = system;
         this.snapshot = snapshot;
-        bindEvents(this, new Events(["endpointStart", "endpointStop", "exit"], (event, signal, timeout) => transport(system).control({
+        bindEvents(this, new Events(["exit"], (event, signal, timeout) => transport(system).control({
             capability: "process", operation: "wait", input: { process: snapshot.identity, event, timeout }
-        }, signal).then(value => processEvent(system, value))));
+        }, signal).then(exactProcessEvent)));
         this.identity = snapshot.identity;
         this.name = snapshot.name;
         this.startedAt = new Date(snapshot.startedAt);
@@ -377,6 +377,7 @@ class EndpointOperations extends Events {
     system;
     owner;
     endpoint;
+    lifecycle;
     constructor(system, owner, endpoint) {
         super([], (event, signal, timeout) => event === null
             ? transport(system).api({ capability: "endpoint", operation: "wait", process: owner.identity, endpoint, event, timeout }, signal)
@@ -386,6 +387,9 @@ class EndpointOperations extends Events {
         this.system = system;
         this.owner = owner;
         this.endpoint = endpoint;
+        this.lifecycle = new Events(["start", "stop"], (event, signal, timeout) => {
+            return waitEndpointLifecycle(system, owner, endpoint, event, signal, timeout);
+        });
     }
     process() { return Promise.resolve(this.owner); }
     async exists() {
@@ -418,12 +422,14 @@ class ServerEndpoint extends ServerBase {
     system;
     owner;
     endpoint = "server";
+    lifecycle;
     base;
     constructor(system, owner) {
         super();
         this.system = system;
         this.owner = owner;
         this.base = new EndpointOperations(system, owner, "server");
+        this.lifecycle = this.base.lifecycle;
         bindEvents(this, this.base);
     }
     process() { return this.base.process(); }
@@ -450,11 +456,13 @@ class ServerEndpoint extends ServerBase {
 }
 class ClientEndpoint extends ClientBase {
     endpoint = "client";
+    lifecycle;
     window;
     base;
     constructor(system, owner) {
         super();
         this.base = new EndpointOperations(system, owner, "client");
+        this.lifecycle = this.base.lifecycle;
         bindEvents(this, this.base);
         this.window = new SystemWindow(system, owner);
     }
@@ -497,16 +505,17 @@ class SystemWindow extends Events {
         await transport(this.system).control({ capability: "window", operation, input: { process: this.process.identity, ...input } });
     }
 }
-class ServiceBase extends Events {
+class ServiceBase {
     system;
     key;
     name;
+    lifecycle;
     constructor(system, key) {
-        super(["enable", "disable"], (event, signal, timeout) => transport(system).api({
-            capability: "service", operation: "wait", scope: "lifecycle", key, event, timeout
-        }, signal));
         this.system = system;
         this.key = key;
+        this.lifecycle = new Events(["enable", "disable"], (event, signal, timeout) => transport(system).api({
+            capability: "service", operation: "wait", scope: "lifecycle", key, event, timeout
+        }, signal));
         this.name = key.name;
     }
     async enabled() { return await transport(this.system).api({ capability: "service", operation: "enabled", key: this.key }); }
@@ -517,18 +526,35 @@ export class ServerService extends CoreServerService {
     constructor() { super(); }
 }
 class ServerServiceHandle extends ServerService {
+    system;
+    key;
     name;
-    channel;
+    lifecycle;
     base;
     constructor(system, key) {
         super();
+        this.system = system;
+        this.key = key;
         this.base = new ServiceBase(system, key);
         this.name = key.name;
-        this.channel = new ServerServiceChannelHandle(system, key);
-        Object.assign(this, eventsOf(this.base));
+        this.lifecycle = this.base.lifecycle;
+        bindEvents(this, new Events([], (event, signal, timeout) => transport(system).api({
+            capability: "service", operation: "wait", scope: "events", key, event, timeout
+        }, signal)));
     }
     enabled() { return this.base.enabled(); }
     waitReady(timeout) { return this.base.waitReady(timeout); }
+    publish = (event, payload) => {
+        void transport(this.system).api({ capability: "service", operation: "publish", key: this.key, event, payload });
+    };
+    async ask(event, payload) {
+        return await transport(this.system).api({ capability: "service", operation: "ask", key: this.key, event, payload });
+    }
+    timeout(milliseconds) {
+        return { ask: (event, payload) => transport(this.system).api({
+                capability: "service", operation: "ask", key: this.key, event, payload, timeout: milliseconds
+            }) };
+    }
 }
 /** Node-SDK handle for a Service provided by a Client Endpoint. */
 export class ClientService extends CoreClientService {
@@ -536,40 +562,20 @@ export class ClientService extends CoreClientService {
 }
 class ClientServiceHandle extends ClientService {
     name;
-    channel;
+    lifecycle;
     base;
     constructor(system, key) {
         super();
         this.base = new ServiceBase(system, key);
         this.name = key.name;
-        this.channel = new ClientServiceChannelHandle(system, key);
-        Object.assign(this, eventsOf(this.base));
+        this.lifecycle = this.base.lifecycle;
+        bindEvents(this, new Events([], (event, signal, timeout) => transport(system).api({
+            capability: "service", operation: "wait", scope: "events", key, event, timeout
+        }, signal)));
     }
     enabled() { return this.base.enabled(); }
     waitReady(timeout) { return this.base.waitReady(timeout); }
 }
-class ClientServiceChannelHandle extends Events {
-    system;
-    key;
-    constructor(system, key) {
-        super([], (event, signal, timeout) => transport(system).api({ capability: "service", operation: "wait", scope: "channel", key, event, timeout }, signal));
-        this.system = system;
-        this.key = key;
-    }
-}
-class ServerServiceChannelHandle extends ClientServiceChannelHandle {
-    async ask(event, payload) {
-        return await transport(this.system).api({ capability: "service", operation: "ask", key: this.key, event, payload });
-    }
-    timeout(milliseconds) {
-        return { ask: (event, payload) => transport(this.system).api({
-                capability: "service", operation: "ask", key: this.key, event, payload, timeout: milliseconds
-            }) };
-    }
-    publish(event, payload) {
-        void transport(this.system).api({ capability: "service", operation: "publish", key: this.key, event, payload });
-    }
-}
 async function listProcesses(system, program) {
     const processes = [];
     let offset = 0;
@@ -590,6 +596,19 @@ async function* command(system, request) {
             };
     }
 }
+async function waitEndpointLifecycle(system, owner, endpoint, event, signal, timeout = 10_000) {
+    if (event !== "start" && event !== "stop")
+        throw new Error(`An Endpoint lifecycle has no "${event}" event`);
+    await transport(system).control({
+        capability: "endpoint",
+        operation: "waitLifecycle",
+        input: { process: owner.identity, endpoint, event, timeout }
+    }, signal);
+}
+function programEntityEvent(event, value) {
+    const payload = value.payload;
+    return event === "uninstall" ? payload?.everything === true : undefined;
+}
 function processEvent(system, value) {
     const waited = value;
     const payload = waited.payload;
@@ -600,14 +619,20 @@ function processEvent(system, value) {
             code: payload.code,
             signal: payload.signal
         };
-    if ((waited.event === "endpointStart" || waited.event === "endpointStop") && payload?.processSnapshot) {
-        const process = processHandle(system, payload.processSnapshot);
-        return payload.endpoint === "client" ? process.client : process.server;
-    }
     if (payload && typeof payload.identity === "string")
         return processHandle(system, payload);
     return payload;
 }
+function exactProcessEvent(value) {
+    const payload = value.payload;
+    if (!payload)
+        return payload;
+    return {
+        status: payload.status,
+        code: payload.code,
+        signal: payload.signal
+    };
+}
 function bindEvents(target, events) {
     Object.assign(target, eventsOf(events));
 }
@@ -615,8 +640,7 @@ function eventsOf(events) {
     return {
         subscribe: events.subscribe,
         waitFor: events.waitFor,
-        events: events.events,
-        observe: events.observe
+        events: events.events
     };
 }
 function chronological(left, right) { return left.startedAt.getTime() - right.startedAt.getTime(); }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/node",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Node.js access to PhreshOS and Program projects.",
   "type": "module",
   "main": "dist/main.js",
@@ -11,7 +11,11 @@
       "default": "./dist/main.js"
     }
   },
-  "files": ["dist", "LICENSE", "README.md"],
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
   "author": "Zohayr SLILEH",
   "license": "MIT",
   "repository": {
@@ -32,7 +36,7 @@
     "prepack": "node --run build"
   },
   "dependencies": {
-    "@phreshos/core": "^0.1.25",
+    "@phreshos/core": "^0.1.27",
     "adm-zip": "^0.6.0",
     "jiti": "^2.7.0"
   },