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

@heartsradiant/blocks

v5.0.6

Published

REST API framework for Node.js - Hearts Radiant fork

Downloads

19

Readme

CircleCI npm package version Coverage Status

blocks

REST API framework for Node.js

Request-Response cycle


Features

Validate input

Pass request data (headers, body, query parameters, URL parameters) through custom JSON Schemas defined for each route. Make sure no unwanted data gets in, de-clutter the route logic and make the API behave more consistent. If validation fails, an automatic 409 Conflict response will be sent.

Permissions

Function outside of main route logic. If it returns false, an automatic 403 Forbidden response will be sent.

Plugin / Dependency Injection

Separate 3rd party systems logic or splitting code for better SOC

Promises

async/await in Plugins and Routes

Other

  • File upload and form parsing for multipart/form-data - busboy
  • Middleware support of existing package - connect
  • JSON Web Token - jsonwebtoken
  • Query string parsing - qs
  • Route parameter parsing - path-to-regexp
  • Cross-origin resource sharing - cors
  • Secure your API with various HTTP headers - helmet

Install

npm install @heartsradiant/blocks

Example

src/index.js

import http from "node:http"
import glob from "glob"
import { block } from "@heartsradiant/blocks"

const [middleware] = await block({
  plugins: glob.sync("./plugins/*.js", { absolute: true }),
  routes: glob.sync("./**/*.route.js", { absolute: true }),
})

http
  .createServer(middleware)
  .listen(process.env.PORT)
  .on("error", error => {
    console.log("Server error", error)
  })
  .on("listening", () => {
    console.log(`Server started on port ${process.env.PORT}`)
  })

Configuration

blocks uses a set of process.env variables for configuration. See _env file for all available options and defaults.

Use dotenv for easy local development.

Routes

Default "/ping"

GET: /ping

{
  "name": "@heartsradiant/blocks",
  "ping": "pong",
  "aliveFor": {
    "days": 2, "hours": 1, "minutes": 47, "seconds": 46
  }
}

Definition

src/something.route.js

import schema from "./something.schema.js"

export default {
  method: "GET",
  path: "/something/:id",

  /**
   * Check "req.query", "req.header", "req.params" and "req.body"
   * against a JSON Schema. If check fails, respond with 409,
   * otherwise continue to ".authenticate".
   */
  schema,

  /**
   * Check for valid JWT.
   *
   * @param {object} plugins
   *
   * @returns {(object) => Promise<boolean>}
   * If false, responds with 401, otherwise continue to ".authorize".
   */
  authenticate: (/* plugins */) => (/* req */) => true,

  /**
   * Check if is allowed to access underlying resource.
   *
   * @param {object} plugins
   *
   * @returns {(object) => Promise<boolean>}
   * If false, respond with 403, otherwise continue to ".action".
   */
  authorize: (/* plugins */) => (/* req */) => true,

  /**
   * Route/Controller logic
   *
   * @param {object} plugins
   *
   * @returns {(object) => Promise<*>} 500 if throws, 201 if POST, 200 otherwise
   */
  action: (/* plugins */) => req => {
    return {
      message: req.ctx.params.id,
    }
  },
}

JSON schemas

Input validation is the first step in the processing pipeline. It's meant to validate that incoming data corresponds with what the route expects in order to do it's job properly. See ajv and JSON Schema docs for more on data validation.

Schemas can contain only 4 (optional) keys. Each key must be a ajv compatible object.

  • headers validates req.headers
  • params validates req.ctx.params parsed from URL with path-to-regexp
  • query: validates req.ctx.query parsed from URL with qs
  • body validates req.ctx.body parsed from req with JSON.parse

See src/plugins/route-default.schema.js for default values.

src/something.schema.js

export default {
  headers: {
    type: "object",
    required: ["authorization"],
    properties: {
      authorization: {
        type: "string",
      },
    },
  },

  params: {
    type: "object",
    additionalProperties: false,
    required: ["id"],
    properties: {
      id: {
        type: "string",
        pattern: "^[a-z0-9-]+$",
        maxLength: 25,
        minLength: 25,
      },
    },
  },

  query: {
    type: "object",
    additionalProperties: false,
    properties: {
      offset: {
        type: "integer",
        minimum: 0,
        default: 0,
      },
      limit: {
        type: "integer",
        minimum: 1,
        maximum: 100,
        default: 20,
      },
    },
  },
}

Data formats

  • date: full-date according to RFC3339
  • time: time with optional time-zone
  • date-time: date-time from the same source (time-zone is mandatory)
  • duration: duration from RFC3339
  • uri: full URI
  • email: email address
  • ipv4: IP address v4
  • ipv6: IP address v6
  • regex: tests whether a string is a valid regular expression by passing it to RegExp constructor
  • uuid: Universally Unique IDentifier according to RFC4122
{
  "params": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "id": {
        "type": "string",
        "format": "uuid"
      }
    }
  },

  "query": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "email": {
        "type": "string",
        "format": "email"
      }
    }
  },

  "body": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "thumbnailURL": {
        "type": "string",
        "format": "uri"
      },
      "createdAt": {
        "type": "string",
        "format": "date-time"
      }
    }
  }
}

Plugins

Separate code interfacing with 3rd party libraries or services. pluginus dependency injection library is used.

Plugins are accessible in other plugins, middleware and routes.

Custom plugin

A plugin consists of a constructor function and a list of other plugins that is dependent on.

Whatever the create function returns will be considered as the plugin's content and is what will be exposed to the routes, middleware and other plugins.

src/plugins/database.js

import Sequelize from "sequelize"

export default {
  /**
   * Array of plugins to wait for before running `create`.
   * Name is constructed from the filename by removing the extension and
   * turning it into CammelCase.
   *
   * Ex. "test__name--BEM.plugin.js" => "TestNameBemPlugin"
   */
  depend: ["Lorem"],

  /**
   * Constructor, return value will be considered the plugin's content exposed
   * to routes, middleware and other plugins.
   *
   * @returns  {Promise<any>}  Plugin content
   */
  create: => Lorem => {
    console.log("Checking DB connection")

    // Database connection, model loading etc
    ...
    return {
      Todos: ...,
      Comments: ...,
    }
  }
}

Develop

git clone [email protected]:asd-xiv/blocks.git && \
  cd blocks && \
  npm run setup

Run all *.test.js in tests folder

npm test

Watch src and tests folders and re-run tests

npm run tdd

Changelog

See the releases section for details.