native-document 1.0.251 → 1.0.252

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "native-document",
-  "version": "1.0.251",
+  "version": "1.0.252",
   "description": "A reactive JavaScript framework that preserves native DOM simplicity without sacrificing modern features",
   "author": "AfroCodeur <https://github.com/afrocodeur>",
   "license": "MIT",

package/src/core/data/ObservableItem.js

@@ -678,6 +678,60 @@ ObservableItem.prototype.sync = function(targetObservable) {
     };
 };
 
+/**
+ * Subscribes to the observable and re-runs the callback whenever the value changes.
+ * The callback can mutate $currentValue directly or return a new value to set.
+ * A lock prevents re-entrant calls caused by mutations inside the callback.
+ *
+ * @param {(current: *, operations: *) => *|void} fn - Callback receiving the current value and
+ *     the triggering operation. If a value is returned, it is applied via .set().
+ *     If nothing is returned, no set is performed.
+ * @param {boolean} [autoCall=true] - If true, the callback is called immediately upon registration.
+ * @returns {this}
+ *
+ * @example
+ * // Mutate directly
+ * $items.watch((current) => {
+ *     if(!current.find(i => i.day === 'mon')) {
+ *         current.push({ day: 'mon', enabled: false });
+ *     }
+ * });
+ *
+ * @example
+ * // Return a new value
+ * $items.watch((current) => {
+ *     return DAYS.map(day =>
+ *         current.find(i => i.day === day) ?? { day, enabled: false }
+ *     );
+ * });
+ *
+ * @example
+ * // Disable auto-call
+ * $items.watch((current) => { ... }, false);
+ */
+ObservableItem.prototype.watch = function(fn, autoCall = true) {
+    let locked = false;
+
+    const handler = (value, prev, operations) => {
+        if(locked) return;
+        locked = true;
+        try {
+            const result = fn(this.$currentValue, operations);
+            if(result !== undefined) {
+                this.set(result);
+            }
+        }
+        finally {
+            locked = false;
+        }
+    };
+
+    this.subscribe(handler);
+    autoCall && handler(this.$currentValue, null, null);
+
+    return this;
+};
+
 
 ObservableItem.prototype.fnSet = function(value) {
     return () => this.set(value);

package/types/observable.d.ts

@@ -90,6 +90,8 @@ export interface ObservableItem<T = any> {
     get(key: string | number): any;
     when(value: T): ObservableWhen<T>;
 
+    watch(fn: (current: this['$currentValue'], operations: ObservableOperation | null) => typeof this['$currentValue'] | void, autoCall?: boolean): this;
+
     persist(key: string, options?: {
         get?: (value: any) => T;
         set?: (value: T) => any;