@hile/ioredis

Create Redis clients manually or as Hile services with lifecycle cleanup.

@hile/ioredis

Create Redis clients manually or as Hile services with lifecycle cleanup.

Choose This Package When

User asks for	Use	Also read
Connect to Redis	@hile/ioredis	packages/core-lifecycle.md, packages/infrastructure.md

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.

Do Not Use When

• Do not use loadService() at module top level.
• Do not use auto_load_packages for file paths. It accepts package names only.
• Do not use the default @hile/ioredis or @hile/typeorm services when one app needs multiple Redis or database connections; define separate services with separate keys.

Install

pnpm add @hile/core @hile/logger @hile/ioredis @hile/typeorm
pnpm add -D @hile/cli

Imports

import { defineService, loadService, container } from '@hile/core'
import { createLogger } from '@hile/logger'
import redisService, { createRedis } from '@hile/ioredis'
import typeormService, { createDataSource, transaction } from '@hile/typeorm'

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.

Related Recipes

Redis Cache With Singleflight

Complete Example

import { loadService } from '@hile/core'
import redisService from '@hile/ioredis'
import { Cache, defineCache, RedisCache } from '@hile/cache'

const userProfileCache = defineCache(
  'user:{id:string}:profile',
  async ({ id }) => {
    const profile = await loadProfileFromDatabase(id)
    if (!profile) return new Cache(undefined)
    return new Cache(profile).setExpire(300)
  },
  {
    singleflight: { ttl: 10_000, wait: 10_000 },
    stale: { ttl: 60 },
    negative: { ttl: 30 },
    tags: (params, data) => data ? [`user:${params.id}`] : [],
  },
)

const redis = await loadService(redisService)
const cache = new RedisCache('app:', redis)
const userProfiles = await cache.loadCache(userProfileCache)

const profile = await userProfiles.read({ id: 'u1' })
await userProfiles.remove({ id: 'u1' })
await cache.removeTag('user:u1')

Package-Local AI Guide

This package also ships AI.md in npm so agents can read accurate examples after installation.