71 lines
2.3 KiB
Markdown
71 lines
2.3 KiB
Markdown
# 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
|
|
|
|
```ts
|
|
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`:
|
|
|
|
```ts
|
|
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:
|
|
|
|
```ts
|
|
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.
|