Moment Creation and Parsing

/**
 * Create a Moment instance from various input types
 * @param inp - Input to parse (string, Date, number, array, object, or another Moment)
 * @param strict - Enable strict parsing mode (disables fallback to native Date constructor)
 * @returns New Moment instance
 */
function moment(inp?: MomentInput, strict?: boolean): Moment;

/**
 * Create a Moment instance with format specification
 * @param inp - Input to parse
 * @param format - Format specification string or array of formats
 * @param strict - Enable strict parsing (format and input must match exactly)
 * @returns New Moment instance
 */
function moment(inp?: MomentInput, format?: MomentFormatSpecification, strict?: boolean): Moment;

/**
 * Create a Moment instance with format and locale
 * @param inp - Input to parse
 * @param format - Format specification
 * @param language - Locale string for parsing
 * @param strict - Enable strict parsing
 * @returns New Moment instance
 */
function moment(inp?: MomentInput, format?: MomentFormatSpecification, language?: string, strict?: boolean): Moment;

import moment from "moment";

// Current date/time
const now = moment();

// From string (ISO 8601)
const date1 = moment("2023-12-25");
const date2 = moment("2023-12-25T15:30:00Z");

// From Date object
const date3 = moment(new Date());

// From timestamp (milliseconds)
const date4 = moment(1640447400000);

// From array [year, month, day, hour, minute, second, millisecond]
const date5 = moment([2023, 11, 25, 15, 30, 0, 0]); // Note: month is 0-indexed

// From object
const date6 = moment({
  year: 2023,
  month: 11, // December (0-indexed)
  day: 25,
  hour: 15,
  minute: 30
});

// With format string
const date7 = moment("25/12/2023", "DD/MM/YYYY");
const date8 = moment("December 25, 2023 3:30 PM", "MMMM DD, YYYY h:mm A");

// Strict parsing
const date9 = moment("2023-12-25", "YYYY-MM-DD", true); // Must match exactly
const invalid = moment("2023/12/25", "YYYY-MM-DD", true); // Invalid because format doesn't match

// Multiple formats
const date10 = moment("2023-12-25", ["MM/DD/YYYY", "YYYY-MM-DD"]); // Tries both formats

// With locale
const date11 = moment("25 décembre 2023", "DD MMMM YYYY", "fr");

/**
 * Create a UTC Moment instance
 * @param inp - Input to parse
 * @param strict - Enable strict parsing mode
 * @returns New Moment instance in UTC mode
 */
function utc(inp?: MomentInput, strict?: boolean): Moment;

/**
 * Create a UTC Moment instance with format specification
 * @param inp - Input to parse
 * @param format - Format specification
 * @param strict - Enable strict parsing
 * @returns New Moment instance in UTC mode
 */
function utc(inp?: MomentInput, format?: MomentFormatSpecification, strict?: boolean): Moment;

/**
 * Create a UTC Moment instance with format and locale
 * @param inp - Input to parse
 * @param format - Format specification
 * @param language - Locale string
 * @param strict - Enable strict parsing
 * @returns New Moment instance in UTC mode
 */
function utc(inp?: MomentInput, format?: MomentFormatSpecification, language?: string, strict?: boolean): Moment;

import moment from "moment";

// Current UTC time
const nowUtc = moment.utc();

// Parse as UTC
const utcDate1 = moment.utc("2023-12-25T15:30:00");
const utcDate2 = moment.utc("25/12/2023 15:30", "DD/MM/YYYY HH:mm");

// Compare local vs UTC
const local = moment("2023-12-25T15:30:00");
const utc = moment.utc("2023-12-25T15:30:00");
console.log(local.format()); // Interprets as local time
console.log(utc.format());   // Interprets as UTC time

/**
 * Create a Moment instance from Unix timestamp
 * @param timestamp - Unix timestamp in seconds (not milliseconds)
 * @returns New Moment instance
 */
function unix(timestamp: number): Moment;

import moment from "moment";

// From Unix timestamp (seconds)
const date1 = moment.unix(1640447400); // December 25, 2021 15:30:00 UTC

// Note: moment() constructor uses milliseconds, unix() uses seconds
const date2 = moment(1640447400000); // Same date using milliseconds
const date3 = moment.unix(1640447400); // Same date using seconds

console.log(date2.isSame(date3)); // true

/**
 * Parse input while keeping original timezone offset
 * @param inp - Input to parse
 * @param format - Format specification
 * @param strict - Enable strict parsing
 * @returns New Moment instance with preserved timezone
 */
function parseZone(inp?: MomentInput, format?: MomentFormatSpecification, strict?: boolean): Moment;

/**
 * Parse input with format and locale while keeping timezone
 * @param inp - Input to parse  
 * @param format - Format specification
 * @param language - Locale string
 * @param strict - Enable strict parsing
 * @returns New Moment instance with preserved timezone
 */
function parseZone(inp?: MomentInput, format?: MomentFormatSpecification, language?: string, strict?: boolean): Moment;

import moment from "moment";

// Parse with timezone preservation
const date1 = moment.parseZone("2023-12-25T15:30:00-05:00");
const date2 = moment.parseZone("2023-12-25T15:30:00+03:00");

console.log(date1.format()); // Maintains -05:00 offset
console.log(date2.format()); // Maintains +03:00 offset

// Compare with regular parsing
const regular = moment("2023-12-25T15:30:00-05:00"); // Converts to local timezone
const parseZone = moment.parseZone("2023-12-25T15:30:00-05:00"); // Keeps original timezone

console.log(regular.utcOffset()); // Local timezone offset
console.log(parseZone.utcOffset()); // -300 (5 hours behind UTC)

/**
 * Create a copy of this Moment instance
 * @returns New Moment instance with same date/time and settings
 */
clone(): Moment;

import moment from "moment";

const original = moment("2023-12-25");
const copy = original.clone();

// Modifications to copy don't affect original
copy.add(1, "day");
console.log(original.format("YYYY-MM-DD")); // "2023-12-25"
console.log(copy.format("YYYY-MM-DD"));     // "2023-12-26"

type MomentInput = Moment | Date | string | number | (number | string)[] | MomentInputObject | void;

interface MomentInputObject {
  years?: numberlike;
  year?: numberlike;
  y?: numberlike;
  months?: numberlike;
  month?: numberlike;
  M?: numberlike;
  days?: numberlike;
  day?: numberlike;
  d?: numberlike;
  dates?: numberlike;
  date?: numberlike;
  D?: numberlike;
  hours?: numberlike;
  hour?: numberlike;
  h?: numberlike;
  minutes?: numberlike;
  minute?: numberlike;
  m?: numberlike;
  seconds?: numberlike;
  second?: numberlike;
  s?: numberlike;
  milliseconds?: numberlike;
  millisecond?: numberlike;
  ms?: numberlike;
}

type numberlike = number | string;

type MomentFormatSpecification = string | MomentBuiltinFormat | (string | MomentBuiltinFormat)[];

interface MomentBuiltinFormat {
  __momentBuiltinFormatBrand: any;
}

// Built-in format constants
const ISO_8601: MomentBuiltinFormat;
const RFC_2822: MomentBuiltinFormat;

/**
 * Create an invalid Moment instance with optional parsing flags
 * @param flags - Optional parsing flags for debugging
 * @returns Invalid Moment instance
 */
function invalid(flags?: MomentParsingFlagsOpt): Moment;

interface MomentParsingFlagsOpt {
  empty?: boolean;
  unusedTokens?: string[];
  unusedInput?: string[];
  overflow?: number;
  charsLeftOver?: number;
  nullInput?: boolean;
  invalidMonth?: string;
  invalidFormat?: boolean;
  userInvalidated?: boolean;
  iso?: boolean;
  parsedDateParts?: any[];
  meridiem?: string;
}

import moment from "moment";

// Create explicitly invalid moment
const invalid = moment.invalid();
console.log(invalid.isValid()); // false

// Invalid parsing results
const badDate = moment("not a date");
console.log(badDate.isValid()); // false
console.log(badDate.format()); // "Invalid date"

// Strict parsing with invalid input
const strictBad = moment("2023/12/25", "YYYY-MM-DD", true);
console.log(strictBad.isValid()); // false (format doesn't match)

/**
 * Check if this Moment instance represents a valid date
 * @returns true if valid, false otherwise
 */
isValid(): boolean;

/**
 * Get index of invalid field (for debugging parsing failures)
 * @returns Index of invalid field, or -1 if valid
 */
invalidAt(): number;

/**
 * Get creation metadata for this Moment instance
 * @returns Object containing input, format, locale, and other creation details
 */
creationData(): MomentCreationData;

/**
 * Get parsing flags for debugging parsing process
 * @returns Object containing parsing flags and error information
 */
parsingFlags(): MomentParsingFlags;

interface MomentCreationData {
  input: MomentInput;
  format?: MomentFormatSpecification;
  locale: Locale;
  isUTC: boolean;
  strict?: boolean;
}

interface MomentParsingFlags {
  empty: boolean;
  unusedTokens: string[];
  unusedInput: string[];
  overflow: number;
  charsLeftOver: number;
  nullInput: boolean;
  invalidMonth: string | void;
  invalidFormat: boolean;
  userInvalidated: boolean;
  iso: boolean;
  parsedDateParts: any[];
  meridiem: string | void;
}

import moment from "moment";

const date = moment("2023-13-45"); // Invalid date
console.log(date.isValid()); // false
console.log(date.invalidAt()); // 1 (month field is invalid)

const flags = date.parsingFlags();
console.log(flags.overflow); // 1 (indicates month overflow)
console.log(flags.invalidMonth); // null

const creation = date.creationData();
console.log(creation.input); // "2023-13-45"
console.log(creation.isUTC); // false