feat: export discriminant match predicate

src/createEffectWhen/__tests__/createEffectWhen.test.ts

@@ -1,7 +1,8 @@
 import { renderHook } from "@testing-library/react";
 import { describe, expect, expectTypeOf, it, vi } from "vitest";
-import { createEffectWhen } from "..";
 import { predicates } from "../../useEffectWhen";
+import { matchPredicate } from "../../useEffectWhenMatch";
+import { createEffectWhen } from "../createEffectWhen";
 import { tuple } from "./createEffectWhen.utils";
 import type { ReadyDeps } from "../../useEffectWhen";
 import type { DependencyList } from "react";
@@ -10,6 +11,11 @@ interface TestUser {
   id: string;
 }
 
+type QueryState =
+  | { status: "idle" }
+  | { status: "success"; data: string }
+  | { status: "error"; error: Error };
+
 const truthy = (deps: DependencyList): boolean => predicates.truthy(deps);
 const readyPair = (
   deps: [string | null, number | null]
@@ -124,5 +130,26 @@ describe("createEffectWhen", () => {
 
       expect(effect).toHaveBeenCalledWith(["hello", 42]);
     });
+
+    it("should compose matchPredicate into a reusable narrowed hook", () => {
+      const useEffectWhenQuerySettled = createEffectWhen(
+        matchPredicate<"status", QueryState, "success" | "error">("status", ["success", "error"])
+      );
+      const effect = vi.fn();
+
+      renderHook(() =>
+        useEffectWhenQuerySettled(
+          ([query]) => {
+            expectTypeOf(query).toEqualTypeOf<
+              Extract<QueryState, { status: "success" | "error" }>
+            >();
+            effect(query.status);
+          },
+          [{ status: "success", data: "result" }]
+        )
+      );
+
+      expect(effect).toHaveBeenCalledWith("success");
+    });
   });
 });

src/index.ts

@@ -2,7 +2,7 @@ export { useEffectWhen, predicates } from "./useEffectWhen";
 export { useEffectWhenReady } from "./useEffectWhenReady";
 export { useEffectWhenTruthy } from "./useEffectWhenTruthy";
 export { useEffectWhenChanged } from "./useEffectWhenChanged";
-export { useEffectWhenMatch } from "./useEffectWhenMatch";
+export { matchPredicate, useEffectWhenMatch } from "./useEffectWhenMatch";
 export { createEffectWhen } from "./createEffectWhen";
 export type {
   Falsy,

src/useEffectWhenMatch/index.ts

@@ -1,2 +1,3 @@
 export { useEffectWhenMatch } from "./useEffectWhenMatch";
+export { matchPredicate } from "./useEffectWhenMatch.utils";
 export type { Discriminant, MatchedDeps } from "./useEffectWhenMatch.types";

src/useEffectWhenMatch/useEffectWhenMatch.ts

@@ -1,7 +1,7 @@
 import { useEffectWhen } from "../useEffectWhen";
-import { isMatch } from "./useEffectWhenMatch.utils";
-import type { UseEffectWhenEffect, UseEffectWhenOptions } from "../useEffectWhen";
+import { matchPredicate } from "./useEffectWhenMatch.utils";
 import type { Discriminant, MatchedDeps } from "./useEffectWhenMatch.types";
+import type { UseEffectWhenEffect, UseEffectWhenOptions } from "../useEffectWhen";
 
 /**
  * Gates an effect on a discriminated union at `deps[0]` whose field at `key`
@@ -23,5 +23,5 @@ export function useEffectWhenMatch<
   value: V | ReadonlyArray<V>,
   options?: UseEffectWhenOptions<readonly [Q]>
 ): void {
-  useEffectWhen(effect, deps, isMatch<K, Q, V>(key, value), options);
+  useEffectWhen(effect, deps, matchPredicate<K, Q, V>(key, value), options);
 }

src/useEffectWhenMatch/useEffectWhenMatch.utils.ts

@@ -1,5 +1,5 @@
-import type { GuardPredicate } from "../useEffectWhen";
 import type { Discriminant, MatchedDeps } from "./useEffectWhenMatch.types";
+import type { GuardPredicate } from "../useEffectWhen";
 
 function isReadonlyArray<T>(value: T | ReadonlyArray<T>): value is ReadonlyArray<T> {
   return Array.isArray(value);
@@ -9,7 +9,7 @@ function includesValue<T>(values: ReadonlyArray<T>, candidate: T): boolean {
   return values.includes(candidate);
 }
 
-export function isMatch<K extends PropertyKey, Q extends Discriminant<K>, V extends Q[K]>(
+export function matchPredicate<K extends PropertyKey, Q extends Discriminant<K>, V extends Q[K]>(
   key: K,
   value: V | ReadonlyArray<V>
 ): GuardPredicate<readonly [Q], MatchedDeps<K, Q, V>> {