kempo-server 1.8.3 → 1.8.4

package/README.md

@@ -364,6 +364,15 @@ https://github.com/dustinpoissant/kempo-testing-framework
 
 ## Documentation
 
+- **[Getting Started](./docs/getting-started.html)** - Installation and basic usage
+- **[Routing](./docs/routing.html)** - File-based routing system
+- **[Request & Response](./docs/request-response.html)** - Working with HTTP objects
+- **[Configuration](./docs/configuration.html)** - Server configuration options
+- **[Middleware](./docs/middleware.html)** - Built-in and custom middleware
+- **[Caching](./docs/caching.html)** - Cache configuration and management
+- **[CLI Utilities](./docs/cli-utils.html)** - Command-line argument parsing
+- **[File System Utilities](./docs/fs-utils.html)** - File and directory operations
+- **[Examples](./docs/examples.html)** - Interactive examples and demos
 - **[CONFIG.md](./CONFIG.md)** - Comprehensive server configuration guide
 - **[UTILS.md](./UTILS.md)** - Utility modules for Node.js projects
 

package/dist/utils/cli.js

@@ -1 +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});
+import{spawn}from"child_process";import readline from"readline";export const getArgs=(mapping={},argv=process.argv)=>{const args={};let currentName="",values=[];const save=()=>{if(currentName)if(0===values.length)args[currentName]=!0;else if(1===values.length){const val=values[0];args[currentName]="false"!==val&&("true"===val||val)}else args[currentName]=values};for(let i=2;i<argv.length;i++){const arg=argv[i];if(arg.startsWith("-")){let name;if(save(),name=arg.startsWith("--")?arg.slice(2):arg.slice(1),name.includes("=")){const[key,...valParts]=name.split("=");name=key,values=[valParts.join("=")]}else values=[];mapping[name]&&(name=mapping[name]),currentName=name}else 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/docs/cli-utils.html

@@ -0,0 +1,87 @@
+<!DOCTYPE html>
+<html lang="en" theme="auto">
+<head>
+  <meta charset='utf-8'>
+  <meta http-equiv='X-UA-Compatible' content='IE=edge'>
+  <title>CLI Utilities - Kempo Server</title>
+  <meta name='viewport' content='width=device-width, initial-scale=1'>
+  <link rel="icon" type="image/png" sizes="48x48" href="./media/icon48.png">
+  <link rel="manifest" href="./manifest.json">
+  <link rel="stylesheet" href="./kempo.min.css" />
+</head>
+<body>
+  <main>
+    <a href="./" class="btn">Home</a>
+    <h1>CLI Utilities</h1>
+    <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>
+  </main>
+  <div style="height:25vh"></div>
+</body>
+</html></content>
+<parameter name="filePath">c:\Users\dusti\dev\kempo-server\docs\cli-utils.html

package/docs/fs-utils.html

@@ -0,0 +1,118 @@
+<!DOCTYPE html>
+<html lang="en" theme="auto">
+<head>
+  <meta charset='utf-8'>
+  <meta http-equiv='X-UA-Compatible' content='IE=edge'>
+  <title>File System Utilities - Kempo Server</title>
+  <meta name='viewport' content='width=device-width, initial-scale=1'>
+  <link rel="icon" type="image/png" sizes="48x48" href="./media/icon48.png">
+  <link rel="manifest" href="./manifest.json">
+  <link rel="stylesheet" href="./kempo.min.css" />
+</head>
+<body>
+  <main>
+    <a href="./" class="btn">Home</a>
+    <h1>File System Utilities</h1>
+    <p>The file system utilities provide common file and directory operations with Promise-based APIs for Node.js applications.</p>
+
+    <h2>Installation</h2>
+    <p>Import the utilities from the kempo-server package:</p>
+    <pre><code class="hljs javascript">import { ensureDir, copyDir, emptyDir } from 'kempo-server/utils/fs-utils';</code></pre>
+
+    <h2>ensureDir(dirPath)</h2>
+    <p>Ensures that a directory exists, creating it and any necessary parent directories if they don't exist. Similar to <code>mkdir -p</code>.</p>
+
+    <h3>Parameters</h3>
+    <ul>
+      <li><code>dirPath</code> (string) - The directory path to ensure exists</li>
+    </ul>
+
+    <h3>Returns</h3>
+    <p>Promise that resolves when the directory is confirmed to exist.</p>
+
+    <h3>Example</h3>
+    <pre><code class="hljs javascript">import { ensureDir } from 'kempo-server/utils/fs-utils';
+
+await ensureDir('./dist/assets');
+await ensureDir('./logs/app');
+// Creates ./dist/assets and ./logs/app directories if they don't exist</code></pre>
+
+    <h2>copyDir(srcPath, destPath)</h2>
+    <p>Recursively copies an entire directory structure from source to destination.</p>
+
+    <h3>Parameters</h3>
+    <ul>
+      <li><code>srcPath</code> (string) - The source directory to copy from</li>
+      <li><code>destPath</code> (string) - The destination directory to copy to</li>
+    </ul>
+
+    <h3>Returns</h3>
+    <p>Promise that resolves when the copy operation is complete.</p>
+
+    <h3>Example</h3>
+    <pre><code class="hljs javascript">import { copyDir } from 'kempo-server/utils/fs-utils';
+
+await copyDir('./src/assets', './dist/assets');
+await copyDir('./public', './dist');
+// Copies all files and subdirectories from src to dest</code></pre>
+
+    <h2>emptyDir(dirPath)</h2>
+    <p>Removes all contents of a directory without deleting the directory itself.</p>
+
+    <h3>Parameters</h3>
+    <ul>
+      <li><code>dirPath</code> (string) - The directory path to empty</li>
+    </ul>
+
+    <h3>Returns</h3>
+    <p>Promise that resolves when the directory has been emptied.</p>
+
+    <h3>Example</h3>
+    <pre><code class="hljs javascript">import { emptyDir } from 'kempo-server/utils/fs-utils';
+
+await emptyDir('./dist');
+await emptyDir('./temp');
+// Removes all files and subdirectories inside ./dist and ./temp</code></pre>
+
+    <h2>Common Use Cases</h2>
+
+    <h3>Build Script</h3>
+    <pre><code class="hljs javascript">import { ensureDir, copyDir, emptyDir } from 'kempo-server/utils/fs-utils';
+
+async function buildProject() {
+  // Clean previous build
+  await emptyDir('./dist');
+  
+  // 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');
+}</code></pre>
+
+    <h3>Backup Script</h3>
+    <pre><code class="hljs javascript">import { ensureDir, copyDir } from 'kempo-server/utils/fs-utils';
+
+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`);
+}</code></pre>
+
+    <h2>Notes</h2>
+    <ul>
+      <li>All functions use Node.js's Promise-based fs APIs</li>
+      <li>Operations are asynchronous and should be awaited</li>
+      <li>Functions handle errors appropriately (e.g., ensureDir ignores EEXIST)</li>
+      <li>copyDir preserves directory structure recursively</li>
+    </ul>
+  </main>
+  <div style="height:25vh"></div>
+</body>
+</html></content>
+<parameter name="filePath">c:\Users\dusti\dev\kempo-server\docs\fs-utils.html

package/docs/index.html

@@ -35,6 +35,8 @@
             <li><a href="configuration.html">Configuration</a></li>
             <li><a href="middleware.html">Middleware</a></li>
             <li><a href="caching.html">Module Caching</a></li>
+            <li><a href="cli-utils.html">CLI Utilities</a></li>
+            <li><a href="fs-utils.html">File System Utilities</a></li>
             <li><a href="examples.html">Examples & Demos</a></li>
           </ul>
         </div>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kempo-server",
   "type": "module",
-  "version": "1.8.3",
+  "version": "1.8.4",
   "description": "A lightweight, zero-dependency, file based routing server.",
   "main": "dist/index.js",
   "exports": {

package/tests/cli.node-test.js

@@ -0,0 +1,64 @@
+import { getArgs } from '../utils/cli.js';
+
+export default {
+  'parses long flags with space-separated values': async ({pass, fail}) => {
+    const argv = ['node', 'script.js', '--name', 'John', '--age', '30'];
+    const args = getArgs({}, argv);
+
+    if (args.name !== 'John') return fail('name not parsed');
+    if (args.age !== '30') return fail('age not parsed');
+
+    pass('space-separated values work');
+  },
+
+  'parses long flags with equals-separated values': async ({pass, fail}) => {
+    const argv = ['node', 'script.js', '--name=John', '--age=30'];
+    const args = getArgs({}, argv);
+
+    if (args.name !== 'John') return fail('name not parsed with equals');
+    if (args.age !== '30') return fail('age not parsed with equals');
+
+    pass('equals-separated values work');
+  },
+
+  'parses short flags with equals-separated values and mapping': async ({pass, fail}) => {
+    const argv = ['node', 'script.js', '-n=John', '-a=30'];
+    const args = getArgs({ n: 'name', a: 'age' }, argv);
+
+    if (args.name !== 'John') return fail('short name not parsed with equals');
+    if (args.age !== '30') return fail('short age not parsed with equals');
+
+    pass('short flags with equals and mapping work');
+  },
+
+  'handles mixed formats': async ({pass, fail}) => {
+    const argv = ['node', 'script.js', '--name=John', '-a', '30', '--verbose'];
+    const args = getArgs({ a: 'age' }, argv);
+
+    if (args.name !== 'John') return fail('equals format failed');
+    if (args.age !== '30') return fail('space format failed');
+    if (args.verbose !== true) return fail('boolean flag failed');
+
+    pass('mixed formats work');
+  },
+
+  'handles values with equals signs': async ({pass, fail}) => {
+    const argv = ['node', 'script.js', '--url=https://example.com?param=value'];
+    const args = getArgs({}, argv);
+
+    if (args.url !== 'https://example.com?param=value') return fail('value with equals not handled');
+
+    pass('values with equals work');
+  },
+
+  'converts string true and false to booleans': async ({pass, fail}) => {
+    const argv = ['node', 'script.js', '--enabled=true', '--disabled=false', '--name=John'];
+    const args = getArgs({}, argv);
+
+    if (args.enabled !== true) return fail('true not converted to boolean');
+    if (args.disabled !== false) return fail('false not converted to boolean');
+    if (args.name !== 'John') return fail('string value not handled');
+
+    pass('string booleans converted correctly');
+  }
+};

package/utils/cli.js

@@ -4,40 +4,51 @@ import readline from 'readline';
 /*
   Argument Parsing
 */
-export const getArgs = (mapping = {}) => {
+export const getArgs = (mapping = {}, argv = process.argv) => {
   const args = {};
-  let name = '';
+  let currentName = '';
   let values = [];
   
   const save = () => {
-    if(name){
+    if(currentName){
       if(values.length === 0){
-        args[name] = true;
+        args[currentName] = true;
       } else if(values.length === 1){
-        if(values[0] === 'false'){
-          args[name] = false;
+        const val = values[0];
+        if(val === 'false'){
+          args[currentName] = false;
+        } else if(val === 'true'){
+          args[currentName] = true;
         } else {
-          args[name] = values[0];
+          args[currentName] = val;
         }
       } else {
-        args[name] = values;
+        args[currentName] = values;
       }
     }
   };
 
-  for(let i = 2; i < process.argv.length; i++){
-    const arg = process.argv[i];
+  for(let i = 2; i < argv.length; i++){
+    const arg = argv[i];
     if(arg.startsWith('-')){
       save();
+      let name;
       if(arg.startsWith('--')){
         name = arg.slice(2);
       } else {
         name = arg.slice(1);
-        if(mapping[name]){
-          name = mapping[name];
-        }
       }
-      values = [];
+      if(name.includes('=')){
+        const [key, ...valParts] = name.split('=');
+        name = key;
+        values = [valParts.join('=')];
+      } else {
+        values = [];
+      }
+      if(mapping[name]){
+        name = mapping[name];
+      }
+      currentName = name;
     } else {
       values.push(arg);
     }