@menapo/machine 0.0.0-stage → 0.1.0

package/dist/instance-BM2UqeXW.js

@@ -0,0 +1,418 @@
+import { a as warnOnce, r as fail } from "./dev-BAz6e3W-.js";
+//#region src/core/env.ts
+/**
+* Whether dev checks and messages run (PLAN §1, principle 4). Vite replaces
+* `import.meta.env.DEV` with a literal, so a production build drops every
+* `if (DEV)` branch and the messages in it (tests/production.test.ts checks
+* the bundle). Without Vite (plain Node, wrangler's esbuild, a CDN) `env` is
+* undefined, and the checks are off instead of throwing.
+*/
+const DEV = !!import.meta.env?.DEV;
+/**
+* Whether normalising a machine checks its config: in development, and in
+* the plugin's build-time compilation (M7), which runs this normaliser in
+* Node, where `import.meta.env` is undefined, and turns its errors into
+* build errors. Only {@link checkAlways} assigns it, and only the plugin
+* imports that, so an app's bundle never does and the bundler reads it as
+* `DEV`, dropping the checks from production builds as before.
+*/
+let CHECK = DEV;
+/**
+* Dev-only bookkeeping: how deep the running code is inside actions, so a
+* context write elsewhere can be named (D5). Only read and written behind
+* `DEV`, so production builds drop it.
+*/
+const dev = { acting: 0 };
+//#endregion
+//#region ../glue/src/record.ts
+/**
+* The record kit's state lives in (machine PLAN D5, spike S1; store PLAN
+* D3): values in an array behind one accessor per field, defined once per
+* key set on a class's prototype, and a change mask with one bit per field.
+* A read is a few ns, and no proxy or snapshot is involved. `@menapo/machine`
+* lays out context and props by `bit`, `@menapo/store` its stores by `bit`
+* and `defineAccessors`, so the bit layout exists once. Machine writes its
+* accessor loop out: the call cost its toggle's size gate 12 B.
+*
+* Read tracking stays with each owner: machine records one mask per
+* derived value, the store one mask per store a derived value read.
+*/
+/** The bit of field `n`: fields past the 31st share the last bit. */
+const bit = (n) => 1 << Math.min(n, 31);
+//#endregion
+//#region src/core/store.ts
+/**
+* Context and props as objects with one accessor per field, defined once per
+* machine on a prototype (D5, spike S1), with the bit layout of
+* `@menapo/glue`'s record, which the store shares: a read is a few ns, a write that
+* changes the value sets the field's bit in a change mask, and no proxy or
+* snapshot is involved. Reads also record their bits while a derived value
+* is being computed, so it is recomputed only when what it read changes.
+*/
+/** Bits read since the innermost derived value started computing. */
+let reads = 0;
+const track = (bits) => {
+	reads |= bits;
+};
+/** Starts recording reads afresh, or ends a recording: returns what was recorded. Parts record their attributes' reads with it. */
+const swap = (bits) => {
+	const read = reads;
+	reads = bits;
+	return read;
+};
+/** Dev only: the name of the machine a store belongs to, for messages. */
+const nameOf = (store) => store.i.M.name;
+/** A class with an accessor per name; `get(k)` and `set(k)` make each one's pair. */
+function accessors(names, get, set) {
+	class Values {
+		v;
+		m = 0;
+		i;
+		constructor(values, instance) {
+			this.v = values;
+			this.i = instance;
+		}
+	}
+	names.forEach((name, k) => {
+		Object.defineProperty(Values.prototype, name, {
+			configurable: true,
+			get: get(k),
+			set: set?.(k, name)
+		});
+	});
+	return Values;
+}
+/**
+* Context (`writable`) or props, over `this.v[k]`. Context is written by
+* actions only (D5: anywhere else throws in dev); props are the owner's,
+* and only bindable ones (which `bindable` redefines) can be written.
+*/
+function storeClass(names, first, writable) {
+	const Values = accessors(names, (k) => {
+		const mask = bit(first + k);
+		return function() {
+			reads |= mask;
+			return this.v[k];
+		};
+	}, (k, name) => {
+		const mask = bit(first + k);
+		return writable ? function(value) {
+			if (DEV && !dev.acting) fail("CONTEXT_WRITE", nameOf(this), `context.${name} was written outside an action. Write context in a transition's \`do\`, \`entry\` or \`exit\`, and send an event from here instead.`);
+			if (this.v[k] !== value) {
+				this.v[k] = value;
+				this.m |= mask;
+			}
+		} : DEV ? function() {
+			fail("PROPS_WRITE", nameOf(this), `props.${name} belongs to the owner and is read-only. Declare it \`${name}: bindable(…)\` to let actions write it.`);
+		} : void 0;
+	});
+	if (writable) Values.s = (machine, given) => {
+		const values = machine.df.slice();
+		if (given) for (const key of Object.keys(given)) {
+			const at = machine.nm.indexOf(key);
+			if (DEV && !(at >= 0 && at < values.length)) fail("UNKNOWN_FIELD", machine.name, `start() was given context.${key}, which the machine does not declare; add it to \`context\`.`);
+			values[at] = given[key];
+		}
+		return values;
+	};
+	return Values;
+}
+/**
+* The derived values' class: each getter returns the cached value while no
+* field it read has changed, else recomputes it with its reads recorded.
+* A value computed while a field it read is changed but not yet told is
+* recomputed on every read until the notification forgets it.
+*/
+function derivedClass(names, fns) {
+	const Derived = accessors(names, (k) => function() {
+		const c = this.v;
+		const instance = this.i;
+		const read = c[2 * k];
+		if (read === void 0 || read & instance.live()) {
+			const outer = reads;
+			reads = 0;
+			c[2 * k + 1] = fns[k](instance);
+			c[2 * k] = reads;
+			reads |= outer;
+		} else reads |= read;
+		return c[2 * k + 1];
+	});
+	/** Forgets the values that read what `changed` says changed: the interpreter calls it as it notifies. */
+	Derived.prototype.f = function(changed) {
+		const c = this.v;
+		for (let k = 0; k < c.length; k += 2) if (c[k] & changed) c[k] = void 0;
+	};
+	return Derived;
+}
+//#endregion
+//#region src/core/instance.ts
+/**
+* The interpreter (PLAN §5.3): a started machine is a few numbers and
+* objects, with every method on the prototype. Events run to completion
+* synchronously (D3): a send made while one is being handled is queued and
+* runs before the outer `send` returns, then subscribers hear once, with
+* the change mask. An unhandled event costs one map lookup and allocates
+* nothing.
+*/
+const IDLE = 0;
+const BUSY = 1;
+const STOPPED = 2;
+const START = { type: "machine.start" };
+/** `always` rules that keep passing this many times in one event are a loop. */
+const ALWAYS_LIMIT = 100;
+/** Context, props or derived values of a machine that declares none. */
+const EMPTY = Object.freeze({});
+function run(fns, view) {
+	if (fns) {
+		if (DEV) dev.acting++;
+		for (const fn of fns) fn(view);
+		if (DEV) dev.acting--;
+	}
+}
+const bindSend = (instance) => instance.sf = (event, payload) => instance.dispatch(event, payload);
+const bindIs = (instance) => instance.wf = (state) => instance.within(state);
+/**
+* D17's hook, set only through `inspect()` (src/inspect.ts): told before each
+* event an instance takes (`null` for owner props) and, with no event, once
+* it is done. Unset, a handled event pays one check and an unhandled one
+* never reaches it; a bundle that never imports `inspect` never assigns it,
+* so the bundler drops the calls.
+*/
+let hook;
+const setHook = (fn) => void (hook = fn);
+/** Dev only: warns, once per name, of an event no state handles, sent now or queued. */
+function unhandled(instance, type) {
+	if (!instance.M.handled.has(type)) warnOnce("UNHANDLED", instance.M.name, `no state handles "${type}"; add it to a state's \`on\`, or stop sending it.`);
+}
+var Interpreter = class {
+	M;
+	/** The active leaf; unset until started. */
+	s;
+	context;
+	props;
+	event = START;
+	/** IDLE, BUSY or STOPPED. */
+	b = IDLE;
+	/** STATE_BIT once the state changed in this event. */
+	d = 0;
+	/** Events sent while busy. */
+	q;
+	l;
+	/** What runs while a state is active: `[state, cleanup or timer, …]` (`effects.ts`). */
+	r;
+	/** States entered in this event whose timers and effects start once it settles. */
+	x;
+	/** The owner's props: the shared frozen empty object until an owner gives some (only read or replaced). */
+	o = EMPTY;
+	/** Owner props to take once the event being handled is done. */
+	n;
+	/** A move waiting for the owner (`bindable`): the rule's target and the event that asked. */
+	p;
+	/** `send` and `is`, bound on first use so they can be destructured. */
+	sf;
+	wf;
+	/** Derived values and `done`, made on first read. */
+	dq;
+	dn;
+	constructor(machine, context, owner) {
+		this.M = machine;
+		const Context = machine.C;
+		if (DEV && context && !Context) fail("UNKNOWN_FIELD", machine.name, `start() was given context, but the machine declares none; add \`context\` to it.`);
+		this.context = Context ? new Context(Context.s(machine, context), this) : EMPTY;
+		this.props = machine.Q ? new machine.Q(machine.pd.slice(), this) : EMPTY;
+		if (owner) machine.P?.(this, owner);
+		this.go(void 0, START);
+		this.mask = 0;
+	}
+	get state() {
+		track(1);
+		return this.s.path;
+	}
+	get send() {
+		return this.sf ?? bindSend(this);
+	}
+	get is() {
+		return this.wf ?? bindIs(this);
+	}
+	get derived() {
+		return this.M.D ? this.dq ??= new this.M.D([], this) : EMPTY;
+	}
+	/**
+	* Each part's id and element (`ids.content`, `el.content`): a component's
+	* (`parts/component.ts`). An instance `start` made renders nothing, so
+	* every part's id and element reads `undefined`, as the types say.
+	*/
+	get ids() {
+		return EMPTY;
+	}
+	get el() {
+		return EMPTY;
+	}
+	get changed() {
+		return this.M.nm.filter((_, n) => this.mask & bit(n + 1));
+	}
+	get done() {
+		return this.dn ??= new Promise((resolve) => this.s.fi ? resolve() : this.subscribe(() => this.s.fi && resolve()));
+	}
+	within(path) {
+		track(1);
+		if (DEV && !this.M.ss.some((state) => state.path === path)) fail("UNKNOWN_STATE", this.M.name, `is("${path}") names no state; the states are ${this.M.ss.map((state) => `"${state.path}"`).join(", ")}.`);
+		for (let at = this.s; at; at = at.up) if (at.path === path) return true;
+		return false;
+	}
+	/** Bits changed in the event being handled and not yet told. */
+	live() {
+		return this.context.m | this.props.m | this.d;
+	}
+	subscribe(listener) {
+		this.l = this.l ? [...this.l, listener] : [listener];
+		return () => {
+			const l = this.l.slice();
+			l.splice(l.indexOf(listener) >>> 0, 1);
+			this.l = l;
+		};
+	}
+	dispatch(event, payload) {
+		const named = typeof event === "string";
+		const type = named ? event : event.type;
+		const handler = this.b ? void 0 : this.s.on.get(type);
+		if (this.b === BUSY) (this.q ??= []).push(named ? {
+			type,
+			...payload
+		} : event);
+		else if (handler) this.go(handler.ru, !named ? event : payload === void 0 ? handler.ev : {
+			type,
+			...payload
+		});
+		else if (DEV) {
+			if (this.b) warnOnce("STOPPED", this.M.name, `"${type}" was sent after ${this.s.fi ? `the final state "${this.s.path}"` : "stop()"} and is ignored; start a new instance with start().`);
+			else if (typeof type !== "string") fail("BAD_EVENT", this.M.name, `send() was given ${JSON.stringify(event)}; send an event name, or an object with a \`type\`.`);
+			else unhandled(this, type);
+		}
+	}
+	/**
+	* Handles one thing from idle (an event's rules; else, before start, the
+	* initial state; else the owner props in `n`), then runs to completion.
+	* After a throw in user code the queue is dropped and the instance accepts
+	* events again.
+	*/
+	go(rules, event) {
+		this.b = BUSY;
+		hook?.(this, rules || !this.s ? event : null);
+		try {
+			if (rules) this.take(rules, event);
+			else if (!this.s) {
+				const { k: control, i0: initial } = this.M;
+				this.enter(void 0, control ? control.initial(this, initial) : initial);
+			}
+			this.settle();
+			hook?.(this);
+		} finally {
+			if (this.b === BUSY) {
+				this.b = IDLE;
+				this.q = this.n = void 0;
+				if (DEV) dev.acting = 0;
+			}
+		}
+	}
+	/** Takes the first rule whose guard passes; true if one did and nothing waits for the owner. */
+	take(rules, event) {
+		this.event = event;
+		for (const rule of rules) if (!rule.if || rule.if(this)) {
+			const p = this.p;
+			if (!rule.to) run(rule.do, this);
+			else if (!this.M.k?.hold(this, rule)) this.move(rule.to, rule.do);
+			return this.p === p;
+		}
+		return false;
+	}
+	/**
+	* Exits up to the nearest common ancestor strictly above the target, runs
+	* the rule's actions, enters down to the target's leaf. A target the
+	* machine is in is exited and entered again, so its timers restart.
+	*/
+	move(to, actions) {
+		const from = this.s;
+		let a = from;
+		let b = to.up;
+		while (a !== b) if (a.i > b.i) a = a.up;
+		else b = b.up;
+		for (let at = from; at !== a; at = at.up) this.exit(at);
+		run(actions, this);
+		this.enter(a, to.lf);
+		this.M.k?.moved(this, from);
+	}
+	/** Enters every state below `from` down to `to`, outermost first; timers and effects start once the event settles. */
+	enter(from, to) {
+		if (to.up !== from && to.up.i >= 0) this.enter(from, to.up);
+		this.s = to;
+		this.d = 1;
+		run(to.en, this);
+		if (to.af || to.ef) (this.x ??= []).push(to);
+	}
+	/** Stops what state `at` runs, latest first, then runs its exit actions. */
+	exit(at) {
+		if (this.r || this.x) this.M.X(this, at);
+		run(at.ex, this);
+	}
+	/**
+	* Sets the timers and starts the effects of states entered in this event
+	* that are still active. The glue's subclass defers it until the
+	* framework has committed the DOM, and never runs it on a server (D13).
+	*/
+	activate(states) {
+		this.M.A?.(this, states);
+	}
+	/**
+	* Runs to completion: `always` rules, queued events, owner props that
+	* arrived meanwhile and new states' effects, then one notification;
+	* again while listeners send.
+	*/
+	settle() {
+		for (;;) {
+			for (let n = 0; this.b === BUSY && this.s.al && this.take(this.s.al, this.event);) if (DEV && ++n > ALWAYS_LIMIT) fail("ALWAYS_LOOP", this.M.name, `"${this.s.path}" took an \`always\` transition ${ALWAYS_LIMIT} times in one event; give it an \`if\` that turns false.`);
+			if (this.b !== BUSY) return;
+			const { q, n, x } = this;
+			if (q?.length) {
+				const event = q.shift();
+				const handler = this.s.on.get(event.type);
+				if (handler) {
+					hook?.(this, event);
+					this.take(handler.ru, event);
+				} else if (DEV) unhandled(this, event.type);
+			} else if (n) {
+				this.n = void 0;
+				this.M.P(this, n);
+			} else if (x) {
+				this.x = void 0;
+				this.activate(x);
+			} else {
+				const changed = this.live();
+				if (!changed) break;
+				if (this.context.m) this.context.m = 0;
+				if (this.props.m) this.props.m = 0;
+				this.d = 0;
+				this.mask = changed;
+				this.dq?.f(changed);
+				if (this.l) for (const listener of this.l) listener(this);
+				if (!this.q?.length && !this.n) break;
+			}
+		}
+		if (this.s.fi) this.stop();
+	}
+	setProps(owner) {
+		this.M.P?.(this, owner, true);
+	}
+	stop() {
+		this.b = STOPPED;
+		this.q = void 0;
+		this.M.X?.(this);
+	}
+};
+/**
+* Creates and starts an instance (PLAN §4.1, §4.8): enters the initial
+* state, runs its entry actions, starts its effects and timers.
+*/
+const start = (machine, options) => new Interpreter(machine, options?.context, options?.props);
+//#endregion
+export { start as a, swap as c, CHECK as d, DEV as f, setHook as i, track as l, hook as n, derivedClass as o, dev as p, run as r, storeClass as s, Interpreter as t, bit as u };