joist-core 2.3.0 → 2.4.0

package/build/InstanceData.js

@@ -1,224 +1,217 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.InstanceData = void 0;
-const EntityManager_1 = require("./EntityManager");
+import { emptyRowData } from "./RowData.js";
+import { hasAnyKey } from "./utils.js";
+import "./EntityMetadata.js";
+import { getEmInternalApi } from "./EntityManager.js";
+import "./Entity.js";
+//#region src/InstanceData.ts
 /** The `#orm` metadata field we track on each instance. */
-class InstanceData {
-    /** 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. */
-    relations = {};
-    /** The database-value of columns, as-is returned from the driver. */
-    row;
-    /** The domain-value of fields, lazily converted (if needed) on read from the database columns. */
-    data;
-    /** A bag to keep the original values, lazily populated as fields are mutated. */
-    originalData = {};
-    /** Reference values that were set through during this unit of work and may need reverse-walking. */
-    referenceHistory = {};
-    /** A bag to keep the flushed-to-database values, only for AsyncReactiveField reactivity. */
-    flushedData;
-    /**
-     * 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
-     */
-    #deleted;
-    /** Whether our entity is new or not. */
-    #new;
-    /** 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 should flush regardless of any other changes. */
-    isTouched = false;
-    /** Creates the `#orm` field. */
-    constructor(em, entity, metadata, isNew) {
-        this.entity = entity;
-        this.em = em;
-        this.metadata = metadata;
-        if (isNew) {
-            this.#new = Operation.Pending;
-            this.data = {};
-            this.row = {};
-            this.flushedData = undefined;
-            if (em)
-                this.markMaybePending();
-        }
-        else {
-            this.#new = undefined;
-            this.data = {};
-            this.flushedData = undefined;
-        }
-    }
-    /** 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 === Operation.Pending)
-            this.#new = Operation.Flushed;
-        if (this.#deleted === Operation.Pending)
-            this.#deleted = Operation.Flushed;
-    }
-    resetAfterFlushed() {
-        this.originalData = {};
-        for (const fieldName of Object.keys(this.referenceHistory))
-            delete this.referenceHistory[fieldName];
-        this.flushedData = undefined;
-        this.isTouched = false;
-        if (this.#new === Operation.Pending || this.#new === Operation.Flushed) {
-            this.#new = Operation.Complete;
-        }
-        if (this.#deleted === Operation.Pending || this.#deleted === Operation.Flushed) {
-            this.#deleted = Operation.Complete;
-        }
-        this.unmarkMaybePending();
-    }
-    /** Our public-facing `isNewEntity`. */
-    get isNewEntity() {
-        return this.#new !== undefined && this.#new !== Operation.Complete;
-    }
-    /** Our public-facing `isDeletedEntity`. */
-    get isDeletedEntity() {
-        return this.#deleted !== undefined;
-    }
-    /** Our public-facing `isDirtyEntity`. */
-    get isDirtyEntity() {
-        return Object.keys(this.originalData).length > 0;
-    }
-    /** This is our internal "is pending flush", which is aware of RQF micro-flush loops. */
-    get pendingOperation() {
-        if (this.#deleted !== undefined) {
-            // Mark entities that were created and them immediately `em.delete`-d; granted this is
-            // probably rare, but we shouldn't run hooks or have the driver try and delete these.
-            // Note that we return them, instead of skipping entirely, so that fixupCreatedThenDeleted
-            // can later be called.
-            return this.#deleted === Operation.Pending && this.#new === Operation.Pending
-                ? "created-then-deleted"
-                : this.#deleted === Operation.Pending
-                    ? "delete"
-                    : "none";
-        }
-        else if (this.#new === Operation.Pending) {
-            // Per ^, if `#new === flushed`, we fall through to check if micro-flush UPDATEs are required
-            return "insert";
-        }
-        else if (this.flushedData) {
-            return Object.keys(this.flushedData).length > 0 ? "update" : "none";
-        }
-        else {
-            return this.isTouched || Object.keys(this.originalData).length > 0 ? "update" : "none";
-        }
-    }
-    get changedFields() {
-        return this.flushedData ? Object.keys(this.flushedData) : Object.keys(this.originalData);
-    }
-    /** Called when an `em.load` tries to find the entity and it's just gone from the db. */
-    markDeletedBecauseNotFound() {
-        this.#deleted = Operation.Complete;
-    }
-    /** Called by `em.delete`, returns true if this is new information. */
-    markDeleted() {
-        if (this.#deleted === undefined) {
-            // Let any OneToManyCollection/ReactiveField/ReactiveReference.get caches know that they should recalc
-            // (i.e. their filterDeleted logic) by asserting the `deleteBook.author` field is changing.
-            for (const field of Object.values(this.metadata.allFields)) {
-                // We only do reference/collection fields and skip the primitives, b/c we assume something like
-                // `{ books: "title" }` doesn't need `resetIsLoaded(..., "title")` b/c the same hint will also
-                // be watching "did books change", and so get reset that way.
-                if (field.kind === "m2o" || field.kind === "poly" || field.kind === "m2m" || field.kind === "m2mEnum") {
-                    (0, EntityManager_1.getEmInternalApi)(this.em).isLoadedCache.resetIsLoaded(this.entity, field.fieldName);
-                }
-                else if (field.kind === "primitive" || field.kind === "enum" || field.kind === "primaryKey") {
-                    // Any reactable watching these fields will also be watching reference/collection
-                }
-                else if (field.kind === "o2m" || field.kind === "o2o") {
-                    // Any reactable watching these actually gets triggered by the primary m2o/poly side changing
-                }
-                else if (field.kind === "lo2m") {
-                    // Doesn't support reactivity
-                }
-                else {
-                    throw new Error(`Unhandled field kind ${field}`);
-                }
-            }
-            this.#deleted = Operation.Pending;
-            this.markMaybePending();
-            return true;
-        }
-        return false;
-    }
-    fixupCreatedThenDeleted() {
-        // Ideally we could do this via `resetAfterFlushed`?
-        this.#deleted = Operation.Complete;
-        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) {
-        delete this.originalData[fieldName];
-        this.markMaybePending();
-    }
-    /** Marks this entity as a possible flush candidate. */
-    markMaybePending() {
-        (0, EntityManager_1.getEmInternalApi)(this.em).markMaybePending(this.entity);
-    }
-    /** Removes this entity from the possible flush candidate set. */
-    unmarkMaybePending() {
-        (0, EntityManager_1.getEmInternalApi)(this.em).unmarkMaybePending(this.entity);
-    }
-    /** Remembers a reference value that may need to be reverse-walked later. */
-    rememberReferenceValue(fieldName, value) {
-        if (value === undefined)
-            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] ?? [];
-    }
-    get isDeletedAndFlushed() {
-        return this.#deleted === Operation.Complete;
-    }
-    /**
-     * 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() {
-        // #new will be left as `complete`
-        return this.#new !== undefined;
-    }
-}
-exports.InstanceData = InstanceData;
-/** An enum to track our insert/delete state progression. */
-var Operation;
-(function (Operation) {
-    Operation[Operation["Pending"] = 1] = "Pending";
-    Operation[Operation["Flushed"] = 2] = "Flushed";
-    Operation[Operation["Complete"] = 3] = "Complete";
-})(Operation || (Operation = {}));
+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 = 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 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 hasAnyKey(this.flushedData) ? "update" : "none";
+		else return this.isTouched || 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") 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() {
+		getEmInternalApi(this.em).markMaybePending(this.entity);
+	}
+	/** Removes this entity from the possible flush candidate set. */
+	unmarkMaybePending() {
+		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
+export { InstanceData };
+
 //# sourceMappingURL=InstanceData.js.map

package/build/InstanceData.js.map

@@ -1 +1 @@
-{"version":3,"file":"InstanceData.js","sourceRoot":"","sources":["../src/InstanceData.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"InstanceData.js","names":["#new","#flags","#deleted","#originalData","#referenceHistory"],"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/PluginManager.cjs

@@ -0,0 +1,89 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("./EntityMetadata.cjs");
+const require_EntityManager = require("./EntityManager.cjs");
+require("./Entity.cjs");
+//#region src/PluginManager.ts
+const syncPluginMethods = [
+	"beforeGetField",
+	"beforeSetField",
+	"beforeFind",
+	"afterFind",
+	"afterWrite"
+];
+const asyncPluginMethods = ["beforeValidate", "afterValidate"];
+const emsSymbol = Symbol("ems");
+/**
+* Base class for plugins that hook into entity lifecycle events.
+*
+* Plugins can implement any of the PluginMethods to intercept entity operations
+* and are automatically registered with the EntityManager when added via PluginManager.
+*/
+var Plugin = class {
+	[emsSymbol] = [];
+	maybeCloneForNewEm() {}
+	get ems() {
+		return this[emsSymbol].values().map((wr) => wr.deref()).filter(require_EntityManager.isDefined).toArray();
+	}
+};
+/**
+* Manages plugin lifecycle and dispatches plugin callbacks to registered plugins.
+*
+* The PluginManager optimizes callback dispatch by only creating dispatcher methods
+* for callbacks that have at least one registered plugin, making unused plugin hooks
+* zero-cost at runtime.
+*/
+var PluginManager = class {
+	em;
+	#plugins = /* @__PURE__ */ new Set();
+	#pluginsByCallback = {};
+	constructor(em) {
+		this.em = em;
+	}
+	/** Returns whether any registered plugin implements `method`, i.e. so callers can skip building its args. */
+	hasHook(method) {
+		return this.#pluginsByCallback[method] !== void 0;
+	}
+	/**
+	* Registers a plugin with this EntityManager.
+	*
+	* Dynamically creates dispatcher methods for any plugin callbacks implemented by this plugin,
+	* enabling lazy initialization of only the hooks that are actually used.
+	*
+	* @throws Error if the plugin is already registered with another EntityManager
+	*/
+	addPlugin(plugin) {
+		if (this.#plugins.has(plugin)) return;
+		this.#plugins.add(plugin);
+		plugin[emsSymbol].push(new WeakRef(this.em));
+		for (const method of syncPluginMethods) if (method in plugin) {
+			(this.#pluginsByCallback[method] ??= []).push(plugin);
+			if (!Object.hasOwn(this, method)) this[method] = function(...args) {
+				for (const plugin of this.#pluginsByCallback[method]) plugin[method](...args);
+			};
+		}
+		for (const method of asyncPluginMethods) if (method in plugin) {
+			(this.#pluginsByCallback[method] ??= []).push(plugin);
+			if (!Object.hasOwn(this, method)) this[method] = async function(...args) {
+				for (const plugin of this.#pluginsByCallback[method]) await plugin[method](...args);
+			};
+		}
+	}
+	get plugins() {
+		return [...this.#plugins];
+	}
+	cloneTo(other) {
+		this.#plugins.values().map((plugin) => plugin.maybeCloneForNewEm()).filter(require_EntityManager.isDefined).forEach((plugin) => other.addPlugin(plugin));
+	}
+	beforeGetField(entity, field) {}
+	beforeSetField(entity, field, newValue) {}
+	beforeFind(meta, operation, query, settings) {}
+	afterFind(meta, operation, rows) {}
+	beforeValidate(entities) {}
+	afterValidate(entities) {}
+	afterWrite(entityTodos, joinRowTodos) {}
+};
+//#endregion
+exports.Plugin = Plugin;
+exports.PluginManager = PluginManager;
+
+//# sourceMappingURL=PluginManager.cjs.map

package/build/PluginManager.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"PluginManager.cjs","names":["isDefined","#pluginsByCallback","#plugins"],"sources":["../src/PluginManager.ts"],"sourcesContent":["import { type Entity } from \"src/Entity.ts\";\nimport { type EntityManager, type FindOperation, isDefined } from \"src/EntityManager.ts\";\nimport { type EntityMetadata } from \"src/EntityMetadata.ts\";\nimport type { JoinRowTodo, Todo } from \"src/flush/Todo.ts\";\nimport type { ParsedFindQuery } from \"src/queries/find/QueryParser.ts\";\nimport { type RowData } from \"src/RowData.ts\";\n\ninterface PluginMethods {\n  /**\n   * Called before a field value is retrieved from an entity via getField.\n   *\n   * @param entity The entity instance being accessed\n   * @param field The field name being retrieved\n   */\n  beforeGetField?(entity: Entity, field: string): void;\n  /**\n   * Called before a field value is set on an entity via setField.\n   *\n   * @param entity The entity instance being modified\n   * @param field The field name being set\n   * @param newValue The new value being assigned to the field\n   */\n  beforeSetField?(entity: Entity, field: string, newValue: any): void;\n  /**\n   * Called before a find operation is executed.\n   *\n   * @param meta Metadata for the entity type being queried\n   * @param operation The type of find operation being performed\n   * @param query The parsed query conditions\n   * @param settings Query settings including limit and offset\n   */\n  beforeFind?(\n    meta: EntityMetadata,\n    operation: FindOperation,\n    query: ParsedFindQuery,\n    settings: {\n      limit?: number;\n      offset?: number;\n      allowMultipleLeftJoins?: boolean;\n      optimizeJoinsToExists?: boolean;\n      pruneJoins?: boolean;\n      keepAliases?: string[];\n    },\n  ): void;\n  /**\n   * Called after a find operation has been executed to observe the raw database rows.\n   *\n   * The result is an observation-only {@link RowData} view — i.e. `rows.rowCount` for metrics,\n   * `rows.get(i, columnName)` for specific cells, or `rows.toRows()` to materialize POJO rows.\n   * For lazy results, cells decode on access, so a hook that only counts rows costs nothing;\n   * materializing via `toRows()` decodes every cell of every row. Mutating materialized rows is\n   * unsupported and is not guaranteed to affect entity hydration.\n   *\n   * @param meta Metadata for the entity type that was queried\n   * @param operation The type of find operation that was performed\n   * @param rows A read-only view of the raw database rows returned from the query\n   */\n  afterFind?(meta: EntityMetadata, operation: FindOperation, rows: RowData): void;\n\n  beforeValidate?(entities: readonly Entity[]): Promise<void> | void;\n\n  afterValidate?(entities: readonly Entity[]): Promise<void> | void;\n\n  afterWrite(entityTodos: Record<string, Todo>, joinRowTodos: Record<string, JoinRowTodo>): void;\n}\n\nconst syncPluginMethods = [\n  \"beforeGetField\",\n  \"beforeSetField\",\n  \"beforeFind\",\n  \"afterFind\",\n  \"afterWrite\",\n] as const satisfies readonly (keyof PluginMethods)[];\nconst asyncPluginMethods = [\"beforeValidate\", \"afterValidate\"] as const satisfies readonly (keyof PluginMethods)[];\nconst emsSymbol = Symbol(\"ems\");\n/**\n * Base class for plugins that hook into entity lifecycle events.\n *\n * Plugins can implement any of the PluginMethods to intercept entity operations\n * and are automatically registered with the EntityManager when added via PluginManager.\n */\nexport abstract class Plugin {\n  // We need to store the EntityManager references in a WeakRef array so that they can be garbage collected.  If we\n  // didn't do this, then multiple EMs with the same plugin instance could keep each other from being garbage collected.\n  [emsSymbol]: WeakRef<EntityManager>[] = [];\n\n  maybeCloneForNewEm(): this | undefined {\n    return undefined;\n  }\n\n  get ems(): readonly EntityManager[] {\n    return this[emsSymbol]\n      .values()\n      .map((wr) => wr.deref())\n      .filter(isDefined)\n      .toArray();\n  }\n}\n\nexport interface Plugin extends PluginMethods {}\n\n/**\n * Manages plugin lifecycle and dispatches plugin callbacks to registered plugins.\n *\n * The PluginManager optimizes callback dispatch by only creating dispatcher methods\n * for callbacks that have at least one registered plugin, making unused plugin hooks\n * zero-cost at runtime.\n */\nexport class PluginManager implements Required<PluginMethods> {\n  #plugins = new Set<Plugin>();\n  readonly #pluginsByCallback: Partial<Record<keyof Plugin, Plugin[]>> = {};\n  constructor(public readonly em: EntityManager) {}\n\n  /** Returns whether any registered plugin implements `method`, i.e. so callers can skip building its args. */\n  hasHook(method: keyof PluginMethods): boolean {\n    return this.#pluginsByCallback[method] !== undefined;\n  }\n\n  /**\n   * Registers a plugin with this EntityManager.\n   *\n   * Dynamically creates dispatcher methods for any plugin callbacks implemented by this plugin,\n   * enabling lazy initialization of only the hooks that are actually used.\n   *\n   * @throws Error if the plugin is already registered with another EntityManager\n   */\n  addPlugin(plugin: Plugin) {\n    if (this.#plugins.has(plugin)) return; // if we're already added, then we can just early exit\n    this.#plugins.add(plugin);\n    plugin[emsSymbol].push(new WeakRef(this.em));\n    for (const method of syncPluginMethods) {\n      if (method in plugin) {\n        (this.#pluginsByCallback[method] ??= []).push(plugin);\n        // As a performance optimization, we only create the actual implementation for each method on the plugin manager\n        // once we have at least one plugin using that method. This is to make it so any unused plugin methods are\n        // effectively no-ops when called from within the em.\n        if (!Object.hasOwn(this, method)) {\n          this[method] = function (this: PluginManager, ...args: any[]) {\n            for (const plugin of this.#pluginsByCallback[method]!) {\n              (plugin[method] as (...args: any[]) => unknown)(...args);\n            }\n          };\n        }\n      }\n    }\n    for (const method of asyncPluginMethods) {\n      if (method in plugin) {\n        (this.#pluginsByCallback[method] ??= []).push(plugin);\n        // Validate-phase plugin hooks are intentionally awaited without making hot-path hooks async.\n        if (!Object.hasOwn(this, method)) {\n          this[method] = async function (this: PluginManager, ...args: any[]) {\n            for (const plugin of this.#pluginsByCallback[method]!) {\n              await (plugin[method] as (...args: any[]) => Promise<void> | void)(...args);\n            }\n          };\n        }\n      }\n    }\n  }\n\n  get plugins(): readonly Plugin[] {\n    return [...this.#plugins];\n  }\n\n  cloneTo(other: PluginManager) {\n    this.#plugins\n      .values()\n      .map((plugin) => plugin.maybeCloneForNewEm())\n      .filter(isDefined)\n      .forEach((plugin) => other.addPlugin(plugin));\n  }\n\n  // Defined as no-op functions initially instead of using optional chaining for performance reasons, see:\n  // https://adventures.nodeland.dev/archive/noop-functions-vs-optional-chaining-a-performance/\n\n  beforeGetField(entity: Entity, field: string): void {}\n  beforeSetField(entity: Entity, field: string, newValue: any): void {}\n  beforeFind(\n    meta: EntityMetadata,\n    operation: FindOperation,\n    query: ParsedFindQuery,\n    settings: {\n      limit?: number;\n      offset?: number;\n      allowMultipleLeftJoins?: boolean;\n      optimizeJoinsToExists?: boolean;\n      pruneJoins?: boolean;\n      keepAliases?: string[];\n    },\n  ): void {}\n  afterFind(meta: EntityMetadata, operation: FindOperation, rows: RowData) {}\n  beforeValidate(entities: readonly Entity[]): Promise<void> | void {}\n  afterValidate(entities: readonly Entity[]): Promise<void> | void {}\n  afterWrite(entityTodos: Record<string, Todo>, joinRowTodos: Record<string, JoinRowTodo>): void {}\n}\n"],"mappings":";;;;;AAkEA,MAAM,oBAAoB;CACxB;CACA;CACA;CACA;CACA;AACF;AACA,MAAM,qBAAqB,CAAC,kBAAkB,eAAe;AAC7D,MAAM,YAAY,OAAO,KAAK;;;;;;;AAO9B,IAAsB,SAAtB,MAA6B;CAG3B,CAAC,aAAuC,CAAC;CAEzC,qBAAuC,CAEvC;CAEA,IAAI,MAAgC;EAClC,OAAO,KAAK,UAAU,CACnB,OAAO,CAAC,CACR,KAAK,OAAO,GAAG,MAAM,CAAC,CAAC,CACvB,OAAOA,sBAAAA,SAAS,CAAC,CACjB,QAAQ;CACb;AACF;;;;;;;;AAWA,IAAa,gBAAb,MAA8D;CAGhC;CAF5B,2BAAW,IAAI,IAAY;CAC3B,qBAAuE,CAAC;CACxE,YAAY,IAAmC;EAAnB,KAAA,KAAA;CAAoB;;CAGhD,QAAQ,QAAsC;EAC5C,OAAO,KAAKC,mBAAmB,YAAY,KAAA;CAC7C;;;;;;;;;CAUA,UAAU,QAAgB;EACxB,IAAI,KAAKC,SAAS,IAAI,MAAM,GAAG;EAC/B,KAAKA,SAAS,IAAI,MAAM;EACxB,OAAO,UAAU,CAAC,KAAK,IAAI,QAAQ,KAAK,EAAE,CAAC;EAC3C,KAAK,MAAM,UAAU,mBACnB,IAAI,UAAU,QAAQ;GACpB,CAAC,KAAKD,mBAAmB,YAAY,CAAC,EAAA,CAAG,KAAK,MAAM;GAIpD,IAAI,CAAC,OAAO,OAAO,MAAM,MAAM,GAC7B,KAAK,UAAU,SAA+B,GAAG,MAAa;IAC5D,KAAK,MAAM,UAAU,KAAKA,mBAAmB,SAC3C,OAAQ,OAAO,CAAiC,GAAG,IAAI;GAE3D;EAEJ;EAEF,KAAK,MAAM,UAAU,oBACnB,IAAI,UAAU,QAAQ;GACpB,CAAC,KAAKA,mBAAmB,YAAY,CAAC,EAAA,CAAG,KAAK,MAAM;GAEpD,IAAI,CAAC,OAAO,OAAO,MAAM,MAAM,GAC7B,KAAK,UAAU,eAAqC,GAAG,MAAa;IAClE,KAAK,MAAM,UAAU,KAAKA,mBAAmB,SAC3C,MAAO,OAAO,OAAO,CAA8C,GAAG,IAAI;GAE9E;EAEJ;CAEJ;CAEA,IAAI,UAA6B;EAC/B,OAAO,CAAC,GAAG,KAAKC,QAAQ;CAC1B;CAEA,QAAQ,OAAsB;EAC5B,KAAKA,SACF,OAAO,CAAC,CACR,KAAK,WAAW,OAAO,mBAAmB,CAAC,CAAC,CAC5C,OAAOF,sBAAAA,SAAS,CAAC,CACjB,SAAS,WAAW,MAAM,UAAU,MAAM,CAAC;CAChD;CAKA,eAAe,QAAgB,OAAqB,CAAC;CACrD,eAAe,QAAgB,OAAe,UAAqB,CAAC;CACpE,WACE,MACA,WACA,OACA,UAQM,CAAC;CACT,UAAU,MAAsB,WAA0B,MAAe,CAAC;CAC1E,eAAe,UAAmD,CAAC;CACnE,cAAc,UAAmD,CAAC;CAClE,WAAW,aAAmC,cAAiD,CAAC;AAClG"}