Contracts
A contract is an interface: a list of what a service can do, without saying how. The framework’s logger, cache, mailer and clock are each described by a contract, and the app gets a concrete implementation through the service container. Your code can depend on the contract, so you can switch the implementation (a different mailer, a fake in tests) without touching the code that uses it.
The smallest example
Section titled “The smallest example”Depend on the Logger contract, not on a particular logger:
import { LoggerToken, type Logger } from '@strutvane/framework'
export class ReportService { static readonly inject = [LoggerToken] as const readonly #log: Logger
constructor(log: Logger) { this.#log = log }
build(): void { this.#log.info('Report built') }}What you’ll see: in the app, the line goes to your log files; in a test that binds a MemoryLogger, it’s captured in memory where the test can read it. ReportService didn’t change.
The contracts
Section titled “The contracts”| Contract | Token | What it promises | Default implementation |
|---|---|---|---|
Logger |
LoggerToken |
info, warn, error with a context object (the full level list arrives with the logging channels) |
the framework logger (channels from .env) |
clock: () => Date |
ClockToken |
the current time | the system clock |
RateLimitStore |
RateLimitStoreToken |
count hits per key in a window | the cache (memory in the prototype) |
IdempotencyStore |
IdempotencyStoreToken |
keep first responses per key | memory in the prototype |
UserProvider |
UserProviderToken |
find the user for a token | @strutvane/auth |
SessionStore |
SessionStoreToken |
sessions that can be flushed | @strutvane/auth’s database store |
| cache, mailer, queue, event dispatcher, file storage, HTTP client | one token each | as their pages describe | arrive with each feature |
The exact list for 0.2 will be in @strutvane/framework/contracts; node strut about will show what’s bound.
Providing your own implementation
Section titled “Providing your own implementation”-
Write a class that implements the contract:
app/services/console-logger.ts import type { Logger } from '@strutvane/framework'export class ConsoleLikeLogger implements Logger {info(message: string, context = {}): void { process.stdout.write(`${message} ${JSON.stringify(context)}\n`) }warn(message: string, context = {}): void { process.stderr.write(`${message} ${JSON.stringify(context)}\n`) }error(message: string, context = {}): void { process.stderr.write(`${message} ${JSON.stringify(context)}\n`) }} -
Bind it to the contract’s token in a provider’s
register():app/providers/app.provider.ts import { LoggerToken, ServiceProvider, type Application } from '@strutvane/framework'import { ConsoleLikeLogger } from '../services/console-logger.ts'export class AppServiceProvider extends ServiceProvider {override register(app: Application): void {app.container.singleton(LoggerToken, () => new ConsoleLikeLogger())}}
What you’ll see: everything that injects LoggerToken (the framework too) now writes through your class. If your class misses a method, it doesn’t compile: implements Logger checks it.
(This replaces the framework’s logger entirely, losing channels and redaction; it’s only an illustration. To change where logs go, configure channels instead: Logging.)
Contracts in tests
Section titled “Contracts in tests”import { randomBytes } from 'node:crypto'import { expect, test } from 'vitest'import { LoggerToken, MemoryLogger } from '@strutvane/framework'import { ReportService } from '../../app/services/report.service.ts'import { createApp } from '../../bootstrap/app.ts'
test('building a report logs it', async () => { const app = createApp({ APP_ENV: 'testing', APP_KEY: `base64:${randomBytes(32).toString('base64')}`, DB_CONNECTION: 'sqlite' }) const log = new MemoryLogger() app.container.instance(LoggerToken, log) await app.boot()
app.make(ReportService).build()
expect(log.entries.map((entry) => entry.message)).toContain('Report built')})What you’ll see with npm test: the test passes, with nothing written to your log files. Bindings made before boot() win over the framework’s defaults.
Contract or concrete class?
Section titled “Contract or concrete class?”| Depend on… | When | Example |
|---|---|---|
| A contract (token + interface) | The implementation may change: per environment, per customer, in tests, or by a package | the logger, the mailer, a payment gateway, your own Notifier |
| A concrete class | There’s exactly one implementation and it’s yours | PostStats, InvoiceNumberGenerator |
| A facade | Short code that isn’t a class you control (a route closure, a seeder) | Log.info(…) (Facades) |
Rules of thumb:
- Start concrete. Inject your own class directly (the container builds it from
static inject). Introduce a contract when a second implementation appears, not before. - Packages depend on contracts. A package shouldn’t import another package’s classes: it asks for a token, so any implementation can be bound. That’s how Strutvane’s own packages stay independent.
- Keep contracts small. A contract with three methods is easy to implement and to fake; one with thirty isn’t.
Your own contract
Section titled “Your own contract”import { token } from '@strutvane/framework'
export interface Notifier { notify(message: string): Promise<void>}
export const NotifierToken = token<Notifier>('Notifier')Bind an implementation per environment in a provider, and inject NotifierToken where you need it. See Service Container.
Common mistakes
Section titled “Common mistakes”“Nothing is bound to … in the container”
Section titled ““Nothing is bound to … in the container””✖ Nothing is bound to "Notifier" in the container.→ Bind it in a service provider's register() method, for example: app.container.singleton(NotifierToken, () => …).Why: a contract (a token) has nothing to build from, so it must be bound. (Classes are built automatically; tokens never are.)
Fix: bind an implementation in a provider’s register().
I injected the interface and got undefined
Section titled “I injected the interface and got undefined”Why: an interface doesn’t exist at runtime, so it can’t be a key. static inject = [Logger] refers to nothing.
Fix: inject the token: static inject = [LoggerToken] as const, and type the constructor parameter with the interface.
My fake isn’t used in the test
Section titled “My fake isn’t used in the test”Why: it was bound after the app booted and something had already resolved the real service.
Fix: bind fakes before await app.boot() (or before the first request).
Next steps
Section titled “Next steps”- Service Container: tokens, bindings and injection.
- Service Providers: where bindings live.
- Facades: the short form for the same services.