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

package/.rollup/index.cjs

@@ -1673,16 +1673,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];
         }
@@ -1690,12 +1718,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 {