triad-services

Services + Dependency Injection

Triad has one DI primitive: ctx.services — a ServiceContainer object you define and then expose to every handler. The goal is that handlers access ctx.services.petRepo.create(...) with full types and no import in the endpoint file.

1. Define your services interface + factory

// src/services.ts
import { PetRepository } from './repositories/pet.js';
import { AdopterRepository } from './repositories/adoption.js';
import type { Db } from './db/client.js';

export interface PetstoreServices {
  db: Db;
  petRepo: PetRepository;
  adopterRepo: AdopterRepository;
}

export function createServices({ db }: { db: Db }): PetstoreServices {
  return {
    db,
    petRepo: new PetRepository(db),
    adopterRepo: new AdopterRepository(db),
  };
}

2. Module-augment ServiceContainer

This is the single place where your container type is declared globally. Put it in src/services.ts alongside the factory:

declare module '@triadjs/core' {
  interface ServiceContainer extends PetstoreServices {}
}

After this, ctx.services.petRepo is typed in every handler with no import required in the endpoint file. If you forget this, ctx.services is {} and every access is a compile error.

3. Wire the adapter

Fastify

// src/server.ts
import Fastify from 'fastify';
import { triadPlugin } from '@triadjs/fastify';
import router from './app.js';
import { createServices } from './services.js';
import { createDatabase } from './db/client.js';

const app = Fastify({ logger: true });
const db = createDatabase(process.env.DATABASE_URL ?? ':memory:');
await app.register(triadPlugin, { router, services: createServices({ db }) });
await app.listen({ port: 3000 });

Express

import express from 'express';
import { createTriadRouter } from '@triadjs/express';
import router from './app.js';
import { createServices } from './services.js';
import { createDatabase } from './db/client.js';

const app = express();
app.use(express.json());
app.use(createTriadRouter(router, { services: createServices({ db: createDatabase() }) }));
app.listen(3000);