@revealui/core 0.0.1-pre.0

package/dist/core/processing/serializers/serializePage/serializeConfigValues.ts

@@ -0,0 +1,336 @@
+export { serializeConfigValues }
+
+import pc from "@brillout/picocolors"
+import { addImportStatement } from "../../../../plugins/importUserCode/addImportStatement.js"
+import type {
+  ConfigEnvInternal,
+  ConfigValue,
+  ConfigValueSource,
+  DefinedAtData,
+  DefinedAtFile,
+  PageConfigBuildTime,
+  PageConfigGlobalBuildTime,
+} from "../../../../types/interfaces/page.js"
+import { assert } from "../../../gaurds/assertions/assert/index.js"
+import { assertIsNotProductionRuntime } from "../../../gaurds/assertions/assertIsNotProductionRuntime/index.js"
+import { assertUsage } from "../../../gaurds/assertions/assertUsage/index.js"
+import { getConfigValueFilePathToShowToUser } from "../../getters/getConfigValueFilePathToShowToUser.js"
+import { getPropAccessNotation } from "../../getters/getPropAccessNotation.js"
+import { parsePointerImportData } from "../../getters/getRevealConfig/transformPointerImports.js"
+import { stringify } from "../stringify.js"
+import type { ValueSerialized } from "./PageConfigSerialized.js"
+const REPLACE_ME_BEFORE = "__reveal__REPLACE_ME_BEFORE__"
+const REPLACE_ME_AFTER = "__reveal__REPLACE_ME_AFTER__"
+
+// This file is never loaded on the client-side but we save it under the reveal/shared/ directory in order to collocate it with parsePageConfigs()
+// - reveal/shared/page-configs/serialize/parsePageConfigs.ts
+// - parsePageConfigs() is loaded on both the client- and server-side.
+assertIsNotProductionRuntime()
+
+function serializeConfigValues(
+  pageConfig:
+    | PageConfigBuildTime
+    | (PageConfigGlobalBuildTime & { configValuesComputed?: undefined }),
+  importStatements: string[],
+  isEnvMatch: (configEnv: ConfigEnvInternal) => boolean,
+  { isEager }: { isEager: boolean },
+  tabspace: string
+): string[] {
+  const lines: string[] = []
+  tabspace += "  "
+
+  Object.entries(pageConfig.configValuesComputed ?? {}).forEach(
+    ([configName, configValuesComputed]) => {
+      if (!isEnvMatch(configValuesComputed.configEnv)) return
+      // Is there a use case for overriding computed values? If yes, then configValeSources has higher precedence
+      if (pageConfig.configValueSources[configName]) return
+      const valueData = serializeWithJson(
+        configValuesComputed.value,
+        configName,
+        null,
+        importStatements
+      )
+      const configValueBase = {
+        type: "computed",
+        definedAtData: null,
+      } as const
+      serializeConfigValue(
+        configValueBase,
+        valueData,
+        configName,
+        lines,
+        tabspace
+      )
+    }
+  )
+
+  Object.entries(pageConfig.configValueSources).forEach(
+    ([configName, sources]) => {
+      const configDef = pageConfig.configDefinitions[configName]
+      assert(configDef)
+      if (isEager !== !!configDef.eager) return
+      if (!configDef.cumulative) {
+        const configValueSource = sources[0]
+        assert(configValueSource)
+        assert(sources.slice(1).every((s) => s.isOverriden === true))
+        if (!isEnvMatch(configValueSource.configEnv)) return
+        const { valueData, definedAtFile } = serializeConfigValueSource(
+          configValueSource,
+          configName,
+          importStatements
+        )
+        const configValueBase = {
+          type: "standard",
+          definedAtData: definedAtFile,
+        } as const
+        serializeConfigValue(
+          configValueBase,
+          valueData,
+          configName,
+          lines,
+          tabspace
+        )
+      } else {
+        const valueDataList: ValueData[] = []
+        const definedAtData: DefinedAtFile[] = []
+        sources
+          .filter((s) => !s.isOverriden)
+          .forEach((configValueSource) => {
+            if (!isEnvMatch(configValueSource.configEnv)) return
+            const { valueData, definedAtFile } = serializeConfigValueSource(
+              configValueSource,
+              configName,
+              importStatements
+            )
+            valueDataList.push(valueData)
+            definedAtData.push(definedAtFile)
+          })
+        if (valueDataList.length === 0) return
+        const configValueBase = {
+          type: "cumulative",
+          definedAtData,
+        } as const
+        serializeConfigValue(
+          configValueBase,
+          valueDataList,
+          configName,
+          lines,
+          tabspace
+        )
+      }
+    }
+  )
+
+  return lines
+}
+
+function serializeConfigValueSource(
+  configValueSource: ConfigValueSource,
+  configName: string,
+  importStatements: string[]
+) {
+  assert(configValueSource.isOverriden === false)
+  let valueData: ValueData
+  if ("value" in configValueSource) {
+    valueData = serializeWithJson(
+      configValueSource.value,
+      configName,
+      configValueSource.definedAtFilePath,
+      importStatements
+    )
+  } else {
+    valueData = serializeWithImport(configValueSource, importStatements)
+  }
+  const definedAtFile: DefinedAtFile = {
+    filePathToShowToUser:
+      configValueSource.definedAtFilePath.filePathToShowToUser,
+    fileExportPathToShowToUser:
+      configValueSource.definedAtFilePath.fileExportPathToShowToUser,
+  }
+  return { valueData, definedAtFile }
+}
+
+type ValueData = {
+  type: ValueSerialized["type"]
+  valueAsJsCode: string
+}
+function serializeConfigValue(
+  configValueBase: Omit<ConfigValue, "value">,
+  valueData: ValueData | ValueData[],
+  configName: string,
+  lines: string[],
+  tabspace: string
+) {
+  lineAdd(`[${JSON.stringify(configName)}]: {`)
+  {
+    tab()
+    lineAdd(`type: "${configValueBase.type}",`)
+    lineAdd(`definedAtData: ${JSON.stringify(configValueBase.definedAtData)},`)
+    lineAdd(`valueSerialized:`)
+    if (!Array.isArray(valueData)) {
+      serializeValueData(valueData)
+    } else {
+      lineAppend(" [")
+      valueData.forEach(serializeValueData)
+      lineAppend(` ],`)
+    }
+    untab()
+  }
+  lineAdd("},")
+
+  return
+
+  function serializeValueData(valueData: ValueData) {
+    lineAppend(` {`)
+    tab()
+    lineAdd(`type: "${valueData.type}",`)
+    const valueProp: ValueProp =
+      valueData.type !== "plus-file" ? "value" : "exportValues"
+    lineAdd(`${valueProp}: ${valueData.valueAsJsCode},`)
+    untab()
+    lineAdd(`},`)
+  }
+  type ValueProp = Exclude<KeysOfUnion<ValueSerialized>, "type">
+  // https://stackoverflow.com/questions/49401866/all-possible-keys-of-an-union-type/49402091#49402091
+  type KeysOfUnion<T> = T extends T ? keyof T : never
+
+  function lineAppend(str: string) {
+    const i = lines.length - 1
+    lines[i] = lines[i] += str
+  }
+  function lineAdd(str: string) {
+    lines.push(`${tabspace}${str}`)
+  }
+  function tab() {
+    tabspace += "  "
+  }
+  function untab() {
+    tabspace = tabspace.slice(2)
+  }
+}
+
+function serializeWithImport(
+  configValueSource: ConfigValueSource,
+  importStatements: string[]
+): ValueData {
+  assert(!configValueSource.valueIsFilePath)
+
+  const {
+    valueIsImportedAtRuntime,
+    valueIsDefinedByPlusFile,
+    definedAtFilePath,
+  } = configValueSource
+  assert(valueIsImportedAtRuntime)
+  const { filePathAbsoluteVite, fileExportName } = definedAtFilePath
+
+  if (valueIsDefinedByPlusFile) assert(fileExportName === undefined)
+  const { importName } = addImportStatement(
+    importStatements,
+    filePathAbsoluteVite,
+    fileExportName || "*"
+  )
+
+  return {
+    type: valueIsDefinedByPlusFile ? "plus-file" : "pointer-import",
+    valueAsJsCode: importName,
+  }
+}
+
+function serializeWithJson(
+  value: unknown,
+  configName: string,
+  definedAtData: DefinedAtData,
+  importStatements: string[]
+): ValueData {
+  const valueAsJsCode = valueToJson(
+    value,
+    configName,
+    definedAtData,
+    importStatements
+  )
+  return {
+    type: "js-serialized",
+    valueAsJsCode,
+  }
+}
+function valueToJson(
+  value: unknown,
+  configName: string,
+  definedAtData: DefinedAtData,
+  importStatements: string[]
+): string {
+  const valueName = `config${getPropAccessNotation(configName)}`
+
+  let configValueSerialized: string
+  try {
+    configValueSerialized = stringify(value, {
+      valueName,
+      forbidReactElements: true,
+      // Replace import strings with import variables.
+      // - We don't need this anymore and could remove it.
+      //   - We temporarily needed it for nested document configs (`config.document.{title,description,favicon}`), but we finally decided to go for flat document configs instead (`config.{title,description,favicon}`).
+      //   - https://github.com/revealjs/reveal-react/pull/113
+      replacer(_, value) {
+        if (typeof value === "string") {
+          const importData = parsePointerImportData(value)
+          if (importData) {
+            const { importName } = addImportStatement(
+              importStatements,
+              importData.importPath,
+              importData.exportName
+            )
+            const replacement = [
+              REPLACE_ME_BEFORE,
+              importName,
+              REPLACE_ME_AFTER,
+            ].join("")
+            return { replacement }
+          }
+        }
+      },
+    })
+  } catch (err) {
+    logJsonSerializeError(err, configName, definedAtData)
+    assert(false)
+  }
+
+  configValueSerialized = configValueSerialized.replaceAll(
+    `"${REPLACE_ME_BEFORE}`,
+    ""
+  )
+  configValueSerialized = configValueSerialized.replaceAll(
+    `${REPLACE_ME_AFTER}"`,
+    ""
+  )
+  assert(!configValueSerialized.includes(REPLACE_ME_BEFORE))
+  assert(!configValueSerialized.includes(REPLACE_ME_AFTER))
+
+  return configValueSerialized
+}
+function logJsonSerializeError(
+  err: unknown,
+  configName: string,
+  definedAtData: DefinedAtData
+) {
+  /*
+  // import { isJsonSerializerError } from '@brillout/json-serializer/stringify'
+  let serializationErrMsg = ''
+  if (isJsonSerializerError(err)) {
+    serializationErrMsg = err.messageCore
+  } else {
+    // When a property getter throws an error
+    console.error('Serialization error:')
+    console.error(err)
+    serializationErrMsg = 'see serialization error printed above'
+  }
+  //*/
+  const configValueFilePathToShowToUser =
+    getConfigValueFilePathToShowToUser(definedAtData)
+  assert(configValueFilePathToShowToUser)
+  assertUsage(
+    false,
+    `${pc.cyan(
+      configName
+    )} defined by ${configValueFilePathToShowToUser} must be defined over a so-called "pointer import", see https://reveal.dev/config#pointer-imports`
+  )
+}

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

@@ -0,0 +1,179 @@
+export { serializePageContextAbort, serializePageContextClientSide }
+export type { PageContextSerialization }
+
+import pc from "@brillout/picocolors"
+import type { PageConfigRuntime } from "../../../types/interfaces/page.js"
+import { assert } from "../../gaurds/assertions/assert/index.js"
+import { assertUsage } from "../../gaurds/assertions/assertUsage/index.js"
+import { assertWarning } from "../../gaurds/assertions/assertWarning/index.js"
+import { hasProp } from "../../gaurds/validators/hasProp.js"
+import { isErrorPage } from "../../gaurds/validators/isErrorPage.js"
+import { isServerSideError } from "../../gaurds/validators/isServerSideError.js"
+import type { UrlRedirect } from "../../router/abort.js"
+import { pageContextInitIsPassedToClient } from "../../targets/client/pageContextInitIsPassedToClient.js"
+import { unique } from "../../targets/client/utils.js"
+import { getPropAccessNotation } from "../getters/getPropAccessNotation.js"
+import { addIs404ToPageProps } from "../setters/addIs404ToPageProps.js"
+import { notSerializable } from "./notSerializable.js"
+import { isJsonSerializerError, stringify } from "./stringify.js"
+
+const PASS_TO_CLIENT: string[] = [
+  "abortReason",
+  "_urlRewrite",
+  "_urlRedirect",
+  "abortStatusCode",
+  "_abortCall",
+  /* Not needed on the client-side
+  '_abortCaller',
+  */
+  pageContextInitIsPassedToClient,
+  "pageId",
+  "routeParams",
+  "data", // for data() hook
+]
+const PASS_TO_CLIENT_ERROR_PAGE = ["pageProps", "is404", isServerSideError]
+
+type PageContextSerialization = {
+  pageId: string
+  routeParams: Record<string, string>
+  _passToClient: string[]
+  _pageConfigs: PageConfigRuntime[]
+  is404: null | boolean
+  pageProps?: Record<string, unknown>
+  _pageContextInit: Record<string, unknown>
+}
+function serializePageContextClientSide(pageContext: PageContextSerialization) {
+  const passToClient = getPassToClient(pageContext)
+  const pageContextClient: Record<string, unknown> = {}
+  passToClient.forEach((prop) => {
+    // We set non-existing props to `undefined`, in order to pass the list of passToClient values to the client-side
+    pageContextClient[prop] = (pageContext as Record<string, unknown>)[prop]
+  })
+  if (
+    Object.keys(pageContext._pageContextInit).some((p) =>
+      passToClient.includes(p)
+    )
+  ) {
+    pageContextClient[pageContextInitIsPassedToClient] = true
+  }
+
+  let pageContextSerialized: string
+  try {
+    pageContextSerialized = serialize(pageContextClient)
+  } catch (err) {
+    const h = (s: string) => pc.cyan(s)
+    let hasWarned = false
+    const propsNonSerializable: string[] = []
+    passToClient.forEach((prop) => {
+      const propName1 = getPropAccessNotation(prop)
+      const propName2 = JSON.stringify(prop)
+      const varName = `pageContext${propName1}`
+      try {
+        serialize((pageContext as Record<string, unknown>)[prop], varName)
+      } catch (err) {
+        hasWarned = true
+        propsNonSerializable.push(prop)
+
+        // useConfig() wrong usage
+        if (prop === "_configFromHook") {
+          let pathString = ""
+          if (isJsonSerializerError(err)) {
+            pathString = err.pathString
+          }
+          assertUsage(
+            false,
+            `Cannot serialize config ${h(
+              pathString
+            )} set by useConfig(), see https://reveal.dev/useConfig#serialization-error`
+          )
+        }
+
+        // Non-serializable pageContext set by the user
+        let msg = [
+          `${h(varName)} can't be serialized and, therefore, can't be passed to the client side.`,
+          `Make sure ${h(varName)} is serializable, or remove ${h(propName2)} from ${h("passToClient")}.`,
+        ].join(" ")
+        if (isJsonSerializerError(err)) {
+          msg = `${msg} Serialization error: ${err.messageCore}.`
+        } else {
+          // When a property getter throws an error
+          console.warn("Serialization error:")
+          console.warn(err)
+          msg = `${msg} The serialization failed because of the error printed above.`
+        }
+        // We warn (instead of throwing an error) since reveal's client runtime throws an error (with `assertUsage()`) if the user's client code tries to access the property that cannot be serialized
+        assertWarning(false, msg, { onlyOnce: false })
+      }
+    })
+    assert(hasWarned)
+    propsNonSerializable.forEach((prop) => {
+      pageContextClient[prop] = notSerializable
+    })
+    try {
+      pageContextSerialized = serialize(pageContextClient)
+    } catch (err) {
+      assert(false)
+    }
+  }
+
+  return pageContextSerialized
+}
+function serialize(value: unknown, varName?: string): string {
+  return stringify(value, { forbidReactElements: true, valueName: varName })
+}
+function getPassToClient(pageContext: {
+  pageId: string
+  _passToClient: string[]
+  _pageConfigs: PageConfigRuntime[]
+  is404: null | boolean
+}): string[] {
+  let passToClient = [...pageContext._passToClient, ...PASS_TO_CLIENT]
+  if (isErrorPage(pageContext.pageId, pageContext._pageConfigs)) {
+    assert(hasProp(pageContext, "is404", "boolean"))
+    addIs404ToPageProps(pageContext)
+    passToClient.push(...PASS_TO_CLIENT_ERROR_PAGE)
+  }
+  passToClient = unique(passToClient)
+  return passToClient
+}
+
+function serializePageContextAbort(
+  pageContext: Record<string, unknown> &
+    (
+      | { _urlRedirect: UrlRedirect }
+      | { _urlRewrite: string }
+      | { abortStatusCode: number }
+    )
+): string {
+  assert(
+    pageContext._urlRedirect ||
+      pageContext._urlRewrite ||
+      pageContext.abortStatusCode
+  )
+  assert(pageContext._abortCall)
+  assert(pageContext._abortCaller)
+  // Not needed on the client-side
+  delete pageContext._abortCaller
+  const unknownProps = Object.keys(pageContext).filter(
+    (prop) =>
+      ![
+        // prettier-ignore
+        // biome-ignore format:
+        '_abortCall',
+        /* Not needed on the client-side
+        '_abortCaller',
+        */
+        "_urlRedirect",
+        "_urlRewrite",
+        "abortStatusCode",
+        "abortReason",
+        "is404",
+        "pageProps",
+      ].includes(prop)
+  )
+  if (!pageContext._isLegacyRenderErrorPage) {
+    assert(unknownProps.length === 0)
+  }
+
+  return serialize(pageContext)
+}

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

@@ -0,0 +1,188 @@
+import { isCallable } from "../../gaurds/validators/isCallable"
+import { isObject } from "../../gaurds/validators/isObject"
+import { isReactElement } from "../../gaurds/validators/isReactElement"
+import { Path, replacerWithPath } from "./replaceWithParserPath"
+import { types } from "./stringifyTypes"
+
+export { isJsonSerializerError, stringify }
+
+function stringify(
+  value: unknown,
+  {
+    forbidReactElements,
+    space,
+    valueName,
+    sortObjectKeys,
+    // Used by reveal: https://github.com/revealjs/reveal/blob/b4ba6b70e6bdc2e1f460c0d2e4c3faae5d0a733c/reveal/node/plugin/plugins/importUserCode/v1-design/getConfigValuesSerialized.ts#L78
+    replacer: replacerUserProvided,
+  }: {
+    forbidReactElements?: boolean
+    space?: number
+    valueName?: string
+    sortObjectKeys?: boolean
+    replacer?: (
+      this: Iterable<string, unknown>,
+      key: string,
+      value: unknown
+    ) => void | { replacement: unknown }
+  } = {}
+): string {
+  // The only error `JSON.stringify()` can throw is `TypeError "cyclic object value"`.
+  // - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#exceptions
+  // - This means we have total of 3 possible errors while serializing:
+  //    - Cyclic references
+  //    - Functions
+  //    - React elements
+  const serializer = (val: unknown) =>
+    JSON.stringify(val, replacerWithPath(replacer as any), space)
+
+  return serializer(value)
+
+  function replacer(
+    this: Iterable<string, unknown>,
+    key: string,
+    value: unknown,
+    path: Path
+  ) {
+    {
+      const ret = replacerUserProvided?.call(this, key, value)
+      if (ret) return ret.replacement
+    }
+
+    if (forbidReactElements && isReactElement(value as any)) {
+      throw genErr({
+        value,
+        valueType: "React element",
+        path,
+        rootValueName: valueName,
+      })
+    }
+
+    if (isCallable(value)) {
+      const functionName = value.name
+      throw genErr({
+        value,
+        valueType: "function",
+        path,
+        rootValueName: valueName,
+        problematicValueName: path.length === 0 ? functionName : undefined,
+      })
+    }
+    //@ts-ignore
+    const valueOriginal = this[key]
+    for (const { is, serialize } of types.slice().reverse()) {
+      if (is(valueOriginal) as any) {
+        //@ts-ignore
+        return serialize(valueOriginal, serializer)
+      }
+    }
+
+    if (sortObjectKeys && isObject(value)) {
+      const copy: Record<string, unknown> = {}
+      Object.keys(value)
+        .sort()
+        .forEach((key) => {
+          copy[key] = (value as Record<string, unknown>)[key]
+        })
+      value = copy
+    }
+
+    return value
+  }
+}
+
+function genErr({
+  value,
+  valueType,
+  path,
+  rootValueName,
+  problematicValueName,
+}: {
+  value: unknown
+  valueType: ValueType
+  path: Path
+  rootValueName?: string
+  problematicValueName?: string
+}) {
+  const subjectName = getSubjectName({
+    path,
+    rootValueName,
+    problematicValueName,
+  })
+  const messageCore =
+    `cannot serialize ${subjectName} because it's a ${valueType}` as const
+  const err = new Error(
+    `[@brillout/json-serializer](https://github.com/brillout/json-serializer) ${messageCore}.`
+  )
+  const pathString = getPathString(path, true)
+  const errAddendum: ErrAddendum & { [stamp]: true } = {
+    [stamp]: true,
+    messageCore,
+    value,
+    path,
+    pathString,
+    subjectName,
+  }
+  Object.assign(err, errAddendum)
+  return err
+}
+type ErrAddendum = {
+  messageCore:
+    | `cannot serialize ${string} because it's a function`
+    | `cannot serialize ${string} because it's a React element`
+  value: unknown
+  path: Path
+  pathString: string
+  subjectName: string
+}
+const stamp = "_isJsonSerializerError"
+function isJsonSerializerError(thing: unknown): thing is Error & ErrAddendum {
+  return isObject(thing) && thing[stamp] === true
+}
+type ValueType = "React element" | "function"
+function getSubjectName({
+  path,
+  rootValueName,
+  problematicValueName,
+}: {
+  path: Path
+  rootValueName?: string
+  problematicValueName?: string
+}) {
+  const pathString = getPathString(path, !rootValueName)
+  let subjectName: string
+  if (!pathString) {
+    subjectName = rootValueName || problematicValueName || "value"
+  } else {
+    if (problematicValueName) {
+      subjectName = problematicValueName + " at "
+    } else {
+      subjectName = ""
+    }
+    subjectName = subjectName + (rootValueName || "") + pathString
+  }
+  return subjectName
+}
+
+function getPathString(path: Path, canBeFirstKey: boolean): string {
+  const pathString = path
+    .map((key, i) => {
+      if (typeof key === "number") {
+        return `[${key}]`
+      }
+      if (i === 0 && canBeFirstKey && isKeyDotNotationCompatible(key)) {
+        return key
+      }
+      return getPropAccessNotation(key)
+    })
+    .join("")
+  return pathString
+}
+function getPropAccessNotation(key: unknown): `.${string}` | `[${string}]` {
+  return typeof key === "string" && isKeyDotNotationCompatible(key)
+    ? `.${key}`
+    : `[${JSON.stringify(key)}]`
+}
+function isKeyDotNotationCompatible(key: string): boolean {
+  return /^[a-z0-9\$_]+$/i.test(key)
+}