joist-core 2.3.0 → 2.4.0-next.2

package/build/EntityManager.cjs

@@ -0,0 +1,1935 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_runtime = require("./_virtual/_rolldown/runtime.cjs");
+const require_batchloaders_BatchLoader = require("./batchloaders/BatchLoader.cjs");
+require("./relations/Collection.cjs");
+const require_relations_CustomCollection = require("./relations/CustomCollection.cjs");
+const require_relations_CustomReference = require("./relations/CustomReference.cjs");
+const require_normalizeHints = require("./normalizeHints.cjs");
+require("./batchloaders/recursiveChildrenBatchLoader.cjs");
+require("./batchloaders/recursiveM2mBatchLoader.cjs");
+require("./batchloaders/recursiveParentsBatchLoader.cjs");
+const require_relations_RecursiveCycleError = require("./relations/RecursiveCycleError.cjs");
+require("./relations/RecursiveCollection.cjs");
+const require_reactivity_reactiveHints = require("./reactivity/reactiveHints.cjs");
+const require_loading_loadHints = require("./loading/loadHints.cjs");
+const require_relations_hasAsyncMethod = require("./relations/hasAsyncMethod.cjs");
+const require_relations_AsyncProperty = require("./relations/AsyncProperty.cjs");
+const require_fields = require("./fields.cjs");
+const require_keys = require("./keys.cjs");
+const require_RowData = require("./RowData.cjs");
+const require_relations_LazyField = require("./relations/LazyField.cjs");
+const require_relations_Reference = require("./relations/Reference.cjs");
+require("./batchloaders/manyToManyBatchLoader.cjs");
+require("./batchloaders/oneToManyBatchLoader.cjs");
+const require_queries_find_scopes = require("./queries/find/scopes.cjs");
+const require_relations_OneToManyCollection = require("./relations/OneToManyCollection.cjs");
+const require_relations_ManyToOneReference = require("./relations/ManyToOneReference.cjs");
+require("./batchloaders/oneToOneBatchLoader.cjs");
+const require_relations_ReactiveReference = require("./relations/ReactiveReference.cjs");
+const require_relations_OneToOneReference = require("./relations/OneToOneReference.cjs");
+const require_relations_PolymorphicReference = require("./relations/PolymorphicReference.cjs");
+require("./relations/index.cjs");
+const require_utils = require("./utils.cjs");
+const require_newEntity = require("./newEntity.cjs");
+require("./typeMap.cjs");
+const require_rules = require("./rules.cjs");
+const require_configure = require("./configure.cjs");
+const require_config = require("./config.cjs");
+const require_EntityMetadata = require("./EntityMetadata.cjs");
+const require_trusted = require("./trusted.cjs");
+const require_defaults = require("./defaults.cjs");
+require("./dataloaders/lensDataLoader.cjs");
+const require_loading_loadLens = require("./loading/loadLens.cjs");
+require("./logging/FactoryLogger.cjs");
+const require_newTestInstance = require("./newTestInstance.cjs");
+const require_queries_find_EntityFilter = require("./queries/find/EntityFilter.cjs");
+const require_flush_JoinRows = require("./flush/JoinRows.cjs");
+const require_PluginManager = require("./PluginManager.cjs");
+const require_queries_find_QueryParser_collectionJoins = require("./queries/find/QueryParser.collectionJoins.cjs");
+const require_flush_Todo = require("./flush/Todo.cjs");
+const require_dataloaders_findDataLoader = require("./dataloaders/findDataLoader.cjs");
+require("./drivers/index.cjs");
+const require_logging_FieldLogger = require("./logging/FieldLogger.cjs");
+const require_logging_ReactionLogger = require("./logging/ReactionLogger.cjs");
+require("./plugins/PreloadPlugin.cjs");
+const require_queries_sql_query = require("./queries/sql/query.cjs");
+const require_upsert = require("./upsert.cjs");
+const require_index = require("./index.cjs");
+require("./batchloaders/enumCollectionBatchLoader.cjs");
+const require_batchloaders_loadBatchLoader = require("./batchloaders/loadBatchLoader.cjs");
+const require_batchloaders_populateBatchLoader = require("./batchloaders/populateBatchLoader.cjs");
+const require_dataloaders_findByUniqueDataLoader = require("./dataloaders/findByUniqueDataLoader.cjs");
+const require_dataloaders_findCountDataLoader = require("./dataloaders/findCountDataLoader.cjs");
+const require_dataloaders_findIdsDataLoader = require("./dataloaders/findIdsDataLoader.cjs");
+const require_dataloaders_findOrCreateDataLoader = require("./dataloaders/findOrCreateDataLoader.cjs");
+const require_dataloaders_findPaginatedDataLoader = require("./dataloaders/findPaginatedDataLoader.cjs");
+const require_flush_FlushLock = require("./flush/FlushLock.cjs");
+const require_IndexManager = require("./IndexManager.cjs");
+const require_loading_IsLoadedCache = require("./loading/IsLoadedCache.cjs");
+const require_queries_sql_execute = require("./queries/sql/execute.cjs");
+const require_reactivity_ReactionsManager = require("./reactivity/ReactionsManager.cjs");
+const require_Entity = require("./Entity.cjs");
+const require_BaseEntity = require("./BaseEntity.cjs");
+let dataloader = require("dataloader");
+dataloader = require_runtime.__toESM(dataloader, 1);
+//#region src/EntityManager.ts
+Symbol.asyncDispose ??= Symbol("Symbol.asyncDispose");
+function isId(value) {
+	return value && typeof value === "string";
+}
+/**
+* The EntityManager is the primary way nearly all code, i.e. anything that finds/creates/updates/deletes entities,
+* will interact with the database.
+*
+* It acts both an Identity Cache (preventing loading the same row twice into memory as separate entities, and then
+* having drift between the two instances) and as a Unit of Work (tracking all changes to entities and then batch
+* flushing only the entities that have changed).
+*
+* Note that the type parameters (C, I, and Entity) will be filled in by codegen with the values specific to your
+* application, so you can import your app-specific EntityManager like:
+*
+* ```ts
+* import { EntityManager } from "src/entities";
+* ```
+*
+* @param C The type of your application-specific app-wide/request-wide Context object that will be passed to hooks
+* @typeParam C - the application-specific context (typically the request-level context)
+* @typeParam Entity - the application's based entity type (i.e. with number ids or string ids)
+* @typeParamTX - the application's Transaction type, i.e. `Knex`
+*/
+var EntityManager = class EntityManager {
+	ctx;
+	driver;
+	/** When we're flushing, the connection/transaction. */
+	txn;
+	entityLimit = defaultEntityLimit;
+	#entitiesArray = [];
+	#maybePendingFlushEntities = /* @__PURE__ */ new Set();
+	#entitiesById = /* @__PURE__ */ new Map();
+	#entitiesByTag = /* @__PURE__ */ new Map();
+	#indexManager = new require_IndexManager.IndexManager();
+	#isValidating = false;
+	#findRestricted = false;
+	#pendingPercolate = /* @__PURE__ */ new Map();
+	#preloadedRelations = /* @__PURE__ */ new Map();
+	/**
+	* Tracks cascade deletes.
+	*
+	* We originally used a beforeDelete lifecycle hook to implement this, but tracking this
+	* individually allows us to a) recursively cascade deletes even during the 1st iteration
+	* of our `flush` loop, and b) cascade deletions before we recalc fields & run user hooks,
+	* so that both see the most accurate state.
+	*/
+	#pendingDeletes = [];
+	#hasAnyDeletes = false;
+	#dataloaders = {};
+	#batchLoaders = {};
+	#joinRows = {};
+	/** Stores any `source -> downstream` reactions to recalc during `em.flush`. */
+	#rm = new require_reactivity_ReactionsManager.ReactionsManager(this);
+	/** Ensures our `em.flush` method is not interrupted. */
+	#fl = new require_flush_FlushLock.FlushLock();
+	#hooks = {
+		beforeBegin: [],
+		afterBegin: [],
+		beforeCommit: [],
+		afterCommit: []
+	};
+	#preloader;
+	#fieldLogger = require_logging_FieldLogger.noopFieldLogger;
+	#isLoadedCache = new require_loading_IsLoadedCache.IsLoadedCache();
+	#merging;
+	/** Track `a#1`, `a#2`, etc indexes for `em.create`-d entities. */
+	#createCounter = void 0;
+	__api;
+	#isRefreshing = false;
+	mode = "writes";
+	constructor(ctx, driverOrOpts) {
+		const opts = driverOrOpts.constructor === Object ? driverOrOpts : { driver: driverOrOpts };
+		this.ctx = ctx;
+		this.driver = opts.driver ?? opts.em.driver;
+		this.#preloader = opts.preloadPlugin ?? (opts.em ? opts.em.#preloader : this.driver.defaultPlugins.preloadPlugin);
+		const pluginManager = new require_PluginManager.PluginManager(this);
+		if (opts.em) {
+			this.#hooks = {
+				beforeBegin: [...opts.em.#hooks.beforeBegin],
+				afterBegin: [...opts.em.#hooks.afterBegin],
+				beforeCommit: [...opts.em.#hooks.beforeCommit],
+				afterCommit: [...opts.em.#hooks.afterCommit]
+			};
+			opts.em.__api.pluginManager.cloneTo(pluginManager);
+		}
+		const em = this;
+		this.__api = {
+			preloader: this.#preloader,
+			pendingPercolate: this.#pendingPercolate,
+			mutatedCollections: /* @__PURE__ */ new Set(),
+			pendingLoads: /* @__PURE__ */ new Set(),
+			hooks: this.#hooks,
+			rm: this.#rm,
+			indexManager: this.#indexManager,
+			isLoadedCache: this.#isLoadedCache,
+			pluginManager,
+			markMaybePending(entity) {
+				em.#maybePendingFlushEntities.add(entity);
+			},
+			unmarkMaybePending(entity) {
+				em.#maybePendingFlushEntities.delete(entity);
+			},
+			hasAnyDeletes() {
+				return em.#hasAnyDeletes;
+			},
+			pendingDeleteIds(type) {
+				return em.#pendingDeletes.filter((entity) => entity instanceof type && entity.idMaybe !== void 0).map((entity) => require_keys.keyToNumber(require_EntityMetadata.getMetadata(entity), entity.id));
+			},
+			isMerging(entity) {
+				return em.#merging?.has(entity) ?? false;
+			},
+			joinRows(m2m) {
+				return require_utils.getOrSet(em.#joinRows, m2m.joinTableName, () => new require_flush_JoinRows.JoinRows(m2m, em.#rm));
+			},
+			/** Returns `a:1.books` if it's in our preload cache. */
+			getPreloadedRelation(taggedId, fieldName) {
+				return em.#preloadedRelations.get(taggedId)?.get(fieldName);
+			},
+			/** Stores `a:1.books` in our preload cache. */
+			setPreloadedRelation(taggedId, fieldName, children) {
+				let map = em.#preloadedRelations.get(taggedId);
+				if (!map) {
+					map = /* @__PURE__ */ new Map();
+					em.#preloadedRelations.set(taggedId, map);
+				}
+				map.set(fieldName, children);
+			},
+			get isValidating() {
+				return em.#isValidating;
+			},
+			checkWritesAllowed() {
+				if (em.mode === "read-only") throw new ReadOnlyError();
+				return em.#fl.checkWritesAllowed();
+			},
+			get fieldLogger() {
+				return em.#fieldLogger;
+			},
+			clearDataloaders() {
+				em.#dataloaders = {};
+				em.#batchLoaders = {};
+			},
+			clearPreloadedRelations() {
+				em.#preloadedRelations = /* @__PURE__ */ new Map();
+			},
+			setIsRefreshing(isRefreshing) {
+				em.#isRefreshing = isRefreshing;
+			}
+		};
+	}
+	/** Returns a read-only shallow copy of the currently-loaded entities. */
+	get entities() {
+		return [...this.#entitiesArray];
+	}
+	/** Returns a list of all pending creates, updates, deletes, and m2m changes that would be flushed. */
+	get pendingChanges() {
+		const changes = [];
+		for (const entity of this.#entitiesArray) switch (require_BaseEntity.getInstanceData(entity).pendingOperation) {
+			case "insert":
+				changes.push({
+					kind: "create",
+					entity
+				});
+				break;
+			case "update":
+				changes.push({
+					kind: "update",
+					entity
+				});
+				break;
+			case "delete": changes.push({
+				kind: "delete",
+				entity
+			});
+		}
+		for (const joinRows of Object.values(this.#joinRows)) {
+			const todo = joinRows.toTodo();
+			if (todo && !todo.m2m.otherEnum) {
+				for (const row of todo.newRows) {
+					const entities = Object.values(row.columns);
+					changes.push({
+						kind: "m2m",
+						op: "add",
+						joinTableName: todo.m2m.joinTableName,
+						entities
+					});
+				}
+				for (const row of todo.deletedRows) {
+					const entities = Object.values(row.columns);
+					changes.push({
+						kind: "m2m",
+						op: "remove",
+						joinTableName: todo.m2m.joinTableName,
+						entities
+					});
+				}
+			}
+		}
+		return changes;
+	}
+	/** Returns a read-only list of the currently-loaded entities of `type`. */
+	getEntities(type) {
+		const meta = require_EntityMetadata.getMetadata(type);
+		const entities = this.#entitiesByTag.get(meta.tagName) ?? [];
+		return meta.baseType ? entities.filter((e) => e instanceof type) : entities;
+	}
+	getEntity(id) {
+		return this.#entitiesById.get(id);
+	}
+	async find(type, where, options) {
+		this.#assertFindAllowed("find");
+		const { populate, ...rest } = options || {};
+		const normalized = require_queries_find_EntityFilter.mergeFindOptions(where, rest);
+		const settings = {
+			where: normalized.where,
+			...normalized.options
+		};
+		const result = await (hasPaginationSettings(normalized.options) ? require_dataloaders_findPaginatedDataLoader.findPaginatedDataLoader(this, type, settings, populate) : require_dataloaders_findDataLoader.findDataLoader(this, type, settings, populate)).catch(function find(err) {
+			throw appendStack(err, /* @__PURE__ */ new Error());
+		});
+		if (populate) await this.populate(result, populate);
+		return result;
+	}
+	query(q, options) {
+		this.#assertFindAllowed("query");
+		const em = this;
+		return (async function query() {
+			const plan = require_queries_sql_query.parseUserQuery(q);
+			if (options?.populate && plan.output.kind !== "entity") require_utils.fail("em.query populate requires an entity selection");
+			const { rows } = await em.driver.executeQuery(em, plan.sql, plan.bindings);
+			const result = plan.decodeRows(em, rows);
+			if (options?.populate) await em.populate(result, options.populate);
+			return result;
+		})().catch(function query(err) {
+			throw appendStack(err, /* @__PURE__ */ new Error());
+		});
+	}
+	execute(statement) {
+		const em = this;
+		return (async function execute() {
+			if (require_queries_sql_execute.isMutation(statement)) {
+				if (em.mode === "read-only") throw new ReadOnlyError();
+				if (em.mode === "in-memory-writes") require_utils.fail("SQL mutations do not support in-memory-writes mode");
+			} else em.#assertFindAllowed("execute");
+			const plan = require_queries_sql_execute.parseStatement(statement);
+			if (!plan) return {
+				rowCount: 0,
+				rows: []
+			};
+			const result = await em.driver.executeQuery(em, plan.sql, plan.bindings);
+			return require_queries_sql_execute.decodeStatementResult(em, plan, result);
+		})().catch(function execute(err) {
+			throw appendStack(err, /* @__PURE__ */ new Error());
+		});
+	}
+	/** Fails fast if `em.${method}` is called from a regular validation rule, i.e. steers to `config.addCommitRule`. */
+	#assertFindAllowed(method) {
+		if (this.#findRestricted) throw new Error(`em.${method} cannot be called from a validation rule (added via config.addRule), because rules run before the flush and would query stale, pre-flush data. Use config.addCommitRule instead, which runs after the INSERT/UPDATE/DELETEs are flushed (within the same transaction) and so sees the changed state.`);
+	}
+	/** Runs the post-parse find pipeline: plugins mutate the logical AST, then Joist optimizes/prunes before SQL. */
+	async executeFind(meta, operation, parsed, settings) {
+		const { checkLimit, findSettings } = this.prepareFind(meta, operation, parsed, settings);
+		return this.executePreparedFind(meta, operation, parsed, findSettings, checkLimit);
+	}
+	/** Like {@link executeFind}, but returns a {@link RowData}; see {@link executePreparedFindRowData}. */
+	async executeFindRowData(meta, operation, parsed, settings) {
+		const { checkLimit, findSettings } = this.prepareFind(meta, operation, parsed, settings);
+		return this.executePreparedFindRowData(meta, operation, parsed, findSettings, checkLimit);
+	}
+	/** Executes a query that has already had find hooks and optimizations applied. */
+	async executePreparedFind(meta, operation, parsed, findSettings, checkLimit) {
+		const { pluginManager } = getEmInternalApi(this);
+		const rows = await this.driver.executeFind(this, parsed, findSettings);
+		if ((checkLimit ?? !("limit" in findSettings && findSettings.limit === void 0)) && rows.length >= this.entityLimit) throw new Error(`Query returned more than ${this.entityLimit} entityLimit rows`);
+		if (pluginManager.hasHook("afterFind")) pluginManager.afterFind(meta, operation, new require_RowData.PojoRowData(rows));
+		return rows;
+	}
+	/**
+	* Like {@link executePreparedFind}, but returns a {@link RowData}: lazy wire rows when the
+	* driver has `lazyRows` enabled, else classic POJO rows wrapped in a `PojoRowData` — so
+	* loaders can hydrate from one shape without caring which the driver provides.
+	*/
+	async executePreparedFindRowData(meta, operation, parsed, findSettings, checkLimit) {
+		const { executeFindRowData } = this.driver;
+		if (executeFindRowData === void 0) return new require_RowData.PojoRowData(await this.executePreparedFind(meta, operation, parsed, findSettings, checkLimit));
+		const { pluginManager } = getEmInternalApi(this);
+		const rowData = await executeFindRowData.call(this.driver, this, parsed, findSettings);
+		if ((checkLimit ?? !("limit" in findSettings && findSettings.limit === void 0)) && rowData.rowCount >= this.entityLimit) throw new Error(`Query returned more than ${this.entityLimit} entityLimit rows`);
+		pluginManager.afterFind(meta, operation, rowData);
+		return rowData;
+	}
+	/**
+	* Runs pre-SQL find hooks and optimizations against a parsed query.
+	*
+	* This allows plugins to see "pre-batched" / "logical" query ASTs, instead of our
+	* more complicated `_find` batched queries. The flow would be:
+	*
+	* - A loader calls `prepareFind(originalQuery)`
+	* - Plugins inspect/modify the query as/if needed
+	* - The loader crafts a new, more complicated query that embeds the originalQuery
+	* - The loader calls `executePreparedFind` with the 2nd query
+	*/
+	prepareFind(meta, operation, parsed, settings) {
+		const { checkLimit, ...findSettings } = settings;
+		const { pluginManager } = getEmInternalApi(this);
+		pluginManager.beforeFind(meta, operation, parsed, findSettings);
+		require_queries_find_QueryParser_collectionJoins.optimizeCollectionJoins(parsed, settings);
+		return {
+			checkLimit,
+			findSettings
+		};
+	}
+	async findGql(type, where, options) {
+		if (!options) return this.find(type, where);
+		const normalized = { ...options };
+		if ("limit" in normalized) normalized.limit = normalized.limit ?? void 0;
+		if ("offset" in normalized) normalized.offset = normalized.offset ?? void 0;
+		return this.find(type, where, normalized);
+	}
+	async findOne(type, where, options) {
+		const list = await this.find(type, where, options);
+		if (list.length === 0) return;
+		else if (list.length === 1) return list[0];
+		else throw new TooManyError(`Found more than one: ${list.map((e) => e.toString()).join(", ")}`);
+	}
+	async findOneOrFail(type, where, options) {
+		const list = await this.find(type, where, options);
+		if (list.length === 0) throw new NotFoundError(`Did not find ${type.name} for given query`);
+		else if (list.length > 1) throw new TooManyError(`Found more than one: ${list.map((e) => e.toString()).join(", ")}`);
+		return list[0];
+	}
+	async findByUnique(type, where, options = {}) {
+		this.#assertFindAllowed("findByUnique");
+		const { populate, softDeletes = "exclude" } = options;
+		const entries = Object.entries(where);
+		if (entries.length !== 1) throw new Error("findByUnique only accepts a single field");
+		const [fieldName, value] = entries[0];
+		const field = require_EntityMetadata.getMetadata(type).allFields[fieldName];
+		const row = await require_dataloaders_findByUniqueDataLoader.findByUniqueDataLoader(this, type, field, softDeletes).load(value).catch(function findByUnique(err) {
+			throw appendStack(err, /* @__PURE__ */ new Error());
+		});
+		if (!row) return;
+		else {
+			const [entity] = this.hydrate(type, [row]);
+			if (this.#hasAnyDeletes && entity.isDeletedEntity) return;
+			if (populate) await this.populate(entity, populate);
+			return entity;
+		}
+	}
+	/**
+	* Returns the count of entities that match the `where` clause.
+	*
+	* The `where` clause, and any options.conditions, matches the same syntax
+	* as `em.find`.
+	*
+	* Note: this method is not currently auto-batched, so it will cause N+1s if called in a loop.
+	*/
+	async findCount(type, where, options = {}) {
+		this.#assertFindAllowed("findCount");
+		const normalized = require_dataloaders_findCountDataLoader.mergeCountOptions(where, options);
+		const settings = {
+			where: normalized.where,
+			...normalized.options
+		};
+		let count = await require_dataloaders_findCountDataLoader.findCountDataLoader(this, type, settings).catch(function findCount(err) {
+			throw appendStack(err, /* @__PURE__ */ new Error());
+		});
+		if (require_queries_find_scopes.isSelectAllFilter(where, options.conditions)) {
+			const tagged = this.#entitiesByTag.get(require_EntityMetadata.getMetadata(type).tagName) ?? [];
+			for (const entity of tagged) if (entity instanceof type) {
+				if (entity.isNewEntity) count++;
+				else if (entity.isDeletedEntity) count--;
+			}
+		}
+		return count;
+	}
+	/**
+	* Returns the IDs of entities that match the `where` clause.
+	*
+	* The `where` clause, and any options.conditions, matches the same syntax
+	* as `em.find`.
+	*/
+	async findIds(type, where, options = {}) {
+		this.#assertFindAllowed("findIds");
+		const normalized = require_dataloaders_findCountDataLoader.mergeCountOptions(where, options);
+		const settings = {
+			where: normalized.where,
+			...normalized.options
+		};
+		return require_dataloaders_findIdsDataLoader.findIdsDataLoader(this, type, settings).catch(function findIds(err) {
+			throw appendStack(err, /* @__PURE__ */ new Error());
+		});
+	}
+	async findWithNewOrChanged(type, where, options) {
+		const { softDeletes = "exclude", populate } = options ?? {};
+		const copy = Object.fromEntries(Object.entries(where).filter(([, v]) => v !== void 0));
+		const unchanged = (await this.find(type, copy, { softDeletes })).filter((e) => !e.isNewEntity && !e.isDirtyEntity && !e.isDeletedEntity);
+		const maybeNew = this.filterEntities(type, where).filter((e) => (e.isNewEntity || e.isDirtyEntity) && !e.isDeletedEntity);
+		const found = [...unchanged, ...maybeNew];
+		if (populate) await this.populate(found, populate);
+		return found;
+	}
+	async findOrCreate(type, where, ifNew, upsert, options) {
+		const { softDeletes = "exclude", populate } = options ?? {};
+		const entity = await require_dataloaders_findOrCreateDataLoader.findOrCreateDataLoader(this, type, where, softDeletes).load({
+			ifNew,
+			upsert
+		}).catch(function findOrCreate(err) {
+			throw appendStack(err, /* @__PURE__ */ new Error());
+		});
+		if (populate) await this.populate(entity, populate);
+		return entity;
+	}
+	/** Creates a new `type` and marks it as loaded, i.e. we know its collections are all safe to access in memory. */
+	create(type, opts) {
+		return this.#doCreate(type, opts, false);
+	}
+	/**
+	* Creates a new `type` but with `opts` that are nullable, to accept partial-update-style input.
+	*
+	* Note that `createPartial` doesn't support the full upsert behavior, i.e. this method:
+	*
+	* - always creates,
+	* - does not support relation markers like `op`, `delete`, and `remove`,
+	* - does not accept deep input, but
+	* - fields set to `undefined` will be skipped instead of unset
+	*
+	* See `upsert` for the upsert/deep upsert behavior.
+	*/
+	createPartial(type, opts) {
+		return this.#doCreate(type, opts, true);
+	}
+	/**
+	* Create or updates `type` based on partial-update-style `input`.
+	*
+	* This supports upsert behavior, i.e.:
+	*
+	* - findOrCreate the primary entity being updated (based on the `id` key being provided),
+	* - upsert relation markers like `op`, `delete`, and `remove` are supported,
+	* - deep input is supported, i.e. `{ firstName: "Bob", books: [{ title: "b1" } ] }`, and
+	* - fields set to `undefined` will be skipped instead of unset
+	*/
+	upsert(type, input) {
+		return require_upsert.upsert(this, type, input);
+	}
+	async clone(entityOrArray, opts) {
+		const { deep = {}, skipIf, skip = {}, postClone } = opts ?? {};
+		const todo = /* @__PURE__ */ new Set();
+		const skipMap = /* @__PURE__ */ new WeakMap();
+		await crawl(todo, skipMap, Array.isArray(entityOrArray) ? entityOrArray : [entityOrArray], deep, {
+			skipIf,
+			skip
+		});
+		const deferredRelations = [];
+		const clones = [...todo].map((entity) => {
+			const skip = skipMap.get(entity) ?? [];
+			const meta = require_EntityMetadata.getMetadata(entity);
+			const copy = Object.fromEntries(Object.values(meta.allFields).map((f) => {
+				if (skip.includes(f.fieldName)) return void 0;
+				switch (f.kind) {
+					case "primitive": if (!f.derived && !f.protected) return [f.fieldName, require_fields.getField(entity, f.fieldName)];
+					else return;
+					case "enum": if (f.derived) return;
+					else return [f.fieldName, require_fields.getField(entity, f.fieldName)];
+					case "m2o":
+					case "poly": {
+						if (f.kind === "m2o" && f.derived) return void 0;
+						const existingIdOrEntity = require_fields.getField(entity, f.fieldName);
+						const target = require_Entity.isEntity(existingIdOrEntity) ? existingIdOrEntity : this.getEntity(existingIdOrEntity);
+						if (target && todo.has(target)) {
+							deferredRelations.push([
+								entity,
+								f.fieldName,
+								target
+							]);
+							return [f.fieldName, void 0];
+						} else return [f.fieldName, existingIdOrEntity];
+					}
+					case "primaryKey":
+					case "o2m":
+					case "m2m":
+					case "m2mEnum":
+					case "o2o":
+					case "lo2m": return;
+					default: require_utils.assertNever(f);
+				}
+			}).filter(isDefined));
+			return [entity, this.create(require_index.asConcreteCstr(meta.cstr), copy)];
+		});
+		const entityToClone = new Map(clones);
+		clones.forEach(([, clone]) => {
+			require_index.getRelationEntries(clone).forEach(([fieldName, value]) => {
+				if (value instanceof require_relations_ManyToOneReference.ManyToOneReferenceImpl || value instanceof require_relations_PolymorphicReference.PolymorphicReferenceImpl || value instanceof require_relations_ReactiveReference.ReactiveReferenceImpl) {
+					const existingIdOrEntity = require_fields.getField(clone, fieldName);
+					const existing = require_Entity.isEntity(existingIdOrEntity) ? existingIdOrEntity : this.getEntity(existingIdOrEntity);
+					if (existing) clone[fieldName].set(entityToClone.get(existing) ?? existing);
+				}
+			});
+		});
+		deferredRelations.forEach(([source, fieldName, target]) => {
+			entityToClone.get(source)[fieldName].set(entityToClone.get(target));
+		});
+		if (postClone) await Promise.all(clones.map(([original, clone]) => postClone(original, clone)));
+		return Array.isArray(entityOrArray) ? entityOrArray.filter((original) => entityToClone.has(original)).map((original) => entityToClone.get(original)) : clones[0] ? clones[0][1] : require_utils.fail("no entities were cloned given the provided options");
+	}
+	/**
+	* Merges multiple source entities into a target entity by updating all references that point
+	* to the source entities to instead point to the target entity.
+	*
+	* This method loads all relations from the source entities, updates any entity that
+	* references a source entity to reference the target entity instead, and then automatically
+	* deletes the source entities.
+	*
+	* @param target - The entity that will become the target of all merged references
+	* @param sources - Array of entities whose references will be redirected to the target
+	* @param opts - Options to control merge behavior
+	*   @param autoDelete - Whether to automatically delete source entities (default: true)
+	* @returns Promise that resolves when all references have been updated and sources deleted
+	*
+	* @example
+	* // Merge duplicate authors - all books pointing to author2 will now point to author1
+	* // author2 will be automatically deleted
+	* await em.merge(author1, [author2]);
+	*
+	* @example
+	* // Merge multiple duplicate publishers into one
+	* // publisher2 and publisher3 will be automatically deleted
+	* await em.merge(publisher1, [publisher2, publisher3]);
+	*
+	* @example
+	* // Merge without auto-deleting sources (for custom cleanup logic)
+	* await em.merge(author1, [author2], { autoDelete: false });
+	* // Custom logic here...
+	* em.delete(author2);
+	*/
+	async merge(target, sources, opts) {
+		const autoDelete = opts?.autoDelete ?? true;
+		if (sources.length === 0) return [];
+		this.#merging ??= /* @__PURE__ */ new Set();
+		this.#merging.add(target);
+		const targetMeta = require_EntityMetadata.getMetadata(target);
+		for (const source of sources) {
+			const sourceMeta = require_EntityMetadata.getMetadata(source);
+			if (sourceMeta.type !== targetMeta.type) throw new Error(`Cannot merge entities of different types: ${targetMeta.type} and ${sourceMeta.type}`);
+		}
+		const fields = Object.values(targetMeta.allFields).filter((field) => [
+			"o2m",
+			"m2o",
+			"m2m",
+			"o2o"
+		].includes(field.kind)).map((field) => field.fieldName);
+		await this.populate(sources, fields);
+		const changedEntities = [];
+		for (const source of sources) for (const field of Object.values(targetMeta.allFields)) {
+			const { kind } = field;
+			if (kind === "o2m") for (const other of source[field.fieldName].get) {
+				this.#merging.add(other);
+				other[field.otherFieldName].set(target);
+				changedEntities.push(other);
+			}
+			else if (kind === "o2o") {
+				const otherField = field.otherMetadata().allFields[field.otherFieldName];
+				if (otherField.kind === "m2o" && otherField.derived) continue;
+				const other = source[field.fieldName].get;
+				if (other) {
+					this.#merging.add(other);
+					other[field.otherFieldName].set(target);
+					changedEntities.push(other);
+				}
+			} else if (kind === "m2m") for (const other of source[field.fieldName].get) {
+				this.#merging.add(other);
+				const collection = other[field.otherFieldName];
+				collection.remove(source);
+				collection.add(target);
+				changedEntities.push(other);
+			}
+			else if (kind === "primitive" || kind === "primaryKey" || kind === "enum" || kind === "m2mEnum" || kind === "poly" || kind === "m2o" || kind === "lo2m") {} else require_utils.assertNever(kind);
+		}
+		if (autoDelete) for (const source of sources) this.delete(source);
+		return changedEntities;
+	}
+	async load(typeOrId, id, hint) {
+		let type;
+		if (typeof typeOrId === "string") {
+			type = require_configure.getConstructorFromTaggedId(typeOrId);
+			id = typeOrId;
+		} else {
+			type = typeOrId;
+			id = id || require_utils.fail(`Invalid ${typeOrId.name} id: ${id}`);
+		}
+		const meta = require_EntityMetadata.getMetadata(type);
+		const taggedId = require_keys.toTaggedId(meta, id);
+		let entity = this.findExistingInstance(taggedId);
+		if (!entity) {
+			await require_batchloaders_loadBatchLoader.loadBatchLoader(this, meta).load({
+				taggedId,
+				hint
+			}).catch(function load(err) {
+				throw appendStack(err, /* @__PURE__ */ new Error());
+			});
+			entity = this.findExistingInstance(taggedId);
+		}
+		if (!entity) throw new NotFoundError(`${taggedId} was not found`);
+		if (hint) await this.populate(entity, hint);
+		if (meta.inheritanceType === "sti" && !(entity instanceof type)) throw new Error(`${entity} is ${entity.constructor.name} but should be ${type.name}`);
+		return entity;
+	}
+	async loadAll(type, _ids, hint) {
+		const meta = require_EntityMetadata.getMetadata(type);
+		const entities = new Array(_ids.length);
+		let idsToLoad;
+		let positionsToLoad;
+		for (let i = 0; i < _ids.length; i++) {
+			const id = require_keys.tagId(meta, _ids[i]);
+			const entity = this.findExistingInstance(id);
+			if (entity) entities[i] = entity;
+			else {
+				(idsToLoad ??= []).push(id);
+				(positionsToLoad ??= []).push(i);
+			}
+		}
+		if (idsToLoad) {
+			await require_batchloaders_loadBatchLoader.loadBatchLoader(this, meta).loadAll(idsToLoad.map((id) => ({
+				taggedId: id,
+				hint
+			}))).catch(function loadAll(err) {
+				throw appendStack(err, /* @__PURE__ */ new Error());
+			});
+			let idsNotFound;
+			for (let j = 0; j < positionsToLoad.length; j++) {
+				const entity = this.findExistingInstance(idsToLoad[j]);
+				entities[positionsToLoad[j]] = entity;
+				if (entity === void 0) (idsNotFound ??= []).push(idsToLoad[j]);
+			}
+			if (idsNotFound) throw new NotFoundError(`${idsNotFound.join(",")} were not found`);
+		}
+		const loadedEntities = entities;
+		if (hint) await this.populate(loadedEntities, hint);
+		if (meta.inheritanceType === "sti" && meta.baseType) {
+			const wrongType = loadedEntities.filter((e) => !(e instanceof meta.cstr));
+			if (wrongType.length > 0) throw new Error(`${wrongType.join(", ")} were not of type ${meta.cstr.name}`);
+		}
+		return loadedEntities;
+	}
+	async loadAllIfExists(type, _ids, hint) {
+		const meta = require_EntityMetadata.getMetadata(type);
+		const maybeEntities = new Array(_ids.length);
+		let idsToLoad;
+		let positionsToLoad;
+		for (let i = 0; i < _ids.length; i++) {
+			const id = require_keys.tagId(meta, _ids[i]);
+			const entity = this.findExistingInstance(id);
+			if (entity) maybeEntities[i] = entity;
+			else {
+				(idsToLoad ??= []).push(id);
+				(positionsToLoad ??= []).push(i);
+			}
+		}
+		let entities;
+		if (idsToLoad) {
+			await require_batchloaders_loadBatchLoader.loadBatchLoader(this, meta).loadAll(idsToLoad.map((id) => ({
+				taggedId: id,
+				hint
+			}))).catch(function loadAllIfExists(err) {
+				throw appendStack(err, /* @__PURE__ */ new Error());
+			});
+			for (let j = 0; j < positionsToLoad.length; j++) maybeEntities[positionsToLoad[j]] = this.findExistingInstance(idsToLoad[j]);
+			entities = [];
+			for (const entity of maybeEntities) if (entity !== void 0) entities.push(entity);
+		} else entities = maybeEntities;
+		if (hint) await this.populate(entities, hint);
+		return entities;
+	}
+	async loadLens(entities, fn, populate) {
+		const result = await require_loading_loadLens.loadLens(entities, fn);
+		if (populate) await this.populate(result, populate);
+		return result;
+	}
+	loadFromQuery(type, rows, populate) {
+		if (Array.isArray(rows)) {
+			const entities = this.hydrate(type, rows);
+			if (populate) return this.populate(entities, populate);
+			return entities;
+		} else return rows.then((rows) => {
+			const entities = this.hydrate(type, rows);
+			if (populate) return this.populate(entities, populate);
+			return entities;
+		});
+	}
+	async loadFromRows(type, rows, populate) {
+		const entities = this.hydrate(type, rows);
+		if (populate) await this.populate(entities, populate);
+		return entities;
+	}
+	async populate(entityOrList, hintOrOpts, fn) {
+		const { hint: hintOpt, ...opts } = typeof hintOrOpts === "object" && "hint" in hintOrOpts ? hintOrOpts : { hint: hintOrOpts };
+		opts[require_relations_hasAsyncMethod.AsyncMethodPopulateSecret] = true;
+		const list = require_utils.toArray(entityOrList).filter((e) => {
+			return e !== void 0 && !require_BaseEntity.getInstanceData(e).isDeletedAndFlushed;
+		});
+		if (list.length === 0) return !fn ? entityOrList : fn(entityOrList);
+		if (!opts.forceReload && list.every((entity) => !entity.isNewEntity && require_loading_loadHints.isLoadedForPopulate(entity, hintOpt))) return fn ? fn(entityOrList) : entityOrList;
+		const meta = require_EntityMetadata.getMetadata(list[0]);
+		if (this.#preloader) {
+			const [preload, non] = this.#preloader.partitionHint(meta, hintOpt);
+			if (preload) await require_batchloaders_populateBatchLoader.populateBatchLoader(this, meta, preload, "preload", opts).loadAll(list.map((entity) => ({
+				entity,
+				hint: preload
+			}))).catch(function populate(err) {
+				throw appendStack(err, /* @__PURE__ */ new Error());
+			});
+			if (non) await require_batchloaders_populateBatchLoader.populateBatchLoader(this, meta, non, "intermixed", opts).loadAll(list.map((entity) => ({
+				entity,
+				hint: non
+			}))).catch(function populate(err) {
+				throw appendStack(err, /* @__PURE__ */ new Error());
+			});
+		} else await require_batchloaders_populateBatchLoader.populateBatchLoader(this, meta, hintOpt, "intermixed", opts).loadAll(list.map((entity) => ({
+			entity,
+			hint: hintOpt
+		}))).catch(function populate(err) {
+			throw appendStack(err, /* @__PURE__ */ new Error());
+		});
+		return fn ? fn(entityOrList) : entityOrList;
+	}
+	/**
+	* Executes `fn` with a transaction, and automatically calls `flush`/`commit` at the end.
+	*
+	* This ensures both any `.find` and `.flush` operations happen within the same
+	* transaction, which is useful for enforcing cross-table/application-level invariants that
+	* cannot be enforced with database-level constraints.
+	*/
+	async transaction(fn) {
+		return this.driver.transaction(this, async (txn) => {
+			const result = await fn(txn);
+			await this.flush();
+			return result;
+		});
+	}
+	delete(entityOrArray) {
+		for (const entity of require_utils.toArray(entityOrArray)) {
+			if (!require_BaseEntity.getInstanceData(entity).markDeleted()) continue;
+			this.#hasAnyDeletes = true;
+			this.#rm.queueAllDownstreamFields(entity, "deleted");
+			getCascadeDeleteRelations(entity).forEach((r) => r.maybeCascadeDelete());
+			this.#pendingDeletes.push(entity);
+		}
+	}
+	async assignNewIds() {
+		let pendingEntities = this.entities.filter((e) => e.isNewEntity && !e.isDeletedEntity && !e.idTaggedMaybe);
+		await this.getLoader("assign-new-ids", "global", async (entities) => {
+			let todos = require_flush_Todo.createTodos(entities);
+			await this.driver.assignNewIds(this, todos);
+			for (const e of entities) this.#entitiesById.set(e.idTagged, e);
+			return entities;
+		}).loadMany(pendingEntities).catch(function assignNewIds(err) {
+			throw appendStack(err, /* @__PURE__ */ new Error());
+		});
+	}
+	/**
+	* Immediately assigns async defaults to `entities`.
+	*
+	* Normally async defaults wait until `em.flush` to run, because their async nature requires
+	* an `await` / `Promise` to be evaluated, and `em.create` is synchronous.
+	*
+	* This `assignDefaults` methods like you move that up, and immediately invoke
+	* any default logic against the `entities`.
+	*/
+	async setDefaults(entities) {
+		return require_trusted.runInTrustedContext(async () => {
+			const suppressedTypeErrors = [];
+			const entitiesByType = require_utils.groupBy(entities.filter((e) => e.isNewEntity), (e) => require_EntityMetadata.getMetadata(e));
+			await require_defaults.setAsyncDefaults(suppressedTypeErrors, this.ctx, entitiesByType);
+		});
+	}
+	/**
+	* Flushes the SQL for any changed entities to the database.
+	*
+	* If this is run outside of an existing transaction, it will `BEGIN` and `COMMIT`
+	* a new transaction on every `.flush()` call so that all of the `INSERT`s/etc.
+	* happen atomically.
+	*
+	* If this is run within an existing transaction, i.e. `EntityManager.transaction`,
+	* then it will only issue `INSERT`s/etc. and defer to the caller to `COMMIT`
+	* the transaction.
+	*
+	* It returns entities that have changed (an entity is considered changed if it has been deleted, inserted, or updated)
+	*/
+	async flush(flushOptions = {}) {
+		return require_trusted.runInTrustedContext(() => this.#flush(flushOptions));
+	}
+	async #flush(flushOptions = {}) {
+		if (this.mode === "read-only") throw new ReadOnlyError();
+		const { skipValidation = false } = flushOptions;
+		this.#fl.startLock();
+		const allFlushedEntities = /* @__PURE__ */ new Set();
+		try {
+			await this.#fl.allowWrites(async () => {
+				await this.flushDeletes();
+				await this.#rm.recalcPendingReactables("reactables");
+			});
+			const createdThenDeleted = /* @__PURE__ */ new Set();
+			const hooksInvoked = /* @__PURE__ */ new Set();
+			let hookLoops = 0;
+			let now = getNow();
+			const suppressedDefaultTypeErrors = [];
+			const runHooksOnPendingEntities = async () => {
+				if (hookLoops++ >= 10) throw new Error("runHooksOnPendingEntities has ran 10 iterations, aborting");
+				const pendingLoads = [...getEmInternalApi(this).pendingLoads];
+				if (pendingLoads.length > 0) {
+					getEmInternalApi(this).pendingLoads.clear();
+					await Promise.all(pendingLoads.map((collection) => collection.load()));
+				}
+				const pendingFlush = /* @__PURE__ */ new Set();
+				const pendingHooks = /* @__PURE__ */ new Set();
+				const alreadyRanHooks = /* @__PURE__ */ new Set();
+				findPendingFlushEntities(this.#maybePendingFlushEntities, hooksInvoked, pendingFlush, pendingHooks, alreadyRanHooks);
+				if (alreadyRanHooks.size > 0) maybeBumpUpdatedAt(this.#rm, require_flush_Todo.createTodos(alreadyRanHooks), now);
+				while (pendingHooks.size > 0) await this.#fl.allowWrites(async () => {
+					let todos = require_flush_Todo.createTodos(pendingHooks);
+					await require_defaults.setAsyncDefaults(suppressedDefaultTypeErrors, this.ctx, require_flush_Todo.Todo.groupInsertsByTypeAndSubType(todos));
+					maybeBumpUpdatedAt(this.#rm, todos, now);
+					for (const group of maybeSetupHookOrdering(todos)) {
+						await beforeCreate(this.ctx, group);
+						await beforeUpdate(this.ctx, group);
+						await beforeFlush(this.ctx, group);
+					}
+					recalcSynchronousDerivedFields(todos);
+					do {
+						await this.flushDeletes();
+						await this.#rm.recalcPendingReactables("reactables");
+					} while (this.#pendingDeletes.length > 0);
+					if (this.#rm.hasPendingTypeErrors) {
+						await this.#rm.recalcPendingTypeErrors();
+						if (this.#rm.needsRecalc("reactables")) await this.#rm.recalcPendingReactables("reactables");
+					}
+					for (const e of pendingHooks) hooksInvoked.add(e);
+					pendingHooks.clear();
+					findPendingFlushEntities(this.#maybePendingFlushEntities, hooksInvoked, pendingFlush, pendingHooks, alreadyRanHooks);
+					if (pendingHooks.size === 0 && this.#rm.hasPendingTypeErrors) await this.#rm.recalcPendingTypeErrors();
+				});
+				return [...pendingFlush].filter((e) => {
+					const createThenDelete = e.isDeletedEntity && e.isNewEntity;
+					if (createThenDelete) createdThenDeleted.add(e);
+					return !createThenDelete;
+				});
+			};
+			const { pluginManager } = getEmInternalApi(this);
+			const runValidation = async (entityTodos, joinRowTodos, validate) => {
+				const changedEntities = entitiesFromTodos(entityTodos, joinRowTodos);
+				try {
+					this.#isValidating = true;
+					await pluginManager.beforeValidate(changedEntities);
+					if (validate) {
+						this.#findRestricted = true;
+						try {
+							await validateSimpleRules(entityTodos);
+							if (suppressedDefaultTypeErrors.length > 0) throw suppressedDefaultTypeErrors[0];
+							await validateReactiveRules(this, this.#rm.logger, entityTodos, joinRowTodos);
+						} finally {
+							this.#findRestricted = false;
+						}
+						await afterValidation(this.ctx, entityTodos);
+					}
+					await pluginManager.afterValidate(changedEntities);
+				} finally {
+					this.#isValidating = false;
+				}
+			};
+			const runCommitValidation = async (entityTodos, joinRowTodos) => {
+				this.#dataloaders = {};
+				this.#batchLoaders = {};
+				this.#preloadedRelations = /* @__PURE__ */ new Map();
+				try {
+					this.#isValidating = true;
+					await validateSimpleRules(entityTodos, (config) => config.commitRules);
+					await validateReactiveRules(this, this.#rm.logger, entityTodos, joinRowTodos, (meta) => meta.reactiveCommitRules);
+				} finally {
+					this.#isValidating = false;
+				}
+			};
+			const commitRuleTodos = {};
+			const commitRuleJoinRowTodos = {};
+			const commitRuleSeen = /* @__PURE__ */ new Set();
+			function collectCommitRuleTodos(entityTodos, joinRowTodos) {
+				if (skipValidation) return;
+				for (const todo of Object.values(entityTodos)) {
+					if (!todo.metadata.hasCommitRules) continue;
+					for (const key of [
+						"inserts",
+						"updates",
+						"deletes"
+					]) for (const e of todo[key]) if (!commitRuleSeen.has(e)) {
+						commitRuleSeen.add(e);
+						require_flush_Todo.getTodo(commitRuleTodos, e)[key].push(e);
+					}
+				}
+				for (const [table, todo] of Object.entries(joinRowTodos)) {
+					if (!todo.m2m.meta.hasCommitRules && !todo.m2m.otherMeta?.hasCommitRules) continue;
+					const into = commitRuleJoinRowTodos[table] ??= {
+						...todo,
+						newRows: [],
+						deletedRows: []
+					};
+					for (const key of ["newRows", "deletedRows"]) for (const r of todo[key]) if (!commitRuleSeen.has(r)) {
+						commitRuleSeen.add(r);
+						into[key].push(r);
+					}
+				}
+			}
+			let entitiesToFlush = await runHooksOnPendingEntities();
+			for (const e of entitiesToFlush) allFlushedEntities.add(e);
+			let entityTodos = require_flush_Todo.createTodos(entitiesToFlush);
+			let joinRowTodos = require_flush_Todo.combineJoinRows(this.#joinRows);
+			await runValidation(entityTodos, joinRowTodos, !skipValidation);
+			this.#rm.throwIfAnySuppressedTypeErrors();
+			if (suppressedDefaultTypeErrors.length > 0) throw suppressedDefaultTypeErrors[0];
+			if (Object.keys(entityTodos).length > 0 || Object.keys(joinRowTodos).length > 0) {
+				await this.driver.transaction(this, async () => {
+					do {
+						if (Object.keys(entityTodos).length > 0 || Object.keys(joinRowTodos).length > 0) {
+							await this.driver.flush(this, entityTodos, joinRowTodos);
+							collectCommitRuleTodos(entityTodos, joinRowTodos);
+						}
+						pluginManager.afterWrite(entityTodos, joinRowTodos);
+						if (this.#rm.hasPendingReactiveQueries()) {
+							for (const e of entitiesToFlush) {
+								if (e.isNewEntity && !e.isDeletedEntity) this.#entitiesById.set(e.idTagged, e);
+								require_BaseEntity.getInstanceData(e).resetForRqfLoop();
+							}
+							await this.#fl.allowWrites(async () => {
+								await this.#rm.recalcPendingReactables("reactiveQueries");
+								await this.#rm.recalcPendingReactables("reactables");
+							});
+							now = getNow();
+							entitiesToFlush = await runHooksOnPendingEntities();
+							for (const e of entitiesToFlush) allFlushedEntities.add(e);
+							entityTodos = require_flush_Todo.createTodos(entitiesToFlush);
+							joinRowTodos = require_flush_Todo.combineJoinRows(this.#joinRows);
+							await runValidation(entityTodos, joinRowTodos, true);
+							this.#rm.throwIfAnySuppressedTypeErrors();
+						} else entityTodos = {};
+					} while (Object.keys(entityTodos).length > 0);
+					if (Object.keys(commitRuleTodos).length > 0 || Object.keys(commitRuleJoinRowTodos).length > 0) {
+						for (const e of allFlushedEntities) if (e.isNewEntity && !e.isDeletedEntity) this.#entitiesById.set(e.idTagged, e);
+						await runCommitValidation(commitRuleTodos, commitRuleJoinRowTodos);
+					}
+					await beforeCommit(this.ctx, allFlushedEntities);
+					if (this.mode === "in-memory-writes") throw new InMemoryRollbackError();
+				});
+				await afterCommit(this.ctx, allFlushedEntities);
+				for (const e of allFlushedEntities) {
+					const instanceData = require_BaseEntity.getInstanceData(e);
+					if (e.isNewEntity && !e.isDeletedEntity) this.#entitiesById.set(e.idTagged, e);
+					instanceData.resetAfterFlushed();
+					const { relations } = instanceData;
+					if (relations) {
+						for (const rel of Object.values(relations)) if (rel instanceof require_relations_AsyncProperty.AsyncPropertyImpl || rel instanceof require_relations_LazyField.LazyFieldImpl) rel.resetAfterFlush();
+					}
+				}
+				for (const joinRow of Object.values(joinRowTodos)) joinRow.resetAfterFlushed();
+				const { mutatedCollections } = getEmInternalApi(this);
+				for (const o2m of mutatedCollections.values()) o2m.resetAddedRemoved();
+				mutatedCollections.clear();
+				this.#dataloaders = {};
+				this.#batchLoaders = {};
+				this.#preloadedRelations = /* @__PURE__ */ new Map();
+				this.#rm.clear();
+			}
+			for (const e of createdThenDeleted) require_BaseEntity.getInstanceData(e).fixupCreatedThenDeleted();
+			this.#merging?.clear();
+			return [...allFlushedEntities].sort((a, b) => require_BaseEntity.getInstanceData(a).entityIndex - require_BaseEntity.getInstanceData(b).entityIndex);
+		} catch (e) {
+			if (e instanceof require_relations_RecursiveCycleError.RecursiveCycleError) {
+				const entity = e.entities[0];
+				for (const meta of require_EntityMetadata.getBaseAndSelfMetas(require_EntityMetadata.getMetadata(entity))) {
+					const messageFn = meta.config.__data.cycleMessages[e.fieldName] ?? meta.config.__data.cycleMessages[entity[e.fieldName]?.otherFieldName];
+					if (messageFn) throw new require_rules.ValidationErrors([{
+						entity,
+						message: messageFn(entity, e.entities)
+					}]);
+				}
+			}
+			const detail = e && typeof e === "object" && "detail" in e && typeof e.detail === "string" ? e.detail : void 0;
+			if (e && typeof e === "object" && "constraint" in e && typeof e.constraint === "string") {
+				const message = require_config.constraintNameToValidationError[e.constraint];
+				if (message) {
+					const errors = new require_rules.ValidationErrors(message);
+					if (detail) errors.message = `${message} — ${detail}`;
+					throw errors;
+				}
+			}
+			if (e instanceof InMemoryRollbackError) return [...allFlushedEntities].sort((a, b) => require_BaseEntity.getInstanceData(a).entityIndex - require_BaseEntity.getInstanceData(b).entityIndex);
+			if (detail && e instanceof Error) e.message = `${e.message} — ${detail}`;
+			throw e;
+		} finally {
+			this.#rm.clearSuppressedTypeErrors();
+			this.#fl.releaseLock();
+			require_newTestInstance.resetFactoryCreated();
+		}
+	}
+	/**
+	* A very simple toJSON.
+	*
+	* This is not really meant to be useful, it's to prevent huge/circular output if
+	* an EntityManager accidentally ends up getting logged to something like pino that
+	* over-zealous toJSONs anything it touches.
+	*/
+	toJSON() {
+		return `<EntityManager ${this.entities.length}>`;
+	}
+	async refresh(param) {
+		this.#isRefreshing = true;
+		this.#dataloaders = {};
+		this.#batchLoaders = {};
+		this.#preloadedRelations = /* @__PURE__ */ new Map();
+		const deepLoad = param && "deepLoad" in param && param.deepLoad;
+		let todo = param === void 0 ? this.#entitiesArray : Array.isArray(param) ? param : require_Entity.isEntity(param) ? [param] : this.#entitiesArray;
+		const done = /* @__PURE__ */ new Set();
+		while (todo.length > 0) {
+			const copy = [...todo];
+			copy.forEach((e) => done.add(e));
+			todo = [];
+			const entitiesToRefresh = copy.filter((e) => e.idTaggedMaybe && !e.isDeletedEntity);
+			await Promise.all(entitiesToRefresh.map((entity) => {
+				const hint = require_index.getRelationEntries(entity).filter(([_, r]) => deepLoad || r.isLoaded).map(([k]) => k);
+				return require_batchloaders_loadBatchLoader.loadBatchLoader(this, require_EntityMetadata.getMetadata(entity), true).load({
+					taggedId: entity.idTagged,
+					hint
+				}).catch(function refresh(err) {
+					throw appendStack(err, /* @__PURE__ */ new Error());
+				});
+			}));
+			const [custom, builtin] = require_utils.partition(entitiesToRefresh.filter((e) => !require_BaseEntity.getInstanceData(e).isDeletedEntity).flatMap((entity) => require_index.getRelations(entity).filter((r) => deepLoad || r.isLoaded)), isCustomRelation);
+			await Promise.all(builtin.map((r) => {
+				if (r.isPreloaded && !r.isLoaded) {
+					r.preload();
+					return;
+				} else return r.load({ forceReload: true });
+			}));
+			await Promise.all(custom.map((r) => r.load({ forceReload: true })));
+			if (deepLoad) todo.push(...builtin.filter((r) => "get" in r).map((r) => r.get).flatMap((value) => Array.isArray(value) ? value : [value]).filter((value) => require_Entity.isEntity(value) && !done.has(value)));
+		}
+		this.#isRefreshing = false;
+	}
+	get numberOfEntities() {
+		return this.entities.length;
+	}
+	findExistingInstance(id) {
+		return this.#entitiesById.get(id);
+	}
+	/**
+	* Takes a result `row` from a custom query and maps the db values into a new-or-existing domain object for that row.
+	*
+	* The `overwriteExisting` controls whether `row`'s values should overwrite the existing fields on
+	* an entity. By default this is true, as we assume the user calling this means they know the DB has
+	* updated values that should be put into the entities. A few internal callers set this to false,
+	* i.e. when we're loading collections and have db results that are potentially stale compared to
+	* the WIP entity state.
+	*/
+	hydrate(type, rows, options) {
+		return this.hydrateFromRowData(type, new require_RowData.PojoRowData(rows), options);
+	}
+	/**
+	* Hydrates a query's `RowData`, running any sidecar reads, and always `finalize`s the result.
+	*
+	* This is the internal API for Joist's find/load loaders: `sidecars` is where reads of
+	* non-entity columns (preload aggregates, `_tags`, found-id checks) belong — they must run
+	* before `finalize`, because compaction drops unretained rows — and the `try/finally`
+	* guarantees a failed hydration or sidecar read still releases the result's unretained
+	* buffers instead of pinning them.
+	*/
+	hydrateAndFinalize(type, rowData, opts) {
+		try {
+			const entities = this.hydrateFromRowData(type, rowData, opts);
+			opts?.sidecars?.(entities);
+			return entities;
+		} finally {
+			rowData.finalize?.();
+		}
+	}
+	/**
+	* Like {@link hydrate}, but reads rows from a {@link RowData}, i.e. a driver-produced
+	* lazy query result, instead of an array of POJO rows.
+	*
+	* This is an internal API used by Joist's own find loaders (usually via
+	* {@link hydrateAndFinalize}); rows whose entities are kept (newly created or
+	* overwrite-refreshed) are `retain`-ed on the `RowData` so the caller can later `finalize`
+	* (trim/compact) the result.
+	*/
+	hydrateFromRowData(type, rowData, options) {
+		const maybeBaseMeta = require_EntityMetadata.getMetadata(type);
+		const overwriteExisting = options?.overwriteExisting === true;
+		const count = rowData.rowCount;
+		const entities = new Array(count);
+		for (let i = 0; i < count; i++) {
+			const id = rowData.get(i, "id");
+			const taggedId = id === void 0 || id === null ? require_utils.fail("No id column was available") : require_keys.keyToTaggedId(maybeBaseMeta, id);
+			let entity = this.findExistingInstance(taggedId);
+			if (!entity) {
+				const meta = findConcreteMeta(maybeBaseMeta, rowData, i);
+				entity = require_newEntity.newEntity(this, require_index.asConcreteCstr(meta.cstr), false);
+				const instanceData = require_BaseEntity.getInstanceData(entity);
+				instanceData.rowData = rowData;
+				instanceData.rowIndex = i;
+				rowData.retain?.(i);
+				instanceData.data["id"] = taggedId;
+				this.#doRegister(entity, taggedId, meta, true);
+			} else if (overwriteExisting) {
+				const instanceData = require_BaseEntity.getInstanceData(entity);
+				instanceData.rowData = rowData;
+				instanceData.rowIndex = i;
+				rowData.retain?.(i);
+				const { data } = instanceData;
+				const dataKeys = Object.keys(data);
+				if (dataKeys.length > ("id" in data ? 1 : 0)) {
+					const allFields = require_EntityMetadata.getMetadata(entity).allFields;
+					const changedFields = instanceData.isNewEntity ? entity.changes.fieldsWithoutRelations : Object.keys(instanceData.originalData);
+					for (const fieldName of dataKeys) {
+						if (fieldName === "id") continue;
+						data[fieldName] = (allFields[fieldName].serde ?? require_utils.fail(`Missing serde for ${fieldName}`)).fromRow(rowData, i);
+						if (changedFields.includes(fieldName)) instanceData.markFieldClean(fieldName);
+					}
+				}
+			}
+			entities[i] = entity;
+		}
+		return entities;
+	}
+	touch(entityOrEntities) {
+		for (const entity of require_utils.toArray(entityOrEntities)) require_BaseEntity.getInstanceData(entity).markTouched();
+	}
+	async recalc(entityOrEntities, reactionName) {
+		const entities = require_utils.toArray(entityOrEntities).filter((entity) => !entity.isDeletedEntity);
+		if (reactionName !== void 0) {
+			const reactions = entities.map((entity) => {
+				return require_EntityMetadata.getBaseAndSelfMetas(require_EntityMetadata.getMetadata(entity)).flatMap((meta) => meta.config.__data.reactions).find((reaction) => reaction.name === reactionName) ?? require_utils.fail(`Reaction '${reactionName}' not found on ${require_EntityMetadata.getMetadata(entity).type}`);
+			});
+			await require_trusted.runInTrustedContext(() => Promise.allSettled(reactions.map((reaction, i) => reaction.fn(entities[i], this.ctx))).then(require_utils.failIfAnyRejected));
+			await this.#rm.recalcPendingReactables("reactables");
+			return;
+		}
+		const relations = entities.flatMap((entity) => Object.values(require_EntityMetadata.getMetadata(entity).allFields).filter((f) => "derived" in f && f.derived === "async").map((field) => entity[field.fieldName]));
+		const results = await Promise.allSettled(relations.map((r) => r.load({ forceReload: true })));
+		const relationsPendingAssignedIds = [];
+		const failures = [];
+		results.forEach((result, i) => {
+			if (result.status === "rejected") {
+				if (result.reason instanceof require_index.NoIdError) relationsPendingAssignedIds.push(relations[i]);
+				else failures.push(result.reason);
+			}
+		});
+		if (relationsPendingAssignedIds.length > 0) {
+			await this.assignNewIds();
+			(await Promise.allSettled(relationsPendingAssignedIds.map((r) => r.load({ forceReload: true })))).forEach((result) => {
+				if (result.status === "rejected") failures.push(result.reason);
+			});
+		}
+		if (failures.length > 0) throw failures[0];
+		entities.flatMap((entity) => Object.values(require_EntityMetadata.getMetadata(entity).allFields).filter((f) => "derived" in f && f.derived === "sync").forEach((field) => {
+			require_fields.setField(entity, field.fieldName, entity[field.fieldName]);
+		}));
+		await this.#rm.recalcPendingReactables("reactables");
+	}
+	beforeBegin(fn) {
+		this.#hooks.beforeBegin.push(fn);
+	}
+	afterBegin(fn) {
+		this.#hooks.afterBegin.push(fn);
+	}
+	beforeCommit(fn) {
+		this.#hooks.beforeCommit.push(fn);
+	}
+	afterCommit(fn) {
+		this.#hooks.afterCommit.push(fn);
+	}
+	/**
+	* Returns an EntityManager-scoped (i.e. request scoped) data loader.
+	*
+	* @param operation the operation being batched, i.e. `load` or `o2m-load`, to avoid clashing batch keys
+	*   across fundamentally different operations
+	* @param batchKey for a given operation, i.e. `load`, a batch key `Author` to batch all Author loads together
+	* @param fn the batch load function, i.e. that will accept all `.load(...)`-d Author ids to load as a single db call
+	* @param opts optional DataLoader options
+	* @returns a DataLoader scoped to the `operation` + `batchKey` combination
+	*/
+	getLoader(operation, batchKey, fn, opts) {
+		const loadersForKind = this.#dataloaders[operation] ??= {};
+		return require_utils.getOrSet(loadersForKind, batchKey, () => new dataloader.default(fn, opts));
+	}
+	/**
+	* Like `getLoader`, but returns a `BatchLoader` where all callers in the same tick
+	* share a single `Promise<void>` instead of getting per-key promises.
+	*
+	* The batch function should write results via side channels (e.g. `setPreloadedRelation`).
+	*/
+	getBatchLoader(operation, batchKey, fn) {
+		const loadersForKind = this.#batchLoaders[operation] ??= {};
+		return require_utils.getOrSet(loadersForKind, batchKey, () => new require_batchloaders_BatchLoader.BatchLoader(fn));
+	}
+	toString() {
+		return "EntityManager";
+	}
+	/** Recursively cascades any pending deletions. */
+	async flushDeletes() {
+		let entities = this.#pendingDeletes;
+		if (entities.length === 0) return;
+		this.#pendingDeletes = [];
+		let relationsToCleanup = [];
+		while (entities.length > 0) {
+			const p = entities.flatMap(getCascadeDeleteRelations).map((r) => r.load().then(() => r.maybeCascadeDelete()));
+			await Promise.all(p);
+			const todos = require_flush_Todo.createTodos(entities);
+			await beforeDelete(this.ctx, todos);
+			for (const entity of entities) {
+				const relations = require_index.getRelations(entity);
+				const start = relationsToCleanup.length;
+				relationsToCleanup.length += relations.length;
+				for (let i = 0; i < relations.length; i++) relationsToCleanup[start + i] = relations[i];
+			}
+			entities = this.#pendingDeletes;
+			this.#pendingDeletes = [];
+		}
+		await Promise.all(relationsToCleanup.map((r) => r.cleanupOnEntityDeleted()));
+	}
+	setReactionLogging(arg) {
+		this.#rm.setLogger(typeof arg === "boolean" ? arg ? new require_logging_ReactionLogger.ReactionLogger() : void 0 : arg);
+	}
+	setFieldLogging(arg) {
+		if (arg instanceof require_logging_FieldLogger.FieldLogger) {
+			this.#fieldLogger = arg;
+			return;
+		}
+		const writeFn = getDefaultWriteFn(this.ctx);
+		if (typeof arg === "boolean") this.#fieldLogger = arg ? new require_logging_FieldLogger.FieldLogger([], writeFn) : require_logging_FieldLogger.noopFieldLogger;
+		else if (typeof arg === "string" || Array.isArray(arg)) {
+			const watching = (Array.isArray(arg) ? arg : [arg]).map((spec) => {
+				const [_, entity, fields, breakpoint] = spec.match(/^([^.!]+)(?:\.([^!]*))?(!)?$/) ?? require_utils.fail(`Unsupported spec ${spec}`);
+				const fieldNames = fields?.split(",");
+				const meta = require_configure.getMetadataForType(entity);
+				fieldNames?.forEach((field) => {
+					if (!meta.allFields[field]) throw new Error(`Field ${field} not found on ${entity}`);
+				});
+				return {
+					entity,
+					fieldNames,
+					breakpoint: !!breakpoint
+				};
+			});
+			this.#fieldLogger = new require_logging_FieldLogger.FieldLogger(watching, writeFn);
+		} else throw new Error("Unsupported override for setFieldLogging");
+	}
+	async [Symbol.asyncDispose]() {
+		await this.flush();
+	}
+	/** Returns entities matching the filter using indexed search when available. */
+	filterEntities(cstr, where) {
+		const meta = require_EntityMetadata.getMetadata(cstr);
+		const entities = this.#entitiesByTag.get(meta.tagName) ?? [];
+		if (!require_utils.hasAnyKey(where)) return entities.filter((e) => e instanceof cstr && !e.isDeletedEntity);
+		if (this.#indexManager.shouldIndexType(entities.length)) {
+			this.#indexManager.enableIndexingForType(meta, entities, where);
+			const result = [];
+			for (const e of this.#indexManager.findMatching(meta, entities, where)) if (e instanceof cstr && !e.isDeletedEntity) result.push(e);
+			return result;
+		} else return entities.filter((e) => e instanceof cstr && !e.isDeletedEntity && require_dataloaders_findOrCreateDataLoader.entityMatches(e, where));
+	}
+	/**
+	* Creates a new EntityManager that shares the same entities as the current one but allows independent changes.
+	*
+	* This is useful for scenarios where you want to:
+	*
+	* - Preload data for use as a cache
+	* - Make speculative changes that may or may not be committed
+	* - Escape a transaction scope
+	*
+	* The fork will:
+	*
+	* - Copy all currently loaded entities to the new EntityManager
+	* - Copy any loaded relation data to keep `.isLoaded` / `.get` state consistent
+	* - Copy and update references to the EntityManager and its entities in the context, which is itself shallowly copied
+	*
+	* The fork will NOT:
+	*
+	* - Copy any pending changes (must call .flush() first)
+	* - Share any changes made in either EntityManager with the other
+	*
+	* @param opts options to control the fork behavior
+	*  - allowPendingChanges - allows the em being forked to have pending changes and forces the resulting em to have
+	*  `mode` set to "in-memory-writes".  Changes to entities in the original em will be copied to the resulting em.
+	*  Optional. default: false
+	*
+	* @throws {Error} If called on an EntityManager with pending changes
+	* @returns A new EntityManager with copied entity state
+	*/
+	fork(opts = {}) {
+		const { allowPendingChanges = false } = opts;
+		const oldEm = this;
+		const ctx = { ...oldEm.ctx };
+		const newEm = new EntityManager(ctx, { em: oldEm });
+		if (allowPendingChanges) newEm.mode = "in-memory-writes";
+		for (const [tag, entities] of oldEm.#entitiesByTag.entries()) {
+			const baseCstr = require_configure.getConstructorFromTag(tag);
+			let rows = new Array(entities.length);
+			let i = 0;
+			for (const entity of entities) {
+				const instanceData = entity.__data;
+				if (!allowPendingChanges && instanceData.pendingOperation !== "none") require_utils.fail("Cannot fork an EntityManager with pending changes");
+				else if (instanceData.isNewEntity) newEm.create(entity.constructor, {});
+				else {
+					rows[i] = createRowFromEntityData(entity);
+					i++;
+				}
+			}
+			if (rows.length !== i) rows = rows.slice(0, i);
+			newEm.hydrate(baseCstr, rows);
+		}
+		function mapEntity(oldEntity) {
+			if (oldEntity.isNewEntity) return newEm.#entitiesById.get(oldEntity.toTaggedString());
+			else return newEm.#entitiesById.get(oldEntity.idTagged);
+		}
+		function mapEntities(v) {
+			if (v === void 0) return void 0;
+			const result = new Array(v.length);
+			for (let i = 0; i < v.length; i++) result[i] = mapEntity(v[i]);
+			return result;
+		}
+		if (allowPendingChanges) for (const oldEntity of oldEm.entities) {
+			const oldInstanceData = oldEntity.__data;
+			if (!(oldInstanceData.isNewEntity || oldInstanceData.isDirtyEntity)) continue;
+			const { originalData: oldOriginalData, data: oldData } = oldInstanceData;
+			const newInstanceData = mapEntity(oldEntity).__data;
+			const { data: newData } = newInstanceData;
+			const maybeEntity = (value) => require_Entity.isEntity(value) ? mapEntity(value) : value;
+			const fields = Object.keys(oldEntity.isNewEntity ? oldData : oldOriginalData);
+			for (const field of fields) {
+				if (field in oldOriginalData) newInstanceData.markFieldDirty(field, maybeEntity(oldOriginalData[field]));
+				newData[field] = maybeEntity(oldData[field]);
+			}
+		}
+		for (const oldEntity of oldEm.entities) {
+			const newEntity = mapEntity(oldEntity);
+			if (oldEntity.isDeletedEntity) {
+				newEntity.__data.markDeleted();
+				continue;
+			}
+			const { relations } = oldEntity.__data;
+			if (!relations) continue;
+			for (const [field, relation] of Object.entries(relations)) {
+				if (!("import" in relation)) continue;
+				if (oldEntity.isNewEntity) {
+					const oldValue = relation.get;
+					if (oldValue === void 0) continue;
+					if (Array.isArray(oldValue) && oldValue.length === 0) continue;
+					const newValue = Array.isArray(oldValue) ? mapEntities(oldValue) : mapEntity(oldValue);
+					delete newEntity.__data.data[field];
+					newEntity[field].setFromOpts(newValue);
+				} else if ("_isLoaded" in relation ? relation._isLoaded : relation.isLoaded) newEntity[field].import(relation, mapEntity, mapEntities);
+			}
+		}
+		for (const [key, value] of Object.entries(ctx)) if (require_Entity.isEntity(value) && value.em === oldEm) ctx[key] = mapEntity(value);
+		else if (value === oldEm) ctx[key] = newEm;
+		return newEm;
+	}
+	importEntity(source, hint, normalizedHint) {
+		if (source.isNewEntity) require_utils.fail("cannot import new entities");
+		if (source.isDeletedEntity) require_utils.fail("cannot import deleted entities");
+		if (source.isDirtyEntity) require_utils.fail("cannot import dirty entities");
+		hint ??= {};
+		if (!normalizedHint) {
+			require_loading_loadHints.assertLoaded(source, hint);
+			normalizedHint = require_normalizeHints.deepNormalizeHint(hint);
+		}
+		if (source.em === this) return source;
+		const meta = require_EntityMetadata.getMetadata(source);
+		let result = this.#entitiesById.get(source.idTagged);
+		if (!result) {
+			const meta = require_EntityMetadata.getMetadata(source);
+			const row = createRowFromEntityData(source);
+			result = this.hydrate(require_EntityMetadata.getBaseMeta(meta).cstr, [row])[0];
+		}
+		for (const [fieldName, subHint] of Object.entries(normalizedHint)) {
+			const field = meta.allFields[fieldName];
+			const relationOrProp = result[fieldName];
+			if (!field) {
+				let loadHint = relationOrProp.loadHint ?? require_utils.fail(`${source}.${fieldName} cannot be imported as it has no loadHint`);
+				this.importEntity(source, loadHint);
+			} else if ("import" in relationOrProp) relationOrProp.import(source[fieldName], (e) => this.importEntity(e, subHint, subHint), (entities) => {
+				if (entities === void 0) return void 0;
+				const result = new Array(entities.length);
+				for (let i = 0; i < entities.length; i++) result[i] = this.importEntity(entities[i], subHint, subHint);
+				return result;
+			});
+		}
+		return result;
+	}
+	addPlugin(plugin) {
+		getEmInternalApi(this).pluginManager.addPlugin(plugin);
+	}
+	getPlugins() {
+		return getEmInternalApi(this).pluginManager.plugins;
+	}
+	get isRefreshing() {
+		return this.#isRefreshing;
+	}
+	get isFlushing() {
+		return this.#fl.isFlushing;
+	}
+	/** Creates a new `type` and marks it as loaded, i.e. we know its collections are all safe to access in memory. */
+	#doCreate(type, opts, partial) {
+		const entity = require_newEntity.newEntity(this, type, true);
+		const meta = require_EntityMetadata.getMetadata(type);
+		const counter = this.#createCounter ??= /* @__PURE__ */ new Map();
+		const i = (counter.get(meta.tagName) ?? 0) + 1;
+		counter.set(meta.tagName, i);
+		require_BaseEntity.getInstanceData(entity).createId = String(i);
+		this.#doRegister(entity, opts.id);
+		const baseMeta = require_EntityMetadata.getBaseMeta(require_EntityMetadata.getMetadata(entity));
+		if (baseMeta.timestampFields) this.#assignTimestamps(entity, baseMeta);
+		if (baseMeta.inheritanceType === "sti") setStiDiscriminatorValue(baseMeta, entity);
+		getEmInternalApi(this)?.fieldLogger.logCreate(entity);
+		require_index.setOpts(entity, opts, {
+			partial,
+			calledFromConstructor: true
+		});
+		if (!this.fakeInstance) require_defaults.setSyncDefaults(entity);
+		this.#rm.queueAllDownstreamFields(entity, "created");
+		return entity;
+	}
+	#assignTimestamps(entity, baseMeta) {
+		const { createdAt, updatedAt } = baseMeta.timestampFields ?? {};
+		const { data } = require_BaseEntity.getInstanceData(entity);
+		const now = /* @__PURE__ */ new Date();
+		if (createdAt) data[createdAt] = baseMeta.fields[createdAt].serde.mapFromNow(now);
+		if (updatedAt) data[updatedAt] = baseMeta.fields[updatedAt].serde.mapFromNow(now);
+	}
+	/** Registers a newly-instantiated entity with our EntityManager; only called by #doCreate and hydrate. */
+	#doRegister(entity, id, meta, skipDuplicateCheck = false) {
+		const maybeId = id ?? entity.idTaggedMaybe;
+		if (maybeId) {
+			if (!skipDuplicateCheck && this.findExistingInstance(maybeId) !== void 0) throw new Error(`Entity ${entity} has a duplicate instance already loaded`);
+			this.#entitiesById.set(maybeId, entity);
+		} else this.#entitiesById.set(entity.toTaggedString(), entity);
+		require_BaseEntity.getInstanceData(entity).entityIndex = this.#entitiesArray.length;
+		this.#entitiesArray.push(entity);
+		meta ??= require_EntityMetadata.getMetadata(entity);
+		const set = this.#entitiesByTag.get(meta.tagName) ?? [];
+		if (set.length === 0) this.#entitiesByTag.set(meta.tagName, set);
+		set.push(entity);
+		if (this.#entitiesArray.length >= this.entityLimit) {
+			const topTypes = [...this.#entitiesByTag.entries()].map(([tag, entities]) => ({
+				tag,
+				count: entities.length
+			})).sort((a, b) => b.count - a.count).slice(0, 3).map(({ tag, count }) => `${tag}=${count}`).join(", ");
+			throw new Error(`More than ${this.entityLimit} entities have been instantiated (top entities: ${topTypes})`);
+		}
+	}
+};
+function getEmInternalApi(em) {
+	return em["__api"];
+}
+let defaultEntityLimit = 5e4;
+function getDefaultEntityLimit() {
+	return defaultEntityLimit;
+}
+function setDefaultEntityLimit(limit) {
+	defaultEntityLimit = limit;
+}
+function resetDefaultEntityLimit() {
+	defaultEntityLimit = 5e4;
+}
+function isKey(k) {
+	return typeof k === "string";
+}
+/** Compares `a` to `b`, where `b` might be an id. */
+function sameEntity(a, b) {
+	if (a === b) return true;
+	if (a === void 0 || b === void 0 || a === null || b === null) return (a === void 0 || a === null) && (b === void 0 || b === null);
+	if (require_Entity.isEntity(a) && require_Entity.isEntity(b)) return a === b;
+	return (require_Entity.isEntity(a) ? a.idTaggedMaybe : a) === (require_Entity.isEntity(b) ? b.idTaggedMaybe : b);
+}
+/** Compares the value `a` to `b`, with handling of new entities w/o ids assigned yet. */
+function sameReference(a, b) {
+	return sameEntity(require_relations_Reference.isLoadedReference(a) ? a.get : a.idTaggedMaybe, require_relations_Reference.isLoadedReference(b) ? b.get : b.idTaggedMaybe);
+}
+/** Thrown by `findOneOrFail`, 'load' & 'loadAll' if an entity is not found. */
+var NotFoundError = class extends Error {};
+/** Thrown by `findOne` and `findOneOrFail` if more than one entity is found. */
+var TooManyError = class extends Error {
+	constructor(message) {
+		super(message);
+	}
+};
+/**
+* For the entities currently in `todos`, find any reactive validation rules that point
+* from the currently-changed entities back to each rule's originally-defined-in entity,
+* and ensure those entities are added to `todos`.
+*/
+async function validateReactiveRules(em, logger, todos, joinRowTodos, getRules = (meta) => meta.reactiveRules) {
+	logger.logStartingValidate(em, todos);
+	const fns = /* @__PURE__ */ new Map();
+	const walks = [];
+	async function followAndQueue(triggered, rule) {
+		if (triggered.length === 0) return;
+		const found = (await require_reactivity_reactiveHints.followReverseHint(rule.name, triggered, rule.path)).filter((entity) => !entity.isDeletedEntity).filter((e) => e instanceof rule.cstr);
+		let entities = fns.get(rule.fn);
+		if (!entities) {
+			entities = /* @__PURE__ */ new Set();
+			fns.set(rule.fn, entities);
+		}
+		walks.push({
+			todo: triggered,
+			r: rule,
+			entities: found
+		});
+		found.forEach((entity) => {
+			entities.add(entity);
+		});
+	}
+	const p1 = Object.values(todos).flatMap((todo) => {
+		const rules = getRules(todo.metadata);
+		if (rules.length === 0) return [];
+		const entities = [
+			...todo.inserts,
+			...todo.updates,
+			...todo.deletes
+		];
+		return rules.map((rule) => {
+			return followAndQueue(entities.filter((e) => {
+				if (!(e instanceof rule.source)) return false;
+				if (e.isNewEntity || e.isDeletedEntity) return true;
+				const { originalData } = require_BaseEntity.getInstanceData(e);
+				for (const field of rule.fields) if (field in originalData) return true;
+				return false;
+			}), rule);
+		});
+	});
+	const p2 = Object.values(joinRowTodos).flatMap((todo) => {
+		const entities = [...todo.newRows, ...todo.deletedRows].flatMap((jr) => Object.values(jr.columns)).filter(require_Entity.isEntity);
+		const a = getRules(todo.m2m.meta).filter((rule) => rule.fields.includes(todo.m2m.fieldName)).map((rule) => {
+			return followAndQueue(entities.filter((e) => e instanceof todo.m2m.meta.cstr), rule);
+		});
+		const { otherMeta, otherFieldName } = todo.m2m;
+		const b = otherMeta ? getRules(otherMeta).filter((rule) => rule.fields.includes(otherFieldName)).map((rule) => {
+			return followAndQueue(entities.filter((e) => e instanceof otherMeta.cstr), rule);
+		}) : [];
+		return [...a, ...b];
+	});
+	require_utils.failIfAnyRejected(await Promise.allSettled([...p1, ...p2]));
+	logger.logWalks(walks, "validate");
+	const p3 = [...fns.entries()].flatMap(([fn, entities]) => [...entities].map(async (entity) => coerceError(entity, await fn(entity))));
+	const errors = require_utils.failIfAnyRejected(await Promise.allSettled(p3)).flat();
+	if (errors.length > 0) throw new require_rules.ValidationErrors(errors);
+}
+async function validateSimpleRules(todos, getRules = (config) => config.rules) {
+	let p = void 0;
+	for (const todoKey in todos) {
+		const { inserts, updates } = todos[todoKey];
+		for (const entities of [inserts, updates]) for (const entity of entities) {
+			if (entity.isDeletedEntity) continue;
+			for (const m of require_EntityMetadata.getBaseAndSelfMetas(require_EntityMetadata.getMetadata(entity))) for (const rule of getRules(m.config.__data)) {
+				if (rule.hint !== void 0) continue;
+				(p ??= []).push(invokeRule(entity, rule.fn));
+			}
+		}
+	}
+	if (!p) return;
+	const errors = require_utils.failIfAnyRejected(await Promise.allSettled(p)).flat();
+	if (errors.length > 0) throw new require_rules.ValidationErrors(errors);
+}
+/** Invokes a single validation rule, coercing its result/sync throws into a promise. */
+async function invokeRule(entity, fn) {
+	return coerceError(entity, await fn(entity));
+}
+function driverBeforeBegin(em, txn) {
+	return Promise.all(getEmInternalApi(em).hooks.beforeBegin.map((fn) => fn(em, txn)));
+}
+function driverAfterBegin(em, txn) {
+	return Promise.all(getEmInternalApi(em).hooks.afterBegin.map((fn) => fn(em, txn)));
+}
+function driverBeforeCommit(em, txn) {
+	return Promise.all(getEmInternalApi(em).hooks.beforeCommit.map((fn) => fn(em, txn)));
+}
+function driverAfterCommit(em, txn) {
+	return Promise.all(getEmInternalApi(em).hooks.afterCommit.map((fn) => fn(em, txn)));
+}
+async function runHookOnTodos(ctx, hook, todos, keys) {
+	let entities = void 0;
+	for (const todoKey in todos) {
+		const todo = todos[todoKey];
+		if (!metaHasHook(todo.metadata, hook)) continue;
+		for (const k of keys) for (const e of todo[k]) {
+			if (k !== "deletes" && e.isDeletedEntity) continue;
+			(entities ??= []).push(e);
+		}
+	}
+	if (entities) return runHook(ctx, hook, entities);
+}
+/** Returns whether `meta`'s base/self/sub hierarchy has any `hook` functions registered. */
+function metaHasHook(meta, hook) {
+	for (const m of require_EntityMetadata.getBaseSelfAndSubMetas(meta)) if (m.config.__data.hooks[hook].length > 0) return true;
+	return false;
+}
+async function runHook(ctx, hook, entities) {
+	let p = void 0;
+	for (const entity of entities) for (const m of require_EntityMetadata.getBaseAndSelfMetas(require_EntityMetadata.getMetadata(entity))) for (const fn of m.config.__data.hooks[hook]) (p ??= []).push(invokeHook(fn, entity, ctx));
+	if (!p) return;
+	const results = await Promise.allSettled(p);
+	require_utils.failIfAnyRejected(results);
+}
+/** Invokes a single hook fn, coercing sync throws into rejections. */
+async function invokeHook(fn, entity, ctx) {
+	return fn(entity, ctx);
+}
+function beforeDelete(ctx, todos) {
+	return runHookOnTodos(ctx, "beforeDelete", todos, ["deletes"]);
+}
+function beforeFlush(ctx, todos) {
+	return runHookOnTodos(ctx, "beforeFlush", todos, ["inserts", "updates"]);
+}
+function beforeCreate(ctx, todos) {
+	return runHookOnTodos(ctx, "beforeCreate", todos, ["inserts"]);
+}
+function beforeUpdate(ctx, todos) {
+	return runHookOnTodos(ctx, "beforeUpdate", todos, ["updates"]);
+}
+function afterValidation(ctx, todos) {
+	return runHookOnTodos(ctx, "afterValidation", todos, ["inserts", "updates"]);
+}
+/** Collects changed entities from flush todos, i.e. m2m endpoint entities. */
+function entitiesFromTodos(entityTodos, joinRowTodos) {
+	const entities = /* @__PURE__ */ new Set();
+	for (const todo of Object.values(entityTodos)) for (const list of [
+		todo.inserts,
+		todo.updates,
+		todo.deletes
+	]) for (const entity of list) entities.add(entity);
+	for (const todo of Object.values(joinRowTodos)) for (const rows of [todo.newRows, todo.deletedRows]) for (const row of rows) for (const value of Object.values(row.columns)) if (require_Entity.isEntity(value)) entities.add(value);
+	return [...entities];
+}
+function beforeCommit(ctx, entities) {
+	return runHook(ctx, "beforeCommit", [...entities]);
+}
+function afterCommit(ctx, entities) {
+	return runHook(ctx, "afterCommit", [...entities]);
+}
+/** Given a validation rule result `maybeError`, returns a canonical `ValidationError[]`. */
+function coerceError(entity, maybeError) {
+	if (maybeError === void 0) return [];
+	else if (typeof maybeError === "string") return [{
+		entity,
+		message: maybeError
+	}];
+	else if (Array.isArray(maybeError)) return maybeError.map((e) => {
+		if (typeof e === "string") return {
+			entity,
+			message: e
+		};
+		else return {
+			entity,
+			...e
+		};
+	});
+	else return [{
+		entity,
+		...maybeError
+	}];
+}
+/** Evaluates each (non-async) derived field to see if it's value has changed. */
+function recalcSynchronousDerivedFields(todos) {
+	for (const todoKey in todos) {
+		const todo = todos[todoKey];
+		for (const entities of [todo.inserts, todo.updates]) for (const entity of entities) {
+			if (entity.isDeletedEntity) continue;
+			for (const fieldName of require_EntityMetadata.getMetadata(entity).syncDerivedFields) require_fields.setField(entity, fieldName, entity[fieldName]);
+		}
+	}
+}
+/** Recursively crawls through `entity`, with the given populate `deep` hint, and adds anything found to `found`. */
+async function crawl(found, skipMap, entities, deep, opts = {}) {
+	const { skipIf = () => false } = opts ?? {};
+	const skip = require_normalizeHints.deepNormalizeHint(opts.skip ?? {});
+	const skipFields = Object.keys(skip).filter((key) => Object.keys(skip[key]).length === 0);
+	const entitiesToClone = entities.filter((e) => !skipIf(e));
+	for (const entity of entitiesToClone) {
+		found.add(entity);
+		skipMap.set(entity, skipFields);
+	}
+	await Promise.all(entitiesToClone.flatMap((entity) => Object.entries(adaptHint(deep)).map(async ([relationName, nested]) => {
+		const relation = entity[relationName];
+		const _opts = {
+			...opts,
+			skip: skip[relationName]
+		};
+		if (relation instanceof require_relations_OneToManyCollection.OneToManyCollection) await crawl(found, skipMap, await relation.load(), nested, _opts);
+		else if (relation instanceof require_relations_OneToOneReference.OneToOneReferenceImpl) {
+			const related = await relation.load();
+			if (related) await crawl(found, skipMap, [related], nested, _opts);
+		} else if (relation instanceof require_relations_ManyToOneReference.ManyToOneReferenceImpl) {
+			const related = await relation.load();
+			if (related) await crawl(found, skipMap, [related], nested, _opts);
+		} else if (relation instanceof require_relations_ReactiveReference.ReactiveReferenceImpl) await crawl(found, skipMap, await relation.load(), nested, _opts);
+		else require_utils.fail(`Uncloneable relation: ${relationName}`);
+	})));
+}
+/** Takes our flexible string or array or hash load hint and makes it always a hash. */
+function adaptHint(hint) {
+	if (typeof hint === "string") return { [hint]: {} };
+	else if (Array.isArray(hint)) return Object.fromEntries(hint.map((relation) => [relation, {}]));
+	else if (hint) return hint;
+	else return {};
+}
+function isDefined(param) {
+	return param !== null && param !== void 0;
+}
+function getCascadeDeleteRelations(entity) {
+	return require_EntityMetadata.getBaseAndSelfMetas(require_EntityMetadata.getMetadata(entity)).flatMap((meta) => {
+		return meta.config.__data.cascadeDeleteFields.map((fieldName) => entity[fieldName]);
+	});
+}
+function isCustomRelation(r) {
+	return r instanceof require_relations_CustomCollection.CustomCollection || r instanceof require_relations_CustomReference.CustomReference || r instanceof require_relations_ReactiveReference.ReactiveReferenceImpl;
+}
+function maybeBumpUpdatedAt(rm, todos, now) {
+	for (const todo of Object.values(todos)) {
+		const { updatedAt } = todo.metadata.timestampFields ?? {};
+		if (updatedAt) for (const e of todo.updates) {
+			const orm = require_BaseEntity.getInstanceData(e);
+			orm.markFieldDirty(updatedAt, require_fields.getField(e, updatedAt));
+			const serde = todo.metadata.fields[updatedAt].serde;
+			orm.data[updatedAt] = serde.mapFromNow(now);
+			rm.queueDownstreamReactables(e, updatedAt);
+		}
+	}
+}
+let lastNow = void 0;
+function setLastNow(now) {
+	lastNow = now;
+}
+function getNow() {
+	let now = /* @__PURE__ */ new Date();
+	if (lastNow && (lastNow.getTime() === now.getTime() || now.getTime() < lastNow.getTime())) now = new Date(lastNow.getTime() + 1);
+	lastNow = now;
+	return now;
+}
+/** Given a `row` from the db, resolves the CTI/STI subtype, if applicable. */
+function findConcreteMeta(maybeBaseMeta, rowData, rowIndex) {
+	if (maybeBaseMeta.inheritanceType === void 0) return maybeBaseMeta;
+	const __class = rowData.get(rowIndex, "__class");
+	if (!__class && maybeBaseMeta.inheritanceType !== "sti") return maybeBaseMeta;
+	if (__class) {
+		if (__class === "_" && maybeBaseMeta.ctiAbstract) {
+			const id = rowData.get(rowIndex, "id");
+			throw new Error(`${maybeBaseMeta.type} ${require_keys.tagId(maybeBaseMeta, id)} must be instantiated via a subtype`);
+		}
+		return maybeBaseMeta.subTypesByType.get(__class) ?? maybeBaseMeta;
+	} else if (maybeBaseMeta.inheritanceType === "sti") {
+		const baseMeta = require_EntityMetadata.getBaseMeta(maybeBaseMeta);
+		const value = rowData.get(rowIndex, baseMeta.stiDiscriminatorColumnName);
+		return baseMeta.subTypesByStiValue.get(value) ?? baseMeta;
+	} else throw new Error("Unknown inheritance type");
+}
+/** Sets the `Animal.type` enum to the right subtype value. */
+function setStiDiscriminatorValue(baseMeta, entity) {
+	const typeName = entity.constructor.name;
+	const st = baseMeta.subTypesByType.get(typeName);
+	if (st) {
+		const code = baseMeta.fields[baseMeta.stiDiscriminatorField].enumDetailType.findById(st.stiDiscriminatorValue).code;
+		entity[baseMeta.stiDiscriminatorField] = code;
+	} else entity[baseMeta.stiDiscriminatorField] = void 0;
+}
+function findPendingFlushEntities(maybePendingFlushEntities, hooksInvoked, pendingFlush, pendingHooks, alreadyRanHooks) {
+	for (const e of maybePendingFlushEntities) {
+		if (require_BaseEntity.getInstanceData(e).pendingOperation === "none") {
+			maybePendingFlushEntities.delete(e);
+			continue;
+		}
+		if (!hooksInvoked.has(e)) pendingHooks.add(e);
+		else alreadyRanHooks.add(e);
+		pendingFlush.add(e);
+	}
+}
+/** Returns true if the caller explicitly asked `find` to use SQL pagination. */
+function hasPaginationSettings(options) {
+	return "limit" in options || "offset" in options;
+}
+/** An error we throw to get knex to `ROLLBACK`, but then catch. */
+var InMemoryRollbackError = class extends Error {};
+/** An error thrown when `em.mode === "read-only"` but entities are mutated/flushed. */
+var ReadOnlyError = class extends Error {
+	constructor() {
+		super("EntityManager is read-only");
+	}
+};
+function maybeSetupHookOrdering(todos) {
+	const group1 = {};
+	const group2 = {};
+	for (const todo of Object.values(todos)) {
+		const group = todo.metadata.config.__data.runHooksBefore.some((cstr) => require_EntityMetadata.getBaseMeta(require_EntityMetadata.getMetadata(cstr)).type in todos) ? group1 : group2;
+		group[todo.metadata.type] = todo;
+	}
+	return Object.keys(group1).length ? [group1, group2] : [group2];
+}
+/**
+* Given an `err` thrown in "a different context", i.e. a database error or dataloader error
+* that doesn't include our stack trace, append our stack for better debugging.
+*
+* See https://github.com/brianc/node-postgres/pull/2983
+*/
+function appendStack(err, dummy) {
+	if (err && typeof err === "object" && "stack" in err) err.stack += dummy.stack.replace(/.*\n/, "\n");
+	return err;
+}
+/** Probe for `ctx.logger.debug` if it exists, otherwise fallback on `console.log`. */
+function getDefaultWriteFn(ctx) {
+	return ctx && typeof ctx === "object" && "logger" in ctx && ctx.logger && typeof ctx.logger === "object" && "debug" in ctx.logger && ctx.logger.debug instanceof Function ? ctx.logger.debug.bind(ctx.logger) : console.log;
+}
+const fieldMap = {};
+function createRowFromEntityData(e, opts = {}) {
+	const { preferOriginalData = true } = opts;
+	const { rowData, rowIndex, data, originalData } = e.__data;
+	const __class = e.constructor.name;
+	const { metadata: meta } = e.__data;
+	if (!fieldMap[__class]) {
+		fieldMap[__class] = [];
+		for (const field of Object.values(meta.allFields)) {
+			if (!field.serde) continue;
+			for (const column of field.serde.columns) fieldMap[__class].push([field, column]);
+		}
+	}
+	const row = meta.inheritanceType === "cti" ? { __class } : {};
+	for (const [field, column] of fieldMap[__class]) {
+		const value = field.fieldName in originalData || field.fieldName in data ? column.rowValue(preferOriginalData && field.fieldName in originalData ? originalData : data) : rowData.get(rowIndex, column.columnName);
+		row[column.columnName] = value ?? null;
+	}
+	return row;
+}
+//#endregion
+exports.EntityManager = EntityManager;
+exports.NotFoundError = NotFoundError;
+exports.ReadOnlyError = ReadOnlyError;
+exports.TooManyError = TooManyError;
+exports.appendStack = appendStack;
+exports.createRowFromEntityData = createRowFromEntityData;
+exports.driverAfterBegin = driverAfterBegin;
+exports.driverAfterCommit = driverAfterCommit;
+exports.driverBeforeBegin = driverBeforeBegin;
+exports.driverBeforeCommit = driverBeforeCommit;
+exports.getDefaultEntityLimit = getDefaultEntityLimit;
+exports.getEmInternalApi = getEmInternalApi;
+exports.isDefined = isDefined;
+exports.isId = isId;
+exports.isKey = isKey;
+exports.resetDefaultEntityLimit = resetDefaultEntityLimit;
+exports.sameEntity = sameEntity;
+exports.sameReference = sameReference;
+exports.setDefaultEntityLimit = setDefaultEntityLimit;
+exports.setLastNow = setLastNow;
+
+//# sourceMappingURL=EntityManager.cjs.map