timezone-friendly

TimeZoneFriendly

TimeZoneFriendly is a lightweight, easy-to-use library for automatically converting and formatting date and time strings based on the user's time zone. It’s designed for both JavaScript and React, with features like customizable friendly text (e.g., "2 hours ago"), time zone conversions, and flexible date formats.

Features

• Time Zone Conversion: Easily convert a date or time from one time zone to another.
• Customizable Date and Time Formats: Display dates in any format you need.
• Friendly Time Display: Display relative times like "yesterday" or "in 3 days".
• Customizable Friendly Text: Replace "0 minutes ago" with "just now", or future dates with "soon".
• Multiple Input Formats: Supports ISO strings, Unix timestamps, and custom date formats.
• Future Date Handling: Displays phrases for future dates like "in 2 hours" or "next week".
• Optional Date and Time Display: Show just the date, just the time, or both based on your needs.
• Caching: Optimizes performance by caching results for repeated date inputs.
• TypeScript Support: Fully typed for TypeScript users.

Installation

You can install the package via npm:

npm install timezone-friendly

Usage

Here’s a basic example of how to use TimeZoneFriendly in a React component:

import React from "react";
import TimeZoneFriendly from "timezone-friendly";

const App = () => {
  const date = "2024-09-26T12:00:00Z"; // Example ISO date

  // Example of converting a date to a user's local time zone and formatting it.
  const formattedDate = TimeZoneFriendly(date, { friendly: true });

  return (
    <div>
      <h1>TimeZoneFriendly Demo</h1>
      <p>Friendly Date: {formattedDate}</p>
    </div>
  );
};

export default App;

Props (Options)

Prop	Type	Description
friendly	boolean	Shows relative time like "2 hours ago" when true. Defaults to false.
formatString	string	Custom date format string. Defaults to "yyyy-MM-dd HH:mm:ss".
locale	string	Locale code for formatting (e.g., "en", "fr", "es"). Defaults to "en".
targetTimeZone	string	Converts date to a specific time zone (e.g., "America/New_York").
inputFormat	string	Format for parsing custom date inputs (e.g., "dd/MM/yyyy").
customText	object	Object to override default text for "just now" and "soon".
showDate	boolean	Controls whether the date is shown. Defaults to true.
showTime	boolean	Controls whether the time is shown. Defaults to true.

Examples

• Friendly Time Display Show relative times like "2 hours ago" or "yesterday":

const friendlyTime = TimeZoneFriendly("2024-09-26T12:00:00Z", { friendly: true });

• Custom Date Format Display a date in a custom format:

const customFormattedDate = TimeZoneFriendly("2024-09-26T12:00:00Z", { 
  friendly: false, 
  formatString: "dd/MM/yyyy" 
});

• Time Zone Conversion Convert a date to a specific time zone:

const timeZoneConvertedDate = TimeZoneFriendly("2024-09-26T12:00:00Z", { 
  friendly: false, 
  targetTimeZone: "America/New_York" 
});

• Custom Friendly Text Customize the display of "just now" and "soon":

const customText = TimeZoneFriendly(new Date(), { 
  friendly: true, 
  customText: { justNow: "just now", soon: "soon" }
});

• Optional Date and Time Display Show only the date or only the time:

const dateOnly = TimeZoneFriendly("2024-09-26T12:00:00Z", { friendly: false, showDate: true, showTime: false });
const timeOnly = TimeZoneFriendly("2024-09-26T12:00:00Z", { friendly: false, showDate: false, showTime: true });

Accessibility

The TimeZoneFriendly package is designed to be used in accessible applications, with keyboard and screen reader support in mind when rendering dates and times in a user-friendly format.

License

This project is licensed under the MIT License – see the LICENSE file for details.