@xpulse/app – Service Loader

Status: ACCEPTED · March 2026 Replaces: hardcoded bootstrap/services.js

Problem

bootstrap/services.js is a hardcoded list of tryInit() calls in a fixed sequence. Every new @xpulse/* package requires a manual edit in @xpulse/app. This violates the auto-discovery principle the rest of the framework follows.

Solution: Auto-Discovery Service Loader

The service loader reads xpulse.json from every installed @xpulse/* package, builds a dependency graph from the service section, sorts it topologically, and calls each package's init() in the correct order.

No manual registration. Installing a package is enough.

Service Metadata in `xpulse.json`

Each @xpulse/* package declares itself in its own xpulse.json:

1
{
2
  "name": "xpulse-router",
3
  "type": "component",
4
  "service": {
5
    "xpulse-router": {
6
      "load": true,
7
      "load-after": ["xpulse-http"]
8
    }
9
  }
10
}

Rules:

• The key inside service is the full package name (e.g. xpulse-router).
• load: true — this package participates in the service loader.
• load-after — list of package names that must be initialised first.
• Packages without a service section are ignored by the loader.
• @xpulse/event and @xpulse/config have no service section — they are always available before the loader runs.

Dependency Graph (reference)

1
xpulse-logger
2
xpulse-http
3
  └── (none)
4
xpulse-router
5
  └── xpulse-http
6
xpulse-template
7
  └── (none)
8
xpulse-theme
9
  └── xpulse-router, xpulse-config
10
xpulse-controller
11
  └── xpulse-router, xpulse-template
12
xpulse-session
13
  └── xpulse-router, xpulse-crypto
14
xpulse-debug
15
  └── not part of the service loader — see below
16
xpulse-doc
17
  └── xpulse-router

App-Level Overrides

The application's own xpulse.json can override any service entry. The loader deep-merges the app config on top of the collected package configs.

Disable a service:

1
{
2
  "service": {
3
    "xpulse-theme": { "load": false }
4
  }
5
}

Register an app-local service (from src/services/):

1
{
2
  "service": {
3
    "my-auth": { "load": true, "load-after": ["xpulse-router", "xpulse-session"] }
4
  }
5
}

App-local services are discovered from src/services/*/xpulse.json and merged before the app-level override is applied.

Merge Order

1
1. node_modules/@xpulse/*/xpulse.json   ← package defaults
2
2. src/services/*/xpulse.json            ← app-local services
3
3. xpulse.json { "service": { … } }     ← app overrides (last wins)

Because each package only declares its own name as the key, step 1 never has conflicts. Steps 2 and 3 can override anything from step 1.

Loader Algorithm

1
1. readdir(node_modules/@xpulse/*)
2
2. For each: read xpulse.json → extract service section
3
3. readdir(src/services/*) → same
4
4. Deep-merge app xpulse.json service section on top
5
5. Filter: load !== false
6
6. Topological sort by load-after[]
7
7. For each (in order):
8
     - import('@xpulse/<name>') or import('src/services/<name>')
9
     - call mod.default.init() if exists
10
     - emit app:service:ready / app:service:error / app:service:skipped

A circular dependency throws an error with a clear message naming the cycle. A missing dependency (listed in load-after but load: false or not installed) emits app:service:skipped and continues — resilient by default.

CLI Behaviour

When running via npx xpulse <command>, app.init() is called without app.start(). The full service stack boots — identical to a normal app start — but the HTTP server does not begin listening on a port.

This is the existing behaviour and does not change with the new loader.

Events

@xpulse/debug — Special Position

@xpulse/debug is not part of the service loader. It has its own dedicated bootstrap step that runs before the loader, so that every subsequent service is already debuggable when it inits.

Controlled via xpulse.json as always:

1
{ "debug": { "enabled": true } }

The service section of @xpulse/debug/xpulse.json has no load entry. The loader ignores it completely.

Bootstrap sequence in app.init():

1
1. config.load()          ← always
2
2. debug.bootstrapDebug() ← only when debug.enabled — before loader
3
3. service loader         ← all other @xpulse/* packages

Implementation Notes

• bootstrap/services.js is replaced entirely by the new loader.
• The loader lives in bootstrap/loader.js — services.js is deleted.
• No new external dependency is needed — pure Node.js readdir + dynamic import.