@zelgadis87/utils-core 5.4.6 → 5.5.0-beta.0

package/.rollup/index.d.ts

@@ -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;
@@ -1423,13 +1431,60 @@ declare class LazyAsync<T> {
     static of<T>(generator: () => Promise<T>): LazyAsync<T>;
 }
 
+/**
+ * A dictionary that lazily initializes values on first access.
+ *
+ * Values are generated by a user-provided factory function and cached for subsequent lookups.
+ * Each key is initialized at most once — repeated calls to `getOrCreate` return the cached value
+ * without invoking the generator again.
+ *
+ * @typeParam K - Key type (string, number, or symbol).
+ * @typeParam T - The type of values produced by the generator.
+ *
+ * @example
+ * ```ts
+ * const dict = LazyDictionary.of( ( key: string ) => key.toUpperCase() );
+ * dict.getOrCreate( 'hello' ); // → 'HELLO'
+ * dict.getOrCreate( 'hello' ); // → 'HELLO' (cached, generator not called again)
+ * dict.hasKey( 'hello' );      // → true
+ * dict.getEntries();           // → [ [ 'hello', 'HELLO' ] ]
+ * ```
+ */
 declare class LazyDictionary<K extends string | number | symbol, T> {
     private readonly _generator;
     private readonly _dictionary;
     private constructor();
+    /**
+     * Creates a new {@link LazyDictionary} instance.
+     * @param generator - Factory function that produces a value for a given key.
+     */
     static of<K extends string | number | symbol, T>(generator: TFunction<K, T>): LazyDictionary<K, T>;
-    getOrCreate(key: K): T;
+    /**
+     * Returns the cached value for `key`, generating and caching it if this is the first access.
+     * The generator is invoked at most once per key.
+     * @param key - The key to look up or generate.
+     * @returns The value associated with `key`.
+     */ getOrCreate(key: K): T;
+    /**
+     * Returns the cached value for `key`, or throws if the key has not been generated yet.
+     * Unlike {@link getOrCreate}, this method does **not** invoke the generator.
+     * @param key - The key to look up.
+     * @param errorMessage - Optional message for the thrown Error.
+     * @throws {Error} If the key has not been generated yet.
+     * @returns The value associated with `key`.
+     */
     getOrThrow(key: K, errorMessage?: "Value not initialized"): T;
+    /**
+     * Returns whether a value has been generated for the given key.
+     * @param key - The key to check.
+     */
+    hasKey(key: K): boolean;
+    /**
+     * Returns all key-value pairs that have been generated so far.
+     * Does not invoke the generator for any key.
+     * @returns An array of `[key, value]` tuples.
+     */
+    getEntries(): [K, T][];
 }
 
 /**

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;
     }
@@ -1653,16 +1671,44 @@ class LazyAsync {
     }
 }
 
+/**
+ * A dictionary that lazily initializes values on first access.
+ *
+ * Values are generated by a user-provided factory function and cached for subsequent lookups.
+ * Each key is initialized at most once — repeated calls to `getOrCreate` return the cached value
+ * without invoking the generator again.
+ *
+ * @typeParam K - Key type (string, number, or symbol).
+ * @typeParam T - The type of values produced by the generator.
+ *
+ * @example
+ * ```ts
+ * const dict = LazyDictionary.of( ( key: string ) => key.toUpperCase() );
+ * dict.getOrCreate( 'hello' ); // → 'HELLO'
+ * dict.getOrCreate( 'hello' ); // → 'HELLO' (cached, generator not called again)
+ * dict.hasKey( 'hello' );      // → true
+ * dict.getEntries();           // → [ [ 'hello', 'HELLO' ] ]
+ * ```
+ */
 class LazyDictionary {
     _generator;
     _dictionary = {};
     constructor(_generator) {
         this._generator = _generator;
     }
+    /**
+     * Creates a new {@link LazyDictionary} instance.
+     * @param generator - Factory function that produces a value for a given key.
+     */
     static of(generator) {
         return new LazyDictionary(generator);
     }
-    getOrCreate(key) {
+    /**
+     * Returns the cached value for `key`, generating and caching it if this is the first access.
+     * The generator is invoked at most once per key.
+     * @param key - The key to look up or generate.
+     * @returns The value associated with `key`.
+     */ getOrCreate(key) {
         if (key in this._dictionary) {
             return this._dictionary[key];
         }
@@ -1670,12 +1716,35 @@ class LazyDictionary {
         this._dictionary[key] = value;
         return value;
     }
+    /**
+     * Returns the cached value for `key`, or throws if the key has not been generated yet.
+     * Unlike {@link getOrCreate}, this method does **not** invoke the generator.
+     * @param key - The key to look up.
+     * @param errorMessage - Optional message for the thrown Error.
+     * @throws {Error} If the key has not been generated yet.
+     * @returns The value associated with `key`.
+     */
     getOrThrow(key, errorMessage) {
         if (key in this._dictionary) {
             return this._dictionary[key];
         }
         throw new Error(errorMessage);
     }
+    /**
+     * Returns whether a value has been generated for the given key.
+     * @param key - The key to check.
+     */
+    hasKey(key) {
+        return key in this._dictionary;
+    }
+    /**
+     * Returns all key-value pairs that have been generated so far.
+     * Does not invoke the generator for any key.
+     * @returns An array of `[key, value]` tuples.
+     */
+    getEntries() {
+        return Object.entries(this._dictionary);
+    }
 }
 
 class TimeUnit {