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

express-version-request

v1.7.0

Published

versions an incoming request to Express based on header or URL

Downloads

8,342

Readme

express-version-request

view on npm view on npm npm module downloads Dependency Status Build Status codecov

What is this?

This npm package provides an ExpressJS middleware that sets the request object with a version property by parsing a request HTTP header.

Usage

Set request version statically

If you wish to employ your own logic in some middleware/configuration and set the request version programmaticaly and not by parsing a specific HTTP header:

const versionRequest = require('express-version-request')

app.use(versionRequest.setVersion('1.2.3'))

Then in later middlewares you will be able to access req.version property and it's value set to 1.2.3.

Set request version by HTTP header

By default, the library will parse the version out of the X-Api-Version HTTP header:

const versionRequest = require('express-version-request')

app.use(versionRequest.setVersionByHeader())

Set request version by custom HTTP header

If you wish to advise the library which HTTP header to parse to extract the version:

const versionRequest = require('express-version-request')

app.use(versionRequest.setVersionByHeader('My-HTTP-Header-Name'))

Set request version by HTTP query parameter

By default, the library will parse the version out of the api-version query parameter:

const versionRequest = require('express-version-request')

app.use(versionRequest.setVersionByQueryParam())

Set request version by custom HTTP query parameter

If you wish to advise the library which query parameter to parse to extract the version:

const versionRequest = require('express-version-request')

app.use(versionRequest.setVersionByQueryParam('myQueryParam'))

setVersionByQueryParam options

The second parameter of setVersionByQueryParam is an options object.

Set request version by 'Accept' header

By default, the library will parse the version from the Accept header, expecting the following format: Accept: application/vnd.company+json;version=1.0.0 For more details about the Accept header format, please refer to the RFC.

const versionRequest = require('express-version-request')

app.use(versionRequest.setVersionByAcceptHeader())

Parsing using an alternative format

As a fallback, the lib supports an alternative Accept header format:

Accept: application/vnd.comapny-v1.0.0+json

or

Accept: application/vnd.comapny.v1.0.0+json

The lib will try to parse the header using the default format, and if it doesn't succeed, tries this alternative format. The usage is the same as in the case of the regular format:

const versionRequest = require('express-version-request')

app.use(versionRequest.setVersionByAcceptHeader())

Parsing using a custom function

If you wish to use your own parsing, it is possible to pass a function as the first parameter. The lib will then call it with the actual value of the Accept header as the first parameter, and the returned value will be set as version. The provided function should return a string.

const versionRequest = require('express-version-request')
function customParsingFunction(header) {
	//function body, that parses the header parameter and returns a string
}

app.use(versionRequest.setVersionByAcceptHeader(customParsingFunction))

Version formatting

Before setting the version, it is always formatted, so the resulting version is a semver comaptible string, except the following cases:

  • if the version was set as an Object, it will be returned in stringified format (using JSON.stringify)
  • if the version is longer than the semver format, we truncate it by cutting off the tail, and leaving the first three segments (e.g.: 1.2.3.4.5 will become 1.2.3)
  • if we encunter something, that can't be parsed or formatted as a version, undefined is returned

This formatting function is called automatically for each version setting method, but it can also be used independently:

const versionRequest = require('express-version-request')
const formattedVersion = versionRequest.formatVersion(versionThatNeedsFormatting)
Options

removeQueryParam

Delete version HTTP query parameter after setting the request object with a version property. By default it is set to false.

const versionRequest = require('express-version-request')
const options = {removeQueryParam: true}

app.use(versionRequest.setVersionByQueryParam('myQueryParam', options))

If you define a middleware after versionRequest then you can verify that the version is indeed set:

app.use((req, res, next) => {
    console.log(req.version)
    next()
  })

Installation

yarn add express-version-request

Tests

yarn test

Project linting:

yarn lint

Coverage

yarn test:coverage

Commit

The project uses the commitizen tool for standardizing changelog style commit messages so you should follow it as so:

git add .           # add files to staging
yarn commit      # use the wizard for the commit message

Author

Liran Tal [email protected]