@schukai/monster 4.38.4 → 4.38.6

package/source/types/observer.mjs

@@ -15,149 +15,144 @@
 import { Base } from "./base.mjs";
 import { isObject } from "./is.mjs";
 import { TokenList } from "./tokenlist.mjs";
-import { UniqueQueue } from "./uniquequeue.mjs";
 import { instanceSymbol } from "../constants.mjs";
 export { Observer };
 
 /**
- * An observer manages a callback function
+ * Manages a callback function that is executed asynchronously when updated.
  *
- * The update method is called with the subject object as this pointer. For this reason
- * the callback should not be an arrow function, because it gets this pointer of its own context.
+ * The `update` method is called with the subject object as its `this` context.
+ * For this reason, the callback should be a regular function, not an arrow function,
+ * if you need access to the subject via `this`.
  *
- * Include this class in your project with the following code:
+ * @example
+ * // Basic usage with a regular function to access the subject
+ * const observer = new Observer(function() {
+ * console.log("Subject updated:", this); // `this` refers to `mySubject`
+ * });
  *
- * ```js
- * import { Observer } from "@schukai/monster/source/types/observer.mjs";
- * ```
+ * // Usage with arguments
+ * const greeter = new Observer(function(greeting) {
+ * console.log(greeting, this.name); // "Hello", "World"
+ * }, "Hello");
  *
- * The callback function is passed as the first argument to the constructor.
- *
- * ```js
- * new Observer(()=>{
- *     // this is not subject
- * })
- *
- * new Observer(function() {
- *     // this is subject
- * })
- * ```
- *
- * Additional arguments can be passed to the callback. To do this, simply specify them.
- *
- * ```js
- * Observer(function(a, b, c) {
- *     console.log(a, b, c); // ↦ "a", 2, true
- * }, "a", 2, true)
- * ```
- *
- * The callback function must have as many parameters as arguments are given.
+ * const mySubject = { name: "World" };
+ * observer.update(mySubject);
+ * greeter.update(mySubject);
  *
  * @license AGPLv3
  * @since 1.0.0
  */
 class Observer extends Base {
-	/**
-	 *
-	 * @param {function} callback
-	 * @param {*} args
-	 */
-	constructor(callback, ...args) {
-		super();
-
-		if (typeof callback !== "function") {
-			throw new Error("observer callback must be a function");
-		}
-
-		this.callback = callback;
-		this.arguments = args;
-		this.tags = new TokenList();
-		this.queue = new UniqueQueue();
-	}
-
-	/**
-	 * This method is called by the `instanceof` operator.
-	 * @return {symbol}
-	 * @since 2.1.0
-	 */
-	static get [instanceSymbol]() {
-		return Symbol.for("@schukai/monster/types/observer");
-	}
-
-	/**
-	 *
-	 * @param {string} tag
-	 * @return {Observer}
-	 */
-	addTag(tag) {
-		this.tags.add(tag);
-		return this;
-	}
-
-	/**
-	 *
-	 * @param {string} tag
-	 * @return {Observer}
-	 */
-	removeTag(tag) {
-		this.tags.remove(tag);
-		return this;
-	}
-
-	/**
-	 *
-	 * @return {Array}
-	 */
-	getTags() {
-		return this.tags.entries();
-	}
-
-	/**
-	 *
-	 * @param {string} tag
-	 * @return {boolean}
-	 */
-	hasTag(tag) {
-		return this.tags.contains(tag);
-	}
-
-	/**
-	 *
-	 * @param {object} subject
-	 * @return {Promise}
-	 */
-	update(subject) {
-		const self = this;
-
-		if (!isObject(subject)) {
-			return Promise.reject("subject must be an object");
-		}
-
-		return new Promise(function (resolve, reject) {
-			self.queue.add(subject);
-
-			queueMicrotask(() => {
-				try {
-					// the queue and the `queueMicrotask` ensure that an object is not
-					// informed of the same change more than once.
-					if (self.queue.isEmpty()) {
-						resolve();
-						return;
-					}
-
-					const s = self.queue.poll();
-					const result = self.callback.apply(s, self.arguments);
-
-					if (isObject(result) && result instanceof Promise) {
-						result.then(resolve).catch(reject);
-						return;
-					}
-
-					resolve(result);
-				} catch (e) {
-					reject(e);
-				}
-			});
-		});
-	}
+  /**
+   * Stores promises for updates that are scheduled but not yet executed.
+   * This prevents multiple executions for the same subject within one microtask cycle.
+   * @type {Map<object, Promise<*>>}
+   */
+  #pendingUpdates = new Map();
+  #callback;
+  #arguments;
+  #tags = new TokenList();
+
+  /**
+   * @param {function} callback The function to execute on update.
+   * @param {...*} args Additional arguments to pass to the callback.
+   */
+  constructor(callback, ...args) {
+    super();
+
+    if (typeof callback !== "function") {
+      throw new Error("Observer callback must be a function.");
+    }
+
+    this.#callback = callback;
+    this.#arguments = args;
+  }
+
+  /**
+   * This method is called by the `instanceof` operator.
+   * @returns {symbol}
+   * @since 2.1.0
+   */
+  static get [instanceSymbol]() {
+    return Symbol.for("@schukai/monster/types/observer");
+  }
+
+  // Getter for properties for cleaner access if needed
+  get callback() {
+    return this.#callback;
+  }
+
+  get arguments() {
+    return this.#arguments;
+  }
+
+  /**
+   * Schedules the callback for execution with the given subject.
+   * If multiple updates for the same subject are requested in the same event loop tick,
+   * the callback is only executed once. All callers will receive the same promise.
+   *
+   * @param {object} subject The subject object that triggered the update.
+   * @returns {Promise<*>} A promise that resolves with the return value of the callback,
+   * or rejects if the callback throws an error.
+   */
+  update(subject) {
+    if (!isObject(subject)) {
+      return Promise.reject(new Error("Subject must be an object."));
+    }
+
+    if (this.#pendingUpdates.has(subject)) {
+      return this.#pendingUpdates.get(subject);
+    }
+
+    const promise = new Promise((resolve, reject) => {
+      queueMicrotask(async () => {
+        try {
+          const result = await this.#callback.apply(subject, this.#arguments);
+          resolve(result);
+        } catch (e) {
+          reject(e);
+        } finally {
+          this.#pendingUpdates.delete(subject);
+        }
+      });
+    });
+
+    this.#pendingUpdates.set(subject, promise);
+
+    return promise;
+  }
+
+  /**
+   * @param {string} tag
+   * @returns {Observer}
+   */
+  addTag(tag) {
+    this.#tags.add(tag);
+    return this;
+  }
+
+  /**
+   * @param {string} tag
+   * @returns {Observer}
+   */
+  removeTag(tag) {
+    this.#tags.remove(tag);
+    return this;
+  }
+
+  /**
+   * @returns {string[]}
+   */
+  getTags() {
+    return this.#tags.entries();
+  }
+
+  /**
+   * @param {string} tag
+   * @returns {boolean}
+   */
+  hasTag(tag) {
+    return this.#tags.contains(tag);
+  }
 }

package/source/types/version.mjs

@@ -156,7 +156,7 @@ function getMonsterVersion() {
 	}
 
 	/** don't touch, replaced by make with package.json version */
-	monsterVersion = new Version("4.38.3");
+	monsterVersion = new Version("4.38.4");
 
 	return monsterVersion;
 }