@miqro/core v5.0.12

@miqro/core

promise based router

• router
  • request parsing
    • custom types
  • static files
  • proxy router
  • error handling
• apirouter
  • auto documentation

router

import {createServer} from "http";
import {Router, JSONParser} from "@miqro/core";

const router = new Router();

router.post("/echo", [JSONParser(), async (ctx) => {
  // the IncomingMessage is in ctx.req
  // the ServerResponse is in ctx.res
  ctx.logger.info("we got a echo request hit with query: %o params: %o body: %o", ctx.query, ctx.params, ctx.body);
  await ctx.json({
    body: ctx.body
  });
}]);
router.get("/user/:userId", async (ctx) => {
  await ctx.json({
    userId: ctx.params.userId
  });
});
router.use(async (ctx) => {
  await ctx.end({
    headers: {
      ["Content-Type"]: "plain/text; charset=utf-8"
    },
    status: 404,
    body: "NOT FOUND"
  });
});

const server = createServer(router.listener).listen(8080);

request parsing

for more examples of parsing see @miqro/parser

router.get("/add/:a/:b", {
  request: {
    body: false, // do not allow body
    params: {
      a: "number", // parse param :a to a number if posible if not throw
      b: "number", // parse param :b to a number if posible if not throw
    },
    query: {
      decimals: "boolean?|number?", // two optional posible parsing types
      format: {
        type: "enum?", // optional enum
        enumValues: ["number", "text"],
        defaultValue: "number"
      }
    }
  },
  handler: async (ctx) => {
    // ctx.params.a and ctx.params.b are numbers and not strings
    const result = ctx.params.a + ctx.params.b;
    ctx.logger.info("adding %s + %s = %s", ctx.params.a, ctx.params.b, result);

    const decimals = ctx.query.decimals;

    ctx.info("decimals set on query %s", decimals);

    switch (ctx.query.format) {
      case "number":
        await ctx.text(result);
        break;
      case "text":
        await ctx.text("the result is " + result);
        break;
      default:
        throw new BadRequest("unsupported format");
    }
  }
});

custom types

import {Parser} from "@miqro/parser";

const parser = new Parser();
parser.registerType("CustomType", {
  //...
});
router.get("/add/:a/:b", {
  parser,
  //...
});

static files

import {Static} from "@miqro/core";

router.use(Static({
  directory: resolve(__dirname, "static")
}), "/content/public");

proxy router

import {Proxy} from "@miqro/core";

router.use(Proxy({
  url: "http://otherhost/api/somepath/";
  //rejectUnauthorized: false;
}), "/proxy/");

error handling

router.catch(myFallBackerrorHandler1) // this will catch all throws
router.catch(myFallBackerrorHandler2) // if myFallBackerrorHandler1 didnt ended the request myFallBackerrorHandler2 will be called

router.use(async (ctx) => {
  throw new Error("");
});

apirouter

for loading full directories with the folders acting as path's

consider the following directory structure

api/
  v1/
    user/
      :userId/
        get.ts
        delete.ts
        patch.ts
      post.ts
    post/
      :postId/
        get.ts
      post.ts

this will producte the following routes.

• GET /api/v1/user/:userId/
• DELETE /api/v1/user/:userId/
• PATCH /api/v1/user/:userId/

• POST /api/v1/user/

• GET /api/v1/post/

• POST /api/v1/post/:postId/

each file has to implement the APIRoute interface.

example

import {APIRoute} from "@miqro/core";

export default {
  handler: async (ctx) => {

  }
} as APIRoute;

to load the routes

import {APIRouter} from "@miqro/core";

const api = APIRouter({ dirname: resolve(__dirname, "api") });

app.use(api);

auto documentation

...
console.dir(router.getJSONDoc());
...

or generate a json

npx miqro doc build/api /api

where build/api is the APIRouter directory