flamefront 0.0.0 → 0.1.0-alpha.0

package/src/octane.ts

@@ -0,0 +1,654 @@
+import type {
+  AppDefinition,
+  GeneratedRouteMetadata,
+  RouteDefinition,
+} from "./index.ts"
+import type {
+  DocumentMode,
+  RouteRuntime,
+  RenderedDocument,
+  RouteRuntimeContextOptions,
+} from "./server.ts"
+import type {
+  ServerRouterOptions,
+  ServerRouterResult,
+} from "./remix-router-core.ts"
+import { stripFlamefrontProtocolRequest } from "./fragment-protocol.ts"
+import {
+  staticFragmentProtocol,
+  type StaticFragmentArtifact,
+  type StaticFragmentBoundary,
+} from "./fragment-client.ts"
+
+export type { DocumentMode, RenderedDocument } from "./server.ts"
+
+export interface RouterDocumentProps {
+  readonly router: unknown
+  readonly context: unknown
+}
+
+export type RouterDocument = (props: RouterDocumentProps) => unknown
+
+/** Framework-rendered document pieces available to the app composer. */
+export interface DocumentParts {
+  readonly template: string
+  readonly body: string
+  readonly css: string
+  readonly hydrationScript: string
+}
+
+export interface DocumentCompositionContext<
+  Route extends RouteDefinition = RouteDefinition,
+> {
+  readonly request: Request
+  readonly mode: DocumentMode
+  readonly route: Route | null
+  readonly params: Readonly<Record<string, string | undefined>>
+  readonly status: number
+}
+
+export type ComposeDocument<Route extends RouteDefinition = RouteDefinition> = (
+  parts: DocumentParts,
+  context: DocumentCompositionContext<Route>,
+) => string | Promise<string>
+
+export interface RenderDocumentOptions {
+  readonly mode?: DocumentMode
+}
+
+export interface OctaneRenderResult {
+  readonly html: string
+  readonly css: string
+}
+
+/**
+ * The renderer is injectable so document behavior can be tested without
+ * loading the compiler-only Octane and Remix Router source modules in Node.
+ */
+export interface OctaneRenderer {
+  readonly createStaticRouter: (
+    routes: readonly unknown[],
+    context: unknown,
+  ) => unknown
+  readonly renderToString: (
+    component: unknown,
+    props: RouterDocumentProps,
+  ) => OctaneRenderResult
+  /** Render one generated route boundary directly from the static router tree. */
+  readonly renderRouteFragment?: (
+    router: unknown,
+    context: unknown,
+    boundary: string,
+  ) => OctaneRenderResult
+  readonly defaultRouterDocument: RouterDocument
+}
+
+export interface DocumentRouter {
+  readonly routes: readonly unknown[]
+  readonly routeMetadata?: readonly GeneratedRouteMetadata[]
+  readonly createServerRouter: (
+    request: Request,
+    options?: ServerRouterOptions,
+  ) => Promise<Response | ServerRouterResult<unknown, unknown>>
+}
+
+export interface OctaneDocumentsOptions<
+  Context = unknown,
+  Route extends RouteDefinition = RouteDefinition,
+> {
+  readonly app: AppDefinition<Route>
+  readonly runtime: RouteRuntime<Context, Route>
+  /** Wrap the framework's default RouterProvider with app providers. */
+  readonly routerDocument?: RouterDocument
+  /** Control HTML placement while retaining framework protocol pieces. */
+  readonly composeDocument?: ComposeDocument<Route>
+  readonly router?: DocumentRouter
+  readonly renderer?: OctaneRenderer
+}
+
+export interface OctaneDocuments {
+  readonly renderDocument: (
+    template: string,
+    request: Request,
+    options?: RenderDocumentOptions,
+  ) => Promise<RenderedDocument>
+  readonly loadRouteData: (request: Request) => Promise<Response>
+  readonly renderFragment: (request: Request) => Promise<StaticFragmentArtifact>
+}
+
+interface StaticDocumentContext {
+  readonly loaderData?: Record<string, unknown>
+  readonly actionData?: Record<string, unknown> | null
+  readonly errors?: Record<string, unknown> | null
+  readonly statusCode?: number
+  readonly matches?: readonly {
+    readonly params?: Readonly<Record<string, string | undefined>>
+    readonly pathname?: string
+    readonly pathnameBase?: string
+    readonly route?: { readonly id?: string }
+  }[]
+}
+
+function isRouteErrorResponse(
+  value: unknown,
+): value is Record<string, unknown> {
+  return Boolean(
+    value &&
+    typeof value === "object" &&
+    typeof (value as { status?: unknown }).status === "number" &&
+    typeof (value as { statusText?: unknown }).statusText === "string" &&
+    typeof (value as { internal?: unknown }).internal === "boolean" &&
+    "data" in value,
+  )
+}
+
+export function serializeErrors(
+  errors: Record<string, unknown> | null | undefined,
+): Record<string, unknown> | null {
+  if (!errors) {
+    return null
+  }
+
+  const serialized: Record<string, unknown> = {}
+
+  for (const [key, value] of Object.entries(errors)) {
+    if (isRouteErrorResponse(value)) {
+      serialized[key] = { ...value, __type: "RouteErrorResponse" }
+    } else if (value instanceof Error) {
+      serialized[key] = {
+        message: value.message,
+        __type: "Error",
+        ...(value.name !== "Error" ? { __subType: value.name } : {}),
+      }
+    } else {
+      serialized[key] = value
+    }
+  }
+
+  return serialized
+}
+
+export const staticRouterHydrationScriptId =
+  "flamefront-static-router-hydration"
+
+export function staticRouterHydrationScript(
+  context: StaticDocumentContext,
+): string {
+  const data = JSON.stringify({
+    loaderData: context.loaderData,
+    actionData: context.actionData,
+    errors: serializeErrors(context.errors),
+  })
+  const escaped = JSON.stringify(data).replace(
+    /[&><\u2028\u2029]/g,
+    (character) => {
+      const escapes: Record<string, string> = {
+        "&": "\\u0026",
+        ">": "\\u003e",
+        "<": "\\u003c",
+        "
": "\\u2028",
+        "
": "\\u2029",
+      }
+
+      return escapes[character] ?? character
+    },
+  )
+
+  return `<script id="${staticRouterHydrationScriptId}">window.__staticRouterHydrationData = JSON.parse(${escaped});</script>`
+}
+
+export function composeDefaultDocument(
+  template: string,
+  body: string,
+  css: string,
+  hydrationScript: string,
+): string {
+  const root = '<div id="root"></div>'
+
+  if (!template.includes(root)) {
+    throw new Error(
+      'The HTML shell must contain an empty <div id="root"></div>.',
+    )
+  }
+
+  return template
+    .replace(root, `<div id="root">${body}</div>`)
+    .replace("</head>", `${css}</head>`)
+    .replace("</body>", `${hydrationScript}</body>`)
+}
+
+async function loadDefaultRouter(): Promise<DocumentRouter> {
+  const module = await import("./remix-router.ts")
+
+  return {
+    routes: module.routes,
+    routeMetadata: module.routeMetadata,
+    createServerRouter: module.createServerRouter,
+  }
+}
+
+async function loadDefaultRenderer(): Promise<OctaneRenderer> {
+  const [remix, routerDocument, octane, fragment] = await Promise.all([
+    import("@octanejs/remix-router"),
+    import("./octane-router-document.ts"),
+    import("octane/server"),
+    import("./fragment.ts"),
+  ])
+
+  const createStaticNavigator = (router: {
+    readonly createHref: (to: unknown) => string
+    readonly encodeLocation: (to: unknown) => unknown
+  }) => ({
+    createHref: router.createHref,
+    encodeLocation: router.encodeLocation,
+    push() {
+      throw new Error(
+        "Static fragment rendering cannot navigate on the server.",
+      )
+    },
+    replace() {
+      throw new Error(
+        "Static fragment rendering cannot navigate on the server.",
+      )
+    },
+    go() {
+      throw new Error(
+        "Static fragment rendering cannot navigate on the server.",
+      )
+    },
+    back() {
+      throw new Error(
+        "Static fragment rendering cannot navigate on the server.",
+      )
+    },
+    forward() {
+      throw new Error(
+        "Static fragment rendering cannot navigate on the server.",
+      )
+    },
+  })
+
+  return {
+    createStaticRouter: (routes, context) =>
+      remix.createStaticRouter(routes as any[], context as any),
+    renderToString: (component, props) =>
+      octane.renderToString(component as never, props as never),
+    renderRouteFragment: (router, context, boundary) => {
+      const dataRouter = router as {
+        readonly state: {
+          readonly location: unknown
+          readonly matches: readonly {
+            readonly route?: { readonly id?: string }
+          }[]
+        }
+        readonly createHref: (to: unknown) => string
+        readonly encodeLocation: (to: unknown) => unknown
+      }
+      const staticContext = context as { readonly basename?: string }
+      const state = dataRouter.state
+      const matchIndex = state.matches.findIndex(
+        (match) => match.route?.id === boundary,
+      )
+
+      if (matchIndex < 0) {
+        throw new Error(
+          `No static router match exists for fragment boundary ${JSON.stringify(boundary)}.`,
+        )
+      }
+
+      const navigator = createStaticNavigator(dataRouter)
+      const dataRouterContext = {
+        router: dataRouter,
+        navigator,
+        static: true,
+        staticContext: context,
+        basename: staticContext.basename ?? "/",
+      }
+      const fragmentTree = remix.renderMatches(
+        state.matches.slice(matchIndex) as never,
+      )
+      const fragmentRoot = octane.createElement(
+        remix.UNSAFE_DataRouterContext.Provider as never,
+        {
+          value: dataRouterContext,
+          children: octane.createElement(
+            remix.UNSAFE_DataRouterStateContext.Provider as never,
+            {
+              value: state,
+              children: octane.createElement(
+                remix.UNSAFE_FetchersContext.Provider as never,
+                {
+                  value: new Map(),
+                  children: octane.createElement(
+                    remix.UNSAFE_ViewTransitionContext.Provider as never,
+                    {
+                      value: { isTransitioning: false },
+                      children: octane.createElement(
+                        remix.StaticRouter as never,
+                        {
+                          basename: staticContext.basename ?? "/",
+                          location: state.location,
+                          children: octane.createElement(
+                            fragment.staticFragmentBoundaryTarget
+                              .Provider as never,
+                            { value: boundary, children: fragmentTree },
+                          ),
+                        },
+                      ),
+                    },
+                  ),
+                },
+              ),
+            },
+          ),
+        },
+      )
+      const FragmentRoot = () => fragmentRoot
+
+      return octane.renderToString(FragmentRoot, {})
+    },
+    defaultRouterDocument: routerDocument.RouterDocument,
+  }
+}
+
+function createShellRouter(
+  request: Request,
+  app: AppDefinition,
+  routeGraph: readonly unknown[],
+  renderer: OctaneRenderer,
+): { readonly context: StaticDocumentContext; readonly router: unknown } {
+  const url = new URL(request.url)
+  const rootRoute =
+    routeGraph[0] && typeof routeGraph[0] === "object" ? routeGraph[0] : {}
+  const context: StaticDocumentContext & {
+    readonly basename: string
+    readonly location: Record<string, unknown>
+  } = {
+    basename: app.routing.basename,
+    location: {
+      pathname: url.pathname,
+      search: url.search,
+      hash: url.hash,
+      state: null,
+      key: "default",
+    },
+    matches: [
+      {
+        params: {},
+        pathname: "",
+        pathnameBase: app.routing.basename,
+        route: { ...rootRoute, id: "0" },
+      },
+    ],
+    loaderData: {},
+    actionData: null,
+    errors: null,
+    statusCode: 200,
+  }
+
+  return {
+    context,
+    router: renderer.createStaticRouter(routeGraph, context),
+  }
+}
+
+function resolveDocumentMode(
+  request: Request,
+  mode: DocumentMode | undefined,
+  route: RouteDefinition | null,
+): DocumentMode {
+  if (mode) {
+    return mode
+  }
+
+  if (new URL(request.url).searchParams.has("__flamefront_shell")) {
+    return "shell"
+  }
+
+  if (!route) {
+    throw new Response("Not found", { status: 404 })
+  }
+
+  return route.render
+}
+
+function assertRouteMode(
+  route: RouteDefinition | null,
+  mode: DocumentMode,
+): void {
+  if (mode === "shell") {
+    return
+  }
+
+  if (!route || route.render !== mode) {
+    throw new Response("Not found", { status: 404 })
+  }
+}
+
+function routeData(context: StaticDocumentContext): unknown {
+  const leaf = context.matches?.at(-1)
+  const routeId = leaf?.route?.id
+
+  return routeId ? (context.loaderData?.[routeId] ?? null) : null
+}
+
+function fragmentMetadataChain(
+  route: RouteDefinition,
+  metadata: readonly GeneratedRouteMetadata[] | undefined,
+): GeneratedRouteMetadata[] {
+  const leaf = metadata?.find(
+    (item) =>
+      item.kind === "route" &&
+      item.entry === route.entry &&
+      (item.path === route.path || item.path === undefined),
+  )
+
+  if (!leaf) {
+    return [
+      {
+        id: route.entry,
+        boundary: route.entry,
+        kind: "route",
+        entry: route.entry,
+        path: route.path,
+        render: route.render,
+        navigation: "fragment",
+        hydration: route.hydration,
+      },
+    ]
+  }
+
+  const byId = new Map((metadata ?? []).map((item) => [item.id, item]))
+  const chain: GeneratedRouteMetadata[] = []
+  let current: GeneratedRouteMetadata | undefined = leaf
+
+  while (current) {
+    chain.unshift(current)
+    current = current.parent ? byId.get(current.parent) : undefined
+  }
+
+  return chain
+}
+
+function createStaticFragmentArtifact(
+  route: RouteDefinition,
+  context: StaticDocumentContext,
+  router: unknown,
+  renderer: OctaneRenderer,
+  fallbackBody: string,
+  metadata: readonly GeneratedRouteMetadata[] | undefined,
+): StaticFragmentArtifact {
+  const chain = fragmentMetadataChain(route, metadata)
+  const boundaries: StaticFragmentBoundary[] = chain.map((item) => {
+    const rendered = renderer.renderRouteFragment?.(
+      router,
+      context,
+      item.boundary,
+    )
+
+    return {
+      id: item.id,
+      boundary: item.boundary,
+      kind: item.kind,
+      ...(item.parent ? { parent: item.parent } : {}),
+      html: rendered?.html ?? (item === chain.at(-1) ? fallbackBody : ""),
+    }
+  })
+  const fragmentHtml = boundaries.at(-1)?.html || fallbackBody
+
+  return {
+    protocol: staticFragmentProtocol,
+    route: route.path,
+    boundary: chain.at(-1)?.boundary ?? route.entry,
+    html: fragmentHtml,
+    routeData: routeData(context),
+    boundaries,
+    hydration: route.hydration,
+    status: context.statusCode ?? 200,
+  }
+}
+
+export function createOctaneDocuments<
+  Context = unknown,
+  Route extends RouteDefinition = RouteDefinition,
+>(options: OctaneDocumentsOptions<Context, Route>): OctaneDocuments {
+  let routerPromise: Promise<DocumentRouter> | undefined
+  let rendererPromise: Promise<OctaneRenderer> | undefined
+
+  const getRouter = (): Promise<DocumentRouter> => {
+    if (options.router) {
+      return Promise.resolve(options.router)
+    }
+
+    return (routerPromise ??= loadDefaultRouter())
+  }
+
+  const getRenderer = (): Promise<OctaneRenderer> => {
+    if (options.renderer) {
+      return Promise.resolve(options.renderer)
+    }
+
+    return (rendererPromise ??= loadDefaultRenderer())
+  }
+
+  const renderRoute = async (
+    request: Request,
+    mode: DocumentMode,
+  ): Promise<{
+    readonly router: DocumentRouter
+    readonly dataRouter: unknown
+    readonly renderer: OctaneRenderer
+    readonly context: StaticDocumentContext
+    readonly rendered: OctaneRenderResult
+  }> => {
+    const contextOptions: RouteRuntimeContextOptions = {
+      purpose: "document",
+      mode,
+    }
+    const requestContext = await options.runtime.createRequestContext(
+      request,
+      contextOptions,
+    )
+    const [router, renderer] = await Promise.all([getRouter(), getRenderer()])
+    const routerDocument =
+      options.routerDocument ?? renderer.defaultRouterDocument
+    const result =
+      mode === "shell" || mode === "client"
+        ? createShellRouter(request, options.app, router.routes, renderer)
+        : await router.createServerRouter(request, {
+            basename: options.app.routing.basename,
+            requestContext,
+          })
+
+    if (result instanceof Response) {
+      throw result
+    }
+
+    const context = result.context as StaticDocumentContext
+
+    return {
+      router,
+      dataRouter: result.router,
+      renderer,
+      context,
+      rendered: renderer.renderToString(routerDocument, {
+        router: result.router,
+        context: result.context,
+      }),
+    }
+  }
+
+  const renderDocument = async (
+    template: string,
+    request: Request,
+    renderOptions: RenderDocumentOptions = {},
+  ): Promise<RenderedDocument> => {
+    const sanitizedRequest = stripFlamefrontProtocolRequest(request)
+    const routeMatch = options.app.match(sanitizedRequest.url)
+    const route = routeMatch?.data ?? null
+    const mode = resolveDocumentMode(request, renderOptions.mode, route)
+
+    assertRouteMode(route, mode)
+    const { context: staticContext, rendered } = await renderRoute(
+      sanitizedRequest,
+      mode,
+    )
+    const status = staticContext.statusCode ?? 200
+    const compositionContext: DocumentCompositionContext<Route> = {
+      request: sanitizedRequest,
+      mode,
+      route,
+      params: routeMatch?.params ?? {},
+      status,
+    }
+    const parts: DocumentParts = {
+      template,
+      body: rendered.html,
+      css: rendered.css,
+      hydrationScript: staticRouterHydrationScript(staticContext),
+    }
+    const html = await (options.composeDocument
+      ? options.composeDocument(parts, compositionContext)
+      : composeDefaultDocument(
+          parts.template,
+          parts.body,
+          parts.css,
+          parts.hydrationScript,
+        ))
+
+    return mode === "static"
+      ? { html, routeData: routeData(staticContext), status }
+      : { html, status }
+  }
+
+  const renderFragment = async (
+    request: Request,
+  ): Promise<StaticFragmentArtifact> => {
+    const sanitizedRequest = stripFlamefrontProtocolRequest(request)
+    const routeMatch = options.app.match(sanitizedRequest.url)
+    const route = routeMatch?.data ?? null
+
+    assertRouteMode(route, "static")
+    if (!route) {
+      throw new Response("Not found", { status: 404 })
+    }
+
+    const { router, dataRouter, renderer, rendered, context } =
+      await renderRoute(sanitizedRequest, "static")
+
+    return createStaticFragmentArtifact(
+      route,
+      context,
+      dataRouter,
+      renderer,
+      rendered.html,
+      router.routeMetadata,
+    )
+  }
+
+  return {
+    renderDocument,
+    loadRouteData: options.runtime.loadRouteData,
+    renderFragment,
+  }
+}

package/src/remix-route-data.ts

@@ -0,0 +1,68 @@
+import {
+  createRouteDataClient,
+  type RouteDataLoadOptions,
+  type RouteDataRoutingOptions,
+} from "./route-data-client.ts"
+import {
+  loadStaticFragment,
+  type StaticFragmentLoadOptions,
+  type StaticFragmentRoutingOptions,
+} from "./fragment-client.ts"
+
+export {
+  createRouteDataClient,
+  type RouteDataClient,
+  type RouteDataLoadOptions,
+  type RouteDataRoutingOptions,
+  type RouteDataSource,
+} from "./route-data-client.ts"
+
+export interface ClientLoaderArgs {
+  readonly request: Request
+}
+
+export interface RouteDataOptions {
+  readonly basename?: string
+  readonly dataPath?: string
+}
+
+function client(options: RouteDataOptions) {
+  return createRouteDataClient(options satisfies RouteDataRoutingOptions)
+}
+
+/** Load route data through Flamefront's server endpoint during browser navigation. */
+export async function loadRouteData(
+  { request }: ClientLoaderArgs,
+  options: RouteDataOptions = {},
+): Promise<unknown> {
+  const loadOptions: RouteDataLoadOptions = { signal: request.signal }
+
+  return client(options).load(request.url, "live", loadOptions)
+}
+
+/** Load a build-time static route artifact during browser navigation. */
+export async function loadStaticRouteData(
+  { request }: ClientLoaderArgs,
+  options: RouteDataOptions = {},
+): Promise<unknown> {
+  const loadOptions: RouteDataLoadOptions = { signal: request.signal }
+
+  return client(options).load(request.url, "static", loadOptions)
+}
+
+/** Load a static fragment and expose only its route data to the router. */
+export async function loadStaticRouteFragment(
+  { request }: ClientLoaderArgs,
+  options: RouteDataOptions = {},
+): Promise<unknown> {
+  const fragmentOptions: StaticFragmentLoadOptions = {
+    signal: request.signal,
+  }
+  const artifact = await loadStaticFragment(
+    request.url,
+    options satisfies StaticFragmentRoutingOptions,
+    fragmentOptions,
+  )
+
+  return artifact.routeData
+}