@holo-js/flux-react 0.1.3

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+import { FluxClient, FluxConnectionStatus, FluxListenerControls } from '@holo-js/flux';
+import { GeneratedBroadcastManifest, BroadcastPayloadFor } from '@holo-js/broadcast';
+
+interface FluxHookOptions<TManifest extends GeneratedBroadcastManifest = GeneratedBroadcastManifest> {
+    readonly client?: FluxClient<TManifest>;
+    readonly onUnmount?: (cleanup: () => void) => void;
+}
+interface FluxConnectionStatusHookOptions<TManifest extends GeneratedBroadcastManifest = GeneratedBroadcastManifest> extends FluxHookOptions<TManifest> {
+    readonly onChange?: (status: FluxConnectionStatus) => void;
+}
+interface FluxPresenceHookCallbacks<TMember = unknown> {
+    readonly onHere?: (members: readonly TMember[]) => void;
+}
+type FluxPresenceHookState<TMember = unknown> = FluxListenerControls & {
+    readonly members: readonly TMember[];
+};
+declare function useFlux<TEvent extends string, TManifest extends GeneratedBroadcastManifest = GeneratedBroadcastManifest>(channel: string, events: TEvent | readonly TEvent[], callback: (payload: BroadcastPayloadFor<TEvent>) => void, options?: FluxHookOptions<TManifest>): FluxListenerControls;
+declare function useFluxPublic<TEvent extends string, TManifest extends GeneratedBroadcastManifest = GeneratedBroadcastManifest>(channel: string, events: TEvent | readonly TEvent[], callback: (payload: BroadcastPayloadFor<TEvent>) => void, options?: FluxHookOptions<TManifest>): FluxListenerControls;
+declare function useFluxPrivate<TEvent extends string, TManifest extends GeneratedBroadcastManifest = GeneratedBroadcastManifest>(channel: string, events: TEvent | readonly TEvent[], callback: (payload: BroadcastPayloadFor<TEvent>) => void, options?: FluxHookOptions<TManifest>): FluxListenerControls;
+declare function useFluxPresence<TMember = unknown, TManifest extends GeneratedBroadcastManifest = GeneratedBroadcastManifest>(channel: string, callbacks?: FluxPresenceHookCallbacks<TMember>, options?: FluxHookOptions<TManifest>): FluxPresenceHookState<TMember>;
+declare function useFluxNotification<TManifest extends GeneratedBroadcastManifest = GeneratedBroadcastManifest>(channel: string, callback: (payload: unknown) => void, options?: FluxHookOptions<TManifest>): FluxListenerControls;
+declare function useFluxModel<TEvent extends string, TManifest extends GeneratedBroadcastManifest = GeneratedBroadcastManifest>(channel: string, events: TEvent | readonly TEvent[], callback: (payload: BroadcastPayloadFor<TEvent>) => void, options?: FluxHookOptions<TManifest>): FluxListenerControls;
+declare function useFluxConnectionStatus<TManifest extends GeneratedBroadcastManifest = GeneratedBroadcastManifest>(options?: FluxConnectionStatusHookOptions<TManifest>): FluxConnectionStatus;
+
+export { type FluxConnectionStatusHookOptions, type FluxHookOptions, type FluxPresenceHookCallbacks, type FluxPresenceHookState, useFlux, useFluxConnectionStatus, useFluxModel, useFluxNotification, useFluxPresence, useFluxPrivate, useFluxPublic };

package/dist/index.mjs

@@ -0,0 +1,204 @@
+// src/index.ts
+import { useEffect, useMemo, useReducer, useRef, useSyncExternalStore } from "react";
+import { getFluxClient } from "@holo-js/flux";
+function resolveClient(options) {
+  return options.client ?? getFluxClient();
+}
+var noop = Function.prototype;
+function createNoopControls() {
+  const controls = {
+    leave: noop,
+    leaveChannel: noop,
+    /* v8 ignore next -- noop listen is only used as initial ref value before useEffect runs */
+    listen: () => controls,
+    stopListening: noop
+  };
+  return Object.freeze(controls);
+}
+function useLatestRef(value) {
+  const ref = useRef(value);
+  ref.current = value;
+  return ref;
+}
+function serializeEventDependency(events) {
+  return Array.isArray(events) ? events.map(String).join("\0") : String(events);
+}
+function useControls(createSubscription, onUnmount, dependencies = []) {
+  const controlsRef = useRef(createNoopControls());
+  const onUnmountRef = useLatestRef(onUnmount);
+  useEffect(() => {
+    const subscription = createSubscription();
+    const cleanup = () => {
+      subscription.leaveChannel();
+    };
+    controlsRef.current = Object.freeze({
+      leave: () => {
+        subscription.leave();
+      },
+      leaveChannel: () => {
+        subscription.leaveChannel();
+      },
+      listen: () => {
+        subscription.listen();
+        return controlsRef.current;
+      },
+      stopListening: () => {
+        subscription.stopListening();
+      }
+    });
+    onUnmountRef.current?.(cleanup);
+    return cleanup;
+  }, dependencies);
+  return useMemo(() => Object.freeze({
+    leave: () => {
+      controlsRef.current.leave();
+    },
+    leaveChannel: () => {
+      controlsRef.current.leaveChannel();
+    },
+    listen: () => {
+      return controlsRef.current.listen();
+    },
+    stopListening: () => {
+      controlsRef.current.stopListening();
+    }
+  }), []);
+}
+function useEventSubscription(buildSubscription, events, callback, onUnmount, dependencies = []) {
+  const callbackRef = useLatestRef(callback);
+  return useControls(() => {
+    return buildSubscription().listen(
+      events,
+      callbackRef.current
+    );
+  }, onUnmount, dependencies);
+}
+function useFlux(channel, events, callback, options = {}) {
+  const client = resolveClient(options);
+  return useEventSubscription(
+    () => client.private(channel),
+    events,
+    callback,
+    options.onUnmount,
+    [client, channel, serializeEventDependency(events)]
+  );
+}
+function useFluxPublic(channel, events, callback, options = {}) {
+  const client = resolveClient(options);
+  return useEventSubscription(
+    () => client.channel(channel),
+    events,
+    callback,
+    options.onUnmount,
+    [client, channel, serializeEventDependency(events)]
+  );
+}
+function useFluxPrivate(channel, events, callback, options = {}) {
+  return useFlux(channel, events, callback, options);
+}
+function useFluxPresence(channel, callbacks = {}, options = {}) {
+  const client = resolveClient(options);
+  const membersRef = useRef([]);
+  const [, rerender] = useReducer((count) => count + 1, 0);
+  const controlsRef = useRef(createNoopControls());
+  const callbacksRef = useLatestRef(callbacks);
+  const onUnmountRef = useLatestRef(options.onUnmount);
+  useEffect(() => {
+    const subscription = client.presence(channel);
+    const updateMembers = (members) => {
+      membersRef.current = members;
+      callbacksRef.current.onHere?.(membersRef.current);
+      rerender();
+    };
+    updateMembers(subscription.members);
+    const stop = subscription.__onPresenceChange?.(updateMembers);
+    const cleanup = () => {
+      stop?.();
+      subscription.leaveChannel();
+    };
+    controlsRef.current = Object.freeze({
+      leave: () => {
+        subscription.leave();
+      },
+      leaveChannel: () => {
+        subscription.leaveChannel();
+      },
+      listen: () => {
+        subscription.listen();
+        return controlsRef.current;
+      },
+      stopListening: () => {
+        subscription.stopListening();
+      }
+    });
+    onUnmountRef.current?.(cleanup);
+    return cleanup;
+  }, [channel, client, callbacksRef, onUnmountRef]);
+  const controls = useMemo(() => Object.freeze({
+    leave: () => {
+      controlsRef.current.leave();
+    },
+    leaveChannel: () => {
+      controlsRef.current.leaveChannel();
+    },
+    listen: () => {
+      return controlsRef.current.listen();
+    },
+    stopListening: () => {
+      controlsRef.current.stopListening();
+    }
+  }), []);
+  return Object.freeze({
+    ...controls,
+    get members() {
+      return membersRef.current;
+    }
+  });
+}
+function useFluxNotification(channel, callback, options = {}) {
+  const client = resolveClient(options);
+  const callbackRef = useLatestRef(callback);
+  return useControls(() => {
+    return client.private(channel).notification(
+      callbackRef.current
+    );
+  }, options.onUnmount, [client, channel]);
+}
+function useFluxModel(channel, events, callback, options = {}) {
+  return useFluxPrivate(channel, events, callback, options);
+}
+function useFluxConnectionStatus(options = {}) {
+  const client = resolveClient(options);
+  const onChangeRef = useLatestRef(options.onChange);
+  const onUnmountRef = useLatestRef(options.onUnmount);
+  useEffect(() => {
+    if (!onChangeRef.current) {
+      return;
+    }
+    const unsubscribe = client.onStatusChange((status) => {
+      onChangeRef.current?.(status);
+    });
+    onUnmountRef.current?.(unsubscribe);
+    return unsubscribe;
+  }, [client, onChangeRef, onUnmountRef]);
+  return useSyncExternalStore(
+    (notify) => {
+      const unsubscribe = client.onStatusChange(() => {
+        notify();
+      });
+      onUnmountRef.current?.(unsubscribe);
+      return unsubscribe;
+    },
+    () => client.getStatus(),
+    () => client.getStatus()
+  );
+}
+export {
+  useFlux,
+  useFluxConnectionStatus,
+  useFluxModel,
+  useFluxNotification,
+  useFluxPresence,
+  useFluxPrivate,
+  useFluxPublic
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@holo-js/flux-react",
+  "version": "0.1.3",
+  "description": "Holo-JS Framework - React and Next hook skeletons for Flux",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "stub": "tsup",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest --run"
+  },
+  "dependencies": {
+    "@holo-js/broadcast": "^0.1.3",
+    "@holo-js/flux": "^0.1.3"
+  },
+  "peerDependencies": {
+    "react": "^18.3.1 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.12",
+    "@types/react-test-renderer": "^18.3.1",
+    "@types/node": "^22.10.2",
+    "react": "^18.3.1",
+    "react-test-renderer": "^18.3.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}