@zelgadis87/utils-core 5.2.10 → 5.2.11

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@zelgadis87/utils-core",
-  "version": "5.2.10",
+  "version": "5.2.11",
   "author": "Zelgadis87",
   "license": "ISC",
   "private": false,

package/src/time/TimeInstant.ts

@@ -2,7 +2,7 @@ import { ICancelable, ICancelablePromise } from "../async/Deferred.js";
 import { TComparisonResult } from "../sorting/_index.js";
 import TimeBase from "./TimeBase";
 import TimeDuration from "./TimeDuration";
-import { TTimeInstantBuilder, TTimeInstantCreationParameters, createTimeInstantFromParameters, timeInstantBuilder } from "./TimeInstantBuilder.js";
+import { TTimeInstantBuilder, TTimeInstantCreationParameters, createTimeInstantFromParameters, timeInstantBuilder, type TTimeInstantParameters } from "./TimeInstantBuilder.js";
 import { TimeUnit } from "./TimeUnit";
 import { TDayOfMonth, TDayOfWeek, THourOfDay, TIso8601DateString, TIso8601DateUtcString, TMillisecondOfSecond, TMinuteOfHour, TMonth, TSecondOfMinute, TWeekNumber } from "./types";
 
@@ -47,7 +47,10 @@ export class TimeInstant extends TimeBase<TimeInstant> {
 	}
 
 	public distanceFromStartOfDay(): TimeDuration {
-		return this.distanceFrom( this.atStartOfDay() );
+		// Calculate milliseconds since start of day directly without creating intermediate TimeInstant
+		const params = this.toParameters();
+		const msInDay = params.hours * 3600000 + params.minutes * 60000 + params.seconds * 1000 + params.milliseconds;
+		return TimeDuration.fromMs( msInDay );
 	}
 
 	public atStartOfDay(): TimeInstant {
@@ -55,7 +58,11 @@ export class TimeInstant extends TimeBase<TimeInstant> {
 	}
 
 	public distanceFromEndOfDay(): TimeDuration {
-		return this.distanceFrom( this.atEndOfDay() );
+		// Calculate milliseconds until end of day directly
+		const params = this.toParameters();
+		const msInDay = params.hours * 3600000 + params.minutes * 60000 + params.seconds * 1000 + params.milliseconds;
+		const msUntilEndOfDay = 86399999 - msInDay; // 23:59:59.999 in ms
+		return TimeDuration.fromMs( msUntilEndOfDay );
 	}
 
 	public atEndOfDay(): TimeInstant {
@@ -89,7 +96,8 @@ export class TimeInstant extends TimeBase<TimeInstant> {
 	}
 
 	public isToday(): boolean {
-		return Math.floor( this.days ) === Math.floor( TimeInstant.now().days );
+		// Calculate days directly from timestamps without creating TimeInstant object
+		return Math.floor( this.ms / 86400000 ) === Math.floor( Date.now() / 86400000 );
 	}
 
 	/**
@@ -158,10 +166,14 @@ export class TimeInstant extends TimeBase<TimeInstant> {
 	 * @throws Error if the string doesn't match the pattern or contains invalid basic values
 	 * @todo Add calendar-aware validation to reject dates like February 30th, April 31st
 	 */
-	public static parse( dateString: string, pattern: string, base: TimeInstant = TimeInstant.now(), config: { locale?: string, timeZone?: string } = {} ): TimeInstant {
+	public static fromString( dateString: string, pattern: string, base: TimeInstant = TimeInstant.now(), config: { locale?: string, timeZone?: string } = {} ): TimeInstant {
 		return parseTimeInstant( dateString, pattern, base, config );
 	}
 
+	public static parse( dateString: string, pattern: string, config: { locale?: string, timeZone?: string } = {} ): Partial<TTimeInstantCreationParameters> {
+		return parseTimeInstantComponents( dateString, pattern, config );
+	}
+
 	/**
  * @returns this instant, in ISO 8601 format (eg, 2024-11-01T15:49:22.024Z). The format is meant to always be realiable.
  */
@@ -177,7 +189,7 @@ export class TimeInstant extends TimeBase<TimeInstant> {
 	}
 
 	public toUnixTimestamp(): number {
-		// Syntatic sugar for this.ms;
+		// Syntactic sugar for this.ms;
 		return this.ms;
 	}
 
@@ -185,8 +197,17 @@ export class TimeInstant extends TimeBase<TimeInstant> {
 		return new Date( this.ms );
 	}
 
-	public toDateUTC(): Date {
-		return new Date( this.ms + new Date().getTimezoneOffset() * 60 * 1000 );
+	public toParameters(): TTimeInstantParameters {
+		const d = this.toDate();
+		return {
+			year: d.getUTCFullYear(),
+			month: d.getUTCMonth() + 1 as TMonth,
+			date: d.getUTCDate() as TDayOfMonth,
+			hours: d.getUTCHours() as THourOfDay,
+			minutes: d.getUTCMinutes() as TMinuteOfHour,
+			seconds: d.getUTCSeconds() as TSecondOfMinute,
+			milliseconds: d.getUTCMilliseconds() as TMillisecondOfSecond,
+		};
 	}
 
 	/**
@@ -351,39 +372,31 @@ export class TimeInstant extends TimeBase<TimeInstant> {
 		return TimeInstant.fromUnixTimestamp( timestamp );
 	}
 
-	public get dayOfMonth(): TDayOfMonth {
-		return this.toDate().getUTCDate() as TDayOfMonth;
-	}
-
-	public get dayOfWeek(): TDayOfWeek {
-		return this.toDate().getUTCDay() + 1 as TDayOfWeek;
-	}
-
-	public get month(): TMonth {
-		return this.toDate().getUTCMonth() + 1 as TMonth;
-	}
-
-	public get year(): number {
-		return this.toDate().getUTCFullYear();
-	}
-
 	/**
 	 * Returns the week number represented by this instant, according to the ISO 8601 standard.
-		* Please note that the instant and the week number could be of two different years, eg the friday 1st january is actually part of week 52 of the previous year.
+	 * Please note that the instant and the week number could be of two different years, eg the friday 1st january is actually part of week 52 of the previous year.
 	 */
 	public get weekNumber(): { weekNumber: TWeekNumber, year: number } {
 		/**
-			* According to the ISO 8601 Standard, week number 1 is defined as the week containing the 4th of january (or, equivalently, the week that contains the first Thursday of the year).
-			* As such, we basically have to count how many Thursdays there has been in this year.
-			* Please note that the thursdayOfThisWeek could be in the previous year.
+		 * According to the ISO 8601 Standard, week number 1 is defined as the week containing the 4th of january (or, equivalently, the week that contains the first Thursday of the year).
+		 * As such, we basically have to count how many Thursdays there has been in this year.
+		 * Please note that the thursdayOfThisWeek could be in the previous year.
 		 */
 		const date = this.toDate();
 		const oneDay = 1000 * 60 * 60 * 24;
-		const thursdayOfThisWeek = new Date( date.getFullYear(), date.getMonth(), date.getDate() + 4 - ( date.getDay() || 7 ), 14, 0, 0 );
-		const firstOfJanuary = new Date( thursdayOfThisWeek.getFullYear(), 0, 1, 14, 0, 0 );
-		const dayOfTheYear = Math.round( ( thursdayOfThisWeek.getTime() - firstOfJanuary.getTime() ) / oneDay );
+
+		// Get thursday of this week
+		const dayOfWeek = date.getUTCDay() || 7; // Sunday = 7 in ISO
+		const thursdayMs = this.ms + ( 4 - dayOfWeek ) * oneDay;
+		const thursdayDate = new Date( thursdayMs );
+		const thursdayYear = thursdayDate.getUTCFullYear();
+
+		// First of January at noon UTC
+		const firstOfJanMs = Date.UTC( thursdayYear, 0, 1, 12, 0, 0 );
+		const dayOfTheYear = Math.round( ( thursdayMs - firstOfJanMs ) / oneDay );
 		const weekNumber = Math.floor( dayOfTheYear / 7 ) + 1;
-		return { weekNumber: weekNumber as TWeekNumber, year: thursdayOfThisWeek.getFullYear() };
+
+		return { weekNumber: weekNumber as TWeekNumber, year: thursdayYear };
 	}
 
 	/**
@@ -445,130 +458,156 @@ function isValidMillisecond( num: number ): num is TMillisecondOfSecond {
 	return num >= 0 && num <= 999;
 }
 
-const PATTERN_REGEX = /(M|y|d|D|h|H|m|s|S|G|Z|P|a)+/g;
-const ESCAPE_REGEX = /\\"|"((?:\\"|[^"])*)"/g;
-
-const optionNames = {
-	y: 'year',
-	M: 'month',
-	d: 'day',
-	D: 'weekday',
-	S: 'fractionalSecondDigits',
-	G: 'era',
-	Z: 'timeZoneName',
-	P: 'dayPeriod',
-	a: 'hour12',
-	h: 'hour',
-	H: 'hour',
-	m: 'minute',
-	s: 'second',
-} as const;
-
-const values = {
-	y: [ 'numeric', '2-digit', undefined, 'numeric' ],
-	M: [ 'narrow', '2-digit', 'short', 'long' ],
-	d: [ 'numeric', '2-digit' ],
-	D: [ 'narrow', 'short', 'long' ],
-	S: [ 1, 2, 3 ],
-	G: [ 'narrow', 'short', 'long' ],
-	Z: [ 'short', 'long' ],
-	P: [ 'narrow', 'short', 'long' ],
-	a: [ true ],
-	h: [ "numeric", "2-digit" ],
-	H: [ "numeric", "2-digit" ],
-	m: [ "numeric", "2-digit" ],
-	s: [ "numeric", "2-digit" ],
-} as const;
-
-function padIf( condition: boolean, value: string | number, length: number ): string {
-	return condition && length === 2 && Number( value ) / 10 < 1 ? '0' + value : String( value );
-}
-
-function formatType( instant: TimeInstant, type: string, length: number, { locale, timeZone }: { locale?: string, timeZone?: string } = {} ): string | undefined {
-	// For timezone-sensitive formatting, we still need to use Intl.DateTimeFormat with a Date
-	// But for basic numeric formatting, we can use the TimeInstant's properties directly
-
-	// Handle basic numeric formatting directly from TimeInstant properties (UTC-based)
-	if ( type === 'y' ) {
-		const year = instant.year;
-		if ( length === 2 ) {
-			return String( year ).slice( -2 );
-		}
-		return String( year );
-	}
-
-	if ( type === 'M' && ( length === 1 || length === 2 ) ) {
-		const month = instant.month;
-		return length === 2 && month < 10 ? '0' + month : String( month );
-	}
-
-	if ( type === 'd' && ( length === 1 || length === 2 ) ) {
-		const day = instant.dayOfMonth;
-		return length === 2 && day < 10 ? '0' + day : String( day );
-	}
-
-	// Handle time components directly from UTC Date to avoid timezone conversion
-	if ( type === 'H' && ( length === 1 || length === 2 ) ) {
-		const hours = instant.toDate().getUTCHours();
-		return length === 2 && hours < 10 ? '0' + hours : String( hours );
-	}
+// Month names cache by locale to avoid regenerating on every call
+const monthNamesCache = new Map<string, { short: string[], long: string[] }>();
 
-	if ( type === 'h' && ( length === 1 || length === 2 ) ) {
-		let hours = instant.toDate().getUTCHours();
-		hours = hours === 0 ? 12 : hours > 12 ? hours - 12 : hours;
-		return length === 2 && hours < 10 ? '0' + hours : String( hours );
+function getMonthNames( locale: string = 'en' ): { short: string[], long: string[] } {
+	// Check cache first
+	const cached = monthNamesCache.get( locale );
+	if ( cached ) {
+		return cached;
 	}
 
-	if ( type === 'm' && ( length === 1 || length === 2 ) ) {
-		const minutes = instant.toDate().getUTCMinutes();
-		return length === 2 && minutes < 10 ? '0' + minutes : String( minutes );
-	}
+	// Use Intl.DateTimeFormat to generate month names for any locale
+	const shortFormatter = new Intl.DateTimeFormat( locale, { month: 'short' } );
+	const longFormatter = new Intl.DateTimeFormat( locale, { month: 'long' } );
 
-	if ( type === 's' && ( length === 1 || length === 2 ) ) {
-		const seconds = instant.toDate().getUTCSeconds();
-		return length === 2 && seconds < 10 ? '0' + seconds : String( seconds );
-	}
+	const short: string[] = [];
+	const long: string[] = [];
 
-	if ( type === 'S' ) {
-		const ms = instant.toDate().getUTCMilliseconds();
-		if ( length === 1 ) return String( Math.floor( ms / 100 ) );
-		if ( length === 2 ) return String( Math.floor( ms / 10 ) ).padStart( 2, '0' );
-		if ( length === 3 ) return String( ms ).padStart( 3, '0' );
-		return String( ms );
+	// Generate names for all 12 months (0-11 in Date constructor)
+	for ( let month = 0; month < 12; month++ ) {
+		// Use January 1st of year 2000 as a reference date (arbitrary non-leap year)
+		const date = new Date( 2000, month, 1 );
+		short.push( normalizeMonthName( shortFormatter.format( date ) ) );
+		long.push( normalizeMonthName( longFormatter.format( date ) ) );
 	}
 
-	// For timezone-sensitive and locale-sensitive formatting, use Date with Intl
-	const date = instant.toDate();
-	const option = optionNames[ type as keyof typeof optionNames ];
-	const value = values[ type as keyof typeof values ][ length - 1 ];
+	const result = { short, long };
+	monthNamesCache.set( locale, result );
+	return result;
+}
 
-	if ( !value ) {
-		return;
-	}
+// Normalize month names by removing accents, periods, and other special characters
+function normalizeMonthName( name: string ): string {
+	return name
+		// Remove periods and other punctuation
+		.replace( /[.,;:!?]/g, '' )
+		// Normalize Unicode (decompose accented characters)
+		.normalize( 'NFD' )
+		// Remove diacritical marks (accents)
+		.replace( /[\u0300-\u036f]/g, '' )
+		// Trim whitespace
+		.trim();
+}
 
-	const options = {
-		[ option ]: value,
-		timeZone,
-	} as Intl.DateTimeFormatOptions;
+const PATTERN_REGEX = /(M|y|d|D|h|H|m|s|S|G|Z|P|a)+/g;
+const ESCAPE_REGEX = /\\"|"((?:\\"|[^"])*)"/g;
 
-	if ( type === 'a' ) {
-		return Intl.DateTimeFormat( locale, {
-			...options,
-			hour: 'numeric',
-		} )
-			.formatToParts( date )
-			.pop()?.value;
-	}
+// Formatter configuration with optional extraction metadata
+type TFormatterConfig = {
+	options: Intl.DateTimeFormatOptions;
+	extract?: {
+		partType: Intl.DateTimeFormatPartTypes;
+		transform?: ( value: string ) => string;
+	};
+};
+
+// Formatter configuration mapping: token pattern -> configuration with optional extraction rules
+const formatterConfigs: Record<string, TFormatterConfig> = {
+	// Year
+	'y': { options: { year: 'numeric' } },
+	'yy': { options: { year: '2-digit' } },
+	'yyyy': { options: { year: 'numeric' } },
+
+	// Month
+	'M': { options: { month: 'numeric' } },
+	'MM': { options: { month: '2-digit' } },
+	'MMM': { options: { month: 'short' } },
+	'MMMM': { options: { month: 'long' } },
+
+	// Day
+	'd': { options: { day: 'numeric' } },
+	'dd': { options: { day: '2-digit' } },
+
+	// Hours (24-hour) - extract and pad manually due to Intl quirk
+	'H': { options: { hour: 'numeric', hour12: false }, extract: { partType: 'hour' } },
+	'HH': { options: { hour: '2-digit', hour12: false }, extract: { partType: 'hour', transform: ( v ) => v.padStart( 2, '0' ) } },
+
+	// Hours (12-hour) - extract and pad manually due to Intl quirk
+	'h': { options: { hour: 'numeric', hour12: true }, extract: { partType: 'hour' } },
+	'hh': { options: { hour: '2-digit', hour12: true }, extract: { partType: 'hour', transform: ( v ) => v.padStart( 2, '0' ) } },
+
+	// Minutes - extract and pad manually due to Intl quirk
+	'm': { options: { minute: 'numeric' }, extract: { partType: 'minute' } },
+	'mm': { options: { minute: '2-digit' }, extract: { partType: 'minute', transform: ( v ) => v.padStart( 2, '0' ) } },
+
+	// Seconds - extract and pad manually due to Intl quirk
+	's': { options: { second: 'numeric' }, extract: { partType: 'second' } },
+	'ss': { options: { second: '2-digit' }, extract: { partType: 'second', transform: ( v ) => v.padStart( 2, '0' ) } },
+
+	// Milliseconds - extract manually
+	'S': { options: { fractionalSecondDigits: 1 }, extract: { partType: 'fractionalSecond' } },
+	'SS': { options: { fractionalSecondDigits: 2 }, extract: { partType: 'fractionalSecond' } },
+	'SSS': { options: { fractionalSecondDigits: 3 }, extract: { partType: 'fractionalSecond' } },
+
+	// Weekday
+	'D': { options: { weekday: 'narrow' } },
+	'DD': { options: { weekday: 'short' } },
+	'DDD': { options: { weekday: 'long' } },
+
+	// Era
+	'G': { options: { era: 'narrow' } },
+	'GG': { options: { era: 'short' } },
+	'GGG': { options: { era: 'long' } },
+
+	// Timezone
+	'Z': { options: { timeZoneName: 'short' } },
+	'ZZ': { options: { timeZoneName: 'long' } },
+
+	// Day period
+	'P': { options: { dayPeriod: 'narrow' } },
+	'PP': { options: { dayPeriod: 'short' } },
+	'PPP': { options: { dayPeriod: 'long' } },
+
+	// Meridiem - extract dayPeriod and lowercase it
+	'a': { options: { hour: 'numeric', hour12: true }, extract: { partType: 'dayPeriod', transform: ( v ) => v.toLowerCase() } },
+};
+
+// Format a token using Intl.DateTimeFormat
+function formatType( type: string, length: number, date: Date, locale: string = 'en', timeZone: string = 'UTC' ): string | undefined {
+	const tokenKey = type.repeat( length );
+	const config = formatterConfigs[ tokenKey ];
+
+	if ( !config ) {
+		return undefined;
+	}
+
+	const formatter = new Intl.DateTimeFormat( locale, { ...config.options, timeZone } );
+
+	// If extraction metadata is specified, use it
+	if ( config.extract ) {
+		const part = formatter.formatToParts( date ).find( p => p.type === config.extract!.partType );
+		const value = part?.value;
+
+		if ( !value ) {
+			return undefined;
+		}
 
-	if ( type === 'G' || type === 'Z' ) {
-		return Intl.DateTimeFormat( locale, options ).formatToParts( date ).pop()?.value;
+		// Apply transformation if specified
+		return config.extract.transform ? config.extract.transform( value ) : value;
 	}
 
-	// For other complex formatting, fall back to Intl
-	return Intl.DateTimeFormat( locale, options ).format( date );
+	// Otherwise, format directly
+	return formatter.format( date );
 }
 
 function formatTimeInstant( instant: TimeInstant, pattern: string, config: { locale?: string, timeZone?: string } = {} ): string {
+
+	const date = instant.toDate();
+	const locale = config.locale || 'en';
+	const timeZone = config.timeZone || 'UTC';
+
 	return pattern
 		.split( ESCAPE_REGEX )
 		.filter( ( sub ) => sub !== undefined )
@@ -580,13 +619,29 @@ function formatTimeInstant( instant: TimeInstant, pattern: string, config: { loc
 
 			return sub.replace( PATTERN_REGEX, ( match ) => {
 				const type = match.charAt( 0 );
-				return formatType( instant, type, match.length, config ) || match;
+				const length = match.length;
+
+				return formatType( type, length, date, locale, timeZone ) || match;
 			} );
 		} )
 		.join( '' );
 }
 
 function parseTimeInstant( dateString: string, pattern: string, base: TimeInstant, config: { locale?: string, timeZone?: string } = {} ): TimeInstant {
+	// Parse the components from the date string
+	const parsed = parseTimeInstantComponents( dateString, pattern, config );
+
+	// Fill in missing values from the base instant
+	const params = {
+		...base.toParameters(),
+		...parsed
+	};
+
+	// Create and return the TimeInstant with complete parameters
+	return TimeInstant.fromParameters( params );
+}
+
+function parseTimeInstantComponents( dateString: string, pattern: string, config: { locale?: string, timeZone?: string } = {} ): Partial<TTimeInstantParameters> {
 	// Create a regex pattern from the format pattern
 	let regexPattern = pattern;
 	const tokens: { type: string; length: number; position: number }[] = [];
@@ -613,7 +668,7 @@ function parseTimeInstant( dateString: string, pattern: string, base: TimeInstan
 			case 'M':
 				if ( match.length === 1 ) return '(\\d{1,2})';
 				if ( match.length === 2 ) return '(\\d{2})';
-				if ( match.length === 3 ) return '([A-Za-z]{3})';
+				if ( match.length === 3 ) return '([A-Za-z.]{1,7})';
 				return '([A-Za-z]+)';
 			case 'd':
 				return match.length === 1 ? '(\\d{1,2})' : '(\\d{2})';
@@ -652,16 +707,12 @@ function parseTimeInstant( dateString: string, pattern: string, base: TimeInstan
 		throw new Error( `Date string "${dateString}" does not match pattern "${pattern}"` );
 	}
 
-	// Extract values from matches using base instant as default
-	let year = base.year;
-	let month = base.month;
-	let day = base.dayOfMonth;
-	let hour = base.toDate().getUTCHours();
-	let minute = base.toDate().getUTCMinutes();
-	let second = base.toDate().getUTCSeconds();
-	let millisecond = base.toDate().getUTCMilliseconds();
+	// Extract only the values that were actually parsed (no defaults)
+	const result: Partial<TTimeInstantParameters> = {};
+	const locale = config.locale || 'en';
 	let isPM = false;
 	let is12Hour = false;
+	let hourValue: number | undefined;
 
 	tokens.forEach( ( token, index ) => {
 		const value = matches[ index + 1 ];
@@ -670,52 +721,63 @@ function parseTimeInstant( dateString: string, pattern: string, base: TimeInstan
 		case 'y':
 			if ( token.length === 2 ) {
 				const shortYear = parseInt( value, 10 );
-				year = shortYear < 50 ? 2000 + shortYear : 1900 + shortYear;
+				result.year = shortYear < 50 ? 2000 + shortYear : 1900 + shortYear;
 			} else {
-				year = parseInt( value, 10 );
+				result.year = parseInt( value, 10 );
 			}
 			break;
 		case 'M':
-			if ( token.length <= 2 ) {
-				month = parseInt( value, 10 ) as TMonth;
-			} else {
-				// Handle month names - simplified approach
-				const monthNames = [ 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
-					'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec' ];
-				const longMonthNames = [ 'January', 'February', 'March', 'April', 'May', 'June',
-					'July', 'August', 'September', 'October', 'November', 'December' ];
-
-				let monthIndex = monthNames.findIndex( name =>
-					name.toLowerCase() === value.toLowerCase() );
-				if ( monthIndex === -1 ) {
-					monthIndex = longMonthNames.findIndex( name =>
-						name.toLowerCase() === value.toLowerCase() );
-				}
-				month = ( monthIndex !== -1 ? monthIndex + 1 : 1 ) as TMonth;
+			switch ( token.length ) {
+			case 1:
+			case 2:
+				result.month = parseInt( value, 10 ) as TMonth;
+				break;
+			case 3: {
+				const normalizedValue = normalizeMonthName( value );
+				const monthIndex = getMonthNames( locale ).short.findIndex( name =>
+					name.toLowerCase() === normalizedValue.toLowerCase()
+				);
+				if ( monthIndex === -1 )
+					throw new Error( `Invalid short month name in date string: ${dateString}` );
+				result.month = ( monthIndex + 1 ) as TMonth;
+				break;
+			}
+			case 4: {
+				const normalizedValue = normalizeMonthName( value );
+				const monthIndex = getMonthNames( locale ).long.findIndex( name =>
+					name.toLowerCase() === normalizedValue.toLowerCase()
+				);
+				if ( monthIndex === -1 )
+					throw new Error( `Invalid full month name in date string: ${dateString}` );
+				result.month = ( monthIndex + 1 ) as TMonth;
+				break;
+			}
+			default:
+				throw new Error( `Invalid month pattern: ${token}` );
 			}
 			break;
 		case 'd':
-			day = parseInt( value, 10 ) as TDayOfMonth;
+			result.date = parseInt( value, 10 ) as TDayOfMonth;
 			break;
 		case 'H':
-			hour = parseInt( value, 10 );
+			result.hours = parseInt( value, 10 ) as THourOfDay;
 			break;
 		case 'h':
-			hour = parseInt( value, 10 );
+			hourValue = parseInt( value, 10 );
 			is12Hour = true;
 			break;
 		case 'm':
-			minute = parseInt( value, 10 );
+			result.minutes = parseInt( value, 10 ) as TMinuteOfHour;
 			break;
 		case 's':
-			second = parseInt( value, 10 );
+			result.seconds = parseInt( value, 10 ) as TSecondOfMinute;
 			break;
 		case 'S':
 			let ms = parseInt( value, 10 );
 			// Normalize to milliseconds based on length
 			if ( token.length === 1 ) ms *= 100;
 			else if ( token.length === 2 ) ms *= 10;
-			millisecond = ms;
+			result.milliseconds = ms as TMillisecondOfSecond;
 			break;
 		case 'a':
 			isPM = value.toLowerCase().includes( 'p' );
@@ -723,30 +785,39 @@ function parseTimeInstant( dateString: string, pattern: string, base: TimeInstan
 		}
 	} );
 
-	// Handle 12-hour format
-	if ( is12Hour && isPM && hour < 12 ) {
-		hour += 12;
-	} else if ( is12Hour && !isPM && hour === 12 ) {
-		hour = 0;
-	}
-
-	// Validate each component using standalone validation functions
-	if ( !isValidYear( year ) ) throw new Error( `Invalid year in date string: ${dateString}` );
-	if ( !isValidMonth( month ) ) throw new Error( `Invalid month in date string: ${dateString}` );
-	if ( !isValidDayOfMonth( day ) ) throw new Error( `Invalid day in date string: ${dateString}` );
-	if ( !isValidHour( hour ) ) throw new Error( `Invalid hour in date string: ${dateString}` );
-	if ( !isValidMinute( minute ) ) throw new Error( `Invalid minute in date string: ${dateString}` );
-	if ( !isValidSecond( second ) ) throw new Error( `Invalid second in date string: ${dateString}` );
-	if ( !isValidMillisecond( millisecond ) ) throw new Error( `Invalid millisecond in date string: ${dateString}` );
-
-	// Use TimeInstant.fromParameters instead of creating a Date
-	return TimeInstant.fromParameters( {
-		year,
-		month: month as TMonth,
-		date: day as TDayOfMonth,
-		hours: hour as THourOfDay,
-		minutes: minute as TMinuteOfHour,
-		seconds: second as TSecondOfMinute,
-		milliseconds: millisecond as TMillisecondOfSecond,
-	} );
+	// Handle 12-hour format conversion
+	if ( is12Hour && hourValue !== undefined ) {
+		if ( isPM && hourValue < 12 ) {
+			result.hours = ( hourValue + 12 ) as THourOfDay;
+		} else if ( !isPM && hourValue === 12 ) {
+			result.hours = 0 as THourOfDay;
+		} else {
+			result.hours = hourValue as THourOfDay;
+		}
+	}
+
+	// Validate each extracted component (only validate primitives)
+	if ( typeof result.year === 'number' && !isValidYear( result.year ) ) {
+		throw new Error( `Invalid year in date string: ${dateString}` );
+	}
+	if ( typeof result.month === 'number' && !isValidMonth( result.month ) ) {
+		throw new Error( `Invalid month in date string: ${dateString}` );
+	}
+	if ( typeof result.date === 'number' && !isValidDayOfMonth( result.date ) ) {
+		throw new Error( `Invalid day in date string: ${dateString}` );
+	}
+	if ( typeof result.hours === 'number' && !isValidHour( result.hours ) ) {
+		throw new Error( `Invalid hour in date string: ${dateString}` );
+	}
+	if ( typeof result.minutes === 'number' && !isValidMinute( result.minutes ) ) {
+		throw new Error( `Invalid minute in date string: ${dateString}` );
+	}
+	if ( typeof result.seconds === 'number' && !isValidSecond( result.seconds ) ) {
+		throw new Error( `Invalid second in date string: ${dateString}` );
+	}
+	if ( typeof result.milliseconds === 'number' && !isValidMillisecond( result.milliseconds ) ) {
+		throw new Error( `Invalid millisecond in date string: ${dateString}` );
+	}
+
+	return result;
 }