@linklabjs/core 0.1.0 → 0.1.1

package/dist/http/LinkBuilder.js

@@ -0,0 +1,190 @@
+/**
+ * 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 { TrailParser } from '../navigation/TrailParser.js';
+// ── LinkBuilder ───────────────────────────────────────────────
+export class LinkBuilder {
+    graph;
+    options;
+    constructor(graph, options = {}) {
+        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) {
+        const currentPath = this.prefix(TrailParser.toPath(trail));
+        const links = {
+            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();
+        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.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.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, items, idField = 'id') {
+        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, relation) {
+        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) {
+        return this.getOutgoingEdges(entity).map(e => e.name ?? e.to);
+    }
+    // ── Privé ──────────────────────────────────────────────────
+    getOutgoingEdges(entity) {
+        return this.graph.edges
+            .filter(e => e.from === entity)
+            .sort((a, b) => b.weight - a.weight); // les plus utilisées en premier
+    }
+    prefix(path) {
+        if (!this.options.prefix)
+            return path;
+        return this.options.prefix.replace(/\/$/, '') + path;
+    }
+    buildTitle(trail, edge) {
+        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}`;
+    }
+}
+//# sourceMappingURL=LinkBuilder.js.map

package/dist/http/LinkBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LinkBuilder.js","sourceRoot":"","sources":["../../src/http/LinkBuilder.ts"],"names":[],"mappings":"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"}

package/dist/http/TrailRequest.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 declare const defaultUserExtractor: UserContextExtractor;
+//# sourceMappingURL=TrailRequest.d.ts.map

package/dist/http/TrailRequest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TrailRequest.d.ts","sourceRoot":"","sources":["../../src/http/TrailRequest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAC7C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAe,wBAAwB,CAAA;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAS,kBAAkB,CAAA;AAEtD;;;GAGG;AACH,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,cAAc;QACtB,6CAA6C;QAC7C,KAAK,EAAE,KAAK,CAAA;QAEZ,yDAAyD;QACzD,WAAW,EAAE,WAAW,CAAA;KACzB;CACF;AAED;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,CACjC,GAAG,EAAE,cAAc,KAChB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;AAEvD;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,oBAGlC,CAAA"}

package/dist/http/TrailRequest.js

@@ -0,0 +1,22 @@
+/**
+ * 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
+ * })
+ * ```
+ */
+/**
+ * Extracteur par défaut — lit req.user si présent (JWT/session)
+ */
+export const defaultUserExtractor = (req) => {
+    const r = req;
+    return r.user ?? r.session?.user ?? {};
+};
+//# sourceMappingURL=TrailRequest.js.map

package/dist/http/TrailRequest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TrailRequest.js","sourceRoot":"","sources":["../../src/http/TrailRequest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA4BH;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAyB,CAAC,GAAG,EAAE,EAAE;IAChE,MAAM,CAAC,GAAG,GAAU,CAAA;IACpB,OAAO,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,OAAO,EAAE,IAAI,IAAI,EAAE,CAAA;AACxC,CAAC,CAAA"}

package/dist/http/example-netflix.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Exemple d'intégration Netflix
+ * Fichier à titre d'exemple uniquement, non exporté.
+ */
+export {};
+//# sourceMappingURL=example-netflix.d.ts.map

package/dist/http/example-netflix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"example-netflix.d.ts","sourceRoot":"","sources":["../../src/http/example-netflix.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/http/example-netflix.js

@@ -0,0 +1,52 @@
+/**
+ * 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 = async (ctx) => {
+            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 });
+//# sourceMappingURL=example-netflix.js.map

package/dist/http/example-netflix.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"example-netflix.js","sourceRoot":"","sources":["../../src/http/example-netflix.ts"],"names":[],"mappings":"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"}

package/dist/http/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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';
+//# sourceMappingURL=index.d.ts.map

package/dist/http/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/http/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAgB,aAAa,CAAA;AACrD,OAAO,EAAE,WAAW,EAAE,MAAkB,kBAAkB,CAAA;AAC1D,OAAO,EAAE,UAAU,EAAE,MAAmB,0BAA0B,CAAA;AAElE,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AACvD,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC9D,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AACrF,YAAY,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AAC7D,YAAY,EAAE,iBAAiB,EAAE,MAAO,0BAA0B,CAAA"}

package/dist/http/index.js

@@ -0,0 +1,27 @@
+/**
+ * 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';
+//# sourceMappingURL=index.js.map

package/dist/http/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/http/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAgB,aAAa,CAAA;AACrD,OAAO,EAAE,WAAW,EAAE,MAAkB,kBAAkB,CAAA;AAC1D,OAAO,EAAE,UAAU,EAAE,MAAmB,0BAA0B,CAAA"}

package/dist/http/plugin.d.ts

@@ -0,0 +1,110 @@
+/**
+ * LinkLab Fastify Plugin
+ *
+ * Transforme automatiquement chaque requête HTTP en Trail,
+ * résout la navigation via le graphe, et retourne une réponse
+ * HATEOAS Level 3 — liens générés automatiquement depuis le graphe.
+ *
+ * Usage minimal :
+ * ```typescript
+ * import Fastify from 'fastify'
+ * import { linklabPlugin } from '@linklab/http'
+ *
+ * const fastify = Fastify()
+ * await fastify.register(linklabPlugin, {
+ *   graph:  compiledGraph,
+ *   prefix: '/api'
+ * })
+ * await fastify.listen({ port: 3000 })
+ * ```
+ *
+ * Toutes ces routes fonctionnent sans configuration supplémentaire :
+ *   GET /api/people
+ *   GET /api/people/Nolan
+ *   GET /api/people/Nolan/movies
+ *   GET /api/people/Nolan/movies/1/actors
+ *
+ * Hooks disponibles sur chaque requête :
+ * ```typescript
+ * fastify.register(linklabPlugin, {
+ *   graph,
+ *   onEngine: (engine, req) => {
+ *     engine.hooks.on('access.check', async (ctx) => {
+ *       if (!ctx.trail.user.userId) {
+ *         return { cancelled: true, reason: 'unauthenticated' }
+ *       }
+ *     })
+ *   }
+ * })
+ * ```
+ */
+import type { FastifyPluginAsync, FastifyRequest } from 'fastify';
+import type { Graph, CompiledGraph } from '../types/index.js';
+import { Trail } from '../navigation/Trail.js';
+import { NavigationEngine } from '../navigation/NavigationEngine.js';
+import { type DataLoaderOptions } from '../runtime/DataLoader.js';
+import { type UserContextExtractor } from './TrailRequest.js';
+export interface LinklabPluginOptions {
+    /** Le graphe sémantique — navigation, LinkBuilder, Resolver */
+    graph: Graph;
+    /** Le graphe compilé — routes SQL optimales pour DataLoader/QueryEngine */
+    compiledGraph?: CompiledGraph;
+    /** Préfixe URL — ex: '/api' ou '/api/v1' */
+    prefix?: string;
+    /** Contexte global injecté dans chaque Trail */
+    global?: Record<string, any>;
+    /**
+     * Extracteur de contexte utilisateur.
+     * Par défaut : lit req.user ou req.session.user
+     */
+    extractUser?: UserContextExtractor;
+    /**
+     * Hook appelé après création du moteur, avant résolution.
+     * C'est ici que Netflix branche sa logique métier.
+     *
+     * @example
+     * ```typescript
+     * onEngine: (engine, req) => {
+     *   engine.hooks.on('access.check', async (ctx) => {
+     *     if (!ctx.trail.user.subscription) {
+     *       return { cancelled: true, reason: 'subscription_required' }
+     *     }
+     *   })
+     * }
+     * ```
+     */
+    onEngine?: (engine: NavigationEngine, req: FastifyRequest) => void | Promise<void>;
+    /**
+     * Options du DataLoader — source de données réelles.
+     *
+     * @example
+     * ```typescript
+     * // Mode JSON (Netflix mock / tests)
+     * dataLoader: { dataset: { movies, people, credits } }
+     *
+     * // Mode SQL (PostgreSQL)
+     * dataLoader: { provider: postgresProvider }
+     * ```
+     */
+    dataLoader?: DataLoaderOptions;
+    /**
+     * Transforme les données avant envoi.
+     * Utile pour la pagination, la sérialisation custom, etc.
+     */
+    transformData?: (data: any, trail: Trail) => any;
+}
+export interface TrailResponse {
+    data: any;
+    _links: Record<string, any>;
+    _trail: string;
+    _meta: ResponseMeta;
+}
+export interface ResponseMeta {
+    entity: string;
+    depth: number;
+    resolved: number;
+    timing: number;
+    count?: number;
+}
+export declare const linklabPlugin: FastifyPluginAsync<LinklabPluginOptions>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/http/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/http/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,cAAc,EAEf,MAAM,SAAS,CAAA;AAGhB,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAC7D,OAAO,EAAE,KAAK,EAAE,MAAuB,wBAAwB,CAAA;AAE/D,OAAO,EAAE,gBAAgB,EAAE,MAAY,mCAAmC,CAAA;AAE1E,OAAO,EAAc,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAC7E,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,mBAAmB,CAAA;AAI1B,MAAM,WAAW,oBAAoB;IACnC,+DAA+D;IAC/D,KAAK,EAAE,KAAK,CAAA;IAEZ,2EAA2E;IAC3E,aAAa,CAAC,EAAE,aAAa,CAAA;IAE7B,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAE5B;;;OAGG;IACH,WAAW,CAAC,EAAE,oBAAoB,CAAA;IAElC;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,EAAE,GAAG,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAElF;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,EAAE,iBAAiB,CAAA;IAE9B;;;OAGG;IACH,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,KAAK,GAAG,CAAA;CACjD;AAID,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAK,GAAG,CAAA;IACZ,MAAM,EAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC5B,MAAM,EAAG,MAAM,CAAA;IACf,KAAK,EAAI,YAAY,CAAA;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAI,MAAM,CAAA;IAChB,KAAK,EAAK,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAI,MAAM,CAAA;IAChB,KAAK,CAAC,EAAI,MAAM,CAAA;CACjB;AA+ND,eAAO,MAAM,aAAa,0CAGxB,CAAA"}