refactor(router): reorganize Router class into separate index file and remove legacy router.js

1 files changed, 127 insertions, 0 deletions

diff --git a/source/library/router/index.md b/source/library/router/index.md
new file mode 100644
index 0000000..65e01ce
--- /dev/null
+++ b/source/library/router/index.md
@@ -0,0 +1,127 @@
+# Router Class Documentation
+
+The `Router` class is designed to handle routing of HTTP requests based on the request path. It allows you to define routes with dynamic parameters and associate them with handler functions.
+
+## Constructor
+
+### `new Router(request, environment, context)`
+
+Creates a new instance of the `Router` class.
+
+- **Parameters:**
+
+  - `request` (Request): The incoming request object.
+  - `environment` (Environment): The environment object.
+  - `context` (Context): The context object.
+
+- **Returns:** A new `Router` instance.
+
+---
+
+## Methods
+
+### `add(path, handler)`
+
+Adds a new route to the router.
+
+- **Parameters:**
+
+  - `path` (string): The path to match. Dynamic segments can be defined using `:paramName`.
+  - `handler` (function): The handler function to call if the path matches. The handler receives `request`, `environment`, and `context` as arguments.
+
+- **Returns:** The `Router` instance for chaining.
+
+- **Example:**
+  ```javascript
+  router.add("/users/:id", (request, environment, context) => {
+    const userId = router.parameters.id;
+    return new Response(`User ID: ${userId}`);
+  });
+  ```
+
+---
+
+### `respond(body, status = 200)`
+
+Helper function to create a JSON response.
+
+- **Parameters:**
+
+  - `body` (object): The JSON object to respond with.
+  - `status` (number, optional): The HTTP status code. Defaults to `200`.
+
+- **Returns:** A `Response` object.
+
+- **Example:**
+  ```javascript
+  return router.respond({ message: "Success" }, 200);
+  ```
+
+---
+
+### `route()`
+
+Routes the incoming request to the appropriate handler based on the request path.
+
+- **Returns:** A `Response` object.
+
+- **Behavior:**
+
+  - Matches the request path against the registered routes.
+  - Extracts dynamic parameters from the path and stores them in `router.parameters`.
+  - Calls the corresponding handler function.
+  - Returns a `404` response if no route matches.
+  - Returns a `500` response in case of unexpected errors.
+
+- **Example:**
+  ```javascript
+  const response = router.route();
+  ```
+
+---
+
+## Example Usage
+
+```javascript
+import Router from "./router.js";
+
+const router = new Router(request, environment, context);
+
+router
+  .add("/hello", () => {
+    return new Response("Hello, world!");
+  })
+  .add("/users/:id", (request, environment, context) => {
+    const userId = router.parameters.id;
+    return new Response(`User ID: ${userId}`);
+  });
+
+const response = router.route();
+```
+
+---
+
+## Error Handling
+
+- **404 Not Found:** If no route matches the request path, the `Router` responds with:
+
+  ```json
+  {
+    "error": "Route not found: /path"
+  }
+  ```
+
+- **500 Internal Server Error:** If an unexpected error occurs, the `Router` responds with:
+  ```json
+  {
+    "error": "Internal Server Error: error message"
+  }
+  ```
+
+---
+
+## Notes
+
+- Paths are normalized by removing trailing slashes.
+- Dynamic parameters in paths (e.g., `:id`) are extracted and stored in the `parameters` property of the `Router` instance.
+- The `add` method uses regular expressions to match paths efficiently.