@zelgadis87/utils-core 5.4.3 → 5.4.5

package/.rollup/index.d.ts

@@ -1069,6 +1069,7 @@ type TValidation<T, E = Error> = {
  */
 type TAsyncValidation<T, E = Error> = Promise<TValidation<T, E>>;
 /**
+
  * An error class that aggregates multiple errors from a combined operation.
  * Used by `Operation.combine` to represent failures from multiple operations.
  *
@@ -1082,6 +1083,32 @@ declare class OperationAggregateError<E = Error> extends Error {
      */
     get count(): number;
 }
+/**
+ * Recursively extracts the innermost error type from potentially nested OperationAggregateError.
+ * This enables `Operation.combine` to return accurate error types after flattening.
+ *
+ * @template E - The error type to flatten
+ * @example
+ *   TOperationAggregateFlattenedError<string>                            // string
+ *   TOperationAggregateFlattenedError<OperationAggregateError<string>>   // string
+ *   TOperationAggregateFlattenedError<Error | OperationAggregateError<string>>  // Error | string
+ */
+type TOperationAggregateFlattenedError<E> = E extends OperationAggregateError<infer Inner> ? TOperationAggregateFlattenedError<Inner> : E;
+/**
+ * Combines multiple operation results into a single result.
+ * - If all operations succeed, returns success with an array of all data values.
+ * - If any operation fails, returns failure with an `OperationAggregateError` containing all errors.
+ *
+ * When combining operations whose error type is already `OperationAggregateError<E>`,
+ * the errors are automatically flattened to avoid nesting (e.g., combining results from
+ * previous `combine` calls).
+ *
+ * @template T - The success data type of individual operations
+ * @template E - The error type of individual operations (defaults to Error)
+ * @param results - Array of operation results to combine
+ * @returns A single operation with either all data or all aggregated errors (flattened)
+ */
+declare function combine<T, E = Error>(results: TReadableArray<TOperation<T, E>>): TOperation<T[], OperationAggregateError<TOperationAggregateFlattenedError<E>>>;
 declare const Operation: {
     ok: <const T>(data: T) => {
         readonly success: true;
@@ -1119,16 +1146,26 @@ declare const Operation: {
      */
     partition: <T, E = Error>(results: TReadableArray<TOperation<T, E>>) => [TOperationSuccess<T>[], TOperationFailure<E>[]];
     /**
-     * Combines multiple operation results into a single result.
-     * - If all operations succeed, returns success with an array of all data values.
-     * - If any operation fails, returns failure with an `OperationAggregateError` containing all errors.
+     * Transforms the success value of an operation using the provided function.
+     * If the operation is a failure, it is returned unchanged (same reference).
+     * The transformation function is never called on a failure.
      *
-     * @template T - The success data type of individual operations
-     * @template E - The error type of individual operations (defaults to Error)
-     * @param results - Array of operation results to combine
-     * @returns A single operation with either all data or all aggregated errors
+     * @template T - The input success data type
+     * @template U - The output success data type
+     * @template E - The error type (preserved exactly)
+     * @param op - The operation result to transform
+     * @param fn - Pure function applied to the success value
+     * @returns A new success with the transformed value, or the original failure
+     *
+     * @example
+     * Operation.map(Operation.ok(1), x => x * 2);
+     * // => { success: true, data: 2 }
+     *
+     * Operation.map(Operation.ko('err'), x => x * 2);
+     * // => { success: false, error: 'err' }
      */
-    combine: <T, E = Error>(results: TReadableArray<TOperation<T, E>>) => TOperation<T[], OperationAggregateError<E>>;
+    map: <T, U, E>(op: TOperation<T, E>, fn: (data: T) => U) => TOperation<U, E>;
+    combine: typeof combine;
 };
 
 declare function withTryCatch<R>(fn: TFunction<void, R>, errMapFn?: TTransformer<Error, Error>): TOperationTuple<R, Error>;
@@ -1566,10 +1603,168 @@ type TPossibleVersion<XStar extends TUpgradable> = XStar["$version"] & number;
 type TPossibleFromVersion<XStar extends TUpgradable, XLatest extends XStar> = Exclude<TPossibleVersion<XStar>, XLatest["$version"]>;
 type TUpgradeFunction<XStar extends TUpgradable, XFrom extends XStar, XTo extends XStar> = TFunction<Readonly<TVersionMap<XStar>[XFrom["$version"]]>, TPromisable<TVersionMap<XStar>[XTo["$version"]]>>;
 
+type TTransitionRecord = readonly [from: number, to: number];
+type TContainsTransition<T extends readonly TTransitionRecord[], From extends number, To extends number> = T extends readonly [infer First, ...infer Rest] ? First extends readonly [From, To] ? true : TContainsTransition<Rest & readonly TTransitionRecord[], From, To> : false;
+type TAddTransition<T extends readonly TTransitionRecord[], From extends number, To extends number> = TContainsTransition<T, From, To> extends true ? never : readonly [...T, readonly [From, To]];
+/**
+ * Builder for creating type-safe DataUpgrader instances with compile-time safety.
+ *
+ * Prevents at compile-time:
+ * - Missing upgrade paths (incomplete version coverage)
+ * - Duplicate transition definitions
+ * - Backward transitions (e.g., version 2 → 1)
+ *
+ * @example
+ * ```typescript
+ * // Step 1: Define all historical versions with $version discriminator
+ * type V1 = { name: string; $version: 1 };
+ * type V2 = { name: string; age: number; $version: 2 };
+ * type V3 = { name: string; age: number; email: string; $version: 3 };
+ *
+ * // Step 2: Build the upgrader with type-safe transitions
+ * const upgrader = DataUpgraderBuilder.start<V1>()
+ *   .addTransition<V1, V2>(1, 2, async (data) => ({
+ *     ...data,
+ *     age: 0,
+ *     $version: 2
+ *   }))
+ *   .addTransition<V2, V3>(2, 3, async (data) => ({
+ *     ...data,
+ *     email: "",
+ *     $version: 3
+ *   }))
+ *   .addShortcut<V1, V3>(1, 3, async (data) => ({
+ *     // Optional: Direct path for efficiency
+ *     ...data,
+ *     age: 0,
+ *     email: "",
+ *     $version: 3
+ *   }))
+ *   .build<V3>(3);
+ *
+ * // Step 3: Use the upgrader
+ * async function loadData(json: string): Promise<V3> {
+ *   const data = JSON.parse(json);
+ *   return await upgrader.upgrade(data);
+ * }
+ *
+ * // Works with any version:
+ * const v1 = await loadData('{"name":"Alice","$version":1}'); // → V3
+ * const v2 = await loadData('{"name":"Bob","age":25,"$version":2}'); // → V3
+ * const v3 = await loadData('{"name":"Carol","age":30,"email":"c@example.com","$version":3}'); // → V3
+ * ```
+ */
+declare class DataUpgraderBuilder<VLowest extends TUpgradable, VUnion extends TUpgradable = VLowest, TTransitions extends readonly TTransitionRecord[] = readonly []> {
+    private transitions;
+    private constructor();
+    /** Starts building a new DataUpgrader from the lowest version. */
+    static start<V1 extends TUpgradable>(): DataUpgraderBuilder<V1, V1, readonly []>;
+    /**
+     * Adds a sequential transition from the current version to the next version.
+     * Prevents backward transitions and duplicates at compile-time.
+     *
+     * @example
+     * ```typescript
+     * builder.addTransition<V1, V2>(1, 2, async (d) => ({ ...d, extra: 0, $version: 2 }))
+     * ```
+     */
+    addTransition<VNext extends TUpgradable, VCurrent extends TUpgradable & VUnion, NewUnion extends TUpgradable = VUnion | VNext, Current extends number = VCurrent["$version"], Next extends number = VNext["$version"], NewTransitions extends readonly TTransitionRecord[] = TAddTransition<TTransitions, Current, Next>>(fromVersion: Current, toVersion: Next, apply: (data: VCurrent) => Promise<VNext> | VNext): DataUpgraderBuilder<VLowest, NewUnion, NewTransitions>;
+    /**
+     * Adds a shortcut transition between arbitrary versions.
+     * Both versions must already be in the accumulated union type.
+     *
+     * @example
+     * ```typescript
+     * builder.addShortcut<V1, V3>(1, 3, async (d) => ({ ...d, extra: 0, flag: false, $version: 3 }))
+     * ```
+     */
+    addShortcut<VFrom extends TUpgradable & VUnion, VTo extends TUpgradable & VUnion, From extends number = VFrom["$version"], To extends number = VTo["$version"], NewTransitions extends readonly TTransitionRecord[] = TAddTransition<TTransitions, From, To>>(fromVersion: From, toVersion: To, apply: (data: VFrom) => Promise<VTo> | VTo): DataUpgraderBuilder<VLowest, VUnion, NewTransitions>;
+    /**
+     * Builds the DataUpgrader with the specified latest version.
+     * The latest version must be in the accumulated union type.
+     *
+     * @example
+     * ```typescript
+     * const upgrader = builder.build<V3>(3);
+     * ```
+     */
+    build<VLatest extends TUpgradable & VUnion>(latestVersion: VLatest["$version"]): DataUpgrader<VUnion, VLatest>;
+    /** @internal */
+    getTransitions(): Record<number, Record<number, {
+        from: number;
+        to: number;
+        apply: (data: unknown) => Promise<unknown>;
+    }>>;
+}
+
 declare const VERSION_FIELD = "$version";
 interface IDataUpgrader<XStar extends TUpgradable, XLatest extends XStar> {
+    /**
+     * Upgrades data from any version to the latest version.
+     *
+     * @param data - Data object from any version (must contain valid $version field)
+     * @returns Promise resolving to data at the latest version
+     */
     upgrade(data: XStar): Promise<XLatest>;
 }
+/**
+ * Versioned data migration system for transparently upgrading serialized data to the latest version.
+ *
+ * DataUpgrader manages the migration of data structures across multiple versions, automatically
+ * finding the shortest upgrade path and applying transformations. This is particularly useful for
+ * handling persisted data that may be in any historical format.
+ *
+ * **Key Use Case:** Reading serialized data of unknown version and migrating it transparently.
+ *
+ * @example
+ * ```typescript
+ * // Step 1: Define all historical versions with $version discriminator
+ * type TSerializedData_V1 = { name: string; $version: 1 };
+ * 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
+ * type TSerializedData_Vstar = TSerializedData_V1 | TSerializedData_V2 | TSerializedData_V3;
+ * type TSerializedData = TSerializedData_V3;
+ *
+ * // Step 3: Create upgrader with transition functions
+ * const upgrader = DataUpgrader.create<TSerializedData_Vstar, TSerializedData>(3)
+ *   .addTransition(1, 2, async (data: TSerializedData_V1) => ({
+ *     ...data,
+ *     age: 0,
+ *     $version: 2
+ *   }))
+ *   .addTransition(2, 3, async (data: TSerializedData_V2) => ({
+ *     ...data,
+ *     email: "",
+ *     $version: 3
+ *   }))
+ *   .addTransition(1, 3, async (data: TSerializedData_V1) => ({
+ *     // Optional: Direct path for efficiency
+ *     ...data,
+ *     age: 0,
+ *     email: "",
+ *     $version: 3
+ *   }));
+ *
+ * // Step 4: Use in data loading - handles any version transparently
+ * async function loadData(json: string): Promise<TSerializedData> {
+ *   const data = parseJson<TSerializedData_Vstar>(json);
+ *   return await upgrader.upgrade(data);
+ * }
+ *
+ * // Works with any version:
+ * const v1 = await loadData('{"name":"Alice","$version":1}'); // → V3
+ * const v2 = await loadData('{"name":"Bob","age":25,"$version":2}'); // → V3
+ * const v3 = await loadData('{"name":"Carol","age":30,"email":"c@example.com","$version":3}'); // → V3
+ * ```
+ *
+ * @typeParam X - Union type of all possible data versions (must extend TUpgradable)
+ * @typeParam XLatest - The latest version type (must extend X)
+ *
+ * @see {@link isUpgradable | Type guard for checking if data is upgradable}
+ * @see {@link DataUpgrader.Errors | Error types for upgrade failures}
+ */
 declare class DataUpgrader<X extends TUpgradable, XLatest extends X> implements IDataUpgrader<X, XLatest> {
     private latestVersion;
     private transitions;
@@ -1578,6 +1773,11 @@ declare class DataUpgrader<X extends TUpgradable, XLatest extends X> implements
     upgrade(data: X): Promise<XLatest>;
     isLatestVersion(data: X): data is XLatest;
     static create<X extends TUpgradable, XLatestVersion extends X>(latest: XLatestVersion[typeof VERSION_FIELD]): DataUpgrader<X, XLatestVersion>;
+    /**
+     * Creates a DataUpgrader from a DataUpgraderBuilder instance.
+     * @internal
+     */
+    static fromBuilder<X extends TUpgradable, XLatestVersion extends X>(builder: DataUpgraderBuilder<any, X, any>, latestVersion: XLatestVersion[typeof VERSION_FIELD]): DataUpgrader<X, XLatestVersion>;
     static Errors: {
         readonly EmptyUpgrade: typeof EmptyUpgradeError;
         readonly UnavailableUpgrade: typeof UnavailableUpgradeError;
@@ -1585,5 +1785,5 @@ declare class DataUpgrader<X extends TUpgradable, XLatest extends X> implements
 }
 declare function isUpgradable(obj: TJsonSerializable): obj is TUpgradable;
 
-export { Cached, DataUpgrader, 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, 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 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

@@ -1274,6 +1274,7 @@ function wrapWithString(str, start, end = start) {
 }
 
 /**
+
  * An error class that aggregates multiple errors from a combined operation.
  * Used by `Operation.combine` to represent failures from multiple operations.
  *
@@ -1293,6 +1294,31 @@ class OperationAggregateError extends Error {
         return this.errors.length;
     }
 }
+/**
+ * Combines multiple operation results into a single result.
+ * - If all operations succeed, returns success with an array of all data values.
+ * - If any operation fails, returns failure with an `OperationAggregateError` containing all errors.
+ *
+ * When combining operations whose error type is already `OperationAggregateError<E>`,
+ * the errors are automatically flattened to avoid nesting (e.g., combining results from
+ * previous `combine` calls).
+ *
+ * @template T - The success data type of individual operations
+ * @template E - The error type of individual operations (defaults to Error)
+ * @param results - Array of operation results to combine
+ * @returns A single operation with either all data or all aggregated errors (flattened)
+ */
+function combine$1(results) {
+    const [successes, failures] = partition(results, r => r.success);
+    if (failures.length === 0) {
+        return { success: true, data: successes.map(r => r.data) };
+    }
+    const allErrors = failures.flatMap(r => {
+        const error = r.error;
+        return error instanceof OperationAggregateError ? error.errors : [error];
+    });
+    return { success: false, error: new OperationAggregateError(allErrors) };
+}
 const Operation = {
     ok: (data) => {
         return { success: true, data };
@@ -1334,19 +1360,31 @@ const Operation = {
         return partition(results, r => r.success);
     },
     /**
-     * Combines multiple operation results into a single result.
-     * - If all operations succeed, returns success with an array of all data values.
-     * - If any operation fails, returns failure with an `OperationAggregateError` containing all errors.
+     * Transforms the success value of an operation using the provided function.
+     * If the operation is a failure, it is returned unchanged (same reference).
+     * The transformation function is never called on a failure.
      *
-     * @template T - The success data type of individual operations
-     * @template E - The error type of individual operations (defaults to Error)
-     * @param results - Array of operation results to combine
-     * @returns A single operation with either all data or all aggregated errors
+     * @template T - The input success data type
+     * @template U - The output success data type
+     * @template E - The error type (preserved exactly)
+     * @param op - The operation result to transform
+     * @param fn - Pure function applied to the success value
+     * @returns A new success with the transformed value, or the original failure
+     *
+     * @example
+     * Operation.map(Operation.ok(1), x => x * 2);
+     * // => { success: true, data: 2 }
+     *
+     * Operation.map(Operation.ko('err'), x => x * 2);
+     * // => { success: false, error: 'err' }
      */
-    combine: (results) => {
-        const [successes, failures] = Operation.partition(results);
-        return failures.length === 0 ? Operation.ok(successes.map(r => r.data)) : Operation.ko(new OperationAggregateError(failures.map(r => r.error)));
+    map: (op, fn) => {
+        if (op.success) {
+            return { success: true, data: fn(op.data) };
+        }
+        return op;
     },
+    combine: combine$1,
 };
 
 function asPromise(promisable) {
@@ -3676,11 +3714,70 @@ function printTransitions(transitions) {
 }
 
 const VERSION_FIELD = "$version";
+/**
+ * Versioned data migration system for transparently upgrading serialized data to the latest version.
+ *
+ * DataUpgrader manages the migration of data structures across multiple versions, automatically
+ * finding the shortest upgrade path and applying transformations. This is particularly useful for
+ * handling persisted data that may be in any historical format.
+ *
+ * **Key Use Case:** Reading serialized data of unknown version and migrating it transparently.
+ *
+ * @example
+ * ```typescript
+ * // Step 1: Define all historical versions with $version discriminator
+ * type TSerializedData_V1 = { name: string; $version: 1 };
+ * 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
+ * type TSerializedData_Vstar = TSerializedData_V1 | TSerializedData_V2 | TSerializedData_V3;
+ * type TSerializedData = TSerializedData_V3;
+ *
+ * // Step 3: Create upgrader with transition functions
+ * const upgrader = DataUpgrader.create<TSerializedData_Vstar, TSerializedData>(3)
+ *   .addTransition(1, 2, async (data: TSerializedData_V1) => ({
+ *     ...data,
+ *     age: 0,
+ *     $version: 2
+ *   }))
+ *   .addTransition(2, 3, async (data: TSerializedData_V2) => ({
+ *     ...data,
+ *     email: "",
+ *     $version: 3
+ *   }))
+ *   .addTransition(1, 3, async (data: TSerializedData_V1) => ({
+ *     // Optional: Direct path for efficiency
+ *     ...data,
+ *     age: 0,
+ *     email: "",
+ *     $version: 3
+ *   }));
+ *
+ * // Step 4: Use in data loading - handles any version transparently
+ * async function loadData(json: string): Promise<TSerializedData> {
+ *   const data = parseJson<TSerializedData_Vstar>(json);
+ *   return await upgrader.upgrade(data);
+ * }
+ *
+ * // Works with any version:
+ * const v1 = await loadData('{"name":"Alice","$version":1}'); // → V3
+ * const v2 = await loadData('{"name":"Bob","age":25,"$version":2}'); // → V3
+ * const v3 = await loadData('{"name":"Carol","age":30,"email":"c@example.com","$version":3}'); // → V3
+ * ```
+ *
+ * @typeParam X - Union type of all possible data versions (must extend TUpgradable)
+ * @typeParam XLatest - The latest version type (must extend X)
+ *
+ * @see {@link isUpgradable | Type guard for checking if data is upgradable}
+ * @see {@link DataUpgrader.Errors | Error types for upgrade failures}
+ */
 class DataUpgrader {
     latestVersion;
-    transitions = {};
-    constructor(latestVersion) {
+    transitions;
+    constructor(latestVersion, transitions = {}) {
         this.latestVersion = latestVersion;
+        this.transitions = transitions;
     }
     addTransition(from, to, apply) {
         if (from === undefined || from < 0)
@@ -3727,6 +3824,17 @@ class DataUpgrader {
     static create(latest) {
         return new DataUpgrader(latest);
     }
+    /**
+     * Creates a DataUpgrader from a DataUpgraderBuilder instance.
+     * @internal
+     */
+    static fromBuilder(builder, latestVersion) {
+        // Extract transitions from builder and convert to strongly-typed TTransitionMatrix
+        // This type assertion is safe because the builder has validated all transitions
+        // at compile-time via its type parameters
+        const transitions = builder.getTransitions();
+        return new DataUpgrader(latestVersion, transitions);
+    }
     static Errors = {
         EmptyUpgrade: EmptyUpgradeError,
         UnavailableUpgrade: UnavailableUpgradeError
@@ -3735,6 +3843,141 @@ class DataUpgrader {
 function isUpgradable(obj) {
     return isDefined(obj) && typeof obj === "object" && VERSION_FIELD in obj && isNumber(obj.$version) && isPositiveNumber(obj.$version);
 }
+/**
+ * The current system is unable to catch the following problems at compile-time:
+ * type A_V1 = { a: number, $version: 1 }
+ * type A_V2 = { a: number, b: number, $version: 2 }
+ * type A_V3 = { a: number, b: number, c: string, $version: 3 }
+ * type A_Vstar = A_V1 | A_V2 | A_V3;
+ * type A = A_V3;
+ *
+ * const DU1 = DataUpgrader.create<A_Vstar, A>( 3 );
+ *
+ * const DU2 = DataUpgrader.create<A_Vstar, A>( 3 )
+ * 	.addTransition( 1, 3, x => ( { ...x, b: 2, c: "foo", $version: 3 } ) )
+ * 	.addTransition( 1, 3, x => ( { ...x, b: 3, c: "bar", $version: 3 } ) )
+ * 	;
+ *
+ * const DU3 = DataUpgrader.create<A_Vstar, A>( 3 )
+ * 	.addTransition( 1, 2, x => ( { ...x, b: 2, $version: 2 } ) )
+ * 	.addTransition( 2, 1, x => ( { ...x, $version: 1 } ) )
+ * 	;
+ */
+
+/**
+ * Builder for creating type-safe DataUpgrader instances with compile-time safety.
+ *
+ * Prevents at compile-time:
+ * - Missing upgrade paths (incomplete version coverage)
+ * - Duplicate transition definitions
+ * - Backward transitions (e.g., version 2 → 1)
+ *
+ * @example
+ * ```typescript
+ * // Step 1: Define all historical versions with $version discriminator
+ * type V1 = { name: string; $version: 1 };
+ * type V2 = { name: string; age: number; $version: 2 };
+ * type V3 = { name: string; age: number; email: string; $version: 3 };
+ *
+ * // Step 2: Build the upgrader with type-safe transitions
+ * const upgrader = DataUpgraderBuilder.start<V1>()
+ *   .addTransition<V1, V2>(1, 2, async (data) => ({
+ *     ...data,
+ *     age: 0,
+ *     $version: 2
+ *   }))
+ *   .addTransition<V2, V3>(2, 3, async (data) => ({
+ *     ...data,
+ *     email: "",
+ *     $version: 3
+ *   }))
+ *   .addShortcut<V1, V3>(1, 3, async (data) => ({
+ *     // Optional: Direct path for efficiency
+ *     ...data,
+ *     age: 0,
+ *     email: "",
+ *     $version: 3
+ *   }))
+ *   .build<V3>(3);
+ *
+ * // Step 3: Use the upgrader
+ * async function loadData(json: string): Promise<V3> {
+ *   const data = JSON.parse(json);
+ *   return await upgrader.upgrade(data);
+ * }
+ *
+ * // Works with any version:
+ * const v1 = await loadData('{"name":"Alice","$version":1}'); // → V3
+ * const v2 = await loadData('{"name":"Bob","age":25,"$version":2}'); // → V3
+ * const v3 = await loadData('{"name":"Carol","age":30,"email":"c@example.com","$version":3}'); // → V3
+ * ```
+ */
+class DataUpgraderBuilder {
+    transitions;
+    constructor(transitions = {}) {
+        this.transitions = transitions;
+    }
+    /** Starts building a new DataUpgrader from the lowest version. */
+    static start() {
+        return new DataUpgraderBuilder();
+    }
+    /**
+     * Adds a sequential transition from the current version to the next version.
+     * Prevents backward transitions and duplicates at compile-time.
+     *
+     * @example
+     * ```typescript
+     * builder.addTransition<V1, V2>(1, 2, async (d) => ({ ...d, extra: 0, $version: 2 }))
+     * ```
+     */
+    addTransition(fromVersion, toVersion, apply) {
+        const newTransitions = {
+            ...this.transitions,
+            [toVersion]: {
+                ...(this.transitions[toVersion] ?? {}),
+                [fromVersion]: { from: fromVersion, to: toVersion, apply: async (d) => apply(d) }
+            }
+        };
+        const builder = new DataUpgraderBuilder(newTransitions);
+        return builder;
+    }
+    /**
+     * Adds a shortcut transition between arbitrary versions.
+     * Both versions must already be in the accumulated union type.
+     *
+     * @example
+     * ```typescript
+     * builder.addShortcut<V1, V3>(1, 3, async (d) => ({ ...d, extra: 0, flag: false, $version: 3 }))
+     * ```
+     */
+    addShortcut(fromVersion, toVersion, apply) {
+        const newTransitions = {
+            ...this.transitions,
+            [toVersion]: {
+                ...(this.transitions[toVersion] ?? {}),
+                [fromVersion]: { from: fromVersion, to: toVersion, apply: async (d) => apply(d) }
+            }
+        };
+        const builder = new DataUpgraderBuilder(newTransitions);
+        return builder;
+    }
+    /**
+     * Builds the DataUpgrader with the specified latest version.
+     * The latest version must be in the accumulated union type.
+     *
+     * @example
+     * ```typescript
+     * const upgrader = builder.build<V3>(3);
+     * ```
+     */
+    build(latestVersion) {
+        return DataUpgrader.fromBuilder(this, latestVersion);
+    }
+    /** @internal */
+    getTransitions() {
+        return this.transitions;
+    }
+}
 
-export { Cached, DataUpgrader, 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, 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 };
 //# sourceMappingURL=index.mjs.map