@memberjunction/server 5.8.0 → 5.9.0

package/src/generic/CacheInvalidationResolver.ts

@@ -0,0 +1,66 @@
+import { Field, ObjectType, Resolver, Root, Subscription } from 'type-graphql';
+
+export const CACHE_INVALIDATION_TOPIC = 'CACHE_INVALIDATION';
+
+@ObjectType()
+export class CacheInvalidationNotification {
+    @Field(() => String)
+    EntityName!: string;
+
+    @Field(() => String, { nullable: true })
+    PrimaryKeyValues?: string;
+
+    @Field(() => String)
+    Action!: string;
+
+    @Field(() => String)
+    SourceServerID!: string;
+
+    @Field(() => Date)
+    Timestamp!: Date;
+
+    @Field(() => String, { nullable: true })
+    OriginSessionID?: string;
+
+    @Field(() => String, { nullable: true })
+    RecordData?: string;
+}
+
+/**
+ * Payload interface for publishing cache invalidation events.
+ * Used by PubSubManager.Publish() to send events from Redis callbacks.
+ */
+export interface CacheInvalidationPayload {
+    entityName: string;
+    primaryKeyValues: string | null;
+    action: string;
+    sourceServerId: string;
+    timestamp: Date;
+    originSessionId?: string;
+    recordData?: string;
+}
+
+@Resolver()
+export class CacheInvalidationResolver {
+    /**
+     * Subscription that broadcasts cache invalidation events to ALL connected clients.
+     * No session filter — every browser connected via WebSocket receives every event.
+     * This enables cross-server cache invalidation to propagate to browser clients.
+     */
+    @Subscription(() => CacheInvalidationNotification, {
+        topics: CACHE_INVALIDATION_TOPIC,
+    })
+    cacheInvalidation(
+        @Root() payload: CacheInvalidationPayload
+    ): CacheInvalidationNotification {
+        return {
+            EntityName: payload.entityName,
+            PrimaryKeyValues: payload.primaryKeyValues ?? undefined,
+            Action: payload.action,
+            SourceServerID: payload.sourceServerId,
+            Timestamp: payload.timestamp,
+            OriginSessionID: payload.originSessionId ?? undefined,
+            RecordData: payload.recordData ?? undefined,
+        };
+    }
+}

package/src/generic/PubSubManager.ts

@@ -0,0 +1,47 @@
+import { PubSubEngine } from 'type-graphql';
+import { BaseSingleton } from '@memberjunction/global';
+
+/**
+ * Singleton manager that holds a reference to the type-graphql PubSubEngine,
+ * allowing any server-side code (not just resolvers with @PubSub() injection)
+ * to publish events to GraphQL subscriptions.
+ */
+export class PubSubManager extends BaseSingleton<PubSubManager> {
+    private _pubSub: PubSubEngine | null = null;
+
+    protected constructor() {
+        super();
+    }
+
+    public static get Instance(): PubSubManager {
+        return super.getInstance<PubSubManager>();
+    }
+
+    /**
+     * Sets the PubSubEngine instance. Should be called once during server startup
+     * after buildSchemaSync creates the PubSub instance.
+     */
+    public SetPubSubEngine(pubSub: PubSubEngine): void {
+        this._pubSub = pubSub;
+    }
+
+    /**
+     * Gets the current PubSubEngine instance, or null if not yet configured.
+     */
+    public get PubSubEngine(): PubSubEngine | null {
+        return this._pubSub;
+    }
+
+    /**
+     * Publishes a payload to the specified topic via the PubSubEngine.
+     * No-op if the PubSubEngine has not been configured yet.
+     */
+    public Publish(topic: string, payload: Record<string, unknown>): void {
+        if (this._pubSub) {
+            console.log(`[PubSubManager] Publishing to topic "${topic}":`, JSON.stringify(payload).substring(0, 200));
+            this._pubSub.publish(topic, payload);
+        } else {
+            console.warn(`[PubSubManager] Cannot publish to "${topic}" — PubSubEngine not set`);
+        }
+    }
+}

package/src/generic/ResolverBase.ts

@@ -31,6 +31,8 @@ import { DeleteOptionsInput } from './DeleteOptionsInput.js';
 import { MJEvent, MJEventType, MJGlobal, ENCRYPTED_SENTINEL, IsValueEncrypted, IsOnlyTimezoneShift } from '@memberjunction/global';
 import { EncryptionEngine } from '@memberjunction/encryption';
 import { PUSH_STATUS_UPDATES_TOPIC } from './PushStatusResolver.js';
+import { CACHE_INVALIDATION_TOPIC } from './CacheInvalidationResolver.js';
+import { PubSubManager } from './PubSubManager.js';
 import { FieldMapper } from '@memberjunction/graphql-dataprovider';
 import { Subscription } from 'rxjs';
 
@@ -128,6 +130,31 @@ export class ResolverBase {
     return dataObject;
   }
 
+  /**
+   * Reverse-maps GraphQL-safe field names back to entity CodeNames in a mutation input object.
+   * For example, `_mj__integration_SyncStatus` is mapped back to `__mj_integration_SyncStatus`.
+   * Also reverse-maps keys inside the `OldValues___` array if present.
+   * This is the inverse of MapFieldNamesToCodeNames and must be called before passing
+   * GraphQL input to entity SetMany() or field lookups.
+   */
+  protected ReverseMapInputFieldNames(input: Record<string, unknown>): Record<string, unknown> {
+    const mapper = new FieldMapper();
+    const mapped: Record<string, unknown> = {};
+    for (const key of Object.keys(input)) {
+      if (key === 'OldValues___') {
+        // Reverse-map the Key property inside each OldValues entry
+        const oldValues = input[key] as Array<{ Key: string; Value: unknown }>;
+        mapped[key] = oldValues.map((item) => ({
+          Key: mapper.ReverseMapFieldName(item.Key),
+          Value: item.Value,
+        }));
+      } else {
+        mapped[mapper.ReverseMapFieldName(key)] = input[key];
+      }
+    }
+    return mapped;
+  }
+
   protected async ArrayMapFieldNamesToCodeNames(entityName: string, dataObjectArray: any[], contextUser?: UserInfo): Promise<any[]> {
     // iterate through the array and call MapFieldNamesToCodeNames for each element
     if (dataObjectArray && dataObjectArray.length > 0) {
@@ -947,6 +974,23 @@ export class ResolverBase {
     return Metadata.Provider.ConfigData.MJCoreSchemaName;
   }
 
+  /**
+   * Publishes a CACHE_INVALIDATION event to connected browser clients after a successful
+   * entity save or delete. Includes the originSessionId so the originating browser can
+   * skip redundant re-fetches (it already handled the event locally).
+   */
+  protected PublishCacheInvalidation(entityObject: BaseEntity, action: 'save' | 'delete', userPayload: UserPayload): void {
+    PubSubManager.Instance.Publish(CACHE_INVALIDATION_TOPIC, {
+      entityName: entityObject.EntityInfo.Name,
+      primaryKeyValues: JSON.stringify(entityObject.PrimaryKey.KeyValuePairs),
+      action,
+      sourceServerId: MJGlobal.Instance.ProcessUUID,
+      timestamp: new Date(),
+      originSessionId: userPayload?.sessionId || null,
+      recordData: action === 'save' ? JSON.stringify(entityObject.GetAll()) : undefined,
+    });
+  }
+
   protected ListenForEntityMessages(entityObject: BaseEntity, pubSub: PubSubEngine, userPayload: UserPayload) {
     // The unique key is set up for each entity object via it's primary key to ensure that we only have one listener at most for each unique
     // entity in the system. This is important because we don't want to have multiple listeners for the same entity as it could
@@ -997,6 +1041,9 @@ export class ResolverBase {
     // Check API key scope authorization for entity create operations
     await this.CheckAPIKeyScopeAuthorization('entity:create', entityName, userPayload);
 
+    // Reverse-map GraphQL field names (e.g. _mj__*) back to entity CodeNames (e.g. __mj_*)
+    input = this.ReverseMapInputFieldNames(input);
+
     if (await this.BeforeCreate(provider, input)) {
       // fire event and proceed if it wasn't cancelled
       const entityObject = await provider.GetEntityObject(entityName, this.GetUserFromPayload(userPayload));
@@ -1009,6 +1056,7 @@ export class ResolverBase {
       if (await entityObject.Save()) {
         // save worked, fire the AfterCreate event and then return all the data
         await this.AfterCreate(provider, input); // fire event
+        this.PublishCacheInvalidation(entityObject, 'save', userPayload);
         const contextUser = this.GetUserFromPayload(userPayload);
         // MapFieldNamesToCodeNames now handles encryption filtering as well
         return await this.MapFieldNamesToCodeNames(entityName, entityObject.GetAll(), contextUser);
@@ -1032,6 +1080,9 @@ export class ResolverBase {
     // Check API key scope authorization for entity update operations
     await this.CheckAPIKeyScopeAuthorization('entity:update', entityName, userPayload);
 
+    // Reverse-map GraphQL field names (e.g. _mj__*) back to entity CodeNames (e.g. __mj_*)
+    input = this.ReverseMapInputFieldNames(input);
+
     if (await this.BeforeUpdate(provider, input)) {
       // fire event and proceed if it wasn't cancelled
       const userInfo = this.GetUserFromPayload(userPayload);
@@ -1088,6 +1139,7 @@ export class ResolverBase {
       if (await entityObject.Save()) {
         // save worked, fire afterevent and return all the data
         await this.AfterUpdate(provider, input); // fire event
+        this.PublishCacheInvalidation(entityObject, 'save', userPayload);
 
         // MapFieldNamesToCodeNames now handles encryption filtering as well
         return await this.MapFieldNamesToCodeNames(entityName, entityObject.GetAll(), userInfo);
@@ -1307,6 +1359,7 @@ export class ResolverBase {
       
       if (await entityObject.Delete(options)) {
         await this.AfterDelete(provider, key); // fire event
+        this.PublishCacheInvalidation(entityObject, 'delete', userPayload);
         return returnValue;
       } else {
         throw new GraphQLError(entityObject.LatestResult?.Message ?? 'Unknown error', {

package/src/hooks.ts

@@ -0,0 +1,77 @@
+/**
+ * Server-level extensibility types for MJServer.
+ *
+ * Provider-level hook types (PreRunViewHook, PostRunViewHook, PreSaveHook)
+ * are defined and exported from @memberjunction/core (hookRegistry.ts) so
+ * that ProviderBase and BaseEntity can reference them without depending
+ * on @memberjunction/server.
+ *
+ * This file re-exports those types for convenience and adds the
+ * server-specific extensibility options (Express middleware, Apollo plugins,
+ * schema transformers).
+ */
+
+export type { PreRunViewHook, PostRunViewHook, PreSaveHook, HookName, HookRegistrationOptions } from '@memberjunction/core';
+
+import type { PreRunViewHook, PostRunViewHook, PreSaveHook, HookRegistrationOptions } from '@memberjunction/core';
+import type { RequestHandler, ErrorRequestHandler, Application } from 'express';
+import type { ApolloServerPlugin } from '@apollo/server';
+import type { GraphQLSchema } from 'graphql';
+
+/**
+ * A hook entry that includes the hook function plus optional registration metadata.
+ * Dynamic packages use this format to declare hooks with priority and namespace.
+ */
+export interface HookWithOptions<T> {
+  hook: T;
+  Priority?: number;
+  Namespace?: string;
+}
+
+/** A hook value is either a plain function or a function with registration options */
+export type HookOrEntry<T> = T | HookWithOptions<T>;
+
+/**
+ * Extensibility options that can be passed to `serve()` (via MJServerOptions)
+ * or to `createMJServer()` (via MJServerConfig).
+ *
+ * All properties are optional — when omitted, zero behavior change (backward compatible).
+ */
+export interface ServerExtensibilityOptions {
+  /** Express middleware applied after compression but before OAuth/REST/GraphQL routes */
+  ExpressMiddlewareBefore?: RequestHandler[];
+
+  /** Express middleware/error handlers applied after all routes (catch-alls, error handlers) */
+  ExpressMiddlewareAfter?: (RequestHandler | ErrorRequestHandler)[];
+
+  /** Escape hatch for advanced Express app configuration (CORS, trust proxy, etc.) */
+  ConfigureExpressApp?: (app: Application) => void | Promise<void>;
+
+  /** Additional Apollo Server plugins merged with the built-in drain/cleanup plugins */
+  ApolloPlugins?: ApolloServerPlugin[];
+
+  /** Schema transformers applied after built-in directive transformers */
+  SchemaTransformers?: ((schema: GraphQLSchema) => GraphQLSchema)[];
+
+  /**
+   * Express middleware that runs AFTER authentication has resolved UserInfo
+   * onto the request. Use this for middleware that needs the authenticated
+   * user (e.g., tenant context resolution, org membership loading).
+   *
+   * The authenticated user payload is available at `req.userPayload`.
+   * Middleware in this array runs in registration order.
+   */
+  ExpressMiddlewarePostAuth?: RequestHandler[];
+
+  /** Hooks that modify RunViewParams before query execution (e.g., tenant filter injection).
+   * Each entry can be a plain hook function or a `{ hook, Priority, Namespace }` object. */
+  PreRunViewHooks?: HookOrEntry<PreRunViewHook>[];
+
+  /** Hooks that modify RunViewResult after query execution (e.g., data masking).
+   * Each entry can be a plain hook function or a `{ hook, Priority, Namespace }` object. */
+  PostRunViewHooks?: HookOrEntry<PostRunViewHook>[];
+
+  /** Hooks that validate/reject Save operations before they hit the database.
+   * Each entry can be a plain hook function or a `{ hook, Priority, Namespace }` object. */
+  PreSaveHooks?: HookOrEntry<PreSaveHook>[];
+}