kilatjs 0.1.4 → 0.1.6

package/README.md

@@ -321,6 +321,41 @@ export async function POST(ctx: RouteContext) {
     headers: { "Content-Type": "application/json" },
   });
 }
+
+/**
+ * NEW: Standalone API Mode with Swagger Documentation
+ * KilatJS provides a dedicated core for building pure APIs.
+ */
+
+// example/server.ts
+import KilatJS, { swagger, RouteContext } from "kilatjs/core";
+
+const app = new KilatJS();
+
+// Register Swagger documentation
+app.use(
+  swagger(app, {
+    path: "/docs",
+    title: "KilatJS API",
+    description: "Automatic API documentation",
+  })
+);
+
+// Route with metadata for Swagger
+app.post(
+  "/api/echo",
+  {
+    summary: "Echo request",
+    body: { text: "string" }, // Optional: for documentation
+    response: { echo: {}, receivedAt: "string" }, // Optional: for documentation
+  },
+  async (ctx: RouteContext) => {
+    const body = await ctx.request.json();
+    return { echo: body, receivedAt: new Date() };
+  }
+);
+
+app.listen(4000);
 ```
 
 ### Step 5: Create Contact Form with PRG Pattern
@@ -614,6 +649,46 @@ KilatJS uniquely allows you to mix **HTML-First SSR** with **Full React CSR**:
 
 ---
 
+## ⚡ Standalone API & Documentation
+
+KilatJS provides a dedicated core for building pure JSON APIs with automatic documentation.
+
+### Features
+
+1. **Automatic Swagger Documentation**: Use the `swagger` middleware to generate interactive documentation.
+2. **Typed Routes**: Use `RouteOptions` to provide metadata, request bodies, and response structures.
+3. **Core API**: Use the lightweight `KilatJS` core for JSON-first services.
+
+### Example
+
+```ts
+import KilatJS, { swagger, RouteContext } from "kilatjs/core";
+
+const app = new KilatJS();
+
+app.use(
+  swagger(app, {
+    path: "/docs",
+    title: "My API Documentation",
+  })
+);
+
+app.get(
+  "/api/users",
+  {
+    summary: "List users",
+    response: { users: [] },
+  },
+  (ctx) => {
+    return { users: ["Alice", "Bob"] };
+  }
+);
+
+app.listen(4000);
+```
+
+---
+
 ## 📝 License
 
 MIT

package/dist/cli.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env bun
-// @bun
 var __create = Object.create;
 var __getProtoOf = Object.getPrototypeOf;
 var __defProp = Object.defineProperty;
@@ -34,7 +33,7 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
   throw Error('Dynamic require of "' + x + '" is not supported');
 });
 
-// src/server/live-reload.ts
+// server/live-reload.ts
 var exports_live_reload = {};
 __export(exports_live_reload, {
   watchDirectory: () => watchDirectory,
@@ -186,7 +185,7 @@ var init_live_reload = __esm(() => {
   clients = new Set;
 });
 
-// src/adapters/react.ts
+// adapters/react.ts
 import { renderToStaticMarkup } from "react-dom/server";
 import React from "react";
 
@@ -282,7 +281,7 @@ var init_react = __esm(() => {
   init_live_reload();
 });
 
-// src/adapters/htmx.ts
+// adapters/htmx.ts
 class HTMXAdapter {
   static async renderToString(template, props) {
     try {
@@ -438,7 +437,7 @@ var init_htmx = __esm(() => {
   init_live_reload();
 });
 
-// src/core/router.ts
+// core/router.ts
 var Router;
 var init_router = __esm(() => {
   init_react();
@@ -452,6 +451,7 @@ var init_router = __esm(() => {
     preloadedRoutes = new Map;
     routePatterns = [];
     apiRoutes = new Map;
+    standaloneMiddleware = null;
     static NOT_FOUND_RESPONSE = new Response("404 Not Found", { status: 404 });
     static METHOD_NOT_ALLOWED_RESPONSE = new Response(JSON.stringify({ error: "Method Not Allowed" }), { status: 405, headers: { "Content-Type": "application/json" } });
     static INTERNAL_ERROR_RESPONSE = new Response(JSON.stringify({ error: "Internal Server Error" }), { status: 500, headers: { "Content-Type": "application/json" } });
@@ -477,11 +477,40 @@ var init_router = __esm(() => {
       this.routePatterns.length = 0;
       this.apiRoutes.clear();
       this.staticHtmlFiles.clear();
+      this.standaloneMiddleware = null;
+      await this.loadMiddlewareFile();
       await this.preloadAllRoutes(silent);
       if (!silent) {
         console.log("\uD83D\uDD04 FileSystemRouter initialized with", this.preloadedRoutes.size, "routes");
       }
     }
+    async loadMiddlewareFile() {
+      const filenames = ["middleware.ts", "middleware.js"];
+      const possibleDirs = [
+        this.config.appDir,
+        process.cwd()
+      ];
+      for (const dir of possibleDirs) {
+        for (const filename of filenames) {
+          let filePath = `${dir}/${filename}`.replace("//", "/");
+          if (!filePath.startsWith("/")) {
+            filePath = `${process.cwd()}/${filePath}`;
+          }
+          const file = Bun.file(filePath);
+          if (await file.exists()) {
+            try {
+              const module = await import(filePath);
+              if (module.middleware) {
+                this.standaloneMiddleware = module;
+                return;
+              }
+            } catch (e) {
+              console.warn(`Failed to load middleware from ${filePath}:`, e);
+            }
+          }
+        }
+      }
+    }
     async preloadAllRoutes(silent = false) {
       await this.scanAndPreloadRoutes(this.config.routesDir, "", silent);
     }
@@ -600,11 +629,65 @@ var init_router = __esm(() => {
       this.routeCache.set(path, match);
       return match;
     }
+    async executeMiddlewares(middlewares, context, handler) {
+      let index = -1;
+      const next = async () => {
+        index++;
+        if (index < middlewares.length) {
+          try {
+            return await middlewares[index](context, next);
+          } catch (error) {
+            console.error("Middleware Error:", error);
+            return Router.INTERNAL_ERROR_RESPONSE;
+          }
+        }
+        return await handler();
+      };
+      return await next();
+    }
+    shouldRunStandaloneMiddleware(path) {
+      if (!this.standaloneMiddleware || !this.standaloneMiddleware.middleware)
+        return false;
+      const config = this.standaloneMiddleware.config;
+      if (!config || !config.matcher)
+        return true;
+      const matchers = Array.isArray(config.matcher) ? config.matcher : [config.matcher];
+      for (const matcher of matchers) {
+        if (matcher === path)
+          return true;
+        if (matcher.endsWith("*")) {
+          const prefix = matcher.slice(0, -1);
+          if (path.startsWith(prefix))
+            return true;
+        }
+        if (matcher.includes(":")) {
+          const pattern = matcher.replace(/:[^\/]+/g, "[^/]+");
+          const regex = new RegExp(`^${pattern}$`);
+          if (regex.test(path))
+            return true;
+        }
+      }
+      return false;
+    }
     async handleRequest(request) {
       const url = request.url;
       const pathStart = url.indexOf("/", 8);
       const pathEnd = url.indexOf("?", pathStart);
       const path = pathEnd === -1 ? url.slice(pathStart) : url.slice(pathStart, pathEnd);
+      if (this.shouldRunStandaloneMiddleware(path)) {
+        const context = {
+          request,
+          params: {},
+          query: new URLSearchParams(url.split("?")[1] || ""),
+          state: {}
+        };
+        return await this.standaloneMiddleware.middleware(context, async () => {
+          return await this.internalDispatch(request, path, url);
+        });
+      }
+      return await this.internalDispatch(request, path, url);
+    }
+    async internalDispatch(request, path, url) {
       if (path.startsWith("/api/")) {
         return this.handleApiRouteFast(request, path);
       }
@@ -658,44 +741,57 @@ var init_router = __esm(() => {
       }
       const { params, exports, routeType } = match;
       const context = this.getContextFromPool(request, params, url);
-      if (request.method !== "GET" && request.method !== "HEAD") {
-        const actionHandler = exports[request.method];
-        if (actionHandler && typeof actionHandler === "function") {
-          try {
-            const result = await actionHandler(context);
-            this.returnContextToPool(context);
-            return result;
-          } catch (error) {
-            this.returnContextToPool(context);
-            console.error(`Error handling ${request.method}:`, error);
-            return Router.INTERNAL_ERROR_RESPONSE;
+      const middlewares = [
+        ...this.config.middlewares || [],
+        ...exports.middlewares || []
+      ];
+      const handler = async () => {
+        if (request.method !== "GET" && request.method !== "HEAD") {
+          const actionHandler = exports[request.method];
+          if (actionHandler && typeof actionHandler === "function") {
+            try {
+              return await actionHandler(context);
+            } catch (error) {
+              console.error(`Error handling ${request.method}:`, error);
+              return Router.INTERNAL_ERROR_RESPONSE;
+            }
           }
+          return Router.METHOD_NOT_ALLOWED_RESPONSE;
         }
-        this.returnContextToPool(context);
-        return Router.METHOD_NOT_ALLOWED_RESPONSE;
-      }
+        try {
+          const data = exports.load ? await exports.load(context) : {};
+          if (data instanceof Response) {
+            return data;
+          }
+          const meta = exports.meta || {};
+          const html = await this.renderPage(exports.default, { data, params, state: context.state }, exports.ui, meta, { clientScript: exports.clientScript });
+          const cacheControl = routeType === "dynamic" ? "no-cache" : "public, max-age=3600";
+          return new Response(html, {
+            headers: {
+              "Content-Type": "text/html; charset=utf-8",
+              "Cache-Control": cacheControl
+            }
+          });
+        } catch (error) {
+          if (error instanceof Response)
+            return error;
+          console.error("Error rendering page:", error);
+          return Router.INTERNAL_ERROR_RESPONSE;
+        }
+      };
       try {
-        const data = exports.load ? await exports.load(context) : {};
-        if (data instanceof Response) {
+        if (middlewares.length > 0) {
+          const response = await this.executeMiddlewares(middlewares, context, handler);
+          this.returnContextToPool(context);
+          return response;
+        } else {
+          const response = await handler();
           this.returnContextToPool(context);
-          return data;
+          return response;
         }
-        const meta = exports.meta || {};
-        const html = await this.renderPage(exports.default, { data, params, state: context.state }, exports.ui, meta, { clientScript: exports.clientScript });
-        const cacheControl = routeType === "dynamic" ? "no-cache" : "public, max-age=3600";
-        this.returnContextToPool(context);
-        return new Response(html, {
-          headers: {
-            "Content-Type": "text/html; charset=utf-8",
-            "Cache-Control": cacheControl
-          }
-        });
       } catch (error) {
         this.returnContextToPool(context);
-        if (error instanceof Response)
-          return error;
-        console.error("Error rendering page:", error);
-        return Router.INTERNAL_ERROR_RESPONSE;
+        throw error;
       }
     }
     async handleApiRouteFast(request, path) {
@@ -723,21 +819,32 @@ var init_router = __esm(() => {
       }
       if (!exports)
         return Router.NOT_FOUND_RESPONSE;
-      const handler = exports[request.method] || exports.default;
-      if (!handler || typeof handler !== "function") {
-        return Router.METHOD_NOT_ALLOWED_RESPONSE;
-      }
-      try {
-        const context = this.getMinimalApiContext(request, params);
-        const response = await handler(context);
-        if (response instanceof Response)
-          return response;
-        return new Response(JSON.stringify(response), {
-          headers: { "Content-Type": "application/json" }
-        });
-      } catch (error) {
-        console.error(`API Error [${request.method} ${path}]:`, error);
-        return Router.INTERNAL_ERROR_RESPONSE;
+      const context = this.getMinimalApiContext(request, params);
+      const middlewares = [
+        ...this.config.middlewares || [],
+        ...exports.middlewares || []
+      ];
+      const handler = async () => {
+        const apiHandler = exports[request.method] || exports.default;
+        if (!apiHandler || typeof apiHandler !== "function") {
+          return Router.METHOD_NOT_ALLOWED_RESPONSE;
+        }
+        try {
+          const response = await apiHandler(context);
+          if (response instanceof Response)
+            return response;
+          return new Response(JSON.stringify(response), {
+            headers: { "Content-Type": "application/json" }
+          });
+        } catch (error) {
+          console.error(`API Error [${request.method} ${path}]:`, error);
+          return Router.INTERNAL_ERROR_RESPONSE;
+        }
+      };
+      if (middlewares.length > 0) {
+        return await this.executeMiddlewares(middlewares, context, handler);
+      } else {
+        return await handler();
       }
     }
     getContextFromPool(request, params, url) {
@@ -805,7 +912,6 @@ var init_router = __esm(() => {
     }
   };
 });
-
 // node:path
 function assertPath(path) {
   if (typeof path !== "string")
@@ -1127,7 +1233,7 @@ var init_path = __esm(() => {
   posix = ((p) => (p.posix = p, p))({ resolve, normalize, isAbsolute, join, relative, _makeLong, dirname, basename, extname, format, parse, sep, delimiter, win32: null, posix: null });
 });
 
-// src/server/server.ts
+// server/server.ts
 class KilatServer {
   router;
   config;
@@ -1138,7 +1244,7 @@ class KilatServer {
     const { appDir, routesDir } = this.resolvePaths(config);
     this.appDir = appDir;
     this.routesDir = routesDir;
-    this.router = new Router({ ...config, routesDir: this.routesDir });
+    this.router = new Router({ ...config, appDir: this.appDir, routesDir: this.routesDir });
   }
   resolvePaths(config) {
     const cwd = process.cwd();
@@ -1274,6 +1380,12 @@ class KilatServer {
           notifyReload(filename);
         });
       }
+      watchDirectory(this.appDir, async (filename) => {
+        if (filename === "middleware.ts" || filename === "middleware.js" || filename === "kilat.config.ts") {
+          await router.loadRoutes(true);
+          notifyReload(filename);
+        }
+      });
     } else {
       console.log(`
 \uD83D\uDE80 KilatJS Production Server
@@ -1634,7 +1746,8 @@ var init_server = __esm(() => {
   init_path();
   init_live_reload();
 });
-// src/index.ts
+
+// index.ts
 var exports_src = {};
 __export(exports_src, {
   stopLiveReload: () => stopLiveReload,
@@ -2026,7 +2139,7 @@ var init_src = __esm(() => {
   src_default = Kilat;
 });
 
-// src/cli.ts
+// cli.ts
 var args = process.argv.slice(2);
 var command = args[0];
 var isHotMode = process.env.__KILAT_HOT === "1";

package/dist/core/index.d.ts

@@ -0,0 +1,5 @@
+export { default as KilatJS, default } from "./kilat";
+export * from "../middleware/cors";
+export * from "../middleware/jwt";
+export * from "../middleware/swagger";
+export * from "./types";