@nodefony/drizzle 10.0.0-alpha.1

package/dist/types/nodefony/src/orm-core/DrizzleTransaction.d.ts

@@ -0,0 +1,71 @@
+import type { ITransaction } from "@nodefony/orm-core";
+import type { DrizzleDb } from "./DrizzleRepository.js";
+/**
+ * Pilotage transactionnel d'**une connexion**, abstrait du driver (INTERNE).
+ *
+ * Existe parce que les trois drivers pilotent une transaction différemment :
+ * `better-sqlite3` est synchrone sur une connexion unique (rien à rendre), là
+ * où `pg` et `mysql2` empruntent une connexion DÉDIÉE à leur pool — qu'il faut
+ * impérativement rendre, sous peine d'épuiser le pool en quelques transactions.
+ * {@link DrizzleTransaction} ne connaît que ce contrat : le choix du driver
+ * appartient à la fabrique posée au connect (cf `DrizzleOrm`).
+ */
+export interface ITxDriver {
+    /** Exécute une instruction de contrôle (`COMMIT`, `SAVEPOINT …`). */
+    exec(sql: string): Promise<void>;
+    /**
+     * Cite un identifiant SQL (nom de savepoint) — **trait de dialecte** :
+     * `"x"` est l'identifiant standard (postgres, sqlite) mais désigne une CHAÎNE
+     * en mysql/mariadb hors mode `ANSI_QUOTES`, qui veut des backticks. D'où la
+     * délégation au driver plutôt qu'un quoting en dur ici.
+     */
+    quoteIdent(name: string): string;
+    /**
+     * Rend la connexion. **`err` renseigné → la connexion est DÉTRUITE**, jamais
+     * recyclée : après un `COMMIT`/`ROLLBACK` en échec, son état transactionnel
+     * est inconnu — la rendre au pool contaminerait l'emprunteur suivant avec une
+     * transaction ouverte. No-op sur une connexion unique (sqlite).
+     */
+    release(err?: unknown): void;
+}
+/**
+ * Adapte une transaction SQL au contrat portable {@link ITransaction}, sur les
+ * trois dialectes (sqlite, postgres, mysql).
+ *
+ * **Pourquoi une transaction manuelle (`BEGIN`/`COMMIT`/`ROLLBACK`) et pas le
+ * helper `db.transaction()` de Drizzle** : `better-sqlite3` est **synchrone** ;
+ * son helper attend un callback synchrone et committe au `return` — donc *avant*
+ * que les `await` du contrat async (`IRepository`) ne s'exécutent. Encadrer le
+ * travail par `BEGIN`…`COMMIT` garantit que toutes les opérations (ordonnées par
+ * les `await`) tombent dans la même transaction.
+ *
+ * **Une transaction vit sur UNE connexion** : {@link DrizzleTransaction.getNative}
+ * rend le db Drizzle lié à cette connexion précise (la connexion unique en
+ * sqlite ; une connexion empruntée au pool en postgres/mysql). Un repository
+ * n'entre dans la transaction que lié par `withTransaction(tx)` — celui rendu par
+ * `orm.getRepository()` passe, lui, par le pool, donc HORS transaction.
+ *
+ * Mode managé (cf `DrizzleOrm.transaction`) : commit auto si la closure résout,
+ * rollback auto si elle rejette. `commit`/`rollback` exposés (idempotents via le
+ * drapeau interne) pour un pilotage manuel éventuel.
+ */
+export declare class DrizzleTransaction implements ITransaction {
+    #private;
+    /**
+     * @param db - handle Drizzle lié à la connexion **déjà en `BEGIN`**.
+     * @param driver - pilotage transactionnel de cette connexion.
+     */
+    constructor(db: DrizzleDb, driver: ITxDriver);
+    /** Indique si la transaction est déjà terminée (commit ou rollback). */
+    isDone(): boolean;
+    /** Valide la transaction (no-op si déjà terminée). */
+    commit(): Promise<void>;
+    /** Annule la transaction (no-op si déjà terminée). */
+    rollback(): Promise<void>;
+    /** Crée un savepoint nommé (nom validé — anti-injection, cf {@link assertSavepointName}). */
+    savepoint(name: string): Promise<void>;
+    /** Annule jusqu'au savepoint sans terminer la transaction (nom validé). */
+    rollbackTo(name: string): Promise<void>;
+    /** Expose le handle Drizzle lié à la connexion encadrée par la transaction. */
+    getNative<C = unknown>(): C;
+}

package/dist/types/nodefony/src/orm-core/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Adapter Drizzle (driver `better-sqlite3`) sur `@nodefony/orm-core` (P7.4).
+ *
+ * adapter du banc multi-ORM ; valide le contrat
+ * sur un ORM type-safe-first et la forme finale des opérateurs riches (ADR-0003).
+ */
+export { DrizzleOrm } from "./DrizzleOrm.js";
+export type { DrizzleOrmOptions } from "./DrizzleOrm.js";
+export { DrizzleRepository } from "./DrizzleRepository.js";
+export type { DrizzleDb, DrizzleTable, DrizzleColumn, DrizzleResolvedRelation, } from "./DrizzleRepository.js";
+export { DrizzleTransaction } from "./DrizzleTransaction.js";

package/dist/types/nodefony/src/queryKit.d.ts

@@ -0,0 +1,136 @@
+import type { IPageQuery } from "nodefony";
+import type { SqlDialect } from "../interfaces/IDrizzleConfig.js";
+import type { DrizzleDb } from "./orm-core/DrizzleRepository.js";
+/**
+ * Cherche l'`id` du user dont le tableau JSON `socialProviders` contient un
+ * lien `{provider, providerId}` — le finder du pattern **Shadow User** OAuth
+ * (`DrizzleUserRepository.findBySocialProvider`).
+ *
+ * Sémantique IDENTIQUE sur tous les dialectes : « il EXISTE un élément du
+ * tableau dont `provider` ET `providerId` valent exactement ces valeurs »
+ * (les autres clés de l'élément, ex. `createdAt`, sont ignorées) :
+ * - **sqlite** : `EXISTS (SELECT 1 FROM json_each(col) WHERE json_extract…)`
+ *   — scan du tableau, valeurs bindées ;
+ * - **postgres** : `col @> '[{"provider":…,"providerId":…}]'::jsonb` —
+ *   containment jsonb natif (indexable GIN), le motif est UN paramètre bindé
+ *   sérialisé JSON ;
+ * - **mysql** : `JSON_CONTAINS(col, <motif>)` — containment JSON natif (même
+ *   sémantique partielle que `@>` : un objet candidat est contenu dans un
+ *   élément du tableau si toutes SES clés y matchent), motif = UN paramètre
+ *   bindé sérialisé JSON, casté par MySQL.
+ *
+ * @param db - handle Drizzle natif (racine ou transaction) du dialecte.
+ * @param dialect - dialecte SQL du connecteur.
+ * @param provider - fournisseur d'identité (`"github"`, `"google"`…).
+ * @param providerId - identifiant du compte CHEZ le fournisseur.
+ * @returns l'`id` du user lié, ou `null` si aucun lien.
+ */
+export declare function findUserIdBySocialProvider(db: DrizzleDb, dialect: SqlDialect, provider: string, providerId: string): Promise<string | null>;
+/**
+ * Réservation **atomique** d'une clé d'idempotence en **MySQL** — l'équivalent
+ * du `INSERT … ON CONFLICT DO UPDATE … WHERE expiré RETURNING` des dialectes
+ * sqlite/pg (cf `DrizzleIdempotencyStore.begin`), reconstruit avec les moyens
+ * du dialecte : MySQL n'a **ni `RETURNING` ni `WHERE` sur le `ON DUPLICATE KEY
+ * UPDATE`** — et le verdict `affectedRows` d'un ODKU est AMBIGU sous mysql2
+ * (flag `CLIENT_FOUND_ROWS` par défaut : ligne « matched inchangée » = 1,
+ * indistinguable d'un INSERT — prouvé sur serveur réel). D'où DEUX
+ * instructions, chacune atomique et au verdict non-ambigu :
+ *
+ * 1. **`INSERT IGNORE`** — clé neuve : `affectedRows = 1` ⇒ réservation
+ *    acquise ; clé existante : TOUJOURS `0` (`FOUND_ROWS` ne concerne pas les
+ *    doublons d'INSERT). L'unicité de la PK garantit UN seul gagnant sous
+ *    concurrence. (`IGNORE` downgrade aussi le mode strict en warnings — sans
+ *    enjeu ici : la clé est bornée en amont, `IDEMPOTENCY_KEY_MAX` 255 ≪
+ *    varchar(512).)
+ * 2. **Vol d'une entrée MORTE** : `UPDATE … WHERE key = ? AND expiresAt < now`
+ *    — le WHERE porte la condition « morte » ; l'UPDATE change TOUJOURS
+ *    `expiresAt` (nouveau > now > ancien) donc `affectedRows = 1` ⇔ vol acquis,
+ *    quel que soit le flag. Deux voleurs concurrents se sérialisent sur le
+ *    verrou de ligne InnoDB : le second ré-évalue le WHERE sur la version
+ *    committée (current read) → 0 ligne. Jamais de double-vol.
+ *
+ * Course résiduelle INSERT(0) → UPDATE(0) alors que la clé vient d'être
+ * supprimée (gc/abort) : verdict « contention » → le SELECT de `begin` ne la
+ * trouve plus → `in-flight` prudent (jamais `fresh` hors réservation atomique,
+ * l'invariant anti double-effet du contrat).
+ *
+ * @param db - handle Drizzle natif mysql.
+ * @param args - clé scopée, empreinte payload, horloge et échéance du bail.
+ * @returns `true` si la réservation est acquise (= le `fresh` du contrat).
+ */
+export declare function reserveIdempotencyKeyMysql(db: DrizzleDb, args: {
+    key: string;
+    fingerprint: string;
+    now: number;
+    leaseExpiresAt: number;
+}): Promise<boolean>;
+/** Filtres du listing utilisateur (sous-ensemble non portable de `IUserListQuery`). */
+export interface UserListFilters {
+    role?: string;
+    enabled?: boolean;
+    locked?: boolean;
+    hasSocial?: boolean;
+    q?: string;
+}
+/** Fenêtre + tri résolus (le défaut `identifier ASC` est posé par l'appelant). */
+export interface UserPageWindow {
+    limit: number;
+    offset: number;
+    order: Array<[string, "ASC" | "DESC"]>;
+}
+/**
+ * Sélectionne les `id` d'une **page** d'utilisateurs (filtres + tri + `LIMIT/
+ * OFFSET`), sans matérialiser les lignes. `limit + 1` → `hasNext` sans `COUNT`.
+ *
+ * @returns les `id` de la page (au plus `window.limit`, dans l'ordre du tri) et
+ *   `hasNext`.
+ */
+export declare function listUserIdsPage(db: DrizzleDb, dialect: SqlDialect, filters: UserListFilters, window: UserPageWindow): Promise<{
+    ids: string[];
+    hasNext: boolean;
+}>;
+/** Filtres du listing d'endpoints (sous-ensemble non portable d'`IWebhookListQuery`). */
+export interface WebhookListFilters {
+    enabled?: boolean;
+    event?: string;
+    failing?: boolean;
+    q?: string;
+}
+/**
+ * Sélectionne les `id` d'une **page** d'endpoints webhook (filtres + tri +
+ * `LIMIT/OFFSET`), sans matérialiser les lignes. `limit + 1` → `hasNext` sans
+ * `COUNT`.
+ *
+ * Le tri descend dans le `ORDER BY` — jamais appliqué après découpe, sinon la
+ * 2ᵉ page recommencerait au lieu de continuer la 1ʳᵉ. À défaut d'`order`
+ * recevable, l'ordre par défaut `createdAt DESC, id ASC` rend l'offset
+ * déterministe quand deux endpoints partagent la même milliseconde de création.
+ *
+ * @param window - fenêtre de page **et** tri demandé (déjà en noms publics ; il
+ *   est re-filtré ici par l'allowlist, cf {@link orderBySql}).
+ * @returns les `id` de la page (au plus `limit`, dans l'ordre) et `hasNext`.
+ */
+export declare function listWebhookIdsPage(db: DrizzleDb, dialect: SqlDialect, filters: WebhookListFilters, window: {
+    limit: number;
+    offset: number;
+    order?: IPageQuery["order"];
+    sortable?: readonly string[];
+}): Promise<{
+    ids: string[];
+    hasNext: boolean;
+}>;
+/**
+ * Compte les endpoints qui matchent les filtres (`COUNT(*)` natif filtré) —
+ * base du `total` d'une page d'endpoints.
+ *
+ * @returns le nombre de lignes correspondantes.
+ */
+export declare function countWebhookEndpoints(db: DrizzleDb, dialect: SqlDialect, filters: WebhookListFilters): Promise<number>;
+/**
+ * Compte les utilisateurs qui matchent les filtres (`COUNT(*)` natif filtré) —
+ * base commune du `total` de la page ET du garde-fou `countActiveAdmins`
+ * (`{ enabled: true, role: adminRole }`).
+ *
+ * @returns le nombre de lignes correspondantes.
+ */
+export declare function countUsers(db: DrizzleDb, dialect: SqlDialect, filters: UserListFilters): Promise<number>;

package/dist/types/nodefony/src/safeTarget.d.ts

@@ -0,0 +1,42 @@
+import path from "node:path";
+import type { SqlDialect } from "../config/config.js";
+/**
+ * Comment DÉSIGNER la base d'un connecteur sans rien faire fuiter.
+ *
+ * **Pourquoi une règle à part, et pourquoi elle est PURE.** Trois endroits
+ * doivent nommer la même base — l'adaptateur, qui la publie au plan
+ * d'administration ; les commandes de migration, qui doivent dire sur QUOI
+ * elles ont travaillé ; et le rapport d'état, que lisent un humain, un script
+ * et une console. Trois rendus recopiés divergeraient, et la divergence serait
+ * silencieuse : chacun passerait ses propres tests. Écrite ici, la règle
+ * s'éprouve sans base, sans kernel et sans variable d'environnement.
+ *
+ * Deux familles, deux dangers différents :
+ *
+ * - **une base FICHIER** (sqlite) : le danger est l'arborescence du serveur —
+ *   le nom de l'utilisateur, la structure du disque. Le chemin est donc rendu
+ *   RELATIF au répertoire de travail, et se réduit au nom de fichier dès qu'il
+ *   sort du projet ;
+ * - **une base RÉSEAU** (PostgreSQL, MySQL) : le danger est le compte. Une URL
+ *   de migration porte l'identifiant et le mot de passe du seul compte autorisé
+ *   à modifier un schéma de production. Seuls l'hôte, le port et le nom de la
+ *   base sont rendus — jamais la partie qui précède l'arobase.
+ *
+ * ⚠️ `redactSecrets` ne couvre PAS ce cas : aucune de ses familles ne masque un
+ * mot de passe d'URL. C'est pourquoi cette fonction ne masque pas, elle
+ * RECONSTRUIT — on ne publie que les morceaux dont on a décidé qu'ils sont
+ * publiables, ce qui reste vrai pour une URL dont la forme nous surprendrait.
+ *
+ * @param target - dialecte et coordonnées, telles que la résolution les rend.
+ * @param cwd - répertoire de référence pour relativiser un chemin de fichier.
+ * @param grammar - grammaire de chemins à employer. Injectée pour une seule
+ *   raison : une fonction qui lit `path` global ne s'éprouve que sur la
+ *   plateforme qu'elle décrit, c'est-à-dire jamais ici. Avec `path.win32`, le
+ *   cas Windows se joue sur n'importe quel système.
+ * @returns une désignation affichable, sans identifiant ni mot de passe.
+ */
+export declare function describeTargetSafely(target: {
+    dialect: SqlDialect;
+    filename?: string;
+    url?: string;
+}, cwd?: string, grammar?: typeof path): string;