sofi-date

A flexible, lightweight date formatting library for Node.js with multi-language support. Format dates in any locale with simple, customizable options.

🌟 Features

• Simple API with intuitive parameters
• Multiple format styles (simple, long, full)
• Support for any locale (en, es, fr, de, ja, zh, etc.)
• Date-only and date-time formatting
• Default parameters for quick usage
• Error handling with helpful messages
• Zero dependencies

📦 Installation

npm install sofi-date

🚀 Quick Start

const { formatDate, formatDateTime, formatLong, formatFull } = require('sofi-date');

// Current date in different locales
console.log(formatDate());                  // 04/17/2025 (default)
console.log(formatDate(new Date(), 'es'));  // 17/04/2025 (Spanish)
console.log(formatDate(new Date(), 'fr'));  // 17/04/2025 (French)

// Different format styles
console.log(formatLong(new Date(), 'en'));  // April 17, 2025
console.log(formatFull(new Date(), 'es'));  // jueves, 17 de abril de 2025

// With time
console.log(formatDateTime(new Date(), 'en'));  // 04/17/2025, 11:16:36

📚 API Documentation

Core Function

format(date, locale, options)

The main formatting function that all other functions use.

• Parameters:

  • date (Date|number|string, optional): Date to format. Defaults to current date.
  • locale (string, optional): Locale code (e.g., 'en', 'es'). Defaults to 'en'.
  • options (Object, optional): Formatting options.
    • includeTime (boolean): Whether to include time. Defaults to false.
    • style (string): Format style ('simple', 'long', 'full'). Defaults to 'simple'.

• Returns: Formatted date string

const { format } = require('sofi-date');

// With default options
format(new Date());  // 04/17/2025

// With time and full style
format(new Date(), 'es', { includeTime: true, style: 'full' });  
// jueves, 17 de abril de 2025, 11:16:36

Helper Functions

formatDate(date, locale, style)

Format a date without time.

• Parameters:

  • date (Date|number|string, optional): Date to format. Defaults to current date.
  • locale (string, optional): Locale code. Defaults to 'en'.
  • style (string, optional): Format style ('simple', 'long', 'full'). Defaults to 'simple'.

• Returns: Formatted date string

const { formatDate } = require('sofi-date');

formatDate();  // 04/17/2025
formatDate(new Date(), 'es');  // 17/04/2025
formatDate(new Date(), 'en', 'long');  // April 17, 2025

formatDateTime(date, locale, style)

Format a date with time.

• Parameters:

  • date (Date|number|string, optional): Date to format. Defaults to current date.
  • locale (string, optional): Locale code. Defaults to 'en'.
  • style (string, optional): Format style ('simple', 'full'). Defaults to 'simple'.

• Returns: Formatted date and time string

const { formatDateTime } = require('sofi-date');

formatDateTime();  // 04/17/2025, 11:16:36
formatDateTime(new Date(), 'es');  // 17/04/2025, 11:16:36
formatDateTime(new Date(), 'en', 'full');  // Thursday, April 17, 2025 at 11:16:36

formatLong(date, locale)

Format a date with month name (no weekday).

• Parameters:

  • date (Date|number|string, optional): Date to format. Defaults to current date.
  • locale (string, optional): Locale code. Defaults to 'en'.

• Returns: Formatted date string with month name

const { formatLong } = require('sofi-date');

formatLong();  // April 17, 2025
formatLong(new Date(), 'es');  // 17 de abril de 2025

formatFull(date, locale)

Format a date with weekday and month name.

• Parameters:

  • date (Date|number|string, optional): Date to format. Defaults to current date.
  • locale (string, optional): Locale code. Defaults to 'en'.

• Returns: Formatted date string with weekday and month name

const { formatFull } = require('sofi-date');

formatFull();  // Thursday, April 17, 2025
formatFull(new Date(), 'es');  // jueves, 17 de abril de 2025

formatFullDateTime(date, locale)

Format a date and time with weekday and month name.

• Parameters:

  • date (Date|number|string, optional): Date to format. Defaults to current date.
  • locale (string, optional): Locale code. Defaults to 'en'.

• Returns: Formatted date and time string with weekday and month name

const { formatFullDateTime } = require('sofi-date');

formatFullDateTime();  // Thursday, April 17, 2025 at 11:16:36
formatFullDateTime(new Date(), 'es');  // jueves, 17 de abril de 2025, 11:16:36

🌎 Locale Support

The library supports any valid locale code using JavaScript's native Intl API. Some examples:

| Code | Language | Example Output | |------|----------|---------------| | 'en' | English | April 17, 2025 | | 'es' | Spanish | 17 de abril de 2025 | | 'fr' | French | 17 avril 2025 | | 'de' | German | 17. April 2025 | | 'it' | Italian | 17 aprile 2025 | | 'ja' | Japanese | 2025年4月17日 | | 'pt' | Portuguese | 17 de abril de 2025 | | 'ru' | Russian | 17 апреля 2025 г. | | 'zh' | Chinese | 2025年4月17日 | | 'ar' | Arabic | ١٧ أبريل ٢٠٢٥ |

You can also use country-specific locale codes like 'en-US', 'en-GB', 'es-ES', 'es-MX', etc.

📋 Examples

Different Locales

const { formatLong } = require('sofi-date');
const birthday = new Date(1990, 0, 15);  // January 15, 1990

console.log(formatLong(birthday, 'en'));  // January 15, 1990
console.log(formatLong(birthday, 'es'));  // 15 de enero de 1990
console.log(formatLong(birthday, 'fr'));  // 15 janvier 1990
console.log(formatLong(birthday, 'de'));  // 15. Januar 1990
console.log(formatLong(birthday, 'ja'));  // 1990年1月15日

Format Styles

const { formatDate } = require('sofi-date');
const meeting = new Date(2023, 5, 15);  // June 15, 2023

// Simple style (numeric)
console.log(formatDate(meeting, 'en', 'simple'));  // 06/15/2023

// Long style (with month name)
console.log(formatDate(meeting, 'en', 'long'));  // June 15, 2023

// Full style (with weekday and month name)
console.log(formatDate(meeting, 'en', 'full'));  // Thursday, June 15, 2023

Date and Time Formatting

const { formatDate, formatDateTime, formatFullDateTime } = require('sofi-date');
const call = new Date(2023, 5, 15, 14, 30, 0);  // June 15, 2023, 14:30:00

// Date only
console.log(formatDate(call, 'en'));  // 06/15/2023

// Date and time
console.log(formatDateTime(call, 'en'));  // 06/15/2023, 14:30:00

// Full date and time
console.log(formatFullDateTime(call, 'en'));  // Thursday, June 15, 2023 at 14:30:00

Error Handling

const { formatDate } = require('sofi-date');

try {
  // This will throw an error
  const result = formatDate('not a valid date', 'en');
  console.log(result);
} catch (error) {
  console.error('Error:', error.message);
  // Output: Error: Invalid date: not a valid date. Could not parse into a valid date.
}

// Invalid locales will fall back to 'en'
const result = formatDate(new Date(), 'invalid-locale');
console.log(result);  // 04/17/2025

📊 Real-World Use Cases

Blog Post Dates

const { formatLong } = require('sofi-date');

const publishDate = new Date(2023, 2, 15);  // March 15, 2023
console.log(`Published on ${formatLong(publishDate, 'en')}`);
// Published on March 15, 2023

Event Calendar

const { formatFull, formatDateTime } = require('sofi-date');

const event = new Date(2023, 6, 4, 18, 30);  // July 4, 2023, 18:30
console.log(`Event: ${formatFull(event, 'en')}`);
// Event: Tuesday, July 4, 2023
console.log(`Starts at: ${formatDateTime(event, 'en')}`);
// Starts at: 07/04/2023, 18:30:00

International Application

const { formatFullDateTime } = require('sofi-date');

const userMeeting = new Date(2023, 5, 15, 14, 30);  // June 15, 2023, 14:30
const userLocale = getUserLocale();  // e.g., 'fr', 'de', 'ja'

console.log(`Your meeting is scheduled for: ${formatFullDateTime(userMeeting, userLocale)}`);
// French: Votre réunion est prévue pour: jeudi 15 juin 2023 à 14:30:00

📜 License

MIT © Angela Sofia Osorio - SofiDev

sofi-date

A flexible date formatter for Node.js with support for both international (YYYY-MM-DD) and US (MM/DD/YYYY) formats. Easily format dates in different languages and styles.

Installation

npm install sofi-date

Usage

const { formateFull, formateShort } = require('sofi-date');

// Full date formatting
console.log(formateFull("2025-03-17T22:17:15", "es-ES")); // "17 de Marzo de 2025"
console.log(formateFull("2025-03-17T22:17:15", "en-US")); // "March 17, 2025"

// Short date formatting
console.log(formateShort("2025-03-17T22:17:15", "es-ES")); // "17/Mar/2025"
console.log(formateShort("2025-03-17T22:17:15", "en-US")); // "Mar/17/2025"

Supported Locales

Currently, the library fully supports the following locales:

• es-ES (Spanish)
• en-US (English - United States)

Other locales may work but have not been specifically tested or optimized.

API Reference

formateFull(date, locale)

Formats a date into its full text representation based on the specified locale.

Parameters:

• date (String|Date): The date to format. Can be a Date object or a string parseable by the Date constructor.
• locale (String): The locale to use for formatting (e.g., "es-ES", "en-US").

Returns:

• (String): The formatted date string in full text format.

Examples:

formateFull("2025-03-17", "es-ES"); // "17 de Marzo de 2025"
formateFull("2025-03-17", "en-US"); // "March 17, 2025"

formateShort(date, locale)

Formats a date into a short representation with abbreviated month name.

Parameters:

• date (String|Date): The date to format. Can be a Date object or a string parseable by the Date constructor.
• locale (String): The locale to use for formatting (e.g., "es-ES", "en-US").

Returns:

• (String): The formatted date string in abbreviated format. Examples:

formateShort("2025-03-17", "es-ES"); // "17/Mar/2025"
formateShort("2025-03-17", "en-US"); // "Mar/17/2025"

Support Development ☕

MIT Licensed | Full Documentation