@revealui/core 0.0.1-pre.0

package/dist/core/processing/serializers/stringifyTypes.ts

@@ -0,0 +1,103 @@
+export { types };
+
+const types: readonly Type<any, any>[] = [
+  ts({
+    is: (val) => val === undefined,
+    match: (str) => str === "!undefined",
+    serialize: () => "!undefined",
+    deserialize: (): undefined => undefined,
+  }),
+  ts({
+    is: (val) => val === Infinity,
+    match: (str) => str === "!Infinity",
+    serialize: () => "!Infinity",
+    deserialize: (): typeof Infinity => Infinity,
+  }),
+  ts({
+    is: (val) => val === -Infinity,
+    match: (str) => str === "!-Infinity",
+    serialize: () => "!-Infinity",
+    deserialize: (): number => -Infinity,
+  }),
+  ts({
+    is: (val) => typeof val === "number" && isNaN(val),
+    match: (str) => str === "!NaN",
+    serialize: () => "!NaN",
+    deserialize: () => NaN,
+  }),
+  ts({
+    is: (val) => val instanceof Date,
+    match: (str) => str.startsWith("!Date:"),
+    serialize: (val: Date) => "!Date:" + val.toISOString(),
+    deserialize: (str) => new Date(str.slice("!Date:".length)),
+  }),
+  ts({
+    is: (val) => typeof val === "bigint",
+    match: (str) => str.startsWith("!BigInt:"),
+    serialize: (val: BigInt) => "!BigInt:" + val.toString(),
+    deserialize: (str) => {
+      if (typeof BigInt === "undefined") {
+        throw new Error(
+          "Your JavaScript environement does not support BigInt. Consider adding a polyfill.",
+        );
+      }
+      return BigInt(str.slice("!BigInt:".length));
+    },
+  }),
+  ts({
+    is: (val) => val instanceof RegExp,
+    match: (str) => str.startsWith("!RegExp:"),
+    serialize: (val: RegExp) => "!RegExp:" + val.toString(),
+    deserialize: (str) => {
+      str = str.slice("!RegExp:".length);
+      // const args: string[] = str.match(/\/(.*?)\/([gimy])?$/)!
+      const args: string[] = str.match(/\/(.*)\/(.*)?/)!;
+      const pattern: string = args[1]!;
+      const flags: string = args[2]!;
+      return new RegExp(pattern, flags);
+    },
+  }),
+  ts({
+    is: (val) => val instanceof Map,
+    match: (str) => str.startsWith("!Map:"),
+    serialize: (
+      val: Map<unknown, unknown>,
+      serializer: (val: [unknown, unknown][]) => string,
+    ) => "!Map:" + serializer(Array.from(val.entries())),
+    deserialize: (str, deserializer) =>
+      new Map(deserializer(str.slice("!Map:".length))),
+  }),
+  ts({
+    is: (val) => val instanceof Set,
+    match: (str) => str.startsWith("!Set:"),
+    serialize: (val: Set<unknown>, serializer: (val: unknown[]) => string) =>
+      "!Set:" + serializer(Array.from(val.values())),
+    deserialize: (str, deserializer) =>
+      new Set(deserializer(str.slice("!Set:".length))),
+  }),
+  // Avoid collisions with the special strings defined above
+  ts({
+    is: (val) => typeof val === "string" && val.startsWith("!"),
+    match: (str) => str.startsWith("!"),
+    serialize: (val: string) => "!" + val,
+    deserialize: (str) => str.slice(1),
+  }),
+] as const;
+
+type Type<ValueType, IntermediateType> = {
+  is: (val: unknown) => asserts val is ValueType;
+  match: (str: string) => boolean;
+  serialize: (
+    val: ValueType,
+    serializer: (val: IntermediateType) => string,
+  ) => string;
+  deserialize: (
+    str: string,
+    deserializer: (str: string) => IntermediateType,
+  ) => ValueType;
+};
+
+// Type check
+function ts<T, IntermediateType>(t: Type<T, IntermediateType>) {
+  return t;
+}

package/dist/core/processing/setters/addIs404ToPageProps.ts

@@ -0,0 +1,27 @@
+import { PageContextAssertIs404 } from "../../../types/interfaces/error";
+import { assertIs404 } from "../../gaurds/assertions/assertIs404";
+import { assertWarning } from "../../gaurds/assertions/assertWarning";
+import { isObject } from "../../gaurds/validators/isObject";
+
+export { addIs404ToPageProps };
+
+function addIs404ToPageProps(
+  pageContext: Record<string, unknown> & PageContextAssertIs404,
+) {
+  assertIs404(pageContext);
+  addIs404(pageContext);
+}
+
+function addIs404(pageContext: Record<string, unknown>) {
+  if (pageContext.is404 === undefined || pageContext.is404 === null) return;
+  const pageProps = pageContext.pageProps || {};
+  if (!isObject(pageProps)) {
+    assertWarning(false, "pageContext.pageProps should be an object", {
+      showStackTrace: true,
+      onlyOnce: true,
+    });
+    return;
+  }
+  pageProps.is404 = pageProps.is404 || pageContext.is404;
+  pageContext.pageProps = pageProps;
+}

package/dist/core/processing/setters/setAlwaysShowStackTrace.ts

@@ -0,0 +1,7 @@
+import { globalObject } from "../../globals/objects/log";
+
+export { setAlwaysShowStackTrace };
+
+function setAlwaysShowStackTrace() {
+  globalObject.alwaysShowStackTrace = true;
+}

package/dist/core/processing/transformers/augmentType.ts

@@ -0,0 +1,10 @@
+import { PageContext } from "../../../types/interfaces/context";
+
+export { augmentType };
+
+function augmentType<T extends PageContext>(
+  pageContext: T,
+  additionalProps: Partial<T>,
+): void {
+  Object.assign(pageContext, additionalProps);
+}

package/dist/core/processing/transformers/rollupSourceMap.ts

@@ -0,0 +1,23 @@
+export { sourceMapRemove };
+export { sourceMapPassthrough };
+
+// https://rollupjs.org/guide/en/#source-code-transformations
+
+/** Remove entire source mapping, to save KBs. */
+function sourceMapRemove(code: string): {
+  code: string;
+  map: { mappings: "" };
+} {
+  return {
+    code,
+    map: { mappings: "" },
+  };
+}
+
+/** Don't provide any source map, pass through current source map instead. */
+function sourceMapPassthrough(code: string): { code: string; map: null } {
+  return {
+    code,
+    map: null,
+  };
+}

package/dist/core/processing/transformers/slice.ts

@@ -0,0 +1,52 @@
+import { assert } from "../../gaurds/assertions/assert";
+
+export { slice };
+
+function slice<Element, T extends Array<Element>>(
+  thing: T,
+  from: number,
+  to: number,
+): T;
+function slice(thing: string, from: number, to: number): string;
+function slice(
+  thing: string | unknown[],
+  from: number,
+  to: number,
+): string | unknown[] {
+  if (typeof thing === "string") {
+    return sliceArray(thing.split(""), from, to).join("");
+  } else {
+    return sliceArray(thing, from, to);
+  }
+}
+
+function sliceArray<Element, T extends Array<Element>>(
+  list: T,
+  from: number,
+  to: number,
+): T {
+  const listSlice: T = [] as unknown as T;
+
+  let start = from >= 0 ? from : list.length + from;
+  assert(start >= 0 && start <= list.length);
+  let end = to >= 0 ? to : list.length + to;
+  assert(end >= 0 && end <= list.length);
+
+  while (true) {
+    if (start === end) {
+      break;
+    }
+    if (start === list.length) {
+      start = 0;
+    }
+    if (start === end) {
+      break;
+    }
+    const el = list[start];
+    assert(el !== undefined);
+    listSlice.push(el);
+    start++;
+  }
+
+  return listSlice;
+}

package/dist/core/renderer/page/executeOnBeforeRenderAndDataHooks.ts

@@ -0,0 +1,53 @@
+export { executeOnBeforeRenderAndDataHooks };
+
+import { assertOnBeforeRenderHookReturn } from "../../gaurds/assertions/assertOnBeforeRenderHookReturn.js";
+import { executeHook } from "../../hooks/executeHook.js";
+import { getHook } from "../../processing/getters/getHook.js";
+import { type PageContextExports } from "../../processing/getters/getPageFiles/index.js";
+import {
+  preparePageContextForUserConsumptionServerSide,
+  type PageContextForUserConsumptionServerSide,
+} from "./preparePageContextForUserConsumptionServerSide.js";
+
+async function executeOnBeforeRenderAndDataHooks(
+  pageContext: {
+    pageId: string;
+    _pageContextAlreadyProvidedByOnPrerenderHook?: true;
+  } & PageContextExports &
+    PageContextForUserConsumptionServerSide,
+): Promise<void> {
+  if (pageContext._pageContextAlreadyProvidedByOnPrerenderHook) {
+    return;
+  }
+  const dataHook = getHook(pageContext, "data");
+  const onBeforeRenderHook = getHook(pageContext, "onBeforeRender");
+  if (!dataHook && !onBeforeRenderHook) {
+    return;
+  }
+
+  preparePageContextForUserConsumptionServerSide(pageContext);
+
+  if (dataHook) {
+    const hookResult = await executeHook(
+      () => dataHook.hookFn(pageContext),
+      dataHook,
+      pageContext,
+    );
+    // Note: hookResult can be anything (e.g. an object) and is to be assigned to pageContext.data
+    const pageContextFromHook = {
+      data: hookResult,
+    };
+    Object.assign(pageContext, pageContextFromHook);
+  }
+
+  if (onBeforeRenderHook) {
+    const hookResult = await executeHook(
+      () => onBeforeRenderHook.hookFn(pageContext),
+      onBeforeRenderHook,
+      pageContext,
+    );
+    assertOnBeforeRenderHookReturn(hookResult, onBeforeRenderHook.hookFilePath);
+    const pageContextFromHook = hookResult?.pageContext;
+    Object.assign(pageContext, pageContextFromHook);
+  }
+}

package/dist/core/renderer/page/executeOnRenderHtmlHook.ts

@@ -0,0 +1,261 @@
+export { executeOnRenderHtmlHook }
+export type { RenderHook }
+
+import pc from "@brillout/picocolors"
+import type { PageConfigRuntime } from "../../../types/interfaces/page.js"
+import { PageContextPromise } from "../../assets/index.js"
+import { assertHookReturnedObject } from "../../gaurds/assertions/assertHookReturnedObject.js"
+import { assertPageContextProvidedByUser } from "../../gaurds/assertions/assertPageContextProvidedByUser.js"
+import { logRuntimeError } from "../../gaurds/logger/loggerRuntime.js"
+import { executeHook } from "../../hooks/executeHook.js"
+import { getHook, type Hook } from "../../processing/getters/getHook.js"
+import { PreloadFilter } from "../../processing/getters/getHtmlTags.js"
+import type { PageAsset } from "../../processing/getters/getPageAssets.js"
+import type { PageContextSerialization } from "../../processing/serializers/serializePageContextClientSide.js"
+import {
+  DocumentHtml,
+  dangerouslySkipEscape,
+  isDocumentHtml,
+  renderDocumentHtml,
+  type HtmlRender,
+} from "../stream/html.js"
+import { isStream } from "../stream/index.js"
+import {
+  assert,
+  assertUsage,
+  assertWarning,
+  isCallable,
+  isObject,
+  isPromise,
+  objectAssign,
+} from "../stream/utils.js"
+import {
+  preparePageContextForUserConsumptionServerSide,
+  type PageContextForUserConsumptionServerSide,
+} from "./preparePageContextForUserConsumptionServerSide.js"
+
+type GetPageAssets = () => Promise<PageAsset[]>
+
+type RenderHook = Hook & { hookName: HookName }
+type HookName = "onRenderHtml"
+
+async function executeOnRenderHtmlHook(
+  pageContext: PageContextForUserConsumptionServerSide &
+    PageContextSerialization & {
+      pageId: string
+      _pageConfigs: PageConfigRuntime[]
+      __getPageAssets: GetPageAssets
+      _isHtmlOnly: boolean
+      _baseServer: string
+      _pageFilePathsLoaded: string[]
+      _httpRequestId: number | null
+    }
+): Promise<{
+  renderHook: RenderHook
+  htmlRender: HtmlRender
+}> {
+  const { renderHook, hookFn } = getRenderHook(pageContext)
+  objectAssign(pageContext, { _renderHook: renderHook })
+
+  preparePageContextForUserConsumptionServerSide(pageContext)
+  const hookReturnValue = await executeHook(
+    () => hookFn(pageContext),
+    renderHook,
+    pageContext
+  )
+  const {
+    documentHtml,
+    pageContextProvidedByRenderHook,
+    pageContextPromise,
+    injectFilter,
+  } = processHookReturnValue(hookReturnValue, renderHook)
+
+  Object.assign(pageContext, pageContextProvidedByRenderHook)
+  objectAssign(pageContext, { _pageContextPromise: pageContextPromise })
+
+  const onErrorWhileStreaming = (err: unknown) => {
+    // Should the stream inject the following?
+    // ```
+    // <script>console.error("An error occurred on the server side while streaming the page to HTML, see server logs.")</script>
+    // ```
+    logRuntimeError(err, pageContext._httpRequestId)
+    if (!pageContext.errorWhileRendering) {
+      pageContext.errorWhileRendering = err
+    }
+  }
+
+  const htmlRender = await renderDocumentHtml(
+    documentHtml,
+    pageContext,
+    onErrorWhileStreaming,
+    injectFilter
+  )
+  assert(typeof htmlRender === "string" || isStream(htmlRender))
+  return { htmlRender, renderHook }
+}
+
+function getRenderHook(pageContext: PageContextForUserConsumptionServerSide) {
+  let hookFound:
+    | undefined
+    | {
+        renderHook: RenderHook
+        hookFn: Function
+      }
+  {
+    let hook: null | Hook
+    let hookName: undefined | HookName = undefined
+    hook = getHook(pageContext, "onRenderHtml")
+    if (hook) {
+      hookName = "onRenderHtml"
+    } else {
+      hook = getHook(pageContext, "onRenderHtml")
+      if (hook) {
+        hookName = "onRenderHtml"
+      }
+    }
+    if (hook) {
+      assert(hookName)
+      const { hookFilePath, hookFn, hookTimeout } = hook
+      hookFound = {
+        hookFn,
+        renderHook: { hookFn, hookFilePath, hookName, hookTimeout },
+      }
+    }
+  }
+  if (!hookFound) {
+    const hookName =
+      pageContext._pageConfigs.length > 0 ? "onRenderHtml" : "onRenderClient"
+    assertUsage(
+      false,
+      [
+        `No ${hookName}() hook found, see https://reveal.dev/${hookName}`,
+        /*
+        'See https://reveal.dev/render-modes for more information.',
+        [
+          // 'Loaded config files (none of them define the onRenderHtml() hook):',
+          'Loaded server-side page files (none of them `export { render }`):',
+          ...pageContext._pageFilePathsLoaded.map((f, i) => ` (${i + 1}): ${f}`)
+        ].join('\n')
+        */
+      ].join(" ")
+    )
+  }
+  return hookFound
+}
+
+function processHookReturnValue(
+  hookReturnValue: unknown,
+  renderHook: RenderHook
+) {
+  let documentHtml: DocumentHtml
+  let pageContextPromise: PageContextPromise = null
+  let pageContextProvidedByRenderHook: null | Record<string, unknown> = null
+  let injectFilter: PreloadFilter = null
+  const ret = () => ({
+    documentHtml,
+    pageContextProvidedByRenderHook,
+    pageContextPromise,
+    injectFilter,
+  })
+
+  if (hookReturnValue === null) return ret()
+
+  if (isDocumentHtml(hookReturnValue)) {
+    documentHtml = hookReturnValue
+    return ret()
+  }
+
+  const errPrefix =
+    `The ${renderHook.hookName as string}() hook defined at ${renderHook.hookFilePath}` as const
+  const errSuffix = `a string generated with the ${pc.cyan(
+    "escapeInject`<html>...</html>`"
+  )} template tag or a string returned by ${pc.cyan(
+    "dangerouslySkipEscape()"
+  )}, see https://reveal.dev/escapeInject` as const
+  if (typeof hookReturnValue === "string") {
+    assertWarning(
+      false,
+      [
+        errPrefix,
+        "returned a plain JavaScript string which is dangerous: it should instead return",
+        errSuffix,
+      ].join(" "),
+      { onlyOnce: true }
+    )
+    hookReturnValue = dangerouslySkipEscape(hookReturnValue)
+  }
+  assertUsage(
+    isObject(hookReturnValue),
+    [
+      errPrefix,
+      `should return ${pc.cyan("null")}, the value ${pc.cyan("documentHtml")}, or an object ${pc.cyan(
+        "{ documentHtml, pageContext }"
+      )} where ${pc.cyan("pageContext")} is ${pc.cyan(
+        "undefined"
+      )} or an object holding additional pageContext values, and where ${pc.cyan("documentHtml")} is`,
+      errSuffix,
+    ].join(" ")
+  )
+  assertHookReturnedObject(
+    hookReturnValue,
+    ["documentHtml", "pageContext", "injectFilter"] as const,
+    errPrefix
+  )
+
+  if (hookReturnValue.injectFilter) {
+    assertUsage(
+      isCallable(hookReturnValue.injectFilter),
+      "injectFilter should be a function"
+    )
+    injectFilter = hookReturnValue.injectFilter as PreloadFilter
+  }
+
+  assertUsage(
+    hookReturnValue.documentHtml,
+    `${errPrefix} returned an object that is missing the ${pc.code("documentHtml")} property.`
+  )
+  {
+    let val = hookReturnValue.documentHtml
+    const errBegin =
+      `${errPrefix} returned ${pc.cyan("{ documentHtml }")}, but ${pc.cyan("documentHtml")}` as const
+    if (typeof val === "string") {
+      assertWarning(
+        false,
+        [
+          errBegin,
+          `is a plain JavaScript string which is dangerous: ${pc.cyan("documentHtml")} should be`,
+          errSuffix,
+        ].join(" "),
+        { onlyOnce: true }
+      )
+      val = dangerouslySkipEscape(val)
+    }
+    assertUsage(
+      isDocumentHtml(val),
+      [errBegin, "should be", errSuffix].join(" ")
+    )
+    documentHtml = val
+  }
+
+  if (hookReturnValue.pageContext) {
+    const val = hookReturnValue.pageContext
+    const errBegin = `${errPrefix} returned ${pc.cyan("{ pageContext }")}, but ${pc.cyan("pageContext")}`
+    if (isPromise(val) || isCallable(val)) {
+      assertWarning(
+        !isPromise(val),
+        `${errBegin} is a promise which is deprecated in favor of async functions, see https://reveal.dev/streaming#initial-data-after-stream-end`,
+        { onlyOnce: true }
+      )
+      pageContextPromise = async () => await val
+    } else {
+      assertUsage(
+        isObject(val),
+        `${errBegin} should be an object or an async function, see https://reveal.dev/streaming#initial-data-after-stream-end`
+      )
+      assertPageContextProvidedByUser(val, renderHook)
+      pageContextProvidedByRenderHook = val
+    }
+  }
+
+  return ret()
+}