REST API framework for Node.js
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 Conflictresponse will be sent.
Function outside of main route logic. If it returns false, an automatic
403 Forbiddenresponse will be sent.
Separate 3rd party systems logic or splitting code for better SOC
async/awaitin Plugins and Routes
- 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
npm install @heartsradiant/blockssrc/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}`)
})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.
GET: /ping
{
"name": "@heartsradiant/blocks",
"ping": "pong",
"aliveFor": {
"days": 2, "hours": 1, "minutes": 47, "seconds": 46
}
}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,
}
},
}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.
headersvalidatesreq.headersparamsvalidatesreq.ctx.paramsparsed from URL withpath-to-regexpquery: validatesreq.ctx.queryparsed from URL withqsbodyvalidatesreq.ctx.bodyparsed fromreqwithJSON.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,
},
},
},
}- 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"
}
}
}
}Separate code interfacing with 3rd party libraries or services. pluginus dependency injection library is used.
Plugins are accessible in other plugins, middleware and routes.
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: ...,
}
}
}git clone [email protected]:asd-xiv/blocks.git && \
cd blocks && \
npm run setupRun all *.test.js in tests folder
npm testWatch src and tests folders and re-run tests
npm run tddSee the releases section for details.