@zelgadis87/utils-core 5.5.0-beta.1 → 5.5.0-beta.4

package/.rollup/index.cjs

@@ -224,10 +224,11 @@ class Optional {
     getRawValue() {
         return this._value;
     }
+    /** @deprecated[2026.04.07]: Replace with {@link getOrElseThrow} (drop-in replacement with no arguments) */
     get() {
-        return this.getOrElseThrow(() => new ErrorGetEmptyOptional());
+        return this.getOrElseThrow();
     }
-    getOrElseThrow(errorProducer) {
+    getOrElseThrow(errorProducer = () => new ErrorGetEmptyOptional()) {
         if (this.isEmpty())
             throw errorProducer();
         return this._value;
@@ -285,6 +286,12 @@ class Optional {
         }
     }
     orElse = this.orElseReturn.bind(this);
+    orElseReturnNull() {
+        return this.isPresent() ? this.get() : null;
+    }
+    orElseReturnUndefined() {
+        return this.isPresent() ? this.get() : undefined;
+    }
     orElseProduce(newValueProducer) {
         if (this.isPresent()) {
             return this.get();
@@ -1581,6 +1588,9 @@ class Lazy {
             fnEmpty();
         }
     }
+    mapOrElse(onPresent, onEmpty) {
+        return this._initialized ? onPresent(this._value) : onEmpty();
+    }
     empty() {
         this._initialized = false;
     }
@@ -3793,6 +3803,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
@@ -3802,9 +3855,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)
@@ -3944,6 +3997,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