@teamvelix/velix-core 5.2.9 → 5.3.0

package/dist/index.d.ts

@@ -288,7 +288,7 @@ interface RouteTreeNode {
     children: Record<string, RouteTreeNode>;
     routes: Route[];
 }
-interface RouteMatch {
+interface RouteMatch$1 {
     route: Route;
     params: Record<string, string>;
 }
@@ -400,43 +400,42 @@ declare const RouteType: {
     readonly ERROR: "error";
     readonly NOT_FOUND: "not-found";
 };
+type RouteMatch = Route & {
+    params: Record<string, string>;
+};
+
+/**
+ * Finds all layouts that apply to a route
+ */
+declare function findRouteLayouts(route: Route, layoutsMap: Map<string, string>): Array<{
+    name: string;
+    filePath: string | undefined;
+}>;
+
 /**
- * Builds the complete route tree from the app/ directory
+ * Matches URL path against routes
  */
-declare function buildRouteTree(appDir: string): {
+declare function matchRoute(urlPath: string, routes: Route[]): RouteMatch | null;
+
+/**
+ * Creates regex pattern for route matching
+ */
+declare function createRoutePattern(routePath: string): RegExp;
+
+/**
+ * Velix v5 Router
+ * File-based routing using the app/ directory convention
+ */
+/**
+ * Builds the complete route tree from the app/ directory asynchronously
+ */
+declare function buildRouteTree(appDir: string): Promise<{
     pages: Route[];
     api: Route[];
     layouts: Map<string, string>;
     tree: RouteTreeNode;
     appRoutes: Route[];
     rootLayout?: string;
-};
-/**
- * Matches URL path against routes
- */
-declare function matchRoute(urlPath: string, routes: Route[]): {
-    params: Record<string, string>;
-    type: RouteType$1;
-    path: string;
-    filePath: string;
-    pattern: RegExp;
-    segments: string[];
-    layout?: string | null;
-    loading?: string | null;
-    error?: string | null;
-    notFound?: string | null;
-    template?: string | null;
-    middleware?: string | null;
-    isServerComponent?: boolean;
-    isClientComponent?: boolean;
-    isIsland?: boolean;
-} | null;
-/**
- * Finds all layouts that apply to a route
- */
-declare function findRouteLayouts(route: Route, layoutsMap: Map<string, string>): Array<{
-    name: string;
-    filePath: string | undefined;
 }>;
 
 /**
@@ -1191,107 +1190,41 @@ declare function isClientComponent(filePath: string): boolean;
  */
 declare function isIsland(filePath: string): boolean;
 
-/**
- * Velix v5 — Advanced Cache (VelixCache)
- *
- * Production-grade caching with:
- * - LRU eviction (configurable maxSize)
- * - TTL-based expiration
- * - Stale-while-revalidate (SWR) window
- * - Tag-based invalidation
- * - Type-safe generics
- */
-type RevalidationType = 'path' | 'tag' | 'layout';
-interface CacheOptions {
-    /** Time-to-live in milliseconds */
+interface ICacheAdapter {
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T, options?: CacheSetOptions): Promise<void>;
+    delete(key: string): Promise<void>;
+    deleteByTag(tag: string): Promise<void>;
+    deleteByPrefix(prefix: string): Promise<void>;
+    clear(): Promise<void>;
+    has(key: string): Promise<boolean>;
+}
+type CacheSetOptions = {
     ttl?: number;
-    /** Stale-while-revalidate window in milliseconds (after TTL expires) */
-    swr?: number;
-    /** Tags for group invalidation */
     tags?: string[];
-}
-interface VelixCacheConfig {
-    /** Maximum number of entries (default: 1000) */
-    maxSize?: number;
-    /** Default TTL in ms (default: 60_000 — 1 minute) */
-    defaultTtl?: number;
-    /** Default SWR window in ms (default: 10_000 — 10 seconds) */
-    defaultSwr?: number;
-}
+};
+
+type RevalidationType = 'path' | 'tag' | 'layout';
 declare class VelixCache {
-    private readonly maxSize;
-    private readonly defaultTtl;
-    private readonly defaultSwr;
-    private readonly store;
-    private readonly tagIndex;
-    private readonly head;
-    private readonly tail;
-    constructor(config?: VelixCacheConfig);
-    /** Current number of entries */
-    get size(): number;
-    /**
-     * Store a value with optional TTL, SWR, and tags.
-     */
-    set<T>(key: string, value: T, options?: CacheOptions): void;
-    /**
-     * Get a cached value. Returns `null` if not found or expired beyond SWR window.
-     *
-     * @returns `{ value, stale }` — `stale` is true when the entry is past TTL but within SWR window.
-     */
-    get<T>(key: string): {
-        value: T;
-        stale: boolean;
-    } | null;
-    /**
-     * Simple get that returns only the value (ignoring staleness).
-     * Returns `null` if not found or expired.
-     */
-    getValue<T>(key: string): T | null;
-    /** Check whether a key exists and is not expired */
-    has(key: string): boolean;
-    /** Remove a specific key */
-    delete(key: string): boolean;
-    /** Invalidate a specific path/key */
-    revalidatePath(path: string): void;
-    /** Invalidate all entries associated with a tag */
-    revalidateTag(tag: string): void;
-    /** Clear all entries */
-    invalidateAll(): void;
-    /** Get cache stats for debugging/monitoring */
-    stats(): {
-        size: number;
-        maxSize: number;
-        tags: number;
-    };
-    private createSentinel;
-    private addToHead;
-    private removeFromList;
-    private moveToHead;
-    private evictLRU;
-    private removeEntry;
+    private adapter;
+    private deduplicator;
+    constructor(adapter?: ICacheAdapter);
+    revalidatePath(path: string): Promise<void>;
+    revalidateTag(tag: string): Promise<void>;
+    unstable_cache<T>(fn: () => Promise<T>, keys: string[], options?: {
+        tags?: string[];
+        revalidate?: number;
+    }): () => Promise<T>;
 }
 declare const cacheManager: VelixCache;
 /**
  * Revalidate a specific path
- * @example
- * ```ts
- * import { revalidatePath } from 'velix/actions';
- *
- * await revalidatePath('/blog');
- * await revalidatePath('/blog/[slug]', 'layout');
- * ```
  */
-declare function revalidatePath(path: string, _type?: RevalidationType): void;
+declare function revalidatePath(path: string, _type?: RevalidationType): Promise<void>;
 /**
  * Revalidate all paths with a specific cache tag
- * @example
- * ```ts
- * import { revalidateTag } from 'velix/actions';
- *
- * await revalidateTag('blog-posts');
- * ```
  */
-declare function revalidateTag(tag: string): void;
+declare function revalidateTag(tag: string): Promise<void>;
 /**
  * Unstable cache wrapper (experimental)
  */
@@ -1382,6 +1315,48 @@ type LoaderResult<T> = {
 };
 declare function defineLoader<T>(fn: (ctx: LoaderContext) => Promise<T>): (ctx: LoaderContext) => Promise<LoaderResult<T>>;
 
+/**
+ * Backplane Redis Pub/Sub pour la synchronisation HMR multi-instances.
+ *
+ * Problème sans backplane :
+ *   Pod A déclenche un HMR → notifie uniquement ses clients WebSocket.
+ *   Les clients connectés sur les pods B et C ne reçoivent rien.
+ *
+ * Solution :
+ *   Chaque pod publie ses events HMR sur le channel Redis 'velix:hmr'.
+ *   Chaque pod écoute ce channel et rebroadcast aux clients WebSocket locaux.
+ *
+ * @example
+ * ```ts
+ * import { HMRPubSubBackplane } from 'velix-core/dev/hmr-pubsub';
+ * import { createHMRServer } from 'velix-core/dev/hmr-server';
+ *
+ * const pubsub = new HMRPubSubBackplane(process.env.REDIS_URL);
+ * const hmr = createHMRServer(httpServer, projectRoot, { pubsub });
+ * ```
+ */
+declare class HMRPubSubBackplane {
+    private pub;
+    private sub;
+    private handlers;
+    constructor(redisUrl: string);
+    /**
+     * Publie un event HMR sur le channel Redis.
+     * Tous les pods abonnés le recevront et le rebroadcastent à leurs clients.
+     */
+    publish(event: HMREvent): Promise<void>;
+    /**
+     * S'abonne aux events HMR reçus depuis les autres instances.
+     * Retourne une fonction de désinscription.
+     */
+    onEvent(handler: (event: HMREvent) => void): () => void;
+    /**
+     * Ferme proprement les connexions pub et sub.
+     * À appeler au shutdown du serveur de dev.
+     */
+    disconnect(): Promise<void>;
+}
+
 type HMREvent = {
     type: 'file-changed';
     file: string;
@@ -1408,8 +1383,16 @@ type HMREvent = {
     type: 'full-reload';
     timestamp: number;
 };
-declare function createHMRServer(httpServer: Server, projectRoot: string): {
+interface HMRServerOptions {
+    /**
+     * Backplane Redis Pub/Sub pour la synchronisation HMR multi-instances.
+     * Optionnel — si absent, le HMR est local à cette instance uniquement.
+     */
+    pubsub?: HMRPubSubBackplane;
+}
+declare function createHMRServer(httpServer: Server, projectRoot: string, options?: HMRServerOptions): {
     broadcast: (event: HMREvent) => void;
+    broadcastLocal: (event: HMREvent) => void;
     watcher: chokidar.FSWatcher;
     wss: ws.Server<typeof WebSocket, typeof http.IncomingMessage>;
     clients: Set<WebSocket>;
@@ -1427,4 +1410,4 @@ declare function resolveErrorBoundary(routeFilePath: string, appDir: string, typ
 declare function defineError(component: ErrorComponent): ErrorComponent;
 declare function defineNotFound(component: NotFoundComponent): NotFoundComponent;
 
-export { type AIClient, type AIInput, type AIPluginConfig, type AIProvider, type AIProviderType, type AIResponse, type AIStreamChunk, type ActionAIConfig, type ActionContext, type ActionOptions, type ActionResult, type ActionState, type Alternates, type ApiHandler, type ApiRoute, type Author, type BuildOptions, type BuildResult, type CacheOptions, type ChatInput, type ChatMessage, type EmbedInput, type EmbedResponse, type ErrorBoundaryType, type ErrorComponent, type ErrorProps, ForbiddenError, type FormatDetection, type HMREvent, type HttpMethod, type IconDescriptor, type Icons, type InferActionInput, type InferActionOutput, type InferLoaderData, type IslandConfig, type IslandManifest, type LayoutComponent, type LayoutProps, type LoaderContext, type LoaderResult, type LoadingComponent, type LoadingProps, type Metadata, type Middleware, type MiddlewareFunction, type MiddlewareRequest, type MiddlewareResponse, type MiddlewareResult, type NextFunction, type NotFoundComponent, NotFoundError, type NotFoundProps, type OGImage, type OGVideo, OllamaProvider, OpenAIProvider, type OpenGraph, type PageComponent, type PageProps, type PluginHook, type PluginHookArgs, PluginHooks, PluginManager, type ResolvedBoundary, type RevalidationType, type Robots, type Route, type RouteContext, type RouteHandler, type RouteMatch, type RouteTree, RouteType, type ServerAction, type StaticPath, type StaticProps, type TailwindPluginOptions, type ThemeColor, type Twitter, type TwitterImage, type TypedActionResult, UnauthorizedError, VelixCache, type VelixConfig, VelixConfigSchema, VelixHttpError, type VelixPlugin, type VelixPluginDefinition, type Verification, type Viewport, buildApiManifest, buildPrompt, buildRouteTree, builtinPlugins, cacheManager, cleanDir, composeMiddleware, copyDir, createAIAction, createAIClient, createDeferred, createHMRServer, createStreamDecoder, debounce, defaultConfig, defineConfig, defineError, defineLoader, defineNotFound, definePlugin, defineRoute, ensureDir, escapeHtml, estimateTokens, filePathToRoute, findFiles, findRouteLayouts, formatBytes, formatTime, generateHash, generateJsonLd, generateMetadataTags, generateRobotsTxt, generateSitemap, getErrorBoundaryType, handleApiRequest, isClientComponent, isIsland, isServerComponent, jsonLd, loadConfig, loadMiddleware, loadPlugins, logger, matchRoute, mergeMetadata, middlewares, parseSSE, pluginManager, resolveErrorBoundary, resolvePaths, retry, revalidatePath, revalidateTag, runMiddleware, safeJsonParse, sanitizeInput, serverAction, sleep, truncateToTokens, unstable_cache, useAI, validateApiKey, validateInput };
+export { type AIClient, type AIInput, type AIPluginConfig, type AIProvider, type AIProviderType, type AIResponse, type AIStreamChunk, type ActionAIConfig, type ActionContext, type ActionOptions, type ActionResult, type ActionState, type Alternates, type ApiHandler, type ApiRoute, type Author, type BuildOptions, type BuildResult, type ChatInput, type ChatMessage, type EmbedInput, type EmbedResponse, type ErrorBoundaryType, type ErrorComponent, type ErrorProps, ForbiddenError, type FormatDetection, type HMREvent, type HMRServerOptions, type HttpMethod, type IconDescriptor, type Icons, type InferActionInput, type InferActionOutput, type InferLoaderData, type IslandConfig, type IslandManifest, type LayoutComponent, type LayoutProps, type LoaderContext, type LoaderResult, type LoadingComponent, type LoadingProps, type Metadata, type Middleware, type MiddlewareFunction, type MiddlewareRequest, type MiddlewareResponse, type MiddlewareResult, type NextFunction, type NotFoundComponent, NotFoundError, type NotFoundProps, type OGImage, type OGVideo, OllamaProvider, OpenAIProvider, type OpenGraph, type PageComponent, type PageProps, type PluginHook, type PluginHookArgs, PluginHooks, PluginManager, type ResolvedBoundary, type RevalidationType, type Robots, type Route, type RouteContext, type RouteHandler, type RouteMatch$1 as RouteMatch, type RouteTree, RouteType, type ServerAction, type StaticPath, type StaticProps, type TailwindPluginOptions, type ThemeColor, type Twitter, type TwitterImage, type TypedActionResult, UnauthorizedError, VelixCache, type VelixConfig, VelixConfigSchema, VelixHttpError, type VelixPlugin, type VelixPluginDefinition, type Verification, type Viewport, buildApiManifest, buildPrompt, buildRouteTree, builtinPlugins, cacheManager, cleanDir, composeMiddleware, copyDir, createAIAction, createAIClient, createDeferred, createHMRServer, createRoutePattern, createStreamDecoder, debounce, defaultConfig, defineConfig, defineError, defineLoader, defineNotFound, definePlugin, defineRoute, ensureDir, escapeHtml, estimateTokens, filePathToRoute, findFiles, findRouteLayouts, formatBytes, formatTime, generateHash, generateJsonLd, generateMetadataTags, generateRobotsTxt, generateSitemap, getErrorBoundaryType, handleApiRequest, isClientComponent, isIsland, isServerComponent, jsonLd, loadConfig, loadMiddleware, loadPlugins, logger, matchRoute, mergeMetadata, middlewares, parseSSE, pluginManager, resolveErrorBoundary, resolvePaths, retry, revalidatePath, revalidateTag, runMiddleware, safeJsonParse, sanitizeInput, serverAction, sleep, truncateToTokens, unstable_cache, useAI, validateApiKey, validateInput };