@linklabjs/core 0.1.0

package/src/navigation/Trail.ts

@@ -0,0 +1,252 @@
+/**
+ * Trail — Contexte de navigation vivant
+ *
+ * Trois niveaux de contexte, trois durées de vie :
+ *
+ *   global   — vit aussi longtemps que l'instance LinkLab
+ *              config, feature flags, métriques globales
+ *
+ *   user     — vit le temps d'une session
+ *              userId, permissions, préférences, historique récent
+ *
+ *   frames   — vit le temps d'une navigation
+ *              le chemin parcouru, position courante
+ *
+ * Deux niveaux d'API :
+ *
+ *   Bas niveau  — trail.push(frame), trail.pop(), trail.compact()
+ *                 fondation sur laquelle tout repose
+ *
+ *   Haut niveau — API fluente, construite sur push()
+ *                 cinema.people('Nolan').movies
+ *
+ * Contrat de sérialisation :
+ *   global et user ne contiennent que des données — jamais de fonctions.
+ *   Un Trail sérialisé peut être rejoué exactement.
+ */
+
+import type { Frame } from '../types/index.js'
+
+// ── Types ─────────────────────────────────────────────────────
+
+export interface TrailInit {
+  global?: Record<string, any>
+  user?:   Record<string, any>
+  frames?: Frame[]
+}
+
+/** Format de sérialisation — versionné pour les migrations futures */
+export interface SerializedTrail {
+  v:       number
+  global:  Record<string, any>
+  user:    Record<string, any>
+  frames:  Frame[]
+  savedAt: string
+}
+
+// ── Trail ─────────────────────────────────────────────────────
+
+export class Trail {
+  /** Contexte global — long terme */
+  public readonly global: Record<string, any>
+
+  /** Contexte utilisateur — session */
+  public readonly user: Record<string, any>
+
+  /** Frames de navigation — readonly depuis l'extérieur */
+  private _frames: Frame[]
+
+  private constructor(init: TrailInit = {}) {
+    this.global  = init.global ?? {}
+    this.user    = init.user   ?? {}
+    this._frames = init.frames ? init.frames.map(f => ({ ...f })) : []
+  }
+
+  // ── Factories ──────────────────────────────────────────────
+
+  /** Crée un Trail vierge, avec contextes optionnels */
+  static create(init: TrailInit = {}): Trail {
+    return new Trail(init)
+  }
+
+  /** Restaure un Trail depuis sa forme sérialisée */
+  static from(serialized: string | SerializedTrail): Trail {
+    const data: SerializedTrail = typeof serialized === 'string'
+      ? JSON.parse(serialized)
+      : serialized
+
+    if (data.v !== 1) {
+      throw new Error(`Trail.from: version ${data.v} non supportée`)
+    }
+
+    return new Trail({
+      global: data.global ?? {},
+      user:   data.user   ?? {},
+      frames: data.frames ?? [],
+    })
+  }
+
+  // ── Accesseurs frames ──────────────────────────────────────
+
+  /** Toutes les frames — tableau immuable depuis l'extérieur */
+  get frames(): readonly Frame[] {
+    return this._frames
+  }
+
+  /** Dernière frame — position courante */
+  get current(): Frame | undefined {
+    return this._frames[this._frames.length - 1]
+  }
+
+  /** Nombre de frames */
+  get depth(): number {
+    return this._frames.length
+  }
+
+  /** Vrai si toutes les frames sont résolues */
+  get isFullyResolved(): boolean {
+    return this._frames.every(f => f.state === 'RESOLVED')
+  }
+
+  /** Frames non résolues */
+  get unresolved(): Frame[] {
+    return this._frames.filter(f => f.state === 'UNRESOLVED')
+  }
+
+  // ── API bas niveau ─────────────────────────────────────────
+
+  /**
+   * Pousse une frame sur le Trail.
+   * Retourne this pour le chaînage.
+   *
+   * Si state n'est pas précisé :
+   *   - id fourni  → RESOLVED
+   *   - id absent  → UNRESOLVED
+   */
+  push(frame: Frame): this {
+    const normalized: Frame = {
+      ...frame,
+      state: frame.state ?? (frame.id !== undefined ? 'RESOLVED' : 'UNRESOLVED'),
+    }
+    this._frames.push(normalized)
+    return this
+  }
+
+  /**
+   * Retire et retourne la dernière frame.
+   * Retourne undefined si le Trail est vide.
+   */
+  pop(): Frame | undefined {
+    return this._frames.pop()
+  }
+
+  /**
+   * Met à jour une frame existante par index ou par entity.
+   * Réservé à LinkLab — permet au moteur de synchroniser les frames résolues.
+   *
+   * @param entity  - L'entité de la frame à mettre à jour
+   * @param updated - Les nouvelles valeurs à merger
+   */
+  updateFrame(entity: string, updated: Partial<Frame>): boolean {
+    const idx = this._frames.findIndex(
+      f => f.entity === entity && f.state === 'UNRESOLVED'
+    )
+    if (idx === -1) return false
+    this._frames[idx] = { ...this._frames[idx], ...updated }
+    return true
+  }
+
+  /**
+   * Compacte le Trail — supprime les frames non-discriminantes
+   * en conservant uniquement les frames qui portent un id
+   * ou qui sont la position courante.
+   *
+   * Exemple :
+   *   [cinema][people(Nolan)][movies(Interstellar)][actors]
+   *   →  [people(Nolan)][movies(Interstellar)][actors]
+   *
+   * Note : réservé à LinkLab — appelé par le moteur, pas par les hooks.
+   */
+  compact(): this {
+    const last = this._frames.length - 1
+    this._frames = this._frames.filter((f, i) =>
+      i === last || f.id !== undefined
+    )
+    return this
+  }
+
+  /**
+   * Retourne la frame à l'index donné (0 = première).
+   * Accepte les index négatifs (-1 = dernière).
+   */
+  at(index: number): Frame | undefined {
+    if (index < 0) index = this._frames.length + index
+    return this._frames[index]
+  }
+
+  /**
+   * Retourne la dernière frame dont l'entity correspond.
+   */
+  find(entity: string): Frame | undefined {
+    return [...this._frames].reverse().find(f => f.entity === entity)
+  }
+
+  /**
+   * Retourne un Trail tronqué jusqu'à l'index donné (non inclus).
+   * Utile pour le replay partiel.
+   */
+  slice(end: number): Trail {
+    return new Trail({
+      global: { ...this.global },
+      user:   { ...this.user },
+      frames: this._frames.slice(0, end),
+    })
+  }
+
+  // ── Sérialisation ──────────────────────────────────────────
+
+  /**
+   * Sérialise le Trail en JSON.
+   * global et user ne doivent contenir que des données — les fonctions
+   * sont silencieusement ignorées par JSON.stringify.
+   */
+  serialize(): string {
+    return JSON.stringify(this.toJSON())
+  }
+
+  toJSON(): SerializedTrail {
+    return {
+      v:       1,
+      global:  this.global,
+      user:    this.user,
+      frames:  [...this._frames],
+      savedAt: new Date().toISOString(),
+    }
+  }
+
+  /**
+   * Deep copy — utile pour le replay ou les tests.
+   * Le clone est indépendant — modifier l'un ne modifie pas l'autre.
+   */
+  clone(): Trail {
+    return Trail.from(this.toJSON())
+  }
+
+  // ── Debug ──────────────────────────────────────────────────
+
+  /**
+   * Représentation lisible du Trail courant.
+   * ex: [people(Nolan)] → [movies(Interstellar)] → [actors?]
+   */
+  toString(): string {
+    if (this._frames.length === 0) return '(trail vide)'
+
+    return this._frames
+      .map(f => {
+        const id    = f.id !== undefined ? `(${f.id})` : ''
+        const state = f.state === 'UNRESOLVED' ? '?' : f.state === 'DEFERRED' ? '…' : ''
+        return `[${f.entity}${id}${state}]`
+      })
+      .join(' → ')
+  }
+}

package/src/navigation/TrailParser.ts

@@ -0,0 +1,207 @@
+/**
+ * TrailParser — Désérialise des représentations externes vers un Trail
+ *
+ * Trois sources supportées :
+ *
+ *   URL path   →  /cinema/people/Nolan/movies/Interstellar/actors
+ *   URL fluent →  cinema.people(Nolan).movies(Interstellar).actors
+ *   JSON       →  SerializedTrail (via Trail.from)
+ *
+ * Le parser est stateless — toutes les méthodes sont statiques.
+ * Il ne valide pas les entités contre le graphe — c'est le rôle du moteur.
+ */
+
+import { Trail } from './Trail.js'
+import type { Frame } from '../types/index.js'
+
+export class TrailParser {
+
+  // ── URL Path ───────────────────────────────────────────────
+
+  /**
+   * Parse un path HTTP en Trail.
+   *
+   * Convention :
+   *   /entity              → Frame(entity, UNRESOLVED)
+   *   /entity/id           → Frame(entity, id, RESOLVED)
+   *   /entity/id/other     → Frame(entity, id) + Frame(other, UNRESOLVED)
+   *
+   * Exemples :
+   *   /people                     → [people?]
+   *   /people/Nolan               → [people(Nolan)]
+   *   /people/Nolan/movies        → [people(Nolan)] → [movies?]
+   *   /people/Nolan/movies/2      → [people(Nolan)] → [movies(2)]
+   *   /cinema/people/Nolan/movies → [cinema] → [people(Nolan)] → [movies?]
+   *
+   * @param path  - URL path, avec ou sans slash initial
+   * @param init  - Contextes global/user à injecter
+   */
+  static fromPath(
+    path: string,
+    init: { global?: Record<string, any>; user?: Record<string, any> } = {}
+  ): Trail {
+    const trail  = Trail.create(init)
+    const parts  = path.replace(/^\/+|\/+$/g, '').split('/').filter(Boolean)
+
+    let i = 0
+    while (i < parts.length) {
+      const entity = parts[i]
+      const next   = parts[i + 1]
+
+      // Si le prochain segment existe et n'est pas une entité connue
+      // (heuristique : commence par une lettre minuscule = entité, sinon = id)
+      const nextIsId = next !== undefined && !TrailParser.looksLikeEntity(next)
+
+      if (nextIsId) {
+        trail.push({ entity, id: TrailParser.coerceId(next), state: 'RESOLVED' })
+        i += 2
+      } else {
+        trail.push({ entity, state: 'UNRESOLVED' })
+        i += 1
+      }
+    }
+
+    return trail
+  }
+
+  /**
+   * Parse une expression fluente en Trail.
+   *
+   * Syntaxe :
+   *   entity                  → Frame(entity, UNRESOLVED)
+   *   entity(id)              → Frame(entity, id, RESOLVED)
+   *   entity.other            → Frame(entity) + Frame(other)
+   *   entity(id).other(id2)   → Frame(entity,id) + Frame(other,id2)
+   *
+   * Exemples :
+   *   people                         → [people?]
+   *   people(Nolan)                  → [people(Nolan)]
+   *   people(Nolan).movies           → [people(Nolan)] → [movies?]
+   *   cinema.people(Nolan).movies(2) → [cinema] → [people(Nolan)] → [movies(2)]
+   *
+   * @param expr  - Expression fluente
+   * @param init  - Contextes global/user à injecter
+   */
+  static fromFluent(
+    expr: string,
+    init: { global?: Record<string, any>; user?: Record<string, any> } = {}
+  ): Trail {
+    const trail   = Trail.create(init)
+
+    // Tokenise : split sur les points, mais pas ceux dans les parenthèses
+    const tokens  = TrailParser.tokenizeFluent(expr)
+
+    for (const token of tokens) {
+      const frame = TrailParser.parseToken(token)
+      trail.push(frame)
+    }
+
+    return trail
+  }
+
+  /**
+   * Sérialise un Trail en path HTTP.
+   *
+   * Exemple :
+   *   Trail([people(Nolan)][movies?])  →  /people/Nolan/movies
+   */
+  static toPath(trail: Trail): string {
+    const parts: string[] = []
+
+    for (const frame of trail.frames) {
+      parts.push(frame.entity)
+      if (frame.id !== undefined) {
+        parts.push(String(frame.id))
+      }
+    }
+
+    return '/' + parts.join('/')
+  }
+
+  /**
+   * Sérialise un Trail en expression fluente.
+   *
+   * Exemple :
+   *   Trail([people(Nolan)][movies?])  →  people(Nolan).movies
+   */
+  static toFluent(trail: Trail): string {
+    return trail.frames
+      .map(f => f.id !== undefined ? `${f.entity}(${f.id})` : f.entity)
+      .join('.')
+  }
+
+  // ── Helpers privés ─────────────────────────────────────────
+
+  /**
+   * Heuristique : un segment ressemble-t-il à un nom d'entité ?
+   * Les entités commencent par une lettre minuscule et ne contiennent
+   * que des lettres, chiffres et tirets.
+   */
+  private static looksLikeEntity(segment: string): boolean {
+    return /^[a-z][a-zA-Z0-9-_]*$/.test(segment)
+  }
+
+  /**
+   * Essaie de convertir un id en nombre, sinon garde la string.
+   */
+  private static coerceId(value: string): string | number {
+    const n = Number(value)
+    return Number.isFinite(n) && value.trim() !== '' ? n : value
+  }
+
+  /**
+   * Tokenise une expression fluente en segments.
+   * Préserve le contenu des parenthèses (les ids peuvent contenir des points).
+   *
+   * ex: "cinema.people(Nolan.Jr).movies"
+   *   → ["cinema", "people(Nolan.Jr)", "movies"]
+   */
+  private static tokenizeFluent(expr: string): string[] {
+    const tokens: string[] = []
+    let current = ''
+    let depth   = 0
+
+    for (const ch of expr) {
+      if (ch === '(') {
+        depth++
+        current += ch
+      } else if (ch === ')') {
+        depth--
+        current += ch
+      } else if (ch === '.' && depth === 0) {
+        if (current) tokens.push(current)
+        current = ''
+      } else {
+        current += ch
+      }
+    }
+
+    if (current) tokens.push(current)
+    return tokens
+  }
+
+  /**
+   * Parse un token "entity" ou "entity(id)" en Frame.
+   */
+  private static parseToken(token: string): Frame {
+    const match = token.match(/^([^(]+)(?:\(([^)]*)\))?$/)
+
+    if (!match) {
+      // Token malformé — on le traite comme une entité sans id
+      return { entity: token, state: 'UNRESOLVED' }
+    }
+
+    const entity = match[1].trim()
+    const rawId  = match[2]
+
+    if (rawId === undefined || rawId === '') {
+      return { entity, state: 'UNRESOLVED' }
+    }
+
+    return {
+      entity,
+      id:    TrailParser.coerceId(rawId),
+      state: 'RESOLVED',
+    }
+  }
+}

package/src/navigation/index.ts

@@ -0,0 +1,11 @@
+/**
+ * navigation — Exports du module de navigation
+ */
+
+export { Trail }       from './Trail.js'
+export { TrailParser } from './TrailParser.js'
+export { NavigationEngine } from './NavigationEngine.js'
+export { Resolver }    from './Resolver.js'
+export { Scheduler }   from './Scheduler.js'
+
+export type { TrailInit, SerializedTrail } from './Trail.js'

package/src/providers/MockProvider.ts

@@ -0,0 +1,68 @@
+/**
+ * MockProvider - In-memory provider for testing
+ */
+
+import type { Provider } from '../types/index.js'
+
+export class MockProvider implements Provider {
+  private data: Map<string, any[]>
+
+  constructor() {
+    this.data = new Map()
+  }
+
+  /**
+   * Set mock data for a table
+   */
+  setData(table: string, rows: any[]): void {
+    this.data.set(table, rows)
+  }
+
+  /**
+   * Execute query (simplified parsing)
+   */
+  async query<T = any>(sql: string, params: any[] = []): Promise<T[]> {
+    // Parse table name
+    const selectMatch = sql.match(/SELECT .* FROM (\w+)/i)
+    if (!selectMatch) {
+      return []
+    }
+
+    const tableName = selectMatch[1]
+    const data = this.data.get(tableName) || []
+
+    // Apply WHERE clause (simplified)
+    let filtered = data
+
+    const whereMatch = sql.match(/WHERE (\w+) = \?/i)
+    if (whereMatch && params.length > 0) {
+      const column = whereMatch[1]
+      const value = params[0]
+
+      filtered = data.filter((row: any) => row[column] === value)
+    }
+
+    return filtered as T[]
+  }
+
+  /**
+   * Close (no-op for mock)
+   */
+  async close(): Promise<void> {
+    // No-op
+  }
+
+  /**
+   * Clear all data
+   */
+  clear(): void {
+    this.data.clear()
+  }
+
+  /**
+   * Get data for a table
+   */
+  getData(table: string): any[] | undefined {
+    return this.data.get(table)
+  }
+}