@lolyjs/core 0.2.0-alpha.3 → 0.2.0-alpha.30

package/dist/index.types-B9j4OQft.d.mts

@@ -0,0 +1,222 @@
+import { Request, Response } from 'express';
+
+type GenerateStaticParams = () => Array<Record<string, string>> | Promise<Array<Record<string, string>>>;
+interface ServerContext {
+    req: Request;
+    res: Response;
+    params: Record<string, string>;
+    pathname: string;
+    locals: Record<string, any>;
+}
+interface WssActions {
+    /**
+     * Emit to current socket only (reply)
+     */
+    reply(event: string, payload?: any): void;
+    /**
+     * Emit an event to all clients in the namespace
+     */
+    emit: (event: string, ...args: any[]) => void;
+    /**
+     * Emit to everyone except current socket
+     */
+    broadcast(event: string, payload?: any, opts?: {
+        excludeSelf?: boolean;
+    }): void;
+    /**
+     * Join a room
+     */
+    join(room: string): Promise<void>;
+    /**
+     * Leave a room
+     */
+    leave(room: string): Promise<void>;
+    /**
+     * Emit to a specific room
+     */
+    toRoom(room: string): {
+        emit(event: string, payload?: any): void;
+    };
+    /**
+     * Emit to a specific user (by userId)
+     * Uses presence mapping to find user's sockets
+     */
+    toUser(userId: string): {
+        emit(event: string, payload?: any): void;
+    };
+    /**
+     * Emit error event (reserved event: __loly:error)
+     */
+    error(code: string, message: string, details?: any): void;
+    /**
+     * Emit an event to a specific socket by Socket.IO socket ID
+     * @deprecated Use toUser() for user targeting
+     */
+    emitTo?: (socketId: string, event: string, ...args: any[]) => void;
+    /**
+     * Emit an event to a specific client by custom clientId
+     * @deprecated Use toUser() for user targeting
+     */
+    emitToClient?: (clientId: string, event: string, ...args: any[]) => void;
+}
+/**
+ * Route middleware function type.
+ * Middlewares run before getServerSideProps and can modify ctx.locals, set headers, redirect, etc.
+ *
+ * @param ctx - Server context with optional theme
+ * @param next - Function to call the next middleware in the chain (must be awaited if used)
+ * @returns Promise<void> | void
+ *
+ * @example
+ * // Simple middleware that adds data to ctx.locals
+ * export const beforeServerData: RouteMiddleware[] = [
+ *   async (ctx, next) => {
+ *     ctx.locals.user = await getUser(ctx.req);
+ *     await next();
+ *   }
+ * ];
+ *
+ * @example
+ * // Middleware that redirects
+ * export const beforeServerData: RouteMiddleware[] = [
+ *   async (ctx, next) => {
+ *     if (!ctx.locals.user) {
+ *       ctx.res.redirect('/login');
+ *       return; // Don't call next() if redirecting
+ *     }
+ *     await next();
+ *   }
+ * ];
+ */
+type RouteMiddleware = (ctx: ServerContext & {
+    theme?: string;
+}, next: () => Promise<void>) => Promise<void> | void;
+/**
+ * Result returned by a server loader (getServerSideProps).
+ * @template TProps - Type of props that will be passed to the component (defaults to Record<string, any>)
+ */
+interface LoaderResult<TProps extends Record<string, any> = Record<string, any>> {
+    pathname?: string;
+    props?: TProps;
+    redirect?: {
+        destination: string;
+        permanent?: boolean;
+    };
+    notFound?: boolean;
+    metadata?: PageMetadata | null;
+    className?: string;
+    theme?: string;
+}
+/**
+ * Server loader function type (getServerSideProps).
+ * This function is exported from server.hook.ts files.
+ *
+ * @template TProps - Type of props that will be returned (defaults to Record<string, any>)
+ *
+ * @example
+ * // Typed loader
+ * export const getServerSideProps: ServerLoader<{ user: User; posts: Post[] }> = async (ctx) => ({
+ *   props: { user: await getUser(), posts: await getPosts() }
+ * });
+ *
+ * @example
+ * // Untyped loader (backward compatible)
+ * export const getServerSideProps: ServerLoader = async (ctx) => ({
+ *   props: { any: 'data' }
+ * });
+ */
+type ServerLoader<TProps extends Record<string, any> = Record<string, any>> = (ctx: ServerContext) => Promise<LoaderResult<TProps>>;
+/**
+ * Comprehensive page metadata for SEO and social sharing.
+ * Supports standard HTML meta tags, Open Graph, Twitter Cards, and more.
+ */
+interface PageMetadata {
+    /** Page title (sets <title> tag) */
+    title?: string;
+    /** Page description (sets <meta name="description">) */
+    description?: string;
+    /** Language code (sets <html lang="...">) */
+    lang?: string;
+    /** Canonical URL (sets <link rel="canonical">) */
+    canonical?: string;
+    /** Robots directive (sets <meta name="robots">) */
+    robots?: string;
+    /** Theme color (sets <meta name="theme-color">) */
+    themeColor?: string;
+    /** Viewport configuration (sets <meta name="viewport">) */
+    viewport?: string;
+    /** Open Graph metadata for social sharing */
+    openGraph?: {
+        title?: string;
+        description?: string;
+        type?: string;
+        url?: string;
+        image?: string | {
+            url: string;
+            width?: number;
+            height?: number;
+            alt?: string;
+        };
+        siteName?: string;
+        locale?: string;
+    };
+    /** Twitter Card metadata */
+    twitter?: {
+        card?: "summary" | "summary_large_image" | "app" | "player";
+        title?: string;
+        description?: string;
+        image?: string;
+        imageAlt?: string;
+        site?: string;
+        creator?: string;
+    };
+    /** Additional custom meta tags */
+    metaTags?: {
+        name?: string;
+        property?: string;
+        httpEquiv?: string;
+        content: string;
+    }[];
+    /** Additional link tags (e.g., preconnect, dns-prefetch) */
+    links?: {
+        rel: string;
+        href: string;
+        as?: string;
+        crossorigin?: string;
+        type?: string;
+    }[];
+}
+type MetadataLoader = (ctx: ServerContext) => PageMetadata | Promise<PageMetadata>;
+interface ApiContext {
+    req: Request;
+    res: Response;
+    Response: (body?: any, status?: number) => Response<any, Record<string, any>>;
+    NotFound: (body?: any) => Response<any, Record<string, any>>;
+    params: Record<string, string>;
+    pathname: string;
+    locals: Record<string, any>;
+}
+/**
+ * API middleware function type.
+ * Middlewares run before the API handler and can modify ctx.locals, set headers, etc.
+ *
+ * @param ctx - API context
+ * @param next - Function to call the next middleware in the chain (must be awaited if used)
+ * @returns Promise<void> | void
+ *
+ * @example
+ * // Authentication middleware
+ * export const middlewares: ApiMiddleware[] = [
+ *   async (ctx, next) => {
+ *     const token = ctx.req.headers.authorization;
+ *     if (!token) {
+ *       return ctx.Response({ error: 'Unauthorized' }, 401);
+ *     }
+ *     ctx.locals.user = await verifyToken(token);
+ *     await next();
+ *   }
+ * ];
+ */
+type ApiMiddleware = (ctx: ApiContext, next: () => Promise<void>) => void | Promise<void>;
+
+export type { ApiMiddleware as A, GenerateStaticParams as G, LoaderResult as L, MetadataLoader as M, PageMetadata as P, RouteMiddleware as R, ServerContext as S, WssActions as W, ApiContext as a, ServerLoader as b };

package/dist/index.types-B9j4OQft.d.ts

@@ -0,0 +1,222 @@
+import { Request, Response } from 'express';
+
+type GenerateStaticParams = () => Array<Record<string, string>> | Promise<Array<Record<string, string>>>;
+interface ServerContext {
+    req: Request;
+    res: Response;
+    params: Record<string, string>;
+    pathname: string;
+    locals: Record<string, any>;
+}
+interface WssActions {
+    /**
+     * Emit to current socket only (reply)
+     */
+    reply(event: string, payload?: any): void;
+    /**
+     * Emit an event to all clients in the namespace
+     */
+    emit: (event: string, ...args: any[]) => void;
+    /**
+     * Emit to everyone except current socket
+     */
+    broadcast(event: string, payload?: any, opts?: {
+        excludeSelf?: boolean;
+    }): void;
+    /**
+     * Join a room
+     */
+    join(room: string): Promise<void>;
+    /**
+     * Leave a room
+     */
+    leave(room: string): Promise<void>;
+    /**
+     * Emit to a specific room
+     */
+    toRoom(room: string): {
+        emit(event: string, payload?: any): void;
+    };
+    /**
+     * Emit to a specific user (by userId)
+     * Uses presence mapping to find user's sockets
+     */
+    toUser(userId: string): {
+        emit(event: string, payload?: any): void;
+    };
+    /**
+     * Emit error event (reserved event: __loly:error)
+     */
+    error(code: string, message: string, details?: any): void;
+    /**
+     * Emit an event to a specific socket by Socket.IO socket ID
+     * @deprecated Use toUser() for user targeting
+     */
+    emitTo?: (socketId: string, event: string, ...args: any[]) => void;
+    /**
+     * Emit an event to a specific client by custom clientId
+     * @deprecated Use toUser() for user targeting
+     */
+    emitToClient?: (clientId: string, event: string, ...args: any[]) => void;
+}
+/**
+ * Route middleware function type.
+ * Middlewares run before getServerSideProps and can modify ctx.locals, set headers, redirect, etc.
+ *
+ * @param ctx - Server context with optional theme
+ * @param next - Function to call the next middleware in the chain (must be awaited if used)
+ * @returns Promise<void> | void
+ *
+ * @example
+ * // Simple middleware that adds data to ctx.locals
+ * export const beforeServerData: RouteMiddleware[] = [
+ *   async (ctx, next) => {
+ *     ctx.locals.user = await getUser(ctx.req);
+ *     await next();
+ *   }
+ * ];
+ *
+ * @example
+ * // Middleware that redirects
+ * export const beforeServerData: RouteMiddleware[] = [
+ *   async (ctx, next) => {
+ *     if (!ctx.locals.user) {
+ *       ctx.res.redirect('/login');
+ *       return; // Don't call next() if redirecting
+ *     }
+ *     await next();
+ *   }
+ * ];
+ */
+type RouteMiddleware = (ctx: ServerContext & {
+    theme?: string;
+}, next: () => Promise<void>) => Promise<void> | void;
+/**
+ * Result returned by a server loader (getServerSideProps).
+ * @template TProps - Type of props that will be passed to the component (defaults to Record<string, any>)
+ */
+interface LoaderResult<TProps extends Record<string, any> = Record<string, any>> {
+    pathname?: string;
+    props?: TProps;
+    redirect?: {
+        destination: string;
+        permanent?: boolean;
+    };
+    notFound?: boolean;
+    metadata?: PageMetadata | null;
+    className?: string;
+    theme?: string;
+}
+/**
+ * Server loader function type (getServerSideProps).
+ * This function is exported from server.hook.ts files.
+ *
+ * @template TProps - Type of props that will be returned (defaults to Record<string, any>)
+ *
+ * @example
+ * // Typed loader
+ * export const getServerSideProps: ServerLoader<{ user: User; posts: Post[] }> = async (ctx) => ({
+ *   props: { user: await getUser(), posts: await getPosts() }
+ * });
+ *
+ * @example
+ * // Untyped loader (backward compatible)
+ * export const getServerSideProps: ServerLoader = async (ctx) => ({
+ *   props: { any: 'data' }
+ * });
+ */
+type ServerLoader<TProps extends Record<string, any> = Record<string, any>> = (ctx: ServerContext) => Promise<LoaderResult<TProps>>;
+/**
+ * Comprehensive page metadata for SEO and social sharing.
+ * Supports standard HTML meta tags, Open Graph, Twitter Cards, and more.
+ */
+interface PageMetadata {
+    /** Page title (sets <title> tag) */
+    title?: string;
+    /** Page description (sets <meta name="description">) */
+    description?: string;
+    /** Language code (sets <html lang="...">) */
+    lang?: string;
+    /** Canonical URL (sets <link rel="canonical">) */
+    canonical?: string;
+    /** Robots directive (sets <meta name="robots">) */
+    robots?: string;
+    /** Theme color (sets <meta name="theme-color">) */
+    themeColor?: string;
+    /** Viewport configuration (sets <meta name="viewport">) */
+    viewport?: string;
+    /** Open Graph metadata for social sharing */
+    openGraph?: {
+        title?: string;
+        description?: string;
+        type?: string;
+        url?: string;
+        image?: string | {
+            url: string;
+            width?: number;
+            height?: number;
+            alt?: string;
+        };
+        siteName?: string;
+        locale?: string;
+    };
+    /** Twitter Card metadata */
+    twitter?: {
+        card?: "summary" | "summary_large_image" | "app" | "player";
+        title?: string;
+        description?: string;
+        image?: string;
+        imageAlt?: string;
+        site?: string;
+        creator?: string;
+    };
+    /** Additional custom meta tags */
+    metaTags?: {
+        name?: string;
+        property?: string;
+        httpEquiv?: string;
+        content: string;
+    }[];
+    /** Additional link tags (e.g., preconnect, dns-prefetch) */
+    links?: {
+        rel: string;
+        href: string;
+        as?: string;
+        crossorigin?: string;
+        type?: string;
+    }[];
+}
+type MetadataLoader = (ctx: ServerContext) => PageMetadata | Promise<PageMetadata>;
+interface ApiContext {
+    req: Request;
+    res: Response;
+    Response: (body?: any, status?: number) => Response<any, Record<string, any>>;
+    NotFound: (body?: any) => Response<any, Record<string, any>>;
+    params: Record<string, string>;
+    pathname: string;
+    locals: Record<string, any>;
+}
+/**
+ * API middleware function type.
+ * Middlewares run before the API handler and can modify ctx.locals, set headers, etc.
+ *
+ * @param ctx - API context
+ * @param next - Function to call the next middleware in the chain (must be awaited if used)
+ * @returns Promise<void> | void
+ *
+ * @example
+ * // Authentication middleware
+ * export const middlewares: ApiMiddleware[] = [
+ *   async (ctx, next) => {
+ *     const token = ctx.req.headers.authorization;
+ *     if (!token) {
+ *       return ctx.Response({ error: 'Unauthorized' }, 401);
+ *     }
+ *     ctx.locals.user = await verifyToken(token);
+ *     await next();
+ *   }
+ * ];
+ */
+type ApiMiddleware = (ctx: ApiContext, next: () => Promise<void>) => void | Promise<void>;
+
+export type { ApiMiddleware as A, GenerateStaticParams as G, LoaderResult as L, MetadataLoader as M, PageMetadata as P, RouteMiddleware as R, ServerContext as S, WssActions as W, ApiContext as a, ServerLoader as b };

package/dist/react/cache.cjs

@@ -113,14 +113,16 @@ function deleteCacheEntry(key) {
 function buildDataUrl(url) {
   return url + (url.includes("?") ? "&" : "?") + "__fw_data=1";
 }
-async function fetchRouteDataOnce(url) {
+async function fetchRouteDataOnce(url, skipLayoutHooks = true) {
   const dataUrl = buildDataUrl(url);
-  const res = await fetch(dataUrl, {
-    headers: {
-      "x-fw-data": "1",
-      Accept: "application/json"
-    }
-  });
+  const headers = {
+    "x-fw-data": "1",
+    Accept: "application/json"
+  };
+  if (skipLayoutHooks) {
+    headers["x-skip-layout-hooks"] = "true";
+  }
+  const res = await fetch(dataUrl, { headers });
   let json = {};
   try {
     const text = await res.text();
@@ -140,7 +142,7 @@ async function fetchRouteDataOnce(url) {
   };
   return result;
 }
-function revalidatePath(path) {
+function revalidatePath(path, skipAutoRevalidate = false) {
   const normalizedPath = path.split("?")[0];
   const hasQueryParams = path.includes("?");
   const keysForPath = pathIndex.get(normalizedPath);
@@ -167,30 +169,86 @@ function revalidatePath(path) {
   keysToDelete.forEach((key) => {
     deleteCacheEntry(key);
   });
+  if (!skipAutoRevalidate && typeof window !== "undefined") {
+    const currentPathname = window.location.pathname;
+    const currentSearch = window.location.search;
+    const matchesCurrentPath = normalizedPath === currentPathname;
+    if (matchesCurrentPath) {
+      if (hasQueryParams && specificQueryParams) {
+        const currentQueryParams = currentSearch.replace("?", "").split("&").filter((p) => !p.startsWith("__fw_data=")).sort().join("&");
+        if (currentQueryParams === specificQueryParams) {
+          revalidate().catch((err) => {
+            console.error(
+              "[client][cache] Error revalidating current route:",
+              err
+            );
+          });
+        }
+      } else {
+        revalidate().catch((err) => {
+          console.error(
+            "[client][cache] Error revalidating current route:",
+            err
+          );
+        });
+      }
+    }
+  }
 }
+var isRevalidating = false;
 async function revalidate() {
   if (typeof window === "undefined") {
     throw new Error("revalidate() can only be called on the client");
   }
-  const pathname = window.location.pathname + window.location.search;
-  revalidatePath(pathname);
-  const freshData = await getRouteData(pathname, { revalidate: true });
-  if (window.__FW_DATA__ && freshData.ok && freshData.json) {
-    const currentData = window.__FW_DATA__;
-    window.__FW_DATA__ = {
-      ...currentData,
-      pathname: pathname.split("?")[0],
-      params: freshData.json.params || currentData.params || {},
-      props: freshData.json.props || currentData.props || {},
-      metadata: freshData.json.metadata ?? currentData.metadata ?? null,
-      notFound: freshData.json.notFound ?? false,
-      error: freshData.json.error ?? false
-    };
-    window.dispatchEvent(new CustomEvent("fw-data-refresh", {
-      detail: { data: freshData }
-    }));
-  }
-  return freshData;
+  if (isRevalidating) {
+    const key = buildDataUrl(window.location.pathname + window.location.search);
+    const entry = dataCache.get(key);
+    if (entry && entry.status === "pending") {
+      return entry.promise;
+    }
+  }
+  isRevalidating = true;
+  try {
+    const pathname = window.location.pathname + window.location.search;
+    revalidatePath(pathname, true);
+    const freshData = await getRouteData(pathname, { revalidate: true });
+    if (window.__FW_DATA__ && freshData.ok && freshData.json) {
+      const currentData = window.__FW_DATA__;
+      if (freshData.json.layoutProps !== void 0 && freshData.json.layoutProps !== null) {
+        window.__FW_LAYOUT_PROPS__ = freshData.json.layoutProps;
+      }
+      let combinedProps = currentData.props || {};
+      if (freshData.json.layoutProps !== void 0 && freshData.json.layoutProps !== null) {
+        combinedProps = {
+          ...freshData.json.layoutProps,
+          ...freshData.json.pageProps ?? freshData.json.props ?? {}
+        };
+      } else if (freshData.json.pageProps !== void 0) {
+        const preservedLayoutProps = window.__FW_LAYOUT_PROPS__ || {};
+        combinedProps = {
+          ...preservedLayoutProps,
+          ...freshData.json.pageProps
+        };
+      } else if (freshData.json.props) {
+        combinedProps = freshData.json.props;
+      }
+      window.__FW_DATA__ = {
+        ...currentData,
+        pathname: pathname.split("?")[0],
+        params: freshData.json.params || currentData.params || {},
+        props: combinedProps,
+        metadata: freshData.json.metadata ?? currentData.metadata ?? null,
+        notFound: freshData.json.notFound ?? false,
+        error: freshData.json.error ?? false
+      };
+      window.dispatchEvent(new CustomEvent("fw-data-refresh", {
+        detail: { data: freshData }
+      }));
+    }
+    return freshData;
+  } finally {
+    isRevalidating = false;
+  }
 }
 function revalidateRouteData(url) {
   revalidatePath(url);
@@ -204,7 +262,7 @@ function prefetchRouteData(url) {
     }
     return;
   }
-  const promise = fetchRouteDataOnce(url).then((value) => {
+  const promise = fetchRouteDataOnce(url, true).then((value) => {
     setCacheEntry(key, { status: "fulfilled", value });
     return value;
   }).catch((error) => {
@@ -220,7 +278,7 @@ async function getRouteData(url, options) {
     deleteCacheEntry(key);
   }
   const entry = dataCache.get(key);
-  if (entry) {
+  if (entry && !options?.revalidate) {
     if (entry.status === "fulfilled") {
       updateLRU(key);
       return entry.value;
@@ -229,12 +287,29 @@ async function getRouteData(url, options) {
       return entry.promise;
     }
   }
-  const promise = fetchRouteDataOnce(url).then((value) => {
-    setCacheEntry(key, { status: "fulfilled", value });
+  const skipLayoutHooks = !options?.revalidate;
+  const currentEntry = dataCache.get(key);
+  if (currentEntry && !options?.revalidate) {
+    if (currentEntry.status === "fulfilled") {
+      updateLRU(key);
+      return currentEntry.value;
+    }
+    if (currentEntry.status === "pending") {
+      return currentEntry.promise;
+    }
+  }
+  const promise = fetchRouteDataOnce(url, skipLayoutHooks).then((value) => {
+    const entryAfterFetch = dataCache.get(key);
+    if (!entryAfterFetch || entryAfterFetch.status === "pending") {
+      setCacheEntry(key, { status: "fulfilled", value });
+    }
     return value;
   }).catch((error) => {
     console.error("[client][cache] Error fetching route data:", error);
-    dataCache.set(key, { status: "rejected", error });
+    const entryAfterFetch = dataCache.get(key);
+    if (!entryAfterFetch || entryAfterFetch.status === "pending") {
+      dataCache.set(key, { status: "rejected", error });
+    }
     throw error;
   });
   dataCache.set(key, { status: "pending", promise });