@zelgadis87/utils-core 5.4.7 → 5.5.0-beta.1

package/.rollup/index.d.ts

@@ -1431,13 +1431,61 @@ 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 readonly _map;
     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>;
+    /**
+     * 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

@@ -1671,29 +1671,81 @@ 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 = {};
+    _map = new Map();
     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);
     }
+    /**
+     * 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];
+        if (!this._map.has(key)) {
+            const value = this._generator(key);
+            this._map.set(key, value);
+            return value;
         }
-        const value = this._generator(key);
-        this._dictionary[key] = value;
-        return value;
+        return this._map.get(key);
     }
+    /**
+     * 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];
+        if (this._map.has(key)) {
+            return this._map.get(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 this._map.has(key);
+    }
+    /**
+     * 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 [...this._map.entries()];
+    }
 }
 
 class TimeUnit {