CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-d3-time-format

A JavaScript time formatter and parser inspired by strftime and strptime.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

locale-support.mddocs/

Locale Support

Internationalization support enabling custom date/time formatting rules for different languages and regions through configurable locale definitions.

Capabilities

Time Format Locale

Creates a locale object with formatting and parsing methods for a specific locale.

/**
 * Creates a locale object with custom formatting rules
 * @param definition - Locale definition with date/time formatting rules
 * @returns Locale object with format, parse, utcFormat, and utcParse methods
 */
function timeFormatLocale(definition: LocaleDefinition): LocaleObject;

interface LocaleDefinition {
  /** Date and time format specifier (e.g., "%x, %X") */
  dateTime: string;
  /** Date format specifier (e.g., "%-m/%-d/%Y") */
  date: string;
  /** Time format specifier (e.g., "%-I:%M:%S %p") */
  time: string;
  /** AM and PM equivalents as [AM, PM] array */
  periods: [string, string];
  /** Full weekday names starting with Sunday */
  days: [string, string, string, string, string, string, string];
  /** Abbreviated weekday names starting with Sunday */
  shortDays: [string, string, string, string, string, string, string];
  /** Full month names starting with January */
  months: [string, string, string, string, string, string, string, string, string, string, string, string];
  /** Abbreviated month names starting with January */
  shortMonths: [string, string, string, string, string, string, string, string, string, string, string, string];
}

interface LocaleObject {
  /** Create formatter function for local time */
  format(specifier: string): (date: Date) => string;
  /** Create parser function for local time */
  parse(specifier: string): (dateString: string) => Date | null;
  /** Create formatter function for UTC time */
  utcFormat(specifier: string): (date: Date) => string;
  /** Create parser function for UTC time */
  utcParse(specifier: string): (dateString: string) => Date | null;
}

Usage Examples:

import { timeFormatLocale } from "d3-time-format";

// Create a custom locale
const germanLocale = timeFormatLocale({
  dateTime: "%A, der %e. %B %Y, %X",
  date: "%d.%m.%Y",
  time: "%H:%M:%S",
  periods: ["AM", "PM"], // German doesn't typically use AM/PM
  days: ["Sonntag", "Montag", "Dienstag", "Mittwoch", "Donnerstag", "Freitag", "Samstag"],
  shortDays: ["So", "Mo", "Di", "Mi", "Do", "Fr", "Sa"],
  months: ["Januar", "Februar", "März", "April", "Mai", "Juni", "Juli", "August", "September", "Oktober", "November", "Dezember"],
  shortMonths: ["Jan", "Feb", "Mär", "Apr", "Mai", "Jun", "Jul", "Aug", "Sep", "Okt", "Nov", "Dez"]
});

// Use the locale
const formatGerman = germanLocale.format("%A, der %e. %B %Y");
const parseGerman = germanLocale.parse("%d.%m.%Y");

formatGerman(new Date(2015, 5, 30)); // "Dienstag, der 30. Juni 2015"
parseGerman("30.06.2015"); // Date object for June 30, 2015

Time Format Default Locale

Sets the default locale and redefines the global timeFormat, timeParse, utcFormat, and utcParse functions.

/**
 * Sets the default locale and redefines global format/parse functions
 * @param definition - Locale definition to use as default
 * @returns Locale object for the new default locale
 */
function timeFormatDefaultLocale(definition: LocaleDefinition): LocaleObject;

Usage Examples:

import { timeFormatDefaultLocale, timeFormat, timeParse } from "d3-time-format";

// Load Russian locale from JSON
const russianLocale = {
  dateTime: "%A, %e %B %Y г. %X",
  date: "%d.%m.%Y",
  time: "%H:%M:%S",
  periods: ["AM", "PM"],
  days: ["воскресенье", "понедельник", "вторник", "среда", "четверг", "пятница", "суббота"],
  shortDays: ["вс", "пн", "вт", "ср", "чт", "пт", "сб"],
  months: ["января", "февраля", "марта", "апреля", "мая", "июня", "июля", "августа", "сентября", "октября", "ноября", "декабря"],
  shortMonths: ["янв", "фев", "мар", "апр", "май", "июн", "июл", "авг", "сен", "окт", "ноя", "дек"]
};

// Set as default locale
timeFormatDefaultLocale(russianLocale);

// Now global functions use Russian locale
const format = timeFormat("%c");
format(new Date()); // "понедельник, 5 декабря 2016 г. 10:31:59"

Built-in Locale Files

The package includes pre-defined locale files in JSON format for various languages and regions:

// Available locale files (partial list)
"locale/en-US.json"  // US English (default)
"locale/en-GB.json"  // British English  
"locale/de-DE.json"  // German (Germany)
"locale/fr-FR.json"  // French (France)
"locale/es-ES.json"  // Spanish (Spain)
"locale/ja-JP.json"  // Japanese
"locale/zh-CN.json"  // Chinese (Simplified)
"locale/ru-RU.json"  // Russian
// ... and many more

Loading Locale Files:

// Using d3.json (requires d3-fetch)
import { json } from "d3-fetch";
import { timeFormatDefaultLocale } from "d3-time-format";

json("https://cdn.jsdelivr.net/npm/d3-time-format@4/locale/ru-RU.json")
  .then(locale => {
    timeFormatDefaultLocale(locale);
    
    const format = timeFormat("%c");
    console.log(format(new Date())); // Russian-formatted date
  });

// Using fetch API
fetch("./locale/fr-FR.json")
  .then(response => response.json())
  .then(locale => timeFormatDefaultLocale(locale));

// Using require/import (Node.js)
const frenchLocale = require("d3-time-format/locale/fr-FR.json");
timeFormatDefaultLocale(frenchLocale);

Default Locale

The default locale is US English with the following definition:

// Default US English locale
{
  dateTime: "%x, %X",           // "%-m/%-d/%Y, %-I:%M:%S %p"
  date: "%-m/%-d/%Y",           // "6/30/2015"
  time: "%-I:%M:%S %p",         // "7:15:28 PM"
  periods: ["AM", "PM"],
  days: ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"],
  shortDays: ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"],
  months: ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"],
  shortMonths: ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]
}

Locale-Affected Specifiers

The following format specifiers are affected by locale definitions:

// Weekday names
%a  // Short weekday from shortDays array
%A  // Full weekday from days array

// Month names  
%b  // Short month from shortMonths array
%B  // Full month from months array

// AM/PM periods
%p  // Period from periods array

// Composite formats
%c  // Uses dateTime format string
%x  // Uses date format string  
%X  // Uses time format string

Creating Custom Locales

When creating custom locale definitions:

  1. Array Ordering: Days start with Sunday (index 0), months start with January (index 0)
  2. Format Strings: Use appropriate padding for your locale's conventions
  3. Periods: Provide AM/PM equivalents even if not commonly used
  4. Completeness: All required properties must be present
// Example: 24-hour Spanish locale
const spanish24h = timeFormatLocale({
  dateTime: "%A, %e de %B de %Y, %X",
  date: "%d/%m/%Y",
  time: "%H:%M:%S",  // 24-hour format
  periods: ["AM", "PM"], // Required even if unused
  days: ["domingo", "lunes", "martes", "miércoles", "jueves", "viernes", "sábado"],
  shortDays: ["dom", "lun", "mar", "mié", "jue", "vie", "sáb"],
  months: ["enero", "febrero", "marzo", "abril", "mayo", "junio", "julio", "agosto", "septiembre", "octubre", "noviembre", "diciembre"],
  shortMonths: ["ene", "feb", "mar", "abr", "may", "jun", "jul", "ago", "sep", "oct", "nov", "dic"]
});

Install with Tessl CLI

npx tessl i tessl/npm-d3-time-format

docs

index.md

iso-utilities.md

locale-support.md

time-formatting.md

tile.json