@revealui/core 0.0.1-pre.0

package/dist/core/router/abort.ts

@@ -0,0 +1,339 @@
+export {
+  AbortRender,
+  assertNoInfiniteAbortLoop,
+  getPageContextFromAllRewrites,
+  isAbortError,
+  isAbortPageContext,
+  logAbortErrorHandled,
+  redirect,
+  render,
+}
+export type {
+  AbortStatusCode,
+  ErrorAbort,
+  PageContextFromRewrite,
+  RedirectStatusCode,
+  UrlRedirect,
+}
+
+import pc from "@brillout/picocolors"
+import { isUserHookError } from "../hooks/executeHook.js"
+import {
+  assert,
+  assertUsage,
+  assertUsageUrlPathnameAbsolute,
+  assertUsageUrlRedirectTarget,
+  assertWarning,
+  checkType,
+  hasProp,
+  joinEnglish,
+  objectAssign,
+  truncateString,
+} from "./utils.js"
+
+type RedirectStatusCode = number &
+  // For improved IntelliSense, we define the list of status code directly on redirect()'s argument type
+  Parameters<typeof redirect>[1]
+type AbortStatusCode = number &
+  // For improved IntelliSense, we define the list of status code directly on render()'s argument type
+  Parameters<typeof render>[0]
+
+type UrlRedirect = {
+  url: string
+  statusCode: RedirectStatusCode
+}
+type AbortRedirect = Error
+
+type AbortReason = Required<
+  ({ abortReason?: unknown } & Reveal.PageContext)["abortReason"]
+>
+
+/**
+ * Abort the rendering of the current page, and redirect the user to another URL instead.
+ *
+ * https://reveal.dev/redirect
+ *
+ * @param url The URL to redirect to.
+ * @param statusCode By default a temporary redirection (`302`) is performed. For permanent redirections (`301`), use `config.redirects` https://reveal.dev/redirects instead or, alternatively, set the `statusCode` argument to `301`.
+ */
+function redirect(url: string, statusCode?: 301 | 302): AbortRedirect {
+  const abortCaller = "throw redirect()" as const
+  assertUsageUrlRedirectTarget(url, getErrPrefix(abortCaller))
+  const args = [JSON.stringify(url)]
+  if (!statusCode) {
+    statusCode = 302
+  } else {
+    assertStatusCode(statusCode, [301, 302], "redirect")
+    args.push(String(statusCode))
+  }
+  const pageContextAbort = {}
+  objectAssign(pageContextAbort, {
+    _abortCaller: abortCaller,
+    _abortCall: `redirect(${args.join(", ")})` as const,
+    _urlRedirect: {
+      url,
+      statusCode,
+    },
+  })
+  return AbortRender(pageContextAbort)
+}
+
+/**
+ * Abort the rendering of the current page, and render the error page instead.
+ *
+ * https://reveal.dev/render
+ *
+ * @param abortStatusCode
+ * One of the following:
+ *   `401` Unauthorized (user isn't logged in)
+ *   `403` Forbidden (user is logged in but isn't allowed)
+ *   `404` Not Found
+ *   `410` Gone (use this instead of `404` if the page existed in the past, see https://github.com/revealjs/reveal/issues/1097#issuecomment-1695260887)
+ *   `429` Too Many Requests (rate limiting)
+ *   `500` Internal Server Error (your client or server has a bug)
+ *   `503` Service Unavailable (server is overloaded, or a third-party API isn't responding)
+ * @param abortReason Sets `pageContext.abortReason` which is usually used by the error page to show a message to the user, see https://reveal.dev/error-page
+ */
+function render(
+  abortStatusCode: 401 | 403 | 404 | 410 | 429 | 500 | 503,
+  abortReason?: AbortReason
+): Error
+/**
+ * Abort the rendering of the current page, and render another page instead.
+ *
+ * https://reveal.dev/render
+ *
+ * @param url The URL to render.
+ * @param abortReason Sets `pageContext.abortReason` which is used by the error page to show a message to the user, see https://reveal.dev/error-page
+ */
+function render(url: `/${string}`, abortReason?: AbortReason): Error
+function render(
+  urlOrStatusCode: string | number,
+  abortReason?: unknown
+): Error {
+  const args = [
+    typeof urlOrStatusCode === "number"
+      ? String(urlOrStatusCode)
+      : JSON.stringify(urlOrStatusCode),
+  ]
+  if (abortReason !== undefined)
+    args.push(truncateString(JSON.stringify(abortReason), 30))
+  const abortCaller = "throw render()"
+  const abortCall = `render(${args.join(", ")})` as const
+  return render_(urlOrStatusCode, abortReason, abortCall, abortCaller)
+}
+
+function render_(
+  urlOrStatusCode: string | number,
+  abortReason: unknown | undefined,
+  abortCall: `render(${string})` | `RenderErrorPage()`,
+  abortCaller: "throw render()" | "throw RenderErrorPage()",
+  pageContextAddendum?: { _isLegacyRenderErrorPage: true } & Record<
+    string,
+    unknown
+  >
+): Error {
+  const pageContextAbort = {
+    abortReason,
+    _abortCaller: abortCaller,
+    _abortCall: abortCall,
+  }
+  if (pageContextAddendum) {
+    assert(pageContextAddendum._isLegacyRenderErrorPage === true)
+    objectAssign(pageContextAbort, pageContextAddendum)
+  }
+  if (typeof urlOrStatusCode === "string") {
+    const url = urlOrStatusCode
+    assertUsageUrlPathnameAbsolute(url, getErrPrefix(abortCaller))
+    objectAssign(pageContextAbort, {
+      _urlRewrite: url,
+    })
+    return AbortRender(pageContextAbort)
+  } else {
+    const abortStatusCode = urlOrStatusCode
+    assertStatusCode(
+      urlOrStatusCode,
+      [401, 403, 404, 410, 429, 500, 503],
+      "redirect"
+    )
+    objectAssign(pageContextAbort, {
+      abortStatusCode,
+      is404: abortStatusCode === 404,
+    })
+    return AbortRender(pageContextAbort)
+  }
+}
+
+type AbortCall =
+  | `redirect(${string})`
+  | `render(${string})`
+  | `RenderErrorPage()`
+type AbortCaller =
+  | `throw redirect()`
+  | `throw render()`
+  | `throw RenderErrorPage()`
+type PageContextAbort = {
+  _abortCall: AbortCall
+  _abortCaller: AbortCaller
+} & (
+  | ({
+      _abortCall: `redirect(${string})`
+      _abortCaller: "throw redirect()"
+      _urlRedirect: UrlRedirect
+    } & Omit<AbortUndefined, "_urlRedirect">)
+  | ({
+      _abortCall: `render(${string})` | `RenderErrorPage()`
+      _abortCaller: "throw render()" | "throw RenderErrorPage()"
+      abortReason: undefined | unknown
+      _urlRewrite: string
+    } & Omit<AbortUndefined, "_urlRewrite">)
+  | ({
+      _abortCall: `render(${string})` | `RenderErrorPage()`
+      _abortCaller: "throw render()" | "throw RenderErrorPage()"
+      abortReason: undefined | unknown
+      abortStatusCode: number
+    } & Omit<AbortUndefined, "abortStatusCode">)
+)
+type AbortUndefined = {
+  _urlRedirect?: undefined
+  _urlRewrite?: undefined
+  abortStatusCode?: undefined
+}
+
+function AbortRender(pageContextAbort: PageContextAbort): Error {
+  const err = new Error("AbortRender")
+  objectAssign(err, { _pageContextAbort: pageContextAbort, [stamp]: true })
+  checkType<ErrorAbort>(err)
+  return err
+}
+
+const stamp = "_isAbortError"
+type ErrorAbort = { _pageContextAbort: PageContextAbort }
+function isAbortError(thing: unknown): thing is ErrorAbort {
+  return typeof thing === "object" && thing !== null && stamp in thing
+}
+function isAbortPageContext(
+  pageContext: Record<string, unknown>
+): pageContext is PageContextAbort {
+  if (
+    !(
+      pageContext._urlRewrite ||
+      pageContext._urlRedirect ||
+      pageContext.abortStatusCode
+    )
+  ) {
+    return false
+  }
+  assert(hasProp(pageContext, "_abortCall", "string"))
+  /* Isn't needed and is missing on the client-side
+  assert(hasProp(pageContext, '_abortCaller', 'string'))
+  */
+  checkType<
+    Omit<PageContextAbort, "_abortCall" | "_abortCaller"> & {
+      _abortCall: string
+    }
+  >(pageContext)
+  return true
+}
+
+function logAbortErrorHandled(
+  err: ErrorAbort,
+  isProduction: boolean,
+  pageContext: { urlOriginal: string; _urlRewrite: null | string }
+) {
+  if (isProduction) return
+  const urlCurrent = pageContext._urlRewrite ?? pageContext.urlOriginal
+  assert(urlCurrent)
+  const abortCall = err._pageContextAbort._abortCall
+  assert(abortCall)
+
+  const hookLoc = isUserHookError(err)
+  let thrownBy = ""
+  if (hookLoc) {
+    thrownBy = ` by ${pc.cyan(`${hookLoc.hookName}()`)} hook defined at ${hookLoc.hookFilePath}`
+  } else {
+    // hookLoc is missing when serializing abort errors from server to client
+  }
+
+  assertWarning(
+    false,
+    `${pc.cyan(abortCall)} thrown${thrownBy} while rendering ${pc.cyan(urlCurrent)}`,
+    {
+      onlyOnce: false,
+    }
+  )
+}
+
+function assertStatusCode(
+  statusCode: number,
+  expected: number[],
+  caller: "redirect"
+) {
+  const expectedEnglish = joinEnglish(
+    expected.map((s) => s.toString()),
+    "or"
+  )
+  assertWarning(
+    expected.includes(statusCode),
+    `Unepexected status code ${statusCode} passed to ${caller}(), we recommend ${expectedEnglish} instead. (Or reach out at https://github.com/revealjs/reveal/issues/1008 if you believe ${statusCode} should be added.)`,
+    { onlyOnce: true }
+  )
+}
+
+type PageContextFromRewrite = { _urlRewrite: string } & Record<string, unknown>
+type PageContextFromAllRewrites = { _urlRewrite: null | string } & Record<
+  string,
+  unknown
+>
+function getPageContextFromAllRewrites(
+  pageContextsFromRewrite: PageContextFromRewrite[]
+): PageContextFromAllRewrites {
+  assertNoInfiniteLoop(pageContextsFromRewrite)
+  const pageContextFromAllRewrites: PageContextFromAllRewrites = {
+    _urlRewrite: null,
+  }
+  pageContextsFromRewrite.forEach((pageContextFromRewrite) => {
+    Object.assign(pageContextFromAllRewrites, pageContextFromRewrite)
+  })
+  return pageContextFromAllRewrites
+}
+function assertNoInfiniteLoop(
+  pageContextsFromRewrite: PageContextFromRewrite[]
+) {
+  const urlRewrites: string[] = []
+  pageContextsFromRewrite.forEach((pageContext) => {
+    const urlRewrite = pageContext._urlRewrite
+    {
+      const idx = urlRewrites.indexOf(urlRewrite)
+      if (idx !== -1) {
+        const loop: string = [...urlRewrites.slice(idx), urlRewrite]
+          .map((url) => `render('${url}')`)
+          .join(" => ")
+        assertUsage(false, `Infinite loop of render() calls: ${loop}`)
+      }
+    }
+    urlRewrites.push(urlRewrite)
+  })
+}
+
+function assertNoInfiniteAbortLoop(
+  rewriteCount: number,
+  redirectCount: number
+) {
+  const abortCalls = [
+    // prettier-ignore
+    // biome-ignore format:
+    rewriteCount > 0 && pc.cyan("throw render('/some-url')"),
+    redirectCount > 0 && pc.cyan("throw redirect('/some-url')"),
+  ]
+    .filter(Boolean)
+    .join(" and ")
+  assertUsage(
+    rewriteCount + redirectCount <= 7,
+    `Maximum chain length of 7 ${abortCalls} exceeded. Did you define an infinite loop of ${abortCalls}?`
+  )
+}
+
+function getErrPrefix(abortCaller: AbortCaller): string {
+  return `URL passed to ${pc.code(abortCaller)}`
+}

package/dist/core/router/apiRoutes.ts

@@ -0,0 +1,94 @@
+const loadApiModule = async (dirName: string, fileName: string) => {
+  try {
+    const module = await import(`${process.cwd()}/${dirName}/${fileName}.ts`);
+    return module;
+  } catch (error) {
+    console.error(`Failed to load API module ${fileName}:`, error);
+    throw error;
+  }
+};
+
+export type ApiRouteName = (typeof apiRouteNames)[number];
+
+const apiRouteNames = [
+  "supabase",
+  "stripe",
+  "payload",
+  "youtube",
+  "services",
+] as const;
+
+export interface ApiRoute {
+  name: string;
+  path: string;
+  component: () => Promise<{ default: unknown }>;
+  href: string;
+  current: boolean;
+}
+
+const apiRoutes = async (): Promise<ApiRoute[]> => {
+  try {
+    const getApiRoutes = await Promise.allSettled(
+      apiRouteNames.map(async (name: ApiRouteName) => {
+        const capitalizedName = `${name.charAt(0).toUpperCase()}${name.slice(1)}`;
+        const lowerCaseName = `${name.toLowerCase()}`;
+        const componentModule = await loadApiModule(name, name);
+        return {
+          name: capitalizedName,
+          path: `/${lowerCaseName}`,
+          component: () => Promise.resolve({ default: componentModule }),
+          href: `/${lowerCaseName}`,
+          current: false,
+        };
+      }),
+    );
+
+    const fulfilledRoutes = getApiRoutes
+      .filter(
+        (result): result is PromiseFulfilledResult<ApiRoute> =>
+          result.status === "fulfilled",
+      )
+      .map((result) => result.value);
+
+    return fulfilledRoutes;
+  } catch (error) {
+    console.error("Failed to initialize API routes:", error);
+    throw error;
+  }
+};
+
+export default apiRoutes;
+
+// const apiModules = async (name: string) => {
+//   // Assume this function loads the appropriate module for the given route name
+//   // Example: dynamic import, fetch, etc.
+//   const module = await import(`./api/${name}.ts`);
+//   return module.default;
+// };
+// const apiRouteNames = [
+//   "supabase",
+//   "stripe",
+//   "payload",
+//   "youtube",
+//   "services",
+// ] as const;
+
+// const apiRoutes = async () => {
+//   const getApiRoutes = await Promise.allSettled(
+//     apiRouteNames.map(async (name) => {
+//       const componentModule = await apiModules(name);
+//       return {
+//         name: name.charAt(0).toUpperCase() + name.slice(1), // Capitalize the first letter
+//         path: `/${name.toLowerCase()}`,
+//         component: () => Promise.resolve({ default: componentModule }),
+//         href: `/${name.toLowerCase()}`,
+//         current: false,
+//       };
+//     }),
+//   );
+
+//   return { getApiRoutes };
+// };
+
+// // Export the async function as the default export
+// export default apiRoutes;

package/dist/core/router/debug.ts

@@ -0,0 +1,19 @@
+export { debug };
+
+// Note how we only import `type`: we don't actually import/load the debug code.
+import type { createDebugger, Debug } from "../gaurds/debugger/index.js";
+
+var _debug: undefined | typeof debug;
+function debug(...args: Parameters<Debug>) {
+  if (!_debug) {
+    // We use this trick instead of `import { createDebugger } from '../../utils/debug` in order to ensure that the `debug` mechanism is only loaded on the server-side
+    _debug = (
+      globalThis as any as {
+        __brillout_debug_createDebugger?: typeof createDebugger;
+      }
+    ).__brillout_debug_createDebugger?.("reveal:routing");
+  }
+  if (_debug) {
+    _debug(...args);
+  }
+}

package/dist/core/router/deduceRouteStringFromFilesystemPath.ts

@@ -0,0 +1,75 @@
+// Unit tests at ./deduceRouteStringFromFilesystemPath.spec.ts
+
+import { assert, assertLog, higherFirst, slice } from "./utils.js";
+
+export { deduceRouteStringFromFilesystemPath };
+export type { FilesystemRoot };
+
+type FilesystemRoot = {
+  filesystemRoot: string;
+  urlRoot: string;
+};
+
+// TODO/next-major-update: remove this and whole filesystemRoot mechanism
+function deduceRouteStringFromFilesystemPath(
+  pageId: string,
+  filesystemRoots: FilesystemRoot[],
+): string {
+  // Handle Filesystem Routing Root
+  const filesystemRootsMatch = filesystemRoots
+    .filter(({ filesystemRoot }) => pageId.startsWith(filesystemRoot))
+    .sort(higherFirst(({ filesystemRoot }) => filesystemRoot.length));
+  const fsBase = filesystemRootsMatch[0];
+
+  let filesystemRoute: string;
+  if (fsBase) {
+    // Example values:
+    //  - `{"pageId":"/pages/index","filesystemRoot":"/","urlRoot":"/client_portal"}`
+    const { filesystemRoot, urlRoot } = fsBase;
+    const debugInfo = { pageId, filesystemRoot, urlRoot };
+    assertLog(
+      urlRoot.startsWith("/") &&
+        pageId.startsWith("/") &&
+        filesystemRoot.startsWith("/"),
+      debugInfo,
+    );
+    assertLog(pageId.startsWith(filesystemRoot), debugInfo);
+    if (filesystemRoot !== "/") {
+      assertLog(!filesystemRoot.endsWith("/"), debugInfo);
+      filesystemRoute = slice(pageId, filesystemRoot.length, 0);
+    } else {
+      filesystemRoute = pageId;
+    }
+    assertLog(filesystemRoute.startsWith("/"), debugInfo);
+    filesystemRoute =
+      urlRoot +
+      (urlRoot.endsWith("/") ? "" : "/") +
+      slice(filesystemRoute, 1, 0);
+  } else {
+    filesystemRoute = pageId;
+  }
+
+  assert(filesystemRoute.startsWith("/"));
+
+  // Remove `pages/`, `index/, and `src/`, directories
+  filesystemRoute = filesystemRoute
+    .split("/")
+    .filter((dir) => dir !== "pages" && dir !== "src" && dir !== "index")
+    .join("/");
+
+  // Hanlde `/index.page.*` suffix
+  assert(!filesystemRoute.includes(".page."));
+  assert(!filesystemRoute.endsWith("."));
+  if (filesystemRoute.endsWith("/index")) {
+    filesystemRoute = slice(filesystemRoute, 0, -"/index".length);
+  }
+
+  if (filesystemRoute === "") {
+    filesystemRoute = "/";
+  }
+
+  assert(filesystemRoute.startsWith("/"));
+  assert(!filesystemRoute.endsWith("/") || filesystemRoute === "/");
+
+  return filesystemRoute;
+}

package/dist/core/router/dynamicApiRoutes.ts

@@ -0,0 +1,18 @@
+interface ApiModule {
+  default: React.ComponentType;
+}
+
+// Dynamically import an API module based on the apiName
+export default async function dynamicApiRoutes(apiName: string): Promise<{
+  default: ApiModule;
+}> {
+  const apiRoot = "api";
+
+  try {
+    const apiModule = await import(`${process.cwd()}/${apiRoot}/${apiName}.ts`);
+    return apiModule;
+  } catch (error) {
+    console.error(`Failed to load API module: ${apiName}`, error);
+    throw new Error(`API module "${apiName}" could not be loaded.`);
+  }
+}

package/dist/core/router/dynamicPageRoutes.ts

@@ -0,0 +1,18 @@
+interface PageModule {
+  default: React.ComponentType;
+}
+export default async function dynamicPageRoutes(pageName: string): Promise<{
+  default: PageModule;
+}> {
+  const errorMessage = `Page module "${pageName}" could not be loaded.`;
+  try {
+    const pageRoot = "pages";
+    const pageModule = await import(
+      `${process.cwd()}/${pageRoot}/${pageName}/+Page.tsx`
+    );
+    return { default: pageModule.default };
+  } catch (error) {
+    console.error(`Failed to load page module: ${pageName}`, error);
+    throw new Error(errorMessage);
+  }
+}

package/dist/core/router/executeGuardHook.ts

@@ -0,0 +1,45 @@
+export { executeGuardHook }
+
+
+import type { PageConfigRuntime } from "../../types/interfaces/page.js"
+import {PageFile} from "../__internal/index.js"
+import { executeHook } from "../hooks/executeHook.js"
+import { getHook, type Hook } from "../processing/getters/getHook.js"
+import type { PageContextExports } from "../processing/getters/getPageFiles/index.js"
+import { assertUsage } from "./utils.js"
+const errIntro = "The guard() hook defined by"
+
+async function executeGuardHook<
+  T extends PageContextExports & {
+    pageId: string
+    _pageFilesAll: PageFile[]
+    _pageConfigs: PageConfigRuntime[]
+  },
+>(
+  pageContext: T,
+  prepareForUserConsumption: (pageConfig: T) => T | void
+): Promise<void> {
+  let hook: Hook | null
+  if (pageContext._pageFilesAll.length > 0) {
+    hook = getHook(pageContext, "guard")
+    if (!hook) return
+  } else {
+    hook = getHook(pageContext, "onBeforeRoute")
+    if (!hook) return
+  }
+  const guard = hook.hookFn
+
+  let pageContextForUserConsumption = pageContext
+  const res = prepareForUserConsumption(pageContext)
+  if (res) pageContextForUserConsumption = res
+
+  const hookResult = await executeHook(
+    () => guard(pageContextForUserConsumption),
+    hook,
+    pageContext
+  )
+  assertUsage(
+    hookResult === undefined,
+    `${errIntro} ${hook.hookFilePath} returns a value, but guard() shouldn't return any value`
+  )
+}