@zelgadis87/utils-core 5.2.8 → 5.2.10

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@zelgadis87/utils-core",
-  "version": "5.2.8",
+  "version": "5.2.10",
   "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/Optional.ts

@@ -221,7 +221,7 @@ export type TOptional<T> = {
 
 	ifEmpty( callback: TVoidFunction ): void;
 	ifPresent( callback: TConsumer<T> ): void;
-	apply<RP = void, RE = void>( callbackIfPresent: TFunction<T, RP>, callbackIfEmpty: TProducer<RE> ): void;
+	apply<RP = void, RE = void>( callbackIfPresent: TFunction<T, RP>, callbackIfEmpty: TProducer<RE> ): RP | RE;
 
 	throwIfPresent: ( errorGenerator: TFunction<T, Error> ) => TEmptyOptional<T>;
 
@@ -255,11 +255,13 @@ export type TEmptyOptional<T> = TOptional<T> & {
 	get(): never;
 	isEmpty(): true;
 	isPresent(): false;
+	apply<RP = void, RE = void>( callbackIfPresent: TFunction<T, RP>, callbackIfEmpty: TProducer<RE> ): RE;
 }
 export type TPresentOptional<T> = TOptional<T> & {
 	get(): T;
 	isEmpty(): false;
 	isPresent(): true;
+	apply<RP = void, RE = void>( callbackIfPresent: TFunction<T, RP>, callbackIfEmpty: TProducer<RE> ): RP;
 }
 
 export class ErrorGetEmptyOptional extends Error {

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 { 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 );
 	}
@@ -96,6 +95,8 @@ export class TimeInstant extends TimeBase<TimeInstant> {
 	/**
 	 * 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 +136,30 @@ 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 parse( dateString: string, pattern: string, base: TimeInstant = TimeInstant.now(), config: { locale?: string, timeZone?: string } = {} ): TimeInstant {
+		return parseTimeInstant( dateString, pattern, base, config );
 	}
 
 	/**
@@ -241,16 +265,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() );
 	}
@@ -286,19 +352,19 @@ export class TimeInstant extends TimeBase<TimeInstant> {
 	}
 
 	public get dayOfMonth(): TDayOfMonth {
-		return this.toDate().getDate() as TDayOfMonth;
+		return this.toDate().getUTCDate() as TDayOfMonth;
 	}
 
 	public get dayOfWeek(): TDayOfWeek {
-		return this.toDate().getDay() + 1 as TDayOfWeek;
+		return this.toDate().getUTCDay() + 1 as TDayOfWeek;
 	}
 
 	public get month(): TMonth {
-		return this.toDate().getMonth() + 1 as TMonth;
+		return this.toDate().getUTCMonth() + 1 as TMonth;
 	}
 
 	public get year(): number {
-		return this.toDate().getFullYear();
+		return this.toDate().getUTCFullYear();
 	}
 
 	/**
@@ -344,3 +410,343 @@ 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;
+}
+
+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 );
+	}
+
+	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 );
+	}
+
+	if ( type === 'm' && ( length === 1 || length === 2 ) ) {
+		const minutes = instant.toDate().getUTCMinutes();
+		return length === 2 && minutes < 10 ? '0' + minutes : String( minutes );
+	}
+
+	if ( type === 's' && ( length === 1 || length === 2 ) ) {
+		const seconds = instant.toDate().getUTCSeconds();
+		return length === 2 && seconds < 10 ? '0' + seconds : String( seconds );
+	}
+
+	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 );
+	}
+
+	// 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 ];
+
+	if ( !value ) {
+		return;
+	}
+
+	const options = {
+		[ option ]: value,
+		timeZone,
+	} as Intl.DateTimeFormatOptions;
+
+	if ( type === 'a' ) {
+		return Intl.DateTimeFormat( locale, {
+			...options,
+			hour: 'numeric',
+		} )
+			.formatToParts( date )
+			.pop()?.value;
+	}
+
+	if ( type === 'G' || type === 'Z' ) {
+		return Intl.DateTimeFormat( locale, options ).formatToParts( date ).pop()?.value;
+	}
+
+	// For other complex formatting, fall back to Intl
+	return Intl.DateTimeFormat( locale, options ).format( date );
+}
+
+function formatTimeInstant( instant: TimeInstant, pattern: string, config: { locale?: string, timeZone?: string } = {} ): string {
+	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 );
+				return formatType( instant, type, match.length, config ) || match;
+			} );
+		} )
+		.join( '' );
+}
+
+function parseTimeInstant( dateString: string, pattern: string, base: TimeInstant, config: { locale?: string, timeZone?: string } = {} ): TimeInstant {
+	// 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]{3})';
+				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 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();
+	let isPM = false;
+	let is12Hour = false;
+
+	tokens.forEach( ( token, index ) => {
+		const value = matches[ index + 1 ];
+
+		switch ( token.type ) {
+		case 'y':
+			if ( token.length === 2 ) {
+				const shortYear = parseInt( value, 10 );
+				year = shortYear < 50 ? 2000 + shortYear : 1900 + shortYear;
+			} else {
+				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;
+			}
+			break;
+		case 'd':
+			day = parseInt( value, 10 ) as TDayOfMonth;
+			break;
+		case 'H':
+			hour = parseInt( value, 10 );
+			break;
+		case 'h':
+			hour = parseInt( value, 10 );
+			is12Hour = true;
+			break;
+		case 'm':
+			minute = parseInt( value, 10 );
+			break;
+		case 's':
+			second = parseInt( value, 10 );
+			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;
+			break;
+		case 'a':
+			isPM = value.toLowerCase().includes( 'p' );
+			break;
+		}
+	} );
+
+	// 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,
+	} );
+}

package/src/time/TimeInstantBuilder.ts

@@ -66,7 +66,7 @@ const timeInstantResolveValue = ( getFromDate: TFunction<Date, number>, referenc
 };
 const getFromDate = {
 	year: d => d.getFullYear(),
-	month: d => d.getMonth(),
+	month: d => d.getMonth() + 1,
 	date: d => d.getDate(),
 	hours: d => d.getHours(),
 	minutes: d => d.getMinutes(),
@@ -84,7 +84,7 @@ export function createTimeInstantFromParameters( aParameters: Partial<TTimeInsta
 	const referenceDate = toReferenceDate( aReferenceDate );
 	const timestamp = Date.UTC(
 		timeInstantResolveValue( getFromDate.year, referenceDate, year ),
-		timeInstantResolveValue( getFromDate.month, referenceDate, month ),
+		timeInstantResolveValue( getFromDate.month, referenceDate, month ) - 1, // Convert from 1-based to 0-based for Date.UTC()
 		timeInstantResolveValue( getFromDate.date, referenceDate, date ),
 		timeInstantResolveValue( getFromDate.hours, referenceDate, hours ),
 		timeInstantResolveValue( getFromDate.minutes, referenceDate, minutes ),

package/src/utils/empties.ts

@@ -17,3 +17,5 @@ export type TIsEmptyObject<T> = keyof T extends never ? true : false;
  * ```
  */
 export type TConditionalOptionalType<T> = TIsEmptyObject<T> extends true ? [] : [ T ];
+
+export type TEmptyObject = Record<string, never>;