TypeSpec HTTP server code generator for JavaScript and TypeScript.
This package generates an implementation of an HTTP server layer for a TypeSpec API. It supports binding directly to a Node.js HTTP server or Express.js application.
npm install @typespec/http-server-js- Via the command line
tsp compile . --emit=@typespec/http-server-js- Via the config
emit:
- "@typespec/http-server-js"Type: boolean
If set to true, the emitter will generate a router that exposes an Express.js middleware function in addition to the
ordinary Node.js HTTP server router.
If this option is not set to true, the expressMiddleware property will not be present on the generated router.
Type: boolean
By default, the emitter will create interfaces that represent all models in the service namespace. If this option is set
to true, the emitter will only emit those types that are reachable from an HTTP operation.
Type: boolean
If set to true, the emitter will not format the generated code using Prettier.
The emitter generates a few major components:
The highest-level component that your code interacts with directly is the router implementation.
@typespec/http-server-js generates a static router that you can bind to an implementation of an HTTP server.
The router is generated in the http/router.js module within the output directory. Each service will have its own
router implementation named after the service. For example, given a service namespace named Todo, the router module
will export a function createTodoRouter. This function creates an instance of a router that dispatches methods within
the Todo service.
import { createTodoRouter } from "../tsp-output/@typespec/http-server-js/http/router.js";
const router = createTodoRouter(users, todoItems, attachments);As arguments, the createTodoRouter function expects implementations of the underlying service interfaces. These
interfaces are explained further in the next section.
Once the router is created, it is bound to an instance of the HTTP server. The router's dispatch method implements the
Node.js event handler signature for the request event on a Node.js HTTP server.
const server = http.createServer();
server.on("request", router.dispatch);
server.listen(8080, () => {
console.log("Server listening on http://localhost:8080");
});Alternatively, the router can be used with Express.js instead of the Node.js HTTP server directly. If the express
feature is enabled in the emitter options, the router will expose an expressMiddleware property that implements the
Express.js middleware interface.
import express from "express";
const app = express();
app.use(router.expressMiddleware);
app.listen(8080, () => {
console.log("Server listening on http://localhost:8080");
});The emitter generates interfaces for each collection of service methods that exists in the service namespace. Implementations of these interfaces are required to instantiate the router. When the router processes an HTTP request, it will call the appropriate method on the service implementation after determining the route and method.
For example, given the following TypeSpec namespace Users within the Todo service:
namespace Users {
@route("/users")
@post
op create(
user: User,
): WithStandardErrors<UserCreatedResponse | UserExistsResponse | InvalidUserResponse>;
}The emitter will generate a corresponding interface Users within the module models/all/todo/index.js in the output
directory.
/** An interface representing the operations defined in the 'Todo.Users' namespace. */
export interface Users<Context = unknown> {
create(
ctx: Context,
user: User,
): Promise<
| UserCreatedResponse
| UserExistsResponse
| InvalidUserResponse
| Standard4XxResponse
| Standard5XxResponse
>;
}An object implementing this Users interface must be passed to the router when it is created. The Context type
parameter represents the underlying protocol or framework-specific context that the service implementation may inspect.
If you need to access the HTTP request or response objects directly in the implementation of the service methods, you
must use the HttpContext type as the Context argument when implementing the service interface. Otherwise, it is safe
to use the default unknown argument.
import { HttpContext } from "../tsp-output/@typespec/http-server-js/helpers/router.js";
import { Users } from "../tsp-output/@typespec/http-server-js/models/all/todo/index.js";
export const users: Users<HttpContext> = {
async create(ctx, user) {
// Implementation
},
};The emitter generates TypeScript interfaces that represent the model types used in the service operations. This allows the service implementation to interact with the data structures carried over the HTTP protocol in a type-safe manner.
While your code should never need to interact with these functions directly, the emitter generates a function per HTTP operation that handles the parsing and validation of the request contents. This allows the service implementation to be written in terms of ordinary TypeScript types and values rather than raw HTTP request and response objects. In general:
- The Node.js HTTP server or Express.js application (your code) calls the router (generated code), which determines which service operation function (generated code) to call based on the route, method, and other HTTP metadata in the case of shared routes.
- The operation function (generated code) deserializes the request body, query parameters, and headers into TypeScript types, and may perform request validation.
- The operation function (generated code) calls the service implementation (your code) with the deserialized request data.
- The service implementation (your code) returns a result or throws an error.
- The operation function (generated code) responds to the HTTP request on your behalf, converting the result or error into HTTP response data.