native-document 1.0.165 → 1.0.168

package/src/core/data/ObservableResource.js

@@ -1,5 +1,5 @@
-import ObservableItem from "./ObservableItem";
-import {debounce} from "../utils/helpers";
+import ObservableItem from './ObservableItem';
+import {debounce} from '../utils/helpers';
 
 const STATE = {
     UNRESOLVED: 'unresolved',
@@ -9,6 +9,28 @@ const STATE = {
     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;
@@ -22,7 +44,7 @@ export default function ObservableResource(fn, deps, config) {
 
     this.loading = ObservableItem.computed(
         (state) => state === STATE.PENDING || state === STATE.REFRESHING,
-        [this.state]
+        [this.state],
     );
 
     if (config.auto) {
@@ -104,6 +126,11 @@ ObservableResource.prototype.$runWithoutAbortController = function(isRefetch = f
         });
 };
 
+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) {
@@ -129,58 +156,138 @@ ObservableResource.prototype.$watchDependencies = function() {
     }
 };
 
+/**
+ * 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) {
@@ -190,6 +297,14 @@ ObservableResource.prototype.onSuccess = function(callback) {
     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) {

package/src/core/data/Store.js

@@ -1,7 +1,14 @@
-import { Observable } from "./Observable";
-import NativeDocumentError from "../errors/NativeDocumentError";
-import DebugManager from "../utils/debug-manager";
-import {$getFromStorage, $saveToStorage, LocalStorage} from "../utils/localstorage";
+import { Observable } from './Observable';
+import NativeDocumentError from '../errors/NativeDocumentError';
+import DebugManager from '../utils/debug-manager';
+import {$getFromStorage, $saveToStorage, LocalStorage} from '../utils/localstorage';
+import Validator from '../utils/validator';
+
+
+const WRITE_METHODS = [
+    'use', 'get', 'create', 'createResettable', 'createComposed',
+    'createPersistent', 'createPersistentResettable', 'delete', 'reset',
+];
 
 export const StoreFactory = function() {
 
@@ -16,7 +23,7 @@ export const StoreFactory = function() {
         if (!item) {
             DebugManager.error('Store', `Store.${method}('${name}') : store not found. Did you call Store.create('${name}') first?`);
             throw new NativeDocumentError(
-                `Store.${method}('${name}') : store not found.`
+                `Store.${method}('${name}') : store not found.`,
             );
         }
         return item;
@@ -29,7 +36,7 @@ export const StoreFactory = function() {
         const readOnlyError = (method) => () => {
             DebugManager.error('Store', `Store.${context}('${name}') is read-only. '${method}()' is not allowed.`);
             throw new NativeDocumentError(
-                `Store.${context}('${name}') is read-only.`
+                `Store.${context}('${name}') is read-only.`,
             );
         };
         observer.set    = readOnlyError('set');
@@ -41,11 +48,11 @@ export const StoreFactory = function() {
         if(Array.isArray(value)) {
             return Observable.array(value, options);
         }
-        if(typeof value === 'object') {
+        if(Validator.isJson(value)) {
             return Observable.object(value, options);
         }
         return Observable(value, options);
-    }
+    };
 
     const $api = {
         /**
@@ -60,10 +67,10 @@ export const StoreFactory = function() {
             if ($stores.has(name)) {
                 DebugManager.warn('Store', `Store.create('${name}') : a store with this name already exists. Use Store.get('${name}') to retrieve it.`);
                 throw new NativeDocumentError(
-                    `Store.create('${name}') : a store with this name already exists.`
+                    `Store.create('${name}') : a store with this name already exists.`,
                 );
             }
-            const observer = $createObservable(value)
+            const observer = $createObservable(value);
             $stores.set(name, { observer, subscribers: new Set(), resettable: false, composed: false });
             return observer;
         },
@@ -81,7 +88,7 @@ export const StoreFactory = function() {
             if ($stores.has(name)) {
                 DebugManager.warn('Store', `Store.createResettable('${name}') : a store with this name already exists.`);
                 throw new NativeDocumentError(
-                    `Store.createResettable('${name}') : a store with this name already exists.`
+                    `Store.createResettable('${name}') : a store with this name already exists.`,
                 );
             }
             const observer = $createObservable(value, { reset: true });
@@ -117,17 +124,17 @@ export const StoreFactory = function() {
             if ($stores.has(name)) {
                 DebugManager.warn('Store', `Store.createComposed('${name}') : a store with this name already exists.`);
                 throw new NativeDocumentError(
-                    `Store.createComposed('${name}') : a store with this name already exists.`
+                    `Store.createComposed('${name}') : a store with this name already exists.`,
                 );
             }
             if (typeof computation !== 'function') {
                 throw new NativeDocumentError(
-                    `Store.createComposed('${name}') : computation must be a function.`
+                    `Store.createComposed('${name}') : computation must be a function.`,
                 );
             }
             if (!Array.isArray(dependencies) || dependencies.length === 0) {
                 throw new NativeDocumentError(
-                    `Store.createComposed('${name}') : dependencies must be a non-empty array of store names.`
+                    `Store.createComposed('${name}') : dependencies must be a non-empty array of store names.`,
                 );
             }
 
@@ -140,7 +147,7 @@ export const StoreFactory = function() {
                 if (!depItem) {
                     DebugManager.error('Store', `Store.createComposed('${name}') : dependency '${depName}' not found. Create it first.`);
                     throw new NativeDocumentError(
-                        `Store.createComposed('${name}') : dependency store '${depName}' not found.`
+                        `Store.createComposed('${name}') : dependency store '${depName}' not found.`,
                     );
                 }
                 return depItem.observer;
@@ -174,13 +181,13 @@ export const StoreFactory = function() {
             if (item.composed) {
                 DebugManager.error('Store', `Store.reset('${name}') : composed stores cannot be reset. Their value is derived from dependencies.`);
                 throw new NativeDocumentError(
-                    `Store.reset('${name}') : composed stores cannot be reset.`
+                    `Store.reset('${name}') : composed stores cannot be reset.`,
                 );
             }
             if (!item.resettable) {
                 DebugManager.error('Store', `Store.reset('${name}') : this store is not resettable. Use Store.createResettable('${name}', value) instead of Store.create().`);
                 throw new NativeDocumentError(
-                    `Store.reset('${name}') : this store is not resettable. Use Store.createResettable('${name}', value) instead of Store.create().`
+                    `Store.reset('${name}') : this store is not resettable. Use Store.createResettable('${name}', value) instead of Store.create().`,
                 );
             }
             item.observer.reset();
@@ -201,7 +208,7 @@ export const StoreFactory = function() {
             if (item.composed) {
                 DebugManager.error('Store', `Store.use('${name}') : composed stores are read-only. Use Store.follow('${name}') instead.`);
                 throw new NativeDocumentError(
-                    `Store.use('${name}') : composed stores are read-only. Use Store.follow('${name}') instead.`
+                    `Store.use('${name}') : composed stores are read-only. Use Store.follow('${name}') instead.`,
                 );
             }
 
@@ -239,7 +246,9 @@ export const StoreFactory = function() {
             const { observer: originalObserver, subscribers } = $getStoreOrThrow('follow', name);
             const observerFollower = $createObservable(originalObserver.val());
 
-            const onStoreChange = value => observerFollower.set(value);
+            const originalSet = observerFollower.set.bind(observerFollower);
+            const onStoreChange = value => originalSet(value);
+
             originalObserver.subscribe(onStoreChange);
 
             $applyReadOnly(observerFollower, name, 'follow');
@@ -295,6 +304,7 @@ export const StoreFactory = function() {
             item.subscribers.clear();
             item.observer.cleanup();
             $stores.delete(name);
+            $followersCache.delete(name);
         },
         /**
          * Creates an isolated store group with its own state namespace.
@@ -349,18 +359,60 @@ export const StoreFactory = function() {
             callback && callback(store);
             return store;
         },
+
+        /**
+         * Creates a store that is automatically persisted to localStorage.
+         * On creation, the store is initialized with the value from localStorage
+         * if it exists, otherwise falls back to the provided default value.
+         * Every mutation is automatically saved to localStorage.
+         *
+         * @param {string} name - Store name
+         * @param {*} value - Default value if nothing is found in localStorage
+         * @param {string} [localstorage_key] - Custom localStorage key. Defaults to the store name.
+         * @returns {ObservableItem}
+         *
+         * @example
+         * const $theme = Store.createPersistent('theme', 'light');
+         *
+         * $theme.set('dark'); // saved to localStorage automatically
+         *
+         * // With a custom key
+         * const $lang = Store.createPersistent('language', 'en', 'nd:lang');
+         */
         createPersistent(name, value, localstorage_key) {
             localstorage_key = localstorage_key || name;
             const observer = this.create(name, $getFromStorage(localstorage_key, value));
-            const saver = $saveToStorage(value)
+            const saver = $saveToStorage(value);
 
             observer.subscribe((val) => saver(localstorage_key, val));
             return observer;
         },
+
+        /**
+         * Creates a resettable store that is automatically persisted to localStorage.
+         * On creation, the store is initialized with the value from localStorage
+         * if it exists, otherwise falls back to the provided default value.
+         * Every mutation is automatically saved to localStorage.
+         * Calling reset() restores the initial value AND removes the localStorage entry.
+         *
+         * @param {string} name - Store name
+         * @param {*} value - Default value if nothing is found in localStorage
+         * @param {string} [localstorage_key] - Custom localStorage key. Defaults to the store name.
+         * @returns {ObservableItem}
+         *
+         * @example
+         * const $filters = Store.createPersistentResettable('filters', { category: null, date: null });
+         *
+         * $filters.set({ category: 'news', date: '2024-01-01' }); // saved to localStorage
+         * $filters.reset(); // restored to { category: null, date: null } + localStorage entry removed
+         *
+         * // With a custom key
+         * const $prefs = Store.createPersistentResettable('preferences', { lang: 'en' }, 'nd:prefs');
+         */
         createPersistentResettable(name, value, localstorage_key) {
             localstorage_key = localstorage_key || name;
             const observer = this.createResettable(name, $getFromStorage(localstorage_key, value));
-            const saver = $saveToStorage(value)
+            const saver = $saveToStorage(value);
             observer.subscribe((val) => saver(localstorage_key, val));
 
             const originalReset = observer.reset.bind(observer);
@@ -370,7 +422,68 @@ export const StoreFactory = function() {
             };
 
             return observer;
-        }
+        },
+        /**
+         * Returns a read-only proxy of this store.
+         * All write operations (use, get, create, createResettable, createComposed,
+         * createPersistent, createPersistentResettable, delete, reset) will throw.
+         * Property access returns a read-only follower via follow().
+         *
+         * The recommended pattern is to keep the original store private
+         * and export only the protected version as the public contract.
+         *
+         * @returns {Proxy}
+         *
+         * @example
+         * // store/user.store.js
+         *
+         * const PrivateUserStore = Store.group('user', (group) => {
+         *     group.create('profile', null);
+         *     group.create('role', 'viewer');
+         *     group.create('token', null);
+         * });
+         *
+         * // Only the read-only version is exported
+         * export const UserStore = PrivateUserStore.protected();
+         *
+         * // --- In any other module ---
+         *
+         * import { UserStore } from './store/user.store.js';
+         *
+         * UserStore.profile // ✅ follower read-only
+         * UserStore.follow('role') // ✅
+         * UserStore.has('token') // ✅
+         *
+         * UserStore.use('profile') // ❌ throws — read-only store
+         * UserStore.get('profile') // ❌ throws — read-only store
+         * UserStore.create('x', 1) // ❌ throws — read-only store
+         */
+        protected() {
+            return new Proxy($api, {
+                get(target, prop) {
+                    if (typeof prop === 'symbol' || prop.startsWith('$')) {
+                        return target[prop];
+                    }
+                    if (WRITE_METHODS.includes(prop)) {
+                        return () => {
+                            throw new NativeDocumentError(
+                                `Store.${prop}() is not allowed on a read-only store. Use the original store reference instead.`
+                            );
+                        };
+                    }
+                    if (target.has(prop)) {
+                        return target.follow(prop);
+                    }
+                    return target[prop];
+                },
+                set() {
+                    throw new NativeDocumentError('This store is read-only.');
+                },
+                deleteProperty() {
+                    throw new NativeDocumentError('This store is read-only.');
+                },
+            });
+        },
     };
 
 
@@ -391,14 +504,17 @@ export const StoreFactory = function() {
         },
         set(target, prop, value) {
             DebugManager.error('Store', `Forbidden: You cannot overwrite the store key '${String(prop)}'. Use .use('${String(prop)}').set(value) instead.`);
-            throw new NativeDocumentError(`Store structure is immutable. Use .set() on the observable.`);
+            throw new NativeDocumentError('Store structure is immutable. Use .set() on the observable.');
         },
         deleteProperty(target, prop) {
-            throw new NativeDocumentError(`Store keys cannot be deleted.`);
-        }
+            throw new NativeDocumentError('Store keys cannot be deleted.');
+        },
     });
 };
 
 export const Store = StoreFactory();
 
-Store.create('locale', navigator.language.split('-')[0] || 'en');
+Store.create(
+    'locale',
+    (typeof navigator !== 'undefined' ? navigator.language.split('-')[0] : 'en') || 'en'
+);