bunsane 0.3.0 → 0.3.2

package/core/Entity.ts

@@ -1,6 +1,7 @@
 import type { ComponentDataType, ComponentGetter, BaseComponent } from "./components";
 import { logger } from "./Logger";
 import db, { QUERY_TIMEOUT_MS } from "../database";
+import { runWithSignal } from "../database/cancellable";
 import EntityManager from "./EntityManager";
 import ComponentRegistry from "./components/ComponentRegistry";
 import { uuidv7 } from "../utils/uuid";
@@ -27,6 +28,17 @@ export class Entity implements IEntity {
     // (H-CACHE-1).
     private static 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.
+    private static 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
@@ -45,11 +57,36 @@ export class Entity implements IEntity {
         ]);
     }
 
+    /**
+     * 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.
+     */
+    public static async drainPendingSideEffects(timeoutMs: number = 5_000): Promise<void> {
+        if (Entity.pendingSideEffects.size === 0) return;
+        const snapshot = [...Entity.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,
+        ]);
+    }
+
     private static trackCacheOp(p: Promise<void>): void {
         Entity.pendingCacheOps.add(p);
         p.finally(() => Entity.pendingCacheOps.delete(p));
     }
 
+    private static trackSideEffect(p: Promise<void>): void {
+        Entity.pendingSideEffects.add(p);
+        p.finally(() => Entity.pendingSideEffects.delete(p));
+    }
+
     constructor(id?: string) {
         // Use || instead of ?? to also handle empty strings
         this.id = (id && id.trim() !== '') ? id : uuidv7();
@@ -348,6 +385,81 @@ export class Entity implements IEntity {
         return this._loadComponent(ctor, context);
     }
 
+    /**
+     * Discard in-memory component state and re-hydrate from the database.
+     * Preserves entity identity — callers holding a reference see fresh data
+     * on the same instance. Use after a raw-SQL write that bypassed
+     * `entity.set`/`entity.save`, or when a different `Entity` instance with
+     * the same id mutated persisted data.
+     *
+     * @param opts Optional transaction
+     */
+    public async reload(opts?: { trx?: SQL }): Promise<this> {
+        if (!this.id || this.id.trim() === '') {
+            return this;
+        }
+        this.components.clear();
+        this.removedComponents.clear();
+        this.savedRemovedComponents.clear();
+
+        const dbConn = opts?.trx ?? db;
+        const rows = await dbConn`
+            SELECT c.id, c.type_id, c.data
+            FROM components c
+            WHERE c.entity_id = ${this.id} AND c.deleted_at IS NULL
+        `;
+
+        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);
+            this.addComponent(comp);
+        }
+
+        this.setPersisted(true);
+        this.setDirty(false);
+        return this;
+    }
+
+    /**
+     * Ensure the given components are hydrated on this entity's in-memory
+     * componentList. No-op for components already loaded. Batched: one SQL
+     * call for all missing components.
+     *
+     * Required when a later `entity.set(...)` + `entity.save()` may trigger
+     * a `@ComponentTargetHook` whose `includeComponents` lists tag
+     * components. Hook matching reads `componentList()` (in-memory only), so
+     * tags must be loaded first for the hook to fire.
+     *
+     * @param ctors Component constructors to ensure are loaded
+     */
+    public async requireComponents(ctors: Array<new (...args: any[]) => BaseComponent>): Promise<void> {
+        if (ctors.length === 0) return;
+        const missing: string[] = [];
+        for (const ctor of ctors) {
+            const existing = Array.from(this.components.values()).find(c => c instanceof ctor);
+            if (existing) continue;
+            const typeId = new ctor().getTypeID();
+            missing.push(typeId);
+        }
+        if (missing.length === 0) return;
+        await Entity.LoadComponents([this], missing);
+    }
+
     private async _loadComponent<T extends BaseComponent>(ctor: new (...args: any[]) => T, context?: { loaders?: { componentsByEntityType?: any }; trx?: SQL }): Promise<T | null> {
         const comp = Array.from(this.components.values()).find(comp => comp instanceof ctor) as T | undefined;
         if (typeof comp !== "undefined") {
@@ -465,14 +577,21 @@ export class Entity implements IEntity {
 
             // Post-commit side effects are fire-and-forget so Redis / hook
             // latency cannot consume the save budget or block the caller.
-            queueMicrotask(() => this.runPostCommitSideEffects(
-                wasNew,
-                changedComponentTypeIds,
-                removedComponentTypeIds,
-                context,
-                profile ? phases : undefined,
-                profile ? phaseStart : undefined,
-            ));
+            // Tracked in pendingSideEffects so tests/shutdown can drain
+            // background work before asserting or tearing down.
+            const sideEffectPromise = new Promise<void>((resolve) => {
+                queueMicrotask(() => {
+                    this.runPostCommitSideEffects(
+                        wasNew,
+                        changedComponentTypeIds,
+                        removedComponentTypeIds,
+                        context,
+                        profile ? phases : undefined,
+                        profile ? phaseStart : undefined,
+                    ).finally(() => resolve());
+                });
+            });
+            Entity.trackSideEffect(sideEffectPromise);
 
             return true;
         } catch (error) {
@@ -645,26 +764,14 @@ export class Entity implements IEntity {
             return true;
         }
 
-        // Execute a Bun SQL query with AbortSignal support. On abort, the
-        // in-flight query is cancelled (SQL.Query.cancel()) which causes the
-        // transaction callback to throw, triggering Bun's automatic ROLLBACK
-        // and releasing the pooled backend connection. Without this, a wall-
-        // clock timeout leaks backends into `idle in transaction` state —
-        // fatal under pgbouncer transaction-mode pooling.
-        const run = async <T>(q: any): Promise<T> => {
-            if (!signal) return await q;
-            if (signal.aborted) {
-                try { q.cancel?.(); } catch { /* ignore */ }
-                throw signal.reason ?? new Error('Entity.save aborted');
-            }
-            const onAbort = () => { try { q.cancel?.(); } catch { /* ignore */ } };
-            signal.addEventListener('abort', onAbort, { once: true });
-            try {
-                return await q;
-            } finally {
-                signal.removeEventListener('abort', onAbort);
-            }
-        };
+        // Cancellation goes through the shared `runWithSignal` helper so
+        // every db.unsafe / trx`...` callsite in the framework uses the same
+        // pattern: on abort the in-flight Bun SQL Query is cancelled, the
+        // transaction callback throws, Bun emits ROLLBACK, and the pooled
+        // backend connection is released. Without this a wall-clock timeout
+        // leaks the backend into `idle in transaction` under pgbouncer
+        // transaction-mode pooling.
+        const run = <T>(q: any): Promise<T> => runWithSignal<T>(q, signal);
 
         const executeSave = async (saveTrx: SQL) => {
             if (!this._persisted) {
@@ -799,19 +906,7 @@ export class Entity implements IEntity {
         }, timeoutMs);
 
         const signal = controller.signal;
-        const run = async <T>(q: any): Promise<T> => {
-            if (signal.aborted) {
-                try { q.cancel?.(); } catch { /* ignore */ }
-                throw signal.reason ?? new Error('Entity.doDelete aborted');
-            }
-            const onAbort = () => { try { q.cancel?.(); } catch { /* ignore */ } };
-            signal.addEventListener('abort', onAbort, { once: true });
-            try {
-                return await q;
-            } finally {
-                signal.removeEventListener('abort', onAbort);
-            }
-        };
+        const run = <T>(q: any): Promise<T> => runWithSignal<T>(q, signal);
 
         try {
             await db.transaction(async (trx) => {

package/core/RequestContext.ts

@@ -1,36 +1,85 @@
-import type { Plugin } from 'graphql-yoga';
-import { createRequestLoaders } from './RequestLoaders';
-import type { RequestLoaders } from './RequestLoaders';
-import db from '../database';
-import { CacheManager } from './cache/CacheManager';
-import { getRequestId } from './middleware/RequestId';
-
-declare module 'graphql-yoga' {
-  interface Context {
-    // 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();
-      // Mount loaders at context.loaders to match ArcheType.ts resolver access pattern
-      (args as any).contextValue.loaders = createRequestLoaders(db, cacheManager);
-      // Prefer the HTTP-layer request id (from requestId() middleware's
-      // AsyncLocalStorage) so access log + GraphQL logs share the same id.
-      (args as any).contextValue.requestId = getRequestId() ?? crypto.randomUUID();
-      (args as any).contextValue.cacheManager = cacheManager;
-    },
-  };
-}
+import type { Plugin } from 'graphql-yoga';
+import { createRequestLoaders } from './RequestLoaders';
+import type { RequestLoaders } from './RequestLoaders';
+import db from '../database';
+import { CacheManager } from './cache/CacheManager';
+import { getRequestId } from './middleware/RequestId';
+
+export interface RequestStats {
+  operationName: string;
+  dataLoaderCalls: { entity: number; component: number; relation: number };
+  dbQueryCount: number;
+  startTime: number;
+}
+
+declare module 'graphql-yoga' {
+  interface Context {
+    // Loaders mounted at top-level context for ArcheType resolver access
+    loaders: RequestLoaders;
+    requestId: string;
+    cacheManager: CacheManager;
+    requestStats: RequestStats;
+    signal?: AbortSignal;
+  }
+}
+
+/**
+ * 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.
+ *
+ * Also threads the request `AbortSignal` into Query/DataLoader DB calls so
+ * the framework's wall-clock timeout (handled in core/app/requestRouter.ts)
+ * cancels in-flight Postgres queries via Bun's `Query.cancel()`. Without
+ * this, an aborted request leaks its backend connection into
+ * `idle in transaction` under pgbouncer transaction-mode pooling.
+ *
+ * Captures per-request stats (operationName, DataLoader call counts,
+ * dbQueryCount) and attaches them to the underlying Request via
+ * `__bunsaneStats` so the HTTP router's catch handler + AccessLog
+ * middleware can read them after the GraphQL pipeline rejects.
+ */
+export function createRequestContextPlugin(): Plugin {
+  return {
+    onExecute: ({ args }) => {
+      const cacheManager = CacheManager.getInstance();
+      const ctx: any = (args as any).contextValue;
+      const request: Request | undefined = ctx?.request;
+      const signal: AbortSignal | undefined = request?.signal;
+
+      // GraphQL operation name. Falls back to first named operation in the
+      // document, or 'anonymous' if the client supplied an inline query
+      // with no name.
+      const operationName: string =
+        (typeof args.operationName === 'string' && args.operationName)
+        || (args.document?.definitions?.find?.(
+              (d: any) => d?.kind === 'OperationDefinition' && d?.name?.value,
+           ) as any)?.name?.value
+        || 'anonymous';
+
+      const stats: RequestStats = {
+        operationName,
+        dataLoaderCalls: { entity: 0, component: 0, relation: 0 },
+        dbQueryCount: 0,
+        startTime: performance.now(),
+      };
+
+      // Mount loaders at context.loaders to match ArcheType.ts resolver access pattern.
+      ctx.loaders = createRequestLoaders(db, cacheManager, signal, stats);
+      // Prefer the HTTP-layer request id (from requestId() middleware's
+      // AsyncLocalStorage) so access log + GraphQL logs share the same id.
+      ctx.requestId = getRequestId() ?? crypto.randomUUID();
+      ctx.cacheManager = cacheManager;
+      ctx.requestStats = stats;
+      ctx.signal = signal;
+
+      // Attach to the raw Request so the HTTP router catch block + access
+      // log middleware can read stats after Yoga rejects.
+      if (request) {
+        (request as any).__bunsaneStats = stats;
+      }
+    },
+  };
+}

package/core/RequestLoaders.ts

@@ -2,10 +2,12 @@ import DataLoader from 'dataloader';
 import { Entity } from './Entity';
 import db from '../database';
 import { inList } from '../database/sqlHelpers';
+import { timedUnsafe, incrementDataLoaderCall, type PerRequestCounters } from '../database/instrumentedDb';
 import {logger as MainLogger} from './Logger';
 const logger = MainLogger.child({ module: 'RequestLoaders' });
 import { getMetadataStorage } from './metadata';
 import type { CacheManager } from './cache/CacheManager';
+import { COMPONENT_TOMBSTONE } from './cache/CacheManager';
 
 export type ComponentData = {
   id: string;  // Component ID for updates
@@ -23,8 +25,14 @@ export type RequestLoaders = {
   relationsByEntityField: DataLoader<{ entityId: string; relationField: string; relatedType: string; foreignKey?: string }, Entity[]>;
 };
 
-export function createRequestLoaders(db: any, cacheManager?: CacheManager): RequestLoaders {
+export function createRequestLoaders(
+  db: any,
+  cacheManager?: CacheManager,
+  signal?: AbortSignal,
+  perRequest?: PerRequestCounters,
+): RequestLoaders {
   const entityById = new DataLoader<string, Entity | null>(async (ids: readonly string[]) => {
+    incrementDataLoaderCall('entity', perRequest);
     const startTime = Date.now();
     try {
       // Filter out empty/invalid IDs to prevent PostgreSQL UUID parsing errors
@@ -44,12 +52,12 @@ export function createRequestLoaders(db: any, cacheManager?: CacheManager): Requ
       
       if (missingIds.length > 0) {
         const idList = inList(missingIds, 1);
-        const rows = await db.unsafe(`
+        const rows = await timedUnsafe<any[]>(db, `
           SELECT id
           FROM entities
           WHERE id IN ${idList.sql}
             AND deleted_at IS NULL
-        `, idList.params);
+        `, idList.params, signal, perRequest);
         
         const entities = rows.map((row: any) => {
           const entity = new Entity(row.id);
@@ -89,6 +97,7 @@ export function createRequestLoaders(db: any, cacheManager?: CacheManager): Requ
 
   const componentsByEntityType = new DataLoader<{ entityId: string; typeId: string }, ComponentData | null>(
     async (keys: readonly { entityId: string; typeId: string }[]) => {
+      incrementDataLoaderCall('component', perRequest);
       const startTime = Date.now();
       try {
         // Filter out keys with empty/invalid entity IDs to prevent PostgreSQL UUID parsing errors
@@ -99,16 +108,20 @@ export function createRequestLoaders(db: any, cacheManager?: CacheManager): Requ
 
         const results = new Map<string, ComponentData | null>();
 
-        // Check cache first if cache manager is available
+        // Check cache first if cache manager is available. Tombstone hits
+        // are recorded as null in `results` so the DB-fetch step skips them.
         let cacheHits = 0;
         let cacheMisses = 0;
         if (cacheManager && cacheManager.getConfig().enabled && cacheManager.getConfig().component?.enabled) {
           try {
             const cachedComponents = await cacheManager.getComponents(validKeys);
-            cachedComponents.forEach((component, index) => {
-              if (component) {
-                const key = `${validKeys[index]!.entityId}-${validKeys[index]!.typeId}`;
-                results.set(key, component);
+            cachedComponents.forEach((value, index) => {
+              const key = `${validKeys[index]!.entityId}-${validKeys[index]!.typeId}`;
+              if (value === COMPONENT_TOMBSTONE) {
+                results.set(key, null);
+                cacheHits++;
+              } else if (value) {
+                results.set(key, value);
                 cacheHits++;
               } else {
                 cacheMisses++;
@@ -122,17 +135,16 @@ export function createRequestLoaders(db: any, cacheManager?: CacheManager): Requ
           cacheMisses += validKeys.length;
         }
 
-        // Log cache hit/miss rates for monitoring
         if (validKeys.length > 0) {
           const hitRate = (cacheHits / validKeys.length) * 100;
-          logger.debug({ 
-            scope: 'cache', 
-            component: 'RequestLoaders', 
-            msg: 'Component cache statistics', 
-            total: validKeys.length, 
-            hits: cacheHits, 
-            misses: cacheMisses, 
-            hitRate: `${hitRate.toFixed(1)}%` 
+          logger.trace({
+            scope: 'cache',
+            component: 'RequestLoaders',
+            msg: 'Component cache statistics',
+            total: validKeys.length,
+            hits: cacheHits,
+            misses: cacheMisses,
+            hitRate: `${hitRate.toFixed(1)}%`,
           });
         }
 
@@ -144,13 +156,13 @@ export function createRequestLoaders(db: any, cacheManager?: CacheManager): Requ
           const typeIds = [...new Set(missingKeys.map(k => k.typeId))];
           const entityIdList = inList(entityIds, 1);
           const typeIdList = inList(typeIds, entityIdList.newParamIndex);
-          const rows = await db.unsafe(`
+          const rows = await timedUnsafe<any[]>(db, `
             SELECT id, entity_id, type_id, data, created_at, updated_at, deleted_at
             FROM components
             WHERE entity_id IN ${entityIdList.sql}
               AND type_id IN ${typeIdList.sql}
               AND deleted_at IS NULL
-          `, [...entityIdList.params, ...typeIdList.params]);
+          `, [...entityIdList.params, ...typeIdList.params], signal, perRequest);
           
           const components: ComponentData[] = rows.map((row: any) => ({
             id: row.id,
@@ -162,10 +174,15 @@ export function createRequestLoaders(db: any, cacheManager?: CacheManager): Requ
             deletedAt: row.deleted_at,
           }));
 
-          // Cache the loaded components if cache is enabled
+          // Cache the loaded components + tombstone any requested keys whose
+          // row was absent (single setMany — see CacheManager.setComponentsWriteThrough).
           if (cacheManager && cacheManager.getConfig().enabled && cacheManager.getConfig().component?.enabled) {
             try {
-              await cacheManager.setComponentsWriteThrough(components, cacheManager.getConfig().component!.ttl);
+              await cacheManager.setComponentsWriteThrough(
+                components,
+                missingKeys,
+                cacheManager.getConfig().component!.ttl,
+              );
             } catch (error: any) {
               logger.warn({ scope: 'cache', component: 'RequestLoaders', msg: 'Cache write failed for components', error });
             }
@@ -199,6 +216,7 @@ export function createRequestLoaders(db: any, cacheManager?: CacheManager): Requ
 
   const relationsByEntityField = new DataLoader<{ entityId: string; relationField: string; relatedType: string; foreignKey?: string }, Entity[]>(
     async (keys: readonly { entityId: string; relationField: string; relatedType: string; foreignKey?: string }[]) => {
+      incrementDataLoaderCall('relation', perRequest);
       const startTime = Date.now();
       try {
         // Filter valid keys
@@ -207,9 +225,35 @@ export function createRequestLoaders(db: any, cacheManager?: CacheManager): Requ
           return keys.map(() => []);
         }
 
+        const resultMap = new Map<string, Entity[]>();
+
+        // Negative-cache lookup: skip DB for keys recorded as empty.
+        let keysToQuery = validKeys;
+        const relCacheEnabled = !!(cacheManager
+          && cacheManager.getConfig().enabled
+          && cacheManager.getConfig().relation?.negativeCacheEnabled);
+        if (relCacheEnabled) {
+          try {
+            const tombstones = await cacheManager!.getRelationsEmpty(validKeys);
+            const remaining: typeof validKeys = [];
+            tombstones.forEach((isEmpty, i) => {
+              const k = validKeys[i]!;
+              if (isEmpty) {
+                const mapKey = `${k.entityId}\x00${k.relationField}\x00${k.relatedType}`;
+                resultMap.set(mapKey, []);
+              } else {
+                remaining.push(k);
+              }
+            });
+            keysToQuery = remaining;
+          } catch (error) {
+            logger.warn({ scope: 'cache', component: 'RequestLoaders', msg: 'Cache read failed for relation tombstones', error });
+          }
+        }
+
         // Group keys by foreign key for efficient batching
-        const keysByForeignKey = new Map<string, typeof validKeys>();
-        for (const key of validKeys) {
+        const keysByForeignKey = new Map<string, typeof keysToQuery>();
+        for (const key of keysToQuery) {
           const fk = key.foreignKey || 'default';
           if (!keysByForeignKey.has(fk)) {
             keysByForeignKey.set(fk, []);
@@ -217,8 +261,6 @@ export function createRequestLoaders(db: any, cacheManager?: CacheManager): Requ
           keysByForeignKey.get(fk)!.push(key);
         }
 
-        const resultMap = new Map<string, Entity[]>();
-
         // OPTIMIZED: Batch query for each foreign key type (instead of N separate queries)
         for (const [foreignKey, groupedKeys] of keysByForeignKey) {
           const entityIds = [...new Set(groupedKeys.map(k => k.entityId))];
@@ -240,19 +282,19 @@ export function createRequestLoaders(db: any, cacheManager?: CacheManager): Requ
           logger.trace(`[RelationLoader] Batched query for ${groupedKeys.length} keys with foreign key ${foreignKey}`);
 
           // SINGLE BATCHED QUERY for all entities in this group
-          const rows = await db.unsafe(`
-            SELECT DISTINCT 
-              c.entity_id, 
-              c.data, 
+          const rows = await timedUnsafe<any[]>(db, `
+            SELECT DISTINCT
+              c.entity_id,
+              c.data,
               c.type_id,
               c.data->>'${foreignKeyField}' as fk_value,
               COALESCE(c.data->>'user_id', c.data->>'parent_id') as fallback_fk_value
             FROM components c
             INNER JOIN entities e ON c.entity_id = e.id
-            WHERE e.deleted_at IS NULL 
+            WHERE e.deleted_at IS NULL
               AND c.deleted_at IS NULL
               AND ${whereClause}
-          `, [entityIds]);
+          `, [entityIds], signal, perRequest);
 
           logger.trace(`[RelationLoader] Found ${rows.length} total components for ${entityIds.length} entities`);
 
@@ -281,6 +323,22 @@ export function createRequestLoaders(db: any, cacheManager?: CacheManager): Requ
           }
         }
 
+        // Write tombstones for queried keys whose result was empty.
+        if (relCacheEnabled && keysToQuery.length > 0) {
+          const emptyKeys = keysToQuery.filter(k => {
+            const mapKey = `${k.entityId}\x00${k.relationField}\x00${k.relatedType}`;
+            const r = resultMap.get(mapKey);
+            return !r || r.length === 0;
+          });
+          if (emptyKeys.length > 0) {
+            try {
+              await cacheManager!.setRelationsEmpty(emptyKeys);
+            } catch (error) {
+              logger.warn({ scope: 'cache', component: 'RequestLoaders', msg: 'Cache write failed for relation tombstones', error });
+            }
+          }
+        }
+
         const duration = Date.now() - startTime;
         if (duration > 1000) {
           logger.warn(`Slow relationsByEntityField query: ${duration}ms for ${keys.length} keys`);

package/core/SchedulerManager.ts

@@ -109,12 +109,10 @@ export class SchedulerManager {
             throw error;
         }
 
-        // Validate query configuration
-        if (!taskInfo.options?.query && !taskInfo.options?.componentTarget && !taskInfo.componentTarget) {
-            const error = new Error(`Invalid task info: must provide either query function, componentTarget config, or legacy componentTarget`);
-            loggerInstance.error(`Failed to register task: ${error.message}`);
-            throw error;
-        }
+        // Time-based tasks (no query, no componentTarget) are allowed — they
+        // invoke the handler with no entity arguments on each tick. Useful
+        // for external polling, stats aggregation, or ad-hoc queries inside
+        // the callback.
 
         if (!taskInfo.service) {
             const error = new Error(`Task ${taskInfo.id} has no service instance`);
@@ -395,7 +393,7 @@ export class SchedulerManager {
         try {
             // Create query based on targeting configuration
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            let query: Query<any>;
+            let query: Query<any> | null = null;
 
             if (taskInfo.options?.query) {
                 // Use custom query function (preferred approach)
@@ -407,16 +405,16 @@ export class SchedulerManager {
             } else if (taskInfo.componentTarget) {
                 // Use legacy single component targeting (deprecated - use query instead)
                 query = new Query().with(taskInfo.componentTarget);
-            } else {
-                throw new Error('No query function or component target specified');
             }
+            // else: time-based task — no entity selection. Handler invoked
+            // with no arguments on each tick.
 
             // Apply entity limit if specified (can be used with query function)
-            if (taskInfo.options?.maxEntitiesPerExecution) {
+            if (query && taskInfo.options?.maxEntitiesPerExecution) {
                 query.take(taskInfo.options.maxEntitiesPerExecution);
             }
 
-            const entities = await query.exec();
+            const entities = query ? await query.exec() : [];
 
             // Execute the scheduled method with the entities array
             const method = taskInfo.service[taskInfo.methodName];
@@ -424,9 +422,11 @@ export class SchedulerManager {
                 throw new Error(`Method ${taskInfo.methodName} not found on service`);
             }
 
-            // Execute with timeout
+            // Execute with timeout. Time-based tasks receive no entity arg.
             const result = await this.executeWithTimeout(
-                method.call(taskInfo.service, entities),
+                query
+                    ? method.call(taskInfo.service, entities)
+                    : method.call(taskInfo.service),
                 timeout,
                 taskInfo
             );