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

package/.rollup/index.d.ts

@@ -97,98 +97,81 @@ 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;
-    /** @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;
-    clear(): void;
     isEmpty(): this is TEmptyOptional<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;
+    /**
+     * 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<RP = void, RE = void>(callbackIfPresent: TFunction<T, RP>, callbackIfEmpty: TProducer<RE>): RP | RE;
     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;
+    orElseReturnNullable(newValue: T | null | undefined): TOptional<T>;
+    orElseProduceNullable(newValueProducer: TProducer<T | null | undefined>): TOptional<T>;
     orElseThrow(errorProducer: TProducer<Error>): TPresentOptional<T>;
-    throwIfPresent(errorProducer: TFunction<T, Error>): any;
-    mapTo<R>(mapper: TFunction<T, R | null | undefined>): any;
-    flatMapTo<R>(mapper: TFunction<T, TOptional<R>>): any;
+    throwIfPresent(errorProducer: TFunction<T, Error>): TEmptyOptional<T>;
+    mapTo<R>(mapper: TFunction<T, R>): TPresentOptional<R> | TEmptyOptional<R>;
+    flatMapTo<R>(mapper: TFunction<T, TOptional<R>>): TOptional<R> | TEmptyOptional<R>;
     filter(predicate: TPredicate<T>): this | TEmptyOptional<T>;
     static empty<T>(): TEmptyOptional<T>;
+    /**
+     * 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>(t: T): TPresentOptional<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>(t: T | null | undefined): 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;
-    /**
-     * @returns the currently stored value, if any; returns undefined otherwise;
-     */
-    getRawValue(): T | undefined;
     /**
      * @returns the currently stored value, if any; throws {@link ErrorGetEmptyOptional} if no errorProducer is provided, or the error generated by errorProducer otherwise;
      */
     getOrElseThrow(): T;
     getOrElseThrow(errorProducer: TProducer<Error>): T;
-    /**
-     * Places a new value inside this optional. Throws {@link ErrorSetEmptyOptional} if t is null or undefined.
-     */
-    set(t: T): void;
-    /**
-     * Clears the current value from this optional, if any.
-     */
-    clear(): void;
     isEmpty(): boolean;
     isPresent(): boolean;
     ifEmpty(callback: TVoidFunction): void;
     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>;
-    orElseReturnAndApply: (newValue: T) => T;
-    orElseProduceAndApply: (newValueProducer: TProducer<T>) => T;
-    orElseReturnNullableAndApply: (newValue: T | null | undefined) => TOptional<T>;
-    orElseProduceNullableAndApply: (newValueProducer: TProducer<T | null | undefined>) => TOptional<T>;
     orElseThrow: (errorProducer: TProducer<Error>) => TPresentOptional<T>;
-    mapTo<R>(mapper: TFunction<T, R>): TPresentOptional<R> | TEmptyOptional<T>;
-    flatMapTo<R>(mapper: TFunction<T, TOptional<R>>): TOptional<R> | TEmptyOptional<T>;
+    mapTo<R>(mapper: TFunction<T, R>): TOptional<R>;
+    flatMapTo<R>(mapper: TFunction<T, TOptional<R>>): TOptional<R>;
     filter(predicate: TPredicate<T>): TOptional<T>;
 };
 type TEmptyOptional<T> = TOptional<T> & {
@@ -199,8 +182,8 @@ type TEmptyOptional<T> = TOptional<T> & {
     isEmpty(): true;
     isPresent(): false;
     apply<RP = void, RE = void>(callbackIfPresent: TFunction<T, RP>, callbackIfEmpty: TProducer<RE>): RE;
-    mapTo<R>(mapper: TFunction<T, R>): TEmptyOptional<T>;
-    flatMapTo<R>(mapper: TFunction<T, TOptional<R>>): TEmptyOptional<T>;
+    mapTo<R>(mapper: TFunction<T, R>): TEmptyOptional<R>;
+    flatMapTo<R>(mapper: TFunction<T, TOptional<R>>): TEmptyOptional<R>;
     filter(predicate: TPredicate<T>): TEmptyOptional<T>;
     orElseReturn: <R>(newValue: R) => R;
     orElseReturnNull(): null;
@@ -208,13 +191,8 @@ type TEmptyOptional<T> = TOptional<T> & {
     orElseProduce: <R>(newValueProducer: TProducer<R>) => R;
     orElseReturnNullable: <R>(newValue: R | null | undefined) => TOptional<R>;
     orElseProduceNullable: <R>(newValueProducer: TProducer<R | null | undefined>) => TOptional<R>;
-    orElseReturnAndApply: <R>(newValue: R) => R;
-    orElseProduceAndApply: <R>(newValueProducer: TProducer<R>) => R;
-    orElseReturnNullableAndApply: <R>(newValue: R | null | undefined) => TOptional<R>;
-    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;
@@ -229,17 +207,10 @@ type TPresentOptional<T> = TOptional<T> & {
     orElseProduce: (newValueProducer: TProducer<T>) => T;
     orElseReturnNullable: (newValue: T | null | undefined) => TOptional<T>;
     orElseProduceNullable: (newValueProducer: TProducer<T | null | undefined>) => TOptional<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>;
 };
 declare class ErrorGetEmptyOptional extends Error {
     constructor();
 }
-declare class ErrorSetEmptyOptional extends Error {
-    constructor();
-}
 declare class ErrorCannotInstantiatePresentOptionalWithEmptyValue extends Error {
     constructor();
 }
@@ -560,7 +531,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;
@@ -704,16 +675,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?: {
@@ -961,8 +932,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>;
@@ -1071,7 +1040,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;
@@ -1081,7 +1050,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>>;
 /**
@@ -1277,7 +1246,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;
 /**
@@ -1910,5 +1879,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, 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) {
@@ -219,10 +219,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();
     }
@@ -231,22 +227,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;
     }
@@ -261,12 +241,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();
@@ -283,7 +264,6 @@ class Optional {
             return newValue;
         }
     }
-    orElse = this.orElseReturn.bind(this);
     orElseReturnNull() {
         return this.isPresent() ? this.get() : null;
     }
@@ -298,59 +278,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();
@@ -362,35 +301,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 {
@@ -398,11 +350,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.");
@@ -839,11 +786,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)
@@ -864,8 +811,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) {
@@ -1444,7 +1391,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);
@@ -1499,8 +1446,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));
 }
@@ -2506,7 +2451,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() {
@@ -4110,5 +4055,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, 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