flamefront 0.0.0 → 0.1.0-alpha.0

package/src/remix-router-core.ts

@@ -0,0 +1,106 @@
+export interface RemixStaticContext {
+  readonly loaderData: Record<string, unknown>
+  readonly actionData: Record<string, unknown> | null
+  readonly errors: Record<string, unknown> | null
+  readonly statusCode?: number
+}
+
+export interface RemixRouterRuntime<
+  Route = unknown,
+  ClientRouter = unknown,
+  ServerRouter = unknown,
+  Context extends RemixStaticContext = RemixStaticContext,
+  ClientOptions = unknown,
+> {
+  createBrowserRouter(routes: Route[], options?: ClientOptions): ClientRouter
+  createStaticHandler(
+    routes: Route[],
+    options?: { basename?: string },
+  ): {
+    readonly dataRoutes: Route[]
+    query(
+      request: Request,
+      options?: { requestContext?: unknown },
+    ): Promise<Response | Context>
+  }
+  createStaticRouter(routes: Route[], context: Context): ServerRouter
+}
+
+export interface ServerRouterResult<
+  Router = unknown,
+  Context = RemixStaticContext,
+> {
+  readonly context: Context
+  readonly hydrationData: {
+    readonly loaderData: Record<string, unknown>
+    readonly actionData: Record<string, unknown> | null
+    readonly errors: Record<string, unknown> | null
+  }
+  readonly router: Router
+}
+
+export interface ServerRouterOptions {
+  readonly basename?: string
+  readonly requestContext?: unknown
+}
+
+export interface RemixRouterAdapterOptions {
+  readonly basename?: string
+}
+
+export function createRemixRouterAdapter<
+  Route,
+  ClientRouter,
+  ServerRouter,
+  Context extends RemixStaticContext,
+  ClientOptions,
+>(
+  routeGraph: Route[],
+  runtime: RemixRouterRuntime<
+    Route,
+    ClientRouter,
+    ServerRouter,
+    Context,
+    ClientOptions
+  >,
+  defaults: RemixRouterAdapterOptions = {},
+) {
+  return {
+    routes: routeGraph,
+    createClientRouter(options?: ClientOptions) {
+      if (defaults.basename === undefined) {
+        return runtime.createBrowserRouter(routeGraph, options)
+      }
+
+      return runtime.createBrowserRouter(routeGraph, {
+        ...(options && typeof options === "object" ? options : {}),
+        basename: defaults.basename,
+      } as ClientOptions)
+    },
+    async createServerRouter(
+      request: Request,
+      options: ServerRouterOptions = {},
+    ): Promise<Response | ServerRouterResult<ServerRouter, Context>> {
+      const handler = runtime.createStaticHandler(routeGraph, {
+        basename: options.basename ?? defaults.basename,
+      })
+      const context = await handler.query(request, {
+        requestContext: options.requestContext,
+      })
+
+      if (context instanceof Response) {
+        return context
+      }
+
+      return {
+        context,
+        hydrationData: {
+          loaderData: context.loaderData,
+          actionData: context.actionData,
+          errors: context.errors,
+        },
+        router: runtime.createStaticRouter(handler.dataRoutes, context),
+      }
+    },
+  }
+}

package/src/remix-router.ts

@@ -0,0 +1,111 @@
+import {
+  createRemixRouterAdapter,
+  type ServerRouterOptions,
+  type ServerRouterResult,
+} from "./remix-router-core.ts"
+import {
+  createBrowserRouter,
+  createStaticHandler,
+  createStaticRouter,
+} from "@octanejs/remix-router"
+import type { HydrationState } from "@octanejs/remix-router"
+import type {
+  AppDefinition,
+  LoadRouteOptions,
+  RouteDefinition,
+} from "./index.ts"
+import {
+  createRoutePrefetchCallback,
+  prefetchRouteResources,
+  type RoutePrefetchCallback,
+  type RoutePrefetchResources,
+} from "./route-prefetch.ts"
+import { prefetchStaticFragment } from "./fragment-client.ts"
+import {
+  preloadRoute as preloadGeneratedRoute,
+  RouterDocument,
+  routeMetadata,
+  routes,
+  routing,
+} from "virtual:flamefront/remix-routes"
+
+export { RouterDocument, routeMetadata, routes, routing }
+export { createRemixRouterAdapter }
+export type { ServerRouterOptions, ServerRouterResult }
+export type {
+  RoutePrefetchCallback,
+  RoutePrefetchResources,
+} from "./route-prefetch.ts"
+
+export const staticRouterHydrationScriptId =
+  "flamefront-static-router-hydration"
+
+/** Read and remove the hydration payload emitted by the server document adapter. */
+export function consumeStaticRouterHydrationData(): HydrationState | undefined {
+  const data = (
+    window as typeof window & {
+      __staticRouterHydrationData?: unknown
+    }
+  ).__staticRouterHydrationData
+
+  document.getElementById(staticRouterHydrationScriptId)?.remove()
+  return data as HydrationState | undefined
+}
+
+const adapter = createRemixRouterAdapter(
+  routes,
+  {
+    createBrowserRouter,
+    createStaticHandler,
+    createStaticRouter,
+  },
+  routing,
+)
+
+export const createClientRouter = adapter.createClientRouter
+export const createServerRouter = adapter.createServerRouter
+
+function withDefaultPrefetchResources<
+  Route extends RouteDefinition = RouteDefinition,
+>(
+  resources: RoutePrefetchResources<Route> = {},
+): RoutePrefetchResources<Route> {
+  return {
+    ...resources,
+    staticFragment:
+      resources.staticFragment ??
+      ((url, _route, options) => prefetchStaticFragment(url, routing, options)),
+  }
+}
+
+/** Prefetch route resources selected by the matched Flamefront route. */
+export async function prefetchRoute<
+  Route extends RouteDefinition = RouteDefinition,
+>(
+  app: Pick<AppDefinition<Route>, "match" | "prefetch">,
+  url: string | URL,
+  options?: LoadRouteOptions,
+  resources?: RoutePrefetchResources<Route>,
+): Promise<void> {
+  await prefetchRouteResources(
+    app,
+    preloadGeneratedRoute,
+    url,
+    options,
+    withDefaultPrefetchResources(resources),
+  )
+}
+
+/** Create the callback used by `createClientRouter({ prefetch })`. */
+export function createRoutePrefetcher<
+  Route extends RouteDefinition = RouteDefinition,
+>(
+  app: Pick<AppDefinition<Route>, "match" | "prefetch">,
+  resources?: RoutePrefetchResources<Route>,
+): RoutePrefetchCallback {
+  return createRoutePrefetchCallback(
+    app,
+    preloadGeneratedRoute,
+    withDefaultPrefetchResources(resources),
+  )
+}

package/src/remove-exports.ts

@@ -0,0 +1,148 @@
+import { getBindingIdentifiers } from "@babel/types"
+import {
+  deadCodeElimination,
+  findReferencedIdentifiers,
+} from "babel-dead-code-elimination"
+import type { Babel, NodePath, ParseResult } from "./babel.ts"
+import { traverse } from "./babel.ts"
+
+function exportedIdentifierName(
+  exported: Babel.Identifier | Babel.StringLiteral,
+): string | undefined {
+  return exported.type === "Identifier" ? exported.name : exported.value
+}
+
+function assertRemovableBinding(
+  id: Babel.VariableDeclarator["id"],
+  exportsToRemove: ReadonlySet<string>,
+): void {
+  if (id.type === "Identifier") {
+    return
+  }
+
+  const bindingNames = new Set(Object.keys(getBindingIdentifiers(id)))
+
+  for (const exportName of exportsToRemove) {
+    if (bindingNames.has(exportName)) {
+      throw new SyntaxError(
+        `Flamefront cannot safely remove destructured route export "${exportName}".`,
+      )
+    }
+  }
+}
+
+/**
+ * Remove selected exports and declarations that became unreachable as a result.
+ * This follows React Router's client-route transform: the pre-transform reference
+ * set constrains DCE so unrelated, already-unused authored code is preserved.
+ */
+export function removeExports(
+  ast: ParseResult<Babel.File>,
+  exportNames: readonly string[],
+): boolean {
+  const exportsToRemove = new Set(exportNames)
+  const referencedBeforeRemoval = findReferencedIdentifiers(ast)
+  const pathsToRemove = new Set<NodePath<Babel.Node>>()
+  const removedLocalNames = new Set<string>()
+  let changed = false
+
+  traverse(ast, {
+    ExportNamedDeclaration(path) {
+      if (path.node.specifiers.length > 0) {
+        path.node.specifiers = path.node.specifiers.filter((specifier) => {
+          if (specifier.type !== "ExportSpecifier") {
+            return true
+          }
+
+          const exportName = exportedIdentifierName(specifier.exported)
+
+          if (!exportName || !exportsToRemove.has(exportName)) {
+            return true
+          }
+
+          changed = true
+          if (specifier.local.type === "Identifier") {
+            removedLocalNames.add(specifier.local.name)
+          }
+
+          return false
+        })
+
+        if (path.node.specifiers.length === 0) {
+          pathsToRemove.add(path)
+        }
+      }
+
+      const declaration = path.node.declaration
+
+      if (declaration?.type === "VariableDeclaration") {
+        declaration.declarations = declaration.declarations.filter(
+          (declarator) => {
+            assertRemovableBinding(declarator.id, exportsToRemove)
+            if (
+              declarator.id.type !== "Identifier" ||
+              !exportsToRemove.has(declarator.id.name)
+            ) {
+              return true
+            }
+
+            changed = true
+            removedLocalNames.add(declarator.id.name)
+            return false
+          },
+        )
+
+        if (declaration.declarations.length === 0) {
+          pathsToRemove.add(path)
+        }
+      }
+
+      if (
+        (declaration?.type === "FunctionDeclaration" ||
+          declaration?.type === "ClassDeclaration") &&
+        declaration.id &&
+        exportsToRemove.has(declaration.id.name)
+      ) {
+        changed = true
+        removedLocalNames.add(declaration.id.name)
+        pathsToRemove.add(path)
+      }
+    },
+  })
+
+  if (!changed) {
+    return false
+  }
+
+  // Remove metadata assignments such as `loader.cache = true` with the loader.
+  traverse(ast, {
+    ExpressionStatement(path) {
+      if (!path.parentPath.isProgram()) {
+        return
+      }
+
+      const expression = path.node.expression
+
+      if (expression.type !== "AssignmentExpression") {
+        return
+      }
+
+      const target = expression.left
+
+      if (
+        target.type === "MemberExpression" &&
+        target.object.type === "Identifier" &&
+        removedLocalNames.has(target.object.name)
+      ) {
+        pathsToRemove.add(path)
+      }
+    },
+  })
+
+  for (const path of pathsToRemove) {
+    path.remove()
+  }
+
+  deadCodeElimination(ast, referencedBeforeRemoval)
+  return true
+}

package/src/route-data-client.ts

@@ -0,0 +1,224 @@
+import { stripFlamefrontProtocolParams } from "./fragment-protocol.ts"
+
+export type RouteDataSource = "live" | "static"
+
+export interface RouteDataRoutingOptions {
+  readonly basename?: string
+  readonly dataPath?: string
+}
+
+export interface RouteDataLoadOptions {
+  readonly signal?: AbortSignal
+  readonly reload?: boolean
+}
+
+export interface RouteDataClient {
+  readonly load: <Data = unknown>(
+    url: string | URL,
+    source: RouteDataSource,
+    options?: RouteDataLoadOptions,
+  ) => Promise<Data>
+  readonly prefetch: (
+    url: string | URL,
+    source: RouteDataSource,
+    options?: RouteDataLoadOptions,
+  ) => Promise<void>
+}
+
+const defaultRouting = Object.freeze({
+  basename: "/",
+  dataPath: "/__flamefront/data",
+})
+
+/**
+ * Browser route-data clients share one cache per routing configuration so
+ * app.prefetch() and generated router loaders can consume the same promise.
+ * Server callers receive an isolated client to avoid a process-wide browser
+ * cache; server rendering invokes route loaders directly instead.
+ */
+const browserClients = new Map<string, RouteDataClient>()
+
+function normalizePath(value: string | undefined, fallback: string): string {
+  return value?.replace(/\/+$/, "") || fallback
+}
+
+function normalizeRouting(options: RouteDataRoutingOptions): {
+  readonly basename: string
+  readonly dataPath: string
+} {
+  return {
+    basename: normalizePath(options.basename, defaultRouting.basename),
+    dataPath: normalizePath(options.dataPath, defaultRouting.dataPath),
+  }
+}
+
+function resolveRouteUrl(url: string | URL): URL {
+  const browserOrigin =
+    typeof location === "undefined" ? undefined : location.origin
+
+  if (!browserOrigin && typeof url === "string" && !URL.canParse(url)) {
+    throw new TypeError(
+      "flamefront route data requires an absolute URL outside the browser.",
+    )
+  }
+
+  return new URL(url, browserOrigin)
+}
+
+function stripBasename(pathname: string, basename: string): string | null {
+  if (basename === "/") {
+    return pathname
+  }
+
+  if (pathname === basename) {
+    return "/"
+  }
+
+  if (!pathname.startsWith(`${basename}/`)) {
+    return null
+  }
+
+  return pathname.slice(basename.length) || "/"
+}
+
+function joinBasename(basename: string, pathname: string): string {
+  if (basename === "/") {
+    return pathname || "/"
+  }
+
+  if (pathname === "/") {
+    return basename
+  }
+
+  return `${basename}${pathname.startsWith("/") ? pathname : `/${pathname}`}`
+}
+
+function staticRouteDataPath(routeUrl: URL, basename: string): string {
+  const appPathname =
+    stripBasename(routeUrl.pathname, basename) ?? routeUrl.pathname
+  const pathname = joinBasename(basename, appPathname).replace(/\/+$/, "")
+
+  return pathname === "" ? "/index.data.json" : `${pathname}/index.data.json`
+}
+
+function cacheKey(routeUrl: URL, source: RouteDataSource): string {
+  return `${source}:${routeUrl.origin}${routeUrl.pathname}${routeUrl.search}`
+}
+
+function abortable<Data>(
+  pending: Promise<Data>,
+  signal: AbortSignal | undefined,
+): Promise<Data> {
+  if (!signal) {
+    return pending
+  }
+
+  if (signal.aborted) {
+    return Promise.reject(signal.reason)
+  }
+
+  return new Promise<Data>((resolve, reject) => {
+    const onAbort = () => reject(signal.reason)
+
+    signal.addEventListener("abort", onAbort, { once: true })
+    pending.then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort)
+        resolve(value)
+      },
+      (error) => {
+        signal.removeEventListener("abort", onAbort)
+        reject(error)
+      },
+    )
+  })
+}
+
+function createIsolatedRouteDataClient(routing: {
+  readonly basename: string
+  readonly dataPath: string
+}): RouteDataClient {
+  const cache = new Map<string, Promise<unknown>>()
+
+  const load = <Data = unknown>(
+    url: string | URL,
+    source: RouteDataSource,
+    options: RouteDataLoadOptions = {},
+  ): Promise<Data> => {
+    const routeUrl = stripFlamefrontProtocolParams(resolveRouteUrl(url))
+    const key = cacheKey(routeUrl, source)
+
+    if (options.reload) {
+      cache.delete(key)
+    }
+
+    const cached = cache.get(key)
+
+    if (cached) {
+      return abortable(cached as Promise<Data>, options.signal)
+    }
+
+    const endpoint =
+      source === "static"
+        ? new URL(
+            staticRouteDataPath(routeUrl, routing.basename),
+            routeUrl.origin,
+          )
+        : new URL(routing.dataPath, routeUrl.origin)
+
+    if (source === "live") {
+      endpoint.searchParams.set("url", routeUrl.href)
+    }
+
+    const pending = globalThis
+      .fetch(endpoint, options.signal ? { signal: options.signal } : undefined)
+      .then(async (response) => {
+        if (!response.ok) {
+          const label = source === "static" ? "static route data" : "loader"
+
+          throw new Error(
+            `flamefront ${label} request failed with ${response.status}.`,
+          )
+        }
+
+        return response.json() as Promise<Data>
+      })
+
+    cache.set(key, pending)
+    void pending.catch(() => {
+      if (cache.get(key) === pending) {
+        cache.delete(key)
+      }
+    })
+    return abortable(pending, options.signal)
+  }
+
+  return {
+    load,
+    prefetch: async (url, source, options) => {
+      await load(url, source, options)
+    },
+  }
+}
+
+export function createRouteDataClient(
+  options: RouteDataRoutingOptions = {},
+): RouteDataClient {
+  const routing = normalizeRouting(options)
+
+  if (typeof window === "undefined") {
+    return createIsolatedRouteDataClient(routing)
+  }
+
+  const key = `${routing.basename}\u0000${routing.dataPath}`
+  const existing = browserClients.get(key)
+
+  if (existing) {
+    return existing
+  }
+
+  const client = createIsolatedRouteDataClient(routing)
+
+  browserClients.set(key, client)
+  return client
+}

package/src/route-prefetch.ts

@@ -0,0 +1,72 @@
+import type {
+  AppDefinition,
+  LoadRouteOptions,
+  RouteDefinition,
+} from "./index.ts"
+
+/**
+ * Resources that a route-aware prefetcher can warm without taking over
+ * navigation. The framework adapter supplies the static fragment transport;
+ * callers can replace it when they own the transport.
+ */
+export interface RoutePrefetchResources<
+  Route extends RouteDefinition = RouteDefinition,
+> {
+  readonly staticFragment?: (
+    url: string | URL,
+    route: Route,
+    options?: LoadRouteOptions,
+  ) => void | Promise<void>
+}
+
+export type RouteModulePreloader = (entry: string) => void | Promise<void>
+
+export type RoutePrefetchCallback = (to: string) => void | Promise<void>
+
+type RoutePrefetchApp<Route extends RouteDefinition> = Pick<
+  AppDefinition<Route>,
+  "match" | "prefetch"
+>
+
+/**
+ * Warm the resources used by a matched route. Live routes share route data
+ * and client-module caches. Static routes hand off to the fragment resource
+ * seam and never import their route module as a rendering path.
+ */
+export async function prefetchRouteResources<
+  Route extends RouteDefinition = RouteDefinition,
+>(
+  app: RoutePrefetchApp<Route>,
+  preloadRoute: RouteModulePreloader,
+  url: string | URL,
+  options: LoadRouteOptions = {},
+  resources: RoutePrefetchResources<Route> = {},
+): Promise<void> {
+  const match = app.match(url)
+
+  if (!match) {
+    return
+  }
+
+  if (match.data.render === "static") {
+    await resources.staticFragment?.(url, match.data, options)
+    return
+  }
+
+  await Promise.all([
+    app.prefetch(url, options),
+    preloadRoute(match.data.entry),
+  ])
+}
+
+/** Create the callback accepted by the generic browser router. */
+export function createRoutePrefetchCallback<
+  Route extends RouteDefinition = RouteDefinition,
+>(
+  app: RoutePrefetchApp<Route>,
+  preloadRoute: RouteModulePreloader,
+  resources: RoutePrefetchResources<Route> = {},
+): RoutePrefetchCallback {
+  return (to) =>
+    prefetchRouteResources(app, preloadRoute, to, undefined, resources)
+}