@develia/commons 0.4.14 → 0.4.15

package/src/collections/cache-dictionary.ts

@@ -1,9 +1,17 @@
+/**
+ * A dictionary-like structure with caching and expiration capabilities.
+ * @template T - The type of the values stored in the cache.
+ */
 export default class CacheDictionary<T> {
     private readonly fallback: ((key: string) => T) | null;
     private readonly cache: { [key: string]: T };
     private readonly defaultDuration: number | null;
     private readonly expiration: { [key: string]: Date | undefined };
 
+    /**
+     * @param {((key: string) => T) | null} fallback - Optional function to call when a key is not found.
+     * @param {number | null} defaultDuration - Default duration in seconds for cache items.
+     */
     constructor(fallback: ((key: string) => T) | null = null, defaultDuration: number | null = null) {
         this.fallback = fallback;
         this.cache = {};
@@ -11,15 +19,29 @@ export default class CacheDictionary<T> {
         this.expiration = {};
     }
 
-
+    /**
+     * Gets the expiration date for a specific key.
+     * @param {string} key - The key.
+     * @returns {Date | undefined} The expiration date or undefined.
+     */
     public getExpiration(key: string): Date | undefined {
         return this.expiration[key];
     }
 
+    /**
+     * Sets a specific expiration date for a key.
+     * @param {string} key - The key.
+     * @param {Date | undefined} expiration - The expiration date.
+     */
     public setExpiration(key: string, expiration: Date | undefined): void {
         this.expiration[key] = expiration;
     }
 
+    /**
+     * Sets a duration in seconds for a key's expiration.
+     * @param {string} key - The key.
+     * @param {number | null} duration - Duration in seconds. If null, expiration is removed.
+     */
     public setDuration(key: string, duration: number | null): void {
         if (duration === null) {
             delete this.expiration[key];
@@ -30,6 +52,12 @@ export default class CacheDictionary<T> {
         }
     }
 
+    /**
+     * Gets a value from the cache. If not found and a fallback exists, it uses the fallback.
+     * If the item is expired, it's removed and null is returned.
+     * @param {string} key - The key to retrieve.
+     * @returns {T | null} The value or null if not found/expired.
+     */
     public get(key: string): T | null {
         if (!this.cache.hasOwnProperty(key)) {
             if (this.fallback) {
@@ -48,11 +76,21 @@ export default class CacheDictionary<T> {
         return this.cache[key];
     }
 
+    /**
+     * Sets a value in the cache with an optional duration.
+     * @param {string} key - The key.
+     * @param {T} value - The value to store.
+     * @param {number | null} duration - Duration in seconds.
+     */
     public set(key: string, value: T, duration: number | null = null): void {
         this.cache[key] = value;
         this.expiration[key] = this.calculateExpiration(duration);
     }
 
+    /**
+     * Removes an item from the cache.
+     * @param {string} key - The key to remove.
+     */
     public remove(key: string): void {
         delete this.cache[key];
         delete this.expiration[key];

package/src/collections/default-map.ts

@@ -2,31 +2,37 @@ import type {Optional, UnaryFunction} from "../types.js";
 
 /**
  * DefaultMap<K, V>
- * Un Map que crea y guarda automáticamente un valor por defecto
- * cuando accedes a una clave inexistente con get(key).
+ * A Map that automatically creates and saves a default value
+ * when accessing a non-existent key with get(key).
  *
- * Ejemplo rápido:
+ * @template K - The type of the keys.
+ * @template V - The type of the values.
+ * @example
  *   const m = new DefaultMap<string, number>(() => 0);
- *   m.get("a") += 1;  // ahora m.get("a") === 1
+ *   m.get("a"); // 0
+ *   m.set("a", m.get("a") + 1); // 1
  */
 export default class DefaultMap<K, V> extends Map<K, V> {
     private readonly _factoryMethod: (key: K) => V;
 
     /**
-     * @param factoryMethod Función que produce el valor por defecto para una clave.
-     * @param entries Entradas iniciales.
+     * @param {UnaryFunction<K, V>} factoryMethod - Function that produces the default value for a key.
+     * @param {Optional<Iterable<[K, V]>>} entries - Initial entries.
      */
     constructor(factoryMethod: UnaryFunction<K, V>, entries: Optional<Iterable<[K, V]>> = undefined) {
         super(entries);
         if (typeof factoryMethod !== "function") {
-            throw new TypeError("DefaultMap necesita una factory (key => defaultValue).");
+            throw new TypeError("DefaultMap needs a factory (key => defaultValue).");
         }
         this._factoryMethod = factoryMethod;
     }
 
     /**
-     * Obtiene el valor de la clave. Si no existe, lo crea con la factory,
-     * lo guarda y lo devuelve.
+     * Gets the value for the key. If it does not exist, it creates it using the factory,
+     * saves it, and returns it.
+     *
+     * @param {K} key - The key to get.
+     * @returns {V} The value associated with the key.
      */
     override get(key: K): V {
         if (!super.has(key)) {

package/src/collections/default-weak-map.ts

@@ -1,20 +1,19 @@
 import type {Optional, UnaryFunction} from "../types.js";
 
 /**
- * DefaultMap<K, V>
- * Un Map que crea y guarda automáticamente un valor por defecto
- * cuando accedes a una clave inexistente con get(key).
+ * DefaultWeakMap<K, V>
+ * A WeakMap that automatically creates and saves a default value
+ * when accessing a non-existent key with get(key).
  *
- * Ejemplo rápido:
- *   const m = new DefaultMap<string, number>(() => 0);
- *   m.get("a") += 1;  // ahora m.get("a") === 1
+ * @template K - The type of the keys. Must be an object.
+ * @template V - The type of the values.
  */
-export default class DefaultMap<K extends object, V> extends WeakMap<K, V> {
+export default class DefaultWeakMap<K extends object, V> extends WeakMap<K, V> {
     private readonly _factoryMethod: (key: K) => V;
 
     /**
-     * @param factoryMethod Función que produce el valor por defecto para una clave.
-     * @param entries Entradas iniciales.
+     * @param {UnaryFunction<K, V>} factoryMethod - Function that produces the default value for a key.
+     * @param {Optional<Iterable<[K, V]>>} entries - Initial entries.
      */
     constructor(factoryMethod: UnaryFunction<K, V>, entries: Optional<Iterable<[K, V]>> = undefined) {
         super();
@@ -26,14 +25,17 @@ export default class DefaultMap<K extends object, V> extends WeakMap<K, V> {
         }
 
         if (typeof factoryMethod !== "function") {
-            throw new TypeError("DefaultMap necesita una factory (key => defaultValue).");
+            throw new TypeError("DefaultWeakMap needs a factory (key => defaultValue).");
         }
         this._factoryMethod = factoryMethod;
     }
 
     /**
-     * Obtiene el valor de la clave. Si no existe, lo crea con la factory,
-     * lo guarda y lo devuelve.
+     * Gets the value for the key. If it does not exist, it creates it using the factory,
+     * saves it, and returns it.
+     *
+     * @param {K} key - The key to get.
+     * @returns {V} The value associated with the key.
      */
     override get(key: K): V {
         if (!super.has(key)) {