Duration Operations

/**
 * Create a Duration instance
 * @param inp - Duration input (number, string, object, Duration, or from/to object)
 * @param unit - Unit of time when inp is number/string
 * @returns New Duration instance
 */
function duration(inp?: DurationInputArg1, unit?: DurationInputArg2): Duration;

// Input types
type DurationInputArg1 = Duration | number | string | FromTo | DurationInputObject | void;
type DurationInputArg2 = unitOfTime.DurationConstructor;

interface DurationInputObject extends MomentInputObject {
  quarters?: numberlike;
  quarter?: numberlike;
  Q?: numberlike;
  weeks?: numberlike;
  week?: numberlike;
  w?: numberlike;
}

interface FromTo {
  from: MomentInput;
  to: MomentInput;
}

// Duration constructor units
type DurationConstructor = "year" | "years" | "y" |
                          "quarter" | "quarters" | "Q" |
                          "month" | "months" | "M" |
                          "week" | "weeks" | "w" |
                          "isoWeek" | "isoWeeks" | "W" |
                          "day" | "days" | "d" |
                          "hour" | "hours" | "h" |
                          "minute" | "minutes" | "m" |
                          "second" | "seconds" | "s" |
                          "millisecond" | "milliseconds" | "ms";

import moment from "moment";

// From number and unit
const hours2 = moment.duration(2, "hours");
const minutes30 = moment.duration(30, "minutes");
const days5 = moment.duration(5, "days");

// From milliseconds (default unit)
const ms5000 = moment.duration(5000); // 5 seconds

// From object
const complex = moment.duration({
  years: 1,
  months: 2,
  days: 3,
  hours: 4,
  minutes: 5,
  seconds: 6
});

// From string (ISO 8601 duration format)
const iso = moment.duration("P1Y2M3DT4H5M6S"); // 1 year, 2 months, 3 days, 4 hours, 5 minutes, 6 seconds
const simple = moment.duration("2:30:45"); // 2 hours, 30 minutes, 45 seconds

// From two moments (time between them)
const start = moment("2023-12-25T10:00:00");
const end = moment("2023-12-25T15:30:00");
const between = moment.duration({ from: start, to: end });

// Clone existing duration
const original = moment.duration(2, "hours");
const copy = moment.duration(original);

console.log(hours2.asHours()); // 2
console.log(minutes30.asMinutes()); // 30
console.log(complex.asMilliseconds()); // Total milliseconds
console.log(between.asHours()); // 5.5 hours

/**
 * Add time to this duration
 * @param inp - Amount to add (number, string, Duration, or object)
 * @param unit - Unit of time when inp is number/string
 * @returns New Duration instance (original is not modified)
 */
add(inp?: DurationInputArg1, unit?: DurationInputArg2): Duration;

/**
 * Subtract time from this duration
 * @param inp - Amount to subtract (number, string, Duration, or object)
 * @param unit - Unit of time when inp is number/string
 * @returns New Duration instance (original is not modified)
 */
subtract(inp?: DurationInputArg1, unit?: DurationInputArg2): Duration;

/**
 * Get absolute value of duration (remove negative sign)
 * @returns New Duration instance with positive value
 */
abs(): Duration;

/**
 * Create a copy of this Duration instance
 * @returns New Duration instance with same values
 */
clone(): Duration;

import moment from "moment";

const duration1 = moment.duration(2, "hours");
const duration2 = moment.duration(30, "minutes");

// Add durations
const sum = duration1.add(duration2);
console.log(sum.asMinutes()); // 150 minutes (2.5 hours)

// Add with different input types
const base = moment.duration(1, "hour");
const added1 = base.add(30, "minutes");
const added2 = base.add({ minutes: 45, seconds: 30 });
const added3 = base.add("PT30M"); // ISO 8601 format

console.log(added1.asMinutes()); // 90 minutes
console.log(added2.asMinutes()); // 105.5 minutes
console.log(added3.asMinutes()); // 90 minutes

// Subtract durations
const total = moment.duration(3, "hours");
const remaining = total.subtract(45, "minutes");
console.log(remaining.asHours()); // 2.25 hours

// Absolute value
const negative = moment.duration(-2, "hours");
const positive = negative.abs();
console.log(negative.asHours()); // -2
console.log(positive.asHours()); // 2

// Chaining operations
const result = moment.duration(1, "day")
  .add(6, "hours")
  .subtract(30, "minutes")
  .add({ hours: 2, minutes: 15 });
console.log(result.asHours()); // 31.75 hours

// Clone to avoid mutation
const original = moment.duration(2, "hours");
const modified = original.clone().add(1, "hour");
console.log(original.asHours()); // 2 (unchanged)
console.log(modified.asHours()); // 3

/**
 * Get duration component for specific unit
 * @param units - Time unit to get
 * @returns Value for the specified unit
 */
get(units: unitOfTime.Base): number;

/**
 * Convert entire duration to specified unit
 * @param units - Time unit to convert to
 * @returns Total duration in specified unit
 */
as(units: unitOfTime.Base): number;

// Specific component getters (get portion of duration)
milliseconds(): number;
seconds(): number;
minutes(): number;
hours(): number;
days(): number;
weeks(): number;
months(): number;
years(): number;

// Total duration converters (convert entire duration)
asMilliseconds(): number;
asSeconds(): number;
asMinutes(): number;
asHours(): number;
asDays(): number;
asWeeks(): number;
asMonths(): number;
asYears(): number;

// Base units
type Base = "year" | "years" | "y" |
            "month" | "months" | "M" |
            "week" | "weeks" | "w" |
            "day" | "days" | "d" |
            "hour" | "hours" | "h" |
            "minute" | "minutes" | "m" |
            "second" | "seconds" | "s" |
            "millisecond" | "milliseconds" | "ms";

import moment from "moment";

// Create a complex duration
const duration = moment.duration({
  hours: 25,
  minutes: 90,
  seconds: 130
});

// Component getters (individual parts)
console.log(duration.hours()); // 1 (25 hours = 1 day + 1 hour)
console.log(duration.minutes()); // 32 (90 minutes + 130 seconds = 92 minutes = 1 hour + 32 minutes)
console.log(duration.seconds()); // 10 (130 seconds = 2 minutes + 10 seconds)
console.log(duration.days()); // 1 (from 25 hours)

// Total converters (entire duration in unit)
console.log(duration.asHours()); // 26.53... (total hours)
console.log(duration.asMinutes()); // 1592.17... (total minutes)
console.log(duration.asSeconds()); // 95530 (total seconds)
console.log(duration.asMilliseconds()); // 95530000 (total milliseconds)

// Generic get and as methods
console.log(duration.get("hours")); // 1 (component)
console.log(duration.as("hours")); // 26.53... (total)
console.log(duration.get("minutes")); // 32 (component)
console.log(duration.as("minutes")); // 1592.17... (total)

// Simple duration examples
const simple = moment.duration(2.5, "hours");
console.log(simple.hours()); // 2 (component)
console.log(simple.minutes()); // 30 (component)
console.log(simple.asHours()); // 2.5 (total)
console.log(simple.asMinutes()); // 150 (total)

// Negative durations
const negative = moment.duration(-75, "minutes");
console.log(negative.hours()); // -1
console.log(negative.minutes()); // -15
console.log(negative.asHours()); // -1.25

/**
 * Get human-readable representation of duration
 * @param argWithSuffix - Include "ago"/"in" suffix (default: false)
 * @param argThresholds - Custom thresholds for units
 * @returns Human-readable string like "2 hours", "a day"
 */
humanize(argWithSuffix?: boolean, argThresholds?: argThresholdOpts): string;
humanize(argThresholds?: argThresholdOpts): string;

/**
 * Get ISO 8601 duration string representation
 * @returns ISO 8601 formatted string like "PT2H30M"
 */
toISOString(): string;

/**
 * Get JSON representation (same as toISOString)
 * @returns ISO 8601 formatted string for JSON serialization
 */
toJSON(): string;

/**
 * Check if this duration represents a valid time span
 * @returns true if valid, false otherwise
 */
isValid(): boolean;

/**
 * Get numeric value (milliseconds, same as asMilliseconds)
 * @returns Duration in milliseconds
 */
valueOf(): number;

interface argThresholdOpts {
  ss?: number; // seconds
  s?: number;  // second
  m?: number;  // minute
  h?: number;  // hour
  d?: number;  // day
  w?: number | void; // week
  M?: number;  // month
}

import moment from "moment";

// Basic humanization
const duration1 = moment.duration(2, "hours");
const duration2 = moment.duration(90, "minutes");
const duration3 = moment.duration(1, "day");

console.log(duration1.humanize()); // "2 hours"
console.log(duration2.humanize()); // "an hour" (90 minutes rounds to 1 hour)
console.log(duration3.humanize()); // "a day"

// With suffix
console.log(duration1.humanize(true)); // "in 2 hours"
console.log(moment.duration(-2, "hours").humanize(true)); // "2 hours ago"

// Various durations
const examples = [
  moment.duration(45, "seconds"),
  moment.duration(2, "minutes"),
  moment.duration(1, "hour"),
  moment.duration(2, "days"),
  moment.duration(1, "week"),
  moment.duration(3, "months"),
  moment.duration(1, "year")
];

examples.forEach(d => {
  console.log(`${d.asMilliseconds()}ms -> ${d.humanize()}`);
});
// Output:
// "45000ms -> a few seconds"
// "120000ms -> 2 minutes" 
// "3600000ms -> an hour"
// "172800000ms -> 2 days"
// "604800000ms -> 7 days"
// "7776000000ms -> 3 months"
// "31536000000ms -> a year"

// ISO 8601 formatting
const complex = moment.duration({
  years: 1,
  months: 2,
  days: 3,
  hours: 4,
  minutes: 5,
  seconds: 6
});

console.log(complex.toISOString()); // "P1Y2M3DT4H5M6S"
console.log(duration1.toISOString()); // "PT2H"
console.log(moment.duration(90, "minutes").toISOString()); // "PT1H30M"

// JSON serialization
console.log(JSON.stringify({ duration: duration1 })); // {"duration":"PT2H"}

// Validation
console.log(duration1.isValid()); // true
console.log(moment.duration("invalid").isValid()); // false

// Numeric value
console.log(duration1.valueOf()); // 7200000 (milliseconds)
console.log(+duration1); // 7200000 (same as valueOf)

// Custom thresholds for humanize
const customDuration = moment.duration(90, "seconds");
console.log(customDuration.humanize()); // "2 minutes" (default)
console.log(customDuration.humanize({ ss: 60 })); // "a minute" (custom threshold)

/**
 * Get or set locale for this duration instance
 * @param locale - Locale identifier (when setting)
 * @returns Current locale string (when getting) or this duration (when setting)
 */
locale(): string;
locale(locale: LocaleSpecifier): Duration;

/**
 * Get locale data object for this duration's locale
 * @returns Locale data object
 */
localeData(): Locale;

type LocaleSpecifier = string | Moment | Duration | string[] | boolean;

import moment from "moment";

const duration = moment.duration(2, "hours");

// Default locale
console.log(duration.humanize()); // "2 hours"
console.log(duration.locale()); // "en"

// Set locale
const frenchDuration = duration.clone().locale("fr");
console.log(frenchDuration.humanize()); // "2 heures"
console.log(frenchDuration.locale()); // "fr"

// Different locales
const germanDuration = duration.clone().locale("de");
console.log(germanDuration.humanize()); // "2 Stunden"

// Relative time with suffix in different locales
const relativeDuration = moment.duration(30, "minutes");
console.log(relativeDuration.humanize(true)); // "in 30 minutes"
console.log(relativeDuration.clone().locale("fr").humanize(true)); // "dans 30 minutes"
console.log(relativeDuration.clone().locale("es").humanize(true)); // "en 30 minutos"

// Locale data
const localeData = frenchDuration.localeData();
console.log(localeData.relativeTime.h); // "une heure" (French hour format)

/**
 * Create duration from the difference between two moments
 * @param from - Start moment
 * @param to - End moment
 * @returns Duration representing the time between moments
 */
// Usage: moment.duration({ from: moment1, to: moment2 })

/**
 * Parse ISO 8601 duration strings
 * @param input - ISO 8601 duration string
 * @returns Duration instance
 */
// Usage: moment.duration("P1Y2M3DT4H5M6S")

import moment from "moment";

// Calculate age as duration
function getAge(birthDate) {
  const birth = moment(birthDate);
  const now = moment();
  return moment.duration({ from: birth, to: now });
}

const age = getAge("1990-06-15");
console.log(age.humanize()); // "33 years" (approximate)
console.log(age.asYears()); // 33.5... (precise)

// Time remaining calculations
function timeUntil(targetDate) {
  const target = moment(targetDate);
  const now = moment();
  return moment.duration({ from: now, to: target });
}

const christmas = timeUntil("2024-12-25");
console.log(christmas.humanize()); // "11 months" (approximate)
console.log(`${christmas.days()} days remaining`); // Exact days

// Working time calculations
function calculateWorkingHours(startTime, endTime, breaks = []) {
  let totalTime = moment.duration({ from: startTime, to: endTime });
  
  breaks.forEach(breakPeriod => {
    const breakDuration = moment.duration({
      from: breakPeriod.start,
      to: breakPeriod.end
    });
    totalTime = totalTime.subtract(breakDuration);
  });
  
  return totalTime;
}

const workStart = moment("2023-12-25T09:00:00");
const workEnd = moment("2023-12-25T17:30:00");
const breaks = [
  { start: moment("2023-12-25T12:00:00"), end: moment("2023-12-25T13:00:00") },
  { start: moment("2023-12-25T15:00:00"), end: moment("2023-12-25T15:15:00") }
];

const workingTime = calculateWorkingHours(workStart, workEnd, breaks);
console.log(workingTime.asHours()); // 7.25 hours

// Duration formatting for timers
function formatTimer(milliseconds) {
  const duration = moment.duration(milliseconds);
  const hours = String(Math.floor(duration.asHours())).padStart(2, '0');
  const minutes = String(duration.minutes()).padStart(2, '0');
  const seconds = String(duration.seconds()).padStart(2, '0');
  return `${hours}:${minutes}:${seconds}`;
}

console.log(formatTimer(3661000)); // "01:01:01"
console.log(formatTimer(7323000)); // "02:02:03"

// Sum multiple durations
function sumDurations(durations) {
  return durations.reduce((total, current) => {
    return total.add(current);
  }, moment.duration(0));
}

const durations = [
  moment.duration(1, "hour"),
  moment.duration(30, "minutes"),
  moment.duration(45, "minutes"),
  moment.duration(15, "minutes")
];

const total = sumDurations(durations);
console.log(total.asHours()); // 2.5 hours

// Parse complex duration strings
const isoDurations = [
  "PT1H30M",          // 1 hour 30 minutes
  "P1DT2H",           // 1 day 2 hours
  "P1Y2M3DT4H5M6S",   // Complex duration
  "PT45S"             // 45 seconds
];

isoDurations.forEach(iso => {
  const duration = moment.duration(iso);
  console.log(`${iso} -> ${duration.humanize()}`);
});

// Default thresholds (approximate)
// ss: 44 seconds -> "a few seconds"
// s: 44 seconds -> "a minute" 
// m: 44 minutes -> "an hour"
// h: 21 hours -> "a day"
// d: 25 days -> "a month"
// M: 10 months -> "a year"