Container

Service container examples, lifecycle rules, dependency loading, and cleanup.

Container

Use When

Use these packages when an app needs managed startup, singleton resources, dependency ordering, environment-file loading, graceful shutdown, logs, Redis, or SQL database connections.

Copy-Paste Example

// src/services/http.boot.ts
import { defineService } from '@hile/core'
import { Http } from '@hile/http'

export default defineService('http', async (shutdown) => {
  const http = new Http({ port: Number(process.env.HTTP_PORT ?? 3000) })
  await http.load(new URL('../controllers', import.meta.url).pathname)
  const close = await http.listen()
  shutdown(close)
  return http
})

Run:

hile start --dev --env-file .env

More Examples

Use package.json auto-load for integration services that default-export a Hile service:

{
  "type": "module",
  "scripts": {
    "dev": "hile start --dev --env-file .env",
    "start": "hile start --env-file .env.prod"
  },
  "hile": {
    "auto_load_packages": ["@hile/logger", "@hile/ioredis", "@hile/typeorm"]
  }
}

Inside another service, load dependencies:

import { defineService, loadService } from '@hile/core'
import redisService from '@hile/ioredis'
import typeormService from '@hile/typeorm'

export default defineService('user.service', async () => {
  const [redis, ds] = await Promise.all([
    loadService(redisService),
    loadService(typeormService),
  ])
  return { redis, ds }
})

Runtime And Lifecycle Notes

• defineService(key, fn) registers a service factory and does not execute it.
• loadService(service) executes the factory on first call and returns the cached value afterwards.
• The shutdown callback registers teardown functions; they run in LIFO order.
• The container tracks dependencies when service factories call loadService().
• container.shutdown() triggers registered teardowns.
• @hile/bootstrap loads env files first, sets NODE_ENV, imports auto-load packages, scans boot files, and installs exit hooks.
• @hile/logger.createLogger() returns { logger, teardown }.
• @hile/ioredis.createRedis() waits for connect.
• @hile/typeorm.createDataSource() initializes a TypeORM DataSource.

Anti-Patterns

• Reusing one service key for unrelated factories.
• Missing shutdown() callbacks for network connections or servers.
• Assuming TypeORM env config fills entities automatically when TYPEORM_ENTITIES is not set.
• Calling transaction() and manually committing; the helper commits or rolls back internally.

Verification Checklist

• Boot files default-export defineService(...).
• Long-lived resources register teardown callbacks.
• auto_load_packages contains package names, not local files.
• hile start --dev can find src/**/*.boot.ts.
• Production build emits dist/**/*.boot.js.