joist-core 2.3.0 → 2.4.0

package/build/relations/ManyToOneReference.cjs

@@ -0,0 +1,364 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_relations_AbstractRelationImpl = require("./AbstractRelationImpl.cjs");
+const require_relations_RelationSymbols = require("./RelationSymbols.cjs");
+const require_relations_ReferenceSymbols = require("./ReferenceSymbols.cjs");
+const require_fields = require("../fields.cjs");
+const require_keys = require("../keys.cjs");
+const require_relations_isCascadeDelete = require("./isCascadeDelete.cjs");
+const require_relations_OneToManyCollection = require("./OneToManyCollection.cjs");
+const require_relations_OneToManyLargeCollection = require("./OneToManyLargeCollection.cjs");
+const require_relations_OneToOneReference = require("./OneToOneReference.cjs");
+const require_utils = require("../utils.cjs");
+const require_newEntity = require("../newEntity.cjs");
+const require_EntityMetadata = require("../EntityMetadata.cjs");
+const require_index = require("../index.cjs");
+const require_EntityManager = require("../EntityManager.cjs");
+const require_Entity = require("../Entity.cjs");
+const require_BaseEntity = require("../BaseEntity.cjs");
+//#region src/relations/ManyToOneReference.ts
+/** An alias for creating `ManyToOneReference`s. */
+function hasOne() {
+	return require_newEntity.lazyField((entity, fieldName) => {
+		const m2o = require_EntityMetadata.getMetadata(entity).allFields[fieldName];
+		return new ManyToOneReferenceImpl(entity, m2o);
+	});
+}
+/** Type guard utility for determining if an entity field is a ManyToOneReference. */
+function isManyToOneReference(maybeReference) {
+	return maybeReference instanceof ManyToOneReferenceImpl;
+}
+/**
+* Manages a foreign key from one entity to another, i.e. `Book.author --> Author`.
+*
+* We keep the current `author` / `author_id` value in the `__orm.data` hash, where the
+* current value could be either the (string) author id from the database, or an entity
+* `Author` that the user has set.
+*
+* Note that if our `images.author_id` column is unique, this `ManyToOneReference` will essentially
+* be half of a one-to-one relationship, but we'll keep using this `ManyToOneReference` on the "many"
+* side, and the other side, i.e. `Author.image` will use a `OneToOneReference` to point back to us.
+*/
+var ManyToOneReferenceImpl = class extends require_relations_AbstractRelationImpl.AbstractRelationImpl {
+	#field;
+	#state;
+	#loadPromise;
+	#hasBeenSet = false;
+	constructor(entity, field) {
+		super(entity);
+		this.#field = field;
+		this.#state = require_BaseEntity.getInstanceData(entity).isOrWasNew ? new M2OLoadedState(this, void 0) : new M2OUnloadedState(this);
+	}
+	async load(opts = {}) {
+		require_index.ensureNotDeleted(this.entity, "pending");
+		this.#state = this.#state.maybeInstantLoad();
+		if (!this.#state.isLoaded || opts.forceReload) {
+			const current = this.current();
+			if (require_Entity.isEntity(current) || current === void 0) this.#state = new M2OLoadedState(this, current);
+			else await (this.#loadPromise ??= this.entity.em.load(this.otherMeta.cstr, current).then((entity) => {
+				this.#loadPromise = void 0;
+				if (require_EntityManager.sameEntity(entity, this.current())) this.#state = this.#state.applyLoad(entity);
+			}));
+		}
+		return this.filterDeleted(this.#state.doGet(), opts);
+	}
+	set(other) {
+		this.#setImpl(other);
+	}
+	get isSet() {
+		return this.current() !== void 0;
+	}
+	get isLoaded() {
+		this.#state = this.#state.maybeInstantLoad();
+		return this.#state.isLoaded;
+	}
+	get isPreloaded() {
+		return !!this.maybeFindEntity();
+	}
+	preload() {
+		this.#state = new M2OLoadedState(this, this.maybeFindEntity());
+	}
+	unload() {
+		this.#state = new M2OUnloadedState(this);
+		this.#loadPromise = void 0;
+	}
+	/** Copy another em's `source` relation into our state. */
+	import(source, findEntity) {
+		this.#state = source.#state.import(this, findEntity);
+	}
+	doGet(opts) {
+		require_index.ensureNotDeleted(this.entity, "pending");
+		this.#state = this.#state.maybeInstantLoad();
+		return this.filterDeleted(this.#state.doGet(), opts);
+	}
+	get getWithDeleted() {
+		return this.doGet({ withDeleted: true });
+	}
+	get get() {
+		return this.doGet({ withDeleted: false });
+	}
+	/** Returns the id of the current value. */
+	get id() {
+		return this.idMaybe || failNoId(this.entity, this.fieldName, this.current());
+	}
+	/** Sets the m2o to `id`, and allows accepting `undefined` (`N`) if this is a nullable relation. */
+	set id(id) {
+		require_index.ensureNotDeleted(this.entity, "pending");
+		const newId = require_keys.toTaggedId(this.otherMeta, id);
+		const previousId = this.idTaggedMaybe;
+		const previous = this.maybeFindEntity();
+		if (!require_fields.setField(this.entity, this.fieldName, id)) return;
+		const loaded = newId ? this.entity.em.getEntity(newId) : void 0;
+		this.#state = loaded ? new M2OLoadedState(this, loaded) : new M2OUnloadedState(this);
+		this.#loadPromise = void 0;
+		this.#percolateRemove(previousId, previous);
+		this.#percolateAdd();
+	}
+	get idIfSet() {
+		return this.idMaybe || failIfNewEntity(this.entity, this.fieldName, this.current());
+	}
+	get idUntagged() {
+		return this.idUntaggedMaybe || failNoId(this.entity, this.fieldName, this.current());
+	}
+	get idUntaggedIfSet() {
+		return this.idUntaggedMaybe || failIfNewEntity(this.entity, this.fieldName, this.current());
+	}
+	get idMaybe() {
+		require_index.ensureNotDeleted(this.entity, "pending");
+		return require_keys.toIdOf(this.otherMeta, this.idTaggedMaybe);
+	}
+	/** Returns the tagged id of the current value, or undefined if unset or a new entity. */
+	get idTaggedMaybe() {
+		return require_keys.maybeResolveReferenceToId(this.current());
+	}
+	get fieldName() {
+		return this.#field.fieldName;
+	}
+	get otherFieldName() {
+		return this.#field.otherFieldName;
+	}
+	get idUntaggedMaybe() {
+		return require_keys.deTagId(this.otherMeta, this.idMaybe);
+	}
+	#setImpl(_other) {
+		require_index.ensureNotDeleted(this.entity, "pending");
+		this.#hasBeenSet = true;
+		const other = require_keys.ensureTagged(this.otherMeta, _other);
+		if (require_EntityManager.sameEntity(other, this.current({ withDeleted: true }))) return;
+		const previousId = this.idTaggedMaybe;
+		const previous = this.maybeFindEntity();
+		require_fields.setField(this.entity, this.fieldName, require_Entity.isEntity(other) ? other?.idTaggedMaybe ?? other : other);
+		const maybeEntity = require_Entity.isEntity(other) ? other : other ? this.entity.em.getEntity(other) : void 0;
+		if (maybeEntity || other === void 0) this.#state = new M2OLoadedState(this, maybeEntity ?? other);
+		else this.#state = new M2OUnloadedState(this);
+		this.#loadPromise = void 0;
+		this.#percolateRemove(previousId, previous);
+		this.#percolateAdd();
+	}
+	setFromOpts(other) {
+		this.#setImpl(other);
+	}
+	maybeCascadeDelete() {
+		if (this.isCascadeDelete) {
+			const current = this.current({ withDeleted: true });
+			if (current !== void 0) {
+				if (typeof current === "string") {
+					const other = this.entity.em.getEntity(current);
+					if (other) this.entity.em.delete(other);
+				} else this.entity.em.delete(current);
+			}
+		}
+	}
+	async cleanupOnEntityDeleted() {
+		if (this.isCascadeDelete) return;
+		const current = await this.load({ withDeleted: true });
+		if (current !== void 0) {
+			const o2m = this.getOtherRelation(current);
+			if (o2m instanceof require_relations_OneToManyCollection.OneToManyCollection) o2m.remove(this.entity, { requireLoaded: false });
+			else if (o2m instanceof require_relations_OneToManyLargeCollection.OneToManyLargeCollection) o2m.remove(this.entity);
+			else if (o2m instanceof require_relations_OneToOneReference.OneToOneReferenceImpl) o2m.set(void 0);
+			else throw new Error(`Unhandled ${o2m}`);
+		}
+		require_fields.setField(this.entity, this.fieldName, void 0);
+		this.#state = new M2OLoadedState(this, void 0);
+	}
+	#percolateRemove(prevId, prevEntity) {
+		if (prevEntity) {
+			const prevRelation = this.getOtherRelation(prevEntity);
+			if (prevRelation instanceof require_relations_OneToManyCollection.OneToManyCollection) prevRelation.removeIfLoaded(this.entity);
+			else if (prevRelation instanceof require_relations_OneToManyLargeCollection.OneToManyLargeCollection) prevRelation.remove(this.entity);
+			else prevRelation.set(void 0, { percolating: true });
+		} else if (prevId) {
+			const { em } = this.entity;
+			let map = require_EntityManager.getEmInternalApi(em).pendingPercolate.get(prevId);
+			if (!map) {
+				map = /* @__PURE__ */ new Map();
+				require_EntityManager.getEmInternalApi(em).pendingPercolate.set(prevId, map);
+			}
+			let pending = map.get(this.otherFieldName);
+			if (!pending) {
+				pending = {
+					adds: [],
+					removes: []
+				};
+				map.set(this.otherFieldName, pending);
+			}
+			require_utils.maybeAdd(pending.removes, this.entity);
+			require_utils.maybeRemove(pending.adds, this.entity);
+		}
+	}
+	#percolateAdd() {
+		const id = this.current();
+		const other = this.maybeFindEntity();
+		if (other) {
+			const newRelation = this.getOtherRelation(other);
+			if (newRelation instanceof require_relations_OneToManyCollection.OneToManyCollection) newRelation.add(this.entity);
+			else if (newRelation instanceof require_relations_OneToManyLargeCollection.OneToManyLargeCollection) newRelation.add(this.entity);
+			else if (newRelation) newRelation.set(this.entity, { percolating: true });
+		} else if (typeof id === "string") {
+			const { em } = this.entity;
+			let map = require_EntityManager.getEmInternalApi(em).pendingPercolate.get(id);
+			if (!map) {
+				map = /* @__PURE__ */ new Map();
+				require_EntityManager.getEmInternalApi(em).pendingPercolate.set(id, map);
+			}
+			let pending = map.get(this.otherFieldName);
+			if (!pending) {
+				pending = {
+					adds: [],
+					removes: []
+				};
+				map.set(this.otherFieldName, pending);
+			}
+			require_utils.maybeAdd(pending.adds, this.entity);
+			require_utils.maybeRemove(pending.removes, this.entity);
+		}
+	}
+	current(opts) {
+		const current = require_fields.getField(this.entity, this.fieldName);
+		if (current !== void 0 && require_Entity.isEntity(current)) return this.filterDeleted(current, opts);
+		return current;
+	}
+	get otherMeta() {
+		return this.#field.otherMetadata();
+	}
+	get hasBeenSet() {
+		return this.#hasBeenSet;
+	}
+	toString() {
+		return `ManyToOneReference(entity: ${this.entity}, fieldName: ${this.fieldName}, otherType: ${this.otherMeta.type}, otherFieldName: ${this.otherFieldName}, id: ${this.idMaybe})`;
+	}
+	/**
+	* Removes pending-hard-delete (but not soft-deleted), unless explicitly asked for.
+	*
+	* Note that we leave soft-deleted entities b/c the call signature of a `book.author.get`
+	* very likely does not expect a soft-deleted entity to result in `undefined`.
+	*
+	* (Contrasted with `author.books.get` which is more intuitive to have soft-deleted
+	* entities filtered out, i.e. it doesn't fundamentally change the return type.)
+	*/
+	filterDeleted(entity, opts) {
+		if (entity && (!opts || !opts.withDeleted) && entity.isDeletedEntity) return;
+		return entity;
+	}
+	/** Returns the other relation that points back at us, i.e. we're `book.author_id` and this is `Author.books`. */
+	getOtherRelation(other) {
+		return other[this.otherFieldName];
+	}
+	get isCascadeDelete() {
+		return require_relations_isCascadeDelete.isCascadeDelete(this, this.fieldName);
+	}
+	/**
+	* Looks for an entity in `EntityManager`, b/c we may have it in memory even if
+	* our reference is not specifically loaded.
+	*/
+	maybeFindEntity() {
+		const current = this.current();
+		if (require_Entity.isEntity(current)) return current;
+		const { idTaggedMaybe } = this;
+		return idTaggedMaybe !== void 0 ? this.entity.em.getEntity(idTaggedMaybe) : void 0;
+	}
+	[require_relations_RelationSymbols.RelationT] = null;
+	[require_relations_RelationSymbols.RelationU] = null;
+	[require_relations_ReferenceSymbols.ReferenceN] = null;
+};
+/**
+* Fails when we can't return an `.id` for a reference, i.e. it's unset or a new entity.
+*
+* We strictly type `book.author.id` as `AuthorId`, even if `book.author` is nullable, to
+* avoid users calling `.id` and getting back `undefined`, but not because "there is no
+* author", but only because "the assigned author doesn't have an id assigned yet".
+*
+* To handle nullable references, set `.idIfSet`.
+*
+* Assumes being called like `return idMaybe ?? failNoId()`, i.e. if we're called we
+* know the id is not available.
+*/
+function failNoId(entity, fieldName, current) {
+	if (!current) require_utils.fail(`Reference ${entity}.${fieldName} is unset`);
+	if (current instanceof require_BaseEntity.BaseEntity) throw new require_index.NoIdError(`Reference ${entity}.${fieldName} is assigned to a new entity`);
+	require_utils.fail(`Unreachable`);
+}
+/**
+* Fails when we can't return an `.idIfSet` for a reference, i.e. it's a new entity.
+*
+* Assumes being called like `return idMaybe ?? failIfNewEntity()`, i.e. if we're called we
+* know the id is not available.
+*/
+function failIfNewEntity(entity, fieldName, current) {
+	if (current instanceof require_BaseEntity.BaseEntity) throw new require_index.NoIdError(`Reference ${entity}.${fieldName} is assigned to a new entity`);
+}
+var M2OUnloadedState = class M2OUnloadedState {
+	isLoaded = false;
+	#m2o;
+	constructor(m2o) {
+		this.#m2o = m2o;
+	}
+	applyLoad(loaded) {
+		return new M2OLoadedState(this.#m2o, loaded);
+	}
+	import(target) {
+		return new M2OUnloadedState(target);
+	}
+	maybeInstantLoad() {
+		const current = this.#m2o.current();
+		if (current === void 0 || require_Entity.isEntity(current)) return new M2OLoadedState(this.#m2o, current);
+		else {
+			const maybeFound = this.#m2o.entity.em.getEntity(current);
+			if (maybeFound) return new M2OLoadedState(this.#m2o, maybeFound);
+		}
+		return this;
+	}
+	doGet() {
+		throw new Error(`${this.#m2o.entity}.${this.#m2o.fieldName} was not loaded`);
+	}
+};
+/** The when loaded, with either the loaded entity or undefined. */
+var M2OLoadedState = class M2OLoadedState {
+	isLoaded = true;
+	#m2o;
+	#loaded;
+	constructor(m2o, loaded) {
+		this.#loaded = loaded;
+		this.#m2o = m2o;
+	}
+	applyLoad(loaded) {
+		return new M2OLoadedState(this.#m2o, loaded);
+	}
+	import(target, findEntity) {
+		return new M2OLoadedState(target, require_Entity.isEntity(this.#loaded) ? findEntity(this.#loaded) : void 0);
+	}
+	maybeInstantLoad() {
+		return this;
+	}
+	doGet() {
+		return this.#loaded;
+	}
+};
+//#endregion
+exports.ManyToOneReferenceImpl = ManyToOneReferenceImpl;
+exports.failIfNewEntity = failIfNewEntity;
+exports.failNoId = failNoId;
+exports.hasOne = hasOne;
+exports.isManyToOneReference = isManyToOneReference;
+
+//# sourceMappingURL=ManyToOneReference.cjs.map

package/build/relations/ManyToOneReference.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ManyToOneReference.cjs","names":["lazyField","getMetadata","AbstractRelationImpl","#field","#state","getInstanceData","isEntity","#loadPromise","sameEntity","#setImpl","toTaggedId","setField","#percolateRemove","#percolateAdd","toIdOf","maybeResolveReferenceToId","deTagId","#hasBeenSet","ensureTagged","OneToManyCollection","OneToManyLargeCollection","OneToOneReferenceImpl","getEmInternalApi","getField","isCascadeDelete","RelationT","RelationU","ReferenceN","BaseEntity","NoIdError","#m2o","#loaded"],"sources":["../../src/relations/ManyToOneReference.ts"],"sourcesContent":["import { type Entity, isEntity } from \"src/Entity.ts\";\nimport { type IdOf, type TaggedId, getEmInternalApi, sameEntity } from \"src/EntityManager.ts\";\nimport { type EntityMetadata, type ManyToOneField, getMetadata } from \"src/EntityMetadata.ts\";\nimport { getField, setField } from \"src/fields.ts\";\nimport {\n  BaseEntity,\n  NoIdError,\n  OneToManyLargeCollection,\n  OneToOneReferenceImpl,\n  type Reference,\n  deTagId,\n  ensureNotDeleted,\n  ensureTagged,\n  fail,\n  getInstanceData,\n  maybeResolveReferenceToId,\n  toIdOf,\n  toTaggedId,\n} from \"src/index.ts\";\nimport { lazyField } from \"src/newEntity.ts\";\nimport { AbstractRelationImpl } from \"src/relations/AbstractRelationImpl.ts\";\nimport { isCascadeDelete } from \"src/relations/isCascadeDelete.ts\";\nimport { OneToManyCollection } from \"src/relations/OneToManyCollection.ts\";\nimport { ReferenceN } from \"src/relations/ReferenceSymbols.ts\";\nimport { RelationT, RelationU } from \"src/relations/RelationSymbols.ts\";\nimport { maybeAdd, maybeRemove } from \"src/utils.ts\";\n\n/** An alias for creating `ManyToOneReference`s. */\nexport function hasOne<T extends Entity, U extends Entity, N extends never | undefined>(): ManyToOneReference<T, U, N> {\n  return lazyField((entity: T, fieldName) => {\n    const m2o = getMetadata(entity).allFields[fieldName] as ManyToOneField;\n    return new ManyToOneReferenceImpl<T, U, N>(entity, m2o);\n  });\n}\n\n/** Type guard utility for determining if an entity field is a ManyToOneReference. */\nexport function isManyToOneReference(maybeReference: any): maybeReference is ManyToOneReference<any, any, any> {\n  return maybeReference instanceof ManyToOneReferenceImpl;\n}\n\nexport interface ManyToOneReference<T extends Entity, U extends Entity, N extends never | undefined> extends Reference<\n  T,\n  U,\n  N\n> {\n  /** Returns the id of the current assigned entity, or a runtime error if either 1) unset or 2) set to a new entity that doesn't have an `id` yet. */\n  id: IdOf<U>;\n\n  /** Returns the id of the current assigned entity, undefined if unset, or a runtime error if set to a new entity. */\n  idIfSet: IdOf<U> | undefined;\n\n  /** Returns the id of the current assigned entity, undefined if unset, or undefined if set to a new entity. */\n  idMaybe: IdOf<U> | undefined;\n\n  idUntagged: string;\n\n  idUntaggedIfSet: string | undefined;\n\n  /** Returns `true` if this relation is currently set (i.e. regardless of whether it's loaded, or if it is set but the assigned entity doesn't have an id saved. */\n  readonly isSet: boolean;\n}\n\n/**\n * Manages a foreign key from one entity to another, i.e. `Book.author --> Author`.\n *\n * We keep the current `author` / `author_id` value in the `__orm.data` hash, where the\n * current value could be either the (string) author id from the database, or an entity\n * `Author` that the user has set.\n *\n * Note that if our `images.author_id` column is unique, this `ManyToOneReference` will essentially\n * be half of a one-to-one relationship, but we'll keep using this `ManyToOneReference` on the \"many\"\n * side, and the other side, i.e. `Author.image` will use a `OneToOneReference` to point back to us.\n */\nexport class ManyToOneReferenceImpl<T extends Entity, U extends Entity, N extends never | undefined>\n  extends AbstractRelationImpl<T, U>\n  implements ManyToOneReference<T, U, N>\n{\n  readonly #field: ManyToOneField;\n  #state: M2OState<U, N>;\n  #loadPromise: Promise<void> | undefined;\n  #hasBeenSet = false;\n\n  constructor(entity: T, field: ManyToOneField) {\n    super(entity);\n    this.#field = field;\n    this.#state = getInstanceData(entity).isOrWasNew\n      ? new M2OLoadedState<U, N>(this, undefined)\n      : new M2OUnloadedState<U, N>(this);\n  }\n\n  async load(opts: { withDeleted?: boolean; forceReload?: boolean } = {}): Promise<U | N> {\n    ensureNotDeleted(this.entity, \"pending\");\n    this.#state = this.#state.maybeInstantLoad();\n    if (!this.#state.isLoaded || opts.forceReload) {\n      const current = this.current();\n      if (isEntity(current) || current === undefined) {\n        this.#state = new M2OLoadedState<U, N>(this, current as U | N | undefined);\n      } else {\n        await (this.#loadPromise ??= this.entity.em.load(this.otherMeta.cstr, current).then((entity) => {\n          this.#loadPromise = undefined;\n          // In extremely rare cases, someone might have called `set` while this promise was in-flight,\n          // so make sure our current value is still the same as the fetched entity.\n          if (sameEntity(entity, this.current())) {\n            this.#state = this.#state.applyLoad(entity);\n          }\n        }));\n      }\n    }\n    return this.filterDeleted(this.#state.doGet() as U | N, opts);\n  }\n\n  set(other: U | N): void {\n    this.#setImpl(other);\n  }\n\n  get isSet(): boolean {\n    return this.current() !== undefined;\n  }\n\n  get isLoaded(): boolean {\n    // Even if `.load()` has not been called, `.get` will detect\n    this.#state = this.#state.maybeInstantLoad();\n    return this.#state.isLoaded;\n  }\n\n  get isPreloaded(): boolean {\n    return !!this.maybeFindEntity();\n  }\n\n  preload(): void {\n    this.#state = new M2OLoadedState<U, N>(this, this.maybeFindEntity());\n  }\n\n  private unload(): void {\n    this.#state = new M2OUnloadedState<U, N>(this);\n    this.#loadPromise = undefined;\n  }\n\n  /** Copy another em's `source` relation into our state. */\n  import(source: ManyToOneReferenceImpl<T, U, N>, findEntity: (e: U) => U): void {\n    this.#state = source.#state.import(this, findEntity);\n  }\n\n  private doGet(opts?: { withDeleted?: boolean }): U | N {\n    ensureNotDeleted(this.entity, \"pending\");\n    this.#state = this.#state.maybeInstantLoad();\n    return this.filterDeleted(this.#state.doGet() as U | N, opts);\n  }\n\n  get getWithDeleted(): U | N {\n    return this.doGet({ withDeleted: true });\n  }\n\n  get get(): U | N {\n    return this.doGet({ withDeleted: false });\n  }\n\n  /** Returns the id of the current value. */\n  get id(): IdOf<U> {\n    return this.idMaybe || failNoId(this.entity, this.fieldName, this.current());\n  }\n\n  /** Sets the m2o to `id`, and allows accepting `undefined` (`N`) if this is a nullable relation. */\n  set id(id: IdOf<U> | N) {\n    ensureNotDeleted(this.entity, \"pending\");\n    const newId = toTaggedId(this.otherMeta, id);\n\n    const previousId = this.idTaggedMaybe;\n    const previous = this.maybeFindEntity();\n    const changed = setField(this.entity, this.fieldName, id);\n    if (!changed) {\n      return;\n    }\n\n    const loaded = newId ? (this.entity.em.getEntity(newId) as U) : undefined;\n    this.#state = loaded ? new M2OLoadedState<U, N>(this, loaded) : new M2OUnloadedState<U, N>(this);\n    this.#loadPromise = undefined;\n    this.#percolateRemove(previousId, previous);\n    this.#percolateAdd();\n  }\n\n  get idIfSet(): IdOf<U> | N | undefined {\n    return this.idMaybe || failIfNewEntity(this.entity, this.fieldName, this.current());\n  }\n\n  get idUntagged(): string {\n    return this.idUntaggedMaybe || failNoId(this.entity, this.fieldName, this.current());\n  }\n\n  get idUntaggedIfSet(): string | undefined {\n    return this.idUntaggedMaybe || failIfNewEntity(this.entity, this.fieldName, this.current());\n  }\n\n  get idMaybe(): IdOf<U> | N | undefined {\n    ensureNotDeleted(this.entity, \"pending\");\n    return toIdOf(this.otherMeta, this.idTaggedMaybe);\n  }\n\n  /** Returns the tagged id of the current value, or undefined if unset or a new entity. */\n  get idTaggedMaybe(): TaggedId | undefined {\n    // Skip the deleted check so that `isPreloaded` doesn't blow up during em.refreshes/populates\n    // ensureNotDeleted(this.entity, \"pending\");\n    return maybeResolveReferenceToId(this.current());\n  }\n\n  get fieldName(): string {\n    return this.#field.fieldName;\n  }\n\n  get otherFieldName(): keyof U & string {\n    return this.#field.otherFieldName as keyof U & string;\n  }\n\n  private get idUntaggedMaybe(): string | undefined {\n    return deTagId(this.otherMeta, this.idMaybe);\n  }\n\n  #setImpl(_other: U | IdOf<U> | N): void {\n    ensureNotDeleted(this.entity, \"pending\");\n    this.#hasBeenSet = true;\n\n    // If the project is not using tagged ids, we still want it tagged internally\n    const other = ensureTagged(this.otherMeta, _other);\n    if (sameEntity(other, this.current({ withDeleted: true }))) {\n      return;\n    }\n\n    const previousId = this.idTaggedMaybe;\n    const previous = this.maybeFindEntity();\n    // Prefer to keep the id in our data hash, but if this is a new entity w/o an id, use the entity itself\n    setField(this.entity, this.fieldName, isEntity(other) ? (other?.idTaggedMaybe ?? other) : other);\n\n    // Setting to an entity | undefined => loaded, setting to an id might reverse to unloaded\n    const maybeEntity = isEntity(other) ? (other as U) : other ? this.entity.em.getEntity(other) : undefined;\n    if (maybeEntity || other === undefined) {\n      this.#state = new M2OLoadedState<U, N>(this, (maybeEntity ?? other) as U | N);\n    } else {\n      this.#state = new M2OUnloadedState<U, N>(this);\n    }\n    this.#loadPromise = undefined;\n    this.#percolateRemove(previousId, previous);\n    this.#percolateAdd();\n  }\n\n  // private impl\n\n  setFromOpts(other: U | IdOf<U> | N): void {\n    this.#setImpl(other);\n  }\n\n  maybeCascadeDelete(): void {\n    if (this.isCascadeDelete) {\n      const current = this.current({ withDeleted: true });\n      if (current !== undefined) {\n        if (typeof current === \"string\") {\n          // We're invoked twice, once sync on em.delete, and again in em.flush when we're loaded;\n          // but even when loaded, current might still be the tagged id, but we can find the entity in the EM\n          const other = this.entity.em.getEntity(current);\n          if (other) this.entity.em.delete(other as U);\n        } else {\n          this.entity.em.delete(current as U);\n        }\n      }\n    }\n  }\n\n  async cleanupOnEntityDeleted(): Promise<void> {\n    // if we are going to delete this relation as well, then we don't need to clean it up\n    if (this.isCascadeDelete) return;\n    const current = await this.load({ withDeleted: true });\n    if (current !== undefined) {\n      const o2m = this.getOtherRelation(current);\n      if (o2m instanceof OneToManyCollection) {\n        o2m.remove(this.entity, { requireLoaded: false });\n      } else if (o2m instanceof OneToManyLargeCollection) {\n        o2m.remove(this.entity);\n      } else if (o2m instanceof OneToOneReferenceImpl) {\n        o2m.set(undefined as any);\n      } else {\n        throw new Error(`Unhandled ${o2m}`);\n      }\n    }\n    setField(this.entity, this.fieldName, undefined);\n    this.#state = new M2OLoadedState<U, N>(this, undefined as any);\n  }\n\n  // Called on `book.author.set(...)` with our previous value, to percolate a `author.books.remove`. */\n  #percolateRemove(prevId: string | undefined, prevEntity: U | undefined) {\n    if (prevEntity) {\n      const prevRelation = this.getOtherRelation(prevEntity);\n      if (prevRelation instanceof OneToManyCollection) {\n        prevRelation.removeIfLoaded(this.entity);\n      } else if (prevRelation instanceof OneToManyLargeCollection) {\n        prevRelation.remove(this.entity);\n      } else {\n        prevRelation.set(undefined as any, { percolating: true });\n      }\n    } else if (prevId) {\n      // prevEntity is not loaded in memory, but cache it in case our other side is later loaded\n      const { em } = this.entity;\n      let map = getEmInternalApi(em).pendingPercolate.get(prevId);\n      if (!map) {\n        map = new Map();\n        getEmInternalApi(em).pendingPercolate.set(prevId, map);\n      }\n      let pending = map.get(this.otherFieldName);\n      if (!pending) {\n        pending = { adds: [], removes: [] };\n        map.set(this.otherFieldName, pending);\n      }\n      maybeAdd(pending.removes, this.entity);\n      maybeRemove(pending.adds, this.entity);\n    }\n  }\n\n  #percolateAdd() {\n    const id = this.current();\n    const other = this.maybeFindEntity();\n    if (other) {\n      // Other is already loaded in memory, immediately hook it up\n      const newRelation = this.getOtherRelation(other);\n      if (newRelation instanceof OneToManyCollection) {\n        newRelation.add(this.entity);\n      } else if (newRelation instanceof OneToManyLargeCollection) {\n        newRelation.add(this.entity);\n      } else if (newRelation) {\n        newRelation.set(this.entity, { percolating: true });\n      } else {\n        // Something is wrong, we should always have a relation, but instead\n        // of blowing up here, let this finish b/c it will probably turn into\n        // a validation error.\n      }\n    } else if (typeof id === \"string\") {\n      // Other is not loaded in memory, but cache it in case our other side is later loaded\n      const { em } = this.entity;\n      let map = getEmInternalApi(em).pendingPercolate.get(id);\n      if (!map) {\n        map = new Map();\n        getEmInternalApi(em).pendingPercolate.set(id, map);\n      }\n      let pending = map.get(this.otherFieldName);\n      if (!pending) {\n        pending = { adds: [], removes: [] };\n        map.set(this.otherFieldName, pending);\n      }\n      maybeAdd(pending.adds, this.entity);\n      maybeRemove(pending.removes, this.entity);\n    }\n  }\n\n  // We need to keep U in data[fieldName] to handle entities without an id assigned yet.\n  current(opts?: { withDeleted?: boolean }): U | TaggedId | N {\n    const current = getField(this.entity, this.fieldName);\n    if (current !== undefined && isEntity(current)) {\n      return this.filterDeleted(current as U, opts);\n    }\n    return current;\n  }\n\n  get otherMeta(): EntityMetadata<U> {\n    return this.#field.otherMetadata();\n  }\n\n  get hasBeenSet(): boolean {\n    return this.#hasBeenSet;\n  }\n\n  public toString(): string {\n    return `ManyToOneReference(entity: ${this.entity}, fieldName: ${this.fieldName}, otherType: ${this.otherMeta.type}, otherFieldName: ${this.otherFieldName}, id: ${this.idMaybe})`;\n  }\n\n  /**\n   * Removes pending-hard-delete (but not soft-deleted), unless explicitly asked for.\n   *\n   * Note that we leave soft-deleted entities b/c the call signature of a `book.author.get`\n   * very likely does not expect a soft-deleted entity to result in `undefined`.\n   *\n   * (Contrasted with `author.books.get` which is more intuitive to have soft-deleted\n   * entities filtered out, i.e. it doesn't fundamentally change the return type.)\n   */\n  private filterDeleted(entity: U | N, opts?: { withDeleted?: boolean }): U | N {\n    if (entity && (!opts || !opts.withDeleted) && entity.isDeletedEntity) {\n      return undefined!;\n    }\n    return entity;\n  }\n\n  /** Returns the other relation that points back at us, i.e. we're `book.author_id` and this is `Author.books`. */\n  private getOtherRelation(\n    other: U,\n  ): OneToManyCollection<U, T> | OneToOneReferenceImpl<U, T> | OneToManyLargeCollection<U, T> {\n    return (other as U)[this.otherFieldName] as any;\n  }\n\n  private get isCascadeDelete(): boolean {\n    return isCascadeDelete(this, this.fieldName);\n  }\n\n  /**\n   * Looks for an entity in `EntityManager`, b/c we may have it in memory even if\n   * our reference is not specifically loaded.\n   */\n  maybeFindEntity(): U | undefined {\n    // Check current() first b/c a new entity won't have an id yet\n    const current = this.current();\n    if (isEntity(current)) return current as U;\n    const { idTaggedMaybe } = this;\n    return idTaggedMaybe !== undefined ? (this.entity.em.getEntity(idTaggedMaybe) as U) : undefined;\n  }\n\n  [RelationT]: T = null!;\n  [RelationU]: U = null!;\n  [ReferenceN]: N = null!;\n}\n\n/**\n * Fails when we can't return an `.id` for a reference, i.e. it's unset or a new entity.\n *\n * We strictly type `book.author.id` as `AuthorId`, even if `book.author` is nullable, to\n * avoid users calling `.id` and getting back `undefined`, but not because \"there is no\n * author\", but only because \"the assigned author doesn't have an id assigned yet\".\n *\n * To handle nullable references, set `.idIfSet`.\n *\n * Assumes being called like `return idMaybe ?? failNoId()`, i.e. if we're called we\n * know the id is not available.\n */\nexport function failNoId(entity: Entity, fieldName: string, current: string | Entity | undefined): never {\n  if (!current) fail(`Reference ${entity}.${fieldName} is unset`);\n  // Throw NoIdError, which lets ReactionsManager will handle reactive fields gracefully\n  if (current instanceof BaseEntity)\n    throw new NoIdError(`Reference ${entity}.${fieldName} is assigned to a new entity`);\n  fail(`Unreachable`);\n}\n\n/**\n * Fails when we can't return an `.idIfSet` for a reference, i.e. it's a new entity.\n *\n * Assumes being called like `return idMaybe ?? failIfNewEntity()`, i.e. if we're called we\n * know the id is not available.\n */\nexport function failIfNewEntity(entity: Entity, fieldName: string, current: string | Entity | undefined): undefined {\n  if (current instanceof BaseEntity) {\n    throw new NoIdError(`Reference ${entity}.${fieldName} is assigned to a new entity`);\n  }\n  // Since this is a `.idIfSet`, having no `current` is fine, return undefined.\n  return undefined;\n}\n\ninterface M2OState<U extends Entity, N extends never | undefined> {\n  readonly isLoaded: boolean;\n  maybeInstantLoad(): M2OState<U, N>;\n  applyLoad(loaded: U | N | undefined): M2OLoadedState<U, N>;\n  import(target: ManyToOneReferenceImpl<any, any, any>, findEntity: (e: U) => U): M2OState<U, N>;\n  doGet(): U | N | undefined;\n}\n\nclass M2OUnloadedState<U extends Entity, N extends never | undefined> implements M2OState<U, N> {\n  readonly isLoaded = false;\n  #m2o: ManyToOneReferenceImpl<any, any, any>;\n  constructor(m2o: ManyToOneReferenceImpl<any, any, any>) {\n    this.#m2o = m2o;\n  }\n  applyLoad(loaded: U | N | undefined): M2OLoadedState<U, N> {\n    return new M2OLoadedState<U, N>(this.#m2o, loaded);\n  }\n  import(target: ManyToOneReferenceImpl<any, any, any>): M2OState<U, N> {\n    return new M2OUnloadedState<U, N>(target);\n  }\n  maybeInstantLoad(): M2OState<U, N> {\n    const current = this.#m2o.current();\n    if (current === undefined || isEntity(current)) {\n      return new M2OLoadedState<U, N>(this.#m2o, current as U | undefined);\n    } else {\n      const maybeFound = this.#m2o.entity.em.getEntity(current);\n      if (maybeFound) {\n        return new M2OLoadedState<U, N>(this.#m2o, maybeFound as U);\n      }\n    }\n    return this;\n  }\n  doGet(): U | N | undefined {\n    throw new Error(`${this.#m2o.entity}.${this.#m2o.fieldName} was not loaded`);\n  }\n}\n\n/** The when loaded, with either the loaded entity or undefined. */\nclass M2OLoadedState<U extends Entity, N extends never | undefined> implements M2OState<U, N> {\n  readonly isLoaded = true;\n  #m2o: ManyToOneReferenceImpl<any, any, any>;\n  #loaded: U | N | undefined;\n  constructor(m2o: ManyToOneReferenceImpl<any, any, any>, loaded: U | N | undefined) {\n    this.#loaded = loaded;\n    this.#m2o = m2o;\n  }\n  applyLoad(loaded: U | N | undefined): M2OLoadedState<U, N> {\n    return new M2OLoadedState<U, N>(this.#m2o, loaded);\n  }\n  import(target: ManyToOneReferenceImpl<any, any, any>, findEntity: (e: U) => U): M2OState<U, N> {\n    return new M2OLoadedState<U, N>(target, isEntity(this.#loaded) ? findEntity(this.#loaded) : undefined);\n  }\n  maybeInstantLoad(): M2OState<U, N> {\n    return this;\n  }\n  doGet(): U | N | undefined {\n    return this.#loaded;\n  }\n}\n"],"mappings":"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"}

package/build/relations/ManyToOneReference.d.cts

@@ -0,0 +1,121 @@
+import { AbstractRelationImpl } from "./AbstractRelationImpl.cjs";
+import { RelationT, RelationU } from "./RelationSymbols.cjs";
+import { ReferenceN } from "./ReferenceSymbols.cjs";
+import { Reference } from "./Reference.cjs";
+import { EntityMetadata, ManyToOneField } from "../EntityMetadata.cjs";
+import "../index.cjs";
+import { IdOf, TaggedId } from "../EntityManager.cjs";
+import { Entity } from "../Entity.cjs";
+//#region src/relations/ManyToOneReference.d.ts
+/** An alias for creating `ManyToOneReference`s. */
+declare function hasOne<T extends Entity, U extends Entity, N extends never | undefined>(): ManyToOneReference<T, U, N>;
+/** Type guard utility for determining if an entity field is a ManyToOneReference. */
+declare function isManyToOneReference(maybeReference: any): maybeReference is ManyToOneReference<any, any, any>;
+interface ManyToOneReference<T extends Entity, U extends Entity, N extends never | undefined> extends Reference<T, U, N> {
+  /** Returns the id of the current assigned entity, or a runtime error if either 1) unset or 2) set to a new entity that doesn't have an `id` yet. */
+  id: IdOf<U>;
+  /** Returns the id of the current assigned entity, undefined if unset, or a runtime error if set to a new entity. */
+  idIfSet: IdOf<U> | undefined;
+  /** Returns the id of the current assigned entity, undefined if unset, or undefined if set to a new entity. */
+  idMaybe: IdOf<U> | undefined;
+  idUntagged: string;
+  idUntaggedIfSet: string | undefined;
+  /** Returns `true` if this relation is currently set (i.e. regardless of whether it's loaded, or if it is set but the assigned entity doesn't have an id saved. */
+  readonly isSet: boolean;
+}
+/**
+ * Manages a foreign key from one entity to another, i.e. `Book.author --> Author`.
+ *
+ * We keep the current `author` / `author_id` value in the `__orm.data` hash, where the
+ * current value could be either the (string) author id from the database, or an entity
+ * `Author` that the user has set.
+ *
+ * Note that if our `images.author_id` column is unique, this `ManyToOneReference` will essentially
+ * be half of a one-to-one relationship, but we'll keep using this `ManyToOneReference` on the "many"
+ * side, and the other side, i.e. `Author.image` will use a `OneToOneReference` to point back to us.
+ */
+declare class ManyToOneReferenceImpl<T extends Entity, U extends Entity, N extends never | undefined> extends AbstractRelationImpl<T, U> implements ManyToOneReference<T, U, N> {
+  #private;
+  constructor(entity: T, field: ManyToOneField);
+  load(opts?: {
+    withDeleted?: boolean;
+    forceReload?: boolean;
+  }): Promise<U | N>;
+  set(other: U | N): void;
+  get isSet(): boolean;
+  get isLoaded(): boolean;
+  get isPreloaded(): boolean;
+  preload(): void;
+  private unload;
+  /** Copy another em's `source` relation into our state. */
+  import(source: ManyToOneReferenceImpl<T, U, N>, findEntity: (e: U) => U): void;
+  private doGet;
+  get getWithDeleted(): U | N;
+  get get(): U | N;
+  /** Returns the id of the current value. */
+  get id(): IdOf<U>;
+  /** Sets the m2o to `id`, and allows accepting `undefined` (`N`) if this is a nullable relation. */
+  set id(id: IdOf<U> | N);
+  get idIfSet(): IdOf<U> | N | undefined;
+  get idUntagged(): string;
+  get idUntaggedIfSet(): string | undefined;
+  get idMaybe(): IdOf<U> | N | undefined;
+  /** Returns the tagged id of the current value, or undefined if unset or a new entity. */
+  get idTaggedMaybe(): TaggedId | undefined;
+  get fieldName(): string;
+  get otherFieldName(): keyof U & string;
+  private get idUntaggedMaybe();
+  setFromOpts(other: U | IdOf<U> | N): void;
+  maybeCascadeDelete(): void;
+  cleanupOnEntityDeleted(): Promise<void>;
+  current(opts?: {
+    withDeleted?: boolean;
+  }): U | TaggedId | N;
+  get otherMeta(): EntityMetadata<U>;
+  get hasBeenSet(): boolean;
+  toString(): string;
+  /**
+   * Removes pending-hard-delete (but not soft-deleted), unless explicitly asked for.
+   *
+   * Note that we leave soft-deleted entities b/c the call signature of a `book.author.get`
+   * very likely does not expect a soft-deleted entity to result in `undefined`.
+   *
+   * (Contrasted with `author.books.get` which is more intuitive to have soft-deleted
+   * entities filtered out, i.e. it doesn't fundamentally change the return type.)
+   */
+  private filterDeleted;
+  /** Returns the other relation that points back at us, i.e. we're `book.author_id` and this is `Author.books`. */
+  private getOtherRelation;
+  private get isCascadeDelete();
+  /**
+   * Looks for an entity in `EntityManager`, b/c we may have it in memory even if
+   * our reference is not specifically loaded.
+   */
+  maybeFindEntity(): U | undefined;
+  [RelationT]: T;
+  [RelationU]: U;
+  [ReferenceN]: N;
+}
+/**
+ * Fails when we can't return an `.id` for a reference, i.e. it's unset or a new entity.
+ *
+ * We strictly type `book.author.id` as `AuthorId`, even if `book.author` is nullable, to
+ * avoid users calling `.id` and getting back `undefined`, but not because "there is no
+ * author", but only because "the assigned author doesn't have an id assigned yet".
+ *
+ * To handle nullable references, set `.idIfSet`.
+ *
+ * Assumes being called like `return idMaybe ?? failNoId()`, i.e. if we're called we
+ * know the id is not available.
+ */
+declare function failNoId(entity: Entity, fieldName: string, current: string | Entity | undefined): never;
+/**
+ * Fails when we can't return an `.idIfSet` for a reference, i.e. it's a new entity.
+ *
+ * Assumes being called like `return idMaybe ?? failIfNewEntity()`, i.e. if we're called we
+ * know the id is not available.
+ */
+declare function failIfNewEntity(entity: Entity, fieldName: string, current: string | Entity | undefined): undefined;
+//#endregion
+export { ManyToOneReference, ManyToOneReferenceImpl, failIfNewEntity, failNoId, hasOne, isManyToOneReference };
+//# sourceMappingURL=ManyToOneReference.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ManyToOneReference.d.cts","names":[],"sources":["../../src/relations/ManyToOneReference.ts"],"mappings":";;;;;;;;;;iBA4BgB,OAAO,UAAU,QAAQ,UAAU,QAAQ,gCAAgC,mBAAmB,GAAG,GAAG;;iBAQpG,qBAAqB,sBAAsB,kBAAkB;UAI5D,mBAAmB,UAAU,QAAQ,UAAU,QAAQ,qCAAqC,UAC3G,GACA,GACA;;EAGA,IAAI,KAAK;;EAGT,SAAS,KAAK;;EAGd,SAAS,KAAK;EAEd;EAEA;;WAGS;;;;;;;;;;;;;cAcE,uBAAuB,UAAU,QAAQ,UAAU,QAAQ,qCAC9D,qBAAqB,GAAG,cACrB,mBAAmB,GAAG,GAAG;;EAOpC,YAAY,QAAQ,GAAG,OAAO;EAQxB,KAAK;IAAQ;IAAuB;MAA+B,QAAQ,IAAI;EAqBrF,IAAI,OAAO,IAAI;MAIX;MAIA;MAMA;EAIJ;UAIQ;;EAMR,OAAO,QAAQ,uBAAuB,GAAG,GAAG,IAAI,aAAa,GAAG,MAAM;UAI9D;MAMJ,kBAAkB,IAAI;MAItB,OAAO,IAAI;;MAKX,MAAM,KAAK;;MAKX,GAAG,IAAI,KAAK,KAAK;MAkBjB,WAAW,KAAK,KAAK;MAIrB;MAIA;MAIA,WAAW,KAAK,KAAK;;MAMrB,iBAAiB;MAMjB;MAIA,wBAAwB;cAIhB;EAiCZ,YAAY,OAAO,IAAI,KAAK,KAAK;EAIjC;EAgBM,0BAA0B;EAqFhC,QAAQ;IAAS;MAA0B,IAAI,WAAW;MAQtD,aAAa,eAAe;MAI5B;EAIG;;;;;;;;;;UAaC;;UAQA;cAMI;;;;;EAQZ,mBAAmB;GAQlB,YAAY;GACZ,YAAY;GACZ,aAAa;;;;;;;;;;;;;;iBAeA,SAAS,QAAQ,QAAQ,mBAAmB,kBAAkB;;;;;;;iBAc9D,gBAAgB,QAAQ,QAAQ,mBAAmB,kBAAkB"}