bunsane 0.3.1 → 0.4.0

package/core/entity/componentAccess.ts

@@ -0,0 +1,364 @@
+// Component access + mutation for Entity (add/set/remove/get/has/reload
+// and the in-memory helpers). Extracted from Entity.ts
+// (RFC_REFACTOR_TARGETS §3.2). Pure functions take the entity instance as
+// the first parameter; hook phases/order are byte-identical to the
+// original inline implementation.
+import type { ComponentDataType, ComponentGetter, BaseComponent } from "../components";
+import { logger } from "../Logger";
+import db from "../../database";
+import { runWithSignal } from "../../database/cancellable";
+import ComponentRegistry from "../components/ComponentRegistry";
+import { SQL } from "bun";
+import EntityHookManager from "../EntityHookManager";
+import { getMetadataStorage } from "../metadata";
+import { ComponentAddedEvent, ComponentUpdatedEvent, ComponentRemovedEvent } from "../events/EntityLifecycleEvents";
+import { getRequestScope } from "../requestScope";
+import { trackCacheOp } from "./pendingOps";
+import type { Entity } from "../Entity";
+
+export function addComponent(entity: Entity, component: BaseComponent): Entity {
+    entity.components.set(component.getTypeID(), component);
+    return entity;
+}
+
+/**
+ * Resolve a component constructor to its type id. `getComponentId` is
+ * memoized in metadata storage, so this is an O(1) Map lookup with no
+ * component instantiation — unlike `new ctor().getTypeID()`. The
+ * `components` map is keyed by type id (see addComponent), so callers can
+ * then do `entity.components.get(typeId)` instead of allocating an array and
+ * scanning it with `instanceof`.
+ */
+export function typeIdOf(ctor: new (...args: any[]) => BaseComponent): string {
+    return getMetadataStorage().getComponentId(ctor.name);
+}
+
+export function componentList(entity: Entity): BaseComponent[] {
+    return Array.from(entity.components.values());
+}
+
+export function getInMemory<T extends BaseComponent>(entity: Entity, ctor: new (...args: any[]) => T): T | undefined {
+    return entity.components.get(typeIdOf(ctor)) as T | undefined;
+}
+
+export function hasInMemory<T extends BaseComponent>(entity: Entity, ctor: new (...args: any[]) => T): boolean {
+    return entity.components.has(typeIdOf(ctor));
+}
+
+export function wasRemoved<T extends BaseComponent>(entity: Entity, ctor: new (...args: any[]) => T): boolean {
+    const typeId = typeIdOf(ctor);
+    // Check both pending removals and already-saved removals
+    return entity.removedComponents.has(typeId) || entity.savedRemovedComponents.has(typeId);
+}
+
+export function add<T extends BaseComponent>(entity: Entity, ctor: new (...args: any[]) => T, data?: Partial<ComponentDataType<T>>): Entity {
+    const instance = new ctor();
+    if (data) {
+        Object.assign(instance, data);
+    } else {
+        Object.assign(instance, {});
+    }
+    addComponent(entity, instance);
+    entity.setDirty(true);
+    // executeHooks is async; the surrounding try/catch only captures
+    // synchronous throws. Attach a .catch so an async rejection from a
+    // hook handler does not escape as an unhandled rejection (H-HOOK-1).
+    // Add stays sync to preserve the fluent chaining signature; hook
+    // failures are logged and do not fail the add operation.
+    Promise.resolve()
+        .then(() => EntityHookManager.executeHooks(new ComponentAddedEvent(entity, instance)))
+        .catch((error) => {
+            logger.error(`Error firing component added hook for ${instance.getTypeID()}: ${error}`);
+        });
+
+    return entity;
+}
+
+export async function set<T extends BaseComponent>(entity: Entity, ctor: new (...args: any[]) => T, data: Partial<ComponentDataType<T>>, context?: { loaders?: { componentsByEntityType?: any }; trx?: SQL; signal?: AbortSignal }): Promise<Entity> {
+    await get(entity, ctor, context);
+
+    const component = entity.components.get(typeIdOf(ctor)) as T;
+    if (component) {
+        // Store old data for the update event
+        const oldData = { ...component };
+
+        // Update existing component
+        Object.assign(component, data);
+        component.setDirty(true);
+        entity.setDirty(true);
+
+        // Fire component updated event. Await so a hook rejection is
+        // captured by this method's try/catch and does not escape as an
+        // unhandled rejection (H-HOOK-1).
+        try {
+            await EntityHookManager.executeHooks(new ComponentUpdatedEvent(entity, component, oldData, component));
+        } catch (error) {
+            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: entity.id,
+                typeId: component.getTypeID()
+            });
+        }
+
+        // Fire-and-forget cache update, tracked via drainable set so
+        // App.shutdown can await it (H-CACHE-1).
+        trackCacheOp((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') {
+                        await cacheManager.setComponentWriteThrough(entity.id, [component], component.getTypeID(), config.component.ttl);
+                    } else {
+                        await cacheManager.invalidateComponent(entity.id, component.getTypeID());
+                    }
+                }
+            } catch (error) {
+                logger.warn({ scope: 'cache', component: 'Entity', msg: 'Cache operation failed after set', err: error });
+            }
+        })());
+    } else {
+        // Add new component
+        add(entity, ctor, data);
+        entity.setDirty(true);
+        // Note: add() already fires ComponentAddedEvent, so we don't need to fire it again
+    }
+    return entity;
+}
+
+export function remove<T extends BaseComponent>(entity: Entity, ctor: new (...args: any[]) => T, context?: { loaders?: { componentsByEntityType?: any }; trx?: SQL; signal?: AbortSignal }): boolean {
+    const component = entity.components.get(typeIdOf(ctor)) as T;
+
+    if (component) {
+        const typeId = component.getTypeID();
+
+        // Track the component type for database deletion
+        entity.removedComponents.add(typeId);
+
+        // Remove the component from the map
+        entity.components.delete(typeId);
+        entity.setDirty(true);
+
+        // Fire component removed event. remove() stays sync to preserve
+        // the boolean return signature used by callers; attach .catch so
+        // async hook rejections do not escape (H-HOOK-1).
+        Promise.resolve()
+            .then(() => EntityHookManager.executeHooks(new ComponentRemovedEvent(entity, component)))
+            .catch((error) => {
+                logger.error(`Error firing component removed hook for ${typeId}: ${error}`);
+            });
+
+        // Invalidate DataLoader cache if context is provided
+        if (context?.loaders?.componentsByEntityType) {
+            context.loaders.componentsByEntityType.clear({
+                entityId: entity.id,
+                typeId: typeId
+            });
+        }
+
+        // Fire-and-forget cache invalidation, tracked for shutdown drain
+        // (H-CACHE-1).
+        trackCacheOp((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(entity.id, typeId);
+                }
+            } catch (error) {
+                logger.warn({ scope: 'cache', component: 'Entity', msg: 'Cache invalidation failed after remove', err: error });
+            }
+        })());
+
+        return true;
+    }
+
+    return false;
+}
+
+export async function get<T extends BaseComponent>(entity: Entity, ctor: new (...args: any[]) => T, context?: { loaders?: { componentsByEntityType?: any }; trx?: SQL; signal?: AbortSignal }): Promise<ComponentDataType<T> | null> {
+    const comp = await loadComponent(entity, ctor, context);
+    return comp ? (comp as ComponentGetter<T>).data() : null;
+}
+
+export function has<T extends BaseComponent>(entity: Entity, ctor: new (...args: any[]) => T): boolean {
+    return hasInMemory(entity, ctor);
+}
+
+export async function getOrThrow<T extends BaseComponent>(
+    entity: Entity,
+    ctor: new (...args: any[]) => T,
+    context?: { loaders?: { componentsByEntityType?: any }; trx?: SQL; signal?: AbortSignal }
+): Promise<ComponentDataType<T>> {
+    const data = await get(entity, ctor, context);
+    if (data === null) {
+        throw new Error(`Entity ${entity.id} is missing required component ${ctor.name}`);
+    }
+    return data;
+}
+
+export function getCached<T extends BaseComponent>(entity: Entity, ctor: new (...args: any[]) => T): ComponentDataType<T> | undefined {
+    const comp = getInMemory(entity, ctor);
+    return comp ? (comp as ComponentGetter<T>).data() : undefined;
+}
+
+export async function getInstanceOf<T extends BaseComponent>(entity: Entity, ctor: new (...args: any[]) => T, context?: { loaders?: { componentsByEntityType?: any }; trx?: SQL; signal?: AbortSignal }): Promise<T | null> {
+    return loadComponent(entity, ctor, context);
+}
+
+export async function reload(entity: Entity, opts?: { trx?: SQL; signal?: AbortSignal }): Promise<Entity> {
+    if (!entity.id || entity.id.trim() === '') {
+        return entity;
+    }
+    entity.components.clear();
+    entity.removedComponents.clear();
+    entity.savedRemovedComponents.clear();
+
+    const dbConn = opts?.trx ?? db;
+    const rows = await runWithSignal<any[]>(
+        dbConn`
+        SELECT c.id, c.type_id, c.data
+        FROM components c
+        WHERE c.entity_id = ${entity.id} AND c.deleted_at IS NULL
+    `,
+        opts?.signal
+    );
+
+    const storage = getMetadataStorage();
+    for (const row of rows) {
+        const ctor = ComponentRegistry.getConstructor(row.type_id);
+        if (!ctor) continue;
+        const comp: any = new ctor();
+        const parsed = typeof row.data === 'string' ? JSON.parse(row.data) : row.data;
+        Object.assign(comp, parsed);
+        comp.id = row.id;
+        const props = storage.componentProperties.get(row.type_id);
+        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);
+        addComponent(entity, comp);
+    }
+
+    entity.setPersisted(true);
+    entity.setDirty(false);
+    return entity;
+}
+
+export async function requireComponents(entity: Entity, ctors: Array<new (...args: any[]) => BaseComponent>): Promise<void> {
+    if (ctors.length === 0) return;
+    const missing: string[] = [];
+    for (const ctor of ctors) {
+        // components is keyed by type id — O(1) lookup, no instantiation
+        // and no O(K) instanceof scan per constructor.
+        const typeId = typeIdOf(ctor);
+        if (!entity.components.has(typeId)) {
+            missing.push(typeId);
+        }
+    }
+    if (missing.length === 0) return;
+    const { Entity } = await import("../Entity");
+    await Entity.LoadComponents([entity], missing);
+}
+
+async function loadComponent<T extends BaseComponent>(entity: Entity, ctor: new (...args: any[]) => T, context?: { loaders?: { componentsByEntityType?: any }; trx?: SQL; signal?: AbortSignal }): Promise<T | null> {
+    const comp = entity.components.get(typeIdOf(ctor)) as T | undefined;
+    if (typeof comp !== "undefined") {
+        return comp;
+    }
+
+    // Validate entity ID before database query
+    if (!entity.id || entity.id.trim() === '') {
+        logger.warn(`Cannot load component ${ctor.name}: entity id is empty`);
+        return null;
+    }
+
+    // Memoized metadata lookup — no throwaway component instantiation
+    // just to read the type id.
+    const typeId = typeIdOf(ctor);
+
+    // Use transaction if provided, otherwise use default db
+    const dbConn = context?.trx ?? db;
+
+    // Ambient request scope fallback: bare entity.get() calls (e.g.
+    // inside @ArcheTypeFunction bodies or Unwrap()) batch through the
+    // request's DataLoaders instead of firing one SELECT per call.
+    // Never substituted when the caller passed an explicit trx — a
+    // loader read outside the transaction could see stale data.
+    const scope = (!context?.loaders && !context?.trx) ? getRequestScope() : undefined;
+    const loaders = context?.loaders ?? scope?.loaders;
+    const signal = context?.signal ?? scope?.signal;
+
+    try {
+        let componentData: any = null;
+        let componentId: string | null = null;
+
+        if (loaders?.componentsByEntityType) {
+            const loaderResult = await loaders.componentsByEntityType.load({
+                entityId: entity.id,
+                typeId: typeId
+            });
+            if (loaderResult) {
+                componentData = loaderResult.data;
+                componentId = loaderResult.id;
+            }
+        } else {
+            // Route through runWithSignal so a request/wall-clock abort can
+            // cancel this in-flight read. When dbConn is context.trx, an
+            // uncancelled read leaks the backend into `idle in transaction`
+            // on timeout (matches the d1dde84 save/delete fix, which missed
+            // the read path).
+            const rows = await runWithSignal<any[]>(
+                dbConn`SELECT id, data FROM components WHERE entity_id = ${entity.id} AND type_id = ${typeId} AND deleted_at IS NULL`,
+                signal
+            );
+            if (rows.length > 0) {
+                componentData = rows[0].data;
+                componentId = rows[0].id;
+            }
+        }
+
+        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);
+            addComponent(entity, comp);
+            return comp as T;
+        } else {
+            return null;
+        }
+    } catch (error) {
+        logger.error(`Failed to fetch component ${ctor.name}: ${error}`);
+        return null;
+    }
+}
+
+export { loadComponent };

package/core/entity/finders.ts

@@ -0,0 +1,202 @@
+// Entity loaders, clone/ref factories, and (de)serialization. Extracted
+// from Entity.ts (RFC_REFACTOR_TARGETS §3.2). Functions take/return the
+// Entity instance; the Entity class is imported lazily where construction
+// is needed to avoid a module-eval cycle.
+import { logger } from "../Logger";
+import db from "../../database";
+import ComponentRegistry from "../components/ComponentRegistry";
+import { uuidv7 } from "../../utils/uuid";
+import { sql, SQL } from "bun";
+import { getMetadataStorage } from "../metadata";
+import { addComponent } from "./componentAccess";
+// Value import: the Entity class is only referenced inside function bodies
+// (called at runtime, after module init), so the ESM cycle with Entity.ts
+// resolves via live bindings without a load-order hazard.
+import { Entity } from "../Entity";
+
+export async function 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(validIds)} AND c.deleted_at IS NULL
+    `;
+
+    const entitiesMap = new Map<string, Entity>();
+
+    for (const id of validIds) {
+        const entity = new Entity();
+        entity.id = id;
+        entity.setPersisted(true);
+        entity.setDirty(false);
+        entitiesMap.set(id, entity);
+    }
+
+    for (const row of components) {
+        const { id, entity_id, type_id, data } = row;
+        const ctor = ComponentRegistry.getConstructor(type_id);
+        if (ctor) {
+            const comp = new ctor();
+            const componentData = typeof data === 'string' ? JSON.parse(data) : data;
+            Object.assign(comp, componentData);
+            comp.id = id;
+            comp.setPersisted(true);
+            comp.setDirty(false);
+            const target = entitiesMap.get(entity_id);
+            if (target) addComponent(target, comp);
+        }
+    }
+
+    return Array.from(entitiesMap.values());
+}
+
+export async function loadComponents(entities: Entity[], componentIds: string[], skipCache: boolean = false): Promise<void> {
+    if (entities.length === 0 || componentIds.length === 0) return;
+
+    // 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
+        FROM components c
+        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 = entityMap.get(entity_id);  // O(1) instead of O(n)
+        if (entity) {
+            const ctor = ComponentRegistry.getConstructor(type_id);
+            if (ctor) {
+                const comp = new ctor();
+                const componentData = typeof data === 'string' ? JSON.parse(data) : data;
+                Object.assign(comp, componentData);
+                comp.id = id;
+                comp.setPersisted(true);
+                comp.setDirty(false);
+                addComponent(entity, comp);
+            }
+        }
+    }
+}
+
+/**
+ * Find an entity by its ID. Returning populated with all components. Or null if not found.
+ */
+export async function 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;
+}
+
+export function clone(entity: Entity): Entity {
+    const clone = new Entity();
+    clone.setDirty(true);
+    clone.setPersisted(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);
+        addComponent(clone, newComp);
+    }
+    return clone;
+}
+
+export function makeRef(entity: Entity): Entity {
+    const ref = new Entity();
+    ref.setDirty(true);
+    ref.setPersisted(false);
+    for (const comp of entity.components.values()) {
+        const refComp = comp;
+        refComp.setDirty(false);
+        refComp.setPersisted(true);
+        addComponent(ref, refComp);
+    }
+    return ref;
+}
+
+/**
+ * Serialize the entity with only the currently loaded components
+ */
+export function serialize(entity: Entity): { id: string; components: Record<string, any> } {
+    const components: Record<string, any> = {};
+    for (const comp of entity.components.values()) {
+        components[comp.constructor.name] = comp.serializableData();
+    }
+    return {
+        id: entity.id,
+        components
+    };
+}
+
+/**
+ * Deserialize/reconstitute an Entity from cached/serialized data.
+ */
+export function deserialize(data: any): Entity {
+    if (data instanceof Entity) {
+        return data;
+    }
+
+    const entity = new Entity(data.id);
+    entity.setPersisted(true);
+    entity.setDirty(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);
+            addComponent(entity, comp);
+        }
+    }
+
+    return entity;
+}

package/core/entity/pendingOps.ts

@@ -0,0 +1,72 @@
+// Drainable background-work tracking for Entity. Extracted from Entity.ts
+// (RFC_REFACTOR_TARGETS §3.2). Module-level state owns the Sets; Entity
+// keeps thin public static delegates for external callers.
+
+// Drainable set of fire-and-forget cache ops triggered from set/remove.
+// App.shutdown can await these to avoid losing writes mid-shutdown
+// (H-CACHE-1).
+const pendingCacheOps: Set<Promise<void>> = new Set();
+
+// Drainable set of post-commit side-effect Promises scheduled via
+// queueMicrotask from save(). Includes cache invalidation + lifecycle
+// hooks (EntityCreated / EntityUpdated). Hooks may transitively trigger
+// more DB work (e.g., entity.save() from a handler), which is why this
+// is tracked separately from pendingCacheOps. Tests running against
+// PGlite's single-connection pool should drain this between test files
+// to prevent background work from prior files queueing behind the
+// current file's save and masking visibility of recently-committed
+// rows. See BUNSANE-001.
+const pendingSideEffects: Set<Promise<void>> = new Set();
+
+/**
+ * Await all pending background cache operations. Call during shutdown
+ * after HTTP drain but before cache.disconnect so setImmediate'd cache
+ * writes are not lost. Bounded by `timeoutMs`.
+ */
+export async function drainPendingCacheOps(timeoutMs: number = 5_000): Promise<void> {
+    if (pendingCacheOps.size === 0) return;
+    const snapshot = [...pendingCacheOps];
+    const drainTimer = new Promise<'timeout'>((resolve) => {
+        const t = setTimeout(() => resolve('timeout'), timeoutMs);
+        t.unref?.();
+    });
+    await Promise.race([
+        Promise.allSettled(snapshot).then(() => 'drained' as const),
+        drainTimer,
+    ]);
+}
+
+/**
+ * Await all pending post-commit side effects (cache invalidation +
+ * lifecycle hooks scheduled via queueMicrotask from save()). Call from
+ * test setup/teardown hooks under PGlite to guarantee prior-file
+ * background work has settled before the next file's saves run. Bounded
+ * by `timeoutMs`. Safe to call repeatedly; no-op when the set is empty.
+ */
+export async function drainPendingSideEffects(timeoutMs: number = 5_000): Promise<void> {
+    if (pendingSideEffects.size === 0) return;
+    const snapshot = [...pendingSideEffects];
+    const drainTimer = new Promise<'timeout'>((resolve) => {
+        const t = setTimeout(() => resolve('timeout'), timeoutMs);
+        t.unref?.();
+    });
+    await Promise.race([
+        Promise.allSettled(snapshot).then(() => 'drained' as const),
+        drainTimer,
+    ]);
+}
+
+/**
+ * Track a fire-and-forget cache promise in the drainable set. Public so
+ * other framework read paths (e.g. Query.populateComponents cache
+ * warming) share the same drain semantics (H-CACHE-1).
+ */
+export function trackCacheOp(p: Promise<void>): void {
+    pendingCacheOps.add(p);
+    p.finally(() => pendingCacheOps.delete(p));
+}
+
+export function trackSideEffect(p: Promise<void>): void {
+    pendingSideEffects.add(p);
+    p.finally(() => pendingSideEffects.delete(p));
+}