# `services/registry-augmentation`

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

Augments the `ServiceRegistry` interface from `@suaveplan/api-plugin` to register the `db` slot typed as `@suaveplan/db`'s `DatabaseAdapter`. Module augmentation is the canonical suaveplan pattern for cross-plugin typed services: it keeps `ctx.getService("db")` strongly typed without forcing every consumer to import a plugin-specific type and without leaking the implementation through the augmentation. Downstream plugins (e.g. `api-plugin-user`, future `api-plugin-tenant`) consume the slot purely by importing this module's barrel side effect.

The file is intentionally minimal: a single `declare module` block plus an empty `export {}` so module resolution treats it as a module rather than a script. Importing it from the package root barrel is a free type-only side effect at runtime.

## Features

- Adds `db: DatabaseAdapter` to the shared `ServiceRegistry`.
- Zero runtime cost — pure type augmentation.
- Re-imported via the package root barrel so consumers get the slot for free with `import "@suaveplan/api-plugin-database"`.

## Usage: Basic

```ts
import "@suaveplan/api-plugin-database";

declare module "@suaveplan/api-plugin/service-registry" {
    // db is already registered by the import above.
}

const db = ctx.getService("db"); // typed as DatabaseAdapter | undefined
```

## Usage: Advanced

```ts
import "@suaveplan/api-plugin-database/services/registry-augmentation";
import type { DatabaseAdapter } from "@suaveplan/db";

async function withTx<T>(
    ctx: PluginContext,
    fn: (db: DatabaseAdapter) => Promise<T>
): Promise<T> {
    const db = ctx.getService("db");
    if (db === undefined) throw new Error("db service not registered");
    return db.transaction(fn);
}
```

## API Reference

No runtime exports. The file augments `ServiceRegistry["db"]` at the type level.

## Implementation Notes

- The augmentation imports `DatabaseAdapter` as a type-only reference. The runtime cost of importing the module is zero.
- The plugin descriptor (in `plugin/plugin.ts`) imports this module as a side effect so consumers that pull the descriptor in get the augmentation transitively.
- Augmenting through a single canonical file (rather than each plugin) prevents duplicate-slot drift — any future package wanting to override or extend `db` would have to do so explicitly.