bunsane 0.3.1 → 0.4.0

package/core/cache/strategies/writeThrough.ts

@@ -0,0 +1,233 @@
+import { type CacheProvider } from '../CacheProvider';
+import { type CacheConfig } from '../../../config/cache.config';
+import { logger } from '../../Logger';
+import type { Entity } from '../../Entity';
+import type { BaseComponent } from '../../components';
+import type { ComponentData } from '../../RequestLoaders';
+
+// Must match the value exported by CacheManager — inlined here to avoid
+// a circular import (CacheManager imports this module).
+const COMPONENT_TOMBSTONE = '__TOMBSTONE__' as const;
+type ComponentCacheValue = ComponentData | typeof COMPONENT_TOMBSTONE;
+
+/**
+ * Write-through strategy: entity get/set operations
+ */
+
+export async function getEntity(provider: CacheProvider, config: CacheConfig, id: string): Promise<string | null> {
+    if (!config.enabled || !config.entity?.enabled) {
+        return null;
+    }
+
+    try {
+        const key = `entity:${id}`;
+        const result = await provider.get<string>(key);
+        return result || null;
+    } catch (error) {
+        logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error getting entity from cache', error });
+        return null;
+    }
+}
+
+export async function setEntityWriteThrough(provider: CacheProvider, config: CacheConfig, entity: Entity, ttl?: number): Promise<void> {
+    if (!config.enabled || !config.entity?.enabled) {
+        return;
+    }
+
+    try {
+        const key = `entity:${entity.id}`;
+        const effectiveTTL = ttl ?? config.entity.ttl;
+        // Only cache entity ID for existence check
+        await provider.set(key, entity.id, effectiveTTL);
+    } catch (error) {
+        logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error setting entity in cache', error });
+    }
+}
+
+export async function getEntities(provider: CacheProvider, config: CacheConfig, ids: string[]): Promise<(string | null)[]> {
+    if (!config.enabled || !config.entity?.enabled) {
+        return ids.map(() => null);
+    }
+
+    try {
+        const cacheKeys = ids.map(id => `entity:${id}`);
+        const results = await provider.getMany<string>(cacheKeys);
+        return results;
+    } catch (error) {
+        logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error getting entities from cache', error });
+        return ids.map(() => null);
+    }
+}
+
+export async function setEntitiesWriteThrough(provider: CacheProvider, config: CacheConfig, entities: Entity[], ttl?: number): Promise<void> {
+    if (!config.enabled || !config.entity?.enabled) {
+        return;
+    }
+
+    try {
+        const effectiveTTL = ttl ?? config.entity?.ttl;
+        const entries = entities.map(entity => ({
+            key: `entity:${entity.id}`,
+            // Only cache entity ID for existence check
+            value: entity.id,
+            ttl: effectiveTTL
+        }));
+        await provider.setMany(entries);
+    } catch (error) {
+        logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error setting entities in cache', error });
+    }
+}
+
+export async function getComponentsByEntity(provider: CacheProvider, config: CacheConfig, entityId: string, componentType?: string): Promise<BaseComponent[] | null> {
+    if (!config.enabled || !config.component?.enabled) {
+        return null;
+    }
+
+    try {
+        const key = componentType
+            ? `component:${entityId}:${componentType}`
+            : `components:${entityId}`;
+        return await provider.get<BaseComponent[]>(key);
+    } catch (error) {
+        logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error getting components from cache', error });
+        return null;
+    }
+}
+
+/**
+ * Set components for an entity in cache with write-through strategy.
+ * Converts BaseComponent instances to ComponentData format for cache compatibility with DataLoader.
+ * Delegates to setComponentsBatchWriteThrough for a single-entity, 2-RTT batch.
+ */
+export async function setComponentWriteThrough(provider: CacheProvider, config: CacheConfig, entityId: string, components: BaseComponent[], componentType?: string, ttl?: number): Promise<void> {
+    if (!config.enabled || !config.component?.enabled) {
+        return;
+    }
+    const entries = components.map(c => ({
+        entityId,
+        typeId: componentType || c.getTypeID(),
+        component: c,
+        ttl,
+    }));
+    await setComponentsBatchWriteThrough(provider, config, entries);
+}
+
+/**
+ * Batch write-through for BaseComponent instances across any number of
+ * entities. Performs exactly 2 Redis round-trips regardless of entry count:
+ *   1. pipelined getMany  — reads existing entries to preserve createdAt (H-CACHE-3)
+ *   2. pipelined setMany  — writes all updated entries
+ */
+export async function setComponentsBatchWriteThrough(
+    provider: CacheProvider,
+    config: CacheConfig,
+    entries: Array<{ entityId: string; typeId: string; component: BaseComponent; ttl?: number }>,
+): Promise<void> {
+    if (!config.enabled || !config.component?.enabled || entries.length === 0) {
+        return;
+    }
+
+    try {
+        const effectiveTTL = config.component.ttl;
+        const keys = entries.map(e => `component:${e.entityId}:${e.typeId}`);
+
+        // One batched read — preserves createdAt from existing entries (H-CACHE-3).
+        const existing = await provider.getMany<ComponentData>(keys);
+
+        const now = new Date();
+        const setEntries = entries.map((e, i) => {
+            const prev = existing[i];
+            const createdAt: Date =
+                prev && prev.createdAt
+                    ? (prev.createdAt instanceof Date ? prev.createdAt : new Date(prev.createdAt))
+                    : now;
+
+            const componentData: ComponentData = {
+                id: e.component.id,
+                entityId: e.entityId,
+                typeId: e.typeId,
+                data: e.component.data(),
+                createdAt,
+                updatedAt: now,
+                deletedAt: null,
+            };
+
+            return { key: keys[i]!, value: componentData, ttl: e.ttl ?? effectiveTTL };
+        });
+
+        // One batched write.
+        await provider.setMany(setEntries);
+    } catch (error) {
+        logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error setting components in cache (batch)', err: error });
+    }
+}
+
+export async function getComponents(provider: CacheProvider, config: CacheConfig, keys: Array<{ entityId: string; typeId: string }>): Promise<(ComponentCacheValue | null)[]> {
+    if (!config.enabled || !config.component?.enabled) {
+        return keys.map(() => null);
+    }
+
+    try {
+        const cacheKeys = keys.map(k => `component:${k.entityId}:${k.typeId}`);
+        const results = await provider.getMany<ComponentCacheValue>(cacheKeys);
+        return results;
+    } catch (error) {
+        logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error getting components from cache', error });
+        return keys.map(() => null);
+    }
+}
+
+/**
+ * Set components in cache with write-through strategy (for DataLoader integration).
+ *
+ * When `requestedKeys` is supplied and `component.negativeCacheEnabled` is
+ * true, tombstones are written for any requested key not present in
+ * `components` (within the same setMany call — single round-trip).
+ */
+export async function setComponentsWriteThrough(
+    provider: CacheProvider,
+    config: CacheConfig,
+    components: ComponentData[],
+    ttlOrRequested?: number | Array<{ entityId: string; typeId: string }>,
+    ttlIfRequested?: number,
+): Promise<void> {
+    if (!config.enabled || !config.component?.enabled) {
+        return;
+    }
+
+    // Backward-compatible overload: (components, ttl?) or (components, requestedKeys, ttl?)
+    const requestedKeys = Array.isArray(ttlOrRequested) ? ttlOrRequested : undefined;
+    const ttl = Array.isArray(ttlOrRequested) ? ttlIfRequested : ttlOrRequested;
+
+    try {
+        const componentTTL = ttl ?? config.component.ttl;
+        const entries: Array<{ key: string; value: ComponentCacheValue; ttl: number }> = components.map(comp => ({
+            key: `component:${comp.entityId}:${comp.typeId}`,
+            value: comp,
+            ttl: componentTTL,
+        }));
+
+        const negativeEnabled = config.component.negativeCacheEnabled === true;
+        if (negativeEnabled && requestedKeys && requestedKeys.length > 0) {
+            const found = new Set(components.map(c => `${c.entityId}-${c.typeId}`));
+            const tombstoneTTL = config.component.negativeCacheTtl
+                ?? Math.min(componentTTL, 60_000);
+            for (const k of requestedKeys) {
+                const dedupeKey = `${k.entityId}-${k.typeId}`;
+                if (!found.has(dedupeKey)) {
+                    entries.push({
+                        key: `component:${k.entityId}:${k.typeId}`,
+                        value: COMPONENT_TOMBSTONE,
+                        ttl: tombstoneTTL,
+                    });
+                }
+            }
+        }
+
+        if (entries.length > 0) {
+            await provider.setMany(entries);
+        }
+    } catch (error) {
+        logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error setting components in cache', error });
+    }
+}

package/core/components/BaseComponent.ts

@@ -52,11 +52,16 @@ export class BaseComponent {
         const data: Record<string, any> = {};
         const storage = getMetadataStorage();
         const props = storage.componentProperties.get(this._typeId);
-        this.properties().forEach((prop: string) => {
+        if (!props) return data;
+        // Iterate the property metadata directly — avoids the prior O(n²)
+        // pattern (properties().forEach + props.find per property) and the
+        // redundant second metadata lookup inside properties(). Hot write path:
+        // runs for every dirty component on every save.
+        for (const propMeta of props) {
+            const prop = propMeta.propertyKey;
             let value = (this as any)[prop];
-            const propMeta = props?.find(p => p.propertyKey === prop);
             if (value !== null && value !== undefined) {
-                if (propMeta?.propertyType === Date) {
+                if (propMeta.propertyType === Date) {
                     if (!(value instanceof Date)) {
                         throw new Error(`Type mismatch for property '${prop}' on component '${this._comp_name}': expected Date, got ${typeof value}`);
                     }
@@ -64,17 +69,21 @@ export class BaseComponent {
                         throw new Error(`Invalid Date for property '${prop}' on component '${this._comp_name}'`);
                     }
                     value = value.toISOString();
-                } else if (propMeta?.propertyType === Number && typeof value === 'number' && !Number.isFinite(value)) {
+                } else if (propMeta.propertyType === Number && typeof value === 'number' && !Number.isFinite(value)) {
                     throw new Error(`Invalid number for property '${prop}' on component '${this._comp_name}': ${value}`);
                 }
             }
             data[prop] = value;
-        });
+        }
         return data;
     }
 
     async save(trx: Bun.SQL, entity_id: string) {
-        logger.trace(`Saving component ${this._comp_name} for entity ${entity_id}`);
+        // Level-gated: template literal allocates per component save even
+        // when trace is disabled.
+        if (logger.isLevelEnabled?.('trace')) {
+            logger.trace(`Saving component ${this._comp_name} for entity ${entity_id}`);
+        }
         // Only check readiness if component is not yet registered
         // This optimization avoids 40,000+ unnecessary async calls for bulk operations
         if(!ComponentRegistry.isComponentReady(this._comp_name)) {
@@ -98,10 +107,9 @@ export class BaseComponent {
         if (!entity_id || entity_id.trim() === '') {
             throw new Error(`Cannot insert component ${this._comp_name}: entity_id is empty or invalid`);
         }
-        await trx`INSERT INTO components 
+        await trx`INSERT INTO components
         (id, entity_id, name, type_id, data)
         VALUES (${this.id}, ${entity_id}, ${this._comp_name}, ${this._typeId}, ${this.serializableData()})`
-        await trx`INSERT INTO entity_components (entity_id, type_id, component_id) VALUES (${entity_id}, ${this._typeId}, ${this.id}) ON CONFLICT DO NOTHING`
     }
 
     async update(trx: Bun.SQL) {

package/core/components/ComponentRegistry.ts

@@ -8,6 +8,7 @@ import {
     GenerateTableName,
     UpdateComponentIndexes,
     AnalyzeAllComponentTables,
+    CreateRelationIndexes,
     GetPartitionStrategy,
 } from "../../database/DatabaseHelper";
 import { ensureMultipleJSONBPathIndexes } from "../../database/IndexingStrategy";
@@ -34,6 +35,7 @@ class ComponentRegistry {
     private readinessPromises = new Map<string, Promise<void>>();
     private readinessResolvers = new Map<string, () => void>();
     private componentsRegistered: boolean = false;
+    private cachedPartitionStrategy: string | null = null;
 
     constructor() {}
 
@@ -200,6 +202,18 @@ class ComponentRegistry {
     }
 
     register(name: string, typeid: string, ctor: ComponentConstructor) {
+        // Warn when a LIST partition is being attached after startup registration
+        // completed. CREATE TABLE ... PARTITION OF takes ACCESS EXCLUSIVE on the
+        // parent `components` table, stalling all component I/O during the lock.
+        // Fine at boot; dangerous if a request triggers first use of a new type.
+        if (this.componentsRegistered && this.cachedPartitionStrategy === 'list') {
+            logger.warn(
+                `Runtime partition attach for component "${name}" takes ACCESS EXCLUSIVE on the ` +
+                `components table, stalling all component reads and writes until the DDL completes. ` +
+                `Pre-register all components at startup, or set BUNSANE_PARTITION_STRATEGY=hash ` +
+                `to avoid per-component partitions.`
+            );
+        }
         return new Promise<boolean>(async (resolve) => {
             const partitionTableName = GenerateTableName(name);
             // await this.populateCurrentTables();
@@ -289,6 +303,7 @@ class ComponentRegistry {
 
         // Check partitioning strategy for index creation
         const partitionStrategy = await GetPartitionStrategy();
+        this.cachedPartitionStrategy = partitionStrategy;
 
         // Update component indexes for components that have indexed properties
         // NOTE: Index operations are serialized to prevent deadlocks with ANALYZE
@@ -346,6 +361,19 @@ class ComponentRegistry {
         }
         logger.info(`Registered hooks for ${services.length} services`);
 
+        // Create btree indexes on archetype relation foreign-key fields
+        // (data->>'fk'). Without these, @BelongsTo/@HasMany resolver queries
+        // sequentially scan the relation component partition tables. Runs
+        // before ANALYZE so the planner picks up fresh stats for the new
+        // indexes. Idempotent (IF NOT EXISTS) and CONCURRENTLY on LIST
+        // partitions, so it is safe to re-run on every startup against live
+        // tables.
+        try {
+            await CreateRelationIndexes();
+        } catch (error) {
+            logger.warn(`Failed to create relation FK indexes: ${error}`);
+        }
+
         // Run ANALYZE on all component tables to update query planner statistics
         await AnalyzeAllComponentTables();
     }

package/core/decorators/IndexedField.ts

@@ -11,7 +11,7 @@ import { getMetadataStorage } from '../metadata';
  *   - 'numeric': BTREE index with numeric cast for range queries (>, <, BETWEEN)
  * @param isDateField Whether this field contains date values (affects BTREE index casting)
  */
-export function IndexedField(indexType: 'gin' | 'btree' | 'hash' | 'numeric' = 'gin', isDateField: boolean = false) {
+export function IndexedField(indexType: 'gin' | 'btree' | 'hash' | 'numeric' | 'fulltext' = 'gin', isDateField: boolean = false) {
     return function(target: any, propertyKey: string) {
         const storage = getMetadataStorage();
         const componentId = storage.getComponentId(target.constructor.name);

package/core/entity/cacheStrategies.ts

@@ -0,0 +1,97 @@
+// Cache side-effect strategies for Entity save/delete. Extracted from
+// Entity.ts (RFC_REFACTOR_TARGETS §3.2). Pure functions take the entity
+// instance as the first parameter.
+import type { BaseComponent } from "../components";
+import { logger } from "../Logger";
+import EntityHookManager from "../EntityHookManager";
+import { EntityDeletedEvent } from "../events/EntityLifecycleEvents";
+import type { SQL } from "bun";
+import type { Entity } from "../Entity";
+
+/**
+ * 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)
+ */
+export async function handleCacheAfterSave(entity: Entity, changedComponentTypeIds: string[], removedComponentTypeIds: string[], context?: { loaders?: { componentsByEntityType?: any }; trx?: SQL; signal?: AbortSignal }): Promise<void> {
+    try {
+        // Import CacheManager dynamically to avoid circular dependency
+        const { CacheManager } = await import('../cache/CacheManager');
+        const cacheManager = CacheManager.getInstance();
+        const config = cacheManager.getConfig();
+
+        const entityEnabled = !!(config.enabled && config.entity?.enabled);
+        const componentEnabled = !!(config.enabled && config.component?.enabled);
+
+        if (entityEnabled && config.strategy === 'write-through') {
+            await cacheManager.setEntityWriteThrough(entity, config.entity!.ttl);
+        }
+
+        // Handle component cache invalidation with granular approach
+        if (componentEnabled) {
+            // Use the pre-captured lists instead of re-querying (dirty flags are already cleared by doSave)
+
+            if (config.strategy === 'write-through') {
+                // Single batched write-through (2 pipelined provider
+                // round-trips total) instead of one GET+SET pair per
+                // changed component.
+                const entries = changedComponentTypeIds
+                    .map(typeId => ({ typeId, component: entity.components.get(typeId) }))
+                    .filter((e): e is { typeId: string; component: BaseComponent } => !!e.component)
+                    .map(e => ({ entityId: entity.id, typeId: e.typeId, component: e.component, ttl: config.component!.ttl }));
+                if (entries.length > 0) {
+                    await cacheManager.setComponentsBatchWriteThrough(entries);
+                }
+                // Removed components must still drop out of cache.
+                if (removedComponentTypeIds.length > 0) {
+                    await cacheManager.invalidateEntityComponents(entity.id, removedComponentTypeIds);
+                }
+            } else {
+                // One deleteMany + ONE pub/sub message for the whole save
+                // (entity key included) — previously N+1 DEL+PUBLISH pairs
+                // per save, fanning out to every other instance.
+                const toInvalidate = [...changedComponentTypeIds, ...removedComponentTypeIds];
+                if (toInvalidate.length > 0 || entityEnabled) {
+                    await cacheManager.invalidateEntityComponents(entity.id, toInvalidate, { includeEntityKey: entityEnabled });
+                }
+            }
+
+            // Invalidate DataLoader cache for changed + removed components
+            if (context?.loaders?.componentsByEntityType) {
+                for (const typeId of [...changedComponentTypeIds, ...removedComponentTypeIds]) {
+                    context.loaders.componentsByEntityType.clear({
+                        entityId: entity.id,
+                        typeId: typeId
+                    });
+                }
+            }
+        } else if (entityEnabled && config.strategy !== 'write-through') {
+            await cacheManager.invalidateEntity(entity.id);
+        }
+    } catch (error) {
+        logger.warn({ scope: 'cache', component: 'Entity', msg: 'Cache operation failed after save', error });
+    }
+}
+
+export async function runPostDeleteSideEffects(entity: Entity, softDelete: boolean): Promise<void> {
+    try {
+        await EntityHookManager.executeHooks(new EntityDeletedEvent(entity, softDelete));
+    } catch (err) {
+        logger.error({ scope: 'hooks', entityId: entity.id, err }, 'post-delete lifecycle hooks failed');
+    }
+
+    try {
+        const { CacheManager } = await import('../cache/CacheManager');
+        const cacheManager = CacheManager.getInstance();
+        const config = cacheManager.getConfig();
+
+        if (config.enabled && config.entity?.enabled) {
+            await cacheManager.invalidateEntity(entity.id);
+        }
+        if (config.enabled && config.component?.enabled) {
+            await cacheManager.invalidateAllEntityComponents(entity.id);
+        }
+    } catch (err) {
+        logger.warn({ scope: 'cache', entityId: entity.id, err }, 'post-delete cache invalidation failed');
+    }
+}