@zelgadis87/utils-core 5.5.0-beta.4 → 6.0.0-beta.6

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) {
@@ -221,10 +221,6 @@ class Optional {
         this._value = defined ? t : undefined;
         this._present = defined;
     }
-    getRawValue() {
-        return this._value;
-    }
-    /** @deprecated[2026.04.07]: Replace with {@link getOrElseThrow} (drop-in replacement with no arguments) */
     get() {
         return this.getOrElseThrow();
     }
@@ -233,22 +229,6 @@ class Optional {
             throw errorProducer();
         return this._value;
     }
-    set(t) {
-        if (isNullOrUndefined(t))
-            throw new ErrorSetEmptyOptional();
-        this._value = t;
-        this._present = true;
-    }
-    setNullable(t) {
-        if (isDefined(t)) {
-            return this.set(t);
-        }
-        return this;
-    }
-    clear() {
-        this._value = undefined;
-        this._present = false;
-    }
     isEmpty() {
         return !this._present;
     }
@@ -263,12 +243,13 @@ class Optional {
         if (this.isPresent())
             return callback(this.get());
     }
-    ifPresentThenClear(callback) {
-        if (this.isPresent()) {
-            callback(this.get());
-            this.clear();
-        }
-    }
+    /**
+     * Dispatches to one of two callbacks based on whether a value is present.
+     * Equivalent to `fold` (fp-ts), `match` (effect/Scala), and `ifPresentOrElse` (Java, but with return values).
+     * @param callbackIfPresent - called with the current value when present; its return value is forwarded
+     * @param callbackIfEmpty - called when empty; its return value is forwarded
+     * @returns the return value of whichever callback was invoked
+     */
     apply(callbackIfPresent, callbackIfEmpty) {
         if (this.isEmpty()) {
             return callbackIfEmpty();
@@ -285,7 +266,6 @@ class Optional {
             return newValue;
         }
     }
-    orElse = this.orElseReturn.bind(this);
     orElseReturnNull() {
         return this.isPresent() ? this.get() : null;
     }
@@ -300,59 +280,18 @@ class Optional {
             return newValueProducer();
         }
     }
-    orElseGet = this.orElseProduce.bind(this);
-    orElseReturnAndApply(newValue) {
-        if (this.isPresent()) {
-            return this.get();
-        }
-        else {
-            this.set(newValue);
-            return newValue;
-        }
-    }
-    orElseProduceAndApply(newValueProducer) {
-        if (this.isPresent()) {
-            return this.get();
-        }
-        else {
-            const newValue = newValueProducer();
-            this.set(newValue);
-            return newValue;
-        }
-    }
-    orElseReturnNullableAndApply(newValue) {
-        if (this.isPresent()) {
-            return this;
-        }
-        else {
-            this.setNullable(newValue);
-            return this;
-        }
-    }
-    orElseProduceNullableAndApply(newValueProducer) {
-        if (this.isPresent()) {
-            return this;
-        }
-        else {
-            const newValue = newValueProducer();
-            this.setNullable(newValue);
-            return this;
-        }
-    }
     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();
@@ -364,35 +303,48 @@ class Optional {
         throw errorProducer(this.get());
     }
     mapTo(mapper) {
-        return this.apply(() => Optional.ofNullable(mapper(this.get())), () => Optional.empty());
+        return this.apply(() => OptionalClz.of(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);
     }
+    /**
+     * Creates a present optional wrapping a non-null value.
+     * Throws {@link ErrorCannotInstantiatePresentOptionalWithEmptyValue} if `t` is null or undefined.
+     *
+     * ⚠️ Do NOT use this method when the value may be null/undefined.
+     * Anti-pattern: `value ? Optional.of(value!) : Optional.empty()` → use {@link ofNullable} instead.
+     * Only use this when you are certain the value is defined (e.g. a literal, a validated input, or a narrowed type).
+     */
     static of(t) {
         if (isNullOrUndefined(t))
             throw new ErrorCannotInstantiatePresentOptionalWithEmptyValue();
-        return new Optional(t);
+        return new OptionalClz(t);
     }
+    /**
+     * Creates an optional that is present when `t` is defined, or empty when null/undefined.
+     * This is the idiomatic replacement for the anti-pattern:
+     * `value ? Optional.of(value!) : Optional.empty()` → `Optional.ofNullable(value)`
+     */
     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 {
@@ -400,11 +352,6 @@ class ErrorGetEmptyOptional extends Error {
         super("Cannot retrieve a value from an empty Optional.");
     }
 }
-class ErrorSetEmptyOptional extends Error {
-    constructor() {
-        super("Cannot set a null or undefined value.");
-    }
-}
 class ErrorCannotInstantiatePresentOptionalWithEmptyValue extends Error {
     constructor() {
         super("Cannot initialize a PresentOptional with a null or undefined value.");
@@ -841,11 +788,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)
@@ -866,8 +813,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) {
@@ -1446,7 +1393,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);
@@ -1501,8 +1448,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));
 }
@@ -2508,7 +2453,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() {
@@ -4119,7 +4064,6 @@ exports.Deferred = Deferred;
 exports.DeferredCanceledError = DeferredCanceledError;
 exports.ErrorCannotInstantiatePresentOptionalWithEmptyValue = ErrorCannotInstantiatePresentOptionalWithEmptyValue;
 exports.ErrorGetEmptyOptional = ErrorGetEmptyOptional;
-exports.ErrorSetEmptyOptional = ErrorSetEmptyOptional;
 exports.Lazy = Lazy;
 exports.LazyAsync = LazyAsync;
 exports.LazyDictionary = LazyDictionary;
@@ -4128,7 +4072,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;
@@ -4241,7 +4185,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;