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

package/.rollup/index.cjs

@@ -213,7 +213,7 @@ function throwIfNullOrUndefined(source, errorProducer = () => new Error(`Unexpec
     return ifNullOrUndefined(source, () => { throw errorProducer(); });
 }
 
-class Optional {
+class OptionalClz {
     _present;
     _value;
     constructor(t) {
@@ -225,9 +225,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;
@@ -262,12 +262,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();
@@ -284,7 +278,6 @@ class Optional {
             return newValue;
         }
     }
-    orElse = this.orElseReturn.bind(this);
     orElseReturnNull() {
         return this.isPresent() ? this.get() : null;
     }
@@ -299,7 +292,6 @@ class Optional {
             return newValueProducer();
         }
     }
-    orElseGet = this.orElseProduce.bind(this);
     orElseReturnAndApply(newValue) {
         if (this.isPresent()) {
             return this.get();
@@ -340,18 +332,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();
@@ -363,35 +353,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 {
@@ -840,11 +830,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)
@@ -865,8 +855,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) {
@@ -1445,7 +1435,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);
@@ -1500,8 +1490,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));
 }
@@ -1587,6 +1575,9 @@ class Lazy {
             fnEmpty();
         }
     }
+    mapOrElse(onPresent, onEmpty) {
+        return this._initialized ? onPresent(this._value) : onEmpty();
+    }
     empty() {
         this._initialized = false;
     }
@@ -2504,7 +2495,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() {
@@ -3799,6 +3790,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
@@ -3808,9 +3842,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)
@@ -3950,6 +3984,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
@@ -4074,7 +4115,7 @@ exports.NEVER = NEVER;
 exports.NonExhaustiveSwitchError = NonExhaustiveSwitchError;
 exports.Operation = Operation;
 exports.OperationAggregateError = OperationAggregateError;
-exports.Optional = Optional;
+exports.Optional = OptionalClz;
 exports.PredicateBuilder = PredicateBuilder;
 exports.RandomTimeDuration = RandomTimeDuration;
 exports.RateThrottler = RateThrottler;
@@ -4187,7 +4228,6 @@ exports.jsonCloneDeep = jsonCloneDeep;
 exports.last = last$1;
 exports.listToDict = listToDict;
 exports.mapDefined = mapDefined;
-exports.mapEntries = mapEntries;
 exports.mapFirstTruthy = mapFirstTruthy;
 exports.mapTruthys = mapTruthys;
 exports.max = max;