tessl/npm-strftime

Comprehensive strftime implementation for JavaScript with localization and timezone support

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

strftime

Name: tessl/npm-strftime
Author: tessl

strftime is a comprehensive JavaScript date and time formatting library that brings POSIX strftime functionality to JavaScript environments. It provides extensive format specifier support, built-in localization for 11 languages, timezone handling, and works seamlessly in both Node.js and browser environments with zero dependencies.

Package Information

Package Name: strftime
Package Type: npm
Language: JavaScript
Installation: npm install strftime

Alternative installations:

Bower: bower install strftime
Component: component install samsonjs/strftime
Yarn: yarn add strftime

Core Imports

const strftime = require("strftime");

For browsers (via script tag):

<script src="strftime.js"></script>
<!-- strftime is available globally -->

Basic Usage

const strftime = require("strftime");

// Format current date/time
console.log(strftime('%B %d, %Y %H:%M:%S'));
// => "January 15, 2024 14:30:45"

// Format specific date
const date = new Date(2011, 5, 7, 18, 51, 45); // June 7, 2011 18:51:45
console.log(strftime('%F %T', date));
// => "2011-06-07 18:51:45"

// Use predefined format combinations
console.log(strftime('%c', date));  // Complete date/time
console.log(strftime('%x', date));  // Date only
console.log(strftime('%X', date));  // Time only

Architecture

strftime is built around several key components:

Core Function: Main strftime(format, date?) function with default en_US locale
Instance Methods: Factory methods (localize, localizeByIdentifier, timezone, utc) that return configured strftime instances
Locale System: Built-in locale data for 11 languages with customizable formats
Format Engine: Comprehensive format specifier processing supporting 40+ POSIX and Ruby extension specifiers
Timezone Support: UTC conversion and custom timezone offset handling

Capabilities

Core Formatting

Primary date/time formatting function with extensive format specifier support.

/**
 * Format a date using strftime format specifiers
 * @param format - Format string with % specifiers
 * @param date - Date object to format (optional, defaults to current date/time)
 * @returns Formatted date string
 */
function strftime(format, date);

Format Specifiers:

Date Specifiers:

%A - Full weekday name (Sunday, Monday, ...)
%a - Abbreviated weekday name (Sun, Mon, ...)
%B - Full month name (January, February, ...)
%b - Abbreviated month name (Jan, Feb, ...)
%C - Century (year/100), padded to 2 digits
%D - Date in mm/dd/yy format
%d - Day of month, padded to 2 digits (01-31)
%e - Day of month, space-padded for single digits (1-31)
%F - Date in ISO format (YYYY-mm-dd)
%j - Day of year, padded to 3 digits (001-366)
%m - Month, padded to 2 digits (01-12)
%o - Day of month as ordinal (1st, 2nd, 3rd, ...)
%Y - Year with century
%y - Year without century, padded to 2 digits (00-99)

Time Specifiers:

%H - Hour in 24-hour format, padded to 2 digits (00-23)
%I - Hour in 12-hour format, padded to 2 digits (01-12)
%k - Hour in 24-hour format, space-padded for single digits (0-23)
%l - Hour in 12-hour format, space-padded for single digits (1-12)
%L - Milliseconds, padded to 3 digits (Ruby extension)
%M - Minutes, padded to 2 digits (00-59)
%P - Lowercase am/pm (Ruby extension)
%p - Uppercase AM/PM
%S - Seconds, padded to 2 digits (00-60)
%s - Unix timestamp (seconds since epoch)

Week Specifiers:

%U - Week number (Sunday as first day), padded to 2 digits (00-53)
%W - Week number (Monday as first day), padded to 2 digits (00-53)
%u - Weekday (Monday as first day) (1-7)
%w - Weekday (Sunday as first day) (0-6)

Timezone Specifiers:

%Z - Timezone name
%z - Timezone offset from UTC (+HHMM or -HHMM)

Compound Specifiers (locale-dependent):

%c - Complete date and time representation
%R - Time in HH:MM format
%r - Time in 12-hour format with AM/PM
%T - Time in HH:MM:SS format
%v - Date in dd-mmm-yyyy format
%X - Time representation
%x - Date representation

Literal Characters:

%n - Newline character
%t - Tab character
%% - Literal % character

Padding Modifiers:

%- - Remove padding (e.g., %-d for day without leading zero)
%_ - Use spaces for padding instead of zeros
%0 - Force zeros for padding (default for most specifiers)
%: - Add colon delimiter (e.g., %:z for timezone with colon)

Usage Examples:

const strftime = require("strftime");
const date = new Date(2024, 0, 15, 14, 5, 3); // January 15, 2024 14:05:03

// Date formatting
console.log(strftime('%Y-%m-%d', date));      // "2024-01-15"
console.log(strftime('%B %d, %Y', date));     // "January 15, 2024"
console.log(strftime('%A, %b %e', date));     // "Monday, Jan 15"

// Time formatting
console.log(strftime('%H:%M:%S', date));      // "14:05:03"
console.log(strftime('%I:%M %p', date));      // "02:05 PM"
console.log(strftime('%l:%M%P', date));       // " 2:05pm"

// Combined formatting
console.log(strftime('%c', date));            // "Mon 15 Jan 2024 02:05:03 PM EST"
console.log(strftime('%F %T', date));         // "2024-01-15 14:05:03"

// Padding modifiers
console.log(strftime('%-d/%-m/%Y', date));    // "15/1/2024"
console.log(strftime('%_d/%_m/%Y', date));    // "15/ 1/2024"

Localization

Create strftime instances with custom or bundled locale configurations.

/**
 * Create a strftime instance with custom locale
 * @param locale - Locale configuration object
 * @returns New strftime function with specified locale
 */
strftime.localize(locale);

/**
 * Create a strftime instance using a bundled locale identifier
 * @param localeIdentifier - Bundled locale identifier (e.g., 'it_IT', 'de_DE')
 * @returns New strftime function with specified locale, or original strftime if locale not found
 */
strftime.localizeByIdentifier(localeIdentifier);

Bundled Locale Identifiers:

de_DE - German (Germany)
en_CA - English (Canada)
en_US - English (United States) - default
es_MX - Spanish (Mexico)
fr_FR - French (France)
it_IT - Italian (Italy)
nl_NL - Dutch (Netherlands)
pt_BR - Portuguese (Brazil)
ru_RU - Russian (Russia)
tr_TR - Turkish (Turkey)
zh_CN - Chinese (China)

Usage Examples:

const strftime = require("strftime");

// Using bundled locale
const strftimeIT = strftime.localizeByIdentifier('it_IT');
console.log(strftimeIT('%B %d, %Y'));  // "gennaio 15, 2024"

// Custom locale
const customLocale = {
  identifier: 'custom',
  days: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'],
  shortDays: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'],
  months: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
  shortMonths: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
  AM: 'AM',
  PM: 'PM',
  am: 'am',
  pm: 'pm',
  formats: {
    D: '%m/%d/%y',
    F: '%Y-%m-%d',
    R: '%H:%M',
    T: '%H:%M:%S',
    X: '%T',
    c: '%a %b %d %X %Y',
    r: '%I:%M:%S %p',
    v: '%e-%b-%Y',
    x: '%D'
  }
};

const strftimeCustom = strftime.localize(customLocale);
console.log(strftimeCustom('%B %d, %Y'));

Timezone Support

Create strftime instances with custom timezone offsets or UTC time.

/**
 * Create a strftime instance with custom timezone offset
 * @param timezone - Timezone offset in minutes (number) or ISO 8601 format string (e.g., '+0200', '-0700')
 * @returns New strftime function with specified timezone
 */
strftime.timezone(timezone);

/**
 * Create a strftime instance that formats dates in UTC
 * @returns New strftime function using UTC time
 */
strftime.utc();

Usage Examples:

const strftime = require("strftime");
const date = new Date('2024-01-15T18:30:00Z'); // UTC time

// Timezone with offset in minutes
const strftimePST = strftime.timezone(-480); // PST is UTC-8 (8 * 60 = 480 minutes)
console.log(strftimePST('%F %T', date));     // "2024-01-15 10:30:00"

// Timezone with ISO 8601 format
const strftimeCET = strftime.timezone('+0100'); // CET is UTC+1
console.log(strftimeCET('%F %T', date));     // "2024-01-15 19:30:00"

// UTC formatting
const strftimeUTC = strftime.utc();
console.log(strftimeUTC('%F %T', date));     // "2024-01-15 18:30:00"

// Combined with localization
const strftimeITUTC = strftime.localizeByIdentifier('it_IT').utc();
console.log(strftimeITUTC('%B %d, %Y %T', date)); // "gennaio 15, 2024 18:30:00"

Method Chaining

All strftime methods return new instances, allowing for method chaining.

const strftime = require("strftime");

// Chain timezone and localization
const formatter = strftime
  .timezone('+0200')           // Set timezone to UTC+2
  .localizeByIdentifier('de_DE'); // Use German locale

console.log(formatter('%A, %d. %B %Y %H:%M', new Date()));
// => "Montag, 15. Januar 2024 20:30"

// UTC with custom locale
const utcFormatter = strftime
  .localize(customLocale)
  .utc();

Types

/**
 * Locale configuration object for customizing date/time formatting
 */
interface LocaleConfig {
  /** BCP 47 language tag identifier */
  identifier: string;
  /** Full weekday names (Sunday to Saturday) */
  days: string[];
  /** Abbreviated weekday names */
  shortDays: string[];
  /** Full month names (January to December) */
  months: string[];
  /** Abbreviated month names */
  shortMonths: string[];
  /** Ordinal suffixes for day numbers (optional) */
  ordinalSuffixes?: string[];
  /** Uppercase AM indicator */
  AM: string;
  /** Uppercase PM indicator */
  PM: string;
  /** Lowercase AM indicator */
  am: string;
  /** Lowercase PM indicator */
  pm: string;
  /** Locale-specific format definitions for compound specifiers */
  formats: {
    /** %D format */
    D: string;
    /** %F format */
    F: string;
    /** %R format */
    R: string;
    /** %T format */
    T: string;
    /** %X format */
    X: string;
    /** %c format */
    c: string;
    /** %r format */
    r: string;
    /** %v format */
    v: string;
    /** %x format */
    x: string;
  };
}

/**
 * Strftime function type
 */
interface StrftimeFunction {
  /** Format a date using strftime format specifiers */
  (format: string, date?: Date): string;
  /** Create instance with custom locale */
  localize(locale: LocaleConfig): StrftimeFunction;
  /** Create instance with bundled locale */
  localizeByIdentifier(localeIdentifier: string): StrftimeFunction;
  /** Create instance with timezone offset */
  timezone(timezone: number | string): StrftimeFunction;
  /** Create instance using UTC time */
  utc(): StrftimeFunction;
}

Workspace: tessl
Visibility: Public
Created: 7 months ago
Last updated: 3 months ago
Describes: pkg:npm/strftime@0.10.x
Publish Source: CLI
Badge