joist-core 2.3.0 → 2.4.0-next.10

package/build/InstanceData.cjs

@@ -0,0 +1,218 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_RowData = require("./RowData.cjs");
+const require_utils = require("./utils.cjs");
+require("./EntityMetadata.cjs");
+const require_EntityManager = require("./EntityManager.cjs");
+require("./Entity.cjs");
+//#region src/InstanceData.ts
+/** The `#orm` metadata field we track on each instance. */
+var InstanceData = class {
+	/** The entity this instance data belongs to. */
+	entity;
+	/** All entities must be associated to an `EntityManager` to handle lazy loading/etc. */
+	em;
+	/** A pointer to our entity type's metadata. */
+	metadata;
+	/** A bag for our lazy-initialized relations, allocated on first relation access. */
+	relations = void 0;
+	/** The as-loaded database row, i.e. our `rowIndex`-th row within our query's `RowData` result. */
+	rowData = require_RowData.emptyRowData;
+	/** Our row's index within `rowData`; see {@link RowData}. */
+	rowIndex = 0;
+	/** The domain-value of fields, lazily converted (if needed) on read from the database columns. */
+	data;
+	/** A bag to keep the original values, allocated on first mutation (most entities are never mutated). */
+	#originalData = void 0;
+	/** Reference values that were set during this unit of work, allocated on first m2o/poly change. */
+	#referenceHistory = void 0;
+	/** A bag to keep the flushed-to-database values, only for AsyncReactiveField reactivity. */
+	flushedData;
+	/** Packs the new/deleted `Operation`s + isTouched into one slot; see the accessors below. */
+	#flags = 0;
+	/** The `a#1`, `a#2` index if we're an em.create-d entity. We never unset this, to keep ids stable across flushes. */
+	createId;
+	/** The zero-based order this entity was registered with its EntityManager. */
+	entityIndex = -1;
+	/** Whether our entity is new or not. */
+	get #new() {
+		const value = this.#flags & 3;
+		return value === 0 ? void 0 : value;
+	}
+	set #new(op) {
+		this.#flags = this.#flags & -4 | (op ?? 0);
+	}
+	/**
+	* Whether our entity has been deleted or not.
+	*
+	* - `pending` means we've been marked for deletion via `em.delete` but not issued a `DELETE`
+	* - `flushed` means we've flushed a `DELETE` but `em.flush` hasn't fully completed yet, likely due to AsyncReactiveField calcs
+	* - `deleted` means we've been flushed and `em.flush` has completed
+	*/
+	get #deleted() {
+		const value = this.#flags >> 2 & 3;
+		return value === 0 ? void 0 : value;
+	}
+	set #deleted(op) {
+		this.#flags = this.#flags & -13 | (op ?? 0) << 2;
+	}
+	/** Whether our entity should flush regardless of any other changes. */
+	get isTouched() {
+		return (this.#flags & 16) !== 0;
+	}
+	set isTouched(value) {
+		this.#flags = value ? this.#flags | 16 : this.#flags & -17;
+	}
+	/** Creates the `#orm` field. */
+	constructor(em, entity, metadata, isNew) {
+		this.entity = entity;
+		this.em = em;
+		this.metadata = metadata;
+		if (isNew) {
+			this.#new = 1;
+			this.data = {};
+			this.flushedData = void 0;
+			if (em) this.markMaybePending();
+		} else {
+			this.#new = void 0;
+			this.data = {};
+			this.flushedData = void 0;
+		}
+	}
+	/**
+	* Returns the as-loaded value of `columnName`, i.e. `getColumn("rank")`.
+	*
+	* This saves callers from knowing that `rowData`/`rowIndex` are a pair, but note it is
+	* a snapshot of the query that loaded us, and specifically:
+	*
+	* - The value is driver-level, i.e. numeric enum ids, untagged foreign keys, and temporals
+	*   as strings; use `getField` if you want the domain value, and
+	* - The value is not updated by `em.flush`, so after a flush it is the pre-flush value, and
+	* - New entities have no row, so every column is `undefined`.
+	*/
+	getColumn(columnName) {
+		return this.rowData.get(this.rowIndex, columnName);
+	}
+	/** If `em.flush` has detected a dirty RQF, reset our internal dirty state, w/o reseting our external-dirty state. */
+	resetForRqfLoop() {
+		this.flushedData = {};
+		if (this.#new === 1) this.#new = 2;
+		if (this.#deleted === 1) this.#deleted = 2;
+	}
+	resetAfterFlushed() {
+		this.#originalData = void 0;
+		this.#referenceHistory = void 0;
+		this.flushedData = void 0;
+		this.isTouched = false;
+		if (this.#new === 1 || this.#new === 2) this.#new = 3;
+		if (this.#deleted === 1 || this.#deleted === 2) this.#deleted = 3;
+		this.unmarkMaybePending();
+	}
+	/** Our public-facing `isNewEntity`. */
+	get isNewEntity() {
+		return this.#new !== void 0 && this.#new !== 3;
+	}
+	/** Our public-facing `isDeletedEntity`. */
+	get isDeletedEntity() {
+		return this.#deleted !== void 0;
+	}
+	/** The original values of mutated fields; a shared empty object until the entity is actually mutated. */
+	get originalData() {
+		return this.#originalData ?? emptyObject;
+	}
+	/** Our public-facing `isDirtyEntity`. */
+	get isDirtyEntity() {
+		return require_utils.hasAnyKey(this.#originalData);
+	}
+	/** This is our internal "is pending flush", which is aware of RQF micro-flush loops. */
+	get pendingOperation() {
+		if (this.#deleted !== void 0) return this.#deleted === 1 && this.#new === 1 ? "created-then-deleted" : this.#deleted === 1 ? "delete" : "none";
+		else if (this.#new === 1) return "insert";
+		else if (this.flushedData) return require_utils.hasAnyKey(this.flushedData) ? "update" : "none";
+		else return this.isTouched || require_utils.hasAnyKey(this.#originalData) ? "update" : "none";
+	}
+	get changedFields() {
+		return Object.keys(this.changedData);
+	}
+	/** The changed-fields bag (flushedData during RQF loops, else originalData) without allocating a keys array. */
+	get changedData() {
+		return this.flushedData ?? this.#originalData ?? emptyObject;
+	}
+	/** Called when an `em.load` tries to find the entity and it's just gone from the db. */
+	markDeletedBecauseNotFound() {
+		this.#deleted = 3;
+	}
+	/** Called by `em.delete`, returns true if this is new information. */
+	markDeleted() {
+		if (this.#deleted === void 0) {
+			for (const field of Object.values(this.metadata.allFields)) if (field.kind === "m2o" || field.kind === "poly" || field.kind === "m2m" || field.kind === "m2mEnum") require_EntityManager.getEmInternalApi(this.em).isLoadedCache.resetIsLoaded(this.entity, field.fieldName);
+			else if (field.kind === "primitive" || field.kind === "enum" || field.kind === "primaryKey") {} else if (field.kind === "o2m" || field.kind === "o2o") {} else if (field.kind === "lo2m") {} else throw new Error(`Unhandled field kind ${field}`);
+			this.#deleted = 1;
+			this.markMaybePending();
+			return true;
+		}
+		return false;
+	}
+	fixupCreatedThenDeleted() {
+		this.#deleted = 3;
+		this.unmarkMaybePending();
+	}
+	/** Marks this entity as needing a flush even if no fields changed. */
+	markTouched() {
+		this.isTouched = true;
+		this.markMaybePending();
+	}
+	/** Marks a field as dirty with its pre-mutation value. */
+	markFieldDirty(fieldName, value) {
+		(this.#originalData ??= {})[fieldName] = value;
+		this.markMaybePending();
+	}
+	/** Marks a reverted field as clean again. */
+	markFieldClean(fieldName) {
+		if (this.#originalData) delete this.#originalData[fieldName];
+		this.markMaybePending();
+	}
+	/** Marks this entity as a possible flush candidate. */
+	markMaybePending() {
+		require_EntityManager.getEmInternalApi(this.em).markMaybePending(this.entity);
+	}
+	/** Removes this entity from the possible flush candidate set. */
+	unmarkMaybePending() {
+		require_EntityManager.getEmInternalApi(this.em).unmarkMaybePending(this.entity);
+	}
+	/** Remembers a reference value that may need to be reverse-walked later. */
+	rememberReferenceValue(fieldName, value) {
+		if (value === void 0) return;
+		const values = (this.#referenceHistory ??= {})[fieldName] ??= [];
+		if (!values.includes(value)) values.push(value);
+	}
+	/** Returns reference values that may need to be reverse-walked later. */
+	getReferenceHistory(fieldName) {
+		return this.#referenceHistory?.[fieldName] ?? emptyArray;
+	}
+	get isDeletedAndFlushed() {
+		return this.#deleted === 3;
+	}
+	/**
+	* Returns true if the entity is new or was new in this EM.
+	*
+	* This is primarily used for lazy-initializing relations, i.e. if:
+	*
+	* - A new `Author` is created
+	* - We `em.flush` the author to the database
+	* - Then `a1.books` is accessed for the first time
+	*
+	* We can have a high-confidence that `a1` has no books, because we just
+	* created it, so we can set the OneToManyCollection to loaded.
+	*/
+	get isOrWasNew() {
+		return this.#new !== void 0;
+	}
+};
+/** A shared frozen bag for un-mutated entities; strict mode makes accidental writes throw. */
+const emptyObject = Object.freeze({});
+/** A shared frozen array for fields with no remembered reference values. */
+const emptyArray = Object.freeze([]);
+//#endregion
+exports.InstanceData = InstanceData;
+
+//# sourceMappingURL=InstanceData.cjs.map

package/build/InstanceData.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"InstanceData.cjs","names":["emptyRowData","#new","#flags","#deleted","#originalData","#referenceHistory","hasAnyKey"],"sources":["../src/InstanceData.ts"],"sourcesContent":["import { type Entity } from \"src/Entity.ts\";\nimport { type EntityManager, getEmInternalApi } from \"src/EntityManager.ts\";\nimport { type EntityMetadata } from \"src/EntityMetadata.ts\";\nimport { type RowData, emptyRowData } from \"src/RowData.ts\";\nimport { hasAnyKey } from \"src/utils.ts\";\n\n/** The `#orm` metadata field we track on each instance. */\nexport class InstanceData {\n  /** The entity this instance data belongs to. */\n  readonly entity: Entity;\n  /** All entities must be associated to an `EntityManager` to handle lazy loading/etc. */\n  readonly em: EntityManager;\n  /** A pointer to our entity type's metadata. */\n  readonly metadata: EntityMetadata;\n  /** A bag for our lazy-initialized relations, allocated on first relation access. */\n  relations: Record<any, any> | undefined = undefined;\n  /** The as-loaded database row, i.e. our `rowIndex`-th row within our query's `RowData` result. */\n  rowData: RowData = emptyRowData;\n  /** Our row's index within `rowData`; see {@link RowData}. */\n  rowIndex: number = 0;\n  /** The domain-value of fields, lazily converted (if needed) on read from the database columns. */\n  data: Record<string, any>;\n  /** A bag to keep the original values, allocated on first mutation (most entities are never mutated). */\n  #originalData: Record<any, any> | undefined = undefined;\n  /** Reference values that were set during this unit of work, allocated on first m2o/poly change. */\n  #referenceHistory: Record<string, any[]> | undefined = undefined;\n  /** A bag to keep the flushed-to-database values, only for AsyncReactiveField reactivity. */\n  flushedData: Record<any, any> | undefined;\n  /** Packs the new/deleted `Operation`s + isTouched into one slot; see the accessors below. */\n  #flags: number = 0;\n  /** The `a#1`, `a#2` index if we're an em.create-d entity. We never unset this, to keep ids stable across flushes. */\n  createId: string | undefined;\n  /** The zero-based order this entity was registered with its EntityManager. */\n  entityIndex: number = -1;\n\n  /** Whether our entity is new or not. */\n  get #new(): Operation | undefined {\n    const value = this.#flags & 0b11;\n    return value === 0 ? undefined : value;\n  }\n\n  set #new(op: Operation | undefined) {\n    this.#flags = (this.#flags & ~0b11) | (op ?? 0);\n  }\n\n  /**\n   * Whether our entity has been deleted or not.\n   *\n   * - `pending` means we've been marked for deletion via `em.delete` but not issued a `DELETE`\n   * - `flushed` means we've flushed a `DELETE` but `em.flush` hasn't fully completed yet, likely due to AsyncReactiveField calcs\n   * - `deleted` means we've been flushed and `em.flush` has completed\n   */\n  get #deleted(): Operation | undefined {\n    const value = (this.#flags >> 2) & 0b11;\n    return value === 0 ? undefined : value;\n  }\n\n  set #deleted(op: Operation | undefined) {\n    this.#flags = (this.#flags & ~0b1100) | ((op ?? 0) << 2);\n  }\n\n  /** Whether our entity should flush regardless of any other changes. */\n  get isTouched(): boolean {\n    return (this.#flags & 0b10000) !== 0;\n  }\n\n  set isTouched(value: boolean) {\n    this.#flags = value ? this.#flags | 0b10000 : this.#flags & ~0b10000;\n  }\n\n  /** Creates the `#orm` field. */\n  constructor(em: EntityManager, entity: Entity, metadata: EntityMetadata, isNew: boolean) {\n    this.entity = entity;\n    this.em = em;\n    this.metadata = metadata;\n    if (isNew) {\n      this.#new = Operation.Pending;\n      this.data = {};\n      this.flushedData = undefined;\n      if (em) this.markMaybePending();\n    } else {\n      this.#new = undefined;\n      this.data = {};\n      this.flushedData = undefined;\n    }\n  }\n\n  /**\n   * Returns the as-loaded value of `columnName`, i.e. `getColumn(\"rank\")`.\n   *\n   * This saves callers from knowing that `rowData`/`rowIndex` are a pair, but note it is\n   * a snapshot of the query that loaded us, and specifically:\n   *\n   * - The value is driver-level, i.e. numeric enum ids, untagged foreign keys, and temporals\n   *   as strings; use `getField` if you want the domain value, and\n   * - The value is not updated by `em.flush`, so after a flush it is the pre-flush value, and\n   * - New entities have no row, so every column is `undefined`.\n   */\n  getColumn(columnName: string): any {\n    return this.rowData.get(this.rowIndex, columnName);\n  }\n\n  /** If `em.flush` has detected a dirty RQF, reset our internal dirty state, w/o reseting our external-dirty state. */\n  resetForRqfLoop() {\n    this.flushedData = {};\n    if (this.#new === Operation.Pending) this.#new = Operation.Flushed;\n    if (this.#deleted === Operation.Pending) this.#deleted = Operation.Flushed;\n  }\n\n  resetAfterFlushed() {\n    this.#originalData = undefined;\n    this.#referenceHistory = undefined;\n    this.flushedData = undefined;\n    this.isTouched = false;\n    if (this.#new === Operation.Pending || this.#new === Operation.Flushed) {\n      this.#new = Operation.Complete;\n    }\n    if (this.#deleted === Operation.Pending || this.#deleted === Operation.Flushed) {\n      this.#deleted = Operation.Complete;\n    }\n    this.unmarkMaybePending();\n  }\n\n  /** Our public-facing `isNewEntity`. */\n  get isNewEntity(): boolean {\n    return this.#new !== undefined && this.#new !== Operation.Complete;\n  }\n\n  /** Our public-facing `isDeletedEntity`. */\n  get isDeletedEntity(): boolean {\n    return this.#deleted !== undefined;\n  }\n\n  /** The original values of mutated fields; a shared empty object until the entity is actually mutated. */\n  get originalData(): Record<any, any> {\n    return this.#originalData ?? emptyObject;\n  }\n\n  /** Our public-facing `isDirtyEntity`. */\n  get isDirtyEntity(): boolean {\n    return hasAnyKey(this.#originalData);\n  }\n\n  /** This is our internal \"is pending flush\", which is aware of RQF micro-flush loops. */\n  get pendingOperation(): \"insert\" | \"update\" | \"delete\" | \"none\" | \"created-then-deleted\" {\n    if (this.#deleted !== undefined) {\n      // Mark entities that were created and them immediately `em.delete`-d; granted this is\n      // probably rare, but we shouldn't run hooks or have the driver try and delete these.\n      // Note that we return them, instead of skipping entirely, so that fixupCreatedThenDeleted\n      // can later be called.\n      return this.#deleted === Operation.Pending && this.#new === Operation.Pending\n        ? \"created-then-deleted\"\n        : this.#deleted === Operation.Pending\n          ? \"delete\"\n          : \"none\";\n    } else if (this.#new === Operation.Pending) {\n      // Per ^, if `#new === flushed`, we fall through to check if micro-flush UPDATEs are required\n      return \"insert\";\n    } else if (this.flushedData) {\n      return hasAnyKey(this.flushedData) ? \"update\" : \"none\";\n    } else {\n      return this.isTouched || hasAnyKey(this.#originalData) ? \"update\" : \"none\";\n    }\n  }\n\n  get changedFields(): string[] {\n    return Object.keys(this.changedData);\n  }\n\n  /** The changed-fields bag (flushedData during RQF loops, else originalData) without allocating a keys array. */\n  get changedData(): Record<any, any> {\n    return this.flushedData ?? this.#originalData ?? emptyObject;\n  }\n\n  /** Called when an `em.load` tries to find the entity and it's just gone from the db. */\n  markDeletedBecauseNotFound(): void {\n    this.#deleted = Operation.Complete;\n  }\n\n  /** Called by `em.delete`, returns true if this is new information. */\n  markDeleted(): boolean {\n    if (this.#deleted === undefined) {\n      // Let any OneToManyCollection/ReactiveField/ReactiveReference.get caches know that they should recalc\n      // (i.e. their filterDeleted logic) by asserting the `deleteBook.author` field is changing.\n      for (const field of Object.values(this.metadata.allFields)) {\n        // We only do reference/collection fields and skip the primitives, b/c we assume something like\n        // `{ books: \"title\" }` doesn't need `resetIsLoaded(..., \"title\")` b/c the same hint will also\n        // be watching \"did books change\", and so get reset that way.\n        if (field.kind === \"m2o\" || field.kind === \"poly\" || field.kind === \"m2m\" || field.kind === \"m2mEnum\") {\n          getEmInternalApi(this.em).isLoadedCache.resetIsLoaded(this.entity, field.fieldName);\n        } else if (field.kind === \"primitive\" || field.kind === \"enum\" || field.kind === \"primaryKey\") {\n          // Any reactable watching these fields will also be watching reference/collection\n        } else if (field.kind === \"o2m\" || field.kind === \"o2o\") {\n          // Any reactable watching these actually gets triggered by the primary m2o/poly side changing\n        } else if (field.kind === \"lo2m\") {\n          // Doesn't support reactivity\n        } else {\n          throw new Error(`Unhandled field kind ${field}`);\n        }\n      }\n      this.#deleted = Operation.Pending;\n      this.markMaybePending();\n      return true;\n    }\n    return false;\n  }\n\n  fixupCreatedThenDeleted(): void {\n    // Ideally we could do this via `resetAfterFlushed`?\n    this.#deleted = Operation.Complete;\n    this.unmarkMaybePending();\n  }\n\n  /** Marks this entity as needing a flush even if no fields changed. */\n  markTouched(): void {\n    this.isTouched = true;\n    this.markMaybePending();\n  }\n\n  /** Marks a field as dirty with its pre-mutation value. */\n  markFieldDirty(fieldName: string, value: any): void {\n    (this.#originalData ??= {})[fieldName] = value;\n    this.markMaybePending();\n  }\n\n  /** Marks a reverted field as clean again. */\n  markFieldClean(fieldName: string): void {\n    if (this.#originalData) delete this.#originalData[fieldName];\n    this.markMaybePending();\n  }\n\n  /** Marks this entity as a possible flush candidate. */\n  markMaybePending(): void {\n    getEmInternalApi(this.em).markMaybePending(this.entity);\n  }\n\n  /** Removes this entity from the possible flush candidate set. */\n  private unmarkMaybePending(): void {\n    getEmInternalApi(this.em).unmarkMaybePending(this.entity);\n  }\n\n  /** Remembers a reference value that may need to be reverse-walked later. */\n  rememberReferenceValue(fieldName: string, value: any): void {\n    if (value === undefined) return;\n    const values = ((this.#referenceHistory ??= {})[fieldName] ??= []);\n    if (!values.includes(value)) values.push(value);\n  }\n\n  /** Returns reference values that may need to be reverse-walked later. */\n  getReferenceHistory(fieldName: string): readonly any[] {\n    return this.#referenceHistory?.[fieldName] ?? emptyArray;\n  }\n\n  get isDeletedAndFlushed(): boolean {\n    return this.#deleted === Operation.Complete;\n  }\n\n  /**\n   * Returns true if the entity is new or was new in this EM.\n   *\n   * This is primarily used for lazy-initializing relations, i.e. if:\n   *\n   * - A new `Author` is created\n   * - We `em.flush` the author to the database\n   * - Then `a1.books` is accessed for the first time\n   *\n   * We can have a high-confidence that `a1` has no books, because we just\n   * created it, so we can set the OneToManyCollection to loaded.\n   */\n  get isOrWasNew(): boolean {\n    // #new will be left as `complete`\n    return this.#new !== undefined;\n  }\n}\n\n/** An enum to track our insert/delete state progression. */\nenum Operation {\n  Pending = 1,\n  Flushed = 2,\n  Complete = 3,\n}\n\n/** A shared frozen bag for un-mutated entities; strict mode makes accidental writes throw. */\nconst emptyObject: Record<any, any> = Object.freeze({});\n\n/** A shared frozen array for fields with no remembered reference values. */\nconst emptyArray: readonly any[] = Object.freeze([]);\n"],"mappings":"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"}

package/build/InstanceData.d.cts

@@ -0,0 +1,98 @@
+import { RowData } from "./RowData.cjs";
+import { EntityMetadata } from "./EntityMetadata.cjs";
+import { EntityManager } from "./EntityManager.cjs";
+import { Entity } from "./Entity.cjs";
+//#region src/InstanceData.d.ts
+/** The `#orm` metadata field we track on each instance. */
+declare class InstanceData {
+  #private;
+  /** The entity this instance data belongs to. */
+  readonly entity: Entity;
+  /** All entities must be associated to an `EntityManager` to handle lazy loading/etc. */
+  readonly em: EntityManager;
+  /** A pointer to our entity type's metadata. */
+  readonly metadata: EntityMetadata;
+  /** A bag for our lazy-initialized relations, allocated on first relation access. */
+  relations: Record<any, any> | undefined;
+  /** The as-loaded database row, i.e. our `rowIndex`-th row within our query's `RowData` result. */
+  rowData: RowData;
+  /** Our row's index within `rowData`; see {@link RowData}. */
+  rowIndex: number;
+  /** The domain-value of fields, lazily converted (if needed) on read from the database columns. */
+  data: Record<string, any>;
+  /** A bag to keep the flushed-to-database values, only for AsyncReactiveField reactivity. */
+  flushedData: Record<any, any> | undefined;
+  /** The `a#1`, `a#2` index if we're an em.create-d entity. We never unset this, to keep ids stable across flushes. */
+  createId: string | undefined;
+  /** The zero-based order this entity was registered with its EntityManager. */
+  entityIndex: number;
+  /** Whether our entity should flush regardless of any other changes. */
+  get isTouched(): boolean;
+  set isTouched(value: boolean);
+  /** Creates the `#orm` field. */
+  constructor(em: EntityManager, entity: Entity, metadata: EntityMetadata, isNew: boolean);
+  /**
+   * Returns the as-loaded value of `columnName`, i.e. `getColumn("rank")`.
+   *
+   * This saves callers from knowing that `rowData`/`rowIndex` are a pair, but note it is
+   * a snapshot of the query that loaded us, and specifically:
+   *
+   * - The value is driver-level, i.e. numeric enum ids, untagged foreign keys, and temporals
+   *   as strings; use `getField` if you want the domain value, and
+   * - The value is not updated by `em.flush`, so after a flush it is the pre-flush value, and
+   * - New entities have no row, so every column is `undefined`.
+   */
+  getColumn(columnName: string): any;
+  /** If `em.flush` has detected a dirty RQF, reset our internal dirty state, w/o reseting our external-dirty state. */
+  resetForRqfLoop(): void;
+  resetAfterFlushed(): void;
+  /** Our public-facing `isNewEntity`. */
+  get isNewEntity(): boolean;
+  /** Our public-facing `isDeletedEntity`. */
+  get isDeletedEntity(): boolean;
+  /** The original values of mutated fields; a shared empty object until the entity is actually mutated. */
+  get originalData(): Record<any, any>;
+  /** Our public-facing `isDirtyEntity`. */
+  get isDirtyEntity(): boolean;
+  /** This is our internal "is pending flush", which is aware of RQF micro-flush loops. */
+  get pendingOperation(): "insert" | "update" | "delete" | "none" | "created-then-deleted";
+  get changedFields(): string[];
+  /** The changed-fields bag (flushedData during RQF loops, else originalData) without allocating a keys array. */
+  get changedData(): Record<any, any>;
+  /** Called when an `em.load` tries to find the entity and it's just gone from the db. */
+  markDeletedBecauseNotFound(): void;
+  /** Called by `em.delete`, returns true if this is new information. */
+  markDeleted(): boolean;
+  fixupCreatedThenDeleted(): void;
+  /** Marks this entity as needing a flush even if no fields changed. */
+  markTouched(): void;
+  /** Marks a field as dirty with its pre-mutation value. */
+  markFieldDirty(fieldName: string, value: any): void;
+  /** Marks a reverted field as clean again. */
+  markFieldClean(fieldName: string): void;
+  /** Marks this entity as a possible flush candidate. */
+  markMaybePending(): void;
+  /** Removes this entity from the possible flush candidate set. */
+  private unmarkMaybePending;
+  /** Remembers a reference value that may need to be reverse-walked later. */
+  rememberReferenceValue(fieldName: string, value: any): void;
+  /** Returns reference values that may need to be reverse-walked later. */
+  getReferenceHistory(fieldName: string): readonly any[];
+  get isDeletedAndFlushed(): boolean;
+  /**
+   * Returns true if the entity is new or was new in this EM.
+   *
+   * This is primarily used for lazy-initializing relations, i.e. if:
+   *
+   * - A new `Author` is created
+   * - We `em.flush` the author to the database
+   * - Then `a1.books` is accessed for the first time
+   *
+   * We can have a high-confidence that `a1` has no books, because we just
+   * created it, so we can set the OneToManyCollection to loaded.
+   */
+  get isOrWasNew(): boolean;
+}
+//#endregion
+export { InstanceData };
+//# sourceMappingURL=InstanceData.d.cts.map

package/build/InstanceData.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InstanceData.d.cts","names":[],"sources":["../src/InstanceData.ts"],"mappings":";;;;;;cAOa;;;WAEF,QAAQ;;WAER,IAAI;;WAEJ,UAAU;;EAEnB,WAAW;;EAEX,SAAS;;EAET;;EAEA,MAAM;;EAMN,aAAa;;EAIb;;EAEA;;MA6BI;MAIA,UAAU;;EAKd,YAAY,IAAI,eAAe,QAAQ,QAAQ,UAAU,gBAAgB;;;;;;;;;;;;EA2BzE,UAAU;;EAKV;EAMA;;MAeI;;MAKA;;MAKA,gBAAgB;;MAKhB;;MAKA;MAqBA;;MAKA,eAAe;;EAKnB;;EAKA;EA2BA;;EAOA;;EAMA,eAAe,mBAAmB;;EAMlC,eAAe;;EAMf;;UAKQ;;EAKR,uBAAuB,mBAAmB;;EAO1C,oBAAoB;MAIhB;;;;;;;;;;;;;MAgBA"}

package/build/InstanceData.d.mts

@@ -0,0 +1,98 @@
+import { RowData } from "./RowData.mjs";
+import { EntityMetadata } from "./EntityMetadata.mjs";
+import { EntityManager } from "./EntityManager.mjs";
+import { Entity } from "./Entity.mjs";
+//#region src/InstanceData.d.ts
+/** The `#orm` metadata field we track on each instance. */
+declare class InstanceData {
+  #private;
+  /** The entity this instance data belongs to. */
+  readonly entity: Entity;
+  /** All entities must be associated to an `EntityManager` to handle lazy loading/etc. */
+  readonly em: EntityManager;
+  /** A pointer to our entity type's metadata. */
+  readonly metadata: EntityMetadata;
+  /** A bag for our lazy-initialized relations, allocated on first relation access. */
+  relations: Record<any, any> | undefined;
+  /** The as-loaded database row, i.e. our `rowIndex`-th row within our query's `RowData` result. */
+  rowData: RowData;
+  /** Our row's index within `rowData`; see {@link RowData}. */
+  rowIndex: number;
+  /** The domain-value of fields, lazily converted (if needed) on read from the database columns. */
+  data: Record<string, any>;
+  /** A bag to keep the flushed-to-database values, only for AsyncReactiveField reactivity. */
+  flushedData: Record<any, any> | undefined;
+  /** The `a#1`, `a#2` index if we're an em.create-d entity. We never unset this, to keep ids stable across flushes. */
+  createId: string | undefined;
+  /** The zero-based order this entity was registered with its EntityManager. */
+  entityIndex: number;
+  /** Whether our entity should flush regardless of any other changes. */
+  get isTouched(): boolean;
+  set isTouched(value: boolean);
+  /** Creates the `#orm` field. */
+  constructor(em: EntityManager, entity: Entity, metadata: EntityMetadata, isNew: boolean);
+  /**
+   * Returns the as-loaded value of `columnName`, i.e. `getColumn("rank")`.
+   *
+   * This saves callers from knowing that `rowData`/`rowIndex` are a pair, but note it is
+   * a snapshot of the query that loaded us, and specifically:
+   *
+   * - The value is driver-level, i.e. numeric enum ids, untagged foreign keys, and temporals
+   *   as strings; use `getField` if you want the domain value, and
+   * - The value is not updated by `em.flush`, so after a flush it is the pre-flush value, and
+   * - New entities have no row, so every column is `undefined`.
+   */
+  getColumn(columnName: string): any;
+  /** If `em.flush` has detected a dirty RQF, reset our internal dirty state, w/o reseting our external-dirty state. */
+  resetForRqfLoop(): void;
+  resetAfterFlushed(): void;
+  /** Our public-facing `isNewEntity`. */
+  get isNewEntity(): boolean;
+  /** Our public-facing `isDeletedEntity`. */
+  get isDeletedEntity(): boolean;
+  /** The original values of mutated fields; a shared empty object until the entity is actually mutated. */
+  get originalData(): Record<any, any>;
+  /** Our public-facing `isDirtyEntity`. */
+  get isDirtyEntity(): boolean;
+  /** This is our internal "is pending flush", which is aware of RQF micro-flush loops. */
+  get pendingOperation(): "insert" | "update" | "delete" | "none" | "created-then-deleted";
+  get changedFields(): string[];
+  /** The changed-fields bag (flushedData during RQF loops, else originalData) without allocating a keys array. */
+  get changedData(): Record<any, any>;
+  /** Called when an `em.load` tries to find the entity and it's just gone from the db. */
+  markDeletedBecauseNotFound(): void;
+  /** Called by `em.delete`, returns true if this is new information. */
+  markDeleted(): boolean;
+  fixupCreatedThenDeleted(): void;
+  /** Marks this entity as needing a flush even if no fields changed. */
+  markTouched(): void;
+  /** Marks a field as dirty with its pre-mutation value. */
+  markFieldDirty(fieldName: string, value: any): void;
+  /** Marks a reverted field as clean again. */
+  markFieldClean(fieldName: string): void;
+  /** Marks this entity as a possible flush candidate. */
+  markMaybePending(): void;
+  /** Removes this entity from the possible flush candidate set. */
+  private unmarkMaybePending;
+  /** Remembers a reference value that may need to be reverse-walked later. */
+  rememberReferenceValue(fieldName: string, value: any): void;
+  /** Returns reference values that may need to be reverse-walked later. */
+  getReferenceHistory(fieldName: string): readonly any[];
+  get isDeletedAndFlushed(): boolean;
+  /**
+   * Returns true if the entity is new or was new in this EM.
+   *
+   * This is primarily used for lazy-initializing relations, i.e. if:
+   *
+   * - A new `Author` is created
+   * - We `em.flush` the author to the database
+   * - Then `a1.books` is accessed for the first time
+   *
+   * We can have a high-confidence that `a1` has no books, because we just
+   * created it, so we can set the OneToManyCollection to loaded.
+   */
+  get isOrWasNew(): boolean;
+}
+//#endregion
+export { InstanceData };
+//# sourceMappingURL=InstanceData.d.mts.map

package/build/InstanceData.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InstanceData.d.mts","names":[],"sources":["../src/InstanceData.ts"],"mappings":";;;;;;cAOa;;;WAEF,QAAQ;;WAER,IAAI;;WAEJ,UAAU;;EAEnB,WAAW;;EAEX,SAAS;;EAET;;EAEA,MAAM;;EAMN,aAAa;;EAIb;;EAEA;;MA6BI;MAIA,UAAU;;EAKd,YAAY,IAAI,eAAe,QAAQ,QAAQ,UAAU,gBAAgB;;;;;;;;;;;;EA2BzE,UAAU;;EAKV;EAMA;;MAeI;;MAKA;;MAKA,gBAAgB;;MAKhB;;MAKA;MAqBA;;MAKA,eAAe;;EAKnB;;EAKA;EA2BA;;EAOA;;EAMA,eAAe,mBAAmB;;EAMlC,eAAe;;EAMf;;UAKQ;;EAKR,uBAAuB,mBAAmB;;EAO1C,oBAAoB;MAIhB;;;;;;;;;;;;;MAgBA"}