@jskit-ai/realtime 0.1.4

package/src/client/composables/useRealtimeEvent.js

@@ -0,0 +1,147 @@
+import { inject, onBeforeUnmount, ref, unref, watch } from "vue";
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { REALTIME_SOCKET_CLIENT_INJECTION_KEY } from "../tokens.js";
+
+const EMPTY_REALTIME_SOCKET = Object.freeze({
+  on() {},
+  off() {},
+  onAny() {},
+  offAny() {}
+});
+
+function isRealtimeSocket(socket) {
+  return Boolean(
+    socket &&
+      typeof socket === "object" &&
+      typeof socket.on === "function" &&
+      typeof socket.off === "function"
+  );
+}
+
+function resolveEnabled(value) {
+  if (value === undefined) {
+    return true;
+  }
+  return Boolean(unref(value));
+}
+
+function resolveEventName(value) {
+  const normalized = normalizeText(unref(value));
+  return normalized || "*";
+}
+
+function useRealtimeSocket({ required = false } = {}) {
+  const socket = inject(REALTIME_SOCKET_CLIENT_INJECTION_KEY, null);
+  if (isRealtimeSocket(socket)) {
+    return socket;
+  }
+
+  if (required) {
+    throw new Error("Realtime client socket is not available in Vue injection context.");
+  }
+
+  return EMPTY_REALTIME_SOCKET;
+}
+
+function useRealtimeEvent({
+  event = "*",
+  enabled = true,
+  matches = null,
+  onEvent
+} = {}) {
+  if (typeof onEvent !== "function") {
+    throw new TypeError("useRealtimeEvent requires onEvent().");
+  }
+
+  const socket = useRealtimeSocket({ required: false });
+  const active = ref(false);
+  let release = null;
+
+  function detach() {
+    if (typeof release === "function") {
+      try {
+        release();
+      } catch {}
+    }
+    release = null;
+    active.value = false;
+  }
+
+  function runHandler(eventName, payload) {
+    const context = Object.freeze({
+      event: eventName,
+      payload,
+      socket
+    });
+
+    if (typeof matches === "function" && matches(context) !== true) {
+      return;
+    }
+
+    Promise.resolve(onEvent(context)).catch((error) => {
+      console.error(
+        {
+          event: eventName,
+          error: String(error?.message || error || "unknown error")
+        },
+        "Realtime event handler failed."
+      );
+    });
+  }
+
+  function attach() {
+    detach();
+
+    if (socket === EMPTY_REALTIME_SOCKET) {
+      return;
+    }
+    if (!resolveEnabled(enabled)) {
+      return;
+    }
+
+    const eventName = resolveEventName(event);
+    if (eventName === "*") {
+      if (typeof socket.onAny !== "function") {
+        return;
+      }
+      const onAny = (nextEventName, payload) => runHandler(nextEventName, payload);
+      socket.onAny(onAny);
+      release = () => {
+        if (typeof socket.offAny === "function") {
+          socket.offAny(onAny);
+        }
+      };
+      active.value = true;
+      return;
+    }
+
+    const onEventMessage = (payload) => runHandler(eventName, payload);
+    socket.on(eventName, onEventMessage);
+    release = () => {
+      socket.off(eventName, onEventMessage);
+    };
+    active.value = true;
+  }
+
+  watch(
+    () => [resolveEnabled(enabled), resolveEventName(event)],
+    () => {
+      attach();
+    },
+    { immediate: true }
+  );
+
+  onBeforeUnmount(() => {
+    detach();
+  });
+
+  return Object.freeze({
+    active
+  });
+}
+
+export {
+  EMPTY_REALTIME_SOCKET,
+  useRealtimeSocket,
+  useRealtimeEvent
+};

package/src/client/listeners.js

@@ -0,0 +1,69 @@
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { REALTIME_CLIENT_LISTENER_TAG } from "./tokens.js";
+
+function normalizeListenerEntries(value) {
+  const queue = Array.isArray(value) ? [...value] : [value];
+  const listeners = [];
+
+  while (queue.length > 0) {
+    const entry = queue.shift();
+    if (Array.isArray(entry)) {
+      queue.push(...entry);
+      continue;
+    }
+    if (entry == null) {
+      continue;
+    }
+    listeners.push(entry);
+  }
+
+  return listeners;
+}
+
+function normalizeRealtimeClientListener(entry) {
+  if (typeof entry === "function") {
+    return Object.freeze({
+      listenerId: String(entry.name || "anonymous"),
+      event: "*",
+      matches: null,
+      handle: entry
+    });
+  }
+
+  if (entry && typeof entry === "object" && typeof entry.handle === "function") {
+    const event = normalizeText(entry.event) || "*";
+    return Object.freeze({
+      ...entry,
+      listenerId: String(entry.listenerId || "anonymous"),
+      event,
+      matches: typeof entry.matches === "function" ? entry.matches : null
+    });
+  }
+
+  return null;
+}
+
+function registerRealtimeClientListener(app, token, factory) {
+  if (!app || typeof app.singleton !== "function" || typeof app.tag !== "function") {
+    throw new Error("registerRealtimeClientListener requires application singleton()/tag().");
+  }
+
+  app.singleton(token, factory);
+  app.tag(token, REALTIME_CLIENT_LISTENER_TAG);
+}
+
+function resolveRealtimeClientListeners(scope) {
+  if (!scope || typeof scope.resolveTag !== "function") {
+    return [];
+  }
+
+  return normalizeListenerEntries(scope.resolveTag(REALTIME_CLIENT_LISTENER_TAG))
+    .map((entry) => normalizeRealtimeClientListener(entry))
+    .filter(Boolean);
+}
+
+export {
+  normalizeRealtimeClientListener,
+  registerRealtimeClientListener,
+  resolveRealtimeClientListeners
+};

package/src/client/runtime.js

@@ -0,0 +1,37 @@
+import { io as connectSocketIoClient } from "socket.io-client";
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+
+const SOCKET_IO_PATH = "/socket.io";
+
+function createSocketIoClient({
+  url = "",
+  options = {},
+  connect = connectSocketIoClient
+} = {}) {
+  if (typeof connect !== "function") {
+    throw new Error("createSocketIoClient requires a valid socket.io client connect function.");
+  }
+
+  const normalizedUrl = normalizeText(url);
+  const source = options && typeof options === "object" && !Array.isArray(options) ? options : {};
+  const normalizedOptions = {
+    ...source,
+    path: SOCKET_IO_PATH
+  };
+  if (normalizedUrl) {
+    return connect(normalizedUrl, normalizedOptions);
+  }
+  return connect(normalizedOptions);
+}
+
+function disconnectSocketIoClient(socket) {
+  if (!socket || typeof socket.disconnect !== "function") {
+    return;
+  }
+  socket.disconnect();
+}
+
+export {
+  createSocketIoClient,
+  disconnectSocketIoClient
+};

package/src/client/tokens.js

@@ -0,0 +1,11 @@
+const REALTIME_RUNTIME_CLIENT_TOKEN = "runtime.realtime.client";
+const REALTIME_SOCKET_CLIENT_TOKEN = "runtime.realtime.client.socket";
+const REALTIME_SOCKET_CLIENT_INJECTION_KEY = Symbol.for("jskit.realtime.runtime.client.socket");
+const REALTIME_CLIENT_LISTENER_TAG = Symbol.for("jskit.runtime.realtime.client.listeners");
+
+export {
+  REALTIME_RUNTIME_CLIENT_TOKEN,
+  REALTIME_SOCKET_CLIENT_TOKEN,
+  REALTIME_SOCKET_CLIENT_INJECTION_KEY,
+  REALTIME_CLIENT_LISTENER_TAG
+};