express-cargo

express-cargo is a middleware library for Express.js that makes handling request data easier and more type-safe. It provides class-based decorators and binding features to simplify complex request parsing and validation.

Installation

npm install express-cargo reflect-metadata

TypeScript Configuration

express-cargo uses TypeScript decorators and runtime type metadata. To use it properly, you need to install TypeScript and enable a few compiler options.

1. Install TypeScript (if not already installed)

npm install -D typescript

2. Enable Decorator Support

Add the following settings to your tsconfig.json:

{
    "compilerOptions": {
        "experimentalDecorators": true,
        "emitDecoratorMetadata": true
    }
}

Quick Start

import express from 'express'
import { Body, bindingCargo, getCargo, Min, Header, Params } from 'express-cargo'

const app = express()
app.use(express.json())

class RequestExample {
    @Body()
    name!: string

    @Body()
    @Min(0)
    age!: number

    @Params('id')
    id!: number

    @Header()
    authorization!: string
}

app.post('/:id', bindingCargo(RequestExample), (req, res) => {
    const data = getCargo<RequestExample>(req)
    // write your code with bound data
})

app.listen(3000)

Documentation

Full guide and API reference:
👉 express-cargo Documentation

Features

Class-based request parsing: Automatically bind request data (body, query, params, etc.) using decorators
Type safety: Fully compatible with TypeScript
Easy middleware integration: Seamlessly works with existing Express middleware

Binding Decorators

Decorator	Description	Example
`@Body()`	Binds a field from `req.body`	`@Body() name: string`
`@Query()`	Binds a field from `req.query`	`@Query() page: number`
`@Params()`	Binds a field from `req.params`	`@Params() id: string`
`@Uri()`	alias of `@Params()`	`@Uri() id: string`
`@Header()`	Binds a field from `req.headers`	`@Header() token: string`
`@Session()`	Binds a field from `req.session`	`@Session() userId: string`
`@UploadedFile()`	Binds a single uploaded file from a `multipart/form-data` request	`@UploadedFile() avatar: Express.Multer.File`
`@UploadedFiles()`	Binds all uploaded files sharing a field name as an array	`@UploadedFiles() photos: Express.Multer.File[]`

File binding needs a multipart parser (e.g. multer) to run before bindingCargo. See File Upload Decorators for details.

Validation Decorators

Decorator	Description	Example
`@Min(minimum: number)`	Number must be greater than or equal to `minimum`.	`@Min(18) age!: number`
`@Max(maximum: number)`	Number must be less than or equal to `maximum`.	`@Max(100) score!: number`
`@Range(min: number, max: number)`	Number must be between `min` and `max` (inclusive).	`@Range(1, 5) rating!: number`
`@Contains(seed: string)`	String must contain `seed`.	`@Contains('hello') greeting!: string`
`@Prefix(prefixText: string)`	String must start with `prefixText`.	`@Prefix('IMG_') fileName!: string`
`@Suffix(suffixText: string)`	String must end with `suffixText`.	`@Suffix('.jpg') fileName!: string`
`@Length(value: number)`	String length must be exactly `value`.	`@Length(6) otp!: string`
`@MinLength(min: number)`	String length must be greater than or equal to `min`.	`@MinLength(8) password!: string`
`@MaxLength(max: number)`	String length must be less than or equal to `max`.	`@MaxLength(20) username!: string`
`@Equal(value: any)`	Value must be strictly equal to `value`.	`@Equal('production') env!: string`
`@NotEqual(value: any)`	Value must not be equal to `value`.	`@NotEqual('admin') role!: string`
`@IsTrue()`	Value must be `true`.	`@IsTrue() acceptedTerms!: boolean`
`@IsFalse()`	Value must be `false`.	`@IsFalse() blocked!: boolean`
`@OneOf(options: readonly any[])`	Value must be one of `options`.	`@OneOf(['credit','debit'] as const) method!: 'credit' \| 'debit'`
`@ListContains(values: any[], comparator?: (expected, actual) => boolean)`	The array must contain all specified values. When `comparator` is provided, all comparisons are delegated to it.	`@ListContains([1, 2]) nums!: number[]` `@ListContains(['a'], (e, a) => a.toLowerCase() === e) strs!: string[]`
`@ListNotContains(values: any[], comparator?: (expected, actual) => boolean)`	The array must NOT contain any of the specified values. When `comparator` is provided, all comparisons are delegated to it.	`@ListNotContains([1, 2]) nums!: number[]` `@ListNotContains(['a'], (e, a) => a.toLowerCase() === e) strs!: string[]`
`@ListMaxSize(max: number, message?)`	The array must contain no more than `max` elements.	`@ListMaxSize(5) tags!: string[]`
`@ListMinSize(min: number, message?)`	The array must contain at least `min` elements.	`@ListMinSize(5) tags!: string[]`
`@Each(...args: (Validator \| Function)[])`	Applies validation rules to every individual element within an array. Wraps validation decorators only.	`@Each(Length(10)) tags!: string[]`
`@Validate(validateFn, message?)`	Custom validation function.	`@Validate(v => typeof v === 'string' && v.includes('@'), 'invalid email') email!: string`
`@Regexp(pattern: RegExp, message?)`	String must match the given regular expression.	`@Regexp(/^[0-9]+$/, 'digits only') phone!: string`
`@Email()`	String must be email format.	`@Email() email!: string`
`@Uuid(version?, message?)`	Validates that the field is a valid UUID, optionally restricted to a specific version (v1, v3, v4, or v5).	`@Uuid('v4') requestId!: string`
`@Alpha(message?: string)`	Validates that the field contains alphabetic characters (A–Z, a–z) only.	`@Alpha() firstName!: string`
`@Alphanumeric(message?: string)`	Validates that the field contains alphanumeric characters (A-Z, a-z, 0-9) only.	`@Alphanumeric() productCode!: string`
`@IsUppercase(message?: string)`	Validates that the field contains only uppercase characters.	`@IsUppercase() countryCode!: string`
`@IsLowercase(message?: string)`	Validates that the field contains only lowercase characters.	`@IsLowercase() username!: string`
`@IsJwt(message?: string)`	Validates that the field is a valid JSON Web Token (JWT) in `header.payload.signature` format using Base64URL characters.	`@IsJwt() accessToken!: string`
`@IsUrl(options?: IsUrlOptions, message?: string)`	Validates that the field is a valid URL. `http`, `https`, and `ftp` protocols are allowed by default. Use `options.protocols` to customize allowed protocols.	`@IsUrl() website!: string`
`@IsPhoneNumber(region?: CountryCode, message?: string)`	Validates that the field is a valid phone number using libphonenumber-js. Supports all countries. With a region, local formats are accepted.	`@IsPhoneNumber('KR') phone!: string`
`@IsTimeZone(message?: string)`	Validates that the field is a valid IANA timezone identifier (e.g., `Asia/Seoul`, `UTC`). Uses the built-in `Intl` API.	`@IsTimeZone() tz!: string`
`@IsHexColor(message?: string)`	Validates that the field is a valid hex color code. Supports `#RGB`, `#RGBA`, `#RRGGBB`, and `#RRGGBBAA` formats (case-insensitive). The `#` prefix is required.	`@IsHexColor() color!: string`
`@IsHexadecimal(message?: string)`	Validates that the field is a hexadecimal number (characters `0-9` and `a-f`, case-insensitive). The `0x` prefix is also allowed.	`@IsHexadecimal() color!: string`
`@IsHash(algorithm: HashAlgorithm, message?: string)`	Validates that the field is a valid hash string for the given algorithm. Supported: `md5`, `sha1`, `sha256`, `sha384`, `sha512`, `crc32`, `crc32b`.	`@IsHash('sha256') checksum!: string`
`@MinDate(min: Date \| (() => Date), message?: string)`	Validates that the field is a `Date` on or after the given minimum date. Accepts a fixed date or a function for dynamic comparison.	`@MinDate(new Date('2000-01-01')) createdAt!: Date`
`@MaxDate(max: Date \| (() => Date), message?: string)`	Validates that the field is a `Date` on or before the given maximum date. Accepts a fixed date or a function for dynamic comparison.	`@MaxDate(new Date('2099-12-31')) createdAt!: Date`
`@With(fieldName: string)`	Validates that if the decorated field has a value, the specified target field (fieldName) must also have a value, establishing a mandatory dependency.	`@With('price') discountRate?: number`
`@Without(fieldName: string)`	Validates that if the decorated field has a value, the specified target field (fieldName) must NOT have a value, establishing a mutually exclusive relationship.	`@Without('isGuest') password?: string`

Transform Decorators

Decorator	Description	Example
`@Transform(transformer)`	Transform the parsed value	`@Transform(v => v.trim()) name!: string`
`@Request<T>(transformer)`	Extract value from Express Request object	`@Request<object>(req => req.user!) user!: object`
`@Virtual(transformer)`	Compute value from other fields	`@Virtual(obj => obj.firstName + ' ' + obj.lastName) fullName!: string`

Binding Order and Priority

bindingCargo() fills each request object in a fixed order. This matters when a field uses a transformer or when a computed field depends on other fields.

When the Value Exists

The @Request() decorator runs first. Its transformer receives the raw Express Request object and bypasses source lookup and built-in type casting.
Source decorators run next: @Body(), @Query(), @Params(), @Uri(), @Header(), and @Session(). The value is read from the selected request source, type-cast to the declared property type, passed through @Transform() when present, and then validated.
The @Virtual() decorator runs last. Its transformer receives the request object after request and source fields have been bound.

Passport.js Example

Passport sets the authenticated user on req.user. Run Passport authentication before bindingCargo(), then bind that object with @Request<object>.

import passport from 'passport'
import { Request, bindingCargo, getCargo } from 'express-cargo'

class PassportRequest {
    @Request<object>(req => req.user!)
    user!: object
}

app.get('/passport', passport.authenticate('bearer', { session: false }), bindingCargo(PassportRequest), (req, res) => {
    const cargo = getCargo<PassportRequest>(req)
    res.json(cargo)
})

@Request assigns req.user as-is without built-in type casting. Use an application-specific type instead of object when code needs access to fields such as user.id.

class OrderRequest {
    @Body()
    price!: number

    @Body()
    quantity!: number

    @Virtual((order: OrderRequest) => order.price * order.quantity)
    total!: number
}

In this example, price and quantity are bound before total is computed.

When the Value Is Missing

When a value is undefined or null, express-cargo handles it in this order:

@Default(value) uses the default value.
@Optional() sets the property to null.
If neither is present, a required-field error is added.

After a missing value is handled by one of these paths, the remaining transform and validation steps for that field are skipped.

Type Helper Decorators

Decorator	Description	Example
`@Type(typeFn, options?)`	Specifies the class used to transform raw data. Supports dynamic class resolution and resolves circular dependencies.	`@Type(() => User) user!: User`
`@List(elementType)`	Specify array element type	`@List(String) tags!: string[]`
`@Enum(enumObj: object, message?)`	Maps the value onto a member of `enumObj`, and rejects a value that is not a member.	`@Enum(UserRole) role!: UserRole`

A field takes at most one type helper. @Enum installs its own transformer, so it cannot be combined with @Transform, and @Each cannot wrap it. See Type Helper Decorators for details.

Missing-Value Decorators

Decorator	Description	Example
`@Optional()`	Skip validation when value is null or undefined.	`@Optional() value?: number`
`@Default(value)`	Set default value when field is missing	`@Default(0) count!: number`

A field takes a single missing-value strategy; @Optional and @Default cannot be combined.

Error Handling

When validation fails, bindingCargo throws a CargoValidationError containing a list of CargoFieldError objects. You can handle it using setCargoErrorHandler (recommended) or Express's built-in error middleware.

Option 1: setCargoErrorHandler (Recommended)

Register a global handler once at app startup:

import { setCargoErrorHandler, CargoValidationError } from 'express-cargo'

setCargoErrorHandler((err, req, res, next) => {
    res.status(400).json({
        error: 'Validation failed',
        details: err.errors.map(e => ({
            field: e.field,
            message: e.message,
        })),
    })
})

Option 2: Express Error Middleware

import { CargoValidationError } from 'express-cargo'
import { Request, Response, NextFunction } from 'express'

app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
    if (err instanceof CargoValidationError) {
        return res.status(400).json({
            error: 'Validation failed',
            details: err.errors.map(e => ({
                field: e.field,
                message: e.message,
            })),
        })
    }
    next(err)
})

If setCargoErrorHandler is registered, it takes priority over the Express error middleware. The Express error middleware will only receive the error if next(err) is called inside setCargoErrorHandler.

License

MIT

Name		Name	Last commit message	Last commit date
.gemini		.gemini
.github		.github
apps		apps
packages/express-cargo		packages/express-cargo
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.prettierrc		.prettierrc
DEVELOPMENT.md		DEVELOPMENT.md
LICENSE		LICENSE
README.ko.md		README.ko.md
README.md		README.md
context7.json		context7.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.base.json		tsconfig.base.json

Navigation Menu

Uh oh!

Repository files navigation

express-cargo

Installation

TypeScript Configuration

1. Install TypeScript (if not already installed)

2. Enable Decorator Support

Quick Start

Documentation

Features

Binding Decorators

Validation Decorators

Transform Decorators

Binding Order and Priority

When the Value Exists

Passport.js Example

When the Value Is Missing

Type Helper Decorators

Missing-Value Decorators

Error Handling

License

About

Releases

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

express-cargo

Installation

TypeScript Configuration

1. Install TypeScript (if not already installed)

2. Enable Decorator Support

Quick Start

Documentation

Features

Binding Decorators

Validation Decorators

Transform Decorators

Binding Order and Priority

When the Value Exists

Passport.js Example

When the Value Is Missing

Type Helper Decorators

Missing-Value Decorators

Error Handling

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages