@gasket/request
The purpose of this package is to provide a consistent request object for Gasket plugins and apps to use, regardless of the request handling framework.
Installation
Existing apps
npm install @gasket/request
Functions
GasketRequest
The GasketRequest
class is a representation of a request object that can be
used by Gasket plugins and apps. It is a consistent shape that can be used
across different request handling frameworks.
A GasketRequest
object has the following properties:
Property | Type | Description | Arguments |
---|---|---|---|
headers | object | Request headers | required |
cookies | object | Request cookies | default: {} |
query | object | Query parameters | default: {} |
path | string | Request path | default: '' |
makeGasketRequest
A GasketRequest
can be created from a Node IncomingMessage
object, an
Express Request
object, or a Next.js NextRequest
object, amongst others.
import { makeGasketRequest } from '@gasket/request';
export default async function expressHandler(req, res) {
const gasketRequest = await makeGasketRequest(req);
// use gasketRequest
}
You can also assemble a GasketRequest
object from parts of a request object.
import { GasketRequest } from '@gasket/request';
const headers = {
'x-example': 'example'
};
const staticGasketRequest = await makeGasketRequest({ headers });
withGasketRequest
A higher-order function that can wrap a GasketAction function and provides a
GasketRequest
object as the first argument.
This provides an easy way to normalize the request object for any GasketAction
and potential lifecycle hooks.
import { withGasketRequest } from '@gasket/request';
export const myAction = withGasketRequest(
async function handler(gasket, gasketRequest) {
// use gasketRequest
}
);
// example usage
await gasket.actions.myAction(req);
If your action needs additional arguments, you can pass them following the gasketReq
.
import { withGasketRequest } from '@gasket/request';
export const myAction = withGasketRequest(
async function handler(gasket, gasketRequest, arg1, arg2) {
// use gasketRequest
}
);
// example usage
await gasket.actions.myAction(req, true, false);
withGasketRequestCache
Much like the previous function, withGasketRequestCache
is a higher-order
function that wraps an action handler function and provides a GasketRequest
.
The difference is the handler will only be triggered once per request, and the
result will be cached for subsequent calls.
import { withGasketRequestCache } from '@gasket/request';
export const myAction = withGasketRequestCache(
async function handler(gasketRequest, req, arg1, arg2) {
// use gasketRequest
}
);
// example usage
await gasket.actions.myAction(req, true, false);
Purpose
Why do we need a request object for Gasket?
Some Gasket plugins and apps need to interact with the request object. Unfortunately, the shape and details of a request object is not consistent across all request handling frameworks.
For example:
- Node's
IncomingMessage
docs - Express "enhances" this as
Request
docs- Various other engines also do the same
- Next.js API's (including middleware) use
NextRequest
docs - This extends the browser-compatible Fetch
Request
docs - Next.js App Router does not expose the request object, so we make a representation with the parts available docs
And we are aware of apps using Gasket for Static Pages with Next.js, assembling a request-like object to use with certain actions.