@revealui/core 0.0.1-pre.0

package/dist/core/gaurds/logger/loggerNotProd.ts

@@ -0,0 +1,271 @@
+// Non-production logger used for:
+//  - Development
+//  - Preview
+//  - Build
+//  - Pre-rendering
+// In other words: everywhere except in production
+
+export {
+  logConfigError,
+  logConfigErrorRecover,
+  logConfigInfo,
+  logErrorDebugNote,
+  logViteAny,
+  logViteError,
+}
+export type {
+  LogCategory,
+  LogError,
+  LogErrorArgs,
+  LogInfo,
+  LogInfoArgs,
+  LogType,
+}
+
+import pc from "@brillout/picocolors"
+
+import { getViteConfig } from "../../globals/contexts/globalContext"
+import { isUserHookError } from "../../hooks/executeHook"
+import { getAssertErrMsg } from "../../processing/getters/getAssertErrMsg"
+import { getHttpRequestAsyncStore } from "../../processing/getters/getHttpRequestAsyncStore"
+import {
+  getConfigBuildErrorFormatted,
+  getConfigExecutionErrorIntroMsg,
+} from "../../processing/getters/getRevealConfig/transpileAndExecuteFile"
+import { isAbortError } from "../../router/abort"
+import { stripAnsi } from "../../utils/string/stripAnsi"
+import { assert } from "../assertions/assert"
+import { assertIsNotProductionRuntime } from "../assertions/assertIsNotProductionRuntime"
+import { isErrorDebug } from "../validators/isErrorDebug"
+import { setAlreadyLogged } from "../validators/isNewError"
+import { formatHintLog } from "./formatHintLog"
+import {
+  getPrettyErrorWithCodeSnippet,
+  isErrorWithCodeSnippet,
+} from "./loggerNotProd/errorWithCodeSnippet"
+import {
+  applyViteSourceMapToStackTrace,
+  logDirectly,
+  logWithRevealTag,
+  logWithViteTag,
+} from "./loggerNotProd/log"
+import { onRuntimeError } from "./loggerProd"
+import { overwriteRuntimeProductionLogger } from "./loggerRuntime"
+import { overwriteAssertProductionLogger } from "./overwriteAssertProductionLogger"
+import { warnIfErrorIsNotObject } from "./warnIfErrorIsNotObject"
+
+assertIsNotProductionRuntime()
+overwriteRuntimeProductionLogger(logRuntimeError, logRuntimeInfo)
+overwriteAssertProductionLogger(assertLogger)
+
+type LogType = "info" | "warn" | "error" | "error-recover"
+type LogCategory = "config" | `request(${number})`
+type LogInfo = (...args: LogInfoArgs) => void
+type LogInfoArgs = Parameters<typeof logRuntimeInfo>
+type LogError = (...args: LogErrorArgs) => void
+type LogErrorArgs = Parameters<typeof logRuntimeError>
+
+function logRuntimeInfo(msg: string, httpRequestId: number, logType: LogType) {
+  const category = getCategory(httpRequestId)
+  assert(category)
+  logWithRevealTag(msg, logType, category)
+}
+function logViteAny(
+  msg: string,
+  logType: LogType,
+  httpRequestId: number | null,
+  prependViteTag: boolean
+): void {
+  if (prependViteTag) {
+    const category = getCategory(httpRequestId)
+    logWithViteTag(msg, logType, category)
+  } else {
+    logDirectly(msg, logType)
+  }
+}
+function logConfigInfo(msg: string, logType: LogType): void {
+  const category = getConfigCategory()
+  logWithRevealTag(msg, logType, category)
+}
+function logConfigErrorRecover(): void {
+  const msg = pc.bold(pc.green("Configuration successfully loaded"))
+  const category = getConfigCategory()
+  logWithRevealTag(msg, "error-recover", category)
+}
+
+function logRuntimeError(
+  err: unknown,
+  // httpRequestId is `null` when pre-rendering
+  httpRequestId: number | null
+): void {
+  logErr(err, httpRequestId, false)
+}
+function logViteError(
+  err: unknown,
+  // httpRequestId is `undefined` if development environment doesn't support async stores
+  httpRequestId: number | undefined
+): void {
+  logErr(err, httpRequestId, true)
+}
+function logErr(
+  err: unknown,
+  httpRequestId: number | null = null,
+  errorComesFromVite: boolean
+): void {
+  warnIfErrorIsNotObject(err)
+
+  if (isAbortError(err) && !isErrorDebug()) {
+    return
+  }
+
+  const store = getHttpRequestAsyncStore()
+
+  setAlreadyLogged(err)
+  if (getHttpRequestAsyncStore()?.shouldErrorBeSwallowed(err)) {
+    if (!isErrorDebug()) return
+  } else {
+    store?.markErrorAsLogged(err)
+  }
+
+  const category = getCategory(httpRequestId)
+
+  if (!isErrorDebug()) {
+    if (isErrorWithCodeSnippet(err)) {
+      // We handle transpile errors globally because wrapping viteDevServer.ssrLoadModule() wouldn't be enough: transpile errors can be thrown not only when calling viteDevServer.ssrLoadModule() but also later when loading user code with import() (since Vite lazy-transpiles import() calls)
+      const viteConfig = getViteConfig()
+      assert(viteConfig)
+      let prettyErr = getPrettyErrorWithCodeSnippet(err, viteConfig.root)
+      assert(stripAnsi(prettyErr).startsWith("Failed to transpile"))
+      logWithViteTag(prettyErr, "error", category)
+      logErrorDebugNote()
+      return
+    }
+
+    {
+      const logged = handleAssertMsg(err, category)
+      if (logged) return
+    }
+  }
+
+  // Needs to be after assertion messages handling, because user hooks may throw an assertion error
+  const hook = isUserHookError(err)
+  if (hook) {
+    const { hookName, hookFilePath } = hook
+    logWithRevealTag(
+      pc.red(
+        `Following error was thrown by the ${hookName}() hook defined at ${hookFilePath}`
+      ),
+      "error",
+      category
+    )
+  } else if (category) {
+    logFallbackErrIntro(category, errorComesFromVite)
+  }
+
+  logDirectly(err, "error")
+
+  // Needs to be called after logging the error.
+  onRuntimeError(err)
+}
+
+function logConfigError(err: unknown): void {
+  warnIfErrorIsNotObject(err)
+
+  const category = getConfigCategory()
+
+  {
+    const errIntroMsg = getConfigExecutionErrorIntroMsg(err)
+    if (errIntroMsg) {
+      assert(stripAnsi(errIntroMsg).startsWith("Failed to execute"))
+      logWithRevealTag(errIntroMsg, "error", category)
+      logDirectly(err, "error")
+      return
+    }
+  }
+  {
+    const errMsgFormatted = getConfigBuildErrorFormatted(err)
+    if (errMsgFormatted) {
+      assert(stripAnsi(errMsgFormatted).startsWith("Failed to transpile"))
+      if (!isErrorDebug()) {
+        logWithRevealTag(errMsgFormatted, "error", category)
+      } else {
+        logDirectly(err, "error")
+      }
+      return
+    }
+  }
+  {
+    const logged = handleAssertMsg(err, category)
+    if (logged) return
+  }
+
+  if (category) logFallbackErrIntro(category, false)
+  logDirectly(err, "error")
+}
+
+function logFallbackErrIntro(
+  category: LogCategory,
+  errorComesFromVite: boolean
+) {
+  const msg = errorComesFromVite ? "Transpilation error" : "An error was thrown"
+  logWithRevealTag(pc.bold(pc.red(`[Error] ${msg}:`)), "error", category)
+}
+
+function getConfigCategory(): LogCategory {
+  const category = getCategory() ?? "config"
+  return category
+}
+
+function handleAssertMsg(err: unknown, category: LogCategory | null): boolean {
+  const res = getAssertErrMsg(err)
+  if (!res) return false
+  const { assertMsg, showRevealVersion } = res
+  logWithRevealTag(assertMsg, "error", category, showRevealVersion)
+  return true
+}
+function assertLogger(thing: string | Error, logType: LogType): void {
+  // vite.ssrFixStacktrace() is needed for `assertWarning(..., { showStackTrace: true })`
+  applyViteSourceMapToStackTrace(thing)
+  const category = getCategory()
+  const res = getAssertErrMsg(thing)
+  /* Risk of infinite loop
+  assert(res)
+  */
+  if (!res) throw new Error("Internal error, reach out to a maintainer")
+  const { assertMsg, showRevealVersion } = res
+  logWithRevealTag(assertMsg, logType, category, showRevealVersion)
+}
+
+/** Note shown to user when reveal does something risky:
+ *  - When reveal dedupes (i.e. swallows) an error with getHttpRequestAsyncStore().shouldErrorBeSwallowed(err)
+ *  - When reveal modifies the error with getPrettyErrorWithCodeSnippet(err)
+ */
+function logErrorDebugNote() {
+  if (isErrorDebug()) return
+  const store = getHttpRequestAsyncStore()
+  if (store) {
+    if (store.errorDebugNoteAlreadyShown) return
+    store.errorDebugNoteAlreadyShown = true
+  }
+  const msg = pc.dim(
+    formatHintLog(
+      "Error isn't helpful? See https://reveal.dev/debug#verbose-errors"
+    )
+  )
+  logDirectly(msg, "error")
+}
+
+function getCategory(httpRequestId: number | null = null): LogCategory | null {
+  const store = getHttpRequestAsyncStore()
+  if (store?.httpRequestId !== undefined) {
+    if (httpRequestId === null) {
+      httpRequestId = store.httpRequestId
+    } else {
+      assert(httpRequestId === store.httpRequestId)
+    }
+  }
+  if (httpRequestId === null) return null
+  // const category = httpRequestId % 2 === 1 ? (`request-${httpRequestId}` as const) : (`request(${httpRequestId})` as const)
+  const category = `request(${httpRequestId})` as const
+  return category
+}

package/dist/core/gaurds/logger/loggerProd.ts

@@ -0,0 +1,37 @@
+// Logger used for the production server.
+// Any other environement (dev, preview, build, and pre-rendering) uses loggerNotProd.ts instead.
+
+export { logErrorProd, onRuntimeError }
+
+import pc from "@brillout/picocolors"
+import { isAbortError } from "../../router/abort.js"
+import { setAlreadyLogged } from "../validators/isNewError.js"
+import { isObject } from "../validators/isObject.js"
+import { logErrorHint } from "./logErrorHint.js"
+import { warnIfErrorIsNotObject } from "./warnIfErrorIsNotObject.js"
+
+function logErrorProd(err: unknown, _httpRquestId: null | number): void {
+  warnIfErrorIsNotObject(err)
+  setAlreadyLogged(err)
+
+  if (isAbortError(err)) {
+    return
+  }
+
+  // We ensure we print a string; Cloudflare Workers doesn't seem to properly stringify `Error` objects.
+  const errStr =
+    isObject(err) && "stack" in err ? String(err.stack) : String(err)
+  console.error(pc.red(errStr))
+
+  // Needs to be called after logging the error.
+  onRuntimeError(err)
+}
+
+// Every server-side runtime error is expected to go through `onRuntimeError()`.
+//  - onRuntimeError(err) should always be called after `console.error(err)`.
+//    - Because the error hint of logErrorHint(err) should be shown *after* the error.
+//  - In principle, any runtime error is (or at least should) be catched by reveal, otherwise reveal couldn't render the error page.
+function onRuntimeError(err: unknown) {
+  // The more runtime errors we pass to logErrorHint() the better.
+  logErrorHint(err)
+}

package/dist/core/gaurds/logger/loggerRuntime.ts

@@ -0,0 +1,46 @@
+// Logger used by the the server runtime. (Also during pre-rendering since it uses the sever runtime.)
+
+export let logRuntimeError: LogError = logErrorProd;
+export let logRuntimeInfo: null | LogInfo = null; // logInfo is null in production
+export { overwriteRuntimeProductionLogger };
+
+import { LogError, LogInfo } from "./loggerNotProd.js";
+import { logErrorProd } from "./loggerProd.js";
+
+// Set production logger (which is overwritten by loggerNotProd.ts in non-production environments such as development and during pre-rendering)
+logRuntimeError =
+  logRuntimeError ??
+  // Default
+  logErrorProd;
+
+function overwriteRuntimeProductionLogger(
+  logError_: LogError,
+  logInfo_: LogInfo | null,
+) {
+  logRuntimeError = logError_;
+  logRuntimeInfo = logInfo_;
+}
+
+// // Logger used by the the server runtime. (Also during pre-rendering since it uses the sever runtime.)
+
+// export let logRuntimeError: LogError
+// export let logRuntimeInfo: null | LogInfo = null // logInfo is null in production
+// export { overwriteRuntimeProductionLogger }
+
+// import type { LogError, LogInfo } from "../../core/loggerNotProd.js"
+// import { logErrorProd } from "../../utils/gaurds/logger/loggerProd.js"
+
+// // Set production logger (which is overwritten by loggerNotProd.ts in non-production environments such as development and during pre-rendering)
+// logRuntimeError =
+//   // @ts-expect-error
+//   logRuntimeError ??
+//   // Default
+//   logErrorProd
+
+// function overwriteRuntimeProductionLogger(
+//   logError_: LogError,
+//   logInfo_: LogInfo | null
+// ) {
+//   logRuntimeError = logError_
+//   logRuntimeInfo = logInfo_
+// }

package/dist/core/gaurds/logger/loggerVite/removeSuperfluousViteLog.ts

@@ -0,0 +1,30 @@
+export {
+  removeSuperfluousViteLog,
+  removeSuperfluousViteLog_disable,
+  removeSuperfluousViteLog_enable,
+};
+
+import { assert } from "../../../../plugins/utils.js";
+
+const superfluousLog = "Forced re-optimization of dependencies";
+let enabled = false;
+
+function removeSuperfluousViteLog(msg: string): boolean {
+  if (!enabled) {
+    return false;
+  }
+  if (
+    msg.toLowerCase().includes("forced") &&
+    msg.toLowerCase().includes("optimization")
+  ) {
+    assert(msg === superfluousLog, msg); // assertion fails => Vite changed its message => update this function
+    return true;
+  }
+  return false;
+}
+function removeSuperfluousViteLog_enable(): void {
+  enabled = true;
+}
+function removeSuperfluousViteLog_disable(): void {
+  enabled = false;
+}

package/dist/core/gaurds/logger/loggerVite.ts

@@ -0,0 +1,65 @@
+export { improveViteLogs }
+
+import type { LogErrorOptions, LogType, ResolvedConfig } from "vite"
+
+import { getHttpRequestAsyncStore } from "../../processing/getters/getHttpRequestAsyncStore.js"
+import { removeEmptyLines } from "../../utils/string/removeEmptyLines.js"
+import {
+  trimWithAnsi,
+  trimWithAnsiTrailOnly,
+} from "../../utils/string/trimWithAnsi.js"
+import { assert } from "../assertions/assert/index.js"
+import { isErrorDebug } from "../validators/isErrorDebug.js"
+import { logViteAny, logViteError } from "./loggerNotProd.js"
+import { removeSuperfluousViteLog } from "./loggerVite/removeSuperfluousViteLog.js"
+
+function improveViteLogs(config: ResolvedConfig) {
+  intercept("info", config)
+  intercept("warn", config)
+  intercept("error", config)
+}
+
+function intercept(logType: LogType, config: ResolvedConfig) {
+  config.logger[logType] = (msg, options: LogErrorOptions = {}) => {
+    assert(!isErrorDebug())
+
+    if (removeSuperfluousViteLog(msg)) return
+
+    if (!!options.timestamp) {
+      msg = trimWithAnsi(msg)
+    } else {
+      // No timestamp => no "[vite]" tag prepended => we don't trim the beginning of the message
+      msg = trimWithAnsiTrailOnly(msg)
+    }
+    msg = cleanFirstViteLog(msg)
+
+    const store = getHttpRequestAsyncStore()
+
+    if (options.error) {
+      // Vite does a poor job of handling errors.
+      //  - It doesn't format error code snippets.
+      //  - It only shows error.message which means that crucial information such as error.id isn't shown to the user.
+      logViteError(options.error, store?.httpRequestId)
+      // We swallow Vite's message: we didn't see it add any value so far.
+      //  - It can even be confusing, such as the following:
+      //    ```
+      //    Error when evaluating SSR module virtual:reveal:pageConfigValuesAll:server:/pages/abort: failed to import "/pages/abort/+Page.mdx"
+      //    ```
+      assert(!isErrorDebug())
+      return
+    }
+
+    // Vite's default logger preprends the "[vite]" tag if and only if options.timestamp is true
+    const prependViteTag = options.timestamp || !!store?.httpRequestId
+    logViteAny(msg, logType, store?.httpRequestId ?? null, prependViteTag)
+  }
+}
+
+function cleanFirstViteLog(msg: string): string {
+  const isFirstVitLog = msg.includes("VITE") && msg.includes("ready")
+  if (isFirstVitLog) {
+    return removeEmptyLines(msg)
+  } else {
+    return msg
+  }
+}

package/dist/core/gaurds/logger/overwriteAssertProductionLogger/index.ts

@@ -0,0 +1,9 @@
+import { Logger } from "../../../../types/interfaces/log";
+import { globalObject } from "../../../globals/objects/log";
+
+export { overwriteAssertProductionLogger };
+export type { Logger };
+
+function overwriteAssertProductionLogger(logger: Logger): void {
+  globalObject.logger = logger;
+}

package/dist/core/gaurds/logger/trackLogs.ts

@@ -0,0 +1,35 @@
+import pc from "@brillout/picocolors";
+import { isDebugActivated } from "../debugger/index.js";
+import { assertIsNotBrowser } from "../assertions/assertIsNotBrowser/index.js";
+
+assertIsNotBrowser();
+
+if (isDebugActivated("reveal:log")) {
+  trackLogs();
+}
+
+// https://stackoverflow.com/questions/45395369/how-to-get-console-log-line-numbers-shown-in-nodejs/75109905#75109905
+function trackLogs() {
+  const logOriginal = process.stdout.write;
+  // @ts-ignore
+  const log = (msg) => logOriginal.call(process.stdout, msg + "\n");
+  ["stdout", "stderr"].forEach((stdName) => {
+    // @ts-ignore
+    var methodOriginal = process[stdName].write;
+    // @ts-ignore
+    process[stdName].write = function (...args) {
+      log(pc.bold(pc.blue("*** LOG ***")));
+      // @ts-ignore
+      methodOriginal.apply(process[stdName], args);
+      // @ts-ignore
+      log(
+        new Error().stack?.replace(
+          /^Error(\:|)/,
+          pc.magenta("*** LOG ORIGIN ***"),
+        ),
+      );
+    };
+  });
+
+  Error.stackTraceLimit = Infinity;
+}

package/dist/core/gaurds/logger/warnIfErrorIsNotObject.ts

@@ -0,0 +1,31 @@
+export { warnIfErrorIsNotObject }
+
+import pc from "@brillout/picocolors"
+import { assertIsNotBrowser } from "../assertions/assertIsNotBrowser/index.js"
+import { assertWarning } from "../assertions/assertWarning/index.js"
+import { isObject } from "../validators/isObject.js"
+
+assertIsNotBrowser()
+
+// It would be cleaner to:
+//  - Call assertUsageErrorIsObject() right after calling the user's hook
+//    - Attach the original error: assertUsageError.originalErrorValue = err
+//      - Show the original error in reveal's error handling
+//  - Use assertErrorIsObject() throughout reveal's source code
+function warnIfErrorIsNotObject(err: unknown): void {
+  if (!isObject(err)) {
+    console.warn("[reveal] The thrown value is:")
+    console.warn(err)
+    assertWarning(
+      false,
+      `One of your hooks threw an error ${pc.cyan("throw someValue")} but ${pc.cyan(
+        "someValue"
+      )} isn't an object (it's ${pc.cyan(
+        `typeof someValue === ${typeof err}`
+      )} instead). Make sure thrown values are always wrapped with ${pc.cyan("new Error()")}, in other words: ${pc.cyan(
+        "throw someValue"
+      )} should be replaced with ${pc.cyan("throw new Error(someValue)")}. The thrown value is printed above.`,
+      { onlyOnce: false }
+    )
+  }
+}

package/dist/core/gaurds/normalization/freezePartial.ts

@@ -0,0 +1,39 @@
+export { freezePartial };
+
+import pc from "@brillout/picocolors";
+import { assertIsNotBrowser } from "../assertions/assertIsNotBrowser";
+// Unit tests at ./freezePartial.spec.ts
+
+assertIsNotBrowser();
+
+function freezePartial(
+  obj: Record<string, unknown>,
+  allowList: Record<string, (val: unknown) => boolean>,
+) {
+  Object.entries(obj).forEach(([key, val]) => {
+    Object.defineProperty(obj, key, {
+      get() {
+        return val;
+      },
+      set(newVal: unknown) {
+        if (key in allowList) {
+          const isAllowed = allowList[key]!(newVal);
+          if (isAllowed) {
+            val = newVal;
+            return;
+          } else {
+            throw new Error(
+              `Setting wrong value ${pc.cyan(JSON.stringify(newVal))} for property ${pc.cyan(key)}`,
+            );
+          }
+        }
+        throw new Error(
+          `You aren't allowed to mutate property ${pc.cyan(key)}`,
+        );
+      },
+      configurable: false,
+      enumerable: true,
+    });
+  });
+  Object.preventExtensions(obj);
+}

package/dist/core/gaurds/normalization/normalizeHeaders.ts

@@ -0,0 +1,20 @@
+import { isObject } from "../validators/isObject";
+
+export { normalizeHeaders };
+
+function normalizeHeaders(
+  /* This type is precise, too precise which can be annoying: e.g. cannot pass a string[][] argument because it doesn't match the more precise [string,string][] type.
+  headersOriginal ConstructorParameters<typeof Headers>[0]
+  */
+  headersOriginal: unknown,
+): Record<string, string> {
+  let headersCleaned = headersOriginal;
+  // Copied from https://github.com/hattipjs/hattip/blob/69237d181300b200a14114df2c3c115c44e0f3eb/packages/adapter/adapter-node/src/request.ts#L78-L83
+  if (isObject(headersCleaned) && headersCleaned[":method"])
+    headersCleaned = Object.fromEntries(
+      Object.entries(headersCleaned).filter(([key]) => !key.startsWith(":")),
+    );
+  const headersStandard = new Headers(headersCleaned as any);
+  const headers = Object.fromEntries(headersStandard.entries());
+  return headers;
+}

package/dist/core/gaurds/normalization/normalizeLink.tsx

@@ -0,0 +1,14 @@
+import React from "react";
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const normalizeLink = (href: string, children: any) => {
+  function normalize(url: string) {
+    return "/" + url.split("/").filter(Boolean).join("/");
+  }
+  if (!href.startsWith("/")) throw new Error("Link href should start with /");
+  href = import.meta.env.VITE_PUBLIC_URL + href;
+  href = normalize(href);
+  return <a href={href}>{children}</a>;
+};
+
+export default normalizeLink;

package/dist/core/gaurds/normalization/normalizeUrlArgument.ts

@@ -0,0 +1,22 @@
+import { isUrl, isUrlPathnameRelative } from "../../targets/url/parseUrl";
+import { assertUsage } from "../assertions/assertUsage";
+
+export { normalizeUrlArgument };
+
+function normalizeUrlArgument(
+  url: string,
+  fnName: "prefetch" | "navigate",
+): string {
+  // Succinct error message to save client-side KBs
+  const errMsg = `[${fnName}(url)] Invalid URL ${url}`;
+  assertUsage(isUrl(url), errMsg);
+  if (url.startsWith(location.origin)) {
+    url = url.slice(location.origin.length);
+  }
+  assertUsage(
+    url.startsWith("/") || isUrlPathnameRelative(url),
+    // `errMsg` used the original `url` value
+    errMsg,
+  );
+  return url;
+}