kempo-server 2.2.0 → 3.0.1

package/docs-src/examples.page.html

@@ -0,0 +1,192 @@
+<page pageName="Examples &amp; Demos" title="Examples &amp; Demos - Kempo Server">
+	<content>
+    <p>Explore practical examples and try interactive demos of Kempo Server features.</p>
+
+    <h2>Code Examples</h2>
+
+    <h3>Simple API Route</h3>
+    <pre><code class="hljs javascript"><span class="hljs-comment">// api/hello/GET.js</span><br /><span class="hljs-keyword">export</span> <span class="hljs-keyword">default</span> <span class="hljs-keyword">async</span> <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">request, response</span>) </span>{<br />  <span class="hljs-keyword">const</span> { name } = request.query;<br />  <span class="hljs-keyword">const</span> message = name ? <span class="hljs-string">`Hello ${name}!`</span> : <span class="hljs-string">'Hello World!'</span>;<br />  <br />  response.json({ message });<br />}</code></pre>
+
+    <h3>Dynamic User Profile Route</h3>
+    <pre><code class="hljs javascript"><span class="hljs-comment">// api/users/[id]/GET.js</span><br /><span class="hljs-keyword">export</span> <span class="hljs-keyword">default</span> <span class="hljs-keyword">async</span> <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">request, response</span>) </span>{<br />  <span class="hljs-keyword">const</span> { id } = request.params;<br />  <span class="hljs-keyword">const</span> { includeProfile } = request.query;<br />  <br />  <span class="hljs-comment">// Simulate database lookup</span><br />  <span class="hljs-keyword">const</span> user = {<br />    id: id,<br />    name: <span class="hljs-string">`User ${id}`</span>,<br />    email: <span class="hljs-string">`user${id}@example.com`</span><br />  };<br />  <br />  <span class="hljs-keyword">if</span> (includeProfile === <span class="hljs-string">'true'</span>) {<br />    user.profile = {<br />      bio: <span class="hljs-string">`Bio for user ${id}`</span>,<br />      joinDate: <span class="hljs-string">'2024-01-01'</span><br />    };<br />  }<br />  <br />  response.json(user);<br />}</code></pre>
+
+    <h3>Form Handling Route</h3>
+    <pre><code class="hljs javascript"><span class="hljs-comment">// contact/POST.js</span><br /><span class="hljs-keyword">export</span> <span class="hljs-keyword">default</span> <span class="hljs-keyword">async</span> <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">request, response</span>) </span>{<br />  <span class="hljs-keyword">try</span> {<br />    <span class="hljs-keyword">const</span> body = <span class="hljs-keyword">await</span> request.text();<br />    <span class="hljs-keyword">const</span> formData = <span class="hljs-keyword">new</span> URLSearchParams(body);<br />    <span class="hljs-keyword">const</span> name = formData.get(<span class="hljs-string">'name'</span>);<br />    <span class="hljs-keyword">const</span> email = formData.get(<span class="hljs-string">'email'</span>);<br />    <span class="hljs-keyword">const</span> message = formData.get(<span class="hljs-string">'message'</span>);<br />    <br />    <span class="hljs-comment">// Process form data...</span><br />    <span class="hljs-keyword">await</span> sendContactEmail({ name, email, message });<br />    <br />    response.html(<span class="hljs-string">'&lt;h1&gt;Thank you for your message!&lt;/h1&gt;'</span>);<br />  } <span class="hljs-keyword">catch</span> (error) {<br />    response.status(<span class="hljs-number">400</span>).html(<span class="hljs-string">'&lt;h1&gt;Error processing form&lt;/h1&gt;'</span>);<br />  }<br />}</code></pre>
+
+    <h3>File Upload Handling</h3>
+    <pre><code class="hljs javascript"><span class="hljs-comment">// api/upload/POST.js</span><br /><span class="hljs-keyword">import</span> fs <span class="hljs-keyword">from</span> <span class="hljs-string">'fs/promises'</span>;<br /><span class="hljs-keyword">import</span> path <span class="hljs-keyword">from</span> <span class="hljs-string">'path'</span>;<br /><br /><span class="hljs-keyword">export</span> <span class="hljs-keyword">default</span> <span class="hljs-keyword">async</span> <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">request, response</span>) </span>{<br />  <span class="hljs-keyword">try</span> {<br />    <span class="hljs-keyword">const</span> buffer = <span class="hljs-keyword">await</span> request.buffer();<br />    <span class="hljs-keyword">const</span> contentType = request.get(<span class="hljs-string">'content-type'</span>);<br />    <br />    <span class="hljs-comment">// Generate filename</span><br />    <span class="hljs-keyword">const</span> extension = getExtensionFromMimeType(contentType);<br />    <span class="hljs-keyword">const</span> filename = <span class="hljs-string">`upload_${Date.now()}.${extension}`</span>;<br />    <span class="hljs-keyword">const</span> filepath = path.join(<span class="hljs-string">'./uploads'</span>, filename);<br />    <br />    <span class="hljs-comment">// Ensure uploads directory exists</span><br />    <span class="hljs-keyword">await</span> fs.mkdir(<span class="hljs-string">'./uploads'</span>, { recursive: <span class="hljs-literal">true</span> });<br />    <br />    <span class="hljs-comment">// Save file</span><br />    <span class="hljs-keyword">await</span> fs.writeFile(filepath, buffer);<br />    <br />    response.json({<br />      message: <span class="hljs-string">'File uploaded successfully'</span>,<br />      filename: filename,<br />      size: buffer.length,<br />      type: contentType<br />    });<br />  } <span class="hljs-keyword">catch</span> (error) {<br />    response.status(<span class="hljs-number">500</span>).json({<br />      error: <span class="hljs-string">'Upload failed'</span>,<br />      message: error.message<br />    });<br />  }<br />}<br /><br /><span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-title">getExtensionFromMimeType</span>(<span class="hljs-params">mimeType</span>) </span>{<br />  <span class="hljs-keyword">const</span> mimeMap = {<br />    <span class="hljs-string">'image/jpeg'</span>: <span class="hljs-string">'jpg'</span>,<br />    <span class="hljs-string">'image/png'</span>: <span class="hljs-string">'png'</span>,<br />    <span class="hljs-string">'image/gif'</span>: <span class="hljs-string">'gif'</span>,<br />    <span class="hljs-string">'text/plain'</span>: <span class="hljs-string">'txt'</span>,<br />    <span class="hljs-string">'application/pdf'</span>: <span class="hljs-string">'pdf'</span><br />  };<br />  <span class="hljs-keyword">return</span> mimeMap[mimeType] || <span class="hljs-string">'bin'</span>;<br />}</code></pre>
+
+    <h3>Authentication Route</h3>
+    <pre><code class="hljs javascript"><span class="hljs-comment">// api/auth/login/POST.js</span><br /><span class="hljs-keyword">import</span> crypto <span class="hljs-keyword">from</span> <span class="hljs-string">'crypto'</span>;<br /><br /><span class="hljs-keyword">export</span> <span class="hljs-keyword">default</span> <span class="hljs-keyword">async</span> <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">request, response</span>) </span>{<br />  <span class="hljs-keyword">try</span> {<br />    <span class="hljs-keyword">const</span> { username, password } = <span class="hljs-keyword">await</span> request.json();<br />    <br />    <span class="hljs-comment">// Validate credentials</span><br />    <span class="hljs-keyword">const</span> user = <span class="hljs-keyword">await</span> authenticateUser(username, password);<br />    <br />    <span class="hljs-keyword">if</span> (!user) {<br />      <span class="hljs-keyword">return</span> response.status(<span class="hljs-number">401</span>).json({<br />        error: <span class="hljs-string">'Invalid credentials'</span><br />      });<br />    }<br />    <br />    <span class="hljs-comment">// Generate session token</span><br />    <span class="hljs-keyword">const</span> sessionToken = crypto.randomBytes(<span class="hljs-number">32</span>).toString(<span class="hljs-string">'hex'</span>);<br />    <span class="hljs-keyword">await</span> createSession(user.id, sessionToken);<br />    <br />    <span class="hljs-comment">// Set secure cookie</span><br />    response<br />      .cookie(<span class="hljs-string">'session'</span>, sessionToken, {<br />        httpOnly: <span class="hljs-literal">true</span>,<br />        secure: <span class="hljs-literal">true</span>,<br />        sameSite: <span class="hljs-string">'strict'</span>,<br />        maxAge: <span class="hljs-number">24</span> * <span class="hljs-number">60</span> * <span class="hljs-number">60</span> * <span class="hljs-number">1000</span> <span class="hljs-comment">// 24 hours</span><br />      })<br />      .json({<br />        message: <span class="hljs-string">'Login successful'</span>,<br />        user: {<br />          id: user.id,<br />          username: user.username,<br />          email: user.email<br />        }<br />      });<br />  } <span class="hljs-keyword">catch</span> (error) {<br />    response.status(<span class="hljs-number">400</span>).json({<br />      error: <span class="hljs-string">'Invalid request'</span>,<br />      message: error.message<br />    });<br />  }<br />}</code></pre>
+
+    <h2>Interactive Demos</h2>
+    <p>Try out the example API endpoints below. These demonstrations show the actual routes working in this documentation site.</p>
+
+    <div class="mb">
+      <h3 class="mt0">Get User Profile</h3>
+      <p><code>GET /api/user/[id]</code></p>
+      <div class="row -mx">
+        <div class="col m-span-12 d-span-6 px">
+          <pre><code class="hljs javascript"><span class="hljs-comment">// api/user/[id]/GET.js</span><br /><span class="hljs-keyword">export</span> <span class="hljs-keyword">default</span> <span class="hljs-keyword">async</span> <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">request, response</span>) </span>{<br />  <span class="hljs-keyword">const</span> { id } = request.params;<br />  <br />  <span class="hljs-keyword">const</span> userData = {<br />    id: id,<br />    profile: {<br />      name: <span class="hljs-string">`${id.charAt(0).toUpperCase()}${id.slice(1)}`</span>,<br />      joinDate: <span class="hljs-string">'2024-01-15'</span>,<br />      posts: <span class="hljs-number">42</span><br />    }<br />  };<br />  <br />  response.json(userData);<br />}</code></pre>
+          <div class="mb">
+            <input type="text" id="userId" placeholder="Enter user ID (e.g., john)" value="john" class="mb mr">
+            <button onclick="fetchUser()" class="primary">GET User</button>
+          </div>
+        </div>
+        <div class="col m-span-12 d-span-6 px">
+          <h4>Response:</h4>
+          <pre><output id="userOutput" class="pb">Click "GET User" to see the response</output></pre>
+        </div>
+      </div>
+    </div>
+
+    <div class="mb">
+      <h3 class="mt0">Get User Info</h3>
+      <p><code>GET /api/user/[id]/[info]</code></p>
+      <div class="row -mx">
+        <div class="col m-span-12 d-span-6 px">
+          <pre><code class="hljs javascript"><span class="hljs-comment">// api/user/[id]/[info]/GET.js</span><br /><span class="hljs-keyword">export</span> <span class="hljs-keyword">default</span> <span class="hljs-keyword">async</span> <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">request, response</span>) </span>{<br />  <span class="hljs-keyword">const</span> { id, info } = request.params;<br />  <br />  <span class="hljs-keyword">const</span> userInfo = {<br />    id: id,<br />    details: {<br />      bio: <span class="hljs-string">`This is ${id}'s bio`</span>,<br />      location: <span class="hljs-string">'Earth'</span>,<br />      website: <span class="hljs-string">`https://${id}.dev`</span>,<br />      followers: <span class="hljs-number">123</span>,<br />      following: <span class="hljs-number">456</span><br />    }<br />  };<br />  <br />  response.json(userInfo);<br />}</code></pre>
+          <div class="mb">
+            <input type="text" id="userInfoId" placeholder="Enter user ID" value="alice" class="mb mr">
+            <button onclick="fetchUserInfo()" class="primary">GET User Info</button>
+          </div>
+        </div>
+        <div class="col m-span-12 d-span-6 px">
+          <h4>Response:</h4>
+          <pre><output id="userInfoOutput" class="pb">Click "GET User Info" to see the response</output></pre>
+        </div>
+      </div>
+    </div>
+
+    <div class="mb">
+      <h3 class="mt0">Update User Info</h3>
+      <p><code>POST /api/user/[id]/[info]</code></p>
+      <div class="row -mx">
+        <div class="col m-span-12 d-span-6 px">
+          <pre><code class="hljs javascript"><span class="hljs-comment">// api/user/[id]/[info]/POST.js</span><br /><span class="hljs-keyword">export</span> <span class="hljs-keyword">default</span> <span class="hljs-keyword">async</span> <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">request, response</span>) </span>{<br />  <span class="hljs-keyword">const</span> { id, info } = request.params;<br />  <br />  <span class="hljs-keyword">try</span> {<br />    <span class="hljs-keyword">const</span> updateData = <span class="hljs-keyword">await</span> request.json();<br />    <br />    <span class="hljs-keyword">const</span> updatedUser = {<br />      id: id,<br />      message: <span class="hljs-string">'User info updated successfully'</span>,<br />      updatedFields: updateData<br />    };<br />    <br />    response.json(updatedUser);<br />  } <span class="hljs-keyword">catch</span> (error) {<br />    response.status(<span class="hljs-number">400</span>).json({ error: <span class="hljs-string">'Invalid JSON'</span> });<br />  }<br />}</code></pre>
+          <div class="mb">
+            <input type="text" id="postUserId" placeholder="Enter user ID" value="bob" class="mb">
+            <textarea id="postData" placeholder="Enter JSON data to update" class="mb">{
+  "bio": "Updated bio text",
+  "location": "New York"
+}</textarea>
+            <button onclick="updateUserInfo()" class="primary">POST Update</button>
+          </div>
+        </div>
+        <div class="col m-span-12 d-span-6 px">
+          <h4>Response:</h4>
+          <pre><output id="postOutput" class="pb">Click "POST Update" to see the response</output></pre>
+        </div>
+      </div>
+    </div>
+
+    <div class="mb">
+      <h3 class="mt0">Delete User Info</h3>
+      <p><code>DELETE /api/user/[id]/[info]</code></p>
+      <div class="row -mx">
+        <div class="col m-span-12 d-span-6 px">
+          <pre><code class="hljs javascript"><span class="hljs-comment">// api/user/[id]/[info]/DELETE.js</span><br /><span class="hljs-keyword">export</span> <span class="hljs-keyword">default</span> <span class="hljs-keyword">async</span> <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">request, response</span>) </span>{<br />  <span class="hljs-keyword">const</span> { id, info } = request.params;<br />  <br />  <span class="hljs-keyword">const</span> result = {<br />    id: id,<br />    message: <span class="hljs-string">'User info deleted successfully'</span>,<br />    deletedAt: <span class="hljs-keyword">new</span> <span class="hljs-built_in">Date</span>().toISOString()<br />  };<br />  <br />  response.json(result);<br />}</code></pre>
+          <div class="mb">
+            <input type="text" id="deleteUserId" placeholder="Enter user ID" value="charlie" class="mr">
+            <button onclick="deleteUserInfo()" class="primary">DELETE Info</button>
+          </div>
+        </div>
+        <div class="col m-span-12 d-span-6 px">
+          <h4>Response:</h4>
+          <pre><output id="deleteOutput" class="pb">Click "DELETE Info" to see the response</output></pre>
+        </div>
+      </div>
+    </div>
+
+    <h2>Project Structure Examples</h2>
+
+    <h3>Basic Blog API</h3>
+    <pre><code class="hljs markdown">blog-api/<br />├─ public/                    # Web root<br />│  ├─ index.html             # Homepage<br />│  ├─ api/<br />│  │  ├─ posts/<br />│  │  │  ├─ GET.js           # Get all posts<br />│  │  │  ├─ POST.js          # Create new post<br />│  │  │  ├─ [id]/<br />│  │  │  │  ├─ GET.js        # Get specific post<br />│  │  │  │  ├─ PUT.js        # Update post<br />│  │  │  │  ├─ DELETE.js     # Delete post<br />│  │  │  │  ├─ comments/<br />│  │  │  │  │  ├─ GET.js     # Get post comments<br />│  │  │  │  │  ├─ POST.js    # Add comment<br />│  │  ├─ users/<br />│  │  │  ├─ GET.js           # Get all users<br />│  │  │  ├─ POST.js          # Create user<br />│  │  │  ├─ [id]/<br />│  │  │  │  ├─ GET.js        # Get user profile<br />│  │  │  │  ├─ PUT.js        # Update user<br />│  │  │  │  ├─ DELETE.js     # Delete user<br />│  │  ├─ auth/<br />│  │  │  ├─ login/<br />│  │  │  │  ├─ POST.js       # User login<br />│  │  │  ├─ logout/<br />│  │  │  │  ├─ POST.js       # User logout<br />│  │  │  ├─ register/<br />│  │  │  │  ├─ POST.js       # User registration<br />├─ middleware/<br />│  ├─ auth.js                # Authentication middleware<br />│  ├─ logging.js             # Request logging<br />├─ .config.json              # Server configuration<br />├─ package.json<br /></code></pre>
+
+    <h3>E-commerce API</h3>
+    <pre><code class="hljs markdown">ecommerce-api/<br />├─ public/<br />│  ├─ api/<br />│  │  ├─ products/<br />│  │  │  ├─ GET.js           # Get all products<br />│  │  │  ├─ POST.js          # Create product<br />│  │  │  ├─ [id]/<br />│  │  │  │  ├─ GET.js        # Get product details<br />│  │  │  │  ├─ PUT.js        # Update product<br />│  │  │  │  ├─ DELETE.js     # Delete product<br />│  │  │  │  ├─ reviews/<br />│  │  │  │  │  ├─ GET.js     # Get product reviews<br />│  │  │  │  │  ├─ POST.js    # Add review<br />│  │  │  ├─ categories/<br />│  │  │  │  ├─ [category]/<br />│  │  │  │  │  ├─ GET.js     # Get products by category<br />│  │  ├─ cart/<br />│  │  │  ├─ GET.js           # Get cart contents<br />│  │  │  ├─ POST.js          # Add item to cart<br />│  │  │  ├─ [id]/<br />│  │  │  │  ├─ PUT.js        # Update cart item<br />│  │  │  │  ├─ DELETE.js     # Remove cart item<br />│  │  ├─ orders/<br />│  │  │  ├─ GET.js           # Get user orders<br />│  │  │  ├─ POST.js          # Create order<br />│  │  │  ├─ [id]/<br />│  │  │  │  ├─ GET.js        # Get order details<br />│  │  │  │  ├─ PUT.js        # Update order status<br />│  │  ├─ users/<br />│  │  │  ├─ [id]/<br />│  │  │  │  ├─ profile/<br />│  │  │  │  │  ├─ GET.js     # Get user profile<br />│  │  │  │  │  ├─ PUT.js     # Update profile<br />│  │  │  │  ├─ addresses/<br />│  │  │  │  │  ├─ GET.js     # Get addresses<br />│  │  │  │  │  ├─ POST.js    # Add address<br />│  │  │  │  │  ├─ [addressId]/<br />│  │  │  │  │  │  ├─ PUT.js  # Update address<br />│  │  │  │  │  │  ├─ DELETE.js # Delete address<br />├─ middleware/<br />│  ├─ auth.js                # User authentication<br />│  ├─ admin.js               # Admin-only routes<br />│  ├─ cors.js                # CORS configuration<br />├─ .config.json<br /></code></pre>
+
+    <h3>SaaS Application API</h3>
+    <pre><code class="hljs markdown">saas-api/<br />├─ public/<br />│  ├─ api/<br />│  │  ├─ auth/<br />│  │  │  ├─ login/<br />│  │  │  ├─ register/<br />│  │  │  ├─ reset-password/<br />│  │  │  ├─ verify-email/<br />│  │  ├─ organizations/<br />│  │  │  ├─ [orgId]/<br />│  │  │  │  ├─ GET.js        # Get organization<br />│  │  │  │  ├─ PUT.js        # Update organization<br />│  │  │  │  ├─ members/<br />│  │  │  │  │  ├─ GET.js     # Get members<br />│  │  │  │  │  ├─ POST.js    # Invite member<br />│  │  │  │  │  ├─ [userId]/<br />│  │  │  │  │  │  ├─ PUT.js  # Update member role<br />│  │  │  │  │  │  ├─ DELETE.js # Remove member<br />│  │  │  │  ├─ projects/<br />│  │  │  │  │  ├─ GET.js     # Get projects<br />│  │  │  │  │  ├─ POST.js    # Create project<br />│  │  │  │  │  ├─ [projectId]/<br />│  │  │  │  │  │  ├─ GET.js  # Get project<br />│  │  │  │  │  │  ├─ PUT.js  # Update project<br />│  │  │  │  │  │  ├─ DELETE.js # Delete project<br />│  │  │  │  │  │  ├─ tasks/<br />│  │  │  │  │  │  │  ├─ GET.js # Get tasks<br />│  │  │  │  │  │  │  ├─ POST.js # Create task<br />│  │  │  │  │  │  │  ├─ [taskId]/<br />│  │  │  │  │  │  │  │  ├─ GET.js # Get task<br />│  │  │  │  │  │  │  │  ├─ PUT.js # Update task<br />│  │  │  │  │  │  │  │  ├─ DELETE.js # Delete task<br />│  │  ├─ billing/<br />│  │  │  ├─ subscriptions/<br />│  │  │  ├─ invoices/<br />│  │  │  ├─ payment-methods/<br />│  │  ├─ analytics/<br />│  │  │  ├─ dashboard/<br />│  │  │  ├─ reports/<br />├─ middleware/<br />│  ├─ auth.js                # Authentication<br />│  ├─ organization.js        # Organization context<br />│  ├─ permissions.js         # Permission checking<br />│  ├─ rate-limit.js          # API rate limiting<br />│  ├─ analytics.js           # Usage analytics<br />├─ .config.json<br /></code></pre>
+
+    <h2>Configuration Examples</h2>
+
+    <h3>Development Configuration</h3>
+    <pre><code class="hljs json">{<br />  <span class="hljs-attr">"allowedMimes"</span>: {<br />    <span class="hljs-attr">"html"</span>: <span class="hljs-string">"text/html"</span>,<br />    <span class="hljs-attr">"css"</span>: <span class="hljs-string">"text/css"</span>,<br />    <span class="hljs-attr">"js"</span>: <span class="hljs-string">"application/javascript"</span>,<br />    <span class="hljs-attr">"json"</span>: <span class="hljs-string">"application/json"</span>,<br />    <span class="hljs-attr">"map"</span>: <span class="hljs-string">"application/json"</span>,<br />    <span class="hljs-attr">"png"</span>: <span class="hljs-string">"image/png"</span>,<br />    <span class="hljs-attr">"jpg"</span>: <span class="hljs-string">"image/jpeg"</span><br />  },<br />  <span class="hljs-attr">"middleware"</span>: {<br />    <span class="hljs-attr">"cors"</span>: {<br />      <span class="hljs-attr">"enabled"</span>: <span class="hljs-literal">true</span>,<br />      <span class="hljs-attr">"origin"</span>: <span class="hljs-string">"*"</span><br />    },<br />    <span class="hljs-attr">"compression"</span>: {<br />      <span class="hljs-attr">"enabled"</span>: <span class="hljs-literal">false</span><br />    },<br />    <span class="hljs-attr">"custom"</span>: [<br />      <span class="hljs-string">"./middleware/logging.js"</span><br />    ]<br />  }<br />}</code></pre>
+
+    <h3>Production Configuration</h3>
+    <pre><code class="hljs json">{<br />  <span class="hljs-attr">"allowedMimes"</span>: {<br />    <span class="hljs-attr">"html"</span>: <span class="hljs-string">"text/html"</span>,<br />    <span class="hljs-attr">"css"</span>: <span class="hljs-string">"text/css"</span>,<br />    <span class="hljs-attr">"js"</span>: <span class="hljs-string">"application/javascript"</span>,<br />    <span class="hljs-attr">"json"</span>: <span class="hljs-string">"application/json"</span>,<br />    <span class="hljs-attr">"png"</span>: <span class="hljs-string">"image/png"</span>,<br />    <span class="hljs-attr">"jpg"</span>: <span class="hljs-string">"image/jpeg"</span>,<br />    <span class="hljs-attr">"svg"</span>: <span class="hljs-string">"image/svg+xml"</span>,<br />    <span class="hljs-attr">"woff"</span>: <span class="hljs-string">"font/woff"</span>,<br />    <span class="hljs-attr">"woff2"</span>: <span class="hljs-string">"font/woff2"</span><br />  },<br />  <span class="hljs-attr">"disallowedRegex"</span>: [<br />    <span class="hljs-string">"^/\\..*"</span>,<br />    <span class="hljs-string">"\\.env$"</span>,<br />    <span class="hljs-string">"\\.config$"</span>,<br />    <span class="hljs-string">"password"</span>,<br />    <span class="hljs-string">"secret"</span>,<br />    <span class="hljs-string">"node_modules"</span>,<br />    <span class="hljs-string">"\\.git"</span>,<br />    <span class="hljs-string">"\\.map$"</span><br />  ],<br />  <span class="hljs-attr">"middleware"</span>: {<br />    <span class="hljs-attr">"cors"</span>: {<br />      <span class="hljs-attr">"enabled"</span>: <span class="hljs-literal">true</span>,<br />      <span class="hljs-attr">"origin"</span>: <span class="hljs-string">"https://yourdomain.com"</span>,<br />      <span class="hljs-attr">"credentials"</span>: <span class="hljs-literal">true</span><br />    },<br />    <span class="hljs-attr">"compression"</span>: {<br />      <span class="hljs-attr">"enabled"</span>: <span class="hljs-literal">true</span>,<br />      <span class="hljs-attr">"threshold"</span>: <span class="hljs-number">1024</span><br />    },<br />    <span class="hljs-attr">"security"</span>: {<br />      <span class="hljs-attr">"enabled"</span>: <span class="hljs-literal">true</span>,<br />      <span class="hljs-attr">"headers"</span>: {<br />        <span class="hljs-attr">"X-Content-Type-Options"</span>: <span class="hljs-string">"nosniff"</span>,<br />        <span class="hljs-attr">"X-Frame-Options"</span>: <span class="hljs-string">"DENY"</span>,<br />        <span class="hljs-attr">"X-XSS-Protection"</span>: <span class="hljs-string">"1; mode=block"</span>,<br />        <span class="hljs-attr">"Strict-Transport-Security"</span>: <span class="hljs-string">"max-age=31536000; includeSubDomains"</span><br />      }<br />    },<br />    <span class="hljs-attr">"rateLimit"</span>: {<br />      <span class="hljs-attr">"enabled"</span>: <span class="hljs-literal">true</span>,<br />      <span class="hljs-attr">"maxRequests"</span>: <span class="hljs-number">100</span>,<br />      <span class="hljs-attr">"windowMs"</span>: <span class="hljs-number">60000</span><br />    },<br />    <span class="hljs-attr">"custom"</span>: [<br />      <span class="hljs-string">"./middleware/auth.js"</span>,<br />      <span class="hljs-string">"./middleware/logging.js"</span>,<br />      <span class="hljs-string">"./middleware/analytics.js"</span><br />    ]<br />  }<br />}</code></pre>
+
+    <h3>Programmatic File Rescan</h3>
+    <p>When your code creates or removes files at runtime (e.g., a CMS generating static pages), you can trigger a file rescan without restarting the server. Import the <code>rescan</code> function from anywhere in the same Node process:</p>
+    <pre><code class="hljs javascript"><span class="hljs-comment">// api/pages/POST.js</span><br /><span class="hljs-keyword">import</span> { writeFile } <span class="hljs-keyword">from</span> <span class="hljs-string">'fs/promises'</span>;<br /><span class="hljs-keyword">import</span> rescan <span class="hljs-keyword">from</span> <span class="hljs-string">'kempo-server/rescan'</span>;<br /><br /><span class="hljs-keyword">export</span> <span class="hljs-keyword">default</span> <span class="hljs-keyword">async</span> (req, res) =&gt; {<br />  <span class="hljs-keyword">const</span> { slug, html } = req.body;<br />  <span class="hljs-keyword">await</span> writeFile(<span class="hljs-string">`./pages/${slug}.html`</span>, html);<br />  <span class="hljs-keyword">const</span> fileCount = <span class="hljs-keyword">await</span> rescan();<br />  res.json({ published: <span class="hljs-literal">true</span>, fileCount });<br />};</code></pre>
+    <p>The <code>rescan()</code> function returns a promise that resolves with the number of files found. It works from route handlers, middleware, file watchers, scheduled tasks, or any other code running in the same Node process.</p>
+
+    <script>
+      async function fetchUser() {
+        const userId = document.getElementById('userId').value || 'john';
+        const output = document.getElementById('userOutput');
+        
+        try {
+          output.textContent = 'Loading...';
+          const response = await fetch(`/api/user/${userId}`);
+          const data = await response.json();
+          output.textContent = JSON.stringify(data, null, 2);
+        } catch (error) {
+          output.textContent = `Error: ${error.message}`;
+        }
+      }
+
+      async function fetchUserInfo() {
+        const userId = document.getElementById('userInfoId').value || 'alice';
+        const output = document.getElementById('userInfoOutput');
+        
+        try {
+          output.textContent = 'Loading...';
+          const response = await fetch(`/api/user/${userId}/info`);
+          const data = await response.json();
+          output.textContent = JSON.stringify(data, null, 2);
+        } catch (error) {
+          output.textContent = `Error: ${error.message}`;
+        }
+      }
+
+      async function updateUserInfo() {
+        const userId = document.getElementById('postUserId').value || 'bob';
+        const postData = document.getElementById('postData').value;
+        const output = document.getElementById('postOutput');
+        
+        try {
+          output.textContent = 'Loading...';
+          const response = await fetch(`/api/user/${userId}/info`, {
+            method: 'POST',
+            headers: {
+              'Content-Type': 'application/json',
+            },
+            body: postData
+          });
+          const data = await response.json();
+          output.textContent = JSON.stringify(data, null, 2);
+        } catch (error) {
+          output.textContent = `Error: ${error.message}`;
+        }
+      }
+
+      async function deleteUserInfo() {
+        const userId = document.getElementById('deleteUserId').value || 'charlie';
+        const output = document.getElementById('deleteOutput');
+        
+        try {
+          output.textContent = 'Loading...';
+          const response = await fetch(`/api/user/${userId}/info`, {
+            method: 'DELETE'
+          });
+          const data = await response.json();
+          output.textContent = JSON.stringify(data, null, 2);
+        } catch (error) {
+          output.textContent = `Error: ${error.message}`;
+        }
+      }
+    </script>
+	</content>
+</page>

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

@@ -0,0 +1,102 @@
+<page pageName="File System Utilities" title="File System Utilities - Kempo Server">
+	<content>
+    <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>
+	</content>
+</page>

package/docs-src/getting-started.page.html

@@ -0,0 +1,63 @@
+<page pageName="Getting Started" title="Getting Started - Kempo Server">
+	<content>
+    <p>Get up and running with Kempo Server in just a few steps.</p>
+
+    <h2>Installation</h2>
+    <p>1. Install the npm package.</p>
+    <pre><code>npm install kempo-server</code></pre>
+    
+    <p>2. Add it to your <code>package.json</code> scripts, use the <code>--root</code> flag to tell it where the root of your site is.</p>
+    <pre><code class="hljs json">{<br />  ...<br />  <span class="hljs-attr">"scripts"</span>: {<br />    <span class="hljs-attr">"start"</span>: <span class="hljs-string">"kempo-server --root public"</span><br />  }<br />  ...<br />}</code></pre>
+    
+    <p>3. Run it in your terminal.</p>
+    <pre><code>npm run start</code></pre>
+
+    <h2>Basic Project Structure</h2>
+    <p>Once installed, create a basic project structure:</p>
+    <pre><code class="hljs markdown">my-project/<br />├─ public/             # Your web root<br />│  ├─ index.html       # Homepage<br />│  ├─ styles.css       # CSS files<br />│  ├─ api/             # API routes<br />│  │  ├─ hello/<br />│  │  │  ├─ GET.js     # GET /api/hello/<br />│  │  ├─ users/<br />│  │  │  ├─ GET.js     # GET /api/users/<br />│  │  │  ├─ POST.js    # POST /api/users/<br />├─ package.json<br />├─ .config.json        # Optional configuration<br /></code></pre>
+
+    <h2>Your First Route</h2>
+    <p>Create a simple API endpoint:</p>
+    
+    <h3>1. Create the directory structure</h3>
+    <pre><code>mkdir -p public/api/hello</code></pre>
+    
+    <h3>2. Create your first route file</h3>
+    <p>Create <code>public/api/hello/GET.js</code>:</p>
+    <pre><code class="hljs javascript"><span class="hljs-comment">// public/api/hello/GET.js</span><br /><span class="hljs-keyword">export</span> <span class="hljs-keyword">default</span> <span class="hljs-keyword">async</span> <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">request, response</span>) </span>{<br />  <span class="hljs-keyword">const</span> { name } = request.query;<br />  <span class="hljs-keyword">const</span> message = name ? <span class="hljs-string">`Hello ${name}!`</span> : <span class="hljs-string">'Hello World!'</span>;<br />  <br />  response.json({ message, timestamp: <span class="hljs-keyword">new</span> <span class="hljs-built_in">Date</span>().toISOString() });<br />}</code></pre>
+
+    <h3>3. Test your route</h3>
+    <p>Start your server and visit:</p>
+    <ul>
+      <li><code>http://localhost:3000/api/hello/</code></li>
+      <li><code>http://localhost:3000/api/hello/?name=World</code></li>
+    </ul>
+
+    <h2>Command Line Options</h2>
+    <p>Kempo Server supports several command line options:</p>
+    <ul>
+      <li><code>--root &lt;path&gt;</code> - Set the document root directory (required)</li>
+      <li><code>--port &lt;number&gt;</code> - Set the port number (default: 3000)</li>
+      <li><code>--host &lt;address&gt;</code> - Set the host address (default: localhost)</li>
+      <li><code>--config &lt;path&gt;</code> - Set the configuration file path (default: .config.json)</li>
+      <li><code>--verbose</code> - Enable verbose logging</li>
+    </ul>
+    
+    <p>Basic example:</p>
+    <pre><code>kempo-server --root public --port 8080 --host 0.0.0.0 --verbose</code></pre>
+
+    <h3>Configuration File Examples</h3>
+    <p>You can specify different configuration files for different environments:</p>
+    <pre><code class="hljs bash"># Development<br />kempo-server --root public --config dev.config.json<br /><br /># Staging<br />kempo-server --root public --config staging.config.json<br /><br /># Production with absolute path<br />kempo-server --root public --config /etc/kempo/production.config.json<br /><br /># Mix with other options<br />kempo-server --root dist --port 8080 --config production.config.json</code></pre>
+
+    <h2>What's Next?</h2>
+    <p>Now that you have Kempo Server running, explore these topics:</p>
+    <ul>
+      <li><a href="routing.html">Learn about Routes & Routing</a> - File-based routing, dynamic routes, and HTML routes</li>
+      <li><a href="request-response.html">Request & Response Objects</a> - Working with HTTP requests and responses</li>
+      <li><a href="configuration.html">Configuration</a> - Customize server behavior</li>
+      <li><a href="middleware.html">Middleware</a> - Add authentication, logging, CORS, and more</li>
+      <li><a href="examples.html">Examples & Demos</a> - See real-world examples in action</li>
+    </ul>
+	</content>
+</page>

package/docs-src/index.page.html

@@ -0,0 +1,79 @@
+<page pageName="Kempo Server" title="Kempo Server">
+	<content>
+		<div class="ta-center">
+			<p class="mb0">
+				<a
+					href="https://github.com/dustinpoissant/kempo-server"
+					class="btn primary mr"
+					target="_blank"
+				>GitHub</a>
+				<a
+					href="https://www.npmjs.com/package/kempo-server"
+					class="btn"
+					target="_blank"
+				>NPM</a>
+			</p>
+		</div>
+		<p>A lightweight, zero-dependency, file based routing server.</p>
+
+		<nav class="b r mb p">
+			<div class="row -mx">
+				<div class="col m-span-12 d-span-6 px">
+					<h4 class="mt0">Getting Started</h4>
+					<ul>
+						<li><a href="getting-started.html">Getting Started</a></li>
+						<li><a href="routing.html">Routing</a></li>
+						<li><a href="request-response.html">Request & Response</a></li>
+					</ul>
+				</div>
+				<div class="col m-span-12 d-span-6 px">
+					<h4 class="mt0">Advanced Features</h4>
+					<ul>
+						<li><a href="configuration.html">Configuration</a></li>
+						<li><a href="templating.html">Templating</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>
+			</div>
+		</nav>
+
+		<div class="b r mb p">
+			<h3 class="mt0">Quick Start</h3>
+			<p>Install and run Kempo Server in seconds:</p>
+			<pre><code>npm install kempo-server<br />npx kempo-server --root public</code></pre>
+		</div>
+
+		<div class="row -mx mb">
+			<div class="col m-span-12 d-span-6 px">
+				<div class="b r p">
+					<h4 class="mt0">Features</h4>
+					<ul>
+						<li><strong>Zero Dependencies</strong> - No external dependencies</li>
+						<li><strong>File-based Routing</strong> - Directory structure defines routes</li>
+						<li><strong>Dynamic Routes</strong> - Parameterized routes with [brackets]</li>
+						<li><strong>Wildcard Routes</strong> - Map directories with * patterns</li>
+						<li><strong>Middleware System</strong> - Authentication, CORS, logging, and more</li>
+						<li><strong>Request/Response Objects</strong> - Enhanced request handling</li>
+					</ul>
+				</div>
+			</div>
+			<div class="col m-span-12 d-span-6 px">
+				<div class="b r p">
+					<h4 class="mt0">Built-in Middleware</h4>
+					<ul>
+						<li><strong>CORS</strong> - Cross-origin resource sharing</li>
+						<li><strong>Compression</strong> - Automatic gzip compression</li>
+						<li><strong>Rate Limiting</strong> - Request throttling</li>
+						<li><strong>Security Headers</strong> - Security best practices</li>
+						<li><strong>Request Logging</strong> - Configurable logging</li>
+						<li><strong>Custom Middleware</strong> - Load your own middleware</li>
+					</ul>
+				</div>
+			</div>
+		</div>
+	</content>
+</page>