flamefront 0.1.0-alpha.0 → 0.1.0

package/src/route-prefetch.ts

@@ -1,18 +1,19 @@
 import type {
-  AppDefinition,
   LoadRouteOptions,
+  MatchRouteOptions,
   RouteDefinition,
+  RouteMatchForUrl,
 } from "./index.ts"
 
 /**
  * Resources that a route-aware prefetcher can warm without taking over
- * navigation. The framework adapter supplies the static fragment transport;
+ * navigation. The framework adapter supplies the route fragment transport;
  * callers can replace it when they own the transport.
  */
 export interface RoutePrefetchResources<
   Route extends RouteDefinition = RouteDefinition,
 > {
-  readonly staticFragment?: (
+  readonly routeFragment?: (
     url: string | URL,
     route: Route,
     options?: LoadRouteOptions,
@@ -23,15 +24,21 @@ 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"
->
+type RoutePrefetchApp<Route extends RouteDefinition> = {
+  readonly match: (
+    url: string | URL,
+    options?: MatchRouteOptions,
+  ) => RouteMatchForUrl<Route, string> | null
+  readonly prefetch: (
+    url: string | URL,
+    options?: LoadRouteOptions,
+  ) => Promise<void>
+}
 
 /**
- * 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.
+ * Warm the resources used by a matched route. Client routes share route data
+ * and module caches. Server and static routes use the fragment resource and
+ * never import their route module as a browser rendering path.
  */
 export async function prefetchRouteResources<
   Route extends RouteDefinition = RouteDefinition,
@@ -48,8 +55,8 @@ export async function prefetchRouteResources<
     return
   }
 
-  if (match.data.render === "static") {
-    await resources.staticFragment?.(url, match.data, options)
+  if (match.data.render !== "client") {
+    await resources.routeFragment?.(url, match.data, options)
     return
   }
 

package/src/server.ts

@@ -1,25 +1,50 @@
-import type { Match } from "@remix-run/route-pattern/match"
 import {
   type AppDefinition,
   type MatchRouteOptions,
+  type RouteLoaderFor,
   type RenderMode,
+  type RouteLoaderData,
+  type RouteMatchForUrl,
+  type RouteParams,
   type RouteDefinition,
 } from "./index.ts"
 import { stripFlamefrontProtocolRequest } from "./fragment-protocol.ts"
 
-export interface LoaderArgs<Context = unknown> {
+type LoaderPath<ContextOrPath, PathOrContext> =
+  ContextOrPath extends `/${string}`
+    ? ContextOrPath
+    : PathOrContext extends `/${string}`
+      ? PathOrContext
+      : string
+
+type LoaderContext<ContextOrPath, PathOrContext> =
+  ContextOrPath extends `/${string}`
+    ? PathOrContext extends `/${string}`
+      ? unknown
+      : PathOrContext
+    : ContextOrPath
+
+export interface LoaderArgs<ContextOrPath = unknown, PathOrContext = unknown> {
   readonly request: Request
-  readonly params: Readonly<Record<string, string | undefined>>
-  readonly context: Context
+  readonly params: Readonly<
+    RouteParams<LoaderPath<ContextOrPath, PathOrContext>>
+  >
+  readonly context: LoaderContext<ContextOrPath, PathOrContext>
 }
 
-export type Loader<Data = unknown, Context = unknown> = (
-  args: LoaderArgs<Context>,
-) => Data | Promise<Data>
+export type Loader<
+  Data = unknown,
+  Context = unknown,
+  Path extends string = string,
+> = (args: LoaderArgs<Context, Path>) => Data | Promise<Data>
 
-export interface RouteModule<Data = unknown, Context = unknown> {
+export interface RouteModule<
+  Data = unknown,
+  Context = unknown,
+  Path extends string = string,
+> {
   readonly default: unknown
-  readonly loader?: Loader<Data, Context>
+  readonly loader?: Loader<Data, Context, Path>
 }
 
 export type DocumentMode = "shell" | RenderMode
@@ -31,7 +56,7 @@ export interface RequestContextArgs<
 > {
   readonly request: Request
   readonly route: Route | null
-  readonly params: Readonly<Record<string, string | undefined>>
+  readonly params: Readonly<RouteParams<Route["path"]>>
   readonly purpose: RequestPurpose
   readonly mode?: DocumentMode
 }
@@ -42,9 +67,11 @@ export type RequestContextFactory<
 > = (args: RequestContextArgs<Route>) => Context | Promise<Context>
 
 /** Import a generated or application-provided route module by its entry ID. */
-export type RouteImporter<Data = unknown, Context = unknown> = (
-  entry: string,
-) => Promise<RouteModule<Data, Context>>
+export type RouteImporter<
+  Data = unknown,
+  Context = unknown,
+  Path extends string = string,
+> = (entry: string) => Promise<RouteModule<Data, Context, Path>>
 
 export interface RenderedDocument {
   readonly html: string
@@ -65,6 +92,41 @@ export interface LoadedRoute<
   readonly loaderData: Data | undefined
 }
 
+/** A loaded route whose data follows the generated route-module map. */
+export type LoadedRouteFor<
+  Route extends RouteDefinition,
+  Context = unknown,
+> = Route extends RouteDefinition
+  ? RouteLoaderFor<Route["path"]> extends (
+      ...args: infer _Args
+    ) => infer _Result
+    ? Omit<
+        LoadedRoute<RouteLoaderData<Route["path"]>, Context, Route>,
+        "loaderData"
+      > & {
+        readonly loaderData: RouteLoaderData<Route["path"]>
+      }
+    : LoadedRoute<unknown, Context, Route>
+  : never
+
+/** Route-module shape selected from one authored route definition. */
+export type RouteModuleForRoute<
+  Route extends RouteDefinition,
+  Context = unknown,
+> = Route extends RouteDefinition
+  ? RouteLoaderFor<Route["path"]> extends (
+      ...args: infer _Args
+    ) => infer _Result
+    ? RouteModule<RouteLoaderData<Route["path"]>, Context, Route["path"]>
+    : RouteModule<unknown, Context, Route["path"]>
+  : never
+
+/** Importer shape for applications that own a typed route-module boundary. */
+export type RouteImporterFor<
+  Route extends RouteDefinition,
+  Context = unknown,
+> = (entry: Route["entry"]) => Promise<RouteModuleForRoute<Route, Context>>
+
 export interface RouteRuntimeContextOptions {
   readonly purpose: RequestPurpose
   readonly mode?: DocumentMode
@@ -84,7 +146,7 @@ export interface RouteRuntime<
   readonly match: (
     url: string | URL,
     options?: MatchRouteOptions,
-  ) => Match<string, Route> | null
+  ) => RouteMatchForUrl<Route, string> | null
   readonly createRequestContext: (
     request: Request,
     options: RouteRuntimeContextOptions,
@@ -92,7 +154,7 @@ export interface RouteRuntime<
   readonly loadRoute: (
     request: Request,
     options?: RouteLoadOptions<Context>,
-  ) => Promise<LoadedRoute<unknown, Context, Route> | null>
+  ) => Promise<LoadedRouteFor<Route, Context> | null>
   readonly loadRouteData: (request: Request) => Promise<Response>
 }
 
@@ -111,7 +173,7 @@ async function loadMatchedRoute<
   Context = unknown,
   Route extends RouteDefinition = RouteDefinition,
 >(
-  match: Match<string, Route>,
+  match: RouteMatchForUrl<Route, string>,
   request: Request,
   importRoute: RouteImporter<Data, Context>,
   context?: Context,
@@ -120,8 +182,8 @@ async function loadMatchedRoute<
   const loaderData = routeModule.loader
     ? await routeModule.loader({
         request,
-        params: match.params,
-        context: context as Context,
+        params: match.params as LoaderArgs<Context, string>["params"],
+        context: context as LoaderContext<Context, string>,
       })
     : undefined
 
@@ -132,6 +194,15 @@ async function loadMatchedRoute<
   }
 }
 
+export function createRouteRuntime<
+  Context = unknown,
+  Route extends RouteDefinition = RouteDefinition,
+>(
+  options: Omit<RouteRuntimeOptions<Context, Route>, "importRoute"> & {
+    readonly importRoute: RouteImporterFor<Route, Context>
+  },
+): RouteRuntime<Context, Route>
+
 export function createRouteRuntime<
   Context = unknown,
   Route extends RouteDefinition = RouteDefinition,
@@ -148,7 +219,7 @@ export function createRouteRuntime<
     return options.requestContext({
       request,
       route: match?.data ?? null,
-      params: match?.params ?? {},
+      params: (match?.params ?? {}) as Readonly<RouteParams<Route["path"]>>,
       purpose: contextOptions.purpose,
       ...(contextOptions.mode === undefined
         ? {}
@@ -159,7 +230,7 @@ export function createRouteRuntime<
   const loadRouteForRequest = async (
     request: Request,
     loadOptions: RouteLoadOptions<Context> = {},
-  ): Promise<LoadedRoute<unknown, Context, Route> | null> => {
+  ): Promise<LoadedRouteFor<Route, Context> | null> => {
     const sanitizedRequest = stripFlamefrontProtocolRequest(request)
     const match = options.app.match(sanitizedRequest.url)
 
@@ -181,7 +252,7 @@ export function createRouteRuntime<
       sanitizedRequest,
       options.importRoute,
       context,
-    )
+    ) as Promise<LoadedRouteFor<Route, Context>>
   }
 
   const loadRouteData = async (request: Request): Promise<Response> => {
@@ -219,6 +290,28 @@ export function createRouteRuntime<
   }
 }
 
+export function loadRoute<
+  _Data = unknown,
+  Context = unknown,
+  Route extends RouteDefinition = RouteDefinition,
+>(
+  app: AppDefinition<Route>,
+  request: Request,
+  importRoute: RouteImporterFor<Route, Context>,
+  context?: Context,
+): Promise<LoadedRouteFor<Route, Context> | null>
+
+export function loadRoute<
+  Data = unknown,
+  Context = unknown,
+  Route extends RouteDefinition = RouteDefinition,
+>(
+  app: AppDefinition<Route>,
+  request: Request,
+  importRoute: RouteImporter<Data, Context>,
+  context?: Context,
+): Promise<LoadedRoute<Data, Context, Route> | null>
+
 export async function loadRoute<
   Data = unknown,
   Context = unknown,
@@ -226,9 +319,9 @@ export async function loadRoute<
 >(
   app: AppDefinition<Route>,
   request: Request,
-  importRoute: (entry: string) => Promise<RouteModule<Data, Context>>,
+  importRoute: RouteImporter<Data, Context>,
   context?: Context,
-): Promise<LoadedRoute<Data, Context, Route> | null> {
+): Promise<LoadedRouteFor<Route, Context> | null> {
   const sanitizedRequest = stripFlamefrontProtocolRequest(request)
   const match = app.match(sanitizedRequest.url)
 
@@ -236,5 +329,10 @@ export async function loadRoute<
     return null
   }
 
-  return loadMatchedRoute(match, sanitizedRequest, importRoute, context)
+  return loadMatchedRoute(
+    match,
+    sanitizedRequest,
+    importRoute,
+    context,
+  ) as Promise<LoadedRouteFor<Route, Context>>
 }

package/src/srvx.ts

@@ -4,33 +4,36 @@ import { resolve } from "node:path"
 import { staticMiddleware } from "srvx/static"
 import type { ServerMiddleware, ServerOptions } from "srvx"
 import {
-  joinBasename,
   stripBasename,
   type AppDefinition,
   type RouteDefinition,
 } from "./index.ts"
-import type { OctaneDocuments } from "./octane.ts"
-import type { DocumentMode, RenderedDocument } from "./server.ts"
+import { isRouteFragmentRequest } from "./fragment-protocol.ts"
 import {
-  isStaticFragmentRequest,
-  stripFlamefrontProtocolRequest,
-} from "./fragment-protocol.ts"
+  createFetchServerEntry,
+  type ResponseHeadersHook,
+  type ServerDocuments,
+  type ServerEntryLifecycle,
+  type TemplateLoader,
+} from "./fetch.ts"
 import { staticRouteFragmentDataFile } from "./static-fragment-artifacts.ts"
-import type { StaticFragmentArtifact } from "./fragment-client.ts"
 
-export type SrvxMiddleware = ServerMiddleware
-
-export interface TemplateContext<
-  Route extends RouteDefinition = RouteDefinition,
-> {
-  readonly request: Request
-  readonly route: Route | null
-  readonly mode: DocumentMode
-}
+export type {
+  FetchMiddleware,
+  FetchServerAssets,
+  FetchServerEntryOptions,
+  FlamefrontFetchServerEntry,
+  ResponseHeaders,
+  ResponseHeadersContext,
+  ResponseHeadersHook,
+  ServerDocuments,
+  StaticFragmentContext,
+  StaticFragmentLoader,
+  TemplateContext,
+  TemplateLoader,
+} from "./fetch.ts"
 
-export type TemplateLoader<Route extends RouteDefinition = RouteDefinition> = (
-  context: TemplateContext<Route>,
-) => string | Promise<string>
+export type SrvxMiddleware = ServerMiddleware
 
 /** Client asset location and the optional replacement for template lookup. */
 export interface ServerAssets<Route extends RouteDefinition = RouteDefinition> {
@@ -38,30 +41,7 @@ export interface ServerAssets<Route extends RouteDefinition = RouteDefinition> {
   readonly loadTemplate?: TemplateLoader<Route>
 }
 
-export interface ResponseHeadersContext<
-  Route extends RouteDefinition = RouteDefinition,
-> {
-  readonly request: Request
-  readonly route: Route | null
-  readonly mode: DocumentMode
-  readonly document: RenderedDocument
-}
-
-export type ResponseHeaders = HeadersInit
-
-/** Add or override response headers after document rendering. */
-export type ResponseHeadersHook<
-  Route extends RouteDefinition = RouteDefinition,
-> = (
-  context: ResponseHeadersContext<Route>,
-) => ResponseHeaders | Promise<ResponseHeaders>
-
-/** Lifecycle operations exposed alongside the srvx server options. */
-export interface ServerEntryLifecycle {
-  readonly renderDocument: OctaneDocuments["renderDocument"]
-  readonly loadRouteData: OctaneDocuments["loadRouteData"]
-  readonly renderFragment?: OctaneDocuments["renderFragment"]
-}
+export type { ServerEntryLifecycle }
 
 /** The single default-export value consumed by Flamefront's lifecycle. */
 export type FlamefrontServerEntry = ServerOptions & ServerEntryLifecycle
@@ -71,11 +51,7 @@ export interface SrvxServerEntryOptions<
   Route extends RouteDefinition = RouteDefinition,
 > {
   readonly app: AppDefinition<Route>
-  readonly documents: Pick<
-    OctaneDocuments,
-    "renderDocument" | "loadRouteData"
-  > &
-    Partial<Pick<OctaneDocuments, "renderFragment">>
+  readonly documents: ServerDocuments
   readonly assets: ServerAssets<Route>
   /** Applied outermost first, in declaration order, around framework transport. */
   readonly middleware?: readonly SrvxMiddleware[]
@@ -105,16 +81,6 @@ async function loadDefaultTemplate(clientDirectory: string): Promise<string> {
   throw lastError
 }
 
-function mergeHeaders(target: Headers, source: HeadersInit | undefined): void {
-  if (source === undefined) {
-    return
-  }
-
-  for (const [name, value] of new Headers(source)) {
-    target.set(name, value)
-  }
-}
-
 function staticRequest(request: Request, basename: string): Request {
   if (
     basename === "/" ||
@@ -145,14 +111,11 @@ export function createSrvxServerEntry<
   const loadTemplate =
     options.assets.loadTemplate ?? (() => loadDefaultTemplate(clientDirectory))
   const serveClientFile = staticMiddleware({ dir: clientDirectory })
-  const defaultClientRoute = options.app.routes.find(
-    (route) => route.render === "client",
-  )
 
   const frameworkMiddleware: SrvxMiddleware = (request, next) => {
     const url = new URL(request.url)
 
-    if (isStaticFragmentRequest(url)) {
+    if (isRouteFragmentRequest(url)) {
       return next()
     }
 
@@ -176,139 +139,36 @@ export function createSrvxServerEntry<
     )
   }
 
-  const fetch = async (request: Request): Promise<Response> => {
-    const url = new URL(request.url)
-    const match = options.app.match(url)
-
-    try {
-      if (
-        url.pathname === options.app.routing.basename &&
-        !match &&
-        defaultClientRoute
-      ) {
-        return new Response(null, {
-          status: 302,
-          headers: {
-            Location: joinBasename(
-              options.app.routing.basename,
-              defaultClientRoute.path,
-            ),
-          },
-        })
-      }
-
-      if (url.pathname === options.app.routing.dataPath) {
-        return options.documents.loadRouteData(request)
-      }
-
-      if (isStaticFragmentRequest(url)) {
-        const sanitizedRequest = stripFlamefrontProtocolRequest(request)
-        const fragmentMatch = options.app.match(sanitizedRequest.url)
-
-        if (!fragmentMatch || fragmentMatch.data.render !== "static") {
-          return new Response("Not found", { status: 404 })
-        }
-
-        let artifact: StaticFragmentArtifact | undefined
-
+  const fetchEntry = createFetchServerEntry({
+    app: options.app,
+    documents: options.documents,
+    assets: {
+      loadTemplate,
+      loadStaticFragment: async ({ route }) => {
         try {
-          artifact = JSON.parse(
+          return JSON.parse(
             await readFile(
-              staticRouteFragmentDataFile(clientDirectory, fragmentMatch.data),
+              staticRouteFragmentDataFile(clientDirectory, route),
               "utf8",
             ),
-          ) as StaticFragmentArtifact
+          )
         } catch (error) {
           if ((error as { code?: string }).code !== "ENOENT") {
             throw error
           }
 
-          if (!options.documents.renderFragment) {
-            return new Response("Not found", { status: 404 })
-          }
-
-          artifact = await options.documents.renderFragment(sanitizedRequest)
+          return undefined
         }
-
-        const responseHeaders = new Headers({
-          "Content-Type":
-            "application/vnd.flamefront.fragment+json; charset=utf-8",
-        })
-
-        if (options.headers) {
-          mergeHeaders(
-            responseHeaders,
-            await options.headers({
-              request: sanitizedRequest,
-              route: fragmentMatch.data,
-              mode: "static",
-              document: {
-                html: artifact.html,
-                routeData: artifact.routeData,
-                status: artifact.status,
-              },
-            }),
-          )
-        }
-
-        return new Response(JSON.stringify(artifact), {
-          status: artifact.status ?? 200,
-          headers: responseHeaders,
-        })
-      }
-
-      if (!match) {
-        return new Response("Not found", { status: 404 })
-      }
-
-      const mode: DocumentMode = url.searchParams.has("__flamefront_shell")
-        ? "shell"
-        : match.data.render
-      const template = await loadTemplate({
-        request,
-        route: match.data,
-        mode,
-      })
-      const document = await options.documents.renderDocument(
-        template,
-        request,
-        { mode },
-      )
-      const responseHeaders = new Headers({
-        "Content-Type": "text/html; charset=utf-8",
-      })
-
-      mergeHeaders(responseHeaders, document.headers)
-      if (options.headers) {
-        mergeHeaders(
-          responseHeaders,
-          await options.headers({
-            request,
-            route: match.data,
-            mode,
-            document,
-          }),
-        )
-      }
-
-      return new Response(document.html, {
-        status: document.status ?? 200,
-        headers: responseHeaders,
-      })
-    } catch (error) {
-      if (error instanceof Response) {
-        return error
-      }
-
-      throw error
-    }
-  }
+      },
+    },
+    headers: options.headers,
+  })
 
   return {
-    fetch,
+    fetch: fetchEntry.fetch,
     middleware: [...(options.middleware ?? []), frameworkMiddleware],
-    renderDocument: options.documents.renderDocument,
-    loadRouteData: options.documents.loadRouteData,
-    renderFragment: options.documents.renderFragment,
+    renderDocument: fetchEntry.renderDocument,
+    loadRouteData: fetchEntry.loadRouteData,
+    renderFragment: fetchEntry.renderFragment,
   }
 }