Bots, colas y CLI

Las actualizaciones de bots, los trabajos en cola y los comandos de CLI son operaciones asíncronas acotadas. Los ejemplos crean un scope por cada actualización, trabajo o comando y usan await using cuando la función es dueña de toda la operación.

Comparten examples/_shared/container.ts. Compara la unidad de trabajo que cada biblioteca entrega al código de la aplicación.

Ejemplo	Muestra
telegraf.ts	Scope de actualización de Telegraf
grammy.ts	Scope de actualización de Grammy
bullmq.ts	Scope de trabajo de BullMQ
commander.ts	Scope de comando de Commander
yargs.ts	Scope de comando de Yargs

Telegraf

import { Telegraf, type Context, type MiddlewareFn } from 'telegraf'

import {
  buildRootContainer,
  createRequestScope,
  type RequestContainer,
} from '../_shared/container.js'

const root = buildRootContainer()

type BotContext = Context & {
  container: RequestContainer
}

const withContainer: MiddlewareFn<BotContext> = async (ctx, next) => {
  // Re-use the shared per-request scope shape: `update_id` becomes the
  // requestId, the Telegram user id becomes the userId. This way the
  // shared services (Logger, AuditService) get the same fields they would
  // see in HTTP request context.
  await using scope = await createRequestScope(root, {
    requestId: String(ctx.update.update_id),
    userId: ctx.from?.id !== undefined ? String(ctx.from.id) : undefined,
  })

  ctx.container = scope
  await next()
}

export const bot = new Telegraf<BotContext>(process.env.BOT_TOKEN!)

bot.use(withContainer)
bot.start(async (ctx) => {
  const profile = await ctx.container.get('users').profile(String(ctx.from?.id ?? 'anonymous'))
  await ctx.reply(`Hello ${profile.name}`)
})

Archivo del repositorio: examples/workers-cli/telegraf.ts

Grammy

import { Bot, type Context, type MiddlewareFn } from 'grammy'

import {
  buildRootContainer,
  createRequestScope,
  type RequestContainer,
} from '../_shared/container.js'

const root = buildRootContainer()

type BotContext = Context & {
  container: RequestContainer
}

const withContainer: MiddlewareFn<BotContext> = async (ctx, next) => {
  await using scope = await createRequestScope(root, {
    requestId: String(ctx.update.update_id),
    userId: ctx.from?.id !== undefined ? String(ctx.from.id) : undefined,
  })

  ctx.container = scope
  await next()
}

export const bot = new Bot<BotContext>(process.env.BOT_TOKEN!)

bot.use(withContainer)
bot.command('help', async (ctx) => {
  const profile = await ctx.container.get('users').profile(String(ctx.from?.id ?? 'anonymous'))
  await ctx.reply(`Chat profile: ${profile.name}`)
})

Archivo del repositorio: examples/workers-cli/grammy.ts

BullMQ

import { Worker, type Job } from 'bullmq'

import {
  buildRootContainer,
  createRequestScope,
} from '../_shared/container.js'

const root = buildRootContainer()

export const worker = new Worker('email', async (job: Job<{ to: string }>) => {
  // Reuse the same per-request shape for jobs: jobId → requestId, payload
  // recipient → userId so AuditService records pick up the right user.
  await using scope = await createRequestScope(root, {
    requestId: job.id ?? `job:${job.name}`,
    userId: job.data.to,
  })

  scope.get('audit').record('email.sent', { name: job.name, to: job.data.to })
  // Real implementation would call scope.get('mailer').send(job.data).
})

Archivo del repositorio: examples/workers-cli/bullmq.ts

Commander

import { Command } from 'commander'

import { buildRootContainer } from '../_shared/container.js'

const root = buildRootContainer()

export const program = new Command()

program
  .command('import-users <file>')
  .option('--dry-run')
  .action(async (file: string, options: { dryRun?: boolean }) => {
    // A CLI invocation is a bounded async unit: `await using` ties scope
    // disposal to the action function's exit (success or throw), so the
    // async `Database` factory in the shared root is closed before the
    // process exits.
    await using scope = root.createScope()
    const ctx = scope.get('request')
    ctx.requestId = `cli:import-users:${Date.now()}`

    scope.get('audit').record('cli.import-users.start', {
      file,
      dryRun: options.dryRun === true,
    })

    // Real implementation would stream `file` through scope.get('users')
    // and write to scope.get('db'). The minimal demo just logs.
    scope.get('audit').record('cli.import-users.done', { file })
  })

Archivo del repositorio: examples/workers-cli/commander.ts

Yargs

import yargs from 'yargs'
import { hideBin } from 'yargs/helpers'

import { buildRootContainer } from '../_shared/container.js'

const root = buildRootContainer()

export const cli = yargs(hideBin(process.argv))
  .command(
    'sync <target>',
    'Sync a target',
    (builder) =>
      builder
        .positional('target', { type: 'string', demandOption: true })
        .option('verbose', { type: 'boolean', default: false }),
    async (argv) => {
      // Each CLI invocation owns a fresh scope; `await using` disposes the
      // shared `Database` factory deterministically before the action
      // resolves (and therefore before the Node process exits).
      await using scope = root.createScope()
      scope.get('request').requestId = `cli:sync:${Date.now()}`

      scope.get('audit').record('cli.sync', {
        target: argv.target,
        verbose: argv.verbose,
      })
    },
  )
  .strict()

Archivo del repositorio: examples/workers-cli/yargs.ts