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

package/.rollup/index.d.ts

@@ -102,7 +102,9 @@ declare class Optional<T> implements TOptional<T> {
     private _value;
     private constructor();
     getRawValue(): T | undefined;
+    /** @deprecated[2026.04.07]: Replace with {@link getOrElseThrow} (drop-in replacement with no arguments) */
     get(): T;
+    getOrElseThrow(): T;
     getOrElseThrow(errorProducer: TProducer<Error>): T;
     set(t: T): void;
     protected setNullable(t: T | null | undefined): void | this;
@@ -141,6 +143,7 @@ declare class Optional<T> implements TOptional<T> {
 
 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 +152,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.
      */
@@ -188,7 +192,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;
@@ -207,7 +214,10 @@ type TEmptyOptional<T> = TOptional<T> & {
     orElseProduceNullableAndApply: <R>(newValueProducer: TProducer<R | null | undefined>) => TOptional<R>;
 };
 type TPresentOptional<T> = TOptional<T> & {
+    /** @deprecated[2026.04.07]: Replace with {@link getOrElseThrow} (drop-in replacement with no arguments) */
     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;
@@ -1408,6 +1418,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 +1687,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 +1796,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 +1848,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)

package/.rollup/index.mjs

@@ -222,10 +222,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;
@@ -1585,6 +1586,9 @@ class Lazy {
             fnEmpty();
         }
     }
+    mapOrElse(onPresent, onEmpty) {
+        return this._initialized ? onPresent(this._value) : onEmpty();
+    }
     empty() {
         this._initialized = false;
     }
@@ -3797,6 +3801,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 +3853,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 +3995,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