Configuration

Environment files, package auto-loading, and runtime dynamic configs.

Configuration

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 }
})

Complete Example

import { z } from 'zod'
import { MicroDynamicConfigsServer } from '@hile/micro-dynamic-configs'

const schema = z.object({
  featureCheckout: z.boolean().default(false),
  maxRetries: z.number().int().min(1).max(10).default(3),
})

const configs = new MicroDynamicConfigsServer({
  app,
  redis,
  schema,
  redis_key: 'configs:checkout',
})

const cleanup = await configs.initialize()
shutdown(cleanup)

configs.on('change:featureCheckout', (next, previous) => {
  logger.info({ previous, next }, 'featureCheckout changed')
})

await configs.save({ featureCheckout: true })

Failure And Cleanup Behavior

• save() validates fields before mutating memory.
• Redis is written before memory and event emission update.
• initialize() publishes every config field as a topic.
• Cleanup unpublishes topics and removes listeners.

Runtime And Lifecycle Notes

• MessageLoader maps *.msg.* files to routes using @hile/loader.
• MessageLoader.dispatch(path, data, extras?) invokes the matched handler.
• MessageModem._send() returns a Promise.
• MessageModem._send() and _push() use a 30_000 ms timeout when none is provided. An explicit timeout must be a safe integer from 1 through 2_147_483_647; invalid values throw TypeError before a message is sent.
• MessageModem._stream() returns a Node Readable in object mode.
• Stream timeout and idleTimeout values use the same 1 through 2_147_483_647 ms range. The stream window must be a safe integer from 1 through 64 and defaults to 1.
• Each modem schedules request, total-stream, and idle-stream deadlines through one internal deadline scheduler. This reduces active Node.js timers without changing timeout, cancellation, ordering, or error semantics.
• @hile/message-ws keeps public decodeMessageFrame() payloads isolated from caller-owned input by default. Its owned WebSocket RawData path uses a zero-copy binary Flight payload view internally.
• A stream request requires exec() to return an async iterable.
• Application.call(namespace, url, data, options) requires options.context and returns a promise.
• Application.stream(namespace, url, data, options) requires options.context and returns a readable stream.
• Application.publish(topic, payload) returns an object with update() and unpublish().
• Application.subscribe(topic, callback) returns an unsubscribe function.
• Registry stores service addresses and retained config/topic state under ~/.registry.