owebjs 1.3.0 → 1.3.2

package/README.md

@@ -1,13 +1,270 @@
 # Oweb
 
-Flexible handler that built on top of Fastify
+A flexible and modern web framework built on top of Fastify, designed for creating scalable and maintainable web applications with file-based routing and hot module replacement.
+
+<p align="center">
+  <img src="https://img.shields.io/npm/v/owebjs" alt="npm version">
+  <img src="https://img.shields.io/npm/l/owebjs" alt="license">
+  <img src="https://img.shields.io/npm/dt/owebjs" alt="downloads">
+</p>
+
+## Features
+
+- **File-based Routing**: Automatically generate routes based on your file structure
+- **Hot Module Replacement (HMR)**: Update your routes without restarting the server
+- **Middleware Support**: Use hooks to add middleware functionality
+- **Error Handling**: Global and route-specific error handling
+- **TypeScript Support**: Built with TypeScript for better developer experience
+- **Plugin System**: Extend functionality with plugins
+- **uWebSockets.js Support**: Optional high-performance WebSocket server
 
 ## Installation
 
+```bash
+npm install owebjs
+```
+
+## Quick Start
+
+```javascript
+import Oweb from 'owebjs';
+
+// Create and setup the app
+const app = await new Oweb().setup();
+
+// Load routes from a directory
+await app.loadRoutes({
+    directory: 'routes',
+    hmr: {
+        enabled: true, // Enable hot module replacement
+    },
+});
+
+// Start the server
+await app.start({ port: 3000 });
+console.log('Server running at http://localhost:3000');
+```
+
+## Creating Routes
+
+Routes are automatically generated based on your file structure. Create a file in your routes directory:
+
+```javascript
+// routes/hello.js
+import { Route } from 'owebjs';
+
+export default class extends Route {
+    async handle(req, res) {
+        res.send({ message: 'Hello, World!' });
+    }
+}
+```
+
+This will create a GET route at `/hello`.
+
+### Dynamic Routes
+
+Use brackets to create dynamic route parameters:
+
+```javascript
+// routes/users/[id].js
+import { Route } from 'owebjs';
+
+export default class extends Route {
+    async handle(req, res) {
+        res.send({ userId: req.params.id });
+    }
+}
+```
+
+This will create a GET route at `/users/:id`.
+
+### Parameter Validation with Matchers
+
+Use matchers to validate dynamic route parameters:
+
+```javascript
+// routes/users/[id=integer].js
+import { Route } from 'owebjs';
+
+export default class extends Route {
+    async handle(req, res) {
+        res.send({ userId: req.params.id });
+    }
+}
+```
+
+```javascript
+// matchers/integer.js
+export default function (val) {
+    return !isNaN(val);
+}
 ```
-npm i owebjs
+
+Then configure Oweb to use your matchers directory:
+
+```javascript
+await app.loadRoutes({
+    directory: 'routes',
+    matchersDirectory: 'matchers', // Directory containing custom matchers
+    hmr: {
+        enabled: true,
+        matchersDirectory: 'matchers', // Optional: Enable HMR for matchers
+    },
+});
+```
+
+Now you can use your custom matchers in route filenames with the syntax `[paramName=matcherName]`.
+
+### HTTP Methods
+
+Specify the HTTP method in the filename:
+
+```javascript
+// routes/api/users.post.js
+import { Route } from 'owebjs';
+
+export default class extends Route {
+    async handle(req, res) {
+        // Create a new user
+        const user = req.body;
+        res.status(201).send({ id: 1, ...user });
+    }
+}
 ```
 
-## Usage
+## Middleware (Hooks)
 
-This package is still WIP. However, if you want to check out the usage head over to [test directory](https://github.com/owebjs/oweb/tree/main/test)
+Create hooks to add middleware functionality:
+
+```javascript
+// routes/_hooks.js
+import { Hook } from 'owebjs';
+
+export default class extends Hook {
+    handle(req, res, done) {
+        console.log(`${req.method} ${req.url}`);
+        done(); // Continue to the next hook or route handler
+    }
+}
+```
+
+Hooks are applied to all routes in the current directory and its subdirectories.
+
+## Error Handling
+
+### Global Error Handler
+
+```javascript
+app.setInternalErrorHandler((req, res, error) => {
+    console.error(error);
+    res.status(500).send({
+        error: 'Internal Server Error',
+        message: error.message,
+    });
+});
+```
+
+### Route-specific Error Handler
+
+```javascript
+import { Route } from 'owebjs';
+
+export default class extends Route {
+    async handle(req, res) {
+        throw new Error('Something went wrong');
+    }
+
+    handleError(req, res, error) {
+        res.status(500).send({
+            error: 'Route Error',
+            message: error.message,
+        });
+    }
+}
+```
+
+## Plugins
+
+Oweb supports Fastify plugins and comes with some built-in plugins:
+
+### Using Fastify Plugins
+
+```javascript
+import Oweb from 'owebjs';
+import fastifyMultipart from '@fastify/multipart';
+
+const app = await new Oweb().setup();
+
+// Register Fastify plugin
+await app.register(fastifyMultipart, {
+    limits: {
+        fileSize: 10 * 1024 * 1024, // 10MB
+    },
+});
+```
+
+### Using Built-in Plugins
+
+```javascript
+import { Route } from 'owebjs';
+import { ChunkUpload } from 'owebjs/dist/plugins';
+
+export default class extends Route {
+    async handle(req, res) {
+        const file = await req.file();
+        const buffer = await file.toBuffer();
+
+        await ChunkUpload(
+            {
+                buffer,
+                fileName: file.filename,
+                currentChunk: +req.query.currentChunk,
+                totalChunks: +req.query.totalChunks,
+            },
+            {
+                path: './uploads',
+                maxChunkSize: 5 * 1024 * 1024, // 5MB
+            },
+        );
+
+        return res.status(204).send();
+    }
+}
+```
+
+## Advanced Configuration
+
+### uWebSockets.js Support
+
+```javascript
+const app = await new Oweb({ uWebSocketsEnabled: true }).setup();
+```
+
+### Custom Route Options
+
+```javascript
+import { Route } from 'owebjs';
+
+export default class extends Route {
+    constructor() {
+        super({
+            schema: {
+                body: {
+                    type: 'object',
+                    required: ['username', 'password'],
+                    properties: {
+                        username: { type: 'string' },
+                        password: { type: 'string' },
+                    },
+                },
+            },
+        });
+    }
+
+    async handle(req, res) {
+        // Body is validated according to the schema
+        res.send({ success: true });
+    }
+}
+```

package/dist/index.d.ts

@@ -24,11 +24,13 @@ interface OwebOptions extends FastifyServerOptions {
 }
 interface LoadRoutesOptions {
     directory: string;
+    matchersDirectory?: string;
     hmr?: {
         /**
          * The directory to watch for changes. If not specified, it will use the routes directory.
          */
         directory?: string;
+        matchersDirectory?: string;
         enabled: boolean;
     };
 }
@@ -39,6 +41,7 @@ declare class _FastifyInstance {
 declare class Oweb extends _FastifyInstance {
     _options: OwebOptions;
     private hmrDirectory;
+    private hmrMatchersDirectory;
     routes: Map<string, any>;
     constructor(options?: OwebOptions);
     /**
@@ -49,11 +52,13 @@ declare class Oweb extends _FastifyInstance {
     /**
      * Loads routes from a directory.
      * @param options.directory The directory to load routes from.
+     * @param options.matchersDirectory The directory to load matchers from.
      * @param options.hmr Configuration for Hot Module Replacement.
      * @param options.hmr.enabled Whether to enable HMR. HMR is disabled if NODE_ENV is set to production.
-     * @param options.hmr.directory The directory to watch for changes. If not specified, it will use the routes directory.
+     * @param options.hmr.directory The directory to watch for route changes. If not specified, it will use the routes directory.
+     * @param options.hmr.matchersDirectory The directory to watch for matcher changes. If not specified, it will use the matchers directory.
      */
-    loadRoutes({ directory, hmr }: LoadRoutesOptions): Promise<void>;
+    loadRoutes({ directory, matchersDirectory, hmr }: LoadRoutesOptions): Promise<void>;
     /**
      *
      * Watches for changes in the routes directory

package/dist/structures/Oweb.js

@@ -2,8 +2,8 @@ import {
   __name
 } from "../chunk-SHUYVCID.js";
 import Fastify from "fastify";
-import { applyHMR, assignRoutes } from '../utils/assignRoutes.js';
-import { watchRoutes } from '../utils/watchRoutes.js';
+import { applyMatcherHMR, applyRouteHMR, assignRoutes } from '../utils/assignRoutes.js';
+import { watchDirectory } from '../utils/watcher.js';
 import { info, success, warn } from '../utils/logger.js';
 let _FastifyInstance = class _FastifyInstance2 {
   static {
@@ -16,6 +16,7 @@ class Oweb extends _FastifyInstance {
   }
   _options = {};
   hmrDirectory;
+  hmrMatchersDirectory;
   routes = /* @__PURE__ */ new Map();
   constructor(options) {
     super();
@@ -60,28 +61,37 @@ class Oweb extends _FastifyInstance {
   /**
    * Loads routes from a directory.
    * @param options.directory The directory to load routes from.
+   * @param options.matchersDirectory The directory to load matchers from.
    * @param options.hmr Configuration for Hot Module Replacement.
    * @param options.hmr.enabled Whether to enable HMR. HMR is disabled if NODE_ENV is set to production.
-   * @param options.hmr.directory The directory to watch for changes. If not specified, it will use the routes directory.
+   * @param options.hmr.directory The directory to watch for route changes. If not specified, it will use the routes directory.
+   * @param options.hmr.matchersDirectory The directory to watch for matcher changes. If not specified, it will use the matchers directory.
    */
-  loadRoutes({ directory, hmr }) {
+  loadRoutes({ directory, matchersDirectory, hmr }) {
     if (hmr && !hmr.directory) hmr.directory = directory;
+    if (hmr && !hmr.matchersDirectory) hmr.matchersDirectory = matchersDirectory;
     if (hmr?.enabled) {
       this.hmrDirectory = hmr.directory;
+      this.hmrMatchersDirectory = hmr.matchersDirectory;
       success(`Hot Module Replacement enabled. Watching changes in ${hmr.directory}`, "HMR");
     } else {
       warn('Hot Module Replacement is disabled. Use "await app.loadRoutes({ hmr: { enabled: true, directory: path } })" to enable it.', "HMR");
     }
-    return assignRoutes(this, directory);
+    return assignRoutes(this, directory, matchersDirectory);
   }
   /**
    *
    * Watches for changes in the routes directory
    */
   watch() {
-    return watchRoutes(this.hmrDirectory, (op, path, content) => {
-      applyHMR(this, op, this.hmrDirectory, path, content);
+    watchDirectory(this.hmrDirectory, true, (op, path, content) => {
+      applyRouteHMR(this, op, this.hmrDirectory, path, content);
     });
+    if (this.hmrMatchersDirectory) {
+      watchDirectory(this.hmrMatchersDirectory, true, (op, path, content) => {
+        applyMatcherHMR(this, op, this.hmrMatchersDirectory, path, content);
+      });
+    }
   }
   /**
    *

package/dist/utils/assignRoutes.js

@@ -9,7 +9,9 @@ import { walk } from './walk.js';
 import { success, warn } from './logger.js';
 import { match } from "path-to-regexp";
 import generateFunctionFromTypescript from './generateFunctionFromTypescript.js';
+import { readdirSync } from "node:fs";
 const __dirname = dirname(fileURLToPath(import.meta.url));
+let matcherOverrides = {};
 let routeFunctions = {};
 const temporaryRequests = {
   get: {},
@@ -21,7 +23,41 @@ const temporaryRequests = {
 };
 let routesCache = [];
 const compiledRoutes = {};
-const applyHMR = /* @__PURE__ */ __name(async (oweb, op, workingDir, path2, content) => {
+function removeExtension(filePath) {
+  const lastDotIndex = filePath.lastIndexOf(".");
+  if (lastDotIndex !== -1) {
+    return filePath.substring(0, lastDotIndex);
+  }
+  return filePath;
+}
+__name(removeExtension, "removeExtension");
+const applyMatcherHMR = /* @__PURE__ */ __name(async (oweb, op, workingDir, filePath, content) => {
+  let def;
+  const fileName = path.basename(filePath);
+  if (op === "delete-file") {
+    delete matcherOverrides[removeExtension(fileName)];
+    success(`Matcher ${filePath} removed in 0ms`, "HMR");
+    return;
+  }
+  if (filePath.endsWith(".ts")) {
+    const start = Date.now();
+    def = content.length ? await generateFunctionFromTypescript(content, filePath) : void 0;
+    const end = Date.now() - start;
+    success(`Matcher ${filePath} compiled and reloaded in ${end}ms`, "HMR");
+  } else {
+    const start = Date.now();
+    const newFilePath = filePath.replaceAll("\\", "/");
+    const packageURL = new URL(path.resolve(newFilePath), `file://${__dirname}`).pathname.replaceAll("\\", "/");
+    const cacheBuster = `?t=${Date.now()}`;
+    def = (await import(packageURL + cacheBuster)).default;
+    const end = Date.now() - start;
+    success(`Matcher ${filePath} reloaded in ${end}ms`, "HMR");
+  }
+  if (def) {
+    matcherOverrides[removeExtension(fileName)] = def;
+  }
+}, "applyMatcherHMR");
+const applyRouteHMR = /* @__PURE__ */ __name(async (oweb, op, workingDir, path2, content) => {
   if (path2.endsWith("hooks.js") || path2.endsWith("hooks.ts")) {
     warn(`Hot Module Replacement is not supported for hooks. Restart the server for changes to take effect.`, "HMR");
     return;
@@ -65,7 +101,7 @@ const applyHMR = /* @__PURE__ */ __name(async (oweb, op, workingDir, path2, cont
     const end = Date.now() - start;
     success(`Route ${f.method.toUpperCase()}:${f.url} removed in ${end}ms`, "HMR");
   }
-}, "applyHMR");
+}, "applyRouteHMR");
 const generateRoutes = /* @__PURE__ */ __name(async (files) => {
   const routes = [];
   for (const file of files) {
@@ -78,6 +114,7 @@ const generateRoutes = /* @__PURE__ */ __name(async (files) => {
       routes.push({
         url: route.url,
         method: route.method,
+        matchers: route.matchers,
         fn: compiledRoutes[file.filePath],
         fileInfo: file
       });
@@ -89,6 +126,7 @@ const generateRoutes = /* @__PURE__ */ __name(async (files) => {
     routes.push({
       url: route.url,
       method: route.method,
+      matchers: route.matchers,
       fn: routeFuncs,
       fileInfo: file
     });
@@ -100,7 +138,18 @@ function inner(oweb, route) {
     return;
   }
   const routeFunc = new route.fn();
+  const matchers = route.matchers;
   return function(req, res) {
+    const checkMatchers = /* @__PURE__ */ __name(() => {
+      for (const matcher of matchers) {
+        const param = req.params[matcher.paramName];
+        const fun = matcherOverrides[matcher.matcherName];
+        if (fun) {
+          return fun(param);
+        }
+      }
+      return true;
+    }, "checkMatchers");
     const handle = /* @__PURE__ */ __name(() => {
       if (routeFunc.handle.constructor.name == "AsyncFunction") {
         routeFunc.handle(req, res).catch((error) => {
@@ -127,16 +176,32 @@ function inner(oweb, route) {
         const hookFun = route.fileInfo.hooks[index];
         hookFun.prototype.handle(req, res, () => {
           if (index + 1 == route.fileInfo.hooks.length) {
-            handle();
+            if (!checkMatchers()) {
+              send404(req, res);
+            } else {
+              handle();
+            }
           }
         });
       }
     } else {
-      handle();
+      if (!checkMatchers()) {
+        send404(req, res);
+      } else {
+        handle();
+      }
     }
   };
 }
 __name(inner, "inner");
+function send404(req, res) {
+  return res.status(404).send({
+    message: `Route ${req.method}:${req.url} not found`,
+    error: "Not Found",
+    statusCode: 404
+  });
+}
+__name(send404, "send404");
 function assignSpecificRoute(oweb, route) {
   if (!route.fn) return;
   const routeFunc = new route.fn();
@@ -145,16 +210,39 @@ function assignSpecificRoute(oweb, route) {
     if (routeFunctions[route.fileInfo.filePath]) {
       return routeFunctions[route.fileInfo.filePath](req, res);
     } else {
-      return res.status(404).send({
-        message: `Route ${req.method}:${req.url} not found`,
-        error: "Not Found",
-        statusCode: 404
+      const vals = temporaryRequests[req.method.toLowerCase()];
+      const keys = Object.keys(vals);
+      if (!vals || !keys.length) {
+        return send404(req, res);
+      }
+      const f = keys.find((tempName) => {
+        const matcher = match(tempName);
+        return matcher(req.url);
       });
+      if (f && vals[f]) {
+        return vals[f](req, res);
+      } else {
+        return send404(req, res);
+      }
     }
   });
 }
 __name(assignSpecificRoute, "assignSpecificRoute");
-const assignRoutes = /* @__PURE__ */ __name(async (oweb, directory) => {
+async function loadMatchers(directoryPath) {
+  const files = readdirSync(directoryPath);
+  for (const file of files) {
+    const filePath = path.join(directoryPath, file).replaceAll("\\", "/");
+    const fileName = path.basename(filePath);
+    const packageURL = new URL(path.resolve(filePath), `file://${__dirname}`).pathname.replaceAll("\\", "/");
+    const def = await import(packageURL);
+    matcherOverrides[removeExtension(fileName)] = def.default;
+  }
+}
+__name(loadMatchers, "loadMatchers");
+const assignRoutes = /* @__PURE__ */ __name(async (oweb, directory, matchersDirectory) => {
+  if (matchersDirectory) {
+    loadMatchers(matchersDirectory);
+  }
   const files = await walk(directory);
   const routes = await generateRoutes(files);
   routesCache = routes;
@@ -162,11 +250,7 @@ const assignRoutes = /* @__PURE__ */ __name(async (oweb, directory) => {
     const vals = temporaryRequests[req.method.toLowerCase()];
     const keys = Object.keys(vals);
     if (!vals || !keys.length) {
-      return res.status(404).send({
-        message: `Route ${req.method}:${req.url} not found`,
-        error: "Not Found",
-        statusCode: 404
-      });
+      return send404(req, res);
     }
     const f = keys.find((tempName) => {
       const matcher = match(tempName);
@@ -175,11 +259,7 @@ const assignRoutes = /* @__PURE__ */ __name(async (oweb, directory) => {
     if (f && vals[f]) {
       return vals[f](req, res);
     } else {
-      return res.status(404).send({
-        message: `Route ${req.method}:${req.url} not found`,
-        error: "Not Found",
-        statusCode: 404
-      });
+      return send404(req, res);
     }
   });
   for (const route of routes) {
@@ -187,7 +267,8 @@ const assignRoutes = /* @__PURE__ */ __name(async (oweb, directory) => {
   }
 }, "assignRoutes");
 export {
-  applyHMR,
+  applyMatcherHMR,
+  applyRouteHMR,
   assignRoutes,
   generateRoutes
 };

package/dist/utils/utils.js

@@ -28,6 +28,18 @@ const buildRouteURL = /* @__PURE__ */ __name((path) => {
   let method = "get";
   const paramURL = convertParamSyntax(normalizedPath);
   let url = convertCatchallSyntax(paramURL);
+  const matcherSplit = url.split("/");
+  const matcherFilter = matcherSplit.filter((x) => x.startsWith(":"));
+  const matchers = matcherFilter.map((x) => {
+    const split = x.split("=");
+    return {
+      paramName: split[0].slice(1),
+      matcherName: split[1]
+    };
+  }).filter((x) => x.matcherName);
+  for (const matcher of matchers) {
+    url = url.replace(`:${matcher.paramName}=${matcher.matcherName}`, `:${matcher.paramName}`);
+  }
   for (const m of [
     ".DELETE",
     ".POST",
@@ -43,7 +55,8 @@ const buildRouteURL = /* @__PURE__ */ __name((path) => {
   }
   return {
     url,
-    method
+    method,
+    matchers
   };
 }, "buildRouteURL");
 export {

package/dist/utils/{watchRoutes.js → watcher.js}

@@ -3,11 +3,11 @@ import {
 } from "../chunk-SHUYVCID.js";
 import chokidar from "chokidar";
 import { readFileSync } from "fs";
-function watchRoutes(dir, onUpdate) {
+function watchDirectory(dir, ignoreInitial = true, onUpdate) {
   const watcher = chokidar.watch(dir, {
     ignored: /([/\\]\.)|(node_modules)|(dist)/,
     persistent: true,
-    ignoreInitial: true,
+    ignoreInitial,
     awaitWriteFinish: {
       stabilityThreshold: 150,
       pollInterval: 50
@@ -25,7 +25,7 @@ function watchRoutes(dir, onUpdate) {
     onUpdate("delete-file", filePath, "");
   });
 }
-__name(watchRoutes, "watchRoutes");
+__name(watchDirectory, "watchDirectory");
 export {
-  watchRoutes
+  watchDirectory
 };

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "owebjs",
-    "version": "1.3.0",
-    "description": "Flexible handler that built on top of Fastify",
+    "version": "1.3.2",
+    "description": "A flexible and modern web framework built on top of Fastify",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
     "exports": {