services/registry-augmentation

Purpose

This module is a TypeScript declare module augmentation. It adds the userService slot to the canonical ServiceRegistry interface owned by @suaveplan/api-plugin/service-registry so downstream plugins that import @suaveplan/api-plugin-user for its side effects see ctx.getService("userService") resolve to UserService | undefined without a cast.

Features

One side-effect import of this file (which the package root barrel performs automatically) gives every consumer typed access to the userService slot.
Mirrors the auth plugin's registry-augmentation pattern so a future project-wide audit can grep every plugin's registry slot from a single regex.
Declaration merging means the augmentation composes safely with every other plugin's registry-augmentation file — the host's ServiceRegistry is the union of all loaded plugins' slots.

Usage: Basic

import "@suaveplan/api-plugin-user/services/user-service";
// `ctx.getService("userService")` now types as `UserService | undefined`.

The package root barrel already imports this file for its side effects — explicit import is only required when the consumer pulls the user-service file directly via the subpath export.

Usage: Advanced

Downstream plugins that depend on the user service can resolve it inside their own onInit:

const userService = ctx.getService("userService");
if (!userService) {
    throw new PluginError(PLUGIN_CODES.SERVICE_NOT_AVAILABLE, "userService");
}
const profile = await userService.getById(principal.id);

API Reference

The module has no runtime exports — it is a pure type-level augmentation. The augmentation adds:

declare module "@suaveplan/api-plugin/service-registry" {
    interface ServiceRegistry {
        userService: UserService;
    }
}

Implementation Notes

The augmentation is intentionally minimal — host-side slots (app, openAPIRegistry, migrationRunner, db) are declared by the auth plugin's augmentation and merged in by TypeScript.
The side-effect import in src/index.ts is what makes the augmentation visible to consumers; removing it would silently weaken typing.
This file MUST NOT carry runtime code — Vite would emit a chunk with no exports otherwise.

2.3 KiB Raw Blame History