@cheetah.js/orm 0.1.144 → 0.1.146

package/README.md

@@ -9,6 +9,8 @@ Cheetah.js ORM is a simple and powerful ORM for Cheetah.js and Bun.
   - [Value Objects](#value-objects)
   - [Hooks](#hooks)
 - [Usage](#usage)
+- [Caching](#caching)
+- [Identity Map](#identity-map)
 - [Migrations](#migrations)
 
 ### [Installation](#install)
@@ -124,7 +126,7 @@ export class User {
 }
 ```
 
-For define a index for a multiple properties, add the @Index decorator. You can use it on a property or on the class. It accepts either an array of property names (legacy) or an object with a properties field (recommended):
+For define a index for a multiple properties, add the @Index decorator. You can use it on a property or on the class. It accepts either an array of property names (legacy) or an object with a properties field (recommended):
 
 ```javascript
 @Entity()
@@ -156,60 +158,60 @@ export class User {
   email: string;
 }
 
-// Backward compatible usage (array):
-// @Index(['name', 'email'])
-```
-
-Partial indexes (Postgres only) can be declared with `where`. You can provide a raw SQL string or a typed callback that receives the column map (with autocomplete based on your entity):
-
-```javascript
-@Entity()
-@Index<{ User }>({
-  properties: ['email'],
-  where: (columns) => `${columns.isActive} = true`,
-})
-export class User {
-  @PrimaryKey()
-  id: number;
-
-  @Property()
-  email: string;
-
-  @Property()
-  isActive: boolean;
-}
-```
-
-You can also use the ORM filter syntax in `where` (with `$in`, `$or`, `$nor`, etc.):
-
-```javascript
-@Entity()
-@Index<{ User }>({
-  properties: ['email'],
-  where: {
-    isActive: true,
-    status: { $in: ['active', 'pending'] },
-  },
-})
-export class User {
-  @PrimaryKey()
-  id: number;
-
-  @Property()
-  email: string;
-
-  @Property()
-  isActive: boolean;
-
-  @Property()
-  status: string;
-}
-```
-
-Note: MySQL does not support partial indexes; using `where` with the MySQL driver will throw.
-
-#### Property options
-| Option | Type | Description                                                                                |
+// Backward compatible usage (array):
+// @Index(['name', 'email'])
+```
+
+Partial indexes (Postgres only) can be declared with `where`. You can provide a raw SQL string or a typed callback that receives the column map (with autocomplete based on your entity):
+
+```javascript
+@Entity()
+@Index<{ User }>({
+  properties: ['email'],
+  where: (columns) => `${columns.isActive} = true`,
+})
+export class User {
+  @PrimaryKey()
+  id: number;
+
+  @Property()
+  email: string;
+
+  @Property()
+  isActive: boolean;
+}
+```
+
+You can also use the ORM filter syntax in `where` (with `$in`, `$or`, `$nor`, etc.):
+
+```javascript
+@Entity()
+@Index<{ User }>({
+  properties: ['email'],
+  where: {
+    isActive: true,
+    status: { $in: ['active', 'pending'] },
+  },
+})
+export class User {
+  @PrimaryKey()
+  id: number;
+
+  @Property()
+  email: string;
+
+  @Property()
+  isActive: boolean;
+
+  @Property()
+  status: string;
+}
+```
+
+Note: MySQL does not support partial indexes; using `where` with the MySQL driver will throw.
+
+#### Property options
+| Option | Type | Description                                                                                |
 | ------ | ---- |--------------------------------------------------------------------------------------------|
 | nullable | boolean | Defines if the property is nullable.                                                       |
 | unique | boolean | Defines if the property is unique.                                                         |
@@ -333,6 +335,189 @@ await repo.find({ where: { name: 'John' }, cache: new Date(Date.now() + 60_000)
 // Infinite/driver-default cache
 await repo.find({ where: { name: 'John' }, cache: true });
 ```
+
+### Identity Map
+
+The Identity Map is an in-memory cache that ensures each entity is loaded only once per request context. This pattern reduces database queries and guarantees that all references to the same entity point to the same object instance.
+
+#### Key Benefits
+
+- **Reduced Database Queries**: When querying for an entity that was already loaded in the same context, the cached instance is returned instead of executing another query
+- **Consistent Entity References**: All parts of your code working with the same entity will share the same instance
+- **Memory Efficient**: Uses WeakRef internally, allowing garbage collection of unreferenced entities
+- **Per-Request Isolation**: Each request has its own identity map, preventing data leakage between requests
+
+#### Automatic Activation (Recommended)
+
+**The identity map is automatically enabled for all routes when you use `CheetahOrm`!** No additional configuration needed:
+
+```typescript
+import { Cheetah } from '@cheetah.js/core';
+import { CheetahOrm } from '@cheetah.js/orm';
+
+new Cheetah()
+  .use(CheetahOrm)  // ← Identity map automatically active for all routes
+  .listen();
+```
+
+Now all your controllers automatically benefit from the identity map:
+
+```typescript
+import { Controller, Get } from '@cheetah.js/core';
+
+@Controller('/users')
+export class UserController {
+  @Get('/:id/posts')
+  async getUserPosts(id: number) {
+    // Identity map is AUTOMATICALLY active - no decorator needed!
+    const user = await User.findOne({ id });
+    const posts = await Post.findAll({ userId: id }, { load: ['user'] });
+    
+    // posts[0].user === user (same instance, no extra query)
+    return { user, posts };
+  }
+}
+```
+
+**That's it!** The identity map works transparently across your entire application.
+
+#### Manual Usage (Advanced)
+
+For custom scenarios, use `identityMapContext.run()` directly:
+
+```typescript
+import { identityMapContext } from '@cheetah.js/orm';
+
+async function processUserData(userId: number) {
+  await identityMapContext.run(async () => {
+    // All queries within this context share the same identity map
+    const user = await User.findOne({ id: userId });
+    const posts = await Post.findAll({ userId }, { load: ['user'] });
+    
+    // posts[0].user === user (same instance, no extra query)
+    return { user, posts };
+  });
+}
+```
+
+#### How It Works
+
+```typescript
+await identityMapContext.run(async () => {
+  // First query - fetches from database and caches
+  const user1 = await User.findOne({ id: 1 });
+  
+  // Second query - returns cached instance (no database query)
+  const user2 = await User.findOne({ id: 1 });
+  
+  console.log(user1 === user2); // true - same object instance
+  
+  // Modifications are reflected everywhere
+  user1.name = 'Updated Name';
+  console.log(user2.name); // 'Updated Name'
+});
+```
+
+#### Relationship Loading
+
+The identity map automatically caches entities loaded through relationships:
+
+```typescript
+await identityMapContext.run(async () => {
+  // Load user first
+  const user = await User.findOne({ id: 1 });
+  
+  // Load posts with user relationship
+  const posts = await Post.findAll(
+    { userId: 1 },
+    { load: ['user'] }
+  );
+  
+  // The user loaded through posts is the same cached instance
+  console.log(posts[0].user === user); // true
+});
+```
+
+#### Context Isolation
+
+Each `identityMapContext.run()` creates an isolated scope:
+
+```typescript
+let user1, user2;
+
+// First context
+await identityMapContext.run(async () => {
+  user1 = await User.findOne({ id: 1 });
+});
+
+// Second context - completely separate identity map
+await identityMapContext.run(async () => {
+  user2 = await User.findOne({ id: 1 });
+});
+
+// Different contexts = different instances
+console.log(user1 === user2); // false
+```
+
+#### Without Identity Map Context
+
+When not using `identityMapContext.run()`, the ORM behaves normally without caching:
+
+```typescript
+// Without context wrapper
+const user1 = await User.findOne({ id: 1 });
+const user2 = await User.findOne({ id: 1 });
+
+console.log(user1 === user2); // false - different instances
+```
+
+#### Advanced: Disabling or Customizing
+
+If you need to disable the identity map for specific routes, you can use manual context management:
+
+```typescript
+import { Controller, Get, Middleware } from '@cheetah.js/core';
+import { identityMapContext, IdentityMapMiddleware } from '@cheetah.js/orm';
+
+@Controller('/users')
+export class UserController {
+  @Get('/:id')
+  async getUser(id: number) {
+    // Identity map active (global middleware)
+    return User.findOne({ id });
+  }
+
+  @Get('/legacy')
+  async getLegacyUsers() {
+    // To bypass identity map, just query normally
+    // The global middleware is still active, but you can
+    // control when to use it via manual context management
+    return User.findAll({});
+  }
+}
+```
+
+For other frameworks (Express, Fastify, etc.), use the manual approach:
+
+```typescript
+// Express example
+import { identityMapContext } from '@cheetah.js/orm';
+
+app.use(async (req, res, next) => {
+  await identityMapContext.run(async () => {
+    await next();
+  });
+});
+```
+
+#### Performance Considerations
+
+- The identity map uses O(1) lookup time via Map-based storage
+- WeakRef ensures entities can be garbage collected when no longer referenced
+- FinalizationRegistry automatically cleans up expired cache entries
+- Per-request scope prevents memory buildup across requests
+- No configuration needed - works transparently with existing queries
+
 Is Required to implement the validate method, that returns a boolean value.
 To use the Value Object in the Entity, just add the ValueObject type to the property:
 

package/dist/entry.js

@@ -5,4 +5,9 @@ const core_1 = require("@cheetah.js/core");
 const orm_1 = require("./orm");
 const orm_service_1 = require("./orm.service");
 const entities_1 = require("./domain/entities");
-exports.CheetahOrm = new core_1.Cheetah({ exports: [orm_1.Orm, orm_service_1.OrmService, entities_1.EntityStorage] });
+const identity_map_middleware_1 = require("./middleware/identity-map.middleware");
+exports.CheetahOrm = new core_1.Cheetah({
+    exports: [orm_1.Orm, orm_service_1.OrmService, entities_1.EntityStorage],
+    providers: [identity_map_middleware_1.IdentityMapMiddleware],
+    globalMiddlewares: [identity_map_middleware_1.IdentityMapMiddleware],
+});

package/dist/identity-map/entity-key-generator.d.ts

@@ -0,0 +1,10 @@
+export declare class EntityKeyGenerator {
+    private entityStorage;
+    constructor();
+    generate(entityClass: Function, pk: any): string;
+    generateForEntity(entity: any): string;
+    extractPrimaryKey(entity: any): any;
+    private getPrimaryKeyName;
+    private serializePrimaryKey;
+    private getClassName;
+}

package/dist/identity-map/entity-key-generator.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntityKeyGenerator = void 0;
+const entities_1 = require("../domain/entities");
+class EntityKeyGenerator {
+    constructor() {
+        this.entityStorage = entities_1.EntityStorage.getInstance();
+    }
+    generate(entityClass, pk) {
+        const className = this.getClassName(entityClass);
+        const keyValue = this.serializePrimaryKey(pk);
+        return `${className}:${keyValue}`;
+    }
+    generateForEntity(entity) {
+        const pk = this.extractPrimaryKey(entity);
+        return this.generate(entity.constructor, pk);
+    }
+    extractPrimaryKey(entity) {
+        const pkName = this.getPrimaryKeyName(entity.constructor);
+        return entity[pkName];
+    }
+    getPrimaryKeyName(entityClass) {
+        const options = this.entityStorage.get(entityClass);
+        if (!options) {
+            return 'id';
+        }
+        for (const prop in options.properties) {
+            const property = options.properties[prop];
+            if (property.options.isPrimary) {
+                return prop;
+            }
+        }
+        return 'id';
+    }
+    serializePrimaryKey(pk) {
+        if (Array.isArray(pk)) {
+            return pk.join(':');
+        }
+        return String(pk);
+    }
+    getClassName(entityClass) {
+        return entityClass.name;
+    }
+}
+exports.EntityKeyGenerator = EntityKeyGenerator;

package/dist/identity-map/entity-registry.d.ts

@@ -0,0 +1,11 @@
+export declare class EntityRegistry {
+    private store;
+    private finalizationRegistry;
+    constructor();
+    private setupFinalizationRegistry;
+    get<T>(key: string): T | undefined;
+    set<T extends object>(key: string, entity: T): void;
+    has(key: string): boolean;
+    remove(key: string): void;
+    clear(): void;
+}

package/dist/identity-map/entity-registry.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntityRegistry = void 0;
+class EntityRegistry {
+    constructor() {
+        this.store = new Map();
+        this.setupFinalizationRegistry();
+    }
+    setupFinalizationRegistry() {
+        this.finalizationRegistry = new FinalizationRegistry((key) => {
+            this.store.delete(key);
+        });
+    }
+    get(key) {
+        const weakRef = this.store.get(key);
+        if (!weakRef) {
+            return undefined;
+        }
+        const entity = weakRef.deref();
+        if (!entity) {
+            this.store.delete(key);
+            return undefined;
+        }
+        return entity;
+    }
+    set(key, entity) {
+        const weakRef = new WeakRef(entity);
+        this.store.set(key, weakRef);
+        this.finalizationRegistry.register(entity, key, entity);
+    }
+    has(key) {
+        return this.get(key) !== undefined;
+    }
+    remove(key) {
+        this.store.delete(key);
+    }
+    clear() {
+        this.store.clear();
+    }
+}
+exports.EntityRegistry = EntityRegistry;

package/dist/identity-map/identity-map-context.d.ts

@@ -0,0 +1,9 @@
+import { IdentityMap } from './identity-map';
+export declare class IdentityMapContext {
+    private storage;
+    constructor();
+    run<T>(callback: () => Promise<T>): Promise<T>;
+    getIdentityMap(): IdentityMap | undefined;
+    hasContext(): boolean;
+}
+export declare const identityMapContext: IdentityMapContext;

package/dist/identity-map/identity-map-context.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.identityMapContext = exports.IdentityMapContext = void 0;
+const async_hooks_1 = require("async_hooks");
+const identity_map_1 = require("./identity-map");
+class IdentityMapContext {
+    constructor() {
+        this.storage = new async_hooks_1.AsyncLocalStorage();
+    }
+    run(callback) {
+        const identityMap = new identity_map_1.IdentityMap();
+        return this.storage.run(identityMap, callback);
+    }
+    getIdentityMap() {
+        return this.storage.getStore();
+    }
+    hasContext() {
+        return this.storage.getStore() !== undefined;
+    }
+}
+exports.IdentityMapContext = IdentityMapContext;
+exports.identityMapContext = new IdentityMapContext();

package/dist/identity-map/identity-map-integration.d.ts

@@ -0,0 +1,5 @@
+export declare class IdentityMapIntegration {
+    static getOrCreateInstance<T>(model: new () => T, primaryKey: any, factory: () => T): T;
+    static registerEntity<T extends object>(entity: T): void;
+    static getEntity<T>(entityClass: new () => T, primaryKey: any): T | undefined;
+}

package/dist/identity-map/identity-map-integration.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdentityMapIntegration = void 0;
+const identity_map_context_1 = require("./identity-map-context");
+class IdentityMapIntegration {
+    static getOrCreateInstance(model, primaryKey, factory) {
+        const identityMap = identity_map_context_1.identityMapContext.getIdentityMap();
+        if (!identityMap) {
+            return factory();
+        }
+        if (primaryKey === undefined || primaryKey === null) {
+            return factory();
+        }
+        const cached = identityMap.get(model, primaryKey);
+        if (cached) {
+            return cached;
+        }
+        const instance = factory();
+        return instance;
+    }
+    static registerEntity(entity) {
+        const identityMap = identity_map_context_1.identityMapContext.getIdentityMap();
+        if (!identityMap) {
+            return;
+        }
+        identityMap.set(entity);
+    }
+    static getEntity(entityClass, primaryKey) {
+        const identityMap = identity_map_context_1.identityMapContext.getIdentityMap();
+        if (!identityMap) {
+            return undefined;
+        }
+        return identityMap.get(entityClass, primaryKey);
+    }
+}
+exports.IdentityMapIntegration = IdentityMapIntegration;

package/dist/identity-map/identity-map.d.ts

@@ -0,0 +1,10 @@
+export declare class IdentityMap {
+    private registry;
+    private keyGenerator;
+    constructor();
+    get<T>(entityClass: Function, pk: any): T | undefined;
+    set<T extends object>(entity: T): void;
+    has(entityClass: Function, pk: any): boolean;
+    remove(entityClass: Function, pk: any): void;
+    clear(): void;
+}

package/dist/identity-map/identity-map.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdentityMap = void 0;
+const entity_key_generator_1 = require("./entity-key-generator");
+const entity_registry_1 = require("./entity-registry");
+class IdentityMap {
+    constructor() {
+        this.registry = new entity_registry_1.EntityRegistry();
+        this.keyGenerator = new entity_key_generator_1.EntityKeyGenerator();
+    }
+    get(entityClass, pk) {
+        const key = this.keyGenerator.generate(entityClass, pk);
+        return this.registry.get(key);
+    }
+    set(entity) {
+        const key = this.keyGenerator.generateForEntity(entity);
+        this.registry.set(key, entity);
+    }
+    has(entityClass, pk) {
+        const key = this.keyGenerator.generate(entityClass, pk);
+        return this.registry.has(key);
+    }
+    remove(entityClass, pk) {
+        const key = this.keyGenerator.generate(entityClass, pk);
+        this.registry.remove(key);
+    }
+    clear() {
+        this.registry.clear();
+    }
+}
+exports.IdentityMap = IdentityMap;

package/dist/identity-map/index.d.ts

@@ -0,0 +1,5 @@
+export { IdentityMap } from './identity-map';
+export { EntityKeyGenerator } from './entity-key-generator';
+export { EntityRegistry } from './entity-registry';
+export { IdentityMapContext, identityMapContext } from './identity-map-context';
+export { IdentityMapIntegration } from './identity-map-integration';

package/dist/identity-map/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdentityMapIntegration = exports.identityMapContext = exports.IdentityMapContext = exports.EntityRegistry = exports.EntityKeyGenerator = exports.IdentityMap = void 0;
+var identity_map_1 = require("./identity-map");
+Object.defineProperty(exports, "IdentityMap", { enumerable: true, get: function () { return identity_map_1.IdentityMap; } });
+var entity_key_generator_1 = require("./entity-key-generator");
+Object.defineProperty(exports, "EntityKeyGenerator", { enumerable: true, get: function () { return entity_key_generator_1.EntityKeyGenerator; } });
+var entity_registry_1 = require("./entity-registry");
+Object.defineProperty(exports, "EntityRegistry", { enumerable: true, get: function () { return entity_registry_1.EntityRegistry; } });
+var identity_map_context_1 = require("./identity-map-context");
+Object.defineProperty(exports, "IdentityMapContext", { enumerable: true, get: function () { return identity_map_context_1.IdentityMapContext; } });
+Object.defineProperty(exports, "identityMapContext", { enumerable: true, get: function () { return identity_map_context_1.identityMapContext; } });
+var identity_map_integration_1 = require("./identity-map-integration");
+Object.defineProperty(exports, "IdentityMapIntegration", { enumerable: true, get: function () { return identity_map_integration_1.IdentityMapIntegration; } });

package/dist/index.d.ts

@@ -23,3 +23,5 @@ export * from './common/email.vo';
 export * from './common/uuid';
 export * from './repository/Repository';
 export { transactionContext } from './transaction/transaction-context';
+export { IdentityMapMiddleware } from './middleware/identity-map.middleware';
+export { identityMapContext } from './identity-map';

package/dist/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.transactionContext = exports.EntityStorage = void 0;
+exports.identityMapContext = exports.IdentityMapMiddleware = exports.transactionContext = exports.EntityStorage = void 0;
 __exportStar(require("./decorators/entity.decorator"), exports);
 __exportStar(require("./decorators/property.decorator"), exports);
 __exportStar(require("./decorators/primary-key.decorator"), exports);
@@ -41,3 +41,7 @@ __exportStar(require("./common/uuid"), exports);
 __exportStar(require("./repository/Repository"), exports);
 var transaction_context_1 = require("./transaction/transaction-context");
 Object.defineProperty(exports, "transactionContext", { enumerable: true, get: function () { return transaction_context_1.transactionContext; } });
+var identity_map_middleware_1 = require("./middleware/identity-map.middleware");
+Object.defineProperty(exports, "IdentityMapMiddleware", { enumerable: true, get: function () { return identity_map_middleware_1.IdentityMapMiddleware; } });
+var identity_map_1 = require("./identity-map");
+Object.defineProperty(exports, "identityMapContext", { enumerable: true, get: function () { return identity_map_1.identityMapContext; } });

package/dist/middleware/identity-map.middleware.d.ts

@@ -0,0 +1,4 @@
+import { CheetahMiddleware, Context } from '@cheetah.js/core';
+export declare class IdentityMapMiddleware implements CheetahMiddleware {
+    handle(ctx: Context, next: () => void): Promise<void>;
+}

package/dist/middleware/identity-map.middleware.js

@@ -0,0 +1,22 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdentityMapMiddleware = void 0;
+const core_1 = require("@cheetah.js/core");
+const identity_map_1 = require("../identity-map");
+let IdentityMapMiddleware = class IdentityMapMiddleware {
+    async handle(ctx, next) {
+        await identity_map_1.identityMapContext.run(async () => {
+            await next();
+        });
+    }
+};
+exports.IdentityMapMiddleware = IdentityMapMiddleware;
+exports.IdentityMapMiddleware = IdentityMapMiddleware = __decorate([
+    (0, core_1.Injectable)()
+], IdentityMapMiddleware);

package/dist/query/model-transformer.d.ts

@@ -4,9 +4,14 @@ export declare class ModelTransformer {
     private entityStorage;
     constructor(entityStorage: EntityStorage);
     transform<T>(model: any, statement: Statement<any>, data: any): T;
+    private registerInstancesInIdentityMap;
     private createInstances;
     private createInstance;
     private addJoinedInstances;
+    private extractPrimaryKeyFromData;
+    private extractPrimaryKeyValue;
+    private getPrimaryKeyFromData;
+    private findPrimaryKeyProperty;
     private buildOptionsMap;
     private populateProperties;
     private parseColumnKey;

package/dist/query/model-transformer.js

@@ -3,39 +3,77 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ModelTransformer = void 0;
 const value_object_1 = require("../common/value-object");
 const utils_1 = require("../utils");
+const identity_map_1 = require("../identity-map");
 class ModelTransformer {
     constructor(entityStorage) {
         this.entityStorage = entityStorage;
     }
     transform(model, statement, data) {
-        const instanceMap = this.createInstances(model, statement);
+        const instanceMap = this.createInstances(model, statement, data);
         const optionsMap = this.buildOptionsMap(instanceMap);
         this.populateProperties(data, instanceMap, optionsMap);
         this.linkJoinedEntities(statement, instanceMap, optionsMap);
         this.resetChangedValues(instanceMap);
+        this.registerInstancesInIdentityMap(instanceMap);
         return instanceMap[statement.alias];
     }
-    createInstances(model, statement) {
-        const instance = this.createInstance(model);
+    registerInstancesInIdentityMap(instanceMap) {
+        Object.values(instanceMap).forEach(instance => {
+            identity_map_1.IdentityMapIntegration.registerEntity(instance);
+        });
+    }
+    createInstances(model, statement, data) {
+        const primaryKey = this.extractPrimaryKeyFromData(model, statement.alias, data);
+        const instance = this.createInstance(model, primaryKey);
         const instanceMap = {
             [statement.alias]: instance,
         };
         if (statement.join) {
-            this.addJoinedInstances(statement, instanceMap);
+            this.addJoinedInstances(statement, instanceMap, data);
         }
         return instanceMap;
     }
-    createInstance(model) {
-        const instance = new model();
-        instance.$_isPersisted = true;
-        return instance;
+    createInstance(model, primaryKey) {
+        return identity_map_1.IdentityMapIntegration.getOrCreateInstance(model, primaryKey, () => {
+            const instance = new model();
+            instance.$_isPersisted = true;
+            return instance;
+        });
     }
-    addJoinedInstances(statement, instanceMap) {
+    addJoinedInstances(statement, instanceMap, data) {
         statement.join.forEach(join => {
-            const joinInstance = this.createInstance(join.joinEntity);
+            const primaryKey = this.extractPrimaryKeyFromData(join.joinEntity, join.joinAlias, data);
+            const joinInstance = this.createInstance(join.joinEntity, primaryKey);
             instanceMap[join.joinAlias] = joinInstance;
         });
     }
+    extractPrimaryKeyFromData(model, alias, data) {
+        const options = this.entityStorage.get(model);
+        if (!options) {
+            return undefined;
+        }
+        return this.extractPrimaryKeyValue(options, alias, data);
+    }
+    extractPrimaryKeyValue(options, alias, data) {
+        const pkProperty = this.findPrimaryKeyProperty(options);
+        if (!pkProperty) {
+            return undefined;
+        }
+        return this.getPrimaryKeyFromData(pkProperty, alias, data);
+    }
+    getPrimaryKeyFromData(pkProperty, alias, data) {
+        const pkColumnName = pkProperty.options.columnName;
+        const pkKey = `${alias}_${pkColumnName}`;
+        return data[pkKey];
+    }
+    findPrimaryKeyProperty(options) {
+        for (const prop in options.properties) {
+            if (options.properties[prop].options.isPrimary) {
+                return options.properties[prop];
+            }
+        }
+        return null;
+    }
     buildOptionsMap(instanceMap) {
         const optionsMap = new Map();
         for (const [alias, instance] of Object.entries(instanceMap)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cheetah.js/orm",
-  "version": "0.1.144",
+  "version": "0.1.146",
   "description": "A simple ORM for Cheetah.js.",
   "type": "commonjs",
   "main": "dist/index.js",
@@ -55,5 +55,5 @@
     "bun",
     "value-object"
   ],
-  "gitHead": "73bccb890079ef872f5dcb9f9df1a1a9dfad5912"
+  "gitHead": "01d694ffaf36a91a0367d2d79c3f87f43402f62a"
 }