@pixotope/query 0.0.1

package/src/useSubscriptionCore.test.ts

@@ -0,0 +1,360 @@
+import { act, renderHook } from "@testing-library/react";
+import { vi, describe, test, expect, it } from "vitest";
+
+import { useSubscriptionCore } from "./useSubscriptionCore";
+
+const message = "test";
+
+describe("useSubscriptionCore", () => {
+  function getFns() {
+    const cleanupFn = vi.fn();
+    const subscriberFn = vi.fn(() => cleanupFn);
+    const handler = vi.fn();
+
+    return {
+      cleanupFn,
+      subscriberFn,
+      handler,
+    };
+  }
+
+  test.concurrent("should call subscriberFn by on mount by default", () => {
+    const { subscriberFn } = getFns();
+
+    renderHook(() => useSubscriptionCore({ subscriberFn }));
+
+    expect(subscriberFn).toBeCalledTimes(1);
+  });
+  test.concurrent(
+    "should not call subscriberFn by on mount if enabled is false",
+    () => {
+      const { subscriberFn } = getFns();
+
+      renderHook(() =>
+        useSubscriptionCore({
+          subscriberFn,
+          enabled: false,
+        })
+      );
+
+      expect(subscriberFn).toBeCalledTimes(0);
+    }
+  );
+  test.concurrent("status should be in loading by default", () => {
+    const { subscriberFn } = getFns();
+    const { result } = renderHook(() => useSubscriptionCore({ subscriberFn }));
+
+    expect(result.current.status).toBe("subscribing");
+  });
+  test.concurrent("status should be in idle if enabled is false", () => {
+    const { subscriberFn } = getFns();
+    const { result } = renderHook(() =>
+      useSubscriptionCore({ subscriberFn, enabled: false })
+    );
+
+    expect(result.current.status).toBe("idle");
+  });
+  it.concurrent("should call cleanupFn by on unmount", () => {
+    const { subscriberFn, cleanupFn } = getFns();
+    const { unmount } = renderHook(() => useSubscriptionCore({ subscriberFn }));
+
+    unmount();
+
+    expect(cleanupFn).toBeCalledTimes(1);
+  });
+  it.concurrent(
+    "should not call cleanupFn by on unmount if enabled is false",
+    () => {
+      const { subscriberFn, cleanupFn } = getFns();
+      const { unmount } = renderHook(() =>
+        useSubscriptionCore({ subscriberFn, enabled: false })
+      );
+
+      unmount();
+
+      expect(cleanupFn).toBeCalledTimes(0);
+    }
+  );
+  it.concurrent(
+    "should call cleanupFn if enabled is false and explicit subscribe",
+    () => {
+      const { subscriberFn, cleanupFn } = getFns();
+      const { result, unmount } = renderHook(() =>
+        useSubscriptionCore({ subscriberFn, enabled: false })
+      );
+
+      act(() => result.current.reSubscribe());
+
+      unmount();
+
+      expect(cleanupFn).toBeCalledTimes(1);
+    }
+  );
+  test.concurrent(
+    "status is set to subscribed whien connection is acknowledged manually",
+    () => {
+      const { cleanupFn } = getFns();
+      const { result } = renderHook(() =>
+        useSubscriptionCore({
+          subscriberFn: (_, con) => {
+            con.acknowledge();
+
+            return cleanupFn;
+          },
+        })
+      );
+
+      act(() => result.current.reSubscribe());
+
+      expect(result.current.status).toBe("subscribed");
+    }
+  );
+  test.concurrent(
+    "status is set to subscribed whien connection is acknowledged by handler",
+    () => {
+      const { cleanupFn } = getFns();
+      const { result } = renderHook(() =>
+        useSubscriptionCore({
+          subscriberFn: (handler) => {
+            handler(message);
+
+            return cleanupFn;
+          },
+        })
+      );
+
+      act(() => result.current.reSubscribe());
+
+      expect(result.current.status).toBe("subscribed");
+    }
+  );
+  it.concurrent("should call onSubscribed if provided", () => {
+    const { cleanupFn } = getFns();
+    const onSubscribed = vi.fn();
+
+    renderHook(() =>
+      useSubscriptionCore({
+        subscriberFn: (handler) => {
+          handler(message);
+
+          return cleanupFn;
+        },
+        onSubscribed,
+      })
+    );
+
+    expect(onSubscribed).toBeCalledTimes(1);
+  });
+  it.concurrent("should call onMessage if provided", () => {
+    const { cleanupFn } = getFns();
+    const onMessage = vi.fn();
+
+    renderHook(() =>
+      useSubscriptionCore({
+        subscriberFn: (handler) => {
+          handler(message);
+
+          return cleanupFn;
+        },
+        onMessage,
+      })
+    );
+
+    expect(onMessage).toBeCalledTimes(1);
+  });
+  it.concurrent("should call compareOrThrow if provided", () => {
+    const { cleanupFn } = getFns();
+    const compareOrThrow = vi.fn();
+
+    renderHook(() =>
+      useSubscriptionCore({
+        subscriberFn: (handler) => {
+          handler(message);
+
+          return cleanupFn;
+        },
+        compareOrThrow,
+      })
+    );
+
+    expect(compareOrThrow).toBeCalledTimes(1);
+  });
+  it.concurrent("should call onError if provided", () => {
+    const { cleanupFn } = getFns();
+    const onError = vi.fn();
+
+    renderHook(() =>
+      useSubscriptionCore({
+        subscriberFn: (handler) => {
+          handler(message);
+
+          return cleanupFn;
+        },
+        onError,
+        compareOrThrow: () => true,
+      })
+    );
+
+    expect(onError).toBeCalledTimes(1);
+  });
+  it.concurrent(
+    "should not call onMessage if provided and compareOrThrow is true",
+    () => {
+      const { cleanupFn } = getFns();
+      const onMessage = vi.fn();
+
+      renderHook(() =>
+        useSubscriptionCore({
+          subscriberFn: (handler) => {
+            handler(message);
+
+            return cleanupFn;
+          },
+          onMessage,
+          compareOrThrow: () => true,
+        })
+      );
+
+      expect(onMessage).toBeCalledTimes(0);
+    }
+  );
+  it.concurrent(
+    "should call onMessage if provided and compareOrThrow is false",
+    () => {
+      const { cleanupFn } = getFns();
+      const onMessage = vi.fn();
+
+      renderHook(() =>
+        useSubscriptionCore({
+          subscriberFn: (handler) => {
+            handler(message);
+
+            return cleanupFn;
+          },
+          onMessage,
+          compareOrThrow: () => false,
+        })
+      );
+
+      expect(onMessage).toBeCalledTimes(1);
+    }
+  );
+  it.concurrent(
+    "should call onError if provided and compareOrThrow is false",
+    () => {
+      const { cleanupFn } = getFns();
+      const onError = vi.fn();
+
+      renderHook(() =>
+        useSubscriptionCore({
+          subscriberFn: (handler) => {
+            handler(message);
+
+            return cleanupFn;
+          },
+          onError,
+          compareOrThrow: () => true,
+        })
+      );
+
+      expect(onError).toBeCalledTimes(1);
+    }
+  );
+  it.concurrent("should set initialData if provided", () => {
+    const { cleanupFn } = getFns();
+    const { result } = renderHook(() =>
+      useSubscriptionCore<string>({
+        subscriberFn: (handler) => {
+          handler(message);
+
+          return cleanupFn;
+        },
+        initialState: "test",
+      })
+    );
+
+    expect(result.current.data).toBe("test");
+  });
+  it.concurrent("should call select function if provided", () => {
+    const { cleanupFn } = getFns();
+    const select = vi.fn();
+
+    renderHook(() =>
+      useSubscriptionCore({
+        subscriberFn: (handler) => {
+          handler(message);
+
+          return cleanupFn;
+        },
+        select,
+      })
+    );
+
+    expect(select).toBeCalled();
+  });
+  it.concurrent(
+    "should return correct data if select function is provided",
+    () => {
+      const { cleanupFn } = getFns();
+
+      const { result } = renderHook(() =>
+        useSubscriptionCore<unknown, { foo: string }>({
+          subscriberFn: (handler) => {
+            handler({
+              foo: "test",
+            });
+
+            return cleanupFn;
+          },
+          select: (data) => data.foo,
+        })
+      );
+
+      expect(result.current.data).toBe(message);
+    }
+  );
+  it.concurrent(
+    "should set the state to the message passed to handler function",
+    () => {
+      const { cleanupFn } = getFns();
+
+      const { result } = renderHook(() =>
+        useSubscriptionCore({
+          subscriberFn: (handler) => {
+            handler(message);
+
+            return cleanupFn;
+          },
+        })
+      );
+
+      expect(result.current.data).toBe(message);
+    }
+  );
+  it.concurrent(
+    "should not update status and data when stateless is `true`",
+    () => {
+      const { cleanupFn } = getFns();
+
+      const { result } = renderHook(() =>
+        useSubscriptionCore({
+          subscriberFn: (handler) => {
+            handler({
+              hello: "world",
+            });
+
+            return cleanupFn;
+          },
+          stateless: true,
+        })
+      );
+
+      // @ts-ignore ts should kick in and prevent the
+      //  following action but okay for testing as those values will always exist in returned object
+      const { data, status } = result.current;
+
+      expect(data).toBe(undefined);
+      expect(status).toBe("idle"); // default
+    }
+  );
+});

package/src/useSubscriptionCore.ts

@@ -0,0 +1,223 @@
+/**
+ * @fileoverview useSubscriptionCore
+ * @name useSubscriptionCore.ts
+ * @description useSubscriptionCore | This hook handle core subscription logic
+ * and provides a way to subscribe and unsubscribe to a topic via any callback
+ */
+
+import { shallowEqual } from "@pixotope/utils/comparison";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+type SubscriptionState = "idle" | "subscribed" | "subscribing";
+export type MessageHandler<TMessage> = (message: TMessage) => void;
+export type Connection = {
+  acknowledge: () => void;
+};
+export type SubscriptionCoreOptions<
+  TData,
+  TMessage = TData,
+  Stateless extends true | undefined = undefined,
+> = {
+  /**
+   * @description Function that will be called when the message is received.
+   */
+  onMessage?: (message: TMessage) => void;
+  /**
+   * @description Function that will be called when the subscription is created.
+   */
+  onSubscribed?: (message: TMessage) => void;
+  /**
+   * @description Function that will be called when the subscription is created.
+   */
+  onError?: (error: TMessage) => void;
+  /**
+   * @description Whether the subscription is enabled.
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * @description Function that will be called to compare the message with the
+   * previous message. If the function returns true, the message will be ignored.
+   */
+  compareOrThrow?: (data: TMessage) => boolean;
+  /**
+   * @description Function that will be called to select the data from the message.
+   */
+  select?: (data: TMessage) => TData;
+  /**
+   * @description Initial state of the subscription.
+   * @default undefined
+   */
+  initialState?: TData;
+  /**
+   * @description Function that will be called when the subscription is created.
+   */
+  subscriberFn: (
+    handler: MessageHandler<TMessage>,
+    connection: Connection
+  ) => () => void /** unsubscribe Fn */;
+  /**
+   * @description Whether the subscription is stateless. Data will not be
+   * stored by the hook internally.
+   * @default false
+   */
+  stateless?: Stateless;
+  /**
+   * @description Custom equality function for comparing data.
+   * @default shallowEqual
+   */
+  isEqual?: <T = TData>(a: T, b: T) => boolean;
+};
+
+type WithStatus = {
+  status: SubscriptionState;
+};
+
+type WithData<TData> = {
+  data: TData;
+};
+
+export type SubscriptionCoreReturnType<
+  TData,
+  Stateless extends true | undefined,
+> = {
+  reSubscribe: () => void;
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+} & (Stateless extends true ? {} : WithStatus & WithData<TData>);
+
+/**
+ * @description `useSubscriptionCore` | This hook handle core subscription logic
+ * and provides a way to subscribe and unsubscribe to a topic via any callback.
+ * The hook expose a handler function. All the consumer code need to do is to
+ * call this handler function with the message received from the topic or pass
+ * it directly to the callback function that is passed to the subscriberFn.
+ *  - `status` - current status of the subscription
+ *  - `data` - the data after the select function is applied to the message
+ *  - `reSubscribe` - function that can be called to re-subscribe to the topic
+ *
+ * An example how this hook works can be found in {@link ./useSubscription.ts}
+ */
+export function useSubscriptionCore<
+  TData = unknown,
+  TMessage = TData,
+  Stateless extends true | undefined = undefined,
+>(
+  options: SubscriptionCoreOptions<TData, TMessage, Stateless>
+): SubscriptionCoreReturnType<TData, Stateless> {
+  const {
+    enabled = true,
+    initialState = undefined,
+    onSubscribed,
+    stateless,
+    compareOrThrow,
+    subscriberFn,
+    onMessage,
+    onError,
+    select,
+    isEqual = shallowEqual,
+  } = options;
+  const [status, setStatus] = useState<SubscriptionState>("idle");
+  const [data, setData] = useState<TData | undefined>(initialState);
+  const unsubcribeRef = useRef<() => void | undefined>(undefined);
+  const initialStateRef = useRef(initialState);
+  const subscriberFnRef = useRef(subscriberFn);
+  const callbackRefRegistry = <const>{
+    onMessage,
+    onError,
+    select,
+    compareOrThrow,
+    onSubscribed,
+    isEqual,
+  };
+  const internalCallbacksRef = useRef(callbackRefRegistry);
+  internalCallbacksRef.current = callbackRefRegistry;
+
+  const updateStatus = useCallback(
+    (newStatus: SubscriptionState, message?: TMessage) => {
+      if (stateless) {
+        return;
+      }
+
+      setStatus((prev) => {
+        if (prev === newStatus) {
+          return prev;
+        }
+
+        if (newStatus === "subscribed" && message) {
+          internalCallbacksRef.current.onSubscribed?.(message);
+        }
+
+        return newStatus;
+      });
+    },
+    [stateless]
+  );
+
+  const connection: Connection = useMemo(
+    () => ({
+      acknowledge: () => {
+        updateStatus("subscribed");
+      },
+    }),
+    [updateStatus]
+  );
+
+  const handler = useCallback(
+    async (message: TMessage) => {
+      if (internalCallbacksRef.current.compareOrThrow?.(message)) {
+        internalCallbacksRef.current.onError?.(message);
+
+        return;
+      }
+
+      const selectedMessage = <TData>(
+        (internalCallbacksRef.current.select?.(message) ?? message)
+      );
+
+      if (!stateless) {
+        setData((prev) => {
+          if (isEqual(prev, selectedMessage)) {
+            return prev;
+          }
+
+          return selectedMessage;
+        });
+      }
+
+      updateStatus("subscribed", message);
+      internalCallbacksRef.current.onMessage?.(message);
+    },
+    [stateless, updateStatus]
+  );
+
+  const unsubscribe = useCallback(() => {
+    updateStatus("idle");
+    unsubcribeRef.current?.();
+    unsubcribeRef.current = undefined;
+  }, [updateStatus]);
+
+  const subscribe = useCallback(() => {
+    unsubcribeRef.current?.();
+    updateStatus("subscribing");
+    setData(initialStateRef.current);
+    unsubcribeRef.current = subscriberFnRef.current(handler, connection);
+  }, [connection, handler, updateStatus]);
+
+  useEffect(() => {
+    if (enabled) {
+      subscribe();
+    } else {
+      unsubscribe();
+    }
+
+    return () => {
+      unsubscribe();
+    };
+  }, [enabled, subscribe, unsubscribe]);
+
+  return {
+    status,
+    data,
+    reSubscribe: subscribe,
+  } as unknown as any;
+}

package/src/vitest-setup.ts

@@ -0,0 +1 @@
+import "@testing-library/jest-dom";

package/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "baseUrl": "./src",
+    "rootDir": "./src",
+    "target": "es6",
+    "module": "es6",
+    "lib": ["es6", "dom", "dom.iterable"],
+    "moduleResolution": "bundler",
+    "allowJs": true,
+    "allowSyntheticDefaultImports": true,
+    "useDefineForClassFields": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "sourceMap": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "noEmit": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noImplicitReturns": false,
+    "forceConsistentCasingInFileNames": true,
+    "jsx": "react"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}

package/vitest.config.mts

@@ -0,0 +1,21 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "jsdom",
+    setupFiles: "./src/vitest-setup.ts",
+    testTimeout: 30_000,
+    hookTimeout: 30_000,
+    css: true,
+    include: ["**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}"],
+    server: {
+      deps: {
+        inline: [],
+      },
+    },
+  },
+  resolve: {
+    alias: {},
+  },
+});