@zelgadis87/utils-core 5.4.4 → 5.4.6

package/.rollup/index.d.ts

@@ -1020,7 +1020,7 @@ type TCssSelectorDeclarationRulesDictionary = {
     [selector: string]: TCssDeclarationRulesDictionary | TCssSelectorDeclarationRulesDictionary;
 };
 declare function cssDeclarationRulesDictionaryToCss(syleDeclarationRulesForSelectorsProduceable: TProduceable<TCssSelectorDeclarationRulesDictionary>, indent?: number): string;
-declare function transformCssDictionary(dict: TCssSelectorDeclarationRulesDictionary, transformer: (key: TCssGenericDeclarationKey, value: string) => string): TCssSelectorDeclarationRulesDictionary;
+declare function transformCssDictionary(dict: TCssDeclarationRulesDictionary | TCssSelectorDeclarationRulesDictionary, transformer: (key: TCssGenericDeclarationKey, value: string) => string): TCssSelectorDeclarationRulesDictionary;
 type TProduceable<T> = T | TProducer<T>;
 
 /**
@@ -1108,7 +1108,7 @@ type TOperationAggregateFlattenedError<E> = E extends OperationAggregateError<in
  * @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 function combine<T, E = Error>(results: TReadableArray<TOperation<T, E | OperationAggregateError<E>>>): TOperation<T[], OperationAggregateError<TOperationAggregateFlattenedError<E>>>;
 declare const Operation: {
     ok: <const T>(data: T) => {
         readonly success: true;
@@ -1145,6 +1145,26 @@ declare const Operation: {
      * @returns A tuple of [successes, failures]
      */
     partition: <T, E = Error>(results: TReadableArray<TOperation<T, E>>) => [TOperationSuccess<T>[], TOperationFailure<E>[]];
+    /**
+     * 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 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' }
+     */
+    map: <T, U, E>(op: TOperation<T, E>, fn: (data: T) => U) => TOperation<U, E>;
     combine: typeof combine;
 };
 
@@ -1583,10 +1603,170 @@ 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<V2>(2, async (data) => ({
+ *     ...data,
+ *     age: 0,
+ *     $version: 2
+ *   }))
+ *   .addTransition<V3>(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(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, VLatest extends TUpgradable = VLowest, TTransitions extends readonly TTransitionRecord[] = readonly []> {
+    private latestVersion;
+    private transitions;
+    private constructor();
+    /** Starts building a new DataUpgrader from the lowest version. */
+    static start<V1 extends TUpgradable>(): DataUpgraderBuilder<V1, V1, V1, readonly []>;
+    /**
+     * Adds a sequential transition from the current latest version to a new version.
+     * Only the new version type needs to be specified.
+     *
+     * @example
+     * ```typescript
+     * builder.addTransition<V2>(2, async (d) => ({ ...d, extra: 0, $version: 2 }))
+     * ```
+     */
+    addTransition<VNext extends TUpgradable, NewUnion extends TUpgradable = VUnion | VNext, LatestNumber extends number = VLatest["$version"], NextNumber extends number = VNext["$version"], NewTransitions extends readonly TTransitionRecord[] = TAddTransition<TTransitions, LatestNumber, NextNumber>>(toVersion: NextNumber, apply: (data: VLatest) => Promise<VNext> | VNext): DataUpgraderBuilder<VLowest, NewUnion, VNext, 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, VLatest, NewTransitions>;
+    /**
+     * Builds the DataUpgrader with the current latest version.
+     *
+     * @example
+     * ```typescript
+     * const upgrader = builder.build(3);
+     * ```
+     */
+    build(latestVersion: VLatest["$version"]): DataUpgrader<VUnion, Extract<VUnion, {
+        $version: VLatest["$version"];
+    }>>;
+    /** @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;
@@ -1595,6 +1775,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;
@@ -1602,5 +1787,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

@@ -1359,6 +1359,31 @@ const Operation = {
     partition: (results) => {
         return partition(results, r => r.success);
     },
+    /**
+     * 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 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' }
+     */
+    map: (op, fn) => {
+        if (op.success) {
+            return { success: true, data: fn(op.data) };
+        }
+        return op;
+    },
     combine: combine$1,
 };
 
@@ -3689,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)
@@ -3740,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
@@ -3748,6 +3843,142 @@ 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<V2>(2, async (data) => ({
+ *     ...data,
+ *     age: 0,
+ *     $version: 2
+ *   }))
+ *   .addTransition<V3>(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(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 {
+    latestVersion;
+    transitions;
+    constructor(latestVersion, transitions = {}) {
+        this.latestVersion = latestVersion;
+        this.transitions = transitions;
+    }
+    /** Starts building a new DataUpgrader from the lowest version. */
+    static start() {
+        return new DataUpgraderBuilder(1);
+    }
+    /**
+     * Adds a sequential transition from the current latest version to a new version.
+     * Only the new version type needs to be specified.
+     *
+     * @example
+     * ```typescript
+     * builder.addTransition<V2>(2, async (d) => ({ ...d, extra: 0, $version: 2 }))
+     * ```
+     */
+    addTransition(toVersion, apply) {
+        const newTransitions = {
+            ...this.transitions,
+            [toVersion]: {
+                ...(this.transitions[toVersion] ?? {}),
+                [this.latestVersion]: { from: this.latestVersion, to: toVersion, apply: async (d) => apply(d) }
+            }
+        };
+        const builder = new DataUpgraderBuilder(toVersion, 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(this.latestVersion, newTransitions);
+        return builder;
+    }
+    /**
+     * Builds the DataUpgrader with the current latest version.
+     *
+     * @example
+     * ```typescript
+     * const upgrader = builder.build(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