Aqua

Aqua is a minimal and fast web framework.

Features

• Immediate parsing of the request body, query and the cookie string
• Middleware functions
• Possibility for route changes while runtime
• URL parameters
• Blazing fast

Example usage

import Aqua from "https://deno.land/x/aqua/mod.ts";

const app = new Aqua(3100);

app.get("/", (req) => {
    return "Hello, World!";
});

Routing

You can either use the short-form syntax for the GET and POST method

app.get("/", (req) => "Hello, World!");
app.post("/", (req) => "Hello, World!");

or use the route function

app.route("/", "GET", (req) => "Hello, World!");

Middlewares

You can register middlewares, that will be able to adjust the response object, the following way:

app.register((req, res) => {
    // Make changes to the response object
    // res.content = res.content.replace("Hello", "Hi");
    return res;
});

URL parameters

You can define URL parameters by using a colon followed by the key name.

app.get("/api/:action", (req) => {
    return req.parameters.action;
});

Schemas

Schemas will discard non-matching requests (Defined fallback handler or default 404).

app.get("/", (req) => {
    return req.parameters.action;
}, {
   schema: {
       query: [
           mustExist("hello")
       ]
   }
});

This schema would only allow requests with the hello query (for example, GET /?hello=yes). The following helper functions are currently available:

• mustExist(key)
• valueMustBeByType(key, type)

You can of course also build your own schema validation functions. Here's how the mustExist function looks:

export function mustExist(key: string): RoutingSchemaValidationFunction {
    return function() {
        /*
            `this` depends on the context, it could either be the 
            query, parameters, cookies or body object.
            Luckily, they all have the same type.
        */
        return Object.keys(this).includes(key);
    };
}

Response value

You can either just return a string

app.get("/", (req) => {
    return "Hello, World!";
});

or return a response object to also set cookies, headers or a status code

app.get("/", (req) => {
    return {
        statusCode: 200,
        cookies: { hello: "I'm a cookie value" },
        headers: { hello: "I'm a header value" },
        content: "Hello, World!"
    };
});

Cookies and headers are just getting appended, so no information is getting lost by providing custom ones. However, you can still overwrite existing headers.

Benchmarks

Last updated: 2020-11-01

More examples

Respond with the content of a file

app.get("/", async (req) => {
    return await app.render("index.html");
});

Please note that you must run your application with the --allow-read flag.

Provide own fallback handler

Your provided fallback handler will be executed if no route has been found.

app.provideFallback((req) => {
    return "No page found, sorry!";
});

Redirect a request

app.get("/dashboard", (req) => {
    return { redirect: "/login" };
});

Static routes

You can register static routes by passing the path to the local folder and the public alias to the serve function.

app.serve("mystaticfolder", "/public");
// A GET request to /public/test.txt would serve the local file at mystaticfolder/test.txt

Regex paths

You can provide a RegExp object instead of a string and receive the matches.

app.get(new RegExp("\/(.*)"), (req) => {
    console.log(req.matches); // GET /hello-world -> [ "hello-world" ]

    return "Hello, World!";
});

TLS

You can enable TLS the following way:

const app = new Aqua(3001, {
    tls: {
        hostname: "localhost",
        certFile: "localhost.crt",
        keyFile: "localhost.key"
    }
});

The example above would handle requests coming to https://localhost:3001.

Handle HTTP and HTTPS requests

You are able to provide the TLS certificate to a different port and let the default port still handle HTTP requests.

const app = new Aqua(3001, {
    tls: {
        hostname: "localhost",
        certFile: "localhost.crt",
        keyFile: "localhost.key",
        independentPort: 3002
    }
});

The example above would allow you to handle requests to http://localhost:3001 and https://localhost:3002 at the same time.