@zelgadis87/utils-core 5.2.9 → 5.2.11

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@zelgadis87/utils-core",
-  "version": "5.2.9",
+  "version": "5.2.11",
   "author": "Zelgadis87",
   "license": "ISC",
   "private": false,
@@ -30,8 +30,5 @@
     "typescript": "5.8.3",
     "typescript-eslint": "8.43.0",
     "vitest": "3.2.4"
-  },
-  "dependencies": {
-    "small-date": "^2.0.1"
   }
 }

package/src/time/TimeInstant.ts

@@ -1,11 +1,10 @@
-import { format } from "small-date";
 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, TIso8601DateString, TIso8601DateUtcString, TMonth, TWeekNumber } from "./types";
+import { TDayOfMonth, TDayOfWeek, THourOfDay, TIso8601DateString, TIso8601DateUtcString, TMillisecondOfSecond, TMinuteOfHour, TMonth, TSecondOfMinute, TWeekNumber } from "./types";
 
 export class TimeInstant extends TimeBase<TimeInstant> {
 
@@ -32,7 +31,7 @@ export class TimeInstant extends TimeBase<TimeInstant> {
 	public distanceFromNow(): TimeDuration {
 		return TimeDuration.fromMs( Math.abs( this.ms - Date.now() ) );
 	}
-	
+
 	public distanceFromUnixTimestamp( timestamp: number ): TimeDuration {
 		return TimeDuration.ms( this.ms - timestamp );
 	}
@@ -48,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 {
@@ -56,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 {
@@ -90,12 +96,15 @@ 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 );
 	}
 
 	/**
 	 * Formats this instant using the given pattern. The pattern can contain the following tokens:
 	 * 
+	 * Note: Implementation inspired by the small-date library (https://github.com/robinweser/small-date).
+	 * 
 	 * | Token | Description                     | Example                       |
 	 * |:------|:--------------------------------|:------------------------------|
 	 * | D     | Weekday, 1 letter               | W                             |
@@ -135,7 +144,34 @@ export class TimeInstant extends TimeBase<TimeInstant> {
 	 * @returns a string, formatted using the given pattern, at the given timeZone with the given locale.
 	 */
 	public format( pattern: string, config: { locale?: string, timeZone?: string } = {} ) {
-		return format( this.toDate(), pattern, config );
+		return formatTimeInstant( this, pattern, config );
+	}
+
+	/**
+	 * Parses a date string using the given pattern and creates a TimeInstant.
+	 * This method is the inverse of format() - parsing a formatted string should recreate the original instant.
+	 * 
+	 * For partial patterns (e.g., time-only or date-only), the missing components are taken from the base instant.
+	 * For example, parsing "14:30" with base set to yesterday at midnight will result in yesterday at 14:30.
+	 * 
+	 * Note: Currently performs basic validation (e.g., month 1-12, day 1-31) but does not validate
+	 * calendar-specific constraints (e.g., February 30th, April 31st). Invalid dates may be
+	 * normalized by the underlying Date constructor.
+	 * 
+	 * @param dateString The date string to parse
+	 * @param pattern The pattern used to parse the string (same tokens as format())
+	 * @param base The base TimeInstant to use for partial patterns (defaults to now)
+	 * @param config An optional locale and timeZone definition to use during parsing
+	 * @returns A TimeInstant parsed from the string
+	 * @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 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 );
 	}
 
 	/**
@@ -153,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;
 	}
 
@@ -161,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,
+		};
 	}
 
 	/**
@@ -241,16 +286,58 @@ export class TimeInstant extends TimeBase<TimeInstant> {
 		return timeInstantBuilder();
 	}
 
-	public static fromIso8601( str: TIso8601DateString ) {
-		return TimeInstant.fromUnixTimestamp( new Date( str ).getTime() );
-	}
+	public static fromIso8601( str: string ) {
+		// Regex to capture: YYYY-MM-DDTHH:mm:ss.sssZ or YYYY-MM-DDTHH:mm:ss.sss±HH:mm
+		const iso8601Regex = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})\.(\d{3})(Z|[+-]\d{2}:\d{2})?$/;
+		const match = str.match( iso8601Regex );
+
+		if ( !match ) {
+			throw new Error( 'Invalid ISO 8601 date format: ' + str );
+		}
 
-	public static tryFromIso8601( str: string ) {
-		if ( !str.match( /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:.\d{3}|)(?:Z|[+-]\d{2}:\d{2})?$/ ) )
-			throw new Error( 'Invalid date given: ' + str );
-		return TimeInstant.fromUnixTimestamp( new Date( str ).getTime() );
+		const [ , yearStr, monthStr, dayStr, hourStr, minuteStr, secondStr, millisecondStr ] = match;
+
+		// Parse strings to numbers
+		const year = parseInt( yearStr, 10 );
+		const month = parseInt( monthStr, 10 );
+		const date = parseInt( dayStr, 10 );
+		const hours = parseInt( hourStr, 10 );
+		const minutes = parseInt( minuteStr, 10 );
+		const seconds = parseInt( secondStr, 10 );
+		const milliseconds = parseInt( millisecondStr, 10 );
+
+		// Validate each component using standalone validation functions
+		if ( !isValidYear( year ) )
+			throw new Error( 'Invalid year in: ' + str );
+		if ( !isValidMonth( month ) )
+			throw new Error( 'Invalid month in: ' + str );
+		if ( !isValidDayOfMonth( date ) )
+			throw new Error( 'Invalid day in: ' + str );
+		if ( !isValidHour( hours ) )
+			throw new Error( 'Invalid hour in: ' + str );
+		if ( !isValidMinute( minutes ) )
+			throw new Error( 'Invalid minute in: ' + str );
+		if ( !isValidSecond( seconds ) )
+			throw new Error( 'Invalid second in: ' + str );
+		if ( !isValidMillisecond( milliseconds ) )
+			throw new Error( 'Invalid millisecond in: ' + str );
+
+		return TimeInstant.fromParameters( {
+			year,
+			month,
+			date,
+			hours,
+			minutes,
+			seconds,
+			milliseconds,
+		} );
 	}
 
+	/**
+	 * @deprecated [2025.10.19]: Use fromIso8601 instead.
+	 */
+	public static tryFromIso8601 = this.fromIso8601;
+
 	public static now(): TimeInstant {
 		return TimeInstant.fromUnixTimestamp( Date.now() );
 	}
@@ -285,39 +372,31 @@ export class TimeInstant extends TimeBase<TimeInstant> {
 		return TimeInstant.fromUnixTimestamp( timestamp );
 	}
 
-	public get dayOfMonth(): TDayOfMonth {
-		return this.toDate().getDate() as TDayOfMonth;
-	}
-
-	public get dayOfWeek(): TDayOfWeek {
-		return this.toDate().getDay() + 1 as TDayOfWeek;
-	}
-
-	public get month(): TMonth {
-		return this.toDate().getMonth() + 1 as TMonth;
-	}
-
-	public get year(): number {
-		return this.toDate().getFullYear();
-	}
-
 	/**
 	 * 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 };
 	}
 
 	/**
@@ -344,3 +423,401 @@ export function isTimeInstant( x: unknown ): x is TimeInstant {
 }
 
 export default TimeInstant;
+
+
+// Utility functions for date formatting and parsing
+
+// Standalone validation functions
+// TODO: Add calendar-aware validation to check month-specific day limits
+// (e.g., reject February 30th, April 31st, February 29th in non-leap years)
+function isValidYear( num: number ): boolean {
+	return num >= 0 && num <= 9999;
+}
+
+function isValidMonth( num: number ): num is TMonth {
+	return num >= 1 && num <= 12;
+}
+
+function isValidDayOfMonth( num: number ): num is TDayOfMonth {
+	return num >= 1 && num <= 31;
+}
+
+function isValidHour( num: number ): num is THourOfDay {
+	return num >= 0 && num <= 23;
+}
+
+function isValidMinute( num: number ): num is TMinuteOfHour {
+	return num >= 0 && num <= 59;
+}
+
+function isValidSecond( num: number ): num is TSecondOfMinute {
+	return num >= 0 && num <= 59;
+}
+
+function isValidMillisecond( num: number ): num is TMillisecondOfSecond {
+	return num >= 0 && num <= 999;
+}
+
+// Month names cache by locale to avoid regenerating on every call
+const monthNamesCache = new Map<string, { short: string[], long: string[] }>();
+
+function getMonthNames( locale: string = 'en' ): { short: string[], long: string[] } {
+	// Check cache first
+	const cached = monthNamesCache.get( locale );
+	if ( cached ) {
+		return cached;
+	}
+
+	// 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' } );
+
+	const short: string[] = [];
+	const long: string[] = [];
+
+	// 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 ) ) );
+	}
+
+	const result = { short, long };
+	monthNamesCache.set( locale, result );
+	return result;
+}
+
+// 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 PATTERN_REGEX = /(M|y|d|D|h|H|m|s|S|G|Z|P|a)+/g;
+const ESCAPE_REGEX = /\\"|"((?:\\"|[^"])*)"/g;
+
+// 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;
+		}
+
+		// Apply transformation if specified
+		return config.extract.transform ? config.extract.transform( value ) : value;
+	}
+
+	// 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 )
+		.map( ( sub, index ) => {
+			// keep escaped strings as is
+			if ( index % 2 !== 0 ) {
+				return sub;
+			}
+
+			return sub.replace( PATTERN_REGEX, ( match ) => {
+				const type = match.charAt( 0 );
+				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 }[] = [];
+	let position = 0;
+
+	// Split by escape regex first, like the original implementation
+	const parts = pattern.split( ESCAPE_REGEX ).filter( ( sub ) => sub !== undefined );
+
+	// Rebuild pattern and track tokens
+	regexPattern = parts.map( ( sub, index ) => {
+		// Skip escaped strings (odd indices after split)
+		if ( index % 2 !== 0 ) {
+			return sub.replace( /[.*+?^${}()|[\]\\]/g, '\\$&' ); // Escape special regex chars
+		}
+
+		return sub.replace( PATTERN_REGEX, ( match ) => {
+			const type = match.charAt( 0 );
+			tokens.push( { type, length: match.length, position: position++ } );
+
+			// Create appropriate regex for each token type
+			switch ( type ) {
+			case 'y':
+				return match.length === 2 ? '(\\d{2})' : '(\\d{4})';
+			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.]{1,7})';
+				return '([A-Za-z]+)';
+			case 'd':
+				return match.length === 1 ? '(\\d{1,2})' : '(\\d{2})';
+			case 'H':
+			case 'h':
+				return match.length === 1 ? '(\\d{1,2})' : '(\\d{2})';
+			case 'm':
+			case 's':
+				return match.length === 1 ? '(\\d{1,2})' : '(\\d{2})';
+			case 'S':
+				return `(\\d{${match.length}})`;
+			case 'a':
+				return '([aApP][mM])';
+			case 'D':
+				if ( match.length === 1 ) return '([A-Za-z])';
+				if ( match.length === 2 ) return '([A-Za-z]{3})';
+				return '([A-Za-z]+)';
+			case 'G':
+				if ( match.length === 1 ) return '([A-Za-z])';
+				if ( match.length === 2 ) return '([A-Za-z]{2})';
+				return '([A-Za-z\\s]+)';
+			case 'Z':
+				return match.length === 1 ? '([A-Za-z0-9+\\-:]+)' : '([A-Za-z\\s]+)';
+			case 'P':
+				return '([A-Za-z\\s]+)';
+			default:
+				return match;
+			}
+		} );
+	} ).join( '' );
+
+	const regex = new RegExp( '^' + regexPattern + '$' );
+	const matches = dateString.match( regex );
+
+	if ( !matches ) {
+		throw new Error( `Date string "${dateString}" does not match pattern "${pattern}"` );
+	}
+
+	// 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 ];
+
+		switch ( token.type ) {
+		case 'y':
+			if ( token.length === 2 ) {
+				const shortYear = parseInt( value, 10 );
+				result.year = shortYear < 50 ? 2000 + shortYear : 1900 + shortYear;
+			} else {
+				result.year = parseInt( value, 10 );
+			}
+			break;
+		case 'M':
+			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':
+			result.date = parseInt( value, 10 ) as TDayOfMonth;
+			break;
+		case 'H':
+			result.hours = parseInt( value, 10 ) as THourOfDay;
+			break;
+		case 'h':
+			hourValue = parseInt( value, 10 );
+			is12Hour = true;
+			break;
+		case 'm':
+			result.minutes = parseInt( value, 10 ) as TMinuteOfHour;
+			break;
+		case 's':
+			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;
+			result.milliseconds = ms as TMillisecondOfSecond;
+			break;
+		case 'a':
+			isPM = value.toLowerCase().includes( 'p' );
+			break;
+		}
+	} );
+
+	// 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;
+}