@jskit-ai/realtime 0.1.156 → 0.1.158

package/package.json

@@ -1,22 +1,21 @@
 {
   "name": "@jskit-ai/realtime",
-  "version": "0.1.156",
+  "version": "0.1.158",
   "type": "module",
   "scripts": {
     "test": "node --test"
   },
   "exports": {
-    "./server/RealtimeServiceProvider": "./src/server/RealtimeServiceProvider.js",
+    "./server/RealtimeProvider": "./src/server/RealtimeProvider.js",
     "./server/runtime": "./src/server/runtime.js",
     "./client": "./src/client/RealtimeClientProvider.js",
     "./client/RealtimeClientProvider": "./src/client/RealtimeClientProvider.js",
-    "./client/listeners": "./src/client/listeners.js",
     "./client/composables/useRealtimeEvent": "./src/client/composables/useRealtimeEvent.js",
     "./client/runtime": "./src/client/runtime.js"
   },
   "dependencies": {
-    "@jskit-ai/kernel": "0.1.159",
-    "@jskit-ai/shell-web": "0.1.163",
+    "@jskit-ai/kernel": "0.1.161",
+    "@jskit-ai/shell-web": "0.1.165",
     "@socket.io/redis-adapter": "^8.3.0",
     "redis": "^5.8.2",
     "socket.io": "^4.8.3",
@@ -28,30 +27,25 @@
   "description": "Thin, generic realtime runtime wrappers for socket.io server and client.",
   "jskit": {
     "kind": "runtime",
-    "options": {
-      "realtime-redis-url": {
-        "required": true,
-        "allowEmpty": true,
-        "values": [],
-        "defaultValue": "",
-        "promptLabel": "Realtime Redis URL",
-        "promptHint": "Leave empty to use in-memory socket adapter."
-      }
-    },
     "capabilities": {
       "provides": [
         "runtime.realtime",
         "runtime.realtime.client"
       ],
-      "requires": []
+      "requires": [
+        "runtime.config",
+        "runtime.env",
+        "runtime.events",
+        "runtime.fastify",
+        "runtime.logger"
+      ]
     },
     "runtime": {
       "server": {
-        "providerEntrypoint": "src/server/RealtimeServiceProvider.js",
         "providers": [
           {
-            "entrypoint": "src/server/RealtimeServiceProvider.js",
-            "export": "RealtimeServiceProvider"
+            "entrypoint": "src/server/RealtimeProvider.js",
+            "export": "RealtimeProvider"
           }
         ]
       },
@@ -65,33 +59,34 @@
       }
     },
     "metadata": {
+      "client": {
+        "optimizeDeps": {
+          "include": [
+            "socket.io-client"
+          ]
+        }
+      },
       "apiSummary": {
         "surfaces": [
           {
             "subpath": "./server",
-            "summary": "Exports RealtimeServiceProvider only."
+            "summary": "Exports the explicit RealtimeProvider capability provider."
           },
           {
             "subpath": "./client",
             "summary": "Exports RealtimeClientProvider only."
           },
-          {
-            "subpath": "./client/listeners",
-            "summary": "Exports client listener registration helpers for provider-level realtime subscriptions."
-          },
           {
             "subpath": "./client/composables/*",
             "summary": "Exports component-level realtime socket composables."
           }
         ],
-        "containerTokens": {
+        "capabilities": {
           "server": [
-            "runtime.realtime",
-            "runtime.realtime.io"
+            "runtime.realtime"
           ],
           "client": [
-            "runtime.realtime.client",
-            "runtime.realtime.client.socket",
+            "client.realtime",
             "realtime.web.connection.indicator"
           ]
         }
@@ -109,7 +104,7 @@
               ],
               "order": 950,
               "componentToken": "realtime.web.connection.indicator",
-              "source": "mutations.text#realtime-placement-indicator"
+              "source": "patterns/realtime-application/example/src/placement.js"
             }
           ]
         }
@@ -122,45 +117,6 @@
           "ws": true
         }
       }
-    },
-    "mutations": {
-      "dependencies": {
-        "runtime": {
-          "@jskit-ai/kernel": "0.1.159",
-          "@jskit-ai/shell-web": "0.1.163",
-          "@socket.io/redis-adapter": "^8.3.0",
-          "redis": "^5.8.2",
-          "socket.io": "^4.8.3",
-          "socket.io-client": "^4.8.3"
-        },
-        "dev": {}
-      },
-      "packageJson": {
-        "scripts": {}
-      },
-      "procfile": {},
-      "files": [],
-      "text": [
-        {
-          "file": ".env",
-          "op": "upsert-env",
-          "key": "REALTIME_REDIS_URL",
-          "value": "${option:realtime-redis-url}",
-          "reason": "Configure optional Redis backplane URL for realtime socket adapter.",
-          "category": "runtime-config",
-          "id": "realtime-redis-url"
-        },
-        {
-          "op": "append-text",
-          "file": "src/placement.js",
-          "position": "bottom",
-          "skipIfContains": "id: \"realtime.connection.indicator\"",
-          "value": "\naddPlacement({\n  id: \"realtime.connection.indicator\",\n  target: \"shell.status\",\n  kind: \"component\",\n  surfaces: [\"*\"],\n  order: 950,\n  componentToken: \"realtime.web.connection.indicator\"\n});\n",
-          "reason": "Append realtime connection indicator placement into app-owned placement registry.",
-          "category": "realtime-web",
-          "id": "realtime-placement-indicator"
-        }
-      ]
     }
   }
 }

package/patterns/realtime-application/PATTERN.md

@@ -0,0 +1,69 @@
+---
+id: realtime/realtime-application
+title: Realtime application
+summary: Add JSKIT realtime events with an optional Redis backplane and an explicit shell status contribution.
+keywords: redis, realtime, socket.io, sockets, status, websocket
+requires: @jskit-ai/realtime, @jskit-ai/shell-web
+---
+
+# Realtime application
+
+## Use when
+
+Use this pattern when the product needs server-to-client events or live query
+refresh. Install the realtime package normally, then add only the product's
+listeners and desired shell contribution.
+
+## Do not use when
+
+Do not add realtime merely to poll less often, or before event ownership and
+delivery semantics are clear. A single-process application does not need Redis.
+
+## Product decisions
+
+Decide which events are public contracts, their scopes and payloads, reconnect
+behavior, whether a connection indicator belongs in the UI, and whether the
+deployment needs a Redis backplane.
+
+## Invariants
+
+- Empty `REALTIME_REDIS_URL` means the in-process adapter.
+- Redis credentials stay outside Git.
+- Listeners are registered through the public provider seams.
+- The status indicator is an explicit app placement, not a source mutation.
+- Event payloads do not become an undocumented second API.
+
+## Framework APIs
+
+Server features declare their successful domain events on their actions. The
+installed `RealtimeProvider` delivers only events with an explicit realtime
+name and audience. Client features use `RealtimeClientProvider` and the public
+listener registration helpers from `@jskit-ai/realtime`. Use the normal shell
+placement registry for the optional status component.
+
+## Example files
+
+`example/package.json` declares realtime and shell runtime packages.
+`example/.env.example` documents the optional Redis input.
+`example/src/placement.js` adds the standard connection indicator explicitly.
+
+## Variation points
+
+Omit the placement when the product does not need a visible connection state.
+Change event listeners, Redis provisioning, and client invalidation behavior to
+match the product. Keep transport retry policy in the realtime runtime.
+
+## Verification
+
+- Test in-process delivery without Redis.
+- When Redis is selected, test delivery across two server processes.
+- Disconnect and reconnect a browser and verify recovery behavior.
+- Confirm the status contribution renders in compact and expanded shells.
+
+## Avoid
+
+- prompting for optional Redis configuration during package installation
+- appending source into placement files
+- leaking Redis values to client config
+- generic “data changed” payloads with no scope
+- receipts, provenance, or mutation history

package/patterns/realtime-application/example/.env.example

@@ -0,0 +1 @@
+REALTIME_REDIS_URL=

package/patterns/realtime-application/example/package.json

@@ -0,0 +1,8 @@
+{
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@jskit-ai/realtime": "0.1.158",
+    "@jskit-ai/shell-web": "0.1.165"
+  }
+}

package/patterns/realtime-application/example/src/placement.js

@@ -0,0 +1,17 @@
+import { createPlacementRegistry } from "@jskit-ai/shell-web/client/placement";
+
+const registry = createPlacementRegistry();
+const { addPlacement } = registry;
+
+addPlacement({
+  id: "realtime.connection.indicator",
+  target: "shell.status",
+  kind: "component",
+  surfaces: ["*"],
+  order: 950,
+  componentToken: "realtime.web.connection.indicator"
+});
+
+export default function getPlacements() {
+  return registry.build();
+}

package/src/client/RealtimeClientProvider.js

@@ -1,37 +1,22 @@
-import { createSocketIoClient, disconnectSocketIoClient } from "./runtime.js";
+import { defineProvider } from "@jskit-ai/kernel/shared/capabilities";
 import { normalizeObject, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
-import { createProviderLogger as createSharedProviderLogger } from "@jskit-ai/kernel/shared/support/providerLogger";
+import { createProviderLogger } from "@jskit-ai/kernel/shared/support/providerLogger";
 import { getClientAppConfig, resolveClientBootstrapDebugEnabled, resolveMobileConfig } from "@jskit-ai/kernel/client";
 import RealtimeConnectionIndicator from "./components/RealtimeConnectionIndicator.js";
-import { resolveRealtimeClientListeners } from "./listeners.js";
+import { createSocketIoClient, disconnectSocketIoClient } from "./runtime.js";
 
 const REALTIME_RUNTIME_CLIENT_API = Object.freeze({
   createSocketIoClient,
   disconnectSocketIoClient
 });
 
-function isCapacitorRuntimeAvailable(app) {
-  if (!app || typeof app.has !== "function" || typeof app.make !== "function") {
-    return false;
-  }
-  if (app.has("mobile.capacitor.adapter.client") !== true) {
-    return false;
-  }
-
-  const adapter = app.make("mobile.capacitor.adapter.client");
-  return adapter?.available === true;
-}
-
-function resolveRealtimeClientConfig(app) {
+function resolveRealtimeClientConfig({ env = {}, mobile = null } = {}) {
   const appConfig = normalizeObject(getClientAppConfig());
-  const env = app && typeof app.has === "function" && app.has("jskit.client.env") ? normalizeObject(app.make("jskit.client.env")) : {};
   const realtime = normalizeObject(appConfig.realtime);
   const realtimeClient = normalizeObject(appConfig.realtimeClient);
-  const mobileConfig = resolveMobileConfig({
-    mobile: normalizeObject(appConfig.mobile)
-  });
+  const mobileConfig = resolveMobileConfig({ mobile: normalizeObject(appConfig.mobile) });
   const url = normalizeText(
-    realtimeClient.url || (mobileConfig.enabled === true && isCapacitorRuntimeAvailable(app) ? mobileConfig.apiBaseUrl : "")
+    realtimeClient.url || (mobileConfig.enabled === true && mobile?.adapter?.available === true ? mobileConfig.apiBaseUrl : "")
   );
   const options = normalizeObject(realtimeClient.options);
   const explicitDebugEnabled =
@@ -40,7 +25,7 @@ function resolveRealtimeClientConfig(app) {
       : typeof realtime.debug === "boolean"
         ? realtime.debug
         : undefined;
-  const hasRealtimeDebugEnvOverride = Object.hasOwn(env, "VITE_REALTIME_DEBUG");
+  const hasRealtimeDebugEnvOverride = Object.hasOwn(normalizeObject(env), "VITE_REALTIME_DEBUG");
   const debugEnabled = hasRealtimeDebugEnvOverride
     ? resolveClientBootstrapDebugEnabled({
         env,
@@ -53,221 +38,114 @@ function resolveRealtimeClientConfig(app) {
         debugEnvKey: "VITE_REALTIME_DEBUG"
       });
 
-  return Object.freeze({
-    url,
-    options,
-    debugEnabled
-  });
+  return Object.freeze({ url, options, debugEnabled });
 }
 
-class RealtimeClientProvider {
-  static id = "runtime.realtime.client";
-
-  register(app) {
-    if (!app || typeof app.singleton !== "function") {
-      throw new Error("RealtimeClientProvider requires application singleton().");
-    }
-
-    app.singleton("runtime.realtime.client", () => REALTIME_RUNTIME_CLIENT_API);
-    app.singleton("realtime.web.connection.indicator", () => RealtimeConnectionIndicator);
-    app.singleton("runtime.realtime.client.socket", (scope) => {
-      const realtimeRuntime = scope.make("runtime.realtime.client");
-      const realtimeClientConfig = resolveRealtimeClientConfig(scope);
-      return realtimeRuntime.createSocketIoClient({
-        url: realtimeClientConfig.url,
-        options: realtimeClientConfig.options
-      });
-    });
-  }
+function createRealtimeClient({ config, loggerInput } = {}) {
+  const logger = createProviderLogger(loggerInput, {
+    debugEnabled: config.debugEnabled
+  });
+  const socket = createSocketIoClient({
+    url: config.url,
+    options: config.options
+  });
+  const detach = [];
+  let initialized = false;
 
-  boot(app) {
-    if (!app || typeof app.make !== "function") {
-      throw new Error("RealtimeClientProvider requires application make().");
+  function initialize(vueApp = null) {
+    if (initialized) {
+      return;
     }
-
-    const realtimeClientConfig = resolveRealtimeClientConfig(app);
-    const logger = createSharedProviderLogger(app, {
-      debugEnabled: realtimeClientConfig.debugEnabled
-    });
-    const socket = app.make("runtime.realtime.client.socket");
-    const listeners = resolveRealtimeClientListeners(app);
-    const detach = [];
-
-    logger.debug(
-      {
-        providerId: RealtimeClientProvider.id,
-        listenerCount: listeners.length,
-        listeners: listeners.map((listener) => ({
-          listenerId: listener.listenerId,
-          event: listener.event
-        }))
-      },
-      "Realtime client booted listeners."
-    );
+    initialized = true;
 
     if (typeof socket.on === "function") {
-      const onConnect = () => {
-        logger.debug(
-          {
-            providerId: RealtimeClientProvider.id,
-            socketConnected: true
-          },
-          "Realtime client socket connected."
-        );
-      };
-      const onDisconnect = (reason) => {
+      const onConnect = () => logger.debug({ socketConnected: true }, "Realtime client socket connected.");
+      const onDisconnect = (reason) =>
         logger.debug(
-          {
-            providerId: RealtimeClientProvider.id,
-            socketConnected: false,
-            reason: String(reason || "")
-          },
+          { socketConnected: false, reason: String(reason || "") },
           "Realtime client socket disconnected."
         );
-      };
-      const onConnectError = (error) => {
+      const onConnectError = (error) =>
         logger.warn(
-          {
-            providerId: RealtimeClientProvider.id,
-            error: String(error?.message || error || "unknown error")
-          },
+          { error: String(error?.message || error || "unknown error") },
           "Realtime client socket connect error."
         );
-      };
 
       socket.on("connect", onConnect);
       socket.on("disconnect", onDisconnect);
       socket.on("connect_error", onConnectError);
       detach.push(() => {
-        if (typeof socket.off === "function") {
-          socket.off("connect", onConnect);
-          socket.off("disconnect", onDisconnect);
-          socket.off("connect_error", onConnectError);
-        }
+        socket.off?.("connect", onConnect);
+        socket.off?.("disconnect", onDisconnect);
+        socket.off?.("connect_error", onConnectError);
       });
 
-      if (realtimeClientConfig.debugEnabled === true && typeof socket.onAny === "function") {
-        const onAnyDebug = (eventName, payload) => {
+      if (config.debugEnabled === true && typeof socket.onAny === "function") {
+        const onAny = (eventName, payload) =>
           logger.debug(
             {
-              providerId: RealtimeClientProvider.id,
               event: String(eventName || ""),
               payloadScope: payload?.scope || null,
               payloadEntityId: payload?.entityId || null
             },
             "Realtime client received socket event."
           );
-        };
-        socket.onAny(onAnyDebug);
-        detach.push(() => {
-          if (typeof socket.offAny === "function") {
-            socket.offAny(onAnyDebug);
-          }
-        });
-      }
-    }
-
-    for (const listener of listeners) {
-      const invoke = (eventName, payload) => {
-        const context = Object.freeze({
-          event: eventName,
-          payload,
-          socket,
-          app
-        });
-
-        if (listener.matches && listener.matches(context) !== true) {
-          logger.debug(
-            {
-              listenerId: listener.listenerId,
-              event: eventName
-            },
-            "Realtime client listener skipped event by matches()."
-          );
-          return;
-        }
-
-        logger.debug(
-          {
-            listenerId: listener.listenerId,
-            event: eventName,
-            payloadScope: payload?.scope || null,
-            payloadEntityId: payload?.entityId || null
-          },
-          "Realtime client listener handling event."
-        );
-
-        Promise.resolve(listener.handle(context)).catch((error) => {
-          logger.error(
-            {
-              listenerId: listener.listenerId,
-              event: eventName,
-              error: String(error?.message || error || "unknown error")
-            },
-            "Realtime client listener failed."
-          );
-        });
-      };
-
-      if (listener.event === "*") {
-        if (typeof socket.onAny === "function") {
-          const onAny = (eventName, payload) => invoke(eventName, payload);
-          socket.onAny(onAny);
-          detach.push(() => {
-            if (typeof socket.offAny === "function") {
-              socket.offAny(onAny);
-            }
-          });
-        }
-        continue;
+        socket.onAny(onAny);
+        detach.push(() => socket.offAny?.(onAny));
       }
-
-      if (typeof socket.on === "function") {
-        const onEvent = (payload) => invoke(listener.event, payload);
-        socket.on(listener.event, onEvent);
-        detach.push(() => {
-          if (typeof socket.off === "function") {
-            socket.off(listener.event, onEvent);
-          }
-        });
-      }
-    }
-
-    this.socket = socket;
-    this.detach = detach;
-
-    if (!app.has("jskit.client.vue.app")) {
-      return;
     }
 
-    const vueApp = app.make("jskit.client.vue.app");
-    if (!vueApp || typeof vueApp.provide !== "function") {
-      return;
-    }
-    vueApp.provide("jskit.realtime.runtime.client.socket", socket);
+    vueApp?.provide?.("jskit.realtime.runtime.client.socket", socket);
   }
 
-  shutdown(app) {
-    if (Array.isArray(this.detach)) {
-      for (const release of this.detach) {
-        if (typeof release === "function") {
-          try {
-            release();
-          } catch {}
-        }
-      }
+  function dispose() {
+    for (const release of detach.splice(0, detach.length)) {
+      try {
+        release();
+      } catch {}
     }
-    this.detach = [];
+    disconnectSocketIoClient(socket);
+    initialized = false;
+  }
 
-    if (!this.socket) {
-      return;
-    }
+  return Object.freeze({
+    ...REALTIME_RUNTIME_CLIENT_API,
+    config,
+    dispose,
+    initialize,
+    socket
+  });
+}
 
-    const runtimeApi =
-      app && typeof app.make === "function" ? app.make("runtime.realtime.client") : REALTIME_RUNTIME_CLIENT_API;
-    runtimeApi.disconnectSocketIoClient(this.socket);
-    this.socket = null;
+const RealtimeClientProvider = defineProvider({
+  id: "runtime.realtime.client",
+  requires: {
+    components: "client.components",
+    env: "client.env",
+    logger: "client.logger",
+    vueApp: "client.vue"
+  },
+  optional: {
+    mobile: "client.mobile"
+  },
+  provides: {
+    realtime: "client.realtime"
+  },
+  setup({ components, env, logger, mobile }) {
+    components.register("realtime.web.connection.indicator", RealtimeConnectionIndicator);
+    return {
+      realtime: createRealtimeClient({
+        config: resolveRealtimeClientConfig({ env, mobile }),
+        loggerInput: logger
+      })
+    };
+  },
+  boot({ vueApp }, { outputs }) {
+    outputs.realtime.initialize(vueApp);
+  },
+  shutdown(_dependencies, { outputs }) {
+    outputs.realtime.dispose();
   }
-}
+});
 
-export { RealtimeClientProvider };
+export { RealtimeClientProvider, resolveRealtimeClientConfig };