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:

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.

// 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.

// 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.

// 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.

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

Official Documentation — Full API reference and advanced configuration guides.
Strategy Lab (Server) — Visualize how different strategies handle network delays and cache hits.
Reactive Lab (Client) — Observe real-time component synchronization using the useSmartCache hook.
GitHub Repository — Contribute, report issues, or view the source code.
NPM Registry — View package versions and download statistics.