@zelgadis87/utils-core 5.4.5 → 5.4.7

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;
@@ -1369,7 +1369,15 @@ declare class Semaphore {
     constructor(availableSlots: number);
     private _awaitSlot;
     private _releaseSlot;
+    submit<T>(fn: TAsyncProducer<T> | TProducer<T>, cooldown?: TimeDuration): Promise<T>;
+    /** @deprecated[2026.04.01]: Use {@link submit} instead. */
     execute<T>(fn: TAsyncProducer<T> | TProducer<T>, cooldown?: TimeDuration): Promise<T>;
+    /** Called when a task is added to the queue or immediately starts. Override in subclasses. */
+    protected onTaskAdded(): void;
+    /** Called when a task starts executing (acquires a slot). Override in subclasses. */
+    protected onTaskStarted(): void;
+    /** Called when a task completes and releases its slot. Override in subclasses. */
+    protected onTaskCompleted(): void;
     get availableSlots(): number;
     get queueSize(): number;
     get inProgressSize(): number;
@@ -1623,12 +1631,12 @@ type TAddTransition<T extends readonly TTransitionRecord[], From extends number,
  *
  * // 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
@@ -1640,7 +1648,7 @@ type TAddTransition<T extends readonly TTransitionRecord[], From extends number,
  *     email: "",
  *     $version: 3
  *   }))
- *   .build<V3>(3);
+ *   .build(3);
  *
  * // Step 3: Use the upgrader
  * async function loadData(json: string): Promise<V3> {
@@ -1654,21 +1662,22 @@ type TAddTransition<T extends readonly TTransitionRecord[], From extends number,
  * 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 []> {
+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, readonly []>;
+    static start<V1 extends TUpgradable>(): DataUpgraderBuilder<V1, V1, V1, readonly []>;
     /**
-     * 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<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>;
+    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.
@@ -1678,17 +1687,18 @@ declare class DataUpgraderBuilder<VLowest extends TUpgradable, VUnion extends TU
      * 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>;
+    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 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<VLatest extends TUpgradable & VUnion>(latestVersion: VLatest["$version"]): DataUpgrader<VUnion, VLatest>;
+    build(latestVersion: VLatest["$version"]): DataUpgrader<VUnion, Extract<VUnion, {
+        $version: VLatest["$version"];
+    }>>;
     /** @internal */
     getTransitions(): Record<number, Record<number, {
         from: number;

package/.rollup/index.mjs

@@ -151,9 +151,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;
     }
@@ -3881,12 +3899,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
@@ -3898,7 +3916,7 @@ function isUpgradable(obj) {
  *     email: "",
  *     $version: 3
  *   }))
- *   .build<V3>(3);
+ *   .build(3);
  *
  * // Step 3: Use the upgrader
  * async function loadData(json: string): Promise<V3> {
@@ -3913,32 +3931,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;
     }
     /**
@@ -3958,16 +3978,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) {