kempo-server 1.7.4 → 1.7.6

package/README.md

@@ -211,435 +211,19 @@ export default async function(request, response) {
 
 ## Configuration
 
-To configure the server, create a configuration file (by default `.config.json`) within the root directory of your server (`public` in the start example [above](#getting-started)). You can specify a different configuration file using the `--config` flag.
+Kempo Server can be customized with a simple JSON configuration file to control caching, middleware, security, routing, and more.
 
-**Important:** 
-- When using a relative path for the `--config` flag, the config file must be located within the server root directory
-- When using an absolute path for the `--config` flag, the config file can be located anywhere on the filesystem
-- The server will throw an error if you attempt to use a relative config file path that points outside the root directory
+For detailed configuration options and examples, see **[CONFIG.md](./CONFIG.md)**.
 
-This json file can have any of the following properties, any property not defined will use the "Default Config".
-
-- [allowedMimes](#allowedmimes)
-- [disallowedRegex](#disallowedregex)
-- [customRoutes](#customroutes)
-- [routeFiles](#routefiles)
-- [noRescanPaths](#norescanpaths)
-- [maxRescanAttempts](#maxrescanattempts)
-- [cache](#cache)
-- [middleware](#middleware)
-
-## Cache
-
-Kempo Server includes an intelligent module caching system that dramatically improves performance by caching JavaScript route modules in memory. The cache combines multiple strategies:
-
-- **LRU (Least Recently Used)** - Evicts oldest modules when cache fills
-- **Time-based expiration** - Modules expire after configurable TTL
-- **Memory monitoring** - Automatically clears cache if memory usage gets too high
-- **File watching** - Instantly invalidates cache when files change (development)
-
-### Basic Cache Configuration
-
-Enable caching in your `.config.json`:
-
-```json
-{
-  "cache": {
-    "enabled": true,
-    "maxSize": 100,
-    "maxMemoryMB": 50,
-    "ttlMs": 300000,
-    "watchFiles": true
-  }
-}
-```
-
-### Cache Options
-
-- `enabled` (boolean) - Enable/disable caching (default: `true`)
-- `maxSize` (number) - Maximum cached modules (default: `100`) 
-- `maxMemoryMB` (number) - Memory limit in MB (default: `50`)
-- `ttlMs` (number) - Cache lifetime in milliseconds (default: `300000` - 5 minutes)
-- `maxHeapUsagePercent` (number) - Clear cache when heap exceeds % (default: `70`)
-- `memoryCheckInterval` (number) - Memory check frequency in ms (default: `30000`)
-- `watchFiles` (boolean) - Auto-invalidate on file changes (default: `true`)
-- `enableMemoryMonitoring` (boolean) - Enable memory monitoring (default: `true`)
-
-### Environment-Specific Configurations
-
-Use different config files for different environments:
-
-**Development (`dev.config.json`):**
-```json
-{
-  "cache": {
-    "enabled": true,
-    "maxSize": 50,
-    "ttlMs": 300000,
-    "watchFiles": true
-  }
-}
-```
-
-**Production (`prod.config.json`):**
-```json
-{
-  "cache": {
-    "enabled": true,
-    "maxSize": 1000,
-    "maxMemoryMB": 200,
-    "ttlMs": 3600000,
-    "watchFiles": false
-  }
-}
-```
-
-Run with specific config: `node src/index.js --config prod.config.json`
-
-### Cache Monitoring
-
-Monitor cache performance at runtime:
-
-- **View stats:** `GET /_admin/cache` - Returns detailed cache statistics
-- **Clear cache:** `DELETE /_admin/cache` - Clears entire cache
-
-Example response:
-```json
-{
-  "cache": {
-    "size": 45,
-    "maxSize": 100,
-    "memoryUsageMB": 12.5,
-    "hitRate": 87
-  }
-}
-```
-
-## Middleware
-
-Kempo Server includes a powerful middleware system that allows you to add functionality like authentication, logging, CORS, compression, and more. Middleware runs before your route handlers and can modify requests, responses, or handle requests entirely.
-
-### Built-in Middleware
-
-#### CORS
-Enable Cross-Origin Resource Sharing for your API:
-
-```json
-{
-  "middleware": {
-    "cors": {
-      "enabled": true,
-      "origin": "*",
-      "methods": ["GET", "POST", "PUT", "DELETE"],
-      "headers": ["Content-Type", "Authorization"]
-    }
-  }
-}
-```
-
-#### Compression
-Automatically compress responses with gzip:
-
-```json
-{
-  "middleware": {
-    "compression": {
-      "enabled": true,
-      "threshold": 1024
-    }
-  }
-}
-```
-
-#### Rate Limiting
-Limit requests per client to prevent abuse:
-
-```json
-{
-  "middleware": {
-    "rateLimit": {
-      "enabled": true,
-      "maxRequests": 100,
-      "windowMs": 60000,
-      "message": "Too many requests"
-    }
-  }
-}
-```
-
-#### Security Headers
-Add security headers to all responses:
-
-```json
-{
-  "middleware": {
-    "security": {
-      "enabled": true,
-      "headers": {
-        "X-Content-Type-Options": "nosniff",
-        "X-Frame-Options": "DENY",
-        "X-XSS-Protection": "1; mode=block"
-      }
-    }
-  }
-}
-```
-
-#### Request Logging
-Log requests with configurable detail:
-
-```json
-{
-  "middleware": {
-    "logging": {
-      "enabled": true,
-      "includeUserAgent": true,
-      "includeResponseTime": true
-    }
-  }
-}
-```
-
-### Custom Middleware
-
-Create your own middleware by writing JavaScript files and referencing them in your config:
-
-```json
-{
-  "middleware": {
-    "custom": ["./middleware/auth.js", "./middleware/analytics.js"]
-  }
-}
-```
-
-#### Custom Middleware Example
-
-```javascript
-// middleware/auth.js
-export default (config) => {
-  return async (req, res, next) => {
-    const token = req.headers.authorization;
-    
-    if (!token) {
-      req.user = null;
-      return await next();
-    }
-    
-    try {
-      // Verify JWT token (example)
-      const user = verifyToken(token);
-      req.user = user;
-      req.permissions = await getUserPermissions(user.id);
-      
-      // Add helper methods
-      req.hasPermission = (permission) => req.permissions.includes(permission);
-      
-    } catch (error) {
-      req.user = null;
-    }
-    
-    await next();
-  };
-};
-```
-
-#### Using Enhanced Requests in Routes
-
-Your route files can now access the enhanced request object:
-
-```javascript
-// api/user/profile/GET.js
-export default async (req, res, params) => {
-  if (!req.user) {
-    return res.status(401).json({ error: 'Authentication required' });
-  }
-  
-  if (!req.hasPermission('user:read')) {
-    return res.status(403).json({ error: 'Insufficient permissions' });
-  }
-  
-  const profile = await getUserProfile(req.user.id);
-  res.json(profile);
-};
-```
-
-### Middleware Order
-
-Middleware executes in this order:
-1. Built-in middleware (cors, compression, rateLimit, security, logging)
-2. Custom middleware (in the order listed in config)
-3. Your route handlers
-
-### Route Interception
-
-Middleware can intercept and handle routes completely, useful for authentication endpoints:
-
-```javascript
-// middleware/auth-routes.js
-export default (config) => {
-  return async (req, res, next) => {
-    const url = new URL(req.url, `http://${req.headers.host}`);
-    
-    // Handle login endpoint
-    if (req.method === 'POST' && url.pathname === '/auth/login') {
-      const credentials = await req.json();
-      const token = await authenticateUser(credentials);
-      
-      if (token) {
-        return res.json({ token, success: true });
-      } else {
-        return res.status(401).json({ error: 'Invalid credentials' });
-      }
-    }
-    
-    await next();
-  };
-};
-```
-
-### allowedMimes
-
-An object mapping file extensions to their MIME types. Files with extensions not in this list will not be served.
-
-```json
-{
-  "allowedMimes": {
-    "html": "text/html",
-    "css": "text/css",
-    "js": "application/javascript",
-    "json": "application/json",
-    "png": "image/png",
-    "jpg": "image/jpeg"
-  }
-}
-```
-
-### disallowedRegex
-
-An array of regular expressions that match paths that should never be served. This provides security by preventing access to sensitive files.
-
-```json
-{
-  "disallowedRegex": [
-    "^/\\..*",
-    "\\.env$",
-    "\\.config$",
-    "password"
-  ]
-}
-```
-
-### routeFiles
-
-An array of filenames that should be treated as route handlers and executed as JavaScript modules.
-
-```json
-{
-  "routeFiles": [
-    "GET.js",
-    "POST.js",
-    "PUT.js",
-    "DELETE.js",
-    "index.js"
-  ]
-}
-```
-
-### noRescanPaths
-
-An array of regex patterns for paths that should not trigger a file system rescan. This improves performance for common static assets.
-
-```json
-{
-  "noRescanPaths": [
-    "/favicon\\.ico$",
-    "/robots\\.txt$",
-    "\\.map$"
-  ]
-}
-```
-
-### customRoutes
-
-An object mapping custom route paths to file paths. Useful for aliasing or serving files from outside the document root.
-
-**Note:** All file paths in customRoutes are resolved relative to the server root directory (the `--root` path). This allows you to reference files both inside and outside the document root.
-
-**Basic Routes:**
-```json
-{
-  "customRoutes": {
-    "/vendor/bootstrap.css": "../node_modules/bootstrap/dist/css/bootstrap.min.css",
-    "/api/status": "./status.js"
-  }
-}
-```
-
-**Wildcard Routes:**
-Wildcard routes allow you to map entire directory structures using the `*` and `**` wildcards:
-
-```json
-{
-  "customRoutes": {
-    "kempo/*": "../node_modules/kempo/dist/*",
-    "assets/*": "../static-files/*",
-    "docs/*": "../documentation/*",
-    "src/**": "../src/**"
-  }
-}
-```
-
-With wildcard routes:
-- `kempo/styles.css` would serve `../node_modules/kempo/dist/styles.css`
-- `assets/logo.png` would serve `../static-files/logo.png`  
-- `docs/readme.md` would serve `../documentation/readme.md`
-- `src/components/Button.js` would serve `../src/components/Button.js`
-
-The `*` wildcard matches any single path segment (anything between `/` characters).
-The `**` wildcard matches any number of path segments, allowing you to map entire directory trees.
-Multiple wildcards can be used in a single route pattern.
-
-### maxRescanAttempts
-
-The maximum number of times to attempt rescanning the file system when a file is not found. Defaults to 3.
-
-```json
-{
-  "maxRescanAttempts": 3
-}
-```
-
-### cache
-
-Configure the intelligent module caching system for improved performance:
+Quick start:
+```bash
+# Create a basic config file
+echo '{"cache": {"enabled": true}}' > .config.json
 
-```json
-{
-  "cache": {
-    "enabled": true,
-    "maxSize": 100,
-    "maxMemoryMB": 50,
-    "ttlMs": 300000,
-    "maxHeapUsagePercent": 70,
-    "memoryCheckInterval": 30000,
-    "watchFiles": true,
-    "enableMemoryMonitoring": true
-  }
-}
+# Use different configs for different environments
+kempo-server --root public --config dev.config.json
 ```
 
-Cache options:
-- `enabled` - Enable/disable caching (boolean, default: `true`)
-- `maxSize` - Maximum cached modules (number, default: `100`) 
-- `maxMemoryMB` - Memory limit in MB (number, default: `50`)
-- `ttlMs` - Cache lifetime in milliseconds (number, default: `300000`)
-- `maxHeapUsagePercent` - Clear cache when heap exceeds % (number, default: `70`)
-- `memoryCheckInterval` - Memory check frequency in ms (number, default: `30000`)
-- `watchFiles` - Auto-invalidate on file changes (boolean, default: `true`)
-- `enableMemoryMonitoring` - Enable memory monitoring (boolean, default: `true`)
-
-Use different config files for different environments rather than nested objects.
-
 ## Features
 
 - **Zero Dependencies** - No external dependencies required
@@ -756,24 +340,6 @@ Kempo Server supports several command line options to customize its behavior:
 kempo-server --root public --port 8080 --host 0.0.0.0 --verbose
 ```
 
-### Configuration File Examples
-
-You can specify different configuration files for different environments:
-
-```bash
-# Development
-kempo-server --root public --config dev.config.json
-
-# Staging
-kempo-server --root public --config staging.config.json
-
-# Production with absolute path
-kempo-server --root public --config /etc/kempo/production.config.json
-
-# Mix with other options
-kempo-server --root dist --port 8080 --config production.config.json --scan
-```
-
 ## Testing
 
 This project uses the Kempo Testing Framework. Tests live in the `tests/` folder and follow these naming conventions:
@@ -796,3 +362,8 @@ npm run tests:gui     # Start the GUI test runner
 For advanced usage (filters, flags, GUI options), see:
 https://github.com/dustinpoissant/kempo-testing-framework
 
+## Documentation
+
+- **[CONFIG.md](./CONFIG.md)** - Comprehensive server configuration guide
+- **[UTILS.md](./UTILS.md)** - Utility modules for Node.js projects
+

package/UTILS.md

@@ -0,0 +1,127 @@
+# Utility Modules
+
+Kempo Server includes some utility modules that can be used in your own Node.js projects. These utilities are built and exported alongside the main server package.
+
+> **Note:** These utilities are included here for convenience but may be moved to their own dedicated package in the future as more Node.js utilities are added.
+
+## CLI Utilities
+
+The CLI utilities provide simple command-line argument parsing functionality.
+
+### Usage
+
+```javascript
+import { getArgs } from 'kempo-server/utils/cli';
+
+// Basic usage - get all arguments as key-value pairs
+const args = getArgs();
+console.log(args); // { port: '3000', host: 'localhost', verbose: true }
+
+// With mapping - map short flags to full names
+const args = getArgs({
+  'p': 'port',
+  'h': 'host',
+  'v': 'verbose'
+});
+console.log(args); // Maps -p to port, -h to host, -v to verbose
+```
+
+### Example
+
+```bash
+node myapp.js --port 8080 -h 127.0.0.1 --verbose
+```
+
+```javascript
+import { getArgs } from 'kempo-server/utils/cli';
+
+const args = getArgs({
+  'h': 'host',
+  'p': 'port',
+  'v': 'verbose'
+});
+
+// Results in:
+// {
+//   host: '127.0.0.1',
+//   port: '8080', 
+//   verbose: true
+// }
+```
+
+## File System Utilities
+
+The file system utilities provide common file and directory operations with Promise-based APIs.
+
+### Usage
+
+```javascript
+import { ensureDir, copyDir } from 'kempo-server/utils/fs-utils';
+
+// Ensure a directory exists (creates all parent directories if needed)
+await ensureDir('./my/nested/directory');
+
+// Copy an entire directory structure recursively
+await copyDir('./source', './destination');
+```
+
+### Functions
+
+#### `ensureDir(dirPath)`
+
+Ensures that a directory exists, creating it and any necessary parent directories if they don't exist. Similar to `mkdir -p`.
+
+- **Parameters:**
+  - `dirPath` (string) - The directory path to ensure exists
+- **Returns:** Promise that resolves when the directory is confirmed to exist
+
+#### `copyDir(srcPath, destPath)`
+
+Recursively copies an entire directory structure from source to destination.
+
+- **Parameters:**
+  - `srcPath` (string) - The source directory to copy from
+  - `destPath` (string) - The destination directory to copy to
+- **Returns:** Promise that resolves when the copy operation is complete
+
+### Example Use Cases
+
+```javascript
+import { ensureDir, copyDir } from 'kempo-server/utils/fs-utils';
+
+// Build script example
+async function buildProject() {
+  // Ensure build directories exist
+  await ensureDir('./dist/assets');
+  await ensureDir('./dist/components');
+  
+  // Copy static assets
+  await copyDir('./src/assets', './dist/assets');
+  await copyDir('./src/public', './dist');
+}
+
+// Backup script example
+async function backupProject() {
+  const timestamp = new Date().toISOString().slice(0, 10);
+  const backupPath = `./backups/${timestamp}`;
+  
+  await ensureDir(backupPath);
+  await copyDir('./src', `${backupPath}/src`);
+  await copyDir('./config', `${backupPath}/config`);
+}
+```
+
+## Installation and Build
+
+These utilities are automatically built when you install kempo-server. They're available through the package's exports:
+
+```json
+{
+  "exports": {
+    "./utils/cli": "./dist/utils/cli.js",
+    "./utils/fs-utils": "./dist/utils/fs-utils.js"
+  }
+}
+```
+
+The utilities are ES modules and require Node.js environments that support ES module imports.

package/dist/utils/cli.js

@@ -0,0 +1 @@
+import{spawn}from"child_process";import readline from"readline";export const getArgs=(mapping={})=>{const args={};let name="",values=[];const save=()=>{name&&(0===values.length?args[name]=!0:1===values.length?"false"===values[0]?args[name]=!1:args[name]=values[0]:args[name]=values)};for(let i=2;i<process.argv.length;i++){const arg=process.argv[i];arg.startsWith("-")?(save(),arg.startsWith("--")?name=arg.slice(2):(name=arg.slice(1),mapping[name]&&(name=mapping[name])),values=[]):values.push(arg)}return save(),args};export const runChildProcess=command=>new Promise((resolve,reject)=>{const[cmd,...args]=command.split(" "),child=spawn(cmd,args,{stdio:"inherit",shell:!0});child.on("close",code=>{0===code?resolve(`child process exited with code ${code}`):reject(new Error(`child process exited with code ${code}`))}),child.on("error",reject)});export const runChildNodeProcess=(scriptPath,argsObj={})=>{const command=`node ${scriptPath} ${Object.entries(argsObj).flatMap(([key,value])=>!0===value?[`--${key}`]:[`--${key}`,value]).join(" ")}`;return runChildProcess(command)};export const runChildNodeProcessScript=scriptPath=>{const child=spawn("node",[scriptPath],{stdio:"inherit",shell:!0});return new Promise((resolve,reject)=>{child.on("close",code=>{0===code?resolve():reject(new Error(`Process exited with code ${code}`))}),child.on("error",reject)})};export const promptUser=query=>{const rl=readline.createInterface({input:process.stdin,output:process.stdout});return new Promise(resolve=>{rl.question(`${query}: `,answer=>{rl.close(),resolve(answer)})})};export const promptYN=(query,defaultValue="y")=>promptUser(`${query} (${"y"===defaultValue?"Y/n":"y/N"}): `).then(answer=>{const normalizedAnswer=answer.trim().toLowerCase();return""===normalizedAnswer?"y"===defaultValue:"y"===normalizedAnswer});

package/dist/utils/fs-utils.js

@@ -0,0 +1 @@
+import fs from"fs/promises";import path from"path";export const ensureDir=async dirPath=>{try{await fs.mkdir(dirPath,{recursive:!0})}catch(error){if("EEXIST"!==error.code)throw error}};export const copyDir=async(src,dest)=>{await ensureDir(dest);const entries=await fs.readdir(src,{withFileTypes:!0});for(const entry of entries){const srcPath=path.join(src,entry.name),destPath=path.join(dest,entry.name);entry.isDirectory()?await copyDir(srcPath,destPath):await fs.copyFile(srcPath,destPath)}};export const emptyDir=async dirPath=>{try{const entries=await fs.readdir(dirPath);await Promise.all(entries.map(entry=>fs.rm(path.join(dirPath,entry),{recursive:!0,force:!0})))}catch(error){if("ENOENT"!==error.code)throw error}};

package/package.json

@@ -1,15 +1,20 @@
 {
   "name": "kempo-server",
   "type": "module",
-  "version": "1.7.4",
+  "version": "1.7.6",
   "description": "A lightweight, zero-dependency, file based routing server.",
   "main": "dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./utils/cli": "./dist/utils/cli.js",
+    "./utils/fs-utils": "./dist/utils/fs-utils.js"
+  },
   "bin": {
     "kempo-server": "./dist/index.js"
   },
   "scripts": {
     "build": "node scripts/build.js",
-    "start": "node dist/index.js -r ./docs",
+    "docs": "node dist/index.js -r ./docs",
     "tests": "npx kempo-test",
     "tests:gui": "npx kempo-test --gui",
     "tests:browser": "npx kempo-test -b",