18h

Installation   |   Get Started   |   Examples   |   Contributions

---

What is 18h?

18h is a Next.js-inspired Koa-router wrapper, which allows you to create routes that match the pattern of your filesystem. This speeds up iteration, while maintaining a serverful architecture.

This library is best used with Node.js & TypeScript in order to unlock all the type-safety capabilities it has to offer.

Why is it named 18h?

That is how long Koala's sleep, and all the cooler names were taken.

Get Started

Getting started is pretty snappy.

Installation

In order to install the package, in your root directory simply use your favourite package manager in order to install the package. It is registered on the NPM under the name 18h.

npm install 18h

Creating the Router

First, using your favourite file manager, or the command line, create the folder in which your routes will be stored in. This folder will mirror the structure of your API.

mkdir routes

Once this is complete, we will be able to instantiate our router object by referencing this folder. It's best practice to use the Node.js path module, along with the global __dirname constant in order to ensure the application runs correctly once it is transpiled to JavaScript.

import { join } from "path";
import { router } from "18h";

router({
  routesFolder: join(__dirname, "routes"),
  port: 8000,
  hostname: "localhost",
});

We can also instantiate the 18h router with global middleware that will run prior to every API call.

const logRequest = async (context, next) => {
  console.log(context);
  await next();
};

router({
  // ...
  middleware: [logRequest],
});

Creating Routes

Its important to remember that the structure of the filesystem within the routes folder you provide as the routesFolder key is going to mirror the structure of your URLs.

Example

Assuming you provided a folder called routes as the routesFolder when creating your router object, creating a file at routes/index.ts it will allow consumers to interact with that endpoint at the http://localhost/ URL.

Creating a file called routes/example.ts will allow consumers to interact with that endpoint at the http://localhost/example URL.

Creating a file called routes/example/index.ts will produce the same result as mentioned above.

Note

Placing square brackets [] around the entire name of a folder or file in the routes folder will allow for route parameters to be accepted through that endpoint.

/a/[b]/c would become the endpoint path /a/:b/c.

The following file structure would generate the corresponding API endpoint structure.

File Structure

package.json
package-lock.json
node_modules/
src/
├── index.ts
└── routes/
    ├── index.ts
    ├── feed/
    │   └── index.ts
    ├── user/
    │   ├── delete.ts
    │   ├── index.ts
    │   └── settings/
    │       ├── private.ts
    │       └── name.ts
    ├── users/
    │   └── [userId]/
    │       ├── block.ts
    │       ├── index.ts
    │       └── follow.ts
    └── posts/
        ├── create.ts
        ├── delete.ts
        ├── index.ts
        ├── like.ts
        └── share.ts
tsconfig.json

Resulting API Path Structure

/
/feed
/user/
/user/delete
/user/settings
/user/settings/private
/user/settings/name
/users/:userId
/users/:userId/block
/users/:userId/follow
/posts
/posts/create
/posts/delete
/posts/like
/posts/share

Adding Logic to Paths

Of course, we want the paths to do things when someone interacts with them, that logic is defined in RouteController object, which takes multiple MethodControllers in which we define the logic of that endpoint.

Let's start off by creating the logic for the /users/[userId]/block endpoint so we can get a better feel for all the features.

// src/routes/users/[userId]/block

import { route, method, validation } from "18h";

export default route<{ userId: string }>({
  get: method({
    /** If you are accepting a body, you must
     * define whether it can be `"form"`,
     * `"json"`, or both. */
    // accepts: ["json", "form"],
    /** Validation, request, and response schema
     * definition is done in one swoop. Uses "zod"
     * library under the hood. */
    schema: {
      request: validation.null(),
      response: validation.object({
        userId: validation.string(),
      }),
    },
    /** Optional middleware, `pre` will occur
     * before the hanler, while `post` will happen
     * after. */
    middleware: {
      pre: [],
      post: [],
    },
    async handler(context) {
      console.log(context.params.userId); // :userId sourced from URL.
      console.log(context.request.body); // null

      return {
        status: 200,
        headers: {
          "x-custom-header": "true",
        },
        body: {
          userId: "some_id",
        },
      };
    },
  }),
});

Examples

We can create a simple endpoint that just responds with the node package version of the current project we're in. The endpoint will work on all HTTP methods, not just GET, but we could change it to do that by changing all occurances of all to get.

import { route, method, validation } from "18h";
const { npm_package_version: version } = process.env;

export default route({
  all: method({
    schema: {
      request: validation.null(),
      response: validation.object({
        version: validation.string().optional(),
      }),
    },
    async handler() {
      return { body: { version } };
    },
  }),
});

Contributions

Contributions are welcome! Happy hacking! 🎉