Référence d'API — @nodefony/drizzle — racine

stable

Documentation › Référence d’API › @nodefony/drizzle › racine

Générée depuis les déclarations de types publiées de @nodefony/drizzle 10.0.0-beta.5 : exactement ce que reçoit une application qui l’installe. Cette page n’existe dans aucun dépôt — pour la corriger, on corrige le TSDoc du code.

@nodefony/drizzle#

import { … } from "@nodefony/drizzle" — 14 symboles.

Classes (9)#

DrizzleAuditStore#

class DrizzleAuditStore implements IAuditStore

Journal d’audit Drizzle (driver better-sqlite3 en test, Postgres/MySQL en prod) — implémentation SQL d’IAuditStore (append-only, tamper-evident) pour la rétention longue et le partage cross-pod, là où le store mémoire par défaut reste affine à un pod et volatile.

• constructor(resolveDb: () => DrizzleDb | null, now?: () => number, retentionMs?: number, table?: DrizzleTable, location?: string)
• get location(): string — Emplacement physique de la base (fichier SQLite) pour l’écran Studio « Stores » — lu par readStoreLocation.
• get connector(): string — Connecteur ORM qui porte ce store, lu par readStoreConnector pour le registre des stores : la console rattache la brique à SON connecteur au lieu de le déduire.
• static from(orm: DrizzleOrm, now?: () => number, retentionMs?: number): DrizzleAuditStore — Construit le store depuis un DrizzleOrm.
• append(event: IAuditEvent): Promise<void> — Ajoute un événement (immuable, jamais modifié ensuite).
• listPage(query: IAuditListQuery): Promise<IPage<IAuditEvent>> — Lit une page d’événements filtrés, du plus récent au plus ancien — l’implémentation ne matérialise jamais plus que limit événements.
• gc(now?: number): Promise<number> — Purge les événements au-delà de la fenêtre de rétention.

DrizzleIdempotencyStore#

class DrizzleIdempotencyStore implements IIdempotencyStore

Store d’idempotence Drizzle (driver better-sqlite3 en test, Postgres/MySQL en prod) — implémentation SQL d’IIdempotencyStore (contrat au CORE) pour dédoublonner les mutations rejouées PARTAGÉ cross-pod, là où le store mémoire par défaut reste affine à un pod.

• constructor(resolveDb: () => DrizzleDb | null, now?: () => number, leaseMs?: number, ttlMs?: number, table?: DrizzleTable, resolveLocation?: () => string, connector?: string)
• get location(): string — Emplacement physique de la base (fichier SQLite) pour l’écran Studio « Stores » — lu par readStoreLocation.
• get connector(): string — Connecteur ORM qui porte ce store, lu par readStoreConnector pour le registre des stores : la console rattache la brique à SON connecteur au lieu de le déduire.
• static from(orm: DrizzleOrm, now?: () => number, leaseMs?: number, ttlMs?: number): DrizzleIdempotencyStore — Construit le store depuis un DrizzleOrm.
• get size(): number — Approximation per-pod, best-effort : compteur local des réservations faites par CE pod (incrémenté au fresh, décrémenté au complete/abort), non décrémenté si le bail expire sans complétion, …
• begin(key: string, fingerprint: string): Promise<IdempotencyOutcome> — Réserve atomiquement la clé et renvoie le verdict à suivre.
• complete(key: string, response: IdempotentResponse): Promise<void> — Mémorise la réponse d’une clé in-flight (TTL) → rejeux futurs = replayed.
• abort(key: string): Promise<void> — Libère une clé in-flight dont l’exécution a échoué : rien n’est mémorisé (un échec doit pouvoir être réessayé).
• gc(now?: number): Promise<number> — Purge les entrées mortes (expiresAt <= now) — supplée l’absence de TTL natif SQL (≠ Redis PX).
• listPage(query: IIdempotencyListQuery): Promise<IPage<IIdempotencyKeyEntry>> — {@inheritDoc IIdempotencyStore.listPage}

DrizzleTokenStore#

class DrizzleTokenStore implements ITokenStore

Store de jetons Drizzle (driver better-sqlite3) — implémentation SQL d’ITokenStore au-dessus de trois repositories @nodefony/orm-core (access_token, denied_jti, subject_revocation).

• readonly sortableFields: readonly [ "createdAt", "name", "subjectId", "id" ] — {@inheritDoc ITokenStore.sortableFields}
• constructor(records: IRepository<IAccessTokenRecord>, denied: IRepository<DeniedJtiRow>, revocations: IRepository<SubjectRevocationRow>, now?: () => number, retentionRevokedMs?: number, location?: str …
• get location(): string — Emplacement physique de la base (fichier SQLite) pour l’écran Studio « Stores » — lu par readStoreLocation.
• get connector(): string — Connecteur ORM qui porte ce store, lu par readStoreConnector pour le registre des stores : la console rattache la brique à SON connecteur au lieu de le déduire.
• static from(orm: DrizzleOrm, now?: () => number, retentionRevokedMs?: number): DrizzleTokenStore — Construit le store depuis un DrizzleOrm connecté.
• put(record: IAccessTokenRecord): Promise<void> — Insère ou remplace un record (PAT / refresh) — 1 requête, upsert atomique sur la PK id plutôt qu’un findOne d’existence + create/updateOne (2 round-trips).
• findById(id: string): Promise<IAccessTokenRecord | null> — Recherche par identifiant (jti/id public).
• findByHash(secretHash: string): Promise<IAccessTokenRecord | null> — Recherche par hash de secret présenté.
• findBySubject(subjectId: string): Promise<IAccessTokenRecord[]> — Tous les jetons d’un porteur (console « mes jetons », révocation ciblée).
• listAll(): Promise<IAccessTokenRecord[]> — Tous les jetons (PAT + refresh) — vue d’administration cross-porteur.
• listPage(query: ITokenListQuery): Promise<IPage<IAccessTokenRecord>> — {@inheritDoc ITokenStore.listPage}
• countTokens(query: ITokenListQuery): Promise<number> — {@inheritDoc ITokenStore.countTokens}
• markUsed(id: string, usage: ITokenUsage): Promise<void> — Met à jour lastUsedAt/IP/UA (no-op si l’id est inconnu).
• revoke(id: string, reason: TokenRevokeReason): Promise<void> — Révoque un jeton — idempotent : la 1ʳᵉ date/raison de révocation est conservée (l’audit ne se réécrit pas).
• revokeFamily(family: string, reason: TokenRevokeReason): Promise<void> — Coupe toute une famille de refresh (détection de rejeu, RFC 9700) — les membres déjà révoqués (ex.
• denyJti(jti: string, expiresAt: number): Promise<void> — Inscrit un jti d’access sur la denylist jusqu’à expiresAt (epoch ms) — révocation immédiate avant l’exp du JWT.
• isJtiDenied(jti: string): Promise<boolean> — true si le jti est denylisté et non encore expiré.
• revokeAllForSubject(subjectId: string, invalidBefore: number): Promise<void> — Pose le seuil de révocation en masse d’un porteur (« déconnecte-moi de partout ») : tout jeton émis avant invalidBefore est mort.
• getInvalidBefore(subjectId: string): Promise<number | null> — Seuil invalidBefore d’un porteur (epoch ms) ou null si aucun.
• gc(now?: number): Promise<number> — Purge les entrées devenues inutiles : denylist jti expirée, records arrivés à exp, PAT révoqués sans expiration au-delà de la fenêtre de rétention.

DrizzleTotpSecretStore#

class DrizzleTotpSecretStore implements ITotpSecretStore

Store de secrets TOTP Drizzle (driver better-sqlite3) — implémentation SQL d’ITotpSecretStore au-dessus d’un unique repository @nodefony/orm-core (totp_secret). Comble le gap « 2FA persistant sans fichier » : là où MemoryTotpSecretStore est volatile, ce store survit au redémarrage et se partage entre pods (base durable).

• constructor(repo: IRepository<TotpSecretRow>, location?: string)
• get location(): string — Emplacement physique de la base (fichier SQLite) pour l’écran Studio « Stores » — lu par readStoreLocation.
• get connector(): string — Connecteur ORM qui porte ce store, lu par readStoreConnector pour le registre des stores : la console rattache la brique à SON connecteur au lieu de le déduire.
• static from(orm: DrizzleOrm): DrizzleTotpSecretStore — Construit le store depuis un DrizzleOrm connecté.
• findByUser(userId: string): Promise<ITotpSecret | null> — Secret TOTP de l’utilisateur, ou null si non enrôlé.
• save(secret: ITotpSecret): Promise<void> — Crée ou remplace le secret de l’utilisateur (upsert — ré-enrôlement).
• update(userId: string, patch: TotpSecretUpdate): Promise<void> — Applique un patch partiel (confirmation, anti-rejeu, consommation de codes).
• delete(userId: string): Promise<void> — Supprime le secret de l’utilisateur (désactivation du 2FA).
• listPage(query: ITotpListQuery): Promise<IPage<ITotpEnrollmentSummary>> — {@inheritDoc ITotpSecretStore.listPage}
• countEnrollments(query: ITotpListQuery): Promise<number> — {@inheritDoc ITotpSecretStore.countEnrollments}

DrizzleUserRepository#

class DrizzleUserRepository implements IUserRepository

• readonly sortableFields: readonly [ "identifier", "enabled", "createdAt", "updatedAt", "id" ] — Même vocabulaire public que les autres repositories — ici le tri part dans la requête, où il ne coûte qu’un index.
• constructor(base: IRepository<UserRow>, db: DrizzleDb, dialect?: SqlDialect)
• static from(orm: DrizzleOrm): DrizzleUserRepository — Construit le repository utilisateur depuis un DrizzleOrm connecté.
• find(criteria?: Criteria<IPasswordAuthenticatedUser>, options?: RepositoryReadOptions): Promise<IPasswordAuthenticatedUser[]> — Retourne toutes les entités correspondant au critère (toutes si omis).
• findOne(criteria: Criteria<IPasswordAuthenticatedUser>, options?: RepositoryReadOptions): Promise<IPasswordAuthenticatedUser | null> — Retourne la première entité correspondant au critère, ou null.
• create(data: Partial<IPasswordAuthenticatedUser>): Promise<IPasswordAuthenticatedUser> — Persiste une nouvelle entité et retourne sa version persistée (id généré, valeurs par défaut).
• updateOne(criteria: Criteria<IPasswordAuthenticatedUser>, data: Partial<IPasswordAuthenticatedUser>): Promise<IPasswordAuthenticatedUser | null> — Met à jour au plus une entité correspondant au critère, de façon atomique, et retourne sa version persistée (ou null si aucune ne correspond).
• upsert(criteria: Criteria<IPasswordAuthenticatedUser>, update: Partial<IPasswordAuthenticatedUser>, insertOnly?: Partial<IPasswordAuthenticatedUser>): Promise<IPasswordAuthenticatedUser> — Insère ou met à jour atomiquement l’entité identifiée par criteria (clé unique), en une seule requête (INSERT … ON CONFLICT DO UPDATE … RETURNING SQL / findOneAndUpdate({ upsert }) Mongo …
• createMany(data: Partial<IPasswordAuthenticatedUser>[]): Promise<IPasswordAuthenticatedUser[]> — Insère plusieurs entités en une seule requête (INSERT … VALUES (…),(…) SQL / insertMany Mongo) et retourne leurs versions persistées (ids générés, défauts appliqués), dans l’ordre.
• exists(criteria: Criteria<IPasswordAuthenticatedUser>): Promise<boolean> — Indique si au moins une entité correspond au critère, sans rapatrier la ligne (SELECT 1 … LIMIT 1 SQL / exists Mongo).
• deleteOne(criteria: Criteria<IPasswordAuthenticatedUser>): Promise<boolean> — Supprime au plus une entité de façon atomique (symétrique d’IRepository.updateOne ; DELETE … LIMIT 1 SQL / deleteOne Mongo).
• findOneAndDelete(criteria: Criteria<IPasswordAuthenticatedUser>): Promise<IPasswordAuthenticatedUser | null> — Supprime au plus une entité et retourne sa valeur supprimée (ou null), de façon atomique (DELETE … RETURNING SQL / findOneAndDelete Mongo) — claim-and-remove (file de jobs, outbox, pop a …
• increment(criteria: Criteria<IPasswordAuthenticatedUser>, changes: Partial<Record<keyof IPasswordAuthenticatedUser, number>>): Promise<IPasswordAuthenticatedUser | null> — Incrémente atomiquement des champs numériques d’au plus une entité (SET f = f + ? SQL / $inc Mongo), sans read-modify-write (donc sans race) — pour les compteurs (stats, usage/tokens, rate …
• updateMany(criteria: Criteria<IPasswordAuthenticatedUser>, data: Partial<IPasswordAuthenticatedUser>): Promise<number> — Met à jour toutes les entités correspondant au critère et retourne le nombre de lignes modifiées (parité de signature avec IRepository.delete).
• delete(criteria: Criteria<IPasswordAuthenticatedUser>): Promise<number> — Supprime les entités correspondant au critère.
• count(criteria?: Criteria<IPasswordAuthenticatedUser>): Promise<number> — Compte les entités correspondant au critère (toutes si omis).
• countDistinct(field: Extract<keyof IPasswordAuthenticatedUser, string>, criteria?: Criteria<IPasswordAuthenticatedUser>): Promise<number> — Compte les valeurs distinctes d’un champ parmi les entités qui correspondent au critère (COUNT(DISTINCT col) SQL / agrégation Mongo).
• withTransaction(tx: ITransaction): IUserRepository — Retourne une vue de ce repository liée à une transaction : toutes ses opérations s’exécutent dans tx (commit/rollback gérés par IOrm.transaction()).
• findByIdentifier(identifier: string): Promise<IPasswordAuthenticatedUser | null> — Retrouve un utilisateur par son identifiant fonctionnel (email, login…).
• findBySocialProvider(provider: string, providerId: string): Promise<IPasswordAuthenticatedUser | null> — Recherche par compte externe lié — cherche dans le JSON socialProviders via le queryKit (forme native du dialecte : json_each SQLite / @> jsonb PG, 1 requête), récupère l’id, puis recharge par …
• listPage(query: IUserListQuery): Promise<IPage<IPasswordAuthenticatedUser>> — {@inheritDoc IUserRepository.listPage}
• countUsers(query: IUserListQuery): Promise<number> — {@inheritDoc IUserRepository.countUsers}
• countActiveAdmins(adminRole: string): Promise<number> — {@inheritDoc IUserRepository.countActiveAdmins}

DrizzleWebAuthnCredentialStore#

class DrizzleWebAuthnCredentialStore implements IWebAuthnCredentialStore

Store de credentials WebAuthn Drizzle (driver better-sqlite3) — implémentation SQL d’IWebAuthnCredentialStore au-dessus d’un unique repository @nodefony/orm-core (webauthn_credential).

• constructor(repo: IRepository<WebAuthnCredentialRow>, location?: string)
• get location(): string — Emplacement physique de la base (fichier SQLite) pour l’écran Studio « Stores » — lu par readStoreLocation.
• get connector(): string — Connecteur ORM qui porte ce store, lu par readStoreConnector pour le registre des stores : la console rattache la brique à SON connecteur au lieu de le déduire.
• static from(orm: DrizzleOrm): DrizzleWebAuthnCredentialStore — Construit le store depuis un DrizzleOrm connecté.
• findById(credentialId: string): Promise<IWebAuthnCredential | null> — Credential par son id (base64url), ou null — résolution à l’authentification.
• findByUser(userId: string): Promise<IWebAuthnCredential[]> — Tous les credentials d’un utilisateur — pour allowCredentials (authentification ciblée) et l’UX « mes appareils ».
• countByUser(userId: string): Promise<number> — COUNT(*) natif — jamais un find().length (le plafond ne charge rien).
• save(credential: IWebAuthnCredential): Promise<void> — Persiste un nouveau credential (fin de la cérémonie d’enregistrement).
• update(credentialId: string, patch: WebAuthnAuthUpdate): Promise<void> — Met à jour l’état post-authentification (compteur, sauvegarde, UV, usage).
• delete(credentialId: string): Promise<void> — Révoque un credential (l’utilisateur retire un appareil).
• listPage(query: IWebAuthnListQuery): Promise<IPage<IWebAuthnCredentialSummary>> — {@inheritDoc IWebAuthnCredentialStore.listPage}
• countCredentials(query: IWebAuthnListQuery): Promise<number> — {@inheritDoc IWebAuthnCredentialStore.countCredentials}

DrizzleWebhookStore#

class DrizzleWebhookStore implements IWebhookStore

Store d’endpoints webhook Drizzle (driver better-sqlite3) — implémentation SQL d’IWebhookStore au-dessus d’un unique repository @nodefony/orm-core (webhook_endpoint). Persistance DURABLE du registre (les endpoints survivent au redémarrage, contrairement à MemoryWebhookStore).

• readonly sortableFields: readonly [ "createdAt", "updatedAt", "url", "enabled", "failureCount", "id" ] — {@inheritDoc IWebhookStore.sortableFields}
• constructor(repo: IRepository<WebhookEndpointRow>, location?: string, db?: DrizzleDb | null, dialect?: SqlDialect)
• get location(): string — Emplacement physique de la base (fichier SQLite) pour l’écran Studio « Stores » — lu par readStoreLocation.
• get connector(): string — Connecteur ORM qui porte ce store, lu par readStoreConnector pour le registre des stores : la console rattache la brique à SON connecteur au lieu de le déduire.
• static from(orm: DrizzleOrm): DrizzleWebhookStore — Construit le store depuis un DrizzleOrm connecté.
• save(endpoint: IWebhookEndpoint): Promise<void> — Insère un nouvel endpoint.
• findById(id: string): Promise<IWebhookEndpoint | null> — Charge un endpoint par id, ou null.
• update(id: string, patch: WebhookEndpointUpdate): Promise<void> — Applique un patch partiel (champs mutables) ; no-op si id absent.
• delete(id: string): Promise<void> — Supprime un endpoint ; no-op si id absent.
• listAll(): Promise<IWebhookEndpoint[]> — Tous les endpoints — réservé au snapshot du dispatcher (le service garde en mémoire la table complète des abonnements pour router un événement sans I/O, et la recharge au boot puis après chaqu …
• listPage(query: IWebhookListQuery): Promise<IPage<IWebhookEndpoint>> — {@inheritDoc IWebhookStore.listPage}
• countEndpoints(query: IWebhookListQuery): Promise<number> — {@inheritDoc IWebhookStore.countEndpoints}

SessionStorage#

class SessionStorage implements ISessionStorage

Stockage de session Drizzle (driver better-sqlite3), branché sur @nodefony/orm-core.

• manager: SessionsService
• idleTimeoutS: number
• absoluteTimeoutS: number
• readonly sortableFields: readonly [ "updatedAt", "createdAt", "user", "id" ] — Même vocabulaire public que les autres backends — le tri part dans le ORDER BY, donc il ne coûte rien de plus qu’un index bien posé.
• constructor(manager: SessionsService)
• get location(): string — Emplacement physique de la base (fichier SQLite) pour l’écran Studio « Stores » — lu par readStoreLocation du core au boot de SessionsService.
• get connector(): string — Connecteur ORM qui porte les sessions — lu par readStoreConnector pour le registre des stores.
• read(id: string): Promise<ISerializedSession>
• start(id: string): Promise<ISerializedSession>
• write(id: string, data: ISerializedSession): Promise<ISerializedSession>
• open(): Promise<number>
• close(): boolean
• destroy(id: string): Promise<boolean>
• gc(idleSeconds?: number, absoluteSeconds?: number): Promise<void> — Purge les sessions expirées sur les deux bornes NIST/OWASP : idle (inactivité depuis updatedAt) ET absolute (âge depuis createdAt, jamais prolongé).
• touch(id: string): Promise<void> — Prolonge l’idle d’une session (timeout glissant) : UPDATE updatedAt = now sur la PK session_id — SANS réécrire le blob (touch NIST/OWASP).
• listAll(filter?: ISessionListFilter): Promise<ISessionRecord[]> — Énumération admin (capacité optionnelle d’ISessionStorage) : un SELECT filtrable par user (WHERE indexable côté SQL).
• listPage(query: ISessionListQuery): Promise<IPage<ISessionRecord>> — Pagination native LIMIT/OFFSET + COUNT (helper paginate orm-core) : une page = une requête bornée, quel que soit le nombre de sessions en base.
• countSessions(query?: Partial<ISessionListQuery>): Promise<number> — COUNT(*) natif filtré — aucune ligne matérialisée.
• countDistinctUsers(query?: Partial<ISessionListQuery>): Promise<number> — COUNT(DISTINCT user) natif filtré.

default#

class Drizzle extends Module<IDrizzleConfig>

• constructor(kernel: Kernel)
• configSchema(): unknown — JSON Schema de la config drizzle → data plane admin (config riche Studio).
• onKernelRegister(): Promise<this> — Valide la config (défauts + module.options + surcharge env) au boot via defineDrizzleConfig, et l’expose au container sous drizzleConfig pour que le DrizzleService la consomme.
• onKernelBoot(): Promise<this> — Monte le data plane ORM (/nodefony/orm/api/* + providers santé/flux pour la sonde cluster et le drill Studio) via wireOrmAdminPlane.

Fonctions (2)#

isFrameworkFallbackEntity#

function isFrameworkFallbackEntity(entityName: string, connector?: string): boolean

Cette entité a-t-elle été posée par le repli du framework ?

registerDrizzleFrameworkStores#

function registerDrizzleFrameworkStores(dialect: SqlDialect): IFrameworkStoresReport

Déclare les entités framework portées sur dialect (connecteur default) et enregistre leurs fabriques de stores dans les registres de @nodefony/security et @nodefony/framework. Idempotent (guards) — rejouable sans effet.

Constantes (1)#

FRAMEWORK_CONNECTOR#

const FRAMEWORK_CONNECTOR = "default"

Connecteur conventionnel qui héberge le schéma framework (même convention que SESSION_CONNECTOR : "default" pour Drizzle, "nodefony" pour Mongoose).

Interfaces (2)#

IFrameworkStoresReport#

interface IFrameworkStoresReport

Bilan de l’auto-enregistrement (loggé par le module — jamais silencieux).

• registered: string[] — Entités déclarées par l’auto-register (tables créées au connect).
• appOwned: string[] — Entités déjà enregistrées par l’app (customisation respectée).
• unported: string[] — Entités non portées sur le dialecte configuré (stores indisponibles).

UserRow#

interface IUserRow

Forme plate d’un utilisateur tel qu’un dépôt le rend, avant reconstruction en BaseUser — pendant TypeScript de USER_COLUMNS.

• id: string
• identifier: string
• password: string | null
• roles: string[]
• enabled: boolean
• locked: boolean
• currentRole: string | null
• socialProviders: ISocialProvider[]
• metadata: Record<string, unknown>
• credentialsVersion: number | null
• createdAt: Date
• updatedAt: Date

← Toutes les références d’API