Lifecycle reference

Knowing when during boot/shutdown each module runs which hook is the difference between a clean restart and a half-drained buffer. This page documents the lifecycle behaviour of every official module — verified against source — so you can predict where a console.log('foo') in your onStart will run.

The four phases

Recap of Application lifecycle:

Modules are not obliged to implement all four — most use just one or two. The table below shows what each official module actually does.

Lifecycle behaviour by module

official · @omnitron-dev/titan-*

titan-auth

titan-auth is lifecycle-passive. The JWT service has no long-lived resources to set up or tear down beyond the JWKS HTTP client it opens lazily on first use.

titan-cache

L1 (in-memory LRU/LFU) lives in JS heap. L2 (Redis) is owned by titan-redis and shuts down with that module.

titan-database

The onStop matters: a clean drain prevents in-flight queries from being killed mid-transaction.

titan-discovery

Implemented on both the module and the service.

In clientMode: true, registration is skipped but pub/sub still opens on onStart so the node receives events.

titan-events

Each sub-service has its own onInit / onDestroy; the orchestrator EventsService adds onStart / onStop.

titan-health

titan-health is lifecycle-passive: the module registers its indicators eagerly at config time (inside forRoot / forFeature), not in a lifecycle hook. Checks are pull-driven — Kubernetes probes invoke check() on demand. No background loop runs.

titan-lock

Releasing locks on onStop is best-effort because the process may already be in a degraded state. Always set a lock TTL so abandoned locks self-expire.

titan-metrics

Uses explicit start() / stop() methods rather than the lifecycle interface, called from module setup.

The module calls start() during initialisation and stop() during shutdown — you don't have to wire it up by hand.

titan-notifications

forWorker(...) registrations subscribe to the messaging transport on onStart — the producer (registered via forRoot) opens its publisher connection in the same phase.

titan-pm

Crash-supervised children stop in the opposite order they started — gives you a chance to drain a worker before its dependencies disappear.

titan-ratelimit

Uses an explicit destroy() method called during module shutdown.

titan-redis

titan-redis uses the onModuleInit / onModuleDestroy hook names (on RedisManager) — functionally equivalent to onInit / onDestroy in newer modules. There is no onStop hook; cleanup runs in onModuleDestroy.

titan-scheduler

The split matters: onInit rebuilds the registry, onStart actually arms the timers. Don't expect jobs to fire between those two.

titan-telemetry-relay

Not a module — instantiated directly. Lifecycle is manual:

When integrated into an app via DI, wrap it in a thin lifecycle adapter:

@Injectable()
class TelemetryRelayAdapter implements OnStart, OnStop {
  constructor(private readonly relay: TelemetryRelayService) {}
  async onStart() { await this.relay.start(); }
  async onStop()  { await this.relay.stop();  }
}

Built-in modules

built-in · @omnitron-dev/titan · config + logger

config

If validation fails in onInit, the app aborts boot with the underlying Zod error — no partial start.

logger

The flush in onStop is why graceful shutdown matters for observability — SIGKILL skips it and you lose the last few seconds of logs.

Putting it together — full boot/shutdown timeline

sequenceDiagram
  participant App
  participant Config
  participant Logger
  participant Redis
  participant DB as Database
  participant Lock
  participant Disc as Discovery
  participant Cache
  participant RL as RateLimit
  participant Sched as Scheduler
  participant Notif as Notifications
  participant Metr as Metrics
  participant User as Your services

  App->>Config: onInit (load + validate)
  App->>Logger: onInit (open transports)
  App->>Redis: onModuleInit (connect)
  App->>DB: (no onInit)
  App->>Disc: onInit
  App->>Cache: (no onInit)
  App->>Notif: onInit
  App->>Sched: onInit (rebuild registry)
  App->>Metr: start()
  App->>User: onInit

  Note over App: ─── onInit complete ───

  App->>Config: onStart (watchers)
  App->>Disc: onStart (register node + heartbeat)
  App->>Notif: onStart (subscribe)
  App->>Sched: onStart (arm timers)
  App->>User: onStart

  Note over App: ─── App ready ───
  Note over App: ─── app.stop() called ───

  App->>User: onStop (reverse order)
  App->>Sched: onStop (cancel timers + flush)
  App->>Notif: onStop (drain delivery)
  App->>Disc: onStop (deregister)
  App->>Lock: onStop (release best-effort)
  App->>DB: onStop (drain pool)
  App->>Config: onStop (stop watchers)
  App->>Metr: stop() (drain buffer)
  App->>Logger: onStop (FLUSH transports)

  Note over App: ─── onDestroy phase ───
  App->>User: onDestroy
  App->>Sched: onDestroy
  App->>Notif: onDestroy
  App->>Disc: onDestroy
  App->>RL: destroy()
  App->>Redis: onModuleDestroy (disconnect)
  App->>Logger: onDestroy
  App->>Config: onDestroy

Practical rules

• Long-running background work belongs in onStart, not onInit. Hooks at onInit should be fast — they block every later module from initialising.

• Resources opened in onInit should close in onDestroy. Resources started in onStart should stop in onStop. Mixing them causes subtle leaks.

• onStop runs in reverse dependency order. Your services drain before the modules they depend on. Don't rely on Redis inside an onStop if your service's onStop was already followed by Redis disconnecting.

• Don't throw in onStop / onDestroy. A throw aborts the remaining cleanup chain. Catch + log, let the process exit.

• Heavy CPU work in onStart blocks readiness. If you must precompute, do it in a background task started from onStart and gate readiness on a separate flag.

See also

• Application / Lifecycle — framework-level explanation

• Application / Shutdown — signals, timeouts, graceful drain

• Module map — dependency order determines lifecycle order

• Options patterns — when onInit factories run