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

@loxjs/express-router

v2.15.0

Published

Provides a fluent and convenient way to define and manage routes in Express.js applications.

Downloads

25

Readme

@loxjs/express-router

The @loxjs/express-router module provides a fluent and convenient way to define and manage routes in Express.js applications. It extends the routing capabilities with advanced response handling, allowing for a variety of response types and behaviors.

Features

  • Fluent and chainable API for defining routes.
  • Support for all common HTTP methods (GET, POST, PUT, PATCH, DELETE, HEAD).
  • Simplified controller association with support for both single and multiple controllers.
  • Extended response handling within controllers, including:
    • Custom HTTP status codes.
    • HTTP response headers.
    • Redirects and location headers.
    • Response type formatting (HTML, XML, JavaScript, CSV).
    • Raw data responses without default packaging.
  • Easy integration with existing Express.js applications.

Installation

npm install @loxjs/express-router

Or with yarn:

yarn add @loxjs/express-router

Usage

Import and use @loxjs/express-router to define routes in your Express.js application:

// router.js

const ExpressRouter = require('@loxjs/express-router');
const router = new ExpressRouter();

Define routes using the fluent API and attach controllers:

router
  .get('/example')
  .controller(async (req) => {
    // Your GET controller logic here
  });

router
  .post('/example')
  .controller(async (req) => {
    // Your POST controller logic here
  });

module.exports = router

Once all routes are defined, call end() to finalize and use them in your Express.js application:

const express = require('express');
const router = require('./router.js');

const app = express();

app.use('/api', router.end());

app.listen(3000, () => {
  console.log('Server is running on port 3000');
});

API Reference

path(options)

Defines a new path for a route.

  • options: An object with the following properties:
    • method: The HTTP method (default: 'get').
    • path: The path for the route (default: '/').

controller(controller)

Associates a controller with the current path.

  • controller: A function or an array of functions to handle the route.

end()

Finalizes the route definitions and returns the Express router.

HTTP Method Shortcuts

The following methods are shortcuts for path() with the method preset:

  • get(path)
  • post(path)
  • put(path)
  • patch(path)
  • delete(path)
  • head(path)

use(callback)

Uses a middleware function or an array of functions.

  • callback: A middleware function or an array of middleware functions to apply.

Extended Controller Logic

The generate method within the ExpressRouter class provides several extended response handling features:

  • Custom HTTP Status Codes: Controllers can specify custom HTTP status codes for the response.
  • HTTP Response Headers: Controllers can append custom headers to the response.
  • Redirects: Controllers can trigger HTTP redirects using req.routerRedirect.
  • Location Headers: Controllers can set the Location header using req.routerLocation.
  • Response Type Formatting: Controllers can specify the response type (HTML, XML, JavaScript, CSV) using req.routerResponseType.
  • Raw Data Responses: Controllers can bypass default data packaging by setting req.responseRawData to true or by including __disablePackagingData in the response object.
  • File Downloads: For CSV responses, controllers can specify a filename, which prompts the browser to download the file.

These extended features allow for more granular control over the HTTP response from within your controllers.

Default Response Data Format

By default, responses are sent as JSON with the following format:

{
  "code": 200,
  "data": "your data here" // If `.controller()` returns data
}

If .controller() returns void or undefined, responses are sent as JSON with the following format:

{
  "code": 200
}

Setting a Single Cookie

To set a cookie, you can use the req.setCookie object within your request handler. The req.setCookie object must contain the name and value properties.

  • req.setCookie.name (String): The name of the cookie. This field is required.
  • req.setCookie.value (String): The value of the cookie. This field is required.
  • req.setCookie.options (Object): Optional settings for the cookie, such as maxAge.

Example

router
  .post('/set-cookie')
  .controller((req) => {
    req.setCookie = {
      name: 'sessionId',
      value: 'abc123',
      options: { maxAge: 1000 * 60 * 60 * 24 * 30 } // Expires in 30 days
    };

    // ...additional logic...

    res.end('Cookie set');
  });

Setting Multiple Cookies

To set multiple cookies at once, you can assign an array of cookie objects to req.setCookies.

  • req.setCookies (Array): An array where each element is an object with name, value, and optional options properties.

Example

router
  .post('/set-multiple-cookies')
  .controller((req) => {
    req.setCookies = [
      {
        name: 'sessionId',
        value: 'abc123',
        options: { maxAge: 1000 * 60 * 60 * 24 * 30 }
      },
      {
        name: 'preferences',
        value: 'darkmode',
        // No options provided, default settings will be used
      }
    ];

    // ...additional logic...

    res.end('Multiple cookies set');
  });

Clearing a Single Cookie

To clear a single cookie, assign the cookie name to req.clearCookie.

  • req.clearCookie (String): The name of the cookie to clear.

Example

router
  .post('/clear-cookie')
  .controller((req) => {
    req.clearCookie = 'sessionId';

    // ...additional logic...

    res.end('Cookie cleared');
  });

Clearing Multiple Cookies

To clear multiple cookies, provide an array of cookie names to req.clearCookies.

  • req.clearCookies (Array): An array of strings, where each string is the name of a cookie to clear.

Example

router
  .post('/clear-multiple-cookies')
  .controller((req) => {
    req.clearCookies = ['sessionId', 'preferences'];

    // ...additional logic...

    res.end('Multiple cookies cleared');
  });

Handling res.location

To set the Location header for HTTP redirection:

router
  .get('/example')
  .controller((req) => {
    req.routerLocation = '/new-location';
    req.routerHTTPStatus = 302; // Optional: Set a custom HTTP status code
  });

Handling res.redirect

To redirect the request to a different URL:

router
  .get('/example')
  .controller((req) => {
    req.routerRedirect = '/redirect-url';
  });

Custom HTTP Response Headers

To add custom response headers:

router
  .get('/example')
  .controller((req) => {
    req.routerResponseHeaders = [
      ['X-Custom-Header', 'HeaderValue'],
      ['Another-Header', 'AnotherValue']
    ];
  });

Returning HTTP Error Codes

To return a specific HTTP status code, possibly with data:

router
  .get('/error')
  .controller((req) => {
    req.routerHTTPStatus = 500; // Set the HTTP status code
    return { message: 'Internal Server Error' };
  });

Returning HTML

To return HTML content:

router
  .get('/html')
  .controller((req) => {
    req.routerResponseType = 'plainHTML';
    return '<h1>Welcome to the HTML page</h1>';
  });

Returning XML

To return XML content:

router
  .get('/xml')
  .controller((req) => {
    req.routerResponseType = 'xml';
    return '<note><body>This is a note</body></note>';
  });

Returning JavaScript Code

To return JavaScript code:

router
  .get('/script.js')
  .controller((req) => {
    req.routerResponseType = 'js';
    return 'alert("Hello, world!");';
  });

Returning CSV

To return CSV content and prompt a file download:

router
  .get('/csv')
  .controller((req) => {
    req.routerResponseType = 'csv';
    req.filename = 'example.csv';
    return 'id,name\n1,Alice\n2,Bob';
  });

Disabling Data Packaging

To return raw data without the default JSON packaging:

router
  .get('/rawdata')
  .controller((req) => {
    req.responseRawData = true;
    return 'Raw data response';
  });

Contributing

Contributions to @loxjs/express-router are welcome! Please ensure that your contributions adhere to the following guidelines:

  • Write clear, readable, and maintainable code.
  • Follow existing coding styles and practices.
  • Write meaningful commit messages.
  • Update the documentation accordingly.

For more detailed information, please read the contributing guide.

Enjoy using @loxjs/express-router!