@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	Model and context

Use When

Use @hile/model for reusable business logic. Use @hile/context to create immutable, versioned context data that an application explicitly carries through HTTP ingress, models, Micro calls, RSC, and queue jobs.

@hile/context has no ambient store and owns no AsyncLocalStorage. Context identity is protocol data, not module-instance identity.

Do Not Use When

• Do not use context as a mutable application state container.
• Do not put business fields into a framework-owned global schema; each application owns its context values.
• Do not use ambient state to cross a bundle, Worker, VM, plugin, or transport boundary.

Install

pnpm add @hile/model @hile/context

Imports

import { defineActionModel, defineModel, loadModel } from '@hile/model'
import {
  createExecutionContext,
  createInvocationContext,
  deriveExecutionContext,
  parseExecutionContext,
  pickExecutionContext,
  requireExecutionContextValues,
  withExecutionContextLogger,
  type ExecutionContext,
  type InvocationContext,
} from '@hile/context'

Copy-Paste Example

import { randomUUID } from 'node:crypto'
import { createExecutionContext, createInvocationContext } from '@hile/context'

const invocation = createInvocationContext(
  createExecutionContext({ requestId: randomUUID() }),
  new AbortController().signal,
)

Values must be JSON-compatible plain data. Creation snapshots and deeply freezes them. parseExecutionContext() validates untrusted or transported values and rejects unsupported protocol versions.

More Examples

Pipelines receive the same value as ctx.invocation:

export const findUser = defineModel({
  pipelines: [
    async (ctx, next) => {
      requireExecutionContextValues(ctx.invocation.context, ['tenantId'])
      await next()
    },
  ],
  async main(input: { userId: string }, invocation) {
    return findTenantUser(invocation.context.values.tenantId, input.userId)
  },
})

Action models use the same contract:

export default defineActionModel(async (input: { value: number }, invocation) => {
  invocation.signal.throwIfAborted()
  return { value: input.value + 1 }
})

Runtime And Lifecycle Notes

• Every business invocation has an explicit ExecutionContext and AbortSignal.
• Establishment, derivation, transport, and consumption operate on versioned data rather than a shared module singleton.
• Independently evaluated copies of @hile/context interoperate structurally.
• Context is immutable and cannot leak between concurrent requests.
• Missing or unsupported context fails with a stable diagnostic error instead of becoming {}.
• Model pipeline and main receive the same invocation object.

Anti-Patterns

• Hiding context in module globals, singleton containers, or AsyncLocalStorage.
• Calling loadModel() without an invocation.
• Adding context fields to business payloads merely to compensate for missing transport support.
• Sending the whole context when only a subset is required.
• Logging entire context objects by default.

Verification Checklist

• Create context once at each ingress boundary.
• Pass it explicitly to Model, Micro, RSC, Queue, and Logger APIs.
• Validate transported context with parseExecutionContext().
• Use structured-cloneable, JSON-compatible values only.
• Assert missing context fails before side effects.
• Test independent module instances and concurrent invocations.

Related Recipes

HTTP API + Model + TypeORM

Complete Example

Controller:

// src/controllers/users/[id].controller.ts
import { randomUUID } from 'node:crypto'
import { createExecutionContext, createInvocationContext } from '@hile/context'
import { defineController } from '@hile/http'
import { loadModel } from '@hile/model'
import { getUser } from '../../models/users/get-user.model'

export default defineController('GET', async (ctx) => {
  const invocation = createInvocationContext(
    createExecutionContext({ requestId: randomUUID() }),
    new AbortController().signal,
  )
  return loadModel(getUser, { userId: String(ctx.params.id) }, invocation)
})

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.