From 4f81b2c8895f72ea724583d25fe3dfd69f2b873d Mon Sep 17 00:00:00 2001
From: Juan Hoyos <juan.hoyos4@gmail.com>
Date: Tue, 30 Jul 2024 18:48:07 -0500
Subject: [PATCH] chore: documents DataMap and DataSet

---
 packages/core/src/core/Types/src/data-map.ts | 45 ++++++++++++++++++++
 packages/core/src/core/Types/src/data-set.ts | 40 +++++++++++++++++
 2 files changed, 85 insertions(+)

diff --git a/packages/core/src/core/Types/src/data-map.ts b/packages/core/src/core/Types/src/data-map.ts
index b8eca297..c1d8d1b0 100644
--- a/packages/core/src/core/Types/src/data-map.ts
+++ b/packages/core/src/core/Types/src/data-map.ts
@@ -1,20 +1,56 @@
 import { Event } from "./event";
 
+/**
+ * A class that extends the built-in Map class and provides additional events for item set, update, delete, and clear operations.
+ *
+ * @template K - The type of keys in the map.
+ * @template V - The type of values in the map.
+ */
 export class DataMap<K, V> extends Map<K, V> {
+  /**
+   * An event triggered when a new item is set in the map.
+   */
   readonly onItemSet = new Event<{ key: K; value: V }>();
+
+  /**
+   * An event triggered when an existing item in the map is updated.
+   */
   readonly onItemUpdated = new Event<{ key: K; value: V }>();
+
+  /**
+   * An event triggered when an item is deleted from the map.
+   */
   readonly onItemDeleted = new Event();
+
+  /**
+   * An event triggered when the map is cleared.
+   */
   readonly onCleared = new Event();
 
+  /**
+   * Constructs a new DataMap instance.
+   *
+   * @param iterable - An iterable object containing key-value pairs to populate the map.
+   */
   constructor(iterable?: Iterable<readonly [K, V]> | null | undefined) {
     super(iterable);
   }
 
+  /**
+   * Clears the map and triggers the onCleared event.
+   */
   clear() {
     super.clear();
     this.onCleared.trigger();
   }
 
+  /**
+   * Sets the value for the specified key in the map and triggers the appropriate event (onItemSet or onItemUpdated).
+   *
+   * @param key - The key of the item to set.
+   * @param value - The value of the item to set.
+   * @returns The DataMap instance.
+   */
   set(key: K, value: V) {
     const triggerUpdate = this.has(key);
     const result = super.set(key, value);
@@ -32,12 +68,21 @@ export class DataMap<K, V> extends Map<K, V> {
     return result;
   }
 
+  /**
+   * Deletes the specified key from the map and triggers the onItemDeleted event if the key was found.
+   *
+   * @param key - The key of the item to delete.
+   * @returns True if the key was found and deleted; otherwise, false.
+   */
   delete(key: K) {
     const deleted = super.delete(key);
     if (deleted) this.onItemDeleted.trigger();
     return deleted;
   }
 
+  /**
+   * Clears the map and resets the events.
+   */
   dispose() {
     this.clear();
     this.onItemSet.reset();
diff --git a/packages/core/src/core/Types/src/data-set.ts b/packages/core/src/core/Types/src/data-set.ts
index 7d3b6e20..41711545 100644
--- a/packages/core/src/core/Types/src/data-set.ts
+++ b/packages/core/src/core/Types/src/data-set.ts
@@ -1,19 +1,50 @@
 import { Event } from "./event";
 
+/**
+ * A class that extends the built-in Set class and provides additional functionality.
+ * It triggers events when items are added, deleted, or the set is cleared.
+ *
+ * @template T - The type of elements in the set.
+ */
 export class DataSet<T> extends Set<T> {
+  /**
+   * An event that is triggered when a new item is added to the set.
+   */
   readonly onItemAdded = new Event<T>();
+
+  /**
+   * An event that is triggered when an item is deleted from the set.
+   */
   readonly onItemDeleted = new Event();
+
+  /**
+   * An event that is triggered when the set is cleared.
+   */
   readonly onCleared = new Event();
 
+  /**
+   * Constructs a new instance of the DataSet class.
+   *
+   * @param iterable - An optional iterable object to initialize the set with.
+   */
   constructor(iterable?: Iterable<T> | null) {
     super(iterable);
   }
 
+  /**
+   * Clears the set and triggers the onCleared event.
+   */
   clear() {
     super.clear();
     this.onCleared.trigger();
   }
 
+  /**
+   * Adds a value to the set and triggers the onItemAdded event.
+   *
+   * @param value - The value to add to the set.
+   * @returns - The set instance.
+   */
   add(value: T) {
     const existing = this.has(value);
     if (existing) return this;
@@ -23,12 +54,21 @@ export class DataSet<T> extends Set<T> {
     return result;
   }
 
+  /**
+   * Deletes a value from the set and triggers the onItemDeleted event.
+   *
+   * @param value - The value to delete from the set.
+   * @returns - True if the value was successfully deleted, false otherwise.
+   */
   delete(value: T) {
     const deleted = super.delete(value);
     if (deleted) this.onItemDeleted.trigger();
     return deleted;
   }
 
+  /**
+   * Clears the set and resets the onItemAdded, onItemDeleted, and onCleared events.
+   */
   dispose() {
     this.clear();
     this.onItemAdded.reset();