@connexis/react 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Connexis Realtime Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.mts

@@ -0,0 +1,36 @@
+import React from 'react';
+import { RealtimeClient, SubscribeOptions, ConnectionState, Metrics } from '@connexis/core';
+
+interface RealtimeProviderProps {
+    client: RealtimeClient;
+    children: React.ReactNode;
+}
+/**
+ * Context Provider enabling access to the Realtime Client across the React component tree.
+ */
+declare const RealtimeProvider: React.FC<RealtimeProviderProps>;
+/**
+ * Accesses the raw RealtimeClient instance from Context.
+ */
+declare const useRealtime: () => RealtimeClient;
+/**
+ * Hook to subscribe to connection state and performance metrics.
+ */
+declare const useConnection: () => {
+    state: ConnectionState;
+    metrics: Metrics;
+};
+/**
+ * Hook to subscribe to a realtime topic with automatic subscription lifecycle management.
+ */
+declare const useSubscription: <T = any>(topic: string, optionsOrHandler: SubscribeOptions | ((data: T) => void), handlerOrUndefined?: (data: T) => void) => void;
+/**
+ * Semantic alias for `useSubscription` conforming to the useChannel requirement.
+ */
+declare const useChannel: <T = any>(topic: string, optionsOrHandler: SubscribeOptions | ((data: T) => void), handlerOrUndefined?: (data: T) => void) => void;
+/**
+ * Hook returning a callback to publish events to a topic.
+ */
+declare const usePublish: () => (<K extends string, V = any>(topic: K, payload: V) => Promise<void>);
+
+export { RealtimeProvider, type RealtimeProviderProps, useChannel, useConnection, usePublish, useRealtime, useSubscription };

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+import React from 'react';
+import { RealtimeClient, SubscribeOptions, ConnectionState, Metrics } from '@connexis/core';
+
+interface RealtimeProviderProps {
+    client: RealtimeClient;
+    children: React.ReactNode;
+}
+/**
+ * Context Provider enabling access to the Realtime Client across the React component tree.
+ */
+declare const RealtimeProvider: React.FC<RealtimeProviderProps>;
+/**
+ * Accesses the raw RealtimeClient instance from Context.
+ */
+declare const useRealtime: () => RealtimeClient;
+/**
+ * Hook to subscribe to connection state and performance metrics.
+ */
+declare const useConnection: () => {
+    state: ConnectionState;
+    metrics: Metrics;
+};
+/**
+ * Hook to subscribe to a realtime topic with automatic subscription lifecycle management.
+ */
+declare const useSubscription: <T = any>(topic: string, optionsOrHandler: SubscribeOptions | ((data: T) => void), handlerOrUndefined?: (data: T) => void) => void;
+/**
+ * Semantic alias for `useSubscription` conforming to the useChannel requirement.
+ */
+declare const useChannel: <T = any>(topic: string, optionsOrHandler: SubscribeOptions | ((data: T) => void), handlerOrUndefined?: (data: T) => void) => void;
+/**
+ * Hook returning a callback to publish events to a topic.
+ */
+declare const usePublish: () => (<K extends string, V = any>(topic: K, payload: V) => Promise<void>);
+
+export { RealtimeProvider, type RealtimeProviderProps, useChannel, useConnection, usePublish, useRealtime, useSubscription };

package/dist/index.js

@@ -0,0 +1,128 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  RealtimeProvider: () => RealtimeProvider,
+  useChannel: () => useChannel,
+  useConnection: () => useConnection,
+  usePublish: () => usePublish,
+  useRealtime: () => useRealtime,
+  useSubscription: () => useSubscription
+});
+module.exports = __toCommonJS(index_exports);
+var import_react = __toESM(require("react"));
+var RealtimeContext = (0, import_react.createContext)(null);
+var RealtimeProvider = ({ client, children }) => {
+  return import_react.default.createElement(RealtimeContext.Provider, { value: client }, children);
+};
+var useRealtime = () => {
+  const client = (0, import_react.useContext)(RealtimeContext);
+  if (!client) {
+    throw new Error("useRealtime must be used within a RealtimeProvider");
+  }
+  return client;
+};
+var useConnection = () => {
+  const client = useRealtime();
+  const [state, setState] = (0, import_react.useState)(client.state);
+  const [metrics, setMetrics] = (0, import_react.useState)(client.metrics);
+  (0, import_react.useEffect)(() => {
+    setState(client.state);
+    setMetrics(client.metrics);
+    const unsubState = client.on("stateChange", ({ state: state2 }) => {
+      setState(state2);
+    });
+    const unsubMetrics = client.on("metricsChange", (metrics2) => {
+      setMetrics(metrics2);
+    });
+    return () => {
+      unsubState();
+      unsubMetrics();
+    };
+  }, [client]);
+  return { state, metrics };
+};
+var useSubscription = (topic, optionsOrHandler, handlerOrUndefined) => {
+  const client = useRealtime();
+  const options = typeof optionsOrHandler === "object" ? optionsOrHandler : {};
+  const handler = typeof optionsOrHandler === "function" ? optionsOrHandler : handlerOrUndefined;
+  if (!handler) {
+    throw new Error("Subscription handler function is required");
+  }
+  const handlerRef = (0, import_react.useRef)(handler);
+  handlerRef.current = handler;
+  const filterString = options.filter ? JSON.stringify(options.filter) : "";
+  (0, import_react.useEffect)(() => {
+    let active = true;
+    let unsubPromise = null;
+    let unsubscribe = null;
+    const subOpts = options.filter ? { filter: options.filter } : {};
+    unsubPromise = client.subscribe(topic, subOpts, (data) => {
+      if (active) {
+        handlerRef.current(data);
+      }
+    });
+    unsubPromise.then((unsub) => {
+      if (!active) {
+        unsub();
+      } else {
+        unsubscribe = unsub;
+      }
+    });
+    return () => {
+      active = false;
+      if (unsubscribe) {
+        unsubscribe();
+      } else if (unsubPromise) {
+        unsubPromise.then((unsub) => unsub());
+      }
+    };
+  }, [client, topic, filterString]);
+};
+var useChannel = useSubscription;
+var usePublish = () => {
+  const client = useRealtime();
+  return (0, import_react.useCallback)(
+    async (topic, payload) => {
+      await client.publish(topic, payload);
+    },
+    [client]
+  );
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  RealtimeProvider,
+  useChannel,
+  useConnection,
+  usePublish,
+  useRealtime,
+  useSubscription
+});

package/dist/index.mjs

@@ -0,0 +1,88 @@
+// src/index.ts
+import React, { createContext, useContext, useEffect, useState, useRef, useCallback } from "react";
+var RealtimeContext = createContext(null);
+var RealtimeProvider = ({ client, children }) => {
+  return React.createElement(RealtimeContext.Provider, { value: client }, children);
+};
+var useRealtime = () => {
+  const client = useContext(RealtimeContext);
+  if (!client) {
+    throw new Error("useRealtime must be used within a RealtimeProvider");
+  }
+  return client;
+};
+var useConnection = () => {
+  const client = useRealtime();
+  const [state, setState] = useState(client.state);
+  const [metrics, setMetrics] = useState(client.metrics);
+  useEffect(() => {
+    setState(client.state);
+    setMetrics(client.metrics);
+    const unsubState = client.on("stateChange", ({ state: state2 }) => {
+      setState(state2);
+    });
+    const unsubMetrics = client.on("metricsChange", (metrics2) => {
+      setMetrics(metrics2);
+    });
+    return () => {
+      unsubState();
+      unsubMetrics();
+    };
+  }, [client]);
+  return { state, metrics };
+};
+var useSubscription = (topic, optionsOrHandler, handlerOrUndefined) => {
+  const client = useRealtime();
+  const options = typeof optionsOrHandler === "object" ? optionsOrHandler : {};
+  const handler = typeof optionsOrHandler === "function" ? optionsOrHandler : handlerOrUndefined;
+  if (!handler) {
+    throw new Error("Subscription handler function is required");
+  }
+  const handlerRef = useRef(handler);
+  handlerRef.current = handler;
+  const filterString = options.filter ? JSON.stringify(options.filter) : "";
+  useEffect(() => {
+    let active = true;
+    let unsubPromise = null;
+    let unsubscribe = null;
+    const subOpts = options.filter ? { filter: options.filter } : {};
+    unsubPromise = client.subscribe(topic, subOpts, (data) => {
+      if (active) {
+        handlerRef.current(data);
+      }
+    });
+    unsubPromise.then((unsub) => {
+      if (!active) {
+        unsub();
+      } else {
+        unsubscribe = unsub;
+      }
+    });
+    return () => {
+      active = false;
+      if (unsubscribe) {
+        unsubscribe();
+      } else if (unsubPromise) {
+        unsubPromise.then((unsub) => unsub());
+      }
+    };
+  }, [client, topic, filterString]);
+};
+var useChannel = useSubscription;
+var usePublish = () => {
+  const client = useRealtime();
+  return useCallback(
+    async (topic, payload) => {
+      await client.publish(topic, payload);
+    },
+    [client]
+  );
+};
+export {
+  RealtimeProvider,
+  useChannel,
+  useConnection,
+  usePublish,
+  useRealtime,
+  useSubscription
+};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@connexis/react",
+  "version": "1.0.0",
+  "description": "React hooks and provider for @connexis",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "dependencies": {
+    "@connexis/core": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.3",
+    "react": "^18.3.1",
+    "typescript": "^5.5.2"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean"
+  }
+}

package/src/index.ts

@@ -0,0 +1,133 @@
+import React, { createContext, useContext, useEffect, useState, useRef, useCallback } from 'react';
+import { RealtimeClient, ConnectionState, Metrics, SubscribeOptions } from '@connexis/core';
+
+const RealtimeContext = createContext<RealtimeClient | null>(null);
+
+export interface RealtimeProviderProps {
+  client: RealtimeClient;
+  children: React.ReactNode;
+}
+
+/**
+ * Context Provider enabling access to the Realtime Client across the React component tree.
+ */
+export const RealtimeProvider: React.FC<RealtimeProviderProps> = ({ client, children }) => {
+  return React.createElement(RealtimeContext.Provider, { value: client }, children);
+};
+
+/**
+ * Accesses the raw RealtimeClient instance from Context.
+ */
+export const useRealtime = (): RealtimeClient => {
+  const client = useContext(RealtimeContext);
+  if (!client) {
+    throw new Error('useRealtime must be used within a RealtimeProvider');
+  }
+  return client;
+};
+
+/**
+ * Hook to subscribe to connection state and performance metrics.
+ */
+export const useConnection = (): { state: ConnectionState; metrics: Metrics } => {
+  const client = useRealtime();
+  const [state, setState] = useState<ConnectionState>(client.state);
+  const [metrics, setMetrics] = useState<Metrics>(client.metrics);
+
+  useEffect(() => {
+    // Initial sync
+    setState(client.state);
+    setMetrics(client.metrics);
+
+    const unsubState = client.on('stateChange', ({ state }) => {
+      setState(state);
+    });
+
+    const unsubMetrics = client.on('metricsChange', (metrics) => {
+      setMetrics(metrics);
+    });
+
+    return () => {
+      unsubState();
+      unsubMetrics();
+    };
+  }, [client]);
+
+  return { state, metrics };
+};
+
+/**
+ * Hook to subscribe to a realtime topic with automatic subscription lifecycle management.
+ */
+export const useSubscription = <T = any>(
+  topic: string,
+  optionsOrHandler: SubscribeOptions | ((data: T) => void),
+  handlerOrUndefined?: (data: T) => void
+): void => {
+  const client = useRealtime();
+
+  const options = typeof optionsOrHandler === 'object' ? optionsOrHandler : {};
+  const handler = typeof optionsOrHandler === 'function' ? optionsOrHandler : handlerOrUndefined;
+
+  if (!handler) {
+    throw new Error('Subscription handler function is required');
+  }
+
+  const handlerRef = useRef(handler);
+  handlerRef.current = handler;
+
+  const filterString = options.filter ? JSON.stringify(options.filter) : '';
+
+  useEffect(() => {
+    let active = true;
+    let unsubPromise: Promise<() => Promise<void>> | null = null;
+    let unsubscribe: (() => Promise<void>) | null = null;
+
+    const subOpts = options.filter ? { filter: options.filter } : {};
+
+    unsubPromise = client.subscribe(topic, subOpts, (data) => {
+      if (active) {
+        handlerRef.current(data);
+      }
+    });
+
+    unsubPromise.then((unsub) => {
+      if (!active) {
+        unsub();
+      } else {
+        unsubscribe = unsub;
+      }
+    });
+
+    return () => {
+      active = false;
+      if (unsubscribe) {
+        unsubscribe();
+      } else if (unsubPromise) {
+        unsubPromise.then((unsub) => unsub());
+      }
+    };
+  }, [client, topic, filterString]);
+};
+
+/**
+ * Semantic alias for `useSubscription` conforming to the useChannel requirement.
+ */
+export const useChannel = useSubscription;
+
+/**
+ * Hook returning a callback to publish events to a topic.
+ */
+export const usePublish = (): (<K extends string, V = any>(
+  topic: K,
+  payload: V
+) => Promise<void>) => {
+  const client = useRealtime();
+
+  return useCallback(
+    async <K extends string, V = any>(topic: K, payload: V) => {
+      await client.publish(topic, payload);
+    },
+    [client]
+  );
+};

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "jsx": "react-jsx"
+  },
+  "include": ["src/**/*"]
+}