@oreefy/datetime

A lightweight, zero-dependency TypeScript date-time library for flexible pattern formatting, input binding, duration calculation, and relative time (ago).

@oreefy/datetime is a library built for the Oreefy ecosystem. The package is officially developed, maintained, and fully controlled by Oreefy, ensuring long-term stability, consistency, and compatibility across the ecosystem.

Required Capabilities

• JavaScript / TypeScript

API Reference

import { datetime } from "@oreefy/datetime";

datetime.now(); // Date object
datetime.add(); // Date object
datetime.less(); // Date object
datetime.isExpired(); // Boolean
datetime.duration(); // {seconds: number; minutes: number; hours: number; days: number; months: number; years: number}
datetime.ago(); // String
datetime.format(); // String

datetime.now()

import { datetime } from "@oreefy/datetime";

interface Options {
  date?: Date | string | number; // Default: new Date()
}

// Get current Date object (Default)
const now = datetime.now();

// Parse a custom date safely
const parsedDate = datetime.now({ date: "2020-10-02" });

// Invalid date fallback
// Returns current Date instead of NaN or Throwing Error
const safeDate = datetime.now({ date: "invalid-string" });

datetime.add()

import { datetime } from "@oreefy/datetime";

interface Options {
  ms: number; // Milliseconds to add
  date?: Date | string | number; // Default: datetime.now()
}

// Add 1 hour to current time
const future = datetime.add({ ms: 60 * 60 * 1000 });

// Add 30 mins to a specific date
const target = datetime.add({
  date: "2020-10-02T10:00:00",
  ms: 30 * 60 * 1000,
});

datetime.less()

import { datetime } from "@oreefy/datetime";

interface Options {
  ms: number; // Milliseconds to less
  date?: Date | string | number; // Default: datetime.now()
}

// Less 1 hour to current time
const past = datetime.less({ ms: 60 * 60 * 1000 });

// Less 30 mins to a specific date
const target = datetime.less({
  date: "2020-10-02T10:00:00",
  ms: 30 * 60 * 1000,
});

datetime.isExpired()

import { datetime } from "@oreefy/datetime";

interface Options {
  expiryDate: Date | string | number;
  currentDate?: Date | string | number; // Default: new Date()
}

// Check if an expiry date has passed relative to current time
const isExpired = datetime.isExpired({ expiryDate: "2020-10-02" }); // true

// Compare against a custom reference date
const isExpiredCustom = datetime.isExpired({
  expiryDate: "2020-12-31",
  currentDate: "2020-10-02",
}); // false

datetime.duration()

import { datetime } from "@oreefy/datetime";

interface Options {
  startDate: Date | string | number;
  endDate?: Date | string | number; // Default: new Date()
}

interface Return {
  seconds: number;
  minutes: number;
  hours: number;
  days: number;
  months: number;
  years: number;
}

// Calculate precise breakdown between two dates
// Result: { seconds: 0, minutes: 0, hours: 0, days: 8, months: 1, years: 1 }
const diff = datetime.duration({
  startDate: "2020-10-02",
  endDate: "2021-11-10",
});

// If endDate is earlier than startDate, returns all zeros
// Result: { seconds: 0, minutes: 0, hours: 0, days: 0, months: 0, years: 0 }
const invalidDiff = datetime.duration({
  startDate: "2021-11-10",
  endDate: "2020-10-02",
});

datetime.ago()

import { datetime } from "@oreefy/datetime";

interface Options {
  date: Date | string | number;
}

// Returns human-readable relative time string
datetime.ago({ date: Date.now() - 5000 }); // "Just now"
datetime.ago({ date: Date.now() - 120000 }); // "2m ago"
datetime.ago({ date: Date.now() - 3700000 }); // "1h 1m ago"

datetime.format()

import { datetime } from "@oreefy/datetime";

type FormatPattern =
  | "yyyy"
  | "month"
  | "mon"
  | "mm"
  | "dd"
  | "hh"
  | "m"
  | "ss"
  | "ampm";
type FormatSeparator = " " | "-" | "/" | ", " | ":";
type FormatPredefinedPattern =
  | "dd/mm/yyyy" // "02/10/2020"
  | "dd/mm/yyyy hh:m:ss ampm" // "02/10/2020 00:00 AM"
  | "mm/dd/yyyy" // "10/02/2020"
  | "mm/dd/yyyy hh:m:ss ampm" // "10/02/2020 00:00:00 AM"
  | "dd-mon-yyyy" // "02-Oct-2020"
  | "dd-mon-yyyy hh:m:ss ampm" // "02-Oct-2020 00:00:00 AM"
  | "dd mon yyyy" // "02 Oct 2020"
  | "dd mon yyyy, hh:m ampm" // "02 Oct 2020, 00:00 AM"
  | "dd month yyyy" // "02 October 2020"
  | "dd month yyyy, hh:m ampm" // "02 October 2020, 00:00 AM"
  | "yyyy-mm-dd" // "2020-10-02"
  | "yyyy-mm-dd hh:m ampm" // "2020-10-02 00:00 AM"
  | "yyyy-mm-ddThh:m:ss"; // "2020-10-02T00:00:00"

interface Options {
  date?: Date | string | number; // Default: datetime.now()
  pattern?: FormatPredefinedPattern | (FormatPattern | FormatSeparator)[]; // Default: "dd mon yyyy, hh:m ampm"
}

// Default formatting
// Returns: "02 Oct 2020, 00:00 AM"
datetime.format();
datetime.format({ date: "2020-10-02" });

// 2. Predefined statement patterns
datetime.format({ date: "2020-10-02", pattern: "dd/mm/yyyy" }); // "02/10/2020"
datetime.format({ date: "2020-10-02", pattern: "dd-mon-yyyy" }); // "02-Oct-2020"
datetime.format({ date: "2020-10-02", pattern: "dd month yyyy, hh:m ampm" }); // "02 October 2020, 03:06 PM"

// 3. HTML <input type="datetime-local"> ready (Auto 24-hour format)
datetime.format({ date: "2020-10-02", pattern: "yyyy-mm-ddThh:m:ss" }); // "2020-10-02T15:06:28"

// 4. Custom token array pattern
datetime.format({
  date: "2020-10-02",
  pattern: ["dd", "-", "mon", "-", "yyyy"],
}); // "02-Oct-2020"

About Oreefy

Oreefy is an affordable business ecosystem designed for small to enterprise businesses. Oreefy provides essential software you need for your modern business within a single ecosystem. It will save you significant time, effort, and money.

License

MIT © Oreefy