@saibotsivad/glopen-routes NPM

Glopen Routes

Some common routes that I find myself needing often, in glopen format, with JSON:API schemas.

See the list of route definitions and their functionality.

Install

The usual way:

npm install @saibotsivad/glopen-routes

To use with glopen, you can either include everything in one go, grab individual definitions, or explicitly grab each Operation Object.

(Each definition has an openapi folder or a routes folder, or both. The routes folder separates the Operation Objects out, so they can be explicitly grabbed and still allow merging in the other openapi parts. See below for a detailed explanation.)

Everything At Once

You can use the exported convenience function, which returns a list of all the definitions, ready for use by glopen:

// glopen.config.js
import { all } from '@saibotsivad/glopen-routes'
export default {
	merge: [
		...all({
			// Optional: apply the `api` option to all routes.
			api: '/api/v1'
		})
	]
}

If you want everything else but don't need team support, you can use allNoTeams instead of all.

// glopen.config.js
import { allNoTeams } from '@saibotsivad/glopen-routes'
export default {
	merge: [
		...allNoTeams({
			// Optional: apply the `api` option to all routes.
			api: '/api/v1'
		})
	]
}

Individual Definitions

Each definition is a set of interdependent routes, and each is exported as a named function e.g. singleUser. See the full list for details.

You will also need to merge in the shared items, which are shared across all routes.

For example, the routes for a single user to manage their own self:

// glopen.config.js
import { shared, singleUser } from '@saibotsivad/glopen-routes'
export default {
	merge: [
		// The shared components are always required
		...shared(),
		// Then each definition
		...singleUser({
			// The definitions can have their API path prefix set
			api: '/api/v1'
		})
	],
}

Explicit Import

If you want to be explicit about each Operation Object that you bring in to your project, or if you want to rename the paths entirely, you can create a file and import->export the route, overwriting the bits that you want.

For example: if you simply want to rename GET /user to GET /currentUser you could create a folder structure in your project which you would point glopen to, then create the file like so:

// <YOUR_ROUTES>/currentUser/get.@.js
// First: re-export all the named exports
export * from '@saibotsivad/glopen-routes/definition/basic-user-auth/routes/paths/user/get.@.js'
// Second: re-export the default, which is the route handler
export { default } from '@saibotsivad/glopen-routes/definition/basic-user-auth/routes/paths/user/get.@.js'

Additional example: if you also want to customize the security and tags for each:

// <YOUR_ROUTES>/currentUser/get.@.js
// First: re-export all the named exports
export * from '@saibotsivad/glopen-routes/definition/basic-user-auth/routes/paths/user/get.@.js'
// Second: re-export the default, which is the route handler
export { default } from '@saibotsivad/glopen-routes/definition/basic-user-auth/routes/paths/user/get.@.js'
// Third: exporting `security` here will overwrite whatever was re-exported in the first step
export const security = [ { myBetterAuth: [] } ]
// Fourth: in the same way, exporting `tags` would completely overwrite the re-exported
// tags list. If you want to *merge* the lists, you'll need to import it explicitly, and
// then export the merged list
import { tags as tagsList } from '@saibotsivad/glopen-routes/definition/basic-user-auth/routes/paths/user/get.@.js'
export const tags = [ ...tagsList, 'my-custom-tag' ]

Note: in your glopen config file you'd still need to merge in the shared components and the openapi folder for the named definition:

// glopen.config.js
export default {
	merge: [
		// The shared definition parts are always required
		{ dir: './node_modules/@saibotsivad/glopen-routes/definition/_shared/openapi' },
		// For the explicit imported routes, you need to include the `openapi` part
		// to get the component schemas
		{ dir: './node_modules/@saibotsivad/glopen-routes/definition/basic-user-auth/openapi' },
		// Finally, merge in your own project routes
		{ dir: '<YOUR_ROUTES>' },
	],
}

Using this approach can be a bit tedious, since you would need to recreate the folder structure for all route methods, e.g. in the basic-user-auth there are at least ten (10) files, and you'd need to create all ten in order to have all functionality explicitly named.

One shortcut to note is that glopen will merge first-to-last, so as long as you aren't renaming any files, you could be explicit with one or two Operation Objects, then merge the named definition first and your explicit folder last, and yours would end up overwriting the original.

Design

The route handlers are async and take a request object with a properties that need to be initialized prior to executing the handler function:

body: Object - The request body for all these routes is JSON so, for routes that need it, you'll need a body-parser that parses the JSON in advance.
controller: Object - The set of initialized controllers, which are essentially the functions that do the actual work, like user.create. (Each route lists the controllers it requires.)

Instead of setting properties on a response object, like Express etc., these route handlers return an object with the following properties:

status: Number - The response status code.
headers: Object - These headers should be merged with any other headers, overwriting base headers if any exist.
body: Object | String | null - The response body, if it exists.
json: Boolean - The response body must be passed through a JSON stringify function prior to being returned.

Here is a little demo to show you how you might instantiate and handle a request:

// You'll need to instantiate controllers in advance (or use lazy instantiation techniques).
const controller = {
	demo: {
		getDemo: async (request) => {
			if (request.headers['X-API-Token'] === 'battery-horse-staple') {
				return [ 'first', 'second' ]
			} else {
				return [ 'third', 'fourth' ]
			}
		}
	}
}
// This is what one of the handlers from this project might look like.
const demoRequestHandler = async request => {
	// The controllers are assumed to be instantiated already.
	const data = await request.controller.demo.getDemo(request)
	return {
		status: 200,
		json: true,
		body: { data }
	}
}
// This is a very naive approach, but shows the fundamentals.
import http from 'http'
const server = http.createServer((request, response) => {
	request.controller = controller
	demoRequestHandler(request).then(({ status, json, body }) => {
		response.statusCode = status
		if (json) {
			response.setHeader('Content-Type', 'application/json')
			response.end(JSON.stringify(body))
		} else {
			response.end(body)
		}
	})
})