anear-js-api 0.4.29 → 0.4.31

package/lib/state_machines/AnearEventMachine.js

@@ -30,6 +30,7 @@ const AnearParticipantMachine = require('../state_machines/AnearParticipantMachi
 const AnearParticipant = require('../models/AnearParticipant')
 const RealtimeMessaging = require('../utils/RealtimeMessaging')
 const MetaProcessing = require('../utils/MetaProcessing')
+const DisplayEventProcessor = require('../utils/DisplayEventProcessor')
 const PugHelpers = require('../utils/PugHelpers')
 const C = require('../utils/Constants')
 
@@ -180,7 +181,7 @@ const ActiveEventStatesConfig = {
       ],
       on: {
         RENDER_DISPLAY: {
-          target: '#rendering'
+          target: '.rendering'
         }
       },
       states: {
@@ -196,7 +197,6 @@ const ActiveEventStatesConfig = {
           }
         },
         rendering: {
-          id: 'rendering',
           deferred: DeferredStatesPlus('ANNOUNCE', 'START'),
           invoke: {
             src: 'renderDisplay',
@@ -220,7 +220,7 @@ const ActiveEventStatesConfig = {
       initial: 'transitioning',
       on: {
         RENDER_DISPLAY: {
-          target: '#rendering'
+          target: '.rendering'
         },
         PARTICIPANT_LEAVE: {
           // creator browser refresh or MIA.  Send disconnect events
@@ -273,7 +273,6 @@ const ActiveEventStatesConfig = {
           }
         },
         rendering: {
-          id: 'rendering',
           deferred: DeferredStatesPlus('START'),
           invoke: {
             src: 'renderDisplay',
@@ -792,87 +791,10 @@ const AnearEventMachineFunctions = ({
     }
   },
   services: {
-    renderDisplay: async (context, event) => {
-      const processDisplayEvent = (context, displayEvent) => {
-        const { displayType, viewPath, timeout, appExecutionContext } = displayEvent
-
-        logger.debug("processDisplayEvent - displayType: ", displayType, ", viewPath: ", viewPath)
-
-        const renderedDisplayContent = (template, additionalExecutionContext, timeout) => {
-          const renderedMessage = template(
-            {
-              displayType,
-              ...appExecutionContext,
-              ...additionalExecutionContext,
-              participants: context.participants,
-              ...context.pugHelpers
-            }
-          )
-          const displayContent = { content: renderedMessage }
-          if (timeout) {
-            displayContent['timeout'] = timeout
-          }
-          return displayContent
-        }
-
-        const privateParticipantSend = participantMachine => {
-          const participantState = participantMachine.state
-          const participantContext = participantState.context
-          const { appParticipantMachine, anearParticipant } = participantContext
-
-          // TODO: don't send to participants that aren't in an active state
-
-          const appParticipantContext =
-            appParticipantMachine ? participantContext.appParticipantMachine.state.context : {}
-
-          const privateContext = {
-            anearParticipant: anearParticipant.participantInfo,
-            participantContext: appParticipantContext
-          }
+    renderDisplay: (context, event) => {
+      const displayEventProcessor = new DisplayEventProcessor(context)
 
-          const displayEventPayload = renderedDisplayContent(template, privateContext, timeout)
-
-          participantMachine.send('PRIVATE_DISPLAY', displayEventPayload)
-        }
-
-        const normalizedPath = viewPath.endsWith(C.PugSuffix) ? viewPath : `${viewPath}${C.PugSuffix}`
-        const template = context.pugTemplates[normalizedPath]
-        if (!template) {
-          throw new Error(`Template not found for path "${normalizedPath}".`)
-        }
-        let displayMessage
-
-        switch (displayType) {
-          case 'participants':
-            displayMessage = renderedDisplayContent(template, {}, timeout)
-            return RealtimeMessaging.publish(
-              context.participantsDisplayChannel,
-              'PARTICIPANTS_DISPLAY',
-              displayMessage
-            )
-            break
-          case 'spectators':
-            displayMessage = renderedDisplayContent(template, {})
-            return RealtimeMessaging.publish(
-              context.spectatorsDisplayChannel,
-              'SPECTATORS_DISPLAY',
-              displayMessage
-            )
-            break
-          case 'participant':
-            // For private displays, iterate over active active participant machines.
-            Object.values(context.participantMachines).forEach(privateParticipantSend)
-            return Promise.resolve()
-            break
-          default:
-            throw new Error(`Unknown display type: ${displayType}`)
-        }
-      }
-
-      const publishPromises = event.displayEvents.map(
-        displayEvent => processDisplayEvent(context, displayEvent)
-      )
-      return Promise.all(publishPromises)
+      return displayEventProcessor.processAndPublish(event.displayEvents)
     },
     getAttachedCreatorOrHost: async (context, event) => {
       logger.debug("getAttachedCreatorOrHost() invoked")

package/lib/state_machines/AnearParticipantMachine.js

@@ -22,7 +22,7 @@ const CurrentDateTimestamp = _ => new Date().getTime()
 const MISSING_TIMEOUT = 10000 // msecs
 
 const DeferredStates = [
-  'PRIVATE_DISPLAY',
+  'RENDER_DISPLAY',
   'PARTICIPANT_EXIT',
   'PARTICIPANT_DISCONNECT',
   'PARTICIPANT_RECONNECT'
@@ -92,8 +92,8 @@ const AnearParticipantMachineConfig = participantId => ({
             idle: {
               id: 'idle',
               on: {
-                PRIVATE_DISPLAY: {
-                  target: '#privateDisplay'
+                RENDER_DISPLAY: {
+                  target: '#renderDisplay'
                 },
                 PARTICIPANT_DISCONNECT: {
                   target: 'missing'
@@ -116,11 +116,11 @@ const AnearParticipantMachineConfig = participantId => ({
                 }
               }
             },
-            privateDisplay: {
-              id: 'privateDisplay',
+            renderDisplay: {
+              id: 'renderDisplay',
               deferred: DeferredStates,
               invoke: {
-                src: 'privateParticipantDisplay',
+                src: 'participantDisplay',
                 onDone: [
                   {
                     cond: 'hasMetaTimeout',
@@ -233,7 +233,7 @@ const AnearParticipantMachineFunctions = {
     }
   },
   services: {
-    privateParticipantDisplay: async (context, event) => {
+    participantDisplay: async (context, event) => {
       await RealtimeMessaging.publish(
         context.privateChannel,
         'PRIVATE_DISPLAY',
@@ -248,7 +248,7 @@ const AnearParticipantMachineFunctions = {
   },
   guards: {
     hasAppParticipantMachine: context => context.appParticipantMachineFactory !== null,
-    hasMetaTimeout: (context, event) => event.data.timeout.msecs > 0
+    hasMetaTimeout: (context, event) => event.data.timeout?.msecs > 0
   },
   delays: {
     timeoutMsecsAfterNoResponse: context => context.noResponseTimeout
@@ -258,7 +258,7 @@ const AnearParticipantMachineFunctions = {
 // The AnearParticipantMachine:
 //   1. maintains the presence and geo-location for a Participant in an Event
 //   2. instantiates the XState Machine return by the (optional) appParticipantMachineFactory
-//   3. creates a private display ChannelMachine to which any private display messages get published
+//   3. creates a private display ChannelMachine to which any participant displayType messages get published
 //   4. handles activity state, response timeouts, idle state
 //   5. receives ACTION events relayed by the AnearEventMachine
 //   6. relays all relevant events to the participant XState Machine for Application-specific handling

package/lib/utils/DisplayEventProcessor.js

@@ -0,0 +1,120 @@
+"use strict"
+/**
+ * --------------------------------------------------------------------------
+ * Pug templates receive the following context at render:
+ *
+ * {
+ *   displayType:       // 'participants' | 'spectators' | 'participant'
+ *   context:           // AppEventMachine's XState context for this transition
+ *   state:             // Stringified state name (e.g., 'live.registration.waitForOpponentToJoin')
+ *   event:             // The triggering event for this transition
+ *   participants:      // Map of all participants for this event
+ *
+ *   // When 'participant' displayType
+ *   participant        // current participant
+ *   participantContext // current participant private context if AppParticipantMachine
+ *
+ *   // PLUS all helpers from PugHelpers:
+ *   cdnImg(filename)  // Resolves CDN image path
+ *   action(payload)   // JSON-encodes click action payloads for data attributes
+ * }
+ *
+ * Example usage in Pug:
+ *
+ *   img(src=cdnImg('logo.png'))
+ *   .sq(data-anear-click=action({MOVE: {x, y}}))
+ *   each participant in Object.values(participants)
+ *     li= participant.name
+ *
+ * --------------------------------------------------------------------------
+ */
+
+const logger = require('./Logger')
+const RealtimeMessaging = require('./RealtimeMessaging')
+const C = require('./Constants')
+
+class DisplayEventProcessor {
+  constructor(anearEventMachineContext) {
+    this.pugTemplates = anearEventMachineContext.pugTemplates
+    this.pugHelpers = anearEventMachineContext.pugHelpers
+    this.participants = anearEventMachineContext.participants
+    this.participantMachines = anearEventMachineContext.participantMachines
+    this.participantsDisplayChannel = anearEventMachineContext.participantsDisplayChannel
+    this.spectatorsDisplayChannel = anearEventMachineContext.spectatorsDisplayChannel
+  }
+
+  processAndPublish(displayEvents) {
+    return Promise.all(displayEvents.map(event => this._processSingle(event)))
+  }
+
+  _processSingle(displayEvent) {
+    const { displayType, viewPath, timeout, appExecutionContext } = displayEvent
+
+    const normalizedPath = viewPath.endsWith(C.PugSuffix) ? viewPath : `${viewPath}${C.PugSuffix}`
+    const template = this.pugTemplates[normalizedPath]
+
+    if (!template) {
+      throw new Error(`Template not found: ${normalizedPath}`)
+    }
+
+    const renderContext = {
+      displayType,
+      ...appExecutionContext,
+      participants: this.participants,
+      ...this.pugHelpers
+    }
+
+    const renderedContent = template(renderContext)
+    const message = { content: renderedContent }
+    if (timeout) message.timeout = timeout
+
+    switch (displayType) {
+      case 'participants':
+        logger.debug(`[DisplayEventProcessor] Publishing PARTICIPANTS_DISPLAY`)
+        return RealtimeMessaging.publish(
+          this.participantsDisplayChannel,
+          'PARTICIPANTS_DISPLAY',
+          message.content
+        )
+
+      case 'spectators':
+        logger.debug(`[DisplayEventProcessor] Publishing SPECTATORS_DISPLAY`)
+        return RealtimeMessaging.publish(
+          this.spectatorsDisplayChannel,
+          'SPECTATORS_DISPLAY',
+          message.content
+        )
+
+      case 'participant':
+        logger.debug(`[DisplayEventProcessor] Processing RENDER_DISPLAY for each participant`)
+        return this._processPrivateParticipantDisplays(template, renderContext, timeout)
+
+      default:
+        throw new Error(`Unknown displayType: ${displayType}`)
+    }
+  }
+
+  _processPrivateParticipantDisplays(template, renderContextBase, timeout) {
+    Object.values(this.participantMachines).forEach(participantMachine => {
+      const participantState = participantMachine.state
+      const { anearParticipant, appParticipantMachine } = participantState.context
+
+      const privateRenderContext = {
+        ...renderContextBase,
+        participant: anearParticipant.participantInfo,
+        participantContext: appParticipantMachine?.state?.context || {}
+      }
+
+      const privateHtml = template(privateRenderContext)
+
+      const renderMessage = { content: privateHtml }
+      if (timeout) renderMessage.timeout = timeout
+
+      participantMachine.send('RENDER_DISPLAY', renderMessage)
+    })
+
+    return Promise.resolve()
+  }
+}
+
+module.exports = DisplayEventProcessor

package/lib/utils/MetaProcessing.js

@@ -2,146 +2,94 @@
 
 const logger = require('./Logger')
 
-// Helper functions for processing meta configurations
-const buildTimeout = (timeoutType, timeoutConfig, appExecutionContext) => {
-  let msecs = null
-  let participantId = null
-
-  switch (typeof timeoutConfig) {
-    case 'function':
-      [msecs, participantId] = timeoutConfig(appExecutionContext)
-      break
-    case 'number':
-      msecs = timeoutConfig
-      break
-    default:
-      throw new Error(`unknown timeout config ${typeof timeoutConfig}`)
-  }
-
-  switch (timeoutType) {
-    case 'participant':
-      return { type: timeoutType, msecs, participantId }
-    case 'participants':
-      return { type: timeoutType, msecs }
-    default:
-      throw new Error(`unknown timeout type ${timeoutType}`)
-  }
-}
-
-const metaConfig = (meta, timeoutType, appExecutionContext) => {
-  let timeout = {msecs: 0}
-  let view = null
-
-  switch (typeof meta) {
-    case 'string':
-      view = meta
-      break
-    case 'object':
-      view = meta.view
-      if (meta.timeout) {
-        timeout = buildTimeout(timeoutType, meta.timeout, appExecutionContext)
-      }
-
-      break
-    default:
-      throw new Error(`unknown ${timeoutType} meta format ${meta}`)
-  }
-  return [view, timeout]
-}
-
-const participantsMetaConfig = (participantsMeta, appExecutionContext) => {
-  return metaConfig(participantsMeta, 'participants', appExecutionContext)
-}
-
-const participantMetaConfig = (participantMeta, appExecutionContext) => {
-  return metaConfig(participantMeta, 'participant', appExecutionContext)
-}
-
-const spectatorMetaConfig = config => {
-  if (typeof config === 'string')
-    return config
-  else if (typeof config === 'object')
-    return config.view
-  else
-    throw new Error(`unknown spectator meta format ${config}`)
-}
-
-const Stringified = (stateValue) => {
-  switch (typeof stateValue) {
-    case 'string':
-      return stateValue
-    case 'object':
-      return Object.entries(stateValue)
-        .map(([key, nested]) => `${key}.${Stringified(nested)}`)
-        .join('.')
-    default:
-      throw new Error(`unknown Xstate state value type ${typeof stateValue}`)
-  }
-}
-
-const MetaProcessing = anearEvent => {
-  return appEventMachineState => {
-    const { context: appContext, meta: rawMeta } = appEventMachineState
-    const appStateName = Stringified(appEventMachineState.value)
-    const displayEvents = []
-
-    //logger.debug("MetaProcessing invoked on transition to: ", appStateName)
-    //logger.debug("stateMeta: ", appEventMachineState.meta)
-
-    if (Object.keys(appEventMachineState.meta).length === 0) {
-      return
-    }
-
-    logger.debug("App Context: ", appContext)
-
-    const sendDisplayMessage = () => {
-      logger.debug(`${appStateName} 'RENDER_DISPLAY' to ${anearEvent.id} with ${displayEvents.length} msgs`)
-
-      // sends a RENDER_DISPLAY event with one or more viewPaths and appExecutionContext in the displayEvents array
-      anearEvent.send('RENDER_DISPLAY', { displayEvents })
-    }
-
-    const appendDisplayEvent = (displayType, viewPath, timeout = null) => {
-      displayEvents.push(
-        {
-          displayType,
-          viewPath,
-          timeout,
-          appExecutionContext
-        }
-      )
-    }
+/**
+ * MetaProcessing:
+ *  - Runs inside your appEventMachine onTransition.
+ *  - Knows how to parse the XState meta shape (participants, participant, spectators).
+ *  - Normalizes viewPath + timeout.
+ *  - Emits displayEvents → sends to AnearEventMachine for rendering.
+ */
+const MetaProcessing = (anearEvent) => {
+  return (appEventMachineState) => {
+    const { meta: rawMeta, context: appContext, value, event } = appEventMachineState
+    const [meta] = Object.values(rawMeta)
+
+    if (!meta) return
+
+    const appStateName = _stringifiedState(value)
 
     const appExecutionContext = {
       context: appContext,
       state: appStateName,
-      event: appEventMachineState.event
+      event
     }
 
-    const [meta] = Object.values(appEventMachineState.meta)
-
-    logger.debug("meta: ", meta)
-
-    // Only proceed if there's at least one display meta defined.
-    if (!meta.participants && !meta.participant && !meta.spectators) return
+    const displayEvents = []
 
     if (meta.participants) {
-      const [viewPath, timeout] = participantsMetaConfig(meta.participants, appExecutionContext)
-      appendDisplayEvent('participants', viewPath, timeout)
+      const viewPath = _getViewPath(meta.participants)
+      const timeout = _buildTimeout(meta.participants.timeout, appExecutionContext)
+      displayEvents.push({
+        displayType: 'participants',
+        viewPath,
+        timeout,
+        appExecutionContext
+      })
     }
 
     if (meta.participant) {
-      const [viewPath, timeout] = participantMetaConfig(meta.participant, appExecutionContext)
-      appendDisplayEvent('participant', viewPath, timeout)
+      const viewPath = _getViewPath(meta.participant)
+      const timeout = _buildTimeout(meta.participant.timeout, appExecutionContext)
+      displayEvents.push({
+        displayType: 'participant',
+        viewPath,
+        timeout,
+        appExecutionContext
+      })
     }
 
     if (meta.spectators) {
-      const viewPath = spectatorMetaConfig(meta.spectators)
-      appendDisplayEvent('spectators', viewPath)
+      const viewPath = _getViewPath(meta.spectators)
+      displayEvents.push({
+        displayType: 'spectators',
+        viewPath,
+        timeout: null,
+        appExecutionContext
+      })
+    }
+
+    if (displayEvents.length > 0) {
+      logger.debug(`[MetaProcessing] sending RENDER_DISPLAY with ${displayEvents.length} displayEvents`)
+      anearEvent.send('RENDER_DISPLAY', { displayEvents })
     }
+  }
+}
+
+const _getViewPath = (config) => {
+  if (!config) return null
+  if (typeof config === 'string') return config
+  if (typeof config === 'object') return config.view
+  throw new Error(`Unknown meta format: ${JSON.stringify(config)}`)
+}
+
+const _buildTimeout = (timeoutConfig, appExecutionContext) => {
+  if (!timeoutConfig) return null
 
-    sendDisplayMessage()
+  if (typeof timeoutConfig === 'function') {
+    const [msecs, participantId] = timeoutConfig(appExecutionContext)
+    return { msecs, participantId }
   }
+
+  if (typeof timeoutConfig === 'number') {
+    return { msecs: timeoutConfig }
+  }
+
+  throw new Error(`Unknown timeout config: ${typeof timeoutConfig}`)
+}
+
+const _stringifiedState = (stateValue) => {
+  if (typeof stateValue === 'string') return stateValue
+  return Object.entries(stateValue).map(([k, v]) => `${k}.${_stringifiedState(v)}`).join('.')
 }
 
 module.exports = MetaProcessing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anear-js-api",
-  "version": "0.4.29",
+  "version": "0.4.31",
   "description": "Javascript Developer API for Anear Apps",
   "main": "lib/index.js",
   "scripts": {