joist-core 2.3.0 → 2.4.0-next.10

package/build/relations/LazyField.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"LazyField.cjs","names":["lazyField","AbstractPropertyImpl","#fieldName","#loaded","#loadPromise","#value","getMetadata","getInstanceData","PropertyT","abbreviation","keyToNumber","kqDot","PojoRowData","tagId"],"sources":["../../src/relations/LazyField.ts"],"sourcesContent":["import { getInstanceData } from \"src/BaseEntity.ts\";\nimport { type BatchLoader } from \"src/batchloaders/BatchLoader.ts\";\nimport { type Entity } from \"src/Entity.ts\";\nimport { type EntityManager } from \"src/EntityManager.ts\";\nimport { type EntityMetadata, type PrimitiveField, getMetadata } from \"src/EntityMetadata.ts\";\nimport { setField } from \"src/fields.ts\";\nimport { keyToNumber, tagId } from \"src/keys.ts\";\nimport { lazyField } from \"src/newEntity.ts\";\nimport type { ParsedFindQuery } from \"src/queries/find/QueryParser.ts\";\nimport { kqDot } from \"src/queries/sql/keywords.ts\";\nimport { AbstractPropertyImpl } from \"src/relations/AbstractPropertyImpl.ts\";\nimport { type LoadedProperty, type Property } from \"src/relations/hasProperty.ts\";\nimport { PropertyT } from \"src/relations/PropertySymbols.ts\";\nimport { PojoRowData } from \"src/RowData.ts\";\nimport { abbreviation } from \"src/utils.ts\";\n\nexport const lazyColumnLoadOperation = \"lazy-column-load\";\n\n/**\n * The \"original value\" of an unloaded lazy column: unknown, and never equal to any set value.\n *\n * Seeded into `__orm.data` by `LazyFieldImpl.set` so that setting an unloaded column (even to\n * `undefined`) always registers as a change, i.e. instead of comparing equal to the `undefined`\n * that the excluded column would otherwise read as.\n */\nexport const notLoadedValue = Symbol(\"notLoadedValue\");\n\n/**\n * A single-column primitive (i.e. a large `jsonb`/`text`) that is deliberately excluded from the\n * entity's default SELECT and only fetched from the database on demand.\n *\n * I.e. `await author.someBigColumn.load()`, or synchronously via `.get` after `em.populate`.\n */\nexport interface LazyField<T extends Entity, V> extends Property<T, V> {\n  load(opts?: { forceReload?: boolean }): Promise<V>;\n  /** Sets the value in memory (dirtied for the next flush), i.e. without loading the current db value first. */\n  set(value: V): void;\n}\n\n/** Creates a `LazyField` for a column that codegen has marked `lazy: true`. */\nexport function hasLazyField<T extends Entity, V>(): LazyField<T, V> {\n  return lazyField((entity: T, fieldName: string) => new LazyFieldImpl<T, V>(entity, fieldName));\n}\n\nexport class LazyFieldImpl<T extends Entity, V> extends AbstractPropertyImpl<T> implements LazyField<T, V> {\n  #fieldName: string;\n  #loaded = false;\n  #loadPromise: Promise<V> | undefined;\n\n  constructor(entity: T, fieldName: string) {\n    super(entity);\n    this.#fieldName = fieldName;\n  }\n\n  /** Fetches this column from the database (batched across peers) and caches it on the entity. */\n  load(opts?: { forceReload?: boolean }): Promise<V> {\n    const { entity } = this;\n    if (opts?.forceReload) {\n      this.#loaded = false;\n      this.#loadPromise = undefined;\n    }\n    if (this.isLoaded) return Promise.resolve(this.#value);\n    const meta = getMetadata(entity);\n    return (this.#loadPromise ??= lazyColumnBatchLoader(entity.em, meta, this.#fieldName)\n      .load(entity.idTagged)\n      .then(() => {\n        this.#loaded = true;\n        return this.#value;\n      }));\n  }\n\n  get get(): V {\n    if (!this.isLoaded) {\n      throw new Error(`${this.#fieldName} has not been loaded yet, use '.load()' or an 'em.populate' hint`);\n    }\n    return this.#value;\n  }\n\n  /** Sets the value in memory; the column is dirtied and written on the next `em.flush`. */\n  set(value: V): void {\n    if (this.isLoaded) {\n      setField(this.entity, this.#fieldName, value);\n    } else {\n      // Seed `notLoadedValue` as the current value so the set always registers as a change against\n      // the unknown db value: an unloaded column otherwise reads as `undefined`, which would make\n      // `set(undefined)` a silent no-op, and a later `set(undefined)` falsely revert to clean.\n      const { data } = getInstanceData(this.entity);\n      data[this.#fieldName] = notLoadedValue;\n      try {\n        setField(this.entity, this.#fieldName, value);\n      } catch (e) {\n        // Don't leak the marker as a readable value, i.e. if setting on a deleted entity throws\n        delete data[this.#fieldName];\n        throw e;\n      }\n    }\n    this.#loaded = true;\n  }\n\n  get isLoaded(): boolean {\n    // New entities keep their value in-memory, so there's nothing to lazy-load.\n    if (getInstanceData(this.entity).isOrWasNew) return true;\n    return this.#loaded;\n  }\n\n  /** Called after em.flush to invalidate the cached value, since the db state may have changed. */\n  resetAfterFlush(): void {\n    this.#loaded = false;\n    this.#loadPromise = undefined;\n  }\n\n  /** The domain value, which `load`/`set` keep in the entity's `__orm.data` like any other column. */\n  get #value(): V {\n    return getInstanceData(this.entity).data[this.#fieldName] as V;\n  }\n\n  [PropertyT] = undefined as any as T;\n}\n\n/** Type guard utility for determining if an entity field is a LazyField. */\nexport function isLazyField(maybe: any): maybe is LazyField<any, any> {\n  return maybe instanceof LazyFieldImpl;\n}\n\n/** Type guard utility for determining if an entity field is a loaded LazyField. */\nexport function isLoadedLazyField(maybe: any): maybe is LazyField<any, any> & LoadedProperty<any, any> {\n  return isLazyField(maybe) && maybe.isLoaded;\n}\n\n/** Batches `LazyField.load`s for the same column into a single `SELECT id, <column> ... WHERE id IN (...)`. */\nfunction lazyColumnBatchLoader(em: EntityManager, meta: EntityMetadata, fieldName: string): BatchLoader<string> {\n  return em.getBatchLoader(lazyColumnLoadOperation, `${meta.tableName}-${fieldName}`, async (taggedIds) => {\n    const field = meta.allFields[fieldName] as PrimitiveField;\n    const column = field.serde.columns[0];\n    const alias = abbreviation(meta.tableName);\n    const keys = taggedIds.map((id) => keyToNumber(meta, id));\n    const query: ParsedFindQuery = {\n      selects: [`${kqDot(alias, \"id\")} as id`, kqDot(alias, column.columnName)],\n      tables: [{ alias, join: \"primary\", table: meta.tableName }],\n      condition: {\n        kind: \"exp\",\n        op: \"and\",\n        conditions: [{ kind: \"column\", alias, column: \"id\", dbType: meta.idDbType, cond: { kind: \"in\", value: keys } }],\n      },\n      orderBys: [],\n    };\n    const rows = await em[\"executeFind\"](meta, lazyColumnLoadOperation, query, {});\n    const rowData = new PojoRowData(rows);\n    for (let i = 0; i < rows.length; i++) {\n      const entity = em.findExistingInstance(tagId(meta, rows[i].id));\n      if (entity) getInstanceData(entity).data[fieldName] = field.serde.fromRow(rowData, i);\n    }\n  });\n}\n"],"mappings":"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"}

package/build/relations/LazyField.d.cts

@@ -0,0 +1,51 @@
+import { AbstractPropertyImpl } from "./AbstractPropertyImpl.cjs";
+import { PropertyT } from "./PropertySymbols.cjs";
+import { LoadedProperty, Property } from "./hasProperty.cjs";
+import { Entity } from "../Entity.cjs";
+//#region src/relations/LazyField.d.ts
+declare const lazyColumnLoadOperation = "lazy-column-load";
+/**
+ * The "original value" of an unloaded lazy column: unknown, and never equal to any set value.
+ *
+ * Seeded into `__orm.data` by `LazyFieldImpl.set` so that setting an unloaded column (even to
+ * `undefined`) always registers as a change, i.e. instead of comparing equal to the `undefined`
+ * that the excluded column would otherwise read as.
+ */
+declare const notLoadedValue: unique symbol;
+/**
+ * A single-column primitive (i.e. a large `jsonb`/`text`) that is deliberately excluded from the
+ * entity's default SELECT and only fetched from the database on demand.
+ *
+ * I.e. `await author.someBigColumn.load()`, or synchronously via `.get` after `em.populate`.
+ */
+interface LazyField<T extends Entity, V> extends Property<T, V> {
+  load(opts?: {
+    forceReload?: boolean;
+  }): Promise<V>;
+  /** Sets the value in memory (dirtied for the next flush), i.e. without loading the current db value first. */
+  set(value: V): void;
+}
+/** Creates a `LazyField` for a column that codegen has marked `lazy: true`. */
+declare function hasLazyField<T extends Entity, V>(): LazyField<T, V>;
+declare class LazyFieldImpl<T extends Entity, V> extends AbstractPropertyImpl<T> implements LazyField<T, V> {
+  #private;
+  constructor(entity: T, fieldName: string);
+  /** Fetches this column from the database (batched across peers) and caches it on the entity. */
+  load(opts?: {
+    forceReload?: boolean;
+  }): Promise<V>;
+  get get(): V;
+  /** Sets the value in memory; the column is dirtied and written on the next `em.flush`. */
+  set(value: V): void;
+  get isLoaded(): boolean;
+  /** Called after em.flush to invalidate the cached value, since the db state may have changed. */
+  resetAfterFlush(): void;
+  [PropertyT]: T;
+}
+/** Type guard utility for determining if an entity field is a LazyField. */
+declare function isLazyField(maybe: any): maybe is LazyField<any, any>;
+/** Type guard utility for determining if an entity field is a loaded LazyField. */
+declare function isLoadedLazyField(maybe: any): maybe is LazyField<any, any> & LoadedProperty<any, any>;
+//#endregion
+export { LazyField, LazyFieldImpl, hasLazyField, isLazyField, isLoadedLazyField, lazyColumnLoadOperation, notLoadedValue };
+//# sourceMappingURL=LazyField.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"LazyField.d.cts","names":[],"sources":["../../src/relations/LazyField.ts"],"mappings":";;;;;cAgBa;;;;;;;;cASA;;;;;;;UAQI,UAAU,UAAU,QAAQ,WAAW,SAAS,GAAG;EAClE,KAAK;IAAS;MAA0B,QAAQ;;EAEhD,IAAI,OAAO;;;iBAIG,aAAa,UAAU,QAAQ,MAAM,UAAU,GAAG;cAIrD,cAAc,UAAU,QAAQ,WAAW,qBAAqB,cAAc,UAAU,GAAG;;EAKtG,YAAY,QAAQ,GAAG;;EAMvB,KAAK;IAAS;MAA0B,QAAQ;MAgB5C,OAAO;;EAQX,IAAI,OAAO;MAoBP;;EAOJ;GAUC,YAAiC;;;iBAIpB,YAAY,aAAa,SAAS;;iBAKlC,kBAAkB,aAAa,SAAS,sBAAsB"}

package/build/relations/LazyField.d.mts

@@ -0,0 +1,51 @@
+import { AbstractPropertyImpl } from "./AbstractPropertyImpl.mjs";
+import { PropertyT } from "./PropertySymbols.mjs";
+import { LoadedProperty, Property } from "./hasProperty.mjs";
+import { Entity } from "../Entity.mjs";
+//#region src/relations/LazyField.d.ts
+declare const lazyColumnLoadOperation = "lazy-column-load";
+/**
+ * The "original value" of an unloaded lazy column: unknown, and never equal to any set value.
+ *
+ * Seeded into `__orm.data` by `LazyFieldImpl.set` so that setting an unloaded column (even to
+ * `undefined`) always registers as a change, i.e. instead of comparing equal to the `undefined`
+ * that the excluded column would otherwise read as.
+ */
+declare const notLoadedValue: unique symbol;
+/**
+ * A single-column primitive (i.e. a large `jsonb`/`text`) that is deliberately excluded from the
+ * entity's default SELECT and only fetched from the database on demand.
+ *
+ * I.e. `await author.someBigColumn.load()`, or synchronously via `.get` after `em.populate`.
+ */
+interface LazyField<T extends Entity, V> extends Property<T, V> {
+  load(opts?: {
+    forceReload?: boolean;
+  }): Promise<V>;
+  /** Sets the value in memory (dirtied for the next flush), i.e. without loading the current db value first. */
+  set(value: V): void;
+}
+/** Creates a `LazyField` for a column that codegen has marked `lazy: true`. */
+declare function hasLazyField<T extends Entity, V>(): LazyField<T, V>;
+declare class LazyFieldImpl<T extends Entity, V> extends AbstractPropertyImpl<T> implements LazyField<T, V> {
+  #private;
+  constructor(entity: T, fieldName: string);
+  /** Fetches this column from the database (batched across peers) and caches it on the entity. */
+  load(opts?: {
+    forceReload?: boolean;
+  }): Promise<V>;
+  get get(): V;
+  /** Sets the value in memory; the column is dirtied and written on the next `em.flush`. */
+  set(value: V): void;
+  get isLoaded(): boolean;
+  /** Called after em.flush to invalidate the cached value, since the db state may have changed. */
+  resetAfterFlush(): void;
+  [PropertyT]: T;
+}
+/** Type guard utility for determining if an entity field is a LazyField. */
+declare function isLazyField(maybe: any): maybe is LazyField<any, any>;
+/** Type guard utility for determining if an entity field is a loaded LazyField. */
+declare function isLoadedLazyField(maybe: any): maybe is LazyField<any, any> & LoadedProperty<any, any>;
+//#endregion
+export { LazyField, LazyFieldImpl, hasLazyField, isLazyField, isLoadedLazyField, lazyColumnLoadOperation, notLoadedValue };
+//# sourceMappingURL=LazyField.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"LazyField.d.mts","names":[],"sources":["../../src/relations/LazyField.ts"],"mappings":";;;;;cAgBa;;;;;;;;cASA;;;;;;;UAQI,UAAU,UAAU,QAAQ,WAAW,SAAS,GAAG;EAClE,KAAK;IAAS;MAA0B,QAAQ;;EAEhD,IAAI,OAAO;;;iBAIG,aAAa,UAAU,QAAQ,MAAM,UAAU,GAAG;cAIrD,cAAc,UAAU,QAAQ,WAAW,qBAAqB,cAAc,UAAU,GAAG;;EAKtG,YAAY,QAAQ,GAAG;;EAMvB,KAAK;IAAS;MAA0B,QAAQ;MAgB5C,OAAO;;EAQX,IAAI,OAAO;MAoBP;;EAOJ;GAUC,YAAiC;;;iBAIpB,YAAY,aAAa,SAAS;;iBAKlC,kBAAkB,aAAa,SAAS,sBAAsB"}

package/build/relations/LazyField.js

@@ -0,0 +1,134 @@
+import "../batchloaders/BatchLoader.js";
+import { AbstractPropertyImpl } from "./AbstractPropertyImpl.js";
+import { PropertyT } from "./PropertySymbols.js";
+import "./hasProperty.js";
+import { setField } from "../fields.js";
+import { keyToNumber, tagId } from "../keys.js";
+import { kqDot } from "../queries/sql/keywords.js";
+import { PojoRowData } from "../RowData.js";
+import { abbreviation } from "../utils.js";
+import { lazyField } from "../newEntity.js";
+import { getMetadata } from "../EntityMetadata.js";
+import "../EntityManager.js";
+import "../Entity.js";
+import { getInstanceData } from "../BaseEntity.js";
+//#region src/relations/LazyField.ts
+const lazyColumnLoadOperation = "lazy-column-load";
+/**
+* The "original value" of an unloaded lazy column: unknown, and never equal to any set value.
+*
+* Seeded into `__orm.data` by `LazyFieldImpl.set` so that setting an unloaded column (even to
+* `undefined`) always registers as a change, i.e. instead of comparing equal to the `undefined`
+* that the excluded column would otherwise read as.
+*/
+const notLoadedValue = Symbol("notLoadedValue");
+/** Creates a `LazyField` for a column that codegen has marked `lazy: true`. */
+function hasLazyField() {
+	return lazyField((entity, fieldName) => new LazyFieldImpl(entity, fieldName));
+}
+var LazyFieldImpl = class extends AbstractPropertyImpl {
+	#fieldName;
+	#loaded = false;
+	#loadPromise;
+	constructor(entity, fieldName) {
+		super(entity);
+		this.#fieldName = fieldName;
+	}
+	/** Fetches this column from the database (batched across peers) and caches it on the entity. */
+	load(opts) {
+		const { entity } = this;
+		if (opts?.forceReload) {
+			this.#loaded = false;
+			this.#loadPromise = void 0;
+		}
+		if (this.isLoaded) return Promise.resolve(this.#value);
+		const meta = getMetadata(entity);
+		return this.#loadPromise ??= lazyColumnBatchLoader(entity.em, meta, this.#fieldName).load(entity.idTagged).then(() => {
+			this.#loaded = true;
+			return this.#value;
+		});
+	}
+	get get() {
+		if (!this.isLoaded) throw new Error(`${this.#fieldName} has not been loaded yet, use '.load()' or an 'em.populate' hint`);
+		return this.#value;
+	}
+	/** Sets the value in memory; the column is dirtied and written on the next `em.flush`. */
+	set(value) {
+		if (this.isLoaded) setField(this.entity, this.#fieldName, value);
+		else {
+			const { data } = getInstanceData(this.entity);
+			data[this.#fieldName] = notLoadedValue;
+			try {
+				setField(this.entity, this.#fieldName, value);
+			} catch (e) {
+				delete data[this.#fieldName];
+				throw e;
+			}
+		}
+		this.#loaded = true;
+	}
+	get isLoaded() {
+		if (getInstanceData(this.entity).isOrWasNew) return true;
+		return this.#loaded;
+	}
+	/** Called after em.flush to invalidate the cached value, since the db state may have changed. */
+	resetAfterFlush() {
+		this.#loaded = false;
+		this.#loadPromise = void 0;
+	}
+	/** The domain value, which `load`/`set` keep in the entity's `__orm.data` like any other column. */
+	get #value() {
+		return getInstanceData(this.entity).data[this.#fieldName];
+	}
+	[PropertyT] = void 0;
+};
+/** Type guard utility for determining if an entity field is a LazyField. */
+function isLazyField(maybe) {
+	return maybe instanceof LazyFieldImpl;
+}
+/** Type guard utility for determining if an entity field is a loaded LazyField. */
+function isLoadedLazyField(maybe) {
+	return isLazyField(maybe) && maybe.isLoaded;
+}
+/** Batches `LazyField.load`s for the same column into a single `SELECT id, <column> ... WHERE id IN (...)`. */
+function lazyColumnBatchLoader(em, meta, fieldName) {
+	return em.getBatchLoader(lazyColumnLoadOperation, `${meta.tableName}-${fieldName}`, async (taggedIds) => {
+		const field = meta.allFields[fieldName];
+		const column = field.serde.columns[0];
+		const alias = abbreviation(meta.tableName);
+		const keys = taggedIds.map((id) => keyToNumber(meta, id));
+		const query = {
+			selects: [`${kqDot(alias, "id")} as id`, kqDot(alias, column.columnName)],
+			tables: [{
+				alias,
+				join: "primary",
+				table: meta.tableName
+			}],
+			condition: {
+				kind: "exp",
+				op: "and",
+				conditions: [{
+					kind: "column",
+					alias,
+					column: "id",
+					dbType: meta.idDbType,
+					cond: {
+						kind: "in",
+						value: keys
+					}
+				}]
+			},
+			orderBys: []
+		};
+		const rows = await em["executeFind"](meta, lazyColumnLoadOperation, query, {});
+		const rowData = new PojoRowData(rows);
+		for (let i = 0; i < rows.length; i++) {
+			const entity = em.findExistingInstance(tagId(meta, rows[i].id));
+			if (entity) getInstanceData(entity).data[fieldName] = field.serde.fromRow(rowData, i);
+		}
+	});
+}
+//#endregion
+export { LazyFieldImpl, hasLazyField, isLazyField, isLoadedLazyField, lazyColumnLoadOperation, notLoadedValue };
+
+//# sourceMappingURL=LazyField.js.map

package/build/relations/LazyField.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LazyField.js","names":["#fieldName","#loaded","#loadPromise","#value"],"sources":["../../src/relations/LazyField.ts"],"sourcesContent":["import { getInstanceData } from \"src/BaseEntity.ts\";\nimport { type BatchLoader } from \"src/batchloaders/BatchLoader.ts\";\nimport { type Entity } from \"src/Entity.ts\";\nimport { type EntityManager } from \"src/EntityManager.ts\";\nimport { type EntityMetadata, type PrimitiveField, getMetadata } from \"src/EntityMetadata.ts\";\nimport { setField } from \"src/fields.ts\";\nimport { keyToNumber, tagId } from \"src/keys.ts\";\nimport { lazyField } from \"src/newEntity.ts\";\nimport type { ParsedFindQuery } from \"src/queries/find/QueryParser.ts\";\nimport { kqDot } from \"src/queries/sql/keywords.ts\";\nimport { AbstractPropertyImpl } from \"src/relations/AbstractPropertyImpl.ts\";\nimport { type LoadedProperty, type Property } from \"src/relations/hasProperty.ts\";\nimport { PropertyT } from \"src/relations/PropertySymbols.ts\";\nimport { PojoRowData } from \"src/RowData.ts\";\nimport { abbreviation } from \"src/utils.ts\";\n\nexport const lazyColumnLoadOperation = \"lazy-column-load\";\n\n/**\n * The \"original value\" of an unloaded lazy column: unknown, and never equal to any set value.\n *\n * Seeded into `__orm.data` by `LazyFieldImpl.set` so that setting an unloaded column (even to\n * `undefined`) always registers as a change, i.e. instead of comparing equal to the `undefined`\n * that the excluded column would otherwise read as.\n */\nexport const notLoadedValue = Symbol(\"notLoadedValue\");\n\n/**\n * A single-column primitive (i.e. a large `jsonb`/`text`) that is deliberately excluded from the\n * entity's default SELECT and only fetched from the database on demand.\n *\n * I.e. `await author.someBigColumn.load()`, or synchronously via `.get` after `em.populate`.\n */\nexport interface LazyField<T extends Entity, V> extends Property<T, V> {\n  load(opts?: { forceReload?: boolean }): Promise<V>;\n  /** Sets the value in memory (dirtied for the next flush), i.e. without loading the current db value first. */\n  set(value: V): void;\n}\n\n/** Creates a `LazyField` for a column that codegen has marked `lazy: true`. */\nexport function hasLazyField<T extends Entity, V>(): LazyField<T, V> {\n  return lazyField((entity: T, fieldName: string) => new LazyFieldImpl<T, V>(entity, fieldName));\n}\n\nexport class LazyFieldImpl<T extends Entity, V> extends AbstractPropertyImpl<T> implements LazyField<T, V> {\n  #fieldName: string;\n  #loaded = false;\n  #loadPromise: Promise<V> | undefined;\n\n  constructor(entity: T, fieldName: string) {\n    super(entity);\n    this.#fieldName = fieldName;\n  }\n\n  /** Fetches this column from the database (batched across peers) and caches it on the entity. */\n  load(opts?: { forceReload?: boolean }): Promise<V> {\n    const { entity } = this;\n    if (opts?.forceReload) {\n      this.#loaded = false;\n      this.#loadPromise = undefined;\n    }\n    if (this.isLoaded) return Promise.resolve(this.#value);\n    const meta = getMetadata(entity);\n    return (this.#loadPromise ??= lazyColumnBatchLoader(entity.em, meta, this.#fieldName)\n      .load(entity.idTagged)\n      .then(() => {\n        this.#loaded = true;\n        return this.#value;\n      }));\n  }\n\n  get get(): V {\n    if (!this.isLoaded) {\n      throw new Error(`${this.#fieldName} has not been loaded yet, use '.load()' or an 'em.populate' hint`);\n    }\n    return this.#value;\n  }\n\n  /** Sets the value in memory; the column is dirtied and written on the next `em.flush`. */\n  set(value: V): void {\n    if (this.isLoaded) {\n      setField(this.entity, this.#fieldName, value);\n    } else {\n      // Seed `notLoadedValue` as the current value so the set always registers as a change against\n      // the unknown db value: an unloaded column otherwise reads as `undefined`, which would make\n      // `set(undefined)` a silent no-op, and a later `set(undefined)` falsely revert to clean.\n      const { data } = getInstanceData(this.entity);\n      data[this.#fieldName] = notLoadedValue;\n      try {\n        setField(this.entity, this.#fieldName, value);\n      } catch (e) {\n        // Don't leak the marker as a readable value, i.e. if setting on a deleted entity throws\n        delete data[this.#fieldName];\n        throw e;\n      }\n    }\n    this.#loaded = true;\n  }\n\n  get isLoaded(): boolean {\n    // New entities keep their value in-memory, so there's nothing to lazy-load.\n    if (getInstanceData(this.entity).isOrWasNew) return true;\n    return this.#loaded;\n  }\n\n  /** Called after em.flush to invalidate the cached value, since the db state may have changed. */\n  resetAfterFlush(): void {\n    this.#loaded = false;\n    this.#loadPromise = undefined;\n  }\n\n  /** The domain value, which `load`/`set` keep in the entity's `__orm.data` like any other column. */\n  get #value(): V {\n    return getInstanceData(this.entity).data[this.#fieldName] as V;\n  }\n\n  [PropertyT] = undefined as any as T;\n}\n\n/** Type guard utility for determining if an entity field is a LazyField. */\nexport function isLazyField(maybe: any): maybe is LazyField<any, any> {\n  return maybe instanceof LazyFieldImpl;\n}\n\n/** Type guard utility for determining if an entity field is a loaded LazyField. */\nexport function isLoadedLazyField(maybe: any): maybe is LazyField<any, any> & LoadedProperty<any, any> {\n  return isLazyField(maybe) && maybe.isLoaded;\n}\n\n/** Batches `LazyField.load`s for the same column into a single `SELECT id, <column> ... WHERE id IN (...)`. */\nfunction lazyColumnBatchLoader(em: EntityManager, meta: EntityMetadata, fieldName: string): BatchLoader<string> {\n  return em.getBatchLoader(lazyColumnLoadOperation, `${meta.tableName}-${fieldName}`, async (taggedIds) => {\n    const field = meta.allFields[fieldName] as PrimitiveField;\n    const column = field.serde.columns[0];\n    const alias = abbreviation(meta.tableName);\n    const keys = taggedIds.map((id) => keyToNumber(meta, id));\n    const query: ParsedFindQuery = {\n      selects: [`${kqDot(alias, \"id\")} as id`, kqDot(alias, column.columnName)],\n      tables: [{ alias, join: \"primary\", table: meta.tableName }],\n      condition: {\n        kind: \"exp\",\n        op: \"and\",\n        conditions: [{ kind: \"column\", alias, column: \"id\", dbType: meta.idDbType, cond: { kind: \"in\", value: keys } }],\n      },\n      orderBys: [],\n    };\n    const rows = await em[\"executeFind\"](meta, lazyColumnLoadOperation, query, {});\n    const rowData = new PojoRowData(rows);\n    for (let i = 0; i < rows.length; i++) {\n      const entity = em.findExistingInstance(tagId(meta, rows[i].id));\n      if (entity) getInstanceData(entity).data[fieldName] = field.serde.fromRow(rowData, i);\n    }\n  });\n}\n"],"mappings":"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"}