0
# strftime
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: strftime
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install strftime`
10

11
Alternative installations:
12
- **Bower**: `bower install strftime`
13
- **Component**: `component install samsonjs/strftime`
14
- **Yarn**: `yarn add strftime`
15

16
## Core Imports
17

18
```javascript
19
const strftime = require("strftime");
20
```
21

22
For browsers (via script tag):
23
```html
24
<script src="strftime.js"></script>
25
<!-- strftime is available globally -->
26
```
27

28
## Basic Usage
29

30
```javascript
31
const strftime = require("strftime");
32

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

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

42
// Use predefined format combinations
43
console.log(strftime('%c', date));  // Complete date/time
44
console.log(strftime('%x', date));  // Date only
45
console.log(strftime('%X', date));  // Time only
46
```
47

48
## Architecture
49

50
strftime is built around several key components:
51

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

58
## Capabilities
59

60
### Core Formatting
61

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

64
```javascript { .api }
65
/**
66
 * Format a date using strftime format specifiers
67
 * @param format - Format string with % specifiers
68
 * @param date - Date object to format (optional, defaults to current date/time)
69
 * @returns Formatted date string
70
 */
71
function strftime(format, date);
72
```
73

74
**Format Specifiers:**
75

76
Date Specifiers:
77
- `%A` - Full weekday name (Sunday, Monday, ...)
78
- `%a` - Abbreviated weekday name (Sun, Mon, ...)
79
- `%B` - Full month name (January, February, ...)
80
- `%b` - Abbreviated month name (Jan, Feb, ...)
81
- `%C` - Century (year/100), padded to 2 digits
82
- `%D` - Date in mm/dd/yy format
83
- `%d` - Day of month, padded to 2 digits (01-31)
84
- `%e` - Day of month, space-padded for single digits (1-31)
85
- `%F` - Date in ISO format (YYYY-mm-dd)
86
- `%j` - Day of year, padded to 3 digits (001-366)
87
- `%m` - Month, padded to 2 digits (01-12)
88
- `%o` - Day of month as ordinal (1st, 2nd, 3rd, ...)
89
- `%Y` - Year with century
90
- `%y` - Year without century, padded to 2 digits (00-99)
91

92
Time Specifiers:
93
- `%H` - Hour in 24-hour format, padded to 2 digits (00-23)
94
- `%I` - Hour in 12-hour format, padded to 2 digits (01-12)
95
- `%k` - Hour in 24-hour format, space-padded for single digits (0-23)
96
- `%l` - Hour in 12-hour format, space-padded for single digits (1-12)
97
- `%L` - Milliseconds, padded to 3 digits (Ruby extension)
98
- `%M` - Minutes, padded to 2 digits (00-59)
99
- `%P` - Lowercase am/pm (Ruby extension)
100
- `%p` - Uppercase AM/PM
101
- `%S` - Seconds, padded to 2 digits (00-60)
102
- `%s` - Unix timestamp (seconds since epoch)
103

104
Week Specifiers:
105
- `%U` - Week number (Sunday as first day), padded to 2 digits (00-53)
106
- `%W` - Week number (Monday as first day), padded to 2 digits (00-53)
107
- `%u` - Weekday (Monday as first day) (1-7)
108
- `%w` - Weekday (Sunday as first day) (0-6)
109

110
Timezone Specifiers:
111
- `%Z` - Timezone name
112
- `%z` - Timezone offset from UTC (+HHMM or -HHMM)
113

114
Compound Specifiers (locale-dependent):
115
- `%c` - Complete date and time representation
116
- `%R` - Time in HH:MM format
117
- `%r` - Time in 12-hour format with AM/PM
118
- `%T` - Time in HH:MM:SS format
119
- `%v` - Date in dd-mmm-yyyy format
120
- `%X` - Time representation
121
- `%x` - Date representation
122

123
Literal Characters:
124
- `%n` - Newline character
125
- `%t` - Tab character
126
- `%%` - Literal % character
127

128
**Padding Modifiers:**
129
- `%-` - Remove padding (e.g., `%-d` for day without leading zero)
130
- `%_` - Use spaces for padding instead of zeros
131
- `%0` - Force zeros for padding (default for most specifiers)
132
- `%:` - Add colon delimiter (e.g., `%:z` for timezone with colon)
133

134
**Usage Examples:**
135

136
```javascript
137
const strftime = require("strftime");
138
const date = new Date(2024, 0, 15, 14, 5, 3); // January 15, 2024 14:05:03
139

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

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

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

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

159
### Localization
160

161
Create strftime instances with custom or bundled locale configurations.
162

163
```javascript { .api }
164
/**
165
 * Create a strftime instance with custom locale
166
 * @param locale - Locale configuration object
167
 * @returns New strftime function with specified locale
168
 */
169
strftime.localize(locale);
170

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

179
**Bundled Locale Identifiers:**
180
- `de_DE` - German (Germany)
181
- `en_CA` - English (Canada)
182
- `en_US` - English (United States) - default
183
- `es_MX` - Spanish (Mexico)
184
- `fr_FR` - French (France)
185
- `it_IT` - Italian (Italy)
186
- `nl_NL` - Dutch (Netherlands)
187
- `pt_BR` - Portuguese (Brazil)
188
- `ru_RU` - Russian (Russia)
189
- `tr_TR` - Turkish (Turkey)
190
- `zh_CN` - Chinese (China)
191

192
**Usage Examples:**
193

194
```javascript
195
const strftime = require("strftime");
196

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

201
// Custom locale
202
const customLocale = {
203
  identifier: 'custom',
204
  days: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'],
205
  shortDays: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'],
206
  months: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
207
  shortMonths: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
208
  AM: 'AM',
209
  PM: 'PM',
210
  am: 'am',
211
  pm: 'pm',
212
  formats: {
213
    D: '%m/%d/%y',
214
    F: '%Y-%m-%d',
215
    R: '%H:%M',
216
    T: '%H:%M:%S',
217
    X: '%T',
218
    c: '%a %b %d %X %Y',
219
    r: '%I:%M:%S %p',
220
    v: '%e-%b-%Y',
221
    x: '%D'
222
  }
223
};
224

225
const strftimeCustom = strftime.localize(customLocale);
226
console.log(strftimeCustom('%B %d, %Y'));
227
```
228

229
### Timezone Support
230

231
Create strftime instances with custom timezone offsets or UTC time.
232

233
```javascript { .api }
234
/**
235
 * Create a strftime instance with custom timezone offset
236
 * @param timezone - Timezone offset in minutes (number) or ISO 8601 format string (e.g., '+0200', '-0700')
237
 * @returns New strftime function with specified timezone
238
 */
239
strftime.timezone(timezone);
240

241
/**
242
 * Create a strftime instance that formats dates in UTC
243
 * @returns New strftime function using UTC time
244
 */
245
strftime.utc();
246
```
247

248
**Usage Examples:**
249

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

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

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

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

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

271
### Method Chaining
272

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

275
```javascript
276
const strftime = require("strftime");
277

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

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

286
// UTC with custom locale
287
const utcFormatter = strftime
288
  .localize(customLocale)
289
  .utc();
290
```
291

292
## Types
293

294
```javascript { .api }
295
/**
296
 * Locale configuration object for customizing date/time formatting
297
 */
298
interface LocaleConfig {
299
  /** BCP 47 language tag identifier */
300
  identifier: string;
301
  /** Full weekday names (Sunday to Saturday) */
302
  days: string[];
303
  /** Abbreviated weekday names */
304
  shortDays: string[];
305
  /** Full month names (January to December) */
306
  months: string[];
307
  /** Abbreviated month names */
308
  shortMonths: string[];
309
  /** Ordinal suffixes for day numbers (optional) */
310
  ordinalSuffixes?: string[];
311
  /** Uppercase AM indicator */
312
  AM: string;
313
  /** Uppercase PM indicator */
314
  PM: string;
315
  /** Lowercase AM indicator */
316
  am: string;
317
  /** Lowercase PM indicator */
318
  pm: string;
319
  /** Locale-specific format definitions for compound specifiers */
320
  formats: {
321
    /** %D format */
322
    D: string;
323
    /** %F format */
324
    F: string;
325
    /** %R format */
326
    R: string;
327
    /** %T format */
328
    T: string;
329
    /** %X format */
330
    X: string;
331
    /** %c format */
332
    c: string;
333
    /** %r format */
334
    r: string;
335
    /** %v format */
336
    v: string;
337
    /** %x format */
338
    x: string;
339
  };
340
}
341

342
/**
343
 * Strftime function type
344
 */
345
interface StrftimeFunction {
346
  /** Format a date using strftime format specifiers */
347
  (format: string, date?: Date): string;
348
  /** Create instance with custom locale */
349
  localize(locale: LocaleConfig): StrftimeFunction;
350
  /** Create instance with bundled locale */
351
  localizeByIdentifier(localeIdentifier: string): StrftimeFunction;
352
  /** Create instance with timezone offset */
353
  timezone(timezone: number | string): StrftimeFunction;
354
  /** Create instance using UTC time */
355
  utc(): StrftimeFunction;
356
}
357
```