@zelgadis87/utils-core 5.4.4 → 5.4.5

package/.rollup/index.cjs

@@ -1361,6 +1361,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,
 };
 
@@ -3691,11 +3716,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)
@@ -3742,6 +3826,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
@@ -3750,9 +3845,145 @@ 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;
+    }
+}
 
 exports.Cached = Cached;
 exports.DataUpgrader = DataUpgrader;
+exports.DataUpgraderBuilder = DataUpgraderBuilder;
 exports.Deferred = Deferred;
 exports.DeferredCanceledError = DeferredCanceledError;
 exports.ErrorCannotInstantiatePresentOptionalWithEmptyValue = ErrorCannotInstantiatePresentOptionalWithEmptyValue;