@zelgadis87/utils-core 5.5.0-beta.2 → 6.0.0-beta.5

package/.rollup/index.d.ts

@@ -97,12 +97,13 @@ declare function pipedInvoke<T, A, B, C, D, E, F, G, H, I>(op1: TFunction<T, A>,
 declare function pipedInvoke<T, A, B, C, D, E, F, G, H, I>(op1: TFunction<T, A>, op2: TFunction<A, B>, op3: TFunction<B, C>, op4: TFunction<C, D>, op5: TFunction<D, E>, op6: TFunction<E, F>, op7: TFunction<F, G>, op8: TFunction<G, H>, op9: TFunction<H, I>, ...operations: TFunction<any, any>[]): TFunction<T, unknown>;
 declare function pipedInvokeFromArray<T, R>(fns: Array<TFunction<any, any>>): TFunction<any, any>;
 
-declare class Optional<T> implements TOptional<T> {
+declare class OptionalClz<T> implements TOptional<T> {
     private _present;
     private _value;
     private constructor();
     getRawValue(): T | undefined;
     get(): T;
+    getOrElseThrow(): T;
     getOrElseThrow(errorProducer: TProducer<Error>): T;
     set(t: T): void;
     protected setNullable(t: T | null | undefined): void | this;
@@ -111,22 +112,17 @@ declare class Optional<T> implements TOptional<T> {
     isPresent(): this is TPresentOptional<T>;
     ifEmpty(callback: TVoidFunction): void;
     ifPresent(callback: TConsumer<T>): void;
-    ifPresentThenClear(callback: TConsumer<T>): void;
     apply(callbackIfPresent: TConsumer<T>, callbackIfEmpty: TVoidFunction): any;
     orElseReturn(newValue: T): T;
-    orElse: (newValue: T) => T;
     orElseReturnNull(): T | null;
     orElseReturnUndefined(): T | undefined;
     orElseProduce(newValueProducer: TProducer<T>): T;
-    orElseGet: (newValueProducer: TProducer<T>) => T;
     orElseReturnAndApply(newValue: T): T;
     orElseProduceAndApply(newValueProducer: TProducer<T>): T;
     orElseReturnNullableAndApply(newValue: T | null | undefined): TOptional<T>;
     orElseProduceNullableAndApply(newValueProducer: TProducer<T | null | undefined>): TOptional<T>;
     orElseReturnNullable(newValue: T | null | undefined): any;
-    orElseNullable: (newValue: T | null | undefined) => any;
     orElseProduceNullable(newValueProducer: TProducer<T | null | undefined>): any;
-    orElseGetNullable: (newValueProducer: TProducer<T | null | undefined>) => any;
     orElseThrow(errorProducer: TProducer<Error>): TPresentOptional<T>;
     throwIfPresent(errorProducer: TFunction<T, Error>): any;
     mapTo<R>(mapper: TFunction<T, R | null | undefined>): any;
@@ -138,9 +134,9 @@ declare class Optional<T> implements TOptional<T> {
     static findInArray<T>(arr: ReadonlyArray<T>, predicate: TPredicate<T>): TOptional<T>;
     static findIndexInArray<T>(arr: ReadonlyArray<T>, predicate: TPredicate<T>): TOptional<number>;
 }
-
 type TOptional<T> = {
     /**
+     * @deprecated[2026.04.07]: Replace with {@link getOrElseThrow} (drop-in replacement with no arguments)
      * @returns the currently stored value, if any; throws {@link ErrorGetEmptyOptional} otherwise;
      */
     get(): T;
@@ -149,9 +145,10 @@ type TOptional<T> = {
      */
     getRawValue(): T | undefined;
     /**
-     * @returns the currently stored value, if any; throws the error generated by errorProducer otherwise;
+     * @returns the currently stored value, if any; throws {@link ErrorGetEmptyOptional} if no errorProducer is provided, or the error generated by errorProducer otherwise;
      */
-    getOrElseThrow: (errorProducer: TProducer<Error>) => T;
+    getOrElseThrow(): T;
+    getOrElseThrow(errorProducer: TProducer<Error>): T;
     /**
      * Places a new value inside this optional. Throws {@link ErrorSetEmptyOptional} if t is null or undefined.
      */
@@ -166,15 +163,9 @@ type TOptional<T> = {
     ifPresent(callback: TConsumer<T>): void;
     apply<RP = void, RE = void>(callbackIfPresent: TFunction<T, RP>, callbackIfEmpty: TProducer<RE>): RP | RE;
     throwIfPresent: (errorGenerator: TFunction<T, Error>) => TEmptyOptional<T>;
-    /** @deprecated[2025.07.25]: Replace with {@link orElseReturn} (drop-in replacement) */
-    orElse: (newValue: T) => T;
-    /** @deprecated[2025.07.25]: Replace with {@link orElseProduce} (drop-in replacement) */
-    orElseGet: (newValueProducer: TProducer<T>) => T;
-    /** @deprecated[2025.07.25]: Replace with {@link orElseReturnNullabe} (drop-in replacement) */
-    orElseNullable: (newValue: T | null | undefined) => TOptional<T>;
-    /** @deprecated[2025.07.25]: Replace with {@link orElseProduceNullable} (drop-in replacement) */
-    orElseGetNullable: (newValueProducer: TProducer<T | null | undefined>) => TOptional<T>;
     orElseReturn: (newValue: T) => T;
+    orElseReturnNull(): T | null;
+    orElseReturnUndefined(): T | undefined;
     orElseProduce: (newValueProducer: TProducer<T>) => T;
     orElseReturnNullable: (newValue: T | null | undefined) => TOptional<T>;
     orElseProduceNullable: (newValueProducer: TProducer<T | null | undefined>) => TOptional<T>;
@@ -188,7 +179,10 @@ type TOptional<T> = {
     filter(predicate: TPredicate<T>): TOptional<T>;
 };
 type TEmptyOptional<T> = TOptional<T> & {
+    /** @deprecated[2026.04.07]: Replace with {@link getOrElseThrow} (drop-in replacement with no arguments) */
     get(): never;
+    getOrElseThrow(): never;
+    getOrElseThrow(errorProducer: TProducer<Error>): never;
     isEmpty(): true;
     isPresent(): false;
     apply<RP = void, RE = void>(callbackIfPresent: TFunction<T, RP>, callbackIfEmpty: TProducer<RE>): RE;
@@ -208,6 +202,8 @@ type TEmptyOptional<T> = TOptional<T> & {
 };
 type TPresentOptional<T> = TOptional<T> & {
     get(): T;
+    getOrElseThrow(): T;
+    getOrElseThrow(errorProducer: TProducer<Error>): T;
     isEmpty(): false;
     isPresent(): true;
     apply<RP = void, RE = void>(callbackIfPresent: TFunction<T, RP>, callbackIfEmpty: TProducer<RE>): RP;
@@ -550,7 +546,7 @@ declare class TimeInstant extends TimeBase<TimeInstant> {
     static builder(): TTimeInstantBuilder;
     static fromIso8601(str: string): TimeInstant;
     /**
-     * @deprecated [2025.10.19]: Use fromIso8601 instead.
+     * @deprecated[2025.10.19]: Use fromIso8601 instead.
      */
     static tryFromIso8601: typeof TimeInstant.fromIso8601;
     static now(): TimeInstant;
@@ -694,16 +690,16 @@ type TSorterStepForNumbers<_T, Ret> = {
     }): Ret;
 };
 type TSorterStepForStrings<_T, Ret> = {
-    /** @deprecated: Use inLexographicalOrder instead */ inLexographicalOrder(opts?: {
+    /** @deprecated[2025.09.29]: Use inLexicographicalOrder instead */ inLexographicalOrder(opts?: {
         nullsFirst?: boolean;
     }): Ret;
-    /** @deprecated: Use inLexographicalOrderIgnoringCase instead */ inLexographicalOrderIgnoringCase(opts?: {
+    /** @deprecated[2025.09.29]: Use inLexicographicalOrderIgnoringCase instead */ inLexographicalOrderIgnoringCase(opts?: {
         nullsFirst?: boolean;
     }): Ret;
-    /** @deprecated: Use inReverseLexographicalOrder instead */ inReverseLexographicalOrder(opts?: {
+    /** @deprecated[2025.09.29]: Use inReverseLexicographicalOrder instead */ inReverseLexographicalOrder(opts?: {
         nullsFirst?: boolean;
     }): Ret;
-    /** @deprecated: Use inReverseLexographicalOrderIgnoringCase instead */ inReverseLexographicalOrderIgnoringCase(opts?: {
+    /** @deprecated[2025.09.29]: Use inReverseLexicographicalOrderIgnoringCase instead */ inReverseLexographicalOrderIgnoringCase(opts?: {
         nullsFirst?: boolean;
     }): Ret;
     inLexicographicalOrder(opts?: {
@@ -951,8 +947,6 @@ declare function isFalse(x: unknown): x is false;
 declare function dictToEntries<V, K extends string = string>(obj: Record<K, V>): [K, V][];
 declare function entriesToDict<V, K extends string = string>(entries: [K, V][]): Record<K, V>;
 declare function entriesToEntries<K1 extends string, V1, K2 extends string, V2>(dict: Record<K1, V1>, mapper: TFunction<[K1, V1], [K2, V2]>): Record<K2, V2>;
-/** @deprecated[2025.08.01]: Compatibility layer. */
-declare const mapEntries: typeof entriesToEntries;
 declare function entriesToList<K1 extends string, V1, R>(dict: Record<K1, V1>, mapper: TFunction<[K1, V1], R>): Array<R>;
 
 type TEmpty = Record<string, never>;
@@ -1061,7 +1055,7 @@ type TAsyncOperation<T, E = Error> = Promise<TOperation<T, E>>;
 type TOperationTuple<T, E = Error> = [T, undefined] | [undefined, E];
 type TAsyncOperationTuple<T, E = Error> = Promise<TOperationTuple<T, E>>;
 /**
- * @deprecated Use `TOperation<T, OperationAggregateError<E>>` with `Operation.combine` instead.
+ * @deprecated[2026.03.20]: Use `TOperation<T, OperationAggregateError<E>>` with `Operation.combine` instead.
  */
 type TValidation<T, E = Error> = {
     success: false;
@@ -1071,7 +1065,7 @@ type TValidation<T, E = Error> = {
     data: T;
 };
 /**
- * @deprecated Use `TAsyncOperation<T, OperationAggregateError<E>>` with `Operation.combine` instead.
+ * @deprecated[2026.03.20]: Use `TAsyncOperation<T, OperationAggregateError<E>>` with `Operation.combine` instead.
  */
 type TAsyncValidation<T, E = Error> = Promise<TValidation<T, E>>;
 /**
@@ -1267,7 +1261,7 @@ declare const NEVER: Promise<unknown>;
 
 /**
  * Returns a random integer in the range [min, max].
- * @deprecated Use randomIntegerInInterval or randomDecimalInInterval instead
+ * @deprecated[2026.03.17]: Use randomIntegerInInterval or randomDecimalInInterval instead.
  */
 declare function randomNumberInInterval(min: number, max: number): number;
 /**
@@ -1408,6 +1402,7 @@ declare class Lazy<T> {
     ifPresent(fn: (t: T) => void): void;
     ifEmpty(fn: () => void): void;
     apply(fnPresent: (t: T) => void, fnEmpty: () => void): void;
+    mapOrElse<R>(onPresent: (t: T) => R, onEmpty: () => R): R;
     protected empty(): void;
     static of<T>(generator: () => T): Lazy<T>;
 }
@@ -1676,6 +1671,13 @@ type TAddTransition<T extends readonly TTransitionRecord[], From extends number,
  * - Duplicate transition definitions
  * - Backward transitions (e.g., version 2 → 1)
  *
+ * ## Architectural Convention
+ *
+ * The built DataUpgrader is the **single point of versioning** for your data. Never bypass it
+ * with manual `$version` checks — `upgrade()` is idempotent (no-op on latest version) and
+ * accepts the full `Vstar` union, returning the current latest version. See {@link DataUpgrader}
+ * for the full type aliasing conventions (`Vstar` union, no-suffix alias, adding new versions).
+ *
  * @example
  * ```typescript
  * // Step 1: Define all historical versions with $version discriminator
@@ -1778,6 +1780,49 @@ interface IDataUpgrader<XStar extends TUpgradable, XLatest extends XStar> {
  * finding the shortest upgrade path and applying transformations. This is particularly useful for
  * handling persisted data that may be in any historical format.
  *
+ * ## Architectural Conventions
+ *
+ * ### Type Aliasing
+ * ```typescript
+ * // Xstar = union of ALL known versions (upgrader input type)
+ * type TMyData_Vstar = TMyData_V1 | TMyData_V2 | TMyData_V3;
+ *
+ * // No suffix = alias for the CURRENT latest version (upgrader output type)
+ * type TMyData = TMyData_V3;
+ * // When adding V4 later, update Vstar and change the alias:
+ * // type TMyData_Vstar = TMyData_V1 | TMyData_V2 | TMyData_V3 | TMyData_V4;
+ * // type TMyData = TMyData_V4;
+ * ```
+ *
+ * ### Always Run the Upgrader
+ *
+ * **Every piece of serialized data must be treated as potentially any old version.**
+ *
+ * Never inspect `$version` manually and skip the upgrader. Always feed raw parsed data
+ * directly into `upgrade()`. The upgrader is **idempotent** — calling it on data already
+ * at the latest version is a no-op that returns immediately. Bypassing it creates fragile
+ * fast paths that break when new versions are introduced.
+ *
+ * ```typescript
+ * // ✅ CORRECT — always delegate to the upgrader
+ * const raw = JSON.parse(json) as TMyData_Vstar;
+ * const current = await upgrader.upgrade(raw);
+ *
+ * // ❌ WRONG — manual version check bypasses the upgrader
+ * const raw = JSON.parse(json);
+ * if (raw.$version === 3) {
+ *   // This works today, breaks silently when V4 is added
+ * }
+ * ```
+ *
+ * ### Adding a New Version
+ *
+ * 1. Define the new version type with `$version: N`
+ * 2. Add it to the `Vstar` union
+ * 3. Change the no-suffix alias to point to the new version
+ * 4. Add a transition from the previous latest to the new version
+ * 5. Existing code that calls `upgrade()` requires zero changes
+ *
  * **Key Use Case:** Reading serialized data of unknown version and migrating it transparently.
  *
  * @example
@@ -1787,9 +1832,9 @@ interface IDataUpgrader<XStar extends TUpgradable, XLatest extends XStar> {
  * type TSerializedData_V2 = { name: string; age: number; $version: 2 };
  * type TSerializedData_V3 = { name: string; age: number; email: string; $version: 3 };
  *
- * // Step 2: Create union type and current version type
+ * // Step 2: Create Vstar union (all versions) and current-version alias (latest only)
  * type TSerializedData_Vstar = TSerializedData_V1 | TSerializedData_V2 | TSerializedData_V3;
- * type TSerializedData = TSerializedData_V3;
+ * type TSerializedData = TSerializedData_V3; // Update this when adding V4
  *
  * // Step 3: Create upgrader with transition functions
  * const upgrader = DataUpgrader.create<TSerializedData_Vstar, TSerializedData>(3)
@@ -1849,5 +1894,5 @@ declare class DataUpgrader<X extends TUpgradable, XLatest extends X> implements
 }
 declare function isUpgradable(obj: TJsonSerializable): obj is TUpgradable;
 
-export { Cached, DataUpgrader, DataUpgraderBuilder, Deferred, DeferredCanceledError, ErrorCannotInstantiatePresentOptionalWithEmptyValue, ErrorGetEmptyOptional, ErrorSetEmptyOptional, Lazy, LazyAsync, LazyDictionary, Logger, NEVER, NonExhaustiveSwitchError, Operation, OperationAggregateError, 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, havingMaxBy, havingMinBy, 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, randomDecimalInInterval, randomId, randomIntegerInInterval, randomNumberInInterval, randomPick, randomPicks, 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 { Cached, DataUpgrader, DataUpgraderBuilder, Deferred, DeferredCanceledError, ErrorCannotInstantiatePresentOptionalWithEmptyValue, ErrorGetEmptyOptional, ErrorSetEmptyOptional, Lazy, LazyAsync, LazyDictionary, Logger, NEVER, NonExhaustiveSwitchError, Operation, OperationAggregateError, OptionalClz as 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, havingMaxBy, havingMinBy, 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, mapFirstTruthy, mapTruthys, max, maxBy, min, minBy, multiplyBy, noop, not, omitFromJsonObject, or, pad, padLeft, padRight, parseJson, parseTimeInstantBasicComponents, parseTimeInstantComponents, partition, pick, pipedInvoke, pipedInvokeFromArray, pluralize, promiseSequence, randomDecimalInInterval, randomId, randomIntegerInInterval, randomNumberInInterval, randomPick, randomPicks, 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, TOperationFailure, TOperationSuccess, 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

@@ -211,7 +211,7 @@ function throwIfNullOrUndefined(source, errorProducer = () => new Error(`Unexpec
     return ifNullOrUndefined(source, () => { throw errorProducer(); });
 }
 
-class Optional {
+class OptionalClz {
     _present;
     _value;
     constructor(t) {
@@ -223,9 +223,9 @@ class Optional {
         return this._value;
     }
     get() {
-        return this.getOrElseThrow(() => new ErrorGetEmptyOptional());
+        return this.getOrElseThrow();
     }
-    getOrElseThrow(errorProducer) {
+    getOrElseThrow(errorProducer = () => new ErrorGetEmptyOptional()) {
         if (this.isEmpty())
             throw errorProducer();
         return this._value;
@@ -260,12 +260,6 @@ class Optional {
         if (this.isPresent())
             return callback(this.get());
     }
-    ifPresentThenClear(callback) {
-        if (this.isPresent()) {
-            callback(this.get());
-            this.clear();
-        }
-    }
     apply(callbackIfPresent, callbackIfEmpty) {
         if (this.isEmpty()) {
             return callbackIfEmpty();
@@ -282,7 +276,6 @@ class Optional {
             return newValue;
         }
     }
-    orElse = this.orElseReturn.bind(this);
     orElseReturnNull() {
         return this.isPresent() ? this.get() : null;
     }
@@ -297,7 +290,6 @@ class Optional {
             return newValueProducer();
         }
     }
-    orElseGet = this.orElseProduce.bind(this);
     orElseReturnAndApply(newValue) {
         if (this.isPresent()) {
             return this.get();
@@ -338,18 +330,16 @@ class Optional {
     }
     orElseReturnNullable(newValue) {
         if (this.isEmpty())
-            return Optional.ofNullable(newValue);
+            return OptionalClz.ofNullable(newValue);
         return this;
     }
-    orElseNullable = this.orElseReturnNullable.bind(this);
     orElseProduceNullable(newValueProducer) {
         if (this.isEmpty()) {
             const newValue = newValueProducer();
-            return Optional.ofNullable(newValue);
+            return OptionalClz.ofNullable(newValue);
         }
         return this;
     }
-    orElseGetNullable = this.orElseProduceNullable.bind(this);
     orElseThrow(errorProducer) {
         if (this.isEmpty())
             throw errorProducer();
@@ -361,35 +351,35 @@ class Optional {
         throw errorProducer(this.get());
     }
     mapTo(mapper) {
-        return this.apply(() => Optional.ofNullable(mapper(this.get())), () => Optional.empty());
+        return this.apply(() => OptionalClz.ofNullable(mapper(this.get())), () => OptionalClz.empty());
     }
     flatMapTo(mapper) {
-        return this.apply(() => mapper(this.get()), () => Optional.empty());
+        return this.apply(() => mapper(this.get()), () => OptionalClz.empty());
     }
     filter(predicate) {
         if (this.isEmpty())
             return this;
         if (predicate(this.get()))
             return this;
-        return Optional.empty();
+        return OptionalClz.empty();
     }
     static empty() {
-        return new Optional(undefined);
+        return new OptionalClz(undefined);
     }
     static of(t) {
         if (isNullOrUndefined(t))
             throw new ErrorCannotInstantiatePresentOptionalWithEmptyValue();
-        return new Optional(t);
+        return new OptionalClz(t);
     }
     static ofNullable(t) {
-        return new Optional(t);
+        return new OptionalClz(t);
     }
     static findInArray(arr, predicate) {
-        return Optional.ofNullable(arr.find(predicate));
+        return OptionalClz.ofNullable(arr.find(predicate));
     }
     static findIndexInArray(arr, predicate) {
         const idx = arr.findIndex(predicate);
-        return idx === -1 ? Optional.empty() : Optional.of(idx);
+        return idx === -1 ? OptionalClz.empty() : OptionalClz.of(idx);
     }
 }
 class ErrorGetEmptyOptional extends Error {
@@ -838,11 +828,11 @@ function shallowArrayEquals(a, b) {
 }
 /** @deprecated[2026.03.01]: Use {@link Optional.findInArray} instead. */
 function findInArray(arr, predicate) {
-    return Optional.findInArray(arr, predicate);
+    return OptionalClz.findInArray(arr, predicate);
 }
 /** @deprecated[2026.03.01]: Use {@link Optional.findIndexInArray} instead. */
 function findIndexInArray(arr, predicate) {
-    return Optional.findIndexInArray(arr, predicate);
+    return OptionalClz.findIndexInArray(arr, predicate);
 }
 function zip(ts, rs) {
     if (ts.length !== rs.length)
@@ -863,8 +853,8 @@ function unzip(arr) {
  */
 function arrayGet(arr, index) {
     if (index < 0 || index >= arr.length)
-        return Optional.empty();
-    return Optional.of(arr[index]);
+        return OptionalClz.empty();
+    return OptionalClz.of(arr[index]);
 }
 
 function isTrue(x) {
@@ -1443,7 +1433,7 @@ const NEVER = new Promise(_resolve => { });
 
 /**
  * Returns a random integer in the range [min, max].
- * @deprecated Use randomIntegerInInterval or randomDecimalInInterval instead
+ * @deprecated[2026.03.17]: Use randomIntegerInInterval or randomDecimalInInterval instead.
  */
 function randomNumberInInterval(min, max) {
     return Math.floor(Math.random() * (max - min + 1) + min);
@@ -1498,8 +1488,6 @@ function entriesToDict(entries) {
 function entriesToEntries(dict, mapper) {
     return entriesToDict(dictToEntries(dict).map((entry) => mapper(entry)));
 }
-/** @deprecated[2025.08.01]: Compatibility layer. */
-const mapEntries = entriesToEntries;
 function entriesToList(dict, mapper) {
     return dictToEntries(dict).map((entry) => mapper(entry));
 }
@@ -1585,6 +1573,9 @@ class Lazy {
             fnEmpty();
         }
     }
+    mapOrElse(onPresent, onEmpty) {
+        return this._initialized ? onPresent(this._value) : onEmpty();
+    }
     empty() {
         this._initialized = false;
     }
@@ -2502,7 +2493,7 @@ class TimeInstant extends TimeBase {
         });
     }
     /**
-     * @deprecated [2025.10.19]: Use fromIso8601 instead.
+     * @deprecated[2025.10.19]: Use fromIso8601 instead.
      */
     static tryFromIso8601 = this.fromIso8601;
     static now() {
@@ -3797,6 +3788,49 @@ const VERSION_FIELD = "$version";
  * finding the shortest upgrade path and applying transformations. This is particularly useful for
  * handling persisted data that may be in any historical format.
  *
+ * ## Architectural Conventions
+ *
+ * ### Type Aliasing
+ * ```typescript
+ * // Xstar = union of ALL known versions (upgrader input type)
+ * type TMyData_Vstar = TMyData_V1 | TMyData_V2 | TMyData_V3;
+ *
+ * // No suffix = alias for the CURRENT latest version (upgrader output type)
+ * type TMyData = TMyData_V3;
+ * // When adding V4 later, update Vstar and change the alias:
+ * // type TMyData_Vstar = TMyData_V1 | TMyData_V2 | TMyData_V3 | TMyData_V4;
+ * // type TMyData = TMyData_V4;
+ * ```
+ *
+ * ### Always Run the Upgrader
+ *
+ * **Every piece of serialized data must be treated as potentially any old version.**
+ *
+ * Never inspect `$version` manually and skip the upgrader. Always feed raw parsed data
+ * directly into `upgrade()`. The upgrader is **idempotent** — calling it on data already
+ * at the latest version is a no-op that returns immediately. Bypassing it creates fragile
+ * fast paths that break when new versions are introduced.
+ *
+ * ```typescript
+ * // ✅ CORRECT — always delegate to the upgrader
+ * const raw = JSON.parse(json) as TMyData_Vstar;
+ * const current = await upgrader.upgrade(raw);
+ *
+ * // ❌ WRONG — manual version check bypasses the upgrader
+ * const raw = JSON.parse(json);
+ * if (raw.$version === 3) {
+ *   // This works today, breaks silently when V4 is added
+ * }
+ * ```
+ *
+ * ### Adding a New Version
+ *
+ * 1. Define the new version type with `$version: N`
+ * 2. Add it to the `Vstar` union
+ * 3. Change the no-suffix alias to point to the new version
+ * 4. Add a transition from the previous latest to the new version
+ * 5. Existing code that calls `upgrade()` requires zero changes
+ *
  * **Key Use Case:** Reading serialized data of unknown version and migrating it transparently.
  *
  * @example
@@ -3806,9 +3840,9 @@ const VERSION_FIELD = "$version";
  * type TSerializedData_V2 = { name: string; age: number; $version: 2 };
  * type TSerializedData_V3 = { name: string; age: number; email: string; $version: 3 };
  *
- * // Step 2: Create union type and current version type
+ * // Step 2: Create Vstar union (all versions) and current-version alias (latest only)
  * type TSerializedData_Vstar = TSerializedData_V1 | TSerializedData_V2 | TSerializedData_V3;
- * type TSerializedData = TSerializedData_V3;
+ * type TSerializedData = TSerializedData_V3; // Update this when adding V4
  *
  * // Step 3: Create upgrader with transition functions
  * const upgrader = DataUpgrader.create<TSerializedData_Vstar, TSerializedData>(3)
@@ -3948,6 +3982,13 @@ function isUpgradable(obj) {
  * - Duplicate transition definitions
  * - Backward transitions (e.g., version 2 → 1)
  *
+ * ## Architectural Convention
+ *
+ * The built DataUpgrader is the **single point of versioning** for your data. Never bypass it
+ * with manual `$version` checks — `upgrade()` is idempotent (no-op on latest version) and
+ * accepts the full `Vstar` union, returning the current latest version. See {@link DataUpgrader}
+ * for the full type aliasing conventions (`Vstar` union, no-suffix alias, adding new versions).
+ *
  * @example
  * ```typescript
  * // Step 1: Define all historical versions with $version discriminator
@@ -4056,5 +4097,5 @@ class DataUpgraderBuilder {
     }
 }
 
-export { Cached, DataUpgrader, DataUpgraderBuilder, Deferred, DeferredCanceledError, ErrorCannotInstantiatePresentOptionalWithEmptyValue, ErrorGetEmptyOptional, ErrorSetEmptyOptional, Lazy, LazyAsync, LazyDictionary, Logger, NEVER, NonExhaustiveSwitchError, Operation, OperationAggregateError, 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, havingMaxBy, havingMinBy, 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, randomDecimalInInterval, randomId, randomIntegerInInterval, randomNumberInInterval, randomPick, randomPicks, 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, DataUpgraderBuilder, Deferred, DeferredCanceledError, ErrorCannotInstantiatePresentOptionalWithEmptyValue, ErrorGetEmptyOptional, ErrorSetEmptyOptional, Lazy, LazyAsync, LazyDictionary, Logger, NEVER, NonExhaustiveSwitchError, Operation, OperationAggregateError, OptionalClz as 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, havingMaxBy, havingMinBy, 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, mapFirstTruthy, mapTruthys, max, maxBy, min, minBy, multiplyBy, noop, not, omitFromJsonObject, or, pad, padLeft, padRight, parseJson, parseTimeInstantBasicComponents, parseTimeInstantComponents, partition, pick, pipedInvoke, pipedInvokeFromArray, pluralize, promiseSequence, randomDecimalInInterval, randomId, randomIntegerInInterval, randomNumberInInterval, randomPick, randomPicks, 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