service-layer-style

Thread a ServiceCtx object (db, scoped logger, userId, eventSeriesId, correlationId) as the first argument to every service function. Pick pure functions for 1-2 exports, a factory with closure for 3+ methods sharing setup, and escalate to namespace families or generics only when specialization ratios justify it.

Use a factory function returning an object literal whenever multiple methods share setup like a scoped logger, Stripe client, or OTel span. Classes that extend BaseService are forbidden because this.db! non-null assertions hide runtime failures from the type system.

Exporting $inferSelect leaks every persistence column, including deletedAt and internal fields, into the public API, making future column removals breaking changes. Define an explicit DTO type and a toDto() mapper as the single place controlling what leaves the service.

Build a fake ServiceCtx by hand with a fake db and silent logger, then pass it directly to the service function. The ctx parameter is the test seam, so no jest.mock or vi.mock calls on db or logger modules are needed.

Throw DomainError with code, userMessage, and retryable fields, and let the tRPC error pipeline capture it at the outer boundary. Never silently catch and return empty arrays, and never call Sentry.captureException before throwing, which creates duplicate issues.

Run transactions at the service boundary inside the factory method using ctx.db.transaction. Create a fresh ServiceCtx with the transaction client as db and pass it to nested service calls so everything stays inside the transaction.