Release v1.1.0: Add useAsyncMemoSuspense hook with implementation, tests, and documentation (#7)

* feat: add test suite with GitHub Actions workflow and React version compatibility tests

* feat: add cross-version React testing compatibility layer and fix type issues

* chore: add CodeRabbit config for main and develop branch reviews

* feat: add matrix testing across React 16-19 and Node 16-20 versions

* fix: add conditional testing library versions based on React version in CI workflow

* chore: add @testing-library/react dependency for React version compatibility

* test: add comprehensive test coverage for edge cases and error handling in useAsyncMemo and useAsyncEffekt

* chore: update Codecov action from v3 to v4

* add comment for any type usage

* chore: add strict error handling to matrix test script with set -euo pipefail

* fix: add error handling and exit codes to matrix test script

* style: improve readability of conditional npm install in Dockerfile.test

* chore: remove --force flag from npm install commands in test setup

* reset version to pre-release version

* fix: downgrade testing-library/react to v16.1.0 for React 19 test script

* fix: update test dependencies installation for different React versions in CI/Docker

* docs: add clickable links to README badges

* chore: add sideEffects:false to package.json for tree-shaking optimization

* feat: implement useAsyncMemoSuspense hook with global caching and dependency tracking

* feat(hooks): add docs and tests for useAsyncMemoSuspense

Adds JSDocs, README documentation, and tests for the new `useAsyncMemoSuspense` hook.

The documentation includes examples and important notes about SSR and client component usage.

The tests cover suspense, error handling, dependency changes, and scope usage.

* refactor: improve test coverage with TypeScript and realistic test scenarios

* test: improve timer handling and mock implementations in async memo tests

* ci: skip Suspense tests for React versions 16 and 17 in test workflow

* chore: update ErrorBoundary props type to use simplified React.PropsWithChildren syntax

* ci: exclude suspense module from test coverage collection for React 16/17

* chore: exclude test-utils.ts from code coverage metrics

* test: add comprehensive cache behavior and performance tests for useAsyncMemoSuspense

* docs: add vibe coded testing note in README

* refactor: removing unnecessary comments

---------

Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com>

Author: davemecha

.github/workflows/test.yml

@@ -41,7 +41,12 @@ jobs:
             npm install react@^${{ matrix.react-version }} react-dom@^${{ matrix.react-version }} @types/react@^${{ matrix.react-version }} @types/react-dom@^${{ matrix.react-version }} @testing-library/react@^16.1.0
           fi
 
-      - name: Run tests
+      - name: Run tests (excluding Suspense tests for React 16/17)
+        if: matrix.react-version == '16.8.0' || matrix.react-version == '17.0.0'
+        run: npm test -- --coverage --watchAll=false --testPathIgnorePatterns=".*useAsyncMemoSuspense.*" --collectCoverageFrom="src/**/*.ts" --collectCoverageFrom="!src/useAsyncMemoSuspense.ts"
+
+      - name: Run all tests (React 18+)
+        if: matrix.react-version == '18.0.0' || matrix.react-version == '19.0.0'
         run: npm test -- --coverage --watchAll=false
 
       - name: Upload coverage to Codecov

README.md

@@ -2,18 +2,19 @@
 
 React hooks for async effects and memoization with proper dependency tracking and linting support.
 
-![CI](https://github.com/davemecha/use-async-effekt/actions/workflows/test.yml/badge.svg)
-![npm](https://img.shields.io/npm/v/use-async-effekt-hooks)
-![codecov](https://codecov.io/gh/davemecha/use-async-effekt/branch/main/graph/badge.svg)
-![npm downloads](https://img.shields.io/npm/dw/use-async-effekt-hooks)
-![MIT](https://img.shields.io/npm/l/use-async-effekt-hooks)
-![bundle size](https://img.shields.io/bundlephobia/minzip/use-async-effekt-hooks)
-
-![bundle size](https://img.shields.io/bundlephobia/minzip/use-async-effekt-hooks)
-![Types](https://img.shields.io/npm/types/use-async-effekt-hooks)
-![react 16-19](https://img.shields.io/badge/react-16‒19-brightgreen?logo=react)
-![GitHub stars](https://img.shields.io/github/stars/davemecha/use-async-effekt?style=social)
-![issues](https://img.shields.io/github/issues/davemecha/use-async-effekt)
+[![CI](https://github.com/davemecha/use-async-effekt/actions/workflows/test.yml/badge.svg)](https://github.com/davemecha/use-async-effekt/actions/workflows/test.yml)
+[![npm](https://img.shields.io/npm/v/use-async-effekt-hooks)](https://www.npmjs.com/package/use-async-effekt-hooks)
+[![codecov](https://codecov.io/gh/davemecha/use-async-effekt/branch/main/graph/badge.svg)](https://codecov.io/gh/davemecha/use-async-effekt)
+[![npm downloads](https://img.shields.io/npm/dw/use-async-effekt-hooks)](https://www.npmjs.com/package/use-async-effekt-hooks)
+[![MIT](https://img.shields.io/npm/l/use-async-effekt-hooks)](LICENSE)
+
+[![bundle size](https://img.shields.io/bundlephobia/minzip/use-async-effekt-hooks)](https://bundlephobia.com/package/use-async-effekt-hooks)
+[![Types](https://img.shields.io/npm/types/use-async-effekt-hooks)](https://www.npmjs.com/package/use-async-effekt-hooks)
+[![react 16-19](https://img.shields.io/badge/react-16‒19-brightgreen?logo=react)](https://react.dev/)
+[![GitHub stars](https://img.shields.io/github/stars/davemecha/use-async-effekt?style=social)](https://github.com/davemecha/use-async-effekt/stargazers)
+[![issues](https://img.shields.io/github/issues/davemecha/use-async-effekt)](https://github.com/davemecha/use-async-effekt/issues)
+
+Note: Tests are vibe coded. Specific tests are added when bugs are reported.
 
 ## Installation
 
@@ -311,7 +312,7 @@ module.exports = {
     "react-hooks/exhaustive-deps": [
       "warn",
       {
-        additionalHooks: "(useAsyncEffekt|useAsyncMemo)",
+        additionalHooks: "(useAsyncEffekt|useAsyncMemo|useAsyncMemoSuspense)",
       },
     ],
   },
@@ -326,7 +327,7 @@ Or if you're using `.eslintrc.json`:
     "react-hooks/exhaustive-deps": [
       "warn",
       {
-        "additionalHooks": "(useAsyncEffekt|useAsyncMemo)"
+        "additionalHooks": "(useAsyncEffekt|useAsyncMemo|useAsyncMemoSuspense)"
       }
     ]
   }
@@ -361,6 +362,52 @@ This configuration tells ESLint to treat `useAsyncEffekt` and `useAsyncMemo` the
 
 **Returns:** `T | undefined` - The memoized value, or `undefined` while loading
 
+### `useAsyncMemoSuspense(factory, deps?, options?)`
+
+**Parameters:**
+
+- `factory: () => Promise<T> | T` - The async function to execute.
+- `deps?: DependencyList` - Optional dependency array (same as `useMemo`).
+- `options?: { scope?: string }` - Optional options object.
+  - `scope?: string` - An optional scope to isolate the cache. This is useful when you have multiple instances of the hook with the same factory and dependencies but you want to keep their caches separate.
+
+**Returns:** `T` - The memoized value. It suspends the component while the async operation is in progress.
+
+**Important Notes:**
+
+- **SSR Environments (e.g., Next.js):** In a server-side rendering environment, this hook will always return `undefined` on the server. The component will suspend on the client during hydration (not on initial render on the server). This means the suspense fallback will be displayed on hydration, and nothing will be displayed on the server-side render.
+- **Client Component:** This hook must be used within a "client component" (e.g., in Next.js, the file must have the `"use client";` directive at the top).
+- **Experimental:** This hook is experimental and its API might change in future versions.
+
+**Example:**
+
+```tsx
+import { Suspense } from "react";
+import { useAsyncMemoSuspense } from "use-async-effekt-hooks";
+
+function UserProfile({ userId }) {
+  const user = useAsyncMemoSuspense(async () => {
+    const response = await fetch(`https://api.example.com/users/${userId}`);
+    return response.json();
+  }, [userId]);
+
+  return (
+    <div>
+      <h1>{user.name}</h1>
+      <p>{user.email}</p>
+    </div>
+  );
+}
+
+function App() {
+  return (
+    <Suspense fallback={<div>Loading...</div>}>
+      <UserProfile userId="1" />
+    </Suspense>
+  );
+}
+```
+
 ## Features
 
 - ✅ Full TypeScript support

package-lock.json

@@ -2,6 +2,7 @@
   "name": "use-async-effekt-hooks",
   "version": "1.0.0",
   "description": "React hooks for async effects and memoization with proper dependency tracking and linting support",
+  "sideEffects": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -59,7 +60,7 @@
     "react": "^18.0.0",
     "react-dom": "^18.0.0",
     "semver": "^7.7.2",
-    "ts-jest": "^29.1.0",
+    "ts-jest": "^29.4.0",
     "typescript": "^5.0.0"
   },
   "jest": {
@@ -76,7 +77,8 @@
       "src/**/*.{ts,tsx}",
       "!src/__tests__/**/*.{ts,tsx}",
       "!src/**/*.d.ts",
-      "!src/setupTests.ts"
+      "!src/setupTests.ts",
+      "!src/**/test-utils.ts"
     ],
     "coverageReporters": [
       "text",

package.json

@@ -4,6 +4,7 @@ import { useAsyncMemo } from "../useAsyncMemo";
 
 describe("useAsyncMemo", () => {
   beforeEach(() => {
+    jest.clearAllMocks();
     jest.clearAllTimers();
     jest.useRealTimers();
   });