Candour Backend Timezone Converter

A TypeScript library for automatically converting UTC dates to user timezones in Express API responses.

Features

• ✅ Automatic conversion of dates in API responses to user's timezone
• ✅ Preserves Express response chainability (res.status().json())
• ✅ Type-safe with TypeScript support
• ✅ Configurable date detection and field skipping
• ✅ Works with any database ORM (Sequelize, TypeORM, etc.)
• ✅ Zero changes needed in your controllers or models
• ✅ Lightweight, with minimal dependencies

Installation

npm install @candour/be-timezone-converter

Quick Start

import express from 'express';
import { createTimezoneConverter } from '@candour/be-timezone-converter';

const app = express();
const { timezoneMiddleware, responseTransformerMiddleware } = createTimezoneConverter();

// Apply middleware
app.use(timezoneMiddleware);
app.use(responseTransformerMiddleware);

// Your routes
app.get('/api/data', (req, res) => {
  const data = [
    { id: 1, name: 'Item 1', createdAt: new Date() }
  ];
  
  // Dates will be automatically converted to user's timezone
  res.status(200).json(data);
});

app.listen(3000);

How It Works

1. The timezoneMiddleware extracts the user's timezone from:

   • Query parameter: ?timezone=America/New_York
   • Request header: x-timezone: America/New_York

2. The responseTransformerMiddleware automatically converts all UTC dates in your response to the user's timezone.

3. All database operations continue to use UTC timestamps for consistency.

Configuration Options

const timezoneConverter = createTimezoneConverter({
  // Default timezone if none specified (default: 'UTC')
  defaultTimezone: 'America/New_York',
  
  // Custom header name (default: 'x-timezone')
  timezoneHeader: 'x-user-timezone',

  // Custom query parameter name (default: 'timezone')
  timezoneParam: 'tz',
  
  // Fields to skip during conversion
  skipFields: [
    'metadata',           // Skip the entire metadata object
    'config.*',           // Skip all properties inside config
    'rawTimestamps'       // Skip specific field
  ],

  // overrides other options and automatically detect user timezone based on the ip address and default to UTC if timezone is not found
  detectTimezone:true,
  
  // Custom function to determine if a value is a date
  dateDetector: (value) => {
    // Your custom detection logic
    return value instanceof Date || 
           (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}/.test(value));
  }
});

Manual Conversion

For cases where you need to manually convert dates:

const { convertDate, transformData } = createTimezoneConverter();

// Convert a single date
app.get('/api/time', (req, res) => {
  const now = new Date();
  const localTime = convertDate(now, req.userTimezone);
  
  res.json({ localTime });
});

// Transform a complex object
app.get('/api/custom', (req, res) => {
  const data = {
    user: {
      registeredAt: new Date(),
      lastLogin: new Date()
    }
  };
  
  const transformed = transformData(data, req.userTimezone);
  res.json(transformed);
});

TypeScript Support

The library includes type definitions and extends Express's Request interface:

import { Request, Response } from 'express';

app.get('/api/example', (req: Request, res: Response) => {
  // req.userTimezone is available and typed
  console.log(req.userTimezone); // e.g., 'America/New_York'
});

License

MIT