Friendly Timestamp

friendly-timestamp is a simple npm package designed to manage and format timestamps in a user-friendly manner. This package provides easy-to-use functions to display how long ago a date was, format timestamps, and calculate the difference between two timestamps.

Table of Contents

• Installation
• Usage
  • Get a Human-Friendly Time Ago
  • Format a Timestamp
  • Calculate the Difference Between Two Timestamps
• Examples

Installation

To install friendly-timestamp, use npm:

npm install friendly-timestamp

Usage

Importing the Package

You can import the package into your JavaScript file as follows:

const {
  timeAgo,
  formatTimestamp,
  calculateDifference,
} = require("friendly-timestamp");

1. Get a Human-Friendly Time Ago

The timeAgo function converts a date string into a human-readable format that indicates how long ago that date was.

Syntax

timeAgo(dateString);

Example

const ago = timeAgo("2024-10-01T12:00:00Z");
console.log(ago); // Output: "4 days ago" (if today is October 5, 2024)

2. Format a Timestamp

The formatTimestamp function formats a given timestamp into either an ISO string or a descriptive format.

Syntax

formatTimestamp(dateString, format);

Parameters

• dateString: A date string in ISO format.
• format: A string that specifies the format. It can be either 'ISO' or 'DESCRIPTIVE'. The default is 'ISO'.

Example

const formattedISO = formatTimestamp("2024-10-01T12:00:00Z", "ISO");
console.log(formattedISO); // Output: "10/01/2024, 12:00:00 PM"

const formattedDescriptive = formatTimestamp(
  "2024-10-01T12:00:00Z",
  "DESCRIPTIVE"
);
console.log(formattedDescriptive); // Output: "Tuesday, October 1, 2024"

3. Calculate the Difference Between Two Timestamps

The calculateDifference function calculates the difference between two timestamps, returning the difference in seconds, minutes, hours, and days.

Syntax

calculateDifference(startDateString, endDateString);

Example

const difference = calculateDifference(
  "2024-10-01T12:00:00Z",
  "2024-10-05T12:00:00Z"
);
console.log(difference);
// Output: { seconds: 345600, minutes: 5760, hours: 96, days: 4 }

Examples

Here are a few complete examples demonstrating the usage of all functions in the package:

const {
  timeAgo,
  formatTimestamp,
  calculateDifference,
} = require("friendly-timestamp");

// Example 1: Get a human-friendly time ago
const timeSince = timeAgo("2024-10-01T12:00:00Z");
console.log(`Time since: ${timeSince}`); // Output: "Time since: 4 days ago" (if today is October 5, 2024)

// Example 2: Format a timestamp to ISO format
const isoFormat = formatTimestamp("2024-10-01T12:00:00Z", "ISO");
console.log(`ISO Format: ${isoFormat}`); // Output: "ISO Format: 10/01/2024, 12:00:00 PM"

// Example 3: Format a timestamp to Descriptive format
const descriptiveFormat = formatTimestamp(
  "2024-10-01T12:00:00Z",
  "DESCRIPTIVE"
);
console.log(`Descriptive Format: ${descriptiveFormat}`); // Output: "Descriptive Format: Tuesday, October 1, 2024"

// Example 4: Calculate difference between two timestamps
const diff = calculateDifference(
  "2024-10-01T12:00:00Z",
  "2024-10-05T12:00:00Z"
);
console.log(`Difference: ${JSON.stringify(diff)}`);
// Output: "Difference: {"seconds":345600,"minutes":5760,"hours":96,"days":4}"