@revealui/core 0.0.1-pre.0

package/dist/core/router/executeOnBeforeRouteHook.ts

@@ -0,0 +1,161 @@
+export { executeOnBeforeRouteHook };
+
+import pc from "@brillout/picocolors";
+import { assert } from "../gaurds/assertions/assert/base.js";
+import { assertPageContextProvidedByUser } from "../gaurds/assertions/assertPageContextProvidedByUser.js";
+import { assertUsage } from "../gaurds/assertions/assertUsage/base.js";
+import { assertWarning } from "../gaurds/assertions/assertWarning/index.js";
+import { executeHook } from "../hooks/executeHook.js";
+import type { Hook } from "../processing/getters/getHook.js";
+import type { PageContextForRoute, PageContextFromRoute } from "./index.js";
+import { assertRouteParams } from "./resolveRouteFunction.js";
+import {
+  assertUsageUrlPathnameAbsolute,
+  hasProp,
+  isObjectWithKeys,
+  joinEnglish,
+  objectAssign,
+} from "./utils.js";
+
+async function executeOnBeforeRouteHook(
+  pageContext: PageContextForRoute,
+): Promise<
+  | null
+  | ({ _routingProvidedByOnBeforeRouteHook: true } & PageContextFromRoute)
+  | { _routingProvidedByOnBeforeRouteHook: false }
+> {
+  const pageContextFromOnBeforeRouteHook = {};
+  if (!pageContext._onBeforeRouteHook) return null;
+  const pageContextFromHook = await getPageContextFromHook(
+    pageContext._onBeforeRouteHook,
+    pageContext,
+  );
+  if (pageContextFromHook) {
+    objectAssign(pageContextFromOnBeforeRouteHook, pageContextFromHook);
+    if (
+      hasProp(pageContextFromOnBeforeRouteHook, "pageId", "string") ||
+      hasProp(pageContextFromOnBeforeRouteHook, "pageId", "null")
+    ) {
+      // We bypass Reveal's routing
+      if (!hasProp(pageContextFromOnBeforeRouteHook, "routeParams")) {
+        objectAssign(pageContextFromOnBeforeRouteHook, { routeParams: {} });
+      } else {
+        assert(
+          hasProp(pageContextFromOnBeforeRouteHook, "routeParams", "object"),
+        );
+      }
+      objectAssign(pageContextFromOnBeforeRouteHook, {
+        _routingProvidedByOnBeforeRouteHook: true as const,
+        _debugRouteMatches: "CUSTOM_ROUTING" as const,
+      });
+      return pageContextFromOnBeforeRouteHook;
+    }
+  }
+  objectAssign(pageContextFromOnBeforeRouteHook, {
+    _routingProvidedByOnBeforeRouteHook: false as const,
+  });
+  return pageContextFromOnBeforeRouteHook;
+}
+
+async function getPageContextFromHook(
+  onBeforeRouteHook: Hook,
+  pageContext: {
+    urlOriginal: string;
+    _allPageIds: string[];
+  },
+): Promise<null | {
+  urlOriginal?: string;
+  urlLogical?: string;
+  pageId?: string | null;
+  routeParams?: Record<string, string>;
+}> {
+  let hookReturn: unknown = onBeforeRouteHook.hookFn(pageContext);
+
+  // TODO/v1-release: make executeOnBeforeRouteHook() and route() sync
+  hookReturn = await executeHook(
+    () => hookReturn,
+    onBeforeRouteHook,
+    pageContext,
+  );
+
+  const errPrefix = `The onBeforeRoute() hook defined by ${onBeforeRouteHook.hookFilePath}`;
+
+  assertUsage(
+    hookReturn === null ||
+      hookReturn === undefined ||
+      (isObjectWithKeys(hookReturn, ["pageContext"] as const) &&
+        hasProp(hookReturn, "pageContext")),
+    `${errPrefix} should return ${pc.cyan("null")}, ${pc.cyan("undefined")}, or a plain JavaScript object ${pc.cyan(
+      "{ pageContext: { /* ... */ } }",
+    )}`,
+  );
+
+  if (hookReturn === null || hookReturn === undefined) {
+    return null;
+  }
+
+  assertUsage(
+    hasProp(hookReturn, "pageContext", "object"),
+    `${errPrefix} returned ${pc.cyan("{ pageContext }")} but pageContext should be a plain JavaScript object.`,
+  );
+
+  if (
+    hasProp(hookReturn.pageContext, "pageId") &&
+    !hasProp(hookReturn.pageContext, "pageId", "null")
+  ) {
+    const errPrefix2 =
+      `${errPrefix} returned ${pc.cyan("{ pageContext: { pageId } }")} but ${pc.cyan(
+        "pageId",
+      )} should be` as const;
+    assertUsage(
+      hasProp(hookReturn.pageContext, "pageId", "string"),
+      `${errPrefix2} a string or null`,
+    );
+    assertUsage(
+      pageContext._allPageIds.includes(hookReturn.pageContext.pageId),
+      `${errPrefix2} ${joinEnglish(
+        pageContext._allPageIds.map((s) => pc.cyan(s)),
+        "or",
+      )}`,
+    );
+  }
+  if (hasProp(hookReturn.pageContext, "routeParams")) {
+    assertRouteParams(
+      hookReturn.pageContext,
+      `${errPrefix} returned ${pc.cyan("{ pageContext: { routeParams } }")} but routeParams should`,
+    );
+  }
+
+  const deprecatedReturn = (prop: "url" | "urlOriginal") =>
+    `${errPrefix} returned ${pc.cyan(`{ pageContext: { ${prop} } }`)} which is deprecated. Return ${pc.cyan(
+      "{ pageContext: { urlLogical } }",
+    )} instead.`;
+
+  if (hasProp(hookReturn.pageContext, "url")) {
+    assertWarning(false, deprecatedReturn("url"), { onlyOnce: true });
+    hookReturn.pageContext.urlLogical = hookReturn.pageContext.url;
+    delete hookReturn.pageContext.url;
+  }
+  if (hasProp(hookReturn.pageContext, "urlOriginal")) {
+    assertWarning(false, deprecatedReturn("urlOriginal"), { onlyOnce: true });
+    hookReturn.pageContext.urlLogical = hookReturn.pageContext.urlOriginal;
+    delete hookReturn.pageContext.urlOriginal;
+  }
+
+  if (hasProp(hookReturn.pageContext, "urlLogical")) {
+    assertUsageUrlPathnameAbsolute(
+      // We skip validation and type-cast instead of assertUsage() in order to save client-side KBs
+      hookReturn.pageContext.urlLogical as string,
+      `${errPrefix} returned ${pc.cyan("{ pageContext: { urlLogical } }")} but ${pc.cyan("urlLogical")}`,
+    );
+  }
+
+  assertPageContextProvidedByUser(hookReturn.pageContext, {
+    hookFilePath: onBeforeRouteHook.hookFilePath,
+    hookName: "onBeforeRoute",
+  });
+
+  const pageContextAddendumHook = {};
+  objectAssign(pageContextAddendumHook, hookReturn.pageContext);
+  return pageContextAddendumHook;
+}

package/dist/core/router/index.ts

@@ -0,0 +1,230 @@
+export { route }
+export type {
+  PageContextForRoute,
+  PageContextFromRoute,
+  PageRoutes,
+  RouteMatches,
+}
+
+import apiRoutes, { ApiRoute } from "./apiRoutes.js"
+import dynamicApiRoutes from "./dynamicApiRoutes.js"
+import dynamicPageRoutes from "./dynamicPageRoutes.js"
+import pageRoutes, { PageRoute } from "./pageRoutes.js"
+
+// Ensure we don't bloat runtime of Server Routing
+import { isBrowser } from "../gaurds/validators/isBrowser.js"
+
+if (isBrowser()) {
+  assertClientRouting()
+}
+
+// import pc from "@brillout/picocolors"
+
+
+import {
+  PageConfigGlobalRuntime,
+  PageConfigRuntime,
+} from "../../types/interfaces/page.js"
+import { assert } from "../gaurds/assertions/assert/index.js"
+import { assertClientRouting } from "../gaurds/assertions/assertRoutingType/index.js"
+import { assertUsage } from "../gaurds/assertions/assertUsage/base.js"
+import type { Hook } from "../processing/getters/getHook.js"
+import {
+  assertPageContextUrl,
+  PageContextUrlInternal,
+  PageContextUrlSource,
+} from "../processing/getters/getPageContextUrlComputed.js"
+import { debug } from "./debug.js"
+import { executeOnBeforeRouteHook } from "./executeOnBeforeRouteHook.js"
+import type { PageRoutes, RouteType } from "./loadPageRoutes.js"
+import { resolvePrecedence } from "./resolvePrecedence.js"
+import { resolveRouteFunction } from "./resolveRouteFunction.js"
+import { resolveRouteString } from "./resolveRouteString.js"
+import { isPlainObject, objectAssign } from "./utils.js"
+import {PageFile} from "../__internal/index.js"
+
+type PageContextForRoute = PageContextUrlInternal & {
+  _pageFilesAll: PageFile[]
+  _pageConfigs: PageConfigRuntime[]
+  _allPageIds: string[]
+  _pageConfigGlobal: PageConfigGlobalRuntime
+  _pageRoutes: PageRoutes
+  _onBeforeRouteHook: Hook | null
+} & PageContextUrlSource
+
+type PageContextFromRoute = {
+  pageId: string | null;
+  routeParams: Record<string, string>;
+  _routingProvidedByOnBeforeRouteHook?: boolean;
+  _debugRouteMatches: RouteMatches;
+  getPageRoutes?: PageRoute[] | (() => PageRoute[]);
+  getApiRoutes?: ApiRoute[] | (() => ApiRoute[]);
+  getDynamicPageRoutes?: () => Promise<{ getPageRoutes: PageRoute[] }>;
+  getDynamicApiRoutes?: () => Promise<{ getApiRoutes: ApiRoute[] }>;
+};
+
+type RouteMatch = {
+  pageId: string
+  routeString?: string
+  precedence?: number | null
+  routeType: RouteType
+  routeParams: Record<string, string>
+}
+type RouteMatches = "CUSTOM_ROUTING" | RouteMatch[]
+
+async function route(
+  pageContext: PageContextForRoute
+): Promise<PageContextFromRoute> {
+  if (!pageContext._pageRoutes) {
+    // Fetch page routes (statically)
+    const staticPageRoutes = await pageRoutes();
+    const getPageRoutes = () => staticPageRoutes;
+
+    // Fetch API routes (statically)
+    const staticApiRoutes = await apiRoutes();
+    const getApiRoutes = () => staticApiRoutes;
+
+    // Fetch page routes (dynamically)
+    const getDynamicPageRoutes = async () => {
+      const module = await dynamicPageRoutes("");
+      return {
+        getPageRoutes: Array.isArray(module.default) ? module.default : [],
+      };
+    };
+
+    // Fetch API routes (dynamically)
+    const getDynamicApiRoutes = async () => {
+      const module = await dynamicApiRoutes("");
+      return {
+        getApiRoutes: Array.isArray(module.default) ? module.default : [],
+      };
+    };
+
+    return {
+      pageId: null,
+      routeParams: {},
+      _debugRouteMatches: [],
+      getPageRoutes,
+      getApiRoutes,
+      getDynamicPageRoutes,
+      getDynamicApiRoutes,
+    };
+  }
+
+  debug("Pages routes:", pageContext._pageRoutes)
+  assertPageContextUrl(pageContext)
+  const pageContextFromRoute = {}
+
+  // onBeforeRoute()
+  const pageContextFromOnBeforeRouteHook =
+    await executeOnBeforeRouteHook(pageContext)
+  if (pageContextFromOnBeforeRouteHook) {
+    if (pageContextFromOnBeforeRouteHook._routingProvidedByOnBeforeRouteHook) {
+      assert(pageContextFromOnBeforeRouteHook.pageId)
+      return pageContextFromOnBeforeRouteHook
+    } else {
+      objectAssign(pageContextFromRoute, pageContextFromOnBeforeRouteHook)
+    }
+  }
+  // We take into account pageContext.urlLogical set by onBeforeRoute()
+  objectAssign(pageContext, pageContextFromOnBeforeRouteHook)
+
+  // reveal's routing
+  const allPageIds = pageContext._allPageIds
+  assertUsage(
+    allPageIds.length > 0,
+    "No page found. You must create at least one page."
+  )
+  assert(
+    pageContext._pageFilesAll.length > 0 || pageContext._pageConfigs.length > 0
+  )
+  const { urlPathname } = pageContext
+  assert(urlPathname.startsWith("/"))
+
+  const routeMatches: RouteMatch[] = []
+  await Promise.allSettled(
+    pageContext._pageRoutes.map(async (pageRoute): Promise<void> => {
+      const { pageId, routeType } = pageRoute
+
+      // Filesytem Routing
+      if (pageRoute.routeType === "FILESYSTEM") {
+        const { routeString } = pageRoute
+        const match = resolveRouteString(routeString, urlPathname)
+        if (match) {
+          const { routeParams } = match
+          routeMatches.push({ pageId, routeParams, routeString, routeType })
+        }
+        return
+      }
+
+      // Route String defined in `.page.route.js`
+      if (pageRoute.routeType === "STRING") {
+        const { routeString } = pageRoute
+        const match = resolveRouteString(routeString, urlPathname)
+        if (match) {
+          const { routeParams } = match
+          assert(routeType === "STRING")
+          routeMatches.push({
+            pageId,
+            routeString,
+            routeParams,
+            routeType,
+          })
+        }
+        return
+      }
+
+      // Route Function defined in `.page.route.js`
+      if (pageRoute.routeType === "FUNCTION") {
+        const { routeFunction, routeDefinedAtString } =
+          pageRoute as unknown as {
+            routeFunction: (pageContext: PageContextUrlInternal) => unknown
+            routeDefinedAtString: string
+          }
+        const match = await resolveRouteFunction(
+          routeFunction,
+          pageContext,
+          routeDefinedAtString
+        )
+        if (match) {
+          const { routeParams, precedence } = match
+          routeMatches.push({ pageId, precedence, routeParams, routeType })
+        }
+        return
+      }
+
+      assert(false)
+    })
+  )
+
+  resolvePrecedence(routeMatches)
+  const winner = routeMatches[0] ?? null
+
+  debug(
+    `Route matches for URL ${urlPathname} (in precedence order):`,
+    routeMatches
+  )
+
+  objectAssign(pageContextFromRoute, { _debugRouteMatches: routeMatches })
+  // For vite-plugin-vercel https://github.com/magne4000/vite-plugin-vercel/blob/main/packages/reveal-integration/reveal.ts#L173
+  objectAssign(pageContextFromRoute, { _routeMatch: winner })
+
+  if (!winner) {
+    objectAssign(pageContextFromRoute, {
+      pageId: null,
+      routeParams: {},
+    })
+    return pageContextFromRoute
+  }
+
+  {
+    const { routeParams } = winner
+    assert(isPlainObject(routeParams))
+    objectAssign(pageContextFromRoute, {
+      pageId: winner.pageId,
+      routeParams: winner.routeParams,
+    })
+  }
+
+  return pageContextFromRoute
+}

package/dist/core/router/loadPageRoutes.ts

@@ -0,0 +1,155 @@
+export { loadPageRoutes };
+export type { PageRoutes, RouteType };
+
+import type {
+  PageConfigGlobalRuntime,
+  PageConfigRuntime,
+} from "../../types/interfaces/page.js";
+import { getDefinedAtString } from "../processing/getters/getConfigDefinedAt.js";
+import { getConfigValueRuntime } from "../processing/getters/getConfigValue.js";
+import {
+  getHookFromPageConfigGlobal,
+  type Hook,
+} from "../processing/getters/getHook.js";
+
+import { FilesystemRoot } from "./deduceRouteStringFromFilesystemPath.js";
+import { slice } from "./utils.js";
+import { assert } from "../gaurds/assertions/assert/index.js";
+import { isCallable } from "../gaurds/validators/isCallable.js";
+
+type PageRoute = {
+  pageId: string;
+  comesFromV1PageConfig: boolean;
+} & (
+  | {
+      routeString: string;
+      routeDefinedAtString: null;
+      routeType: "FILESYSTEM";
+      routeFilesystemDefinedBy: string;
+    }
+  | { routeString: string; routeDefinedAtString: string; routeType: "STRING" }
+  | {
+      routeFunction: Function;
+      routeDefinedAtString: string;
+      routeType: "FUNCTION";
+    }
+);
+type PageRoutes = PageRoute[];
+type RouteType = "STRING" | "FUNCTION" | "FILESYSTEM";
+
+async function loadPageRoutes(
+  pageConfigs: PageConfigRuntime[],
+  pageConfigGlobal: PageConfigGlobalRuntime,
+  allPageIds: string[],
+): Promise<{ pageRoutes: PageRoutes; onBeforeRouteHook: null | Hook }> {
+  const { onBeforeRouteHook, filesystemRoots } = getGlobalHooks(
+    pageConfigs,
+    pageConfigGlobal,
+  );
+  const pageRoutes = getPageRoutes(filesystemRoots, pageConfigs, allPageIds);
+  return { pageRoutes, onBeforeRouteHook };
+}
+
+function getPageRoutes(
+  filesystemRoots: null | FilesystemRoot[],
+  pageConfigs: PageConfigRuntime[],
+  allPageIds: string[],
+): PageRoutes {
+  const pageRoutes: PageRoutes = [];
+
+  // V1 Design
+  if (pageConfigs.length > 0) {
+    assert(filesystemRoots === null);
+    const comesFromV1PageConfig = true;
+    pageConfigs
+      .filter((p) => !p.isErrorPage)
+      .forEach((pageConfig) => {
+        const pageId = pageConfig.pageId;
+
+        let pageRoute: null | PageRoute = null;
+        {
+          const configName = "route";
+          const configValue = getConfigValueRuntime(pageConfig, configName);
+          if (configValue) {
+            const route = configValue.value;
+            assert(configValue.definedAtData);
+            const definedAtString = getDefinedAtString(
+              configValue.definedAtData,
+              configName,
+            );
+            if (typeof route === "string") {
+              pageRoute = {
+                pageId,
+                comesFromV1PageConfig,
+                routeString: route,
+                routeDefinedAtString: definedAtString,
+                routeType: "STRING",
+              };
+            } else {
+              assert(isCallable(route));
+              if (
+                getConfigValueRuntime(
+                  pageConfig,
+                  "iKnowThePerformanceRisksOfAsyncRouteFunctions",
+                  "boolean",
+                )
+              )
+                assert(route.constructor.name !== "AsyncFunction");
+              pageRoute = {
+                pageId,
+                comesFromV1PageConfig,
+                routeFunction: route,
+                routeDefinedAtString: definedAtString,
+                routeType: "FUNCTION",
+              };
+            }
+          }
+        }
+
+        if (!pageRoute) {
+          const { routeFilesystem } = pageConfig;
+          assert(routeFilesystem);
+          const { routeString, definedBy } = routeFilesystem;
+          assert(routeFilesystem.routeString.startsWith("/"));
+          pageRoute = {
+            pageId,
+            routeFilesystemDefinedBy: definedBy,
+            comesFromV1PageConfig,
+            routeString,
+            routeDefinedAtString: null,
+            routeType: "FILESYSTEM",
+          };
+        }
+
+        assert(pageRoute);
+        pageRoutes.push(pageRoute);
+      });
+  }
+
+  return pageRoutes;
+}
+
+function getGlobalHooks(
+  pageConfigs: PageConfigRuntime[],
+  pageConfigGlobal: PageConfigGlobalRuntime,
+): {
+  onBeforeRouteHook: null | Hook;
+  filesystemRoots: null | FilesystemRoot[];
+} {
+  // V1 Design
+  if (pageConfigs.length > 0) {
+    const hook = getHookFromPageConfigGlobal(pageConfigGlobal, "onBeforeRoute");
+    return { onBeforeRouteHook: hook, filesystemRoots: null };
+  }
+  return { onBeforeRouteHook: null, filesystemRoots: null };
+}
+
+function dirname(filePath: string): string {
+  assert(filePath.startsWith("/"));
+  assert(!filePath.endsWith("/"));
+  const paths = filePath.split("/");
+  const dirPath = slice(paths, 0, -1).join("/") || "/";
+  assert(dirPath.startsWith("/"));
+  assert(!dirPath.endsWith("/") || dirPath === "/");
+  return dirPath;
+}

package/dist/core/router/noRouteMatch.ts

@@ -0,0 +1 @@
+export const noRouteMatch = "doesn't match the route of any of your pages";

package/dist/core/router/pageRoutes.ts

@@ -0,0 +1,159 @@
+export type PageMetadata = {
+  title: string;
+  description?: string;
+  image?: string;
+  keywords?: string;
+  author?: string;
+  viewport?: string;
+  robots?: string;
+  generator?: string;
+  ogImage?: string;
+  twitterCard?: string;
+  twitterSite?: string;
+  twitterCreator?: string;
+  icons?: string[];
+  themeColor?: string;
+  msapplicationTileColor?: string;
+  manifest?: string;
+  appleTouchIcon?: string;
+  favicon?: string;
+  lang?: string;
+  canonical?: string;
+  sitemap?: string;
+};
+
+export type PageRoute = {
+  name: string;
+  path: string;
+  component: () => Promise<{ default: any }>;
+  href: string;
+  current: boolean;
+  loading?: boolean;
+  metadata?: PageMetadata;
+
+};
+
+// Example predefined list of route names with type safety
+const pageRouteNames = [
+  "index",
+  "home",
+  "about",
+  "events",
+  "fighters",
+  "admin",
+  "game",
+  "_error",
+  "login",
+  "music",
+  "support",
+] as const;
+
+type PageRouteName = (typeof pageRouteNames)[number];
+
+const pageRoutes = async (): Promise<PageRoute[]> => {
+  try {
+    const pageModules = async (name: PageRouteName) => {
+      try {
+        const module = await import(`${process.cwd()}/pages/${name}/+Page.tsx`);
+        return module.default;
+      } catch (error) {
+        console.error(`Failed to load page module for ${name}:`, error);
+        throw new Error(`Page module ${name} not found`);
+      }
+    };
+
+    const formatRoutePath = (name: PageRouteName): string => {
+      if (name === "home" || name === "index") return "/";
+      return `/${name}`;
+    };
+
+    // Use Promise.allSettled to handle the asynchronous imports
+    const routeResults = await Promise.allSettled(
+      pageRouteNames.map(async (name): Promise<PageRoute> => {
+        const componentModule = await pageModules(name);
+        const path = formatRoutePath(name);
+
+        return {
+          name: name.charAt(0).toUpperCase() + name.slice(1),
+          path,
+          component: () => Promise.resolve({ default: componentModule }),
+          href: path,
+          current: false,
+        };
+      })
+    );
+
+    // Filter fulfilled results and extract values
+    const fulfilledRoutes = routeResults
+      .filter(
+        (result): result is PromiseFulfilledResult<PageRoute> =>
+          result.status === "fulfilled"
+      )
+      .map((result) => result.value);
+
+    return fulfilledRoutes;
+  } catch (error) {
+    console.error("Failed to generate page routes:", error);
+    throw error;
+  }
+};
+
+export default pageRoutes;
+
+
+// // Define the route type
+
+
+
+// // Improved module loading with error handling
+// const pageModules = async (name: PageRouteName) => {
+//   try {
+//     const module = await import(`${process.cwd()}/pages/${name}/+Page.tsx`);
+//     return module.default;
+
+//     // Example of how to handle dynamic imports
+//   } catch (error) {
+// Error handling for page module loading
+//     throw new Error(`Page module ${name} not found`);
+//   }
+// };
+
+// // Function to format the route path
+// const formatRoutePath = (name: PageRouteName): string => {
+//   if (name === "home" || name === "index") return "/";
+//   return `/${name}`;
+// };
+
+// // Main pageRoutes function
+// const pageRoutes = async (): Promise<{ getPageRoutes: PageRoute[] }> => {
+//   try {
+//     const getPageRoutes = await Promise.allSettled(
+//       pageRouteNames.map(async (name): Promise<PageRoute> => {
+//         const componentModule = await pageModules(name);
+//         const path = formatRoutePath(name);
+
+//         return {
+//           name: name.charAt(0).toUpperCase() + name.slice(1),
+//           path,
+//           component: () => Promise.resolve({ default: componentModule }),
+//           href: path,
+//           current: false,
+//         };
+//       }),
+//     );
+
+//     const fulfilledRoutes = getPageRoutes
+//       .filter(
+//         (result): result is PromiseFulfilledResult<PageRoute> =>
+//           result.status === "fulfilled",
+//       )
+//       .map((result) => result.value);
+
+//     return { getPageRoutes: fulfilledRoutes };
+//   } catch (error) {
+// Error handling for route generation
+//     throw error;
+//   }
+// };
+
+// export default pageRoutes;