@zelgadis87/utils-core 5.4.5 → 5.4.7

package/.rollup/index.cjs

@@ -153,9 +153,27 @@ class Semaphore {
             this._inProgress -= 1;
         }
     }
-    async execute(fn, cooldown = TimeDuration.ZERO) {
-        return this._awaitSlot().then(fn).finally(() => { void cooldown.delay(() => this._releaseSlot()); });
-    }
+    async submit(fn, cooldown = TimeDuration.ZERO) {
+        this.onTaskAdded();
+        await this._awaitSlot();
+        this.onTaskStarted();
+        const [result, error] = await withTryCatchAsync(async () => fn());
+        this.onTaskCompleted();
+        void cooldown.delay(() => this._releaseSlot());
+        if (error)
+            throw error;
+        return result;
+    }
+    /** @deprecated[2026.04.01]: Use {@link submit} instead. */
+    execute(fn, cooldown = TimeDuration.ZERO) {
+        return this.submit(fn, cooldown);
+    }
+    /** Called when a task is added to the queue or immediately starts. Override in subclasses. */
+    onTaskAdded() { }
+    /** Called when a task starts executing (acquires a slot). Override in subclasses. */
+    onTaskStarted() { }
+    /** Called when a task completes and releases its slot. Override in subclasses. */
+    onTaskCompleted() { }
     get availableSlots() {
         return this._availableSlots;
     }
@@ -3883,12 +3901,12 @@ function isUpgradable(obj) {
  *
  * // Step 2: Build the upgrader with type-safe transitions
  * const upgrader = DataUpgraderBuilder.start<V1>()
- *   .addTransition<V1, V2>(1, 2, async (data) => ({
+ *   .addTransition<V2>(2, async (data) => ({
  *     ...data,
  *     age: 0,
  *     $version: 2
  *   }))
- *   .addTransition<V2, V3>(2, 3, async (data) => ({
+ *   .addTransition<V3>(3, async (data) => ({
  *     ...data,
  *     email: "",
  *     $version: 3
@@ -3900,7 +3918,7 @@ function isUpgradable(obj) {
  *     email: "",
  *     $version: 3
  *   }))
- *   .build<V3>(3);
+ *   .build(3);
  *
  * // Step 3: Use the upgrader
  * async function loadData(json: string): Promise<V3> {
@@ -3915,32 +3933,34 @@ function isUpgradable(obj) {
  * ```
  */
 class DataUpgraderBuilder {
+    latestVersion;
     transitions;
-    constructor(transitions = {}) {
+    constructor(latestVersion, transitions = {}) {
+        this.latestVersion = latestVersion;
         this.transitions = transitions;
     }
     /** Starts building a new DataUpgrader from the lowest version. */
     static start() {
-        return new DataUpgraderBuilder();
+        return new DataUpgraderBuilder(1);
     }
     /**
-     * Adds a sequential transition from the current version to the next version.
-     * Prevents backward transitions and duplicates at compile-time.
+     * 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<V1, V2>(1, 2, async (d) => ({ ...d, extra: 0, $version: 2 }))
+     * builder.addTransition<V2>(2, async (d) => ({ ...d, extra: 0, $version: 2 }))
      * ```
      */
-    addTransition(fromVersion, toVersion, apply) {
+    addTransition(toVersion, apply) {
         const newTransitions = {
             ...this.transitions,
             [toVersion]: {
                 ...(this.transitions[toVersion] ?? {}),
-                [fromVersion]: { from: fromVersion, to: toVersion, apply: async (d) => apply(d) }
+                [this.latestVersion]: { from: this.latestVersion, to: toVersion, apply: async (d) => apply(d) }
             }
         };
-        const builder = new DataUpgraderBuilder(newTransitions);
+        const builder = new DataUpgraderBuilder(toVersion, newTransitions);
         return builder;
     }
     /**
@@ -3960,16 +3980,15 @@ class DataUpgraderBuilder {
                 [fromVersion]: { from: fromVersion, to: toVersion, apply: async (d) => apply(d) }
             }
         };
-        const builder = new DataUpgraderBuilder(newTransitions);
+        const builder = new DataUpgraderBuilder(this.latestVersion, newTransitions);
         return builder;
     }
     /**
-     * Builds the DataUpgrader with the specified latest version.
-     * The latest version must be in the accumulated union type.
+     * Builds the DataUpgrader with the current latest version.
      *
      * @example
      * ```typescript
-     * const upgrader = builder.build<V3>(3);
+     * const upgrader = builder.build(3);
      * ```
      */
     build(latestVersion) {