koa-classic-server 3.0.0 → 3.1.0

package/docs/PERFORMANCE_COMPARISON.md

@@ -1,388 +0,0 @@
-# Performance Comparison: v1.2.0 → v2.0.0
-
-## Executive Summary
-
-**Version 2.0.0 "Performance Edition"** delivers significant performance improvements through:
-- All sync operations converted to async (non-blocking event loop)
-- String concatenation optimized to array join (30-40% less memory)
-- HTTP caching with ETag and Last-Modified (80-95% bandwidth reduction when cached)
-
----
-
-## Benchmark Results Comparison
-
-### File Serving Performance
-
-| Operation | v1.2.0 (before) | v2.0.0 (after) | Improvement |
-|-----------|-----------------|----------------|-------------|
-| **Small file (1KB)** | 2.93ms | 2.93ms | ~0% (same) |
-| **Medium file (100KB)** | 3.59ms | 3.13ms | **13% faster** ✅ |
-| **Large file (1MB)** | 9.03ms | 8.76ms | **3% faster** ✅ |
-
-**Analysis**: Small improvements in file serving due to async operations removing event loop blocking.
-
----
-
-### Directory Listing Performance
-
-| Operation | v1.2.0 (before) | v2.0.0 (after) | Improvement |
-|-----------|-----------------|----------------|-------------|
-| **Small directory (100 files)** | 2.65ms | 2.68ms | -1% (within margin) |
-| **Large directory (1,000 files)** | 9.23ms | 9.49ms | -3% (within margin) |
-| **Very large directory (10,000 files)** | 102.37ms | 90.06ms | **12% faster** ✅ |
-
-**Analysis**:
-- Small/medium directories: Performance similar (within measurement variance)
-- **Large directories: 12% faster** due to async operations and array join optimization
-- Memory usage significantly improved (see below)
-
----
-
-### Concurrent Request Performance
-
-| Operation | v1.2.0 (before) | v2.0.0 (after) | Improvement |
-|-----------|-----------------|----------------|-------------|
-| **10 concurrent small files** | 15.50ms total | 14.35ms total | **7% faster** ✅ |
-| **Avg per request** | 1.55ms | 1.43ms | **8% faster** ✅ |
-| **5 concurrent directories** | 11.30ms total | 7.26ms total | **36% faster** ✅✅ |
-| **Avg per request** | 2.26ms | 1.45ms | **36% faster** ✅✅ |
-
-**Analysis**:
-- ✅ **Concurrent requests 36% faster!** This is the **biggest win**
-- Async operations allow true parallel processing
-- Event loop no longer blocked by sync fs operations
-
----
-
-### 404 Not Found Performance
-
-| Operation | v1.2.0 (before) | v2.0.0 (after) | Improvement |
-|-----------|-----------------|----------------|-------------|
-| **404 handling** | 1.26ms | 1.53ms | -21% (slightly slower) |
-
-**Analysis**: Marginally slower due to async stat call overhead, but acceptable trade-off for non-blocking behavior.
-
----
-
-### Memory Usage (10,000 files directory)
-
-| Metric | v1.2.0 (before) | v1.3.0 (after) | Improvement |
-|--------|-----------------|----------------|-------------|
-| **Heap increase** | 1.16 MB | 0.96 MB | **17% less memory** ✅ |
-| **External increase** | 2.57 MB | 2.54 MB | 1% less |
-| **Total memory** | 3.73 MB | 3.50 MB | **6% less memory** ✅ |
-| **Response size** | 1.29 MB | 1.29 MB | (same) |
-
-**Analysis**:
-- ✅ **17% less heap memory** due to array join optimization
-- String concatenation O(n²) → array join O(n)
-- Reduces garbage collection pressure
-
----
-
-## HTTP Caching Performance
-
-### New Feature: ETag and Conditional Requests
-
-HTTP caching is **enabled by default** in v1.3.0. Here's the expected performance:
-
-| Request Type | Time | Bandwidth | Notes |
-|--------------|------|-----------|-------|
-| **First request (cold cache)** | 2.93ms | 100% | Full file transfer |
-| **Subsequent request (cached)** | ~0.1ms | ~5% | **304 Not Modified** response |
-
-**Bandwidth savings**: 80-95% for cached files ✅✅✅
-
-**How it works**:
-1. First request: Server sends file with `ETag: "mtime-size"` and `Last-Modified`
-2. Browser caches file and stores ETag
-3. Second request: Browser sends `If-None-Match: "mtime-size"`
-4. Server compares ETag:
-   - File unchanged → **304 Not Modified** (no body, 99% bandwidth saved)
-   - File changed → **200 OK** with new file
-
-**Cache invalidation**:
-- ETag is based on file `mtime` (modification time) + `size`
-- When file is modified, `mtime` changes → new ETag → cache invalidated
-- **Automatic and reliable** - no stale content!
-
----
-
-## Key Performance Wins
-
-### 🥇 #1: Concurrent Requests - 36% Faster
-
-**Before (v1.2.0):**
-```
-5 concurrent directory requests
-Total time: 11.30ms (sequential processing)
-Avg per request: 2.26ms
-```
-
-**After (v2.0.0):**
-```
-5 concurrent directory requests
-Total time: 7.26ms (parallel processing)
-Avg per request: 1.45ms
-Improvement: 36% faster ✅✅
-```
-
-**Why**: Async operations (fs.promises) don't block the event loop, allowing true concurrency.
-
----
-
-### 🥈 #2: Memory Usage - 17% Less
-
-**Before (v1.2.0):**
-```javascript
-// String concatenation - O(n²) complexity
-let s_dir = "<table>";
-s_dir += `<tr>...</tr>`;  // Creates new string
-s_dir += `<tr>...</tr>`;  // Creates new string
-s_dir += `<tr>...</tr>`;  // Creates new string
-// For 10,000 files: creates 10,000+ intermediate strings
-```
-
-**After (v2.0.0):**
-```javascript
-// Array join - O(n) complexity
-const parts = [];
-parts.push("<table>");
-parts.push(`<tr>...</tr>`);
-parts.push(`<tr>...</tr>`);
-parts.push(`<tr>...</tr>`);
-const s_dir = parts.join('');  // Single allocation
-// For 10,000 files: creates 1 final string
-```
-
-**Result**: 17% less heap memory, less garbage collection
-
----
-
-### 🥉 #3: HTTP Caching - 95% Bandwidth Saved
-
-**Scenario**: 10,000 users access a 100KB CSS file
-
-**Before (v1.2.0):**
-```
-10,000 requests × 100 KB = 1,000 MB transferred
-Server CPU: 10,000 file reads
-```
-
-**After (v2.0.0):**
-```
-First visit: 10,000 × 100 KB = 1,000 MB
-Subsequent visits: 10,000 × ~0.2 KB headers = 2 MB
-Total bandwidth saved: 998 MB (99.8%)
-Server CPU: 10,000 stat calls (much faster than file reads)
-```
-
-**Cost savings** (AWS CloudFront example):
-- 10k users/day × 30 days × 1 MB/user = **30 GB/month**
-- Before: $3-5/month
-- After: $0.15-0.25/month
-- **Savings: ~$3/month** per app
-
----
-
-## Detailed Before/After Comparison Table
-
-| Metric | v1.2.0 | v1.3.0 | Change | Status |
-|--------|--------|--------|--------|--------|
-| Small file (1KB) | 2.93ms | 2.93ms | 0% | ⚪ Same |
-| Medium file (100KB) | 3.59ms | 3.13ms | -13% | ✅ Faster |
-| Large file (1MB) | 9.03ms | 8.76ms | -3% | ✅ Faster |
-| Directory (100 files) | 2.65ms | 2.68ms | +1% | ⚪ Same |
-| Directory (1K files) | 9.23ms | 9.49ms | +3% | ⚪ Same |
-| Directory (10K files) | 102.37ms | 90.06ms | **-12%** | ✅✅ Faster |
-| 10 concurrent files | 15.50ms | 14.35ms | -7% | ✅ Faster |
-| 5 concurrent dirs | 11.30ms | 7.26ms | **-36%** | ✅✅✅ Faster |
-| 404 handling | 1.26ms | 1.53ms | +21% | ⚠️ Slower |
-| Heap memory (10K dir) | 1.16 MB | 0.96 MB | **-17%** | ✅✅ Less |
-| Total memory (10K dir) | 3.73 MB | 3.50 MB | -6% | ✅ Less |
-
-**Legend:**
-- ✅✅✅ Major improvement (>30%)
-- ✅✅ Significant improvement (10-30%)
-- ✅ Minor improvement (3-10%)
-- ⚪ No significant change (±2%)
-- ⚠️ Slight regression (acceptable trade-off)
-
----
-
-## Configuration Options (New in v2.0.0)
-
-### HTTP Caching Options
-
-```javascript
-const koaClassicServer = require('koa-classic-server');
-
-// Default: caching enabled, 1 hour max-age
-app.use(koaClassicServer('/public'));
-
-// Custom cache duration
-app.use(koaClassicServer('/public', {
-    browserCacheMaxAge: 86400  // 24 hours
-}));
-
-// Disable caching (not recommended)
-app.use(koaClassicServer('/public', {
-    browserCacheEnabled: false
-}));
-
-// Different strategies for different routes
-app.use(koaClassicServer('/static-assets', {
-    browserCacheMaxAge: 31536000  // 1 year for immutable assets
-}));
-
-app.use(koaClassicServer('/dynamic-content', {
-    browserCacheMaxAge: 60  // 1 minute for frequently updated content
-}));
-```
-
----
-
-## Real-World Impact Examples
-
-### Example 1: Small Blog Site
-
-**Setup:**
-- 500 visitors/day
-- 10 static files per page (CSS, JS, images)
-- Average file size: 50 KB
-
-**Before (v1.2.0):**
-- Bandwidth: 500 × 10 × 50 KB = 250 MB/day = 7.5 GB/month
-- Server load: 5,000 file reads/day
-
-**After (v2.0.0):**
-- First visit: 250 MB/day
-- Cached visits (80%): 250 MB × 0.05 = 12.5 MB/day
-- Total: ~1 GB/month (87% reduction)
-- Server load: 5,000 stat calls/day (10x faster than reads)
-
-**Savings**: 6.5 GB/month bandwidth, 80% less CPU usage
-
----
-
-### Example 2: Large Directory Listing
-
-**Setup:**
-- File manager app with 10,000 files
-- 100 users viewing directory per day
-
-**Before (v1.2.0):**
-- Response time: 102ms
-- Memory per request: 3.73 MB
-- String concatenation causes GC spikes
-
-**After (v2.0.0):**
-- Response time: 90ms (12% faster)
-- Memory per request: 3.50 MB (6% less)
-- No GC spikes from string concatenation
-
-**User experience**: Noticeably snappier, especially on slower devices
-
----
-
-### Example 3: API Documentation Site
-
-**Setup:**
-- 1,000 developers/day
-- Each loads 20 HTML/CSS/JS files
-- Average 3 visits per day per developer
-
-**Before (v1.2.0):**
-- Total requests: 1,000 × 20 × 3 = 60,000/day
-- All 60,000 requests serve full files
-- Bandwidth: Heavy
-
-**After (v2.0.0):**
-- First visit: 1,000 × 20 = 20,000 full file requests
-- Subsequent visits: 1,000 × 20 × 2 = 40,000 → **304 responses**
-- Bandwidth saved: 67% (40,000 out of 60,000 requests)
-- Response time: 0.1ms vs 3ms for 304 responses (**30x faster**)
-
----
-
-## Migration from v1.2.0 to v2.0.0
-
-### Breaking Changes
-
-**None!** v1.3.0 is 100% backward compatible.
-
-### Recommended Actions
-
-1. **Update package**:
-   ```bash
-   npm install koa-classic-server@2.0.0
-   ```
-
-2. **No code changes required** - caching is auto-enabled with sensible defaults
-
-3. **Optional**: Configure `browserCacheMaxAge` for your use case:
-   ```javascript
-   // For static assets that rarely change
-   app.use(koaClassicServer('/assets', { browserCacheMaxAge: 31536000 }));
-
-   // For content that updates frequently
-   app.use(koaClassicServer('/content', { browserCacheMaxAge: 300 }));
-   ```
-
-4. **Test caching** in browser DevTools:
-   - First visit: See `200 OK` with full file
-   - Reload (F5): See `304 Not Modified` with 0 bytes transferred
-   - Hard reload (Ctrl+F5): See `200 OK` again (cache bypassed)
-
-### Rollback
-
-If you experience issues (unlikely), roll back to v1.2.0:
-
-```bash
-npm install koa-classic-server@1.2.0
-```
-
-All security fixes from v1.2.0 are retained in v1.3.0.
-
----
-
-## Performance Testing Methodology
-
-### Environment
-- **Node.js**: v20.x
-- **OS**: Linux (Ubuntu)
-- **CPU**: Modern multi-core
-- **Storage**: SSD
-- **Test framework**: Jest + Supertest
-- **Iterations**: 100 (small), 50 (medium), 20 (large), 5 (very large)
-
-### Metrics Collected
-- **Response time**: Average, median, min, max
-- **Memory usage**: Heap, external, total
-- **Concurrency**: Parallel request handling
-- **Bandwidth**: Response sizes
-
-### Reliability
-- Tests run multiple times for consistency
-- Outliers (>2 std dev) excluded
-- System under idle load during testing
-- GC forced before memory measurements
-
----
-
-## Conclusion
-
-**Version 2.0.0 delivers measurable performance improvements** across all key metrics:
-
-✅ **36% faster concurrent requests** (biggest win)
-✅ **17% less memory usage** for large operations
-✅ **80-95% bandwidth savings** with HTTP caching
-✅ **Non-blocking event loop** for better scalability
-✅ **100% backward compatible** - no breaking changes
-
-**Recommendation**: Upgrade to v2.0.0 immediately for better performance and lower costs.
-
----
-
-**Generated**: 2025-11-18
-**Comparison**: v1.2.0 (baseline) vs v2.0.0 (optimized)

package/docs/noteExports.md

@@ -1,148 +0,0 @@
-
-## versione corta
- Utilizzare Conditional Exports in package.json
-
-Con Node.js (versione 12.20+, 14+ o successive) puoi sfruttare il campo exports nel file package.json per indicare percorsi diversi a seconda del metodo di importazione:
-
-Esempio di package.json:
-
-{
-  "name": "mia-libreria",
-  "version": "1.0.0",
-  "main": "./index.cjs",            // entry point per CommonJS
-  "exports": {
-    "import": "./index.js",         // entry point per ESM
-    "require": "./index.cjs"        // entry point per CommonJS
-  }
-}
-
-Con questa configurazione, puoi scrivere la logica principale in un file (ad esempio lib/koaClassicServer.js) e poi creare due entry point:
-
-    Per ESM (index.js)
-
-// index.js
-export { default } from './lib/koaClassicServer.js';
-
-Per CommonJS (index.cjs)
-
-    // index.cjs
-    module.exports = require('./lib/koaClassicServer.js').default;
-
-In questo modo gli utenti potranno importare il modulo in ESM:
-
-import koaClassicServer from "mia-libreria";
-
-oppure in CommonJS:
-
-const koaClassicServer = require("mia-libreria");
-
-
-
-## versione lunga
-
- l'uso dei Conditional Exports nel file package.json, è un meccanismo introdotto nelle versioni moderne di Node.js (dalla 12.20 in poi, con supporto stabile a partire dalla 14) che ti permette di specificare percorsi di ingresso diversi a seconda di come il modulo viene importato:
-
-    ESM (quando usi import ... from 'modulo')
-    CommonJS (quando usi require('modulo'))
-
-Questo approccio ti consente di mantenere una singola distribuzione del tuo modulo, fornendo però due "versioni" compatibili in base al sistema di moduli utilizzato dall'ambiente dell'utente.
-Struttura di Base del package.json
-
-Ecco un esempio di configurazione:
-
-{
-  "name": "mia-libreria",
-  "version": "1.0.0",
-  "main": "./index.cjs",            
-  "exports": {
-    "import": "./index.js",
-    "require": "./index.cjs"
-  }
-}
-
-Spiegazione dei campi principali:
-
-    main:
-    Tradizionalmente questo campo specifica il file di ingresso per i moduli CommonJS. Anche se non è obbligatorio se usi il campo exports, è buona pratica inserirlo per mantenere la compatibilità con strumenti o ambienti che non supportano ancora i conditional exports.
-
-    exports:
-    Questo campo permette di definire in modo esplicito quali file (o percorsi) devono essere utilizzati quando il modulo viene importato, in base al contesto. In questo esempio, abbiamo due condizioni:
-        "import": "./index.js": Quando il modulo viene importato in un contesto ECMAScript (ESM), Node.js userà il file index.js.
-        "require": "./index.cjs": Quando il modulo viene importato tramite CommonJS (require()), verrà usato il file index.cjs.
-
-Strutturare il Modulo per Supportare Entrambi gli Stili
-
-Supponiamo di avere una struttura simile a questa:
-
-mia-libreria/
-├── lib/
-│   └── koaClassicServer.js
-├── index.js      // Entry point per ESM
-├── index.cjs     // Entry point per CommonJS
-└── package.json
-
-1. File lib/koaClassicServer.js (la logica principale)
-
-Scrivi qui il tuo modulo in sintassi moderna (ESM). Ad esempio:
-
-// lib/koaClassicServer.js
-export default function koaClassicServer(rootDir, opts = {}) {
-  // ... implementazione del middleware
-}
-
-2. File index.js (entry point per ESM)
-
-Questo file importa il modulo principale e lo re-esporta:
-
-// index.js (ESM)
-export { default } from './lib/koaClassicServer.js';
-
-3. File index.cjs (entry point per CommonJS)
-
-In questo file, importa il modulo in modo compatibile con CommonJS e lo esporta:
-
-// index.cjs (CommonJS)
-module.exports = require('./lib/koaClassicServer.js').default;
-
-Come Funziona in Pratica
-
-    Utilizzando ESM:
-
-    Se un utente importa il modulo in un file ESM:
-
-import koaClassicServer from 'mia-libreria';
-
-Node.js guarderà il campo exports nel package.json e, vedendo la chiave "import", caricherà il file index.js che esporta il modulo definito in koaClassicServer.js.
-
-Utilizzando CommonJS:
-
-Se invece un utente importa il modulo in un file CommonJS:
-
-    const koaClassicServer = require('mia-libreria');
-
-    Node.js, vedendo la chiave "require" nel campo exports, caricherà il file index.cjs che esporta correttamente il modulo.
-
-Vantaggi di Questo Approccio
-
-    Compatibilità Doppia:
-    Permette agli utenti di utilizzare il modulo indipendentemente dal sistema di moduli scelto.
-
-    Manutenzione Centralizzata:
-    La logica principale è scritta in un solo file (koaClassicServer.js), riducendo la duplicazione del codice.
-
-    Supporto ai Nuovi Standard:
-    Utilizzando i conditional exports, ti prepari per il futuro, dove i moduli ESM diventeranno lo standard principale.
-
-    Controllo Esplicito dell'Interfaccia:
-    Il campo exports consente di definire in modo esplicito e sicuro quali file devono essere esposti agli utenti del modulo, evitando accessi accidentali a file interni non destinati alla pubblicazione.
-
-Considerazioni Finali
-
-    Versione di Node.js:
-    Assicurati che i tuoi utenti utilizzino una versione di Node.js che supporti i conditional exports (Node 14+ è consigliato).
-
-    Compatibilità con Strumenti di Build:
-    Se utilizzi strumenti di build o bundler, verifica che siano configurati per gestire correttamente il campo exports.
-
-Utilizzando i Conditional Exports nel package.json potrai distribuire il tuo modulo in modo elegante e compatibile con entrambi gli stili di moduli, offrendo un'esperienza di utilizzo migliore agli sviluppatori che lo importeranno.
-