# @mostajs/data-plug — fiche LLM
> Prise d'accès aux données — backend interchangeable (ORM direct / proxy REST) décidé par l'env MOSTA_DATA.

- Version: 1.2.5 · Licence: AGPL-3.0-or-later · Auteur: Dr Hamid MADANI <drmdh@msn.com>
- Chemin: mostajs/mosta-data-plug · Statut audit: complet (dist/)

## RÔLE
Couche d'aiguillage (« switcher ») entre deux modes d'accès aux données, transparente pour
l'appelant : `MOSTA_DATA=orm` (accès direct DB via @mostajs/orm) ou `MOSTA_DATA=net`
(transport distant via @mostajs/net : REST/GraphQL/gRPC/WS/MCP). Le code consommateur
(@mostajs/auth, rbac, audit, settings…) appelle `getDialect()` sans savoir à qui il parle.
Fournit aussi : registre multi-dialecte nommé, dialecte SYSTÈME séparé du singleton métier
(apikeys/RBAC/audit/plans), et auto-enregistrement d'apikey via @mostajs/auth-flow (device flow).

## INSTALLATION
npm i @mostajs/data-plug
(peerDeps optionnels : @mostajs/orm >=1.13.0, @mostajs/net >=2.0.0,
@mostajs/auth-flow >=0.1.0-alpha.3 — installer selon le mode utilisé)

## EXPORTS
- Dialecte métier : getDialect, setDialect, resetDialect, disconnect, openIsolatedDialect
- Mode : getDataMode, isNetMode, isOrmMode
- Registre nommé : registerNamedConnection, getNamedConnection, listNamedConnections,
  removeNamedConnection, clearNamedConnections
- Dialecte système (v1.2.2+) : getSystemDialect, bootstrapSystemDialect, setSystemDialect,
  resetSystemDialect
- Apikey / auth (v1.2.1+) : ensureApiKey, clearCachedApiKey
- Ré-exports @mostajs/orm : BaseRepository, normalizeDoc, normalizeDocs, registerSchema,
  registerSchemas, getSchema, getSchemaByCollection, getAllSchemas, getEntityNames,
  hasSchema, validateSchemas, clearRegistry
- Types : IDataDialect, DataMode, EnsureApiKeyOptions ; ré-exports orm : IDialect,
  EntitySchema, FilterQuery, QueryOptions, IRepository, FieldDef, FieldType, RelationDef,
  RelationType, IndexDef

## API — SIGNATURES
- getDataMode(): DataMode  ('orm' | 'net', d'après MOSTA_DATA) ; isNetMode() ; isOrmMode()
- getDialect(): Promise<IDataDialect>  — singleton global, survit aux ré-imports / bundler
- setDialect(d): void  — injecte un dialecte externe (test / custom)
- resetDialect(): void  — vide le singleton (NE ferme pas la connexion)
- disconnect(): Promise<void>  — ferme la connexion physique puis vide le cache
- openIsolatedDialect(config, schemas?): Promise<IDataDialect>  — connexion neuve dédiée, hors singleton
- registerNamedConnection(name, dialect): Promise<void>  ; getNamedConnection(name): Promise<IDataDialect|null>
- listNamedConnections(): Promise<string[]>  ; removeNamedConnection(name) ; clearNamedConnections()
- getSystemDialect(): Promise<IDataDialect>  — dialecte système stable (apikeys/RBAC/audit/plans)
- bootstrapSystemDialect(): Promise<IDataDialect>  — init système au boot (idempotent)
- setSystemDialect(d) / resetSystemDialect()
- ensureApiKey(opts?: EnsureApiKeyOptions): Promise<string>  — apikey valide pour Octonet
- clearCachedApiKey(opts?: { host? }): Promise<void>

## TYPES CLÉS
- DataMode = 'orm' | 'net'
- IDataDialect : contrat minimal identique à IDialect de @mostajs/orm (find, findOne, findById,
  create, update, updateMany, delete, deleteMany, count, distinct, aggregate, findWithRelations,
  findByIdWithRelations, upsert, increment, addToSet, pull, search) — implémenté par les
  dialectes ORM ET par les proxies NET.
- EnsureApiKeyOptions : { onCodeIssued?, clientId?, scope?, host?, store?, forceRefresh? }
- Variables d'env clés : MOSTA_DATA (orm|net), DB_DIALECT + SGBD_URI (mode orm),
  MOSTA_NET_URL + MOSTA_NET_TRANSPORT (mode net), MOSTA_SYSTEM_DIALECT + MOSTA_SYSTEM_URI
  (dialecte système), MOSTA_AUTH_FLOW_URL, MOSTA_NET_API_KEY, MOSTA_HOST, MOSTA_NO_AUTOREGISTER.

## PATTERN
```ts
import { getDialect, getSystemDialect, bootstrapSystemDialect } from '@mostajs/data-plug';

// au boot de l'app, AVANT les middlewares consommateurs
await bootstrapSystemDialect();

// code métier — ne sait pas si c'est ORM direct ou proxy NET
const dialect = await getDialect();
const users = await dialect.find(UserSchema, { active: true });

// services système (apikeys, RBAC, audit) — dialecte stable
const sys = await getSystemDialect();
```

## DÉPEND DE
- @mostajs/config, @mostajs/net-client-js (dependencies directes)
- peerDeps optionnels selon le mode : @mostajs/orm (mode orm), @mostajs/net (mode net),
  @mostajs/auth-flow (auto-enregistrement apikey / device flow)

## PIÈGES
- `getDialect()` est un singleton process-global ; `resetDialect()` vide le cache mais NE
  ferme PAS la connexion — utiliser `disconnect()` pour fermer physiquement (ex : l'admin
  a changé `SGBD_URI` au runtime).
- `getSystemDialect()` ne bouge JAMAIS même si la base métier est mutée au runtime ; si
  `bootstrapSystemDialect()` n'a pas été appelé, fallback transparent vers le singleton métier.
- Appeler `bootstrapSystemDialect()` AVANT d'instancier les middlewares consommateurs
  (apikey-middleware, rbac, audit).
- `ensureApiKey` : ordre de résolution = forceRefresh > MOSTA_NET_API_KEY > cache local
  ~/.config/<host>/auth.json > (throw si MOSTA_NO_AUTOREGISTER) > device flow interactif.
- `forceRefresh: true` ignore le cache ET MOSTA_NET_API_KEY ET MOSTA_NO_AUTOREGISTER.
- `MOSTA_AUTH_FLOW_URL` est distinct de `MOSTA_NET_URL` (v1.2.1+) — privilégier le premier
  pour le device flow ; `MOSTA_NET_URL` n'est qu'un fallback rétro-compat.

## RÉFÉRENCES
- README.md · docs/PLAN-V1.2.1.md
