@xylabs/express
Advanced tools
SDK for base code for Api repos that use express and deploy on AWS ECS
Using npm:
npm install {{name}}
Using yarn:
yarn add {{name}}
Using pnpm:
pnpm add {{name}}
Using bun:
bun add {{name}}
See the LICENSE file for license rights and limitations (LGPL-3.0-only).
### .temp-typedoc
### classes
### <a id="Counters"></a>Counters
Static counter registry for tracking named numeric metrics.
new Counters(): Counters;
Counters
static counters: Record<string, number> = {};
static inc(name, count?): void;
string
number = 1
void
static max(name, count): void;
string
number
void
static min(name, count): void;
string
number
void
### <a id="Profiler"></a>Profiler
Measures and records the execution duration of async operations by name.
new Profiler(): Profiler;
Profiler
stats: Record<string, number> = {};
profile<T>(name, promise): Promise<T>;
T
string
Promise<T>
Promise<T>
### <a id="WrappedWinstonLogger"></a>WrappedWinstonLogger
Wrap Winston logger methods to adapt to familiar console logging methods
Loggernew WrappedWinstonLogger(winston): WrappedWinstonLogger;
Logger
WrappedWinstonLogger
protected readonly winston: Logger;
debug: LogFunction;
Logger.debug
error: LogFunction;
Logger.error
info: LogFunction;
Logger.info
log: LogFunction;
Logger.log
trace: LogFunction;
Logger.trace
warn: LogFunction;
Logger.warn
### functions
### <a id="addRouteDefinitions"></a>addRouteDefinitions
function addRouteDefinitions(app, routeDefinitions): void;
Registers an array of route definitions on an Express application.
Express
The Express application to register routes on.
RouteDefinition<RequestHandler<ParamsDictionary, any, any, ParsedQs, Record<string, any>>>[]
The route definitions to register.
void
### <a id="asyncHandler"></a>asyncHandler
function asyncHandler<P, ResBody, ReqBody, ReqQuery, Locals>(fn): (req, res, next) => Promise<unknown>;
Wraps an async Express request handler to forward rejected promises to the error handler.
P = ParamsDictionary
ResBody = Empty
ReqBody = Empty
ReqQuery = ParsedQs
Locals extends NoLocals = NoLocals
RequestHandler<P, ResBody, ReqBody, ReqQuery, Locals>
The async request handler to wrap.
A request handler that catches async errors and passes them to next().
(req, res, next) => Promise<unknown>
### <a id="clearRawResponseFormat"></a>clearRawResponseFormat
function clearRawResponseFormat(res): void;
Clears any flags on the response, allowing the response to use the default standard response envelope
Response
The response to set to the standard response format
void
### <a id="compactObject"></a>compactObject
function compactObject<T>(obj): T;
Returns a shallow copy of the object with all null and undefined values removed.
T extends Record<string, unknown>
T
The object to compact.
T
A new object with only defined, non-null properties.
### <a id="customPoweredByHeader"></a>customPoweredByHeader
function customPoweredByHeader(
req,
res,
next): void;
Express middleware that sets the X-Powered-By header to 'XYO'.
Request
Response
NextFunction
void
### <a id="disableCaseSensitiveRouting"></a>disableCaseSensitiveRouting
function disableCaseSensitiveRouting(app): void;
Disable case sensitivity. When enabled, "/Foo" and "/foo" are different routes. When disabled, "/Foo" and "/foo" are treated the same.
Express
The Express app to disable the header on.
void
### <a id="disableExpressDefaultPoweredByHeader"></a>disableExpressDefaultPoweredByHeader
function disableExpressDefaultPoweredByHeader(app): void;
By default Express appends the X-Powered-By: Express header to
all responses. Calling this method disables that behavior.
Express
The Express app to disable the header on.
void
### <a id="enableCaseSensitiveRouting"></a>enableCaseSensitiveRouting
function enableCaseSensitiveRouting(app): void;
Enable case sensitivity. When enabled, "/Foo" and "/foo" are different routes. When disabled, "/Foo" and "/foo" are treated the same.
Express
The Express app to disable the header on.
void
### <a id="enableExpressDefaultPoweredByHeader"></a>enableExpressDefaultPoweredByHeader
function enableExpressDefaultPoweredByHeader(app): void;
By default Express appends the X-Powered-By: Express header to
all responses. Calling this method enables that behavior.
Express
The Express app to disable the header on.
void
### <a id="errorToJsonHandler"></a>errorToJsonHandler
function errorToJsonHandler(
error,
req,
res,
next): void;
Express error handler that logs the error and sends a JSON response with the error message and status code.
The Express error to handle.
Request
The incoming request.
Response
The outgoing response.
NextFunction
The next middleware function.
void
### <a id="getDefaultLogger"></a>getDefaultLogger
function getDefaultLogger(): Logger;
Returns the singleton default logger instance, creating one if it does not exist.
Logger
The default logger.
### <a id="getHttpHeader"></a>getHttpHeader
function getHttpHeader(header, req): string | undefined;
Since there can be multiple of certain HTTP headers or to prevent ugliness if someone did send us multiple instances of a header we only expect one of, this method grabs the 1st/only one of the desired header
string
The header to find
Request
The received HTTP request (with headers)
string | undefined
The first or only occurrence of the specified HTTP header
### <a id="getJsonBodyParser"></a>getJsonBodyParser
function getJsonBodyParser(options?): NextHandleFunction;
Get a JSON Body Parser connect middleware handler
OptionsJson = DefaultJsonBodyParserOptions
The options for the JSON Body Parser
NextHandleFunction
A middleware function that parses JSON bodies
### <a id="getJsonBodyParserOptions"></a>getJsonBodyParserOptions
function getJsonBodyParserOptions(options?): OptionsJson;
Gets the default JSON Body Parser options merged with the supplied options with the supplied options taking precedence
Partial<OptionsJson>
The options to override the default JSON Body Parser options with
OptionsJson
The combined JSON Body Parser options with the supplied values taking precedence over the default
### <a id="getLogger"></a>getLogger
function getLogger(minVerbosity?): Logger;
Returns a cached Winston-backed logger at the specified verbosity level.
LoggerVerbosity = 'info'
The minimum log level to output. Defaults to 'info'.
Logger
A logger instance configured for the given verbosity.
### <a id="getResponseMetadata"></a>getResponseMetadata
function getResponseMetadata(res): Record<string, unknown>;
Extracts response metadata from res.locals, computing profile duration if profiling was started.
Response
The Express response to extract metadata from.
Record<string, unknown>
The metadata record including any profiling information.
### <a id="isRawResponseFormatSet"></a>isRawResponseFormatSet
function isRawResponseFormatSet(res): boolean;
Checks if there are any flags on the response that would cause it to forgo the standard response envelope and return the raw response body to the client
Response
boolean
True if there are any flags on the response, false otherwise
### <a id="requestHandlerValidator"></a>requestHandlerValidator
function requestHandlerValidator<TParams, TQuery, TBody, TResponse>(schemas?): (handler) => RequestHandler;
Factory for Express middleware that validates request and response objects using Zod schemas.
TParams extends
| ZodObject<{
}, $catchall<ZodUnion<readonly [ZodString, ZodArray<ZodString>]>>>
| ZodType<Record<string, string>, unknown, $ZodTypeInternals<Record<string, string>, unknown>> = ZodObject<{
}, $catchall<ZodUnion<readonly [ZodString, ZodArray<ZodString>]>>>
TQuery extends
| ZodObject<{
}, $catchall<ZodUnion<readonly [ZodString, ZodArray<ZodString>]>>>
| ZodType<Record<string, string | string[]>, unknown, $ZodTypeInternals<Record<string, string | string[]>, unknown>> = ZodObject<{
}, $catchall<ZodUnion<readonly [ZodString, ZodArray<ZodString>]>>>
TBody extends ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>> = ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>
TResponse extends ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>> = ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>
Partial<{
body: TBody;
params: TParams;
query: TQuery;
response: TResponse;
}>
The Zod schemas to use for validation.
A middleware function for validating requests and responses.
(handler) => RequestHandler
### <a id="responseProfiler"></a>responseProfiler
function responseProfiler(
_req,
res,
next): void;
Connect middleware to enable profiling of response lifecycle timing. To effectively profile the response timing, this middleware needs to be called first when initializing your Express App
Request
The request
Response
The response
NextFunction
The next function
void
const app = express()
app.use(responseProfiler)
// other initialization ...
### <a id="setRawResponseFormat"></a>setRawResponseFormat
function setRawResponseFormat(res): void;
Flags the response to forgo the standard response envelope and return the raw response body to the client
Response
The response to disable the standard response format on
void
### <a id="standardErrors"></a>standardErrors
function standardErrors(
err,
req,
res,
next): void;
Express error handler that logs the error and sends a JSON:API-compliant error response.
ExpressError | undefined
The error to handle, or undefined if no error.
Request
The incoming request.
Response
The outgoing response.
NextFunction
The next middleware function.
void
### <a id="tryParse"></a>tryParse
function tryParse<T>(func, value?): T & object | undefined;
T = number
ParseFunc<T>
string
T & object | undefined
use zod instead
### <a id="useRequestCounters"></a>useRequestCounters
function useRequestCounters(app): void;
Registers middleware that increments per-path request counters and exposes a /stats endpoint.
Application
The Express application to attach counters to.
void
### interfaces
### <a id="ApiDataResponse"></a>ApiDataResponse
A successful JSON:API response containing primary data and optional included resources.
T extends ApiResourceIdentifierObject
optional jsonapi?: JsonApi;
optional links?: ApiLinks;
optional meta?: Record<string, unknown>;
data: T;
optional included?: ApiResourceObject[];
### <a id="ApiError"></a>ApiError
optional code?: string;
An application-specific error code, expressed as a string value.
optional detail?: string;
A human-readable explanation specific to this occurrence of the problem. Like title, this field's value can be localized.
optional id?: string;
A unique identifier for this particular occurrence of the problem.
optional links?: ApiLinks;
A links object containing the following members: about: a link that leads to further details about this particular occurrence of the problem
optional meta?: Record<string, unknown>;
A meta object containing non-standard meta-information about the error.
optional source?: Source;
An object containing references to the source of the error, optionally including any of the following members:
optional status?: string;
The HTTP status code applicable to this problem, expressed as a string value.
optional title?: string;
A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
### <a id="ApiErrorResponse"></a>ApiErrorResponse
A JSON:API error response containing one or more error objects.
optional jsonapi?: JsonApi;
optional links?: ApiLinks;
optional meta?: Record<string, unknown>;
errors: ApiError[];
### <a id="ApiResourceIdentifierObject"></a>ApiResourceIdentifierObject
Within a given API, each resource object's type and id pair MUST identify a single, unique resource. (The set of URIs controlled by a server, or multiple servers acting as one, constitute an API.)
id: string;
The id member is not required when the resource object originates at the client and represents a new resource to be created on the server.
type: string;
The type member is used to describe resource objects that share common attributes and relationships. The values of type members MUST adhere to the same constraints as member names.
### <a id="ApiResourceObject"></a>ApiResourceObject
A JSON:API resource object with optional attributes, links, meta, and relationships.
id: string;
The id member is not required when the resource object originates at the client and represents a new resource to be created on the server.
ApiResourceIdentifierObject.id
type: string;
The type member is used to describe resource objects that share common attributes and relationships. The values of type members MUST adhere to the same constraints as member names.
ApiResourceIdentifierObject.type
optional attributes?: Record<string, unknown>;
An attributes object representing some of the resource's data.
optional links?: ApiLinks;
A links object containing links related to the resource.
optional meta?: Record<string, unknown>;
A meta object containing non-standard meta-information about a resource that can not be represented as an attribute or relationship.
optional relationships?: Record<string, Relationship>;
A relationships object describing relationships between the resource and other JSON:API resources.
### <a id="ApiResponseBase"></a>ApiResponseBase
Base interface for all JSON:API responses, including optional links and metadata.
optional jsonapi?: JsonApi;
optional links?: ApiLinks;
optional meta?: Record<string, unknown>;
### <a id="Empty"></a>Empty
Empty object type used as a default for request/response body generics.
### <a id="ExpressError"></a>ExpressError
An Error with an optional HTTP status code for Express error handling.
Erroroptional statusCode?: number;
### <a id="HrefWithMeta"></a>HrefWithMeta
A link with an href and associated metadata.
href: string;
meta: Record<string, unknown>;
### <a id="IRelationshipData"></a>IRelationshipData
Contains the resource linkage data for a JSON:API relationship.
data: ResourceLinkage;
### <a id="IRelationshipLinks"></a>IRelationshipLinks
Contains the links for a JSON:API relationship.
links:
| IRelationshipSelfLink
| IRelationshipRelatedLink;
### <a id="IRelationshipRelatedLink"></a>IRelationshipRelatedLink
A relationship link pointing to a related resource.
related: string;
A related resource link
### <a id="IRelationshipSelfLink"></a>IRelationshipSelfLink
A relationship link pointing to the relationship itself.
self: string;
A link for the relationship itself (a "relationship link"). This link allows the client to directly manipulate the relationship. For example, removing an author through an article’s relationship URL would disconnect the person from the article without deleting the people resource itself. When fetched successfully, this link returns the linkage for the related resources as its primary data.
### <a id="JsonApi"></a>JsonApi
JSON:API version and metadata descriptor.
optional meta?: Record<string, unknown>;
optional version?: "1.0" | "1.1";
### <a id="LoggerOptions"></a>LoggerOptions
Configuration options for creating a logger instance.
optional defaultMeta?: LoggerMeta;
optional level?: LoggerVerbosity;
### <a id="RouteDefinition"></a>RouteDefinition
Defines an Express route with its HTTP method, path, and handler(s).
H extends RequestHandler = RequestHandler
handlers: H | H[];
method: HttpMethod;
path: string | RegExp;
### <a id="Source"></a>Source
An object containing references to the source of the error
optional parameter?: string;
A string indicating which URI query parameter caused the error.
optional pointer?: string;
A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].
### type-aliases
### <a id="ApiLink"></a>ApiLink
type ApiLink = string | HrefWithMeta;
A JSON:API link, either a simple URL string or an object with href and metadata.
### <a id="ApiLinks"></a>ApiLinks
type ApiLinks = Record<string, ApiLink>;
A collection of named JSON:API links.
### <a id="ApiResponse"></a>ApiResponse
type ApiResponse<T> =
| ApiDataResponse<T>
| ApiErrorResponse;
A JSON:API response, either a data response or an error response.
T extends ApiResourceIdentifierObject
### <a id="HttpMethod"></a>HttpMethod
type HttpMethod = "get" | "post" | "put" | "patch" | "delete" | "options" | "head";
Supported HTTP methods for route definitions.
### <a id="LogFunction"></a>LogFunction
type LogFunction = XyLabsLogFunction;
use from @xylabs/logger instead
### <a id="Logger"></a>Logger
type Logger = XyLabsLogger;
use from @xylabs/logger instead
### <a id="LoggerMeta"></a>LoggerMeta
type LoggerMeta = Record<string, string | number>;
Metadata key-value pairs attached to log entries.
### <a id="LoggerVerbosity"></a>LoggerVerbosity
type LoggerVerbosity = "error" | "warn" | "info" | "debug" | "all";
Application-level log verbosity levels.
### <a id="NoLocals"></a>NoLocals
type NoLocals = Record<string, any>;
Default type for response locals.
### <a id="NoReqBody"></a>NoReqBody
type NoReqBody = Empty;
Default type for request body when none is specified.
### <a id="NoReqParams"></a>NoReqParams
type NoReqParams = ParamsDictionary;
Default type for request route parameters.
### <a id="NoReqQuery"></a>NoReqQuery
type NoReqQuery = Query;
Default type for request query parameters.
### <a id="NoResBody"></a>NoResBody
type NoResBody = Empty;
Default type for response body when none is specified.
### <a id="ParseFunc"></a>ParseFunc
type ParseFunc<T> = (value) => T;
A function that parses a string value into the target type.
T = number
string
T
### <a id="Relationship"></a>Relationship
type Relationship =
| IRelationshipLinks
| IRelationshipData
| RelationshipMeta;
The value of the relationships key MUST be an object (a "relationships object"). Members of the relationships object ("relationships") represent references from the resource object in which it’s defined to other resource objects. Relationships may be to-one or to-many.
### <a id="RelationshipMeta"></a>RelationshipMeta
type RelationshipMeta = Record<string, unknown>;
Non-standard metadata associated with a JSON:API relationship.
### <a id="ResourceLinkage"></a>ResourceLinkage
type ResourceLinkage =
| null
| []
| ApiResourceIdentifierObject
| ApiResourceIdentifierObject[];
Resource linkage in a compound document allows a client to link together all of the included resource objects without having to GET any URLs via links. Resource linkage MUST be represented as one of the following: • null for empty to-one relationships. • an empty array ([]) for empty to-many relationships. • a single resource identifier object for non-empty to-one relationships. • an array of resource identifier objects for non-empty to-many relationships.
### variables
### <a id="DefaultJsonBodyParserOptions"></a>DefaultJsonBodyParserOptions
const DefaultJsonBodyParserOptions: OptionsJson;
The default options for the JSON Body Parser
### <a id="DefaultJsonBodyParserOptionsLimit"></a>DefaultJsonBodyParserOptionsLimit
const DefaultJsonBodyParserOptionsLimit: "100kb" = '100kb';
The default maximum request body size for the JSON Body Parser
### <a id="DefaultJsonBodyParserOptionsTypes"></a>DefaultJsonBodyParserOptionsTypes
const DefaultJsonBodyParserOptionsTypes: string[];
The default MIME types for the JSON Body Parser
### <a id="EmptyParamsZod"></a>EmptyParamsZod
const EmptyParamsZod: ZodObject<{
}, $catchall<ZodString>>;
Empty Zod schema for requests with no parameters.
### <a id="EmptyQueryParamsZod"></a>EmptyQueryParamsZod
const EmptyQueryParamsZod: ZodObject<{
}, $catchall<ZodUnion<readonly [ZodString, ZodArray<ZodString>]>>>;
Empty Zod schema for requests with no query parameters.
### <a id="ValidateRequestDefaults"></a>ValidateRequestDefaults
const ValidateRequestDefaults: object;
Default validation schemas for request handler validator.
params: ZodObject<{
}, $catchall<ZodString>> = EmptyParamsZod;
query: ZodObject<{
}, $catchall<ZodUnion<readonly [ZodString, ZodArray<ZodString>]>>> = EmptyQueryParamsZod;
body: ZodOptional<ZodJSONSchema>;
response: ZodOptional<ZodJSONSchema>;
### <a id="jsonBodyParser"></a>jsonBodyParser
const jsonBodyParser: NextHandleFunction;
A JSON Body Parser middleware handler initialized with the default options
### <a id="notImplemented"></a>notImplemented
const notImplemented: RequestHandler;
Express request handler that responds with a 501 Not Implemented error.
### <a id="standardResponses"></a>standardResponses
const standardResponses: RequestHandler;
Connect middleware to enable the transform of all responses to match the standard response format (compatible with JSON API)
FAQs
SDK for base code for Api repos that use express and deploy on AWS ECS
The npm package @xylabs/express receives a total of 399 weekly downloads. As such, @xylabs/express popularity was classified as not popular.
We found that @xylabs/express demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 5 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Socket found 37 malicious PyPI wheels that abuse Python startup hooks to launch a Bun-powered credential stealer tied to Mini Shai-Hulud/Miasma.
Security News
RubyGems and Bundler 4.0.13 introduced an opt-in cooldown feature that delays newly published gems during dependency resolution.
Security News
pnpm 11.5 now recognizes npm staged publish approvals in release metadata, preventing those releases from being mistaken for lower-trust package publishes.