flamefront 0.1.0-alpha.0 → 0.1.1

package/src/fragment-client.ts

@@ -1,17 +1,14 @@
-import type {
-  GeneratedHydration,
-  GeneratedRouteMetadata,
-  HydrationMode,
-  RouteBoundaryKind,
-} from "./index.ts"
+import type { HydrationMode, RouteBoundaryKind } from "./index.ts"
 import {
   stripFlamefrontProtocolParams,
-  withStaticFragmentProtocol,
+  withRouteFragmentProtocol,
 } from "./fragment-protocol.ts"
 
-export const staticFragmentProtocol = "flamefront-static-fragment-v1" as const
+export const routeFragmentProtocol = "flamefront-route-fragment-v1" as const
+
+export type RouteFragmentCachePolicy = "server" | "static"
 
-export interface StaticFragmentBoundary {
+export interface RouteFragmentBoundary {
   readonly id: string
   readonly boundary: string
   readonly kind: RouteBoundaryKind
@@ -19,33 +16,36 @@ export interface StaticFragmentBoundary {
   readonly html: string
 }
 
-export interface StaticFragmentArtifact {
-  readonly protocol: typeof staticFragmentProtocol
+export interface RouteFragmentArtifact {
+  readonly protocol: typeof routeFragmentProtocol
   readonly route: string
   readonly boundary: string
   readonly html: string
   readonly routeData: unknown
-  readonly boundaries: readonly StaticFragmentBoundary[]
+  readonly boundaries: readonly RouteFragmentBoundary[]
   readonly hydration?: HydrationMode
   readonly status?: number
 }
 
-export interface StaticFragmentLoadOptions {
+export interface RouteFragmentLoadOptions {
+  readonly policy: RouteFragmentCachePolicy
   readonly signal?: AbortSignal
   readonly reload?: boolean
 }
 
-export interface StaticFragmentRoutingOptions {
+export interface RouteFragmentRoutingOptions {
   readonly basename?: string
 }
 
-export function shouldHydrateStaticFragment(
+export function shouldHydrateRouteFragment(
   hydration: HydrationMode | undefined,
 ): boolean {
   return hydration !== "none"
 }
 
-const fragmentCache = new Map<string, Promise<StaticFragmentArtifact>>()
+const staticFragmentRequests = new Map<string, Promise<RouteFragmentArtifact>>()
+const serverFragmentRequests = new Map<string, Promise<RouteFragmentArtifact>>()
+const latestRouteFragments = new Map<string, RouteFragmentArtifact>()
 
 function resolveRouteUrl(input: string | URL): URL {
   const browserOrigin =
@@ -53,11 +53,11 @@ function resolveRouteUrl(input: string | URL): URL {
 
   if (!browserOrigin && typeof input === "string" && !URL.canParse(input)) {
     throw new TypeError(
-      "flamefront static fragments require an absolute URL outside the browser.",
+      "flamefront route fragments require an absolute URL outside the browser.",
     )
   }
 
-  return new URL(input, browserOrigin)
+  return stripFlamefrontProtocolParams(new URL(input, browserOrigin))
 }
 
 function basenamePath(pathname: string, basename: string): string | null {
@@ -76,13 +76,18 @@ function basenamePath(pathname: string, basename: string): string | null {
   return pathname.slice(basename.length) || "/"
 }
 
-function fragmentKey(input: string | URL, basename = "/"): string {
-  const url = stripFlamefrontProtocolParams(resolveRouteUrl(input))
+function staticFragmentKey(url: URL, basename: string): string {
   const pathname = basenamePath(url.pathname, basename) ?? url.pathname
 
   return `${url.origin}${pathname}`
 }
 
+function routeFragmentKey(url: URL, basename = "/"): string {
+  const pathname = basenamePath(url.pathname, basename) ?? url.pathname
+
+  return `${url.origin}${pathname}${url.search}${url.hash}`
+}
+
 function abortable<Data>(
   pending: Promise<Data>,
   signal: AbortSignal | undefined,
@@ -112,17 +117,17 @@ function abortable<Data>(
   })
 }
 
-export function isStaticFragmentArtifact(
+export function isRouteFragmentArtifact(
   value: unknown,
-): value is StaticFragmentArtifact {
+): value is RouteFragmentArtifact {
   if (!value || typeof value !== "object") {
     return false
   }
 
-  const artifact = value as Partial<StaticFragmentArtifact>
+  const artifact = value as Partial<RouteFragmentArtifact>
 
   return (
-    artifact.protocol === staticFragmentProtocol &&
+    artifact.protocol === routeFragmentProtocol &&
     typeof artifact.route === "string" &&
     typeof artifact.boundary === "string" &&
     typeof artifact.html === "string" &&
@@ -130,98 +135,133 @@ export function isStaticFragmentArtifact(
   )
 }
 
-export function assertStaticFragmentArtifact(
+export function assertRouteFragmentArtifact(
   value: unknown,
-): StaticFragmentArtifact {
-  if (!isStaticFragmentArtifact(value)) {
+): RouteFragmentArtifact {
+  if (!isRouteFragmentArtifact(value)) {
     throw new Error(
-      "flamefront static fragment response has an invalid protocol.",
+      "flamefront route fragment response has an invalid protocol.",
     )
   }
 
   return value
 }
 
-export function getStaticFragment(
+export function getRouteFragment(
   url: string | URL,
-  routing: StaticFragmentRoutingOptions = {},
-): StaticFragmentArtifact | undefined {
-  const pending = fragmentCache.get(fragmentKey(url, routing.basename ?? "/"))
-
-  return pending && "value" in pending
-    ? (
-        pending as Promise<StaticFragmentArtifact> & {
-          value?: StaticFragmentArtifact
+  routing: RouteFragmentRoutingOptions = {},
+): RouteFragmentArtifact | undefined {
+  return latestRouteFragments.get(
+    routeFragmentKey(resolveRouteUrl(url), routing.basename ?? "/"),
+  )
+}
+
+function fetchRouteFragment(
+  routeUrl: URL,
+  basename: string,
+  signal: AbortSignal | undefined,
+): Promise<RouteFragmentArtifact> {
+  const endpoint = withRouteFragmentProtocol(routeUrl)
+
+  return globalThis
+    .fetch(endpoint, {
+      headers: { Accept: "application/vnd.flamefront.fragment+json" },
+      ...(signal ? { signal } : {}),
+    })
+    .then(async (response) => {
+      if (response.redirected) {
+        const location = stripFlamefrontProtocolParams(response.url)
+        const pathname =
+          basenamePath(location.pathname, basename) ?? location.pathname
+
+        throw new Response(null, {
+          status: 302,
+          headers: {
+            Location: `${pathname}${location.search}${location.hash}`,
+          },
+        })
+      }
+
+      if (response.status >= 300 && response.status < 400) {
+        throw response
+      }
+
+      let value: unknown
+
+      try {
+        value = await response.json()
+      } catch {
+        if (!response.ok) {
+          throw new Error(
+            `flamefront route fragment request failed with ${response.status}.`,
+          )
         }
-      ).value
-    : undefined
-}
-
-function rememberArtifact(
-  key: string,
-  pending: Promise<StaticFragmentArtifact>,
-): Promise<StaticFragmentArtifact> {
-  const tracked = pending.then((artifact) => {
-    ;(
-      tracked as Promise<StaticFragmentArtifact> & {
-        value?: StaticFragmentArtifact
+
+        throw new Error(
+          "flamefront route fragment response has an invalid protocol.",
+        )
       }
-    ).value = artifact
-    return artifact
-  })
 
-  fragmentCache.set(key, tracked)
-  void tracked.catch(() => {
-    if (fragmentCache.get(key) === tracked) {
-      fragmentCache.delete(key)
-    }
-  })
-  return tracked
+      return assertRouteFragmentArtifact(value)
+    })
 }
 
-export function loadStaticFragment(
+export function loadRouteFragment(
   url: string | URL,
-  routing: StaticFragmentRoutingOptions = {},
-  options: StaticFragmentLoadOptions = {},
-): Promise<StaticFragmentArtifact> {
+  routing: RouteFragmentRoutingOptions = {},
+  options: RouteFragmentLoadOptions,
+): Promise<RouteFragmentArtifact> {
   const routeUrl = resolveRouteUrl(url)
-  const key = fragmentKey(routeUrl, routing.basename ?? "/")
+  const handoffKey = routeFragmentKey(routeUrl, routing.basename ?? "/")
+  const requests =
+    options.policy === "static"
+      ? staticFragmentRequests
+      : serverFragmentRequests
+  const requestKey =
+    options.policy === "static"
+      ? staticFragmentKey(routeUrl, routing.basename ?? "/")
+      : routeUrl.href
 
   if (options.reload) {
-    fragmentCache.delete(key)
+    requests.delete(requestKey)
   }
 
-  const cached = fragmentCache.get(key)
+  let pending = requests.get(requestKey)
 
-  if (cached) {
-    return abortable(cached, options.signal)
-  }
+  if (!pending) {
+    pending = fetchRouteFragment(
+      routeUrl,
+      routing.basename ?? "/",
+      options.signal,
+    )
+    requests.set(requestKey, pending)
 
-  const endpoint = withStaticFragmentProtocol(routeUrl)
-  const pending = globalThis
-    .fetch(endpoint, {
-      headers: { Accept: "application/vnd.flamefront.fragment+json" },
-      ...(options.signal ? { signal: options.signal } : {}),
-    })
-    .then(async (response) => {
-      if (!response.ok) {
-        throw new Error(
-          `flamefront static fragment request failed with ${response.status}.`,
-        )
+    const evict = () => {
+      if (requests.get(requestKey) === pending) {
+        requests.delete(requestKey)
       }
+    }
 
-      return assertStaticFragmentArtifact(await response.json())
-    })
+    if (options.policy === "static") {
+      void pending.catch(evict)
+    } else {
+      void pending.then(evict, evict)
+    }
+  }
 
-  return abortable(rememberArtifact(key, pending), options.signal)
+  return abortable(pending, options.signal).then((artifact) => {
+    latestRouteFragments.set(handoffKey, artifact)
+    return artifact
+  })
 }
 
-export async function prefetchStaticFragment(
+export async function prefetchRouteFragment(
   url: string | URL,
-  routing: StaticFragmentRoutingOptions = {},
-  options?: StaticFragmentLoadOptions,
+  policy: RouteFragmentCachePolicy,
+  routing: RouteFragmentRoutingOptions = {},
+  options: Omit<RouteFragmentLoadOptions, "policy"> = {},
 ): Promise<void> {
-  await loadStaticFragment(url, routing, options)
+  await loadRouteFragment(url, routing, { ...options, policy })
 }
 
 export type {

package/src/fragment-hydration-client.tsx

@@ -0,0 +1,81 @@
+import {
+  createRoot,
+  hydrateRoot,
+  setDangerouslySetInnerHTML,
+  setHTML,
+} from "octane"
+import { outletIdentifierPrefix } from "./identifier-prefix.ts"
+
+type RenderableComponent = (props: Record<string, unknown>) => unknown
+
+interface OutletRoot {
+  unmount(): void
+  render(Component: RenderableComponent, props?: Record<string, unknown>): void
+}
+
+function removeHostChildRange(html: string): string {
+  const start = "<!--[-->"
+  const end = "<!--]-->"
+
+  return html.startsWith(start) && html.endsWith(end)
+    ? html.slice(start.length, -end.length)
+    : html
+}
+
+function createOutletRoot(root: ReturnType<typeof createRoot>): OutletRoot {
+  return {
+    unmount: () => root.unmount(),
+    render: (nextComponent, props) => {
+      root.render(nextComponent, props)
+    },
+  }
+}
+
+/** Transfer inserted fragment DOM from the outer root to a nested Octane root. */
+export function hydrateRouteFragment(
+  host: HTMLDivElement,
+  Component: RenderableComponent,
+): OutletRoot {
+  const html = host.innerHTML
+
+  setDangerouslySetInnerHTML(host, null)
+  setHTML(host, html)
+
+  const root = hydrateRoot(host, Component, undefined, {
+    identifierPrefix: outletIdentifierPrefix,
+  })
+
+  return {
+    unmount: () => root.unmount(),
+    render: (nextComponent) => root.render(nextComponent),
+  }
+}
+
+/** Mount a routed outlet into its own root after the outer shell commits. */
+export function renderRouteOutlet(
+  host: HTMLDivElement,
+  Component: RenderableComponent,
+  hydrate: boolean,
+): OutletRoot {
+  if (hydrate) {
+    const html = removeHostChildRange(host.innerHTML)
+
+    setDangerouslySetInnerHTML(host, null)
+    setHTML(host, html)
+
+    const root = hydrateRoot(host, Component, undefined, {
+      identifierPrefix: outletIdentifierPrefix,
+    })
+
+    return createOutletRoot(root)
+  }
+
+  setDangerouslySetInnerHTML(host, null)
+  setHTML(host, "")
+
+  const root = createRoot(host, { identifierPrefix: outletIdentifierPrefix })
+
+  root.render(Component)
+
+  return createOutletRoot(root)
+}

package/src/fragment-protocol.ts

@@ -11,7 +11,7 @@ export function stripFlamefrontProtocolParams(input: string | URL): URL {
   return url
 }
 
-export function isStaticFragmentRequest(input: string | URL): boolean {
+export function isRouteFragmentRequest(input: string | URL): boolean {
   const url = new URL(input, "http://flamefront.local")
 
   return (
@@ -20,8 +20,8 @@ export function isStaticFragmentRequest(input: string | URL): boolean {
   )
 }
 
-/** Mark a route URL for the static-fragment transport. */
-export function withStaticFragmentProtocol(input: string | URL): URL {
+/** Mark a route URL for the fragment transport. */
+export function withRouteFragmentProtocol(input: string | URL): URL {
   const url = stripFlamefrontProtocolParams(input)
 
   url.searchParams.set(