@pixotope/query 0.0.1

package/src/useQuery.test.ts

@@ -0,0 +1,282 @@
+import { fireEvent } from "@testing-library/dom";
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { vi, describe, beforeEach, it, expect, test } from "vitest";
+
+import { useQuery } from "./useQuery";
+import { MockUseQueryUtils } from "./mock/useQuery";
+const mockQueryKey = ["dummyQK"];
+
+function until(condition: boolean) {
+  return new Promise((resolve, reject) => {
+    if (condition) {
+      resolve(null);
+    } else {
+      reject();
+    }
+  });
+}
+
+describe("useQuery", () => {
+  let defaultQueryMock: MockUseQueryUtils;
+
+  beforeEach(() => {
+    defaultQueryMock = new MockUseQueryUtils({});
+  });
+
+  it("should call queryFn by on mount by default", () => {
+    const mockFunction = vi.fn(() => defaultQueryMock.getMockedQueryFn());
+    renderHook(() =>
+      useQuery({
+        queryFn: mockFunction,
+        key: mockQueryKey,
+      })
+    );
+
+    expect(mockFunction).toBeCalledTimes(1);
+  });
+  it("should be in loading state on mount", () => {
+    const { result } = renderHook(() =>
+      useQuery({
+        queryFn: () => defaultQueryMock.getMockedQueryFn(),
+        key: mockQueryKey,
+      })
+    );
+
+    expect(result.current.status).toBe("loading");
+  });
+  it("should be in success state after queryFn resolves", async () => {
+    const { result } = renderHook(() =>
+      useQuery({
+        queryFn: () => defaultQueryMock.getMockedQueryFn(),
+        key: mockQueryKey,
+      })
+    );
+    act(() => {
+      defaultQueryMock.resolve();
+    });
+    await waitFor(() => until(result.current.status === "success"), {
+      timeout: 1000,
+    });
+  });
+  it("should be in error state after queryFn rejects", async () => {
+    const { result } = renderHook(() =>
+      useQuery({
+        queryFn: () => defaultQueryMock.getMockedQueryFn(),
+        key: mockQueryKey,
+      })
+    );
+    act(() => defaultQueryMock.reject());
+    await waitFor(() => until(result.current.status === "error"), {
+      timeout: 1000,
+    });
+    expect(result.current.status).toBe("error");
+  });
+  it("should be in timeout state after queryFn rejects with timeout", async () => {
+    const { result } = renderHook(() =>
+      useQuery({
+        queryFn: () => defaultQueryMock.getMockedQueryFn(),
+        key: mockQueryKey,
+        timeout: 0.01,
+      })
+    );
+    await waitFor(() => until(result.current.status === "error"), {
+      timeout: 1000,
+    });
+    expect(result.current.status === "error");
+  });
+  it("should be in success state after queryFn resolves with initialData", async () => {
+    const { result } = renderHook(() =>
+      useQuery({
+        queryFn: () => defaultQueryMock.getMockedQueryFn(),
+        key: mockQueryKey,
+        initialData: "test-test",
+      })
+    );
+    defaultQueryMock.resolve();
+    await waitFor(() => until(result.current.status === "success"), {
+      timeout: 1000,
+    });
+  });
+  it("should be in idle state if enabled is false", async () => {
+    const { result } = renderHook(() =>
+      useQuery({
+        queryFn: () => defaultQueryMock.getMockedQueryFn(),
+        key: mockQueryKey,
+        enabled: false,
+      })
+    );
+    expect(result.current.status).toBe("idle");
+  });
+  test("refetch should trigger query function", async () => {
+    const resolver = vi.fn(() => defaultQueryMock.getMockedQueryFn());
+    const { result } = await act(() =>
+      renderHook(() =>
+        useQuery({
+          queryFn: resolver,
+          key: mockQueryKey,
+        })
+      )
+    );
+    await act(() => defaultQueryMock.resolve());
+    await waitFor(() => until(result.current.status === "success"), {
+      timeout: 1000,
+    });
+    await act(() => result.current.refetch());
+    expect(resolver).toBeCalledTimes(2);
+  });
+  test("select should return selected right data", async () => {
+    const queryMock = new MockUseQueryUtils({
+      foo: "bar",
+      baz: "qux",
+    });
+    const { result } = renderHook(() =>
+      useQuery({
+        queryFn: () => queryMock.getMockedQueryFn(),
+        key: mockQueryKey,
+        select: (data) => data?.foo,
+      })
+    );
+    expect(result.current.data).toBeUndefined();
+    queryMock.resolve();
+    await waitFor(() => until(result.current.data !== undefined), {
+      timeout: 1000,
+    });
+    expect(result.current.data).toBe("bar");
+  });
+  test("onSuccess should be called after queryFn resolves", async () => {
+    const onSuccess = vi.fn();
+    renderHook(() =>
+      useQuery({
+        queryFn: () => defaultQueryMock.getMockedQueryFn(),
+        key: mockQueryKey,
+        onSuccess,
+      })
+    );
+    await act(() => defaultQueryMock.resolve());
+    await waitFor(() => {}, {
+      timeout: 1000,
+    });
+    expect(onSuccess).toBeCalledTimes(1);
+  });
+  test("onError should be called after queryFn rejects", async () => {
+    const onError = vi.fn();
+    renderHook(() =>
+      useQuery({
+        queryFn: () => defaultQueryMock.getMockedQueryFn(),
+        key: mockQueryKey,
+        onError,
+      })
+    );
+    await act(() => defaultQueryMock.reject());
+    await waitFor(() => {}, {
+      timeout: 1000,
+    });
+    expect(onError).toBeCalledTimes(1);
+  });
+  test("onSettled should be called after queryFn resolves", async () => {
+    const onSettled = vi.fn();
+    renderHook(() =>
+      useQuery({
+        queryFn: () => defaultQueryMock.getMockedQueryFn(),
+        key: mockQueryKey,
+        onSettled,
+      })
+    );
+    await act(() => defaultQueryMock.resolve());
+    await waitFor(() => {}, {
+      timeout: 1000,
+    });
+    expect(onSettled).toBeCalledTimes(1);
+  });
+  test("onSettled should be called after queryFn rejects", async () => {
+    const onSettled = vi.fn();
+    renderHook(() =>
+      useQuery({
+        queryFn: () => defaultQueryMock.getMockedQueryFn(),
+        key: mockQueryKey,
+        onSettled,
+      })
+    );
+    await act(() => defaultQueryMock.reject());
+    await waitFor(() => {}, {
+      timeout: 1000,
+    });
+    expect(onSettled).toBeCalledTimes(1);
+  });
+  test("refetch is triggered on window focus", async () => {
+    const resolver = vi.fn(() => defaultQueryMock.getMockedQueryFn());
+    const { result } = await act(() =>
+      renderHook(() =>
+        useQuery({
+          queryFn: resolver,
+          refetchOnWindowFocus: true,
+          key: mockQueryKey,
+        })
+      )
+    );
+    await act(() => defaultQueryMock.resolve());
+    await waitFor(() => until(result.current.status === "success"), {
+      timeout: 1000,
+    });
+    await act(() => fireEvent(window, new FocusEvent("focus")));
+    expect(resolver).toBeCalledTimes(2);
+  });
+  test("refetch interval should work", async () => {
+    const resolver = vi.fn(() => defaultQueryMock.getMockedQueryFn());
+    const { result } = renderHook(() =>
+      useQuery({
+        queryFn: resolver,
+        refetchInterval: 10,
+        key: mockQueryKey,
+      })
+    );
+    await act(() => defaultQueryMock.resolve());
+    await waitFor(() => until(result.current.status === "success"), {
+      timeout: 1000,
+    });
+    waitFor(() => until(resolver.call.length > 1), { timeout: 1000 });
+  });
+  test("refetch should automatically trigger if queryKey is changed", async () => {
+    const resolver = vi.fn(() => defaultQueryMock.getMockedQueryFn());
+    const { result, rerender } = await act(() =>
+      renderHook(
+        (props) =>
+          useQuery({
+            queryFn: props.resolver,
+            key: props.key,
+          }),
+        {
+          initialProps: {
+            key: ["dummyQK1"],
+            resolver,
+          },
+        }
+      )
+    );
+    await act(() => defaultQueryMock.resolve());
+    await waitFor(() => until(result.current.status === "success"), {
+      timeout: 1000,
+    });
+    rerender({ key: ["dummyQK2"], resolver });
+    rerender({ key: ["dummyQK2"], resolver });
+    expect(resolver).toBeCalledTimes(2);
+  });
+  test("stateless mode", async () => {
+    const resolver = vi.fn(() => defaultQueryMock.getMockedQueryFn());
+    const { result } = renderHook(() =>
+      useQuery({
+        queryFn: resolver,
+        key: mockQueryKey,
+        stateless: true,
+      })
+    );
+    await act(() => defaultQueryMock.resolve());
+    await waitFor(() => until(result.current.status === "success"), {
+      timeout: 1000,
+    });
+
+    // Here ts should kick in and complain about but for testing purposes, all good
+    // @ts-ignore
+    expect(result.current.data).toBeUndefined();
+  });
+});

package/src/useQuery.ts

@@ -0,0 +1,302 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+export interface QueryOptions<
+  TData = unknown,
+  TError = unknown,
+  TParams = void,
+  TSelectData = TData,
+  Stateless extends true | undefined = undefined,
+> {
+  queryFn: (params: TParams | undefined | void) => Promise<TData>;
+  onSuccess?: (data: TData) => Promise<void> | void;
+  onError?: (error: TError) => Promise<void> | void;
+  onSettled?: (
+    data: TData | undefined,
+    error: TError | undefined
+  ) => Promise<void> | void;
+  timeout?: number;
+  enabled?: boolean;
+  initialData?: TData | Functionize<TData>;
+  select?: (data: TData) => TSelectData;
+  refetchOnWindowFocus?: boolean;
+  refetchInterval?: number;
+  compareOrThrow?: (data: TData) => boolean;
+  stateless?: Stateless;
+  key?: TQueryKey;
+}
+
+type Functionize<T> = () => T;
+type QueryStatus = "idle" | "loading" | "success" | "error" | "timeout";
+type RaceErrorReason = "timeout";
+type RacePromises<T> = Promise<T | RaceErrorReason>;
+type WithData<TData> = { data: TData | undefined };
+type TQueryKey = readonly any[];
+
+export type UseQueryResult<
+  TData = unknown,
+  TError = unknown,
+  TParams = void,
+  TSelectData = TData,
+  Stateless extends true | undefined = undefined,
+> = {
+  error: TError | null;
+  status: QueryStatus;
+  refetch: (params: TParams | void | undefined) => Promise<void>;
+  reset: () => void;
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+} & (Stateless extends true ? {} : WithData<TSelectData>);
+
+function normalizeQueryKey(queryKey: TQueryKey): string {
+  return JSON.stringify(queryKey);
+}
+
+type TInternalCallbackRef<TData, TError, TSelectData> = {
+  onError?: (error: TError) => Promise<void> | void;
+  onSuccess?: (data: TData) => Promise<void> | void;
+  onSettled?: (
+    data: TData | undefined,
+    error: TError | undefined
+  ) => Promise<void> | void;
+  compareOrThrow?: (data: TData) => boolean;
+  select?: (data: TData) => TSelectData;
+};
+
+type TInternalOptionsRef<TData> = {
+  timeout?: number;
+  enabled: boolean;
+  refetchOnWindowFocus: boolean;
+  refetchInterval: number;
+  compareOrThrow?: (data: TData) => boolean;
+  stateless?: boolean;
+};
+
+export const useQuery = <
+  TData = unknown,
+  TError = unknown,
+  TParams = void,
+  TSelected = TData,
+  Stateless extends true | undefined = undefined,
+>({
+  queryFn,
+  ...options
+}: QueryOptions<TData, TError, TParams, TSelected, Stateless>): UseQueryResult<
+  TSelected,
+  TError,
+  TParams,
+  TSelected,
+  Stateless
+> => {
+  const {
+    enabled = true,
+    refetchOnWindowFocus = false,
+    refetchInterval = 0,
+    initialData,
+    select,
+    onError,
+    onSuccess,
+    onSettled,
+    timeout,
+    compareOrThrow,
+    stateless,
+    key: queryKeyPassed,
+  } = options;
+  const queryKey = normalizeQueryKey(queryKeyPassed ?? []);
+  const promiseResolutionInProgress = useRef(false);
+  const lastFetchedAt = useRef<number | null>(null);
+  const lastQueryKey = useRef<string | undefined>(undefined);
+  const queryFnRef = useRef(queryFn);
+  queryFnRef.current = queryFn;
+  const internalCallbackRef = useRef<
+    TInternalCallbackRef<TData, TError, TSelected>
+  >({});
+  internalCallbackRef.current = {
+    onError,
+    onSuccess,
+    onSettled,
+    compareOrThrow,
+    select,
+  };
+  const internalOptionsRef = useRef<TInternalOptionsRef<TData>>({
+    enabled,
+    refetchOnWindowFocus,
+    refetchInterval,
+    compareOrThrow,
+    stateless,
+    timeout,
+  });
+  internalOptionsRef.current = {
+    enabled,
+    refetchOnWindowFocus,
+    refetchInterval,
+    compareOrThrow,
+    stateless,
+    timeout,
+  };
+
+  const [status, setStatus] = useState<QueryStatus>(() => {
+    return "idle";
+  });
+  const [error, setError] = useState<TError | null>(null);
+  const [data, setData] = useState<TData | undefined>(() => {
+    if (initialData !== undefined) {
+      if (typeof initialData === "function") {
+        return (initialData as Functionize<TData>)();
+      }
+
+      return initialData as TData;
+    }
+
+    return undefined;
+  });
+
+  const handleSetData = useCallback((data: TData) => {
+    if (internalOptionsRef.current.stateless) {
+      return;
+    }
+
+    setData(data);
+  }, []);
+
+  const shouldRefetch = useCallback(() => {
+    if (!internalOptionsRef.current.enabled) {
+      return false;
+    }
+
+    if (lastFetchedAt.current === null) {
+      return true;
+    }
+
+    return (
+      new Date().getTime() - lastFetchedAt.current >
+      internalOptionsRef.current?.refetchInterval
+    );
+  }, []);
+
+  const refetch = useCallback(
+    async (params: TParams | void | undefined = undefined) => {
+      if (
+        promiseResolutionInProgress.current ||
+        !internalOptionsRef.current.enabled
+      ) {
+        return;
+      }
+
+      setStatus("loading");
+      setError(null);
+
+      try {
+        const promises: RacePromises<TData>[] = [
+          queryFnRef.current(params),
+          ...(internalOptionsRef.current.timeout
+            ? [
+                new Promise<RaceErrorReason>((resolve) =>
+                  setTimeout(
+                    () => resolve("timeout"),
+                    internalOptionsRef.current.timeout
+                  )
+                ),
+              ]
+            : []),
+        ];
+
+        promiseResolutionInProgress.current = true;
+        const res = await Promise.race(promises);
+        promiseResolutionInProgress.current = false;
+
+        if (res === "timeout") {
+          throw new Error("timeout");
+        }
+
+        handleSetData(res);
+
+        if (
+          internalCallbackRef.current.compareOrThrow &&
+          internalCallbackRef.current.compareOrThrow(res) === true
+        ) {
+          throw new Error("compareOrThrow");
+        }
+
+        setStatus("success");
+        lastFetchedAt.current = new Date().getTime();
+        internalCallbackRef.current.onSuccess?.(res);
+        internalCallbackRef.current.onSettled?.(res, undefined);
+      } catch (error: any) {
+        setError(error);
+        setStatus("error");
+        internalCallbackRef.current.onError?.(error);
+        internalCallbackRef.current.onSettled?.(undefined, error);
+      }
+    },
+    [handleSetData]
+  );
+
+  const reset = useCallback(() => {
+    setData(undefined);
+    setStatus("idle");
+    setError(null);
+    refetch();
+  }, [refetch]);
+
+  useEffect(() => {
+    if (enabled) {
+      refetch();
+    }
+  }, [enabled, refetch, queryKey]);
+
+  useEffect(() => {
+    if (lastQueryKey.current === undefined) {
+      lastQueryKey.current = queryKey;
+      refetch();
+      return;
+    }
+
+    if (queryKey !== lastQueryKey.current) {
+      lastQueryKey.current = queryKey;
+      refetch();
+    }
+  }, [queryKey, refetch, enabled]);
+
+  useEffect(() => {
+    if (refetchOnWindowFocus) {
+      const queryHandleFocus = () => {
+        if (shouldRefetch()) {
+          refetch();
+        }
+      };
+
+      window.addEventListener("focus", queryHandleFocus);
+
+      return () => {
+        window.removeEventListener("focus", queryHandleFocus);
+      };
+    }
+  }, [refetchOnWindowFocus, refetch, shouldRefetch]);
+
+  useEffect(() => {
+    if (refetchInterval !== 0) {
+      const interval = setInterval(
+        () => {
+          if (shouldRefetch()) {
+            refetch();
+          }
+        },
+        Math.max(refetchInterval, 1000)
+      );
+
+      return () => {
+        clearInterval(interval);
+      };
+    }
+  }, [refetch, refetchInterval, shouldRefetch]);
+
+  return {
+    data:
+      select && data !== undefined
+        ? select(data as TData)
+        : (data as unknown as TSelected),
+    error,
+    status,
+    refetch,
+    reset,
+  };
+};

package/src/useSubscription.ts

@@ -0,0 +1,87 @@
+import type { DHClientWebSocketProxy } from "@pixotope/zmq-client";
+import {
+  SubscriptionCoreOptions,
+  useSubscriptionCore,
+} from "./useSubscriptionCore";
+
+export type SubscriptionOptions<
+  TData,
+  TMessage = unknown,
+  Stateless extends true | undefined = undefined,
+> = Omit<
+  SubscriptionCoreOptions<TData, TMessage, Stateless>,
+  "subscriberFn"
+> & {
+  service: string;
+  topic: string;
+  maxDownwardDepth?: number;
+};
+
+export type TSubscriptionHandlerFunction<TMessage> = (opts: {
+  service: string;
+  topic: string;
+  callback: (message: TMessage) => void;
+  maxDownwardDepth?: number;
+}) => () => void;
+
+export function useSubscription<
+  TData = unknown,
+  TMessage = TData,
+  Stateless extends true | undefined = undefined,
+>(
+  subscriptionHandler: TSubscriptionHandlerFunction<TMessage>,
+  options: SubscriptionOptions<TData, TMessage, Stateless>
+) {
+  const { topic, service, maxDownwardDepth = 1000 } = options;
+
+  return useSubscriptionCore<TData, TMessage, Stateless>({
+    ...options,
+    subscriberFn: (handler) => {
+      const unsubscribe = subscriptionHandler({
+        service,
+        topic,
+        callback: (message: TMessage) => {
+          handler(message);
+        },
+        maxDownwardDepth,
+      });
+
+      return unsubscribe;
+    },
+  });
+}
+
+export function buildServiceSubscriptionHook(
+  subscriptionHandler: TSubscriptionHandlerFunction<unknown>,
+  targetMachine: (machine: string | undefined) => string
+) {
+  return function useSubscriptionBuilder<
+    TData,
+    TMessage = TData,
+    Stateless extends true | undefined = undefined,
+  >(
+    options: Omit<
+      SubscriptionOptions<TData, TMessage, Stateless>,
+      "service"
+    > & {
+      machine?: string;
+    }
+  ) {
+    const targetService = targetMachine(options.machine);
+    return useSubscription<TData, TMessage, Stateless>(
+      <TSubscriptionHandlerFunction<TMessage>>subscriptionHandler,
+      {
+        service: targetService,
+        ...options,
+      }
+    );
+  };
+}
+
+export function bindClientSocketProxy(
+  socketClientProxy: DHClientWebSocketProxy
+) {
+  return (
+    ...args: Parameters<Parameters<typeof buildServiceSubscriptionHook>[0]>
+  ) => socketClientProxy.mirror(...args)[0];
+}