npm package: @pixel-pulse/next-cache-brain-core
Description: Universal caching engine for Next.js with React 18 hook support.
Author: Lin Htet Aung
Latest version: 0.5.1

<div align="center">
  <img src="https://next-cache-brain.netlify.app/og-image.jpeg" width="100%" alt="Next Cache Brain - Smart Caching Engine"/>
  
  <br/>
  
  [![npm version](https://img.shields.io/npm/v/@pixel-pulse/next-cache-brain-core.svg)](https://www.npmjs.com/package/@pixel-pulse/next-cache-brain-core)
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  
  <h3>Next-Generation Caching Engine for Next.js</h3>

  <p>
    <a href="https://next-cache-brain.netlify.app/"><b>Documentation</b></a> •
    <a href="https://next-cache-brain.netlify.app/playground/core"><b>Server Lab</b></a> •
    <a href="https://next-cache-brain.netlify.app/playground/hook"><b>Client Lab</b></a> •
    <a href="https://github.com/LinnHtetAungSE"><b>GitHub</b></a>
  </p>
</div>

---

## ✨ Features

- **Atomic Pulse Engine:** Unified API supporting `SWR`, `Cache-First`, and `Network-First` strategies with a single function call.
- **Visual Diagnostics:** Real-time DevTools to track **TTL**, **Registry Hits**, and **Deduplication** events as they happen.
- **Event Bridge:** Reactive synchronization ensuring that when data updates in one component, the entire UI stays in sync.
- **App Router Native:** Deeply optimized for Next.js Server Components, Actions, and high-performance client hydration.

---

## ⚠️ Beta Version Notice

This project is currently in **v0.5.1-beta**. We are actively refining the **Registry Pulse** logic and synchronization performance.

- Please report any bugs via GitHub Issues.
- Expect breaking changes until version **1.0.0**.

---

## 📦 Installation

Install the core engine and the visual diagnostic suite:

```bash
npm install @pixel-pulse/next-cache-brain-core @pixel-pulse/next-cache-brain-devtools
```

---

## Quick Start Guide

### 1. Global Registry Setup

To enable real-time synchronization and the Visual Debugger, wrap your application in the `CacheBrainProvider` within your `layout.tsx`.

```tsx
// app/layout.tsx
import {
  CacheBrainProvider,
  CacheBrainDevtools,
} from "@pixel-pulse/next-cache-brain-devtools";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <CacheBrainProvider>
          {children}

          {/* Diagnostic overlay active in development */}
          <CacheBrainDevtools
            enabled={process.env.NODE_ENV === "development"}
          />
        </CacheBrainProvider>
      </body>
    </html>
  );
}
```

---

### 2. Server-Side Implementation

Use `smartCache` in your Server Components for high-performance data fetching with automatic deduplication.

```tsx
// app/layout.tsx
import { smartCache } from "@pixel-pulse/next-cache-brain-core";

async function Profile({ id }) {
  const user = await smartCache(
    ["user-profile", id], // Unique Cache Key
    () => fetch(`https://api.pulse.tech/users/${id}`).then((res) => res.json()),
    {
      strategy: "cache-first",
      ttl: 60000, // 60 seconds
    },
  );

  return <div>{user.name}</div>;
}
```

---

### 3. Client-Side Reactivity

Use the `useSmartCache` hook to create reactive UIs that stay synchronized across your entire application via the **Event Bridge**.

```tsx
// app/layout.tsx
import { smartCache } from "@pixel-pulse/next-cache-brain-core";

async function Profile({ id }) {
  const user = await smartCache(
    ["user-profile", id], // Unique Cache Key
    () => fetch(`https://api.pulse.tech/users/${id}`).then((res) => res.json()),
    {
      strategy: "cache-first",
      ttl: 60000, // 60 seconds
    },
  );

  return <div>{user.name}</div>;
}
```

---

### Caching Strategies

| Strategy        | Behavior                                                    | Best For                     |
| :-------------- | :---------------------------------------------------------- | :--------------------------- |
| `cache-first`   | Returns cached data if valid; fetches only on miss.         | Static content, settings.    |
| `swr`           | Returns cached data immediately; revalidates in background. | Dashboards, Social feeds.    |
| `network-first` | Attempts fresh fetch; falls back to cache on failure.       | Critical real-time data.     |
| `no-cache`      | Bypasses registry but tracks request in DevTools.           | Testing, Non-cacheable hits. |

---

### Resources & Navigation

Explore the ecosystem and learn how to optimize your application's data pulse:

- **[Official Documentation](https://next-cache-brain.netlify.app/)** — Full API reference and advanced configuration guides.
- **[Strategy Lab (Server)](https://next-cache-brain.netlify.app/playground/core)** — Visualize how different strategies handle network delays and cache hits.
- **[Reactive Lab (Client)](https://next-cache-brain.netlify.app/playground/hook)** — Observe real-time component synchronization using the `useSmartCache` hook.
- **[GitHub Repository](https://github.com/LinnHtetAungSE)** — Contribute, report issues, or view the source code.
- **[NPM Registry](https://www.npmjs.com/package/@pixel-pulse/next-cache-brain-core)** — View package versions and download statistics.

---

<div align="center">
<p>Built with ⚡ by <b>Pixel Pulse Tech MM</b></p>
</div>