Aller au contenu
Tous les logs

Pourquoi j'ai créé Cyphra, un ORM typé pour Neo4j

Prisma ne supporte pas Neo4j, et le driver renvoie des lignes non typées, sans migrations. Cyphra, c'est l'outil que je voulais : un fichier de schéma, un client TypeScript généré et des migrations à partir des diffs. MIT.

Florian Amette4 min de lecture

Tout l'écosystème Cyber vit dans un seul graphe.

Concepts, compétences, rôles, cours, labs, sujets de la bibliothèque et les personnes qui apprennent. Cyber Library, Cyber Courses, CyberCTF et Cyber Bench sont tous des clients de ce même graphe. « Qu'est-ce que je dois apprendre avant ça ? », c'est une marche le long des arêtes REQUIRES. Une base graphe est le foyer naturel pour ça, donc le backend tourne sur Neo4j, et uniquement sur Neo4j.

La base n'a jamais été le problème. Le TypeScript autour, si.

À quoi ça ressemblait sans ORM

Trois choses faisaient mal.

Chaque ligne était une supposition. Le driver renvoie des records, pas des types. Chaque valeur est non typée tant que tu ne la castes pas, et les entiers reviennent sous la forme de la classe Integer du driver. J'ai fini par écrire un wrapper dont le seul rôle est de rendre chaque colonne unknown au lieu de any, plus un helper toInt pour lire les nombres. Rien ne te dit que u.emial est une faute de frappe, jusqu'à ce que la prod te le dise.

Pas de migrations. La couche GraphQL ne gère pas les contraintes, donc le backend les crée lui-même : une liste écrite à la main d'environ 25 CREATE CONSTRAINT, exécutée au cold start. En renommer une, c'est aussi écrire le DROP à la main.

Pas de Prisma. Sur Postgres, je prendrais Prisma sans réfléchir. Mais Prisma ne supporte pas Neo4j : la demande a été fermée comme « not planned » en décembre 2024. Les autres librairies Neo4j règlent chacune une partie du problème. Aucune ne me donnait un schéma, un client typé et des migrations au même endroit.

J'avais déjà écrit un adaptateur Neo4j pour Better Auth. Chaque nouvelle app voulait dire réécrire la même colle.

Alors j'ai construit l'outil que je voulais

Cyphra est un ORM typé pour Neo4j. Tu décris le graphe une fois :

node User {
  id    String @id @default(cuid())
  email String @unique
  posts Post[] @relationship(type: "AUTHORED", direction: OUT)
}

cyphra generate écrit un client qui connaît chaque propriété et chaque relation :

const active = await db.user.findMany({
  where: { posts: { some: { title: { contains: "graph" } } } },
  select: { email: true },
});

active est typé à partir du select. Une faute dans email, et c'est une erreur de compilation, pas un bug à 3 h du matin.

Ce que tu obtiens

FonctionCe que ça remplace
Un schéma .cyphraDes contraintes éparpillées dans le code
Un client typé généréDes lignes unknown et des casts à la main
cyphra migrate devDes listes de CREATE CONSTRAINT écrites à la main
Des écritures imbriquées en une transactionDu Cypher en plusieurs étapes à la main
db.$cypherRien. Le Cypher brut reste à un appel
cyphra devL'installation locale : il lance Neo4j 5 dans Docker et écrit ton .env
cyphra pullRéécrire le schéma d'une base existante

L'API te semblera familière si tu as utilisé Prisma : findMany, include, select, upsert, $transaction. C'est voulu. L'objectif, c'est que choisir Neo4j soit aussi simple que choisir Postgres.

Pas une surcouche de Cypher

Les graphes sont le sujet, donc les relations sont de première classe : leurs propriétés sont typées elles aussi, et connect ne crée pas d'arêtes en double. Quand l'ORM ne suffit pas, tu écris du Cypher. Cyphra ne cache pas la base, il retire le code répétitif autour.

Hébergement

La librairie et la CLI sont gratuites et sous licence MIT. Si tu ne veux pas faire tourner Neo4j toi-même, Cyphra Cloud est en accès anticipé, et l'opérateur Kubernetes derrière est open source lui aussi. L'auto-hébergement reste de première classe.

Essaie-le

C'est jeune, alors dis-moi ce qui casse. Issues et PR bienvenues.

Livrez le correctif. Puis partagez le patch.