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

blueoak-server

v2.13.1

Published

BlueOak Server

Downloads

74

Readme

BlueOak Logo

BlueOak Server is a NodeJS framework for building RESTful APIs.

Build Status npm version

BlueOak Server is swagger-matic, that is, it maximizes the value of your Swagger API (now OpenAPI, but really this supports only V2) by using it to drive runtime behavior.
BlueOak Server loads your Swagger API, connects the paths it defines to your implementation code, exposes that API to the network, and validates that every request is well-formed per that API.

Check out the documentation on our wiki: https://github.com/BlueOakJS/blueoak-server/wiki

Overview

BlueOak Server combines some of the best Node libraries into a single tool for building RESTful APIs. It uses Express under the covers, but adds many additional features:

  • Swagger integration
  • Easy configuration
  • Clustering
  • Logging
  • Dependency injection

Projects use the following directory structure.

├── [your_project_name]/
│   ├── index.js <-- optional Main script
│   ├── package.json
|   ├── config/
|   |     └── default.json
│   ├── handlers/
│   ├── services/
│   ├── middleware/
│   ├── swagger/

Handlers

Handlers contain Express route-handling functions. They can either be directly wired to routes on the Express app, or defined using Swagger.

To use the app directly, simply create a js file in the handlers directory that exports an init function. The init function is called during server startup and injected with the the app automatically.

exports.init = function(app) {
  app.get('/', function(req, res) {
    res.json({});
  });
}

Services

Services do most of the heavy lifting. Like handlers, services contain init functions that are called during server startup. However, services can export other functions, and those functions can be invoked from handlers.

Here's an example of a fizzbuzz service (services/fizzbuzz.js). You'll notice it has an init method with two parameters, logger and callback. The logger is a built-in service for logging. The callback is an optional parameter used for cases where services need to perform asynchronous operations during startup. The service also exports a getResult function. Any service or handler with a dependency on fizzbuzz can invoke fizzbuzz.getResult.

exports.init = function(logger, callback) {
  logger.info("Starting FizzBuzz service");
  callback();
}

exports.getResult = function(num) {
    if (num % 15 === 0) {
        return "FizzBuzz";
    } else if (num % 3 === 0) {
        return "Fizz";
    } else if (num % 5 === 0) {
        return "Buzz";
    } else {
        return num;
    }
};
  

We want to use that service from our handler, so we include fizzbuzz as a parameter of the init function. The server will ensure that the fizzbuzz service is initialized during server startup and passed to the handler.

exports.init = function(app, fizzbuzz) {

  app.get('/fizzbuzz/:num', function(req, res) {
    var num = req.params.num;
    res.json({
        result: fizzbuzz.getResult(num)
     });
  });
  
}

Third-party Services

Services can be published as npm modules and pulled into projects through the npm install command.

For example, the bos-couchdb service adds the ability to connect to a CouchDB database. It can be installed to a blueoak-server project using

$ npm install bos-couchdb --save

Once installed, it can be used in any service or handler through the dependency-injected bosCouchdb parameter.

exports.init = function(config, logger, bosCouchdb) {
  var myDb = bosCouchdb.get('mydb');
}
  • bos-couchdb - service for connecting to CouchDB databases

Config

Configuration is stored in json files in the config directory. Values can be accessed through the config service in handers and services. Configuration also supports layering on environment-specific config as well as encrypted values.

exports.init = function(config) {
  var myServiceConfig = config.get('myService');
}

Middleware

Middleware are similar to services but used to wire up Express middleware. The express section of the config determines which middleware is loaded and in which order.

{
  "express": {
    "middleware": ["csrf", "cors", "session", "body-parser"]
  }
}

Swagger (OpenAPI)

Swagger files in the swagger directory are read during server startup and automatically wired up to handlers. Swagger files can be in either json or yaml formats.

We've really focused on making API development with Swagger and BlueOak Server to be excellent.

At a high-level, BlueOak Server's Swagger support provides the following:

  • Automatic app routing from the API method to the function as defined in the Swagger
  • Request parameter validation, including the body model, based on your method definion
  • Reponse model validation based on your method definitions during development
  • JSON $refs to external Swagger documents on the file system
  • Multiple top-level Swagger API definitions supporting delivery of multiple API base paths
  • Publishing of the fully compiled Swagger spec for input to by tools such as Swagger-UI and swagger-commander

Installation

$ npm install -g blueoak-server

-or-

$ npm install --save blueoak-server

Usage

If installed globally, run blueoak-server from within your project's directory. e.g.:

$ blueoak-server

If installed at a package level, call blueoak-server in the npm start script. e.g.:

  "scripts": {
    "start": "blueoak-server"
  }

Alternatively, it can be launched programmatically from your own js script.

var server = require('blueoak-server');

server.init(function(err) {
    if (err) {
        console.warn(err);
    } else {
        console.log('started');
    }
});

The programmatic approach works well during development with tools like nodemon, which monitor for file changes and automatically restart the server.

Next steps

Read through the docs and look at the our examples.

When you're ready to try it out, start from the template.