native-document 1.0.15 → 1.0.16-8.2

package/src/core/data/ObservableObject.js

@@ -0,0 +1,274 @@
+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;
+
+    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);
+
+Object.defineProperty(ObservableObject, '$value', {
+    get() {
+        return this.val();
+    },
+    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) {
+        const itemValue = initialValue[key];
+        if(Array.isArray(itemValue)) {
+            if(configs?.deep !== false) {
+                const mappedItemValue = itemValue.map(item => {
+                    if(Validator.isJson(item)) {
+                        return new ObservableObject(item, configs);
+                    }
+                    if(Validator.isArray(item)) {
+                        return new ObservableArray(item, configs);
+                    }
+                    return new ObservableItem(item, configs);
+                });
+                this.$observables[key] = new ObservableArray(mappedItemValue, configs);
+                continue;
+            }
+            this.$observables[key] = new ObservableArray(itemValue, configs);
+            continue;
+        }
+        if(itemValue?.__$Observable) {
+            this.$observables[key] = itemValue;
+            continue;
+        }
+        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(dataItem?.__$Observable) {
+            let value = dataItem.val();
+            if(Array.isArray(value)) {
+                value = value.map(item => {
+                    if(item.__$Observable) {
+                        return item.val();
+                    }
+                    return item;
+                });
+            }
+            result[key] = value;
+        } else {
+            result[key] = dataItem;
+        }
+    }
+    return result;
+};
+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(item?.__$Observable) {
+        return item.val();
+    }
+    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 = newData?.__$Observable ? newData.$value : newData;
+    const configs = this.configs;
+
+    for(const key in data) {
+        const targetItem = this.$observables[key];
+        const newValueOrigin = newData[key];
+        const newValue = data[key];
+
+        if(targetItem?.__$Observable) {
+            if(targetItem.__$isObservableObject) {
+                targetItem.update(newValue);
+                continue;
+            }
+            if(!Validator.isArray(newValue)) {
+                targetItem.set(newValue);
+                continue;
+            }
+            const firstElementFromOriginalValue = newValueOrigin.at(0);
+            if(firstElementFromOriginalValue?.__$Observable) {
+                const newValues = newValue.map(item => {
+                    if(firstElementFromOriginalValue.__$isObservableObject) {
+                        return new ObservableObject(item, configs);
+                    }
+                    return ObservableItem(item, configs);
+                });
+                targetItem.set(newValues);
+                continue;
+            }
+            targetItem.set([...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());
+
+    this.originalSubscribe(callback);
+
+    for (let i = 0, length = observables.length; i < length; i++) {
+        const observable = observables[i];
+        if (observable.__$isObservableArray) {
+            observable.deepSubscribe(updatedValue);
+            continue;
+        }
+        observable.subscribe(updatedValue);
+    }
+};
+ObservableObject.prototype.configs = function() {
+    return this.configs;
+};
+
+ObservableObject.prototype.update = ObservableObject.prototype.set;

package/src/core/data/ObservableResource.js

@@ -0,0 +1,315 @@
+import ObservableItem from './ObservableItem';
+import {debounce} from '../utils/helpers';
+
+const STATE = {
+    UNRESOLVED: 'unresolved',
+    PENDING:    'pending',
+    READY:      'ready',
+    REFRESHING: 'refreshing',
+    ERRORED:    'errored',
+};
+
+/**
+ * Reactive async data fetcher with built-in state management.
+ * Tracks loading, ready, refreshing, and error states automatically.
+ * Use Observable.resource() rather than instantiating directly.
+ *
+ * @constructor
+ * @param {(...depValues: any[], signal?: AbortSignal) => Promise<*>} fn - Async function to fetch data. Receives dependency values as arguments. If its arity exceeds the number of dependencies, an AbortSignal is passed as the last argument.
+ * @param {ObservableItem[]} deps - Observable dependencies — resource re-fetches when any changes
+ * @param {{ auto?: boolean, lazy?: boolean, debounce?: number, into?: ObservableItem, apply?: Function }} config - Configuration
+ * @param {boolean} [config.auto=false] - If true, fetch runs automatically on creation (or when deps change)
+ * @param {boolean} [config.lazy=false] - If true with deps, does not fetch immediately — waits for first dep change
+ * @param {number} [config.debounce=0] - Debounce delay in ms for dependency-triggered re-fetches
+ * @param {ObservableItem} [config.into] - Observable to write results into instead of creating a new one
+ * @param {Function} [config.apply] - Custom function to apply the result to this.data
+ * @example
+ * const userId = Observable(1);
+ * const user = Observable.resource(
+ *   async (id, signal) => fetch(`/api/users/${id}`, { signal }).then(r => r.json()),
+ *   [userId],
+ *   { auto: true }
+ * );
+ */
+export default function ObservableResource(fn, deps, config) {
+    this.$fn = (config.debounce > 0) ? debounce(fn, config.debounce) : fn;
+    this.$dependencies = deps;
+    this.$config = config;
+    this.$controller  = null;
+    this.$subscriptions        = [];
+
+    this.data  = config.into ?? new ObservableItem(null);
+    this.error = new ObservableItem(null);
+    this.state = new ObservableItem(STATE.UNRESOLVED);
+
+    this.loading = ObservableItem.computed(
+        (state) => state === STATE.PENDING || state === STATE.REFRESHING,
+        [this.state],
+    );
+
+    if (config.auto) {
+        if (deps.length > 0) {
+            this.$watchDependencies();
+            return;
+        }
+        this.fetch();
+    }
+}
+
+ObservableResource.prototype.$applyResult = function(result) {
+    if(this.$config.apply) {
+        this.$config.apply(result, this.data);
+        return;
+    }
+    this.data.set(result);
+};
+
+ObservableResource.prototype.$abort = function() {
+    if (this.$controller) {
+        this.$controller.abort();
+        this.$controller = null;
+    }
+};
+
+ObservableResource.prototype.$runWithAbortController = function(isRefetch = false) {
+    this.$abort();
+
+    this.$controller = new AbortController();
+    const signal = this.$controller.signal;
+
+    const hasData = this.data.val() !== null;
+    const nextState = isRefetch && hasData ? STATE.REFRESHING : STATE.PENDING;
+
+    this.error.set(null);
+    this.state.set(nextState);
+
+    const depValues = this.$dependencies.map(dep => dep.val());
+    const args = [...depValues, signal];
+
+    Promise.resolve(this.$fn(...args))
+        .then(result => {
+            if (signal.aborted) {
+                return;
+            }
+            this.$applyResult(result);
+            this.error.set(null);
+            this.state.set(STATE.READY);
+            this.$controller = null;
+        })
+        .catch(err => {
+            if (signal.aborted) {
+                return;
+            }
+            this.error.set(err);
+            this.state.set(STATE.ERRORED);
+            this.$controller = null;
+        });
+};
+ObservableResource.prototype.$runWithoutAbortController = function(isRefetch = false) {
+    const hasData = this.data.val() !== null;
+    const nextState = isRefetch && hasData ? STATE.REFRESHING : STATE.PENDING;
+
+    this.error.set(null);
+    this.state.set(nextState);
+
+    const args = this.$dependencies.map(dep => dep.val());
+
+    Promise.resolve(this.$fn(...args))
+        .then(result => {
+            this.$applyResult(result);
+            this.error.set(null);
+            this.state.set(STATE.READY);
+        })
+        .catch(err => {
+            this.error.set(err);
+            this.state.set(STATE.ERRORED);
+        });
+};
+
+ObservableResource.prototype.into = function($observable) {
+    this.data = $observable;
+    return this;
+};
+
+ObservableResource.prototype.$run = function(isRefetch = false) {
+    const needsSignal = this.$fn.length > this.$dependencies.length;
+    if(needsSignal) {
+        this.$run = this.$runWithAbortController;
+        return this.$runWithAbortController(isRefetch);
+    }
+    this.$run = this.$runWithoutAbortController;
+
+    return this.$run(isRefetch);
+};
+
+ObservableResource.prototype.$watchDependencies = function() {
+    this.$subscriptions.forEach(unsub => unsub());
+    this.$subscriptions = [];
+
+    this.$dependencies.forEach(dep => {
+        const callback = () => this.$run(true);
+        dep.subscribe(callback);
+        this.$subscriptions.push(() => dep.unsubscribe(callback));
+    });
+    if (!this.$config.lazy) {
+        this.$run(false);
+    }
+};
+
+/**
+ * Sets a custom function to apply fetched results to this.data.
+ * Useful when the raw response needs transformation before storing.
+ *
+ * @param {(result: *, data: ObservableItem) => void} fn - Function receiving the result and the data observable
+ * @returns {this}
+ * @example
+ * resource.apply((result, data) => data.set(result.items));
+ */
+ObservableResource.prototype.apply = function(fn) {
+    this.$config.apply = fn;
+    return this;
+};
+
+/**
+ * Redirects fetched results into an existing ObservableItem instead of the default internal one.
+ * Updates both this.data reference and config.into.
+ *
+ * @param {ObservableItem} $observable - Target observable to write results into
+ * @returns {this}
+ * @example
+ * const items = Observable([]);
+ * resource.into(items);
+ */
+ObservableResource.prototype.into = function($observable) {
+    this.$config.into = $observable;
+    this.data = $observable;
+    return this;
+};
+
+/**
+ * Triggers a fresh fetch (state transitions to 'pending').
+ * Use when no prior data exists or when a full reload is needed.
+ *
+ * @returns {this}
+ */
+ObservableResource.prototype.fetch = function() {
+    this.$run(false);
+    return this;
+};
+
+/**
+ * Triggers a re-fetch (state transitions to 'refreshing' if data already exists).
+ * Use when you want to reload while keeping the previous data visible.
+ *
+ * @returns {this}
+ */
+ObservableResource.prototype.refetch = function() {
+    this.$run(true);
+    return this;
+};
+
+/**
+ * Manually sets the data value and marks the state as 'ready'.
+ * Useful for optimistic updates or seeding initial data without a network call.
+ *
+ * @param {*} value - New value to set on this.data
+ * @returns {this}
+ * @example
+ * resource.mutate([...resource.data.val(), newItem]);
+ */
+ObservableResource.prototype.mutate = function(value) {
+    this.data.set(value);
+    this.state.set(STATE.READY);
+    return this;
+};
+
+/**
+ * Cancels any pending request, unsubscribes from all dependencies, and clears subscriptions.
+ * Call this when the component using this resource is unmounted.
+ *
+ * @returns {void}
+ */
+ObservableResource.prototype.destroy = function() {
+    this.$abort();
+    this.$subscriptions.forEach(unsub => unsub());
+    this.$subscriptions = [];
+};
+
+/**
+ * Returns a derived observable that emits true when the state is 'ready'.
+ *
+ * @returns {ObservableChecker<boolean>}
+ */
+ObservableResource.prototype.isReady = function() {
+    return this.state.isEqualTo(STATE.READY);
+};
+
+/**
+ * Returns a derived observable that emits true when the state is 'pending' (initial load).
+ *
+ * @returns {ObservableChecker<boolean>}
+ */
+ObservableResource.prototype.isPending = function() {
+    return this.state.isEqualTo(STATE.PENDING);
+};
+
+/**
+ * Returns a derived observable that emits true when the state is 'refreshing' (reload with existing data).
+ *
+ * @returns {ObservableChecker<boolean>}
+ */
+ObservableResource.prototype.isRefreshing = function() {
+    return this.state.isEqualTo(STATE.REFRESHING);
+};
+
+/**
+ * Returns a derived observable that emits true when the state is 'errored'.
+ *
+ * @returns {ObservableChecker<boolean>}
+ */
+ObservableResource.prototype.isErrored = function() {
+    return this.state.isEqualTo(STATE.ERRORED);
+};
+
+/**
+ * Returns a derived observable that emits true when no fetch has been triggered yet.
+ *
+ * @returns {ObservableChecker<boolean>}
+ */
+ObservableResource.prototype.isUnresolved = function() {
+    return this.state.isEqualTo(STATE.UNRESOLVED);
+};
+
+/**
+ * Registers a callback that is called every time a fetch completes successfully.
+ *
+ * @param {(value: *) => void} callback - Called with the fetched data value
+ * @returns {this}
+ * @example
+ * resource.onSuccess((data) => console.log('Loaded:', data));
+ */
+ObservableResource.prototype.onSuccess = function(callback) {
+    this.data.subscribe((value) => {
+        if (this.state.val() === STATE.READY) {
+            callback(value);
+        }
+    });
+    return this;
+};
+
+/**
+ * Registers a callback called every time a fetch fails.
+ *
+ * @param {(error: Error) => void} callback - Called with the error object
+ * @returns {this}
+ * @example
+ * resource.onError((err) => console.error('Failed:', err.message));
+ */
+ObservableResource.prototype.onError = function(callback) {
+    this.error.subscribe((err) => {
+        if (err !== null) {
+            callback(err);
+        }
+    });
+    return this;
+};

package/src/core/data/ObservableWhen.js

@@ -0,0 +1,54 @@
+
+/**
+ * Creates an ObservableWhen that tracks whether an observable equals a specific value.
+ *
+ * @param {ObservableItem} observer - The observable to watch
+ * @param {*} value - The value to compare against
+ * @class ObservableWhen
+ */
+export const ObservableWhen = function(observer, value) {
+    this.$target = value;
+    this.$observer = observer;
+};
+
+ObservableWhen.prototype.__$Observable = true;
+ObservableWhen.prototype.__$isObservableWhen = true;
+
+/**
+ * Subscribes to changes in the match status (true when observable equals target value).
+ *
+ * @param {Function} callback - Function called with boolean indicating if values match
+ * @returns {Function} Unsubscribe function
+ * @example
+ * const status = Observable('idle');
+ * const isLoading = status.when('loading');
+ * isLoading.subscribe(active => console.log('Loading:', active));
+ */
+ObservableWhen.prototype.subscribe = function(callback) {
+    return this.$observer.on(this.$target, callback);
+};
+
+/**
+ * Returns true if the observable's current value equals the target value.
+ *
+ * @returns {boolean} True if observable value matches target value
+ */
+ObservableWhen.prototype.val = function() {
+    return this.$observer.$currentValue === this.$target;
+};
+
+/**
+ * Returns true if the observable's current value equals the target value.
+ * Alias for val().
+ *
+ * @returns {boolean} True if observable value matches target value
+ */
+ObservableWhen.prototype.isMatch = ObservableWhen.prototype.val;
+
+/**
+ * Returns true if the observable's current value equals the target value.
+ * Alias for val().
+ *
+ * @returns {boolean} True if observable value matches target value
+ */
+ObservableWhen.prototype.isActive = ObservableWhen.prototype.val;