npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

zemi

v1.4.8

Published

zemi is a data-driven and reverse-routing library for Express.

Downloads

702

Readme

zemi

build Code Climate Coverage Code Climate Maintainability Snyk.io Vulnerabilities

npm Version Types Dependencies Install Size License

zemi is a data-driven routing library for Express, built with Typescript.

Features:

Table of Contents

  1. Routing
    1. Data-driven
    2. Reverse-routing
    3. Middleware
    4. Parameter Inheritance
  2. Types
    1. ZemiMethod
    2. ZemiRequestHandler
    3. ZemiRequest
    4. ZemiResponse
    5. ZemiRouteDefinition
    6. ZemiRoute
  3. Examples
    1. Simple
    2. With Middleware
    3. Using Named Routes For Redirects
    4. Using Reverse Routing
    5. With Param Inheritance from Parent Routes
  4. Limitations

Routing

Data-driven

Assume you have the following functions defined: petsHandler, dogBreedHandler, dogBreedsIdHandler, catsByIdHandler ; e.g.:

const petsHandler = (request: ZemiRequest, response: ZemiResponse) => {
  // do something with this request and respond
  response.status(200).json({ pets: ["dogs", "cats"] });
};

const dogBreedHandler = (request: ZemiRequest, response: ZemiResponse) => {
   //...
};

const dogBreedsIdHandler = (request: ZemiRequest, response: ZemiResponse) => {
   //...
};

const catsByIdHandler = (request: ZemiRequest, response: ZemiResponse) => {
   //...
};

Then the following code:

import express from "express";
import zemi, { ZemiRoute, ZemiMethod } from "zemi";

const { GET } = ZemiMethod;

const routes: Array<ZemiRoute> = [
  {
    name: "pets",
    path: "/pets",
    [GET]: petsHandler,
    routes: [
      {
        name: "dogBreeds",
        path: "/dogs/:breed",
        [GET]: dogBreedHandler,
        routes: [
          {
            name: "dogsByBreedById",
            path: "/:id",
            [GET]: dogBreedsIdHandler
          }
        ]
      },
      {
        name: "catsById",
        path: "/cats/:id",
        [GET]: catsByIdHandler
      }
    ]
  }
];

const app = express();
app.use(express.json());
app.use("/", zemi(routes));
app.listen(3000);

Generates an API like:

| routes | response | |-------------------------|-----------------------------------------------------| | /pets | {pets: ['dogs', 'cats', 'rabbits']} | | /pets/dogs | Cannot GET /pets/dogs/ (since it was not defined) | | /pets/dogs/labrador | {"result":["Fred","Barney","Wilma"]} | | /pets/dogs/labrador/1 | {"result":"Barney"} | | /pets/cats | Cannot GET /pets/cats/ (since it was not defined) | | /pets/cats/2 | {"result":"Daphne"} |

Reverse-routing

zemi builds route-definitions for all routes and adds them to the ZemiRequest passed to the handler function.

All route-definitions are named (index-accessible) and follow the same naming convention: [ancestor route names]-[parent route name]-[route name], e.g. basePath-greatGrandparent-grandparent-parent-myRoute, pets-dogsBreeds-dogsByBreedById.

Each route-definition contains the name, path, and path-parameters (if present) of the route. It also contains a reverse function which — when invoked with an object mapping path-parameters to values — will return the interpolated path with values.

E.g. a handler like this:

import { ZemiRequest, ZemiResponse, ZemiRouteDefinition } from "zemi";

const petsHandler = (request: ZemiRequest, response: ZemiResponse) => {
  const routeDefinitions: Record<string, ZemiRouteDefinition> = request.routeDefinitions;
  const { path, name, parameters, reverse } = routeDefinitions["pets-dogBreeds-dogsByBreedById"];
  response.status(200).json({ path, name, parameters, reverse: reverse({ breed: 'Corgi', id: '99' }) });
};

Returns:

  {
  "path": "/pets/dogs/:breed/:id",
  "name": "pets-dogBreeds-dogsByBreedById",
  "parameters": [
    "breed",
    "id"
  ],
  "reverse": "/pets/dogs/corgi/99"
}

This allows you to generate links, redirect, and change path values without having to hardcode strings and change them later.

Middleware

zemi lets you define middleware functions at the route level:

Retaking and tweaking our example from the beginning:

import { ZemiRequest, ZemiResponse } from "zemi";
import { NextFunction } from "express";

const routes: Array<ZemiRoute> = [
  {
    name: "pets",
    path: "/pets",
    [GET]: petsHandler,
    routes: [
      {
        name: "dogBreeds",
        path: "/dogs/:breed",
        [GET]: dogBreedHandler,
        middleware: [
          function logRouteDefs(request: ZemiRequest, response: ZemiResponse, next: NextFunction) {
            console.log(JSON.stringify(request.routeDefinitions));
            next();
          }
        ],
        routes: [
          {
            name: "dogsByBreedById",
            path: "/:id",
            [GET]: dogBreedsIdHandler
          }
        ]
      },
      {
        name: "catsById",
        path: "/cats/:id",
        [GET]: { handler: catsByIdHandler }
      }
    ]
  }
];

The middleware function logRouteDefs defined at the dogBreeds level will be applied to all the methods at that level and all nested routes — which means our dogsByBreedById route will gain that functionality also.

Parameter Inheritance

As show in previous examples, parameters defined at parent routes are passed and available to nested routes.

E.g. in this purposefully convoluted example:

const routes: Array<ZemiRoute> = [
  {
    name: "pets",
    path: "/pets",
    [GET]: petsHandler,
    routes: [
      {
        name: "dogBreeds",
        path: "/dogs/:breed",
        [GET]: dogBreedHandler,
        routes: [
          {
            name: "dogsByBreedById",
            path: "/:id",
            [GET]: dogBreedsIdHandler,
            routes: [
              {
                name: "dogsByBreedByIdDetailsSection",
                path: "/details/:section",
                [GET]: dogBreedsIdDetailsSectionHandler,
                routes: [
                  {
                    name: "newDogsByBreedByIdDetailsSection",
                    path: "/new",
                    [POST]: newDogsByBreedByIdDetailsSectionHandler
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
];

The newDogsByBreedByIdDetailsSection route (path: /pets/dogs/:breed/:id/details/:section/new) will have breed, id, and section available as request parameters in the ZemiRequest object.

Types

ZemiMethod

Enum

The HTTP methods supported by ZemiRoute.

| Member | Value | |-----------|-----------| | GET | get | | POST | post | | PUT | put | | DELETE | delete | | OPTIONS | options |

ZemiRequestHandler

How to handle incoming requests for this route method; basically express.RequestHandler, but gets passed its own request and response versions, plus adds that routes ZemiRouteDefinition as an optional fourth param.

(
  request: ZemiRequest,
  response: ZemiResponse,
  next: express.NextFunction,
  routeDef: ZemiRouteDefinition
) => void

ZemiRequest

extends express.Request

A wrapper for express.Request; adds routeDefinitions and allowedResponseHttpCodes to it.

{
  routeDefinitions: Record<string, ZemiRouteDefinition>;
  // all other members from express.Request
}

ZemiResponse

extends express.Response

Just a wrapper for future-proofing; same as express.Response.

ZemiRouteDefinition

Route definition for a given ZemiRoute. Contains the name, path, and path-parameters (if present) of the route it's defining. Also provides a reverse function that, when invoked with an object that has parameter-values, will return the resolved path.

{
  name: string;
  path: string;
  parameters: Array<string>;
  reverse: (parameterValues: object) => string;
}

ZemiRoute

It must be provided a name: string and path: string; a ZemiMethod:ZemiHandlerDefinition needs to be provided if that path should have functionality, but doesn't need to be if the path is just present as a path-prefix for nested routes.

{
   [ZemiMethod]: ZemiHandlerDefinition;
   name: string;
   path: string;
   middleware?: Array<RequestHandler>;
   routes?: Array<ZemiRoute>;
}

Examples

Examples are available in the examples dir:

  1. Simple

  2. With Middleware

  3. Using Named Routes For Redirects

  4. Using Reverse Routing

  5. With Param Inheritance from Parent Routes

Limitations

zemi is a recursive library: it uses recursion across a number of operations in order to facilitate a low footprint and straightforward, declarative definitions.

Recursive operations can break the call-stack by going over its limit, generating Maximum call stack size exceeded errors. This means that the recursive function was called too many times, and exceeded the limit placed on it by Node.

While recursive functions can be optimized via tail call optimization (TCO), that feature has to be present in the environment being run for optimization to work.

Unfortunately — as of Node 8.x — TCO is no longer supported.

This means that, depending on what you're building and the size of your API, zemi might not be the right fit for you. zemi uses recursion when dealing with nested routes, so if your application has a very high number of nested-routes within nested-routes, chances are you might exceed the call stack.