Registry / devops / express-rest-decorators

express-rest-decorators

library1.0.0-rc.2jsnpmunverified

A decorator-based REST controller library for Express v5 (≥20.0.0) that provides a modernized, TypeScript-first alternative to legacy routing-controllers. Current version is 1.0.0-rc.2 — release candidate, still in development phase. Key differentiators: native async error handling leveraging Express 5, method-level input schemas using Standard Schema (validator-agnostic: supports Zod, Valibot, ArkType without adapters), and full TypeScript decorators with experimentalDecorators/emitDecoratorMetadata. No CommonJS or browser support. Requires `reflect-metadata` at runtime.

devops

npm install express-rest-decorators

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · EXPRESS-REST-DECOR

express-rest-decorators

devopsjavascriptv1.0.0-rc.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

JsonController

✓ import { JsonController } from 'express-rest-decorators'

✗ const { JsonController } = require('express-rest-decorators')

ESM-only; require() will throw. The package does not export a CommonJS build.

useExpressControllers

✓ import { useExpressControllers } from 'express-rest-decorators'

✗ import { UseExpressControllers } from 'express-rest-decorators'

The function is named with camelCase — capitalizing 'U' is a common typo from reading the docs.

✓ import { z } from 'zod'

✗ import z from 'zod'

Zod exports a named object `z`, not a default export. This mistake is common among developers used to default-import libraries.

reflect-metadata

✓ import 'reflect-metadata'

✗ import reflect from 'reflect-metadata'

reflect-metadata is a side-effect import — do not assign it to a variable. It must appear before any controller class is loaded.

Sets up a basic Express server with a JSON controller defining two endpoints: GET /users/:id and POST /users, using Zod for input validation.

import 'reflect-metadata'; import express from 'express'; import { z } from 'zod'; import { JsonController, Get, Post, useExpressControllers } from 'express-rest-decorators'; const UserSchema = z.object({ name: z.string(), email: z.string().email() }); @JsonController('/users') class UserController { @Get('/:id', { params: z.object({ id: z.coerce.number() }) }) getOne({ params }: { params: { id: number } }) { return { id: params.id, name: 'Ada' }; } @Post('/', { body: UserSchema }) create({ body }: { body: z.infer<typeof UserSchema> }) { return { id: 1, ...body }; } } const app = express(); app.use(express.json()); useExpressControllers(app, { controllers: [UserController] }); app.listen(3000, () => console.log('http://localhost:3000'));

Debug

Known issues

breakingThis library targets Express v5 only. Express v4 route handling semantics differ significantly (no automatic async error propagation, different middleware behavior).

fix

Ensure your project uses Express ^5.1.0. Downgrading to v4 will cause runtime errors in async handlers.

affects: >=1.0.0-rc.1

breakingMethod-level input schemas replace argument decorators from routing-controllers. Developer must define schemas in the method decorator options (e.g., @Post('/', { body: schema })) and receive a single typed input object.

fix

Migrate from routing-controllers by moving parameter decorators to the method decorator's schema options and restructuring the handler signature.

affects: >=1.0.0-rc.1

deprecatedExperimental decorators (`experimentalDecorators: true`) are required — this library does not yet support TC39 decorators proposal.

fix

Ensure tsconfig.json has experimentalDecorators: true and emitDecoratorMetadata: true. Also set useDefineForClassFields: false to avoid class field initialization issues.

affects: >=1.0.0-rc.1

gotchareflect-metadata must be imported exactly once in your application entry point, before any controller class is loaded. Missing this import causes 'Reflect.getMetadata is not a function' errors.

fix

Add `import 'reflect-metadata'` at the very top of your app's entry file (e.g., index.ts or server.ts). Do not import it multiple times.

affects: >=1.0.0-rc.1

gotchaValidator libraries (Zod, Valibot, ArkType) must implement StandardSchemaV1. Unsupported validators will silently fail validation.

fix

Use a supported library: Zod >=3.23, Valibot >=0.30, ArkType >=1.0. Ensure the version implements the Standard Schema interface.

affects: >=1.0.0-rc.1

Errors

Common errors & fixes

Error: Reflect.getMetadata is not a function

reflect-metadata import missing or placed after controller class definition.

fix

Add `import 'reflect-metadata'` as the first import in your entry file.

TypeError: express_rest_decorators_1.JsonController is not a constructor

Using a default import instead of named import.

fix

Use `import { JsonController } from 'express-rest-decorators'` instead of `import JsonController from 'express-rest-decorators'`.

SyntaxError: Unexpected token '@' — decorators are not supported

TypeScript experimentalDecorators option not enabled or running the code with Node.js directly without compilation.

fix

Add `"experimentalDecorators": true` and `"emitDecoratorMetadata": true` to tsconfig.json, then compile with tsc before running.

ValidationError: Expected object, received array

The schema expects an object but the route handler's input (params/query/body) is an array, often due to misconfigured route or middleware.

fix

Double-check the route path and schema definition. Ensure middleware like express.json() is applied before useExpressControllers (for body parsing) and that the request has proper Content-Type.

Error: Cannot find module 'express'

Express not installed or installed as a dev dependency but missing in node_modules at runtime.

fix

Install express as a regular dependency: `npm install express` or `pnpm add express`. Ensure it's listed in dependencies, not devDependencies.

Upgrade

Version history

1.0.0-rc.2latest on npm

Audit

Dependencies

expressrequiredPeer dependency — requires Express v5 (^5.1.0) for async error handling and HTTP primitives

reflect-metadatarequiredRequired at runtime for decorator metadata reflection — import once at application entry point

multeroptionalPeer dependency — file upload handling (^2.0.0), needed for multipart/form-data routes

zodoptionalCommonly used validation library (Standard Schema), but any validator implementing StandardSchemaV1 works — optional dependency

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/nirajk77777/express-rest-decorators ↗

packageexpress-rest-decorators ↗

homepagehttps://github.com/nirajk77777/express-rest-decorators#readme ↗