tessl/npm-moment
Parse, validate, manipulate, and display dates and times in JavaScript with internationalization support
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Securityby
Pending
The risk profile of this skill
manipulation.mddocs/
Manipulation and Arithmetic
Date manipulation methods for adding/subtracting time, setting specific values, navigating to specific time boundaries, and timezone operations on Moment instances.
Capabilities
Arithmetic Operations
Methods for adding and subtracting time amounts from Moment instances.
/**
* Add time to this moment
* @param amount - Amount to add (number, string, Duration, or object)
* @param unit - Unit of time when amount is number/string
* @returns This moment instance (for chaining)
*/
add(amount?: DurationInputArg1, unit?: DurationInputArg2): Moment;
/**
* Subtract time from this moment
* @param amount - Amount to subtract (number, string, Duration, or object)
* @param unit - Unit of time when amount is number/string
* @returns This moment instance (for chaining)
*/
subtract(amount?: DurationInputArg1, unit?: DurationInputArg2): Moment;
// Input types
type DurationInputArg1 = Duration | number | string | FromTo | DurationInputObject | void;
type DurationInputArg2 = unitOfTime.DurationConstructor;
interface FromTo {
from: MomentInput;
to: MomentInput;
}
interface DurationInputObject extends MomentInputObject {
quarters?: numberlike;
quarter?: numberlike;
Q?: numberlike;
weeks?: numberlike;
week?: numberlike;
w?: numberlike;
}Usage Examples:
import moment from "moment";
const date = moment("2023-12-25T15:30:00");
// Add time (various units)
console.log(date.clone().add(1, "day").format()); // "2023-12-26T15:30:00"
console.log(date.clone().add(2, "hours").format()); // "2023-12-25T17:30:00"
console.log(date.clone().add(30, "minutes").format()); // "2023-12-25T16:00:00"
console.log(date.clone().add(1, "week").format()); // "2024-01-01T15:30:00"
console.log(date.clone().add(1, "month").format()); // "2024-01-25T15:30:00"
console.log(date.clone().add(1, "year").format()); // "2024-12-25T15:30:00"
// Subtract time
console.log(date.clone().subtract(1, "day").format()); // "2023-12-24T15:30:00"
console.log(date.clone().subtract(2, "hours").format()); // "2023-12-25T13:30:00"
console.log(date.clone().subtract(1, "month").format()); // "2023-11-25T15:30:00"
// Add with object notation
console.log(date.clone().add({
years: 1,
months: 2,
days: 3,
hours: 4
}).format()); // "2025-02-28T19:30:00"
// Add with Duration object
const duration = moment.duration(2, "hours");
console.log(date.clone().add(duration).format()); // "2023-12-25T17:30:00"
// Chaining operations
const result = date.clone()
.add(1, "week")
.subtract(2, "days")
.add(3, "hours");
console.log(result.format()); // "2023-12-30T18:30:00"Start and End of Time Periods
Navigate to the beginning or end of various time periods.
/**
* Set to the start of a unit of time
* @param unitOfTime - Time unit to start of
* @returns This moment instance (mutates original)
*/
startOf(unitOfTime: unitOfTime.StartOf): Moment;
/**
* Set to the end of a unit of time
* @param unitOfTime - Time unit to end of
* @returns This moment instance (mutates original)
*/
endOf(unitOfTime: unitOfTime.StartOf): Moment;
// StartOf units
type StartOf = "year" | "years" | "y" |
"quarter" | "quarters" | "Q" |
"month" | "months" | "M" |
"week" | "weeks" | "w" |
"isoWeek" | "isoWeeks" | "W" |
"day" | "days" | "d" |
"date" | "dates" | "D" |
"hour" | "hours" | "h" |
"minute" | "minutes" | "m" |
"second" | "seconds" | "s" |
"millisecond" | "milliseconds" | "ms";Usage Examples:
import moment from "moment";
const date = moment("2023-12-25T15:30:45.123");
// Start of time periods
console.log(date.clone().startOf("year").format()); // "2023-01-01T00:00:00"
console.log(date.clone().startOf("month").format()); // "2023-12-01T00:00:00"
console.log(date.clone().startOf("week").format()); // "2023-12-24T00:00:00" (Sunday)
console.log(date.clone().startOf("isoWeek").format()); // "2023-12-25T00:00:00" (Monday)
console.log(date.clone().startOf("day").format()); // "2023-12-25T00:00:00"
console.log(date.clone().startOf("hour").format()); // "2023-12-25T15:00:00"
console.log(date.clone().startOf("minute").format()); // "2023-12-25T15:30:00"
console.log(date.clone().startOf("second").format()); // "2023-12-25T15:30:45"
// End of time periods
console.log(date.clone().endOf("year").format()); // "2023-12-31T23:59:59"
console.log(date.clone().endOf("month").format()); // "2023-12-31T23:59:59"
console.log(date.clone().endOf("week").format()); // "2023-12-30T23:59:59" (Saturday)
console.log(date.clone().endOf("day").format()); // "2023-12-25T23:59:59"
console.log(date.clone().endOf("hour").format()); // "2023-12-25T15:59:59"
console.log(date.clone().endOf("minute").format()); // "2023-12-25T15:30:59"
// Quarter boundaries
console.log(date.clone().startOf("quarter").format()); // "2023-10-01T00:00:00" (Q4)
console.log(date.clone().endOf("quarter").format()); // "2023-12-31T23:59:59"
// Common use cases
const startOfToday = moment().startOf("day");
const endOfMonth = moment().endOf("month");
const startOfWeek = moment().startOf("week");Timezone Operations
Methods for converting between timezones and managing UTC offsets.
/**
* Convert to local time
* @param keepLocalTime - Keep the same local time when converting (default: false)
* @returns This moment instance
*/
local(keepLocalTime?: boolean): Moment;
/**
* Convert to UTC time
* @param keepLocalTime - Keep the same local time when converting (default: false)
* @returns This moment instance
*/
utc(keepLocalTime?: boolean): Moment;
/**
* Get current UTC offset in minutes, or set new offset
* @param b - Offset in minutes (number) or offset string like "+05:00"
* @param keepLocalTime - Keep the same local time when setting offset
* @returns Current offset (when getting) or this moment (when setting)
*/
utcOffset(): number;
utcOffset(b: number|string, keepLocalTime?: boolean): Moment;
/**
* Parse input while keeping original timezone offset
* @returns This moment instance with preserved timezone
*/
parseZone(): Moment;
/**
* Check if this moment is in local time mode
* @returns true if in local time, false if UTC
*/
isLocal(): boolean;
/**
* Check if this moment is in UTC mode
* @returns true if in UTC, false if local
*/
isUTC(): boolean;
/**
* @deprecated Use isUTC() instead. This alias is deprecated.
*/
isUtc(): boolean;
/**
* Check if UTC offset has been explicitly set
* @returns true if offset is set, false otherwise
*/
isUtcOffset(): boolean;Usage Examples:
import moment from "moment";
// Create moments in different modes
const localMoment = moment("2023-12-25T15:30:00");
const utcMoment = moment.utc("2023-12-25T15:30:00");
console.log(localMoment.format()); // Local interpretation
console.log(utcMoment.format()); // UTC interpretation
// Convert between local and UTC
const local = moment("2023-12-25T15:30:00");
console.log(local.isLocal()); // true
console.log(local.isUTC()); // false
const asUtc = local.clone().utc();
console.log(asUtc.isUTC()); // true
console.log(asUtc.format()); // Converted to UTC
const backToLocal = asUtc.clone().local();
console.log(backToLocal.isLocal()); // true
// UTC offset operations
const withOffset = moment.utc("2023-12-25T15:30:00");
console.log(withOffset.utcOffset()); // 0 (UTC)
// Set timezone offset
withOffset.utcOffset(300); // +5 hours
console.log(withOffset.format()); // Time adjusted for +5 offset
console.log(withOffset.utcOffset()); // 300 minutes
// Set offset with string
withOffset.utcOffset("+08:00");
console.log(withOffset.utcOffset()); // 480 minutes
// Keep local time when changing offset
const keepTime = moment("2023-12-25T15:30:00+05:00");
keepTime.utcOffset("-08:00", true); // Keeps 15:30 local time
console.log(keepTime.format()); // Same local time, different offset
// Parse and preserve timezone
const parsed = moment.parseZone("2023-12-25T15:30:00-05:00");
console.log(parsed.utcOffset()); // -300 (5 hours behind UTC)
console.log(parsed.format()); // Maintains original offsetAdvanced Manipulation
More complex manipulation operations and utility methods.
/**
* Check if this moment has aligned hour offset with another moment
* @param other - Other moment to compare with (defaults to current time)
* @returns true if hour offsets are aligned
*/
hasAlignedHourOffset(other?: MomentInput): boolean;
/**
* Get timezone abbreviation (like "PST", "GMT")
* @returns Timezone abbreviation string
*/
zoneAbbr(): string;
/**
* Get timezone name (like "Pacific Standard Time")
* @returns Timezone name string
*/
zoneName(): string;
/**
* Check if current time is during Daylight Saving Time
* @returns true if in DST, false otherwise
*/
isDST(): boolean;
/**
* Check if current year is a leap year
* @returns true if leap year, false otherwise
*/
isLeapYear(): boolean;
/**
* Get number of days in the current month
* @returns Number of days (28-31)
*/
daysInMonth(): number;
/**
* Get number of weeks in the current year
* @returns Number of weeks (52 or 53)
*/
weeksInYear(): number;
/**
* Get number of weeks in the current week year
* @returns Number of weeks (52 or 53)
*/
weeksInWeekYear(): number;
/**
* Get number of ISO weeks in the current year
* @returns Number of ISO weeks (52 or 53)
*/
isoWeeksInYear(): number;
/**
* Get number of ISO weeks in the current ISO week year
* @returns Number of ISO weeks (52 or 53)
*/
isoWeeksInISOWeekYear(): number;Usage Examples:
import moment from "moment";
const date = moment("2023-12-25T15:30:00");
// Timezone information
console.log(date.zoneAbbr()); // Timezone abbreviation
console.log(date.zoneName()); // Full timezone name
console.log(date.isDST()); // false (December, not DST)
// Calendar information
console.log(date.isLeapYear()); // false (2023 is not a leap year)
console.log(date.daysInMonth()); // 31 (December has 31 days)
// Week information
console.log(date.weeksInYear()); // 52 or 53
console.log(date.isoWeeksInYear()); // 52 or 53
// Hour alignment
const moment1 = moment("2023-12-25T15:30:00+05:00");
const moment2 = moment("2023-12-25T10:30:00+00:00"); // Same UTC time
console.log(moment1.hasAlignedHourOffset(moment2)); // true
// Leap year examples
console.log(moment("2024-02-01").isLeapYear()); // true (2024 is leap year)
console.log(moment("2024-02-01").daysInMonth()); // 29 (February in leap year)
console.log(moment("2023-02-01").daysInMonth()); // 28 (February in normal year)Immutable Operations
While Moment.js mutates the original instance by default, you can create immutable operations using clone().
/**
* Create a copy of this Moment instance
* @returns New Moment instance with same date/time and settings
*/
clone(): Moment;Immutable Patterns:
import moment from "moment";
const original = moment("2023-12-25T15:30:00");
// Mutating operations (change original)
const mutated = original.add(1, "day");
console.log(original === mutated); // true (same object)
console.log(original.format()); // "2023-12-26T15:30:00" (changed)
// Immutable operations (preserve original)
const original2 = moment("2023-12-25T15:30:00");
const immutable = original2.clone().add(1, "day");
console.log(original2 === immutable); // false (different objects)
console.log(original2.format()); // "2023-12-25T15:30:00" (unchanged)
console.log(immutable.format()); // "2023-12-26T15:30:00" (changed)
// Chaining immutable operations
const result = moment("2023-12-25T15:30:00")
.clone()
.startOf("month")
.add(15, "days")
.endOf("day");
// Common immutable patterns
const now = moment();
const startOfWeek = now.clone().startOf("week");
const endOfWeek = now.clone().endOf("week");
const nextMonth = now.clone().add(1, "month");
const lastYear = now.clone().subtract(1, "year");Time Unit Types
// Unit of time namespace
namespace unitOfTime {
// Base units for most operations
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";
// Units for duration constructor
type DurationConstructor = Base | "quarter" | "quarters" | "Q" |
"isoWeek" | "isoWeeks" | "W";
// Units for startOf/endOf operations
type StartOf = Base | "quarter" | "quarters" | "Q" |
"isoWeek" | "isoWeeks" | "W" |
"date" | "dates" | "D";
// Units for diff operations
type Diff = Base | "quarter" | "quarters" | "Q";
// All available units
type All = Base | "quarter" | "quarters" | "Q" |
"isoWeek" | "isoWeeks" | "W" |
"date" | "dates" | "D" |
"weekYear" | "weekYears" | "gg" |
"isoWeekYear" | "isoWeekYears" | "GG" |
"dayOfYear" | "dayOfYears" | "DDD" |
"weekday" | "weekdays" | "e" |
"isoWeekday" | "isoWeekdays" | "E";
}