Event – Message Structure Concept

1
namespace:operation          ←  event name
2
{ key, key, key }            ←  payload

1
event.emit('controller:navigation:ready', {
2
    items: [...],
3
    count: 5,
4
});

1
{namespace}:{operation}
2
{namespace}:{area}:{operation}

1
@xpulse/controller  →  controller
2
@xpulse/http        →  http
3
@xpulse/router      →  router
4
@xpulse/template    →  template
5
@xpulse/logger      →  logger
6
@xpulse/app         →  app

1
auth:login
2
chat:message:received
3
peer:connected

1
✓  controller:ready           ← discovery completed
2
✓  http:request               ← request received
3
✓  router:matched             ← route matched
4
✓  navigation:collected       ← navItems collected
5
✓  template:render:after      ← rendering completed
6
 
7
✗  controller:discovering     ← present progressive – don't use
8
✗  http:will-receive-request  ← future tense – don't use
9
✗  router:match               ← imperative – don't use

1
✓  template:render:before     ← explicit pre-hook, data still mutable
2
✓  http:response:before       ← explicit pre-hook, body still mutable

1
{namespace}:init    ← initialisation begins
2
{namespace}:ready   ← initialisation complete

1
app:init
2
app:ready
3
app:stopping
4
app:stopped
5
 
6
http:init
7
http:ready
8
http:started
9
http:stopped
10
http:request
11
http:response:before
12
http:response
13
 
14
controller:init
15
controller:ready
16
controller:discovered
17
controller:called
18
controller:navigation:collected
19
controller:navigation:ready
20
 
21
router:matched
22
router:not-found
23
 
24
template:render:before
25
template:render:after
26
 
27
logger:init
28
logger:ready
29
logger:write
30
 
31
dotenv:loaded
32
config:loaded

1
// ✓ Always object
2
event.emit('controller:ready', { count: 5, routes: 8 });
3
 
4
// ✗ No primitive value
5
event.emit('controller:ready', 5);

1
// ✓ Flat
2
event.emit('http:request', {
3
    traceId: 'abc123',
4
    method:  'GET',
5
    path:    '/info',
6
    ip:      '192.168.1.0',
7
});
8
 
9
// ✗ Too deeply nested
10
event.emit('http:request', {
11
    request: {
12
        meta: {
13
            traceId: 'abc123',
14
        },
15
    },
16
});

1
// ✓ Array as top-level
2
event.emit('controller:navigation:collected', {
3
    items: [ ... ],
4
    count: 5,
5
});

1
// ✓
2
{ traceId, methodName, filePath, itemCount }
3
 
4
// ✗
5
{ trace_id, method_name, file_path, item_count }

1
// :init – what is being initialised
2
{ root?, config? }
3
 
4
// :ready – result of initialisation
5
{ count?, routes?, items?, uptime? }

1
// Always traceId so requests can be correlated
2
{ traceId, method, path, ... }

1
// Always count – how many were found
2
{ count, ... }

1
// Always message + optional err (the Error object itself)
2
{ message: 'template not found', err, context? }

1
// template:render:before – data is mutable
2
event.on('template:render:before', ({ data }) => {
3
    data._nav   = navigationRegistry.getItems();  // inject
4
    data._route = currentRoute;                   // inject
5
});

1
// Name:    controller:navigation:collected
2
//          ──────────┬────────── ─────────
3
//          namespace │area       operation
4
//                    └─ sub-area of controller
5
 
6
// Payload:
7
{
8
    items: NavItem[],   // mutable – listeners can filter/extend
9
    count: number,      // number of collected items before pipeline
10
}
11
 
12
// Behaviour: fired-and-forgotten, payload is mutable (pre-hook)

1
log.debug('navItem registered', { key: 'info_team' })
2
    ↓
3
logger:write event  →  @xpulse/debug collects
4
    ↓
5
console / file      →  developer reads

1
// Internally in @xpulse/controller on init()
2
event.register('controller:navigation:collected', {
3
    description: 'navItems collected from all controllers – mutable, pipeline open',
4
    emittedBy:   '@xpulse/controller',
5
    payload:     '{ items: NavItem[], count: number }',
6
    mutable:     true,
7
});
8
 
9
event.register('controller:navigation:ready', {
10
    description: 'Navigation finalized – read-only',
11
    emittedBy:   '@xpulse/controller',
12
    payload:     '{ items: NavItem[], count: number }',
13
    mutable:     false,
14
});