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

@trust/http-service

v0.1.0

Published

Modular HTTP Services for Express

Downloads

5

Readme

HTTP Service (@trust/http-service)

standard-readme compliant

Modular HTTP Services

This package codifies a design pattern for defining reusable HTTP services.

Table of Contents

Background

It's desireable in many cases to reuse encapsulated bundles of server behavior. For example, library authors implementing an open standard may wish to export an object that is completely responsible for behavior within it's scope and entirely self-contained, such that integrators have virtually nothing to do other than import the code and pass a few configuration parameters.

const express = require('express')
const SomeService = require('some-service')

let server = express()
let service = SomeService.create(settings)

// mount the service into the new Express server
server.use(service.router)

// register additional route handlers
server.get('/', (req, res) => {
  res.send('Unlike SomeService\'s endpoints, I am specific to this server')
})

server.listen(process.env.PORT || 3000)

Install

$ npm install --save @trust/http-service

Usage

const { BaseRequest, HTTPService } = require('@trust/http-service')

API

BaseRequest

A request handler is a class which optionally extends BaseRequest and defines, at a bare minimum, a static route getter and a static handle method. The route getter describes the handler to the service so it can be wired up to an Express router. The handle method is the route handler, with a special extra argument service. At runtime, the instantiated HTTPService will be passed to this argument. This is a form of dependency injection.

class AlphaRequest extends BaseRequest {

  /**
   * The static `route` method defines the information required to
   * register the request handler with an Express router.
   */
  static get route () {
    return {
      path: '/alpha',
      method: 'GET'
    }
  }

  /**
   * The static `handle` method defines endpoint behavior. This method takes
   * three arguments. The first two are the IncomingRequest and HTTPResponse
   * objects to be passed by Express. The third argument allows state and
   * dependencies associated with the respective service to be injected.
   */
  static handle (req, res, service) {
    res.status(418).send(`I am a teapot. My name is ${service.name}`)
  }

}

Note that there is no next argument to handle(req, res, service). This is by design. Services are meant to be self-contained and responsible for every possible outcome of each request within their scope.

This extended BaseRequest may look like boilerplate without a purpose until we consider a more complex request.

The main advantage of defining a request handler as a class is that we can decompose very complex request logic with mixed synchronicity into smaller functions that can be recomposed to represent complicated control flows using promise chains and share state between them using a request instance. This is a helpful technique for avoiding bad patterns with callbacks and middleware stacks.

class BravoRequest extends BaseRequest {

  /**
   * Route definition
   */
  static get route () {
    return {
      path: '/bravo',
      method: 'GET'
    }
  }

  /**
   * A more complex request handler, with promise-based control flow
   * and state.
   */
  static handle (req, res, service) {
    let request = new BravoRequest({ req, res, service })

    Promise.resolve()
      .then(() => request.step1())
      .then(() => request.step2())
      .then(() => request.step3())
      .catch(err => request.error(err))
  }

  step1 () {
    // do something synchronous
  }

  step2 () {
    // do something asynchronous
  }

  step3 () {
    let {res} = this

    if (!this.isOk()) {
      return this.badRequest()
    }

    res.send('asynchronously, with feeling')
  }

  isOk () {
    return true
  }

}

Here, handle instantiates the request handler class, creating an object representing all the state and behavior required to handle this request.

Handlers should never mutate the req argument, as is common (and bad) practice in Node.js development. Our request handler instance provides a safer scope for accessing mutable data that won't come into conflict with any state defined by middleware upstream.

This technique makes it possible to decompose a complex route handler into a series of methods that are easier to understand and test.

The BaseRequest class provides common response and error handling methods.

request.noContent()

request.badRequest()

request.unauthorized()

request.notFound()

request.internalServerError()

request.error(err)

HTTPService

class MyService extends HTTPService {

  /**
   * The `handlers` method returns an array of request handler classes.
   */
  get handlers () {
    return [
      AlphaRequest,
      BravoRequest
    ]
  }

}

(static) create(data, dependencies) → {service}

(static) handlers(directory) → {service}

(static) with(shared, data, dependencies) → {service}

(get) handlers → {Array}

(get) router → {express.Router}

mount()

unmount()

Contribute

Issues

  • please file issues :)
  • for bug reports, include relevant details such as platform, version, relevant data, and stack traces
  • be sure to check for existing issues before opening new ones
  • read the documentation before asking questions
  • it's strongly recommended to open an issue before hacking and submitting a PR
  • we reserve the right to close an issue for excessive bikeshedding

Pull requests

Policy

  • we're not presently accepting unsolicited pull requests
  • create an issue to discuss proposed features before submitting a pull request
  • create an issue to propose changes of code style or introduce new tooling
  • ensure your work is harmonious with the overall direction of the project
  • ensure your work does not duplicate existing effort
  • keep the scope compact; avoid PRs with more than one feature or fix
  • code review with maintainers is required before any merging of pull requests
  • new code must respect the style guide and overall architecture of the project
  • be prepared to defend your work

Style guide

  • ES6
  • Standard JavaScript
  • jsdocs

Code reviews

  • required before merging PRs
  • reviewers SHOULD run the code under review

Collaborating

Weekly project meeting

  • Thursdays from 1:00 PM to 2:00 Eastern US time at [TBD]
  • Join remotely with Google Hangouts

Pair programming

  • Required for new contributors
  • Work directly with one or more members of the core development team

Code of conduct

Contributors

MIT License

Copyright (c) 2017 Anvil Research, Inc.