chronia

format

Overview

The format function converts a Date object to a formatted string using Unicode format tokens. It provides flexible date and time formatting with support for localization, allowing you to create custom date string representations for display purposes.

Signature

function format(date: Date, pattern: string, locale?: Locale): string;

Parameters

Parameter Type Description
date Date The Date object to format
pattern string The format pattern using Unicode tokens (e.g., “yyyy-MM-dd HH:mm:ss”)
locale Locale (optional) Optional localization object for locale-specific formatting of month names, weekdays, day periods, and eras

Return Value

Type Description
string Formatted date string according to the specified pattern

Description

The format function transforms Date objects into human-readable strings by applying a pattern-based formatting system. It uses the same token syntax as the parse() function to ensure consistency across the Chronia API. The function supports extensive customization through Unicode format tokens and optional localization for internationalized applications.

Specification

Supported Format Tokens:

Year Tokens:

Month Tokens:

Day Tokens:

Hour Tokens:

Minute Tokens:

Second Tokens:

Millisecond Tokens:

Day Period Tokens:

Era Tokens:

Weekday Tokens:

Day of Year Tokens:

Pattern Syntax Rules:

Behavior Notes

Use Cases

Usage Examples

Display Formatting

import { format } from "chronia";

const date = new Date(2024, 0, 15, 14, 30, 45, 123);

// Basic date formats
format(date, "yyyy-MM-dd"); // Returns: "2024-01-15"
format(date, "dd/MM/yyyy"); // Returns: "15/01/2024"
format(date, "MM/dd/yyyy"); // Returns: "01/15/2024"

// Date and time combined
format(date, "yyyy-MM-dd HH:mm:ss"); // Returns: "2024-01-15 14:30:45"
format(date, "dd/MM/yyyy HH:mm"); // Returns: "15/01/2024 14:30"

// 12-hour format with AM/PM
format(date, "h:mm a"); // Returns: "2:30 PM"
format(date, "hh:mm:ss a"); // Returns: "02:30:45 PM"

// With milliseconds
format(date, "HH:mm:ss.SSS"); // Returns: "14:30:45.123"

Date String Standardization

import { format } from "chronia";

// Consistent ISO 8601-like format across application
const standardFormat = "yyyy-MM-dd'T'HH:mm:ss";

const dates = [
  new Date(2024, 0, 15, 9, 0, 0),
  new Date(2024, 5, 20, 14, 30, 0),
  new Date(2024, 11, 31, 23, 59, 59),
];

const formatted = dates.map((date) => format(date, standardFormat));
// Returns: [
//   "2024-01-15T09:00:00",
//   "2024-06-20T14:30:00",
//   "2024-12-31T23:59:59"
// ]

Localized Date Display

import { format } from "chronia";
import { enUS } from "chronia/locale/en-US";
import { ja } from "chronia/locale/ja";

const date = new Date(2024, 0, 15, 14, 30, 0);

// English localized formatting
format(date, "EEEE, MMMM dd, yyyy 'at' h:mm a", enUS);
// Returns: "Monday, January 15, 2024 at 2:30 PM"

// Japanese localized formatting
format(date, "yyyy'年'M'月'd'日' HH:mm", ja);
// Returns: "2024年1月15日 14:30"

// Month names in different locales
format(date, "MMMM", enUS); // Returns: "January"
format(date, "MMMM", ja); // Returns: "1月" (Japanese)

API Response Formatting

import { format } from "chronia";

interface ApiResponse {
  id: string;
  createdAt: string;
  updatedAt: string;
}

function prepareApiResponse(
  id: string,
  created: Date,
  updated: Date,
): ApiResponse {
  // Format dates to ISO 8601 format for API
  return {
    id,
    createdAt: format(created, "yyyy-MM-dd'T'HH:mm:ss.SSS"),
    updatedAt: format(updated, "yyyy-MM-dd'T'HH:mm:ss.SSS"),
  };
}

const response = prepareApiResponse(
  "user-123",
  new Date(2024, 0, 1, 10, 0, 0, 0),
  new Date(2024, 0, 15, 14, 30, 45, 123),
);
// Returns: {
//   id: "user-123",
//   createdAt: "2024-01-01T10:00:00.000",
//   updatedAt: "2024-01-15T14:30:45.123"
// }

Log Timestamps

import { format } from "chronia";

class Logger {
  private formatTimestamp(date: Date): string {
    return format(date, "yyyy-MM-dd HH:mm:ss.SSS");
  }

  log(message: string): void {
    const timestamp = this.formatTimestamp(new Date());
    console.log(`[${timestamp}] ${message}`);
  }

  error(message: string, error: Error): void {
    const timestamp = this.formatTimestamp(new Date());
    console.error(`[${timestamp}] ERROR: ${message}`, error);
  }
}

const logger = new Logger();
logger.log("Application started");
// Console output: [2024-01-15 14:30:45.123] Application started

logger.error("Failed to connect", new Error("Connection refused"));
// Console output: [2024-01-15 14:30:45.456] ERROR: Failed to connect Error: Connection refused

Advanced Pattern Examples

import { format } from "chronia";

const date = new Date(2024, 0, 15, 14, 30, 45, 123);

// Year variations
format(date, "y"); // Returns: "2024"
format(date, "yy"); // Returns: "24"
format(date, "yyy"); // Returns: "024"
format(date, "yyyy"); // Returns: "2024"

// Month variations
format(date, "M"); // Returns: "1"
format(date, "MM"); // Returns: "01"
format(date, "MMM"); // Returns: "Jan"
format(date, "MMMM"); // Returns: "January"
format(date, "MMMMM"); // Returns: "J"

// Weekday formatting
format(date, "E"); // Returns: "Mon"
format(date, "EEEE"); // Returns: "Monday"
format(date, "EEEEE"); // Returns: "M"

// Day period variations
format(date, "h:mm a"); // Returns: "2:30 PM"
format(date, "h:mm aaaa"); // Returns: "2:30 P.M."
format(date, "h:mm aaaaa"); // Returns: "2:30 p"

// Era formatting (BC dates)
const bcDate = new Date(-100, 0, 1);
format(bcDate, "yyyy G"); // Returns: "0101 BC"
format(bcDate, "yyyy GGGG"); // Returns: "0101 Before Christ"
format(bcDate, "yyyy GGGGG"); // Returns: "0101 B"

// Day of year
format(date, "DDD"); // Returns: "015" (15th day of year)

// Literal text with escaped quotes
format(date, "'Year' yyyy', Month' MM"); // Returns: "Year 2024, Month 01"
format(date, "'It''s' yyyy"); // Returns: "It's 2024"

// Complex real-world format
format(date, "EEEE, MMMM dd, yyyy 'at' h:mm a");
// Returns: "Monday, January 15, 2024 at 2:30 PM"
This site is open source. Improve this page.