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

Validation Decorators

Decorator	Description	Example
@optional()	Skip validation when value is null or undefined.	@optional() value?: number
@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
@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'
@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

---

Transform Decorators

Decorator	Description	Example
@transform(transformer)	Transform the parsed value	@transform(v => v.trim()) name!: string
@request(transformer)	Extract value from Express Request object	@request(req => req.ip) clientIp!: string
@virtual(transformer)	Compute value from other fields	@virtual(obj => obj.firstName + ' ' + obj.lastName) fullName!: string

Utility Decorators

Decorator	Description	Example
@defaultValue(value)	Set default value when field is missing	@defaultValue(0) count!: number
@array(elementType)	Specify array element type	@array(String) tags!: string[]

Error Handling

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

// Custom error handler
setCargoErrorHandler((err, req, res, next) => {
    if (err instanceof CargoValidationError) {
        res.status(400).json({
        error: 'Validation failed',
        details: err.errors.map(e => ({
                field: e.field,
                message: e.name
            }))
        })
    } else {
        next(err)
    }
})

License

MIT