@memberjunction/server 5.25.0 → 5.26.0

package/src/config.ts

@@ -192,6 +192,19 @@ const serverExtensionSchema = z.object({
   Settings: z.record(z.unknown()).default({})
 }).passthrough();
 
+const cacheSettingsSchema = z.object({
+  /** Maximum total estimated memory for all cached results in MB. Default: 150. Set to 0 to disable memory-based eviction. */
+  maxMemoryMB: z.number().optional().default(150),
+  /** Maximum percentage of total cache memory that any single entity can occupy. Default: 50. Set to 0 to disable. */
+  maxPercentOfCachePerEntity: z.number().optional().default(50),
+  /** Default TTL in seconds. 0 = no TTL, rely on event-based invalidation. Default: 0. */
+  defaultTTLSeconds: z.number().optional().default(0),
+  /** Interval in seconds for periodic eviction sweep. 0 = disabled. Default: 300 (5 minutes). */
+  evictionSweepIntervalSeconds: z.number().optional().default(300),
+  /** Enable verbose cache logging (hits, misses, evictions). Default: false. */
+  verboseLogging: z.boolean().optional().default(false),
+});
+
 const configInfoSchema = z.object({
   userHandling: userHandlingInfoSchema,
   databaseSettings: databaseSettingsInfoSchema,
@@ -206,6 +219,7 @@ const configInfoSchema = z.object({
   queryDialects: queryDialectSchema.optional().default({}),
   multiTenancy: multiTenancySchema.optional().default({}),
   serverExtensions: z.array(serverExtensionSchema).optional().default([]),
+  cacheSettings: cacheSettingsSchema.optional().default({}),
 
   apiKey: z.string().optional(),
   baseUrl: z.string().default('http://localhost'),
@@ -252,6 +266,7 @@ export type TelemetryConfig = z.infer<typeof telemetrySchema>;
 export type QueryDialectConfig = z.infer<typeof queryDialectSchema>;
 export type MultiTenancyConfig = z.infer<typeof multiTenancySchema>;
 export type ServerExtensionConfig = z.infer<typeof serverExtensionSchema>;
+export type CacheSettingsConfig = z.infer<typeof cacheSettingsSchema>;
 export type ConfigInfo = z.infer<typeof configInfoSchema>;
 
 /**
@@ -378,6 +393,15 @@ export const DEFAULT_SERVER_CONFIG: Partial<ConfigInfo> = {
     level: 'standard'
   },
 
+  // Cache settings defaults
+  cacheSettings: {
+    maxMemoryMB: 150,
+    maxPercentOfCachePerEntity: 50,
+    defaultTTLSeconds: 0,
+    evictionSweepIntervalSeconds: 300,
+    verboseLogging: false,
+  },
+
   // Auth providers (environment-driven)
   authProviders: [
     // Microsoft Azure AD / Entra ID

package/src/generated/generated.ts

@@ -37711,6 +37711,12 @@ export class MJEntity_ {
     @Field(() => Boolean, {description: `When true (default), CodeGen can automatically set SupportsGeoCoding based on LLM analysis of entity fields. Set to 0 to lock the value and prevent CodeGen from changing it.`}) 
     AutoUpdateSupportsGeoCoding: boolean;
         
+    @Field(() => Boolean, {description: `Controls whether this entity participates in server-side and client-side caching. When false, all cache operations (PreRunView checks, auto-cache storage, BaseEntity event fingerprint scans, client-side IndexedDB cache) are skipped entirely. This column is the single source of truth at runtime; schema-level defaults are applied at CodeGen time via newEntityDefaults.AllowCachingBySchema.`}) 
+    AllowCaching: boolean;
+        
+    @Field(() => Boolean, {description: `When set to 1 AND TrackRecordChanges is also 1, the external change detection system will scan this entity for changes made outside the MJ framework (direct SQL, third-party tools, etc.) and replay them through Save() to create proper RecordChange audit entries. Default is 0 (opt-out) because most entities, especially __mj schema metadata tables, are managed by migrations/CodeGen and should not be scanned.`}) 
+    DetectExternalChanges: boolean;
+        
     @Field({nullable: true, description: `Schema-based programmatic code name derived from the entity Name. Uses GetClassNameSchemaPrefix(SchemaName) as the prefix, then strips EntityNamePrefix from the Name and removes spaces. For "__mj" schema with entity "MJ: AI Models", this produces "MJAIModels". For entities in other schemas, the sanitized schema name is prepended. Used in GraphQL type generation and internal code references.`}) 
     CodeName?: string;
         
@@ -38080,6 +38086,12 @@ export class CreateMJEntityInput {
 
     @Field(() => Boolean, { nullable: true })
     AutoUpdateSupportsGeoCoding?: boolean;
+
+    @Field(() => Boolean, { nullable: true })
+    AllowCaching?: boolean;
+
+    @Field(() => Boolean, { nullable: true })
+    DetectExternalChanges?: boolean;
 }
     
 
@@ -38265,6 +38277,12 @@ export class UpdateMJEntityInput {
     @Field(() => Boolean, { nullable: true })
     AutoUpdateSupportsGeoCoding?: boolean;
 
+    @Field(() => Boolean, { nullable: true })
+    AllowCaching?: boolean;
+
+    @Field(() => Boolean, { nullable: true })
+    DetectExternalChanges?: boolean;
+
     @Field(() => [KeyValuePairInput], { nullable: true })
     OldValues___?: KeyValuePairInput[];
 }

package/src/index.ts

@@ -128,6 +128,7 @@ export * from './resolvers/TelemetryResolver.js';
 export * from './resolvers/APIKeyResolver.js';
 export * from './resolvers/MCPResolver.js';
 export * from './resolvers/ActionResolver.js';
+export * from './resolvers/CacheStatsResolver.js';
 export * from './resolvers/EntityCommunicationsResolver.js';
 export * from './resolvers/EntityResolver.js';
 export * from './resolvers/ISAEntityResolver.js';
@@ -451,8 +452,21 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
   }
   // Ensure LocalCacheManager is initialized (no-op if already done during engine loading)
   if (!LocalCacheManager.Instance.IsInitialized) {
-    await LocalCacheManager.Instance.Initialize(Metadata.Provider.LocalStorageProvider);
-    console.log('LocalCacheManager initialized');
+    // Build cache config from mj.config.cjs cacheSettings
+    const cs = configInfo.cacheSettings;
+    const cacheConfig = {
+      maxSizeBytes: (cs.maxMemoryMB ?? 150) * 1024 * 1024,
+      maxPercentOfCachePerEntity: cs.maxPercentOfCachePerEntity ?? 50,
+      defaultTTLMs: (cs.defaultTTLSeconds ?? 0) * 1000,
+      evictionSweepIntervalMs: (cs.evictionSweepIntervalSeconds ?? 300) * 1000,
+      verboseLogging: cs.verboseLogging ?? false,
+    };
+    await LocalCacheManager.Instance.Initialize(Metadata.Provider.LocalStorageProvider, cacheConfig);
+    console.log('LocalCacheManager initialized with cache config:', JSON.stringify({
+      maxMemoryMB: cs.maxMemoryMB ?? 150,
+      maxPercentOfCachePerEntity: cs.maxPercentOfCachePerEntity ?? 50,
+      evictionSweepIntervalSeconds: cs.evictionSweepIntervalSeconds ?? 300,
+    }));
   }
 
   // Initialize APIKeyEngine singleton — reads apiKeyGeneration from mj.config.cjs automatically

package/src/resolvers/CacheStatsResolver.ts

@@ -0,0 +1,142 @@
+import { Field, Float, Int, ObjectType, Query, Resolver } from 'type-graphql';
+import { LocalCacheManager, CacheStats, CacheEntryType } from '@memberjunction/core';
+import { RequireSystemUser } from '../directives/index.js';
+
+// ============================================================================
+// GraphQL Object Types
+// ============================================================================
+
+@ObjectType()
+class CacheStatsByTypeGQL {
+    @Field(() => String)
+    Type: CacheEntryType;
+
+    @Field(() => Int)
+    Count: number;
+
+    @Field(() => Int)
+    SizeBytes: number;
+}
+
+@ObjectType()
+class CacheStatsGQL {
+    @Field(() => Int)
+    TotalEntries: number;
+
+    @Field(() => Int)
+    TotalSizeBytes: number;
+
+    @Field(() => [CacheStatsByTypeGQL])
+    ByType: CacheStatsByTypeGQL[];
+
+    @Field(() => Float)
+    OldestEntry: number;
+
+    @Field(() => Float)
+    NewestEntry: number;
+
+    @Field(() => Int)
+    Hits: number;
+
+    @Field(() => Int)
+    Misses: number;
+
+    @Field(() => Float)
+    HitRate: number;
+}
+
+@ObjectType()
+class CacheEntityBreakdownGQL {
+    @Field(() => String)
+    EntityName: string;
+
+    @Field(() => Int)
+    EntryCount: number;
+
+    @Field(() => Int)
+    TotalSizeBytes: number;
+
+    @Field(() => Int)
+    TotalAccessCount: number;
+}
+
+@ObjectType()
+class CacheStatsDetailGQL extends CacheStatsGQL {
+    @Field(() => [CacheEntityBreakdownGQL])
+    EntityBreakdown: CacheEntityBreakdownGQL[];
+}
+
+// ============================================================================
+// Helpers (pure core)
+// ============================================================================
+
+function toGQL(stats: CacheStats): CacheStatsGQL {
+    const gql = new CacheStatsGQL();
+    gql.TotalEntries = stats.totalEntries;
+    gql.TotalSizeBytes = stats.totalSizeBytes;
+    gql.ByType = (['dataset', 'runview', 'runquery'] as const).map(t => {
+        const bt = stats.byType[t];
+        const entry = new CacheStatsByTypeGQL();
+        entry.Type = t;
+        entry.Count = bt.count;
+        entry.SizeBytes = bt.sizeBytes;
+        return entry;
+    });
+    gql.OldestEntry = stats.oldestEntry;
+    gql.NewestEntry = stats.newestEntry;
+    gql.Hits = stats.hits;
+    gql.Misses = stats.misses;
+    gql.HitRate = (stats.hits + stats.misses) > 0
+        ? (stats.hits / (stats.hits + stats.misses)) * 100
+        : 0;
+    return gql;
+}
+
+function buildEntityBreakdown(): CacheEntityBreakdownGQL[] {
+    const entries = LocalCacheManager.Instance.GetAllEntries();
+    const entityMap = new Map<string, { count: number; sizeBytes: number; accessCount: number }>();
+
+    for (const entry of entries) {
+        if (entry.type !== 'runview' || !entry.name) continue;
+        const existing = entityMap.get(entry.name) ?? { count: 0, sizeBytes: 0, accessCount: 0 };
+        existing.count++;
+        existing.sizeBytes += entry.sizeBytes;
+        existing.accessCount += entry.accessCount;
+        entityMap.set(entry.name, existing);
+    }
+
+    return [...entityMap.entries()]
+        .map(([name, data]) => {
+            const gql = new CacheEntityBreakdownGQL();
+            gql.EntityName = name;
+            gql.EntryCount = data.count;
+            gql.TotalSizeBytes = data.sizeBytes;
+            gql.TotalAccessCount = data.accessCount;
+            return gql;
+        })
+        .sort((a, b) => b.EntryCount - a.EntryCount);
+}
+
+// ============================================================================
+// Resolver
+// ============================================================================
+
+@Resolver()
+export class CacheStatsResolver {
+    @RequireSystemUser()
+    @Query(() => CacheStatsGQL)
+    CacheStats(): CacheStatsGQL {
+        const stats = LocalCacheManager.Instance.GetStats();
+        return toGQL(stats);
+    }
+
+    @RequireSystemUser()
+    @Query(() => CacheStatsDetailGQL)
+    CacheStatsDetail(): CacheStatsDetailGQL {
+        const stats = LocalCacheManager.Instance.GetStats();
+        const result = new CacheStatsDetailGQL();
+        Object.assign(result, toGQL(stats));
+        result.EntityBreakdown = buildEntityBreakdown();
+        return result;
+    }
+}