@coherent.js/state 1.1.2 → 2.0.0

package/dist/reactive-state.js

@@ -14,11 +14,107 @@ var globalErrorHandler = {
     console.error("State Error:", error.message, context);
   }
 };
-var Observable = class _Observable {
+var MAX_FLUSH_ITERATIONS = 100;
+var activeComputed = null;
+var batchDepth = 0;
+var flushing = false;
+var pendingObservables = /* @__PURE__ */ new Map();
+var pendingComputeds = /* @__PURE__ */ new Set();
+var globalVersion = 0;
+function reportError(source, error, type, context = {}) {
+  const onError = source?._options?.onError;
+  if (typeof onError === "function") {
+    try {
+      onError(error, { type, ...context });
+      return;
+    } catch (handlerError) {
+      error = handlerError;
+    }
+  }
+  globalErrorHandler.handle(error, { type, context });
+}
+function runObserver(source, observer, newValue, oldValue) {
+  try {
+    observer.callback(newValue, oldValue, observer.unwatch);
+  } catch (error) {
+    reportError(source, error, "watcher-error", { newValue, oldValue });
+  }
+}
+function flush() {
+  flushing = true;
+  let iterations = 0;
+  try {
+    while (pendingObservables.size > 0 || pendingComputeds.size > 0) {
+      if (++iterations > MAX_FLUSH_ITERATIONS) {
+        const culprits = [...pendingObservables.keys(), ...pendingComputeds];
+        pendingObservables.clear();
+        pendingComputeds.clear();
+        reportError(
+          culprits[0],
+          new StateError(
+            `Watchers kept changing state after ${MAX_FLUSH_ITERATIONS} rounds; a watcher probably writes a new value to a state it (indirectly) watches.`,
+            { type: "update-depth" }
+          ),
+          "update-depth"
+        );
+        return;
+      }
+      const observables = [...pendingObservables];
+      pendingObservables.clear();
+      for (const [source, oldValue] of observables) {
+        const newValue = source._value;
+        if (!source._changed(oldValue, newValue)) continue;
+        for (const observer of [...source._observers]) {
+          if (source._observers.has(observer)) {
+            runObserver(source, observer, newValue, oldValue);
+          }
+        }
+      }
+      const computeds = [...pendingComputeds];
+      pendingComputeds.clear();
+      for (const source of computeds) {
+        if (source._observers.size === 0) continue;
+        try {
+          source._refresh();
+        } catch (error) {
+          reportError(source, error, "computed-error");
+          continue;
+        }
+        const newValue = source._value;
+        const oldValue = source._lastNotified;
+        if (Object.is(newValue, oldValue)) continue;
+        source._lastNotified = newValue;
+        for (const observer of [...source._observers]) {
+          if (source._observers.has(observer)) {
+            runObserver(source, observer, newValue, oldValue);
+          }
+        }
+      }
+    }
+  } finally {
+    flushing = false;
+  }
+}
+function scheduleFlush() {
+  if (batchDepth === 0 && !flushing) {
+    flush();
+  }
+}
+function batch(fn) {
+  batchDepth++;
+  try {
+    return fn();
+  } finally {
+    batchDepth--;
+    scheduleFlush();
+  }
+}
+var Observable = class {
   constructor(value, options = {}) {
     this._value = value;
+    this._version = 0;
     this._observers = /* @__PURE__ */ new Set();
-    this._computedDependents = /* @__PURE__ */ new Set();
+    this._subscribers = /* @__PURE__ */ new Set();
     this._options = {
       deep: options.deep !== false,
       immediate: options.immediate !== false,
@@ -26,107 +122,281 @@ var Observable = class _Observable {
     };
   }
   get value() {
-    if (_Observable._currentComputed) {
-      this._computedDependents.add(_Observable._currentComputed);
-    }
+    activeComputed?._track(this);
     return this._value;
   }
   set value(newValue) {
-    if (this._value === newValue && !this._options.deep) {
+    this._write(newValue);
+  }
+  /** Read without registering a dependency. */
+  peek() {
+    return this._value;
+  }
+  /**
+   * Whether a write from `oldValue` to `newValue` is a change. Identical
+   * primitives never are; with `deep` (the default) re-assigning the same
+   * object is, since it may have been mutated in place.
+   * @private
+   */
+  _changed(oldValue, newValue) {
+    if (!Object.is(oldValue, newValue)) return true;
+    return this._options.deep && newValue !== null && typeof newValue === "object";
+  }
+  /** @private */
+  _write(newValue) {
+    const oldValue = this._value;
+    if (!this._changed(oldValue, newValue)) {
       return;
     }
-    const oldValue = this._value;
     this._value = newValue;
-    this._observers.forEach((observer) => {
-      try {
-        observer(newValue, oldValue);
-      } catch (_error) {
-        globalErrorHandler.handle(_error, {
-          type: "watcher-_error",
-          context: { newValue, oldValue }
-        });
-      }
-    });
-    this._computedDependents.forEach((computed2) => {
-      computed2._invalidate();
-    });
+    this._version++;
+    globalVersion++;
+    for (const subscriber of [...this._subscribers]) {
+      subscriber._markDirty();
+    }
+    if (this._observers.size > 0 && !pendingObservables.has(this)) {
+      pendingObservables.set(this, oldValue);
+    }
+    scheduleFlush();
+  }
+  /** @private */
+  _addSubscriber(computed2) {
+    this._subscribers.add(computed2);
+  }
+  /** @private */
+  _removeSubscriber(computed2) {
+    this._subscribers.delete(computed2);
+  }
+  /** @private */
+  _addObserver(observer) {
+    this._observers.add(observer);
+  }
+  /** @private */
+  _removeObserver(observer) {
+    this._observers.delete(observer);
   }
   watch(callback, options = {}) {
     if (typeof callback !== "function") {
       throw new StateError("Watch callback must be a function");
     }
-    const observer = (newValue, oldValue) => {
-      callback(newValue, oldValue, () => this.unwatch(observer));
-    };
-    this._observers.add(observer);
+    const observer = { callback, unwatch: null };
+    observer.unwatch = () => this._removeObserver(observer);
+    this._addObserver(observer);
     if (options.immediate !== false) {
-      observer(this._value, void 0);
+      runObserver(this, observer, this._value, void 0);
     }
-    return () => this.unwatch(observer);
+    return observer.unwatch;
   }
-  unwatch(observer) {
-    this._observers.delete(observer);
+  /**
+   * Remove a watcher, by the callback passed to watch()
+   * @param {Function} callback
+   */
+  unwatch(callback) {
+    for (const observer of [...this._observers]) {
+      if (observer.callback === callback || observer.unwatch === callback) {
+        this._removeObserver(observer);
+      }
+    }
   }
+  /** Remove every watcher. */
   unwatchAll() {
-    this._observers.clear();
-    this._computedDependents.clear();
+    for (const observer of [...this._observers]) {
+      this._removeObserver(observer);
+    }
   }
 };
-var Computed = class extends Observable {
+var Computed = class _Computed extends Observable {
   constructor(getter, options = {}) {
-    super(void 0, options);
-    this._getter = getter;
-    this._cached = false;
-    this._dirty = true;
     if (typeof getter !== "function") {
       throw new StateError("Computed getter must be a function");
     }
+    super(void 0, options);
+    this._getter = getter;
+    this._deps = /* @__PURE__ */ new Map();
+    this._dirty = true;
+    this._computing = false;
+    this._globalVersionSeen = -1;
+    this._lastNotified = void 0;
   }
   get value() {
-    if (this._dirty || !this._cached) {
-      this._compute();
-    }
+    this._refresh();
+    activeComputed?._track(this);
     return this._value;
   }
-  set value(newValue) {
+  set value(_newValue) {
     throw new StateError("Cannot set value on computed property");
   }
-  _compute() {
-    const prevComputed = Observable._currentComputed;
-    Observable._currentComputed = this;
-    try {
-      const newValue = this._getter();
-      if (newValue !== this._value) {
-        const oldValue = this._value;
-        this._value = newValue;
-        this._observers.forEach((observer) => {
-          observer(newValue, oldValue);
-        });
-      }
-      this._cached = true;
-      this._dirty = false;
-    } catch (_error) {
-      globalErrorHandler.handle(_error, {
-        type: "computed-_error",
-        context: { getter: this._getter.toString() }
+  peek() {
+    this._refresh();
+    return this._value;
+  }
+  /** Watched, or a dependency of a live computed. @private */
+  get _live() {
+    return this._observers.size > 0 || this._subscribers.size > 0;
+  }
+  /** @private */
+  _track(source) {
+    if (!this._deps.has(source)) {
+      this._deps.set(source, source._version);
+    }
+  }
+  /** Bring the cached value up to date. @private */
+  _refresh() {
+    if (this._computing) {
+      throw new StateError("Circular dependency between computed properties", {
+        type: "computed-cycle",
+        context: { getter: this._getter.name || "anonymous" }
       });
+    }
+    if (!this._dirty) {
+      if (this._live || this._globalVersionSeen === globalVersion) return;
+      if (!this._dependenciesChanged()) {
+        this._globalVersionSeen = globalVersion;
+        return;
+      }
+    }
+    this._recompute();
+  }
+  /** @private */
+  _dependenciesChanged() {
+    for (const [source, version] of this._deps) {
+      if (source instanceof _Computed) {
+        source._refresh();
+      }
+      if (source._version !== version) return true;
+    }
+    return false;
+  }
+  /** @private */
+  _recompute() {
+    const previousDeps = this._deps;
+    const previousActive = activeComputed;
+    this._deps = /* @__PURE__ */ new Map();
+    this._computing = true;
+    activeComputed = this;
+    let newValue;
+    try {
+      newValue = this._getter();
+    } catch (error) {
+      this._deps = previousDeps;
+      this._dirty = true;
+      throw error;
     } finally {
-      Observable._currentComputed = prevComputed;
+      this._computing = false;
+      activeComputed = previousActive;
+    }
+    if (this._live) {
+      for (const source of previousDeps.keys()) {
+        if (!this._deps.has(source)) source._removeSubscriber(this);
+      }
+      for (const source of this._deps.keys()) {
+        if (!previousDeps.has(source)) source._addSubscriber(this);
+      }
+    }
+    this._dirty = false;
+    this._globalVersionSeen = globalVersion;
+    if (!Object.is(newValue, this._value)) {
+      this._value = newValue;
+      this._version++;
     }
   }
-  _invalidate() {
+  /** A dependency changed. @private */
+  _markDirty() {
+    if (this._dirty) return;
     this._dirty = true;
-    this._computedDependents.forEach((computed2) => {
-      computed2._invalidate();
-    });
+    if (this._observers.size > 0) {
+      pendingComputeds.add(this);
+    }
+    for (const subscriber of [...this._subscribers]) {
+      subscriber._markDirty();
+    }
+  }
+  /** Subscribe to dependencies. @private */
+  _goLive() {
+    this._refresh();
+    for (const source of this._deps.keys()) {
+      source._addSubscriber(this);
+    }
+  }
+  /** Unsubscribe from dependencies. @private */
+  _goLazy() {
+    for (const source of this._deps.keys()) {
+      source._removeSubscriber(this);
+    }
+  }
+  /** @private */
+  _addSubscriber(computed2) {
+    const wasLive = this._live;
+    this._subscribers.add(computed2);
+    if (!wasLive) this._goLive();
+  }
+  /** @private */
+  _removeSubscriber(computed2) {
+    this._subscribers.delete(computed2);
+    if (!this._live) this._goLazy();
+  }
+  /** @private */
+  _addObserver(observer) {
+    const hadObservers = this._observers.size > 0;
+    const wasLive = this._live;
+    this._observers.add(observer);
+    try {
+      if (wasLive) {
+        this._refresh();
+      } else {
+        this._goLive();
+      }
+    } catch (error) {
+      this._observers.delete(observer);
+      throw error;
+    }
+    if (!hadObservers) {
+      this._lastNotified = this._value;
+    }
+  }
+  /** @private */
+  _removeObserver(observer) {
+    if (!this._observers.delete(observer)) return;
+    if (!this._live) this._goLazy();
   }
 };
-Observable._currentComputed = null;
+var ABSENT = /* @__PURE__ */ Symbol("absent");
+function isPath(key) {
+  return typeof key === "string" && key.includes(".");
+}
+function readPath(value, segments) {
+  let current = value;
+  for (const segment of segments) {
+    if (current === null || current === void 0) return void 0;
+    current = current[segment];
+  }
+  return current;
+}
+function writePath(target, segments, value) {
+  const [head, ...rest] = segments;
+  const base = target !== null && typeof target === "object" ? Array.isArray(target) ? [...target] : { ...target } : {};
+  const next = rest.length === 0 ? value : writePath(base[head], rest, value);
+  Object.defineProperty(base, head, { value: next, enumerable: true, writable: true, configurable: true });
+  return base;
+}
+function deletePath(target, segments) {
+  if (target === null || typeof target !== "object") return target;
+  const [head, ...rest] = segments;
+  if (!Object.prototype.hasOwnProperty.call(target, head)) return target;
+  const base = Array.isArray(target) ? [...target] : { ...target };
+  if (rest.length === 0) {
+    delete base[head];
+  } else {
+    base[head] = deletePath(base[head], rest);
+  }
+  return base;
+}
 var ReactiveState = class {
   constructor(initialState = {}, options = {}) {
     this._state = /* @__PURE__ */ new Map();
     this._computed = /* @__PURE__ */ new Map();
     this._watchers = /* @__PURE__ */ new Map();
+    this._expressionWatchers = /* @__PURE__ */ new Set();
     this._middleware = [];
     this._history = [];
     this._options = {
@@ -140,57 +410,115 @@ var ReactiveState = class {
       this.set(key, value);
     });
   }
+  /** Observable for a key, created as an absent placeholder if needed. @private */
+  _observable(key) {
+    let observable2 = this._state.get(key);
+    if (!observable2) {
+      observable2 = new Observable(ABSENT, this._options);
+      this._state.set(key, observable2);
+    }
+    return observable2;
+  }
+  /** Whether a key is stored under its full name. @private */
+  _hasOwnKey(key) {
+    const observable2 = this._state.get(key);
+    return Boolean(observable2) && observable2._value !== ABSENT;
+  }
+  /** [rootKey, pathSegments] for a dot path, or null for a plain key. @private */
+  _splitPath(key) {
+    if (!isPath(key)) return null;
+    const [root, ...segments] = key.split(".");
+    return [root, segments];
+  }
   /**
    * Get reactive state value
    */
   get(key) {
-    const observable2 = this._state.get(key);
-    return observable2 ? observable2.value : void 0;
+    const path = this._splitPath(key);
+    if (path) {
+      return readPath(this.get(path[0]), path[1]);
+    }
+    const observable2 = activeComputed ? this._observable(key) : this._state.get(key);
+    if (!observable2) return void 0;
+    const value = observable2.value;
+    return value === ABSENT ? void 0 : value;
   }
   /**
    * Set reactive state value
    */
   set(key, value, options = {}) {
     const config = { ...this._options, ...options };
+    const oldValue = this.get(key);
     if (config.enableMiddleware) {
-      const middlewareResult = this._runMiddleware("set", { key, value, oldValue: this.get(key) });
+      const middlewareResult = this._runMiddleware("set", { key, value, oldValue });
       if (middlewareResult.cancelled) {
         return false;
       }
       value = middlewareResult.value !== void 0 ? middlewareResult.value : value;
     }
-    let observable2 = this._state.get(key);
-    if (!observable2) {
-      observable2 = new Observable(value, config);
-      this._state.set(key, observable2);
-    } else {
+    const path = this._splitPath(key);
+    if (path) {
+      const [root, segments] = path;
       if (config.enableHistory) {
-        this._addToHistory("set", key, observable2.value, value);
+        this._addToHistory("set", key, oldValue, value);
       }
-      observable2.value = value;
+      this._writeKey(root, writePath(this.get(root), segments, value));
+      return true;
+    }
+    if (config.enableHistory && this._hasOwnKey(key)) {
+      this._addToHistory("set", key, oldValue, value);
     }
+    this._writeKey(key, value);
     return true;
   }
+  /** @private */
+  _writeKey(key, value) {
+    this._observable(key)._write(value);
+  }
   /**
    * Check if state has a key
    */
   has(key) {
-    return this._state.has(key);
+    const path = this._splitPath(key);
+    if (path) {
+      const parent = readPath(this.get(path[0]), path[1].slice(0, -1));
+      return parent !== null && typeof parent === "object" && Object.prototype.hasOwnProperty.call(parent, path[1][path[1].length - 1]);
+    }
+    return this._hasOwnKey(key);
   }
   /**
-   * Delete state key
+   * Delete state key. Its watchers are removed; computed properties that
+   * read it update.
    */
   delete(key) {
-    const observable2 = this._state.get(key);
-    if (observable2) {
+    const path = this._splitPath(key);
+    if (path) {
+      if (!this.has(key)) return false;
       if (this._options.enableHistory) {
-        this._addToHistory("delete", key, observable2.value, void 0);
+        this._addToHistory("delete", key, this.get(key), void 0);
       }
-      observable2.unwatchAll();
-      this._state.delete(key);
+      this._writeKey(path[0], deletePath(this.get(path[0]), path[1]));
       return true;
     }
-    return false;
+    if (!this._hasOwnKey(key)) {
+      return false;
+    }
+    const observable2 = this._state.get(key);
+    if (this._options.enableHistory) {
+      this._addToHistory("delete", key, observable2._value, void 0);
+    }
+    observable2.unwatchAll();
+    this._releaseKeyWatchers(key);
+    observable2._write(ABSENT);
+    return true;
+  }
+  /** @private */
+  _releaseKeyWatchers(key) {
+    const unwatchers = this._watchers.get(key);
+    if (unwatchers) {
+      for (const unwatch of unwatchers) unwatch();
+      this._watchers.delete(key);
+    }
   }
   /**
    * Clear all state
@@ -199,10 +527,13 @@ var ReactiveState = class {
     if (this._options.enableHistory) {
       this._addToHistory("clear", null, this.toObject(), {});
     }
-    for (const observable2 of this._state.values()) {
-      observable2.unwatchAll();
-    }
-    this._state.clear();
+    batch(() => {
+      for (const [key, observable2] of this._state) {
+        observable2.unwatchAll();
+        this._releaseKeyWatchers(key);
+        observable2._write(ABSENT);
+      }
+    });
     this._computed.clear();
     this._watchers.clear();
   }
@@ -225,40 +556,62 @@ var ReactiveState = class {
     return computed2 ? computed2.value : void 0;
   }
   /**
-   * Watch state changes
+   * Watch state changes: a key, a dot path into a key, or a getter
+   * expression (re-evaluated whenever what it reads changes).
    */
   watch(key, callback, options = {}) {
     if (typeof key === "function") {
       return this._watchComputed(key, callback, options);
     }
-    const observable2 = this._state.get(key);
-    if (!observable2) {
+    const path = this._splitPath(key);
+    if (path) {
+      if (!this._hasOwnKey(path[0])) {
+        throw new StateError(`Cannot watch undefined state key: ${path[0]}`);
+      }
+      const computed2 = new Computed(() => this.get(key), { ...this._options, ...options });
+      return this._track(key, computed2.watch(callback, options));
+    }
+    if (!this._hasOwnKey(key)) {
       throw new StateError(`Cannot watch undefined state key: ${key}`);
     }
-    const unwatch = observable2.watch(callback, options);
+    return this._track(key, this._state.get(key).watch(callback, options));
+  }
+  /** Remember an unwatch function for cleanup. @private */
+  _track(key, unwatch) {
     if (!this._watchers.has(key)) {
       this._watchers.set(key, /* @__PURE__ */ new Set());
     }
-    this._watchers.get(key).add(unwatch);
-    return unwatch;
+    const unwatchers = this._watchers.get(key);
+    const release = () => {
+      unwatch();
+      unwatchers.delete(release);
+    };
+    unwatchers.add(release);
+    return release;
   }
   /**
    * Watch computed expression
    */
   _watchComputed(expression, callback, options = {}) {
-    const computed2 = new Computed(expression, options);
+    const computed2 = new Computed(expression, { ...this._options, ...options });
     const unwatch = computed2.watch(callback, options);
-    return unwatch;
+    const release = () => {
+      unwatch();
+      this._expressionWatchers.delete(release);
+    };
+    this._expressionWatchers.add(release);
+    return release;
   }
   /**
-   * Batch state updates
+   * Batch state updates: watchers run once, after every update, with the
+   * final values.
    */
   batch(updates) {
     if (typeof updates === "function") {
       const oldEnableHistory = this._options.enableHistory;
       this._options.enableHistory = false;
       try {
-        const result = updates(this);
+        const result = batch(() => updates(this));
         if (oldEnableHistory) {
           this._addToHistory("batch", null, null, this.toObject());
         }
@@ -318,11 +671,8 @@ var ReactiveState = class {
             break;
           }
         }
-      } catch (_error) {
-        globalErrorHandler.handle(_error, {
-          type: "middleware-_error",
-          context: { action, middleware: middleware.toString() }
-        });
+      } catch (error) {
+        reportError(this, error, "middleware-error", { action });
       }
     }
     return result;
@@ -386,28 +736,28 @@ var ReactiveState = class {
    * Convert state to plain object
    */
   toObject() {
-    const result = {};
-    for (const [key, observable2] of this._state.entries()) {
-      result[key] = observable2.value;
-    }
-    return result;
+    return Object.fromEntries(
+      [...this._state].filter(([, observable2]) => observable2._value !== ABSENT).map(([key, observable2]) => [key, observable2._value])
+    );
   }
   /**
    * Convert computed properties to object
    */
   getComputedValues() {
-    const result = {};
-    for (const [key, computed2] of this._computed.entries()) {
-      result[key] = computed2.value;
-    }
-    return result;
+    return Object.fromEntries(
+      [...this._computed].map(([key, computed2]) => [key, computed2.value])
+    );
   }
   /**
    * Get state statistics
    */
   getStats() {
+    let stateKeys = 0;
+    for (const observable2 of this._state.values()) {
+      if (observable2._value !== ABSENT) stateKeys++;
+    }
     return {
-      stateKeys: this._state.size,
+      stateKeys,
       computedKeys: this._computed.size,
       watcherKeys: this._watchers.size,
       historyLength: this._history.length,
@@ -418,6 +768,12 @@ var ReactiveState = class {
    * Cleanup and destroy
    */
   destroy() {
+    for (const key of [...this._watchers.keys()]) {
+      this._releaseKeyWatchers(key);
+    }
+    for (const release of [...this._expressionWatchers]) {
+      release();
+    }
     for (const observable2 of this._state.values()) {
       observable2.unwatchAll();
     }
@@ -502,6 +858,7 @@ export {
   Observable,
   ReactiveState,
   StateError,
+  batch,
   computed,
   createReactiveState,
   reactive_state_default as default,