@hile/model

Put reusable business logic behind typed models with services and pipeline middleware.

@hile/model

Put reusable business logic behind typed models with services and pipeline middleware.

Choose This Package When

User asks for	Use	Also read
Put business logic somewhere reusable	@hile/model	packages/model-context.md

Use When

Use @hile/model for reusable business logic and @hile/context for request/work-unit context that should flow through async calls, micro messages, and queue jobs.

Do Not Use When

• Do not put business logic only in controllers when it will be reused by jobs, pages, or message handlers.
• Do not add fixed business fields to @hile/context; each app owns its context shape.

Install

pnpm add @hile/model @hile/context

Imports

import { defineModel, loadModel } from '@hile/model'
import { contextHttp, contextModel, getContext, requireContext, runWithContext } from '@hile/context'

Copy-Paste Example

import { defineModel } from '@hile/model'

export default defineModel(async (input: { name: string }) => {
  return { greeting: `Hello ${input.name}` }
})

Use it:

const result = await loadModel(greetModel, { name: 'Ada' })

More Examples

import { defineModel } from '@hile/model'
import typeormService from '@hile/typeorm'

export const findUser = defineModel({
  services: [typeormService] as const,
  pipelines: [
    async (ctx, next) => {
      if (!ctx.args.userId) throw new Error('userId is required')
      await next()
    },
  ],
  async main([ds], input: { userId: string }) {
    return ds.getRepository(User).findOneBy({ id: input.userId })
  },
})

Context in HTTP:

http.use(contextHttp({
  read: (ctx) => ({ requestId: String(ctx.headers['x-request-id'] ?? crypto.randomUUID()) }),
  write: (context, ctx) => ctx.set('x-request-id', String(context.requestId ?? '')),
}))

Context in model pipeline:

const withTenant = contextModel<{ tenantId: string }>({
  read: (input) => ({ tenantId: input.tenantId }),
})

Runtime And Lifecycle Notes

• loadModel(model, input) rejects if the first argument was not created by defineModel().
• Model input must be an object.
• Services are loaded in the order of the services tuple.
• Pipeline middleware follows Koa-style await next().
• The terminal model result is stored in ctx.state.result and returned by loadModel().
• runWithContext() merges with parent context by default; pass { merge: false } to replace.
• getContext() returns a frozen shallow snapshot.
• requireContext(keys) throws when selected keys are missing.

Anti-Patterns

• Passing primitives to loadModel().
• Mutating context snapshots.
• Logging whole context objects by default.
• Assuming context propagation changes business payloads; it should stay in metadata or async storage.

Verification Checklist

• Models export defineModel(...) results.
• Controllers and pages call loadModel(model, objectInput).
• Pipeline middleware writes derived state to ctx.state.
• Context keys are app-defined and JSON-serializable when crossing process boundaries.

Related Recipes

HTTP API + Model + TypeORM

Complete Example

Controller:

// src/controllers/users/[id].controller.ts
import { defineController } from '@hile/http'
import { loadModel } from '@hile/model'
import { getUser } from '../../models/users/get-user.model'

export default defineController('GET', async (ctx) => {
  return loadModel(getUser, { userId: String(ctx.params.id) })
})

Model:

// src/models/users/get-user.model.ts
import { defineModel } from '@hile/model'
import typeormService from '@hile/typeorm'
import { User } from '../../entities/user.entity'

export const getUser = defineModel({
  services: [typeormService] as const,
  async main([ds], input: { userId: string }) {
    const user = await ds.getRepository(User).findOneBy({ id: input.userId })
    if (!user) return { found: false }
    return { found: true, user }
  },
})

Boot file:

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

Package config:

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

Package-Local AI Guide

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