joist-core 2.3.0 → 2.4.0-next.2

package/build/loading/IsLoadedCache.cjs

@@ -0,0 +1,58 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_EntityMetadata = require("../EntityMetadata.cjs");
+//#region src/loading/IsLoadedCache.ts
+var IsLoadedCache = class {
+	#smartCache = {};
+	#naiveCache = /* @__PURE__ */ new Set();
+	#smartDirtySets = 0;
+	#naiveDirtySets = 0;
+	/** Adds a ReactiveField/Relation/Collection to be invalidated when its dependencies change. */
+	add(target) {
+		const meta = require_EntityMetadata.getMetadata(target.entity);
+		const set = (this.#smartCache[meta.tagName] ??= {})[target.fieldName] ??= /* @__PURE__ */ new Set();
+		if (set.size === 0) this.#smartDirtySets++;
+		set.add(target);
+	}
+	addNaive(target) {
+		if (this.#naiveCache.size === 0) this.#naiveDirtySets++;
+		this.#naiveCache.add(target);
+	}
+	/** Resets any in-memory #isLoaded/#isCached caches that depend on `entity.fieldName`. */
+	resetIsLoaded(entity, fieldName) {
+		if (this.#smartDirtySets === 0 && this.#naiveDirtySets === 0) return;
+		if (this.#smartDirtySets > 0) this.#resetDownstreamReactables(require_EntityMetadata.getMetadata(entity), fieldName);
+		if (this.#naiveCache.size > 0) {
+			for (const target of this.#naiveCache.values()) target.resetIsLoaded();
+			this.#naiveCache.clear();
+			this.#naiveDirtySets--;
+		}
+	}
+	/**
+	* Given a `meta+field`, statically find all downstream Reactables, and if any of those
+	* Reactables are a) in-memory already, and b) registered themselves as cached,
+	* tell them to reset.
+	*/
+	#resetDownstreamReactables(meta, fieldName) {
+		const reactables = meta.reactablesIncludingReadOnlyByField.get(fieldName);
+		if (reactables === void 0) return;
+		for (const r of reactables) {
+			if (this.#smartDirtySets === 0) return;
+			const otherMeta = require_EntityMetadata.getMetadata(r.cstr);
+			const set = this.#smartCache[otherMeta.tagName]?.[r.name];
+			if (set?.size > 0) {
+				for (const target of set) {
+					target.resetIsLoaded();
+					const otherMeta = require_EntityMetadata.getMetadata(target.entity);
+					const otherField = otherMeta.allFields[target.fieldName];
+					if ("derived" in otherField && otherField.derived) this.#resetDownstreamReactables(otherMeta, otherField.fieldName);
+				}
+				set.clear();
+				this.#smartDirtySets--;
+			}
+		}
+	}
+};
+//#endregion
+exports.IsLoadedCache = IsLoadedCache;
+
+//# sourceMappingURL=IsLoadedCache.cjs.map

package/build/loading/IsLoadedCache.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"IsLoadedCache.cjs","names":["getMetadata","#smartCache","#smartDirtySets","#naiveCache","#naiveDirtySets","#resetDownstreamReactables"],"sources":["../../src/loading/IsLoadedCache.ts"],"sourcesContent":["import type { Entity } from \"src/Entity.ts\";\nimport { type EntityMetadata, getMetadata } from \"src/EntityMetadata.ts\";\n\n/**\n * Interface for our relations that have dynamic & expensive `isLoaded` checks.\n *\n * ...and also `OneToManyCollection.get` calls.\n *\n * The primary m2o/o2m/m2m relations all have trivial `isLoaded` checks--are they\n * loaded or not.\n *\n * But for \"composite relations\", i.e. a ReactiveField or ReactiveRelation whose\n * \"load-ness\" is calculated by evaluating its load hint across a subgraph of entities\n * & relations, load-ness can be more dynamic true-then-false, as its subgraph changes.\n *\n * To avoid performance issues (see https://github.com/joist-orm/joist-orm/issues/1166),\n * we cache this dynamic/expensive `isLoaded` checks, and then do targeted, reactivity-driven\n * cache invalidation whenever relations are mutated (via a hook in `setField`).\n */\nexport interface IsLoadedCachable {\n  entity: Entity;\n  fieldName: string;\n  isLoaded: boolean;\n  resetIsLoaded(): void;\n}\n\nexport class IsLoadedCache {\n  // Cache of `{ tag -> { fieldName -> Set<IsLoadedCachable> } }` to hold derived relations\n  // we can selectively invalidate by walking from the mutated field to any downstream\n  // cacheables.\n  #smartCache: Record<string, Record<string, Set<IsLoadedCachable>>> = {};\n  // A dumb cache for things that are hard selectively invalidate (o2m.get, recursive collections,\n  // and custom references/collections), so any mutation resets these.\n  #naiveCache = new Set<IsLoadedCachable>();\n  // Counter to skip reactive hint walking when no smart cache sets are populated.\n  #smartDirtySets = 0;\n  // Counter to fast-path resetIsLoaded when the naive cache is empty.\n  #naiveDirtySets = 0;\n\n  /** Adds a ReactiveField/Relation/Collection to be invalidated when its dependencies change. */\n  add(target: IsLoadedCachable): void {\n    const meta = getMetadata(target.entity);\n    const set = ((this.#smartCache[meta.tagName] ??= {})[target.fieldName] ??= new Set());\n    if (set.size === 0) {\n      this.#smartDirtySets++;\n    }\n    set.add(target);\n  }\n\n  addNaive(target: IsLoadedCachable): void {\n    if (this.#naiveCache.size === 0) this.#naiveDirtySets++;\n    this.#naiveCache.add(target);\n  }\n\n  /** Resets any in-memory #isLoaded/#isCached caches that depend on `entity.fieldName`. */\n  resetIsLoaded(entity: Entity, fieldName: string): void {\n    if (this.#smartDirtySets === 0 && this.#naiveDirtySets === 0) return;\n    // Reset caches that we can deterministically find by walking the reactivity hints\n    if (this.#smartDirtySets > 0) {\n      this.#resetDownstreamReactables(getMetadata(entity), fieldName);\n    }\n    // We could use this to invalidate m2o.get, but it doesn't work for collections\n    // with an orderBy, when the orderBy changes, so for now we use the blunt naiveCache.\n    // const field = meta.allFields[fieldName];\n    // if (field.kind === \"m2o\") {\n    //   const otherMeta = field.otherMetadata();\n    //   const set = this.smartCache[otherMeta.tagName]?.[field.otherFieldName];\n    //   if (set) {\n    //     for (const target of set) target.resetIsLoaded();\n    //     set.clear();\n    //   }\n    // }\n    if (this.#naiveCache.size > 0) {\n      for (const target of this.#naiveCache.values()) target.resetIsLoaded();\n      this.#naiveCache.clear();\n      this.#naiveDirtySets--;\n    }\n  }\n\n  /**\n   * Given a `meta+field`, statically find all downstream Reactables, and if any of those\n   * Reactables are a) in-memory already, and b) registered themselves as cached,\n   * tell them to reset.\n   */\n  #resetDownstreamReactables(meta: EntityMetadata, fieldName: string): void {\n    // These are reactables in other entities that are watching/reacting to this entity/fieldName\n    const reactables = meta.reactablesIncludingReadOnlyByField!.get(fieldName);\n    if (reactables === undefined) return;\n    for (const r of reactables) {\n      if (this.#smartDirtySets === 0) return;\n      // I.e. we've written to Author.firstName, and this reactable in Book/otherMeta depends on it\n      const otherMeta = getMetadata(r.cstr);\n      // Find any cache entries for this cstr + name\n      const set = this.#smartCache[otherMeta.tagName]?.[r.name];\n      if (set?.size > 0) {\n        for (const target of set) {\n          target.resetIsLoaded();\n          // Is this target itself a RF/RR? If so, transitively reset its cache as well.\n          const otherMeta = getMetadata(target.entity);\n          const otherField = otherMeta.allFields[target.fieldName];\n          if (\"derived\" in otherField && otherField.derived) {\n            this.#resetDownstreamReactables(otherMeta, otherField.fieldName);\n          }\n        }\n        set.clear();\n        this.#smartDirtySets--;\n      }\n    }\n  }\n}\n"],"mappings":";;;AA0BA,IAAa,gBAAb,MAA2B;CAIzB,cAAqE,CAAC;CAGtE,8BAAc,IAAI,IAAsB;CAExC,kBAAkB;CAElB,kBAAkB;;CAGlB,IAAI,QAAgC;EAClC,MAAM,OAAOA,uBAAAA,YAAY,OAAO,MAAM;EACtC,MAAM,MAAO,CAAC,KAAKC,YAAY,KAAK,aAAa,CAAC,EAAA,CAAG,OAAO,+BAAe,IAAI,IAAI;EACnF,IAAI,IAAI,SAAS,GACf,KAAKC;EAEP,IAAI,IAAI,MAAM;CAChB;CAEA,SAAS,QAAgC;EACvC,IAAI,KAAKC,YAAY,SAAS,GAAG,KAAKC;EACtC,KAAKD,YAAY,IAAI,MAAM;CAC7B;;CAGA,cAAc,QAAgB,WAAyB;EACrD,IAAI,KAAKD,oBAAoB,KAAK,KAAKE,oBAAoB,GAAG;EAE9D,IAAI,KAAKF,kBAAkB,GACzB,KAAKG,2BAA2BL,uBAAAA,YAAY,MAAM,GAAG,SAAS;EAahE,IAAI,KAAKG,YAAY,OAAO,GAAG;GAC7B,KAAK,MAAM,UAAU,KAAKA,YAAY,OAAO,GAAG,OAAO,cAAc;GACrE,KAAKA,YAAY,MAAM;GACvB,KAAKC;EACP;CACF;;;;;;CAOA,2BAA2B,MAAsB,WAAyB;EAExE,MAAM,aAAa,KAAK,mCAAoC,IAAI,SAAS;EACzE,IAAI,eAAe,KAAA,GAAW;EAC9B,KAAK,MAAM,KAAK,YAAY;GAC1B,IAAI,KAAKF,oBAAoB,GAAG;GAEhC,MAAM,YAAYF,uBAAAA,YAAY,EAAE,IAAI;GAEpC,MAAM,MAAM,KAAKC,YAAY,UAAU,QAAQ,GAAG,EAAE;GACpD,IAAI,KAAK,OAAO,GAAG;IACjB,KAAK,MAAM,UAAU,KAAK;KACxB,OAAO,cAAc;KAErB,MAAM,YAAYD,uBAAAA,YAAY,OAAO,MAAM;KAC3C,MAAM,aAAa,UAAU,UAAU,OAAO;KAC9C,IAAI,aAAa,cAAc,WAAW,SACxC,KAAKK,2BAA2B,WAAW,WAAW,SAAS;IAEnE;IACA,IAAI,MAAM;IACV,KAAKH;GACP;EACF;CACF;AACF"}

package/build/loading/IsLoadedCache.d.cts

@@ -0,0 +1,35 @@
+import { Entity } from "../Entity.cjs";
+//#region src/loading/IsLoadedCache.d.ts
+/**
+ * Interface for our relations that have dynamic & expensive `isLoaded` checks.
+ *
+ * ...and also `OneToManyCollection.get` calls.
+ *
+ * The primary m2o/o2m/m2m relations all have trivial `isLoaded` checks--are they
+ * loaded or not.
+ *
+ * But for "composite relations", i.e. a ReactiveField or ReactiveRelation whose
+ * "load-ness" is calculated by evaluating its load hint across a subgraph of entities
+ * & relations, load-ness can be more dynamic true-then-false, as its subgraph changes.
+ *
+ * To avoid performance issues (see https://github.com/joist-orm/joist-orm/issues/1166),
+ * we cache this dynamic/expensive `isLoaded` checks, and then do targeted, reactivity-driven
+ * cache invalidation whenever relations are mutated (via a hook in `setField`).
+ */
+interface IsLoadedCachable {
+  entity: Entity;
+  fieldName: string;
+  isLoaded: boolean;
+  resetIsLoaded(): void;
+}
+declare class IsLoadedCache {
+  #private;
+  /** Adds a ReactiveField/Relation/Collection to be invalidated when its dependencies change. */
+  add(target: IsLoadedCachable): void;
+  addNaive(target: IsLoadedCachable): void;
+  /** Resets any in-memory #isLoaded/#isCached caches that depend on `entity.fieldName`. */
+  resetIsLoaded(entity: Entity, fieldName: string): void;
+}
+//#endregion
+export { IsLoadedCachable, IsLoadedCache };
+//# sourceMappingURL=IsLoadedCache.d.cts.map

package/build/loading/IsLoadedCache.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IsLoadedCache.d.cts","names":[],"sources":["../../src/loading/IsLoadedCache.ts"],"mappings":";;;;;;;;;;;;;;;;;;UAmBiB;EACf,QAAQ;EACR;EACA;EACA;;cAGW;;;EAcX,IAAI,QAAQ;EASZ,SAAS,QAAQ;;EAMjB,cAAc,QAAQ,QAAQ"}

package/build/loading/IsLoadedCache.d.mts

@@ -0,0 +1,35 @@
+import { Entity } from "../Entity.mjs";
+//#region src/loading/IsLoadedCache.d.ts
+/**
+ * Interface for our relations that have dynamic & expensive `isLoaded` checks.
+ *
+ * ...and also `OneToManyCollection.get` calls.
+ *
+ * The primary m2o/o2m/m2m relations all have trivial `isLoaded` checks--are they
+ * loaded or not.
+ *
+ * But for "composite relations", i.e. a ReactiveField or ReactiveRelation whose
+ * "load-ness" is calculated by evaluating its load hint across a subgraph of entities
+ * & relations, load-ness can be more dynamic true-then-false, as its subgraph changes.
+ *
+ * To avoid performance issues (see https://github.com/joist-orm/joist-orm/issues/1166),
+ * we cache this dynamic/expensive `isLoaded` checks, and then do targeted, reactivity-driven
+ * cache invalidation whenever relations are mutated (via a hook in `setField`).
+ */
+interface IsLoadedCachable {
+  entity: Entity;
+  fieldName: string;
+  isLoaded: boolean;
+  resetIsLoaded(): void;
+}
+declare class IsLoadedCache {
+  #private;
+  /** Adds a ReactiveField/Relation/Collection to be invalidated when its dependencies change. */
+  add(target: IsLoadedCachable): void;
+  addNaive(target: IsLoadedCachable): void;
+  /** Resets any in-memory #isLoaded/#isCached caches that depend on `entity.fieldName`. */
+  resetIsLoaded(entity: Entity, fieldName: string): void;
+}
+//#endregion
+export { IsLoadedCachable, IsLoadedCache };
+//# sourceMappingURL=IsLoadedCache.d.mts.map

package/build/loading/IsLoadedCache.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IsLoadedCache.d.mts","names":[],"sources":["../../src/loading/IsLoadedCache.ts"],"mappings":";;;;;;;;;;;;;;;;;;UAmBiB;EACf,QAAQ;EACR;EACA;EACA;;cAGW;;;EAcX,IAAI,QAAQ;EASZ,SAAS,QAAQ;;EAMjB,cAAc,QAAQ,QAAQ"}

package/build/loading/IsLoadedCache.js

@@ -0,0 +1,57 @@
+import { getMetadata } from "../EntityMetadata.js";
+//#region src/loading/IsLoadedCache.ts
+var IsLoadedCache = class {
+	#smartCache = {};
+	#naiveCache = /* @__PURE__ */ new Set();
+	#smartDirtySets = 0;
+	#naiveDirtySets = 0;
+	/** Adds a ReactiveField/Relation/Collection to be invalidated when its dependencies change. */
+	add(target) {
+		const meta = getMetadata(target.entity);
+		const set = (this.#smartCache[meta.tagName] ??= {})[target.fieldName] ??= /* @__PURE__ */ new Set();
+		if (set.size === 0) this.#smartDirtySets++;
+		set.add(target);
+	}
+	addNaive(target) {
+		if (this.#naiveCache.size === 0) this.#naiveDirtySets++;
+		this.#naiveCache.add(target);
+	}
+	/** Resets any in-memory #isLoaded/#isCached caches that depend on `entity.fieldName`. */
+	resetIsLoaded(entity, fieldName) {
+		if (this.#smartDirtySets === 0 && this.#naiveDirtySets === 0) return;
+		if (this.#smartDirtySets > 0) this.#resetDownstreamReactables(getMetadata(entity), fieldName);
+		if (this.#naiveCache.size > 0) {
+			for (const target of this.#naiveCache.values()) target.resetIsLoaded();
+			this.#naiveCache.clear();
+			this.#naiveDirtySets--;
+		}
+	}
+	/**
+	* Given a `meta+field`, statically find all downstream Reactables, and if any of those
+	* Reactables are a) in-memory already, and b) registered themselves as cached,
+	* tell them to reset.
+	*/
+	#resetDownstreamReactables(meta, fieldName) {
+		const reactables = meta.reactablesIncludingReadOnlyByField.get(fieldName);
+		if (reactables === void 0) return;
+		for (const r of reactables) {
+			if (this.#smartDirtySets === 0) return;
+			const otherMeta = getMetadata(r.cstr);
+			const set = this.#smartCache[otherMeta.tagName]?.[r.name];
+			if (set?.size > 0) {
+				for (const target of set) {
+					target.resetIsLoaded();
+					const otherMeta = getMetadata(target.entity);
+					const otherField = otherMeta.allFields[target.fieldName];
+					if ("derived" in otherField && otherField.derived) this.#resetDownstreamReactables(otherMeta, otherField.fieldName);
+				}
+				set.clear();
+				this.#smartDirtySets--;
+			}
+		}
+	}
+};
+//#endregion
+export { IsLoadedCache };
+
+//# sourceMappingURL=IsLoadedCache.js.map

package/build/loading/IsLoadedCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IsLoadedCache.js","names":["#smartCache","#smartDirtySets","#naiveCache","#naiveDirtySets","#resetDownstreamReactables"],"sources":["../../src/loading/IsLoadedCache.ts"],"sourcesContent":["import type { Entity } from \"src/Entity.ts\";\nimport { type EntityMetadata, getMetadata } from \"src/EntityMetadata.ts\";\n\n/**\n * Interface for our relations that have dynamic & expensive `isLoaded` checks.\n *\n * ...and also `OneToManyCollection.get` calls.\n *\n * The primary m2o/o2m/m2m relations all have trivial `isLoaded` checks--are they\n * loaded or not.\n *\n * But for \"composite relations\", i.e. a ReactiveField or ReactiveRelation whose\n * \"load-ness\" is calculated by evaluating its load hint across a subgraph of entities\n * & relations, load-ness can be more dynamic true-then-false, as its subgraph changes.\n *\n * To avoid performance issues (see https://github.com/joist-orm/joist-orm/issues/1166),\n * we cache this dynamic/expensive `isLoaded` checks, and then do targeted, reactivity-driven\n * cache invalidation whenever relations are mutated (via a hook in `setField`).\n */\nexport interface IsLoadedCachable {\n  entity: Entity;\n  fieldName: string;\n  isLoaded: boolean;\n  resetIsLoaded(): void;\n}\n\nexport class IsLoadedCache {\n  // Cache of `{ tag -> { fieldName -> Set<IsLoadedCachable> } }` to hold derived relations\n  // we can selectively invalidate by walking from the mutated field to any downstream\n  // cacheables.\n  #smartCache: Record<string, Record<string, Set<IsLoadedCachable>>> = {};\n  // A dumb cache for things that are hard selectively invalidate (o2m.get, recursive collections,\n  // and custom references/collections), so any mutation resets these.\n  #naiveCache = new Set<IsLoadedCachable>();\n  // Counter to skip reactive hint walking when no smart cache sets are populated.\n  #smartDirtySets = 0;\n  // Counter to fast-path resetIsLoaded when the naive cache is empty.\n  #naiveDirtySets = 0;\n\n  /** Adds a ReactiveField/Relation/Collection to be invalidated when its dependencies change. */\n  add(target: IsLoadedCachable): void {\n    const meta = getMetadata(target.entity);\n    const set = ((this.#smartCache[meta.tagName] ??= {})[target.fieldName] ??= new Set());\n    if (set.size === 0) {\n      this.#smartDirtySets++;\n    }\n    set.add(target);\n  }\n\n  addNaive(target: IsLoadedCachable): void {\n    if (this.#naiveCache.size === 0) this.#naiveDirtySets++;\n    this.#naiveCache.add(target);\n  }\n\n  /** Resets any in-memory #isLoaded/#isCached caches that depend on `entity.fieldName`. */\n  resetIsLoaded(entity: Entity, fieldName: string): void {\n    if (this.#smartDirtySets === 0 && this.#naiveDirtySets === 0) return;\n    // Reset caches that we can deterministically find by walking the reactivity hints\n    if (this.#smartDirtySets > 0) {\n      this.#resetDownstreamReactables(getMetadata(entity), fieldName);\n    }\n    // We could use this to invalidate m2o.get, but it doesn't work for collections\n    // with an orderBy, when the orderBy changes, so for now we use the blunt naiveCache.\n    // const field = meta.allFields[fieldName];\n    // if (field.kind === \"m2o\") {\n    //   const otherMeta = field.otherMetadata();\n    //   const set = this.smartCache[otherMeta.tagName]?.[field.otherFieldName];\n    //   if (set) {\n    //     for (const target of set) target.resetIsLoaded();\n    //     set.clear();\n    //   }\n    // }\n    if (this.#naiveCache.size > 0) {\n      for (const target of this.#naiveCache.values()) target.resetIsLoaded();\n      this.#naiveCache.clear();\n      this.#naiveDirtySets--;\n    }\n  }\n\n  /**\n   * Given a `meta+field`, statically find all downstream Reactables, and if any of those\n   * Reactables are a) in-memory already, and b) registered themselves as cached,\n   * tell them to reset.\n   */\n  #resetDownstreamReactables(meta: EntityMetadata, fieldName: string): void {\n    // These are reactables in other entities that are watching/reacting to this entity/fieldName\n    const reactables = meta.reactablesIncludingReadOnlyByField!.get(fieldName);\n    if (reactables === undefined) return;\n    for (const r of reactables) {\n      if (this.#smartDirtySets === 0) return;\n      // I.e. we've written to Author.firstName, and this reactable in Book/otherMeta depends on it\n      const otherMeta = getMetadata(r.cstr);\n      // Find any cache entries for this cstr + name\n      const set = this.#smartCache[otherMeta.tagName]?.[r.name];\n      if (set?.size > 0) {\n        for (const target of set) {\n          target.resetIsLoaded();\n          // Is this target itself a RF/RR? If so, transitively reset its cache as well.\n          const otherMeta = getMetadata(target.entity);\n          const otherField = otherMeta.allFields[target.fieldName];\n          if (\"derived\" in otherField && otherField.derived) {\n            this.#resetDownstreamReactables(otherMeta, otherField.fieldName);\n          }\n        }\n        set.clear();\n        this.#smartDirtySets--;\n      }\n    }\n  }\n}\n"],"mappings":";;AA0BA,IAAa,gBAAb,MAA2B;CAIzB,cAAqE,CAAC;CAGtE,8BAAc,IAAI,IAAsB;CAExC,kBAAkB;CAElB,kBAAkB;;CAGlB,IAAI,QAAgC;EAClC,MAAM,OAAO,YAAY,OAAO,MAAM;EACtC,MAAM,MAAO,CAAC,KAAKA,YAAY,KAAK,aAAa,CAAC,EAAA,CAAG,OAAO,+BAAe,IAAI,IAAI;EACnF,IAAI,IAAI,SAAS,GACf,KAAKC;EAEP,IAAI,IAAI,MAAM;CAChB;CAEA,SAAS,QAAgC;EACvC,IAAI,KAAKC,YAAY,SAAS,GAAG,KAAKC;EACtC,KAAKD,YAAY,IAAI,MAAM;CAC7B;;CAGA,cAAc,QAAgB,WAAyB;EACrD,IAAI,KAAKD,oBAAoB,KAAK,KAAKE,oBAAoB,GAAG;EAE9D,IAAI,KAAKF,kBAAkB,GACzB,KAAKG,2BAA2B,YAAY,MAAM,GAAG,SAAS;EAahE,IAAI,KAAKF,YAAY,OAAO,GAAG;GAC7B,KAAK,MAAM,UAAU,KAAKA,YAAY,OAAO,GAAG,OAAO,cAAc;GACrE,KAAKA,YAAY,MAAM;GACvB,KAAKC;EACP;CACF;;;;;;CAOA,2BAA2B,MAAsB,WAAyB;EAExE,MAAM,aAAa,KAAK,mCAAoC,IAAI,SAAS;EACzE,IAAI,eAAe,KAAA,GAAW;EAC9B,KAAK,MAAM,KAAK,YAAY;GAC1B,IAAI,KAAKF,oBAAoB,GAAG;GAEhC,MAAM,YAAY,YAAY,EAAE,IAAI;GAEpC,MAAM,MAAM,KAAKD,YAAY,UAAU,QAAQ,GAAG,EAAE;GACpD,IAAI,KAAK,OAAO,GAAG;IACjB,KAAK,MAAM,UAAU,KAAK;KACxB,OAAO,cAAc;KAErB,MAAM,YAAY,YAAY,OAAO,MAAM;KAC3C,MAAM,aAAa,UAAU,UAAU,OAAO;KAC9C,IAAI,aAAa,cAAc,WAAW,SACxC,KAAKI,2BAA2B,WAAW,WAAW,SAAS;IAEnE;IACA,IAAI,MAAM;IACV,KAAKH;GACP;EACF;CACF;AACF"}

package/build/loading/loadHints.cjs

@@ -0,0 +1,95 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_reactivity_reactiveHints = require("../reactivity/reactiveHints.cjs");
+const require_utils = require("../utils.cjs");
+//#region src/loading/loadHints.ts
+/** Detects whether an entity is newly created, and so we can treat all the relations as loaded. */
+function isNew(e) {
+	return e.isNewEntity;
+}
+/** Recursively checks if the relations from a load hint are loaded on an entity. */
+function isLoaded(entity, hint) {
+	if (typeof hint === "string") return entity[hint].isLoaded;
+	else if (Array.isArray(hint)) {
+		for (const key of hint) if (!entity[key].isLoaded) return false;
+		return true;
+	} else if (typeof hint === "object") {
+		for (const entry of Object.entries(hint)) {
+			const [key, nestedHint] = entry;
+			const relation = require_reactivity_reactiveHints.getRelationFromMaybePolyKey(entity, key);
+			if (!relation || typeof relation.load !== "function") continue;
+			if (relation.isLoaded) {
+				const result = relation.get;
+				if (Array.isArray(result)) {
+					for (const entity of result) if (!isLoaded(entity, nestedHint)) return false;
+				} else if (result && !isLoaded(result, nestedHint)) return false;
+			} else return false;
+		}
+		return true;
+	} else throw new Error(`Unexpected hint ${hint}`);
+}
+/**
+* Recursively checks if a relation-only populate hint is loaded on an entity.
+*
+* Unlike `isLoaded`, this returns `false` for non-loadable/primitive leaves instead of ignoring them, because
+* `ReactiveField.load` calls `em.populate` with load hints converted from reactive hints, i.e. `{ firstName: {} }`.
+* Treating those primitive leaves as loaded would let `EntityManager.populate` skip the batchloader path and change
+* reactive recalculation ordering, so the populate fast-path only applies to true relation populate hints.
+*/
+function isLoadedForPopulate(entity, hint) {
+	if (typeof hint === "string") {
+		const relation = require_reactivity_reactiveHints.getRelationFromMaybePolyKey(entity, hint);
+		return !!relation && typeof relation.load === "function" && relation.isLoaded;
+	} else if (Array.isArray(hint)) {
+		for (const key of hint) if (!isLoadedForPopulate(entity, key)) return false;
+		return true;
+	} else if (typeof hint === "object") {
+		for (const entry of Object.entries(hint)) {
+			const [key, nestedHint] = entry;
+			const relation = require_reactivity_reactiveHints.getRelationFromMaybePolyKey(entity, key);
+			if (!relation || typeof relation.load !== "function" || !relation.isLoaded) return false;
+			const result = relation.get;
+			if (Array.isArray(result)) {
+				for (const entity of result) if (!isLoadedForPopulate(entity, nestedHint)) return false;
+			} else if (result && !isLoadedForPopulate(result, nestedHint)) return false;
+		}
+		return true;
+	} else throw new Error(`Unexpected hint ${hint}`);
+}
+function maybePopulateThen(entity, hint, fn) {
+	return isLoaded(entity, hint) ? fn(entity) : entity.populate(hint).then(fn);
+}
+/**
+* Runtime checks that `entity` has `hint` loaded, and type guards it as a `Loaded<T, hint>`.
+*
+* Similar to `ensureLoaded`, although `ensureLoaded` returns its value.
+*/
+function assertLoaded(entity, hint) {
+	if (!isLoaded(entity, hint)) require_utils.fail(`${entity.id} is not loaded for ${JSON.stringify(hint)}`);
+}
+/**
+* Runtime checks that `entity` has `hint` loaded, and returns it as a `Loaded<T, entity>`.
+*
+* Similar to `assertLoaded`, although `assertLoaded` is a boolean type guard.
+*/
+function ensureLoaded(entity, hint) {
+	assertLoaded(entity, hint);
+	return entity;
+}
+/**
+* Unsafe type check for `entity` to `hint`, *without* a runtime type check.
+*
+* You should only use this if you're extremely sure that entity has hint loaded.
+*/
+function unsafeLoaded(entity, hint) {
+	return entity;
+}
+//#endregion
+exports.assertLoaded = assertLoaded;
+exports.ensureLoaded = ensureLoaded;
+exports.isLoaded = isLoaded;
+exports.isLoadedForPopulate = isLoadedForPopulate;
+exports.isNew = isNew;
+exports.maybePopulateThen = maybePopulateThen;
+exports.unsafeLoaded = unsafeLoaded;
+
+//# sourceMappingURL=loadHints.cjs.map

package/build/loading/loadHints.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"loadHints.cjs","names":["getRelationFromMaybePolyKey"],"sources":["../../src/loading/loadHints.ts"],"sourcesContent":["import type { Entity } from \"src/Entity.ts\";\nimport type { NormalizeHint } from \"src/normalizeHints.ts\";\nimport { getRelationFromMaybePolyKey } from \"src/reactivity/reactiveHints.ts\";\nimport type {\n  AsyncMethod,\n  Collection,\n  EnumCollection,\n  LoadedCollection,\n  LoadedEnumCollection,\n  LoadedMethod,\n  LoadedProperty,\n  LoadedReadOnlyCollection,\n  LoadedReference,\n  OneToOneReference,\n  Property,\n  ReadOnlyCollection,\n  Reference,\n  Relation,\n} from \"src/relations/index.ts\";\nimport type { LoadedOneToOneReference } from \"src/relations/OneToOneReference.ts\";\nimport type { OptsOf } from \"src/typeMap.ts\";\nimport { type MaybePromise, type NullOrDefinedOr, fail } from \"src/utils.ts\";\n\nconst deepLoad = Symbol();\ntype DeepLoadHint<T extends Entity> = NestedLoadHint<T> & { [deepLoad]: true };\n\n// Use any to correctly handle subtype/base type load hints.\n//\n// If a load hint is typed as `LoadHint<SmallPublisher, \"authors\">`, but the property\n// is actually `Publisher.authors`, if we do `P extends LoadedCollection<SmallPublisher, ...>`\n// the `SmallPublisher !== Publisher`, so the `authors` property doesn't match, and then\n// we drop the rest of the nested load hint.\n//\n// But if we check `P extends LoadedCollection<any, ...>` it works.\ntype MaybeBaseType = any;\n\n/** Marks a given `T[K]` field as the loaded/synchronous version of the collection. */\nexport type MarkLoaded<T extends Entity, P, UH = {}> =\n  P extends EnumCollection<MaybeBaseType, infer E>\n    ? LoadedEnumCollection<T, E>\n    : P extends OneToOneReference<MaybeBaseType, infer U>\n      ? LoadedOneToOneReference<T, Loaded<U, UH>>\n      : P extends Reference<MaybeBaseType, infer U, infer N>\n        ? LoadedReference<T, Loaded<U, UH>, N>\n        : P extends Collection<MaybeBaseType, infer U>\n          ? LoadedCollection<T, Loaded<U, UH>>\n          : P extends ReadOnlyCollection<MaybeBaseType, infer U>\n            ? LoadedReadOnlyCollection<T, Loaded<U, UH>>\n            : P extends Property<MaybeBaseType, infer V>\n              ? // prettier-ignore\n                [V] extends [(infer U extends Entity) | undefined]\n    ? LoadedProperty<T, Loaded<U, UH> | Exclude<V, U>>\n    : V extends readonly (infer U extends Entity)[]\n    ? LoadedProperty<T, Loaded<U, UH>[]>\n    : LoadedProperty<T, V>\n              : P extends AsyncMethod<T, infer A, infer V>\n                ? LoadedMethod<T, A, V>\n                : unknown;\n\n/** A version of MarkLoaded the uses `DeepLoadHint` for tests. */\ntype MarkDeepLoaded<T extends Entity, P> =\n  P extends EnumCollection<MaybeBaseType, infer E>\n    ? LoadedEnumCollection<T, E>\n    : P extends OneToOneReference<MaybeBaseType, infer U>\n      ? LoadedOneToOneReference<T, Loaded<U, DeepLoadHint<U>>>\n      : P extends Reference<MaybeBaseType, infer U, infer N>\n        ? LoadedReference<T, Loaded<U, DeepLoadHint<U>>, N>\n        : P extends Collection<MaybeBaseType, infer U>\n          ? LoadedCollection<T, Loaded<U, DeepLoadHint<U>>>\n          : P extends ReadOnlyCollection<MaybeBaseType, infer U>\n            ? LoadedReadOnlyCollection<T, Loaded<U, DeepLoadHint<U>>>\n            : P extends Property<MaybeBaseType, infer V>\n              ? // prettier-ignore\n                [V] extends [(infer U extends Entity) | undefined]\n    ? LoadedProperty<T, Loaded<U, DeepLoadHint<U>> | Exclude<V, U>>\n    : V extends readonly (infer U extends Entity)[]\n    ? LoadedProperty<T, Loaded<U, DeepLoadHint<U>>[]>\n    : LoadedProperty<T, V>\n              : P extends AsyncMethod<T, infer A, infer V>\n                ? LoadedMethod<T, A, V>\n                : unknown;\n\n/**\n * A helper type for `New` that marks every `Reference` and `LoadedCollection` in `T` as loaded.\n *\n * We also look in opts `O` for the \"`U`\" type, i.e. the next level up/down in the graph,\n * because the call site's opts may be using an also-marked loaded parent/child as an opt,\n * so this will infer the type of that parent/child and use that for the `U` type.\n *\n * This means things like `entity.parent.get.grandParent.get` will work on the resulting\n * type.\n *\n * Note that this is also purposefully broken out of `New` because of some weirdness\n * around type narrowing that wasn't working when inlined into `New`.\n */\ntype MaybeUseOptsType<T extends Entity, O, K extends keyof T & keyof O> =\n  O[K] extends NullOrDefinedOr<infer OK>\n    ? OK extends Entity\n      ? T[K] extends OneToOneReference<T, infer U>\n        ? LoadedOneToOneReference<T, U>\n        : T[K] extends Reference<T, infer U, infer N>\n          ? LoadedReference<T, OK, N>\n          : never\n      : OK extends Array<infer OU>\n        ? OU extends Entity\n          ? T[K] extends Collection<T, infer U>\n            ? LoadedCollection<T, OU>\n            : never\n          : T[K]\n        : T[K]\n    : never;\n\n/**\n * Marks all references/collections of `T` as loaded, i.e. for newly instantiated entities where\n * we know there are no already-existing rows with fk's to this new entity in the database.\n *\n * `O` is the generic from the call site so that if the caller passes `{ author: SomeLoadedAuthor }`,\n * we'll prefer that type, as it might have more nested load hints that we can't otherwise assume.\n */\nexport type New<T extends Entity, O extends OptsOf<T> = OptsOf<T>> = T & {\n  // K will be `keyof T` and `keyof O` for codegen'd relations, but custom relations\n  // line `hasOneThrough` and `hasOneDerived` will not pass `keyof O` and so use the\n  // `: MarkLoaded`.\n  //\n  // Note that the safest thing is to probably make this `: unknown` instead so that\n  // custom relations are not marked loaded, b/c they will very likely require a `.load`\n  // to work. However, we have some tests that currently expect `author.image.get` to work\n  // on a new author, so keeping the `MarkLoaded` behavior for now.\n  [K in keyof T]: K extends keyof O ? MaybeUseOptsType<T, O, K> : MarkLoaded<T, T[K]>;\n};\n\n/**\n * Marks all references/collections of `T` as deeply loaded, which is only useful for\n * tests where we can have \"the whole object graph\" in-memory.\n */\nexport type DeepNew<T extends Entity> = Loaded<T, DeepLoadHint<T>>;\n\n/** Detects whether an entity is newly created, and so we can treat all the relations as loaded. */\nexport function isNew<T extends Entity>(e: T): e is New<T> {\n  return e.isNewEntity;\n}\n\n/**\n * All the loadable fields, i.e. relations or lazy-loaded/async properties, in an entity.\n *\n * We use a mapped type (instead of a code-generated type) so that we can pick up custom\n * fields that have be added to the entity classes, i.e. `Author.numberOfBooks2` async\n * properties.\n */\nexport type Loadable<T extends Entity> = {\n  -readonly [K in keyof T as LoadableValue<T[K]> extends never ? never : K]: LoadableValue<T[K]>;\n};\n\n/**\n * Given an entity field/value, return the loadable entity.\n *\n * I.e. `Author.books` as a Reference or Collection, return `Book`.\n *\n * Note that we usually return entities, but for AsyncProperties it could be\n * a calculated primitive value like number or string.\n */\nexport type LoadableValue<V> =\n  V extends EnumCollection<any, infer E>\n    ? E\n    : V extends Reference<any, infer U, any>\n      ? U\n      : V extends Collection<any, infer U>\n        ? U\n        : V extends ReadOnlyCollection<any, infer U>\n          ? U\n          : V extends AsyncMethod<any, any, infer V>\n            ? V\n            : V extends Property<any, infer P>\n              ? // If the Property returns `Comment | undefined`, then we want to return `Comment`\n                // prettier-ignore\n                P extends (infer U extends Entity) | undefined ? U : P\n              : never;\n\n/**\n *  A load hint of a single key, multiple keys, or nested keys and sub-hints.\n *\n * Load hints are different from reactive hints in that load hints include only references,\n * collections, and async properties to preload (like `Book.author` or `Author.books`), and\n * do not include any primitive fields (like `Author.firstName`).\n */\nexport type LoadHint<T extends Entity> =\n  | (keyof Loadable<T> & string)\n  | ReadonlyArray<keyof Loadable<T> & string>\n  | NestedLoadHint<T>;\n\nexport type NestedLoadHint<T extends Entity> = {\n  // Don't filter out entity-loadable keys, because we need to support `{ numberOfBooks2: {} }`\n  [K in keyof Loadable<T>]?: Loadable<T>[K] extends infer U extends Entity ? LoadHint<U> : {};\n};\n\n/** Given an entity `T` that is being populated with hints `H`, marks the `H` attributes as populated. */\nexport type Loaded<T extends Entity, H> = T & {\n  [K in keyof T & keyof NormalizeHint<H>]: H extends DeepLoadHint<T>\n    ? MarkDeepLoaded<T, T[K]>\n    : MarkLoaded<T, T[K], NormalizeHint<H>[K]>;\n};\n\n/** Recursively checks if the relations from a load hint are loaded on an entity. */\nexport function isLoaded<T extends Entity, H extends LoadHint<T>>(entity: T, hint: H): entity is Loaded<T, H> {\n  if (typeof hint === \"string\") {\n    return (entity as any)[hint].isLoaded;\n  } else if (Array.isArray(hint)) {\n    for (const key of hint as string[]) {\n      if (!(entity as any)[key].isLoaded) return false;\n    }\n    return true;\n  } else if (typeof hint === \"object\") {\n    for (const entry of Object.entries(hint as object)) {\n      const [key, nestedHint] = entry;\n      const relation = getRelationFromMaybePolyKey(entity, key);\n      if (!relation || typeof relation.load !== \"function\") continue;\n      if (relation.isLoaded) {\n        const result = relation.get;\n        if (Array.isArray(result)) {\n          for (const entity of result) {\n            if (!isLoaded(entity, nestedHint)) return false;\n          }\n        } else if (result && !isLoaded(result, nestedHint)) {\n          return false;\n        }\n      } else {\n        return false;\n      }\n    }\n    return true;\n  } else {\n    throw new Error(`Unexpected hint ${hint}`);\n  }\n}\n\n/**\n * Recursively checks if a relation-only populate hint is loaded on an entity.\n *\n * Unlike `isLoaded`, this returns `false` for non-loadable/primitive leaves instead of ignoring them, because\n * `ReactiveField.load` calls `em.populate` with load hints converted from reactive hints, i.e. `{ firstName: {} }`.\n * Treating those primitive leaves as loaded would let `EntityManager.populate` skip the batchloader path and change\n * reactive recalculation ordering, so the populate fast-path only applies to true relation populate hints.\n */\nexport function isLoadedForPopulate<T extends Entity, H extends LoadHint<T>>(\n  entity: T,\n  hint: H,\n): entity is Loaded<T, H> {\n  if (typeof hint === \"string\") {\n    const relation = getRelationFromMaybePolyKey(entity, hint);\n    return !!relation && typeof relation.load === \"function\" && relation.isLoaded;\n  } else if (Array.isArray(hint)) {\n    for (const key of hint as string[]) {\n      if (!isLoadedForPopulate(entity, key as H)) return false;\n    }\n    return true;\n  } else if (typeof hint === \"object\") {\n    for (const entry of Object.entries(hint as object)) {\n      const [key, nestedHint] = entry;\n      const relation = getRelationFromMaybePolyKey(entity, key);\n      if (!relation || typeof relation.load !== \"function\" || !relation.isLoaded) return false;\n      const result = relation.get;\n      if (Array.isArray(result)) {\n        for (const entity of result) {\n          if (!isLoadedForPopulate(entity, nestedHint as LoadHint<typeof entity>)) return false;\n        }\n      } else if (result && !isLoadedForPopulate(result, nestedHint as LoadHint<typeof result>)) {\n        return false;\n      }\n    }\n    return true;\n  } else {\n    throw new Error(`Unexpected hint ${hint}`);\n  }\n}\n\nexport function maybePopulateThen<T extends Entity, H extends LoadHint<T>, R>(\n  entity: T,\n  hint: H,\n  fn: (loaded: Loaded<T, H>) => R,\n): MaybePromise<R> {\n  return isLoaded(entity, hint) ? fn(entity) : (entity as any).populate(hint).then(fn);\n}\n\n/**\n * Runtime checks that `entity` has `hint` loaded, and type guards it as a `Loaded<T, hint>`.\n *\n * Similar to `ensureLoaded`, although `ensureLoaded` returns its value.\n */\nexport function assertLoaded<T extends Entity, const H extends LoadHint<T>>(\n  entity: T,\n  hint: H,\n): asserts entity is Loaded<T, H> {\n  if (!isLoaded(entity, hint)) fail(`${entity.id} is not loaded for ${JSON.stringify(hint)}`);\n}\n\n/**\n * Runtime checks that `entity` has `hint` loaded, and returns it as a `Loaded<T, entity>`.\n *\n * Similar to `assertLoaded`, although `assertLoaded` is a boolean type guard.\n */\nexport function ensureLoaded<T extends Entity, const H extends LoadHint<T>>(entity: T, hint: H): Loaded<T, H> {\n  assertLoaded<T, H>(entity, hint);\n  return entity;\n}\n\n/**\n * Unsafe type check for `entity` to `hint`, *without* a runtime type check.\n *\n * You should only use this if you're extremely sure that entity has hint loaded.\n */\nexport function unsafeLoaded<T extends Entity, const H extends LoadHint<T>>(entity: T, hint: H): Loaded<T, H> {\n  return entity as Loaded<T, H>;\n}\n\n/** From any `Relations` field in `T`, i.e. for loader hints. */\nexport type RelationsIn<T extends Entity> = SubType<T, Relation<any, any>>;\n\n// https://medium.com/dailyjs/typescript-create-a-condition-based-subset-types-9d902cea5b8c\ntype SubType<T, C> = Pick<T, { [K in keyof T]: T[K] extends C ? K : never }[keyof T]>;\n"],"mappings":";;;;;AA0IA,SAAgB,MAAwB,GAAmB;CACzD,OAAO,EAAE;AACX;;AA+DA,SAAgB,SAAkD,QAAW,MAAiC;CAC5G,IAAI,OAAO,SAAS,UAClB,OAAQ,OAAe,KAAK,CAAC;MACxB,IAAI,MAAM,QAAQ,IAAI,GAAG;EAC9B,KAAK,MAAM,OAAO,MAChB,IAAI,CAAE,OAAe,IAAI,CAAC,UAAU,OAAO;EAE7C,OAAO;CACT,OAAO,IAAI,OAAO,SAAS,UAAU;EACnC,KAAK,MAAM,SAAS,OAAO,QAAQ,IAAc,GAAG;GAClD,MAAM,CAAC,KAAK,cAAc;GAC1B,MAAM,WAAWA,iCAAAA,4BAA4B,QAAQ,GAAG;GACxD,IAAI,CAAC,YAAY,OAAO,SAAS,SAAS,YAAY;GACtD,IAAI,SAAS,UAAU;IACrB,MAAM,SAAS,SAAS;IACxB,IAAI,MAAM,QAAQ,MAAM,GACjB;UAAA,MAAM,UAAU,QACnB,IAAI,CAAC,SAAS,QAAQ,UAAU,GAAG,OAAO;IAAA,OAEvC,IAAI,UAAU,CAAC,SAAS,QAAQ,UAAU,GAC/C,OAAO;GAEX,OACE,OAAO;EAEX;EACA,OAAO;CACT,OACE,MAAM,IAAI,MAAM,mBAAmB,MAAM;AAE7C;;;;;;;;;AAUA,SAAgB,oBACd,QACA,MACwB;CACxB,IAAI,OAAO,SAAS,UAAU;EAC5B,MAAM,WAAWA,iCAAAA,4BAA4B,QAAQ,IAAI;EACzD,OAAO,CAAC,CAAC,YAAY,OAAO,SAAS,SAAS,cAAc,SAAS;CACvE,OAAO,IAAI,MAAM,QAAQ,IAAI,GAAG;EAC9B,KAAK,MAAM,OAAO,MAChB,IAAI,CAAC,oBAAoB,QAAQ,GAAQ,GAAG,OAAO;EAErD,OAAO;CACT,OAAO,IAAI,OAAO,SAAS,UAAU;EACnC,KAAK,MAAM,SAAS,OAAO,QAAQ,IAAc,GAAG;GAClD,MAAM,CAAC,KAAK,cAAc;GAC1B,MAAM,WAAWA,iCAAAA,4BAA4B,QAAQ,GAAG;GACxD,IAAI,CAAC,YAAY,OAAO,SAAS,SAAS,cAAc,CAAC,SAAS,UAAU,OAAO;GACnF,MAAM,SAAS,SAAS;GACxB,IAAI,MAAM,QAAQ,MAAM,GACjB;SAAA,MAAM,UAAU,QACnB,IAAI,CAAC,oBAAoB,QAAQ,UAAqC,GAAG,OAAO;GAAA,OAE7E,IAAI,UAAU,CAAC,oBAAoB,QAAQ,UAAqC,GACrF,OAAO;EAEX;EACA,OAAO;CACT,OACE,MAAM,IAAI,MAAM,mBAAmB,MAAM;AAE7C;AAEA,SAAgB,kBACd,QACA,MACA,IACiB;CACjB,OAAO,SAAS,QAAQ,IAAI,IAAI,GAAG,MAAM,IAAK,OAAe,SAAS,IAAI,CAAC,CAAC,KAAK,EAAE;AACrF;;;;;;AAOA,SAAgB,aACd,QACA,MACgC;CAChC,IAAI,CAAC,SAAS,QAAQ,IAAI,GAAG,cAAA,KAAK,GAAG,OAAO,GAAG,qBAAqB,KAAK,UAAU,IAAI,GAAG;AAC5F;;;;;;AAOA,SAAgB,aAA4D,QAAW,MAAuB;CAC5G,aAAmB,QAAQ,IAAI;CAC/B,OAAO;AACT;;;;;;AAOA,SAAgB,aAA4D,QAAW,MAAuB;CAC5G,OAAO;AACT"}

package/build/loading/loadHints.d.cts

@@ -0,0 +1,116 @@
+import { OptsOf } from "../typeMap.cjs";
+import { NormalizeHint } from "../normalizeHints.cjs";
+import { Collection, LoadedCollection } from "../relations/Collection.cjs";
+import { EnumCollection, LoadedEnumCollection } from "../relations/EnumCollection.cjs";
+import { AsyncMethod, LoadedMethod } from "../relations/hasAsyncMethod.cjs";
+import { LoadedProperty, Property } from "../relations/hasProperty.cjs";
+import { LoadedReference, Reference } from "../relations/Reference.cjs";
+import { Relation } from "../relations/Relation.cjs";
+import { LoadedOneToOneReference, OneToOneReference } from "../relations/OneToOneReference.cjs";
+import { LoadedReadOnlyCollection, ReadOnlyCollection } from "../relations/ReadOnlyCollection.cjs";
+import "../relations/index.cjs";
+import { MaybePromise, NullOrDefinedOr } from "../utils.cjs";
+import { Entity } from "../Entity.cjs";
+//#region src/loading/loadHints.d.ts
+declare const deepLoad: unique symbol;
+type DeepLoadHint<T extends Entity> = NestedLoadHint<T> & {
+  [deepLoad]: true;
+};
+type MaybeBaseType = any;
+/** Marks a given `T[K]` field as the loaded/synchronous version of the collection. */
+type MarkLoaded<T extends Entity, P, UH = {}> = P extends EnumCollection<MaybeBaseType, infer E> ? LoadedEnumCollection<T, E> : P extends OneToOneReference<MaybeBaseType, infer U> ? LoadedOneToOneReference<T, Loaded<U, UH>> : P extends Reference<MaybeBaseType, infer U, infer N> ? LoadedReference<T, Loaded<U, UH>, N> : P extends Collection<MaybeBaseType, infer U> ? LoadedCollection<T, Loaded<U, UH>> : P extends ReadOnlyCollection<MaybeBaseType, infer U> ? LoadedReadOnlyCollection<T, Loaded<U, UH>> : P extends Property<MaybeBaseType, infer V> ? [V] extends [(infer U extends Entity) | undefined] ? LoadedProperty<T, Loaded<U, UH> | Exclude<V, U>> : V extends readonly (infer U extends Entity)[] ? LoadedProperty<T, Loaded<U, UH>[]> : LoadedProperty<T, V> : P extends AsyncMethod<T, infer A, infer V> ? LoadedMethod<T, A, V> : unknown;
+/** A version of MarkLoaded the uses `DeepLoadHint` for tests. */
+type MarkDeepLoaded<T extends Entity, P> = P extends EnumCollection<MaybeBaseType, infer E> ? LoadedEnumCollection<T, E> : P extends OneToOneReference<MaybeBaseType, infer U> ? LoadedOneToOneReference<T, Loaded<U, DeepLoadHint<U>>> : P extends Reference<MaybeBaseType, infer U, infer N> ? LoadedReference<T, Loaded<U, DeepLoadHint<U>>, N> : P extends Collection<MaybeBaseType, infer U> ? LoadedCollection<T, Loaded<U, DeepLoadHint<U>>> : P extends ReadOnlyCollection<MaybeBaseType, infer U> ? LoadedReadOnlyCollection<T, Loaded<U, DeepLoadHint<U>>> : P extends Property<MaybeBaseType, infer V> ? [V] extends [(infer U extends Entity) | undefined] ? LoadedProperty<T, Loaded<U, DeepLoadHint<U>> | Exclude<V, U>> : V extends readonly (infer U extends Entity)[] ? LoadedProperty<T, Loaded<U, DeepLoadHint<U>>[]> : LoadedProperty<T, V> : P extends AsyncMethod<T, infer A, infer V> ? LoadedMethod<T, A, V> : unknown;
+/**
+ * A helper type for `New` that marks every `Reference` and `LoadedCollection` in `T` as loaded.
+ *
+ * We also look in opts `O` for the "`U`" type, i.e. the next level up/down in the graph,
+ * because the call site's opts may be using an also-marked loaded parent/child as an opt,
+ * so this will infer the type of that parent/child and use that for the `U` type.
+ *
+ * This means things like `entity.parent.get.grandParent.get` will work on the resulting
+ * type.
+ *
+ * Note that this is also purposefully broken out of `New` because of some weirdness
+ * around type narrowing that wasn't working when inlined into `New`.
+ */
+type MaybeUseOptsType<T extends Entity, O, K extends keyof T & keyof O> = O[K] extends NullOrDefinedOr<infer OK> ? OK extends Entity ? T[K] extends OneToOneReference<T, infer U> ? LoadedOneToOneReference<T, U> : T[K] extends Reference<T, infer U, infer N> ? LoadedReference<T, OK, N> : never : OK extends Array<infer OU> ? OU extends Entity ? T[K] extends Collection<T, infer U> ? LoadedCollection<T, OU> : never : T[K] : T[K] : never;
+/**
+ * Marks all references/collections of `T` as loaded, i.e. for newly instantiated entities where
+ * we know there are no already-existing rows with fk's to this new entity in the database.
+ *
+ * `O` is the generic from the call site so that if the caller passes `{ author: SomeLoadedAuthor }`,
+ * we'll prefer that type, as it might have more nested load hints that we can't otherwise assume.
+ */
+type New<T extends Entity, O extends OptsOf<T> = OptsOf<T>> = T & { [K in keyof T]: K extends keyof O ? MaybeUseOptsType<T, O, K> : MarkLoaded<T, T[K]>; };
+/**
+ * Marks all references/collections of `T` as deeply loaded, which is only useful for
+ * tests where we can have "the whole object graph" in-memory.
+ */
+type DeepNew<T extends Entity> = Loaded<T, DeepLoadHint<T>>;
+/** Detects whether an entity is newly created, and so we can treat all the relations as loaded. */
+declare function isNew<T extends Entity>(e: T): e is New<T>;
+/**
+ * All the loadable fields, i.e. relations or lazy-loaded/async properties, in an entity.
+ *
+ * We use a mapped type (instead of a code-generated type) so that we can pick up custom
+ * fields that have be added to the entity classes, i.e. `Author.numberOfBooks2` async
+ * properties.
+ */
+type Loadable<T extends Entity> = { -readonly [K in keyof T as LoadableValue<T[K]> extends never ? never : K]: LoadableValue<T[K]>; };
+/**
+ * Given an entity field/value, return the loadable entity.
+ *
+ * I.e. `Author.books` as a Reference or Collection, return `Book`.
+ *
+ * Note that we usually return entities, but for AsyncProperties it could be
+ * a calculated primitive value like number or string.
+ */
+type LoadableValue<V> = V extends EnumCollection<any, infer E> ? E : V extends Reference<any, infer U, any> ? U : V extends Collection<any, infer U> ? U : V extends ReadOnlyCollection<any, infer U> ? U : V extends AsyncMethod<any, any, infer V> ? V : V extends Property<any, infer P> ? P extends (infer U extends Entity) | undefined ? U : P : never;
+/**
+ *  A load hint of a single key, multiple keys, or nested keys and sub-hints.
+ *
+ * Load hints are different from reactive hints in that load hints include only references,
+ * collections, and async properties to preload (like `Book.author` or `Author.books`), and
+ * do not include any primitive fields (like `Author.firstName`).
+ */
+type LoadHint<T extends Entity> = (keyof Loadable<T> & string) | ReadonlyArray<keyof Loadable<T> & string> | NestedLoadHint<T>;
+type NestedLoadHint<T extends Entity> = { [K in keyof Loadable<T>]?: Loadable<T>[K] extends (infer U extends Entity) ? LoadHint<U> : {}; };
+/** Given an entity `T` that is being populated with hints `H`, marks the `H` attributes as populated. */
+type Loaded<T extends Entity, H> = T & { [K in keyof T & keyof NormalizeHint<H>]: H extends DeepLoadHint<T> ? MarkDeepLoaded<T, T[K]> : MarkLoaded<T, T[K], NormalizeHint<H>[K]>; };
+/** Recursively checks if the relations from a load hint are loaded on an entity. */
+declare function isLoaded<T extends Entity, H extends LoadHint<T>>(entity: T, hint: H): entity is Loaded<T, H>;
+/**
+ * Recursively checks if a relation-only populate hint is loaded on an entity.
+ *
+ * Unlike `isLoaded`, this returns `false` for non-loadable/primitive leaves instead of ignoring them, because
+ * `ReactiveField.load` calls `em.populate` with load hints converted from reactive hints, i.e. `{ firstName: {} }`.
+ * Treating those primitive leaves as loaded would let `EntityManager.populate` skip the batchloader path and change
+ * reactive recalculation ordering, so the populate fast-path only applies to true relation populate hints.
+ */
+declare function isLoadedForPopulate<T extends Entity, H extends LoadHint<T>>(entity: T, hint: H): entity is Loaded<T, H>;
+declare function maybePopulateThen<T extends Entity, H extends LoadHint<T>, R>(entity: T, hint: H, fn: (loaded: Loaded<T, H>) => R): MaybePromise<R>;
+/**
+ * Runtime checks that `entity` has `hint` loaded, and type guards it as a `Loaded<T, hint>`.
+ *
+ * Similar to `ensureLoaded`, although `ensureLoaded` returns its value.
+ */
+declare function assertLoaded<T extends Entity, const H extends LoadHint<T>>(entity: T, hint: H): asserts entity is Loaded<T, H>;
+/**
+ * Runtime checks that `entity` has `hint` loaded, and returns it as a `Loaded<T, entity>`.
+ *
+ * Similar to `assertLoaded`, although `assertLoaded` is a boolean type guard.
+ */
+declare function ensureLoaded<T extends Entity, const H extends LoadHint<T>>(entity: T, hint: H): Loaded<T, H>;
+/**
+ * Unsafe type check for `entity` to `hint`, *without* a runtime type check.
+ *
+ * You should only use this if you're extremely sure that entity has hint loaded.
+ */
+declare function unsafeLoaded<T extends Entity, const H extends LoadHint<T>>(entity: T, hint: H): Loaded<T, H>;
+/** From any `Relations` field in `T`, i.e. for loader hints. */
+type RelationsIn<T extends Entity> = SubType<T, Relation<any, any>>;
+type SubType<T, C> = Pick<T, { [K in keyof T]: T[K] extends C ? K : never; }[keyof T]>;
+//#endregion
+export { DeepNew, LoadHint, Loadable, LoadableValue, Loaded, MarkLoaded, NestedLoadHint, New, RelationsIn, assertLoaded, ensureLoaded, isLoaded, isLoadedForPopulate, isNew, maybePopulateThen, unsafeLoaded };
+//# sourceMappingURL=loadHints.d.cts.map

package/build/loading/loadHints.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loadHints.d.cts","names":[],"sources":["../../src/loading/loadHints.ts"],"mappings":"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"}

package/build/loading/loadHints.d.mts

@@ -0,0 +1,116 @@
+import { OptsOf } from "../typeMap.mjs";
+import { NormalizeHint } from "../normalizeHints.mjs";
+import { Collection, LoadedCollection } from "../relations/Collection.mjs";
+import { EnumCollection, LoadedEnumCollection } from "../relations/EnumCollection.mjs";
+import { AsyncMethod, LoadedMethod } from "../relations/hasAsyncMethod.mjs";
+import { LoadedProperty, Property } from "../relations/hasProperty.mjs";
+import { LoadedReference, Reference } from "../relations/Reference.mjs";
+import { Relation } from "../relations/Relation.mjs";
+import { LoadedOneToOneReference, OneToOneReference } from "../relations/OneToOneReference.mjs";
+import { LoadedReadOnlyCollection, ReadOnlyCollection } from "../relations/ReadOnlyCollection.mjs";
+import "../relations/index.mjs";
+import { MaybePromise, NullOrDefinedOr } from "../utils.mjs";
+import { Entity } from "../Entity.mjs";
+//#region src/loading/loadHints.d.ts
+declare const deepLoad: unique symbol;
+type DeepLoadHint<T extends Entity> = NestedLoadHint<T> & {
+  [deepLoad]: true;
+};
+type MaybeBaseType = any;
+/** Marks a given `T[K]` field as the loaded/synchronous version of the collection. */
+type MarkLoaded<T extends Entity, P, UH = {}> = P extends EnumCollection<MaybeBaseType, infer E> ? LoadedEnumCollection<T, E> : P extends OneToOneReference<MaybeBaseType, infer U> ? LoadedOneToOneReference<T, Loaded<U, UH>> : P extends Reference<MaybeBaseType, infer U, infer N> ? LoadedReference<T, Loaded<U, UH>, N> : P extends Collection<MaybeBaseType, infer U> ? LoadedCollection<T, Loaded<U, UH>> : P extends ReadOnlyCollection<MaybeBaseType, infer U> ? LoadedReadOnlyCollection<T, Loaded<U, UH>> : P extends Property<MaybeBaseType, infer V> ? [V] extends [(infer U extends Entity) | undefined] ? LoadedProperty<T, Loaded<U, UH> | Exclude<V, U>> : V extends readonly (infer U extends Entity)[] ? LoadedProperty<T, Loaded<U, UH>[]> : LoadedProperty<T, V> : P extends AsyncMethod<T, infer A, infer V> ? LoadedMethod<T, A, V> : unknown;
+/** A version of MarkLoaded the uses `DeepLoadHint` for tests. */
+type MarkDeepLoaded<T extends Entity, P> = P extends EnumCollection<MaybeBaseType, infer E> ? LoadedEnumCollection<T, E> : P extends OneToOneReference<MaybeBaseType, infer U> ? LoadedOneToOneReference<T, Loaded<U, DeepLoadHint<U>>> : P extends Reference<MaybeBaseType, infer U, infer N> ? LoadedReference<T, Loaded<U, DeepLoadHint<U>>, N> : P extends Collection<MaybeBaseType, infer U> ? LoadedCollection<T, Loaded<U, DeepLoadHint<U>>> : P extends ReadOnlyCollection<MaybeBaseType, infer U> ? LoadedReadOnlyCollection<T, Loaded<U, DeepLoadHint<U>>> : P extends Property<MaybeBaseType, infer V> ? [V] extends [(infer U extends Entity) | undefined] ? LoadedProperty<T, Loaded<U, DeepLoadHint<U>> | Exclude<V, U>> : V extends readonly (infer U extends Entity)[] ? LoadedProperty<T, Loaded<U, DeepLoadHint<U>>[]> : LoadedProperty<T, V> : P extends AsyncMethod<T, infer A, infer V> ? LoadedMethod<T, A, V> : unknown;
+/**
+ * A helper type for `New` that marks every `Reference` and `LoadedCollection` in `T` as loaded.
+ *
+ * We also look in opts `O` for the "`U`" type, i.e. the next level up/down in the graph,
+ * because the call site's opts may be using an also-marked loaded parent/child as an opt,
+ * so this will infer the type of that parent/child and use that for the `U` type.
+ *
+ * This means things like `entity.parent.get.grandParent.get` will work on the resulting
+ * type.
+ *
+ * Note that this is also purposefully broken out of `New` because of some weirdness
+ * around type narrowing that wasn't working when inlined into `New`.
+ */
+type MaybeUseOptsType<T extends Entity, O, K extends keyof T & keyof O> = O[K] extends NullOrDefinedOr<infer OK> ? OK extends Entity ? T[K] extends OneToOneReference<T, infer U> ? LoadedOneToOneReference<T, U> : T[K] extends Reference<T, infer U, infer N> ? LoadedReference<T, OK, N> : never : OK extends Array<infer OU> ? OU extends Entity ? T[K] extends Collection<T, infer U> ? LoadedCollection<T, OU> : never : T[K] : T[K] : never;
+/**
+ * Marks all references/collections of `T` as loaded, i.e. for newly instantiated entities where
+ * we know there are no already-existing rows with fk's to this new entity in the database.
+ *
+ * `O` is the generic from the call site so that if the caller passes `{ author: SomeLoadedAuthor }`,
+ * we'll prefer that type, as it might have more nested load hints that we can't otherwise assume.
+ */
+type New<T extends Entity, O extends OptsOf<T> = OptsOf<T>> = T & { [K in keyof T]: K extends keyof O ? MaybeUseOptsType<T, O, K> : MarkLoaded<T, T[K]>; };
+/**
+ * Marks all references/collections of `T` as deeply loaded, which is only useful for
+ * tests where we can have "the whole object graph" in-memory.
+ */
+type DeepNew<T extends Entity> = Loaded<T, DeepLoadHint<T>>;
+/** Detects whether an entity is newly created, and so we can treat all the relations as loaded. */
+declare function isNew<T extends Entity>(e: T): e is New<T>;
+/**
+ * All the loadable fields, i.e. relations or lazy-loaded/async properties, in an entity.
+ *
+ * We use a mapped type (instead of a code-generated type) so that we can pick up custom
+ * fields that have be added to the entity classes, i.e. `Author.numberOfBooks2` async
+ * properties.
+ */
+type Loadable<T extends Entity> = { -readonly [K in keyof T as LoadableValue<T[K]> extends never ? never : K]: LoadableValue<T[K]>; };
+/**
+ * Given an entity field/value, return the loadable entity.
+ *
+ * I.e. `Author.books` as a Reference or Collection, return `Book`.
+ *
+ * Note that we usually return entities, but for AsyncProperties it could be
+ * a calculated primitive value like number or string.
+ */
+type LoadableValue<V> = V extends EnumCollection<any, infer E> ? E : V extends Reference<any, infer U, any> ? U : V extends Collection<any, infer U> ? U : V extends ReadOnlyCollection<any, infer U> ? U : V extends AsyncMethod<any, any, infer V> ? V : V extends Property<any, infer P> ? P extends (infer U extends Entity) | undefined ? U : P : never;
+/**
+ *  A load hint of a single key, multiple keys, or nested keys and sub-hints.
+ *
+ * Load hints are different from reactive hints in that load hints include only references,
+ * collections, and async properties to preload (like `Book.author` or `Author.books`), and
+ * do not include any primitive fields (like `Author.firstName`).
+ */
+type LoadHint<T extends Entity> = (keyof Loadable<T> & string) | ReadonlyArray<keyof Loadable<T> & string> | NestedLoadHint<T>;
+type NestedLoadHint<T extends Entity> = { [K in keyof Loadable<T>]?: Loadable<T>[K] extends (infer U extends Entity) ? LoadHint<U> : {}; };
+/** Given an entity `T` that is being populated with hints `H`, marks the `H` attributes as populated. */
+type Loaded<T extends Entity, H> = T & { [K in keyof T & keyof NormalizeHint<H>]: H extends DeepLoadHint<T> ? MarkDeepLoaded<T, T[K]> : MarkLoaded<T, T[K], NormalizeHint<H>[K]>; };
+/** Recursively checks if the relations from a load hint are loaded on an entity. */
+declare function isLoaded<T extends Entity, H extends LoadHint<T>>(entity: T, hint: H): entity is Loaded<T, H>;
+/**
+ * Recursively checks if a relation-only populate hint is loaded on an entity.
+ *
+ * Unlike `isLoaded`, this returns `false` for non-loadable/primitive leaves instead of ignoring them, because
+ * `ReactiveField.load` calls `em.populate` with load hints converted from reactive hints, i.e. `{ firstName: {} }`.
+ * Treating those primitive leaves as loaded would let `EntityManager.populate` skip the batchloader path and change
+ * reactive recalculation ordering, so the populate fast-path only applies to true relation populate hints.
+ */
+declare function isLoadedForPopulate<T extends Entity, H extends LoadHint<T>>(entity: T, hint: H): entity is Loaded<T, H>;
+declare function maybePopulateThen<T extends Entity, H extends LoadHint<T>, R>(entity: T, hint: H, fn: (loaded: Loaded<T, H>) => R): MaybePromise<R>;
+/**
+ * Runtime checks that `entity` has `hint` loaded, and type guards it as a `Loaded<T, hint>`.
+ *
+ * Similar to `ensureLoaded`, although `ensureLoaded` returns its value.
+ */
+declare function assertLoaded<T extends Entity, const H extends LoadHint<T>>(entity: T, hint: H): asserts entity is Loaded<T, H>;
+/**
+ * Runtime checks that `entity` has `hint` loaded, and returns it as a `Loaded<T, entity>`.
+ *
+ * Similar to `assertLoaded`, although `assertLoaded` is a boolean type guard.
+ */
+declare function ensureLoaded<T extends Entity, const H extends LoadHint<T>>(entity: T, hint: H): Loaded<T, H>;
+/**
+ * Unsafe type check for `entity` to `hint`, *without* a runtime type check.
+ *
+ * You should only use this if you're extremely sure that entity has hint loaded.
+ */
+declare function unsafeLoaded<T extends Entity, const H extends LoadHint<T>>(entity: T, hint: H): Loaded<T, H>;
+/** From any `Relations` field in `T`, i.e. for loader hints. */
+type RelationsIn<T extends Entity> = SubType<T, Relation<any, any>>;
+type SubType<T, C> = Pick<T, { [K in keyof T]: T[K] extends C ? K : never; }[keyof T]>;
+//#endregion
+export { DeepNew, LoadHint, Loadable, LoadableValue, Loaded, MarkLoaded, NestedLoadHint, New, RelationsIn, assertLoaded, ensureLoaded, isLoaded, isLoadedForPopulate, isNew, maybePopulateThen, unsafeLoaded };
+//# sourceMappingURL=loadHints.d.mts.map

package/build/loading/loadHints.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loadHints.d.mts","names":[],"sources":["../../src/loading/loadHints.ts"],"mappings":";;;;;;;;;;;;;;cAuBM;KACD,aAAa,UAAU,UAAU,eAAe;GAAQ;;KAUxD;;KAGO,WAAW,UAAU,QAAQ,GAAG,WAC1C,UAAU,eAAe,qBAAqB,KAC1C,qBAAqB,GAAG,KACxB,UAAU,kBAAkB,qBAAqB,KAC/C,wBAAwB,GAAG,OAAO,GAAG,OACrC,UAAU,UAAU,qBAAqB,SAAS,KAChD,gBAAgB,GAAG,OAAO,GAAG,KAAK,KAClC,UAAU,WAAW,qBAAqB,KACxC,iBAAiB,GAAG,OAAO,GAAG,OAC9B,UAAU,mBAAmB,qBAAqB,KAChD,yBAAyB,GAAG,OAAO,GAAG,OACtC,UAAU,SAAS,qBAAqB,MAErC,mBAAmB,UAAU,uBACxC,eAAe,GAAG,OAAO,GAAG,MAAM,QAAQ,GAAG,MAC7C,0BAA0B,UAAU,YACpC,eAAe,GAAG,OAAO,GAAG,SAC5B,eAAe,GAAG,KACR,UAAU,YAAY,SAAS,SAAS,KACtC,aAAa,GAAG,GAAG;;KAIhC,eAAe,UAAU,QAAQ,KACpC,UAAU,eAAe,qBAAqB,KAC1C,qBAAqB,GAAG,KACxB,UAAU,kBAAkB,qBAAqB,KAC/C,wBAAwB,GAAG,OAAO,GAAG,aAAa,OAClD,UAAU,UAAU,qBAAqB,SAAS,KAChD,gBAAgB,GAAG,OAAO,GAAG,aAAa,KAAK,KAC/C,UAAU,WAAW,qBAAqB,KACxC,iBAAiB,GAAG,OAAO,GAAG,aAAa,OAC3C,UAAU,mBAAmB,qBAAqB,KAChD,yBAAyB,GAAG,OAAO,GAAG,aAAa,OACnD,UAAU,SAAS,qBAAqB,MAErC,mBAAmB,UAAU,uBACxC,eAAe,GAAG,OAAO,GAAG,aAAa,MAAM,QAAQ,GAAG,MAC1D,0BAA0B,UAAU,YACpC,eAAe,GAAG,OAAO,GAAG,aAAa,SACzC,eAAe,GAAG,KACR,UAAU,YAAY,SAAS,SAAS,KACtC,aAAa,GAAG,GAAG;;;;;;;;;;;;;;KAgBhC,iBAAiB,UAAU,QAAQ,GAAG,gBAAgB,UAAU,KACnE,EAAE,WAAW,sBAAsB,MAC/B,WAAW,SACT,EAAE,WAAW,kBAAkB,SAAS,KACtC,wBAAwB,GAAG,KAC3B,EAAE,WAAW,UAAU,SAAS,SAAS,KACvC,gBAAgB,GAAG,IAAI,aAE3B,WAAW,YAAY,MACrB,WAAW,SACT,EAAE,WAAW,WAAW,SAAS,KAC/B,iBAAiB,GAAG,cAEtB,EAAE,KACJ,EAAE;;;;;;;;KAUA,IAAI,UAAU,QAAQ,UAAU,OAAO,KAAK,OAAO,MAAM,OASlE,WAAW,IAAI,gBAAgB,IAAI,iBAAiB,GAAG,GAAG,KAAK,WAAW,GAAG,EAAE;;;;;KAOtE,QAAQ,UAAU,UAAU,OAAO,GAAG,aAAa;;iBAG/C,MAAM,UAAU,QAAQ,GAAG,IAAI,KAAK,IAAI;;;;;;;;KAW5C,SAAS,UAAU,uBAClB,WAAW,KAAK,cAAc,EAAE,4BAA4B,IAAI,cAAc,EAAE;;;;;;;;;KAWjF,cAAc,KACxB,UAAU,0BAA0B,KAChC,IACA,UAAU,qBAAqB,UAC7B,IACA,UAAU,sBAAsB,KAC9B,IACA,UAAU,8BAA8B,KACtC,IACA,UAAU,4BAA4B,KACpC,IACA,UAAU,oBAAoB,KAG5B,iBAAiB,UAAU,sBAAsB,IAAI;;;;;;;;KAUzD,SAAS,UAAU,iBACpB,SAAS,eAChB,oBAAoB,SAAS,eAC7B,eAAe;KAEP,eAAe,UAAU,aAElC,WAAW,SAAS,MAAM,SAAS,GAAG,kBAAiB,UAAU,UAAS,SAAS;;KAI1E,OAAO,UAAU,QAAQ,KAAK,OACvC,WAAW,UAAU,cAAc,KAAK,UAAU,aAAa,KAC5D,eAAe,GAAG,EAAE,MACpB,WAAW,GAAG,EAAE,IAAI,cAAc,GAAG;;iBAI3B,SAAS,UAAU,QAAQ,UAAU,SAAS,IAAI,QAAQ,GAAG,MAAM,IAAI,UAAU,OAAO,GAAG;;;;;;;;;iBAwC3F,oBAAoB,UAAU,QAAQ,UAAU,SAAS,IACvE,QAAQ,GACR,MAAM,IACL,UAAU,OAAO,GAAG;iBA6BP,kBAAkB,UAAU,QAAQ,UAAU,SAAS,IAAI,GACzE,QAAQ,GACR,MAAM,GACN,KAAK,QAAQ,OAAO,GAAG,OAAO,IAC7B,aAAa;;;;;;iBASA,aAAa,UAAU,cAAc,UAAU,SAAS,IACtE,QAAQ,GACR,MAAM,YACG,UAAU,OAAO,GAAG;;;;;;iBASf,aAAa,UAAU,cAAc,UAAU,SAAS,IAAI,QAAQ,GAAG,MAAM,IAAI,OAAO,GAAG;;;;;;iBAU3F,aAAa,UAAU,cAAc,UAAU,SAAS,IAAI,QAAQ,GAAG,MAAM,IAAI,OAAO,GAAG;;KAK/F,YAAY,UAAU,UAAU,QAAQ,GAAG;KAGlD,QAAQ,GAAG,KAAK,KAAK,MAAM,WAAW,IAAI,EAAE,WAAW,IAAI,mBAAkB"}