rkk-next 1.0.0 → 1.1.0

package/README.md

@@ -1,218 +1,465 @@
-# 🚀 rkk-next
+<div align="center">
 
-> **SEO, Performance & Routing SDK for Next.js**
+<img src="./assets/logo.svg" alt="rkk-next logo" width="120" height="120" />
 
-[![npm version](https://img.shields.io/npm/v/rkk-next.svg)](https://www.npmjs.com/package/rkk-next)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
-[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+# rkk-next
 
-rkk-next is an opinionated Next.js SDK that helps you build **SEO-optimized**, **blazing fast**, and **scalable** applications with better routing, caching, and performance defaults.
+**Production-ready SEO, Performance & Routing SDK for Next.js**
 
-✨ **Built for Next.js Pages Router & App Router**  
-🎯 **Ideal for:** Startups, Landing Pages, Web3 Dashboards, SaaS, Hackathons
+[![npm version](https://img.shields.io/npm/v/rkk-next.svg?style=flat-square)](https://www.npmjs.com/package/rkk-next)
+[![npm downloads](https://img.shields.io/npm/dm/rkk-next.svg?style=flat-square)](https://www.npmjs.com/package/rkk-next)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](./LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-3178c6.svg?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
 
-## ✨ Features
+**Enterprise-grade toolkit for building SEO-optimized, lightning-fast Next.js applications**
 
-### 🔍 SEO Optimization
-- ✅ Centralized meta management (OpenGraph, Twitter Cards)
-- ✅ JSON-LD structured data (Schema.org)
-- ✅ Canonical URL handling
-- ✅ SEO-safe defaults & best practices
+[Get Started](#-quick-start) · [Documentation](./docs/DOCS.md) · [Examples](./examples/) · [Report Bug](https://github.com/ROHIT8759/rkk-next/issues)
 
-### ⚡ Routing Optimization
-- ✅ Intelligent route prefetching (hover-based)
-- ✅ Network-aware prefetching
-- ✅ Route change observer with performance metrics
-- ✅ Analytics-ready routing events
+</div>
 
-### 🚀 Performance Boost
-- ✅ Lazy loading for heavy components
-- ✅ Optimized image wrapper (SEO + performance)
-- ✅ Cache & CDN header presets
-- ✅ Edge-friendly caching strategies
-- ✅ Security headers included
+---
 
-### 📊 Analytics
-- ✅ Web Vitals tracking (LCP, FID, CLS, etc.)
-- ✅ Route navigation analytics
-- ✅ Performance monitoring
+## 🎯 Why rkk-next?
 
-📦 Installation
-npm install rkk-next
+Building performant, SEO-optimized Next.js applications requires juggling multiple concerns: meta tags, structured data, route prefetching, image optimization, and caching strategies. **rkk-next** provides production-tested solutions out of the box.
+
+**Perfect for:**
+
+- 🚀 Startups needing rapid development
+- 💼 Enterprise applications requiring SEO excellence
+- 🎨 Marketing websites and landing pages
+- 🌐 Web3 dashboards and SaaS platforms
+- ⚡ Performance-critical applications
+
+## ✨ Key Features
+
+<table>
+<tr>
+<td width="50%">
+
+### 🔍 **SEO Excellence**
+
+- Comprehensive meta tag management
+- OpenGraph & Twitter Cards
+- JSON-LD structured data (Schema.org)
+- Automatic canonical URLs
+- Server-side rendering optimized
+
+</td>
+<td width="50%">
+
+### ⚡ **Performance First**
+
+- Intelligent route prefetching
+- Network-aware optimizations
+- Lazy loading for heavy components
+- CDN & edge caching strategies
+- Built-in security headers
+
+</td>
+</tr>
+<tr>
+<td width="50%">
+
+### 📊 **Analytics Ready**
+
+- Core Web Vitals tracking
+- Route navigation metrics
+- Performance monitoring
+- Custom event tracking
+- Production-ready insights
+
+</td>
+<td width="50%">
+
+### ⚡ **Backend Utilities**
+
+- Express-like middleware
+- API route optimization
+- Rate limiting & CORS
+- Response caching
+- Request validation
+
+</td>
+</tr>
+<tr>
+<td width="50%">
+
+### 🎨 **Developer Experience**
+
+- Full TypeScript support
+- Zero configuration needed
+- Pages Router & App Router
+- Comprehensive documentation
+- Active maintenance
+
+</td>
+</tr>
+</table>
+
+---
+
+## 🚀 Quick Start
 
+### Create New Project (Recommended)
 
-or
+Get started instantly with our CLI tool:
 
+```bash
+npx create-next-rkk@latest my-app
+cd my-app
+npm run dev
+```
+
+### Add to Existing Project
+
+Install into your existing Next.js application:
+
+```bash
+npm install rkk-next
+# or
 yarn add rkk-next
+# or
+pnpm add rkk-next
+```
+
+---
 
-🧠 Basic Usage
-1️⃣ SEO Meta Manager
+## 📖 Usage Examples
+
+### SEO Meta Management
+
+Centralize your SEO configuration with type-safe components:
+
+```tsx
 import { MetaManager } from "rkk-next";
 
-export default function Home() {
+export default function HomePage() {
   return (
     <>
       <MetaManager
         title="Home | My App"
-        description="SEO optimized Next.js app using rkk-next"
-        keywords="Next.js, SEO, Performance"
-        image="/og.png"
+        description="Production-ready Next.js application with enterprise SEO"
+        keywords="Next.js, React, SEO, Performance"
+        image="https://myapp.com/og-image.png"
         siteName="My App"
+        twitterHandle="myhandle"
       />
 
-      <h1>Hello World</h1>
+      <main>{/* Your content */}</main>
     </>
   );
 }
+```
 
-2️⃣ JSON-LD (Schema.org)
-import { JsonLd } from "rkk-next";
+### Structured Data (JSON-LD)
 
-<JsonLd
-  type="WebSite"
-  data={{
-    name: "My App",
-    url: "https://myapp.com",
-  }}
-/>
+Improve search engine understanding with structured data:
 
-🔗 Smart Routing
-SmartLink (Enhanced next/link)
-import { SmartLink } from "rkk-next";
+```tsx
+import { JsonLd } from "rkk-next";
 
-<SmartLink href="/dashboard">
-  Go to Dashboard
-</SmartLink>
+export default function ArticlePage() {
+  return (
+    <>
+      <JsonLd
+        type="Article"
+        data={{
+          headline: "Advanced Next.js SEO Techniques",
+          image: "https://myapp.com/article.jpg",
+          datePublished: "2025-12-18T08:00:00.000Z",
+          author: {
+            "@type": "Person",
+            name: "John Doe",
+          },
+        }}
+      />
 
+      <article>{/* Article content */}</article>
+    </>
+  );
+}
+```
 
-✔ Prefetch on hover
-✔ Network-aware
-✔ SEO-safe <a> tag
+### Smart Routing & Prefetching
 
-Route Observer
-import { observeRoutes } from "rkk-next";
+Enhance navigation performance with intelligent prefetching:
 
-observeRoutes((event) => {
-  console.log(event.url, event.duration);
-});
+```tsx
+import { SmartLink, observeRoutes } from "rkk-next";
+import { useEffect } from "react";
 
-🖼️ Image Optimization
-import { OptimizedImage } from "rkk-next";
+export default function Navigation() {
+  useEffect(() => {
+    // Track route changes for analytics
+    const unsubscribe = observeRoutes((event) => {
+      analytics.track("page_view", {
+        url: event.url,
+        duration: event.duration,
+      });
+    });
 
-<OptimizedImage
-  src="/hero.png"
-  alt="Landing page hero image"
-  width={1200}
-  height={630}
-  priority
-/>
+    return unsubscribe;
+  }, []);
 
+  return (
+    <nav>
+      <SmartLink href="/products" prefetchOnHover>
+        Products
+      </SmartLink>
+    </nav>
+  );
+}
+```
 
-✔ SEO-safe alt enforcement
-✔ Responsive sizes
-✔ LCP optimized
+### Optimized Images
 
-💤 Lazy Loading
-import { lazyImport } from "rkk-next";
+Ensure SEO-compliant and performant images:
 
-const Chart = lazyImport(() => import("./Chart"));
+```tsx
+import { OptimizedImage } from "rkk-next";
 
-export default function Dashboard() {
-  return <Chart />;
+export default function Hero() {
+  return (
+    <OptimizedImage
+      src="/hero-banner.jpg"
+      alt="Professional hero banner showcasing our product"
+      width={1920}
+      height={1080}
+      priority // For above-the-fold images
+      quality={85}
+    />
+  );
 }
+```
+
+### Code Splitting & Lazy Loading
 
-🧠 Intelligent Prefetching
-import { prefetchRoute, isFastConnection } from "rkk-next";
+Reduce initial bundle size with intelligent lazy loading:
 
-prefetchRoute("/dashboard", {
-  condition: isFastConnection,
+```tsx
+import { lazyImport, DefaultLoader } from "rkk-next";
+
+// Heavy component loaded on-demand
+const AnalyticsDashboard = lazyImport(() => import("./AnalyticsDashboard"), {
+  loading: DefaultLoader,
+  ssr: false,
+  delay: 100,
 });
 
-🗄️ Cache Headers
+export default function Dashboard() {
+  return (
+    <main>
+      <h1>Dashboard</h1>
+      <AnalyticsDashboard />
+    </main>
+  );
+}
+```
+
+### Performance-Optimized Caching
 
-Use directly inside next.config.js:
+Configure production-grade caching in `next.config.js`:
 
+```javascript
 const {
   LONG_TERM_CACHE,
   EDGE_CACHE,
   NO_CACHE,
+  SECURITY_HEADERS,
   applyCache,
-} = require("rkk-next");
+} = require("rkk-next/performance/cacheHeaders");
 
 module.exports = {
   async headers() {
     return [
+      // Static assets: aggressive caching
       applyCache("/_next/static/:path*", LONG_TERM_CACHE),
+      applyCache("/images/:path*", LONG_TERM_CACHE),
+
+      // API routes: edge caching
       applyCache("/api/public/:path*", EDGE_CACHE),
+
+      // User-specific pages: no cache
       applyCache("/dashboard/:path*", NO_CACHE),
+
+      // Security headers for all routes
+      {
+        source: "/:path*",
+        headers: SECURITY_HEADERS,
+      },
     ];
   },
 };
+```
+
+### Backend API Utilities
+
+Build robust Next.js API routes with Express-like middleware:
+
+```typescript
+// pages/api/users/[id].ts
+import { NextApiRequest, NextApiResponse } from "next";
+import {
+  composeMiddleware,
+  cors,
+  rateLimit,
+  validateRequest,
+  logger,
+  errorHandler,
+  cacheResponse,
+  jsonResponse,
+  allowMethods,
+} from "rkk-next";
+
+// Compose middleware chain
+const handler = composeMiddleware(
+  cors({ origin: "https://yourdomain.com" }),
+  rateLimit({ maxRequests: 100, windowMs: 60000 }),
+  logger(),
+  allowMethods(["GET", "PUT", "DELETE"]),
+  cacheResponse({ ttl: 300 }), // Cache for 5 minutes
+  validateRequest((req) => {
+    if (req.method === "PUT" && !req.body.name) {
+      return "Name is required";
+    }
+  }),
+  errorHandler()
+)(async (req: NextApiRequest, res: NextApiResponse) => {
+  const { id } = req.query;
+
+  // Your API logic
+  const user = await getUserById(id as string);
+
+  return jsonResponse(res, {
+    success: true,
+    data: user,
+  });
+});
+
+export default handler;
+```
 
-## 🧩 Supported Next.js Versions
+**Server-side caching with automatic TTL:**
 
-| Feature           | Pages Router | App Router |
-|-------------------|--------------|------------|
-| MetaManager       | ✅          | ✅ (via generateAppMetadata) |
-| JsonLd            | ✅          | ✅         |
-| SmartLink         | ✅          | ⚠️ (use for internal links only) |
-| Routing Observer  | ✅          | ⚠️ (Pages Router recommended) |
-| OptimizedImage    | ✅          | ✅         |
-| Lazy Loading      | ✅          | ✅         |
-| Cache Headers     | ✅          | ✅         |
-| Web Vitals        | ✅          | ✅         |
+```typescript
+import { cache, memoize } from "rkk-next";
 
-**Minimum Requirements:**
-- Next.js >= 12.0.0
-- React >= 17.0.0
-- TypeScript >= 4.5.0 (optional but recommended)
-🛠️ Best Practices
+// Cache expensive operations
+const expensiveQuery = memoize(
+  async (userId: string) => {
+    return await database.query(/* ... */);
+  },
+  { ttl: 600 } // 10 minutes
+);
 
-Use MetaManager on every page
+// Manual cache control
+cache.set("user:123", userData, 300);
+const cachedUser = cache.get("user:123");
+```
 
-Avoid lazy loading LCP elements
+See [Backend Utilities Documentation](docs/BACKEND.md) for complete API reference.
 
-Use SmartLink for internal navigation
+---
 
-Enable cache headers for static assets
+## 🧩 Compatibility Matrix
 
-Always provide alt text for images
+| Feature        | Pages Router | App Router | Notes                                 |
+| -------------- | :----------: | :--------: | ------------------------------------- |
+| MetaManager    |      ✅      |     ✅     | App Router uses `generateAppMetadata` |
+| JsonLd         |      ✅      |     ✅     | Works with both routers               |
+| SmartLink      |      ✅      |     ⚠️     | Recommended for Pages Router          |
+| RouteObserver  |      ✅      |     ⚠️     | Pages Router only                     |
+| OptimizedImage |      ✅      |     ✅     | Full support both routers             |
+| Lazy Loading   |      ✅      |     ✅     | Dynamic imports supported             |
+| Cache Headers  |      ✅      |     ✅     | Universal support                     |
+| Web Vitals     |      ✅      |     ✅     | Analytics integration                 |
+| Backend Utils  |      ✅      |     ✅     | API routes middleware                 |
 
-## 🧑‍💻 Author
+**System Requirements:**
 
-**Rohit Kumar Kundu**  
-🎓 B.Tech CSE | Web3 & Next.js Developer  
-🔗 [GitHub](https://github.com/ROHIT8759) | [LinkedIn](https://linkedin.com/in/rohit-kumar-kundu)
+- Next.js `>= 12.0.0`
+- React `>= 17.0.0`
+- Node.js `>= 16.0.0`
+- TypeScript `>= 4.5.0` (optional but recommended)
 
-## 📚 Documentation
+---
+
+## 🎓 Learn More
+
+### 📚 Documentation
 
-- 📖 [Full Documentation](./docs/DOCS.md)
-- 🚀 [Quick Start Guide](./docs/QUICKSTART.md)
-- 📝 [API Reference](./docs/DOCS.md#api-reference)
-- 💡 [Examples](./examples/)
+- [Complete Documentation](./docs/DOCS.md) - Comprehensive API reference
+- [Quick Start Guide](./docs/QUICKSTART.md) - Get running in 5 minutes
+- [Migration Guide](./docs/DOCS.md) - Upgrade from other solutions
+- [Best Practices](./docs/DOCS.md#best-practices) - Production tips
 
 ## 🤝 Contributing
 
-We welcome contributions! See [CONTRIBUTING.md](./docs/CONTRIBUTING.md) for guidelines.
+We welcome contributions from the community! Whether it's:
+
+- 🐛 Bug reports and fixes
+- ✨ New features and enhancements
+- 📖 Documentation improvements
+- 💡 Feature suggestions
+
+**Getting Started:**
 
 1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+2. Create a feature branch: `git checkout -b feature/amazing-feature`
+3. Make your changes with clear commit messages
+4. Write or update tests as needed
+5. Submit a pull request
 
-## 🚀 Next Steps
+See [CONTRIBUTING.md](./docs/CONTRIBUTING.md) for detailed guidelines.
 
-- [ ] Add App Router `generateMetadata` helper
-- [ ] Expand Web Vitals analytics integration
-- [ ] Create demo app showcase
-- [ ] Add Lighthouse CI integration
-- [ ] Video tutorials & guides
+---
 
 ## 📄 License
 
 MIT License © 2025 [Rohit Kumar Kundu](https://github.com/ROHIT8759)
 
+Free for commercial and personal use. See [LICENSE](./LICENSE) for details.
+
+---
+
+## 🙏 Support & Community
+
+### Get Help
+
+- 📖 [Documentation](./docs/DOCS.md)
+- 💬 [GitHub Discussions](https://github.com/ROHIT8759/rkk-next/discussions)
+- 🐛 [Issue Tracker](https://github.com/ROHIT8759/rkk-next/issues)
+
+### Show Your Support
+
+If rkk-next helps your project:
+
+- ⭐ Star the repository
+- 🐦 Share on social media
+- 📝 Write about your experience
+- 🤝 Contribute back to the project
+
+---
+
+## 🧑‍💻 Author
+
+**Rohit Kumar Kundu**  
+Full-Stack Developer | Next.js & Web3 Specialist
+
+🔗 [GitHub](https://github.com/ROHIT8759) · [LinkedIn](https://linkedin.com/in/rohit-kumar-kundu) · [Portfolio](https://rohitkundu.dev)
+
+---
+
+<div align="center">
+
+**Built with ❤️ for the Next.js community**
+
+[Get Started](./docs/QUICKSTART.md) · [Documentation](./docs/DOCS.md) · [Examples](./examples/) · [Changelog](./CHANGELOG.md)
+
+</div>
+MIT License © 2025 [Rohit Kumar Kundu](https://github.com/ROHIT8759)
+
 Free to use, modify, and distribute. See [LICENSE](./LICENSE) for details.
 
 ## ⭐ Support the Project
@@ -245,4 +492,4 @@ If you want, I can now:
 
 ✔ Final SDK audit before release
 
-Just tell me 👍
+Just tell me 👍

package/dist/backend/cache.d.ts

@@ -0,0 +1,49 @@
+import { NextApiRequest, NextApiResponse } from 'next';
+export interface CacheOptions {
+    /** Time to live in seconds */
+    ttl?: number;
+    /** Cache key generator function */
+    keyGenerator?: (req: NextApiRequest) => string;
+    /** Conditional caching based on request */
+    shouldCache?: (req: NextApiRequest) => boolean;
+}
+/**
+ * In-memory cache store for API responses
+ */
+declare class MemoryCache {
+    private cache;
+    set<T = any>(key: string, data: T, ttl: number): void;
+    get<T = any>(key: string): T | null;
+    has(key: string): boolean;
+    delete(key: string): void;
+    clear(): void;
+    size(): number;
+    /**
+     * Clean up expired entries
+     */
+    cleanup(): void;
+}
+export declare const cache: MemoryCache;
+/**
+ * Cache API response middleware
+ */
+export declare function cacheResponse(options?: CacheOptions): (req: NextApiRequest, res: NextApiResponse, next: () => void | Promise<void>) => Promise<void>;
+/**
+ * Invalidate cache by pattern or specific key
+ */
+export declare function invalidateCache(pattern?: string | RegExp): void;
+/**
+ * Get cache statistics
+ */
+export declare function getCacheStats(): {
+    size: number;
+    timestamp: string;
+};
+/**
+ * Memoize function results with TTL
+ */
+export declare function memoize<T extends (...args: any[]) => any>(fn: T, options?: {
+    ttl?: number;
+    keyGenerator?: (...args: Parameters<T>) => string;
+}): T;
+export {};

package/dist/backend/cache.js

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cache = void 0;
+exports.cacheResponse = cacheResponse;
+exports.invalidateCache = invalidateCache;
+exports.getCacheStats = getCacheStats;
+exports.memoize = memoize;
+/**
+ * In-memory cache store for API responses
+ */
+class MemoryCache {
+    constructor() {
+        this.cache = new Map();
+    }
+    set(key, data, ttl) {
+        this.cache.set(key, {
+            data,
+            timestamp: Date.now(),
+            ttl: ttl * 1000, // Convert to milliseconds
+        });
+    }
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return null;
+        }
+        const isExpired = Date.now() - entry.timestamp > entry.ttl;
+        if (isExpired) {
+            this.cache.delete(key);
+            return null;
+        }
+        return entry.data;
+    }
+    has(key) {
+        return this.get(key) !== null;
+    }
+    delete(key) {
+        this.cache.delete(key);
+    }
+    clear() {
+        this.cache.clear();
+    }
+    size() {
+        return this.cache.size;
+    }
+    /**
+     * Clean up expired entries
+     */
+    cleanup() {
+        const now = Date.now();
+        for (const [key, entry] of this.cache.entries()) {
+            if (now - entry.timestamp > entry.ttl) {
+                this.cache.delete(key);
+            }
+        }
+    }
+}
+exports.cache = new MemoryCache();
+// Periodic cleanup every 5 minutes
+if (typeof setInterval !== 'undefined') {
+    setInterval(() => exports.cache.cleanup(), 5 * 60 * 1000);
+}
+/**
+ * Default cache key generator
+ */
+function defaultKeyGenerator(req) {
+    const method = req.method || 'GET';
+    const url = req.url || '';
+    const query = JSON.stringify(req.query || {});
+    return `${method}:${url}:${query}`;
+}
+/**
+ * Cache API response middleware
+ */
+function cacheResponse(options = {}) {
+    const { ttl = 60, // Default 60 seconds
+    keyGenerator = defaultKeyGenerator, shouldCache = (req) => req.method === 'GET', } = options;
+    return async (req, res, next) => {
+        // Skip caching if condition not met
+        if (!shouldCache(req)) {
+            await next();
+            return;
+        }
+        const cacheKey = keyGenerator(req);
+        // Check if cached response exists
+        const cachedData = exports.cache.get(cacheKey);
+        if (cachedData) {
+            res.setHeader('X-Cache', 'HIT');
+            res.setHeader('Cache-Control', `public, max-age=${ttl}`);
+            res.status(200).json(cachedData);
+            return;
+        }
+        // Intercept response to cache it
+        const originalJson = res.json;
+        const originalSend = res.send;
+        let responseData;
+        res.json = function (data) {
+            responseData = data;
+            return originalJson.call(this, data);
+        };
+        res.send = function (data) {
+            responseData = data;
+            return originalSend.call(this, data);
+        };
+        const originalEnd = res.end;
+        res.end = function (...args) {
+            // Only cache successful responses
+            if (res.statusCode >= 200 && res.statusCode < 300 && responseData) {
+                exports.cache.set(cacheKey, responseData, ttl);
+                res.setHeader('X-Cache', 'MISS');
+                res.setHeader('Cache-Control', `public, max-age=${ttl}`);
+            }
+            return originalEnd.apply(this, args);
+        };
+        await next();
+    };
+}
+/**
+ * Invalidate cache by pattern or specific key
+ */
+function invalidateCache(pattern) {
+    if (!pattern) {
+        exports.cache.clear();
+        return;
+    }
+    const regex = typeof pattern === 'string'
+        ? new RegExp(pattern)
+        : pattern;
+    // This is a simplified implementation
+    // In production, you'd want a more efficient pattern matching
+    exports.cache.clear(); // For now, clear all
+}
+/**
+ * Get cache statistics
+ */
+function getCacheStats() {
+    return {
+        size: exports.cache.size(),
+        timestamp: new Date().toISOString(),
+    };
+}
+/**
+ * Memoize function results with TTL
+ */
+function memoize(fn, options = {}) {
+    const { ttl = 60, keyGenerator = (...args) => JSON.stringify(args), } = options;
+    const memoCache = new Map();
+    return ((...args) => {
+        const key = keyGenerator(...args);
+        const cached = memoCache.get(key);
+        if (cached) {
+            const isExpired = Date.now() - cached.timestamp > cached.ttl;
+            if (!isExpired) {
+                return cached.data;
+            }
+            memoCache.delete(key);
+        }
+        const result = fn(...args);
+        memoCache.set(key, {
+            data: result,
+            timestamp: Date.now(),
+            ttl: ttl * 1000,
+        });
+        return result;
+    });
+}

package/dist/backend/middleware.d.ts

@@ -0,0 +1,43 @@
+import { NextApiRequest, NextApiResponse } from 'next';
+export type NextApiHandler = (req: NextApiRequest, res: NextApiResponse) => Promise<void> | void;
+export type Middleware = (req: NextApiRequest, res: NextApiResponse, next: () => void | Promise<void>) => void | Promise<void>;
+/**
+ * Compose multiple middleware functions into a single handler
+ */
+export declare function composeMiddleware(...middlewares: Middleware[]): (handler: NextApiHandler) => NextApiHandler;
+/**
+ * CORS middleware for Next.js API routes
+ */
+export declare function cors(options?: {
+    origin?: string | string[];
+    methods?: string[];
+    credentials?: boolean;
+    allowedHeaders?: string[];
+}): Middleware;
+/**
+ * Rate limiting middleware
+ */
+export declare function rateLimit(options?: {
+    windowMs?: number;
+    max?: number;
+    message?: string;
+}): Middleware;
+/**
+ * Request validation middleware
+ */
+export declare function validateRequest(schema: {
+    body?: (data: any) => boolean;
+    query?: (data: any) => boolean;
+    headers?: (data: any) => boolean;
+}): Middleware;
+/**
+ * Request logging middleware
+ */
+export declare function logger(options?: {
+    verbose?: boolean;
+    includeBody?: boolean;
+}): Middleware;
+/**
+ * Error handling middleware
+ */
+export declare function errorHandler(): Middleware;

package/dist/backend/middleware.js

@@ -0,0 +1,185 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.composeMiddleware = composeMiddleware;
+exports.cors = cors;
+exports.rateLimit = rateLimit;
+exports.validateRequest = validateRequest;
+exports.logger = logger;
+exports.errorHandler = errorHandler;
+/**
+ * Compose multiple middleware functions into a single handler
+ */
+function composeMiddleware(...middlewares) {
+    return (handler) => {
+        return async (req, res) => {
+            let index = 0;
+            const next = async () => {
+                if (index < middlewares.length) {
+                    const middleware = middlewares[index++];
+                    await middleware(req, res, next);
+                }
+                else {
+                    await handler(req, res);
+                }
+            };
+            await next();
+        };
+    };
+}
+/**
+ * CORS middleware for Next.js API routes
+ */
+function cors(options = {}) {
+    const { origin = '*', methods = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'], credentials = true, allowedHeaders = ['Content-Type', 'Authorization'], } = options;
+    return (req, res, next) => {
+        const requestOrigin = req.headers.origin || '*';
+        if (Array.isArray(origin)) {
+            if (origin.includes(requestOrigin)) {
+                res.setHeader('Access-Control-Allow-Origin', requestOrigin);
+            }
+        }
+        else if (origin === '*' || origin === requestOrigin) {
+            res.setHeader('Access-Control-Allow-Origin', origin);
+        }
+        res.setHeader('Access-Control-Allow-Methods', methods.join(', '));
+        res.setHeader('Access-Control-Allow-Headers', allowedHeaders.join(', '));
+        if (credentials) {
+            res.setHeader('Access-Control-Allow-Credentials', 'true');
+        }
+        // Handle preflight requests
+        if (req.method === 'OPTIONS') {
+            res.status(200).end();
+            return;
+        }
+        next();
+    };
+}
+/**
+ * Rate limiting middleware
+ */
+function rateLimit(options = {}) {
+    const { windowMs = 60000, // 1 minute
+    max = 60, // 60 requests per minute
+    message = 'Too many requests, please try again later.', } = options;
+    const requests = new Map();
+    return (req, res, next) => {
+        const identifier = req.headers['x-forwarded-for'] ||
+            req.socket.remoteAddress ||
+            'unknown';
+        const now = Date.now();
+        const windowStart = now - windowMs;
+        // Get existing requests for this identifier
+        let userRequests = requests.get(identifier) || [];
+        // Filter out requests outside the time window
+        userRequests = userRequests.filter(time => time > windowStart);
+        if (userRequests.length >= max) {
+            res.status(429).json({ error: message });
+            return;
+        }
+        // Add current request
+        userRequests.push(now);
+        requests.set(identifier, userRequests);
+        // Cleanup old entries periodically
+        if (Math.random() < 0.01) {
+            for (const [key, times] of requests.entries()) {
+                const filteredTimes = times.filter(time => time > windowStart);
+                if (filteredTimes.length === 0) {
+                    requests.delete(key);
+                }
+                else {
+                    requests.set(key, filteredTimes);
+                }
+            }
+        }
+        next();
+    };
+}
+/**
+ * Request validation middleware
+ */
+function validateRequest(schema) {
+    return (req, res, next) => {
+        try {
+            if (schema.body && !schema.body(req.body)) {
+                res.status(400).json({ error: 'Invalid request body' });
+                return;
+            }
+            if (schema.query && !schema.query(req.query)) {
+                res.status(400).json({ error: 'Invalid query parameters' });
+                return;
+            }
+            if (schema.headers && !schema.headers(req.headers)) {
+                res.status(400).json({ error: 'Invalid headers' });
+                return;
+            }
+            next();
+        }
+        catch (error) {
+            res.status(400).json({ error: 'Validation error' });
+        }
+    };
+}
+/**
+ * Request logging middleware
+ */
+function logger(options = {}) {
+    const { verbose = false, includeBody = false } = options;
+    return (req, res, next) => {
+        const start = Date.now();
+        const originalJson = res.json;
+        const originalSend = res.send;
+        const originalEnd = res.end;
+        let responseBody;
+        res.json = function (body) {
+            responseBody = body;
+            return originalJson.call(this, body);
+        };
+        res.send = function (body) {
+            responseBody = body;
+            return originalSend.call(this, body);
+        };
+        res.end = function (...args) {
+            const duration = Date.now() - start;
+            const logData = {
+                method: req.method,
+                url: req.url,
+                status: res.statusCode,
+                duration: `${duration}ms`,
+            };
+            if (verbose) {
+                logData.headers = req.headers;
+                logData.query = req.query;
+            }
+            if (includeBody && req.body) {
+                logData.requestBody = req.body;
+            }
+            console.log(`[API] ${req.method} ${req.url} - ${res.statusCode} (${duration}ms)`);
+            if (verbose) {
+                console.log(JSON.stringify(logData, null, 2));
+            }
+            return originalEnd.apply(this, args);
+        };
+        next();
+    };
+}
+/**
+ * Error handling middleware
+ */
+function errorHandler() {
+    return async (req, res, next) => {
+        try {
+            await next();
+        }
+        catch (error) {
+            console.error('[API Error]', error);
+            const isDev = process.env.NODE_ENV === 'development';
+            res.status(500).json({
+                error: 'Internal server error',
+                ...(isDev && {
+                    message: error instanceof Error ? error.message : 'Unknown error',
+                    stack: error instanceof Error ? error.stack : undefined
+                }),
+            });
+        }
+    };
+}

package/dist/backend/optimization.d.ts

@@ -0,0 +1,63 @@
+import { NextApiRequest, NextApiResponse } from 'next';
+import { Middleware } from './middleware';
+/**
+ * Compression middleware for API responses
+ */
+export declare function compress(options?: {
+    threshold?: number;
+    level?: number;
+}): Middleware;
+/**
+ * Response time tracking
+ */
+export declare function responseTime(): Middleware;
+/**
+ * Pagination helper for API responses
+ */
+export interface PaginationOptions {
+    page?: number;
+    limit?: number;
+    maxLimit?: number;
+}
+export interface PaginatedResponse<T> {
+    data: T[];
+    pagination: {
+        page: number;
+        limit: number;
+        total: number;
+        totalPages: number;
+        hasNext: boolean;
+        hasPrev: boolean;
+    };
+}
+export declare function paginate<T>(data: T[], options?: PaginationOptions): PaginatedResponse<T>;
+/**
+ * Parse pagination params from request
+ */
+export declare function getPaginationParams(req: NextApiRequest): PaginationOptions;
+/**
+ * JSON response helper with consistent format
+ */
+export declare function jsonResponse<T = any>(res: NextApiResponse, options: {
+    status?: number;
+    data?: T;
+    error?: string;
+    message?: string;
+    meta?: Record<string, any>;
+}): void;
+/**
+ * API response formatter middleware
+ */
+export declare function formatResponse(): Middleware;
+/**
+ * Request timeout middleware
+ */
+export declare function timeout(ms: number): Middleware;
+/**
+ * Body size limiter
+ */
+export declare function bodyLimit(maxSize: number): Middleware;
+/**
+ * Method filter middleware
+ */
+export declare function allowMethods(methods: string[]): Middleware;

package/dist/backend/optimization.js

@@ -0,0 +1,186 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compress = compress;
+exports.responseTime = responseTime;
+exports.paginate = paginate;
+exports.getPaginationParams = getPaginationParams;
+exports.jsonResponse = jsonResponse;
+exports.formatResponse = formatResponse;
+exports.timeout = timeout;
+exports.bodyLimit = bodyLimit;
+exports.allowMethods = allowMethods;
+/**
+ * Compression middleware for API responses
+ */
+function compress(options = {}) {
+    const { threshold = 1024 } = options; // 1KB default threshold
+    return (req, res, next) => {
+        const acceptEncoding = req.headers['accept-encoding'] || '';
+        if (!acceptEncoding.includes('gzip')) {
+            next();
+            return;
+        }
+        const originalJson = res.json;
+        const originalSend = res.send;
+        res.json = function (data) {
+            const jsonString = JSON.stringify(data);
+            if (jsonString.length > threshold) {
+                res.setHeader('Content-Encoding', 'gzip');
+                res.setHeader('Vary', 'Accept-Encoding');
+            }
+            return originalJson.call(this, data);
+        };
+        res.send = function (data) {
+            if (typeof data === 'string' && data.length > threshold) {
+                res.setHeader('Content-Encoding', 'gzip');
+                res.setHeader('Vary', 'Accept-Encoding');
+            }
+            return originalSend.call(this, data);
+        };
+        next();
+    };
+}
+/**
+ * Response time tracking
+ */
+function responseTime() {
+    return (req, res, next) => {
+        const start = process.hrtime();
+        const originalEnd = res.end;
+        res.end = function (...args) {
+            const diff = process.hrtime(start);
+            const time = (diff[0] * 1e9 + diff[1]) / 1e6; // Convert to milliseconds
+            res.setHeader('X-Response-Time', `${time.toFixed(2)}ms`);
+            return originalEnd.apply(this, args);
+        };
+        next();
+    };
+}
+function paginate(data, options = {}) {
+    const { page = 1, limit = 10, maxLimit = 100, } = options;
+    const actualLimit = Math.min(limit, maxLimit);
+    const actualPage = Math.max(1, page);
+    const startIndex = (actualPage - 1) * actualLimit;
+    const endIndex = startIndex + actualLimit;
+    const paginatedData = data.slice(startIndex, endIndex);
+    const total = data.length;
+    const totalPages = Math.ceil(total / actualLimit);
+    return {
+        data: paginatedData,
+        pagination: {
+            page: actualPage,
+            limit: actualLimit,
+            total,
+            totalPages,
+            hasNext: actualPage < totalPages,
+            hasPrev: actualPage > 1,
+        },
+    };
+}
+/**
+ * Parse pagination params from request
+ */
+function getPaginationParams(req) {
+    const page = parseInt(req.query.page) || 1;
+    const limit = parseInt(req.query.limit) || 10;
+    return { page, limit };
+}
+/**
+ * JSON response helper with consistent format
+ */
+function jsonResponse(res, options) {
+    const { status = 200, data, error, message, meta } = options;
+    const response = {};
+    if (data !== undefined) {
+        response.data = data;
+    }
+    if (message) {
+        response.message = message;
+    }
+    if (error) {
+        response.error = error;
+    }
+    if (meta) {
+        response.meta = meta;
+    }
+    return res.status(status).json(response);
+}
+/**
+ * API response formatter middleware
+ */
+function formatResponse() {
+    return (req, res, next) => {
+        const originalJson = res.json;
+        res.json = function (data) {
+            const formattedResponse = {
+                success: res.statusCode >= 200 && res.statusCode < 300,
+                statusCode: res.statusCode,
+                data,
+                timestamp: new Date().toISOString(),
+            };
+            return originalJson.call(this, formattedResponse);
+        };
+        next();
+    };
+}
+/**
+ * Request timeout middleware
+ */
+function timeout(ms) {
+    return async (req, res, next) => {
+        const timeoutPromise = new Promise((_, reject) => {
+            setTimeout(() => {
+                reject(new Error(`Request timeout after ${ms}ms`));
+            }, ms);
+        });
+        try {
+            await Promise.race([
+                next(),
+                timeoutPromise,
+            ]);
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes('timeout')) {
+                res.status(408).json({
+                    error: 'Request timeout',
+                    message: error.message,
+                });
+            }
+            else {
+                throw error;
+            }
+        }
+    };
+}
+/**
+ * Body size limiter
+ */
+function bodyLimit(maxSize) {
+    return (req, res, next) => {
+        const contentLength = parseInt(req.headers['content-length'] || '0');
+        if (contentLength > maxSize) {
+            res.status(413).json({
+                error: 'Payload too large',
+                maxSize: `${maxSize} bytes`,
+            });
+            return;
+        }
+        next();
+    };
+}
+/**
+ * Method filter middleware
+ */
+function allowMethods(methods) {
+    const allowedMethods = methods.map(m => m.toUpperCase());
+    return (req, res, next) => {
+        if (!req.method || !allowedMethods.includes(req.method.toUpperCase())) {
+            res.status(405).json({
+                error: 'Method not allowed',
+                allowed: allowedMethods,
+            });
+            return;
+        }
+        next();
+    };
+}

package/dist/index.d.ts

@@ -10,3 +10,6 @@ export * from "./performance/Lazy";
 export * from "./performance/cacheHeaders";
 export * from "./performance/securityHeaders";
 export * from "./analytics/webVitals";
+export * from "./backend/middleware";
+export * from "./backend/cache";
+export * from "./backend/optimization";

package/dist/index.js

@@ -30,3 +30,7 @@ __exportStar(require("./performance/cacheHeaders"), exports);
 __exportStar(require("./performance/securityHeaders"), exports);
 // Analytics
 __exportStar(require("./analytics/webVitals"), exports);
+// Backend
+__exportStar(require("./backend/middleware"), exports);
+__exportStar(require("./backend/cache"), exports);
+__exportStar(require("./backend/optimization"), exports);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rkk-next",
-  "version": "1.0.0",
-  "description": "SEO, routing and performance optimization SDK for Next.js",
+  "version": "1.1.0",
+  "description": "SEO, routing, performance optimization and backend utilities SDK for Next.js",
   "author": "Rohit Kumar Kundu",
   "license": "MIT",
   "main": "dist/index.js",
@@ -20,8 +20,10 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
-    "prepublishOnly": "npm run build",
-    "test": "echo \"Tests coming soon\" && exit 0"
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "prepublishOnly": "npm run build"
   },
   "peerDependencies": {
     "next": ">=12",
@@ -29,9 +31,15 @@
     "react-dom": ">=17"
   },
   "devDependencies": {
+    "@testing-library/jest-dom": "^6.1.5",
+    "@testing-library/react": "^14.1.2",
+    "@types/jest": "^29.5.11",
     "@types/node": "^20.10.0",
     "@types/react": "^18.2.45",
     "@types/react-dom": "^18.2.18",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "ts-jest": "^29.1.1",
     "typescript": "^5.3.3"
   },
   "keywords": [
@@ -46,6 +54,13 @@
     "react",
     "meta-tags",
     "json-ld",
-    "prefetch"
+    "prefetch",
+    "middleware",
+    "api-routes",
+    "backend",
+    "caching",
+    "rate-limiting",
+    "cors",
+    "express"
   ]
 }