Skip to main content

QExpressEngine

@quik/http-express

@quik/http-express / QExpressEngine

Class: QExpressEngine

Defined in: http-express/src/QExpressEngine.ts:24

Implementation of IQHTTPEngine using Express.

Extends​

  • QHTTPEngine

Implements​

  • IQHTTPEngine

Constructors​

Constructor​

new QExpressEngine(): QExpressEngine

Defined in: http-express/src/QExpressEngine.ts:51

Initializes the Express application and default middlewares.

Returns​

QExpressEngine

Overrides​

QHTTPEngine.constructor

Properties​

_connections​

protected _connections: Set<Socket>

Defined in: http-express/src/QExpressEngine.ts:165

_express​

protected _express: Application

Defined in: http-express/src/QExpressEngine.ts:151

Instance of the Express application.

_router​

protected _router: Router

Defined in: http-express/src/QExpressEngine.ts:164

Internal Express router used to register all endpoints. All routes and endpoints are registered on this router instance.

_server​

protected _server: Server

Defined in: http/src/engine/QHTTPEngine.ts:25

Instance of the node:http server.

Inherited from​

QHTTPEngine._server

_setupCompleted​

protected _setupCompleted: boolean = false

Defined in: http/src/engine/QHTTPEngine.ts:18

Inherited from​

QHTTPEngine._setupCompleted

Accessors​

engine​

Get Signature​

get engine(): string

Defined in: http-express/src/QExpressEngine.ts:144

Name of the underlying HTTP engine.

Returns​

string

Implementation of​

IQHTTPEngine.engine

Overrides​

QHTTPEngine.engine

express​

Get Signature​

get express(): Application

Defined in: http-express/src/QExpressEngine.ts:156

Returns the Express application instance.

Returns​

Application

host​

Get Signature​

get host(): string

Defined in: http/src/engine/QHTTPEngine.ts:51

Lists the host on which we expose the server.

Returns​

string

Implementation of​

IQHTTPEngine.host

Inherited from​

QHTTPEngine.host

isListening​

Get Signature​

get isListening(): boolean

Defined in: http/src/engine/QHTTPEngine.ts:37

Flag to let the user know that the server was started and listening for connections.

Returns​

boolean

Implementation of​

IQHTTPEngine.isListening

Inherited from​

QHTTPEngine.isListening

isSetupCompleted​

Get Signature​

get protected isSetupCompleted(): boolean

Defined in: http/src/engine/QHTTPEngine.ts:55

Returns​

boolean

Inherited from​

QHTTPEngine.isSetupCompleted

logger​

Get Signature​

get protected logger(): IQLogger

Defined in: core/src/QObject.ts:15

The logger getter for the object.

Returns​

IQLogger

Inherited from​

QHTTPEngine.logger

name​

Get Signature​

get name(): string

Defined in: core/src/QObject.ts:8

Returns​

string

Inherited from​

QHTTPEngine.name

port​

Get Signature​

get port(): number

Defined in: http/src/engine/QHTTPEngine.ts:44

Lists the port on which we expose the server.

Returns​

number

Implementation of​

IQHTTPEngine.port

Inherited from​

QHTTPEngine.port

router​

Get Signature​

get protected router(): Router

Defined in: http-express/src/QExpressEngine.ts:170

Returns the Express router instance.

Returns​

Router

server​

Get Signature​

get server(): Server

Defined in: http/src/engine/QHTTPEngine.ts:30

Getter for the node:http server.

Returns​

Server

Implementation of​

IQHTTPEngine.server

Inherited from​

QHTTPEngine.server

staticContentDefinition​

Get Signature​

get protected staticContentDefinition(): QStaticContent

Defined in: http/src/engine/QHTTPEngine.ts:59

Returns​

QStaticContent

Inherited from​

QHTTPEngine.staticContentDefinition

Methods​

addResponseSpanAttributes()​

protected addResponseSpanAttributes(span, response): void

Defined in: http/src/engine/QHTTPEngine.ts:275

Add response metadata to the telemetry span when available.

Parameters​

span​

TelemetrySpan

response​

IQResponse

Returns​

void

Inherited from​

QHTTPEngine.addResponseSpanAttributes

close()​

protected close(): Promise<void>

Defined in: http-express/src/QExpressEngine.ts:195

Closes the underlying HTTP server.

Returns​

Promise<void>

Overrides​

QHTTPEngine.close

defaultErrorHandler()​

protected defaultErrorHandler(serverError, translate?): IQErrorResponse

Defined in: http/src/engine/QHTTPEngine.ts:148

Default error handler used when the engine fails processing a request.

Parameters​

serverError​

Error

The thrown error instance.

translate?​

QTranslatorFunction

Optional translation function.

Returns​

IQErrorResponse

Inherited from​

QHTTPEngine.defaultErrorHandler

endRequestSpan()​

protected endRequestSpan(span?): void

Defined in: http/src/engine/QHTTPEngine.ts:314

End the telemetry span when available.

Parameters​

span?​

TelemetrySpan

Returns​

void

Inherited from​

QHTTPEngine.endRequestSpan

endSpan()​

protected endSpan(span): void

Defined in: core/src/QObject.ts:35

End a span returned by startSpan.

Parameters​

span​

TelemetrySpan

The span to end.

Returns​

void

Inherited from​

QHTTPEngine.endSpan

eventEndpoint()​

protected eventEndpoint(props): Promise<void>

Defined in: http-express/src/QExpressEngine.ts:492

Executes a server-events endpoint and establishes a Server-Sent Events (SSE) connection. Connects the client to the specified event channel using the route's connect method.

Parameters​

props​

QEndpointCallingParameters<QServerEventRoute, Request<ParamsDictionary, any, any, ParsedQs, Record<string, any>>, Response<any, Record<string, any>>, NextFunction>

Endpoint calling parameters containing request, response, and endpoint metadata

Returns​

Promise<void>

execute()​

protected execute(event, route, endpoint): Promise<IQResponse<any>>

Defined in: http/src/engine/QHTTPEngine.ts:226

Parameters​

event​

QEvent

route​

QRoute

endpoint​

IQEndpointDefinition

Returns​

Promise<IQResponse<any>>

Inherited from​

QHTTPEngine.execute

executeEndpoint()​

protected executeEndpoint(props): Promise<void>

Defined in: http-express/src/QExpressEngine.ts:433

Executes an HTTP endpoint and writes the response back to the client via Express. Handles different response types including redirects, file downloads, and JSON responses.

Parameters​

props​

QEndpointCallingParameters<QRoute, Request<ParamsDictionary, any, any, ParsedQs, Record<string, any>>, Response<any, Record<string, any>>, NextFunction>

Endpoint calling parameters containing request, response, and endpoint metadata

Returns​

Promise<void>

getPath()​

protected getPath(...pathElements): string

Defined in: http/src/engine/QHTTPEngine.ts:222

Join multiple path elements using the framework utility.

Parameters​

pathElements​

...string[]

Returns​

string

Inherited from​

QHTTPEngine.getPath

getSinglePageApplicationFallbackMiddleware()​

protected getSinglePageApplicationFallbackMiddleware(indexFilePath): (request, response, next) => void

Defined in: http-express/src/QExpressEngine.ts:338

Build the middleware responsible for serving the SPA entry point.

Parameters​

indexFilePath​

string

Absolute path to the HTML entry file.

Returns​

(request, response, next) => void

listen()​

protected listen(): Promise<void>

Defined in: http-express/src/QExpressEngine.ts:256

Starts listening for incoming connections.

Returns​

Promise<void>

Overrides​

QHTTPEngine.listen

recordRequestSpanError()​

protected recordRequestSpanError(span, err): void

Defined in: http/src/engine/QHTTPEngine.ts:325

Record an error on the telemetry span when available.

Parameters​

span​

TelemetrySpan

err​

unknown

Returns​

void

Inherited from​

QHTTPEngine.recordRequestSpanError

recordSpanError()​

protected recordSpanError(span, err): void

Defined in: core/src/QObject.ts:45

Record an exception on an active span.

Parameters​

span​

TelemetrySpan

The span to record the error on.

err​

unknown

The error to record.

Returns​

void

Inherited from​

QHTTPEngine.recordSpanError

registerEndpoint()​

protected registerEndpoint(route, endpoint): Promise<void>

Defined in: http-express/src/QExpressEngine.ts:407

Registers a single endpoint handler on the Express router. Maps the HTTP verb and path to the corresponding endpoint handler, and applies route and endpoint specific middlewares.

Parameters​

route​

QRoute

The parent route instance containing middleware and path information

endpoint​

IQEndpointDefinition

Endpoint definition metadata with verb, path, and handler information

Returns​

Promise<void>

Overrides​

QHTTPEngine.registerEndpoint

registerErrorHandler()​

protected registerErrorHandler(): Promise<void>

Defined in: http-express/src/QExpressEngine.ts:385

Registers the default error handler middleware on the Express application. Adds two middlewares:

  1. A 404 handler that catches unmatched routes
  2. A general error handler that formats errors according to the application standards

Returns​

Promise<void>

Overrides​

QHTTPEngine.registerErrorHandler

registerRoute()​

protected registerRoute(route): void

Defined in: http/src/engine/QHTTPEngine.ts:202

Register all endpoints associated with a route.

Parameters​

route​

QRoute

The route being registered.

Returns​

void

Inherited from​

QHTTPEngine.registerRoute

registerRoutes()​

protected registerRoutes(): void

Defined in: http/src/engine/QHTTPEngine.ts:187

Register all routes available in the router.

Returns​

void

Inherited from​

QHTTPEngine.registerRoutes

registerSinglePageApplicationFallback()​

protected registerSinglePageApplicationFallback(): void

Defined in: http-express/src/QExpressEngine.ts:312

Registers a history-API fallback for SPA frontends served from static content. Only HTML navigation requests are rewritten to the configured index file.

Returns​

void

registerStaticContent()​

protected registerStaticContent(): Promise<void>

Defined in: http-express/src/QExpressEngine.ts:275

Registers static content folders defined in the configuration. Supports both global static content and path-specific static content directories. Uses Express's static middleware to serve files from the filesystem.

Returns​

Promise<void>

Overrides​

QHTTPEngine.registerStaticContent

reload()​

reload(): Promise<void>

Defined in: http/src/engine/QHTTPEngine.ts:108

Stop the server, re-register all routes and static content, then restart listening. The error handler registered at startup is preserved across reloads.

Returns​

Promise<void>

Implementation of​

IQHTTPEngine.reload

Inherited from​

QHTTPEngine.reload

reset()​

protected reset(): void

Defined in: http-express/src/QExpressEngine.ts:178

Replace the Express router with a fresh instance and create a new Server. The existing Express app and all one-time middleware (error handler, i18n, etc.) are preserved.

Returns​

void

Overrides​

QHTTPEngine.reset

setSpanAttribute()​

protected setSpanAttribute(span, key, value): void

Defined in: core/src/QObject.ts:64

Set a single attribute on an active span.

Parameters​

span​

TelemetrySpan

The span to update.

key​

string

Attribute key.

value​

string | number | boolean

Attribute value.

Returns​

void

Inherited from​

QHTTPEngine.setSpanAttribute

setupCompleted()​

protected setupCompleted(): void

Defined in: http/src/engine/QHTTPEngine.ts:100

Mark the setup process as completed.

Returns​

void

Inherited from​

QHTTPEngine.setupCompleted

shouldServeSinglePageApplicationFallback()​

protected shouldServeSinglePageApplicationFallback(request): boolean

Defined in: http-express/src/QExpressEngine.ts:358

Decide whether a request should be rewritten to the SPA entry file.

Parameters​

request​

Request

Incoming Express request.

Returns​

boolean

start()​

start(): Promise<void>

Defined in: http/src/engine/QHTTPEngine.ts:66

Start the HTTP server and register routes when needed.

Returns​

Promise<void>

Implementation of​

IQHTTPEngine.start

Inherited from​

QHTTPEngine.start

startRequestSpan()​

protected startRequestSpan(route, endpoint): TelemetrySpan

Defined in: http/src/engine/QHTTPEngine.ts:260

Start a telemetry span for the request pipeline when available.

Parameters​

route​

QRoute

endpoint​

IQEndpointDefinition

Returns​

TelemetrySpan

Inherited from​

QHTTPEngine.startRequestSpan

startSpan()​

protected startSpan(spanName, options?): TelemetrySpan

Defined in: core/src/QObject.ts:26

Start a telemetry span for the given operation name. Returns undefined when no telemetry provider is active.

Parameters​

spanName​

string

Name of the span.

options?​

TelemetrySpanOptions

Optional span attributes and kind.

Returns​

TelemetrySpan

Inherited from​

QHTTPEngine.startSpan

stop()​

stop(): Promise<void>

Defined in: http/src/engine/QHTTPEngine.ts:87

Stop the HTTP server.

Returns​

Promise<void>

Implementation of​

IQHTTPEngine.stop

Inherited from​

QHTTPEngine.stop

setSessionStore()​

static setSessionStore(store): void

Defined in: http-express/src/QExpressEngine.ts:44

Configure the session store used by all Express engine instances. Must be called before the engine is instantiated (i.e. before the HTTP module boots).

Parameters​

store​

Store

An express-session compatible store (e.g. connect-redis, connect-pg-simple).

Returns​

void

Example​

import RedisStore from "connect-redis";
import { createClient } from "redis";
import { QExpressEngine } from "@quik/http-express";

const client = createClient();
await client.connect();
QExpressEngine.setSessionStore(new RedisStore({ client }));