@revealui/core 0.0.1-pre.0

package/dist/core/processing/getters/getRevealConfig/configDefinitionsBuiltIn.ts

@@ -0,0 +1,711 @@
+export { configDefinitionsBuiltIn, configDefinitionsBuiltInGlobal }
+export type {
+  ConfigDefinition,
+  ConfigDefinitionInternal,
+  ConfigDefinitions,
+  ConfigEffect,
+  ConfigNameGlobal,
+}
+
+import { assert, assertUsage } from "../../../../plugins/utils.js"
+import type {
+  Config,
+  ConfigNameBuiltIn,
+} from "../../../../types/interfaces/config.js"
+import type {
+  ConfigEnv,
+  ConfigEnvInternal,
+  ConfigValueSource,
+  ConfigValueSources,
+  DefinedAtFilePath,
+} from "../../../../types/interfaces/page.js"
+import {
+  getConfigDefinedAt,
+  type ConfigDefinedAt,
+} from "../getConfigDefinedAt.js"
+
+// For users
+/** The meta definition of a config.
+ *
+ * https://reveal.dev/meta
+ */
+type ConfigDefinition = {
+  /** In what environment(s) the config value is loaded.
+   *
+   * https://reveal.dev/meta
+   */
+  env: ConfigEnv
+  /** Disable config overriding and make config values cumulative instead.
+   *
+   * @default false
+   *
+   * https://reveal.dev/meta
+   */
+  cumulative?: boolean
+  /**
+   * Function called when the config value is defined.
+   *
+   * https://reveal.dev/meta
+   */
+  effect?: ConfigEffect
+  /**
+   * Always load the configuration value, and as soon as possible.
+   *
+   * @default false
+   *
+   * https://reveal.dev/meta
+   */
+  eager?: boolean
+  // TODO/soon: use `global` internally and remove configDefinitionsBuiltInGlobal
+  /**
+   * Whether the configuration always applies to all pages (no config inheritance).
+   *
+   * @default false
+   *
+   * https://reveal.dev/extends#inheritance
+   */
+  global?: boolean
+}
+
+/**
+ * Function called when the config value is defined.
+ *
+ * https://reveal.dev/meta
+ */
+type ConfigEffect = (config: {
+  /** The config value.
+   *
+   * https://reveal.dev/meta
+   */
+  configValue: unknown
+  /** Where the config value is defined.
+   *
+   * https://reveal.dev/meta
+   */
+  configDefinedAt: ConfigDefinedAt
+}) => Config | undefined
+
+/** For Reveal internal use */
+type ConfigDefinitionInternal = Omit<ConfigDefinition, "env"> & {
+  _computed?: (configValueSources: ConfigValueSources) => unknown
+  _valueIsFilePath?: true
+  _userEffectDefinedAtFilePath?: DefinedAtFilePath
+  env: ConfigEnvInternal
+}
+
+type ConfigDefinitions = Record<
+  string, // configName
+  ConfigDefinitionInternal
+>
+type ConfigDefinitionsBuiltIn = Record<
+  ConfigNameBuiltIn,
+  ConfigDefinitionInternal
+>
+
+type ConfigNameGlobal =
+  | "onPrerenderStart"
+  | "onBeforeRoute"
+  | "prerender"
+  | "disableAutoFullBuild"
+  | "includeAssetsImportedByServer"
+  | "baseAssets"
+  | "baseServer"
+  | "redirects"
+  | "trailingSlash"
+  | "disableUrlNormalization"
+const configDefinitionsBuiltInGlobal: Record<
+  ConfigNameGlobal,
+  ConfigDefinitionInternal
+> = {
+  onPrerenderStart: {
+    env: { server: true, production: true },
+    eager: true,
+  },
+  onBeforeRoute: {
+    env: { server: true, client: "if-client-routing" },
+    eager: true,
+  },
+  prerender: {
+    env: { config: true },
+  },
+  disableAutoFullBuild: { env: { config: true } },
+  includeAssetsImportedByServer: { env: { config: true } },
+  baseAssets: { env: { config: true } },
+  baseServer: { env: { config: true } },
+  redirects: { env: { server: true } },
+  trailingSlash: { env: { server: true } },
+  disableUrlNormalization: { env: { server: true } },
+}
+
+function getConfigEnv(
+  configValueSources: ConfigValueSources,
+  configName: string
+): null | ConfigEnvInternal {
+  const configValueSource = getConfigValueSource(configValueSources, configName)
+  if (!configValueSource) return null
+  const { configEnv } = configValueSource
+  const env: { client?: true; server?: true } = {}
+  if (configEnv.client) env.client = true
+  if (configEnv.server) env.server = true
+  return env
+}
+function isConfigSet(
+  configValueSources: ConfigValueSources,
+  configName: string
+): boolean {
+  const configValueSource = getConfigValueSource(configValueSources, configName)
+  // Enable users to suppress global config values by overriding the config's value to null
+  if (configValueSource?.value === null) return false
+  return !!configValueSource
+}
+function getConfigValueSource(
+  configValueSources: ConfigValueSources,
+  configName: string
+): null | ConfigValueSource {
+  const sources = configValueSources[configName]
+  if (!sources) return null
+  const configValueSource = sources[0]
+  assert(configValueSource)
+  return configValueSource
+}
+
+const configDefinitionsBuiltIn: ConfigDefinitionsBuiltIn = {
+  onRenderHtml: {
+    env: { server: true },
+  },
+  onRenderClient: {
+    env: { client: true },
+  },
+  onHydrationEnd: {
+    env: { client: true },
+  },
+  onPageTransitionStart: {
+    env: { client: true },
+  },
+  onPageTransitionEnd: {
+    env: { client: true },
+  },
+  onBeforeRender: {
+    env: { server: true },
+  },
+  onBeforePrerenderStart: {
+    env: { server: true, production: true },
+  },
+  Page: {
+    env: { server: true, client: true },
+  },
+  // passToClient: {
+  //   env: {client: true},
+  // },
+  // Head: {
+  //   env: {client: true},
+  // },
+  // Layout: {
+  //   env: {server: true,client: true},
+  // },
+  // Wrapper: {
+  //   env: {client: true},
+  // },
+  // title: {
+  //   env: {server: true,client: true},
+  // },
+  // description: {
+  //   env: {server: true},
+  // },
+  // keywords: {
+  //   env: { server: true, client: true },
+  // },
+  // author: {
+  //   env: { server: true },
+  // },
+  // viewport: {
+  //   env: {client: true},
+  // },
+  // ogImage: {
+  //   env: { server: true },
+  // },
+  // twitterCard: {
+  //   env: { server: true, client: true },
+  // },
+  // twitterSite: {
+  //   env: { client: true },
+  // },
+  // twitterCreator: {
+  //   env: { server: true },
+  // },
+  // icons: {
+  //   env: { client: true },
+  // },
+  // themeColor: {
+  keepScrollPosition: {
+    env: { client: true },
+  },
+  // route: {
+  //   env: { client: true } // Add the required 'env' property
+  // },
+  // guard: {
+  //   env: { client: true }, // Assuming `env` should be included
+  // },
+  // prerender: { env: { client: true } },
+  // extends: { env: { client: true } },
+  // data: { env: { client: true } },
+  // iKnowThePerformanceRisksOfAsyncRouteFunctions: { env: { client: true } },
+  filesystemRoutingRoot: { env: { client: true } },
+  // hydrationCanBeAborted: { env: { client: true } },
+  client: { env: { client: true } },
+  clientRouting: { env: { client: true } },
+  // clientHooks: { env: { client: true } },
+  // meta: { env: { client: true } },
+  // prefetch: { env: { client: true } },
+  prefetchStaticAssets: { env: { client: true } },
+  // hooksTimeout: { env: { client: true } },
+  // cacheControl: { env: { client: true } },
+  // injectScriptsAt: { env: { client: true } },
+  name: { env: { client: true } },
+  require: { env: { client: true } },
+  // image: { env: { client: true } },
+  // favicon: { env: { client: true } },
+  // lang: { env: { client: true } },
+  // bodyHtmlBegin: { env: { client: true } },
+  // bodyHtmlEnd: { env: { client: true } },
+  // htmlAttributes: { env: { client: true } },
+  // bodyAttributes: { env: { client: true } },
+  // ssr: { env: { client: true } },
+  // stream: { env: { client: true } },
+  // streamIsRequired: { env: { client: true } },
+  // reactStrictMode: { env: { client: true } },
+  // onAfterRenderHtml: { env: { client: true } },
+  // onBeforeRenderClient: { env: { client: true } },
+  // onAfterRenderClient: { env: { client: true } },
+  // Loading: { env: { client: true } },
+  // isClientRuntimeLoaded: { env: { client: true } },
+  // onBeforeRenderEnv: { env: { client: true } },
+  // dataEnv: { env: { client: true } },
+  // onRenderHtml: {
+  //   env: { server: true },
+  // },
+  // onRenderClient: {
+  //   env: { client: true },
+  // },
+  // onHydrationEnd: {
+  //   env: { client: true },
+  // },
+  // onPageTransitionStart: {
+  //   env: { client: true },
+  // },
+  // onPageTransitionEnd: {
+  //   env: { client: true },
+  // },
+  // onBeforeRender: {
+  //   env: { server: true },
+  // },
+  // onBeforePrerenderStart: {
+  //   env: { server: true, production: true },
+  // },
+  // Page: {
+  //   env: { server: true, client: true },
+  // },
+  passToClient: {
+    env: { server: true },
+    cumulative: true,
+  },
+  route: {
+    env: { server: true, client: "if-client-routing" },
+    eager: true,
+  },
+  guard: {
+    env: { server: true, client: "if-client-routing" },
+  },
+  data: {
+    env: { server: true },
+  },
+  iKnowThePerformanceRisksOfAsyncRouteFunctions: {
+    env: { server: true, client: "if-client-routing" },
+    eager: true,
+  },
+  // filesystemRoutingRoot: {
+  //   env: { config: true },
+  // },
+  // client: {
+  //   // The value of the client config is merely the file path to the client entry file, which is only needed on the sever-side
+  //   env: { server: true, config: true },
+  //   _valueIsFilePath: true,
+  // },
+  // clientRouting: {
+  //   // We could make it { client: false } but we don't yet because of some legacy V0.4 design code
+  //   env: { server: true, client: true, config: true },
+  //   eager: true,
+  // },
+  clientHooks: {
+    env: { config: true },
+  },
+  prerender: {
+    env: { config: true },
+  },
+  hydrationCanBeAborted: {
+    env: { client: true },
+  },
+  prefetch: {
+    env: { client: true },
+    eager: true,
+  },
+
+  extends: {
+    env: { config: true },
+  },
+  meta: {
+    env: { config: true },
+  },
+  // Whether the page loads:
+  //  - reveal's client runtime
+  //  - User's client hooks
+  // In other words, whether the page is "HTML-only" (https://reveal.dev/render-modes). HTML-only pages shouldn't load the client runtime nor client hooks.
+  isClientRuntimeLoaded: {
+    env: { server: true, client: true },
+    eager: true,
+    _computed: (configValueSources): boolean => {
+      {
+        const source = getConfigValueSource(configValueSources, "clientHooks")
+        if (source && source.value !== null) {
+          const { value } = source
+          const definedAt = getConfigDefinedAt(
+            "Config",
+            "clientHooks",
+            source.definedAtFilePath
+          )
+          assertUsage(
+            typeof value === "boolean",
+            `${definedAt} should be a boolean`
+          )
+          return value
+        }
+      }
+      return (
+        isConfigSet(configValueSources, "onRenderClient") &&
+        isConfigSet(configValueSources, "Page") &&
+        !!getConfigEnv(configValueSources, "Page")?.client
+      )
+    },
+  },
+  onBeforeRenderEnv: {
+    env: { client: true },
+    eager: true,
+    _computed: (configValueSources): null | ConfigEnvInternal =>
+      !isConfigSet(configValueSources, "onBeforeRender")
+        ? null
+        : getConfigEnv(configValueSources, "onBeforeRender"),
+  },
+  dataEnv: {
+    env: { client: true },
+    eager: true,
+    _computed: (configValueSources): null | ConfigEnvInternal =>
+      !isConfigSet(configValueSources, "data")
+        ? null
+        : getConfigEnv(configValueSources, "data"),
+  },
+  hooksTimeout: {
+    env: { server: true, client: true },
+  },
+  cacheControl: {
+    env: { server: true },
+  },
+  injectScriptsAt: {
+    env: { server: true },
+  },
+  ssr: {
+    env: { server: true },
+  },
+  Head: {
+    env: { server: true },
+  },
+  Layout: {
+    env: { server: true },
+  },
+  Wrapper: {
+    env: { server: true },
+  },
+  title: {
+    env: { server: true },
+  },
+  description: {
+    env: { server: true },
+  },
+  image: {
+    env: { server: true },
+  },
+  viewport: {
+    env: { server: true },
+  },
+  favicon: {
+    env: { server: true },
+  },
+  lang: {
+    env: { server: true },
+  },
+  bodyHtmlBegin: {
+    env: { server: true },
+  },
+  bodyHtmlEnd: {
+    env: { server: true },
+  },
+  htmlAttributes: {
+    env: { server: true },
+  },
+  bodyAttributes: {
+    env: { server: true },
+  },
+  stream: {
+    env: { server: true },
+  },
+  streamIsRequired: {
+    env: { server: true },
+  },
+  reactStrictMode: {
+    env: { server: true },
+  },
+  onAfterRenderHtml: {
+    env: { server: true },
+  },
+  onBeforeRenderClient: {
+    env: { server: true },
+  },
+  onAfterRenderClient: {
+    env: { server: true },
+  },
+  Loading: {
+    env: { server: true },
+  },
+}
+
+// Adding the missing placeholder properties
+// stream: {
+//   env: { server: true, client: true },
+// },
+// ssr: {
+//   env: { server: true },
+// },
+// viewport: {
+//   env: { client: true },
+// },
+// image: {
+//   env: { server: true, client: true },
+// },
+// fonts: {
+//   env: { client: true },
+// },
+
+// const configDefinitionsBuiltIn: ConfigDefinitionsBuiltIn = {
+// onRenderHtml: {
+//   env: { server: true },
+// },
+// onRenderClient: {
+//   env: { client: true },
+// },
+// onHydrationEnd: {
+//   env: { client: true },
+// },
+// onPageTransitionStart: {
+//   env: { client: true },
+// },
+// onPageTransitionEnd: {
+//   env: { client: true },
+// },
+// onBeforeRender: {
+//   env: { server: true },
+// },
+// onBeforePrerenderStart: {
+//   env: { server: true, production: true },
+// },
+// Page: {
+//   env: { server: true, client: true },
+// },
+// passToClient: {
+//   env: { server: true },
+//   cumulative: true,
+// },
+// route: {
+//   env: { server: true, client: "if-client-routing" },
+//   eager: true,
+// },
+// guard: {
+//   env: { server: true, client: "if-client-routing" },
+// },
+// data: {
+//   env: { server: true },
+// },
+// iKnowThePerformanceRisksOfAsyncRouteFunctions: {
+//   env: { server: true, client: "if-client-routing" },
+//   eager: true,
+// },
+// filesystemRoutingRoot: {
+//   env: { config: true },
+// },
+// client: {
+//   // The value of the client config is merely the file path to the client entry file, which is only needed on the sever-side
+//   env: { server: true, config: true },
+//   _valueIsFilePath: true,
+// },
+// clientRouting: {
+//   // We could make it { client: false } but we don't yet because of some legacy V0.4 design code
+//   env: { server: true, client: true, config: true },
+//   eager: true,
+// },
+// clientHooks: {
+//   env: { config: true },
+// },
+// prerender: {
+//   env: { config: true },
+// },
+// hydrationCanBeAborted: {
+//   env: { client: true },
+// },
+// prefetch: {
+//   env: { client: true },
+//   eager: true,
+// },
+
+// extends: {
+//   env: { config: true },
+// },
+// meta: {
+//   env: { config: true },
+// },
+// // Whether the page loads:
+// //  - reveal's client runtime
+// //  - User's client hooks
+// // In other words, whether the page is "HTML-only" (https://reveal.dev/render-modes). HTML-only pages shouldn't load the client runtime nor client hooks.
+// isClientRuntimeLoaded: {
+//   env: { server: true, client: true },
+//   eager: true,
+//   _computed: (configValueSources): boolean => {
+//     {
+//       const source = getConfigValueSource(configValueSources, "clientHooks");
+//       if (source && source.value !== null) {
+//         const { value } = source;
+//         const definedAt = getConfigDefinedAt(
+//           "Config",
+//           "clientHooks",
+//           source.definedAtFilePath,
+//         );
+//         assertUsage(
+//           typeof value === "boolean",
+//           `${definedAt} should be a boolean`,
+//         );
+//         return value;
+//       }
+//     }
+//     return (
+//       isConfigSet(configValueSources, "onRenderClient") &&
+//       isConfigSet(configValueSources, "Page") &&
+//       !!getConfigEnv(configValueSources, "Page")?.client
+//     );
+//   },
+// },
+// onBeforeRenderEnv: {
+//   env: { client: true },
+//   eager: true,
+//   _computed: (configValueSources): null | ConfigEnvInternal =>
+//     !isConfigSet(configValueSources, "onBeforeRender")
+//       ? null
+//       : getConfigEnv(configValueSources, "onBeforeRender"),
+// },
+// dataEnv: {
+//   env: { client: true },
+//   eager: true,
+//   _computed: (configValueSources): null | ConfigEnvInternal =>
+//     !isConfigSet(configValueSources, "data")
+//       ? null
+//       : getConfigEnv(configValueSources, "data"),
+// },
+// hooksTimeout: {
+//   env: { server: true, client: true },
+// },
+// cacheControl: {
+//   env: { server: true },
+// },
+// injectScriptsAt: {
+//   env: { server: true },
+// },
+//   name: {
+//     env: { config: true },
+//   },
+//   require: {
+//     env: { config: true },
+//   },
+//   keepScrollPosition: {
+//     env: { client: true },
+//   },
+// };
+
+// type ConfigNameGlobal =
+//   | "onPrerenderStart"
+//   | "onBeforeRoute"
+//   | "prerender"
+//   | "disableAutoFullBuild"
+//   | "includeAssetsImportedByServer"
+//   | "baseAssets"
+//   | "baseServer"
+//   | "redirects"
+//   | "trailingSlash"
+//   | "disableUrlNormalization";
+// const configDefinitionsBuiltInGlobal: Record<
+//   ConfigNameGlobal,
+//   ConfigDefinitionInternal
+// > = {
+//   onPrerenderStart: {
+//     env: { server: true, production: true },
+//     eager: true,
+//   },
+//   onBeforeRoute: {
+//     env: { server: true, client: "if-client-routing" },
+//     eager: true,
+//   },
+//   prerender: {
+//     env: { config: true },
+//   },
+//   disableAutoFullBuild: { env: { config: true } },
+//   includeAssetsImportedByServer: { env: { config: true } },
+//   baseAssets: { env: { config: true } },
+//   baseServer: { env: { config: true } },
+//   redirects: { env: { server: true } },
+//   trailingSlash: { env: { server: true } },
+//   disableUrlNormalization: { env: { server: true } },
+// };
+
+// function getConfigEnv(
+//   configValueSources: ConfigValueSources,
+//   configName: string,
+// ): null | ConfigEnvInternal {
+//   const configValueSource = getConfigValueSource(
+//     configValueSources,
+//     configName,
+//   );
+//   if (!configValueSource) return null;
+//   const { configEnv } = configValueSource;
+//   const env: { client?: true; server?: true } = {};
+//   if (configEnv.client) env.client = true;
+//   if (configEnv.server) env.server = true;
+//   return env;
+// }
+// function isConfigSet(
+//   configValueSources: ConfigValueSources,
+//   configName: string,
+// ): boolean {
+//   const configValueSource = getConfigValueSource(
+//     configValueSources,
+//     configName,
+//   );
+//   // Enable users to suppress global config values by overriding the config's value to null
+//   if (configValueSource?.value === null) return false;
+//   return !!configValueSource;
+// }
+// function getConfigValueSource(
+//   configValueSources: ConfigValueSources,
+//   configName: string,
+// ): null | ConfigValueSource {
+//   const sources = configValueSources[configName];
+//   if (!sources) return null;
+//   const configValueSource = sources[0];
+//   assert(configValueSource);
+//   return configValueSource;
+// }