joist-core 2.3.0 → 2.4.0-next.10

package/build/flush/JoinRows.cjs

@@ -0,0 +1,263 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_keys = require("../keys.cjs");
+const require_utils = require("../utils.cjs");
+const require_EntityMetadata = require("../EntityMetadata.cjs");
+const require_EntityManager = require("../EntityManager.cjs");
+//#region src/flush/JoinRows.ts
+/** Whether a join column points at a not-yet-inserted entity (enum ids are never "new"). */
+function isNewColumn(value) {
+	return typeof value !== "number" && value.isNewEntity;
+}
+/** A small holder around m2m join rows, which we treat as psuedo-entities. */
+var JoinRows = class {
+	m2m;
+	rm;
+	rows = [];
+	index;
+	constructor(m2m, rm) {
+		this.m2m = m2m;
+		this.rm = rm;
+		this.index = new ManyToManyIndex(m2m);
+	}
+	/** Adds a new join row to this table. */
+	addNew(m2m, e1, e2) {
+		if (!e1) throw new Error(`Cannot add a m2m row with an entity that is ${e1}`);
+		if (!e2) throw new Error(`Cannot add a m2m row with an entity that is ${e2}`);
+		const existing = this.index.get(m2m, e1, e2);
+		if (existing) {
+			existing.deleted = false;
+			existing.op = "pending";
+		} else {
+			const row = {
+				op: "pending",
+				id: void 0,
+				persisted: false,
+				columns: {
+					[m2m.columnName]: e1,
+					[m2m.otherColumnName]: e2
+				}
+			};
+			this.rows.push(row);
+			this.index.add(m2m, e1, e2, row);
+		}
+		this.#reactToChange(m2m, e1, e2);
+	}
+	/** Adds a new remove to this table. */
+	addRemove(m2m, e1, e2) {
+		const existing = this.index.get(m2m, e1, e2);
+		if (existing) {
+			if (!existing.persisted) {
+				require_utils.remove(this.rows, existing);
+				this.index.remove(existing);
+			} else existing.deleted = true;
+			existing.op = "pending";
+		} else {
+			const row = {
+				op: "pending",
+				id: void 0,
+				persisted: true,
+				columns: {
+					[m2m.columnName]: e1,
+					[m2m.otherColumnName]: e2
+				},
+				deleted: true
+			};
+			this.rows.push(row);
+			this.index.add(m2m, e1, e2, row);
+		}
+		this.#reactToChange(m2m, e1, e2);
+	}
+	/** Return any "old values" for a m2m collection that might need reactivity checks. */
+	removedFor(m2m, e1) {
+		const { otherColumnName } = m2m;
+		return this.index.getOthers(m2m.columnName, e1).filter((r) => r.deleted).map((r) => r.columns[otherColumnName]);
+	}
+	addedFor(m2m, e1) {
+		const { otherColumnName } = m2m;
+		return this.index.getOthers(m2m.columnName, e1).filter((r) => (!r.persisted && r.op === "pending" || r.op === "flushed") && r.deleted !== true).map((r) => r.columns[otherColumnName]);
+	}
+	/** Adds an existing join row to this table. */
+	addPreloadedRow(m2m, id, e1, e2) {
+		if (this.index.get(m2m, e1, e2)) {} else {
+			const row = {
+				op: "pending",
+				id,
+				persisted: true,
+				columns: {
+					[m2m.columnName]: e1,
+					[m2m.otherColumnName]: e2
+				}
+			};
+			this.rows.push(row);
+			this.index.add(m2m, e1, e2, row);
+		}
+	}
+	/** Look up/create our internal JoinRow psuedo-entities for the db rows. */
+	async loadRows(tuples, dbRows) {
+		const { em } = this.m2m.entity;
+		const { columnName: column1, otherColumnName: column2, meta: meta1, otherMeta: meta2, otherEnum } = this.m2m;
+		const oneIds = [];
+		const twoVals = [];
+		for (const dbRow of dbRows) {
+			oneIds.push(require_keys.keyToTaggedId(meta1, dbRow[column1]));
+			twoVals.push(otherEnum ? dbRow[column2] : em.getEntity(require_keys.keyToTaggedId(meta2, dbRow[column2])));
+		}
+		await Promise.all([em.loadAll(meta1.cstr, oneIds), otherEnum ? Promise.resolve([]) : em.loadAll(meta2.cstr, dbRows.map((dbRow) => require_keys.keyToTaggedId(meta2, dbRow[column2])))]);
+		const existingRows = /* @__PURE__ */ new Set();
+		for (const [columnName, id] of tuples) {
+			const others = this.index.getOthers(columnName, em.getEntity(id));
+			for (const row of others) if (!otherEnum || row.persisted) existingRows.add(row);
+		}
+		let i = 0;
+		for (const dbRow of dbRows) {
+			const e1 = em.getEntity(oneIds[i]);
+			const e2 = otherEnum ? dbRow[column2] : em.getEntity(require_keys.keyToTaggedId(meta2, dbRow[column2]));
+			i++;
+			let row = this.index.get(this.m2m, e1, e2);
+			if (!row) {
+				row = {
+					op: "completed",
+					id: dbRow.id,
+					persisted: true,
+					columns: {
+						[column1]: e1,
+						[column2]: e2
+					},
+					created_at: dbRow.created_at
+				};
+				this.rows.push(row);
+				this.index.add(this.m2m, e1, e2, row);
+			} else {
+				row.id = dbRow.id;
+				row.persisted = true;
+				existingRows.delete(row);
+			}
+		}
+		for (const row of existingRows) row.deleted = true;
+	}
+	getOthers(columnName, entity) {
+		const others = this.index.getOthers(columnName, entity);
+		if (others.length === 0) return [];
+		const [c1, c2] = Object.keys(others[0].columns);
+		const c = others[0].columns[c1] === entity ? c2 : c1;
+		return others.filter((o) => !o.deleted).map((row) => row.columns[c]);
+	}
+	/** Drops all in-memory rows where `entity` is on `columnName`, e.g. when it is being deleted. */
+	removeAllFor(columnName, entity) {
+		for (const row of this.index.getOthers(columnName, entity)) {
+			require_utils.remove(this.rows, row);
+			this.index.remove(row);
+		}
+	}
+	/** Drops a single `(e1, e2)` row without queuing a flush, e.g. when mirroring another em's removal. */
+	removePreloadedRow(m2m, e1, e2) {
+		const row = this.index.get(m2m, e1, e2);
+		if (row) {
+			require_utils.remove(this.rows, row);
+			this.index.remove(row);
+		}
+	}
+	/** Scans our `rows` for newly-added/newly-deleted rows that need `INSERT`s/`UPDATE`s. */
+	toTodo() {
+		const newRows = this.rows.filter((r) => !r.persisted && r.deleted !== true && r.op === "pending");
+		const deletedRows = this.rows.filter((r) => r.persisted && r.deleted === true && r.op === "pending");
+		if (newRows.length === 0 && deletedRows.length === 0) return;
+		return {
+			m2m: this.m2m,
+			newRows,
+			deletedRows,
+			resetAfterFlushed: () => {
+				for (const row of this.rows) if (row.op === "pending" || row.op === "flushed") row.op = "completed";
+			},
+			dbValue: (row, columnName) => this.#dbValue(row, columnName),
+			isNew: (row, columnName) => isNewColumn(row.columns[columnName])
+		};
+	}
+	get hasChanges() {
+		return this.rows.some(({ op }) => op === "pending" || op === "flushed");
+	}
+	/** The db int value for `row`'s `columnName`: an entity's id, or (for enums) the enum's id itself. */
+	#dbValue(row, columnName) {
+		const value = row.columns[columnName];
+		if (typeof value === "number") return value;
+		const meta = columnName === this.m2m.columnName ? this.m2m.meta : this.m2m.otherMeta;
+		return require_keys.keyToNumber(meta, value.idTagged);
+	}
+	/**
+	* Invalidates caches & queues reactivity for a join-row change.
+	*
+	* The owning entity (`e1`) always reacts; the "other" side only reacts when it is an entity,
+	* since enum other-sides have no `em`/reverse-field to keep in sync.
+	*/
+	#reactToChange(m2m, e1, e2) {
+		const { em } = this.m2m.entity;
+		const api = require_EntityManager.getEmInternalApi(e1.em);
+		api.isLoadedCache.resetIsLoaded(e1, m2m.fieldName);
+		this.rm.queueDownstreamReactables(e1, m2m.fieldName);
+		if (require_EntityMetadata.getBaseAndSelfMetas(e1).some((meta) => meta.config.__data.touchOnChange.has(m2m.fieldName))) em.touch(e1);
+		if (!m2m.otherEnum) {
+			const other = e2;
+			const otherFieldName = m2m.otherFieldName;
+			api.isLoadedCache.resetIsLoaded(other, otherFieldName);
+			this.rm.queueDownstreamReactables(other, otherFieldName);
+			if (require_EntityMetadata.getBaseAndSelfMetas(other).some((meta) => meta.config.__data.touchOnChange.has(otherFieldName))) em.touch(other);
+		}
+	}
+};
+/** An enum to track our insert/delete state progression. */
+let JoinRowOperation = /* @__PURE__ */ function(JoinRowOperation) {
+	JoinRowOperation["Pending"] = "pending";
+	JoinRowOperation["Flushed"] = "flushed";
+	JoinRowOperation["Completed"] = "completed";
+	return JoinRowOperation;
+}({});
+/** Keep an in-memory index to avoid sequentially scanning `rows`. */
+var ManyToManyIndex = class {
+	m2m;
+	indexes = {};
+	constructor(m2m) {
+		this.m2m = m2m;
+		this.indexes[m2m.columnName] = /* @__PURE__ */ new Map();
+		this.indexes[m2m.otherColumnName] = /* @__PURE__ */ new Map();
+	}
+	add(m2m, e1, e2, value) {
+		this.#doAdd(this.indexes[m2m.columnName], e1, e2, value);
+		this.#doAdd(this.indexes[m2m.otherColumnName], e2, e1, value);
+	}
+	remove(value) {
+		const [[column1, e1], [column2, e2]] = Object.entries(value.columns);
+		this.#doRemove(this.indexes[column1], e1, e2);
+		this.#doRemove(this.indexes[column2], e2, e1);
+	}
+	get(m2m, e1, e2) {
+		return this.indexes[m2m.columnName].get(e1)?.get(e2);
+	}
+	/** Cheat and use the index to return "the other entities" for `entity`. */
+	getOthers(columnName, entity) {
+		const map = this.indexes[columnName].get(entity);
+		if (!map) return [];
+		const rows = Array.from(map.values());
+		if (this.m2m.hasJoinTableId) return rows.sort((a, b) => (a.id ?? Infinity) - (b.id ?? Infinity));
+		const otherColumn = columnName === this.m2m.columnName ? this.m2m.otherColumnName : this.m2m.columnName;
+		if (this.m2m.otherEnum && otherColumn === this.m2m.otherColumnName) return rows.sort((a, b) => a.columns[otherColumn] - b.columns[otherColumn]);
+		const otherMeta = columnName === this.m2m.columnName ? this.m2m.otherMeta : this.m2m.meta;
+		const key = (r) => {
+			const other = r.columns[otherColumn];
+			return other.isNewEntity ? Infinity : require_keys.keyToNumber(otherMeta, other.id);
+		};
+		return rows.sort((a, b) => key(a) - key(b));
+	}
+	#doAdd(index, e1, e2, value) {
+		const map = index.get(e1) ?? /* @__PURE__ */ new Map();
+		if (map.size === 0) index.set(e1, map);
+		map.set(e2, value);
+	}
+	#doRemove(index, e1, e2) {
+		index.get(e1)?.delete(e2);
+	}
+};
+//#endregion
+exports.JoinRowOperation = JoinRowOperation;
+exports.JoinRows = JoinRows;
+
+//# sourceMappingURL=JoinRows.cjs.map

package/build/flush/JoinRows.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"JoinRows.cjs","names":["#reactToChange","keyToTaggedId","#dbValue","keyToNumber","getEmInternalApi","getBaseAndSelfMetas","#doAdd","#doRemove"],"sources":["../../src/flush/JoinRows.ts"],"sourcesContent":["import type { Entity } from \"src/Entity.ts\";\nimport { getEmInternalApi } from \"src/EntityManager.ts\";\nimport { type EntityMetadata, getBaseAndSelfMetas } from \"src/EntityMetadata.ts\";\nimport type { EnumMetadata } from \"src/EnumMetadata.ts\";\nimport type { JoinRowTodo } from \"src/flush/Todo.ts\";\nimport { keyToNumber, keyToTaggedId } from \"src/keys.ts\";\nimport type { ReactionsManager } from \"src/reactivity/ReactionsManager.ts\";\nimport { remove } from \"src/utils.ts\";\n\n/**\n * A simplified interface for ManyToManyCollection-like relations.\n *\n * Specifically lets ReactiveManyToMany & ReactiveManyToManyOtherSide use JoinRows\n * as if they were full-fledged m2m relations.\n *\n * The \"other\" side of the join table is usually a second entity, but for `EnumCollection`s\n * (i.e. `Publisher.logoColors`) it is an enum table; in that case `otherEnum` is set and the\n * other column's value is the enum's numeric id rather than an `Entity` (there is also no\n * `otherMeta`/`otherFieldName`, since enums have no reverse collection to keep in sync).\n */\nexport type ManyToManyLike = {\n  entity: Entity;\n  joinTableName: string;\n  columnName: string;\n  otherColumnName: string;\n  fieldName: string;\n  meta: EntityMetadata;\n  /** Undefined when the other side is an enum. */\n  otherFieldName?: string;\n  /** Undefined when the other side is an enum. */\n  otherMeta?: EntityMetadata;\n  /** Set when the other side is an enum table, for mapping enum codes <-> their numeric ids. */\n  otherEnum?: EnumMetadata<any, any, number>;\n  /** Whether the join table has a surrogate `id` PK; if false the FK pair is the composite PK. */\n  hasJoinTableId: boolean;\n};\n\n/** The value of a join row's column: an `Entity`, or an enum's numeric id for `EnumCollection`s. */\nexport type JoinColumnValue = Entity | number;\n\n/** Whether a join column points at a not-yet-inserted entity (enum ids are never \"new\"). */\nfunction isNewColumn(value: JoinColumnValue): boolean {\n  return typeof value !== \"number\" && value.isNewEntity;\n}\n\n/** A small holder around m2m join rows, which we treat as psuedo-entities. */\nexport class JoinRows {\n  // The in-memory rows for our m2m table.\n  private readonly rows: JoinRow[] = [];\n  private readonly index: ManyToManyIndex;\n\n  constructor(\n    // This could be either side of the m2m relation, depending on which is accessed first.\n    // Regardless of which m2m side, we still have a single `JoinRows` instance in memory per m2m table.\n    readonly m2m: ManyToManyLike,\n    private rm: ReactionsManager,\n  ) {\n    this.index = new ManyToManyIndex(m2m);\n  }\n\n  /** Adds a new join row to this table. */\n  addNew(m2m: ManyToManyLike, e1: Entity, e2: JoinColumnValue): void {\n    if (!e1) throw new Error(`Cannot add a m2m row with an entity that is ${e1}`);\n    if (!e2) throw new Error(`Cannot add a m2m row with an entity that is ${e2}`);\n    const existing = this.index.get(m2m, e1, e2);\n    if (existing) {\n      existing.deleted = false;\n      existing.op = JoinRowOperation.Pending;\n    } else {\n      const row = {\n        op: JoinRowOperation.Pending,\n        id: undefined,\n        persisted: false,\n        columns: { [m2m.columnName]: e1, [m2m.otherColumnName]: e2 },\n      } satisfies JoinRow;\n      this.rows.push(row);\n      this.index.add(m2m, e1, e2, row);\n    }\n    this.#reactToChange(m2m, e1, e2);\n  }\n\n  /** Adds a new remove to this table. */\n  addRemove(m2m: ManyToManyLike, e1: Entity, e2: JoinColumnValue): void {\n    const existing = this.index.get(m2m, e1, e2);\n    if (existing) {\n      if (!existing.persisted) {\n        // It was only added in-memory and never persisted, so just drop it\n        remove(this.rows, existing);\n        this.index.remove(existing);\n      } else {\n        existing.deleted = true;\n      }\n      existing.op = JoinRowOperation.Pending;\n    } else {\n      // We're removing against an unloaded collection, so assume the row exists in the database\n      // (persisted: true) and queue a delete; the delete keys off the (col1, col2) composite.\n      const row = {\n        op: JoinRowOperation.Pending,\n        id: undefined,\n        persisted: true,\n        columns: { [m2m.columnName]: e1, [m2m.otherColumnName]: e2 },\n        deleted: true,\n      } satisfies JoinRow;\n      this.rows.push(row);\n      this.index.add(m2m, e1, e2, row);\n    }\n    this.#reactToChange(m2m, e1, e2);\n  }\n\n  /** Return any \"old values\" for a m2m collection that might need reactivity checks. */\n  removedFor(m2m: ManyToManyLike, e1: Entity): JoinColumnValue[] {\n    const { otherColumnName } = m2m;\n    // I.e. if we did `t1.books.remove(b1)` find all join rows that have\n    // `tag_id=t1`, are marked for deletion, and then `.map` them to the removed book.\n    const removedRows = this.index.getOthers(m2m.columnName, e1).filter((r) => r.deleted);\n    return removedRows.map((r) => r.columns[otherColumnName]);\n  }\n\n  addedFor(m2m: ManyToManyLike, e1: Entity): JoinColumnValue[] {\n    const { otherColumnName } = m2m;\n    const addedRows = this.index\n      .getOthers(m2m.columnName, e1)\n      .filter(\n        (r) =>\n          ((!r.persisted && r.op === JoinRowOperation.Pending) || r.op === JoinRowOperation.Flushed) &&\n          r.deleted !== true,\n      );\n    return addedRows.map((r) => r.columns[otherColumnName]);\n  }\n\n  /** Adds an existing join row to this table. */\n  addPreloadedRow(m2m: ManyToManyLike, id: number | undefined, e1: Entity, e2: JoinColumnValue): void {\n    const existing = this.index.get(m2m, e1, e2);\n    if (existing) {\n      // Treat any existing WIP change as source-of-truth, so leave it alone\n    } else {\n      const row = {\n        op: JoinRowOperation.Pending,\n        id,\n        persisted: true,\n        columns: { [m2m.columnName]: e1, [m2m.otherColumnName]: e2 },\n      } satisfies JoinRow;\n      this.rows.push(row);\n      this.index.add(m2m, e1, e2, row);\n    }\n  }\n\n  /** Look up/create our internal JoinRow psuedo-entities for the db rows. */\n  async loadRows(tuples: [string, string][], dbRows: any[]): Promise<void> {\n    const { em } = this.m2m.entity;\n    const { columnName: column1, otherColumnName: column2, meta: meta1, otherMeta: meta2, otherEnum } = this.m2m;\n\n    const oneIds: string[] = [];\n    // Tagged ids for an entity other-side, or raw enum ids for an enum other-side.\n    const twoVals: JoinColumnValue[] = [];\n    for (const dbRow of dbRows) {\n      oneIds.push(keyToTaggedId(meta1, dbRow[column1])!);\n      twoVals.push(\n        otherEnum ? (dbRow[column2] as number) : (em.getEntity(keyToTaggedId(meta2!, dbRow[column2])!) as any),\n      );\n    }\n\n    // Make sure we have entities in memory for all the joined-to tables. The enum side has no\n    // entities to load; the entity sides do (and `twoVals` is re-resolved to entities below).\n    await Promise.all([\n      em.loadAll(meta1.cstr, oneIds),\n      otherEnum\n        ? Promise.resolve([])\n        : em.loadAll(\n            meta2!.cstr,\n            dbRows.map((dbRow) => keyToTaggedId(meta2!, dbRow[column2])!),\n          ),\n    ]);\n\n    // If we're doing a em.refresh/reload, we need to watch for rows that are no longer here. For an\n    // enum other-side, only persisted rows are delete-candidates (pending in-memory adds are kept,\n    // since `EnumCollection` relies on `JoinRows` to hold them rather than re-asserting on load).\n    const existingRows = new Set<JoinRow>();\n    for (const [columnName, id] of tuples) {\n      const others = this.index.getOthers(columnName, em.getEntity(id)!);\n      for (const row of others) if (!otherEnum || row.persisted) existingRows.add(row);\n    }\n\n    let i = 0;\n    for (const dbRow of dbRows) {\n      const e1 = em.getEntity(oneIds[i])!;\n      const e2 = otherEnum ? (dbRow[column2] as number) : em.getEntity(keyToTaggedId(meta2!, dbRow[column2])!)!;\n      i++;\n      let row = this.index.get(this.m2m, e1, e2);\n      if (!row) {\n        row = {\n          op: JoinRowOperation.Completed,\n          id: dbRow.id,\n          persisted: true,\n          columns: { [column1]: e1, [column2]: e2 },\n          created_at: dbRow.created_at,\n        };\n        this.rows.push(row);\n        this.index.add(this.m2m, e1, e2, row);\n      } else {\n        // If a placeholder row was created while a ManyToManyCollection was unloaded, and we find it during\n        // a subsequent load/query, update its id to be what is in the database and mark it persisted.\n        row.id = dbRow.id;\n        row.persisted = true;\n        // Mark this row as still valid\n        existingRows.delete(row);\n      }\n    }\n\n    // Mark all no-longer-there rows as deleted\n    for (const row of existingRows) row.deleted = true;\n  }\n\n  getOthers(columnName: string, entity: Entity): JoinColumnValue[] {\n    const others = this.index.getOthers(columnName, entity);\n    if (others.length === 0) return [];\n    const [c1, c2] = Object.keys(others[0].columns);\n    const c = others[0].columns[c1] === entity ? c2 : c1;\n    return others.filter((o) => !o.deleted).map((row) => row.columns[c]);\n  }\n\n  /** Drops all in-memory rows where `entity` is on `columnName`, e.g. when it is being deleted. */\n  removeAllFor(columnName: string, entity: Entity): void {\n    for (const row of this.index.getOthers(columnName, entity)) {\n      remove(this.rows, row);\n      this.index.remove(row);\n    }\n  }\n\n  /** Drops a single `(e1, e2)` row without queuing a flush, e.g. when mirroring another em's removal. */\n  removePreloadedRow(m2m: ManyToManyLike, e1: Entity, e2: JoinColumnValue): void {\n    const row = this.index.get(m2m, e1, e2);\n    if (row) {\n      remove(this.rows, row);\n      this.index.remove(row);\n    }\n  }\n\n  /** Scans our `rows` for newly-added/newly-deleted rows that need `INSERT`s/`UPDATE`s. */\n  toTodo(): JoinRowTodo | undefined {\n    const newRows = this.rows.filter((r) => !r.persisted && r.deleted !== true && r.op === \"pending\");\n    const deletedRows = this.rows.filter((r) => r.persisted && r.deleted === true && r.op === \"pending\");\n    if (newRows.length === 0 && deletedRows.length === 0) {\n      return undefined;\n    }\n    return {\n      m2m: this.m2m,\n      newRows,\n      deletedRows,\n      resetAfterFlushed: () => {\n        for (const row of this.rows) {\n          if (row.op === JoinRowOperation.Pending || row.op === JoinRowOperation.Flushed)\n            row.op = JoinRowOperation.Completed;\n        }\n      },\n      // The driver flushes pure (int, int) FK pairs; resolve them here so it never has to know\n      // whether a column points at an entity (use its id) or an enum (its value is already the id).\n      dbValue: (row, columnName) => this.#dbValue(row, columnName),\n      isNew: (row, columnName) => isNewColumn(row.columns[columnName]),\n    };\n  }\n\n  get hasChanges() {\n    return this.rows.some(({ op }) => op === JoinRowOperation.Pending || op === JoinRowOperation.Flushed);\n  }\n\n  /** The db int value for `row`'s `columnName`: an entity's id, or (for enums) the enum's id itself. */\n  #dbValue(row: JoinRow, columnName: string): number {\n    const value = row.columns[columnName];\n    if (typeof value === \"number\") return value;\n    const meta = columnName === this.m2m.columnName ? this.m2m.meta : this.m2m.otherMeta!;\n    return keyToNumber(meta, value.idTagged)!;\n  }\n\n  /**\n   * Invalidates caches & queues reactivity for a join-row change.\n   *\n   * The owning entity (`e1`) always reacts; the \"other\" side only reacts when it is an entity,\n   * since enum other-sides have no `em`/reverse-field to keep in sync.\n   */\n  #reactToChange(m2m: ManyToManyLike, e1: Entity, e2: JoinColumnValue): void {\n    const { em } = this.m2m.entity;\n    const api = getEmInternalApi(e1.em);\n    api.isLoadedCache.resetIsLoaded(e1, m2m.fieldName);\n    this.rm.queueDownstreamReactables(e1, m2m.fieldName);\n    if (getBaseAndSelfMetas(e1).some((meta) => meta.config.__data.touchOnChange.has(m2m.fieldName))) {\n      em.touch(e1);\n    }\n    if (!m2m.otherEnum) {\n      const other = e2 as Entity;\n      const otherFieldName = m2m.otherFieldName!;\n      api.isLoadedCache.resetIsLoaded(other, otherFieldName);\n      this.rm.queueDownstreamReactables(other, otherFieldName);\n      if (getBaseAndSelfMetas(other).some((meta) => meta.config.__data.touchOnChange.has(otherFieldName))) {\n        em.touch(other);\n      }\n    }\n  }\n}\n\n/**\n * A \"psuedo-entity\" for a join row.\n *\n * We treat this as a special entity, i.e. it has two \"relations\" to each entity for the current\n * row, an optional surrogate `id` primary key, and an optional `created_at` column.\n *\n * These rows are immutable, i.e. once created we don't change either FK, and instead make\n * collection changes only by inserting new rows and deleting old rows.\n *\n * This makes the column1+column2 combination a composite key. For id-less join tables, that\n * composite is the actual primary key and `id` is always undefined.\n */\nexport interface JoinRow {\n  /**\n   * Whether our relation has been processed or not.\n   *\n   * - `pending` means we've not flushed it to the Database\n   * - `flushed` means we've flushed but `em.flush` hasn't fully completed yet, likely due to AsyncReactiveField calcs\n   * - `completed` means we've been flushed and `em.flush` has completed\n   */\n  op: JoinRowOperation;\n  /** The surrogate key for id-ful join tables; always undefined for id-less tables. */\n  id: number | undefined;\n  /**\n   * Whether this row exists (or is assumed to exist) in the database.\n   *\n   * This is orthogonal to `op` (the flush lifecycle) and is what distinguishes a pending insert\n   * from a pending delete: a `pending` row that is `!persisted` is a pending INSERT (added in\n   * memory, not yet in the db), while a `pending` row that is `persisted` is a pending DELETE\n   * (in the db, marked `deleted`). `op` alone cannot tell these apart, because both inserts and\n   * deletes walk the same `pending -> flushed -> completed` progression.\n   *\n   * We track this as its own flag rather than inferring it from `id` being set/unset, because\n   * id-less join tables (whose PK is just the composite of the two FKs) never have an `id` — so\n   * `id === undefined` would be ambiguous. `persisted` is the id-agnostic generalization of the\n   * `id`-is-set check that id-ful tables historically relied on.\n   *\n   * It must survive add/remove/re-add sequences: e.g. loading a row (persisted), removing it\n   * (pending delete), then re-adding it (`deleted` flipped back to false, `op` back to `pending`)\n   * leaves a `pending && !deleted` row that looks identical to a fresh insert — but it is still in\n   * the db, so a subsequent remove must issue a DELETE, which only `persisted` can tell us.\n   */\n  persisted: boolean;\n  /** Maps each FK column to its value: an `Entity`, or (for `EnumCollection`s) an enum's numeric id. */\n  columns: Record<string, JoinColumnValue>;\n  created_at?: Date;\n  deleted?: boolean;\n}\n\n/** An enum to track our insert/delete state progression. */\nexport enum JoinRowOperation {\n  Pending = \"pending\",\n  Flushed = \"flushed\",\n  Completed = \"completed\",\n}\n\n/** Keep an in-memory index to avoid sequentially scanning `rows`. */\nclass ManyToManyIndex {\n  private indexes: Record<string, Map<JoinColumnValue, Map<JoinColumnValue, JoinRow>>> = {};\n\n  constructor(private readonly m2m: ManyToManyLike) {\n    this.indexes[m2m.columnName] = new Map();\n    this.indexes[m2m.otherColumnName] = new Map();\n  }\n\n  add(m2m: ManyToManyLike, e1: JoinColumnValue, e2: JoinColumnValue, value: JoinRow): void {\n    // Store both e1+e2 => value and e2+e1 => value so we can do lookups from either side\n    this.#doAdd(this.indexes[m2m.columnName], e1, e2, value);\n    this.#doAdd(this.indexes[m2m.otherColumnName], e2, e1, value);\n  }\n\n  remove(value: JoinRow): void {\n    const [[column1, e1], [column2, e2]] = Object.entries(value.columns);\n    this.#doRemove(this.indexes[column1], e1, e2);\n    this.#doRemove(this.indexes[column2], e2, e1);\n  }\n\n  get(m2m: ManyToManyLike, e1: JoinColumnValue, e2: JoinColumnValue): JoinRow | undefined {\n    return this.indexes[m2m.columnName].get(e1)?.get(e2);\n  }\n\n  /** Cheat and use the index to return \"the other entities\" for `entity`. */\n  getOthers(columnName: string, entity: JoinColumnValue): JoinRow[] {\n    // It's empty m2m collection won't have any other entities, and so no index entries\n    const map = this.indexes[columnName].get(entity);\n    if (!map) return [];\n    // Sort for a stable order regardless of how many batches contributed rows — the underlying\n    // Map preserves insertion order, which depends on DataLoader timing and is non-deterministic\n    // across processes. New rows (no key yet) sort last.\n    const rows = Array.from(map.values());\n    if (this.m2m.hasJoinTableId) {\n      // Sort by join-row id.\n      return rows.sort((a, b) => (a.id ?? Infinity) - (b.id ?? Infinity));\n    }\n    // Id-less tables have no surrogate id, so sort by the other side's id.\n    const otherColumn = columnName === this.m2m.columnName ? this.m2m.otherColumnName : this.m2m.columnName;\n    if (this.m2m.otherEnum && otherColumn === this.m2m.otherColumnName) {\n      // The other side is an enum, so its column value is already its numeric id.\n      return rows.sort((a, b) => (a.columns[otherColumn] as number) - (b.columns[otherColumn] as number));\n    }\n    const otherMeta = columnName === this.m2m.columnName ? this.m2m.otherMeta! : this.m2m.meta;\n    const key = (r: JoinRow) => {\n      const other = r.columns[otherColumn] as Entity;\n      return other.isNewEntity ? Infinity : keyToNumber(otherMeta, other.id)!;\n    };\n    return rows.sort((a, b) => key(a) - key(b));\n  }\n\n  #doAdd(\n    index: Map<JoinColumnValue, Map<JoinColumnValue, JoinRow>>,\n    e1: JoinColumnValue,\n    e2: JoinColumnValue,\n    value: JoinRow,\n  ): void {\n    const map = index.get(e1) ?? new Map();\n    if (map.size === 0) index.set(e1, map);\n    map.set(e2, value);\n  }\n\n  #doRemove(\n    index: Map<JoinColumnValue, Map<JoinColumnValue, JoinRow>>,\n    e1: JoinColumnValue,\n    e2: JoinColumnValue,\n  ): void {\n    index.get(e1)?.delete(e2);\n  }\n}\n"],"mappings":";;;;;;;AAyCA,SAAS,YAAY,OAAiC;CACpD,OAAO,OAAO,UAAU,YAAY,MAAM;AAC5C;;AAGA,IAAa,WAAb,MAAsB;CAQT;CACD;CAPV,OAAmC,CAAC;CACpC;CAEA,YAGE,KACA,IACA;EAFS,KAAA,MAAA;EACD,KAAA,KAAA;EAER,KAAK,QAAQ,IAAI,gBAAgB,GAAG;CACtC;;CAGA,OAAO,KAAqB,IAAY,IAA2B;EACjE,IAAI,CAAC,IAAI,MAAM,IAAI,MAAM,+CAA+C,IAAI;EAC5E,IAAI,CAAC,IAAI,MAAM,IAAI,MAAM,+CAA+C,IAAI;EAC5E,MAAM,WAAW,KAAK,MAAM,IAAI,KAAK,IAAI,EAAE;EAC3C,IAAI,UAAU;GACZ,SAAS,UAAU;GACnB,SAAS,KAAA;EACX,OAAO;GACL,MAAM,MAAM;IACV,IAAA;IACA,IAAI,KAAA;IACJ,WAAW;IACX,SAAS;MAAG,IAAI,aAAa;MAAK,IAAI,kBAAkB;IAAG;GAC7D;GACA,KAAK,KAAK,KAAK,GAAG;GAClB,KAAK,MAAM,IAAI,KAAK,IAAI,IAAI,GAAG;EACjC;EACA,KAAKA,eAAe,KAAK,IAAI,EAAE;CACjC;;CAGA,UAAU,KAAqB,IAAY,IAA2B;EACpE,MAAM,WAAW,KAAK,MAAM,IAAI,KAAK,IAAI,EAAE;EAC3C,IAAI,UAAU;GACZ,IAAI,CAAC,SAAS,WAAW;IAEvB,cAAA,OAAO,KAAK,MAAM,QAAQ;IAC1B,KAAK,MAAM,OAAO,QAAQ;GAC5B,OACE,SAAS,UAAU;GAErB,SAAS,KAAA;EACX,OAAO;GAGL,MAAM,MAAM;IACV,IAAA;IACA,IAAI,KAAA;IACJ,WAAW;IACX,SAAS;MAAG,IAAI,aAAa;MAAK,IAAI,kBAAkB;IAAG;IAC3D,SAAS;GACX;GACA,KAAK,KAAK,KAAK,GAAG;GAClB,KAAK,MAAM,IAAI,KAAK,IAAI,IAAI,GAAG;EACjC;EACA,KAAKA,eAAe,KAAK,IAAI,EAAE;CACjC;;CAGA,WAAW,KAAqB,IAA+B;EAC7D,MAAM,EAAE,oBAAoB;EAI5B,OADoB,KAAK,MAAM,UAAU,IAAI,YAAY,EAAE,CAAC,CAAC,QAAQ,MAAM,EAAE,OAC5D,CAAC,CAAC,KAAK,MAAM,EAAE,QAAQ,gBAAgB;CAC1D;CAEA,SAAS,KAAqB,IAA+B;EAC3D,MAAM,EAAE,oBAAoB;EAQ5B,OAPkB,KAAK,MACpB,UAAU,IAAI,YAAY,EAAE,CAAC,CAC7B,QACE,OACG,CAAC,EAAE,aAAa,EAAE,OAAA,aAAoC,EAAE,OAAA,cAC1D,EAAE,YAAY,IAEL,CAAC,CAAC,KAAK,MAAM,EAAE,QAAQ,gBAAgB;CACxD;;CAGA,gBAAgB,KAAqB,IAAwB,IAAY,IAA2B;EAElG,IADiB,KAAK,MAAM,IAAI,KAAK,IAAI,EAC9B,GAAG,CAEd,OAAO;GACL,MAAM,MAAM;IACV,IAAA;IACA;IACA,WAAW;IACX,SAAS;MAAG,IAAI,aAAa;MAAK,IAAI,kBAAkB;IAAG;GAC7D;GACA,KAAK,KAAK,KAAK,GAAG;GAClB,KAAK,MAAM,IAAI,KAAK,IAAI,IAAI,GAAG;EACjC;CACF;;CAGA,MAAM,SAAS,QAA4B,QAA8B;EACvE,MAAM,EAAE,OAAO,KAAK,IAAI;EACxB,MAAM,EAAE,YAAY,SAAS,iBAAiB,SAAS,MAAM,OAAO,WAAW,OAAO,cAAc,KAAK;EAEzG,MAAM,SAAmB,CAAC;EAE1B,MAAM,UAA6B,CAAC;EACpC,KAAK,MAAM,SAAS,QAAQ;GAC1B,OAAO,KAAKC,aAAAA,cAAc,OAAO,MAAM,QAAQ,CAAE;GACjD,QAAQ,KACN,YAAa,MAAM,WAAuB,GAAG,UAAUA,aAAAA,cAAc,OAAQ,MAAM,QAAQ,CAAE,CAC/F;EACF;EAIA,MAAM,QAAQ,IAAI,CAChB,GAAG,QAAQ,MAAM,MAAM,MAAM,GAC7B,YACI,QAAQ,QAAQ,CAAC,CAAC,IAClB,GAAG,QACD,MAAO,MACP,OAAO,KAAK,UAAUA,aAAAA,cAAc,OAAQ,MAAM,QAAQ,CAAE,CAC9D,CACN,CAAC;EAKD,MAAM,+BAAe,IAAI,IAAa;EACtC,KAAK,MAAM,CAAC,YAAY,OAAO,QAAQ;GACrC,MAAM,SAAS,KAAK,MAAM,UAAU,YAAY,GAAG,UAAU,EAAE,CAAE;GACjE,KAAK,MAAM,OAAO,QAAQ,IAAI,CAAC,aAAa,IAAI,WAAW,aAAa,IAAI,GAAG;EACjF;EAEA,IAAI,IAAI;EACR,KAAK,MAAM,SAAS,QAAQ;GAC1B,MAAM,KAAK,GAAG,UAAU,OAAO,EAAE;GACjC,MAAM,KAAK,YAAa,MAAM,WAAsB,GAAG,UAAUA,aAAAA,cAAc,OAAQ,MAAM,QAAQ,CAAE;GACvG;GACA,IAAI,MAAM,KAAK,MAAM,IAAI,KAAK,KAAK,IAAI,EAAE;GACzC,IAAI,CAAC,KAAK;IACR,MAAM;KACJ,IAAA;KACA,IAAI,MAAM;KACV,WAAW;KACX,SAAS;OAAG,UAAU;OAAK,UAAU;KAAG;KACxC,YAAY,MAAM;IACpB;IACA,KAAK,KAAK,KAAK,GAAG;IAClB,KAAK,MAAM,IAAI,KAAK,KAAK,IAAI,IAAI,GAAG;GACtC,OAAO;IAGL,IAAI,KAAK,MAAM;IACf,IAAI,YAAY;IAEhB,aAAa,OAAO,GAAG;GACzB;EACF;EAGA,KAAK,MAAM,OAAO,cAAc,IAAI,UAAU;CAChD;CAEA,UAAU,YAAoB,QAAmC;EAC/D,MAAM,SAAS,KAAK,MAAM,UAAU,YAAY,MAAM;EACtD,IAAI,OAAO,WAAW,GAAG,OAAO,CAAC;EACjC,MAAM,CAAC,IAAI,MAAM,OAAO,KAAK,OAAO,EAAE,CAAC,OAAO;EAC9C,MAAM,IAAI,OAAO,EAAE,CAAC,QAAQ,QAAQ,SAAS,KAAK;EAClD,OAAO,OAAO,QAAQ,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC,KAAK,QAAQ,IAAI,QAAQ,EAAE;CACrE;;CAGA,aAAa,YAAoB,QAAsB;EACrD,KAAK,MAAM,OAAO,KAAK,MAAM,UAAU,YAAY,MAAM,GAAG;GAC1D,cAAA,OAAO,KAAK,MAAM,GAAG;GACrB,KAAK,MAAM,OAAO,GAAG;EACvB;CACF;;CAGA,mBAAmB,KAAqB,IAAY,IAA2B;EAC7E,MAAM,MAAM,KAAK,MAAM,IAAI,KAAK,IAAI,EAAE;EACtC,IAAI,KAAK;GACP,cAAA,OAAO,KAAK,MAAM,GAAG;GACrB,KAAK,MAAM,OAAO,GAAG;EACvB;CACF;;CAGA,SAAkC;EAChC,MAAM,UAAU,KAAK,KAAK,QAAQ,MAAM,CAAC,EAAE,aAAa,EAAE,YAAY,QAAQ,EAAE,OAAO,SAAS;EAChG,MAAM,cAAc,KAAK,KAAK,QAAQ,MAAM,EAAE,aAAa,EAAE,YAAY,QAAQ,EAAE,OAAO,SAAS;EACnG,IAAI,QAAQ,WAAW,KAAK,YAAY,WAAW,GACjD;EAEF,OAAO;GACL,KAAK,KAAK;GACV;GACA;GACA,yBAAyB;IACvB,KAAK,MAAM,OAAO,KAAK,MACrB,IAAI,IAAI,OAAA,aAAmC,IAAI,OAAA,WAC7C,IAAI,KAAA;GAEV;GAGA,UAAU,KAAK,eAAe,KAAKC,SAAS,KAAK,UAAU;GAC3D,QAAQ,KAAK,eAAe,YAAY,IAAI,QAAQ,WAAW;EACjE;CACF;CAEA,IAAI,aAAa;EACf,OAAO,KAAK,KAAK,MAAM,EAAE,SAAS,OAAA,aAAmC,OAAA,SAA+B;CACtG;;CAGA,SAAS,KAAc,YAA4B;EACjD,MAAM,QAAQ,IAAI,QAAQ;EAC1B,IAAI,OAAO,UAAU,UAAU,OAAO;EACtC,MAAM,OAAO,eAAe,KAAK,IAAI,aAAa,KAAK,IAAI,OAAO,KAAK,IAAI;EAC3E,OAAOC,aAAAA,YAAY,MAAM,MAAM,QAAQ;CACzC;;;;;;;CAQA,eAAe,KAAqB,IAAY,IAA2B;EACzE,MAAM,EAAE,OAAO,KAAK,IAAI;EACxB,MAAM,MAAMC,sBAAAA,iBAAiB,GAAG,EAAE;EAClC,IAAI,cAAc,cAAc,IAAI,IAAI,SAAS;EACjD,KAAK,GAAG,0BAA0B,IAAI,IAAI,SAAS;EACnD,IAAIC,uBAAAA,oBAAoB,EAAE,CAAC,CAAC,MAAM,SAAS,KAAK,OAAO,OAAO,cAAc,IAAI,IAAI,SAAS,CAAC,GAC5F,GAAG,MAAM,EAAE;EAEb,IAAI,CAAC,IAAI,WAAW;GAClB,MAAM,QAAQ;GACd,MAAM,iBAAiB,IAAI;GAC3B,IAAI,cAAc,cAAc,OAAO,cAAc;GACrD,KAAK,GAAG,0BAA0B,OAAO,cAAc;GACvD,IAAIA,uBAAAA,oBAAoB,KAAK,CAAC,CAAC,MAAM,SAAS,KAAK,OAAO,OAAO,cAAc,IAAI,cAAc,CAAC,GAChG,GAAG,MAAM,KAAK;EAElB;CACF;AACF;;AAoDA,IAAY,mBAAL,yBAAA,kBAAA;CACL,iBAAA,aAAA;CACA,iBAAA,aAAA;CACA,iBAAA,eAAA;;AACF,EAAA,CAAA,CAAA;;AAGA,IAAM,kBAAN,MAAsB;CAGS;CAF7B,UAAuF,CAAC;CAExF,YAAY,KAAsC;EAArB,KAAA,MAAA;EAC3B,KAAK,QAAQ,IAAI,8BAAc,IAAI,IAAI;EACvC,KAAK,QAAQ,IAAI,mCAAmB,IAAI,IAAI;CAC9C;CAEA,IAAI,KAAqB,IAAqB,IAAqB,OAAsB;EAEvF,KAAKC,OAAO,KAAK,QAAQ,IAAI,aAAa,IAAI,IAAI,KAAK;EACvD,KAAKA,OAAO,KAAK,QAAQ,IAAI,kBAAkB,IAAI,IAAI,KAAK;CAC9D;CAEA,OAAO,OAAsB;EAC3B,MAAM,CAAC,CAAC,SAAS,KAAK,CAAC,SAAS,OAAO,OAAO,QAAQ,MAAM,OAAO;EACnE,KAAKC,UAAU,KAAK,QAAQ,UAAU,IAAI,EAAE;EAC5C,KAAKA,UAAU,KAAK,QAAQ,UAAU,IAAI,EAAE;CAC9C;CAEA,IAAI,KAAqB,IAAqB,IAA0C;EACtF,OAAO,KAAK,QAAQ,IAAI,WAAW,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE;CACrD;;CAGA,UAAU,YAAoB,QAAoC;EAEhE,MAAM,MAAM,KAAK,QAAQ,WAAW,CAAC,IAAI,MAAM;EAC/C,IAAI,CAAC,KAAK,OAAO,CAAC;EAIlB,MAAM,OAAO,MAAM,KAAK,IAAI,OAAO,CAAC;EACpC,IAAI,KAAK,IAAI,gBAEX,OAAO,KAAK,MAAM,GAAG,OAAO,EAAE,MAAM,aAAa,EAAE,MAAM,SAAS;EAGpE,MAAM,cAAc,eAAe,KAAK,IAAI,aAAa,KAAK,IAAI,kBAAkB,KAAK,IAAI;EAC7F,IAAI,KAAK,IAAI,aAAa,gBAAgB,KAAK,IAAI,iBAEjD,OAAO,KAAK,MAAM,GAAG,MAAO,EAAE,QAAQ,eAA2B,EAAE,QAAQ,YAAuB;EAEpG,MAAM,YAAY,eAAe,KAAK,IAAI,aAAa,KAAK,IAAI,YAAa,KAAK,IAAI;EACtF,MAAM,OAAO,MAAe;GAC1B,MAAM,QAAQ,EAAE,QAAQ;GACxB,OAAO,MAAM,cAAc,WAAWJ,aAAAA,YAAY,WAAW,MAAM,EAAE;EACvE;EACA,OAAO,KAAK,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC;CAC5C;CAEA,OACE,OACA,IACA,IACA,OACM;EACN,MAAM,MAAM,MAAM,IAAI,EAAE,qBAAK,IAAI,IAAI;EACrC,IAAI,IAAI,SAAS,GAAG,MAAM,IAAI,IAAI,GAAG;EACrC,IAAI,IAAI,IAAI,KAAK;CACnB;CAEA,UACE,OACA,IACA,IACM;EACN,MAAM,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE;CAC1B;AACF"}

package/build/flush/JoinRows.d.cts

@@ -0,0 +1,120 @@
+import { EnumMetadata } from "../EnumMetadata.cjs";
+import { JoinRowTodo } from "./Todo.cjs";
+import { ReactionsManager } from "../reactivity/ReactionsManager.cjs";
+import { EntityMetadata } from "../EntityMetadata.cjs";
+import { Entity } from "../Entity.cjs";
+//#region src/flush/JoinRows.d.ts
+/**
+ * A simplified interface for ManyToManyCollection-like relations.
+ *
+ * Specifically lets ReactiveManyToMany & ReactiveManyToManyOtherSide use JoinRows
+ * as if they were full-fledged m2m relations.
+ *
+ * The "other" side of the join table is usually a second entity, but for `EnumCollection`s
+ * (i.e. `Publisher.logoColors`) it is an enum table; in that case `otherEnum` is set and the
+ * other column's value is the enum's numeric id rather than an `Entity` (there is also no
+ * `otherMeta`/`otherFieldName`, since enums have no reverse collection to keep in sync).
+ */
+type ManyToManyLike = {
+  entity: Entity;
+  joinTableName: string;
+  columnName: string;
+  otherColumnName: string;
+  fieldName: string;
+  meta: EntityMetadata;
+  /** Undefined when the other side is an enum. */
+  otherFieldName?: string;
+  /** Undefined when the other side is an enum. */
+  otherMeta?: EntityMetadata;
+  /** Set when the other side is an enum table, for mapping enum codes <-> their numeric ids. */
+  otherEnum?: EnumMetadata<any, any, number>;
+  /** Whether the join table has a surrogate `id` PK; if false the FK pair is the composite PK. */
+  hasJoinTableId: boolean;
+};
+/** The value of a join row's column: an `Entity`, or an enum's numeric id for `EnumCollection`s. */
+type JoinColumnValue = Entity | number;
+/** A small holder around m2m join rows, which we treat as psuedo-entities. */
+declare class JoinRows {
+  #private;
+  readonly m2m: ManyToManyLike;
+  private rm;
+  private readonly rows;
+  private readonly index;
+  constructor(m2m: ManyToManyLike, rm: ReactionsManager);
+  /** Adds a new join row to this table. */
+  addNew(m2m: ManyToManyLike, e1: Entity, e2: JoinColumnValue): void;
+  /** Adds a new remove to this table. */
+  addRemove(m2m: ManyToManyLike, e1: Entity, e2: JoinColumnValue): void;
+  /** Return any "old values" for a m2m collection that might need reactivity checks. */
+  removedFor(m2m: ManyToManyLike, e1: Entity): JoinColumnValue[];
+  addedFor(m2m: ManyToManyLike, e1: Entity): JoinColumnValue[];
+  /** Adds an existing join row to this table. */
+  addPreloadedRow(m2m: ManyToManyLike, id: number | undefined, e1: Entity, e2: JoinColumnValue): void;
+  /** Look up/create our internal JoinRow psuedo-entities for the db rows. */
+  loadRows(tuples: [string, string][], dbRows: any[]): Promise<void>;
+  getOthers(columnName: string, entity: Entity): JoinColumnValue[];
+  /** Drops all in-memory rows where `entity` is on `columnName`, e.g. when it is being deleted. */
+  removeAllFor(columnName: string, entity: Entity): void;
+  /** Drops a single `(e1, e2)` row without queuing a flush, e.g. when mirroring another em's removal. */
+  removePreloadedRow(m2m: ManyToManyLike, e1: Entity, e2: JoinColumnValue): void;
+  /** Scans our `rows` for newly-added/newly-deleted rows that need `INSERT`s/`UPDATE`s. */
+  toTodo(): JoinRowTodo | undefined;
+  get hasChanges(): boolean;
+}
+/**
+ * A "psuedo-entity" for a join row.
+ *
+ * We treat this as a special entity, i.e. it has two "relations" to each entity for the current
+ * row, an optional surrogate `id` primary key, and an optional `created_at` column.
+ *
+ * These rows are immutable, i.e. once created we don't change either FK, and instead make
+ * collection changes only by inserting new rows and deleting old rows.
+ *
+ * This makes the column1+column2 combination a composite key. For id-less join tables, that
+ * composite is the actual primary key and `id` is always undefined.
+ */
+interface JoinRow {
+  /**
+   * Whether our relation has been processed or not.
+   *
+   * - `pending` means we've not flushed it to the Database
+   * - `flushed` means we've flushed but `em.flush` hasn't fully completed yet, likely due to AsyncReactiveField calcs
+   * - `completed` means we've been flushed and `em.flush` has completed
+   */
+  op: JoinRowOperation;
+  /** The surrogate key for id-ful join tables; always undefined for id-less tables. */
+  id: number | undefined;
+  /**
+   * Whether this row exists (or is assumed to exist) in the database.
+   *
+   * This is orthogonal to `op` (the flush lifecycle) and is what distinguishes a pending insert
+   * from a pending delete: a `pending` row that is `!persisted` is a pending INSERT (added in
+   * memory, not yet in the db), while a `pending` row that is `persisted` is a pending DELETE
+   * (in the db, marked `deleted`). `op` alone cannot tell these apart, because both inserts and
+   * deletes walk the same `pending -> flushed -> completed` progression.
+   *
+   * We track this as its own flag rather than inferring it from `id` being set/unset, because
+   * id-less join tables (whose PK is just the composite of the two FKs) never have an `id` — so
+   * `id === undefined` would be ambiguous. `persisted` is the id-agnostic generalization of the
+   * `id`-is-set check that id-ful tables historically relied on.
+   *
+   * It must survive add/remove/re-add sequences: e.g. loading a row (persisted), removing it
+   * (pending delete), then re-adding it (`deleted` flipped back to false, `op` back to `pending`)
+   * leaves a `pending && !deleted` row that looks identical to a fresh insert — but it is still in
+   * the db, so a subsequent remove must issue a DELETE, which only `persisted` can tell us.
+   */
+  persisted: boolean;
+  /** Maps each FK column to its value: an `Entity`, or (for `EnumCollection`s) an enum's numeric id. */
+  columns: Record<string, JoinColumnValue>;
+  created_at?: Date;
+  deleted?: boolean;
+}
+/** An enum to track our insert/delete state progression. */
+declare enum JoinRowOperation {
+  Pending = "pending",
+  Flushed = "flushed",
+  Completed = "completed"
+}
+//#endregion
+export { JoinColumnValue, JoinRow, JoinRowOperation, JoinRows, ManyToManyLike };
+//# sourceMappingURL=JoinRows.d.cts.map

package/build/flush/JoinRows.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JoinRows.d.cts","names":[],"sources":["../../src/flush/JoinRows.ts"],"mappings":";;;;;;;;;;;;;;;;;KAoBY;EACV,QAAQ;EACR;EACA;EACA;EACA;EACA,MAAM;;EAEN;;EAEA,YAAY;;EAEZ,YAAY;;EAEZ;;;KAIU,kBAAkB;;cAQjB;;WAQA,KAAK;UACN;mBAPO;mBACA;EAEjB,YAGW,KAAK,gBACN,IAAI;;EAMd,OAAO,KAAK,gBAAgB,IAAI,QAAQ,IAAI;;EAqB5C,UAAU,KAAK,gBAAgB,IAAI,QAAQ,IAAI;;EA4B/C,WAAW,KAAK,gBAAgB,IAAI,SAAS;EAQ7C,SAAS,KAAK,gBAAgB,IAAI,SAAS;;EAa3C,gBAAgB,KAAK,gBAAgB,wBAAwB,IAAI,QAAQ,IAAI;;EAiBvE,SAAS,4BAA4B,gBAAgB;EAiE3D,UAAU,oBAAoB,QAAQ,SAAS;;EAS/C,aAAa,oBAAoB,QAAQ;;EAQzC,mBAAmB,KAAK,gBAAgB,IAAI,QAAQ,IAAI;;EASxD,UAAU;MAuBN;;;;;;;;;;;;;;UAkDW;;;;;;;;EAQf,IAAI;;EAEJ;;;;;;;;;;;;;;;;;;;;EAoBA;;EAEA,SAAS,eAAe;EACxB,aAAa;EACb;;;aAIU;EACV;EACA;EACA"}

package/build/flush/JoinRows.d.mts

@@ -0,0 +1,120 @@
+import { EnumMetadata } from "../EnumMetadata.mjs";
+import { JoinRowTodo } from "./Todo.mjs";
+import { ReactionsManager } from "../reactivity/ReactionsManager.mjs";
+import { EntityMetadata } from "../EntityMetadata.mjs";
+import { Entity } from "../Entity.mjs";
+//#region src/flush/JoinRows.d.ts
+/**
+ * A simplified interface for ManyToManyCollection-like relations.
+ *
+ * Specifically lets ReactiveManyToMany & ReactiveManyToManyOtherSide use JoinRows
+ * as if they were full-fledged m2m relations.
+ *
+ * The "other" side of the join table is usually a second entity, but for `EnumCollection`s
+ * (i.e. `Publisher.logoColors`) it is an enum table; in that case `otherEnum` is set and the
+ * other column's value is the enum's numeric id rather than an `Entity` (there is also no
+ * `otherMeta`/`otherFieldName`, since enums have no reverse collection to keep in sync).
+ */
+type ManyToManyLike = {
+  entity: Entity;
+  joinTableName: string;
+  columnName: string;
+  otherColumnName: string;
+  fieldName: string;
+  meta: EntityMetadata;
+  /** Undefined when the other side is an enum. */
+  otherFieldName?: string;
+  /** Undefined when the other side is an enum. */
+  otherMeta?: EntityMetadata;
+  /** Set when the other side is an enum table, for mapping enum codes <-> their numeric ids. */
+  otherEnum?: EnumMetadata<any, any, number>;
+  /** Whether the join table has a surrogate `id` PK; if false the FK pair is the composite PK. */
+  hasJoinTableId: boolean;
+};
+/** The value of a join row's column: an `Entity`, or an enum's numeric id for `EnumCollection`s. */
+type JoinColumnValue = Entity | number;
+/** A small holder around m2m join rows, which we treat as psuedo-entities. */
+declare class JoinRows {
+  #private;
+  readonly m2m: ManyToManyLike;
+  private rm;
+  private readonly rows;
+  private readonly index;
+  constructor(m2m: ManyToManyLike, rm: ReactionsManager);
+  /** Adds a new join row to this table. */
+  addNew(m2m: ManyToManyLike, e1: Entity, e2: JoinColumnValue): void;
+  /** Adds a new remove to this table. */
+  addRemove(m2m: ManyToManyLike, e1: Entity, e2: JoinColumnValue): void;
+  /** Return any "old values" for a m2m collection that might need reactivity checks. */
+  removedFor(m2m: ManyToManyLike, e1: Entity): JoinColumnValue[];
+  addedFor(m2m: ManyToManyLike, e1: Entity): JoinColumnValue[];
+  /** Adds an existing join row to this table. */
+  addPreloadedRow(m2m: ManyToManyLike, id: number | undefined, e1: Entity, e2: JoinColumnValue): void;
+  /** Look up/create our internal JoinRow psuedo-entities for the db rows. */
+  loadRows(tuples: [string, string][], dbRows: any[]): Promise<void>;
+  getOthers(columnName: string, entity: Entity): JoinColumnValue[];
+  /** Drops all in-memory rows where `entity` is on `columnName`, e.g. when it is being deleted. */
+  removeAllFor(columnName: string, entity: Entity): void;
+  /** Drops a single `(e1, e2)` row without queuing a flush, e.g. when mirroring another em's removal. */
+  removePreloadedRow(m2m: ManyToManyLike, e1: Entity, e2: JoinColumnValue): void;
+  /** Scans our `rows` for newly-added/newly-deleted rows that need `INSERT`s/`UPDATE`s. */
+  toTodo(): JoinRowTodo | undefined;
+  get hasChanges(): boolean;
+}
+/**
+ * A "psuedo-entity" for a join row.
+ *
+ * We treat this as a special entity, i.e. it has two "relations" to each entity for the current
+ * row, an optional surrogate `id` primary key, and an optional `created_at` column.
+ *
+ * These rows are immutable, i.e. once created we don't change either FK, and instead make
+ * collection changes only by inserting new rows and deleting old rows.
+ *
+ * This makes the column1+column2 combination a composite key. For id-less join tables, that
+ * composite is the actual primary key and `id` is always undefined.
+ */
+interface JoinRow {
+  /**
+   * Whether our relation has been processed or not.
+   *
+   * - `pending` means we've not flushed it to the Database
+   * - `flushed` means we've flushed but `em.flush` hasn't fully completed yet, likely due to AsyncReactiveField calcs
+   * - `completed` means we've been flushed and `em.flush` has completed
+   */
+  op: JoinRowOperation;
+  /** The surrogate key for id-ful join tables; always undefined for id-less tables. */
+  id: number | undefined;
+  /**
+   * Whether this row exists (or is assumed to exist) in the database.
+   *
+   * This is orthogonal to `op` (the flush lifecycle) and is what distinguishes a pending insert
+   * from a pending delete: a `pending` row that is `!persisted` is a pending INSERT (added in
+   * memory, not yet in the db), while a `pending` row that is `persisted` is a pending DELETE
+   * (in the db, marked `deleted`). `op` alone cannot tell these apart, because both inserts and
+   * deletes walk the same `pending -> flushed -> completed` progression.
+   *
+   * We track this as its own flag rather than inferring it from `id` being set/unset, because
+   * id-less join tables (whose PK is just the composite of the two FKs) never have an `id` — so
+   * `id === undefined` would be ambiguous. `persisted` is the id-agnostic generalization of the
+   * `id`-is-set check that id-ful tables historically relied on.
+   *
+   * It must survive add/remove/re-add sequences: e.g. loading a row (persisted), removing it
+   * (pending delete), then re-adding it (`deleted` flipped back to false, `op` back to `pending`)
+   * leaves a `pending && !deleted` row that looks identical to a fresh insert — but it is still in
+   * the db, so a subsequent remove must issue a DELETE, which only `persisted` can tell us.
+   */
+  persisted: boolean;
+  /** Maps each FK column to its value: an `Entity`, or (for `EnumCollection`s) an enum's numeric id. */
+  columns: Record<string, JoinColumnValue>;
+  created_at?: Date;
+  deleted?: boolean;
+}
+/** An enum to track our insert/delete state progression. */
+declare enum JoinRowOperation {
+  Pending = "pending",
+  Flushed = "flushed",
+  Completed = "completed"
+}
+//#endregion
+export { JoinColumnValue, JoinRow, JoinRowOperation, JoinRows, ManyToManyLike };
+//# sourceMappingURL=JoinRows.d.mts.map

package/build/flush/JoinRows.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JoinRows.d.mts","names":[],"sources":["../../src/flush/JoinRows.ts"],"mappings":";;;;;;;;;;;;;;;;;KAoBY;EACV,QAAQ;EACR;EACA;EACA;EACA;EACA,MAAM;;EAEN;;EAEA,YAAY;;EAEZ,YAAY;;EAEZ;;;KAIU,kBAAkB;;cAQjB;;WAQA,KAAK;UACN;mBAPO;mBACA;EAEjB,YAGW,KAAK,gBACN,IAAI;;EAMd,OAAO,KAAK,gBAAgB,IAAI,QAAQ,IAAI;;EAqB5C,UAAU,KAAK,gBAAgB,IAAI,QAAQ,IAAI;;EA4B/C,WAAW,KAAK,gBAAgB,IAAI,SAAS;EAQ7C,SAAS,KAAK,gBAAgB,IAAI,SAAS;;EAa3C,gBAAgB,KAAK,gBAAgB,wBAAwB,IAAI,QAAQ,IAAI;;EAiBvE,SAAS,4BAA4B,gBAAgB;EAiE3D,UAAU,oBAAoB,QAAQ,SAAS;;EAS/C,aAAa,oBAAoB,QAAQ;;EAQzC,mBAAmB,KAAK,gBAAgB,IAAI,QAAQ,IAAI;;EASxD,UAAU;MAuBN;;;;;;;;;;;;;;UAkDW;;;;;;;;EAQf,IAAI;;EAEJ;;;;;;;;;;;;;;;;;;;;EAoBA;;EAEA,SAAS,eAAe;EACxB,aAAa;EACb;;;aAIU;EACV;EACA;EACA"}