bunsane 0.3.0 → 0.3.2

package/core/cache/CacheManager.ts

@@ -15,6 +15,16 @@ interface InvalidationMessage {
     pattern?: string;
 }
 
+/**
+ * Sentinel value written to the cache to record "known absent" lookups.
+ * String literal (not object) so it round-trips cleanly through
+ * JSON.stringify in RedisCache + CompressionUtils. Callers must treat it
+ * as a cache hit but propagate a `null`/`[]` upstream.
+ */
+export const COMPONENT_TOMBSTONE = '__TOMBSTONE__' as const;
+export const RELATION_TOMBSTONE = '__TOMBSTONE__' as const;
+export type ComponentCacheValue = ComponentData | typeof COMPONENT_TOMBSTONE;
+
 /**
  * High-level cache operations manager
  * Singleton that provides entity and component caching methods
@@ -284,6 +294,24 @@ export class CacheManager {
         }
     }
 
+    /**
+     * Invalidate cached state (entity + all components) for a batch of
+     * entity IDs. Call this after a raw-SQL write (db.unsafe) that bypasses
+     * Entity.set/save, so downstream reads observe fresh data instead of
+     * stale L1/L2 cache entries.
+     */
+    public async invalidateEntities(entityIds: string[]): Promise<void> {
+        if (!this.config.enabled || entityIds.length === 0) {
+            return;
+        }
+        await Promise.all(
+            entityIds.flatMap(id => [
+                this.invalidateEntity(id),
+                this.invalidateAllEntityComponents(id),
+            ])
+        );
+    }
+
     /**
      * Invalidate all components for a specific entity from cache
      * Uses pattern matching to efficiently clear all component caches for an entity
@@ -303,16 +331,18 @@ export class CacheManager {
     }
 
     /**
-     * Get components by entity and type from cache (for DataLoader integration)
+     * Get components by entity and type from cache (for DataLoader integration).
+     * Returns COMPONENT_TOMBSTONE for keys whose absence was previously
+     * recorded; callers must treat this as a hit and propagate null upstream.
      */
-    public async getComponents(keys: Array<{ entityId: string; typeId: string }>): Promise<(ComponentData | null)[]> {
+    public async getComponents(keys: Array<{ entityId: string; typeId: string }>): Promise<(ComponentCacheValue | null)[]> {
         if (!this.config.enabled || !this.config.component?.enabled) {
             return keys.map(() => null);
         }
 
         try {
             const cacheKeys = keys.map(k => `component:${k.entityId}:${k.typeId}`);
-            const results = await this.provider.getMany<ComponentData>(cacheKeys);
+            const results = await this.provider.getMany<ComponentCacheValue>(cacheKeys);
             return results;
         } catch (error) {
             logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error getting components from cache', error });
@@ -321,26 +351,131 @@ export class CacheManager {
     }
 
     /**
-     * Set components in cache with write-through strategy (for DataLoader integration)
+     * 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).
      */
-    public async setComponentsWriteThrough(components: ComponentData[], ttl?: number): Promise<void> {
+    public async setComponentsWriteThrough(
+        components: ComponentData[],
+        ttlOrRequested?: number | Array<{ entityId: string; typeId: string }>,
+        ttlIfRequested?: number,
+    ): Promise<void> {
         if (!this.config.enabled || !this.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 effectiveTTL = ttl ?? this.config.component?.ttl;
-            const entries = components.map(comp => ({
+            const componentTTL = ttl ?? this.config.component.ttl;
+            const entries: Array<{ key: string; value: ComponentCacheValue; ttl: number }> = components.map(comp => ({
                 key: `component:${comp.entityId}:${comp.typeId}`,
                 value: comp,
-                ttl: effectiveTTL
+                ttl: componentTTL,
             }));
-            await this.provider.setMany(entries);
+
+            const negativeEnabled = this.config.component.negativeCacheEnabled === true;
+            if (negativeEnabled && requestedKeys && requestedKeys.length > 0) {
+                const found = new Set(components.map(c => `${c.entityId}-${c.typeId}`));
+                const tombstoneTTL = this.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 this.provider.setMany(entries);
+            }
         } catch (error) {
             logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error setting components in cache', error });
         }
     }
 
+    // Relation negative-cache methods
+
+    /**
+     * Build the cache key for a relation tombstone. Null byte separator
+     * prevents collision when relationField contains hyphens or colons.
+     */
+    private static relationCacheKey(entityId: string, relationField: string, relatedType: string, foreignKey?: string): string {
+        const fk = foreignKey ?? '';
+        return `relation:${entityId}\x00${relationField}\x00${relatedType}\x00${fk}`;
+    }
+
+    /**
+     * Bulk-check relation tombstones. Returns true at index i when the
+     * relation at keys[i] was previously recorded as empty.
+     */
+    public async getRelationsEmpty(
+        keys: Array<{ entityId: string; relationField: string; relatedType: string; foreignKey?: string }>,
+    ): Promise<boolean[]> {
+        if (!this.config.enabled || !this.config.relation?.negativeCacheEnabled) {
+            return keys.map(() => false);
+        }
+        try {
+            const cacheKeys = keys.map(k => CacheManager.relationCacheKey(k.entityId, k.relationField, k.relatedType, k.foreignKey));
+            const values = await this.provider.getMany<string>(cacheKeys);
+            return values.map(v => v === RELATION_TOMBSTONE);
+        } catch (error) {
+            logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error getting relation tombstones', error });
+            return keys.map(() => false);
+        }
+    }
+
+    /**
+     * Record relation tombstones for keys whose query returned []. TTL
+     * defaults to relation.negativeCacheTtl (60s).
+     */
+    public async setRelationsEmpty(
+        keys: Array<{ entityId: string; relationField: string; relatedType: string; foreignKey?: string }>,
+        ttl?: number,
+    ): Promise<void> {
+        if (!this.config.enabled || !this.config.relation?.negativeCacheEnabled || keys.length === 0) {
+            return;
+        }
+        try {
+            const effectiveTTL = ttl ?? this.config.relation.negativeCacheTtl ?? 60_000;
+            const entries = keys.map(k => ({
+                key: CacheManager.relationCacheKey(k.entityId, k.relationField, k.relatedType, k.foreignKey),
+                value: RELATION_TOMBSTONE,
+                ttl: effectiveTTL,
+            }));
+            await this.provider.setMany(entries);
+        } catch (error) {
+            logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error setting relation tombstones', error });
+        }
+    }
+
+    /**
+     * Drop a relation tombstone. Call when a target component is created
+     * that may newly satisfy the relation. Pub/sub invalidation is wired
+     * identically to component invalidation.
+     */
+    public async invalidateRelation(entityId: string, relationField: string, relatedType: string, foreignKey?: string): Promise<void> {
+        if (!this.config.enabled || !this.config.relation?.negativeCacheEnabled) {
+            return;
+        }
+        try {
+            const key = CacheManager.relationCacheKey(entityId, relationField, relatedType, foreignKey);
+            await this.provider.delete(key);
+            await this.publishInvalidation('key', [key]);
+        } catch (error) {
+            logger.error({ scope: 'cache', component: 'CacheManager', msg: 'Error invalidating relation tombstone', error });
+        }
+    }
+
     // Generic cache methods
 
     /**

package/core/components/BaseComponent.ts

@@ -55,8 +55,18 @@ export class BaseComponent {
         this.properties().forEach((prop: string) => {
             let value = (this as any)[prop];
             const propMeta = props?.find(p => p.propertyKey === prop);
-            if (propMeta?.propertyType === Date && value instanceof Date) {
-                value = value.toISOString();
+            if (value !== null && value !== undefined) {
+                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}`);
+                    }
+                    if (Number.isNaN(value.getTime())) {
+                        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)) {
+                    throw new Error(`Invalid number for property '${prop}' on component '${this._comp_name}': ${value}`);
+                }
             }
             data[prop] = value;
         });

package/core/middleware/AccessLog.ts

@@ -1,6 +1,7 @@
 import type { Middleware } from '../Middleware';
 import { logger as MainLogger } from '../Logger';
 import { getRequestId } from './RequestId';
+import type { RequestStats } from '../RequestContext';
 
 const logger = MainLogger.child({ scope: 'HTTP' });
 
@@ -37,7 +38,8 @@ export function accessLog(options: AccessLogOptions = {}): Middleware {
         }
 
         const duration = Math.round(performance.now() - start);
-        const logData = {
+        const stats = (req as any).__bunsaneStats as RequestStats | undefined;
+        const logData: Record<string, any> = {
             requestId: getRequestId(),
             method: req.method,
             path: url.pathname,
@@ -45,6 +47,11 @@ export function accessLog(options: AccessLogOptions = {}): Middleware {
             duration,
             msg: `${req.method} ${url.pathname} ${response.status} ${duration}ms`,
         };
+        if (stats) {
+            logData.operationName = stats.operationName;
+            logData.dataLoaderCalls = stats.dataLoaderCalls;
+            logData.dbQueryCount = stats.dbQueryCount;
+        }
 
         if (response.status >= 500) {
             logger.error(logData);

package/database/PreparedStatementCache.ts

@@ -1,4 +1,5 @@
 import { logger } from "../core/Logger";
+import { timedUnsafe, type PerRequestCounters } from "./instrumentedDb";
 
 export interface CacheEntry {
     sql: string;
@@ -108,23 +109,23 @@ export class PreparedStatementCache {
     }
 
     /**
-     * Execute a prepared statement with parameters
+     * Execute a prepared statement with parameters. Routes through
+     * `timedUnsafe` so the call is timed and (when a signal is supplied)
+     * cancellable via Bun's `Query.cancel()` on abort.
      */
-    public async execute(statement: any, params: any[], db: any): Promise<any[]> {
-        // Validate params to catch empty strings that would cause UUID parsing errors
-        for (let i = 0; i < params.length; i++) {
-            const param = params[i];
-            if (param === '' || (typeof param === 'string' && param.trim() === '')) {
-                logger.error(`[PreparedStatementCache] Empty string parameter at position ${i + 1}`);
-                logger.error(`[PreparedStatementCache] SQL: ${statement.sql}`);
-                logger.error(`[PreparedStatementCache] All params: ${JSON.stringify(params)}`);
-                throw new Error(`PreparedStatementCache.execute: Parameter $${i + 1} is an empty string. SQL: ${statement.sql.substring(0, 100)}...`);
-            }
-        }
-        
-        // For Bun's SQL, we still use db.unsafe() but with the prepared statement concept
-        // In a real implementation, this might use a prepared statement pool
-        return await db.unsafe(statement.sql, params);
+    public async execute(
+        statement: any,
+        params: any[],
+        db: any,
+        signal?: AbortSignal,
+        perRequest?: PerRequestCounters,
+    ): Promise<any[]> {
+        // Empty-string params are legitimate for text-field filters
+        // (`c.data->>'field' = ''`). UUID-typed params never reach this
+        // point empty — callers (Query.findById etc.) guard at entry. PG
+        // emits a clear error at execution time if a UUID cast meets an
+        // empty string.
+        return await timedUnsafe<any[]>(db, statement.sql, params, signal, perRequest);
     }
 
     /**

package/database/cancellable.ts

@@ -0,0 +1,22 @@
+/**
+ * Wraps a Bun SQL Query so an AbortSignal can cancel the in-flight query
+ * via the underlying `query.cancel()` method. When the signal fires the
+ * server-side query receives a cancel request, the awaited promise rejects,
+ * any enclosing transaction triggers 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.
+ */
+export async function runWithSignal<T>(q: any, signal?: AbortSignal): Promise<T> {
+    if (!signal) return await q;
+    if (signal.aborted) {
+        try { q.cancel?.(); } catch { /* ignore */ }
+        throw signal.reason ?? new Error('Query aborted');
+    }
+    const onAbort = () => { try { q.cancel?.(); } catch { /* ignore */ } };
+    signal.addEventListener('abort', onAbort, { once: true });
+    try {
+        return await q;
+    } finally {
+        signal.removeEventListener('abort', onAbort);
+    }
+}

package/database/instrumentedDb.ts

@@ -0,0 +1,141 @@
+import type { SQL } from "bun";
+import { logger as MainLogger } from "../core/Logger";
+import { runWithSignal } from "./cancellable";
+
+const logger = MainLogger.child({ scope: "db" });
+
+const SLOW_MS = parseInt(process.env.BUNSANE_DB_SLOW_MS ?? '500', 10);
+
+export type DataLoaderKind = 'entity' | 'component' | 'relation';
+
+interface DbStatsInternal {
+    totalCount: number;
+    totalMs: number;
+    maxMs: number;
+    slowCount: number;
+    abortedCount: number;
+    inFlight: number;
+    inFlightMax: number;
+    dataLoaderCalls: { entity: number; component: number; relation: number };
+}
+
+const stats: DbStatsInternal = {
+    totalCount: 0,
+    totalMs: 0,
+    maxMs: 0,
+    slowCount: 0,
+    abortedCount: 0,
+    inFlight: 0,
+    inFlightMax: 0,
+    dataLoaderCalls: { entity: 0, component: 0, relation: 0 },
+};
+
+/**
+ * Per-request counter incremented when current request context is reachable
+ * via the (request as any).__bunsaneStats pointer. We accept that as a
+ * parameter from the call site so this module stays free of GraphQL imports.
+ */
+export interface PerRequestCounters {
+    dbQueryCount: number;
+}
+
+/**
+ * Execute `db.unsafe(sql, params)` with optional AbortSignal cancellation
+ * and roundtrip telemetry. On abort the in-flight query is cancelled via
+ * `Query.cancel()`. Total ms is recorded into module-level stats; calls
+ * over `BUNSANE_DB_SLOW_MS` increment slowCount and emit a warn log.
+ */
+export async function timedUnsafe<T = any>(
+    db: SQL,
+    sql: string,
+    params: any[],
+    signal?: AbortSignal,
+    perRequest?: PerRequestCounters,
+): Promise<T> {
+    const t0 = performance.now();
+    stats.inFlight++;
+    if (stats.inFlight > stats.inFlightMax) stats.inFlightMax = stats.inFlight;
+    if (perRequest) perRequest.dbQueryCount++;
+    let aborted = false;
+    try {
+        const q = (db as any).unsafe(sql, params);
+        return await runWithSignal<T>(q, signal);
+    } catch (err) {
+        if ((err as Error)?.name === 'AbortError' || signal?.aborted) {
+            aborted = true;
+            stats.abortedCount++;
+        }
+        throw err;
+    } finally {
+        const dt = performance.now() - t0;
+        stats.inFlight--;
+        stats.totalCount++;
+        stats.totalMs += dt;
+        if (dt > stats.maxMs) stats.maxMs = dt;
+        if (SLOW_MS > 0 && dt > SLOW_MS && !aborted) {
+            stats.slowCount++;
+            logger.warn(
+                {
+                    durationMs: Math.round(dt),
+                    thresholdMs: SLOW_MS,
+                    sqlSnippet: sql.length > 200 ? sql.slice(0, 200) + '…' : sql,
+                    msg: 'Slow DB call',
+                },
+                'Slow DB call',
+            );
+        }
+    }
+}
+
+/**
+ * Increment the per-kind DataLoader counter. Called from inside DataLoader
+ * batch functions so /metrics + access log can attribute load patterns.
+ *
+ * `perRequest` is loosely typed because RequestContext's `RequestStats`
+ * (defined in core/RequestContext.ts) extends `PerRequestCounters` with
+ * extra fields like `dataLoaderCalls`. We accept either shape here without
+ * importing the higher-level type (which would create a cycle).
+ */
+export function incrementDataLoaderCall(
+    kind: DataLoaderKind,
+    perRequest?: PerRequestCounters | { dataLoaderCalls?: { entity: number; component: number; relation: number } },
+): void {
+    stats.dataLoaderCalls[kind]++;
+    const dlc = (perRequest as any)?.dataLoaderCalls;
+    if (dlc) dlc[kind]++;
+}
+
+/**
+ * Snapshot of accumulated DB stats for the /metrics endpoint.
+ */
+export function getDbStats() {
+    const avgMs = stats.totalCount > 0 ? stats.totalMs / stats.totalCount : 0;
+    return {
+        totalCount: stats.totalCount,
+        totalMs: Math.round(stats.totalMs),
+        maxMs: Math.round(stats.maxMs),
+        avgMs: Number(avgMs.toFixed(2)),
+        slowCount: stats.slowCount,
+        abortedCount: stats.abortedCount,
+        inFlight: stats.inFlight,
+        inFlightMax: stats.inFlightMax,
+        slowThresholdMs: SLOW_MS,
+        dataLoaderCalls: { ...stats.dataLoaderCalls },
+    };
+}
+
+/**
+ * Reset counters. Intended for tests only.
+ */
+export function resetDbStats(): void {
+    stats.totalCount = 0;
+    stats.totalMs = 0;
+    stats.maxMs = 0;
+    stats.slowCount = 0;
+    stats.abortedCount = 0;
+    stats.inFlight = 0;
+    stats.inFlightMax = 0;
+    stats.dataLoaderCalls.entity = 0;
+    stats.dataLoaderCalls.component = 0;
+    stats.dataLoaderCalls.relation = 0;
+}