rename yield to passive

CHANGELOG.md

@@ -7,16 +7,16 @@
 
 - **basic `useEvent` data caching**
 
-  The last response from any `useEvent` is cached across all instances. This means that if if you recieve any event for a channel topic, and for example the `useEvent` hook unmounts, once it remounts, it will instantly load the last recieved data for the given `event`.
+  The last response from any `useEvent` is cached across all instances. This means that if if you recieve any event for a channel topic, and for example the `useEvent` hook unmounts, once it remounts, it will instantly load the last recieved data and state for the given `event`.
 
   Previously if you recieved an event and the hook unmounted and remounted, the data stored in the `useEvent` hook was lost and you have needed to recieve the event again to get the data back.
 
   Once you leave a channel using `leave()` all cached data for the `useEvent` will be cleared.
 
 ### Additional changes
-- `useChannel` now accepts a `yield` option
+- `useChannel` now accepts a `passive` option
 
-  yield will force the channel to wait for another instance of `useChannel` to connect with the necessary params and then connect itself to the channel for regular usage. See the docs for more information.
+  `passive` will instruct the channel to wait for another instance of `useChannel` to connect with the necessary params and then once a connection is made, the `passive` channel will connect itself. See the js docs for more information.
 # 0.0.1
 
 2024-2-15

README.md

@@ -1,5 +1,10 @@
 # use-phoenix
 The library will not follow semver until version `1.0.0`. expect potential breaking changes on any new versions until then.
+
+This library deviates in a few areas to better fit with react's paradigm. The biggest deviations are as follows:
+
+1. In Phoenix.js, "opening" a new instance of a channel topic will close any previous instance. This makes sense as we only want one source of truth, and we don't want to recieve duplicate events. This is still the case in `use-phoenix`, however calling `useChannel` multiple times does not create new instances of a channel like how calling `new Channel()` does. In this case, subsequent `useChannel` hooks will attach to the already existing channel if it exists, otherwise it will create it.
+
 ## Connecting to your Phoenix Socket
 
 Wrap the intended part of your application with a `PhoenixProvider`.
@@ -166,7 +171,7 @@ leave();
 ## Waiting for another `useChannel` to make the connection
 Consider the case where you are using `useChannel` in multiple components, but only one of the components really has the necessary `params` to connect to the channel topic, and you just want the other components to work with the channel after the channel has been connected. The problem is, if the component that does not have access to connection params occurs earlier in the react tree, it will naturally try to connect and be unable to because the required params are contained within a later component in the tree.
 
-What you can do is indicate `useChannel` to `yield` and wait for another `useChannel` to connect and once it connects, the yielded `useChannel` will connect to the instance and operate as usual. Note if no connection is ever made, a yielded `useChannel` will never connect.
+What you can do is indicate `useChannel` to become `passive` and wait for another `useChannel` to connect and once it connects, the passive `useChannel` will connect to the instance and operate as usual. Note if no connection is ever made, a passive `useChannel` will never connect.
 
 ### Example
 
@@ -177,7 +182,7 @@ const [channel] = useChannel('map:1', { params: { coordinates: [0, 0] }});
 //                                                   value only known by main.tsx
 
 // Layout.tsx which doesnt have access to the coordinates...
-const [channel] = useChannel('map:1', { yield: true });
+const [channel] = useChannel('map:1', { passive: true });
 //                                      ^^^^^
 // this channel will wait until map.tsx connects instead of connecting itself.
 // thus allowing you to not need params

package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-phoenix",
-  "version": "0.0.2-alpha.4",
+  "version": "0.0.2-alpha.6",
   "description": "React hooks for the Phoenix Framework",
   "main": "dist/index.js",
   "module": "dist/index.esm.js",

src/useChannel/types.ts

@@ -51,9 +51,9 @@ export type ChannelOptions<Params = undefined> = {
    *
    * Note that this option will ignore any `params` given if set to `true`.
    * Params should be passed to the `useChannel` hook that is meant to connect.
-   * If there is no non-lazy `useChannel` that connects, this hook will never connect.
+   * If there is no non-passive `useChannel` that connects, this hook will never connect.
    */
-  yield?: boolean;
+  passive?: boolean;
 };
 
 export type ChannelParams = Record<string, any>;

src/useChannel/useChannel.ts

@@ -37,7 +37,7 @@ import cache, { defaultMeta } from '../cache';
  * @param topic - the topic to connect to.
  * @param options - options for the channel.
  *  - `params` - The params to send to the server when joining the channel.
- *  - `yield` - A boolean indicating whether the channel should wait until another `useChannel` hook has connected to the topic instead of trying to connect itself.
+ *  - `passive` - A boolean indicating whether the channel should wait until another `useChannel` hook has connected to the topic instead of trying to connect itself.
  */
 export function useChannel<Params extends ChannelParams, JoinPayload>(
   topic: string | boolean | null | undefined,
@@ -84,8 +84,8 @@ export function useChannel<Params extends ChannelParams, JoinPayload>(
     if (!isConnected) return;
     if (typeof topic !== 'string') return;
 
-    const isLazy = optionsRef.current?.yield ?? false;
-    if (isLazy) return;
+    const isPassive = optionsRef.current?.passive ?? false;
+    if (isPassive) return;
 
     const existingChannel = findChannel(socket, topic);
     if (existingChannel) return handleJoin(existingChannel);
@@ -168,7 +168,7 @@ export function useChannel<Params extends ChannelParams, JoinPayload>(
         // @ts-ignore
         if (_channel.joinPush) _channel.joinPush.recHooks = [];
 
-        
+
         _channel.off('phx_error');
         _channel.off('phx_close');
         _channel.off('phx_reply');
@@ -177,9 +177,9 @@ export function useChannel<Params extends ChannelParams, JoinPayload>(
   }, [isConnected, topic, handleJoin]);
 
   useEffect(() => {
-    const isLazy = optionsRef.current?.yield ?? false;
+    const isPassive = optionsRef.current?.passive ?? false;
 
-    if (!isLazy) return;
+    if (!isPassive) return;
     if (!socket) return;
     if (!isConnected) return;
     if (typeof topic !== 'string') return;
@@ -194,9 +194,9 @@ export function useChannel<Params extends ChannelParams, JoinPayload>(
 
   useEffect(() => {
     return () => {
-      const isLazy = optionsRef.current?.yield ?? false;
+      const isPassive = optionsRef.current?.passive ?? false;
 
-      if (isLazy && channel && socket && messageRef.current) {
+      if (isPassive && channel && socket && messageRef.current) {
         socket.off([messageRef.current]);
         messageRef.current = undefined;
       }