@intrig/plugin-react 0.0.1

package/src/lib/templates/docs/__snapshots__/async-hook.spec.ts.snap

@@ -0,0 +1,889 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`reactAsyncFunctionHookDocs > snapshot — path params only (no request body) 1`] = `
+"# Intrig Async Hooks — Quick Guide
+
+## Copy-paste starter (fast lane)
+
+### 1) Hook import
+
+\`\`\`ts
+import { useVerifyUserByIdAsync } from "@intrig/react/users/{id}/client";
+\`\`\`
+
+### 2) Create an instance
+
+\`\`\`ts
+const [verifyUserById, abortVerifyUserById] = useVerifyUserByIdAsync();
+\`\`\`
+
+### 3) Call it (awaitable)
+
+\`\`\`ts
+// body?, params? — pass what your endpoint needs (order: body, params)
+await verifyUserById(verifyUserByIdParams);
+\`\`\`
+
+Async hooks are for one-off, low-friction calls (e.g., validations, submissions). They return an **awaitable function** plus an **abort** function. No NetworkState.
+
+---
+
+## TL;DR (copy–paste)
+
+\`\`\`tsx
+import { useVerifyUserByIdAsync } from "@intrig/react/users/{id}/client";
+import { useCallback, useEffect } from "react";
+
+export default function Example() {
+  const [verifyUserById, abortVerifyUserById] = useVerifyUserByIdAsync();
+
+  const run = useCallback(async () => {
+    try {
+      const result = await verifyUserById(verifyUserByIdParams);
+      // do something with result
+      console.log(result);
+    } catch (e) {
+      // request failed or was aborted
+      console.error(e);
+    }
+  }, [verifyUserById]);
+
+  // Optional: abort on unmount
+  useEffect(() => abortVerifyUserById, [abortVerifyUserById]);
+
+  return <button onClick={run}>Call</button>;
+}
+\`\`\`
+
+### Optional types (if generated by your build)
+
+\`\`\`ts
+import type { VerifyUserByIdParams } from "@intrig/react/users/{id}/VerifyUserById.params";
+import type { VerifyUserByIdResponseBody } from "@intrig/react/users/{id}/VerifyUserById.response";
+\`\`\`
+
+---
+
+## Hook API
+
+\`\`\`ts
+// Prefer concrete types if your build emits them:
+// import type { VerifyUserByIdResponseBody } from '@intrig/react/users/{id}/VerifyUserById.response';
+// import type { VerifyUserByIdParams } from '@intrig/react/users/{id}/VerifyUserById.params';
+
+type VerifyUserByIdData = unknown; // replace with VerifyUserByIdResponseBody if generated
+type VerifyUserByIdRequest = {
+  body?: unknown;
+  params?: VerifyUserByIdParams;
+};
+
+// Signature (shape shown; return type depends on your endpoint)
+declare function useVerifyUserByIdAsync(): [
+  (
+    body?: VerifyUserByIdRequest["body"],
+    params?: VerifyUserByIdRequest["params"],
+  ) => Promise<VerifyUserByIdData>,
+  () => void, // abort
+];
+\`\`\`
+
+### Why async hooks?
+
+- **No state machine:** just \`await\` the result.
+- **Great for validations & submits:** uniqueness checks, field-level checks, updates.
+- **Abortable:** cancel in-flight work on demand.
+
+---
+
+## Usage Patterns
+
+### 1) Simple try/catch (recommended)
+
+\`\`\`tsx
+const [verifyUserById] = useVerifyUserByIdAsync();
+
+try {
+  const res = await verifyUserById(verifyUserByIdParams);
+  // use res
+} catch (e) {
+  // network error or abort
+}
+\`\`\`
+
+<details><summary>Description</summary>
+<p><strong>Use when</strong> you just need the value or an error. Ideal for validators, uniqueness checks, or quick lookups.</p>
+</details>
+
+### 2) Abort on unmount (safe cleanup)
+
+\`\`\`tsx
+const [verifyUserById, abortVerifyUserById] = useVerifyUserByIdAsync();
+
+useEffect(() => abortVerifyUserById, [abortVerifyUserById]);
+\`\`\`
+
+<details><summary>Description</summary>
+<p><strong>Use when</strong> the component may unmount while a request is in-flight (route changes, conditional UI).</p>
+</details>
+
+### 3) Debounced validation (e.g., on input change)
+
+\`\`\`tsx
+const [verifyUserById, abortVerifyUserById] = useVerifyUserByIdAsync();
+
+const onChange = useMemo(() => {
+  let t: any;
+  return (value: string) => {
+    clearTimeout(t);
+    t = setTimeout(async () => {
+      try {
+        // Optionally abort before firing a new request
+        abortVerifyUserById();
+        await verifyUserById(/* body from value */, verifyUserByIdParams);
+      } catch {}
+    }, 250);
+  };
+}, [verifyUserById, abortVerifyUserById]);
+\`\`\`
+
+<details><summary>Description</summary>
+<p><strong>Use when</strong> validating as the user types. Debounce to reduce chatter; consider <code>abortVerifyUserById()</code> before firing a new call.</p>
+</details>
+
+### 4) Guard against races (latest-only)
+
+\`\`\`tsx
+const [verifyUserById, abortVerifyUserById] = useVerifyUserByIdAsync();
+
+const latestOnly = async () => {
+  abortVerifyUserById();
+  return verifyUserById(verifyUserByIdParams);
+};
+\`\`\`
+
+<details><summary>Description</summary>
+<p><strong>Use when</strong> only the most recent call should win (search suggestions, live filters).</p>
+</details>
+
+---
+
+## Full example
+
+\`\`\`tsx
+import { useVerifyUserByIdAsync } from "@intrig/react/users/{id}/client";
+import { useCallback } from "react";
+
+function MyComponent() {
+  const [verifyUserById, abortVerifyUserById] = useVerifyUserByIdAsync();
+
+  const run = useCallback(async () => {
+    try {
+      const data = await verifyUserById(verifyUserByIdParams);
+      alert(JSON.stringify(data));
+    } catch (e) {
+      console.error("Call failed/aborted", e);
+    }
+  }, [verifyUserById]);
+
+  return (
+    <>
+      <button onClick={run}>Call remote</button>
+      <button onClick={abortVerifyUserById}>Abort</button>
+    </>
+  );
+}
+\`\`\`
+
+---
+
+## Gotchas & Tips
+
+- **No \`NetworkState\`:** async hooks return a Promise, not a state machine.
+- **Abort:** always available; call it to cancel the latest in-flight request.
+- **Errors:** wrap calls with \`try/catch\` to handle network failures or abort errors.
+- **Debounce & throttle:** combine with timers to cut down chatter for typeahead/validators.
+- **Types:** prefer generated \`VerifyUserByIdResponseBody\` and \`VerifyUserByIdParams\` if your build emits them.
+
+---
+
+## Reference: Minimal cheat sheet
+
+\`\`\`ts
+const [fn, abort] = useVerifyUserByIdAsync();
+await fn(verifyUserByIdParams);
+abort(); // optional
+\`\`\`
+"
+`;
+
+exports[`reactAsyncFunctionHookDocs > snapshot — request body and path params 1`] = `
+"# Intrig Async Hooks — Quick Guide
+
+## Copy-paste starter (fast lane)
+
+### 1) Hook import
+
+\`\`\`ts
+import { useRecalculateUserScoreAsync } from "@intrig/react/users/{id}/client";
+\`\`\`
+
+### 2) Create an instance
+
+\`\`\`ts
+const [recalculateUserScore, abortRecalculateUserScore] =
+  useRecalculateUserScoreAsync();
+\`\`\`
+
+### 3) Call it (awaitable)
+
+\`\`\`ts
+// body?, params? — pass what your endpoint needs (order: body, params)
+await recalculateUserScore(
+  recalculateUserScoreRequest,
+  recalculateUserScoreParams,
+);
+\`\`\`
+
+Async hooks are for one-off, low-friction calls (e.g., validations, submissions). They return an **awaitable function** plus an **abort** function. No NetworkState.
+
+---
+
+## TL;DR (copy–paste)
+
+\`\`\`tsx
+import { useRecalculateUserScoreAsync } from "@intrig/react/users/{id}/client";
+import { useCallback, useEffect } from "react";
+
+export default function Example() {
+  const [recalculateUserScore, abortRecalculateUserScore] =
+    useRecalculateUserScoreAsync();
+
+  const run = useCallback(async () => {
+    try {
+      const result = await recalculateUserScore(
+        recalculateUserScoreRequest,
+        recalculateUserScoreParams,
+      );
+      // do something with result
+      console.log(result);
+    } catch (e) {
+      // request failed or was aborted
+      console.error(e);
+    }
+  }, [recalculateUserScore]);
+
+  // Optional: abort on unmount
+  useEffect(() => abortRecalculateUserScore, [abortRecalculateUserScore]);
+
+  return <button onClick={run}>Call</button>;
+}
+\`\`\`
+
+### Optional types (if generated by your build)
+
+\`\`\`ts
+import type { RecalculateUserScoreRequest } from "@intrig/react/demo_api/components/schemas/RecalculateUserScoreRequest";
+import type { RecalculateUserScoreParams } from "@intrig/react/users/{id}/RecalculateUserScore.params";
+import type { RecalculateUserScoreResponseBody } from "@intrig/react/users/{id}/RecalculateUserScore.response";
+\`\`\`
+
+---
+
+## Hook API
+
+\`\`\`ts
+// Prefer concrete types if your build emits them:
+// import type { RecalculateUserScoreResponseBody } from '@intrig/react/users/{id}/RecalculateUserScore.response';
+// import type { RecalculateUserScoreParams } from '@intrig/react/users/{id}/RecalculateUserScore.params';
+
+type RecalculateUserScoreData = unknown; // replace with RecalculateUserScoreResponseBody if generated
+type RecalculateUserScoreRequest = {
+  body?: RecalculateUserScoreRequest;
+  params?: RecalculateUserScoreParams;
+};
+
+// Signature (shape shown; return type depends on your endpoint)
+declare function useRecalculateUserScoreAsync(): [
+  (
+    body?: RecalculateUserScoreRequest["body"],
+    params?: RecalculateUserScoreRequest["params"],
+  ) => Promise<RecalculateUserScoreData>,
+  () => void, // abort
+];
+\`\`\`
+
+### Why async hooks?
+
+- **No state machine:** just \`await\` the result.
+- **Great for validations & submits:** uniqueness checks, field-level checks, updates.
+- **Abortable:** cancel in-flight work on demand.
+
+---
+
+## Usage Patterns
+
+### 1) Simple try/catch (recommended)
+
+\`\`\`tsx
+const [recalculateUserScore] = useRecalculateUserScoreAsync();
+
+try {
+  const res = await recalculateUserScore(
+    recalculateUserScoreRequest,
+    recalculateUserScoreParams,
+  );
+  // use res
+} catch (e) {
+  // network error or abort
+}
+\`\`\`
+
+<details><summary>Description</summary>
+<p><strong>Use when</strong> you just need the value or an error. Ideal for validators, uniqueness checks, or quick lookups.</p>
+</details>
+
+### 2) Abort on unmount (safe cleanup)
+
+\`\`\`tsx
+const [recalculateUserScore, abortRecalculateUserScore] =
+  useRecalculateUserScoreAsync();
+
+useEffect(() => abortRecalculateUserScore, [abortRecalculateUserScore]);
+\`\`\`
+
+<details><summary>Description</summary>
+<p><strong>Use when</strong> the component may unmount while a request is in-flight (route changes, conditional UI).</p>
+</details>
+
+### 3) Debounced validation (e.g., on input change)
+
+\`\`\`tsx
+const [recalculateUserScore, abortRecalculateUserScore] =
+  useRecalculateUserScoreAsync();
+
+const onChange = useMemo(() => {
+  let t: any;
+  return (recalculateUserScoreRequest: RecalculateUserScoreRequest) => {
+    clearTimeout(t);
+    t = setTimeout(async () => {
+      try {
+        // Optionally abort before firing a new request
+        abortRecalculateUserScore();
+        await recalculateUserScore(
+          recalculateUserScoreRequest,
+          recalculateUserScoreParams,
+        );
+      } catch {}
+    }, 250);
+  };
+}, [recalculateUserScore, abortRecalculateUserScore]);
+\`\`\`
+
+<details><summary>Description</summary>
+<p><strong>Use when</strong> validating as the user types. Debounce to reduce chatter; consider <code>abortRecalculateUserScore()</code> before firing a new call.</p>
+</details>
+
+### 4) Guard against races (latest-only)
+
+\`\`\`tsx
+const [recalculateUserScore, abortRecalculateUserScore] =
+  useRecalculateUserScoreAsync();
+
+const latestOnly = async () => {
+  abortRecalculateUserScore();
+  return recalculateUserScore(
+    recalculateUserScoreRequest,
+    recalculateUserScoreParams,
+  );
+};
+\`\`\`
+
+<details><summary>Description</summary>
+<p><strong>Use when</strong> only the most recent call should win (search suggestions, live filters).</p>
+</details>
+
+---
+
+## Full example
+
+\`\`\`tsx
+import { useRecalculateUserScoreAsync } from "@intrig/react/users/{id}/client";
+import { useCallback } from "react";
+
+function MyComponent() {
+  const [recalculateUserScore, abortRecalculateUserScore] =
+    useRecalculateUserScoreAsync();
+
+  const run = useCallback(async () => {
+    try {
+      const data = await recalculateUserScore(
+        recalculateUserScoreRequest,
+        recalculateUserScoreParams,
+      );
+      alert(JSON.stringify(data));
+    } catch (e) {
+      console.error("Call failed/aborted", e);
+    }
+  }, [recalculateUserScore]);
+
+  return (
+    <>
+      <button onClick={run}>Call remote</button>
+      <button onClick={abortRecalculateUserScore}>Abort</button>
+    </>
+  );
+}
+\`\`\`
+
+---
+
+## Gotchas & Tips
+
+- **No \`NetworkState\`:** async hooks return a Promise, not a state machine.
+- **Abort:** always available; call it to cancel the latest in-flight request.
+- **Errors:** wrap calls with \`try/catch\` to handle network failures or abort errors.
+- **Debounce & throttle:** combine with timers to cut down chatter for typeahead/validators.
+- **Types:** prefer generated \`RecalculateUserScoreResponseBody\` and \`RecalculateUserScoreParams\` if your build emits them.
+
+---
+
+## Reference: Minimal cheat sheet
+
+\`\`\`ts
+const [fn, abort] = useRecalculateUserScoreAsync();
+await fn(recalculateUserScoreRequest, recalculateUserScoreParams);
+abort(); // optional
+\`\`\`
+"
+`;
+
+exports[`reactAsyncFunctionHookDocs > snapshot — request body only (no path params) 1`] = `
+"# Intrig Async Hooks — Quick Guide
+
+## Copy-paste starter (fast lane)
+
+### 1) Hook import
+
+\`\`\`ts
+import { useCheckPasswordStrengthAsync } from "@intrig/react/security/client";
+\`\`\`
+
+### 2) Create an instance
+
+\`\`\`ts
+const [checkPasswordStrength, abortCheckPasswordStrength] =
+  useCheckPasswordStrengthAsync();
+\`\`\`
+
+### 3) Call it (awaitable)
+
+\`\`\`ts
+// body?, params? — pass what your endpoint needs (order: body, params)
+await checkPasswordStrength(checkPasswordStrengthRequest);
+\`\`\`
+
+Async hooks are for one-off, low-friction calls (e.g., validations, submissions). They return an **awaitable function** plus an **abort** function. No NetworkState.
+
+---
+
+## TL;DR (copy–paste)
+
+\`\`\`tsx
+import { useCheckPasswordStrengthAsync } from "@intrig/react/security/client";
+import { useCallback, useEffect } from "react";
+
+export default function Example() {
+  const [checkPasswordStrength, abortCheckPasswordStrength] =
+    useCheckPasswordStrengthAsync();
+
+  const run = useCallback(async () => {
+    try {
+      const result = await checkPasswordStrength(checkPasswordStrengthRequest);
+      // do something with result
+      console.log(result);
+    } catch (e) {
+      // request failed or was aborted
+      console.error(e);
+    }
+  }, [checkPasswordStrength]);
+
+  // Optional: abort on unmount
+  useEffect(() => abortCheckPasswordStrength, [abortCheckPasswordStrength]);
+
+  return <button onClick={run}>Call</button>;
+}
+\`\`\`
+
+### Optional types (if generated by your build)
+
+\`\`\`ts
+import type { CheckPasswordStrengthRequest } from "@intrig/react/demo_api/components/schemas/CheckPasswordStrengthRequest";
+import type { CheckPasswordStrengthResponseBody } from "@intrig/react/security/CheckPasswordStrength.response";
+\`\`\`
+
+---
+
+## Hook API
+
+\`\`\`ts
+// Prefer concrete types if your build emits them:
+// import type { CheckPasswordStrengthResponseBody } from '@intrig/react/security/CheckPasswordStrength.response';
+//
+
+type CheckPasswordStrengthData = unknown; // replace with CheckPasswordStrengthResponseBody if generated
+type CheckPasswordStrengthRequest = {
+  body?: CheckPasswordStrengthRequest;
+  params?: unknown;
+};
+
+// Signature (shape shown; return type depends on your endpoint)
+declare function useCheckPasswordStrengthAsync(): [
+  (
+    body?: CheckPasswordStrengthRequest["body"],
+    params?: CheckPasswordStrengthRequest["params"],
+  ) => Promise<CheckPasswordStrengthData>,
+  () => void, // abort
+];
+\`\`\`
+
+### Why async hooks?
+
+- **No state machine:** just \`await\` the result.
+- **Great for validations & submits:** uniqueness checks, field-level checks, updates.
+- **Abortable:** cancel in-flight work on demand.
+
+---
+
+## Usage Patterns
+
+### 1) Simple try/catch (recommended)
+
+\`\`\`tsx
+const [checkPasswordStrength] = useCheckPasswordStrengthAsync();
+
+try {
+  const res = await checkPasswordStrength(checkPasswordStrengthRequest);
+  // use res
+} catch (e) {
+  // network error or abort
+}
+\`\`\`
+
+<details><summary>Description</summary>
+<p><strong>Use when</strong> you just need the value or an error. Ideal for validators, uniqueness checks, or quick lookups.</p>
+</details>
+
+### 2) Abort on unmount (safe cleanup)
+
+\`\`\`tsx
+const [checkPasswordStrength, abortCheckPasswordStrength] =
+  useCheckPasswordStrengthAsync();
+
+useEffect(() => abortCheckPasswordStrength, [abortCheckPasswordStrength]);
+\`\`\`
+
+<details><summary>Description</summary>
+<p><strong>Use when</strong> the component may unmount while a request is in-flight (route changes, conditional UI).</p>
+</details>
+
+### 3) Debounced validation (e.g., on input change)
+
+\`\`\`tsx
+const [checkPasswordStrength, abortCheckPasswordStrength] =
+  useCheckPasswordStrengthAsync();
+
+const onChange = useMemo(() => {
+  let t: any;
+  return (checkPasswordStrengthRequest: CheckPasswordStrengthRequest) => {
+    clearTimeout(t);
+    t = setTimeout(async () => {
+      try {
+        // Optionally abort before firing a new request
+        abortCheckPasswordStrength();
+        await checkPasswordStrength(checkPasswordStrengthRequest /* params? */);
+      } catch {}
+    }, 250);
+  };
+}, [checkPasswordStrength, abortCheckPasswordStrength]);
+\`\`\`
+
+<details><summary>Description</summary>
+<p><strong>Use when</strong> validating as the user types. Debounce to reduce chatter; consider <code>abortCheckPasswordStrength()</code> before firing a new call.</p>
+</details>
+
+### 4) Guard against races (latest-only)
+
+\`\`\`tsx
+const [checkPasswordStrength, abortCheckPasswordStrength] =
+  useCheckPasswordStrengthAsync();
+
+const latestOnly = async () => {
+  abortCheckPasswordStrength();
+  return checkPasswordStrength(checkPasswordStrengthRequest);
+};
+\`\`\`
+
+<details><summary>Description</summary>
+<p><strong>Use when</strong> only the most recent call should win (search suggestions, live filters).</p>
+</details>
+
+---
+
+## Full example
+
+\`\`\`tsx
+import { useCheckPasswordStrengthAsync } from "@intrig/react/security/client";
+import { useCallback } from "react";
+
+function MyComponent() {
+  const [checkPasswordStrength, abortCheckPasswordStrength] =
+    useCheckPasswordStrengthAsync();
+
+  const run = useCallback(async () => {
+    try {
+      const data = await checkPasswordStrength(checkPasswordStrengthRequest);
+      alert(JSON.stringify(data));
+    } catch (e) {
+      console.error("Call failed/aborted", e);
+    }
+  }, [checkPasswordStrength]);
+
+  return (
+    <>
+      <button onClick={run}>Call remote</button>
+      <button onClick={abortCheckPasswordStrength}>Abort</button>
+    </>
+  );
+}
+\`\`\`
+
+---
+
+## Gotchas & Tips
+
+- **No \`NetworkState\`:** async hooks return a Promise, not a state machine.
+- **Abort:** always available; call it to cancel the latest in-flight request.
+- **Errors:** wrap calls with \`try/catch\` to handle network failures or abort errors.
+- **Debounce & throttle:** combine with timers to cut down chatter for typeahead/validators.
+- **Types:** prefer generated \`CheckPasswordStrengthResponseBody\` and \`...Params\` if your build emits them.
+
+---
+
+## Reference: Minimal cheat sheet
+
+\`\`\`ts
+const [fn, abort] = useCheckPasswordStrengthAsync();
+await fn(checkPasswordStrengthRequest);
+abort(); // optional
+\`\`\`
+"
+`;
+
+exports[`reactAsyncFunctionHookDocs > snapshot — simple REST descriptor (no body, no path params) 1`] = `
+"# Intrig Async Hooks — Quick Guide
+
+## Copy-paste starter (fast lane)
+
+### 1) Hook import
+
+\`\`\`ts
+import { useValidateUsernameAsync } from "@intrig/react/users/client";
+\`\`\`
+
+### 2) Create an instance
+
+\`\`\`ts
+const [validateUsername, abortValidateUsername] = useValidateUsernameAsync();
+\`\`\`
+
+### 3) Call it (awaitable)
+
+\`\`\`ts
+// body?, params? — pass what your endpoint needs (order: body, params)
+await validateUsername();
+\`\`\`
+
+Async hooks are for one-off, low-friction calls (e.g., validations, submissions). They return an **awaitable function** plus an **abort** function. No NetworkState.
+
+---
+
+## TL;DR (copy–paste)
+
+\`\`\`tsx
+import { useValidateUsernameAsync } from "@intrig/react/users/client";
+import { useCallback, useEffect } from "react";
+
+export default function Example() {
+  const [validateUsername, abortValidateUsername] = useValidateUsernameAsync();
+
+  const run = useCallback(async () => {
+    try {
+      const result = await validateUsername();
+      // do something with result
+      console.log(result);
+    } catch (e) {
+      // request failed or was aborted
+      console.error(e);
+    }
+  }, [validateUsername]);
+
+  // Optional: abort on unmount
+  useEffect(() => abortValidateUsername, [abortValidateUsername]);
+
+  return <button onClick={run}>Call</button>;
+}
+\`\`\`
+
+---
+
+## Hook API
+
+\`\`\`ts
+// Prefer concrete types if your build emits them:
+// import type { ValidateUsernameResponseBody } from '@intrig/react/users/ValidateUsername.response';
+//
+
+type ValidateUsernameData = unknown; // replace with ValidateUsernameResponseBody if generated
+type ValidateUsernameRequest = {
+  body?: unknown;
+  params?: unknown;
+};
+
+// Signature (shape shown; return type depends on your endpoint)
+declare function useValidateUsernameAsync(): [
+  (
+    body?: ValidateUsernameRequest["body"],
+    params?: ValidateUsernameRequest["params"],
+  ) => Promise<ValidateUsernameData>,
+  () => void, // abort
+];
+\`\`\`
+
+### Why async hooks?
+
+- **No state machine:** just \`await\` the result.
+- **Great for validations & submits:** uniqueness checks, field-level checks, updates.
+- **Abortable:** cancel in-flight work on demand.
+
+---
+
+## Usage Patterns
+
+### 1) Simple try/catch (recommended)
+
+\`\`\`tsx
+const [validateUsername] = useValidateUsernameAsync();
+
+try {
+  const res = await validateUsername();
+  // use res
+} catch (e) {
+  // network error or abort
+}
+\`\`\`
+
+<details><summary>Description</summary>
+<p><strong>Use when</strong> you just need the value or an error. Ideal for validators, uniqueness checks, or quick lookups.</p>
+</details>
+
+### 2) Abort on unmount (safe cleanup)
+
+\`\`\`tsx
+const [validateUsername, abortValidateUsername] = useValidateUsernameAsync();
+
+useEffect(() => abortValidateUsername, [abortValidateUsername]);
+\`\`\`
+
+<details><summary>Description</summary>
+<p><strong>Use when</strong> the component may unmount while a request is in-flight (route changes, conditional UI).</p>
+</details>
+
+### 3) Debounced validation (e.g., on input change)
+
+\`\`\`tsx
+const [validateUsername, abortValidateUsername] = useValidateUsernameAsync();
+
+const onChange = useMemo(() => {
+  let t: any;
+  return (value: string) => {
+    clearTimeout(t);
+    t = setTimeout(async () => {
+      try {
+        // Optionally abort before firing a new request
+        abortValidateUsername();
+        await validateUsername(/* body from value */, /* params? */);
+      } catch {}
+    }, 250);
+  };
+}, [validateUsername, abortValidateUsername]);
+\`\`\`
+
+<details><summary>Description</summary>
+<p><strong>Use when</strong> validating as the user types. Debounce to reduce chatter; consider <code>abortValidateUsername()</code> before firing a new call.</p>
+</details>
+
+### 4) Guard against races (latest-only)
+
+\`\`\`tsx
+const [validateUsername, abortValidateUsername] = useValidateUsernameAsync();
+
+const latestOnly = async () => {
+  abortValidateUsername();
+  return validateUsername();
+};
+\`\`\`
+
+<details><summary>Description</summary>
+<p><strong>Use when</strong> only the most recent call should win (search suggestions, live filters).</p>
+</details>
+
+---
+
+## Full example
+
+\`\`\`tsx
+import { useValidateUsernameAsync } from "@intrig/react/users/client";
+import { useCallback } from "react";
+
+function MyComponent() {
+  const [validateUsername, abortValidateUsername] = useValidateUsernameAsync();
+
+  const run = useCallback(async () => {
+    try {
+      const data = await validateUsername();
+      alert(JSON.stringify(data));
+    } catch (e) {
+      console.error("Call failed/aborted", e);
+    }
+  }, [validateUsername]);
+
+  return (
+    <>
+      <button onClick={run}>Call remote</button>
+      <button onClick={abortValidateUsername}>Abort</button>
+    </>
+  );
+}
+\`\`\`
+
+---
+
+## Gotchas & Tips
+
+- **No \`NetworkState\`:** async hooks return a Promise, not a state machine.
+- **Abort:** always available; call it to cancel the latest in-flight request.
+- **Errors:** wrap calls with \`try/catch\` to handle network failures or abort errors.
+- **Debounce & throttle:** combine with timers to cut down chatter for typeahead/validators.
+- **Types:** prefer generated \`ValidateUsernameResponseBody\` and \`...Params\` if your build emits them.
+
+---
+
+## Reference: Minimal cheat sheet
+
+\`\`\`ts
+const [fn, abort] = useValidateUsernameAsync();
+await fn();
+abort(); // optional
+\`\`\`
+"
+`;