joist-core 2.3.0 → 2.4.0

package/build/reactivity/ReactionsManager.js

@@ -0,0 +1,263 @@
+import { followReverseHint } from "./reactiveHints.js";
+import { getMetadata } from "../EntityMetadata.js";
+import { runInTrustedContext } from "../trusted.js";
+import { globalLogger, noopReactionLogger } from "../logging/ReactionLogger.js";
+import { NoIdError } from "../index.js";
+import { getEmInternalApi } from "../EntityManager.js";
+//#region src/reactivity/ReactionsManager.ts
+/**
+* Manages the reactivity of tracking which source fields have changed and finding/recalculating
+* their downstream derived fields.
+*
+* Source fields are usually regular/dumb primitives, i.e. `Author.age` is a source field
+* of `Book.isPublic`, but derived fields can themselves be source fields as well.
+*/
+var ReactionsManager = class {
+	/** Stores all source `Reactables`s that have been marked for later traversal. */
+	pendingReactables = /* @__PURE__ */ new Map();
+	/** Failed actions to retry post-hooks, deduped by target field name -> entity (rare error path). */
+	actionsPendingTypeErrors = /* @__PURE__ */ new Map();
+	/**
+	* A map of entity tagName -> fields that have been marked as dirty.
+	*
+	* The key of the map is "just" the tag name, instead of a specific entity, b/c at the time of
+	* being marked dirty, we only have the upstream/source entity + fieldName that has changed, and
+	* not the 1-or-more downstream/target entities that will actually recalc.
+	*
+	* Instead, we just track the dirty fields by type-of-entity, which is enough for `isPendingRecalc`.
+	*/
+	dirtyFields = /* @__PURE__ */ new Map();
+	/**
+	* Tracks which entities have already run a `runOnce` reactable, keyed by the target field
+	* name -> entities. We key on `r.name` (not `r` itself) b/c two `Reactable`s reverse-indexed
+	* from different source paths can target the same derived field, and must dedupe together.
+	* Keying the outer map by field name (of which there are few) instead of by entity (of which
+	* there are many) means we allocate just one `Set` per distinct field name, rather than a
+	* `Set` per entity or the old per-action `${entity.toTaggedString()}_${r.name}` key strings.
+	*/
+	processedActions = /* @__PURE__ */ new Map();
+	#needsRecalc = {
+		populate: false,
+		query: false,
+		reaction: false
+	};
+	logger = globalLogger ?? noopReactionLogger;
+	em;
+	/** These are NPEs that *might* have been from invalid m2o fields, so we only throw them after validation. */
+	suppressedTypeErrors = [];
+	constructor(em) {
+		this.em = em;
+	}
+	/**
+	* Queue all downstream reactive fields that depend on `fieldName` as a source field.
+	*
+	* This method can be synchronous b/c we internally queue the `Reactable` reverse
+	* indexes on the given source `fieldName`, and don't crawl/walk back to the downstream
+	* entities/fields until `recalcPendingReactables` is called.
+	*/
+	queueDownstreamReactables(entity, fieldName) {
+		for (const r of this.getReactablesByField(entity, fieldName)) {
+			this.getPending(r).todo.add(entity);
+			this.#needsRecalc[r.kind] = true;
+			this.logger.logQueued(entity, fieldName, r);
+		}
+	}
+	/** Dequeues reactivity on `fieldName`, i.e. if it's no longer dirty. */
+	dequeueDownstreamReactables(entity, fieldName) {
+		for (const r of this.getReactablesByField(entity, fieldName)) {
+			const pending = this.getPending(r);
+			if (pending.done.has(entity)) {
+				pending.todo.add(entity);
+				this.#needsRecalc[r.kind] = true;
+			} else if (r.fields.length === 1) pending.todo.delete(entity);
+		}
+	}
+	/** Queue all downstream reactive fields that depend on this entity being created or deleted. */
+	queueAllDownstreamFields(entity, reason) {
+		for (const r of this.getReactables(entity)) {
+			this.getPending(r).todo.add(entity);
+			this.#needsRecalc[r.kind] = true;
+			this.logger.logQueuedAll(entity, reason, r);
+		}
+	}
+	/**
+	* Returns whether this field might be pending recalc.
+	*
+	* This is technically a guess, b/c our reaction infra may not yet have crawled from an upstream
+	* source field down to the `N` specific target entities that need recalced, and instead just
+	* knows "it will need to do that soon" i.e. at the next `em.flush`.
+	*
+	* So, instead this is a heuristic that reports if `fieldName` has been marked dirty for _some_
+	* entities of type `entity`, but we don't technically know if that's _this_ entity.
+	*
+	* I.e. this might return false positives, but should never return false negatives.
+	*/
+	isMaybePendingRecalc(entity, fieldName) {
+		return this.getDirtyFields(getMetadata(entity)).has(fieldName);
+	}
+	hasPendingReactiveQueries() {
+		return this.#needsRecalc.query;
+	}
+	/**
+	* Given source `Reactable` "reverse indexes" that have been queued as dirty by calls
+	* to setters, `em.register`, or `em.delete`, asynchronously walks/crawls to the downstream
+	* derived fields and calls `.load()` on them to calc.
+	*
+	* We also do this in a loop to handle reactive fields depending on other reactive fields.
+	*/
+	async recalcPendingReactables(kind) {
+		if (this.needsRecalc(kind)) this.logger.logStartingRecalc(this.em, kind);
+		let loops = 0;
+		while (this.needsRecalc(kind)) {
+			if (kind === "reactables") {
+				this.#needsRecalc.populate = false;
+				this.#needsRecalc.reaction = false;
+			} else this.#needsRecalc.query = false;
+			const seen = /* @__PURE__ */ new Map();
+			const actions = [];
+			const walks = await Promise.all([...this.pendingReactables.entries()].map(async ([r, pending]) => {
+				if (kind === "reactables" && r.kind === "query") return void 0;
+				if (kind === "reactiveQueries" && (r.kind === "populate" || r.kind === "reaction")) return void 0;
+				const todo = [...pending.todo];
+				if (todo.length === 0) return void 0;
+				pending.todo.clear();
+				for (const doing of todo) pending.done.add(doing);
+				const actionableEntities = (r.path.length === 0 ? todo : await followReverseHint(r.name, todo, r.path)).filter((entity) => !entity.isDeletedEntity && entity instanceof r.cstr);
+				let seenEntities = seen.get(r.name);
+				if (!seenEntities) seen.set(r.name, seenEntities = /* @__PURE__ */ new Set());
+				const processed = r.runOnce ? this.processedActions.get(r.name) : void 0;
+				for (const entity of actionableEntities) {
+					if (seenEntities.has(entity)) continue;
+					if (processed && processed.has(entity)) continue;
+					seenEntities.add(entity);
+					actions.push({
+						r,
+						entity
+					});
+				}
+				return {
+					r,
+					todo,
+					entities: actionableEntities
+				};
+			}));
+			this.logger.logWalks(walks, "recalc");
+			this.logger.logLoadingStart(this.em, actions);
+			const startTime = this.logger.now();
+			const results = await runInTrustedContext(() => Promise.allSettled(actions.map((a) => this.#doAction(a))));
+			const endTime = this.logger.now();
+			this.logger.logLoadingEnd(this.em, endTime - startTime);
+			const actionsPendingAssignedIds = [];
+			const failures = [];
+			results.forEach((result, i) => {
+				if (result.status === "rejected") {
+					if (result.reason instanceof NoIdError) actionsPendingAssignedIds.push(actions[i]);
+					else if (result.reason instanceof TypeError) this.addPendingTypeError(actions[i]);
+					else failures.push(result.reason);
+				}
+			});
+			if (actionsPendingAssignedIds.length > 0) {
+				await this.em.assignNewIds();
+				this.logger.logLoadingStart(this.em, actionsPendingAssignedIds);
+				const startTime = this.logger.now();
+				const results = await runInTrustedContext(() => Promise.allSettled(actionsPendingAssignedIds.map((a) => this.#doAction(a))));
+				const endTime = this.logger.now();
+				this.logger.logLoadingEnd(this.em, endTime - startTime);
+				results.forEach((result, i) => {
+					if (result.status === "rejected") {
+						if (result.reason instanceof TypeError) this.addPendingTypeError(actionsPendingAssignedIds[i]);
+						else failures.push(result.reason);
+					}
+				});
+			}
+			if (failures.length > 0) throw failures[0];
+			for (const action of actions) if (action.r.runOnce) {
+				let set = this.processedActions.get(action.r.name);
+				if (!set) this.processedActions.set(action.r.name, set = /* @__PURE__ */ new Set());
+				set.add(action.entity);
+			}
+			if (loops++ > 50) throw new Error("recalc looped too many times, probably a circular dependency");
+		}
+	}
+	async recalcPendingTypeErrors() {
+		const actions = [];
+		for (const byEntity of this.actionsPendingTypeErrors.values()) for (const action of byEntity.values()) actions.push(action);
+		this.actionsPendingTypeErrors.clear();
+		const startTime = this.logger.now();
+		const results = await runInTrustedContext(() => Promise.allSettled(actions.filter((a) => !a.entity.isDeletedEntity).map((a) => this.#doAction(a))));
+		const endTime = this.logger.now();
+		this.logger.logLoadingEnd(this.em, endTime - startTime);
+		const failures = [];
+		results.forEach((result) => {
+			if (result.status === "rejected") {
+				if (result.reason instanceof TypeError) this.suppressedTypeErrors.push(result.reason);
+				else failures.push(result.reason);
+			}
+		});
+		if (failures.length > 0) throw failures[0];
+	}
+	get hasPendingTypeErrors() {
+		return this.actionsPendingTypeErrors.size > 0;
+	}
+	/** Clears all the pending source fields, i.e. after `em.flush` is complete. */
+	clear() {
+		this.pendingReactables = /* @__PURE__ */ new Map();
+		this.processedActions.clear();
+	}
+	setLogger(logger) {
+		this.logger = logger ?? noopReactionLogger;
+	}
+	clearSuppressedTypeErrors() {
+		this.suppressedTypeErrors = [];
+	}
+	throwIfAnySuppressedTypeErrors() {
+		if (this.suppressedTypeErrors.length > 0) throw this.suppressedTypeErrors[0];
+	}
+	#doAction(action) {
+		const { r, entity } = action;
+		return r.kind === "reaction" ? r.fn(entity, this.em.ctx) : entity[r.name].load();
+	}
+	/** Remembers a TypeError'd action to retry post-hooks, deduped by (target field name, entity). */
+	addPendingTypeError(action) {
+		let byEntity = this.actionsPendingTypeErrors.get(action.r.name);
+		if (!byEntity) this.actionsPendingTypeErrors.set(action.r.name, byEntity = /* @__PURE__ */ new Map());
+		byEntity.set(action.entity, action);
+	}
+	needsRecalc(kind) {
+		return kind === "reactables" ? this.#needsRecalc.populate || this.#needsRecalc.reaction : this.#needsRecalc.query;
+	}
+	getPending(r) {
+		let pending = this.pendingReactables.get(r);
+		if (!pending) {
+			pending = {
+				todo: /* @__PURE__ */ new Set(),
+				done: /* @__PURE__ */ new Set()
+			};
+			this.pendingReactables.set(r, pending);
+			this.getDirtyFields(getMetadata(r.cstr)).add(r.name);
+		}
+		return pending;
+	}
+	getDirtyFields(meta) {
+		let dirty = this.dirtyFields.get(meta.tagName);
+		if (!dirty) {
+			dirty = /* @__PURE__ */ new Set();
+			this.dirtyFields.set(meta.tagName, dirty);
+		}
+		return dirty;
+	}
+	getReactables(entity) {
+		const meta = getMetadata(entity);
+		return getEmInternalApi(this.em).isMerging(entity) ? meta.reactablesIncludingReadOnly : meta.reactables;
+	}
+	getReactablesByField(entity, fieldName) {
+		const meta = getMetadata(entity);
+		return (getEmInternalApi(this.em).isMerging(entity) ? meta.reactablesIncludingReadOnlyByField : meta.reactablesByField).get(fieldName) ?? noReactables;
+	}
+};
+/** A shared frozen array for fields with no downstream reactables. */
+const noReactables = Object.freeze([]);
+//#endregion
+export { ReactionsManager };
+
+//# sourceMappingURL=ReactionsManager.js.map

package/build/reactivity/ReactionsManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReactionsManager.js","names":["#needsRecalc","#doAction"],"sources":["../../src/reactivity/ReactionsManager.ts"],"sourcesContent":["import type { Reactable } from \"src/config.ts\";\nimport type { Entity } from \"src/Entity.ts\";\nimport { type EntityManager, getEmInternalApi } from \"src/EntityManager.ts\";\nimport { type EntityMetadata, getMetadata } from \"src/EntityMetadata.ts\";\nimport { NoIdError } from \"src/index.ts\";\nimport { type ReactionLogger, globalLogger, noopReactionLogger } from \"src/logging/ReactionLogger.ts\";\nimport { followReverseHint } from \"src/reactivity/reactiveHints.ts\";\nimport { runInTrustedContext } from \"src/trusted.ts\";\n\nexport type ReactiveAction = { r: Reactable; entity: Entity };\n/**\n * Manages the reactivity of tracking which source fields have changed and finding/recalculating\n * their downstream derived fields.\n *\n * Source fields are usually regular/dumb primitives, i.e. `Author.age` is a source field\n * of `Book.isPublic`, but derived fields can themselves be source fields as well.\n */\nexport class ReactionsManager {\n  /** Stores all source `Reactables`s that have been marked for later traversal. */\n  private pendingReactables: Map<Reactable, { todo: Set<Entity>; done: Set<Entity> }> = new Map();\n  /** Failed actions to retry post-hooks, deduped by target field name -> entity (rare error path). */\n  private actionsPendingTypeErrors: Map<string, Map<Entity, ReactiveAction>> = new Map();\n  /**\n   * A map of entity tagName -> fields that have been marked as dirty.\n   *\n   * The key of the map is \"just\" the tag name, instead of a specific entity, b/c at the time of\n   * being marked dirty, we only have the upstream/source entity + fieldName that has changed, and\n   * not the 1-or-more downstream/target entities that will actually recalc.\n   *\n   * Instead, we just track the dirty fields by type-of-entity, which is enough for `isPendingRecalc`.\n   */\n  private dirtyFields: Map<string, Set<string>> = new Map();\n  /**\n   * Tracks which entities have already run a `runOnce` reactable, keyed by the target field\n   * name -> entities. We key on `r.name` (not `r` itself) b/c two `Reactable`s reverse-indexed\n   * from different source paths can target the same derived field, and must dedupe together.\n   * Keying the outer map by field name (of which there are few) instead of by entity (of which\n   * there are many) means we allocate just one `Set` per distinct field name, rather than a\n   * `Set` per entity or the old per-action `${entity.toTaggedString()}_${r.name}` key strings.\n   */\n  private processedActions: Map<string, Set<Entity>> = new Map();\n  #needsRecalc = { populate: false, query: false, reaction: false };\n  // Accessible for EntityManager.runValidation to reuse\n  logger: ReactionLogger = globalLogger ?? noopReactionLogger;\n  private em: EntityManager;\n  /** These are NPEs that *might* have been from invalid m2o fields, so we only throw them after validation. */\n  private suppressedTypeErrors: Error[] = [];\n\n  constructor(em: EntityManager) {\n    this.em = em;\n  }\n\n  /**\n   * Queue all downstream reactive fields that depend on `fieldName` as a source field.\n   *\n   * This method can be synchronous b/c we internally queue the `Reactable` reverse\n   * indexes on the given source `fieldName`, and don't crawl/walk back to the downstream\n   * entities/fields until `recalcPendingReactables` is called.\n   */\n  queueDownstreamReactables(entity: Entity, fieldName: string): void {\n    // Use the reverse index of Reactables that configureMetadata sets up\n    for (const r of this.getReactablesByField(entity, fieldName)) {\n      // We always queue the reactable/entity, even if we're mid-flush or even mid-recalc, to avoid:\n      // - firstName is changed from a1 to a2\n      // - this triggers firstName's reactable to `Author.initials` to be queued\n      // - during the 1st em.flush loop, we recalc `Author.initials` and it didn't change\n      // - during the 1st em.flush loop, a hook changes firstName from a2 to b2\n      // - if we skip re-queuing firstName's reactables, we will miss that initials needs\n      //   its `.load()` called again so that it's `setField` marks `initials` as\n      //   dirty, otherwise it will be left out of any INSERTs/UPDATEs.\n      this.getPending(r).todo.add(entity);\n      this.#needsRecalc[r.kind] = true;\n      this.logger.logQueued(entity, fieldName, r);\n    }\n  }\n\n  /** Dequeues reactivity on `fieldName`, i.e. if it's no longer dirty. */\n  dequeueDownstreamReactables(entity: Entity, fieldName: string): void {\n    // Use the reverse index of Reactables that configureMetadata sets up\n    for (const r of this.getReactablesByField(entity, fieldName)) {\n      const pending = this.getPending(r);\n      if (pending.done.has(entity)) {\n        // Ironically, if we've already run this reactable, asking to dequeue probably means\n        // we need to run it again (to recalc its value), b/c this could be a mid-flush change, i.e.:\n        // - firstName = a1 from db\n        // - firstName is changed to a2, triggers initials reactable\n        // - firstName is changed back to a1, which is the original value, so setField\n        //   thinks we can dequeue the reactable\n        // - but actually our reactable needs to be re-run with the restored value\n        pending.todo.add(entity);\n        this.#needsRecalc[r.kind] = true;\n      } else if (r.fields.length === 1) {\n        // We can only delete/dequeue a reaction if `fieldName` is the only or last field\n        // that had triggered `r` to run. Since we don't track that currently, i.e. we'd\n        // need to have a `Pending.dirtyFields`, for now just only dequeue if `r` only\n        // has one field (which is us) anyway.\n        pending.todo.delete(entity);\n      }\n    }\n  }\n\n  /** Queue all downstream reactive fields that depend on this entity being created or deleted. */\n  queueAllDownstreamFields(entity: Entity, reason: \"created\" | \"deleted\"): void {\n    for (const r of this.getReactables(entity)) {\n      this.getPending(r).todo.add(entity);\n      this.#needsRecalc[r.kind] = true;\n      this.logger.logQueuedAll(entity, reason, r);\n    }\n  }\n\n  /**\n   * Returns whether this field might be pending recalc.\n   *\n   * This is technically a guess, b/c our reaction infra may not yet have crawled from an upstream\n   * source field down to the `N` specific target entities that need recalced, and instead just\n   * knows \"it will need to do that soon\" i.e. at the next `em.flush`.\n   *\n   * So, instead this is a heuristic that reports if `fieldName` has been marked dirty for _some_\n   * entities of type `entity`, but we don't technically know if that's _this_ entity.\n   *\n   * I.e. this might return false positives, but should never return false negatives.\n   */\n  isMaybePendingRecalc(entity: Entity, fieldName: string): boolean {\n    return this.getDirtyFields(getMetadata(entity)).has(fieldName);\n  }\n\n  hasPendingReactiveQueries(): boolean {\n    return this.#needsRecalc.query;\n  }\n\n  /**\n   * Given source `Reactable` \"reverse indexes\" that have been queued as dirty by calls\n   * to setters, `em.register`, or `em.delete`, asynchronously walks/crawls to the downstream\n   * derived fields and calls `.load()` on them to calc.\n   *\n   * We also do this in a loop to handle reactive fields depending on other reactive fields.\n   */\n  async recalcPendingReactables(kind: \"reactables\" | \"reactiveQueries\") {\n    if (this.needsRecalc(kind)) this.logger.logStartingRecalc(this.em, kind);\n\n    let loops = 0;\n    while (this.needsRecalc(kind)) {\n      // ...we probably should only loop for `kind=reactables` Reactables, and `kind=reactiveQueries`\n      // AsyncReactiveFields should probably only have a single loop, after which we return and\n      // let `em.flush` push the latest values to the db, so our 2nd-order AsyncReactiveFields\n      // will see the latest value.\n      if (kind === \"reactables\") {\n        this.#needsRecalc.populate = false;\n        this.#needsRecalc.reaction = false;\n      } else {\n        this.#needsRecalc.query = false;\n      }\n\n      // Dedupe actions by (target field name, entity); see the `processedActions` docs for why\n      // we key on `r.name` instead of `r` or the old per-action key strings\n      const seen: Map<string, Set<Entity>> = new Map();\n      const actions: ReactiveAction[] = [];\n\n      const walks = await Promise.all(\n        [...this.pendingReactables.entries()].map(async ([r, pending]) => {\n          // Skip reactive queries until post-flush\n          if (kind === \"reactables\" && r.kind === \"query\") return undefined;\n          if (kind === \"reactiveQueries\" && (r.kind === \"populate\" || r.kind === \"reaction\")) return undefined;\n          // Copy pending and clear it\n          const todo = [...pending.todo];\n          if (todo.length === 0) return undefined;\n          pending.todo.clear();\n          for (const doing of todo) pending.done.add(doing);\n          // Walk back from the source to any downstream entities\n          const entities = r.path.length === 0 ? todo : await followReverseHint(r.name, todo, r.path);\n          const actionableEntities = entities.filter((entity) => !entity.isDeletedEntity && entity instanceof r.cstr);\n          let seenEntities = seen.get(r.name);\n          if (!seenEntities) seen.set(r.name, (seenEntities = new Set()));\n          const processed = r.runOnce ? this.processedActions.get(r.name) : undefined;\n          for (const entity of actionableEntities) {\n            // We could arrive at the same reactable from multiple paths (eg, 2 dependent fields changed), so we need to\n            // dedupe based on the entity and reactable to only run each action once for any given entity per loop\n            if (seenEntities.has(entity)) continue;\n            // If this reactable has already run and shouldn't run again, then skip it\n            if (processed && processed.has(entity)) continue;\n            seenEntities.add(entity);\n            actions.push({ r, entity });\n          }\n          return { r, todo, entities: actionableEntities };\n        }),\n      );\n      this.logger.logWalks(walks, \"recalc\");\n      this.logger.logLoadingStart(this.em, actions);\n      // Use allSettled so that we can watch for derived values that want to use an entity's id\n      // i.e. they can fail, but we'll queue them from later.\n      const startTime = this.logger.now();\n      const results = await runInTrustedContext(() => Promise.allSettled(actions.map((a) => this.#doAction(a))));\n      const endTime = this.logger.now();\n      this.logger.logLoadingEnd(this.em, endTime - startTime);\n\n      // This loop's actions are already unique by (name, entity), so a plain array dedupes fine\n      const actionsPendingAssignedIds: ReactiveAction[] = [];\n      const failures: any[] = [];\n      results.forEach((result, i) => {\n        if (result.status === \"rejected\") {\n          // Let `author.id` and `book.author.get.firstName` errors run again after flush/hooks fills them in\n          if (result.reason instanceof NoIdError) {\n            actionsPendingAssignedIds.push(actions[i]);\n          } else if (result.reason instanceof TypeError) {\n            this.addPendingTypeError(actions[i]);\n          } else {\n            failures.push(result.reason);\n          }\n        }\n      });\n\n      // If we have any actions that need to be re-run because they failed due to a missing id, then we assign ids and\n      // re-run them.\n      if (actionsPendingAssignedIds.length > 0) {\n        await this.em.assignNewIds();\n        this.logger.logLoadingStart(this.em, actionsPendingAssignedIds);\n        const startTime = this.logger.now();\n        const results = await runInTrustedContext(() =>\n          Promise.allSettled(actionsPendingAssignedIds.map((a) => this.#doAction(a))),\n        );\n        const endTime = this.logger.now();\n        this.logger.logLoadingEnd(this.em, endTime - startTime);\n        results.forEach((result, i) => {\n          if (result.status === \"rejected\") {\n            if (result.reason instanceof TypeError) {\n              this.addPendingTypeError(actionsPendingAssignedIds[i]);\n            } else {\n              failures.push(result.reason);\n            }\n          }\n        });\n      }\n\n      if (failures.length > 0) throw failures[0];\n      // Record any successful actions that should only run once so we don't run them again\n      for (const action of actions) {\n        if (action.r.runOnce) {\n          let set = this.processedActions.get(action.r.name);\n          if (!set) this.processedActions.set(action.r.name, (set = new Set()));\n          set.add(action.entity);\n        }\n      }\n      // This should generally not happen, only if two reactive fields depend on each other,\n      // which in theory should probably be caught/blow up in the `configureMetadata` step,\n      // but if it's not caught sooner, at least don't infinite loop.\n      if (loops++ > 50) {\n        throw new Error(\"recalc looped too many times, probably a circular dependency\");\n      }\n    }\n  }\n\n  async recalcPendingTypeErrors() {\n    const actions: ReactiveAction[] = [];\n    for (const byEntity of this.actionsPendingTypeErrors.values()) {\n      for (const action of byEntity.values()) actions.push(action);\n    }\n    this.actionsPendingTypeErrors.clear();\n\n    const startTime = this.logger.now();\n    const results = await runInTrustedContext(() =>\n      Promise.allSettled(actions.filter((a) => !a.entity.isDeletedEntity).map((a) => this.#doAction(a))),\n    );\n    const endTime = this.logger.now();\n    this.logger.logLoadingEnd(this.em, endTime - startTime);\n\n    const failures: any[] = [];\n    results.forEach((result) => {\n      if (result.status === \"rejected\") {\n        if (result.reason instanceof TypeError) {\n          // Defer to the validation error to catch this\n          this.suppressedTypeErrors.push(result.reason);\n        } else {\n          failures.push(result.reason);\n        }\n      }\n    });\n    if (failures.length > 0) throw failures[0];\n  }\n\n  get hasPendingTypeErrors(): boolean {\n    return this.actionsPendingTypeErrors.size > 0;\n  }\n\n  /** Clears all the pending source fields, i.e. after `em.flush` is complete. */\n  clear(): void {\n    this.pendingReactables = new Map();\n    this.processedActions.clear();\n  }\n\n  setLogger(logger: ReactionLogger | undefined): void {\n    this.logger = logger ?? noopReactionLogger;\n  }\n\n  clearSuppressedTypeErrors(): void {\n    this.suppressedTypeErrors = [];\n  }\n\n  throwIfAnySuppressedTypeErrors(): void {\n    if (this.suppressedTypeErrors.length > 0) {\n      throw this.suppressedTypeErrors[0];\n    }\n  }\n\n  #doAction(action: ReactiveAction) {\n    const { r, entity } = action;\n    return r.kind === \"reaction\" ? r.fn(entity, this.em.ctx) : (entity as any)[r.name].load();\n  }\n\n  /** Remembers a TypeError'd action to retry post-hooks, deduped by (target field name, entity). */\n  private addPendingTypeError(action: ReactiveAction): void {\n    let byEntity = this.actionsPendingTypeErrors.get(action.r.name);\n    if (!byEntity) this.actionsPendingTypeErrors.set(action.r.name, (byEntity = new Map()));\n    byEntity.set(action.entity, action);\n  }\n\n  needsRecalc(kind: \"reactables\" | \"reactiveQueries\"): boolean {\n    return kind === \"reactables\" ? this.#needsRecalc.populate || this.#needsRecalc.reaction : this.#needsRecalc.query;\n  }\n\n  private getPending(r: Reactable): { todo: Set<Entity>; done: Set<Entity> } {\n    let pending = this.pendingReactables.get(r);\n    if (!pending) {\n      pending = { todo: new Set(), done: new Set() };\n      this.pendingReactables.set(r, pending);\n      // The dirty field name is constant per reactable, so mark it once on the first\n      // queue instead of paying the `getMetadata` + map lookup on every queued entity.\n      this.getDirtyFields(getMetadata(r.cstr)).add(r.name);\n    }\n    return pending;\n  }\n\n  private getDirtyFields(meta: EntityMetadata): Set<string> {\n    let dirty = this.dirtyFields.get(meta.tagName);\n    if (!dirty) {\n      dirty = new Set();\n      this.dirtyFields.set(meta.tagName, dirty);\n    }\n    return dirty;\n  }\n\n  private getReactables(entity: Entity): Reactable[] {\n    // If two books are getting merged, and so a normally-immutable `BookReview.book` is being changed,\n    // then even normally-immutable fields need to be recalculated.\n    const meta = getMetadata(entity);\n    return getEmInternalApi(this.em).isMerging(entity) ? meta.reactablesIncludingReadOnly! : meta.reactables!;\n  }\n\n  private getReactablesByField(entity: Entity, fieldName: string): readonly Reactable[] {\n    const meta = getMetadata(entity);\n    const byField = getEmInternalApi(this.em).isMerging(entity)\n      ? meta.reactablesIncludingReadOnlyByField!\n      : meta.reactablesByField!;\n    // Most fields have no reactables, so return a shared empty array instead of allocating one per set\n    return byField.get(fieldName) ?? noReactables;\n  }\n}\n\n/** A shared frozen array for fields with no downstream reactables. */\nconst noReactables: readonly Reactable[] = Object.freeze([]);\n"],"mappings":"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"}

package/build/reactivity/reactiveHints.cjs

@@ -0,0 +1,328 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_normalizeHints = require("../normalizeHints.cjs");
+const require_relations_ReactiveGetter = require("../relations/ReactiveGetter.cjs");
+const require_relations_RecursiveCollection = require("../relations/RecursiveCollection.cjs");
+const require_relations_hasProperty = require("../relations/hasProperty.cjs");
+require("../relations/index.cjs");
+const require_utils = require("../utils.cjs");
+const require_getProperties = require("../getProperties.cjs");
+const require_EntityMetadata = require("../EntityMetadata.cjs");
+const require_EntityManager = require("../EntityManager.cjs");
+const require_Entity = require("../Entity.cjs");
+const require_BaseEntity = require("../BaseEntity.cjs");
+//#region src/reactivity/reactiveHints.ts
+/**
+* Takes a reactive hint and returns the `ReactiveTarget`s that, should they change, need to
+* walk back to this watching reactable.
+*
+* @param rootType The original type that contained the reactive rule/field, used for helpful error messages
+* @param entityType The current entity of the step we're walking
+* @param hint The current hint we're walking
+* @param reactForOtherSide the name of our FK column, if the previous collection needs to react to our FK changing
+* @param isFirst
+*/
+function reverseReactiveHint(rootType, entityType, hint, reactForOtherSide, reactForOtherSideIsReadOnly, isFirst = true) {
+	const meta = require_EntityMetadata.getMetadata(entityType);
+	const fields = [];
+	const readOnlyFields = [];
+	const maybeRecursive = [];
+	if (reactForOtherSide) {
+		const _fields = reactForOtherSideIsReadOnly ? readOnlyFields : fields;
+		_fields.push(reactForOtherSide);
+		if (meta.timestampFields?.deletedAt) _fields.push(meta.timestampFields.deletedAt);
+	}
+	const subHintTargets = Object.entries(require_normalizeHints.normalizeHint(hint)).flatMap(([keyMaybeSuffix, subHint]) => {
+		return reverseSubHint(rootType, entityType, hint, meta, fields, readOnlyFields, maybeRecursive, keyMaybeSuffix, subHint);
+	});
+	const myTargets = [];
+	if (fields.length > 0 || isFirst || reactForOtherSideIsReadOnly === "field-read-only") myTargets.push({
+		kind: "update",
+		entity: entityType,
+		fields,
+		path: []
+	});
+	if (readOnlyFields.length > 0) myTargets.push({
+		kind: "read-only",
+		entity: entityType,
+		fields: readOnlyFields,
+		path: []
+	});
+	return [
+		...myTargets,
+		...maybeRecursive,
+		...subHintTargets
+	];
+}
+function reverseSubHint(rootType, entityType, hint, meta, fields, readOnlyFields, maybeRecursive, keyMaybeSuffix, subHint) {
+	const key = keyMaybeSuffix.replace(require_normalizeHints.suffixRe, "");
+	const field = meta.allFields[key];
+	const isReadOnly = !!keyMaybeSuffix.match(require_normalizeHints.suffixRe) || field && field.immutable;
+	const _fields = isReadOnly ? readOnlyFields : fields;
+	if (field) switch (field.kind) {
+		case "m2o": {
+			_fields.push(field.fieldName);
+			const otherMeta = field.otherMetadata();
+			if (!otherMeta.allFields[field.otherFieldName] && !isAllReadOnly(subHint)) throw new Error(`Invalid hint in ${rootType.name}.ts, we don't currently support reacting through ReactiveReferences, ${JSON.stringify(hint)}`);
+			return reverseReactiveHint(rootType, otherMeta.cstr, subHint, void 0, false, false).map(appendPath(maybeAddTypeFilterSuffix(meta, field)));
+		}
+		case "poly":
+			_fields.push(field.fieldName);
+			return field.components.flatMap((comp) => {
+				return reverseReactiveHint(rootType, comp.otherMetadata().cstr, subHint, void 0, false, false).map(appendPath(maybeAddTypeFilterSuffix(meta, comp)));
+			});
+		case "m2m": {
+			_fields.push(field.fieldName);
+			const otherFieldName = maybeAddTypeFilterSuffix(meta, field);
+			return reverseReactiveHint(rootType, field.otherMetadata().cstr, subHint, void 0, false, false).map(appendPath(otherFieldName));
+		}
+		case "o2m":
+		case "o2o": {
+			const isOtherReadOnly = field.otherMetadata().allFields[field.otherFieldName].immutable;
+			const otherFieldName = maybeAddTypeFilterSuffix(meta, field);
+			return reverseReactiveHint(rootType, field.otherMetadata().cstr, subHint, field.otherFieldName, isReadOnly ? "hint-read-only" : isOtherReadOnly ? "field-read-only" : false, false).map(appendPath(otherFieldName));
+		}
+		case "primaryKey":
+		case "primitive":
+		case "enum":
+			_fields.push(key);
+			return [];
+		case "m2mEnum":
+			_fields.push(key);
+			return [];
+		default: throw new Error(`Invalid hint in ${rootType.name}.ts hint ${JSON.stringify(hint)}`);
+	}
+	else {
+		const p = require_getProperties.getProperties(meta)[key];
+		if (p instanceof require_relations_hasProperty.PropertyImpl) {
+			if (isReadOnly) return [];
+			if (!p.reactiveHint) throw new Error(`Property ${key} cannot be used in reactive hints in ${rootType.name}.ts hint ${JSON.stringify(hint)}, please use hasReactiveProperty instead`);
+			return reverseReactiveHint(rootType, meta.cstr, p.reactiveHint, void 0, false, false);
+		} else if (p instanceof require_relations_ReactiveGetter.ReactiveGetterImpl) {
+			if (isReadOnly) return [];
+			return reverseReactiveHint(rootType, meta.cstr, p.reactiveHint, void 0, false, false);
+		} else if (p instanceof require_relations_RecursiveCollection.RecursiveParentsCollectionImpl) {
+			const { otherFieldName, m2oFieldName } = p;
+			_fields.push(m2oFieldName);
+			maybeRecursive.push({
+				kind: isReadOnly ? "read-only" : "update",
+				entity: entityType,
+				fields: recursiveMembershipFields(meta, m2oFieldName),
+				path: [otherFieldName]
+			});
+			return reverseReactiveHint(rootType, entityType, subHint, void 0, false).map(appendPath(otherFieldName));
+		} else if (p instanceof require_relations_RecursiveCollection.RecursiveChildrenCollectionImpl) {
+			const { otherFieldName, o2mFieldName } = p;
+			const m2oFieldName = meta.allFields[o2mFieldName].otherFieldName;
+			_fields.push(m2oFieldName);
+			maybeRecursive.push({
+				kind: isReadOnly ? "read-only" : "update",
+				entity: entityType,
+				fields: recursiveMembershipFields(meta, m2oFieldName),
+				path: [otherFieldName]
+			});
+			return reverseReactiveHint(rootType, entityType, subHint, void 0, false).map(appendPath(otherFieldName));
+		} else if (p instanceof require_relations_RecursiveCollection.RecursiveM2mCollectionImpl) {
+			const { otherFieldName, m2mFieldName } = p;
+			_fields.push(m2mFieldName);
+			maybeRecursive.push({
+				kind: isReadOnly ? "read-only" : "update",
+				entity: entityType,
+				fields: recursiveMembershipFields(meta, m2mFieldName),
+				path: [otherFieldName]
+			});
+			return reverseReactiveHint(rootType, entityType, subHint, void 0, false).map(appendPath(otherFieldName));
+		} else throw new Error(`Invalid hint in ${rootType.name}.ts ${JSON.stringify(hint)}`);
+	}
+}
+function maybeAddTypeFilterSuffix(meta, field) {
+	const otherField = field.otherMetadata().allFields[field.otherFieldName];
+	if (!otherField) {
+		if (!("kind" in field && field.kind === "m2o" && field.derived === "async")) require_utils.fail(`No field ${field.otherMetadata().type}.${field.otherFieldName}`);
+		return field.otherFieldName;
+	}
+	const nextFieldIsPoly = otherField.kind === "poly";
+	const nextFieldPointsToBaseType = !!meta.baseType && otherField.kind !== "poly" && otherField.otherMetadata().cstr !== meta.cstr;
+	return nextFieldIsPoly || nextFieldPointsToBaseType ? `${field.otherFieldName}@${meta.type}` : field.otherFieldName;
+}
+/**
+* Walks `reverseHint` for every entity in `entities`.
+*
+* I.e. given `[book1, book2]` and `["author", 'publisher"]`, will return all the books' authors' publishers.
+*
+* Note that for references (and only references), we walk both through "the current value"
+* and prior values remembered in `referenceHistory`. This is fundamentally because references are the true "owner"
+* of the relation, while collections are derived.
+*
+* For example, with reversals walking through collections:
+*
+* - Given a hint `book: { author: firstName }`
+* - Which reverses to `author[firstName] -> books`
+* - When we walk through `a1.books`, we use only the current value, which might have only `[b2]` in it.
+* - We don't need to worry about "the old a1.books" value, which might have previously had `[b1]` in it,
+*   because the `b1.author` changing authors (from `a1` to `a2`) will trigger its own reactivity.
+*
+* Contrast with reversals walking through references:
+*
+* - Given a hint `author: { books: "title" }`
+* - Which reverses to `book[title] -> author`
+* - When we traverse through `b1.author`, we use both the current value and remembered values, so that both
+*   "our prior authors" and "our new author" see their latest `author.books` collection values.
+*
+* Delete cleanup runs before reverse hints are walked, so the current relation value may already be unset by the
+* time we get here. For persisted entities, `cleanupOnEntityDeleted` clears the owning FK via `setField`, which
+* remembers the prior FK in `referenceHistory`; this lets us still find the old owner. For collection reversals
+* this is enough because collections are derived from the owning FK: removing `b1` from `a1.books` is represented
+* by `b1.author` changing, not by an independent "old books" snapshot.
+*
+* References can also have transient values during a unit of work, i.e. a ReactiveField might observe `b1.author=a2`
+* before the final flush changes it to `a3`. `setField` remembers both original and transient reference values
+* separately from `originalData`, and we walk them in addition to the current value.
+*/
+async function followReverseHint(reactionName, entities, reverseHint) {
+	let current = new Set(entities);
+	const paths = [...reverseHint];
+	while (paths.length) {
+		const [fieldName, viaType] = paths.shift().split("@");
+		const promises = new Array(current.size);
+		for (const c of current) {
+			const relation = c[fieldName];
+			if (!relation) continue;
+			const currentValuePromise = maybeApplyTypeFilter(relation.load(), viaType);
+			promises.push(currentValuePromise);
+			const fieldKind = require_EntityMetadata.getMetadata(c).allFields[fieldName]?.kind;
+			const isReference = fieldKind === "m2o" || fieldKind === "poly";
+			const isManyToMany = fieldKind === "m2m";
+			if (isReference) for (const value of require_BaseEntity.getInstanceData(c).getReferenceHistory(fieldName)) promises.push(maybeApplyTypeFilter(loadReferenceHistoryValue(c, value), viaType));
+			if (isManyToMany) {
+				const m2m = c[fieldName];
+				const joinRows = require_EntityManager.getEmInternalApi(m2m.entity.em).joinRows(m2m);
+				promises.push(joinRows.removedFor(m2m, c));
+			}
+			if (relation instanceof require_relations_RecursiveCollection.RecursiveParentsCollectionImpl) {
+				const { m2oFieldName } = relation;
+				for (const value of require_BaseEntity.getInstanceData(c).getReferenceHistory(m2oFieldName)) promises.push(loadReferenceHistoryValue(c, value).then((oldParent) => {
+					if (!oldParent) return void 0;
+					return oldParent[fieldName].load().then((parents) => {
+						return [oldParent, ...parents];
+					});
+				}));
+			}
+		}
+		const nextLevel = await Promise.all(promises);
+		current = require_utils.flatAndUnique(nextLevel);
+	}
+	return [...current];
+}
+/** Converts a normalized reactive `hint` into a load hint. */
+function convertToLoadHint(meta, hint, allowCustomKeys = false) {
+	const loadHint = {};
+	for (const [keyMaybeSuffix, subHint] of Object.entries(require_normalizeHints.normalizeHint(hint))) {
+		let key = keyMaybeSuffix.replace(require_normalizeHints.suffixRe, "");
+		let field = meta.allFields[key];
+		if (!field && allowCustomKeys) {
+			const realField = Object.values(meta.allFields).find((f) => f.fieldIdName === key);
+			if (realField) {
+				field = realField;
+				key = realField.fieldName;
+			}
+		}
+		if (field) switch (field.kind) {
+			case "m2m":
+			case "m2o":
+			case "o2m":
+			case "o2o":
+				require_utils.mergeNormalizedHints(loadHint, { [key]: convertToLoadHint(field.otherMetadata(), subHint, allowCustomKeys) });
+				break;
+			case "poly":
+				for (const comp of field.components) require_utils.mergeNormalizedHints(loadHint, { [key]: Object.fromEntries(Object.entries(convertToLoadHint(comp.otherMetadata(), subHint, allowCustomKeys)).map(([subKey, subHint]) => [`${subKey}@${comp.otherMetadata().type}`, subHint])) });
+				break;
+			case "primitive":
+			case "enum":
+				if (field.derived === "async") require_utils.mergeNormalizedHints(loadHint, { [key]: {} });
+				continue;
+			case "m2mEnum":
+				require_utils.mergeNormalizedHints(loadHint, { [key]: {} });
+				break;
+			case "primaryKey": continue;
+			default: throw new Error(`Invalid reactive hint ${meta.tableName} ${JSON.stringify(hint)}`);
+		}
+		else {
+			const p = require_getProperties.getProperties(meta)[key];
+			if (p instanceof require_relations_RecursiveCollection.RecursiveParentsCollectionImpl) require_utils.mergeNormalizedHints(loadHint, { [p.fieldName]: convertToLoadHint(meta, subHint, allowCustomKeys) });
+			else if (p instanceof require_relations_RecursiveCollection.RecursiveChildrenCollectionImpl) require_utils.mergeNormalizedHints(loadHint, { [p.fieldName]: convertToLoadHint(meta, subHint, allowCustomKeys) });
+			else if (p instanceof require_relations_RecursiveCollection.RecursiveM2mCollectionImpl) require_utils.mergeNormalizedHints(loadHint, { [p.fieldName]: convertToLoadHint(meta, subHint, allowCustomKeys) });
+			else if (p && p.reactiveHint) require_utils.mergeNormalizedHints(loadHint, convertToLoadHint(meta, p.reactiveHint, allowCustomKeys));
+			else if (!allowCustomKeys) require_utils.fail(`Invalid reactive hint on ${meta.tableName} ${JSON.stringify(hint)}`);
+		}
+	}
+	return loadHint;
+}
+function maybeApplyTypeFilter(loadPromise, viaType) {
+	if (viaType) return loadPromise.then((loaded) => {
+		if (Array.isArray(loaded)) return loaded.filter((e) => isTypeOrSubType(e, viaType));
+		else if (loaded && isTypeOrSubType(loaded, viaType)) return loaded;
+		else return;
+	});
+	return loadPromise;
+}
+/** Loads a remembered reference value so reverse-hint walking can revisit it. */
+function loadReferenceHistoryValue(entity, value) {
+	if (require_Entity.isEntity(value)) return Promise.resolve(value);
+	if (require_EntityManager.isId(value)) return entity.em.load(value);
+	return Promise.resolve(void 0);
+}
+/** Returns true if `entity` is exactly `typeName` or a subtype of `typeName`.
+*
+* Used to honor poly/type filters like `@Publisher` during reverse-hint walks:
+* a `SmallPublisher` entity should pass an `@Publisher` filter because it is
+* a Publisher via inheritance.
+*/
+function isTypeOrSubType(entity, typeName) {
+	const meta = require_EntityMetadata.getMetadata(entity);
+	return meta.type === typeName || meta.baseTypes.some((b) => b.type === typeName);
+}
+function isPolyHint(key) {
+	return key.includes("@");
+}
+function splitPolyHintToKeyAndType(key) {
+	const [k, type] = key.split("@");
+	return [k, type];
+}
+/** If this hint is a poly like `author@Book`, return the type, otherwise return undefined. */
+function getRelationFromMaybePolyKey(entity, key) {
+	if (isPolyHint(key)) {
+		const [realKey, typeName] = splitPolyHintToKeyAndType(key);
+		if (!require_EntityMetadata.getBaseAndSelfMetas(require_EntityMetadata.getMetadata(entity)).some((meta) => meta.type === typeName)) return void 0;
+		return entity[realKey];
+	} else return entity[key];
+}
+/**
+* For an `author -> books -> bookReviews` hint, appends `BookReview.book`, `Book.author`,
+* i.e. the "other side" relation, to the reversed path on the way "out" from a mutated BookReview
+* to the target `Author` RF/RR/rule.
+*/
+function appendPath(reverseField) {
+	return (rt) => {
+		rt.path = [...rt.path, reverseField];
+		return rt;
+	};
+}
+/** Recursive membership changes on soft deletion or resurrection, even when the underlying relation is unchanged. */
+function recursiveMembershipFields(meta, fieldName) {
+	const deletedAt = require_EntityMetadata.getBaseMeta(meta).timestampFields?.deletedAt;
+	return deletedAt ? [fieldName, deletedAt] : [fieldName];
+}
+function isAllReadOnly(hint) {
+	for (const [key, subHint] of Object.entries(require_normalizeHints.normalizeHint(hint))) if (!((key.endsWith("_ro") || key.endsWith(":ro")) && isAllReadOnly(subHint))) return false;
+	return true;
+}
+//#endregion
+exports.convertToLoadHint = convertToLoadHint;
+exports.followReverseHint = followReverseHint;
+exports.getRelationFromMaybePolyKey = getRelationFromMaybePolyKey;
+exports.isPolyHint = isPolyHint;
+exports.isTypeOrSubType = isTypeOrSubType;
+exports.reverseReactiveHint = reverseReactiveHint;
+exports.splitPolyHintToKeyAndType = splitPolyHintToKeyAndType;
+
+//# sourceMappingURL=reactiveHints.cjs.map