@expressive/mvc 0.87.0 → 0.89.0

package/dist/state.js

@@ -1,6 +1,6 @@
-import { Caught } from "./caught.js";
+import { REPORT } from "./dispatch.js";
 import { capture, event, listener, observer, queued, touch, watch } from "./observable.js";
-import { Context, join } from "./context.js";
+import { Context, host, join } from "./context.js";
 
 //#region src/state.ts
 const define = Object.defineProperty;
@@ -8,7 +8,7 @@ const define = Object.defineProperty;
 const ID = /* @__PURE__ */ new WeakMap();
 /** Internal state assigned to states. */
 const STORE = /* @__PURE__ */ new WeakMap();
-/** States under construction - added on `new`, removed when activated or released.
+/** Models under construction - added on `new`, removed when activated or released.
 *  Also carries work to run at the deadline, which `def` uses to bound its registry. */
 const PENDING = /* @__PURE__ */ new Set();
 const SETUP = /* @__PURE__ */ new WeakMap();
@@ -22,35 +22,31 @@ const METHODS = /* @__PURE__ */ new WeakMap();
 const GETTERS = /* @__PURE__ */ new WeakMap();
 /** Replacement for a getter captured by live computed properties, for hot patching. */
 const LATEST = /* @__PURE__ */ new WeakMap();
-/** Method implementations replaced by a hot patch. */
-const PAST = /* @__PURE__ */ new WeakSet();
-/** Live instances, tracked once hot patching is enabled. */
-let LIVE;
-/** Bootstrapped subclasses of each class, tracked once hot patching is enabled. */
-const SUBCLASSES = /* @__PURE__ */ new WeakMap();
 /** Event every observer treats as watched, forcing a refresh after a hot patch. */
 const REFRESH = Symbol.for("@expressive/mvc.refresh");
 /** Stale flags for compute closures awaiting refresh on next access. */
 const STALE = /* @__PURE__ */ new WeakSet();
 /** Whether the deadline which drains `PENDING` is already queued for this tick. */
 let QUEUED = false;
-/** Global list each loaded copy of this module adds its `State` to, on first construction. */
+/** Global list each loaded copy of this module adds its `Model` to, on first construction. */
 const COPIES = Symbol.for("@expressive/mvc");
 let ANNOUNCED = false;
-/** Adopters for managed properties which have held a child State. */
+/** Adopters for managed properties which have held a child Model. */
 const ADOPT = /* @__PURE__ */ new WeakMap();
 const CHILDREN = /* @__PURE__ */ new WeakMap();
-var State = class State {
+const OWNS = /* @__PURE__ */ new WeakMap();
+const OWNED = /* @__PURE__ */ new WeakMap();
+var Model = class Model {
 	/**
 	* Whether an instance activated with no enclosing context registers itself
 	* to the process-global root, where `get()` can resolve it from anywhere.
 	* `false` (the default) keeps a context-less instance fully functional but
 	* private - not injectable, though it can still read declared globals. Opt in
-	* with `static readonly global = true`; a resolver (see {@link State.Global})
+	* with `static readonly global = true`; a resolver (see {@link Model.Global})
 	* makes the choice conditional. It must be declared per class - a subclass
 	* that would inherit a global without its own declaration throws on
-	* activation, so an accidental global (a forgotten `Provider`, an extended
-	* global) cannot leak into the shared root.
+	* activation, so an accidental global (a forgotten `<Component for>`, an
+	* extended global) cannot leak into the shared root.
 	*/
 	static global = false;
 	constructor(...args) {
@@ -60,7 +56,8 @@ var State = class State {
 	get(arg1, arg2, arg3) {
 		const self = this.is;
 		if (arg1 === void 0) return values(self);
-		if (State.is(arg1)) return Context.get(self).get(arg1, arg2, arg3, self);
+		if (arg1 === Model) return typeof arg2 == "function" ? owned(self, arg2) : observed(this, arg1, owner(self, arg2));
+		if (Model.is(arg1)) return observed(this, arg1, Context.get(self).get(arg1, arg2, arg3, self));
 		if (typeof arg1 == "function") return watch(self, unbind(arg1));
 		if (typeof arg2 == "function") return callback(self, arg2, arg1);
 		if (arg1 === null) return observer(self) === null;
@@ -78,7 +75,7 @@ var State = class State {
 		return queued(self);
 	}
 	/**
-	* Iterate over managed properties in this instance of State.
+	* Iterate over managed properties in this instance of Model.
 	* Yeilds the key and current value for each property.
 	*/
 	[Symbol.iterator]() {
@@ -105,30 +102,23 @@ var State = class State {
 	static is(maybe) {
 		return maybe === this || typeof maybe == "function" && maybe.prototype instanceof this;
 	}
-	/**
-	* Register a lifecycle handler for this State and its subclasses.
-	*
-	* A bare function is per-instance setup run in the `prepare` phase (sugar for
-	* `{ before }`); if it returns a function, that runs when the instance is
-	* destroyed. Pass a {@link State.On} object to hook by cadence - `type`
-	* (per-class, at bootstrap), `before` (per-instance, before `new()`), and
-	* `after` (per-instance, at the `new()` slot).
-	*
-	* @returns Function to remove the handler.
-	*/
 	static on(handler) {
+		if (typeof handler == "function") handler = { setup: handler };
 		let setup = SETUP.get(this);
 		if (!setup) SETUP.set(this, setup = /* @__PURE__ */ new Set());
 		setup.add(handler);
 		return () => setup.delete(handler);
 	}
 };
-define(State.prototype, "toString", { value() {
+define(Model.prototype, "toString", { value() {
 	return ID.get(this.is);
 } });
-define(State, "toString", { value() {
+define(Model, "toString", { value() {
 	return this.name;
 } });
+function observed(from, key, value) {
+	return value instanceof Model ? touch(from, key, value) : value;
+}
 /** Register a user OnEvent callback, preserving `this` and `source`. */
 function callback(self, cb, select) {
 	return listener(self, (key) => cb.call(self, key, self), select);
@@ -139,15 +129,14 @@ function callback(self, cb, select) {
 **/
 function init(state, ...args) {
 	const T = state.constructor;
-	if (T === State) throw new Error("Cannot create base State.");
+	if (T === Model) throw new Error("Cannot create base Model.");
 	if (!ANNOUNCED) {
 		ANNOUNCED = true;
-		(globalThis[COPIES] ||= []).push(State);
+		(globalThis[COPIES] ||= []).push(Model);
 	}
 	const { before, after } = bootstrap(T);
 	ID.set(state, `${T}-${uid()}`);
 	STORE.set(state, {});
-	LIVE?.add(new WeakRef(state));
 	function observe() {
 		for (const key in state) {
 			const desc = Object.getOwnPropertyDescriptor(state, key) || {};
@@ -162,13 +151,20 @@ function init(state, ...args) {
 		const g = type.global;
 		if (!(typeof g == "function" ? g(state) : g)) return;
 		if (!Object.prototype.hasOwnProperty.call(type, "global")) throw new Error(`${state} would register as a global by inheritance alone - re-declare \`static global\` on ${type.name} (\`true\` to keep it, \`false\` to opt out).`);
+		for (let T = type; T !== Model; T = Object.getPrototypeOf(T)) {
+			const found = Context.root.get(T, false);
+			if (found && (T === type || found.constructor === T)) throw new Error(`Cannot register ${state} as a global - ${found} already exists in root. Destroy the existing instance first, or provide additional ones via explicit context.`);
+		}
 		return Context.root.add(state);
 	}
 	listener(state, (key) => {
 		const rest = trailing(state);
 		PENDING.delete(state);
 		if (key === null) return null;
-		parent(state, null);
+		if (!PARENT.has(state)) parent(state, host(state) || null);
+		const above = PARENT.get(state);
+		const owns = above && (OWNS.get(above) || OWNS.set(above, /* @__PURE__ */ new Set()).get(above));
+		if (owns) listener(state, () => void owns.delete(state), null);
 		const queue = [
 			...before,
 			observe,
@@ -181,12 +177,16 @@ function init(state, ...args) {
 			for (let i = 0; i < queue.length; i++) {
 				const arg = queue[i];
 				const out = typeof arg == "function" ? arg.call(state, state) : arg;
-				if (out instanceof Promise) out.catch((err) => report(new Caught.Init(state, err)));
+				if (out instanceof Promise) out.catch((err) => report("setup", state, err));
 				else if (Array.isArray(out)) queue.splice(i + 1, 0, ...out);
 				else if (typeof out == "function") listener(state, out, null);
 				else if (typeof out == "object") assign(state, out, true);
 			}
 		});
+		if (owns) {
+			owns.add(state);
+			OWNED.get(above)?.forEach((cb) => cb(state));
+		}
 		let end = rest.length;
 		while (end-- > 0 && PENDING.has(rest[end]));
 		for (let i = 0; i < end; i++) PENDING.delete(rest[i]);
@@ -197,7 +197,7 @@ function init(state, ...args) {
 		queueMicrotask(() => {
 			QUEUED = false;
 			for (const item of PENDING) if (typeof item == "function") item();
-			else report(new Caught.Inactive(item));
+			else report("unused", item, /* @__PURE__ */ new Error(`${item} was constructed but never activated.`));
 			PENDING.clear();
 		});
 	}
@@ -216,7 +216,7 @@ function unmanaged(state, key, value) {
 /**
 * Apply instructions and inherited event listeners. Ensure class metadata is ready.
 *
-* @param T - State class to bootstrap.
+* @param T - Model class to bootstrap.
 * @return Array of init functions to run on instance, in order of class hierarchy.
 */
 function bootstrap(T) {
@@ -228,29 +228,22 @@ function bootstrap(T) {
 	let getters = /* @__PURE__ */ new Map();
 	while (true) {
 		chain.unshift(T);
-		if (T === State) break;
+		if (T === Model) break;
 		T = Object.getPrototypeOf(T);
 	}
 	for (const type of chain) {
-		for (const handler of SETUP.get(type) || []) if (typeof handler == "function") before.add(handler);
-		else {
-			if (handler.before) before.add(handler.before);
-			if (handler.after) after.add(handler.after);
+		for (const handler of SETUP.get(type) || []) {
+			if (handler.setup) before.add(handler.setup);
+			if (handler.ready) after.add(handler.ready);
 			if (handler.type) onType.add(handler.type);
 		}
-		if (type === State) continue;
+		if (type === Model) continue;
 		if (METHODS.has(type)) {
 			keys = METHODS.get(type);
 			getters = GETTERS.get(type);
 			continue;
 		}
 		for (const setupType of onType) setupType(type);
-		if (LIVE) {
-			const parent = Object.getPrototypeOf(type);
-			let children = SUBCLASSES.get(parent);
-			if (!children) SUBCLASSES.set(parent, children = /* @__PURE__ */ new Set());
-			children.add(type);
-		}
 		METHODS.set(type, keys = new Map(keys));
 		GETTERS.set(type, getters = new Map(getters));
 		classify(type, keys, getters);
@@ -295,6 +288,7 @@ function classify(type, keys, getters) {
 				writable: true,
 				configurable: true
 			});
+			for (const handler of stages(is.constructor, "method")) handler.call(is, key, bound, is);
 			return bound;
 		}
 		UNBIND.set(bind, value);
@@ -305,6 +299,12 @@ function classify(type, keys, getters) {
 		});
 	}
 }
+/** Handlers of one stage along the class chain - ancestor first, in registration order, each once. */
+function stages(T, key) {
+	const found = T === Model ? /* @__PURE__ */ new Set() : stages(Object.getPrototypeOf(T), key);
+	for (const handler of SETUP.get(T) || []) if (handler[key]) found.add(handler[key]);
+	return found;
+}
 /**
 * Install a reactive computed property on a state instance, derived from a prototype
 * getter or an arity-bearing `set` factory.
@@ -317,6 +317,8 @@ function compute(getter, key) {
 	const store = STORE.get(this);
 	let reset;
 	let isAsync;
+	let suspended = false;
+	let waiting;
 	let proxy;
 	const connect = () => {
 		reset = watch(this, (current) => {
@@ -332,15 +334,27 @@ function compute(getter, key) {
 	};
 	const run = (initial) => {
 		let next;
+		waiting = void 0;
 		try {
 			next = latest(getter).call(proxy, proxy);
 		} catch (err) {
-			if (initial) {
+			if (err instanceof Promise) {
+				if (initial) {
+					suspended = true;
+					throw err;
+				}
+				const retry = () => {
+					if (waiting === err && observer(this) !== null) run();
+				};
+				waiting = err;
+				err.then(retry, retry);
+				if (suspended) return;
+			} else if (initial) {
 				console.warn(`An exception was thrown while initializing ${this}.${key}.`);
 				throw err;
-			}
-			if (!(err instanceof Promise)) report(new Caught.Getter(this, key, err));
+			} else report("getter", this, err, key);
 		}
+		suspended = false;
 		update(this, key, next, !isAsync);
 	};
 	apply(this, key, {
@@ -353,7 +367,7 @@ function compute(getter, key) {
 				isAsync = true;
 			}
 			if (STALE.delete(run)) run();
-			return access(this, key, !proxy);
+			return access(this, key, suspended);
 		}
 	}, true);
 }
@@ -362,7 +376,7 @@ function compute(getter, key) {
 * If the property already is managed, config will only accept value.
 * If the property does not exist, it will be created and made reactive.
 *
-* @param state - State to apply property to.
+* @param state - Model to apply property to.
 * @param key - Property to define or update.
 * @param config - Descriptor config with value, get, set, enumerable, and/or destroy.
 * @param silent - If an update does occur, listeners will not be refreshed automatically.
@@ -420,7 +434,7 @@ function child(state) {
 	listener(state, reset, null);
 	return (value) => {
 		reset();
-		if (!(value instanceof State)) return;
+		if (!(value instanceof Model)) return;
 		if (parent(value, state)) {
 			const remove = join(state, value);
 			cleanup = () => {
@@ -435,18 +449,18 @@ function child(state) {
 	};
 }
 /**
-* Pending States constructed after this one - in a parent, the products of
+* Pending Models constructed after this one - in a parent, the products of
 * its own initializers, until the last one it kept.
 */
 function trailing(state) {
 	const rest = [];
 	let seen = false;
 	for (const item of PENDING) if (!seen) seen = item === state;
-	else if (item instanceof State) rest.push(item);
+	else if (item instanceof Model) rest.push(item);
 	return rest;
 }
 /**
-* Report States adopted by a parent - those already held, then each one
+* Report Models adopted by a parent - those already held, then each one
 * claimed later. Returns a callback to stop watching.
 */
 function children(state, callback) {
@@ -454,13 +468,33 @@ function children(state, callback) {
 	const keys = ADOPT.get(state);
 	if (keys) for (const key of keys.keys()) {
 		const value = store[key];
-		if (value instanceof State) callback(value);
+		if (value instanceof Model) callback(value);
 	}
 	let set = CHILDREN.get(state);
 	if (!set) CHILDREN.set(state, set = /* @__PURE__ */ new Set());
 	set.add(callback);
 	return () => set.delete(callback);
 }
+function owner(state, required) {
+	const found = PARENT.get(state);
+	if (found || required === false) return found || void 0;
+	throw new Error(`${state} has no owner.`);
+}
+/**
+* Report Models owned by this one - those active now, then each one as it
+* activates. A function returned by `callback` runs when that Model is destroyed.
+*/
+function owned(state, callback) {
+	function each(child) {
+		const done = callback(child);
+		if (typeof done == "function") listener(child, () => void done(), null);
+	}
+	OWNS.get(state)?.forEach(each);
+	let set = OWNED.get(state);
+	if (!set) OWNED.set(state, set = /* @__PURE__ */ new Set());
+	set.add(each);
+	return () => void set.delete(each);
+}
 /** Currently accumulating export. Stores real values of placeholder properties such as ref() or child states. */
 let EXPORT;
 function values(state) {
@@ -524,15 +558,16 @@ function assign(state, data, silent) {
 *
 * This is used internally to update properties, but can also be used to update properties which are not managed by state, or to update values without triggering setters.
 *
-* A destroyed state reports the write - thrown to the writer unless a `catch` handler takes it - and returns `false`; `silent` skips both, and dispatch.
+* A destroyed state stores the write without dispatch, reports it unless `silent`, and returns `false`.
 */
 function update(state, key, value, silent, own) {
+	const store = STORE.get(state);
+	if (value instanceof Model) value = value.is;
 	if (observer(state) === null) {
-		if (!silent) report(new Caught.Destroyed(state, String(key)), true);
+		if (!silent) report("dead", state, /* @__PURE__ */ new Error(`Tried to update ${state}.${String(key)} but state is destroyed.`), String(key));
+		store[key] = value;
 		return false;
 	}
-	const store = STORE.get(state);
-	if (value instanceof State) value = value.is;
 	if (key in store && value === store[key]) return false;
 	store[key] = value;
 	if (!silent) event(state, key);
@@ -540,55 +575,38 @@ function update(state, key, value, silent, own) {
 	return true;
 }
 /**
-* Pass a caught error along `catch` handlers - most-derived class first, last registered
-* first - until one returns nothing. Passed off the end, a warning logs and anything
-* else is thrown - to the caller when `sync`, else uncaught. So is a handler's throw,
-* and one wrapping an error a handler already threw escapes that error unreported.
+* Pass an error along `catch` handlers - most-derived class first, last registered
+* first, one on several classes once at the outermost - until one returns nothing. Passed off
+* the end, a destroyed write outputs nothing, `unused` warns, anything else escapes uncaught;
+* so does a handler's throw.
 */
-function report(caught, sync) {
-	const handlers = /* @__PURE__ */ new Set();
-	let error = caught;
-	if (caught.cause instanceof Caught) return escape(caught.cause);
-	for (let T = caught.state.constructor;; T = Object.getPrototypeOf(T)) {
-		for (const handler of [...SETUP.get(T) || []].reverse()) if (typeof handler == "object" && handler.catch) handlers.add(handler.catch);
-		if (T === State) break;
-	}
+function report(kind, owner, error, key) {
+	const state = owner instanceof Model ? owner : owner && PARENT.get(owner);
+	if (!state) return REPORT.error(error);
 	try {
-		for (const handler of handlers) if (!(error = handler.call(caught.state, error))) return;
+		for (const handler of [...stages(state.constructor, "catch")].reverse()) if ((error = handler.call(state, error, kind, key)) === void 0) return;
+		if (kind == "unused") console.warn(error);
+		else if (kind != "dead") REPORT.error(error);
 	} catch (err) {
-		if (sync) throw err;
-		return escape(err);
+		REPORT.error(err);
 	}
-	if (error.warning) console.warn(error);
-	else if (sync) throw error;
-	else escape(error);
-}
-function escape(err) {
-	queueMicrotask(() => {
-		throw err;
-	});
-}
-/** Error thrown by a handler replaying in dispatch, attributed to the State which queued it. */
-function fault(err, owner) {
-	const state = owner instanceof State ? owner : owner && PARENT.get(owner);
-	if (state) report(new Caught.Effect(state, err));
-	else escape(err);
 }
+REPORT.as = report;
 /**
 * Hand a value stored by an owning writer to that property's adopter,
-* creating one the first time a State is stored there. A property which has
-* held a State keeps its adopter, so a later non-State value releases the
+* creating one the first time a Model is stored there. A property which has
+* held a Model keeps its adopter, so a later non-Model value releases the
 * previous child.
 */
 function adopt(state, key, value) {
 	let keys = ADOPT.get(state);
 	if (!keys) {
-		if (!(value instanceof State)) return;
+		if (!(value instanceof Model)) return;
 		ADOPT.set(state, keys = /* @__PURE__ */ new Map());
 	}
 	let claim = keys.get(key);
 	if (!claim) {
-		if (!(value instanceof State)) return;
+		if (!(value instanceof Model)) return;
 		keys.set(key, claim = child(state));
 	}
 	claim(value);
@@ -598,101 +616,6 @@ function latest(getter) {
 	for (let next; next = LATEST.get(getter);) getter = next;
 	return getter;
 }
-/** Begin tracking live instances, so a hot patch can reach them. */
-function track() {
-	LIVE ||= /* @__PURE__ */ new Set();
-}
-/**
-* Move the members of `next` onto `prev`, which keeps its identity. Returns the
-* live instances of `prev`, each needing a refresh.
-*/
-function patch(prev, next, own) {
-	const proto = prev.prototype;
-	const incoming = Object.getOwnPropertyDescriptors(next.prototype);
-	const keys = METHODS.get(prev);
-	const getters = GETTERS.get(prev);
-	const methods = /* @__PURE__ */ new Map();
-	const knownKeys = new Set(keys?.keys());
-	const knownGetters = new Set(getters?.keys());
-	let setup = SETUP.get(prev);
-	for (const handler of own) setup.delete(handler);
-	for (const handler of handlers(next)) {
-		if (!setup) SETUP.set(prev, setup = /* @__PURE__ */ new Set());
-		setup.add(handler);
-	}
-	for (const key of Reflect.ownKeys(next)) {
-		if (key == "prototype" || key == "length" || key == "name") continue;
-		if (Object.getOwnPropertyDescriptor(prev, key)?.configurable !== false) define(prev, key, Object.getOwnPropertyDescriptor(next, key));
-	}
-	const removed = /* @__PURE__ */ new Set();
-	for (const key of Object.getOwnPropertyNames(proto)) if (key != "constructor" && !(key in incoming)) {
-		const bind = keys?.get(key);
-		if (bind && Object.getOwnPropertyDescriptor(proto, key).get === bind) {
-			PAST.add(UNBIND.get(bind));
-			keys.delete(key);
-		}
-		removed.add(key);
-		Reflect.deleteProperty(proto, key);
-		getters?.delete(key);
-	}
-	for (const [key, desc] of Object.entries(incoming)) {
-		if (key == "constructor") continue;
-		const current = Object.getOwnPropertyDescriptor(proto, key);
-		if (typeof desc.value == "function") methods.set(key, desc.value);
-		if (current?.configurable === false) {
-			if (current.writable) proto[key] = desc.value;
-			continue;
-		}
-		if (current?.get && keys?.get(key) === current.get) PAST.add(UNBIND.get(current.get));
-		const getter = getters?.get(key);
-		if (getter) LATEST.set(getter, desc.get);
-		define(proto, key, {
-			...desc,
-			configurable: true
-		});
-	}
-	if (keys) {
-		for (let T = prev;; T = Object.getPrototypeOf(T)) {
-			for (const handler of SETUP.get(T) || []) if (typeof handler == "object" && handler.type) handler.type(prev);
-			if (T === State) break;
-		}
-		classify(prev, keys, getters);
-	}
-	const live = [];
-	for (const ref of LIVE) {
-		const state = ref.deref();
-		if (!state) LIVE.delete(ref);
-		else if (state instanceof prev) live.push(state);
-	}
-	const descendants = new Set([prev, ...live.map((state) => state.constructor)]);
-	for (const type of descendants) for (const child of SUBCLASSES.get(type) || []) descendants.add(child);
-	descendants.delete(prev);
-	for (const type of descendants) {
-		const inherit = METHODS.get(type);
-		const computed = GETTERS.get(type);
-		for (const [key, bind] of keys) if (!knownKeys.has(key) && !inherit.has(key)) inherit.set(key, bind);
-		for (const [key, get] of getters) if (!knownGetters.has(key) && !computed.has(key)) computed.set(key, get);
-		for (const key of removed) if (!(key in type.prototype)) {
-			inherit.delete(key);
-			computed.delete(key);
-		}
-	}
-	for (const state of live) {
-		for (const [key, value] of methods) {
-			const desc = Object.getOwnPropertyDescriptor(state, key);
-			if (!desc) continue;
-			if (desc.set) desc.set.call(state, value);
-			else if (PAST.has(UNBIND.get(desc.value))) delete state[key];
-		}
-		for (const key of removed) if (PAST.has(UNBIND.get(Object.getOwnPropertyDescriptor(state, key)?.value))) delete state[key];
-		for (const [key, get] of GETTERS.get(state.constructor)) if (!knownGetters.has(key) && get === getters.get(key)) compute.call(state, get, key);
-	}
-	return live;
-}
-/** Lifecycle handlers registered on a class itself. */
-function handlers(type) {
-	return [...SETUP.get(type) || []];
-}
 /** Random alphanumberic of length 6; always starts with a letter. */
 function uid() {
 	return (.278 + Math.random() * .722).toString(36).substring(2, 8).toUpperCase();
@@ -708,5 +631,5 @@ function parent(child, value) {
 }
 
 //#endregion
-export { PENDING, STORE, State, access, apply, children, compute, event, fault, handlers, parent, patch, track, trailing, uid, unbind, update };
+export { GETTERS, LATEST, METHODS, Model, PENDING, SETUP, STORE, UNBIND, access, adopt, apply, children, classify, compute, event, owned, parent, trailing, uid, unbind, update };
 //# sourceMappingURL=state.js.map