bunsane 0.1.4 → 0.2.0

package/core/Entity.ts

@@ -1,13 +1,14 @@
-import type { ComponentDataType, ComponentGetter, BaseComponent } from "./Components";
+import type { ComponentDataType, ComponentGetter, BaseComponent } from "./components";
 import { logger } from "./Logger";
-import db from "database";
+import db from "../database";
 import EntityManager from "./EntityManager";
-import ComponentRegistry from "./ComponentRegistry";
-import { uuidv7 } from "utils/uuid";
-import { sql } from "bun";
+import ComponentRegistry from "./components/ComponentRegistry";
+import { uuidv7 } from "../utils/uuid";
+import { sql, SQL } from "bun";
 // import Query from "./Query"; // Lazy import to avoid cycle
 import { timed } from "./Decorators";
 import EntityHookManager from "./EntityHookManager";
+import { getMetadataStorage } from "./metadata";
 import { EntityCreatedEvent, EntityUpdatedEvent, EntityDeletedEvent, ComponentAddedEvent, ComponentUpdatedEvent, ComponentRemovedEvent } from "./events/EntityLifecycleEvents";
 import type { IEntity } from "./EntityInterface";
 
@@ -16,10 +17,14 @@ export class Entity implements IEntity {
     public _persisted: boolean = false;
     private components: Map<string, BaseComponent> = new Map<string, BaseComponent>();
     private removedComponents: Set<string> = new Set<string>();
+    // Track components that were removed and already saved to DB
+    // This persists after save() so resolvers can detect removed components
+    private savedRemovedComponents: Set<string> = new Set<string>();
     protected _dirty: boolean = false;
 
     constructor(id?: string) {
-        this.id = id ?? uuidv7();
+        // Use || instead of ?? to also handle empty strings
+        this.id = (id && id.trim() !== '') ? id : uuidv7();
         this._dirty = true;
     }
 
@@ -27,6 +32,10 @@ export class Entity implements IEntity {
         return new Entity();
     }
 
+    public static CreateWithId(id: string): Entity {
+        return new Entity(id);
+    }
+
     protected addComponent(component: BaseComponent): Entity {
         this.components.set(component.getTypeID(), component);
         return this;
@@ -36,6 +45,38 @@ export class Entity implements IEntity {
         return Array.from(this.components.values());
     }
 
+    /**
+     * Synchronously check if a component is already loaded in memory.
+     * This does NOT trigger a database fetch - use get() for that.
+     * @param ctor Component constructor
+     * @returns Component instance if already in memory, undefined otherwise
+     */
+    public getInMemory<T extends BaseComponent>(ctor: new (...args: any[]) => T): T | undefined {
+        return Array.from(this.components.values()).find(comp => comp instanceof ctor) as T | undefined;
+    }
+
+    /**
+     * Check if a component exists in memory (synchronous, no DB fetch).
+     * @param ctor Component constructor
+     * @returns true if component is already loaded in memory
+     */
+    public hasInMemory<T extends BaseComponent>(ctor: new (...args: any[]) => T): boolean {
+        return Array.from(this.components.values()).some(comp => comp instanceof ctor);
+    }
+
+    /**
+     * Check if a component was explicitly removed from this entity (pending or already saved deletion).
+     * Useful in resolvers to avoid returning stale cached data for removed components.
+     * @param ctor Component constructor
+     * @returns true if component was removed (pending or saved)
+     */
+    public wasRemoved<T extends BaseComponent>(ctor: new (...args: any[]) => T): boolean {
+        const temp = new ctor();
+        const typeId = temp.getTypeID();
+        // Check both pending removals and already-saved removals
+        return this.removedComponents.has(typeId) || this.savedRemovedComponents.has(typeId);
+    }
+
     /**
      * Adds a new component to the entity.
      * Use like: entity.add(Component, { value: "Test" })
@@ -66,8 +107,8 @@ export class Entity implements IEntity {
      * If it doesn't exist, it adds a new component.
      * Use like: entity.set(Component, { value: "Test" })
      */
-    public async set<T extends BaseComponent>(ctor: new (...args: any[]) => T, data: Partial<ComponentDataType<T>>): Promise<this> {
-        await this.get(ctor);
+    public async set<T extends BaseComponent>(ctor: new (...args: any[]) => T, data: Partial<ComponentDataType<T>>, context?: { loaders?: { componentsByEntityType?: any }; trx?: SQL }): Promise<this> {
+        await this.get(ctor, context);
         
         const component = Array.from(this.components.values()).find(comp => comp instanceof ctor) as T;
         if (component) {
@@ -86,6 +127,35 @@ export class Entity implements IEntity {
                 logger.error(`Error firing component updated hook for ${component.getTypeID()}: ${error}`);
                 // Don't fail the set operation if hooks fail
             }
+            
+            // Invalidate DataLoader cache if context is provided
+            if (context?.loaders?.componentsByEntityType) {
+                context.loaders.componentsByEntityType.clear({
+                    entityId: this.id,
+                    typeId: component.getTypeID()
+                });
+            }
+            
+            // Handle cache operations for component update
+            setImmediate(async () => {
+                try {
+                    const { CacheManager } = await import('./cache/CacheManager');
+                    const cacheManager = CacheManager.getInstance();
+                    const config = cacheManager.getConfig();
+                    
+                    if (config.enabled && config.component?.enabled) {
+                        if (config.strategy === 'write-through') {
+                            // Write-through: update cache with new component data
+                            await cacheManager.setComponentWriteThrough(this.id, [component], component.getTypeID(), config.component.ttl);
+                        } else {
+                            // Write-invalidate: remove from cache
+                            await cacheManager.invalidateComponent(this.id, component.getTypeID());
+                        }
+                    }
+                } catch (error) {
+                    logger.warn({ scope: 'cache', component: 'Entity', msg: 'Cache operation failed after set', error });
+                }
+            });
         } else {
             // Add new component
             this.add(ctor, data);
@@ -102,101 +172,218 @@ export class Entity implements IEntity {
      * If you want to keep the component in the database but just remove it from the entity instance,
      * consider implementing a different method.
      */
-    public remove<T extends BaseComponent>(ctor: new (...args: any[]) => T): boolean {
+    public remove<T extends BaseComponent>(ctor: new (...args: any[]) => T, context?: { loaders?: { componentsByEntityType?: any }; trx?: SQL }): boolean {
         const component = Array.from(this.components.values()).find(comp => comp instanceof ctor) as T;
         
         if (component) {
+            const typeId = component.getTypeID();
+            
             // Track the component type for database deletion
-            this.removedComponents.add(component.getTypeID());
+            this.removedComponents.add(typeId);
             
             // Remove the component from the map
-            this.components.delete(component.getTypeID());
+            this.components.delete(typeId);
             this._dirty = true;
             
             // Fire component removed event
             try {
                 EntityHookManager.executeHooks(new ComponentRemovedEvent(this, component));
             } catch (error) {
-                logger.error(`Error firing component removed hook for ${component.getTypeID()}: ${error}`);
+                logger.error(`Error firing component removed hook for ${typeId}: ${error}`);
                 // Don't fail the remove operation if hooks fail
             }
             
+            // Invalidate DataLoader cache if context is provided
+            if (context?.loaders?.componentsByEntityType) {
+                context.loaders.componentsByEntityType.clear({
+                    entityId: this.id,
+                    typeId: typeId
+                });
+            }
+            
+            // Invalidate cache for removed component
+            setImmediate(async () => {
+                try {
+                    const { CacheManager } = await import('./cache/CacheManager');
+                    const cacheManager = CacheManager.getInstance();
+                    const config = cacheManager.getConfig();
+                    
+                    if (config.enabled && config.component?.enabled) {
+                        await cacheManager.invalidateComponent(this.id, typeId);
+                    }
+                } catch (error) {
+                    logger.warn({ scope: 'cache', component: 'Entity', msg: 'Cache invalidation failed after remove', error });
+                }
+            });
+            
             return true;
         }
         
         return false;
     }
+
     /**
-     * Get component from entities. If entity is populated in query the component will get within the entitiy
-     * If not it will fetch from database
-     * @param Component
-     * @returns `Component | null` *if entity doesn't have the component
+     * Get component data from entity. Loads from DB if not cached.
+     * @param ctor Component constructor
+     * @param context Optional DataLoader context and/or transaction
+     * @returns Component data or null
      */
-    public async get<T extends BaseComponent>(ctor: new (...args: any[]) => T): Promise<ComponentDataType<T> | null> {
-        const comp = Array.from(this.components.values()).find(comp => comp instanceof ctor) as ComponentGetter<T> | undefined;
-        if(typeof comp !== "undefined") {
-            return comp.data();
-        } else {
-            // fetch from db
-            const temp = new ctor();
-            const typeId = temp.getTypeID();
-            try {
-                const rows = await db`SELECT id, data FROM components WHERE entity_id = ${this.id} AND type_id = ${typeId} AND deleted_at IS NULL`;
-                if (rows.length > 0) {
-                    const row = rows[0];
-                    const comp = new ctor();
-                    Object.assign(comp, row.data);
-                    comp.id = row.id;
-                    comp.setPersisted(true);
-                    comp.setDirty(false);
-                    this.addComponent(comp);
-                    return comp.data();
-                } else {
-                    return null;
-                }
-            } catch (error) {
-                logger.error(`Failed to fetch component: ${error}`);
-                return null;
-            }
+    public async get<T extends BaseComponent>(ctor: new (...args: any[]) => T, context?: { loaders?: { componentsByEntityType?: any }; trx?: SQL }): Promise<ComponentDataType<T> | null> {
+        const comp = await this._loadComponent(ctor, context);
+        return comp ? (comp as ComponentGetter<T>).data() : null;
+    }
+
+    /**
+     * Check if entity has a component (type guard).
+     * Uses in-memory check only - does not query database.
+     * Useful for runtime checks before accessing component data.
+     *
+     * @example
+     * ```typescript
+     * if (entity.has(Health)) {
+     *   // TypeScript knows entity has Health component
+     *   const health = entity.getCached(Health); // guaranteed to exist
+     * }
+     * ```
+     *
+     * @param ctor Component constructor
+     * @returns true if component exists in memory
+     */
+    public has<T extends BaseComponent>(ctor: new (...args: any[]) => T): boolean {
+        return this.hasInMemory(ctor);
+    }
+
+    /**
+     * Get component data or throw if not found.
+     * Use this when you know the component must exist (e.g., after a query that included it).
+     *
+     * @example
+     * ```typescript
+     * // After query that included Position
+     * const pos = await entity.getOrThrow(Position);
+     * // pos is guaranteed to be ComponentDataType<Position>, not null
+     * ```
+     *
+     * @param ctor Component constructor
+     * @param context Optional DataLoader context and/or transaction
+     * @returns Component data (never null)
+     * @throws Error if component not found
+     */
+    public async getOrThrow<T extends BaseComponent>(
+        ctor: new (...args: any[]) => T,
+        context?: { loaders?: { componentsByEntityType?: any }; trx?: SQL }
+    ): Promise<ComponentDataType<T>> {
+        const data = await this.get(ctor, context);
+        if (data === null) {
+            throw new Error(`Entity ${this.id} is missing required component ${ctor.name}`);
         }
+        return data;
+    }
+
+    /**
+     * Get component data synchronously if already loaded in memory.
+     * Does NOT trigger a database fetch - returns undefined if not cached.
+     *
+     * Use this for performance-critical code paths when you know
+     * the component was already loaded (e.g., via query populate).
+     *
+     * @example
+     * ```typescript
+     * // After query with .populate()
+     * const pos = entity.getCached(Position);
+     * if (pos) {
+     *   console.log(pos.x, pos.y);
+     * }
+     * ```
+     *
+     * @param ctor Component constructor
+     * @returns Component data if in memory, undefined otherwise
+     */
+    public getCached<T extends BaseComponent>(ctor: new (...args: any[]) => T): ComponentDataType<T> | undefined {
+        const comp = this.getInMemory(ctor);
+        return comp ? (comp as ComponentGetter<T>).data() : undefined;
     }
 
     /**
-     * Get a component from the entity.
+     * Get component instance from entity. Loads from DB if not cached.
      * @param ctor Constructor of the component to fetch
-     * @returns Component instance or null if not found
+     * @param context Optional DataLoader context and/or transaction
+     * @returns Component instance or null
      */
-    public async getComponent<T extends BaseComponent>(ctor: new (...args: any[]) => T): Promise<T | null> {
+    public async getInstanceOf<T extends BaseComponent>(ctor: new (...args: any[]) => T, context?: { loaders?: { componentsByEntityType?: any }; trx?: SQL }): Promise<T | null> {
+        return this._loadComponent(ctor, context);
+    }
+
+    private async _loadComponent<T extends BaseComponent>(ctor: new (...args: any[]) => T, context?: { loaders?: { componentsByEntityType?: any }; trx?: SQL }): Promise<T | null> {
         const comp = Array.from(this.components.values()).find(comp => comp instanceof ctor) as T | undefined;
-        if(typeof comp !== "undefined") {
+        if (typeof comp !== "undefined") {
             return comp;
-        } else {
-            // fetch from db
-            const temp = new ctor();
-            const typeId = temp.getTypeID();
-            try {
-                const rows = await db`SELECT id, data FROM components WHERE entity_id = ${this.id} AND type_id = ${typeId} AND deleted_at IS NULL`;
+        }
+
+        // Validate entity ID before database query
+        if (!this.id || this.id.trim() === '') {
+            logger.warn(`Cannot load component ${ctor.name}: entity id is empty`);
+            return null;
+        }
+
+        const temp = new ctor();
+        const typeId = temp.getTypeID();
+        
+        // Use transaction if provided, otherwise use default db
+        const dbConn = context?.trx ?? db;
+        
+        try {
+            let componentData: any = null;
+            let componentId: string | null = null;
+
+            if (context?.loaders?.componentsByEntityType) {
+                const loaderResult = await context.loaders.componentsByEntityType.load({
+                    entityId: this.id,
+                    typeId: typeId
+                });
+                if (loaderResult) {
+                    componentData = loaderResult.data;
+                    componentId = loaderResult.id;
+                }
+            } else {
+                const rows = await dbConn`SELECT id, data FROM components WHERE entity_id = ${this.id} AND type_id = ${typeId} AND deleted_at IS NULL`;
                 if (rows.length > 0) {
-                    const row = rows[0];
-                    const comp = new ctor();
-                    Object.assign(comp, row.data);
-                    comp.id = row.id;
-                    comp.setPersisted(true);
-                    comp.setDirty(false);
-                    this.addComponent(comp);
-                    return comp;
-                } else {
-                    return null;
+                    componentData = rows[0].data;
+                    componentId = rows[0].id;
                 }
-            } catch (error) {
-                logger.error(`Failed to fetch component: ${error}`);
+            }
+
+            if (componentData !== null) {
+                const comp: any = new ctor();
+                if (componentId) {
+                    comp.id = componentId;
+                }
+                const parsedData = typeof componentData === 'string' ? JSON.parse(componentData) : componentData;
+                Object.assign(comp, parsedData);
+                const storage = getMetadataStorage();
+                const props = storage.componentProperties.get(typeId);
+                if (props) {
+                    for (const prop of props) {
+                        if (prop.propertyType === Date && typeof comp[prop.propertyKey] === 'string') {
+                            comp[prop.propertyKey] = new Date(comp[prop.propertyKey]);
+                        }
+                    }
+                }
+                comp.setPersisted(true);
+                comp.setDirty(false);
+                this.addComponent(comp);
+                return comp as T;
+            } else {
                 return null;
             }
+        } catch (error) {
+            logger.error(`Failed to fetch component ${ctor.name}: ${error}`);
+            return null;
         }
     }
 
     @timed("Entity.save")
-    public save() {
+    public save(trx?: SQL, context?: { loaders?: { componentsByEntityType?: any }; trx?: SQL }) {
         return new Promise<boolean>((resolve, reject) => {
             // Add timeout to prevent hanging
             const timeout = setTimeout(() => {
@@ -204,41 +391,177 @@ export class Entity implements IEntity {
                 reject(new Error(`Entity save timeout for entity ${this.id}`));
             }, 30000); // 30 second timeout
 
-            this.doSave()
-                .then(result => {
+            // Capture dirty components BEFORE doSave clears the dirty flags
+            const changedComponentTypeIds = this.getDirtyComponents();
+            const removedComponentTypeIds = Array.from(this.removedComponents);
+
+            if (trx) {
+                // Use provided transaction
+                this.doSave(trx)
+                .then(async result => {
+                    clearTimeout(timeout);
+                    await this.handleCacheAfterSave(changedComponentTypeIds, removedComponentTypeIds, context);
+                    resolve(result);
+                })
+                .catch(error => {
+                    clearTimeout(timeout);
+                    reject(error);
+                });
+            } else {
+                // Create new transaction
+                db.transaction(async (newTrx) => {
+                    return await this.doSave(newTrx);
+                })
+                .then(async result => {
                     clearTimeout(timeout);
+                    await this.handleCacheAfterSave(changedComponentTypeIds, removedComponentTypeIds, context);
                     resolve(result);
                 })
                 .catch(error => {
                     clearTimeout(timeout);
                     reject(error);
                 });
+            }
         });
     }
 
-    
+    /**
+     * Handle cache operations after successful save
+     * @param changedComponentTypeIds - Component type IDs that were dirty before save (captured before doSave clears flags)
+     * @param removedComponentTypeIds - Component type IDs that were removed (captured before doSave clears the set)
+     */
+    private async handleCacheAfterSave(changedComponentTypeIds: string[], removedComponentTypeIds: string[], context?: { loaders?: { componentsByEntityType?: any }; trx?: SQL }): Promise<void> {
+        try {
+            // Import CacheManager dynamically to avoid circular dependency
+            const { CacheManager } = await import('./cache/CacheManager');
+            const cacheManager = CacheManager.getInstance();
+            const config = cacheManager.getConfig();
+
+            if (config.enabled && config.entity?.enabled) {
+                // Always update entity existence cache
+                if (config.strategy === 'write-through') {
+                    await cacheManager.setEntityWriteThrough(this, config.entity.ttl);
+                } else {
+                    await cacheManager.invalidateEntity(this.id);
+                }
+            }
+
+            // Handle component cache invalidation with granular approach
+            if (config.enabled && config.component?.enabled) {
+                // Use the pre-captured lists instead of re-querying (dirty flags are already cleared by doSave)
+
+                // Invalidate cache for changed components
+                for (const typeId of changedComponentTypeIds) {
+                    if (config.strategy === 'write-through') {
+                        // Update component cache with new data
+                        const component = this.components.get(typeId);
+                        if (component) {
+                            await cacheManager.setComponentWriteThrough(this.id, [component], typeId, config.component.ttl);
+                        }
+                    } else {
+                        // Invalidate component cache
+                        await cacheManager.invalidateComponent(this.id, typeId);
+                    }
+                    
+                    // Invalidate DataLoader cache for changed component
+                    if (context?.loaders?.componentsByEntityType) {
+                        context.loaders.componentsByEntityType.clear({
+                            entityId: this.id,
+                            typeId: typeId
+                        });
+                    }
+                }
+
+                // Invalidate cache for removed components
+                for (const typeId of removedComponentTypeIds) {
+                    await cacheManager.invalidateComponent(this.id, typeId);
+                    
+                    // Invalidate DataLoader cache for removed component
+                    if (context?.loaders?.componentsByEntityType) {
+                        context.loaders.componentsByEntityType.clear({
+                            entityId: this.id,
+                            typeId: typeId
+                        });
+                    }
+                }
+            }
+        } catch (error) {
+            logger.warn({ scope: 'cache', component: 'Entity', msg: 'Cache operation failed after save', error });
+        }
+    }
+
+    public doSave(trx: SQL) {
+        return new Promise<boolean>(async (resolve, reject) => {
+            // Validate entity ID to prevent PostgreSQL UUID parsing errors
+            if (!this.id || this.id.trim() === '') {
+                logger.error(`Cannot save entity: id is empty or invalid`);
+                return reject(new Error(`Cannot save entity: id is empty or invalid`));
+            }
 
-    public doSave() {
-        return new Promise<boolean>(async resolve => {
             if(!this._dirty) {
-                logger.trace("Entity is not dirty, no need to save.");
-                return resolve(true); 
+                let dirtyComponents: string[] = [];
+                try {
+                    dirtyComponents = this.getDirtyComponents();
+                } catch {
+                    // best-effort diagnostics only
+                }
+
+                const removedTypeIds = Array.from(this.removedComponents);
+                const entityType = (this as any)?.constructor?.name ?? "Entity";
+                const dirtyComponentPreview = dirtyComponents.slice(0, 10).map((component) => {
+                    const anyComponent = component as any;
+                    return {
+                        type: anyComponent?.constructor?.name ?? "Component",
+                        typeId: typeof anyComponent?.getTypeID === "function" ? anyComponent.getTypeID() : undefined,
+                        id: anyComponent?.id,
+                        persisted: anyComponent?._persisted,
+                        dirty: anyComponent?._dirty,
+                    };
+                });
+
+                logger.trace(
+                    {
+                        component: "Entity",
+                        entity: {
+                            type: entityType,
+                            id: this.id,
+                            persisted: this._persisted,
+                            dirty: this._dirty,
+                        },
+                        components: {
+                            total: this.components.size,
+                            dirtyCount: dirtyComponents.length,
+                            dirtyPreview: dirtyComponentPreview,
+                        },
+                        removedComponents: {
+                            count: removedTypeIds.length,
+                            typeIdsPreview: removedTypeIds.slice(0, 10),
+                        },
+                    },
+                    "[Entity.doSave] Skipping save because entity is not dirty"
+                );
+                return resolve(true);
             }
 
             const wasNew = !this._persisted;
             const changedComponents = this.getDirtyComponents();
 
-            await db.transaction(async (trx) => {
+            const executeSave = async (saveTrx: SQL) => {
                 if(!this._persisted) {
-                    await trx`INSERT INTO entities (id) VALUES (${this.id}) ON CONFLICT DO NOTHING`;
+                    await saveTrx`INSERT INTO entities (id) VALUES (${this.id}) ON CONFLICT DO NOTHING`;
                     this._persisted = true;
                 }
-                
+
                 // Delete removed components from database
                 if (this.removedComponents.size > 0) {
                     const typeIds = Array.from(this.removedComponents);
-                    await trx`DELETE FROM components WHERE entity_id = ${this.id} AND type_id IN ${sql(typeIds)}`;
-                    await trx`DELETE FROM entity_components WHERE entity_id = ${this.id} AND type_id IN ${sql(typeIds)}`;
+                    await saveTrx`DELETE FROM components WHERE entity_id = ${this.id} AND type_id IN ${sql(typeIds)}`;
+                    await saveTrx`DELETE FROM entity_components WHERE entity_id = ${this.id} AND type_id IN ${sql(typeIds)}`;
+                    // Move to savedRemovedComponents so resolvers can still detect removed components
+                    // This is needed because DataLoader may have stale cached data for this request
+                    for (const typeId of typeIds) {
+                        this.savedRemovedComponents.add(typeId);
+                    }
                     this.removedComponents.clear();
                 }
                 
@@ -246,12 +569,83 @@ export class Entity implements IEntity {
                     logger.trace(`No components to save for entity ${this.id}`);
                     return;
                 }
-                const waitable = [];
+                
+                // Batch inserts and updates for better performance
+                const componentsToInsert = [];
+                const entityComponentsToInsert = [];
+                const componentsToUpdate = [];
+                
                 for(const comp of this.components.values()) {
-                    waitable.push(comp.save(trx, this.id));
+                    const compName = comp.constructor.name;
+                    if (!ComponentRegistry.isComponentReady(compName)) {
+                        await ComponentRegistry.getReadyPromise(compName);
+                    }
+                    
+                    if(!(comp as any)._persisted) {
+                        if(comp.id === "") {
+                            comp.id = uuidv7();
+                        }
+                        componentsToInsert.push({
+                            id: comp.id,
+                            entity_id: this.id,
+                            name: compName,
+                            type_id: comp.getTypeID(),
+                            data: comp.serializableData()
+                        });
+                        entityComponentsToInsert.push({
+                            entity_id: this.id,
+                            type_id: comp.getTypeID(),
+                            component_id: comp.id
+                        });
+                        (comp as any).setPersisted(true);
+                        (comp as any).setDirty(false);
+                    } else if((comp as any)._dirty) {
+                        componentsToUpdate.push({
+                            id: comp.id,
+                            data: comp.serializableData()
+                        });
+                        (comp as any).setDirty(false);
+                    }
+                }
+                
+                // Perform batch inserts
+                if(componentsToInsert.length > 0) {
+                    await saveTrx`INSERT INTO components ${sql(componentsToInsert, 'id', 'entity_id', 'name', 'type_id', 'data')}`;
+                    await saveTrx`INSERT INTO entity_components ${sql(entityComponentsToInsert, 'entity_id', 'type_id', 'component_id')} ON CONFLICT DO NOTHING`;
                 }
-                await Promise.all(waitable);
-            });
+
+                // Insert entity_components for existing components if entity is new
+                if(!this._persisted) {
+                    const existingEntityComponents = [];
+                    for(const comp of this.components.values()) {
+                        if((comp as any)._persisted) {
+                            existingEntityComponents.push({
+                                entity_id: this.id,
+                                type_id: comp.getTypeID(),
+                                component_id: comp.id
+                            });
+                        }
+                    }
+                    if(existingEntityComponents.length > 0) {
+                        await saveTrx`INSERT INTO entity_components ${sql(existingEntityComponents, 'entity_id', 'type_id', 'component_id')} ON CONFLICT DO NOTHING`;
+                    }
+                }
+
+                // Perform batch updates
+                if(componentsToUpdate.length > 0) {
+                    for(const comp of componentsToUpdate) {
+                        // Validate component ID to prevent PostgreSQL UUID parsing errors
+                        if (!comp.id || comp.id.trim() === '') {
+                            logger.error(`Cannot update component: id is empty or invalid. Component data: ${JSON.stringify(comp.data).substring(0, 200)}`);
+                            throw new Error(`Cannot update component: component id is empty or invalid`);
+                        }
+                        logger.trace({ componentId: comp.id, data: comp.data }, `[Entity.doSave] Updating component`);
+                        await saveTrx`UPDATE components SET data = ${comp.data} WHERE id = ${comp.id}`;
+                    }
+                }
+            };
+
+            await executeSave(trx);
 
             this._dirty = false;
 
@@ -303,6 +697,22 @@ export class Entity implements IEntity {
                     // Don't fail the delete operation if hooks fail
                 }
 
+                // Invalidate cache after successful deletion
+                try {
+                    const { CacheManager } = await import('./cache/CacheManager');
+                    const cacheManager = CacheManager.getInstance();
+                    const config = cacheManager.getConfig();
+
+                    if (config.enabled && config.entity?.enabled) {
+                        await cacheManager.invalidateEntity(this.id);
+                    }
+                    if (config.enabled && config.component?.enabled) {
+                        await cacheManager.invalidateAllEntityComponents(this.id);
+                    }
+                } catch (error) {
+                    logger.warn({ scope: 'cache', component: 'Entity', msg: 'Cache invalidation failed after delete', error });
+                }
+
                 resolve(true);
             } catch (error) {
                 logger.error(`Failed to delete entity: ${error}`);
@@ -325,7 +735,9 @@ export class Entity implements IEntity {
     private getDirtyComponents(): string[] {
         const dirtyComponents: string[] = [];
         for (const component of this.components.values()) {
-            if ((component as any)._dirty) {
+            // Include both dirty (modified) components AND new (not persisted) components
+            // New components need to be cached after save, not just modified ones
+            if ((component as any)._dirty || !(component as any)._persisted) {
                 dirtyComponents.push(component.getTypeID());
             }
         }
@@ -336,16 +748,23 @@ export class Entity implements IEntity {
     @timed("Entity.LoadMultiple")
     public static async LoadMultiple(ids: string[]): Promise<Entity[]> {
         if (ids.length === 0) return [];
+        
+        // Filter out empty/invalid IDs to prevent PostgreSQL UUID parsing errors
+        const validIds = ids.filter(id => id && id.trim() !== '');
+        if (validIds.length === 0) return [];
+        if (validIds.length !== ids.length) {
+            logger.warn(`LoadMultiple: Filtered out ${ids.length - validIds.length} invalid entity IDs`);
+        }
 
         const components = await db`
             SELECT c.id, c.entity_id, c.type_id, c.data
             FROM components c
-            WHERE c.entity_id IN ${sql(ids)} AND c.deleted_at IS NULL
+            WHERE c.entity_id IN ${sql(validIds)} AND c.deleted_at IS NULL
         `;
 
         const entitiesMap = new Map<string, Entity>();
 
-        for (const id of ids) {
+        for (const id of validIds) {
             const entity = new Entity();
             entity.id = id;
             entity.setPersisted(true);
@@ -358,7 +777,8 @@ export class Entity implements IEntity {
             const ctor = ComponentRegistry.getConstructor(type_id);
             if (ctor) {
                 const comp = new ctor();
-                Object.assign(comp, data);
+                const componentData = typeof data === 'string' ? JSON.parse(data) : data;
+                Object.assign(comp, componentData);
                 comp.id = id;
                 comp.setPersisted(true);
                 comp.setDirty(false);
@@ -369,10 +789,14 @@ export class Entity implements IEntity {
         return Array.from(entitiesMap.values());
     }
 
-    public static async LoadComponents(entities: Entity[], componentIds: string[]): Promise<void> {
+    public static async LoadComponents(entities: Entity[], componentIds: string[], skipCache: boolean = false): Promise<void> {
         if (entities.length === 0 || componentIds.length === 0) return;
 
-        const entityIds = entities.map(e => e.id);
+        // Filter out entities with empty/invalid IDs to prevent PostgreSQL UUID parsing errors
+        const validEntities = entities.filter(e => e.id && e.id.trim() !== '');
+        if (validEntities.length === 0) return;
+        
+        const entityIds = validEntities.map(e => e.id);
 
         const components = await db`
             SELECT c.id, c.entity_id, c.type_id, c.data
@@ -380,14 +804,18 @@ export class Entity implements IEntity {
             WHERE c.entity_id IN ${sql(entityIds)} AND c.type_id IN ${sql(componentIds)} AND c.deleted_at IS NULL
         `;
 
+        // Use Map for O(1) lookups instead of O(n) find() - fixes O(n²) performance issue
+        const entityMap = new Map<string, Entity>(validEntities.map(e => [e.id, e]));
+
         for (const row of components) {
             const { id, entity_id, type_id, data } = row;
-            const entity = entities.find(e => e.id === entity_id);
+            const entity = entityMap.get(entity_id);  // O(1) instead of O(n)
             if (entity) {
                 const ctor = ComponentRegistry.getConstructor(type_id);
                 if (ctor) {
                     const comp = new ctor();
-                    Object.assign(comp, data);
+                    const componentData = typeof data === 'string' ? JSON.parse(data) : data;
+                    Object.assign(comp, componentData);
                     comp.id = id;
                     comp.setPersisted(true);
                     comp.setDirty(false);
@@ -402,14 +830,115 @@ export class Entity implements IEntity {
      * @param id Entity ID
      * @returns Entity | null
      */
-    public static async FindById(id: string): Promise<Entity | null> {
-        const { default: Query } = await import("./Query");
-        const entities = await new Query().findById(id).populate().exec()
+    public static async FindById(id: string, trx?: SQL): Promise<Entity | null> {
+        // Validate ID to prevent PostgreSQL UUID parsing errors
+        if (!id || typeof id !== 'string' || id.trim() === '') {
+            logger.warn(`FindById called with invalid id: "${id}"`);
+            return null;
+        }
+        const { Query } = await import("../query/Query");
+        const entities = await new Query(trx).findById(id).populate().exec()
         if(entities.length === 1) {
             return entities[0]!;
         }
         return null;
     }
+
+    public static Clone(entity: Entity): Entity {
+        const clone = new Entity();
+        clone._dirty = true;
+        clone._persisted = false;
+        for (const comp of entity.components.values()) {
+            const newComp = new (comp.constructor as any)();
+            Object.assign(newComp, comp.data());
+            newComp.id = uuidv7();
+            newComp.setDirty(true);
+            newComp.setPersisted(false);
+            clone.addComponent(newComp);
+        }
+        return clone;
+    }
+
+    public static MakeRef(entity: Entity): Entity {
+        const ref = new Entity();
+        ref._dirty = true;
+        ref._persisted = false;
+        for (const comp of entity.components.values()) {
+            const refComp = comp;
+            refComp.setDirty(false);
+            refComp.setPersisted(true);
+            ref.addComponent(refComp);
+        }
+        return ref;
+    }
+
+    /**
+     * Serialize the entity with only the currently loaded components
+     * @returns Object containing id and components data
+     */
+    public serialize(): { id: string; components: Record<string, any> } {
+        const components: Record<string, any> = {};
+        for (const comp of this.components.values()) {
+            components[comp.constructor.name] = comp.serializableData();
+        }
+        return {
+            id: this.id,
+            components
+        };
+    }
+
+    /**
+     * Deserialize/reconstitute an Entity from cached/serialized data.
+     * Handles both serialized format { id, components } and raw Entity-like objects.
+     * @param data Serialized entity data or Entity-like plain object
+     * @returns Reconstituted Entity instance
+     */
+    public static deserialize(data: any): Entity {
+        if (data instanceof Entity) {
+            return data;
+        }
+
+        const entity = new Entity(data.id);
+        entity._persisted = true;
+        entity._dirty = false;
+
+        // Handle serialized format: { id, components: { ComponentName: {...data} } }
+        if (data.components && typeof data.components === 'object') {
+            const storage = getMetadataStorage();
+            
+            for (const [componentName, componentData] of Object.entries(data.components)) {
+                // Find the component constructor by name
+                const ComponentCtor = ComponentRegistry.getConstructorByName(componentName);
+                if (!ComponentCtor) {
+                    logger.warn(`Cannot deserialize component: constructor not found for ${componentName}`);
+                    continue;
+                }
+
+                const comp = new ComponentCtor();
+                const parsedData = typeof componentData === 'string' ? JSON.parse(componentData) : componentData;
+                Object.assign(comp, parsedData);
+
+                // Restore Date objects
+                const typeId = comp.getTypeID();
+                const props = storage.componentProperties.get(typeId);
+                if (props) {
+                    for (const prop of props) {
+                        if (prop.propertyType === Date && typeof (comp as any)[prop.propertyKey] === 'string') {
+                            (comp as any)[prop.propertyKey] = new Date((comp as any)[prop.propertyKey]);
+                        }
+                    }
+                }
+
+                comp.setPersisted(true);
+                comp.setDirty(false);
+                entity.addComponent(comp);
+            }
+        }
+
+        return entity;
+    }
+
+
 }
 
 export default Entity;