Various new features: catchAbortError, isAbortError, intersects, useIsOnline, React Query mock helpers

package.json

@@ -11,7 +11,7 @@
     "packages/*"
   ],
   "scripts": {
-    "postinstall": "manypkg check",
+    "postinstall": "patch-package && manypkg check",
     "prebuild": "yarn workspace @kablamo/rollup-plugin-resolve-externals run build && yarn workspace @kablamo/kerosene run build",
     "build": "yarn workspaces run build",
     "clean": "yarn workspaces run clean",
@@ -27,7 +27,7 @@
     "preset": "ts-jest/presets/js-with-ts",
     "testEnvironment": "jsdom",
     "setupFilesAfterEnv": [
-      "./testSetup.ts"
+      "<rootDir>/testSetup.ts"
     ],
     "transform": {
       "^.+\\.(?:[jt]sx?)$": [
@@ -53,11 +53,11 @@
     "@types/jest": "^29.5.14",
     "@types/jest-when": "^3.5.5",
     "@types/lodash": "^4.17.13",
-    "@types/node": "^22.9.0",
+    "@types/node": "^22.10.1",
     "@types/react": "^18.3.12",
     "@types/react-dom": "^18.3.1",
-    "@typescript-eslint/eslint-plugin": "^8.13.0",
-    "@typescript-eslint/parser": "^8.13.0",
+    "@typescript-eslint/eslint-plugin": "^8.16.0",
+    "@typescript-eslint/parser": "^8.16.0",
     "core-js": "^3.39.0",
     "eslint": "^8.57.1",
     "eslint-config-prettier": "^9.1.0",
@@ -70,11 +70,13 @@
     "jsdom-global": "^3.0.2",
     "lodash": "^4.17.21",
     "npm-run-all": "^4.1.5",
-    "prettier": "^3.3.3",
+    "patch-package": "^8.0.0",
+    "postinstall-postinstall": "^2.1.0",
+    "prettier": "^3.4.1",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "rimraf": "^6.0.1",
     "ts-jest": "^29.2.5",
-    "typescript": "^5.6.3"
+    "typescript": "^5.7.2"
   }
 }

packages/eslint-config/package.json

@@ -25,8 +25,8 @@
   },
   "dependencies": {
     "@kablamo/eslint-plugin": "^2.0.1",
-    "@typescript-eslint/eslint-plugin": "^8.13.0",
-    "@typescript-eslint/parser": "^8.13.0",
+    "@typescript-eslint/eslint-plugin": "^8.16.0",
+    "@typescript-eslint/parser": "^8.16.0",
     "eslint-config-airbnb": "^19.0.4",
     "eslint-config-prettier": "^9.1.0",
     "eslint-import-resolver-node": "^0.3.9",

packages/kerosene-test/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kablamo/kerosene-test",
-  "version": "0.0.18",
+  "version": "0.0.19",
   "repository": "https://github.com/KablamoOSS/kerosene/tree/master/packages/kerosene-test",
   "bugs": {
     "url": "https://github.com/KablamoOSS/kerosene/issues"
@@ -46,19 +46,26 @@
     "utils"
   ],
   "dependencies": {
-    "@kablamo/kerosene": "^0.0.45",
+    "@kablamo/kerosene": "^0.0.46",
     "lodash": "^4.17.21",
     "sinon": "^19.0.2"
   },
   "devDependencies": {
+    "@tanstack/react-query": "^5.62.0",
     "@types/lodash": "^4.17.13",
     "@types/sinon": "^17.0.3",
     "react": "^18.3.1",
     "react-dom": "^18.3.1"
   },
   "peerDependencies": {
-    "react": ">=16.8.6",
-    "react-dom": ">=16.8.6"
+    "@tanstack/react-query": ">=5.0.0 <6.0.0",
+    "react": ">=18.3.1",
+    "react-dom": ">=18.3.1"
+  },
+  "peerDependenciesMeta": {
+    "@tanstack/react-query": {
+      "optional": true
+    }
   },
   "scripts": {
     "build": "tsc",

packages/kerosene-test/readme.md

@@ -18,6 +18,26 @@ Creates a StubComponent for unit testing.
 
 Creates a stub React Context for unit testing.
 
+### `createQueryObserverBaseResult(queryKey?)`
+
+Creates a fake query observer result useful for mocking React Query.
+
+### `createQueryObserverSuccessResult(data, queryKey?)`
+
+Creates a fake query observer success result useful for mocking React Query.
+
+### `createQueryObserverRefetchErrorResult(data, error, queryKey?)`
+
+Creates a fake query observer refetch error result useful for mocking React Query.
+
+### `createQueryObserverLoadingErrorResult(error, queryKey?)`
+
+Creates a fake query observer loading error result useful for mocking React Query.
+
+### `createQueryObserverLoadingResult(queryKey?)`
+
+Creates a fake query observer loading result useful for mocking React Query.
+
 ### Stubs
 
 #### `createStubStyles(classNames, values?)`

packages/kerosene-test/src/index.ts

@@ -2,6 +2,7 @@ export * from "./jest";
 
 export { default as createStubComponent } from "./react/createStubComponent";
 export { default as createStubContext } from "./react/createStubContext";
+export * from "./react/reactQuery";
 
 export * from "./sinon";
 

packages/kerosene-ui/src/components/Boundaries/testHelpers.ts → packages/kerosene-test/src/react/reactQuery.ts

@@ -1,4 +1,7 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
 import type {
+  DataTag,
+  QueryKey,
   QueryObserverBaseResult,
   QueryObserverLoadingErrorResult,
   QueryObserverLoadingResult,
@@ -10,7 +13,12 @@ import { noop } from "lodash";
 function createQueryObserverBaseResult<
   TData = unknown,
   TError = unknown,
->(): QueryObserverBaseResult<TData, TError> {
+  TQueryKey extends QueryKey = any[],
+>(
+  queryKey: TQueryKey = [] as unknown as TQueryKey,
+): QueryObserverBaseResult<TData, TError> & {
+  queryKey: DataTag<TQueryKey, TData>;
+} {
   return {
     data: undefined,
     dataUpdatedAt: 0,
@@ -37,14 +45,22 @@ function createQueryObserverBaseResult<
     refetch: jest.fn(),
     status: "pending",
     fetchStatus: "idle",
+    queryKey: queryKey as DataTag<TQueryKey, TData>,
   };
 }
 
-export function createQueryObserverSuccessResult<TData, TError = never>(
+export function createQueryObserverSuccessResult<
+  TData,
+  TError = never,
+  TQueryKey extends QueryKey = any[],
+>(
   data: TData,
-): QueryObserverSuccessResult<TData, TError> {
+  queryKey?: TQueryKey,
+): QueryObserverSuccessResult<TData, TError> & {
+  queryKey: DataTag<TQueryKey, TData>;
+} {
   return {
-    ...createQueryObserverBaseResult<TData, TError>(),
+    ...createQueryObserverBaseResult<TData, TError, TQueryKey>(queryKey),
     data,
     error: null,
     isError: false,
@@ -61,9 +77,16 @@ export function createQueryObserverSuccessResult<TData, TError = never>(
 export function createQueryObserverRefetchErrorResult<
   TData = unknown,
   TError = unknown,
->(data: TData, error: TError): QueryObserverRefetchErrorResult<TData, TError> {
+  TQueryKey extends QueryKey = any[],
+>(
+  data: TData,
+  error: TError,
+  queryKey?: TQueryKey,
+): QueryObserverRefetchErrorResult<TData, TError> & {
+  queryKey: DataTag<TQueryKey, TData>;
+} {
   return {
-    ...createQueryObserverBaseResult<TData, TError>(),
+    ...createQueryObserverBaseResult<TData, TError, TQueryKey>(queryKey),
     data,
     error,
     isError: true,
@@ -79,9 +102,15 @@ export function createQueryObserverRefetchErrorResult<
 export function createQueryObserverLoadingErrorResult<
   TData = unknown,
   TError = unknown,
->(error: TError): QueryObserverLoadingErrorResult<TData, TError> {
+  TQueryKey extends QueryKey = any[],
+>(
+  error: TError,
+  queryKey?: TQueryKey,
+): QueryObserverLoadingErrorResult<TData, TError> & {
+  queryKey: DataTag<TQueryKey, TData>;
+} {
   return {
-    ...createQueryObserverBaseResult<TData, TError>(),
+    ...createQueryObserverBaseResult<TData, TError, TQueryKey>(queryKey),
     data: undefined,
     error,
     isError: true,
@@ -97,9 +126,14 @@ export function createQueryObserverLoadingErrorResult<
 export function createQueryObserverLoadingResult<
   TData = unknown,
   TError = unknown,
->(): QueryObserverLoadingResult<TData, TError> {
+  TQueryKey extends QueryKey = any[],
+>(
+  queryKey?: TQueryKey,
+): QueryObserverLoadingResult<TData, TError> & {
+  queryKey: DataTag<TQueryKey, TData>;
+} {
   return {
-    ...createQueryObserverBaseResult<TData, TError>(),
+    ...createQueryObserverBaseResult<TData, TError, TQueryKey>(queryKey),
     data: undefined,
     error: null,
     isError: false,

packages/kerosene-ui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kablamo/kerosene-ui",
-  "version": "0.0.45",
+  "version": "0.0.46",
   "repository": "https://github.com/KablamoOSS/kerosene/tree/master/packages/kerosene-ui",
   "bugs": {
     "url": "https://github.com/KablamoOSS/kerosene/issues"
@@ -35,16 +35,16 @@
     "node": ">=18.12.0"
   },
   "dependencies": {
-    "@kablamo/kerosene": "^0.0.45",
+    "@kablamo/kerosene": "^0.0.46",
     "lodash": "^4.17.21",
     "use-sync-external-store": "^1.2.2"
   },
   "devDependencies": {
-    "@kablamo/kerosene-test": "^0.0.18",
+    "@kablamo/kerosene-test": "^0.0.19",
     "@kablamo/rollup-plugin-resolve-externals": "^0.0.2",
     "@optimize-lodash/rollup-plugin": "^5.0.0",
     "@sinonjs/fake-timers": "^13.0.5",
-    "@tanstack/react-query": "^5.59.20",
+    "@tanstack/react-query": "^5.62.0",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/react": "^16.0.1",
     "@testing-library/user-event": "^14.5.2",
@@ -58,7 +58,7 @@
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "react-error-boundary": "^4.1.2",
-    "rollup": "^4.25.0",
+    "rollup": "^4.28.0",
     "rollup-plugin-esbuild": "^6.1.1"
   },
   "peerDependencies": {

packages/kerosene-ui/readme.md

@@ -50,6 +50,10 @@ Custom hook which applies a CSS `property` `value` with `priority` to the elemen
 
 Custom hook that makes `setInterval` work declaritively with hooks. See https://overreacted.io/making-setinterval-declarative-with-react-hooks/ for more details.
 
+### `useIsOnline()`
+
+Custom hook which returns the current value of `navigator.onLine`, watching for changes via the `"online"` and `"offline"` events.
+
 ### `useKonamiCode(code, callback)`
 
 Custom hook which listens for keydown events for the specified `code` and triggers the callback when the code is entered.

packages/kerosene-ui/src/components/Boundaries/QueriesBoundary.spec.tsx

@@ -1,4 +1,5 @@
 import { Deferred, type DistributiveOmit } from "@kablamo/kerosene";
+import { createQueryObserverLoadingErrorResult } from "@kablamo/kerosene-test";
 import {
   useQuery,
   QueryClientProvider,
@@ -14,7 +15,6 @@ import QueriesBoundary, {
   AggregateQueriesError,
   type QueriesBoundaryProps,
 } from "./QueriesBoundary";
-import { createQueryObserverLoadingErrorResult } from "./testHelpers";
 
 const error = new Error("an error");
 const rejectedPromise = Promise.reject(error);

packages/kerosene-ui/src/components/Boundaries/QueryBoundary.spec.tsx

@@ -1,4 +1,5 @@
 import { Deferred, type DistributiveOmit } from "@kablamo/kerosene";
+import { createQueryObserverLoadingErrorResult } from "@kablamo/kerosene-test";
 import {
   useQuery,
   QueryClientProvider,
@@ -10,7 +11,6 @@ import { noop } from "lodash";
 import * as React from "react";
 import type { FallbackProps } from "react-error-boundary";
 import QueryBoundary, { type QueryBoundaryProps } from "./QueryBoundary";
-import { createQueryObserverLoadingErrorResult } from "./testHelpers";
 
 const error = new Error("an error");
 const rejectedPromise = Promise.reject(error);
@@ -31,7 +31,7 @@ describe("QueryBoundary", () => {
       expected: "data",
       props: {
         // eslint-disable-next-line react/jsx-no-useless-fragment
-        children: ({ data }) => <>{data}</>,
+        children: ({ data }) => <>{data as string}</>,
         errorFallback: <>errorFallback</>,
       },
       value: "data",

packages/kerosene-ui/src/hooks/useIsOnline.spec.ts

@@ -0,0 +1,46 @@
+import { stubProperties } from "@kablamo/kerosene-test";
+import { renderHook } from "@testing-library/react";
+import { identity } from "lodash";
+import { act } from "react";
+import useIsOnline from "./useIsOnline";
+
+describe("useIsOnline", () => {
+  let restoreNavigator: () => void;
+  let onLine: boolean;
+  const update = (_onLine: boolean) => {
+    onLine = _onLine;
+    const event = new Event(onLine ? "online" : "offline", {
+      cancelable: false,
+    });
+    act(() => {
+      window.dispatchEvent(event);
+    });
+  };
+  beforeEach(() => {
+    onLine = true;
+    restoreNavigator = stubProperties(navigator, {
+      onLine: { configurable: true, get: () => onLine },
+    });
+  });
+
+  afterEach(() => {
+    restoreNavigator();
+  });
+
+  it("should always return true during hydration and update after", () => {
+    update(false);
+
+    const monitor = jest.fn<boolean, [boolean]>(identity);
+    const utils = renderHook(() => monitor(useIsOnline()), { hydrate: true });
+
+    // Hydration
+    expect(monitor.mock.calls[0]![0]).toBe(true);
+
+    expect(utils.result.current).toEqual(false);
+
+    update(true);
+    expect(utils.result.current).toEqual(true);
+
+    utils.unmount();
+  });
+});

packages/kerosene-ui/src/hooks/useIsOnline.ts

@@ -0,0 +1,26 @@
+import * as React from "react";
+
+function getSnapshot() {
+  return navigator.onLine;
+}
+
+function getServerSnapshot() {
+  return true;
+}
+
+function subscribe(callback: () => void) {
+  window.addEventListener("online", callback);
+  window.addEventListener("offline", callback);
+  return () => {
+    window.removeEventListener("online", callback);
+    window.removeEventListener("offline", callback);
+  };
+}
+
+/**
+ * Custom hook which returns the current value of `navigator.onLine`, watching for changes via the
+ * `"online"` and `"offline"` events
+ */
+export default function useIsOnline() {
+  return React.useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}