@singhey/spa-ssr-renderer 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 singhey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,247 @@
+# @singhey/spa-ssr-renderer
+
+A Node.js server application that intelligently serves Single Page Applications (SPAs) by providing server-side rendered content to bots and crawlers while serving the original SPA files to regular users.
+
+## Features
+
+- **Bot Detection**: Identifies web crawlers and search engine bots using ua-parser-js
+- **Server-Side Rendering**: Uses Playwright for headless browser rendering
+- **Intelligent Caching**: TTL-based cache with `@isaacs/ttlcache`
+- **Static File Serving**: Efficient serving of static assets with SPA fallback
+- **Sitemap Support**: Parse sitemaps to discover paths for pre-rendering
+- **Exclusion Patterns**: Flexible path exclusion with wildcard support
+- **Graceful Fallbacks**: Continues operation even when components fail
+- **Library & CLI**: Can be used as an importable library or standalone CLI tool
+
+## Installation
+
+```bash
+npm install @singhey/spa-ssr-renderer
+# or
+pnpm add @singhey/spa-ssr-renderer
+# or
+yarn add @singhey/spa-ssr-renderer
+```
+
+## Usage
+
+### As a Library
+
+Import and use the server in your Node.js application:
+
+```typescript
+import { SPASSRServer, ServerConfig } from '@singhey/spa-ssr-renderer';
+
+// Define your configuration
+const config: ServerConfig = {
+  port: 3000,
+  staticDir: 'public',
+  spaEntryPoint: 'index.html',
+  prerender: {
+    // Explicit paths to pre-render
+    paths: ['/', '/about', '/products'],
+    
+    // Sitemaps to parse (URLs or local file paths)
+    sitemaps: ['https://example.com/sitemap.xml', './public/sitemap.xml'],
+    
+    // Paths or patterns to exclude (supports wildcards)
+    exclude: ['/admin/*', '/api/*', '/private']
+  },
+  cache: {
+    type: 'memory',
+    ttl: 300000, // 5 minutes
+    maxSize: 100,
+  },
+  renderer: {
+    timeout: 30000,
+    viewport: { width: 1280, height: 720 },
+    waitForNetworkIdle: false,
+  },
+  botDetection: {
+    customPatterns: [],
+    enableVerification: false,
+  },
+};
+
+// Create and start server
+const server = new SPASSRServer({ config });
+
+await server.start();
+console.log('Server running!');
+
+// Access underlying Fastify instance for custom routes
+const fastifyInstance = server.getServer();
+fastifyInstance.get('/api/custom', async () => {
+  return { message: 'Custom endpoint' };
+});
+
+// Graceful shutdown
+process.on('SIGTERM', async () => {
+  await server.stop();
+});
+```
+
+### As a CLI Tool
+
+Run directly from the command line:
+
+```bash
+# Using npx
+npx @singhey/spa-ssr-renderer
+
+# Or install globally
+npm install -g @singhey/spa-ssr-renderer
+spa-ssr-renderer
+```
+
+### Environment Variables
+
+Configure the server using environment variables:
+
+- `PORT` - Server port (default: 3000)
+- `STATIC_DIR` - Static files directory (default: public)
+- `SPA_ENTRY_POINT` - SPA entry file (default: index.html)
+- **Pre-rendering Configuration:**
+  - `PRERENDER_PATHS` - Comma-separated list of paths to pre-render (e.g., "/,/about,/products")
+  - `PRERENDER_SITEMAPS` - Comma-separated list of sitemap URLs or file paths (e.g., "https://example.com/sitemap.xml,./public/sitemap.xml")
+  - `PRERENDER_EXCLUDE` - Comma-separated list of paths or patterns to exclude (supports wildcards: `*` and `?`)
+- `CACHE_TYPE` - Cache type: memory|redis (default: memory)
+- `CACHE_TTL` - Cache TTL in ms (default: 300000)
+- `RENDER_TIMEOUT` - Render timeout in ms (default: 30000)
+- `VIEWPORT_WIDTH` - Render viewport width (default: 1280)
+- `VIEWPORT_HEIGHT` - Render viewport height (default: 720)
+
+## How It Works
+
+1. **Static Files**: If a file exists in the static directory, it's served directly
+2. **Pre-rendering**: On startup, specified paths are rendered using Playwright and cached
+   - **Explicit Paths**: Define specific paths to pre-render
+   - **Sitemap Support**: Parse sitemaps (URLs or local files) to discover paths
+   - **Exclusions**: Use patterns to exclude paths from pre-rendering (e.g., `/admin/*`, `/api/*`)
+3. **Bot Detection**: Incoming requests are analyzed for bot User-Agents using ua-parser-js
+4. **Smart Serving**:
+   - **Bots**: Served pre-rendered, cached HTML for instant SEO-friendly content
+   - **Regular Users**: Served the SPA entry point for full client-side interactivity
+5. **SPA Fallback**: For routes without file extensions, serves the SPA entry point (index.html)
+6. **Caching**: Pre-rendered content is cached using `@isaacs/ttlcache` with configurable TTL
+
+### Pre-rendering Configuration Examples
+
+**Explicit paths only:**
+```typescript
+prerender: {
+  paths: ['/', '/about', '/products', '/contact']
+}
+```
+
+**Using sitemaps:**
+```typescript
+prerender: {
+  sitemaps: [
+    'https://example.com/sitemap.xml',  // Remote sitemap
+    './public/sitemap.xml'               // Local sitemap
+  ]
+}
+```
+
+**With exclusions (supports wildcards):**
+```typescript
+prerender: {
+  paths: ['/', '/about', '/products'],
+  sitemaps: ['./public/sitemap.xml'],
+  exclude: [
+    '/admin/*',      // Exclude all admin paths
+    '/api/*',        // Exclude all API paths
+    '/private',      // Exclude specific path
+    '*/draft'        // Exclude all draft pages
+  ]
+}
+```
+
+**Combined configuration:**
+```typescript
+prerender: {
+  paths: ['/', '/about'],              // Always pre-render these
+  sitemaps: ['./public/sitemap.xml'],  // Plus paths from sitemap
+  exclude: ['/admin/*', '/api/*']      // But exclude these patterns
+}
+```
+
+## Project Structure
+
+```
+src/
+├── components/          # Core application components
+│   ├── BotDetector.ts   # Bot detection logic
+│   ├── FileServer.ts    # Static file serving
+│   ├── RequestRouter.ts # Request routing and classification
+│   ├── CacheManager.ts  # Caching system
+│   ├── SSRRenderer.ts   # Server-side rendering
+│   └── index.ts         # Component exports
+├── config/              # Configuration management
+│   └── index.ts         # Default config and environment loading
+├── types/               # TypeScript interfaces and types
+│   └── index.ts         # All type definitions
+├── utils/               # Shared utilities
+│   ├── logger.ts        # Logging utilities
+│   └── index.ts         # Utility exports
+├── __tests__/           # Test files
+│   └── setup.test.ts    # Foundation tests
+└── index.ts             # Main application entry point
+```
+
+## Development
+
+### Prerequisites
+
+- Node.js 18+
+- pnpm
+
+### Installation
+
+```bash
+pnpm install
+npx playwright install
+```
+
+### Scripts
+
+- `pnpm dev` - Start development server with hot reload
+- `pnpm build` - Build for production
+- `pnpm start` - Start production server
+- `pnpm test` - Run tests
+- `pnpm test:watch` - Run tests in watch mode
+- `pnpm test:coverage` - Run tests with coverage
+
+### Environment Variables
+
+- `PORT` - Server port (default: 3000)
+- `STATIC_DIR` - Static files directory (default: public)
+- `SPA_ENTRY_POINT` - SPA entry file (default: index.html)
+- `CACHE_TYPE` - Cache type: memory|redis (default: memory)
+- `CACHE_TTL` - Cache TTL in ms (default: 300000)
+- `RENDER_TIMEOUT` - Render timeout in ms (default: 30000)
+- `VIEWPORT_WIDTH` - Render viewport width (default: 1280)
+- `VIEWPORT_HEIGHT` - Render viewport height (default: 720)
+
+## Implementation Status
+
+This is the foundation setup. Core functionality will be implemented in subsequent tasks:
+
+- [x] Task 1: Project foundation and interfaces
+- [ ] Task 2: Bot Detection System
+- [ ] Task 3: File Server Component
+- [ ] Task 4: Request Router
+- [ ] Task 5: Cache Manager
+- [ ] Task 6: SSR Renderer
+- [ ] Task 7: Main Server Integration
+- [ ] Task 8: Configuration System
+- [ ] Task 9: Final Integration
+
+## Testing
+
+The project uses Jest for unit testing and fast-check for property-based testing. Each component will have comprehensive test coverage including:
+
+- Unit tests for specific scenarios
+- Property-based tests for universal behaviors
+- Integration tests for component interactions

package/dist/__tests__/setup.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=setup.test.d.ts.map

package/dist/__tests__/setup.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/setup.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/setup.test.js

@@ -0,0 +1,22 @@
+import { loadConfig } from '../config/index.js';
+import { ConsoleLogger } from '../utils/index.js';
+describe('Project Foundation Setup', () => {
+    test('should load default configuration', () => {
+        const config = loadConfig();
+        expect(config).toBeDefined();
+        expect(config.port).toBe(3000);
+        expect(config.staticDir).toBe('public');
+        expect(config.spaEntryPoint).toBe('index.html');
+        expect(config.cache.type).toBe('memory');
+        expect(config.renderer.timeout).toBe(30000);
+    });
+    test('should create logger instance', () => {
+        const logger = new ConsoleLogger();
+        expect(logger).toBeDefined();
+        expect(typeof logger.info).toBe('function');
+        expect(typeof logger.warn).toBe('function');
+        expect(typeof logger.error).toBe('function');
+        expect(typeof logger.debug).toBe('function');
+    });
+});
+//# sourceMappingURL=setup.test.js.map

package/dist/__tests__/setup.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.test.js","sourceRoot":"","sources":["../../src/__tests__/setup.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD,QAAQ,CAAC,0BAA0B,EAAE,GAAG,EAAE;IACxC,IAAI,CAAC,mCAAmC,EAAE,GAAG,EAAE;QAC7C,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;QAE5B,MAAM,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,CAAC;QAC7B,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/B,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACxC,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAChD,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACzC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACzC,MAAM,MAAM,GAAG,IAAI,aAAa,EAAE,CAAC;QAEnC,MAAM,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,CAAC;QAC7B,MAAM,CAAC,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC5C,MAAM,CAAC,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC5C,MAAM,CAAC,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC7C,MAAM,CAAC,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC/C,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/components/BotDetector.d.ts

@@ -0,0 +1,12 @@
+import { BotDetector as IBotDetector, BotInfo } from '../types/index.js';
+export declare class BotDetector implements IBotDetector {
+    private customPatterns;
+    private parser;
+    private readonly knownBots;
+    constructor();
+    isBot(userAgent: string): boolean;
+    addBotPattern(pattern: RegExp): void;
+    getBotInfo(userAgent: string): BotInfo | null;
+    parseUserAgent(userAgent: string): UAParser.IResult;
+}
+//# sourceMappingURL=BotDetector.d.ts.map

package/dist/components/BotDetector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BotDetector.d.ts","sourceRoot":"","sources":["../../src/components/BotDetector.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,IAAI,YAAY,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAIzE,qBAAa,WAAY,YAAW,YAAY;IAC9C,OAAO,CAAC,cAAc,CAAgB;IACtC,OAAO,CAAC,MAAM,CAAW;IAGzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAuBxB;;IAMF,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAIjC,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAIpC,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI;IAI7C,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,CAAC,OAAO;CAGpD"}

package/dist/components/BotDetector.js

@@ -0,0 +1,46 @@
+import { UAParser } from 'ua-parser-js';
+import { isBot } from 'ua-parser-js/bot-detection';
+export class BotDetector {
+    constructor() {
+        this.customPatterns = [];
+        // Known bot patterns organized by type
+        this.knownBots = {
+            search: [
+                { name: 'Googlebot', patterns: ['googlebot', 'google'] },
+                { name: 'Bingbot', patterns: ['bingbot', 'msnbot'] },
+                { name: 'Yahoo Slurp', patterns: ['slurp'] },
+                { name: 'DuckDuckBot', patterns: ['duckduckbot'] },
+                { name: 'Baiduspider', patterns: ['baiduspider'] },
+                { name: 'YandexBot', patterns: ['yandexbot'] }
+            ],
+            social: [
+                { name: 'Facebook', patterns: ['facebookexternalhit', 'facebookcatalog'] },
+                { name: 'Twitter', patterns: ['twitterbot'] },
+                { name: 'LinkedIn', patterns: ['linkedinbot'] },
+                { name: 'Pinterest', patterns: ['pinterest'] },
+                { name: 'WhatsApp', patterns: ['whatsapp'] },
+                { name: 'Telegram', patterns: ['telegrambot'] }
+            ],
+            ai: [
+                { name: 'ChatGPT', patterns: ['chatgpt-user', 'gptbot'] },
+                { name: 'Claude', patterns: ['claude-web', 'anthropic'] },
+                { name: 'Perplexity', patterns: ['perplexitybot'] },
+                { name: 'Bing AI', patterns: ['edgechat', 'sydney'] }
+            ]
+        };
+        this.parser = new UAParser();
+    }
+    isBot(userAgent) {
+        return isBot(userAgent);
+    }
+    addBotPattern(pattern) {
+        this.customPatterns.push(pattern);
+    }
+    getBotInfo(userAgent) {
+        return null;
+    }
+    parseUserAgent(userAgent) {
+        return this.parser.setUA(userAgent).getResult();
+    }
+}
+//# sourceMappingURL=BotDetector.js.map

package/dist/components/BotDetector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BotDetector.js","sourceRoot":"","sources":["../../src/components/BotDetector.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAA;AAElD,MAAM,OAAO,WAAW;IA8BtB;QA7BQ,mBAAc,GAAa,EAAE,CAAC;QAGtC,uCAAuC;QACtB,cAAS,GAAG;YAC3B,MAAM,EAAE;gBACN,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC,WAAW,EAAE,QAAQ,CAAC,EAAE;gBACxD,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,EAAE;gBACpD,EAAE,IAAI,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE;gBAC5C,EAAE,IAAI,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAC,aAAa,CAAC,EAAE;gBAClD,EAAE,IAAI,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAC,aAAa,CAAC,EAAE;gBAClD,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC,WAAW,CAAC,EAAE;aAC/C;YACD,MAAM,EAAE;gBACN,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC,qBAAqB,EAAE,iBAAiB,CAAC,EAAE;gBAC1E,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,YAAY,CAAC,EAAE;gBAC7C,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC,aAAa,CAAC,EAAE;gBAC/C,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC,WAAW,CAAC,EAAE;gBAC9C,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC,UAAU,CAAC,EAAE;gBAC5C,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC,aAAa,CAAC,EAAE;aAChD;YACD,EAAE,EAAE;gBACF,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,cAAc,EAAE,QAAQ,CAAC,EAAE;gBACzD,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,YAAY,EAAE,WAAW,CAAC,EAAE;gBACzD,EAAE,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,eAAe,CAAC,EAAE;gBACnD,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,UAAU,EAAE,QAAQ,CAAC,EAAE;aACtD;SACF,CAAC;QAGA,IAAI,CAAC,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;IAC/B,CAAC;IAED,KAAK,CAAC,SAAiB;QACrB,OAAO,KAAK,CAAC,SAAS,CAAC,CAAA;IACzB,CAAC;IAED,aAAa,CAAC,OAAe;QAC3B,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC;IAED,UAAU,CAAC,SAAiB;QAC1B,OAAO,IAAI,CAAA;IACb,CAAC;IAED,cAAc,CAAC,SAAiB;QAC9B,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,SAAS,EAAE,CAAC;IAClD,CAAC;CACF"}

package/dist/components/CacheManager.d.ts

@@ -0,0 +1,13 @@
+import { CacheManager as ICacheManager, CacheStats } from '../types/index.js';
+export declare class CacheManager implements ICacheManager {
+    private cache;
+    private stats;
+    private defaultTTL;
+    constructor(maxSize?: number, defaultTTL?: number);
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttl?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    getStats(): CacheStats;
+}
+//# sourceMappingURL=CacheManager.d.ts.map

package/dist/components/CacheManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CacheManager.d.ts","sourceRoot":"","sources":["../../src/components/CacheManager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,IAAI,aAAa,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAG9E,qBAAa,YAAa,YAAW,aAAa;IAChD,OAAO,CAAC,KAAK,CAA2B;IACxC,OAAO,CAAC,KAAK,CAGX;IACF,OAAO,CAAC,UAAU,CAAS;gBAEf,OAAO,GAAE,MAAY,EAAE,UAAU,GAAE,MAAe;IAQxD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAYxC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK5D,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B,QAAQ,IAAI,UAAU;CAWvB"}

package/dist/components/CacheManager.js

@@ -0,0 +1,46 @@
+import { TTLCache } from '@isaacs/ttlcache';
+export class CacheManager {
+    constructor(maxSize = 100, defaultTTL = 300000) {
+        this.stats = {
+            hits: 0,
+            misses: 0,
+        };
+        this.defaultTTL = defaultTTL;
+        this.cache = new TTLCache({
+            max: maxSize,
+            ttl: defaultTTL,
+        });
+    }
+    async get(key) {
+        const value = this.cache.get(key);
+        if (value === undefined) {
+            this.stats.misses++;
+            return null;
+        }
+        this.stats.hits++;
+        return value;
+    }
+    async set(key, value, ttl) {
+        const effectiveTTL = ttl || this.defaultTTL;
+        this.cache.set(key, value, { ttl: effectiveTTL });
+    }
+    async delete(key) {
+        this.cache.delete(key);
+    }
+    async clear() {
+        this.cache.clear();
+        this.stats.hits = 0;
+        this.stats.misses = 0;
+    }
+    getStats() {
+        const totalRequests = this.stats.hits + this.stats.misses;
+        const hitRate = totalRequests > 0 ? this.stats.hits / totalRequests : 0;
+        return {
+            hits: this.stats.hits,
+            misses: this.stats.misses,
+            size: this.cache.size,
+            hitRate,
+        };
+    }
+}
+//# sourceMappingURL=CacheManager.js.map

package/dist/components/CacheManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CacheManager.js","sourceRoot":"","sources":["../../src/components/CacheManager.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,MAAM,OAAO,YAAY;IAQvB,YAAY,UAAkB,GAAG,EAAE,aAAqB,MAAM;QANtD,UAAK,GAAG;YACd,IAAI,EAAE,CAAC;YACP,MAAM,EAAE,CAAC;SACV,CAAC;QAIA,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,KAAK,GAAG,IAAI,QAAQ,CAAC;YACxB,GAAG,EAAE,OAAO;YACZ,GAAG,EAAE,UAAU;SAChB,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAElC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;YACpB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QAClB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,KAAa,EAAE,GAAY;QAChD,MAAM,YAAY,GAAG,GAAG,IAAI,IAAI,CAAC,UAAU,CAAC;QAC5C,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,YAAY,EAAE,CAAC,CAAC;IACpD,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACnB,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC;QACpB,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;IACxB,CAAC;IAED,QAAQ;QACN,MAAM,aAAa,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;QAC1D,MAAM,OAAO,GAAG,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;QAExE,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI;YACrB,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM;YACzB,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI;YACrB,OAAO;SACR,CAAC;IACJ,CAAC;CACF"}

package/dist/components/FileServer.d.ts

@@ -0,0 +1,7 @@
+import { FileServer as IFileServer, Response } from '../types/index.js';
+export declare class FileServer implements IFileServer {
+    serveFile(filePath: string, res: Response): Promise<void>;
+    getMimeType(extension: string): string;
+    setSecurityHeaders(res: Response): void;
+}
+//# sourceMappingURL=FileServer.d.ts.map

package/dist/components/FileServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileServer.d.ts","sourceRoot":"","sources":["../../src/components/FileServer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,IAAI,WAAW,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAExE,qBAAa,UAAW,YAAW,WAAW;IACtC,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAK/D,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAKtC,kBAAkB,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI;CAIxC"}

package/dist/components/FileServer.js

@@ -0,0 +1,15 @@
+export class FileServer {
+    async serveFile(filePath, res) {
+        // Implementation will be added in task 3
+        throw new Error('Method not implemented.');
+    }
+    getMimeType(extension) {
+        // Implementation will be added in task 3
+        throw new Error('Method not implemented.');
+    }
+    setSecurityHeaders(res) {
+        // Implementation will be added in task 3
+        throw new Error('Method not implemented.');
+    }
+}
+//# sourceMappingURL=FileServer.js.map

package/dist/components/FileServer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileServer.js","sourceRoot":"","sources":["../../src/components/FileServer.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,UAAU;IACrB,KAAK,CAAC,SAAS,CAAC,QAAgB,EAAE,GAAa;QAC7C,yCAAyC;QACzC,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;IAC7C,CAAC;IAED,WAAW,CAAC,SAAiB;QAC3B,yCAAyC;QACzC,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;IAC7C,CAAC;IAED,kBAAkB,CAAC,GAAa;QAC9B,yCAAyC;QACzC,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;IAC7C,CAAC;CACF"}

package/dist/components/RequestRouter.d.ts

@@ -0,0 +1,7 @@
+import { RequestRouter as IRequestRouter, Request, Response } from '../types/index.js';
+export declare class RequestRouter implements IRequestRouter {
+    handleRequest(req: Request, res: Response): Promise<void>;
+    isFileRequest(path: string): boolean;
+    fileExists(path: string): boolean;
+}
+//# sourceMappingURL=RequestRouter.d.ts.map

package/dist/components/RequestRouter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RequestRouter.d.ts","sourceRoot":"","sources":["../../src/components/RequestRouter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,IAAI,cAAc,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAEvF,qBAAa,aAAc,YAAW,cAAc;IAC5C,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAK/D,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAKpC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;CAIlC"}

package/dist/components/RequestRouter.js

@@ -0,0 +1,15 @@
+export class RequestRouter {
+    async handleRequest(req, res) {
+        // Implementation will be added in task 4
+        throw new Error('Method not implemented.');
+    }
+    isFileRequest(path) {
+        // Implementation will be added in task 4
+        throw new Error('Method not implemented.');
+    }
+    fileExists(path) {
+        // Implementation will be added in task 4
+        throw new Error('Method not implemented.');
+    }
+}
+//# sourceMappingURL=RequestRouter.js.map

package/dist/components/RequestRouter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RequestRouter.js","sourceRoot":"","sources":["../../src/components/RequestRouter.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,aAAa;IACxB,KAAK,CAAC,aAAa,CAAC,GAAY,EAAE,GAAa;QAC7C,yCAAyC;QACzC,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;IAC7C,CAAC;IAED,aAAa,CAAC,IAAY;QACxB,yCAAyC;QACzC,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;IAC7C,CAAC;IAED,UAAU,CAAC,IAAY;QACrB,yCAAyC;QACzC,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;IAC7C,CAAC;CACF"}

package/dist/components/SSRRenderer.d.ts

@@ -0,0 +1,9 @@
+import { SSRRenderer as ISSRRenderer, RenderOptions } from '../types/index.js';
+export declare class SSRRenderer implements ISSRRenderer {
+    private browser;
+    private isInitialized;
+    initialize(): Promise<void>;
+    render(url: string, options?: RenderOptions): Promise<string>;
+    cleanup(): Promise<void>;
+}
+//# sourceMappingURL=SSRRenderer.d.ts.map

package/dist/components/SSRRenderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SSRRenderer.d.ts","sourceRoot":"","sources":["../../src/components/SSRRenderer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,IAAI,YAAY,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAG/E,qBAAa,WAAY,YAAW,YAAY;IAC9C,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,aAAa,CAAS;IAExB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAY3B,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IAsC7D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAO/B"}

package/dist/components/SSRRenderer.js

@@ -0,0 +1,55 @@
+import { chromium } from 'playwright';
+export class SSRRenderer {
+    constructor() {
+        this.browser = null;
+        this.isInitialized = false;
+    }
+    async initialize() {
+        if (this.isInitialized) {
+            return;
+        }
+        this.browser = await chromium.launch({
+            headless: true,
+            args: ['--no-sandbox', '--disable-setuid-sandbox'],
+        });
+        this.isInitialized = true;
+    }
+    async render(url, options) {
+        if (!this.browser) {
+            await this.initialize();
+        }
+        if (!this.browser) {
+            throw new Error('Browser not initialized');
+        }
+        const page = await this.browser.newPage({
+            viewport: options?.viewport || { width: 1280, height: 720 },
+        });
+        try {
+            const timeout = options?.timeout || 30000;
+            await page.goto(url, {
+                waitUntil: options?.waitForNetworkIdle ? 'networkidle' : 'domcontentloaded',
+                timeout,
+            });
+            // Wait for specific selector if provided
+            if (options?.waitForSelector) {
+                await page.waitForSelector(options.waitForSelector, { timeout });
+            }
+            // Get the rendered HTML
+            const html = await page.content();
+            await page.close();
+            return html;
+        }
+        catch (error) {
+            await page.close();
+            throw error;
+        }
+    }
+    async cleanup() {
+        if (this.browser) {
+            await this.browser.close();
+            this.browser = null;
+            this.isInitialized = false;
+        }
+    }
+}
+//# sourceMappingURL=SSRRenderer.js.map

package/dist/components/SSRRenderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SSRRenderer.js","sourceRoot":"","sources":["../../src/components/SSRRenderer.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAiB,MAAM,YAAY,CAAC;AAErD,MAAM,OAAO,WAAW;IAAxB;QACU,YAAO,GAAmB,IAAI,CAAC;QAC/B,kBAAa,GAAG,KAAK,CAAC;IA2DhC,CAAC;IAzDC,KAAK,CAAC,UAAU;QACd,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACvB,OAAO;QACT,CAAC;QAED,IAAI,CAAC,OAAO,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC;YACnC,QAAQ,EAAE,IAAI;YACd,IAAI,EAAE,CAAC,cAAc,EAAE,0BAA0B,CAAC;SACnD,CAAC,CAAC;QACH,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC;IAC5B,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW,EAAE,OAAuB;QAC/C,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;QAC1B,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;QAC7C,CAAC;QAED,MAAM,IAAI,GAAS,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC;YAC5C,QAAQ,EAAE,OAAO,EAAE,QAAQ,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE;SAC5D,CAAC,CAAC;QAEH,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,KAAK,CAAC;YAE1C,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE;gBACnB,SAAS,EAAE,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,kBAAkB;gBAC3E,OAAO;aACR,CAAC,CAAC;YAEH,yCAAyC;YACzC,IAAI,OAAO,EAAE,eAAe,EAAE,CAAC;gBAC7B,MAAM,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,eAAe,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;YACnE,CAAC;YAED,wBAAwB;YACxB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;YAElC,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;YAEnB,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;YACnB,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,KAAK,CAAC,OAAO;QACX,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;YAC3B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;YACpB,IAAI,CAAC,aAAa,GAAG,KAAK,CAAC;QAC7B,CAAC;IACH,CAAC;CACF"}

package/dist/components/index.d.ts

@@ -0,0 +1,6 @@
+export { BotDetector } from './BotDetector.js';
+export { FileServer } from './FileServer.js';
+export { RequestRouter } from './RequestRouter.js';
+export { CacheManager } from './CacheManager.js';
+export { SSRRenderer } from './SSRRenderer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/components/index.js

@@ -0,0 +1,6 @@
+export { BotDetector } from './BotDetector.js';
+export { FileServer } from './FileServer.js';
+export { RequestRouter } from './RequestRouter.js';
+export { CacheManager } from './CacheManager.js';
+export { SSRRenderer } from './SSRRenderer.js';
+//# sourceMappingURL=index.js.map

package/dist/components/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/config/index.d.ts

@@ -0,0 +1,4 @@
+import { ServerConfig } from '../types/index.js';
+export declare const defaultConfig: ServerConfig;
+export declare function loadConfig(): ServerConfig;
+//# sourceMappingURL=index.d.ts.map

package/dist/config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAIjD,eAAO,MAAM,aAAa,EAAE,YAqC3B,CAAC;AAEF,wBAAgB,UAAU,IAAI,YAAY,CAEzC"}