CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-formatjs--intl

Internationalize JS apps with APIs to format dates, numbers, and strings, including pluralization and handling translations.

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

date-time-formatting.mddocs/

Date and Time Formatting

Comprehensive date and time formatting with timezone support, custom formats, and parts-based output. Provides both individual functions and intl instance methods for locale-aware date and time presentation.

Capabilities

formatDate Function

Formats dates according to locale with extensive customization options.

/**
 * Format dates according to locale and options
 * @param config - Configuration with locale, timezone, formats, and error handler
 * @param getDateTimeFormat - DateTime formatter factory function
 * @param value - Date value as Date object, string, or number
 * @param options - Formatting options including custom format names
 * @returns Formatted date string
 */
function formatDate(
  config: {
    locale: string;
    timeZone?: string;
    formats: CustomFormats;
    onError: OnErrorFn;
  },
  getDateTimeFormat: Formatters['getDateTimeFormat'],
  value: Date | string | number,
  options?: FormatDateOptions
): string;

formatTime Function

Formats time values with locale-specific conventions and timezone handling.

/**
 * Format time values with locale-specific conventions
 * @param config - Configuration with locale, timezone, formats, and error handler  
 * @param getDateTimeFormat - DateTime formatter factory function
 * @param value - Time value as Date object, string, or number
 * @param options - Formatting options with default hour/minute display
 * @returns Formatted time string
 */
function formatTime(
  config: {
    locale: string;
    timeZone?: string;
    formats: CustomFormats;
    onError: OnErrorFn;
  },
  getDateTimeFormat: Formatters['getDateTimeFormat'],
  value: Date | string | number,
  options?: FormatDateOptions
): string;

Usage Examples:

import { formatDate, formatTime, createFormatters } from "@formatjs/intl";

const config = {
  locale: 'en-US',
  timeZone: 'America/New_York',
  formats: {
    date: {
      short: { month: 'numeric', day: 'numeric', year: '2-digit' },
      long: { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' }
    }
  },
  onError: console.error
};

const formatters = createFormatters();
const date = new Date('2024-03-15T14:30:00Z');

// Basic date formatting
const basicDate = formatDate(config, formatters.getDateTimeFormat, date);
// Result: "3/15/2024" (in en-US locale)

// Custom format
const longDate = formatDate(config, formatters.getDateTimeFormat, date, { format: 'long' });
// Result: "Friday, March 15, 2024"

// Custom options
const customDate = formatDate(config, formatters.getDateTimeFormat, date, {
  year: 'numeric',
  month: 'short',
  day: 'numeric',
  weekday: 'short'
});
// Result: "Fri, Mar 15, 2024"

// Time formatting
const time = formatTime(config, formatters.getDateTimeFormat, date);
// Result: "10:30 AM" (adjusted for timezone)

// 24-hour format
const time24 = formatTime(config, formatters.getDateTimeFormat, date, {
  hour: 'numeric',
  minute: 'numeric',
  hour12: false
});
// Result: "10:30" (adjusted for timezone)

formatDateToParts and formatTimeToParts Functions

Format dates and times returning arrays of parts for custom rendering.

/**
 * Format dates returning array of parts for custom rendering
 * @param config - Configuration with locale, timezone, formats, and error handler
 * @param getDateTimeFormat - DateTime formatter factory function  
 * @param value - Date value as Date object, string, or number
 * @param options - Formatting options
 * @returns Array of date parts with types and values
 */
function formatDateToParts(
  config: {
    locale: string;
    timeZone?: string;
    formats: CustomFormats;
    onError: OnErrorFn;
  },
  getDateTimeFormat: Formatters['getDateTimeFormat'],
  value: Date | string | number,
  options?: FormatDateOptions
): Intl.DateTimeFormatPart[];

/**
 * Format times returning array of parts for custom rendering
 * @param config - Configuration with locale, timezone, formats, and error handler
 * @param getDateTimeFormat - DateTime formatter factory function
 * @param value - Time value as Date object, string, or number  
 * @param options - Formatting options
 * @returns Array of time parts with types and values
 */
function formatTimeToParts(
  config: {
    locale: string;
    timeZone?: string; 
    formats: CustomFormats;
    onError: OnErrorFn;
  },
  getDateTimeFormat: Formatters['getDateTimeFormat'],
  value: Date | string | number,
  options?: FormatDateOptions
): Intl.DateTimeFormatPart[];

Usage Examples:

// Date parts for custom rendering
const dateParts = formatDateToParts(config, formatters.getDateTimeFormat, date, {
  year: 'numeric',
  month: 'long',
  day: 'numeric'
});

// Result: [
//   { type: 'month', value: 'March' },
//   { type: 'literal', value: ' ' },
//   { type: 'day', value: '15' },
//   { type: 'literal', value: ', ' },
//   { type: 'year', value: '2024' }
// ]

// Custom rendering with parts
const customDateRender = dateParts
  .map(part => {
    if (part.type === 'month') {
      return `<strong>${part.value}</strong>`;
    }
    return part.value;
  })
  .join('');
// Result: "<strong>March</strong> 15, 2024"

// Time parts
const timeParts = formatTimeToParts(config, formatters.getDateTimeFormat, date, {
  hour: 'numeric',
  minute: 'numeric',
  dayPeriod: 'short'
});

// Result: [
//   { type: 'hour', value: '10' },
//   { type: 'literal', value: ':' },
//   { type: 'minute', value: '30' },
//   { type: 'literal', value: ' ' },
//   { type: 'dayPeriod', value: 'AM' }
// ]

formatDateTimeRange Function

Format date ranges with locale-appropriate range formatting.

/**
 * Format date ranges with locale-appropriate range formatting
 * @param config - Configuration with locale, timezone, and error handler
 * @param getDateTimeFormat - DateTime formatter factory function
 * @param from - Start date of the range
 * @param to - End date of the range  
 * @param options - Formatting options for the range
 * @returns Formatted date range string
 */
function formatDateTimeRange(
  config: {
    locale: string;
    timeZone?: string;
    onError: OnErrorFn;
  },
  getDateTimeFormat: Formatters['getDateTimeFormat'],
  from: Date | string | number,
  to: Date | string | number,
  options?: FormatDateOptions
): string;

Usage Examples:

const startDate = new Date('2024-03-15T09:00:00Z');
const endDate = new Date('2024-03-15T17:00:00Z');

// Date range formatting
const dateRange = formatDateTimeRange(
  config,
  formatters.getDateTimeFormat,
  startDate,
  endDate,
  {
    year: 'numeric',
    month: 'short',
    day: 'numeric',
    hour: 'numeric',
    minute: 'numeric'
  }
);
// Result: "Mar 15, 2024, 5:00 AM – 1:00 PM"

// Different dates
const startDate2 = new Date('2024-03-15T09:00:00Z');
const endDate2 = new Date('2024-03-16T17:00:00Z');

const multiDayRange = formatDateTimeRange(
  config,
  formatters.getDateTimeFormat,
  startDate2,
  endDate2,
  {
    month: 'short',
    day: 'numeric',
    hour: 'numeric'
  }
);
// Result: "Mar 15, 5:00 AM – Mar 16, 1:00 PM"

FormatDateOptions Interface

Comprehensive options for date and time formatting.

type FormatDateOptions = Omit<Intl.DateTimeFormatOptions, 'localeMatcher'> & {
  /** Named format reference from custom formats */
  format?: string;
};

// Intl.DateTimeFormatOptions includes:
interface DateTimeFormatOptions {
  formatMatcher?: 'basic' | 'best fit';
  timeZone?: string;
  hour12?: boolean;
  weekday?: 'narrow' | 'short' | 'long';
  era?: 'narrow' | 'short' | 'long';
  year?: 'numeric' | '2-digit';
  month?: 'numeric' | '2-digit' | 'narrow' | 'short' | 'long';
  day?: 'numeric' | '2-digit';
  hour?: 'numeric' | '2-digit';
  minute?: 'numeric' | '2-digit';
  second?: 'numeric' | '2-digit';
  timeZoneName?: 'short' | 'long' | 'shortOffset' | 'longOffset' | 'shortGeneric' | 'longGeneric';
  hourCycle?: 'h11' | 'h12' | 'h23' | 'h24';
  dateStyle?: 'full' | 'long' | 'medium' | 'short';
  timeStyle?: 'full' | 'long' | 'medium' | 'short';
  calendar?: string;
  numberingSystem?: string;
  fractionalSecondDigits?: 0 | 1 | 2 | 3;
}

Usage Examples:

// Using dateStyle and timeStyle
const styledDate = formatDate(config, formatters.getDateTimeFormat, date, {
  dateStyle: 'full',
  timeStyle: 'short'
});
// Result: "Friday, March 15, 2024 at 10:30 AM"

// Custom calendar system
const hebrewDate = formatDate(
  { ...config, locale: 'he-IL' },
  formatters.getDateTimeFormat,
  date,
  {
    calendar: 'hebrew',
    year: 'numeric',
    month: 'long',
    day: 'numeric'
  }
);

// Fractional seconds
const preciseTime = formatTime(config, formatters.getDateTimeFormat, date, {
  hour: 'numeric',
  minute: 'numeric',
  second: 'numeric',
  fractionalSecondDigits: 3
});
// Result: "10:30:00.000 AM"

// Timezone display
const timeWithZone = formatTime(config, formatters.getDateTimeFormat, date, {
  hour: 'numeric',
  minute: 'numeric',
  timeZoneName: 'short'
});
// Result: "10:30 AM EST"

Custom Date Formats

Define reusable date format configurations.

Usage Examples:

const intl = createIntl({
  locale: 'en-US',
  timeZone: 'America/New_York',
  formats: {
    date: {
      compact: { 
        month: 'numeric', 
        day: 'numeric' 
      },
      verbose: { 
        weekday: 'long', 
        year: 'numeric', 
        month: 'long', 
        day: 'numeric',
        hour: 'numeric',
        minute: 'numeric',
        timeZoneName: 'short'
      },
      iso: {
        year: 'numeric',
        month: '2-digit', 
        day: '2-digit'
      }
    },
    time: {
      brief: { 
        hour: 'numeric', 
        minute: 'numeric' 
      },
      detailed: { 
        hour: 'numeric', 
        minute: 'numeric', 
        second: 'numeric',
        timeZoneName: 'short'
      }
    }
  }
});

// Use custom formats
const compactDate = intl.formatDate(date, { format: 'compact' });
// Result: "3/15"

const verboseDate = intl.formatDate(date, { format: 'verbose' });
// Result: "Friday, March 15, 2024 at 10:30 AM EST"

const briefTime = intl.formatTime(date, { format: 'brief' });
// Result: "10:30 AM"

docs

date-time-formatting.md

display-name-formatting.md

index.md

intl-instance.md

list-formatting.md

message-formatting.md

number-formatting.md

relative-time-pluralization.md

utility-functions.md

tile.json