Kozen trigger

@kozen/trigger — Self-Hosted MongoDB Triggers

@kozen/trigger enables MongoDB Change Stream-based triggers that run on your own infrastructure. Each trigger is a JavaScript/TypeScript delegate file where exported function names map to MongoDB operation types. Kozen manages the Change Stream lifecycle, error recovery, and dependency injection into every handler call.

---

Routing table

Signal	Reference
TriggerModule, ChangeStreamService, ChangeStreamService.start, ChangeStreamService.stop, ChangeStreamService.onChange, ChangeStreamService constructor, ITriggerDelegate, ITriggerOptions, ITriggerTools, all trigger exports, trigger public API, trigger class documentation, trigger:start CLI, trigger:help, trigger CLI flags, trigger MCP, standalone trigger, programmatic trigger, embed trigger, trigger as library, trigger Node.js, start change stream, stop change stream, dispatch rules, handler not found, flow ID trigger	references/api.md
delegate file, event handler, insert handler, update handler, delete handler, replace handler, default handler, on handler, catch-all handler, ITriggerTools assistant db collection flow, resolve service in handler, write to MongoDB from handler, ESM delegate format, CJS delegate format, module.exports delegate, change event structure, updatedFields, fullDocument, operationType, change stream document	references/delegates.md
KOZEN_TRIGGER_FILE, KOZEN_TRIGGER_DATABASE, KOZEN_TRIGGER_COLLECTION, KOZEN_TRIGGER_URI, KOZEN_TRIGGER_KEY, ESM CJS delegate type, delegateType, KOZEN_TRIGGER_DELEGATE_TYPE, .env trigger, trigger environment variables, trigger configuration, ITriggerOptions mdb, PM2 trigger, systemd trigger, Docker trigger, deployment patterns	references/configuration.md

---

When to use this skill

• Writing a delegate file to react to MongoDB change events
• Starting a Kozen trigger from the CLI
• Using ChangeStreamService directly in a Node.js project
• Configuring the module's environment variables in a .env file or CI pipeline
• Understanding how ESM vs CJS delegate loading works

---

Quick start

npm install @kozen/trigger

# Start a trigger (reads KOZEN_TRIGGER_* from .env)
npx kozen --moduleLoad=@kozen/trigger --action=trigger:start --envFile=.env

Minimal .env:

KOZEN_MODULE_LOAD=@kozen/trigger
KOZEN_TRIGGER_DATABASE=mydb
KOZEN_TRIGGER_COLLECTION=orders
KOZEN_TRIGGER_URI=mongodb+srv://user:[email protected]/
KOZEN_TRIGGER_FILE=/absolute/path/to/mydelegate.mjs
KOZEN_LOG_LEVEL=INFO

Minimal ESM delegate (mydelegate.mjs):

export async function insert(change, tools) {
  tools.assistant?.logger?.info({
    flow: tools.flow,
    message: 'New order received',
    data: { doc: change.fullDocument }
  });
}

---

Do & Don't

Do:

• Keep delegate handlers small and idempotent — change streams can replay events.
• Use tools.db or tools.collection for direct MongoDB access inside handlers.
• Include flow: tools.flow in every log call for end-to-end tracing.
• Run the process under PM2, systemd, or a container orchestrator for resilience.
• Use least-privilege credentials: read-only if handlers do not write back.

Don't:

• Never perform heavy synchronous I/O inside a handler; offload to queues or background tasks.
• Never rely on in-memory state between handler invocations (the process may restart).
• Never use relative file paths for KOZEN_TRIGGER_FILE — always absolute paths.