Merge pull request #176 from sejori/router-rework

Router rework

.github/workflows/deno.yml

@@ -26,8 +26,7 @@ jobs:
  uses: actions/checkout@v3
 
  - name: Setup Deno
- # uses: denoland/setup-deno@v1
- uses: denoland/setup-deno@004814556e37c54a2f6e31384c9e18e983317366
+ uses: denoland/setup-deno@v1
  with:
  deno-version: v1.x
 
@@ -41,5 +40,5 @@ jobs:
  - name: Run tests
  run: deno task test
 
- - name: Run profile
- run: deno task profile
+ # - name: Run profile
+ # run: deno task profile

README.md

@@ -9,28 +9,28 @@
 <p align="center">
  <span>
   &nbsp;
-  <a href="https://github.com/sebringrose/peko/blob/main/overview.md#server">
-  Server
+  <a href="#Types">
+  Types
   </a>
   &nbsp;
  </span>
  <span>
   &nbsp;
-  <a href="https://github.com/sebringrose/peko/blob/main/overview.md#routing">
+  <a href="#routing">
   Routing
   </a>
   &nbsp;
  </span>
  <span>
   &nbsp;
-  <a href="https://github.com/sebringrose/peko/blob/main/overview.md#request-handling">
+  <a href="#request-handling">
   Request handling
   </a>
   &nbsp;
  </span>
  <span>
   &nbsp;
-  <a href="https://github.com/sebringrose/peko/blob/main/overview.md#response-caching">
+  <a href="#response-caching">
   Response caching
   </a>
   &nbsp;
@@ -64,21 +64,98 @@
 
 - <strong>Community-driven</strong> - Popular tool integrations + contributions encouraged 
 
-<h2>Getting started</h2>
+<h1>Overview</h1>
+
+Routes and middleware are added to a `Router` instance with `.use`, `.addRoute` or `.get/post/put/delete`. 
+
+The router is then used with your web server of choice, e.g. `Deno.serve`!
 
 ```js
-import * as Peko from "https://deno.land/x/peko/mod.ts"; 
-// import from ".../peko/lib/Server.ts" for featherweight mode
+import * as Peko from "https://deno.land/x/peko/mod.ts";
+
+const router = new Peko.Router();
+
+router.use(Peko.logger(console.log));
 
-const server = new Peko.Server();
+router.get("/shorthand-route", () => new Response("Hello world!"));
 
-server.use(Peko.logger(console.log));
+router.post("/shorthand-route-ext", async (ctx, next) => { await next(); console.log(ctx.request.headers); }, (req) => new Response(req.body));
 
-server.get("/hello", () => new Response("Hello world!"));
+router.addRoute({
+ path: "/object-route",
+ middleware: async (ctx, next) => { await next(); console.log(ctx.request.headers); }, // can also be array of middleware
+ handler: () => new Response("Hello world!")
+})
 
-server.listen(7777, () => console.log("Peko server started - let's go!"));
+router.addRoutes([ /* array of route objects */ ])
+
+Deno.serve((req) => router.requestHandler(req))
 ```
 
+<h2 id="types">Types</h2>
+
+### [**Router**](https://deno.land/x/peko/mod.ts?s=Router)
+The main class of Peko, provides `requestHandler` method to generate `Response` from `Request` via configured routes and middleware. 
+
+### [**Route**](https://deno.land/x/peko/mod.ts?s=Route)
+Objects with `path`, `method`, `middleware`, and `handler` properties. Requests are matched to a regex generated from the given path. Dynamic parameters are supported in the `/users/:userid` syntax.
+
+### [**RequestContext**](https://deno.land/x/peko/mod.ts?s=RequestContext)
+An object containing `url`, `params` and `state` properties that is provided to all middleware and handler functions associated to a router or matched route. 
+
+### [**Middleware**](https://deno.land/x/peko/mod.ts?s=Middleware)
+Functions that receives a RequestContext and a next fcn. Should update `ctx.state`, perform side-effects or return a response.
+
+### [**Handler**](https://deno.land/x/peko/mod.ts?s=Handler)
+The final request handling function on a `Route`. Must generate and return a response using the provided request context.
+
+<h2 id="request-handling">Request handling</h2>
+
+Each route must have a <code>handler</code> function that generates a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response/Response). Upon receiving a request the `Server` will construct a [RequestContext](https://deno.land/x/peko/server.ts?s=RequestContext) and cascade it through any global middleware, then route middleware and finally the route handler. Global and route middleware are invoked in the order they are added. If a response is returned by any middleware along the chain no subsequent middleware/handler will run.
+
+Peko comes with a library of utilities, middleware and handlers for common route use-cases, such as:
+- server-side-rendering
+- opening WebSockets/server-sent events
+- JWT signing/verifying & authentication
+- logging
+- caching
+
+See `handlers`, `mmiddleware` or `utils` for source, or dive into `examples` for demo implementations. 
+
+The second argument to any middleware is the `next` fcn. This returns a promise that resolves to the first response returned by any subsequent middleware/handler. This is useful for error-handling as well as post-response operations such as editing headers or logging. See the below snippet or `middleware/logger.ts` for examples.
+
+If no matching route is found for a request an empty 404 response is sent. If an error occurs in handling a request an empty 500 response is sent. Both of these behaviours can be overwritten with the following middleware:
+
+```js
+router.use(async (_, next) => {
+ const response = await next();
+ if (!response) return new Response("Would you look at that? Nothing's here!", { status: 404 });
+});
+```
+
+```js
+router.use(async (_, next) => {
+ try {
+ await next();
+ } catch(e) {
+ console.log(e);
+ return new Response("Oh no! An error occured :(", { status: 500 });
+ }
+});
+```
+
+<h2 id="response-caching">Response caching</h2>
+
+In stateless computing, memory should only be used for source code and disposable cache data. Response caching ensures that we only store data that can be regenerated or refetched. Peko provides a `ResponseCache` utility for this with configurable item lifetime. The `cacher` middleware wraps it and provides drop in handler memoization and response caching for your routes.
+
+```js
+const cache = new Peko.ResponseCache({ lifetime: 5000 });
+
+router.addRoute("/do-stuff", Peko.cacher(cache), () => new Response(Date.now()));
+```
+
+And that's it! Check out the API docs for deeper info. Otherwise happy coding 🤓
+
 <h2>App showcase</h2>
 
 PR to add your project 🙌
@@ -122,5 +199,3 @@ The modern JavaScript edge rocks because the client-server gap practically disap
 This is made possible by engines such as Deno that are built to the [ECMAScript](https://tc39.es/) specification</a> (support for URL module imports is the secret sauce). UI libraries like [Preact](https://github.com/preactjs/preact) combined with [htm](https://github.com/developit/htm) offer lightning fast client-side hydration with a browser-friendly markup syntax. Deno also has native TypeScript support, a rich runtime API and loads of community tools for your back-end needs.
 
 If you are interested in contributing please submit a PR or get in contact ^^
-
-Read `overview.md` for a more detailed guide on using Peko.

examples/auth/app.ts

@@ -1,6 +1,7 @@
-import * as Peko from "https://deno.land/x/peko/mod.ts"
+import * as Peko from "../../mod.ts" // "https://deno.land/x/peko/mod.ts"
 
-const server = new Peko.Server()
+const html = String
+const router = new Peko.Router()
 const crypto = new Peko.Crypto("SUPER_SECRET_KEY_123") // <-- replace from env
 const user = { // <-- replace with db / auth provider query
  username: "test-user",
@@ -13,8 +14,8 @@ const validateUser = async (username: string, password: string) => {
  && await crypto.hash(password) === user.password 
 }
 
-server.use(Peko.logger(console.log))
-server.post("/login", async (ctx) => {
+router.use(Peko.logger(console.log))
+router.post("/login", async (ctx) => {
  const { username, password } = await ctx.request.json()
 
  if (!await validateUser(username, password)) {
@@ -37,14 +38,13 @@ server.post("/login", async (ctx) => {
  })
 })
 
-server.get(
+router.get(
  "/verify", 
  Peko.authenticator(crypto), 
  () => new Response("You are authenticated!")
 )
 
-const html = String
-server.get("/", Peko.ssrHandler(() => html`<!doctype html>
+router.get("/asdf", Peko.ssrHandler(() => html`<!doctype html>
  <html lang="en">
  <head>
  <title>Peko auth example</title>
@@ -132,4 +132,4 @@ server.get("/", Peko.ssrHandler(() => html`<!doctype html>
  </html>
 `))
 
-server.listen()
+Deno.serve((req) => router.requestHandler(req))

examples/preact/index.ts

@@ -1,20 +1,20 @@
-import { Server, logger } from "https://deno.land/x/peko/mod.ts"
+import { Router, logger } from "../../mod.ts" //"https://deno.land/x/peko/mod.ts"
 import pages from "./routes/pages.ts"
 import assets from "./routes/assets.ts"
 import APIs from "./routes/APIs.ts"
 
 // initialize server
-const server = new Server()
-server.use(logger(console.log))
+const router = new Router()
+router.use(logger(console.log))
 
 // SSR'ed app page routes
-server.addRoutes(pages)
+router.addRoutes(pages)
 
 // Static assets
-server.addRoutes(assets)
+router.addRoutes(assets)
 
 // Custom API functions
-server.addRoutes(APIs)
+router.addRoutes(APIs)
 
-// Start Peko server :^)
-server.listen()
+// Start Deno server with Peko router :^)
+Deno.serve((req) => router.requestHandler(req))

examples/preact/routes/APIs.ts

@@ -2,7 +2,7 @@ import {
  RequestContext, 
  Route,
  sseHandler
-} from "https://deno.land/x/peko/mod.ts"
+} from "../../../mod.ts"
 
 const demoEventTarget = new EventTarget()
 setInterval(() => {

examples/preact/routes/assets.ts

@@ -3,7 +3,7 @@ import {
  staticHandler,
  cacher,
  ResponseCache
-} from "https://deno.land/x/peko/mod.ts"
+} from "../../../mod.ts"
 
 import { recursiveReaddir } from "https://deno.land/x/recursive_readdir@v2.0.0/mod.ts"
 import { fromFileUrl } from "https://deno.land/std@0.174.0/path/mod.ts"

examples/preact/routes/pages.ts

@@ -3,7 +3,7 @@ import {
  ssrHandler, 
  cacher,
  ResponseCache
-} from "https://deno.land/x/peko/mod.ts"
+} from "../../../mod.ts"
 
 import { renderToString } from "https://npm.reversehttp.com/preact,preact/hooks,htm/preact,preact-render-to-string"
 

examples/preact/src/components/Layout.js

@@ -5,7 +5,8 @@ const Layout = ({ navColor, navLink, children }) => {
  <nav style=${navStyle(navColor)}>
  <div class="container align-center">
  <img height="200px" width="1000px" style="max-width:100%; margin: 1rem;" src="/assets/logo_dark_alpha.webp" alt="peko-chick" /> 
- <h1 style="text-align: center;">Featherweight <a href="/${navLink}" style=${navLinkStyle}>apps</a> on the stateless edge</h1>
+ <h1 style="text-align: center;">Featherweight HTTP routing and utilities</h1>
+ <h2 style="text-align: center;">for <a href="/${navLink}" style=${navLinkStyle}>apps</a> on the stateless edge 🐣⚡</h2>
  </div>
  </nav>
  <main style="padding: 1rem;" class="container">
@@ -26,7 +27,7 @@ const Layout = ({ navColor, navLink, children }) => {
  <a style=${footerLinkStyle} href="/">Home</a>
  <a style=${footerLinkStyle} href="/about">About</a>
  </div>
- <p style="margin: 10px; text-align: center">Made by <a href="https://thesebsite.com">Seb R</a></p>
+ <p style="margin: 10px; text-align: center">Made by <a href="https://thesebsite.com">Sejori</a></p>
  </footer>
  ` 
 }

examples/preact/src/pages/Home.js

@@ -7,12 +7,18 @@ const Home = () => {
  <${Layout} navLink="about" navColor="#101727">
  <h2>Features</h2>
  <ul>
- <li>Simple and familiar syntax, built on top of Deno's <a href="https://deno.land/std/http/server.ts?s=Server">std/http</a>.</li>
+ <li>Simple and familiar syntax, supports any modern JS/TS environment.</li>
  <li>Library of request <a href="#handlers">handlers</a>, <a href="#middleware">middleware</a> and <a href="#utils">utils</a>.</li>
  <li>Cascades <a target="_blank" href="https://github.com/sebringrose/peko/blob/main/server.ts">Request Context</a> through middleware stack for data flow and post-response operations.</li>
  <li>100% TypeScript complete with tests.</li>
  </ul>
 
+ <h2>Guides</h2>
+ <ol>
+ <li><a href="https://github.com/sebringrose/peko/blob/main/react.md">How to build a full-stack React application with Peko and Deno</a></li>
+ <li>Want to build a lightweight HTML or Preact app? Check out the <a href="https://github.com/sebringrose/peko/blob/main/examples">examples</a>!</li>
+ </ol>
+
  <div style="display: flex; justify-content: space-between; flex-wrap: wrap;">
  <div>
  <h2 id="handlers">Handlers</h2>
@@ -36,8 +42,10 @@ const Home = () => {
  <div>
  <h2 id="utils">Utils</h2>
  <ul>
- <li><a target="_blank" href="https://github.com/sebringrose/peko/blob/main/middleware/Crypto.ts">Crypto - JWT/hashing</a></li>
- <li><a target="_blank" href="https://github.com/sebringrose/peko/blob/main/middleware/ResponseCache.ts">Response cache</a></li>
+ <li><a target="_blank" href="https://github.com/sebringrose/peko/blob/main/utils/Crypto.ts">Crypto - JWT/hashing</a></li>
+ <li><a target="_blank" href="https://github.com/sebringrose/peko/blob/main/utils/ResponseCache.ts">Response cache</a></li>
+ <li><a target="_blank" href="https://github.com/sebringrose/peko/blob/main/utils/Profiler.ts">Profiler</a></li>
+ <li><a target="_blank" href="https://github.com/sebringrose/peko/blob/main/utils/helpers.ts">routesFromDir</a></li>
  </ul>
  </div>
  </div>