@jskit-ai/realtime 0.1.4

package/src/server/runtime.js

@@ -0,0 +1,134 @@
+import { Server as SocketIoServer } from "socket.io";
+import { createAdapter as createSocketIoRedisAdapter } from "@socket.io/redis-adapter";
+import { createClient as createRedisClient } from "redis";
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+
+const SOCKET_IO_PATH = "/socket.io";
+const REALTIME_REDIS_URL_ENV_KEY = "REALTIME_REDIS_URL";
+
+function resolveHttpServer({ httpServer = null, fastify = null } = {}) {
+  if (httpServer && typeof httpServer === "object") {
+    return httpServer;
+  }
+  if (fastify && typeof fastify === "object" && fastify.server && typeof fastify.server === "object") {
+    return fastify.server;
+  }
+  throw new Error("createSocketIoServer requires httpServer or fastify.server.");
+}
+
+function createSocketIoServer({
+  httpServer = null,
+  fastify = null,
+  options = {},
+  ServerCtor = SocketIoServer
+} = {}) {
+  if (typeof ServerCtor !== "function") {
+    throw new Error("createSocketIoServer requires a valid socket.io Server constructor.");
+  }
+
+  const server = resolveHttpServer({
+    httpServer,
+    fastify
+  });
+  const source = options && typeof options === "object" && !Array.isArray(options) ? options : {};
+  const normalizedOptions = {
+    ...source,
+    path: SOCKET_IO_PATH
+  };
+  return new ServerCtor(server, normalizedOptions);
+}
+
+async function closeSocketIoServer(io) {
+  if (!io || typeof io.close !== "function") {
+    return;
+  }
+  await new Promise((resolve, reject) => {
+    io.close((error) => {
+      if (error) {
+        if (error.code === "ERR_SERVER_NOT_RUNNING") {
+          resolve();
+          return;
+        }
+        reject(error);
+        return;
+      }
+      resolve();
+    });
+  });
+}
+
+function resolveRealtimeRedisUrl(env = {}) {
+  const source = env && typeof env === "object" && !Array.isArray(env) ? env : {};
+  return normalizeText(source[REALTIME_REDIS_URL_ENV_KEY]);
+}
+
+async function configureSocketIoRedisAdapter(
+  io,
+  { redisUrl = "" } = {}
+) {
+  const normalizedRedisUrl = normalizeText(redisUrl);
+  if (!normalizedRedisUrl) {
+    return Object.freeze({
+      enabled: false,
+      redisUrl: "",
+      pubClient: null,
+      subClient: null
+    });
+  }
+  if (!io || typeof io.adapter !== "function") {
+    throw new Error("configureSocketIoRedisAdapter requires socket.io server instance with adapter().");
+  }
+
+  const pubClient = createRedisClient({
+    url: normalizedRedisUrl
+  });
+  const subClient = pubClient.duplicate();
+
+  try {
+    await pubClient.connect();
+    await subClient.connect();
+    io.adapter(createSocketIoRedisAdapter(pubClient, subClient));
+  } catch (error) {
+    await closeSocketIoRedisConnections({
+      pubClient,
+      subClient
+    });
+    throw error;
+  }
+
+  return Object.freeze({
+    enabled: true,
+    redisUrl: normalizedRedisUrl,
+    pubClient,
+    subClient
+  });
+}
+
+async function closeSocketIoRedisConnections({ pubClient = null, subClient = null } = {}) {
+  const connections = [subClient, pubClient];
+  for (const connection of connections) {
+    if (!connection) {
+      continue;
+    }
+    if (typeof connection.quit === "function") {
+      try {
+        await connection.quit();
+      } catch {}
+      continue;
+    }
+    if (typeof connection.disconnect === "function") {
+      try {
+        await connection.disconnect();
+      } catch {}
+    }
+  }
+}
+
+export {
+  createSocketIoServer,
+  closeSocketIoServer,
+  REALTIME_REDIS_URL_ENV_KEY,
+  resolveRealtimeRedisUrl,
+  configureSocketIoRedisAdapter,
+  closeSocketIoRedisConnections
+};

package/src/server/tokens.js

@@ -0,0 +1,7 @@
+const REALTIME_RUNTIME_SERVER_TOKEN = "runtime.realtime";
+const REALTIME_SOCKET_IO_SERVER_TOKEN = "runtime.realtime.io";
+
+export {
+  REALTIME_RUNTIME_SERVER_TOKEN,
+  REALTIME_SOCKET_IO_SERVER_TOKEN
+};

package/test/clientListeners.test.js

@@ -0,0 +1,66 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  normalizeRealtimeClientListener,
+  registerRealtimeClientListener,
+  resolveRealtimeClientListeners
+} from "../src/client/listeners.js";
+
+function createSingletonApp() {
+  const instances = new Map();
+  const singletons = new Map();
+  const tags = new Map();
+  return {
+    singleton(token, factory) {
+      singletons.set(token, factory);
+    },
+    tag(token, tagName) {
+      const normalizedTagName = String(tagName || "").trim();
+      if (!tags.has(normalizedTagName)) {
+        tags.set(normalizedTagName, new Set());
+      }
+      tags.get(normalizedTagName).add(token);
+    },
+    resolveTag(tagName) {
+      const normalizedTagName = String(tagName || "").trim();
+      const tagged = tags.get(normalizedTagName);
+      if (!tagged || tagged.size < 1) {
+        return [];
+      }
+      return [...tagged].map((token) => this.make(token));
+    },
+    make(token) {
+      if (instances.has(token)) {
+        return instances.get(token);
+      }
+      if (!singletons.has(token)) {
+        throw new Error(`Missing token: ${String(token)}`);
+      }
+      const resolved = singletons.get(token)(this);
+      instances.set(token, resolved);
+      return resolved;
+    }
+  };
+}
+
+test("normalizeRealtimeClientListener supports function shorthand", () => {
+  const listener = normalizeRealtimeClientListener(function onAnyEvent() {});
+  assert.equal(listener.listenerId, "onAnyEvent");
+  assert.equal(listener.event, "*");
+  assert.equal(typeof listener.handle, "function");
+});
+
+test("registerRealtimeClientListener + resolveRealtimeClientListeners round-trip", () => {
+  const app = createSingletonApp();
+  registerRealtimeClientListener(app, "listener.customers.changed", () => ({
+    listenerId: "listener.customers.changed",
+    event: "customers.record.changed",
+    handle() {}
+  }));
+
+  const listeners = resolveRealtimeClientListeners(app);
+  assert.equal(listeners.length, 1);
+  assert.equal(listeners[0].listenerId, "listener.customers.changed");
+  assert.equal(listeners[0].event, "customers.record.changed");
+  assert.equal(typeof listeners[0].handle, "function");
+});

package/test/clientRuntime.test.js

@@ -0,0 +1,81 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { createSocketIoClient, disconnectSocketIoClient } from "../src/client/runtime.js";
+
+test("createSocketIoClient calls connect with fixed socket path", () => {
+  const calls = [];
+  const socket = {
+    id: "socket-1"
+  };
+  const connect = (...args) => {
+    calls.push(args);
+    return socket;
+  };
+
+  const created = createSocketIoClient({
+    url: " https://example.com ",
+    options: {
+      path: "realtime",
+      withCredentials: true
+    },
+    connect
+  });
+
+  assert.equal(created, socket);
+  assert.equal(calls.length, 1);
+  assert.deepEqual(calls[0], [
+    "https://example.com",
+    {
+      path: "/socket.io",
+      withCredentials: true
+    }
+  ]);
+});
+
+test("createSocketIoClient supports url-less connection with fixed socket path", () => {
+  const calls = [];
+  const connect = (...args) => {
+    calls.push(args);
+    return {
+      id: "socket-2"
+    };
+  };
+
+  createSocketIoClient({
+    options: {
+      path: "ws"
+    },
+    connect
+  });
+
+  assert.equal(calls.length, 1);
+  assert.deepEqual(calls[0], [
+    {
+      path: "/socket.io"
+    }
+  ]);
+});
+
+test("createSocketIoClient rejects invalid connect function", () => {
+  assert.throws(
+    () => createSocketIoClient({ connect: null }),
+    /requires a valid socket\.io client connect function/
+  );
+});
+
+test("disconnectSocketIoClient calls socket.disconnect when available", () => {
+  let disconnected = false;
+  disconnectSocketIoClient({
+    disconnect() {
+      disconnected = true;
+    }
+  });
+  assert.equal(disconnected, true);
+});
+
+test("disconnectSocketIoClient is a no-op for missing socket", () => {
+  disconnectSocketIoClient(null);
+  disconnectSocketIoClient({});
+  assert.equal(true, true);
+});

package/test/entrypoints.boundary.test.js

@@ -0,0 +1,45 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import * as serverApi from "../src/server/RealtimeServiceProvider.js";
+import * as serverRuntimeApi from "../src/server/runtime.js";
+import * as clientApi from "../src/client/RealtimeClientProvider.js";
+import * as clientRuntimeApi from "../src/client/runtime.js";
+import * as clientListenerApi from "../src/client/listeners.js";
+import * as serverTokens from "../src/server/tokens.js";
+import * as clientTokens from "../src/client/tokens.js";
+
+test("server entrypoint exports provider only", () => {
+  assert.equal(typeof serverApi.RealtimeServiceProvider, "function");
+  assert.deepEqual(Object.keys(serverApi).sort(), ["RealtimeServiceProvider"]);
+});
+
+test("client entrypoint exports provider only", () => {
+  assert.equal(typeof clientApi.RealtimeClientProvider, "function");
+  assert.deepEqual(Object.keys(clientApi).sort(), ["RealtimeClientProvider"]);
+});
+
+test("token entrypoints export runtime token constants", () => {
+  assert.equal(serverTokens.REALTIME_RUNTIME_SERVER_TOKEN, "runtime.realtime");
+  assert.equal(serverTokens.REALTIME_SOCKET_IO_SERVER_TOKEN, "runtime.realtime.io");
+  assert.equal(clientTokens.REALTIME_RUNTIME_CLIENT_TOKEN, "runtime.realtime.client");
+  assert.equal(clientTokens.REALTIME_SOCKET_CLIENT_TOKEN, "runtime.realtime.client.socket");
+  assert.equal(typeof clientTokens.REALTIME_SOCKET_CLIENT_INJECTION_KEY, "symbol");
+  assert.equal(typeof clientTokens.REALTIME_CLIENT_LISTENER_TAG, "symbol");
+});
+
+test("server runtime entrypoint exports server-only helpers", () => {
+  assert.equal(typeof serverRuntimeApi.createSocketIoServer, "function");
+  assert.equal(typeof serverRuntimeApi.closeSocketIoServer, "function");
+});
+
+test("client runtime entrypoint exports client-only helpers", () => {
+  assert.equal(typeof clientRuntimeApi.createSocketIoClient, "function");
+  assert.equal(typeof clientRuntimeApi.disconnectSocketIoClient, "function");
+});
+
+test("client listeners entrypoint exports realtime listener registration helpers", () => {
+  assert.equal(typeof clientListenerApi.registerRealtimeClientListener, "function");
+  assert.equal(typeof clientListenerApi.resolveRealtimeClientListeners, "function");
+  assert.equal(typeof clientListenerApi.normalizeRealtimeClientListener, "function");
+});