@zelgadis87/utils-core 5.3.3 → 5.3.5

package/.rollup/index.d.ts

@@ -549,6 +549,22 @@ declare class TimeInstant extends TimeBase<TimeInstant> {
 }
 declare function isTimeInstant(x: unknown): x is TimeInstant;
 
+declare function parseTimeInstantComponents(dateString: string, pattern: string, config?: {
+    locale?: string;
+    timeZone?: string;
+}): Partial<TTimeInstantParameters>;
+type TBasicTimePattern = 'y' | 'yy' | 'yyyy' | 'M' | 'MM' | 'd' | 'dd' | 'H' | 'HH' | 'm' | 'mm' | 's' | 'ss' | 'S' | 'SS' | 'SSS' | 'yyyy-MM-dd' | 'yyyy-MM-dd HH:mm' | 'yyyy-MM-dd HH:mm:ss' | 'yyyy-MM-dd HH:mm:ss.SSS' | 'yyyy/MM/dd' | 'yyyy/MM/dd HH:mm' | 'yyyy/MM/dd HH:mm:ss' | 'yyyy/MM/dd HH:mm:ss.SSS' | 'MM/dd/yyyy' | 'MM/dd/yyyy HH:mm' | 'MM/dd/yyyy HH:mm:ss' | 'MM/dd/yyyy HH:mm:ss.SSS' | 'dd/MM/yyyy' | 'dd/MM/yyyy HH:mm' | 'dd/MM/yyyy HH:mm:ss' | 'dd/MM/yyyy HH:mm:ss.SSS' | 'HH:mm:ss' | 'HH:mm';
+/**
+    * Parses a date string using only basic patterns that don't require Intl.
+    * This is a safer alternative to parseTimeInstantComponents that works even when Intl is not available.
+    *
+    * @param dateString The date string to parse
+    * @param pattern A basic pattern that doesn't require Intl (strongly typed)
+    * @returns Partial time instant parameters that were parsed from the string
+    * @throws Error if the string doesn't match the pattern or contains invalid values
+    */
+declare function parseTimeInstantBasicComponents(dateString: string, pattern: TBasicTimePattern, ignoreIntlAvailability?: boolean): Partial<TTimeInstantParameters>;
+
 declare class TimeDuration extends TimeBase<TimeDuration> {
     protected constructor(value: number, unit: TimeUnit);
     protected create(value: number, unit: TimeUnit): TimeDuration;
@@ -762,13 +778,14 @@ declare function indexByNumberWith<V, R = V>(arr: V[], keyGetter: TFunction<V, n
 declare function indexBySymbolWith<V, R = V>(arr: V[], keyGetter: TFunction<V, symbol>, valueMapper?: TFunction<V, R>): Record<symbol, R>;
 declare function indexByWith<K extends string | number | symbol, V, R = V>(arr: V[], keyGetter: TFunction<V, K>, valueMapper?: TFunction<V, R>): Record<K, R>;
 
-declare function average(arr: TReadableArray<number>): number;
+declare function average(arr: TReadableArray<number>): TMaybe<number>;
+declare function averageBy<T>(arr: TReadableArray<T>, getter: (t: T) => number): TMaybe<number>;
 declare function sum(arr: TReadableArray<number>): number;
 declare function sumBy<T>(arr: TReadableArray<T>, getter: (t: T) => number): number;
-declare function min(arr: TReadableArray<number>): number;
-declare function minBy<T>(arr: TReadableArray<T>, getter: (t: T) => number): number;
-declare function max(arr: TReadableArray<number>): number;
-declare function maxBy<T>(arr: TReadableArray<T>, getter: (t: T) => number): number;
+declare function min(arr: TReadableArray<number>): TMaybe<number>;
+declare function minBy<T>(arr: TReadableArray<T>, getter: (t: T) => number): TMaybe<number>;
+declare function max(arr: TReadableArray<number>): TMaybe<number>;
+declare function maxBy<T>(arr: TReadableArray<T>, getter: (t: T) => number): TMaybe<number>;
 
 declare function uniq<T>(arr: T[]): T[];
 declare function uniqBy<T, K>(arr: T[], getter: TFunction<T, K>): T[];
@@ -791,7 +808,28 @@ declare function isArray<const T>(t: unknown): t is Array<T>;
  */
 declare function upsert<T>(arr: ReadonlyArray<T>, item: T, isEqual: TBiPredicate<T>): Array<T>;
 declare function range(start: number, end: number): Array<number>;
+/**
+ * Creates an array of the specified length, where each element is filled with the given value.
+ * @param length - The length of the array to create. Must be a non-negative integer.
+ * @param value - The value to fill each element with.
+ * @returns A new array with all elements set to the given value.
+ * @throws {RangeError} If length is negative, not an integer, or NaN.
+ * @example
+ * ```ts
+ * fill(3, 'a'); // ['a', 'a', 'a']
+ * fill(0, 42); // []
+ * fill(5, null); // [null, null, null, null, null]
+ * ```
+ */
 declare function fill<T>(length: number, value: T): Array<T>;
+/**
+ * Creates an array of the specified length, where each element is generated by the provided generator function.
+ * @param length - The length of the array to create. Must be a non-negative integer.
+ * @param generator - A function that takes an index and returns the value for that position.
+ * @returns A new array with elements generated by the generator function.
+ * @throws {RangeError} If length is negative or not an integer.
+ */
+declare function fillWith<T>(length: number, generator: TFunction<number, T>): Array<T>;
 declare function extendArray<T extends Record<string | number | symbol, unknown>, X extends Record<string | number | symbol, unknown>>(arr: TReadableArray<T>, props: X): Array<(T & X)>;
 declare function extendArrayWith<T extends Record<string | number | symbol, unknown>, X extends Record<string | number | symbol, unknown>>(arr: TReadableArray<T>, propsFn: (t: T) => X): Array<(T & X)>;
 declare function reverse<T>(arr: TReadableArray<T>): Array<T>;
@@ -1406,5 +1444,5 @@ declare class DataUpgrader<X extends TUpgradable, XLatest extends X> implements
 }
 declare function isUpgradable(obj: TJsonSerializable): obj is TUpgradable;
 
-export { Cached, DataUpgrader, Deferred, DeferredCanceledError, ErrorCannotInstantiatePresentOptionalWithEmptyValue, ErrorGetEmptyOptional, ErrorSetEmptyOptional, Lazy, LazyAsync, LazyDictionary, Logger, NEVER, NonExhaustiveSwitchError, Operation, Optional, PredicateBuilder, RandomTimeDuration, RateThrottler, Semaphore, Sorter, StringParts, TimeDuration, TimeFrequency, TimeInstant, TimeRange, TimeUnit, TimeoutError, alwaysFalse, alwaysTrue, and, arrayGet, arrayIncludes, asError, asPromise, average, awaitAtMost, capitalizeWord, clamp, clampInt0_100, constant, constantFalse, constantNull, constantOne, constantTrue, constantUndefined, constantZero, cssDeclarationRulesDictionaryToCss, decrement, decrementBy, delayPromise, dictToEntries, dictToList, divideBy, ellipsis, ensureArray, ensureDefined, ensureNegativeNumber, ensureNonNegativeNumber, ensureNonPositiveNumber, ensurePositiveNumber, ensureReadableArray, entriesToDict, entriesToEntries, entriesToList, extendArray, extendArrayWith, fill, filterMap, filterMapReduce, filterWithTypePredicate, findInArray, findIndexInArray, first, flatMapTruthys, getCauseMessageFromError, getCauseStackFromError, getMessageFromError, getStackFromError, groupByBoolean, groupByBooleanWith, groupByNumber, groupByNumberWith, groupByString, groupByStringWith, groupBySymbol, groupBySymbolWith, hashCode, head, identity, ifDefined, ifNullOrUndefined, iff, includes, increment, incrementBy, indexByNumber, indexByNumberWith, indexByString, indexByStringWith, indexBySymbol, indexBySymbolWith, indexByWith, isAllowedTimeDuration, isArray, isDefined, isEmpty, isError, isFalse, isFunction, isNegativeNumber, isNullOrUndefined, isNullOrUndefinedOrEmpty, isNumber, isPositiveNumber, isString, isTimeInstant, isTrue, isUpgradable, isZero, jsonCloneDeep, last, listToDict, mapDefined, mapEntries, mapFirstTruthy, mapTruthys, max, maxBy, min, minBy, multiplyBy, noop, not, omitFromJsonObject, or, pad, padLeft, padRight, parseJson, partition, pick, pipedInvoke, pipedInvokeFromArray, pluralize, promiseSequence, randomId, randomNumberInInterval, range, repeat, reverse, round, roundAwayFromZero, roundToLower, roundToNearest, roundToUpper, roundTowardsZero, shallowArrayEquals, shallowRecordEquals, sortedArray, splitWords, stringToNumber, stringifyJson, sum, sumBy, tail, throttle, throwIfNullOrUndefined, transformCssDictionary, tryToParseJson, tryToParseNumber, uniq, uniqBy, uniqByKey, unzip, upsert, withTryCatch, withTryCatchAsync, wrapWithString, xor, zip };
-export type { ICancelable, ICancelablePromise, IDataUpgrader, TAccumulator, TAllKeysOptional, TAnyFunction, TArrayable, TAsyncAnyFunction, TAsyncBiConsumer, TAsyncBiFunction, TAsyncBiPredicate, TAsyncConsumer, TAsyncFunction, TAsyncOperation, TAsyncOperationTuple, TAsyncPredicate, TAsyncProducer, TAsyncValidation, TAsyncVoidFunction, TBiConsumer, TBiFunction, TBiPredicate, TComparisonDirection, TComparisonFunction, TComparisonResult, TConditionalOptionalType, TConditionalParameter, TConditionalParameterOptions, TConsumer, TCssDeclarationRulesDictionary, TCssSelectorDeclarationRulesDictionary, TDayOfMonth, TDayOfWeek, TDigit, TDigit1_9, TEmpty, TEmptyArray, TEmptyObject, TEmptyOptional, TFourDigits, TFourDigitsMillisecond, TFourDigitsYear, TFunction, THasNever, THourOfDay, THtmlString, TIdentityFunction, TIntervalHandle, TIsEmptyObject, TIso8601DateString, TIso8601DateUtcString, TJsonArray, TJsonObject, TJsonPrimitive, TJsonSerializable, TKeysOfType, TLoggerOpts, TMaybe, TMillisecondOfSecond, TMinuteOfHour, TMonth, TMonthName, TNegativeNumber, TNumber0_10, TNumber0_100, TNumber0_1000, TNumber0_15, TNumber0_20, TNumber0_5, TNumber1_10, TNumericFloatingPointString, TNumericString, TOneDigit, TOperation, TOperationTuple, TOptional, TOptionalKeysForType, TOptionsWithoutDefaults, TParseInt, TParseableInt, TPositiveNumber, TPredefinedTimeDuration, TPredicate, TPresentOptional, TPrettify, TPrimitive, TProducer, TPromisable, TReadableArray, TRelativeUrl, TReplaceType, TRequiredKeysForType, TSecondOfMinute, TSorter, TSorterBuilder, TStrictComparisonResult, TThreeDigits, TThreeDigitsMillisecond, TTimeInUnits, TTimeoutHandle, TTransformer, TTwoDigits, TTwoDigitsDate, TTwoDigitsHour, TTwoDigitsMinute, TTwoDigitsMonth, TTwoDigitsSecond, TTypePredicate, TUpToFourDigits, TUpToThreeDigits, TUpToTwoDigits, TUpgradable, TUrl, TValidTimeDuration, TValidation, TVoidFunction, TWeekNumber, TWithExtras, TWithRequiredProperties, TWithRequiredProperty, TYear, TZero };
+export { Cached, DataUpgrader, Deferred, DeferredCanceledError, ErrorCannotInstantiatePresentOptionalWithEmptyValue, ErrorGetEmptyOptional, ErrorSetEmptyOptional, Lazy, LazyAsync, LazyDictionary, Logger, NEVER, NonExhaustiveSwitchError, Operation, Optional, PredicateBuilder, RandomTimeDuration, RateThrottler, Semaphore, Sorter, StringParts, TimeDuration, TimeFrequency, TimeInstant, TimeRange, TimeUnit, TimeoutError, alwaysFalse, alwaysTrue, and, arrayGet, arrayIncludes, asError, asPromise, average, averageBy, awaitAtMost, capitalizeWord, clamp, clampInt0_100, constant, constantFalse, constantNull, constantOne, constantTrue, constantUndefined, constantZero, cssDeclarationRulesDictionaryToCss, decrement, decrementBy, delayPromise, dictToEntries, dictToList, divideBy, ellipsis, ensureArray, ensureDefined, ensureNegativeNumber, ensureNonNegativeNumber, ensureNonPositiveNumber, ensurePositiveNumber, ensureReadableArray, entriesToDict, entriesToEntries, entriesToList, extendArray, extendArrayWith, fill, fillWith, filterMap, filterMapReduce, filterWithTypePredicate, findInArray, findIndexInArray, first, flatMapTruthys, getCauseMessageFromError, getCauseStackFromError, getMessageFromError, getStackFromError, groupByBoolean, groupByBooleanWith, groupByNumber, groupByNumberWith, groupByString, groupByStringWith, groupBySymbol, groupBySymbolWith, hashCode, head, identity, ifDefined, ifNullOrUndefined, iff, includes, increment, incrementBy, indexByNumber, indexByNumberWith, indexByString, indexByStringWith, indexBySymbol, indexBySymbolWith, indexByWith, isAllowedTimeDuration, isArray, isDefined, isEmpty, isError, isFalse, isFunction, isNegativeNumber, isNullOrUndefined, isNullOrUndefinedOrEmpty, isNumber, isPositiveNumber, isString, isTimeInstant, isTrue, isUpgradable, isZero, jsonCloneDeep, last, listToDict, mapDefined, mapEntries, mapFirstTruthy, mapTruthys, max, maxBy, min, minBy, multiplyBy, noop, not, omitFromJsonObject, or, pad, padLeft, padRight, parseJson, parseTimeInstantBasicComponents, parseTimeInstantComponents, partition, pick, pipedInvoke, pipedInvokeFromArray, pluralize, promiseSequence, randomId, randomNumberInInterval, range, repeat, reverse, round, roundAwayFromZero, roundToLower, roundToNearest, roundToUpper, roundTowardsZero, shallowArrayEquals, shallowRecordEquals, sortedArray, splitWords, stringToNumber, stringifyJson, sum, sumBy, tail, throttle, throwIfNullOrUndefined, transformCssDictionary, tryToParseJson, tryToParseNumber, uniq, uniqBy, uniqByKey, unzip, upsert, withTryCatch, withTryCatchAsync, wrapWithString, xor, zip };
+export type { ICancelable, ICancelablePromise, IDataUpgrader, TAccumulator, TAllKeysOptional, TAnyFunction, TArrayable, TAsyncAnyFunction, TAsyncBiConsumer, TAsyncBiFunction, TAsyncBiPredicate, TAsyncConsumer, TAsyncFunction, TAsyncOperation, TAsyncOperationTuple, TAsyncPredicate, TAsyncProducer, TAsyncValidation, TAsyncVoidFunction, TBasicTimePattern, TBiConsumer, TBiFunction, TBiPredicate, TComparisonDirection, TComparisonFunction, TComparisonResult, TConditionalOptionalType, TConditionalParameter, TConditionalParameterOptions, TConsumer, TCssDeclarationRulesDictionary, TCssSelectorDeclarationRulesDictionary, TDayOfMonth, TDayOfWeek, TDigit, TDigit1_9, TEmpty, TEmptyArray, TEmptyObject, TEmptyOptional, TFourDigits, TFourDigitsMillisecond, TFourDigitsYear, TFunction, THasNever, THourOfDay, THtmlString, TIdentityFunction, TIntervalHandle, TIsEmptyObject, TIso8601DateString, TIso8601DateUtcString, TJsonArray, TJsonObject, TJsonPrimitive, TJsonSerializable, TKeysOfType, TLoggerOpts, TMaybe, TMillisecondOfSecond, TMinuteOfHour, TMonth, TMonthName, TNegativeNumber, TNumber0_10, TNumber0_100, TNumber0_1000, TNumber0_15, TNumber0_20, TNumber0_5, TNumber1_10, TNumericFloatingPointString, TNumericString, TOneDigit, TOperation, TOperationTuple, TOptional, TOptionalKeysForType, TOptionsWithoutDefaults, TParseInt, TParseableInt, TPositiveNumber, TPredefinedTimeDuration, TPredicate, TPresentOptional, TPrettify, TPrimitive, TProducer, TPromisable, TReadableArray, TRelativeUrl, TReplaceType, TRequiredKeysForType, TSecondOfMinute, TSorter, TSorterBuilder, TStrictComparisonResult, TThreeDigits, TThreeDigitsMillisecond, TTimeInUnits, TTimeoutHandle, TTransformer, TTwoDigits, TTwoDigitsDate, TTwoDigitsHour, TTwoDigitsMinute, TTwoDigitsMonth, TTwoDigitsSecond, TTypePredicate, TUpToFourDigits, TUpToThreeDigits, TUpToTwoDigits, TUpgradable, TUrl, TValidTimeDuration, TValidation, TVoidFunction, TWeekNumber, TWithExtras, TWithRequiredProperties, TWithRequiredProperty, TYear, TZero };

package/.rollup/index.mjs

@@ -445,9 +445,14 @@ function indexByWith(arr, keyGetter, valueMapper = v => v) {
 }
 
 function average(arr) {
+    if (arr.length === 0)
+        return null;
     const f = 1 / arr.length;
     return arr.reduce((tot, cur) => tot + (cur * f), 0);
 }
+function averageBy(arr, getter) {
+    return average(arr.map(getter));
+}
 function sum(arr) {
     return arr.reduce((tot, cur) => tot + cur, 0);
 }
@@ -456,7 +461,7 @@ function sumBy(arr, getter) {
 }
 function min(arr) {
     if (arr.length === 0)
-        throw new Error('Cannot calculate value on empty array');
+        return null;
     return arr.reduce((min, cur) => cur < min ? cur : min);
 }
 function minBy(arr, getter) {
@@ -464,7 +469,7 @@ function minBy(arr, getter) {
 }
 function max(arr) {
     if (arr.length === 0)
-        throw new Error('Cannot calculate value on empty array');
+        return null;
     return arr.reduce((max, cur) => cur > max ? cur : max);
 }
 function maxBy(arr, getter) {
@@ -619,9 +624,36 @@ function range(start, end) {
     let length = (end - start) + 1;
     return new Array(length).fill(1).map((_, i) => start + i);
 }
+/**
+ * Creates an array of the specified length, where each element is filled with the given value.
+ * @param length - The length of the array to create. Must be a non-negative integer.
+ * @param value - The value to fill each element with.
+ * @returns A new array with all elements set to the given value.
+ * @throws {RangeError} If length is negative, not an integer, or NaN.
+ * @example
+ * ```ts
+ * fill(3, 'a'); // ['a', 'a', 'a']
+ * fill(0, 42); // []
+ * fill(5, null); // [null, null, null, null, null]
+ * ```
+ */
 function fill(length, value) {
+    if (!Number.isInteger(length) || length < 0)
+        throw new RangeError(`Length must be a non-negative integer. Got: ${length}`);
     return new Array(length).fill(value);
 }
+/**
+ * Creates an array of the specified length, where each element is generated by the provided generator function.
+ * @param length - The length of the array to create. Must be a non-negative integer.
+ * @param generator - A function that takes an index and returns the value for that position.
+ * @returns A new array with elements generated by the generator function.
+ * @throws {RangeError} If length is negative or not an integer.
+ */
+function fillWith(length, generator) {
+    if (!Number.isInteger(length) || length < 0)
+        throw new RangeError(`Length must be a non-negative integer. Got: ${length}`);
+    return Array.from({ length }, (_, i) => generator(i));
+}
 function extendArray(arr, props) {
     return arr.map((t) => ({
         ...t,
@@ -2139,8 +2171,8 @@ class TimeInstant extends TimeBase {
         return timeInstantBuilder();
     }
     static fromIso8601(str) {
-        // 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})?$/;
+        // Regex to capture: YYYY-MM-DDTHH:mm:ss[.sss]Z 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);
@@ -2153,7 +2185,7 @@ class TimeInstant extends TimeBase {
         const hours = parseInt(hourStr, 10);
         const minutes = parseInt(minuteStr, 10);
         const seconds = parseInt(secondStr, 10);
-        const milliseconds = parseInt(millisecondStr, 10);
+        const milliseconds = millisecondStr ? parseInt(millisecondStr, 10) : 0;
         // Validate each component using standalone validation functions
         if (!isValidYear(year))
             throw new Error('Invalid year in: ' + str);
@@ -2589,6 +2621,216 @@ function parseTimeInstantComponents(dateString, pattern, config = {}) {
     }
     return result;
 }
+/**
+    * Parses a date string using only basic patterns that don't require Intl.
+    * This is a safer alternative to parseTimeInstantComponents that works even when Intl is not available.
+    *
+    * @param dateString The date string to parse
+    * @param pattern A basic pattern that doesn't require Intl (strongly typed)
+    * @returns Partial time instant parameters that were parsed from the string
+    * @throws Error if the string doesn't match the pattern or contains invalid values
+    */
+function parseTimeInstantBasicComponents(dateString, pattern, ignoreIntlAvailability = false) {
+    // Check if Intl is available, if so warn the user about the existing function
+    const isIntlAvailable = typeof Intl !== 'undefined' && typeof Intl.DateTimeFormat !== 'undefined';
+    if (isIntlAvailable && !ignoreIntlAvailability)
+        console.warn('Intl is available, use parseTimeInstantComponents instead of parseTimeInstantBasicComponents.');
+    const result = {};
+    let patternIndex = 0;
+    let dateStringIndex = 0;
+    // Helper function to check if a character is a pattern token
+    const isPatternChar = (char) => ['y', 'M', 'd', 'H', 'm', 's', 'S'].includes(char);
+    // Token extraction rules dictionary
+    const tokenRules = {
+        '': { maxLength: undefined }, // Default rule
+        'H': {
+            maxLength: 2,
+            validator: (value) => /^\d{1,2}$/.test(value) && parseInt(value, 10) >= 0 && parseInt(value, 10) <= 23,
+            description: 'Hour (0-23, 1-2 digits)'
+        },
+        'HH': {
+            maxLength: 2,
+            validator: (value) => /^\d{2}$/.test(value) && parseInt(value, 10) >= 0 && parseInt(value, 10) <= 23,
+            description: 'Hour (00-23, exactly 2 digits)'
+        },
+        'M': {
+            maxLength: 2,
+            validator: (value) => /^\d{1,2}$/.test(value) && parseInt(value, 10) >= 1 && parseInt(value, 10) <= 12,
+            description: 'Month (1-12, 1-2 digits)'
+        },
+        'MM': {
+            maxLength: 2,
+            validator: (value) => /^\d{2}$/.test(value) && parseInt(value, 10) >= 1 && parseInt(value, 10) <= 12,
+            description: 'Month (01-12, exactly 2 digits)'
+        },
+        'd': {
+            maxLength: 2,
+            validator: (value) => /^\d{1,2}$/.test(value) && parseInt(value, 10) >= 1 && parseInt(value, 10) <= 31,
+            description: 'Day (1-31, 1-2 digits)'
+        },
+        'dd': {
+            maxLength: 2,
+            validator: (value) => /^\d{2}$/.test(value) && parseInt(value, 10) >= 1 && parseInt(value, 10) <= 31,
+            description: 'Day (01-31, exactly 2 digits)'
+        },
+        'm': {
+            maxLength: 2,
+            validator: (value) => /^\d{1,2}$/.test(value) && parseInt(value, 10) >= 0 && parseInt(value, 10) <= 59,
+            description: 'Minutes (0-59, 1-2 digits)'
+        },
+        'mm': {
+            maxLength: 2,
+            validator: (value) => /^\d{2}$/.test(value) && parseInt(value, 10) >= 0 && parseInt(value, 10) <= 59,
+            description: 'Minutes (00-59, exactly 2 digits)'
+        },
+        's': {
+            maxLength: 2,
+            validator: (value) => /^\d{1,2}$/.test(value) && parseInt(value, 10) >= 0 && parseInt(value, 10) <= 59,
+            description: 'Seconds (0-59, 1-2 digits)'
+        },
+        'ss': {
+            maxLength: 2,
+            validator: (value) => /^\d{2}$/.test(value) && parseInt(value, 10) >= 0 && parseInt(value, 10) <= 59,
+            description: 'Seconds (00-59, exactly 2 digits)'
+        },
+        'S': {
+            maxLength: 3,
+            validator: (value) => /^\d{1,3}$/.test(value) && parseInt(value, 10) >= 0 && parseInt(value, 10) <= 999,
+            description: 'Milliseconds (0-999, 1-3 digits)'
+        },
+        'SS': {
+            maxLength: 2,
+            validator: (value) => /^\d{2}$/.test(value) && parseInt(value, 10) >= 0 && parseInt(value, 10) <= 99,
+            description: 'Milliseconds (0-99, exactly 2 digits)'
+        },
+        'SSS': {
+            maxLength: 3,
+            validator: (value) => /^\d{3}$/.test(value) && parseInt(value, 10) >= 0 && parseInt(value, 10) <= 999,
+            description: 'Milliseconds (000-999, exactly 3 digits)'
+        },
+        'y': {
+            maxLength: 4,
+            validator: (value) => /^\d{1,4}$/.test(value) && parseInt(value, 10) >= 0 && parseInt(value, 10) <= 9999,
+            description: 'Year (0-9999, 1-4 digits)'
+        },
+        'yy': {
+            maxLength: 2,
+            validator: (value) => /^\d{2}$/.test(value),
+            description: 'Year (2 digits)'
+        },
+        'yyyy': {
+            maxLength: 4,
+            validator: (value) => /^\d{4}$/.test(value),
+            description: 'Year (4 digits)'
+        }
+    };
+    // Helper function to extract a token value from the date string using token rules
+    const extractValue = (tokenType, tokenLength) => {
+        const tokenKey = tokenType.repeat(tokenLength);
+        const rule = tokenRules[tokenKey] || tokenRules[''];
+        // Extract consecutive digits up to maxLength
+        let endIndex = dateStringIndex;
+        let digitCount = 0;
+        const maxChars = rule.maxLength || tokenLength;
+        while (endIndex < dateString.length && /\d/.test(dateString[endIndex]) && digitCount < maxChars) {
+            endIndex++;
+            digitCount++;
+        }
+        const value = dateString.substring(dateStringIndex, endIndex);
+        dateStringIndex = endIndex;
+        // Validate the extracted value if a validator is provided
+        if (rule.validator && !rule.validator(value)) {
+            // Extract field name from description for better error messages
+            const fieldName = (rule.description || tokenKey).split(' ')[0].toLowerCase();
+            throw new Error(`Invalid ${fieldName} value: "${value}"`);
+        }
+        return value;
+    };
+    // Helper function to parse and validate a numeric value
+    const parseNumericValue = (value, min, max, field) => {
+        const num = parseInt(value, 10);
+        if (isNaN(num) || num < min || num > max)
+            throw new Error(`Invalid ${field} value: ${value}`);
+        return num;
+    };
+    while (patternIndex < pattern.length) {
+        const patternChar = pattern[patternIndex];
+        if (isPatternChar(patternChar)) {
+            // Start of a token - determine its full length
+            let tokenLength = 0;
+            while (patternIndex + tokenLength < pattern.length &&
+                pattern[patternIndex + tokenLength] === patternChar) {
+                tokenLength++;
+            }
+            // Extract and parse the corresponding value from the date string
+            const value = extractValue(patternChar, tokenLength);
+            // Check if we got enough characters for this token (after extraction)
+            if (value.length < tokenLength) {
+                throw new Error(`Date string "${dateString}" does not match pattern "${pattern}"`);
+            }
+            // Debug: log pattern processing (commented out for production)
+            // console.log( `Processing patternChar="${patternChar}" with tokenLength=${tokenLength}, value="${value}"` );
+            switch (patternChar) {
+                case 'y': {
+                    if (tokenLength === 2) {
+                        // 2-digit year
+                        const shortYear = parseNumericValue(value, 0, 99, 'year');
+                        result.year = shortYear < 50 ? 2000 + shortYear : 1900 + shortYear;
+                    }
+                    else {
+                        // 4-digit year
+                        result.year = parseNumericValue(value, 0, 9999, 'year');
+                    }
+                    break;
+                }
+                case 'M':
+                    result.month = parseNumericValue(value, 1, 12, 'month');
+                    break;
+                case 'd':
+                    result.date = parseNumericValue(value, 1, 31, 'day');
+                    break;
+                case 'H':
+                    result.hours = parseNumericValue(value, 0, 23, 'hours');
+                    break;
+                case 'm':
+                    result.minutes = parseNumericValue(value, 0, 59, 'minutes');
+                    break;
+                case 's':
+                    result.seconds = parseNumericValue(value, 0, 59, 'seconds');
+                    break;
+                case 'S': {
+                    let ms = parseInt(value, 10);
+                    if (isNaN(ms))
+                        throw new Error(`Invalid milliseconds value: ${value}`);
+                    // Normalize to milliseconds based on length
+                    if (tokenLength === 1)
+                        ms *= 100;
+                    else if (tokenLength === 2)
+                        ms *= 10;
+                    result.milliseconds = ms;
+                    break;
+                }
+                default:
+                    throw new Error(`Unsupported pattern character: ${patternChar}`);
+            }
+            patternIndex += tokenLength;
+        }
+        else {
+            // Non-pattern character (separator like '-', '/', ':', ' ', '.')
+            if (dateStringIndex >= dateString.length ||
+                dateString[dateStringIndex] !== patternChar) {
+                throw new Error(`Date string "${dateString}" does not match pattern "${pattern}"`);
+            }
+            patternIndex++;
+            dateStringIndex++;
+        }
+    }
+    // After processing the entire pattern, check if we consumed the entire date string
+    if (dateStringIndex < dateString.length) {
+        throw new Error(`Date string "${dateString}" does not match pattern "${pattern}"`);
+    }
+    return result;
+}
 
 const LEVELS = ["trace", "log", "debug", "info", "warn", "error"];
 const timestamp = () => TimeInstant.now().format('HH:mm:ss');
@@ -3263,5 +3505,5 @@ function isUpgradable(obj) {
     return isDefined(obj) && typeof obj === "object" && VERSION_FIELD in obj && isNumber(obj.$version) && isPositiveNumber(obj.$version);
 }
 
-export { Cached, DataUpgrader, Deferred, DeferredCanceledError, ErrorCannotInstantiatePresentOptionalWithEmptyValue, ErrorGetEmptyOptional, ErrorSetEmptyOptional, Lazy, LazyAsync, LazyDictionary, Logger, NEVER, NonExhaustiveSwitchError, Operation, Optional, PredicateBuilder, RandomTimeDuration, RateThrottler, Semaphore, Sorter, StringParts, TimeDuration, TimeFrequency, TimeInstant, TimeRange, TimeUnit, TimeoutError, alwaysFalse, alwaysTrue, and, arrayGet, arrayIncludes, asError, asPromise, average, awaitAtMost, capitalizeWord, clamp, clampInt0_100, constant, constantFalse, constantNull, constantOne, constantTrue, constantUndefined, constantZero, cssDeclarationRulesDictionaryToCss, decrement, decrementBy, delayPromise, dictToEntries, dictToList, divideBy, ellipsis, ensureArray, ensureDefined, ensureNegativeNumber, ensureNonNegativeNumber, ensureNonPositiveNumber, ensurePositiveNumber, ensureReadableArray, entriesToDict, entriesToEntries, entriesToList, extendArray, extendArrayWith, fill, filterMap, filterMapReduce, filterWithTypePredicate, findInArray, findIndexInArray, first$1 as first, flatMapTruthys, getCauseMessageFromError, getCauseStackFromError, getMessageFromError, getStackFromError, groupByBoolean, groupByBooleanWith, groupByNumber, groupByNumberWith, groupByString, groupByStringWith, groupBySymbol, groupBySymbolWith, hashCode, head, identity, ifDefined, ifNullOrUndefined, iff, includes, increment, incrementBy, indexByNumber, indexByNumberWith, indexByString, indexByStringWith, indexBySymbol, indexBySymbolWith, indexByWith, isAllowedTimeDuration, isArray, isDefined, isEmpty, isError, isFalse, isFunction, isNegativeNumber, isNullOrUndefined, isNullOrUndefinedOrEmpty, isNumber, isPositiveNumber, isString, isTimeInstant, isTrue, isUpgradable, isZero, jsonCloneDeep, last$1 as last, listToDict, mapDefined, mapEntries, mapFirstTruthy, mapTruthys, max, maxBy, min, minBy, multiplyBy, noop, not, omitFromJsonObject, or, pad, padLeft, padRight, parseJson, partition, pick, pipedInvoke, pipedInvokeFromArray, pluralize, promiseSequence, randomId, randomNumberInInterval, range, repeat, reverse$1 as reverse, round, roundAwayFromZero, roundToLower, roundToNearest, roundToUpper, roundTowardsZero, shallowArrayEquals, shallowRecordEquals, sortedArray, splitWords, stringToNumber, stringifyJson, sum, sumBy, tail, throttle, throwIfNullOrUndefined, transformCssDictionary, tryToParseJson, tryToParseNumber, uniq, uniqBy, uniqByKey, unzip, upsert, withTryCatch, withTryCatchAsync, wrapWithString, xor, zip };
+export { Cached, DataUpgrader, Deferred, DeferredCanceledError, ErrorCannotInstantiatePresentOptionalWithEmptyValue, ErrorGetEmptyOptional, ErrorSetEmptyOptional, Lazy, LazyAsync, LazyDictionary, Logger, NEVER, NonExhaustiveSwitchError, Operation, Optional, PredicateBuilder, RandomTimeDuration, RateThrottler, Semaphore, Sorter, StringParts, TimeDuration, TimeFrequency, TimeInstant, TimeRange, TimeUnit, TimeoutError, alwaysFalse, alwaysTrue, and, arrayGet, arrayIncludes, asError, asPromise, average, averageBy, awaitAtMost, capitalizeWord, clamp, clampInt0_100, constant, constantFalse, constantNull, constantOne, constantTrue, constantUndefined, constantZero, cssDeclarationRulesDictionaryToCss, decrement, decrementBy, delayPromise, dictToEntries, dictToList, divideBy, ellipsis, ensureArray, ensureDefined, ensureNegativeNumber, ensureNonNegativeNumber, ensureNonPositiveNumber, ensurePositiveNumber, ensureReadableArray, entriesToDict, entriesToEntries, entriesToList, extendArray, extendArrayWith, fill, fillWith, filterMap, filterMapReduce, filterWithTypePredicate, findInArray, findIndexInArray, first$1 as first, flatMapTruthys, getCauseMessageFromError, getCauseStackFromError, getMessageFromError, getStackFromError, groupByBoolean, groupByBooleanWith, groupByNumber, groupByNumberWith, groupByString, groupByStringWith, groupBySymbol, groupBySymbolWith, hashCode, head, identity, ifDefined, ifNullOrUndefined, iff, includes, increment, incrementBy, indexByNumber, indexByNumberWith, indexByString, indexByStringWith, indexBySymbol, indexBySymbolWith, indexByWith, isAllowedTimeDuration, isArray, isDefined, isEmpty, isError, isFalse, isFunction, isNegativeNumber, isNullOrUndefined, isNullOrUndefinedOrEmpty, isNumber, isPositiveNumber, isString, isTimeInstant, isTrue, isUpgradable, isZero, jsonCloneDeep, last$1 as last, listToDict, mapDefined, mapEntries, mapFirstTruthy, mapTruthys, max, maxBy, min, minBy, multiplyBy, noop, not, omitFromJsonObject, or, pad, padLeft, padRight, parseJson, parseTimeInstantBasicComponents, parseTimeInstantComponents, partition, pick, pipedInvoke, pipedInvokeFromArray, pluralize, promiseSequence, randomId, randomNumberInInterval, range, repeat, reverse$1 as reverse, round, roundAwayFromZero, roundToLower, roundToNearest, roundToUpper, roundTowardsZero, shallowArrayEquals, shallowRecordEquals, sortedArray, splitWords, stringToNumber, stringifyJson, sum, sumBy, tail, throttle, throwIfNullOrUndefined, transformCssDictionary, tryToParseJson, tryToParseNumber, uniq, uniqBy, uniqByKey, unzip, upsert, withTryCatch, withTryCatchAsync, wrapWithString, xor, zip };
 //# sourceMappingURL=index.mjs.map