native-document 1.0.165 → 1.0.166

package/src/core/data/ObservableItem.js

@@ -1,16 +1,24 @@
-import DebugManager from "../../core/utils/debug-manager";
-import MemoryManager from "./MemoryManager";
-import NativeDocumentError from "../../core/errors/NativeDocumentError";
-import PluginsManager from "../../core/utils/plugins-manager";
-import Validator from "../../core/utils/validator";
-import {deepClone} from "../utils/helpers";
-import {$getFromStorage, $saveToStorage} from "../utils/localstorage";
+import DebugManager from '../../core/utils/debug-manager';
+import MemoryManager from './MemoryManager';
+import NativeDocumentError from '../../core/errors/NativeDocumentError';
+import PluginsManager from '../../core/utils/plugins-manager';
+import Validator from '../../core/utils/validator';
+import {deepClone} from '../utils/helpers';
+import {$getFromStorage, $saveToStorage} from '../utils/localstorage';
 
 /**
+ * Reactive primitive value container.
+ * Notifies subscribers whenever its value changes.
+ * The core building block of NativeDocument's reactivity system.
  *
- * @param {*} value
- * @param {{ propagation: boolean, reset: boolean} | null} configs
- * @class ObservableItem
+ * @constructor
+ * @param {*} value - Initial value of the observable
+ * @param {{ propagation?: boolean, reset?: boolean, deep?: boolean } | null} [configs=null] - Optional configuration
+ * @param {boolean} [configs.reset] - If true, stores the initial value for later reset via .reset()
+ * @param {boolean} [configs.propagation] - Controls whether changes propagate to parent observables
+ * @example
+ * const count = new ObservableItem(0);
+ * const name  = new ObservableItem('John', { reset: true });
  */
 export default function ObservableItem(value, configs = null) {
     value = Validator.isObservable(value) ? value.val() : value;
@@ -71,15 +79,34 @@ ObservableItem.prototype.intercept = function(callback) {
     return this;
 };
 
+/**
+ * Intercepts mutations of the array observable before they are applied.
+ * Allows transforming or cancelling array operations.
+ *
+ * @param {(operation: { action: string, args: any[] }) => void} callback - Called before each mutation with the operation details
+ * @returns {ObservableItem} this
+ */
 ObservableItem.prototype.interceptMutations = function(callback) {
     this.$mutationInterceptor = callback;
     return this;
 };
 
+/**
+ * Calls the first registered subscriber directly (internal optimisation).
+ *
+ * @internal
+ * @param {{ action?: string, args?: any[], result?: any }} [operations] - Mutation metadata
+ */
 ObservableItem.prototype.triggerFirstListener = function(operations) {
     this.$firstListener(this.$currentValue, this.$previousValue, operations);
 };
 
+/**
+ * Calls all registered subscribers (internal).
+ *
+ * @internal
+ * @param {{ action?: string, args?: any[], result?: any }} [operations] - Mutation metadata
+ */
 ObservableItem.prototype.triggerListeners = function(operations) {
     const $listeners = this.$listeners;
     const $previousValue = this.$previousValue;
@@ -90,6 +117,12 @@ ObservableItem.prototype.triggerListeners = function(operations) {
     }
 };
 
+/**
+ * Triggers callbacks registered via .on() for the current and previous values (internal).
+ *
+ * @internal
+ * @param {{ action?: string, args?: any[], result?: any }} [operations] - Mutation metadata
+ */
 ObservableItem.prototype.triggerWatchers = function(operations) {
     const $watchers = this.$watchers;
     const $previousValue = this.$previousValue;
@@ -105,28 +138,47 @@ ObservableItem.prototype.triggerWatchers = function(operations) {
     }
 };
 
+/**
+ * Triggers both watchers and all subscribers (internal).
+ *
+ * @internal
+ * @param {{ action?: string, args?: any[], result?: any }} [operations] - Mutation metadata
+ */
 ObservableItem.prototype.triggerAll = function(operations) {
     this.triggerWatchers(operations);
     this.triggerListeners(operations);
 };
 
+/**
+ * Triggers both watchers and the first subscriber only (internal optimization).
+ *
+ * @internal
+ * @param {{ action?: string, args?: any[], result?: any }} [operations] - Mutation metadata
+ */
 ObservableItem.prototype.triggerWatchersAndFirstListener = function(operations) {
     this.triggerWatchers(operations);
     this.triggerFirstListener(operations);
 };
 
+/**
+ * Selects and assigns the optimal trigger strategy based on the current
+ * combination of listeners and watchers (internal).
+ * Called automatically after every subscribe / unsubscribe / on / off.
+ *
+ * @internal
+ */
 ObservableItem.prototype.assocTrigger = function() {
     this.$firstListener = null;
     if(this.$watchers?.size && this.$listeners?.length) {
         this.$firstListener = this.$listeners[0];
-        this.trigger = this.$firstListener.length === 0 ? this.$firstListener : this.triggerFirstListener
+        this.trigger = this.$firstListener.length === 0 ? this.$firstListener : this.triggerFirstListener;
         this.trigger = (this.$listeners.length === 1) ? this.triggerWatchersAndFirstListener : this.triggerAll;
         return;
     }
     if(this.$listeners?.length) {
         if(this.$listeners.length === 1) {
             this.$firstListener = this.$listeners[0];
-            this.trigger = this.$firstListener.length === 0 ? this.$firstListener : this.triggerFirstListener
+            this.trigger = this.$firstListener.length === 0 ? this.$firstListener : this.triggerFirstListener;
         }
         else {
             this.trigger = this.triggerListeners;
@@ -179,16 +231,30 @@ ObservableItem.prototype.$setWithInterceptor = function(data) {
  * @param {*} data
  */
 ObservableItem.prototype.$basicSet = function(data) {
-    let newValue = (typeof data === 'function') ? data(this.$currentValue) : data;
+    const newValue = (typeof data === 'function') ? data(this.$currentValue) : data;
     this.$updateWithNewValue(newValue);
 };
 
 ObservableItem.prototype.set = ObservableItem.prototype.$basicSet;
 
+/**
+ * Returns the current value of the observable.
+ *
+ * @returns {*} The current value
+ * @example
+ * const count = Observable(42);
+ * count.val(); // 42
+ */
 ObservableItem.prototype.val = function() {
     return this.$currentValue;
 };
 
+/**
+ * Disconnects all listeners and watchers and nullifies internal state.
+ * Does not trigger cleanup callbacks. Prefer .cleanup() for full disposal.
+ *
+ * @returns {void}
+ */
 ObservableItem.prototype.disconnectAll = function() {
     this.$previousValue = null;
     this.$currentValue = null;
@@ -212,6 +278,16 @@ ObservableItem.prototype.onCleanup = function(callback) {
     this.$cleanupListeners.push(callback);
 };
 
+/**
+ * Disposes the observable: runs cleanup callbacks, unregisters from MemoryManager,
+ * disconnects all listeners and removes the $value property.
+ *
+ * @returns {void}
+ * @example
+ * const obs = Observable(0);
+ * obs.onCleanup(() => console.log('disposed'));
+ * obs.cleanup(); // logs 'disposed', frees memory
+ */
 ObservableItem.prototype.cleanup = function() {
     if (this.$cleanupListeners) {
         for (let i = 0; i < this.$cleanupListeners.length; i++) {
@@ -227,10 +303,16 @@ ObservableItem.prototype.cleanup = function() {
     delete this.$value;
 };
 
+
 /**
+ * Subscribes to value changes. The callback is called every time the value changes.
+ * Returns nothing — use .unsubscribe(callback) to remove the listener.
  *
- * @param {Function} callback
- * @returns {(function(): void)}
+ * @param {(current: *, previous: *, operations?: { action?: string }) => void} callback - Called on each value change
+ * @example
+ * const count = Observable(0);
+ * count.subscribe((val) => console.log('New value:', val));
+ * count.$value++; // logs 'New value: 1'
  */
 ObservableItem.prototype.subscribe = function(callback) {
     if(process.env.NODE_ENV === 'development') {
@@ -280,7 +362,7 @@ ObservableItem.prototype.on = function(value, callback) {
             for(let i = 0, length = watchValueList.length; i < length; i++) {
                 watchValueList[i](value);
             }
-        }
+        };
         callback.list = watchValueList;
         this.$watchers.set(value, callback);
     } else {
@@ -346,9 +428,16 @@ ObservableItem.prototype.once = function(predicate, callback) {
     this.subscribe(handler);
 };
 
+
 /**
- * Unsubscribe from an observable.
- * @param {Function} callback
+ * Removes a previously registered subscriber.
+ *
+ * @param {Function} callback - The exact function reference passed to .subscribe()
+ * @returns {void}
+ * @example
+ * const handler = (val) => console.log(val);
+ * count.subscribe(handler);
+ * count.unsubscribe(handler);
  */
 ObservableItem.prototype.unsubscribe = function(callback) {
     if(!this.$listeners) return;
@@ -445,7 +534,7 @@ ObservableItem.prototype.reset = function() {
             observable.reset();
         })
         : this.$initialValue;
-    this.set(resetValue)
+    this.set(resetValue);
 };
 
 /**
@@ -467,8 +556,22 @@ ObservableItem.prototype.valueOf = function() {
     return this.$currentValue;
 };
 
-
-
+/**
+ * Syncs this observable's value to localStorage and restores it on load.
+ * Optionally transforms values on get and set.
+ *
+ * @param {string} key - localStorage key
+ * @param {{ get?: (stored: any) => T, set?: (value: T) => any }} [options={}] - Transform options
+ * @param {Function} [options.get] - Transform the stored value before applying it
+ * @param {Function} [options.set] - Transform the value before saving it
+ * @returns {ObservableItem} this — chainable
+ * @example
+ * const theme = Observable('light').persist('app-theme');
+ * const count = Observable(0).persist('count', {
+ *   get: (v) => parseInt(v),
+ *   set: (v) => String(v),
+ * });
+ */
 ObservableItem.prototype.persist = function(key, options = {}) {
     let value = $getFromStorage(key, this.$currentValue);
     if(options.get) {
@@ -482,6 +585,17 @@ ObservableItem.prototype.persist = function(key, options = {}) {
     return this;
 };
 
+/**
+ * Creates a new ObservableItem with a deep clone of the current value.
+ * For objects implementing a .clone() method, delegates to that method.
+ *
+ * @returns {ObservableItem} A new independent observable with the cloned value
+ * @example
+ * const original = Observable({ x: 1 });
+ * const copy = original.clone();
+ * copy.set({ x: 99 });
+ * original.val(); // { x: 1 } — untouched
+ */
 ObservableItem.prototype.clone = function() {
     let clonedValue = this.$currentValue;
 

package/src/core/data/ObservableObject.js

@@ -1,24 +1,49 @@
-import ObservableItem from "./ObservableItem";
-import Validator from "../utils/validator";
-import {nextTick} from "../utils/helpers";
-import ObservableArray from "./ObservableArray";
+import ObservableItem from './ObservableItem';
+import Validator from '../utils/validator';
+import {nextTick} from '../utils/helpers';
+import ObservableArray from './ObservableArray';
 
+/**
+ * Reactive object container extending ObservableItem.
+ * Each property of the target object becomes an individual ObservableItem (or ObservableArray/ObservableObject for nested structures).
+ * Use Observable.object() or Observable.init() rather than instantiating directly.
+ *
+ * @constructor
+ * @param {Record<string, *>} target - Plain object to make reactive
+ * @param {{ deep?: boolean, reset?: boolean, propagation?: boolean }|null} [configs] - Configuration
+ * @param {boolean} [configs.deep] - If false, nested objects and arrays are not wrapped recursively (default: true)
+ * @example
+ * const user = Observable.object({ name: 'John', age: 25 });
+ * user.name.$value = 'Jane'; // triggers reactivity on name only
+ */
 export const ObservableObject = function(target, configs) {
     ObservableItem.call(this, target);
     this.$observables = {};
     this.configs = configs;
 
-    this.$load(target);
-
-    for(const name in target) {
-        if(!Object.hasOwn(this, name)) {
-            Object.defineProperty(this, name, {
-                get: () => this.$observables[name],
-                set: (value) => this.$observables[name].set(value)
+    for(const key in target) {
+        if(!Object.hasOwn(this, key)) {
+            Object.defineProperty(this, key, {
+                get: () => this.$observables[key],
+                set: (value) => {
+                    this.$observables[key].set(value);
+                },
+                configurable: true,
+                enumerable: true,
             });
         }
     }
 
+    this.$load(target);
+
+    Object.defineProperty(this, '$currentValue', {
+        get: function() {
+            return this.val();
+        },
+        set(value) {
+            this.set(value);
+        }
+    });
 };
 
 ObservableObject.prototype = Object.create(ObservableItem.prototype);
@@ -29,12 +54,19 @@ Object.defineProperty(ObservableObject, '$value', {
     },
     set(value) {
         this.set(value);
-    }
-})
+    },
+});
 
 ObservableObject.prototype.__$isObservableObject = true;
 ObservableObject.prototype.__isProxy__ = true;
 
+/**
+ * Initialises (or reinitialize) the internal observables map from a plain object.
+ * Called automatically in the constructor.
+ *
+ * @internal
+ * @param {Record<string, *>} initialValue - Object whose properties are turned into observables
+ */
 ObservableObject.prototype.$load = function(initialValue) {
     const configs = this.configs;
     for(const key in initialValue) {
@@ -56,34 +88,39 @@ ObservableObject.prototype.$load = function(initialValue) {
             this.$observables[key] = new ObservableArray(itemValue, configs);
             continue;
         }
-        if(Validator.isObservable(itemValue) || Validator.isProxy(itemValue)) {
+        if(itemValue?.__$Observable) {
             this.$observables[key] = itemValue;
             continue;
         }
-        this.$observables[key] = (typeof itemValue === 'object') ? new ObservableObject(itemValue, configs) : new ObservableItem(itemValue, configs);
+        this.$observables[key] = (Validator.isJson(itemValue)) ? new ObservableObject(itemValue, configs) : new ObservableItem(itemValue, configs);
     }
 };
 
+/**
+ * Returns a plain snapshot of all observable values.
+ * Unwraps nested ObservableItem, ObservableArray, and ObservableObject recursively.
+ * Alias: $val()
+ *
+ * @returns {Record<string, *>} Plain object with current values
+ * @example
+ * const user = Observable.object({ name: 'John', age: 25 });
+ * user.val(); // { name: 'John', age: 25 }
+ */
 ObservableObject.prototype.val = function() {
     const result = {};
     for(const key in this.$observables) {
         const dataItem = this.$observables[key];
-        if(Validator.isObservable(dataItem)) {
+        if(dataItem?.__$Observable) {
             let value = dataItem.val();
             if(Array.isArray(value)) {
                 value = value.map(item => {
-                    if(Validator.isObservable(item)) {
+                    if(item.__$Observable) {
                         return item.val();
                     }
-                    if(Validator.isProxy(item)) {
-                        return item.$value;
-                    }
                     return item;
                 });
             }
             result[key] = value;
-        } else if(Validator.isProxy(dataItem)) {
-            result[key] = dataItem.$value;
         } else {
             result[key] = dataItem;
         }
@@ -92,20 +129,37 @@ ObservableObject.prototype.val = function() {
 };
 ObservableObject.prototype.$val = ObservableObject.prototype.val;
 
+/**
+ * Returns the current value of a single property, unwrapped from its observable.
+ * Alias: $get(property)
+ *
+ * @param {string} property - Property name
+ * @returns {*} The current value of that property
+ * @example
+ * const user = Observable.object({ name: 'John' });
+ * user.get('name'); // 'John'
+ */
 ObservableObject.prototype.get = function(property) {
     const item = this.$observables[property];
-    if(Validator.isObservable(item)) {
+    if(item?.__$Observable) {
         return item.val();
     }
-    if(Validator.isProxy(item)) {
-        return item.$value;
-    }
     return item;
 };
 ObservableObject.prototype.$get = ObservableObject.prototype.get;
 
+/**
+ * Updates one or more properties with new values.
+ * Supports partial updates — only provided keys are changed.
+ * Aliases: $set(newData), $updateWith(newData), update(newData)
+ *
+ * @param {Partial<Record<string, *>>} newData - Object with properties to update
+ * @example
+ * const user = Observable.object({ name: 'John', age: 25 });
+ * user.set({ name: 'Jane' }); // Only name changes, age stays 25
+ */
 ObservableObject.prototype.set = function(newData) {
-    const data = Validator.isProxy(newData) ? newData.$value : newData;
+    const data = newData?.__$Observable ? newData.$value : newData;
     const configs = this.configs;
 
     for(const key in data) {
@@ -113,15 +167,19 @@ ObservableObject.prototype.set = function(newData) {
         const newValueOrigin = newData[key];
         const newValue = data[key];
 
-        if(Validator.isObservable(targetItem)) {
+        if(targetItem?.__$Observable) {
+            if(targetItem.__$isObservableObject) {
+                targetItem.update(newValue);
+                continue;
+            }
             if(!Validator.isArray(newValue)) {
                 targetItem.set(newValue);
                 continue;
             }
             const firstElementFromOriginalValue = newValueOrigin.at(0);
-            if(Validator.isObservable(firstElementFromOriginalValue) || Validator.isProxy(firstElementFromOriginalValue)) {
+            if(firstElementFromOriginalValue?.__$Observable) {
                 const newValues = newValue.map(item => {
-                    if(Validator.isProxy(firstElementFromOriginalValue)) {
+                    if(firstElementFromOriginalValue.__$isObservableObject) {
                         return new ObservableObject(item, configs);
                     }
                     return ObservableItem(item, configs);
@@ -132,35 +190,68 @@ ObservableObject.prototype.set = function(newData) {
             targetItem.set([...newValue]);
             continue;
         }
-        if(Validator.isProxy(targetItem)) {
-            targetItem.update(newValue);
-            continue;
-        }
         this[key] = newValue;
     }
 };
 ObservableObject.prototype.$set = ObservableObject.prototype.set;
 ObservableObject.prototype.$updateWith = ObservableObject.prototype.set;
 
+/**
+ * Returns an array of all internal observable instances (one per property).
+ * Alias: $observables()
+ *
+ * @returns {ObservableItem[]} Array of observable instances
+ */
 ObservableObject.prototype.observables = function() {
     return Object.values(this.$observables);
 };
 ObservableObject.prototype.$observables = ObservableObject.prototype.observables;
 
+/**
+ * Returns all property names of the observable object.
+ * Alias: $keys()
+ *
+ * @returns {string[]} Array of property names
+ */
 ObservableObject.prototype.keys = function() {
     return Object.keys(this.$observables);
 };
 ObservableObject.prototype.$keys = ObservableObject.prototype.keys;
+
+/**
+ * Creates a new ObservableObject with a snapshot of the current values.
+ * Changes to the clone do not affect the original.
+ * Alias: $clone()
+ *
+ * @returns {ObservableObject} New independent ObservableObject with the same structure and values
+ */
 ObservableObject.prototype.clone = function() {
     return new ObservableObject(this.val(), this.configs);
 };
 ObservableObject.prototype.$clone = ObservableObject.prototype.clone;
+
+/**
+ * Resets all properties to their initial values by calling .reset() on each child observable.
+ * Only works if observables were created with { reset: true }.
+ */
 ObservableObject.prototype.reset = function() {
     for(const key in this.$observables) {
         this.$observables[key].reset();
     }
 };
 ObservableObject.prototype.originalSubscribe = ObservableObject.prototype.subscribe;
+
+/**
+ * Subscribes to changes across all nested observables.
+ * The callback is called whenever any property (or nested value) changes.
+ * Internally uses debouncing (nextTick) to batch multiple simultaneous changes.
+ *
+ * @param {(value: Record<string, *>) => void} callback - Called on any nested change
+ * @example
+ * const user = Observable.object({ name: 'John', age: 25 });
+ * user.subscribe(() => console.log('user changed:', user.val()));
+ * user.name.$value = 'Jane'; // logs 'user changed: { name: "Jane", age: 25 }'
+ */
 ObservableObject.prototype.subscribe = function(callback) {
     const observables = this.observables();
     const updatedValue = nextTick(() => this.trigger());
@@ -171,7 +262,7 @@ ObservableObject.prototype.subscribe = function(callback) {
         const observable = observables[i];
         if (observable.__$isObservableArray) {
             observable.deepSubscribe(updatedValue);
-            continue
+            continue;
         }
         observable.subscribe(updatedValue);
     }