bunsane 0.2.4 → 0.2.7

package/core/ArcheType.ts

@@ -1323,16 +1323,29 @@ export class BaseArcheType {
                             }
                         }
                     } else {
+                        // OPTIMIZED: Find candidate components first, then load in parallel
+                        const candidateComponents: Array<{ compCtor: any }> = [];
                         for (const compCtor of Object.values(this.componentMap)) {
                             const typeId = storage.getComponentId(compCtor.name);
                             const componentProps = storage.getComponentProperties(typeId);
                             const hasForeignKey = componentProps.some(prop => prop.propertyKey === foreignKey);
-                            if (!hasForeignKey) continue;
-                            
-                            const componentInstance = await entity.get(compCtor as any);
-                            if (componentInstance && (componentInstance as any)[foreignKey] !== undefined) {
-                                foreignId = (componentInstance as any)[foreignKey];
-                                break;
+                            if (hasForeignKey) {
+                                candidateComponents.push({ compCtor });
+                            }
+                        }
+
+                        if (candidateComponents.length > 0) {
+                            // Load all candidate components in parallel
+                            const componentInstances = await Promise.all(
+                                candidateComponents.map(({ compCtor }) => entity.get(compCtor as any))
+                            );
+
+                            // Find the first one with the foreign key value
+                            for (const componentInstance of componentInstances) {
+                                if (componentInstance && (componentInstance as any)[foreignKey] !== undefined) {
+                                    foreignId = (componentInstance as any)[foreignKey];
+                                    break;
+                                }
                             }
                         }
                     }
@@ -1392,20 +1405,14 @@ export class BaseArcheType {
                     }
 
                     if (foreignKeyComponent) {
-                        // Query related entities
-                        const relatedEntities = await new Query()
-                            .with(foreignKeyComponent)
+                        // OPTIMIZED: Use Query with filter instead of fetching all + filtering in JS
+                        // This pushes the filtering to the database, avoiding N+1 queries
+                        const matchingEntities = await new Query()
+                            .with(foreignKeyComponent, {
+                                filters: [{ field: foreignKey, operator: '=', value: entity.id }]
+                            })
                             .exec();
 
-                        // Filter entities that reference this entity
-                        const matchingEntities: Entity[] = [];
-                        for (const relatedEntity of relatedEntities) {
-                            const componentInstance = await relatedEntity.get(foreignKeyComponent);
-                            if (componentInstance && (componentInstance as any)[foreignKey] === entity.id) {
-                                matchingEntities.push(relatedEntity);
-                            }
-                        }
-
                         // Attach as computed property
                         (entity as any)[fieldName] = matchingEntities;
                     }
@@ -2037,21 +2044,34 @@ export class BaseArcheType {
                                         }
                                     }
                                 } else {
-                                    // Original logic for flat foreign key
+                                    // OPTIMIZED: Load all candidate components in parallel via DataLoader
+                                    const candidateLoads: Array<{ compCtor: any; typeId: string }> = [];
                                     for (const [componentField, compCtor] of Object.entries(this.componentMap)) {
                                         const typeIdForComponent = storage.getComponentId(compCtor.name);
                                         const componentProps = storage.getComponentProperties(typeIdForComponent);
                                         const hasForeignKey = componentProps.some(prop => prop.propertyKey === foreignKey);
-                                        if (!hasForeignKey || !foreignKey) continue;
-
-                                        const componentData = await context.loaders.componentsByEntityType.load({
-                                            entityId: entityId,
-                                            typeId: typeIdForComponent,
-                                        });
+                                        if (hasForeignKey && foreignKey) {
+                                            candidateLoads.push({ compCtor, typeId: typeIdForComponent });
+                                        }
+                                    }
 
-                                        if (componentData?.data && componentData.data[foreignKey] !== undefined) {
-                                            foreignId = componentData.data[foreignKey];
-                                            break;
+                                    if (candidateLoads.length > 0) {
+                                        // Load all candidate components in parallel
+                                        const componentDataResults = await Promise.all(
+                                            candidateLoads.map(({ typeId }) =>
+                                                context.loaders.componentsByEntityType.load({
+                                                    entityId: entityId,
+                                                    typeId: typeId,
+                                                })
+                                            )
+                                        );
+
+                                        // Find the first one with the foreign key value
+                                        for (const componentData of componentDataResults) {
+                                            if (componentData?.data && componentData.data[foreignKey] !== undefined) {
+                                                foreignId = componentData.data[foreignKey];
+                                                break;
+                                            }
                                         }
                                     }
                                 }
@@ -2072,16 +2092,29 @@ export class BaseArcheType {
                                         }
                                     }
                                 } else {
-                                    // Original logic for flat foreign key
+                                    // OPTIMIZED: Find candidates first, then load in parallel
+                                    const candidateComponents: Array<{ compCtor: any }> = [];
                                     for (const compCtor of Object.values(this.componentMap)) {
                                         const typeIdForComponent = storage.getComponentId(compCtor.name);
                                         const componentProps = storage.getComponentProperties(typeIdForComponent);
                                         const hasForeignKey = componentProps.some(prop => prop.propertyKey === foreignKey);
-                                        if (!hasForeignKey || !foreignKey) continue;
-                                        const componentInstance = await entity.get(compCtor as any);
-                                        if (componentInstance && (componentInstance as any)[foreignKey] !== undefined) {
-                                            foreignId = (componentInstance as any)[foreignKey];
-                                            break;
+                                        if (hasForeignKey && foreignKey) {
+                                            candidateComponents.push({ compCtor });
+                                        }
+                                    }
+
+                                    if (candidateComponents.length > 0) {
+                                        // Load all candidate components in parallel
+                                        const componentInstances = await Promise.all(
+                                            candidateComponents.map(({ compCtor }) => entity.get(compCtor as any))
+                                        );
+
+                                        // Find the first one with the foreign key value
+                                        for (const componentInstance of componentInstances) {
+                                            if (componentInstance && (componentInstance as any)[foreignKey] !== undefined) {
+                                                foreignId = (componentInstance as any)[foreignKey];
+                                                break;
+                                            }
                                         }
                                     }
                                 }

package/core/BatchLoader.ts

@@ -7,6 +7,7 @@ import { sql } from "bun";
 interface CachedRelation {
     ids: string[];
     expiresAt: number;
+    lastAccessed: number;
 }
 
 interface BatchLoaderOptions {
@@ -16,11 +17,192 @@ interface BatchLoaderOptions {
     cacheTTL?: number;
 }
 
+interface BatchLoaderConfig {
+    maxCacheEntries: number;
+    maxCacheTypes: number;
+    evictionBatchSize: number;
+}
+
+/**
+ * LRU-bounded cache for relation lookups.
+ * Prevents unbounded memory growth under high cardinality.
+ */
+class BoundedRelationCache {
+    private cache = new Map<string, Map<string, CachedRelation>>();
+    private accessOrder: string[] = []; // Tracks global access order for LRU eviction
+    private totalEntries = 0;
+    private config: BatchLoaderConfig;
+
+    constructor(config: BatchLoaderConfig) {
+        this.config = config;
+    }
+
+    getTypeCache(cacheKey: string): Map<string, CachedRelation> {
+        let typeCache = this.cache.get(cacheKey);
+        if (!typeCache) {
+            // Evict oldest type caches if at limit
+            if (this.cache.size >= this.config.maxCacheTypes) {
+                this.evictOldestType();
+            }
+            typeCache = new Map();
+            this.cache.set(cacheKey, typeCache);
+        }
+        return typeCache;
+    }
+
+    get(cacheKey: string, parentId: string): CachedRelation | undefined {
+        const typeCache = this.cache.get(cacheKey);
+        if (!typeCache) return undefined;
+
+        const entry = typeCache.get(parentId);
+        if (entry) {
+            // Update access time for LRU
+            entry.lastAccessed = Date.now();
+        }
+        return entry;
+    }
+
+    set(cacheKey: string, parentId: string, entry: CachedRelation): void {
+        const typeCache = this.getTypeCache(cacheKey);
+
+        // Evict if at capacity before adding new entries
+        if (this.totalEntries >= this.config.maxCacheEntries && !typeCache.has(parentId)) {
+            this.evictLRUEntries(this.config.evictionBatchSize);
+        }
+
+        if (!typeCache.has(parentId)) {
+            this.totalEntries++;
+        }
+        typeCache.set(parentId, entry);
+    }
+
+    delete(cacheKey: string, parentId: string): boolean {
+        const typeCache = this.cache.get(cacheKey);
+        if (!typeCache) return false;
+
+        const existed = typeCache.delete(parentId);
+        if (existed) {
+            this.totalEntries--;
+        }
+        return existed;
+    }
+
+    clear(): void {
+        this.cache.clear();
+        this.accessOrder = [];
+        this.totalEntries = 0;
+    }
+
+    getStats(): { types: number; entries: number; expired: number; memoryEstimate: string } {
+        let expiredEntries = 0;
+        const now = Date.now();
+
+        for (const [, typeCache] of this.cache) {
+            for (const [, entry] of typeCache) {
+                if (now > entry.expiresAt) {
+                    expiredEntries++;
+                }
+            }
+        }
+
+        // Rough memory estimate: ~100 bytes per entry (UUID strings + overhead)
+        const memoryBytes = this.totalEntries * 100;
+        const memoryEstimate = memoryBytes > 1024 * 1024
+            ? `${(memoryBytes / (1024 * 1024)).toFixed(2)} MB`
+            : `${(memoryBytes / 1024).toFixed(2)} KB`;
+
+        return {
+            types: this.cache.size,
+            entries: this.totalEntries,
+            expired: expiredEntries,
+            memoryEstimate
+        };
+    }
+
+    private evictOldestType(): void {
+        // Find the type cache with oldest average access time
+        let oldestKey: string | null = null;
+        let oldestAvgAccess = Infinity;
+
+        for (const [key, typeCache] of this.cache) {
+            let totalAccess = 0;
+            let count = 0;
+            for (const [, entry] of typeCache) {
+                totalAccess += entry.lastAccessed;
+                count++;
+            }
+            const avgAccess = count > 0 ? totalAccess / count : 0;
+            if (avgAccess < oldestAvgAccess) {
+                oldestAvgAccess = avgAccess;
+                oldestKey = key;
+            }
+        }
+
+        if (oldestKey) {
+            const evictedCache = this.cache.get(oldestKey);
+            if (evictedCache) {
+                this.totalEntries -= evictedCache.size;
+            }
+            this.cache.delete(oldestKey);
+        }
+    }
+
+    private evictLRUEntries(count: number): void {
+        // Collect all entries with their access times
+        const entries: Array<{ cacheKey: string; parentId: string; lastAccessed: number }> = [];
+
+        for (const [cacheKey, typeCache] of this.cache) {
+            for (const [parentId, entry] of typeCache) {
+                entries.push({ cacheKey, parentId, lastAccessed: entry.lastAccessed });
+            }
+        }
+
+        // Sort by lastAccessed ascending (oldest first)
+        entries.sort((a, b) => a.lastAccessed - b.lastAccessed);
+
+        // Evict the oldest entries
+        const toEvict = entries.slice(0, count);
+        for (const { cacheKey, parentId } of toEvict) {
+            this.delete(cacheKey, parentId);
+        }
+    }
+
+    /**
+     * Prune expired entries. Call periodically to reclaim memory.
+     */
+    pruneExpired(): number {
+        const now = Date.now();
+        let prunedCount = 0;
+
+        for (const [cacheKey, typeCache] of this.cache) {
+            for (const [parentId, entry] of typeCache) {
+                if (now > entry.expiresAt) {
+                    typeCache.delete(parentId);
+                    this.totalEntries--;
+                    prunedCount++;
+                }
+            }
+            // Remove empty type caches
+            if (typeCache.size === 0) {
+                this.cache.delete(cacheKey);
+            }
+        }
+
+        return prunedCount;
+    }
+}
+
 export class BatchLoader {
-    private static cache = new Map<string, Map<string, CachedRelation>>();
+    private static cache = new BoundedRelationCache({
+        maxCacheEntries: 100_000, // Max 100k relation entries (~10MB)
+        maxCacheTypes: 500,       // Max 500 different component types
+        evictionBatchSize: 1000   // Evict 1000 entries at a time
+    });
     private static readonly DEFAULT_BATCH_SIZE = 1000;
     private static readonly DEFAULT_MAX_CONCURRENCY = 5;
     private static readonly DEFAULT_CACHE_TTL = 300_000; // 5 minutes
+    private static lastPruneTime = 0;
+    private static readonly PRUNE_INTERVAL = 60_000; // Prune every minute
 
     /**
      * Load related entities efficiently with caching and batching
@@ -34,6 +216,13 @@ export class BatchLoader {
     ): Promise<Map<string, Entity>> {
         if (entities.length === 0) return new Map();
 
+        // Periodic pruning of expired entries
+        const now = Date.now();
+        if (now - this.lastPruneTime > this.PRUNE_INTERVAL) {
+            this.cache.pruneExpired();
+            this.lastPruneTime = now;
+        }
+
         const {
             fieldName = 'value',
             batchSize = this.DEFAULT_BATCH_SIZE,
@@ -45,22 +234,15 @@ export class BatchLoader {
         const typeId = comp.getTypeID();
         const parentIds = entities.map(e => e.id);
 
-        // Check cache first
-        const cacheKey = `${typeId}:${fieldName}`;
-        let cachedResults = this.cache.get(cacheKey);
-        if (!cachedResults) {
-            cachedResults = new Map();
-            this.cache.set(cacheKey, cachedResults);
-        }
-
-        const now = Date.now();
+        // Cache key uses null byte separator to prevent collision
+        const cacheKey = `${typeId}\x00${fieldName}`;
 
         // Get uncached or expired parent IDs
         const uncachedParentIds = parentIds.filter(id => {
-            const entry = cachedResults.get(id);
+            const entry = this.cache.get(cacheKey, id);
             if (!entry) return true;
             if (now > entry.expiresAt) {
-                cachedResults.delete(id);
+                this.cache.delete(cacheKey, id);
                 return true;
             }
             return false;
@@ -92,16 +274,17 @@ export class BatchLoader {
                 }
 
                 const expiresAt = Date.now() + cacheTTL;
+                const lastAccessed = Date.now();
 
                 // Cache the related IDs for each parent
                 for (const [parentId, relatedIds] of parentGroups) {
-                    cachedResults.set(parentId, { ids: relatedIds, expiresAt });
+                    this.cache.set(cacheKey, parentId, { ids: relatedIds, expiresAt, lastAccessed });
                 }
 
                 // Cache empty arrays for parents with no relations
                 for (const parentId of batch) {
                     if (!parentGroups.has(parentId)) {
-                        cachedResults.set(parentId, { ids: [], expiresAt });
+                        this.cache.set(cacheKey, parentId, { ids: [], expiresAt, lastAccessed });
                     }
                 }
             }
@@ -110,7 +293,7 @@ export class BatchLoader {
         // Collect all unique related IDs from cache
         const allRelatedIds = new Set<string>();
         for (const parentId of parentIds) {
-            const entry = cachedResults.get(parentId);
+            const entry = this.cache.get(cacheKey, parentId);
             const relatedIds = entry?.ids || [];
             relatedIds.forEach((id: string) => allRelatedIds.add(id));
         }
@@ -151,21 +334,23 @@ export class BatchLoader {
     }
 
     /**
-     * Get cache statistics including expired entry count
+     * Get cache statistics including memory estimate
      */
-    static getCacheStats(): { size: number; entries: number; expired: number } {
-        let totalEntries = 0;
-        let expiredEntries = 0;
-        const now = Date.now();
-        for (const [, parentMap] of this.cache) {
-            for (const [, entry] of parentMap) {
-                totalEntries++;
-                if (now > entry.expiresAt) {
-                    expiredEntries++;
-                }
-            }
-        }
-        return { size: this.cache.size, entries: totalEntries, expired: expiredEntries };
+    static getCacheStats(): { size: number; entries: number; expired: number; memoryEstimate?: string } {
+        const stats = this.cache.getStats();
+        return {
+            size: stats.types,
+            entries: stats.entries,
+            expired: stats.expired,
+            memoryEstimate: stats.memoryEstimate
+        };
+    }
+
+    /**
+     * Manually prune expired entries. Returns count of pruned entries.
+     */
+    static pruneExpiredEntries(): number {
+        return this.cache.pruneExpired();
     }
 
     private static chunkArray<T>(array: T[], size: number): T[][] {
@@ -207,4 +392,4 @@ class Semaphore {
             resolve();
         }
     }
-}
+}

package/core/Entity.ts

@@ -1,6 +1,6 @@
 import type { ComponentDataType, ComponentGetter, BaseComponent } from "./components";
 import { logger } from "./Logger";
-import db from "../database";
+import db, { QUERY_TIMEOUT_MS } from "../database";
 import EntityManager from "./EntityManager";
 import ComponentRegistry from "./components/ComponentRegistry";
 import { uuidv7 } from "../utils/uuid";
@@ -389,7 +389,7 @@ export class Entity implements IEntity {
             const timeout = setTimeout(() => {
                 logger.error(`Entity save timeout for entity ${this.id}`);
                 reject(new Error(`Entity save timeout for entity ${this.id}`));
-            }, 30000); // 30 second timeout
+            }, QUERY_TIMEOUT_MS); // Configurable timeout via DB_QUERY_TIMEOUT env var
 
             // Capture dirty components BEFORE doSave clears the dirty flags
             const changedComponentTypeIds = this.getDirtyComponents();

package/core/RequestContext.ts

@@ -6,23 +6,28 @@ import { CacheManager } from './cache/CacheManager';
 
 declare module 'graphql-yoga' {
   interface Context {
-    locals: {
-      loaders: RequestLoaders;
-      requestId: string;
-      cacheManager: CacheManager;
-    };
+    // Loaders mounted at top-level context for ArcheType resolver access
+    loaders: RequestLoaders;
+    requestId: string;
+    cacheManager: CacheManager;
   }
 }
 
+/**
+ * GraphQL Yoga plugin that creates per-request DataLoaders for batching.
+ *
+ * IMPORTANT: Loaders are mounted at context.loaders (NOT context.locals.loaders)
+ * to match what ArcheType.ts resolvers expect. This enables DataLoader batching
+ * for BelongsTo/HasMany relations, preventing N+1 queries.
+ */
 export function createRequestContextPlugin(): Plugin {
   return {
     onExecute: ({ args }) => {
       const cacheManager = CacheManager.getInstance();
-      (args as any).contextValue.locals = {
-        loaders: createRequestLoaders(db, cacheManager),
-        requestId: crypto.randomUUID(),
-        cacheManager: cacheManager,
-      };
+      // Mount loaders at context.loaders to match ArcheType.ts resolver access pattern
+      (args as any).contextValue.loaders = createRequestLoaders(db, cacheManager);
+      (args as any).contextValue.requestId = crypto.randomUUID();
+      (args as any).contextValue.cacheManager = cacheManager;
     },
   };
 }

package/core/RequestLoaders.ts

@@ -273,7 +273,8 @@ export function createRequestLoaders(db: any, cacheManager?: CacheManager): Requ
               return entity;
             });
 
-            const mapKey = `${key.entityId}-${key.relationField}-${key.relatedType}`;
+            // Use null byte separator to prevent key collision when fields contain hyphens
+            const mapKey = `${key.entityId}\x00${key.relationField}\x00${key.relatedType}`;
             resultMap.set(mapKey, entities);
             
             logger.trace(`[RelationLoader] Mapped ${entities.length} entities for ${key.relationField} on ${key.entityId}`);
@@ -291,7 +292,8 @@ export function createRequestLoaders(db: any, cacheManager?: CacheManager): Requ
           if (!k.entityId || typeof k.entityId !== 'string' || k.entityId.trim() === '') {
             return [];
           }
-          const mapKey = `${k.entityId}-${k.relationField}-${k.relatedType}`;
+          // Use null byte separator to prevent key collision when fields contain hyphens
+          const mapKey = `${k.entityId}\x00${k.relationField}\x00${k.relatedType}`;
           const result = resultMap.get(mapKey) || [];
           return result;
         });

package/core/cache/CacheProvider.ts

@@ -9,6 +9,7 @@ export interface CacheStats {
     hitRate: number;
     size: number;
     memoryUsage?: number;
+    memoryUsageHuman?: string;
 }
 
 export interface CacheProvider {

package/core/cache/MemoryCache.ts

@@ -1,6 +1,14 @@
 import { type CacheProvider, type CacheStats } from './CacheProvider';
 import { logger } from '../Logger';
 
+function formatBytes(bytes: number): string {
+    if (bytes === 0) return '0 B';
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    const i = Math.floor(Math.log(bytes) / Math.log(1024));
+    const value = bytes / Math.pow(1024, i);
+    return `${value.toFixed(2)} ${units[i]}`;
+}
+
 interface CacheEntry<T> {
     value: T;
     expiresAt?: number;
@@ -158,7 +166,8 @@ export class MemoryCache implements CacheProvider {
             misses: this.stats.misses,
             hitRate,
             size: this.stats.size,
-            memoryUsage: this.stats.memoryUsage
+            memoryUsage: this.stats.memoryUsage,
+            memoryUsageHuman: formatBytes(this.stats.memoryUsage)
         };
     }
 

package/core/cache/RedisCache.ts

@@ -13,10 +13,22 @@ export interface HealthStatus {
     connected: boolean;
     latency: number;
     memoryUsage?: number;
+    memoryUsageHuman?: string;
     connections?: number;
     version?: string;
 }
 
+/**
+ * Format bytes into human-readable string
+ */
+function formatBytes(bytes: number): string {
+    if (bytes === 0) return '0 B';
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    const i = Math.floor(Math.log(bytes) / Math.log(1024));
+    const value = bytes / Math.pow(1024, i);
+    return `${value.toFixed(2)} ${units[i]}`;
+}
+
 export interface RedisCacheConfig {
     host: string;
     port: number;
@@ -108,7 +120,7 @@ export class RedisCache implements CacheProvider {
                 const memoryMatch = info.match(/used_memory:(\d+)/);
                 if (memoryMatch && memoryMatch[1]) {
                     const memoryUsage = parseInt(memoryMatch[1], 10);
-                    logger.debug({ msg: 'Redis memory usage', memoryUsage });
+                    logger.debug({ msg: 'Redis memory usage', memoryUsage: formatBytes(memoryUsage), memoryUsageBytes: memoryUsage });
                 }
             } catch (error) {
                 logger.error({ error, msg: 'Failed to get Redis memory info' });
@@ -311,7 +323,8 @@ export class RedisCache implements CacheProvider {
                 misses: this.stats.misses,
                 hitRate: this.stats.hits / (this.stats.hits + this.stats.misses) || 0,
                 size,
-                memoryUsage
+                memoryUsage,
+                memoryUsageHuman: memoryUsage !== undefined ? formatBytes(memoryUsage) : undefined
             };
         } catch (error) {
             logger.error({ error, msg: 'Redis getStats error' });
@@ -356,6 +369,7 @@ export class RedisCache implements CacheProvider {
                 connected: true,
                 latency,
                 memoryUsage,
+                memoryUsageHuman: memoryUsage !== undefined ? formatBytes(memoryUsage) : undefined,
                 connections,
                 version
             };

package/core/validateEnv.ts

@@ -52,6 +52,14 @@ const envSchema = z
             .string()
             .regex(/^\d+$/, "DB_STATEMENT_TIMEOUT must be numeric")
             .optional(),
+        DB_QUERY_TIMEOUT: z
+            .string()
+            .regex(/^\d+$/, "DB_QUERY_TIMEOUT must be numeric (milliseconds)")
+            .optional(),
+        DB_CONNECTION_TIMEOUT: z
+            .string()
+            .regex(/^\d+$/, "DB_CONNECTION_TIMEOUT must be numeric (seconds)")
+            .optional(),
     })
     .refine(
         (env) => {