joist-core 2.3.0 → 2.4.0

package/build/relations/ReactiveField.cjs

@@ -0,0 +1,114 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_relations_AbstractPropertyImpl = require("./AbstractPropertyImpl.cjs");
+const require_relations_PropertySymbols = require("./PropertySymbols.cjs");
+const require_reactivity_reactiveHints = require("../reactivity/reactiveHints.cjs");
+const require_loading_loadHints = require("../loading/loadHints.cjs");
+const require_fields = require("../fields.cjs");
+const require_newEntity = require("../newEntity.cjs");
+const require_EntityMetadata = require("../EntityMetadata.cjs");
+require("../index.cjs");
+const require_EntityManager = require("../EntityManager.cjs");
+require("../Entity.cjs");
+//#region src/relations/ReactiveField.ts
+/**
+* Creates a calculated derived value from a load hint + lambda.
+*
+* The property can be accessed by default as a promise, with `someProperty.load()`.
+*
+* But if `someProperty` is used as a populate hint, then it can be accessed synchronously,
+* with `someProperty.get`.
+*/
+function hasReactiveField(hint, fn) {
+	return require_newEntity.lazyField((entity, fieldName) => {
+		const field = require_EntityMetadata.getMetadata(entity).allFields[fieldName];
+		return new ReactiveFieldImpl(entity, field, hint, fn);
+	});
+}
+var ReactiveFieldImpl = class extends require_relations_AbstractPropertyImpl.AbstractPropertyImpl {
+	fn;
+	#field;
+	#reactiveHint;
+	#loadPromise;
+	#isLoaded;
+	#isCached = false;
+	constructor(entity, field, reactiveHint, fn) {
+		super(entity);
+		this.fn = fn;
+		this.#field = field;
+		this.#reactiveHint = reactiveHint;
+	}
+	async load(opts) {
+		if (!this.isLoaded || opts?.forceReload) return this.#loadPromise ??= this.entity.em.populate(this.entity, { hint: this.loadHint }).then(() => {
+			this.#loadPromise = void 0;
+			this.#isLoaded = true;
+			require_EntityManager.getEmInternalApi(this.entity.em).isLoadedCache.add(this);
+			this.resetCacheUnlessFactoryPinned();
+			return this.get;
+		});
+		this.resetCacheUnlessFactoryPinned();
+		return this.get;
+	}
+	/** Returns either the latest calculated value (if loaded) or the previously-calculated value (if not loaded). */
+	get get() {
+		const { fn } = this;
+		if (this.#isCached) return this.fieldValue;
+		if (this.isLoaded) {
+			const newValue = fn(this.entity);
+			if (!require_EntityManager.getEmInternalApi(this.entity.em).isValidating) {
+				require_fields.setField(this.entity, this.fieldName, newValue);
+				this.#isCached = true;
+				require_EntityManager.getEmInternalApi(this.entity.em).isLoadedCache.add(this);
+			}
+			return newValue;
+		} else if (this.isSet) {
+			this.#isCached = true;
+			require_EntityManager.getEmInternalApi(this.entity.em).isLoadedCache.add(this);
+			return this.fieldValue;
+		} else throw new Error(`${this.fieldName} has not been derived yet`);
+	}
+	get fieldName() {
+		return this.#field.fieldName;
+	}
+	get reactiveHint() {
+		return this.#reactiveHint;
+	}
+	get fieldValue() {
+		return require_fields.getField(this.entity, this.fieldName);
+	}
+	get isSet() {
+		return require_fields.isFieldSet(this.entity, this.fieldName);
+	}
+	get isLoaded() {
+		if (this.#isLoaded !== void 0) return this.#isLoaded;
+		this.#isLoaded = require_loading_loadHints.isLoaded(this.entity, this.loadHint);
+		require_EntityManager.getEmInternalApi(this.entity.em).isLoadedCache.add(this);
+		return this.#isLoaded;
+	}
+	resetIsLoaded() {
+		this.#isLoaded = void 0;
+		this.resetCacheUnlessFactoryPinned();
+	}
+	get loadHint() {
+		const meta = require_EntityMetadata.getMetadata(this.entity);
+		return meta.config.__data.cachedReactiveLoadHints[this.fieldName] ??= require_reactivity_reactiveHints.convertToLoadHint(meta, this.reactiveHint);
+	}
+	setFactoryValue(newValue) {
+		require_fields.setField(this.entity, this.fieldName, newValue);
+		this.#isCached = "factory-value";
+	}
+	[require_relations_PropertySymbols.PropertyT] = void 0;
+	resetCacheUnlessFactoryPinned() {
+		if (this.#isCached === "factory-value") return;
+		this.#isCached = false;
+	}
+};
+/** Type guard utility for determining if an entity field is a ReactiveField. */
+function isReactiveField(maybeReactiveField) {
+	return maybeReactiveField instanceof ReactiveFieldImpl;
+}
+//#endregion
+exports.ReactiveFieldImpl = ReactiveFieldImpl;
+exports.hasReactiveField = hasReactiveField;
+exports.isReactiveField = isReactiveField;
+
+//# sourceMappingURL=ReactiveField.cjs.map

package/build/relations/ReactiveField.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReactiveField.cjs","names":["lazyField","getMetadata","AbstractPropertyImpl","#field","#reactiveHint","#loadPromise","#isLoaded","#isCached","getEmInternalApi","getField","isFieldSet","isLoaded","convertToLoadHint","PropertyT"],"sources":["../../src/relations/ReactiveField.ts"],"sourcesContent":["import { type Entity } from \"src/Entity.ts\";\nimport { getEmInternalApi } from \"src/EntityManager.ts\";\nimport { type PrimitiveField, getMetadata } from \"src/EntityMetadata.ts\";\nimport { getField, isFieldSet, setField } from \"src/fields.ts\";\nimport { isLoaded } from \"src/index.ts\";\nimport type { IsLoadedCachable } from \"src/loading/IsLoadedCache.ts\";\nimport { lazyField } from \"src/newEntity.ts\";\nimport { type Reacted, type ReactiveHint, convertToLoadHint } from \"src/reactivity/reactiveHints.ts\";\nimport { AbstractPropertyImpl } from \"src/relations/AbstractPropertyImpl.ts\";\nimport { PropertyT } from \"src/relations/PropertySymbols.ts\";\n\n/**\n * A `ReactiveField` is a value that is derived from other entities/values,\n * similar to a `Property`, but it is also persisted in the database.\n *\n * This allows callers (or SQL queries) to access the value without first calling\n * `await load()` on the property.\n *\n * So, unlike `Property`, `.get` is always available; if the property is unloaded,\n * then `.get` will return the last-calculated value, but if the property is loaded,\n * then it will go ahead and invoke function to calculate the latest value (i.e. so\n * that you can observe the latest & greatest value w/o waiting for `em.flush` to\n * re-calc the value while persisting to the database.\n */\nexport interface ReactiveField<T extends Entity, V> {\n  [PropertyT]: T;\n  isLoaded: boolean;\n  isSet: boolean;\n\n  /**\n   * Calculates the latest derived value.\n   *\n   * Users are not required to call this method explicitly, as Joist will keep the\n   * persisted value automatically in-sync, but if for some reason (code changes,\n   * bug fixes, etc.) you need to trigger an explicit recalc, you can call `.load()`,\n   * any dependent data will be loaded from the database, and the latest value\n   * returned, and then later stored to the database on `em.flush`.\n   *\n   * Note that persisted properties used in load hints, i.e. `em.populate`s that\n   * accidentally list reactive fields (instead of just relations) will not have\n   * `.load()` invoked, and will instead use the previously-calculated value.\n   * The rationale is that one persisted property should be able to declare its\n   * dependency on another persisted property (for its reactive field-level hint)\n   * without causing that dependent property's populate hint to itself be loaded.\n   */\n  load(opts?: { forceReload?: boolean }): Promise<V>;\n\n  /** If loaded, returns the latest derived value, or if unload returns the previously-calculated value. */\n  get: V;\n\n  /**\n   * Returns the as-of-last-flush previously-calculated value.\n   *\n   * This is useful if you have to purposefully avoid using the lambda to calc the latest value,\n   * i.e. if you're in a test and want to watch a calculated value change from some dummy value\n   * to the new derived value.\n   * */\n  fieldValue: V;\n}\n\n/**\n * Creates a calculated derived value from a load hint + lambda.\n *\n * The property can be accessed by default as a promise, with `someProperty.load()`.\n *\n * But if `someProperty` is used as a populate hint, then it can be accessed synchronously,\n * with `someProperty.get`.\n */\nexport function hasReactiveField<T extends Entity, const H extends ReactiveHint<T>, V>(\n  hint: H,\n  fn: (entity: Reacted<T, H>) => V,\n): ReactiveField<T, V> {\n  return lazyField((entity: T, fieldName) => {\n    const field = getMetadata(entity).allFields[fieldName] as PrimitiveField;\n    return new ReactiveFieldImpl(entity, field, hint, fn);\n  });\n}\n\nexport class ReactiveFieldImpl<T extends Entity, H extends ReactiveHint<T>, V>\n  extends AbstractPropertyImpl<T>\n  implements ReactiveField<T, V>, IsLoadedCachable\n{\n  readonly #field: PrimitiveField;\n  readonly #reactiveHint: H;\n  #loadPromise: any;\n  // Initially undefined, then cached as true/false\n  #isLoaded: boolean | undefined;\n  #isCached: boolean | \"factory-value\" = false;\n\n  constructor(\n    entity: T,\n    field: PrimitiveField,\n    reactiveHint: H,\n    private fn: (entity: Reacted<T, H>) => V,\n  ) {\n    super(entity);\n    this.#field = field;\n    this.#reactiveHint = reactiveHint;\n  }\n\n  async load(opts?: { forceReload?: boolean }): Promise<V> {\n    // Even without `forceReload=true`, any explicit calls to `.load()` ==> ensure a fresh value,\n    // because `.get` may have cached the stale/previously-calculated value.\n    //\n    // (Currently `em.populate` / `populateDataLoader` has a hack/escape hatch that ignores calling\n    // RF.load(), to avoid pulling in the RF subgraph over using the materialized value, which ideally would be\n    // replaced with us learning to do the maybeDirty approach.)\n    if (!this.isLoaded || opts?.forceReload) {\n      return (this.#loadPromise ??= this.entity.em.populate(this.entity, { hint: this.loadHint } as any).then(() => {\n        this.#loadPromise = undefined;\n        this.#isLoaded = true;\n        getEmInternalApi(this.entity.em).isLoadedCache.add(this);\n        // Wait and reset `#isCached` until inside this `then`, so that we don't have a race condition where:\n        // - two relations (us and someone else) are both passed to `em.calc`\n        // - their load hint is simpler, so their promises resolves first, and their `.get` calls our `.get`\n        // - our `.get` sees we're not loaded, but calls `fieldValue` for the existing value, and dutifully sets `#isCached=true`\n        // - finally our promise runs, and if we didn't immediately set `#isCached=false` here, our `.get` would again\n        //   early return and keep using the stale fieldValue.\n        this.resetCacheUnlessFactoryPinned();\n        // Go through `this.get` so that `setField` is called to set our latest value\n        return this.get;\n      }));\n    }\n    this.resetCacheUnlessFactoryPinned();\n    return this.get;\n  }\n\n  /** Returns either the latest calculated value (if loaded) or the previously-calculated value (if not loaded). */\n  get get(): V {\n    const { fn } = this;\n    // Some ReactiveFields can have surprisingly expensive calculations, especially in loops\n    // or those that invoke loops, so cache the value.\n    if (this.#isCached) return this.fieldValue;\n    // isLoaded will watch for our previously-loaded subgraph being mutated (isLoaded is locally cached but hooked into\n    // our IsLoadedCache cache that is immediately invalidated on write-path), and if we've drifted to not-loaded, it's\n    // better to fail and tell the user.\n    if (this.isLoaded) {\n      const newValue = fn(this.entity as Reacted<T, H>);\n      if (!getEmInternalApi(this.entity.em).isValidating) {\n        // setField will immediately invalidate downstream #isLoaded/#isCached values\n        setField(this.entity, this.fieldName, newValue);\n        this.#isCached = true;\n        getEmInternalApi(this.entity.em).isLoadedCache.add(this);\n      }\n      return newValue;\n    } else if (this.isSet) {\n      this.#isCached = true;\n      getEmInternalApi(this.entity.em).isLoadedCache.add(this);\n      return this.fieldValue;\n    } else {\n      throw new Error(`${this.fieldName} has not been derived yet`);\n    }\n  }\n\n  get fieldName(): keyof T & string {\n    return this.#field.fieldName as keyof T & string;\n  }\n\n  get reactiveHint(): H {\n    return this.#reactiveHint;\n  }\n\n  get fieldValue(): V {\n    return getField(this.entity, this.fieldName);\n  }\n\n  get isSet() {\n    return isFieldSet(this.entity, this.fieldName);\n  }\n\n  get isLoaded() {\n    // Skip an expensive isLoaded(subgraph) call if no mutations have happened\n    if (this.#isLoaded !== undefined) return this.#isLoaded;\n    this.#isLoaded = isLoaded(this.entity, this.loadHint);\n    getEmInternalApi(this.entity.em).isLoadedCache.add(this);\n    return this.#isLoaded;\n  }\n\n  resetIsLoaded(): void {\n    // Even though we reset this on every mutation, `isLoaded` will still realize when the subgraph\n    // is still loaded (as it did before we added caching), so users won't see false positive.\n    this.#isLoaded = undefined;\n    this.resetCacheUnlessFactoryPinned();\n  }\n\n  get loadHint(): any {\n    const meta = getMetadata(this.entity);\n    return (meta.config.__data.cachedReactiveLoadHints[this.fieldName] ??= convertToLoadHint(meta, this.reactiveHint));\n  }\n\n  setFactoryValue(newValue: any): void {\n    setField(this.entity, this.fieldName, newValue);\n    this.#isCached = \"factory-value\";\n  }\n\n  [PropertyT] = undefined as any as T;\n\n  private resetCacheUnlessFactoryPinned(): void {\n    // If factories asked for a hard-coded value, don't reset the cached flag\n    if (this.#isCached === \"factory-value\") return;\n    this.#isCached = false;\n  }\n}\n\n/** Type guard utility for determining if an entity field is a ReactiveField. */\nexport function isReactiveField(maybeReactiveField: any): maybeReactiveField is ReactiveField<any, any> {\n  return maybeReactiveField instanceof ReactiveFieldImpl;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAoEA,SAAgB,iBACd,MACA,IACqB;CACrB,OAAOA,kBAAAA,WAAW,QAAW,cAAc;EACzC,MAAM,QAAQC,uBAAAA,YAAY,MAAM,CAAC,CAAC,UAAU;EAC5C,OAAO,IAAI,kBAAkB,QAAQ,OAAO,MAAM,EAAE;CACtD,CAAC;AACH;AAEA,IAAa,oBAAb,cACUC,uCAAAA,qBAEV;CAYY;CAXV;CACA;CACA;CAEA;CACA,YAAuC;CAEvC,YACE,QACA,OACA,cACA,IACA;EACA,MAAM,MAAM;EAFJ,KAAA,KAAA;EAGR,KAAKC,SAAS;EACd,KAAKC,gBAAgB;CACvB;CAEA,MAAM,KAAK,MAA8C;EAOvD,IAAI,CAAC,KAAK,YAAY,MAAM,aAC1B,OAAQ,KAAKC,iBAAiB,KAAK,OAAO,GAAG,SAAS,KAAK,QAAQ,EAAE,MAAM,KAAK,SAAS,CAAQ,CAAC,CAAC,WAAW;GAC5G,KAAKA,eAAe,KAAA;GACpB,KAAKC,YAAY;GACjB,sBAAA,iBAAiB,KAAK,OAAO,EAAE,CAAC,CAAC,cAAc,IAAI,IAAI;GAOvD,KAAK,8BAA8B;GAEnC,OAAO,KAAK;EACd,CAAC;EAEH,KAAK,8BAA8B;EACnC,OAAO,KAAK;CACd;;CAGA,IAAI,MAAS;EACX,MAAM,EAAE,OAAO;EAGf,IAAI,KAAKC,WAAW,OAAO,KAAK;EAIhC,IAAI,KAAK,UAAU;GACjB,MAAM,WAAW,GAAG,KAAK,MAAuB;GAChD,IAAI,CAACC,sBAAAA,iBAAiB,KAAK,OAAO,EAAE,CAAC,CAAC,cAAc;IAElD,eAAA,SAAS,KAAK,QAAQ,KAAK,WAAW,QAAQ;IAC9C,KAAKD,YAAY;IACjB,sBAAA,iBAAiB,KAAK,OAAO,EAAE,CAAC,CAAC,cAAc,IAAI,IAAI;GACzD;GACA,OAAO;EACT,OAAO,IAAI,KAAK,OAAO;GACrB,KAAKA,YAAY;GACjB,sBAAA,iBAAiB,KAAK,OAAO,EAAE,CAAC,CAAC,cAAc,IAAI,IAAI;GACvD,OAAO,KAAK;EACd,OACE,MAAM,IAAI,MAAM,GAAG,KAAK,UAAU,0BAA0B;CAEhE;CAEA,IAAI,YAA8B;EAChC,OAAO,KAAKJ,OAAO;CACrB;CAEA,IAAI,eAAkB;EACpB,OAAO,KAAKC;CACd;CAEA,IAAI,aAAgB;EAClB,OAAOK,eAAAA,SAAS,KAAK,QAAQ,KAAK,SAAS;CAC7C;CAEA,IAAI,QAAQ;EACV,OAAOC,eAAAA,WAAW,KAAK,QAAQ,KAAK,SAAS;CAC/C;CAEA,IAAI,WAAW;EAEb,IAAI,KAAKJ,cAAc,KAAA,GAAW,OAAO,KAAKA;EAC9C,KAAKA,YAAYK,0BAAAA,SAAS,KAAK,QAAQ,KAAK,QAAQ;EACpD,sBAAA,iBAAiB,KAAK,OAAO,EAAE,CAAC,CAAC,cAAc,IAAI,IAAI;EACvD,OAAO,KAAKL;CACd;CAEA,gBAAsB;EAGpB,KAAKA,YAAY,KAAA;EACjB,KAAK,8BAA8B;CACrC;CAEA,IAAI,WAAgB;EAClB,MAAM,OAAOL,uBAAAA,YAAY,KAAK,MAAM;EACpC,OAAQ,KAAK,OAAO,OAAO,wBAAwB,KAAK,eAAeW,iCAAAA,kBAAkB,MAAM,KAAK,YAAY;CAClH;CAEA,gBAAgB,UAAqB;EACnC,eAAA,SAAS,KAAK,QAAQ,KAAK,WAAW,QAAQ;EAC9C,KAAKL,YAAY;CACnB;CAEA,CAACM,kCAAAA,aAAa,KAAA;CAEd,gCAA8C;EAE5C,IAAI,KAAKN,cAAc,iBAAiB;EACxC,KAAKA,YAAY;CACnB;AACF;;AAGA,SAAgB,gBAAgB,oBAAwE;CACtG,OAAO,8BAA8B;AACvC"}

package/build/relations/ReactiveField.d.cts

@@ -0,0 +1,88 @@
+import { AbstractPropertyImpl } from "./AbstractPropertyImpl.cjs";
+import { PropertyT } from "./PropertySymbols.cjs";
+import { IsLoadedCachable } from "../loading/IsLoadedCache.cjs";
+import { Reacted, ReactiveHint } from "../reactivity/reactiveHints.cjs";
+import { PrimitiveField } from "../EntityMetadata.cjs";
+import { Entity } from "../Entity.cjs";
+//#region src/relations/ReactiveField.d.ts
+/**
+ * A `ReactiveField` is a value that is derived from other entities/values,
+ * similar to a `Property`, but it is also persisted in the database.
+ *
+ * This allows callers (or SQL queries) to access the value without first calling
+ * `await load()` on the property.
+ *
+ * So, unlike `Property`, `.get` is always available; if the property is unloaded,
+ * then `.get` will return the last-calculated value, but if the property is loaded,
+ * then it will go ahead and invoke function to calculate the latest value (i.e. so
+ * that you can observe the latest & greatest value w/o waiting for `em.flush` to
+ * re-calc the value while persisting to the database.
+ */
+interface ReactiveField<T extends Entity, V> {
+  [PropertyT]: T;
+  isLoaded: boolean;
+  isSet: boolean;
+  /**
+   * Calculates the latest derived value.
+   *
+   * Users are not required to call this method explicitly, as Joist will keep the
+   * persisted value automatically in-sync, but if for some reason (code changes,
+   * bug fixes, etc.) you need to trigger an explicit recalc, you can call `.load()`,
+   * any dependent data will be loaded from the database, and the latest value
+   * returned, and then later stored to the database on `em.flush`.
+   *
+   * Note that persisted properties used in load hints, i.e. `em.populate`s that
+   * accidentally list reactive fields (instead of just relations) will not have
+   * `.load()` invoked, and will instead use the previously-calculated value.
+   * The rationale is that one persisted property should be able to declare its
+   * dependency on another persisted property (for its reactive field-level hint)
+   * without causing that dependent property's populate hint to itself be loaded.
+   */
+  load(opts?: {
+    forceReload?: boolean;
+  }): Promise<V>;
+  /** If loaded, returns the latest derived value, or if unload returns the previously-calculated value. */
+  get: V;
+  /**
+   * Returns the as-of-last-flush previously-calculated value.
+   *
+   * This is useful if you have to purposefully avoid using the lambda to calc the latest value,
+   * i.e. if you're in a test and want to watch a calculated value change from some dummy value
+   * to the new derived value.
+   * */
+  fieldValue: V;
+}
+/**
+ * Creates a calculated derived value from a load hint + lambda.
+ *
+ * The property can be accessed by default as a promise, with `someProperty.load()`.
+ *
+ * But if `someProperty` is used as a populate hint, then it can be accessed synchronously,
+ * with `someProperty.get`.
+ */
+declare function hasReactiveField<T extends Entity, const H extends ReactiveHint<T>, V>(hint: H, fn: (entity: Reacted<T, H>) => V): ReactiveField<T, V>;
+declare class ReactiveFieldImpl<T extends Entity, H extends ReactiveHint<T>, V> extends AbstractPropertyImpl<T> implements ReactiveField<T, V>, IsLoadedCachable {
+  #private;
+  private fn;
+  constructor(entity: T, field: PrimitiveField, reactiveHint: H, fn: (entity: Reacted<T, H>) => V);
+  load(opts?: {
+    forceReload?: boolean;
+  }): Promise<V>;
+  /** Returns either the latest calculated value (if loaded) or the previously-calculated value (if not loaded). */
+  get get(): V;
+  get fieldName(): keyof T & string;
+  get reactiveHint(): H;
+  get fieldValue(): V;
+  get isSet(): boolean;
+  get isLoaded(): boolean;
+  resetIsLoaded(): void;
+  get loadHint(): any;
+  setFactoryValue(newValue: any): void;
+  [PropertyT]: T;
+  private resetCacheUnlessFactoryPinned;
+}
+/** Type guard utility for determining if an entity field is a ReactiveField. */
+declare function isReactiveField(maybeReactiveField: any): maybeReactiveField is ReactiveField<any, any>;
+//#endregion
+export { ReactiveField, ReactiveFieldImpl, hasReactiveField, isReactiveField };
+//# sourceMappingURL=ReactiveField.d.cts.map

package/build/relations/ReactiveField.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReactiveField.d.cts","names":[],"sources":["../../src/relations/ReactiveField.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;UAwBiB,cAAc,UAAU,QAAQ;GAC9C,YAAY;EACb;EACA;;;;;;;;;;;;;;;;;EAkBA,KAAK;IAAS;MAA0B,QAAQ;;EAGhD,KAAK;;;;;;;;EASL,YAAY;;;;;;;;;;iBAWE,iBAAiB,UAAU,cAAc,UAAU,aAAa,IAAI,GAClF,MAAM,GACN,KAAK,QAAQ,QAAQ,GAAG,OAAO,IAC9B,cAAc,GAAG;cAOP,kBAAkB,UAAU,QAAQ,UAAU,aAAa,IAAI,WAClE,qBAAqB,cAClB,cAAc,GAAG,IAAI;;UAatB;EAJV,YACE,QAAQ,GACR,OAAO,gBACP,cAAc,GACN,KAAK,QAAQ,QAAQ,GAAG,OAAO;EAOnC,KAAK;IAAS;MAA0B,QAAQ;;MA4BlD,OAAO;MA0BP,mBAAmB;MAInB,gBAAgB;MAIhB,cAAc;MAId;MAIA;EAQJ;MAOI;EAKJ,gBAAgB;GAKf,YAAiC;UAE1B;;;iBAQM,gBAAgB,0BAA0B,sBAAsB"}

package/build/relations/ReactiveField.d.mts

@@ -0,0 +1,88 @@
+import { AbstractPropertyImpl } from "./AbstractPropertyImpl.mjs";
+import { PropertyT } from "./PropertySymbols.mjs";
+import { IsLoadedCachable } from "../loading/IsLoadedCache.mjs";
+import { Reacted, ReactiveHint } from "../reactivity/reactiveHints.mjs";
+import { PrimitiveField } from "../EntityMetadata.mjs";
+import { Entity } from "../Entity.mjs";
+//#region src/relations/ReactiveField.d.ts
+/**
+ * A `ReactiveField` is a value that is derived from other entities/values,
+ * similar to a `Property`, but it is also persisted in the database.
+ *
+ * This allows callers (or SQL queries) to access the value without first calling
+ * `await load()` on the property.
+ *
+ * So, unlike `Property`, `.get` is always available; if the property is unloaded,
+ * then `.get` will return the last-calculated value, but if the property is loaded,
+ * then it will go ahead and invoke function to calculate the latest value (i.e. so
+ * that you can observe the latest & greatest value w/o waiting for `em.flush` to
+ * re-calc the value while persisting to the database.
+ */
+interface ReactiveField<T extends Entity, V> {
+  [PropertyT]: T;
+  isLoaded: boolean;
+  isSet: boolean;
+  /**
+   * Calculates the latest derived value.
+   *
+   * Users are not required to call this method explicitly, as Joist will keep the
+   * persisted value automatically in-sync, but if for some reason (code changes,
+   * bug fixes, etc.) you need to trigger an explicit recalc, you can call `.load()`,
+   * any dependent data will be loaded from the database, and the latest value
+   * returned, and then later stored to the database on `em.flush`.
+   *
+   * Note that persisted properties used in load hints, i.e. `em.populate`s that
+   * accidentally list reactive fields (instead of just relations) will not have
+   * `.load()` invoked, and will instead use the previously-calculated value.
+   * The rationale is that one persisted property should be able to declare its
+   * dependency on another persisted property (for its reactive field-level hint)
+   * without causing that dependent property's populate hint to itself be loaded.
+   */
+  load(opts?: {
+    forceReload?: boolean;
+  }): Promise<V>;
+  /** If loaded, returns the latest derived value, or if unload returns the previously-calculated value. */
+  get: V;
+  /**
+   * Returns the as-of-last-flush previously-calculated value.
+   *
+   * This is useful if you have to purposefully avoid using the lambda to calc the latest value,
+   * i.e. if you're in a test and want to watch a calculated value change from some dummy value
+   * to the new derived value.
+   * */
+  fieldValue: V;
+}
+/**
+ * Creates a calculated derived value from a load hint + lambda.
+ *
+ * The property can be accessed by default as a promise, with `someProperty.load()`.
+ *
+ * But if `someProperty` is used as a populate hint, then it can be accessed synchronously,
+ * with `someProperty.get`.
+ */
+declare function hasReactiveField<T extends Entity, const H extends ReactiveHint<T>, V>(hint: H, fn: (entity: Reacted<T, H>) => V): ReactiveField<T, V>;
+declare class ReactiveFieldImpl<T extends Entity, H extends ReactiveHint<T>, V> extends AbstractPropertyImpl<T> implements ReactiveField<T, V>, IsLoadedCachable {
+  #private;
+  private fn;
+  constructor(entity: T, field: PrimitiveField, reactiveHint: H, fn: (entity: Reacted<T, H>) => V);
+  load(opts?: {
+    forceReload?: boolean;
+  }): Promise<V>;
+  /** Returns either the latest calculated value (if loaded) or the previously-calculated value (if not loaded). */
+  get get(): V;
+  get fieldName(): keyof T & string;
+  get reactiveHint(): H;
+  get fieldValue(): V;
+  get isSet(): boolean;
+  get isLoaded(): boolean;
+  resetIsLoaded(): void;
+  get loadHint(): any;
+  setFactoryValue(newValue: any): void;
+  [PropertyT]: T;
+  private resetCacheUnlessFactoryPinned;
+}
+/** Type guard utility for determining if an entity field is a ReactiveField. */
+declare function isReactiveField(maybeReactiveField: any): maybeReactiveField is ReactiveField<any, any>;
+//#endregion
+export { ReactiveField, ReactiveFieldImpl, hasReactiveField, isReactiveField };
+//# sourceMappingURL=ReactiveField.d.mts.map

package/build/relations/ReactiveField.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReactiveField.d.mts","names":[],"sources":["../../src/relations/ReactiveField.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;UAwBiB,cAAc,UAAU,QAAQ;GAC9C,YAAY;EACb;EACA;;;;;;;;;;;;;;;;;EAkBA,KAAK;IAAS;MAA0B,QAAQ;;EAGhD,KAAK;;;;;;;;EASL,YAAY;;;;;;;;;;iBAWE,iBAAiB,UAAU,cAAc,UAAU,aAAa,IAAI,GAClF,MAAM,GACN,KAAK,QAAQ,QAAQ,GAAG,OAAO,IAC9B,cAAc,GAAG;cAOP,kBAAkB,UAAU,QAAQ,UAAU,aAAa,IAAI,WAClE,qBAAqB,cAClB,cAAc,GAAG,IAAI;;UAatB;EAJV,YACE,QAAQ,GACR,OAAO,gBACP,cAAc,GACN,KAAK,QAAQ,QAAQ,GAAG,OAAO;EAOnC,KAAK;IAAS;MAA0B,QAAQ;;MA4BlD,OAAO;MA0BP,mBAAmB;MAInB,gBAAgB;MAIhB,cAAc;MAId;MAIA;EAQJ;MAOI;EAKJ,gBAAgB;GAKf,YAAiC;UAE1B;;;iBAQM,gBAAgB,0BAA0B,sBAAsB"}

package/build/relations/ReactiveField.js

@@ -1,144 +1,111 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ReactiveFieldImpl = void 0;
-exports.hasReactiveField = hasReactiveField;
-exports.isReactiveField = isReactiveField;
-const EntityManager_1 = require("../EntityManager");
-const EntityMetadata_1 = require("../EntityMetadata");
-const fields_1 = require("../fields");
-const index_1 = require("../index");
-const newEntity_1 = require("../newEntity");
-const reactiveHints_1 = require("../reactiveHints");
-const AbstractPropertyImpl_1 = require("./AbstractPropertyImpl");
-const hasProperty_1 = require("./hasProperty");
+import { AbstractPropertyImpl } from "./AbstractPropertyImpl.js";
+import { PropertyT } from "./PropertySymbols.js";
+import { convertToLoadHint } from "../reactivity/reactiveHints.js";
+import { isLoaded } from "../loading/loadHints.js";
+import { getField, isFieldSet, setField } from "../fields.js";
+import { lazyField } from "../newEntity.js";
+import { getMetadata } from "../EntityMetadata.js";
+import "../index.js";
+import { getEmInternalApi } from "../EntityManager.js";
+import "../Entity.js";
+//#region src/relations/ReactiveField.ts
 /**
- * Creates a calculated derived value from a load hint + lambda.
- *
- * The property can be accessed by default as a promise, with `someProperty.load()`.
- *
- * But if `someProperty` is used as a populate hint, then it can be accessed synchronously,
- * with `someProperty.get`.
- */
+* Creates a calculated derived value from a load hint + lambda.
+*
+* The property can be accessed by default as a promise, with `someProperty.load()`.
+*
+* But if `someProperty` is used as a populate hint, then it can be accessed synchronously,
+* with `someProperty.get`.
+*/
 function hasReactiveField(hint, fn) {
-    return (0, newEntity_1.lazyField)((entity, fieldName) => {
-        const field = (0, EntityMetadata_1.getMetadata)(entity).allFields[fieldName];
-        return new ReactiveFieldImpl(entity, field, hint, fn);
-    });
+	return lazyField((entity, fieldName) => {
+		const field = getMetadata(entity).allFields[fieldName];
+		return new ReactiveFieldImpl(entity, field, hint, fn);
+	});
 }
-class ReactiveFieldImpl extends AbstractPropertyImpl_1.AbstractPropertyImpl {
-    fn;
-    #field;
-    #reactiveHint;
-    #loadPromise;
-    // Initially undefined, then cached as true/false
-    #isLoaded;
-    #isCached = false;
-    constructor(entity, field, reactiveHint, fn) {
-        super(entity);
-        this.fn = fn;
-        this.#field = field;
-        this.#reactiveHint = reactiveHint;
-    }
-    async load(opts) {
-        // Even without `forceReload=true`, any explicit calls to `.load()` ==> ensure a fresh value,
-        // because `.get` may have cached the stale/previously-calculated value.
-        //
-        // (Currently `em.populate` / `populateDataLoader` has a hack/escape hatch that ignores calling
-        // RF.load(), to avoid pulling in the RF subgraph over using the materialized value, which ideally would be
-        // replaced with us learning to do the maybeDirty approach.)
-        if (!this.isLoaded || opts?.forceReload) {
-            return (this.#loadPromise ??= this.entity.em.populate(this.entity, { hint: this.loadHint }).then(() => {
-                this.#loadPromise = undefined;
-                this.#isLoaded = true;
-                (0, EntityManager_1.getEmInternalApi)(this.entity.em).isLoadedCache.add(this);
-                // Wait and reset `#isCached` until inside this `then`, so that we don't have a race condition where:
-                // - two relations (us and someone else) are both passed to `em.calc`
-                // - their load hint is simpler, so their promises resolves first, and their `.get` calls our `.get`
-                // - our `.get` sees we're not loaded, but calls `fieldValue` for the existing value, and dutifully sets `#isCached=true`
-                // - finally our promise runs, and if we didn't immediately set `#isCached=false` here, our `.get` would again
-                //   early return and keep using the stale fieldValue.
-                this.resetCacheUnlessFactoryPinned();
-                // Go through `this.get` so that `setField` is called to set our latest value
-                return this.get;
-            }));
-        }
-        this.resetCacheUnlessFactoryPinned();
-        return this.get;
-    }
-    /** Returns either the latest calculated value (if loaded) or the previously-calculated value (if not loaded). */
-    get get() {
-        const { fn } = this;
-        // Some ReactiveFields can have surprisingly expensive calculations, especially in loops
-        // or those that invoke loops, so cache the value.
-        if (this.#isCached)
-            return this.fieldValue;
-        // isLoaded will watch for our previously-loaded subgraph being mutated (isLoaded is locally cached but hooked into
-        // our IsLoadedCache cache that is immediately invalidated on write-path), and if we've drifted to not-loaded, it's
-        // better to fail and tell the user.
-        if (this.isLoaded) {
-            const newValue = fn(this.entity);
-            if (!(0, EntityManager_1.getEmInternalApi)(this.entity.em).isValidating) {
-                // setField will immediately invalidate downstream #isLoaded/#isCached values
-                (0, fields_1.setField)(this.entity, this.fieldName, newValue);
-                this.#isCached = true;
-                (0, EntityManager_1.getEmInternalApi)(this.entity.em).isLoadedCache.add(this);
-            }
-            return newValue;
-        }
-        else if (this.isSet) {
-            this.#isCached = true;
-            (0, EntityManager_1.getEmInternalApi)(this.entity.em).isLoadedCache.add(this);
-            return this.fieldValue;
-        }
-        else {
-            throw new Error(`${this.fieldName} has not been derived yet`);
-        }
-    }
-    get fieldName() {
-        return this.#field.fieldName;
-    }
-    get reactiveHint() {
-        return this.#reactiveHint;
-    }
-    get fieldValue() {
-        return (0, fields_1.getField)(this.entity, this.fieldName);
-    }
-    get isSet() {
-        return (0, fields_1.isFieldSet)(this.entity, this.fieldName);
-    }
-    get isLoaded() {
-        // Skip an expensive isLoaded(subgraph) call if no mutations have happened
-        if (this.#isLoaded !== undefined)
-            return this.#isLoaded;
-        this.#isLoaded = (0, index_1.isLoaded)(this.entity, this.loadHint);
-        (0, EntityManager_1.getEmInternalApi)(this.entity.em).isLoadedCache.add(this);
-        return this.#isLoaded;
-    }
-    resetIsLoaded() {
-        // Even though we reset this on every mutation, `isLoaded` will still realize when the subgraph
-        // is still loaded (as it did before we added caching), so users won't see false positive.
-        this.#isLoaded = undefined;
-        this.resetCacheUnlessFactoryPinned();
-    }
-    get loadHint() {
-        const meta = (0, EntityMetadata_1.getMetadata)(this.entity);
-        return (meta.config.__data.cachedReactiveLoadHints[this.fieldName] ??= (0, reactiveHints_1.convertToLoadHint)(meta, this.reactiveHint));
-    }
-    setFactoryValue(newValue) {
-        (0, fields_1.setField)(this.entity, this.fieldName, newValue);
-        this.#isCached = "factory-value";
-    }
-    [hasProperty_1.PropertyT] = undefined;
-    resetCacheUnlessFactoryPinned() {
-        // If factories asked for a hard-coded value, don't reset the cached flag
-        if (this.#isCached === "factory-value")
-            return;
-        this.#isCached = false;
-    }
-}
-exports.ReactiveFieldImpl = ReactiveFieldImpl;
+var ReactiveFieldImpl = class extends AbstractPropertyImpl {
+	fn;
+	#field;
+	#reactiveHint;
+	#loadPromise;
+	#isLoaded;
+	#isCached = false;
+	constructor(entity, field, reactiveHint, fn) {
+		super(entity);
+		this.fn = fn;
+		this.#field = field;
+		this.#reactiveHint = reactiveHint;
+	}
+	async load(opts) {
+		if (!this.isLoaded || opts?.forceReload) return this.#loadPromise ??= this.entity.em.populate(this.entity, { hint: this.loadHint }).then(() => {
+			this.#loadPromise = void 0;
+			this.#isLoaded = true;
+			getEmInternalApi(this.entity.em).isLoadedCache.add(this);
+			this.resetCacheUnlessFactoryPinned();
+			return this.get;
+		});
+		this.resetCacheUnlessFactoryPinned();
+		return this.get;
+	}
+	/** Returns either the latest calculated value (if loaded) or the previously-calculated value (if not loaded). */
+	get get() {
+		const { fn } = this;
+		if (this.#isCached) return this.fieldValue;
+		if (this.isLoaded) {
+			const newValue = fn(this.entity);
+			if (!getEmInternalApi(this.entity.em).isValidating) {
+				setField(this.entity, this.fieldName, newValue);
+				this.#isCached = true;
+				getEmInternalApi(this.entity.em).isLoadedCache.add(this);
+			}
+			return newValue;
+		} else if (this.isSet) {
+			this.#isCached = true;
+			getEmInternalApi(this.entity.em).isLoadedCache.add(this);
+			return this.fieldValue;
+		} else throw new Error(`${this.fieldName} has not been derived yet`);
+	}
+	get fieldName() {
+		return this.#field.fieldName;
+	}
+	get reactiveHint() {
+		return this.#reactiveHint;
+	}
+	get fieldValue() {
+		return getField(this.entity, this.fieldName);
+	}
+	get isSet() {
+		return isFieldSet(this.entity, this.fieldName);
+	}
+	get isLoaded() {
+		if (this.#isLoaded !== void 0) return this.#isLoaded;
+		this.#isLoaded = isLoaded(this.entity, this.loadHint);
+		getEmInternalApi(this.entity.em).isLoadedCache.add(this);
+		return this.#isLoaded;
+	}
+	resetIsLoaded() {
+		this.#isLoaded = void 0;
+		this.resetCacheUnlessFactoryPinned();
+	}
+	get loadHint() {
+		const meta = getMetadata(this.entity);
+		return meta.config.__data.cachedReactiveLoadHints[this.fieldName] ??= convertToLoadHint(meta, this.reactiveHint);
+	}
+	setFactoryValue(newValue) {
+		setField(this.entity, this.fieldName, newValue);
+		this.#isCached = "factory-value";
+	}
+	[PropertyT] = void 0;
+	resetCacheUnlessFactoryPinned() {
+		if (this.#isCached === "factory-value") return;
+		this.#isCached = false;
+	}
+};
 /** Type guard utility for determining if an entity field is a ReactiveField. */
 function isReactiveField(maybeReactiveField) {
-    return maybeReactiveField instanceof ReactiveFieldImpl;
+	return maybeReactiveField instanceof ReactiveFieldImpl;
 }
+//#endregion
+export { ReactiveFieldImpl, hasReactiveField, isReactiveField };
+
 //# sourceMappingURL=ReactiveField.js.map

package/build/relations/ReactiveField.js.map

@@ -1 +1 @@
-{"version":3,"file":"ReactiveField.js","sourceRoot":"","sources":["../../src/relations/ReactiveField.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ReactiveField.js","names":["#field","#reactiveHint","#loadPromise","#isLoaded","#isCached"],"sources":["../../src/relations/ReactiveField.ts"],"sourcesContent":["import { type Entity } from \"src/Entity.ts\";\nimport { getEmInternalApi } from \"src/EntityManager.ts\";\nimport { type PrimitiveField, getMetadata } from \"src/EntityMetadata.ts\";\nimport { getField, isFieldSet, setField } from \"src/fields.ts\";\nimport { isLoaded } from \"src/index.ts\";\nimport type { IsLoadedCachable } from \"src/loading/IsLoadedCache.ts\";\nimport { lazyField } from \"src/newEntity.ts\";\nimport { type Reacted, type ReactiveHint, convertToLoadHint } from \"src/reactivity/reactiveHints.ts\";\nimport { AbstractPropertyImpl } from \"src/relations/AbstractPropertyImpl.ts\";\nimport { PropertyT } from \"src/relations/PropertySymbols.ts\";\n\n/**\n * A `ReactiveField` is a value that is derived from other entities/values,\n * similar to a `Property`, but it is also persisted in the database.\n *\n * This allows callers (or SQL queries) to access the value without first calling\n * `await load()` on the property.\n *\n * So, unlike `Property`, `.get` is always available; if the property is unloaded,\n * then `.get` will return the last-calculated value, but if the property is loaded,\n * then it will go ahead and invoke function to calculate the latest value (i.e. so\n * that you can observe the latest & greatest value w/o waiting for `em.flush` to\n * re-calc the value while persisting to the database.\n */\nexport interface ReactiveField<T extends Entity, V> {\n  [PropertyT]: T;\n  isLoaded: boolean;\n  isSet: boolean;\n\n  /**\n   * Calculates the latest derived value.\n   *\n   * Users are not required to call this method explicitly, as Joist will keep the\n   * persisted value automatically in-sync, but if for some reason (code changes,\n   * bug fixes, etc.) you need to trigger an explicit recalc, you can call `.load()`,\n   * any dependent data will be loaded from the database, and the latest value\n   * returned, and then later stored to the database on `em.flush`.\n   *\n   * Note that persisted properties used in load hints, i.e. `em.populate`s that\n   * accidentally list reactive fields (instead of just relations) will not have\n   * `.load()` invoked, and will instead use the previously-calculated value.\n   * The rationale is that one persisted property should be able to declare its\n   * dependency on another persisted property (for its reactive field-level hint)\n   * without causing that dependent property's populate hint to itself be loaded.\n   */\n  load(opts?: { forceReload?: boolean }): Promise<V>;\n\n  /** If loaded, returns the latest derived value, or if unload returns the previously-calculated value. */\n  get: V;\n\n  /**\n   * Returns the as-of-last-flush previously-calculated value.\n   *\n   * This is useful if you have to purposefully avoid using the lambda to calc the latest value,\n   * i.e. if you're in a test and want to watch a calculated value change from some dummy value\n   * to the new derived value.\n   * */\n  fieldValue: V;\n}\n\n/**\n * Creates a calculated derived value from a load hint + lambda.\n *\n * The property can be accessed by default as a promise, with `someProperty.load()`.\n *\n * But if `someProperty` is used as a populate hint, then it can be accessed synchronously,\n * with `someProperty.get`.\n */\nexport function hasReactiveField<T extends Entity, const H extends ReactiveHint<T>, V>(\n  hint: H,\n  fn: (entity: Reacted<T, H>) => V,\n): ReactiveField<T, V> {\n  return lazyField((entity: T, fieldName) => {\n    const field = getMetadata(entity).allFields[fieldName] as PrimitiveField;\n    return new ReactiveFieldImpl(entity, field, hint, fn);\n  });\n}\n\nexport class ReactiveFieldImpl<T extends Entity, H extends ReactiveHint<T>, V>\n  extends AbstractPropertyImpl<T>\n  implements ReactiveField<T, V>, IsLoadedCachable\n{\n  readonly #field: PrimitiveField;\n  readonly #reactiveHint: H;\n  #loadPromise: any;\n  // Initially undefined, then cached as true/false\n  #isLoaded: boolean | undefined;\n  #isCached: boolean | \"factory-value\" = false;\n\n  constructor(\n    entity: T,\n    field: PrimitiveField,\n    reactiveHint: H,\n    private fn: (entity: Reacted<T, H>) => V,\n  ) {\n    super(entity);\n    this.#field = field;\n    this.#reactiveHint = reactiveHint;\n  }\n\n  async load(opts?: { forceReload?: boolean }): Promise<V> {\n    // Even without `forceReload=true`, any explicit calls to `.load()` ==> ensure a fresh value,\n    // because `.get` may have cached the stale/previously-calculated value.\n    //\n    // (Currently `em.populate` / `populateDataLoader` has a hack/escape hatch that ignores calling\n    // RF.load(), to avoid pulling in the RF subgraph over using the materialized value, which ideally would be\n    // replaced with us learning to do the maybeDirty approach.)\n    if (!this.isLoaded || opts?.forceReload) {\n      return (this.#loadPromise ??= this.entity.em.populate(this.entity, { hint: this.loadHint } as any).then(() => {\n        this.#loadPromise = undefined;\n        this.#isLoaded = true;\n        getEmInternalApi(this.entity.em).isLoadedCache.add(this);\n        // Wait and reset `#isCached` until inside this `then`, so that we don't have a race condition where:\n        // - two relations (us and someone else) are both passed to `em.calc`\n        // - their load hint is simpler, so their promises resolves first, and their `.get` calls our `.get`\n        // - our `.get` sees we're not loaded, but calls `fieldValue` for the existing value, and dutifully sets `#isCached=true`\n        // - finally our promise runs, and if we didn't immediately set `#isCached=false` here, our `.get` would again\n        //   early return and keep using the stale fieldValue.\n        this.resetCacheUnlessFactoryPinned();\n        // Go through `this.get` so that `setField` is called to set our latest value\n        return this.get;\n      }));\n    }\n    this.resetCacheUnlessFactoryPinned();\n    return this.get;\n  }\n\n  /** Returns either the latest calculated value (if loaded) or the previously-calculated value (if not loaded). */\n  get get(): V {\n    const { fn } = this;\n    // Some ReactiveFields can have surprisingly expensive calculations, especially in loops\n    // or those that invoke loops, so cache the value.\n    if (this.#isCached) return this.fieldValue;\n    // isLoaded will watch for our previously-loaded subgraph being mutated (isLoaded is locally cached but hooked into\n    // our IsLoadedCache cache that is immediately invalidated on write-path), and if we've drifted to not-loaded, it's\n    // better to fail and tell the user.\n    if (this.isLoaded) {\n      const newValue = fn(this.entity as Reacted<T, H>);\n      if (!getEmInternalApi(this.entity.em).isValidating) {\n        // setField will immediately invalidate downstream #isLoaded/#isCached values\n        setField(this.entity, this.fieldName, newValue);\n        this.#isCached = true;\n        getEmInternalApi(this.entity.em).isLoadedCache.add(this);\n      }\n      return newValue;\n    } else if (this.isSet) {\n      this.#isCached = true;\n      getEmInternalApi(this.entity.em).isLoadedCache.add(this);\n      return this.fieldValue;\n    } else {\n      throw new Error(`${this.fieldName} has not been derived yet`);\n    }\n  }\n\n  get fieldName(): keyof T & string {\n    return this.#field.fieldName as keyof T & string;\n  }\n\n  get reactiveHint(): H {\n    return this.#reactiveHint;\n  }\n\n  get fieldValue(): V {\n    return getField(this.entity, this.fieldName);\n  }\n\n  get isSet() {\n    return isFieldSet(this.entity, this.fieldName);\n  }\n\n  get isLoaded() {\n    // Skip an expensive isLoaded(subgraph) call if no mutations have happened\n    if (this.#isLoaded !== undefined) return this.#isLoaded;\n    this.#isLoaded = isLoaded(this.entity, this.loadHint);\n    getEmInternalApi(this.entity.em).isLoadedCache.add(this);\n    return this.#isLoaded;\n  }\n\n  resetIsLoaded(): void {\n    // Even though we reset this on every mutation, `isLoaded` will still realize when the subgraph\n    // is still loaded (as it did before we added caching), so users won't see false positive.\n    this.#isLoaded = undefined;\n    this.resetCacheUnlessFactoryPinned();\n  }\n\n  get loadHint(): any {\n    const meta = getMetadata(this.entity);\n    return (meta.config.__data.cachedReactiveLoadHints[this.fieldName] ??= convertToLoadHint(meta, this.reactiveHint));\n  }\n\n  setFactoryValue(newValue: any): void {\n    setField(this.entity, this.fieldName, newValue);\n    this.#isCached = \"factory-value\";\n  }\n\n  [PropertyT] = undefined as any as T;\n\n  private resetCacheUnlessFactoryPinned(): void {\n    // If factories asked for a hard-coded value, don't reset the cached flag\n    if (this.#isCached === \"factory-value\") return;\n    this.#isCached = false;\n  }\n}\n\n/** Type guard utility for determining if an entity field is a ReactiveField. */\nexport function isReactiveField(maybeReactiveField: any): maybeReactiveField is ReactiveField<any, any> {\n  return maybeReactiveField instanceof ReactiveFieldImpl;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAoEA,SAAgB,iBACd,MACA,IACqB;CACrB,OAAO,WAAW,QAAW,cAAc;EACzC,MAAM,QAAQ,YAAY,MAAM,CAAC,CAAC,UAAU;EAC5C,OAAO,IAAI,kBAAkB,QAAQ,OAAO,MAAM,EAAE;CACtD,CAAC;AACH;AAEA,IAAa,oBAAb,cACU,qBAEV;CAYY;CAXV;CACA;CACA;CAEA;CACA,YAAuC;CAEvC,YACE,QACA,OACA,cACA,IACA;EACA,MAAM,MAAM;EAFJ,KAAA,KAAA;EAGR,KAAKA,SAAS;EACd,KAAKC,gBAAgB;CACvB;CAEA,MAAM,KAAK,MAA8C;EAOvD,IAAI,CAAC,KAAK,YAAY,MAAM,aAC1B,OAAQ,KAAKC,iBAAiB,KAAK,OAAO,GAAG,SAAS,KAAK,QAAQ,EAAE,MAAM,KAAK,SAAS,CAAQ,CAAC,CAAC,WAAW;GAC5G,KAAKA,eAAe,KAAA;GACpB,KAAKC,YAAY;GACjB,iBAAiB,KAAK,OAAO,EAAE,CAAC,CAAC,cAAc,IAAI,IAAI;GAOvD,KAAK,8BAA8B;GAEnC,OAAO,KAAK;EACd,CAAC;EAEH,KAAK,8BAA8B;EACnC,OAAO,KAAK;CACd;;CAGA,IAAI,MAAS;EACX,MAAM,EAAE,OAAO;EAGf,IAAI,KAAKC,WAAW,OAAO,KAAK;EAIhC,IAAI,KAAK,UAAU;GACjB,MAAM,WAAW,GAAG,KAAK,MAAuB;GAChD,IAAI,CAAC,iBAAiB,KAAK,OAAO,EAAE,CAAC,CAAC,cAAc;IAElD,SAAS,KAAK,QAAQ,KAAK,WAAW,QAAQ;IAC9C,KAAKA,YAAY;IACjB,iBAAiB,KAAK,OAAO,EAAE,CAAC,CAAC,cAAc,IAAI,IAAI;GACzD;GACA,OAAO;EACT,OAAO,IAAI,KAAK,OAAO;GACrB,KAAKA,YAAY;GACjB,iBAAiB,KAAK,OAAO,EAAE,CAAC,CAAC,cAAc,IAAI,IAAI;GACvD,OAAO,KAAK;EACd,OACE,MAAM,IAAI,MAAM,GAAG,KAAK,UAAU,0BAA0B;CAEhE;CAEA,IAAI,YAA8B;EAChC,OAAO,KAAKJ,OAAO;CACrB;CAEA,IAAI,eAAkB;EACpB,OAAO,KAAKC;CACd;CAEA,IAAI,aAAgB;EAClB,OAAO,SAAS,KAAK,QAAQ,KAAK,SAAS;CAC7C;CAEA,IAAI,QAAQ;EACV,OAAO,WAAW,KAAK,QAAQ,KAAK,SAAS;CAC/C;CAEA,IAAI,WAAW;EAEb,IAAI,KAAKE,cAAc,KAAA,GAAW,OAAO,KAAKA;EAC9C,KAAKA,YAAY,SAAS,KAAK,QAAQ,KAAK,QAAQ;EACpD,iBAAiB,KAAK,OAAO,EAAE,CAAC,CAAC,cAAc,IAAI,IAAI;EACvD,OAAO,KAAKA;CACd;CAEA,gBAAsB;EAGpB,KAAKA,YAAY,KAAA;EACjB,KAAK,8BAA8B;CACrC;CAEA,IAAI,WAAgB;EAClB,MAAM,OAAO,YAAY,KAAK,MAAM;EACpC,OAAQ,KAAK,OAAO,OAAO,wBAAwB,KAAK,eAAe,kBAAkB,MAAM,KAAK,YAAY;CAClH;CAEA,gBAAgB,UAAqB;EACnC,SAAS,KAAK,QAAQ,KAAK,WAAW,QAAQ;EAC9C,KAAKC,YAAY;CACnB;CAEA,CAAC,aAAa,KAAA;CAEd,gCAA8C;EAE5C,IAAI,KAAKA,cAAc,iBAAiB;EACxC,KAAKA,YAAY;CACnB;AACF;;AAGA,SAAgB,gBAAgB,oBAAwE;CACtG,OAAO,8BAA8B;AACvC"}