Container Number Validator

A TypeScript/JavaScript library for validating, parsing, and generating ISO 6346 shipping container numbers.

Features

• ✅ Validate container numbers against ISO 6346 standard
• 🔍 Parse container numbers into components (owner code, equipment category, serial number, check digit)
• 🎯 Calculate check digits using the official algorithm
• 🏗️ Generate valid container numbers from components
• 📝 Format container numbers for display
• 💯 100% TypeScript with full type definitions
• 🧪 Fully tested with comprehensive test suite

Installation

npm install container-number-validator

Usage

Basic Validation

import { isValidContainerNumber } from 'container-number-validator';

console.log(isValidContainerNumber('MSCU5285725')); // true
console.log(isValidContainerNumber('INVALID123'));  // false

Parse Container Number

import { parseContainerNumber } from 'container-number-validator';

const result = parseContainerNumber('MSCU5285725');

if (result.isValid) {
  console.log(result.parts);
  // {
  //   ownerCode: 'MSC',
  //   equipmentCategory: 'U',
  //   serialNumber: '528572',
  //   checkDigit: 5,
  //   raw: 'MSCU5285725'
  // }
} else {
  console.error(result.error);
}

Generate Container Number

import { generateContainerNumber } from 'container-number-validator';

const containerNumber = generateContainerNumber('MSC', 'U', '528572');
console.log(containerNumber); // 'MSCU5285725'

Calculate Check Digit

import { calculateCheckDigit } from 'container-number-validator';

const checkDigit = calculateCheckDigit('MSC', 'U', '528572');
console.log(checkDigit); // 5

Format for Display

import { formatContainerNumber } from 'container-number-validator';

const formatted = formatContainerNumber('MSCU5285725');
console.log(formatted); // 'MSCU 528572 [5]'

Get Equipment Description

import { getEquipmentDescription } from 'container-number-validator';

console.log(getEquipmentDescription('U')); // 'All freight containers'
console.log(getEquipmentDescription('J')); // 'Equipment related to freight containers (detachable)'
console.log(getEquipmentDescription('Z')); // 'Trailers or chassis'

Container Number Format

A valid container number consists of 11 characters:

1. Owner Code (3 letters): Identifies the container owner (e.g., MSC, HLXU, TLLU)
2. Equipment Category (1 letter): Type of equipment
   • U - All freight containers
   • J - Equipment related to freight containers (detachable)
   • Z - Trailers or chassis
3. Serial Number (6 digits): Unique identifier assigned by the owner
4. Check Digit (1 digit): Validation digit calculated using ISO 6346 algorithm

Example Breakdown

Container Number: MSCU5285725

MSC   U    528572   5
│     │      │      │
│     │      │      └─ Check Digit
│     │      └──────── Serial Number
│     └─────────────── Equipment Category (U = freight container)
└───────────────────── Owner Code (MSC = Mediterranean Shipping Company)

API Reference

Types

type EquipmentCategory = 'U' | 'J' | 'Z';

interface ContainerNumberParts {
  ownerCode: string;
  equipmentCategory: EquipmentCategory;
  serialNumber: string;
  checkDigit: number;
  raw: string;
}

interface ValidationResult {
  isValid: boolean;
  error?: string;
  parts?: ContainerNumberParts;
}

Functions

parseContainerNumber(containerNumber: string): ValidationResult

Parses and validates a container number, returning detailed information about its components.

isValidContainerNumber(containerNumber: string): boolean

Simple validation that returns true if the container number is valid.

calculateCheckDigit(ownerCode: string, equipmentCategory: string, serialNumber: string): number

Calculates the check digit for a container number using the ISO 6346 algorithm.

generateContainerNumber(ownerCode: string, equipmentCategory: EquipmentCategory, serialNumber: string): string

Generates a complete valid container number with check digit.

formatContainerNumber(containerNumber: string): string

Formats a container number for display with spacing and bracketed check digit.

getEquipmentDescription(category: EquipmentCategory): string

Returns the description for an equipment category code.

Standards

This library implements the ISO 6346 standard for shipping container identification.

Testing

npm test

License

ISC

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Known Owner Codes

• MSC - Mediterranean Shipping Company
• HLXU - Hapag Lloyd
• TLLU - Triton Containers International Limited
• CMAU - CMA CGM
• MAEU - Maersk Line

Note: Owner codes are registered with the Bureau International des Containers (BIC).