@linklabjs/core 0.1.0

package/src/providers/PostgresProvider.ts

@@ -0,0 +1,187 @@
+/**
+ * PostgresProvider - PostgreSQL database provider with JSON fallback
+ *
+ * Dual-mode: real PostgreSQL or mock JSON files
+ */
+
+import type { Provider, ProviderConfig } from '../types/index.js'
+import { ProviderError } from '../types/index.js'
+import * as fs from 'fs'
+import * as path from 'path'
+import { Pool } from 'pg'
+
+interface PostgresConfig extends ProviderConfig {
+  host?: string
+  port?: number
+  user?: string
+  password?: string
+  connectionString?: string
+}
+
+export class PostgresProvider implements Provider {
+  private useMock: boolean
+  private pool: any | null = null
+  private dbPath: string
+  private tables: Map<string, any[]>
+
+  constructor(config: PostgresConfig) {
+    this.useMock = config.mock ?? false
+    console.log(' useMock: ', this.useMock)
+    this.dbPath = config.database ? `./db/postgres/${config.database}` : './db/postgres'
+    this.tables = new Map()
+
+    if (!this.useMock) {
+      try {
+        // Try to load pg module
+        // const { Pool } = require('pg')
+
+        this.pool = new Pool({
+          host: config.host ?? 'localhost',
+          port: config.port ?? 5432,
+          database: config.database,
+          user: config.user ?? 'postgres',
+          password: config.password,
+          connectionString: config.connectionString
+        })
+
+        console.log(`🐘 Postgres connected: ${config.database}`)
+      } catch (err) {
+        console.warn('⚠️  pg module not found, falling back to mock mode')
+        this.useMock = true
+      }
+    }
+
+    if (this.useMock) {
+      console.log(`🐘 Postgres connected (MOCK mode): ${config.database}`)
+      this.loadTables()
+    }
+  }
+
+  /**
+   * Load tables from JSON files (mock mode)
+   */
+  private loadTables(): void {
+    if (!fs.existsSync(this.dbPath)) {
+      this.tables = new Map()
+      return
+    }
+
+    const files = fs.readdirSync(this.dbPath)
+
+    for (const file of files) {
+      if (file.endsWith('.json')) {
+        const tableName = file.replace('.json', '')
+        const content = fs.readFileSync(path.join(this.dbPath, file), 'utf-8')
+        this.tables.set(tableName, JSON.parse(content))
+      }
+    }
+  }
+
+  /**
+   * Execute query
+   */
+  async query<T = any>(sql: string, params: any[] = []): Promise<T[]> {
+    if (this.useMock) {
+      return this.queryMock<T>(sql, params)
+    }
+
+    if (!this.pool) {
+      throw new ProviderError('PostgreSQL pool not initialized')
+    }
+
+    try {
+      console.log('🐘 Postgres:', sql)
+      if (params.length > 0) {
+        console.log('   Params:', params)
+      }
+
+      const result = await this.pool.query(sql, params)
+
+      console.log(`✅ Postgres result: ${result.rows.length} rows`)
+
+      return result.rows as T[]
+    } catch (err) {
+      throw new ProviderError(`PostgreSQL query failed: ${(err as Error).message}`, {
+        sql,
+        params,
+        error: err
+      })
+    }
+  }
+
+  /**
+   * Execute query in mock mode
+   */
+  private async queryMock<T = any>(sql: string, params: any[]): Promise<T[]> {
+    console.log('🐘 Postgres:', sql)
+    if (params.length > 0) {
+      console.log('   Params:', params)
+    }
+
+    // Parse SQL (simplified)
+    const selectMatch = sql.match(/SELECT .* FROM (\w+)/i)
+    if (!selectMatch) {
+      console.log('✅ Postgres result (MOCK): 0 rows')
+      return []
+    }
+
+    const tableName = selectMatch[1]
+    const data = this.tables.get(tableName) || []
+
+    // Apply WHERE clause (simplified)
+    let filtered = data
+
+    const whereMatch = sql.match(/WHERE (\w+)\.(\w+) = \$(\d+)/i)
+    if (whereMatch && params.length > 0) {
+      const column = whereMatch[2]
+      const paramIndex = parseInt(whereMatch[3]) - 1
+      const value = params[paramIndex]
+
+      filtered = data.filter((row: any) => row[column] === value)
+    }
+
+    console.log(`✅ Postgres result (MOCK): ${filtered.length} rows`)
+    return filtered as T[]
+  }
+
+  /**
+   * Close connection
+   */
+  async close(): Promise<void> {
+    if (this.pool) {
+      await this.pool.end()
+      console.log('🐘 Postgres closed')
+    } else {
+      console.log('🐘 Postgres closed')
+    }
+  }
+
+  /**
+   * Save data (mock mode only)
+   */
+  async save(tableName: string, data: any[]): Promise<void> {
+    if (!this.useMock) {
+      throw new ProviderError('Save only available in mock mode')
+    }
+
+    if (!fs.existsSync(this.dbPath)) {
+      fs.mkdirSync(this.dbPath, { recursive: true })
+    }
+
+    const filepath = path.join(this.dbPath, `${tableName}.json`)
+    fs.writeFileSync(filepath, JSON.stringify(data, null, 2))
+
+    this.tables.set(tableName, data)
+  }
+
+  /**
+   * Get table data (mock mode only)
+   */
+  getTable(tableName: string): any[] | undefined {
+    if (!this.useMock) {
+      throw new ProviderError('getTable only available in mock mode')
+    }
+
+    return this.tables.get(tableName)
+  }
+}

package/src/runtime/CompiledGraphEngine.ts

@@ -0,0 +1,274 @@
+/**
+ * CompiledGraphEngine - Production engine using precompiled graph
+ *
+ * - O(1) route lookup
+ * - Automatic fallback
+ * - Live metrics
+ * - Hot reload support
+ */
+
+import type { CompiledGraph, RouteInfo, PathMetrics, Provider } from '../types/index.js'
+
+interface LiveMetrics {
+  path: string[]
+  executions: number
+  successes: number
+  failures: number
+  totalTime: number
+  avgTime: number
+}
+
+export class CompiledGraphEngine {
+  private compiled: CompiledGraph
+  private provider: Provider
+  private liveMetrics: Map<string, LiveMetrics>
+  private routeCache: Map<string, RouteInfo>
+
+  constructor(compiled: CompiledGraph, provider: Provider) {
+    this.compiled = compiled
+    this.provider = provider
+    this.liveMetrics = new Map()
+    this.routeCache = this.buildRouteCache(compiled)
+
+    console.log('🚀 Compiled Graph Engine initialized')
+    console.log(`   Routes loaded: ${compiled.routes.length}`)
+    console.log(`   Nodes: ${compiled.nodes.length}`)
+  }
+
+  /**
+   * Build fast lookup cache
+   */
+  private buildRouteCache(compiled: CompiledGraph): Map<string, RouteInfo> {
+    const cache = new Map<string, RouteInfo>()
+
+    for (const route of compiled.routes) {
+      const key = `${route.from}→${route.to}`
+      cache.set(key, route)
+    }
+
+    return cache
+  }
+
+  /**
+   * Execute query from -> to
+   */
+  async query(from: string, to: string, data: Record<string, any> = {}): Promise<any[]> {
+    const key = `${from}→${to}`
+
+    // O(1) lookup!
+    const route = this.routeCache.get(key)
+
+    if (!route) {
+      throw new Error(`No compiled route from ${from} to ${to}`)
+    }
+
+    // Try primary path
+    try {
+      const start = performance.now()
+      const result = await this.executePath(route.primary.path, data)
+      const duration = performance.now() - start
+
+      // Update metrics
+      this.updateMetrics(route.primary.path, duration, true)
+
+      return result
+    } catch (err) {
+      console.warn(`⚠️  Primary path failed: ${(err as Error).message}`)
+
+      // Try fallbacks
+      return await this.fallback(route, data)
+    }
+  }
+
+  /**
+   * Execute path with JOINs
+   */
+  private async executePath(path: string[], data: Record<string, any>): Promise<any[]> {
+    // Build SQL with JOINs
+    let sql = `SELECT * FROM ${path[0]}`
+    const params: any[] = []
+
+    // Add JOINs
+    for (let i = 1; i < path.length; i++) {
+      const from = path[i - 1]
+      const to = path[i]
+
+      // Find edge in compiled graph
+      const edge = this.findEdge(from, to)
+
+      if (edge) {
+        sql += ` JOIN ${to} ON ${from}.${edge.via} = ${to}.id`
+      }
+    }
+
+    // Add WHERE if ID provided
+    if (data.id) {
+      sql += ` WHERE ${path[0]}.id = $${params.length + 1}`
+      params.push(data.id)
+    }
+
+    // Execute
+    return await this.provider.query(sql, params)
+  }
+
+  /**
+   * Find edge between nodes
+   */
+  private findEdge(from: string, to: string): { via: string } | null {
+    // Simplified - would look in compiled graph edges
+    return { via: 'id' }
+  }
+
+  /**
+   * Fallback to alternative paths
+   */
+  private async fallback(route: RouteInfo, data: Record<string, any>): Promise<any[]> {
+    for (const [index, fallback] of route.fallbacks.entries()) {
+      try {
+        console.log(`   Trying fallback ${index + 1}/${route.fallbacks.length}...`)
+
+        const start = performance.now()
+        const result = await this.executePath(fallback.path, data)
+        const duration = performance.now() - start
+
+        // Success!
+        console.log(`   ✅ Fallback worked: ${fallback.path.join('→')}`)
+
+        this.updateMetrics(fallback.path, duration, true)
+
+        // Maybe promote this fallback?
+        this.considerPromotion(route, index)
+
+        return result
+      } catch (err) {
+        console.warn(`   ✗ Fallback ${index + 1} failed: ${(err as Error).message}`)
+        this.updateMetrics(fallback.path, 0, false)
+        continue
+      }
+    }
+
+    throw new Error('All paths failed')
+  }
+
+  /**
+   * Update live metrics
+   */
+  private updateMetrics(path: string[], duration: number, success: boolean): void {
+    const key = path.join('→')
+
+    if (!this.liveMetrics.has(key)) {
+      this.liveMetrics.set(key, {
+        path,
+        executions: 0,
+        successes: 0,
+        failures: 0,
+        totalTime: 0,
+        avgTime: 0
+      })
+    }
+
+    const metric = this.liveMetrics.get(key)!
+    metric.executions++
+
+    if (success) {
+      metric.successes++
+      metric.totalTime += duration
+      metric.avgTime = metric.totalTime / metric.successes
+    } else {
+      metric.failures++
+    }
+  }
+
+  /**
+   * Consider promoting a fallback to primary
+   */
+  private considerPromotion(route: RouteInfo, fallbackIndex: number): void {
+    const fallback = route.fallbacks[fallbackIndex]
+    const fallbackKey = fallback.path.join('→')
+    const primaryKey = route.primary.path.join('→')
+
+    const fallbackMetric = this.liveMetrics.get(fallbackKey)
+    const primaryMetric = this.liveMetrics.get(primaryKey)
+
+    if (!fallbackMetric || !primaryMetric) return
+
+    // Promote if fallback is faster AND more reliable
+    const fallbackBetter =
+      fallbackMetric.avgTime < primaryMetric.avgTime && fallbackMetric.successes > 5 // Min sample size
+
+    if (fallbackBetter) {
+      console.log(`🔄 Promoting fallback to primary: ${fallbackKey}`)
+
+      // Swap
+      const temp = route.primary
+      route.primary = fallback
+      route.fallbacks[fallbackIndex] = temp
+
+      // Update cache
+      const key = `${route.from}→${route.to}`
+      this.routeCache.set(key, route)
+    }
+  }
+
+  /**
+   * Get live statistics
+   */
+  getStats(): {
+    totalExecutions: number
+    totalSuccesses: number
+    successRate: string
+    avgTime: string
+    uniquePaths: number
+    fastest?: LiveMetrics
+    slowest?: LiveMetrics
+  } {
+    const metrics = Array.from(this.liveMetrics.values())
+
+    if (metrics.length === 0) {
+      return {
+        totalExecutions: 0,
+        totalSuccesses: 0,
+        successRate: '0%',
+        avgTime: '0ms',
+        uniquePaths: 0
+      }
+    }
+
+    const totalExecutions = metrics.reduce((sum, m) => sum + m.executions, 0)
+    const totalSuccesses = metrics.reduce((sum, m) => sum + m.successes, 0)
+    const avgTime = metrics.reduce((sum, m) => sum + m.avgTime * m.successes, 0) / totalSuccesses
+
+    const fastest = metrics.reduce((min, m) => (m.avgTime < min.avgTime ? m : min))
+
+    const slowest = metrics.reduce((max, m) => (m.avgTime > max.avgTime ? m : max))
+
+    return {
+      totalExecutions,
+      totalSuccesses,
+      successRate: ((totalSuccesses / totalExecutions) * 100).toFixed(1) + '%',
+      avgTime: avgTime.toFixed(2) + 'ms',
+      uniquePaths: metrics.length,
+      fastest,
+      slowest
+    }
+  }
+
+  /**
+   * Export metrics for recompilation
+   */
+  exportMetrics(): Map<string, LiveMetrics> {
+    return new Map(this.liveMetrics)
+  }
+
+  /**
+   * Hot reload compiled graph
+   */
+  reload(compiled: CompiledGraph): void {
+    console.log('🔄 Hot reloading compiled graph...')
+
+    this.compiled = compiled
+    this.routeCache = this.buildRouteCache(compiled)
+
+    console.log(`✅ Reloaded: ${compiled.routes.length} routes`)
+  }
+}

package/src/runtime/DataLoader.ts

@@ -0,0 +1,236 @@
+/**
+ * DataLoader — Fetch les données pour un Trail résolu
+ *
+ * Fait le pont entre :
+ *   Trail (sémantique — où on est, d'où on vient)
+ *   QueryEngine (technique — comment fetcher les données)
+ *   Provider (physique — SQL ou JSON en mémoire)
+ *
+ * Principe :
+ *   Pour chaque frame RESOLVED dans le Trail, DataLoader
+ *   construit la requête optimale depuis le graphe compilé
+ *   et remplit frame.data avec les résultats.
+ *
+ * Deux modes de fetch :
+ *   SQL  — via Provider (PostgreSQL, MySQL...)
+ *   JSON — via dataset en mémoire (mock, tests, Netflix JSON)
+ *
+ * Usage :
+ * ```typescript
+ * const loader = new DataLoader(compiledGraph, { dataset })
+ * await loader.load(trail)
+ * // trail.current.data contient maintenant les données
+ * ```
+ */
+
+import type { CompiledGraph, Frame }  from '../types/index.js'
+import type { Trail }                  from '../navigation/Trail.js'
+import { QueryEngine }                 from './QueryEngine.js'
+
+// ── Types ─────────────────────────────────────────────────────
+
+export interface DataLoaderOptions {
+  /**
+   * Dataset JSON en mémoire — pour les providers mock ou Netflix JSON.
+   * Clé = nom de l'entité, valeur = tableau de rows.
+   */
+  dataset?: Record<string, any[]>
+
+  /**
+   * Provider SQL — pour PostgreSQL, MySQL, etc.
+   * Si fourni, prend la priorité sur dataset.
+   */
+  provider?: {
+    query<T = any>(sql: string, params?: any[]): Promise<T[]>
+  }
+
+  /**
+   * Transforme les filtres d'une frame en paramètres SQL.
+   * Par défaut : { field: 'id', value: 1 } → WHERE entity.id = 1
+   */
+  buildFilters?: (frame: Frame) => Record<string, any>
+}
+
+// ── DataLoader ────────────────────────────────────────────────
+
+export class DataLoader {
+  private queryEngine: QueryEngine
+  private options:     DataLoaderOptions
+
+  constructor(compiledGraph: CompiledGraph, options: DataLoaderOptions = {}) {
+    this.queryEngine = new QueryEngine(compiledGraph)
+    this.options     = options
+  }
+
+  /**
+   * Charge les données pour la frame courante du Trail.
+   *
+   * Stratégie :
+   *   1. Si la frame courante est UNRESOLVED → rien à fetcher
+   *   2. Si depth === 1 → fetch direct de l'entité (avec id si présent)
+   *   3. Si depth > 1  → traverse depuis le dernier ancêtre résolu
+   *
+   * Mutate trail.current.data avec les résultats.
+   */
+  async load(trail: Trail): Promise<void> {
+    const current = trail.current
+    if (!current) return
+    if (current.state === 'UNRESOLVED') return
+
+    // Trouver l'ancêtre — point d'entrée de la traversée
+    const anchor = this.findAnchor(trail)
+
+    let data: any[]
+
+    if (!anchor || anchor.entity === current.entity) {
+      const filters = current.id !== undefined ? { id: current.id } : {}
+      data = await this.fetchDirect(current.entity, filters)
+    } else {
+      const filters = anchor.id !== undefined ? { id: anchor.id } : {}
+      data = await this.fetchViaRoute(anchor.entity, current.entity, filters)
+    }
+    ;(current as any).data = data
+  }
+
+  /**
+   * Charge les données pour toutes les frames RESOLVED du Trail.
+   * Utile pour les réponses enrichies (chaque frame a ses données).
+   */
+  async loadAll(trail: Trail): Promise<void> {
+    for (let i = 0; i < trail.depth; i++) {
+      const frame = trail.at(i)
+      if (!frame || frame.state !== 'RESOLVED') continue
+
+      const subTrail = trail.slice(i + 1)
+      await this.load(subTrail)
+    }
+  }
+
+  // ── Privé ──────────────────────────────────────────────────
+
+  /**
+   * Trouve le premier ancêtre résolu avec un id dans le Trail.
+   * C'est le point de départ de la traversée.
+   */
+  private findAnchor(trail: Trail): Frame | undefined {
+    // Remonter le Trail depuis l'avant-dernière frame
+    for (let i = trail.depth - 2; i >= 0; i--) {
+      const frame = trail.at(i)
+      if (frame?.state === 'RESOLVED' && frame.id !== undefined) {
+        return frame
+      }
+    }
+    return undefined
+  }
+
+  /**
+   * Construit les filtres depuis le Trail.
+   * Combine les filtres de resolvedBy + l'id de l'ancêtre.
+   */
+  private buildFilters(trail: Trail): Record<string, any> {
+    const current = trail.current!
+    const filters: Record<string, any> = {}
+
+    // Filtre sur l'id de la frame courante si présent
+    if (current.id !== undefined) {
+      filters['id'] = current.id
+    }
+
+    // Filtres portés par resolvedBy (conditions sémantiques)
+    if (current.resolvedBy?.filters) {
+      for (const f of current.resolvedBy.filters) {
+        if (f.operator === 'equals') {
+          filters[f.field] = f.value
+        }
+      }
+    }
+
+    // Override par buildFilters custom si fourni
+    if (this.options.buildFilters) {
+      return { ...filters, ...this.options.buildFilters(current) }
+    }
+
+    return filters
+  }
+
+  /**
+   * Résout la clé primaire d'une entité depuis le graphe compilé.
+   * Fallback : {entity}_id (convention dvdrental, PostgreSQL standard).
+   */
+  private pkOf(entity: string): string {
+    const node = this.queryEngine.compiledGraph.nodes.find((n: any) => n.id === entity)
+    const pk   = (node as any)?.primaryKey
+    return Array.isArray(pk) ? pk[0] : (pk ?? `${entity}_id`)
+  }
+
+  /**
+   * Fetch direct — une seule entité, sans traversée.
+   */
+  private async fetchDirect(
+    entity:  string,
+    filters: Record<string, any>
+  ): Promise<any[]> {
+    if (this.options.provider) {
+      // SQL via provider — résoudre la PK réelle au lieu de supposer 'id'
+      const conditions = Object.entries(filters)
+        .map(([k, v], i) => {
+          const col = k === 'id' ? this.pkOf(entity) : k
+          return `${entity}.${col} = $${i + 1}`
+        })
+        .join(' AND ')
+
+      const sql    = conditions
+        ? `SELECT * FROM ${entity} WHERE ${conditions}`
+        : `SELECT * FROM ${entity}`
+      const params = Object.values(filters)
+
+      return this.options.provider.query(sql, params)
+    }
+
+    if (this.options.dataset) {
+      // JSON en mémoire — chercher sur la PK réelle ou 'id'
+      const pk   = this.pkOf(entity)
+      const rows = this.options.dataset[entity] ?? []
+      return rows.filter(row =>
+        Object.entries(filters).every(([k, v]) => {
+          const col = k === 'id' ? pk : k
+          return row[col] === v
+        })
+      )
+    }
+
+    return []
+  }
+
+  /**
+   * Fetch via route compilée — traverse from → to.
+   */
+  private async fetchViaRoute(
+    from:    string,
+    to:      string,
+    filters: Record<string, any>
+  ): Promise<any[]> {
+    // Vérifier que la route existe
+    let route
+    try {
+      route = this.queryEngine.getRoute(from, to)
+    } catch {
+      return this.fetchDirect(to, filters)
+    }
+
+    if (this.options.provider) {
+      const sql = this.queryEngine.generateSQL({ from, to, filters })
+      return this.options.provider.query(sql)
+    }
+
+    if (this.options.dataset) {
+      const result = this.queryEngine.executeInMemory(
+        { from, to, filters },
+        this.options.dataset
+      )
+      return result
+    }
+
+    return []
+  }
+}