Common Package

Shared code package for microservices in the ticketing system.

Overview

The @mttickets12/common package contains shared code used across all microservices, including error classes, event definitions, middleware, and base classes for event handling.

Installation

This package is published to npm. Install it in your service:

npm install @mttickets12/common

For local development, use npm link:

# In common directory
npm link

# In service directory
npm link @mttickets12/common

Building

Build the package:

npm run build

This compiles TypeScript to JavaScript in the build/ directory.

Publishing

Publish to npm:

npm run pub

This will:

1. Clean the build directory
2. Build the package
3. Increment patch version
4. Publish to npm

Contents

Errors

Custom error classes for consistent error handling:

• BadRequestError - 400 status code
• NotAuthorizedError - 401 status code
• NotFoundError - 404 status code
• RequestValidationError - 400 status code (validation errors)
• DatabaseValidationError - 400 status code (database errors)
• CustomError - Base error class

Middleware

Express middleware functions:

• currentUser - Extracts and validates JWT token, sets req.currentUser
• requireAuth - Ensures user is authenticated
• validateRequest - Validates request using express-validator
• errorHandler - Centralized error handling middleware

Events

Event-driven architecture components:

Base Classes

• BaseListener - Abstract base class for event listeners
• BasePublisher - Abstract base class for event publishers

Event Types

• TicketCreatedEvent
• TicketUpdatedEvent
• OrderCreatedEvent
• OrderCancelledEvent
• ExpirationCompleteEvent
• PaymentCreatedEvent

Subjects

Type-safe event subject constants:

• Subject.TicketCreated
• Subject.TicketUpdated
• Subject.OrderCreated
• Subject.OrderCancelled
• Subject.ExpirationComplete
• Subject.PaymentCreated

Usage Examples

Using Middleware

import { requireAuth, currentUser } from '@mttickets12/common';
import express from 'express';

const router = express.Router();

// Protected route
router.get('/api/orders', currentUser, requireAuth, async (req, res) => {
  // req.currentUser is available here
  res.send({ userId: req.currentUser!.id });
});

Using Error Classes

import { NotFoundError, BadRequestError } from '@mttickets12/common';

if (!ticket) {
  throw new NotFoundError();
}

if (price < 0) {
  throw new BadRequestError('Price must be positive');
}

Creating Event Listeners

import { Listener, TicketCreatedEvent, Subjects } from '@mttickets12/common';
import { Message } from 'node-nats-streaming';

class TicketCreatedListener extends Listener<TicketCreatedEvent> {
  readonly subject = Subjects.TicketCreated;
  queueGroupName = 'orders-service';

  async onMessage(data: TicketCreatedEvent['data'], msg: Message) {
    // Handle event
    console.log('Ticket created:', data);
    msg.ack();
  }
}

Creating Event Publishers

import { Publisher, TicketCreatedEvent, Subjects } from '@mttickets12/common';

class TicketCreatedPublisher extends Publisher<TicketCreatedEvent> {
  readonly subject = Subjects.TicketCreated;
}

// Usage
await new TicketCreatedPublisher(natsClient).publish({
  id: 'ticket_id',
  title: 'Concert',
  price: 50,
  userId: 'user_id',
  version: 0
});

Using Validation Middleware

import { validateRequest } from '@mttickets12/common';
import { body } from 'express-validator';

router.post(
  '/api/tickets',
  [
    body('title').notEmpty().withMessage('Title is required'),
    body('price').isFloat({ gt: 0 }).withMessage('Price must be greater than 0')
  ],
  validateRequest,
  async (req, res) => {
    // Request is validated here
  }
);

Type Safety

The package is written in TypeScript and provides full type safety:

• Event data types
• Error types
• Middleware request types

Versioning

The package follows semantic versioning:

• Patch (1.0.x) - Bug fixes, no breaking changes
• Minor (1.x.0) - New features, backward compatible
• Major (x.0.0) - Breaking changes

When updating the package:

1. Make changes
2. Update version: npm version patch|minor|major
3. Build: npm run build
4. Publish: npm publish --access public

Dependencies

• express - Web framework types
• express-validator - Request validation
• jsonwebtoken - JWT types
• cookie-session - Session types
• node-nats-streaming - NATS types

Development

1. Make changes to TypeScript files in src/
2. Build the package: npm run build
3. Test in consuming services
4. Publish when ready: npm run pub

Contributing

When adding new shared code:

1. Ensure it's truly shared across services
2. Maintain backward compatibility
3. Add proper TypeScript types
4. Update this README
5. Test in at least one consuming service