@linklabjs/core 0.1.0

package/src/http/LinkBuilder.ts

@@ -0,0 +1,244 @@
+/**
+ * LinkBuilder — Génère les liens HATEOAS depuis le graphe
+ *
+ * Logique pure, sans dépendance à Fastify.
+ * Prend un Trail + un Graph, retourne des liens navigables.
+ *
+ * Trois catégories de liens générés automatiquement :
+ *
+ *   self      — l'URL courante (Trail sérialisé)
+ *   up        — le parent (Trail sans la dernière frame)
+ *   relations — toutes les arêtes sortantes du nœud courant
+ *
+ * Les liens émergent du graphe — le dev ne configure rien.
+ */
+
+import type { Graph, GraphEdge } from '../types/index.js'
+import { Trail }       from '../navigation/Trail.js'
+import { TrailParser } from '../navigation/TrailParser.js'
+
+// ── Types ─────────────────────────────────────────────────────
+
+export interface HateoasLink {
+  href:     string
+  method:   'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'
+  templated?: boolean   // true si l'href contient {id}
+  title?:   string      // label lisible — ex: "Films de Nolan"
+  rel?:     string      // relation sémantique — ex: "movies"
+}
+
+export interface HateoasLinks {
+  self:  HateoasLink
+  up?:   HateoasLink
+  [relation: string]: HateoasLink | undefined
+}
+
+export interface LinkBuilderOptions {
+  /** Préfixe ajouté à toutes les URLs générées — ex: '/api/v1' */
+  prefix?: string
+  /** Inclure les arêtes inverses (retour vers le parent) */
+  includeReverse?: boolean
+  /** Exclure certaines relations — ex: ['internal', 'debug'] */
+  exclude?: string[]
+}
+
+// ── LinkBuilder ───────────────────────────────────────────────
+
+export class LinkBuilder {
+  private graph:   Graph
+  private options: Required<LinkBuilderOptions>
+
+  constructor(graph: Graph, options: LinkBuilderOptions = {}) {
+    this.graph   = graph
+    this.options = {
+      prefix:         options.prefix         ?? '',
+      includeReverse: options.includeReverse ?? false,
+      exclude:        options.exclude        ?? [],
+    }
+  }
+
+  /**
+   * Génère les liens HATEOAS pour un Trail donné.
+   *
+   * @example
+   * ```typescript
+   * const builder = new LinkBuilder(graph, { prefix: '/api' })
+   * const links   = builder.from(trail)
+   * // {
+   * //   self:    { href: '/api/people/Nolan/movies' },
+   * //   up:      { href: '/api/people/Nolan' },
+   * //   actors:  { href: '/api/people/Nolan/movies/{id}/actors', templated: true },
+   * //   ratings: { href: '/api/people/Nolan/movies/{id}/ratings', templated: true }
+   * // }
+   * ```
+   */
+  from(trail: Trail): HateoasLinks {
+    const currentPath = this.prefix(TrailParser.toPath(trail))
+
+    const links: HateoasLinks = {
+      self: {
+        href:   currentPath,
+        method: 'GET',
+        rel:    'self',
+      }
+    }
+
+    // ── Frame courante ────────────────────────────────────────
+    const current = trail.current
+
+    // ── Lien "up" — parent dans le Trail ou collection ─────────
+    // depth = 1 avec id : up vers la collection (ex: /movies/278 → up: /movies)
+    // depth > 1 : up vers l'entité parente (ex: /movies/278/people → up: /movies/278)
+    if (trail.depth === 1 && current?.id !== undefined) {
+      links.up = {
+        href:   this.prefix('/' + current.entity),
+        method: 'GET',
+        rel:    'up',
+        title:  `Collection ${current.entity}`,
+      }
+    } else if (trail.depth > 1) {
+      const parentTrail = trail.slice(trail.depth - 1)
+      links.up = {
+        href:   this.prefix(TrailParser.toPath(parentTrail)),
+        method: 'GET',
+        rel:    'up',
+        title:  `Retour vers ${parentTrail.current?.entity}`,
+      }
+    }
+
+    // ── Liens sortants — arêtes depuis le nœud courant ────────
+    if (!current) return links
+
+    const outgoing = this.getOutgoingEdges(current.entity)
+
+    // Grouper les arêtes par entité cible (.to)
+    // Plusieurs arêtes peuvent pointer vers la même entité (ex: actor, director, writer → people)
+    // On génère un seul lien par entité cible, avec l'arête de poids minimal
+    const byTarget = new Map<string, GraphEdge>()
+    for (const edge of outgoing) {
+      // Ignorer les relations exclues
+      if (this.options.exclude.includes(edge.name ?? '')) continue
+      if (this.options.exclude.includes(edge.to)) continue
+
+      const edgeLabel = (edge as any).label ?? edge.name ?? ''
+      // Préférer une edge avec un label significatif (pas 'unknow', pas vide)
+      const isSignificant = edgeLabel && edgeLabel !== 'unknow'
+
+      const existing = byTarget.get(edge.to)
+      if (!existing) {
+        byTarget.set(edge.to, edge)
+      } else {
+        const existingLabel = (existing as any).label ?? existing.name ?? ''
+        const existingSignificant = existingLabel && existingLabel !== 'unknow'
+        // Remplacer si : l'actuelle est insignifiante ET la nouvelle est significative,
+        // ou les deux sont significatives et la nouvelle est moins lourde
+        if ((!existingSignificant && isSignificant) ||
+            (existingSignificant && isSignificant && edge.weight < existing.weight)) {
+          byTarget.set(edge.to, edge)
+        }
+      }
+    }
+
+    for (const [targetEntity, edge] of byTarget) {
+      // L'URL utilise l'entité cible comme segment — pas le nom de l'arête
+      // /api/movies/278/people  (pas /api/movies/278/actor)
+      const href = current.id !== undefined
+        ? this.prefix(TrailParser.toPath(trail) + '/' + targetEntity)
+        : this.prefix(TrailParser.toPath(trail) + '/{id}/' + targetEntity)
+
+      const templated = current.id === undefined || href.includes('{id}')
+
+      links[targetEntity] = {
+        href,
+        method:    'GET',
+        templated: templated || undefined,
+        rel:       targetEntity,
+        title:     this.buildTitle(trail, edge),
+      }
+    }
+
+    return links
+  }
+
+  /**
+   * Génère les liens pour une collection de résultats.
+   * Chaque item reçoit ses propres liens self + relations.
+   *
+   * @example
+   * ```typescript
+   * // GET /people/Nolan/movies → liste de films
+   * const itemLinks = builder.forItems(trail, movies, 'id')
+   * // itemLinks[0] = { self: { href: '/people/Nolan/movies/1' }, actors: {...} }
+   * ```
+   */
+  forItems(
+    trail:   Trail,
+    items:   any[],
+    idField: string = 'id'
+  ): HateoasLinks[] {
+    return items.map(item => {
+      const id = item[idField]
+      if (id === undefined) return this.from(trail)
+
+      // Construire un Trail avec l'id de l'item
+      const itemTrail = trail.clone()
+      const last = itemTrail.current
+      if (last) {
+        // Remplacer la dernière frame avec l'id
+        itemTrail.pop()
+        itemTrail.push({ ...last, id, state: 'RESOLVED' })
+      }
+
+      return this.from(itemTrail)
+    })
+  }
+
+  /**
+   * Vérifie si une relation existe depuis un nœud donné.
+   * Utile pour les hooks d'access.check.
+   */
+  hasRelation(fromEntity: string, relation: string): boolean {
+    return this.graph.edges.some(
+      e => e.from === fromEntity && (e.name === relation || e.to === relation)
+    )
+  }
+
+  /**
+   * Retourne toutes les entités accessibles depuis un nœud.
+   */
+  reachableFrom(entity: string): string[] {
+    return this.getOutgoingEdges(entity).map(e => e.name ?? e.to)
+  }
+
+  // ── Privé ──────────────────────────────────────────────────
+
+  private getOutgoingEdges(entity: string): GraphEdge[] {
+    return this.graph.edges
+      .filter(e => e.from === entity)
+      .sort((a, b) => b.weight - a.weight)  // les plus utilisées en premier
+  }
+
+  private prefix(path: string): string {
+    if (!this.options.prefix) return path
+    return this.options.prefix.replace(/\/$/, '') + path
+  }
+
+  private buildTitle(trail: Trail, edge: GraphEdge): string {
+    const current = trail.current
+
+    // Résoudre un label lisible pour l'edge :
+    //   1. edge.name explicite et non générique  (ex: 'LIST_OF_CREDITS', 'actor')
+    //   2. edge.to comme fallback neutre          (ex: 'people', 'movies')
+    const rawName = edge.name ?? ''
+    const isGeneric = !rawName || rawName === 'unknow' || rawName === 'unknow_in'
+    const edgeLabel = isGeneric ? edge.to : rawName
+
+    if (!current) return edgeLabel
+
+    const from = current.id !== undefined
+      ? `${current.entity}(${current.id})`
+      : current.entity
+
+    return `${edgeLabel} de ${from}`
+  }
+}

package/src/http/TrailRequest.ts

@@ -0,0 +1,48 @@
+/**
+ * TrailRequest — Augmentation du type Request Fastify
+ *
+ * Ajoute `request.trail` et `request.linkBuilder`
+ * sur chaque requête décorée par le plugin LinkLab.
+ *
+ * Usage :
+ * ```typescript
+ * fastify.get('/*', async (req, reply) => {
+ *   const trail = req.trail         // Trail parsé depuis l'URL
+ *   const links = req.linkBuilder   // LinkBuilder prêt à l'emploi
+ * })
+ * ```
+ */
+
+import type { FastifyRequest } from 'fastify'
+import type { Trail }          from '../navigation/Trail.js'
+import type { LinkBuilder }    from './LinkBuilder.js'
+
+/**
+ * Déclaration d'augmentation du module Fastify.
+ * TypeScript merge automatiquement avec FastifyRequest.
+ */
+declare module 'fastify' {
+  interface FastifyRequest {
+    /** Trail parsé depuis l'URL de la requête */
+    trail: Trail
+
+    /** LinkBuilder configuré avec le graphe de l'instance */
+    linkBuilder: LinkBuilder
+  }
+}
+
+/**
+ * Extrait le contexte utilisateur depuis une requête Fastify.
+ * Extensible par le dev via les options du plugin.
+ */
+export type UserContextExtractor = (
+  req: FastifyRequest
+) => Promise<Record<string, any>> | Record<string, any>
+
+/**
+ * Extracteur par défaut — lit req.user si présent (JWT/session)
+ */
+export const defaultUserExtractor: UserContextExtractor = (req) => {
+  const r = req as any
+  return r.user ?? r.session?.user ?? {}
+}

package/src/http/example-netflix.ts

@@ -0,0 +1,59 @@
+/**
+ * Exemple d'intégration Netflix
+ * Fichier à titre d'exemple uniquement, non exporté.
+ */
+
+import { createRequire } from 'module'
+import { fileURLToPath } from 'url'
+import path              from 'path'
+import Fastify           from 'fastify'
+import { linklabPlugin } from './index.js'
+
+const require   = createRequire(import.meta.url)
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const dataDir   = path.join(__dirname, '../examples/netflix/data')
+
+const compiledGraph = require('../examples/netflix/compiled-graph.json')
+const movies        = require(path.join(dataDir, 'movies.json'))
+const people        = require(path.join(dataDir, 'people.json'))
+const credits       = require(path.join(dataDir, 'credits.json'))
+const categories    = require(path.join(dataDir, 'categories.json'))
+const departments   = require(path.join(dataDir, 'departments.json'))
+const jobs          = require(path.join(dataDir, 'jobs.json'))
+
+const fastify = Fastify({ logger: true })
+
+await fastify.register(linklabPlugin, {
+  graph:  compiledGraph,
+  prefix: '/api',
+  global: { domain: 'netflix', version: 'v1' },
+
+  dataLoader: {
+    dataset: { movies, people, credits, categories, departments, jobs }
+  },
+
+  extractUser: async (req) => {
+    const auth = req.headers.authorization
+    if (!auth) return {}
+    return { userId: 'u_123', subscription: 'premium', locale: 'fr-FR' }
+  },
+
+  onEngine: (engine, req) => {
+    const accessHandler: any = async (ctx: any) => {
+      const protected_ = ['movies', 'series', 'episodes']
+      if (protected_.includes(ctx.node) && !ctx.trail?.user?.subscription) {
+        return { cancelled: true, reason: 'subscription_required' }
+      }
+      return undefined
+    }
+    engine.hooks.on('access.check', accessHandler)
+    engine.events.on('traversal.complete', ({ routeUsed, durationMs }) => {
+      fastify.log.info({ routeUsed, durationMs }, 'traversal')
+    })
+    engine.errors.on('route.notfound', ({ from, to }) => {
+      fastify.log.warn({ from, to }, 'route not found')
+    })
+  },
+})
+
+await fastify.listen({ port: 3000 })

package/src/http/hateoas/README.md

@@ -0,0 +1,87 @@
+1. packages/linklab-http/README.md
+   Ce document présente le bridge entre le moteur LinkLab et le monde Web via Fastify.
+
+Markdown
+
+# @linklab/http
+
+Ce package fournit l'intégration HTTP officielle pour LinkLab, permettant d'exposer un graphe sémantique sous forme d'API **HATEOAS** automatisée.
+
+## Installation
+
+```bash
+pnpm add @linklab/http
+```
+
+Usage (Fastify Plugin)
+Le plugin linklabPlugin transforme vos définitions de graphes en routes API prêtes à l'emploi.
+
+```typeScript
+import Fastify from 'fastify'
+import { linklabPlugin } from '@linklab/http'
+
+const fastify = Fastify()
+
+await fastify.register(linklabPlugin, {
+  graph: semanticGraph,         // Le graphe logique (noeuds/arêtes)
+  compiledGraph: compiledGraph, // Le graphe compilé pour la navigation
+  prefix: '/api',               // Préfixe de l'API
+  dataLoader: {
+    dataset: { movies, people, credits, ... }
+  }
+})
+
+fastify.listen({ port: 3000 })
+```
+
+## 1. Fonctionnalités
+
+- HATEOAS Automatique : Injection de l'objet \_links dans chaque réponse.
+- Navigation Récursive : Support des chemins complexes (ex: /movies/278/credits/people).
+- Découvrabilité : Navigation fluide de parent à enfant (self, up, et relations nommées).
+- Instrumentation : Compatible avec @linklab/telemetry pour le monitoring de la tension API.
+
+---
+
+## 2. docs/architecture/hateoas.md
+
+Ce document détaille la logique de navigation par liens hypermédias.
+
+````markdown
+# Architecture HATEOAS dans LinkLab
+
+L'implémentation HATEOAS (_Hypermedia as the Engine of Application State_) de LinkLab repose sur la structure du graphe sémantique pour générer dynamiquement des liens de navigation.
+
+## Concept de Navigation
+
+Contrairement aux API REST classiques où les URLs sont codées en dur, LinkLab utilise les arêtes (edges) du graphe pour déterminer les transitions d'état possibles.
+
+### Structure d'une Réponse
+
+Chaque entité renvoyée par le `linklabPlugin` est enrichie d'un bloc `_links` :
+
+- **self** : L'URL unique de la ressource actuelle.
+- **up** : Le lien vers la collection parente (nœud précédent dans la hiérarchie).
+- **Relations** : Liens vers les nœuds adjacents définis dans le graphe (ex: `credits`, `categories`, `people`).
+
+### Exemple de Payload
+
+Pour une requête sur `/api/movies/278` :
+
+```json
+{
+  "id": 278,
+  "title": "The Shawshank Redemption",
+  "_links": {
+    "self": { "href": "/api/movies/278", "method": "GET" },
+    "up": { "href": "/api/movies", "title": "Collection movies" },
+    "credits": { "href": "/api/movies/278/credits", "title": "LIST_OF_CREDITS" },
+    "people": { "href": "/api/movies/278/people", "title": "actor" }
+  }
+}
+```
+````
+
+## 3. Résolution des Chemins
+
+Le NavigationEngine de LinkLab est sollicité à chaque requête pour valider que le chemin demandé existe dans le graphe compilé avant de déléguer l'extraction des données au QueryEngine.

package/src/http/index.ts

@@ -0,0 +1,33 @@
+/**
+ * http — Exports du module HTTP LinkLab
+ *
+ * Point d'entrée unique pour le plugin Fastify et
+ * les utilitaires HTTP associés.
+ *
+ * @example
+ * ```typescript
+ * import { linklabPlugin, LinkBuilder, TrailParser } from '@linklab/http'
+ *
+ * await fastify.register(linklabPlugin, {
+ *   graph:  compiledGraph,
+ *   prefix: '/api',
+ *   onEngine: (engine, req) => {
+ *     engine.hooks.on('access.check', async (ctx) => {
+ *       if (!ctx.trail.user.userId) {
+ *         return { cancelled: true, reason: 'unauthenticated' }
+ *       }
+ *     })
+ *   }
+ * })
+ * ```
+ */
+
+export { linklabPlugin }           from './plugin.js'
+export { LinkBuilder }             from './LinkBuilder.js'
+export { DataLoader }              from '../runtime/DataLoader.js'
+
+export type { LinklabPluginOptions } from './plugin.js'
+export type { TrailResponse, ResponseMeta } from './plugin.js'
+export type { HateoasLink, HateoasLinks, LinkBuilderOptions } from './LinkBuilder.js'
+export type { UserContextExtractor } from './TrailRequest.js'
+export type { DataLoaderOptions }  from '../runtime/DataLoader.js'