@phreshos/client 0.1.51 → 0.1.53

package/dist/client-memory.d.ts

@@ -0,0 +1,3 @@
+import type { ClientMemory, HandleAddress } from "@phreshos/core";
+/** The System, not this browser document, owns the values and ordering. */
+export default function clientMemory(target: HandleAddress | null): ClientMemory;

package/dist/client-memory.js

@@ -0,0 +1,57 @@
+import wire from "./wire.js";
+/** The System, not this browser document, owns the values and ordering. */
+export default function clientMemory(target) {
+    const snapshots = new Map();
+    const address = () => target ? Promise.resolve(target) : wire.identity().then(({ process, reference }) => ({ identity: process, reference }));
+    const ask = async (operation, key, value, expected) => {
+        const [result] = await wire.request(["client-memory", await address(), operation, key, value, expected]);
+        return result;
+    };
+    return {
+        async get(key) {
+            const snapshot = await ask("snapshot", key);
+            snapshots.set(key, snapshot);
+            return snapshot.value;
+        },
+        async set(key, value) { snapshots.set(key, await ask("set", key, value)); },
+        async update(key, updater) {
+            let snapshot = snapshots.get(key) ?? await ask("snapshot", key);
+            for (;;) {
+                const next = updater(snapshot.value);
+                const result = await ask("compareAndSet", key, next, snapshot);
+                snapshots.set(key, result.snapshot);
+                if (result.changed)
+                    return result.snapshot.value;
+                if (result.snapshot.run !== snapshot.run)
+                    throw new Error("The Client run changed during the update");
+                snapshot = result.snapshot;
+            }
+        },
+        async delete(key) { const deleted = await ask("delete", key); snapshots.delete(key); return deleted; },
+        async entries() { return await ask("entries"); },
+        subscribe(key, subscriber) {
+            let active = true;
+            let stop;
+            let latest;
+            void address().then(value => {
+                if (!active)
+                    return;
+                // Register first; an older snapshot response cannot overtake a newer event.
+                stop = wire.on("host-client-memory", key, (identity, snapshot) => {
+                    if (identity !== value.identity || !active)
+                        return;
+                    deliver(snapshot);
+                }, value.identity);
+                void ask("snapshot", key).then(snapshot => deliver(snapshot)).catch(() => undefined);
+            }).catch(() => undefined);
+            const deliver = (snapshot) => {
+                if (!active || (latest && (latest.run !== snapshot.run || latest.revision > snapshot.revision)))
+                    return;
+                latest = snapshot;
+                snapshots.set(key, snapshot);
+                subscriber(snapshot.value);
+            };
+            return () => { active = false; stop?.(); };
+        }
+    };
+}

package/dist/context.js

@@ -2,6 +2,7 @@ import Deadline from "./deadline.js";
 import { ClientEndpoint, ServerEndpoint, ServerTrafficHandle, TrafficHandle, endpointLifecycle, endpointEvents, process, program, visibleEndpoint, presentation, window as windowHandle, } from "./domain.js";
 import Events from "./events.js";
 import wire from "./wire.js";
+import clientMemory from "./client-memory.js";
 import { contextPermissions } from "./permissions.js";
 class ContextServerHandle extends ServerEndpoint {
     owner;
@@ -68,6 +69,7 @@ class ContextClientHandle extends ClientEndpoint {
     traffic = new TrafficHandle(null, "client");
     lifecycle = endpointLifecycle(currentAddress, "client");
     window = windowHandle(currentAddress);
+    memory = clientMemory(null);
     constructor(owner) {
         super();
         this.owner = owner;
@@ -95,6 +97,7 @@ contextClient = new ContextClientHandle(owner);
 class ClientContext extends Events {
     server = contextServer;
     window = contextClient.window;
+    memory = contextClient.memory;
     presentation = presentation(currentAddress);
     permissions = contextPermissions();
     constructor() {

package/dist/domain.js

@@ -6,6 +6,7 @@ import { area, programLogs, sql, store } from "./storage.js";
 import startup from "./startup.js";
 import { programPermissions } from "./permissions.js";
 import wire from "./wire.js";
+import clientMemory from "./client-memory.js";
 const handles = new HandleRegistry();
 class ProgramHandle extends CoreProgram {
     subscribe;
@@ -79,10 +80,10 @@ class ProgramHandle extends CoreProgram {
         const answer = await wire.request(["program-processes", this.address]);
         return answer[0].map(record => process(record));
     }
-    async firstProcess() {
+    async oldestProcess() {
         return chronological(await this.processes())[0] ?? null;
     }
-    async lastProcess() {
+    async newestProcess() {
         return chronological(await this.processes()).at(-1) ?? null;
     }
     async findProcess(identityOrName) {
@@ -285,12 +286,14 @@ class ClientEndpointHandle extends CoreClientEndpoint {
     traffic;
     lifecycle;
     window;
+    memory;
     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);
+        this.memory = clientMemory(owner.address);
         const events = endpointEvents(owner.address, "client");
         this.subscribe = events.subscribe;
         this.wait = events.wait;

package/dist/storage.js

@@ -200,16 +200,67 @@ function parseEntry(value) {
     return { kind: entry.kind, path: entry.path };
 }
 export function store(program) {
+    const snapshots = new Map();
+    const local = new Set();
+    const notify = (key, snapshot) => { for (const listener of local)
+        listener(key, snapshot); };
     async function ask(operation, ...values) {
         const answer = await wire.request(["store", program, operation, ...values]);
         return answer[0];
     }
     return {
         get: (key) => ask("get", key),
-        set: (key, value, ttl) => ask("set", key, value, ttl),
-        delete: (key) => ask("delete", key),
+        async set(key, value, ttl) {
+            const result = await ask("set", key, value, ttl);
+            snapshots.delete(key);
+            return result;
+        },
+        async getOrSet(key, initial) {
+            // The response carries the authoritative revision so an older initial event cannot win hydration.
+            const snapshot = await ask("getOrSet", key, initial);
+            notify(key, snapshot);
+            return snapshot.value;
+        },
+        async update(key, updater) {
+            let snapshot = snapshots.get(key) ?? await ask("snapshot", key);
+            for (;;) {
+                const next = updater(snapshot.value);
+                const result = await ask("compareAndSet", key, next, snapshot);
+                snapshots.set(key, result.snapshot);
+                notify(key, result.snapshot);
+                if (result.changed)
+                    return result.snapshot.value;
+                snapshot = result.snapshot;
+            }
+        },
+        async delete(key) {
+            const result = await ask("delete", key);
+            for (const name of Array.isArray(key) ? key : [key])
+                snapshots.delete(name);
+            return result;
+        },
         has: (key) => ask("has", key),
-        clear: () => ask("clear")
+        async clear() { await ask("clear"); snapshots.clear(); },
+        subscribe(key, subscriber) {
+            let active = true;
+            let latest;
+            const deliver = (snapshot) => {
+                if (!active || (latest?.run === snapshot.run && latest.revision >= snapshot.revision))
+                    return;
+                latest = snapshot;
+                snapshots.set(key, snapshot);
+                subscriber(snapshot.value);
+            };
+            const stop = wire.on("program-host", "storeChange", (reference, changedKey, snapshot) => {
+                if (reference === program.reference && changedKey === key)
+                    deliver(snapshot);
+            }, program.reference);
+            const localListener = (changedKey, snapshot) => { if (changedKey === key)
+                deliver(snapshot); };
+            local.add(localListener);
+            void ask("snapshot", key).then(deliver).catch(() => undefined);
+            return () => { active = false; local.delete(localListener); stop(); };
+        }
     };
 }
 export function sql(kind, program) {

package/dist/system.js

@@ -1,4 +1,4 @@
-import { parseShellEvent, parseAuthenticationRequirements, parseAuthenticationState, parsePermissions, parseSessionEndSnapshot, execute as executeRequest } from "@phreshos/core";
+import { parseShellEvent, parseAuthenticationRequirements, parseAuthenticationState, parsePermissions, parseSessionEndSnapshot, parseSystemProgramListOptions, parseSystemServiceListOptions, execute as executeRequest } from "@phreshos/core";
 import ClientAppearance from "./appearance.js";
 import wire from "./wire.js";
 import { prepareService } from "./service.js";
@@ -36,12 +36,8 @@ class SystemServiceHandle extends Events {
                 observer(event, prepareService(values[1]));
         }));
     }
-    async list() {
-        const [addresses] = await wire.request(["host-service-list"]);
-        return addresses.map(address => prepareService(address));
-    }
-    async search(name) {
-        const [addresses] = await wire.request(["host-service-search", name]);
+    async list(options = {}) {
+        const [addresses] = await wire.request(["host-service-list", parseSystemServiceListOptions(options)]);
         return addresses.map(address => prepareService(address));
     }
     prepare(address) { return prepareService(address); }
@@ -53,8 +49,8 @@ class SystemProgramHandle extends Events {
                 observer(event, systemProgramEvent(event, values));
         }));
     }
-    async list(onlyInstalled = false) {
-        const answer = await wire.request(["host-program-list", onlyInstalled]);
+    async list(options = {}) {
+        const answer = await wire.request(["host-program-list", parseSystemProgramListOptions(options)]);
         return answer[0].map(program);
     }
     async find(identity) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/client",
-  "version": "0.1.51",
+  "version": "0.1.53",
   "description": "The SDK used by a Program's client endpoint.",
   "type": "module",
   "main": "dist/main.js",
@@ -46,13 +46,13 @@
     "test": "vitest run --project default"
   },
   "peerDependencies": {
-    "@phreshos/core": "^0.1.60"
+    "@phreshos/core": "^0.1.63"
   },
   "dependencies": {
     "@the-link/messagepack": "^0.1.0"
   },
   "devDependencies": {
-        "@phreshos/core": "^0.1.60",
+    "@phreshos/core": "^0.1.63",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }