kempo-server 2.2.0 → 3.0.1

package/docs-src/caching.page.html

@@ -0,0 +1,220 @@
+<page pageName="Module Caching" title="Module Caching - Kempo Server">
+	<content>
+    <p>Kempo Server includes an intelligent module caching system that dramatically improves performance by caching JavaScript route modules in memory.</p>
+
+    <h2>How It Works</h2>
+    <p>The cache system combines multiple strategies to optimize performance while preventing memory issues:</p>
+    <ul>
+      <li><strong>LRU (Least Recently Used)</strong> - Evicts oldest modules when cache fills</li>
+      <li><strong>Time-based expiration</strong> - Modules expire after configurable TTL</li>
+      <li><strong>Memory monitoring</strong> - Automatically clears cache if memory usage gets too high</li>
+      <li><strong>File watching</strong> - Instantly invalidates cache when files change (development)</li>
+    </ul>
+
+    <h2>Basic Configuration</h2>
+    <p>Add a <code>cache</code> object to your <code>.config.json</code> file:</p>
+    <pre><code class="hljs json">{
+  <span class="hljs-attr">"cache"</span>: {
+    <span class="hljs-attr">"enabled"</span>: <span class="hljs-literal">true</span>,
+    <span class="hljs-attr">"maxSize"</span>: <span class="hljs-number">100</span>,
+    <span class="hljs-attr">"maxMemoryMB"</span>: <span class="hljs-number">50</span>,
+    <span class="hljs-attr">"ttlMs"</span>: <span class="hljs-number">300000</span>,
+    <span class="hljs-attr">"watchFiles"</span>: <span class="hljs-literal">true</span>
+  }
+}</code></pre>
+
+    <h2>Configuration Options</h2>
+    <table>
+      <thead>
+        <tr>
+          <th>Option</th>
+          <th>Type</th>
+          <th>Default</th>
+          <th>Description</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr>
+          <td><code>enabled</code></td>
+          <td>boolean</td>
+          <td><code>true</code></td>
+          <td>Enable/disable the entire caching system</td>
+        </tr>
+        <tr>
+          <td><code>maxSize</code></td>
+          <td>number</td>
+          <td><code>100</code></td>
+          <td>Maximum number of modules to cache</td>
+        </tr>
+        <tr>
+          <td><code>maxMemoryMB</code></td>
+          <td>number</td>
+          <td><code>50</code></td>
+          <td>Memory limit for cache in megabytes</td>
+        </tr>
+        <tr>
+          <td><code>ttlMs</code></td>
+          <td>number</td>
+          <td><code>300000</code></td>
+          <td>Time to live in milliseconds (5 minutes)</td>
+        </tr>
+        <tr>
+          <td><code>maxHeapUsagePercent</code></td>
+          <td>number</td>
+          <td><code>70</code></td>
+          <td>Clear cache when heap usage exceeds this percentage</td>
+        </tr>
+        <tr>
+          <td><code>memoryCheckInterval</code></td>
+          <td>number</td>
+          <td><code>30000</code></td>
+          <td>How often to check memory usage (milliseconds)</td>
+        </tr>
+        <tr>
+          <td><code>watchFiles</code></td>
+          <td>boolean</td>
+          <td><code>true</code></td>
+          <td>Auto-invalidate cache when files change</td>
+        </tr>
+        <tr>
+          <td><code>enableMemoryMonitoring</code></td>
+          <td>boolean</td>
+          <td><code>true</code></td>
+          <td>Enable automatic memory monitoring</td>
+        </tr>
+      </tbody>
+    </table>
+
+    <h2>Environment-Specific Configuration</h2>
+    <p>Use separate configuration files for different environments instead of nested objects:</p>
+
+    <h3>Development Configuration</h3>
+    <p>Create <code>dev.config.json</code> with settings optimized for development:</p>
+    <pre><code class="hljs json">{
+  <span class="hljs-attr">"cache"</span>: {
+    <span class="hljs-attr">"enabled"</span>: <span class="hljs-literal">true</span>,
+    <span class="hljs-attr">"maxSize"</span>: <span class="hljs-number">50</span>,
+    <span class="hljs-attr">"maxMemoryMB"</span>: <span class="hljs-number">25</span>,
+    <span class="hljs-attr">"ttlMs"</span>: <span class="hljs-number">300000</span>,
+    <span class="hljs-attr">"watchFiles"</span>: <span class="hljs-literal">true</span>
+  }
+}</code></pre>
+    <pre><code class="hljs bash">node src/index.js --config dev.config.json</code></pre>
+
+    <h3>Production Configuration</h3>
+    <p>Create <code>prod.config.json</code> with settings optimized for production:</p>
+    <pre><code class="hljs json">{
+  <span class="hljs-attr">"cache"</span>: {
+    <span class="hljs-attr">"enabled"</span>: <span class="hljs-literal">true</span>,
+    <span class="hljs-attr">"maxSize"</span>: <span class="hljs-number">1000</span>,
+    <span class="hljs-attr">"maxMemoryMB"</span>: <span class="hljs-number">200</span>,
+    <span class="hljs-attr">"ttlMs"</span>: <span class="hljs-number">3600000</span>,
+    <span class="hljs-attr">"watchFiles"</span>: <span class="hljs-literal">false</span>
+  }
+}</code></pre>
+    <pre><code class="hljs bash">node src/index.js --config prod.config.json</code></pre>
+
+    <h2>Cache Monitoring</h2>
+    <p>Monitor cache performance and manage cached modules at runtime:</p>
+
+    <h3>View Cache Statistics</h3>
+    <pre><code class="hljs bash">curl http://localhost:3000/_admin/cache</code></pre>
+    <p>Returns detailed statistics including:</p>
+    <ul>
+      <li>Cache size and memory usage</li>
+      <li>Hit/miss rates</li>
+      <li>Node.js memory usage</li>
+      <li>List of cached files</li>
+    </ul>
+
+    <h3>Clear Cache</h3>
+    <pre><code class="hljs bash">curl -X DELETE http://localhost:3000/_admin/cache</code></pre>
+    <p>Immediately clears all cached modules.</p>
+
+    <h2>Performance Tuning</h2>
+
+    <h3>Memory Settings</h3>
+    <ul>
+      <li>Set <code>maxMemoryMB</code> to 10-20% of available server RAM</li>
+      <li>Use lower <code>maxHeapUsagePercent</code> (60-70%) for memory-constrained environments</li>
+      <li>Monitor actual usage with <code>/_admin/cache</code> endpoint</li>
+    </ul>
+
+    <h3>Cache Size</h3>
+    <ul>
+      <li>Start with <code>maxSize</code> = 10x your typical concurrent routes</li>
+      <li>Increase if you have many route files and sufficient memory</li>
+      <li>Decrease for microservices with few routes</li>
+    </ul>
+
+    <h3>TTL Settings</h3>
+    <ul>
+      <li><strong>Development:</strong> Short TTL (5-10 minutes) for quick iteration</li>
+      <li><strong>Production:</strong> Longer TTL (30-60 minutes) for stability</li>
+      <li><strong>High-change environments:</strong> Shorter TTL or rely on file watching</li>
+    </ul>
+
+    <h3>File Watching</h3>
+    <ul>
+      <li><strong>Enable</strong> (<code>watchFiles: true</code>) in development for instant invalidation</li>
+      <li><strong>Disable</strong> (<code>watchFiles: false</code>) in production to reduce overhead</li>
+    </ul>
+
+    <h2>Configuration Examples</h2>
+
+    <h3>Minimal Configuration</h3>
+    <p>Just enable caching with defaults:</p>
+    <pre><code class="hljs json">{
+  <span class="hljs-attr">"cache"</span>: {
+    <span class="hljs-attr">"enabled"</span>: <span class="hljs-literal">true</span>
+  }
+}</code></pre>
+
+    <h3>High-Traffic Configuration</h3>
+    <p>For servers with lots of routes and traffic:</p>
+    <pre><code class="hljs json">{
+  <span class="hljs-attr">"cache"</span>: {
+    <span class="hljs-attr">"enabled"</span>: <span class="hljs-literal">true</span>,
+    <span class="hljs-attr">"maxSize"</span>: <span class="hljs-number">2000</span>,
+    <span class="hljs-attr">"maxMemoryMB"</span>: <span class="hljs-number">500</span>,
+    <span class="hljs-attr">"ttlMs"</span>: <span class="hljs-number">7200000</span>,
+    <span class="hljs-attr">"watchFiles"</span>: <span class="hljs-literal">false</span>
+  }
+}</code></pre>
+
+    <h3>Memory-Constrained Configuration</h3>
+    <p>For servers with limited RAM:</p>
+    <pre><code class="hljs json">{
+  <span class="hljs-attr">"cache"</span>: {
+    <span class="hljs-attr">"enabled"</span>: <span class="hljs-literal">true</span>,
+    <span class="hljs-attr">"maxSize"</span>: <span class="hljs-number">25</span>,
+    <span class="hljs-attr">"maxMemoryMB"</span>: <span class="hljs-number">10</span>,
+    <span class="hljs-attr">"ttlMs"</span>: <span class="hljs-number">120000</span>,
+    <span class="hljs-attr">"maxHeapUsagePercent"</span>: <span class="hljs-number">60</span>
+  }
+}</code></pre>
+
+    <h2>Troubleshooting</h2>
+
+    <h3>Cache Not Working</h3>
+    <ul>
+      <li>Verify <code>cache.enabled</code> is <code>true</code></li>
+      <li>Check file permissions for watching</li>
+      <li>Review server logs for cache statistics</li>
+    </ul>
+
+    <h3>Memory Issues</h3>
+    <ul>
+      <li>Reduce <code>maxMemoryMB</code> and <code>maxSize</code></li>
+      <li>Lower <code>maxHeapUsagePercent</code></li>
+      <li>Enable more aggressive memory monitoring</li>
+    </ul>
+
+    <h3>Performance Issues</h3>
+    <ul>
+      <li>Increase cache limits if you have available memory</li>
+      <li>Extend <code>ttlMs</code> for stable route files</li>
+      <li>Monitor hit rates with admin endpoints</li>
+    </ul>
+	</content>
+</page>

package/docs-src/cli-utils.page.html

@@ -0,0 +1,71 @@
+<page pageName="CLI Utilities" title="CLI Utilities - Kempo Server">
+	<content>
+    <p>The CLI utilities provide simple command-line argument parsing functionality for Node.js applications.</p>
+
+    <h2>Installation</h2>
+    <p>Import the utilities from the kempo-server package:</p>
+    <pre><code class="hljs javascript">import { getArgs } from 'kempo-server/utils/cli';</code></pre>
+
+    <h2>getArgs(mapping, argv)</h2>
+    <p>Parses command-line arguments into a key-value object.</p>
+
+    <h3>Parameters</h3>
+    <ul>
+      <li><code>mapping</code> (object, optional) - Maps short flag names to full names</li>
+      <li><code>argv</code> (array, optional) - Array of arguments to parse (defaults to <code>process.argv</code>)</li>
+    </ul>
+
+    <h3>Returns</h3>
+    <p>An object where keys are argument names and values are parsed argument values.</p>
+
+    <h3>Features</h3>
+    <ul>
+      <li>Supports both space-separated (<code>--flag value</code>) and equals-separated (<code>--flag=value</code>) formats</li>
+      <li>Automatically converts <code>"true"</code> and <code>"false"</code> strings to boolean values</li>
+      <li>Supports short flags with mapping (e.g., <code>-p</code> maps to <code>port</code>)</li>
+      <li>Handles multiple values for the same flag</li>
+      <li>Boolean flags without values are set to <code>true</code></li>
+    </ul>
+
+    <h3>Examples</h3>
+
+    <h4>Basic Usage</h4>
+    <pre><code class="hljs bash">node app.js --port 8080 --host localhost --verbose</code></pre>
+    <pre><code class="hljs javascript">const args = getArgs();
+// Result: { port: '8080', host: 'localhost', verbose: true }</code></pre>
+
+    <h4>With Short Flag Mapping</h4>
+    <pre><code class="hljs bash">node app.js -p 8080 -h localhost -v</code></pre>
+    <pre><code class="hljs javascript">const args = getArgs({
+  p: 'port',
+  h: 'host',
+  v: 'verbose'
+});
+// Result: { port: '8080', host: 'localhost', verbose: true }</code></pre>
+
+    <h4>Equals-Separated Values</h4>
+    <pre><code class="hljs bash">node app.js --port=8080 --enabled=true --disabled=false --name=John</code></pre>
+    <pre><code class="hljs javascript">const args = getArgs();
+// Result: { port: '8080', enabled: true, disabled: false, name: 'John' }</code></pre>
+
+    <h4>Mixed Formats</h4>
+    <pre><code class="hljs bash">node app.js --port=8080 -h localhost --verbose --config=prod.json</code></pre>
+    <pre><code class="hljs javascript">const args = getArgs({ h: 'host' });
+// Result: { port: '8080', host: 'localhost', verbose: true, config: 'prod.json' }</code></pre>
+
+    <h4>Values with Equals Signs</h4>
+    <pre><code class="hljs bash">node app.js --url=https://example.com?param=value</code></pre>
+    <pre><code class="hljs javascript">const args = getArgs();
+// Result: { url: 'https://example.com?param=value' }</code></pre>
+
+    <h2>Other Functions</h2>
+    <p>The CLI utilities module also exports other functions for running child processes and prompting users:</p>
+    <ul>
+      <li><code>runChildProcess(command)</code> - Run a shell command</li>
+      <li><code>runChildNodeProcess(scriptPath, argsObj)</code> - Run a Node.js script with arguments</li>
+      <li><code>runChildNodeProcessScript(scriptPath)</code> - Run a Node.js script</li>
+      <li><code>promptUser(query)</code> - Prompt user for input</li>
+      <li><code>promptYN(query, defaultValue)</code> - Prompt for yes/no with default</li>
+    </ul>
+	</content>
+</page>