@zelgadis87/utils-core 5.4.3 → 5.4.5

package/.rollup/index.cjs

@@ -1276,6 +1276,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.
  *
@@ -1295,6 +1296,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 };
@@ -1336,19 +1362,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) {
@@ -3678,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)
@@ -3729,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
@@ -3737,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;