TypeScript REST API Library

Common errors

• ReferenceError: Reflect is not defined

  cause The `reflect-metadata` polyfill was not loaded, which is required by TypeScript's `emitDecoratorMetadata` feature.
  fix Install `reflect-metadata` (`npm install reflect-metadata`) and add `import 'reflect-metadata';` once at the very top of your application's entry file (e.g., `server.ts` or `app.ts`).

• Decorator '...' is not a valid decorator factory.

  cause The TypeScript compiler option `experimentalDecorators` is not enabled, preventing the use of decorator syntax.
  fix In your `tsconfig.json`, add `"experimentalDecorators": true` to the `compilerOptions` section.

• Error: Can't set headers after they are sent to the client.

  cause This is a common Express.js error, often occurring when an asynchronous operation or error handler attempts to send a response after one has already been sent (e.g., by a decorator, another middleware, or a prior `res.send`/`res.json` call).
  fix Ensure that your API methods and middleware handle responses exactly once. For asynchronous operations, ensure you `await` promises. If using custom error handlers, make sure they only attempt to send a response if one hasn't already been sent, or pass control to the next error handler using `next(err)`.

• Argument of type 'string | undefined' is not assignable to parameter of type 'string'.

  cause This TypeScript error often occurs when a decorated parameter (e.g., `@QueryParam('id') id: string`) might implicitly be `undefined` or `null` if the client doesn't provide it, but the method parameter expects a non-nullable type.
  fix Make the parameter type explicit to allow `undefined` or provide a default value. For example, change `id: string` to `id?: string` or `id: string = 'default_value'`.

Warnings

• breaking Upgrading from `typescript-rest` v2.x to v3.x may introduce breaking changes. Always consult the official changelog or migration guide before a major version upgrade to understand specific API changes.
  Fix: Review the project's GitHub releases and Wiki for detailed migration instructions and API changes between major versions.
• gotcha TypeScript's experimental decorators (`experimentalDecorators: true` in tsconfig.json) are required for `typescript-rest` to function. Additionally, `emitDecoratorMetadata: true` and `reflect-metadata` (imported once globally) are essential for advanced features like dependency injection and proper type reflection.
  Fix: Add `"experimentalDecorators": true, "emitDecoratorMetadata": true` to your `compilerOptions` in `tsconfig.json`. Install `reflect-metadata` (`npm install reflect-metadata`) and import it once at your application's entry point (`import 'reflect-metadata';`).
• gotcha TypeScript 5.0 introduced a new, standardized decorators implementation. `typescript-rest` currently relies on TypeScript's 'legacy' or 'experimental' decorators. Mixing these with native TS 5+ decorators or failing to configure `tsconfig.json` correctly for legacy decorators can lead to unexpected behavior or compilation errors.
  Fix: Ensure your `tsconfig.json` explicitly enables `experimentalDecorators: true`. If targeting Node.js, `"target": "es6"` or newer is recommended. Be aware that the `experimentalDecorators` flag will eventually be deprecated by TypeScript, potentially requiring future migration.
• gotcha Error handling in `typescript-rest` relies on Express.js middleware. Custom error handling middleware should be registered *after* `Server.buildServices(app)` to catch errors thrown by the REST services. Incorrect ordering can result in unhandled exceptions or generic 500 responses.
  Fix: Implement custom error handling middleware in Express, ensuring it's defined and registered after `Server.buildServices(app)` in your application setup. Example: `app.use((err: any, req: express.Request, res: express.Response, next: express.NextFunction) => { /* handle error */ });`

Install

• npm install typescript-rest npm
• yarn add typescript-rest yarn
• pnpm add typescript-rest pnpm

Imports

• Server
  wrong:

  import Server from 'typescript-rest';

  correct:

  import { Server } from 'typescript-rest';

  The primary entry point for registering decorated service classes with an Express application. It is a named export, not a default export.
• Path
  wrong:

  const Path = require('typescript-rest').Path;

  correct:

  import { Path, GET, PathParam } from 'typescript-rest';

  Decorators like `Path`, `GET`, `POST`, `PathParam`, etc., are named exports. Ensure TypeScript compiler options `experimentalDecorators` and `emitDecoratorMetadata` are set to `true`.
• express.Application
  wrong:

  import express from 'express';

  correct:

  import * as express from 'express';

  While `import express from 'express';` often works with `esModuleInterop: true`, `import * as express from 'express';` is a more robust import style for the Express module in TypeScript projects to correctly handle its CommonJS export structure.

Quickstart

Demonstrates defining a simple REST endpoint using decorators (`@Path`, `@GET`, `@PathParam`) and integrating it with an Express application.

import * as express from "express";
import { Server, Path, GET, PathParam } from "typescript-rest";

// Ensure you have 'npm install reflect-metadata' and import it once globally if using IoC/complex types with decorators:
// import 'reflect-metadata'; 

@Path("/hello")
class HelloService {
  @Path(":name")
  @GET
  sayHello( @PathParam('name') name: string ): string {
    return "Hello " + name;
  }
}

let app: express.Application = express();

// Build and register all decorated services with the Express app
Server.buildServices(app);

app.listen(3000, function() {
  console.log('typescript-rest server listening on port 3000!');
  console.log('Try: GET http://localhost:3000/hello/john_doe');
});