Designing Type-Safe Shutdown and Restart Logic for Long-Running TypeScript Services

Hook: Your service will be killed—plan for it

You ship a TypeScript service to production and assume the cloud, container scheduler, or an angry operator will politely stop it. Reality in 2026: processes get randomly killed (intentional chaos engineering, preemption, OOMs, or the infamous process-roulette tests). If your shutdown and restart logic is ad-hoc, you risk corrupted state, duplicated transactions, and confusing bugs that only show up under failure.

The goal in 2026: deterministic, type-safe lifecycle management

This article shows patterns that combine runtime techniques (idempotent shutdown, in-flight-request tracking, transactional commits, write-ahead logs) with TypeScript's advanced type system (generics, conditional types, mapped types) to ensure you can't accidentally call the wrong API at the wrong lifecycle phase. You will get practical code, checklists, and migration advice you can apply today.

Why this matters now

• Cloud-native orchestration in 2026 expects graceful termination windows (Kubernetes' terminationGracePeriodSeconds, preStop hooks) while chaos engineering workflows intentionally kill processes—your shutdown must be idempotent and predictable.
• TypeScript's 5.x family and later runtime patterns give us better control-flow and type-level guarantees; using them reduces cognitive load and prevents dangerous runtime calls during shutdown.
• Modern Node runtimes (Node 20+/22 LTS) ship first-class AbortController and stable top-level await patterns that simplify cancellation and restart logic.

High-level patterns we'll implement

1. Idempotent shutdown via single Promise and guarded state
2. Transactional commit with WAL and resume/replay on restart
3. In-flight request tracking with typed registries and cancellable requests
4. Strong lifecycle state types implemented as a compile-time state machine

Pattern 1 — Idempotent shutdown

Shutdown must be safe to call multiple times and reentrant during concurrent signal handling. The standard pattern is a singleton Promise that all callers await. If shutdown has started, new calls receive the same Promise. This is simple at runtime but gets stronger when combined with types that prevent starting new work after shutdown begins.

// simple idempotent shutdown helper
class ShutdownCoordinator {
  private shutdownPromise: Promise | null = null
  private shutdownStarted = false

  startShutdown(signalReason?: string): Promise {
    if (this.shutdownPromise) return this.shutdownPromise

    this.shutdownStarted = true
    this.shutdownPromise = (async () => {
      // run cleanup tasks with timeout and error isolation
      try {
        await Promise.race([
          this.cleanupAll(),
          new Promise((_, rej) => setTimeout(() => rej(new Error('shutdown timeout')), 30_000)),
        ])
      } finally {
        // ensure deterministic final state
        this.shutdownStarted = true
      }
    })()

    return this.shutdownPromise
  }

  isShuttingDown() { return this.shutdownStarted }

  private async cleanupAll() { /* ... */ }
}

Key takeaways:

• Expose isShuttingDown so other subsystems can refuse new work.
• Make shutdown deterministically finish by using timeouts and isolation.
• Log and persist critical signals so restart logic can inspect unfinished work.

Pattern 2 — Track in-flight work and cancel safely

Graceful shutdown waits for in-flight requests to finish or aborts them after a timeout. Use AbortController where possible and keep a typed registry of in-flight operations.

type RequestId = string

class InFlightTracker {
  private map = new Map()

  startRequest(id: RequestId) {
    const ac = new AbortController()
    this.map.set(id, ac)
    return ac
  }

  finishRequest(id: RequestId) {
    this.map.delete(id)
  }

  async awaitDrain(timeoutMs = 10_000) {
    const controllers = Array.from(this.map.values())
    if (controllers.length === 0) return

    const deadline = Date.now() + timeoutMs
    await Promise.all(controllers.map((ac) => {
      return new Promise((res) => {
        const remaining = Math.max(0, deadline - Date.now())
        setTimeout(res, remaining)
      })
    }))
  }
}

In practice, use this from your HTTP layer:

const tracker = new InFlightTracker()

httpServer.on('request', async (req, res) => {
  const id = generateId()
  const ac = tracker.startRequest(id)
  try {
    await handleRequest(req, res, ac.signal)
  } finally {
    tracker.finishRequest(id)
  }
})

Pattern 3 — Transactional commits with write-ahead logs (WAL)

To avoid corruption on random crashes, use a simple WAL: write intent, flush to durable store, then apply. This lets restart logic replay in a deterministic order and keep commits idempotent.

// a tiny WAL interface and typed entry
type WALKey = string

interface WalEntry {
  id: string // unique transaction id
  type: string
  payload: T
}

interface WAL {
  append(entry: WalEntry): Promise
  flush(): Promise
  replay(handler: (entry: WalEntry) => Promise): Promise
}

The commit process becomes two-phase and idempotent:

1. Append 'prepare' entry to WAL with transaction id
2. Flush WAL to disk
3. Apply the change to live system (or call remote service)
4. Append 'commit' entry and flush

async function commitTransaction(wal: WAL, txId: string, payload: any, apply: () => Promise) {
  const prepare: WalEntry = { id: txId, type: 'prepare', payload }
  await wal.append(prepare)
  await wal.flush()

  // idempotently apply
  await apply()

  const commit: WalEntry = { id: txId, type: 'commit', payload: null }
  await wal.append(commit)
  await wal.flush()
}

On restart, replay WAL and apply any prepared-but-not-committed entries. By using unique transaction ids and checking for existing commits during replay, the commit becomes idempotent.

Pattern 4 — Strong lifecycle types with TypeScript

Preventing invalid calls at compile time is the most powerful defense. We model lifecycle states as a generic parameter and annotate methods with a this-type bound so only allowed states can call them.

type State = 'INIT' | 'RUNNING' | 'SHUTTING_DOWN' | 'TERMINATED'

class TypedService {
  private state!: S

  // only callable on INIT
  async start(this: TypedService<'INIT'>): Promise> {
    // initialize resources
    const svc = (this as unknown) as TypedService<'RUNNING'>
    svc.state = 'RUNNING'
    return svc
  }

  // only callable on RUNNING
  handleRequest(this: TypedService<'RUNNING'>, req: any) {
    // handle work
  }

  // callable on RUNNING or INIT -> transitions to SHUTTING_DOWN
  async shutdown(this: TypedService<'RUNNING' | 'INIT'>): Promise> {
    // start shutdown coordinator, stop accepting new work
    const svc = (this as unknown) as TypedService<'SHUTTING_DOWN'>
    svc.state = 'SHUTTING_DOWN'
    return svc
  }

  // finalizer
  finalize(this: TypedService<'SHUTTING_DOWN'>): TypedService<'TERMINATED'> {
    const svc = (this as unknown) as TypedService<'TERMINATED'>
    svc.state = 'TERMINATED'
    return svc
  }
}

// Usage:
async function main() {
  const s0 = new TypedService<'INIT'>()
  const s1 = await s0.start()
  s1.handleRequest({})
  const s2 = await s1.shutdown()
  const s3 = s2.finalize()
}

type Resources = {
  db: { query: (sql: string) => Promise }
  cache: { get: (k: string) => Promise }
}

// when stopped, resources are null; when running, they are present
type ResourceHandles, S extends State> = {
  [K in keyof R]: S extends 'RUNNING' ? R[K] : R[K] | null
}

class ResourceService {
  resources!: ResourceHandles
}

// Combining patterns into a minimal service scaffold
class OrchestrationService extends TypedService {
  private shutdown = new ShutdownCoordinator()
  private tracker = new InFlightTracker()
  private wal: WAL

  constructor(wal: WAL) {
    super()
    this.wal = wal
  }

  async start(this: OrchestrationService<'INIT'>) {
    // replay any WAL state before starting
    await this.wal.replay(async (e) => {
      if (e.type === 'prepare') await applyPrepared(e)
      // skip already committed
    })
    return super.start()
  }

  async handleHttp(req: any, res: any) {
    if (this.shutdown.isShuttingDown()) {
      res.statusCode = 503
      res.end('shutting down')
      return
    }

    const id = generateId()
    const ac = this.tracker.startRequest(id)
    try {
      await processRequest(req, ac.signal, this.wal)
    } finally {
      this.tracker.finishRequest(id)
    }
  }

  async initiateShutdown(reason?: string) {
    await this.shutdown.startShutdown(reason)
    // ask in-flight to drain
    await this.tracker.awaitDrain(15_000)
    // finalize WAL or other durable work
    await this.wal.flush()
  }
}