flamefront 0.1.1 → 0.1.3

package/src/server.ts

@@ -9,6 +9,27 @@ import {
   type RouteDefinition,
 } from "./index.ts"
 import { stripFlamefrontProtocolRequest } from "./fragment-protocol.ts"
+import {
+  actionErrorResponse,
+  actionResultResponse,
+  executeRegisteredAction,
+  getRegisteredAction,
+  isSameOriginActionRequest,
+  parseActionArguments,
+} from "./action.ts"
+
+export { action } from "./action.ts"
+export type {
+  ActionDataWithResponseInit,
+  ActionFunction,
+  ActionInput,
+  ActionOutput,
+  ActionValidationError,
+  StandardSchema,
+  StandardSchemaIssue,
+  StandardSchemaV1,
+} from "./action.ts"
+export { data, redirect } from "@octanejs/remix-router"
 
 type LoaderPath<ContextOrPath, PathOrContext> =
   ContextOrPath extends `/${string}`
@@ -32,12 +53,24 @@ export interface LoaderArgs<ContextOrPath = unknown, PathOrContext = unknown> {
   readonly context: LoaderContext<ContextOrPath, PathOrContext>
 }
 
+/** Arguments passed to a page module's HTTP action. */
+export interface ActionArgs<
+  ContextOrPath = unknown,
+  PathOrContext = unknown,
+> extends LoaderArgs<ContextOrPath, PathOrContext> {}
+
 export type Loader<
   Data = unknown,
   Context = unknown,
   Path extends string = string,
 > = (args: LoaderArgs<Context, Path>) => Data | Promise<Data>
 
+export type RouteAction<
+  Data = unknown,
+  Context = unknown,
+  Path extends string = string,
+> = (args: ActionArgs<Context, Path>) => Data | Promise<Data>
+
 export interface RouteModule<
   Data = unknown,
   Context = unknown,
@@ -45,10 +78,11 @@ export interface RouteModule<
 > {
   readonly default: unknown
   readonly loader?: Loader<Data, Context, Path>
+  readonly action?: RouteAction<unknown, Context, Path>
 }
 
 export type DocumentMode = "shell" | RenderMode
-export type RequestPurpose = "data" | "document"
+export type RequestPurpose = "data" | "document" | "action"
 
 /** Inputs for constructing one request-scoped value for route work. */
 export interface RequestContextArgs<
@@ -71,7 +105,10 @@ export type RouteImporter<
   Data = unknown,
   Context = unknown,
   Path extends string = string,
-> = (entry: string) => Promise<RouteModule<Data, Context, Path>>
+> = ((entry: string) => Promise<RouteModule<Data, Context, Path>>) & {
+  /** Optional eager import hook used by generated server action registries. */
+  readonly loadActions?: () => void | Promise<void>
+}
 
 export interface RenderedDocument {
   readonly html: string
@@ -156,6 +193,7 @@ export interface RouteRuntime<
     options?: RouteLoadOptions<Context>,
   ) => Promise<LoadedRouteFor<Route, Context> | null>
   readonly loadRouteData: (request: Request) => Promise<Response>
+  readonly loadAction: (request: Request) => Promise<Response>
 }
 
 export interface RouteRuntimeOptions<
@@ -164,6 +202,8 @@ export interface RouteRuntimeOptions<
 > {
   readonly app: AppDefinition<Route>
   readonly importRoute: RouteImporter<unknown, Context>
+  /** Eagerly load generated action modules before direct dispatch. */
+  readonly loadActions?: () => void | Promise<void>
   /** Build request context for data requests and document router queries. */
   readonly requestContext?: RequestContextFactory<Context, Route>
 }
@@ -279,6 +319,71 @@ export function createRouteRuntime<
     return Response.json(loaded.loaderData ?? null)
   }
 
+  const loadAction = async (request: Request): Promise<Response> => {
+    const sanitizedRequest = stripFlamefrontProtocolRequest(request)
+    const url = new URL(sanitizedRequest.url)
+
+    if (["GET", "HEAD", "OPTIONS"].includes(sanitizedRequest.method)) {
+      return new Response("Method not allowed.", { status: 405 })
+    }
+
+    if (!isSameOriginActionRequest(sanitizedRequest)) {
+      return new Response("Forbidden.", { status: 403 })
+    }
+
+    const actionId = url.searchParams.get("action")
+
+    if (actionId) {
+      try {
+        const args = await parseActionArguments(sanitizedRequest)
+
+        if (!getRegisteredAction(actionId)) {
+          await (options.loadActions ?? options.importRoute.loadActions)?.()
+        }
+
+        return await executeRegisteredAction(actionId, args)
+      } catch (error) {
+        return actionErrorResponse(error)
+      }
+    }
+
+    const match = options.app.match(sanitizedRequest.url)
+
+    if (!match) {
+      return new Response("Not found.", { status: 404 })
+    }
+
+    if (match.data.render === "static") {
+      return new Response(
+        "Static routes cannot define actions; submit to a server route instead.",
+        { status: 405 },
+      )
+    }
+
+    const routeModule = await options.importRoute(match.data.entry)
+
+    if (!routeModule.action) {
+      return new Response("Method not allowed.", { status: 405 })
+    }
+
+    try {
+      const context = await createRequestContext(
+        sanitizedRequest,
+        { purpose: "action", mode: match.data.render },
+        match,
+      )
+      const value = await routeModule.action({
+        request: sanitizedRequest,
+        params: match.params as ActionArgs<Context, string>["params"],
+        context: context as LoaderContext<Context, string>,
+      })
+
+      return actionResultResponse(value)
+    } catch (error) {
+      return actionErrorResponse(error)
+    }
+  }
+
   return {
     app: options.app,
     importRoute: options.importRoute,
@@ -287,6 +392,7 @@ export function createRouteRuntime<
       createRequestContext(request, contextOptions),
     loadRoute: loadRouteForRequest,
     loadRouteData,
+    loadAction,
   }
 }
 

package/src/srvx.ts

@@ -133,6 +133,10 @@ export function createSrvxServerEntry<
       return next()
     }
 
+    if (!["GET", "HEAD", "OPTIONS"].includes(request.method)) {
+      return next()
+    }
+
     return serveClientFile(
       staticRequest(request, options.app.routing.basename),
       next,
@@ -169,6 +173,7 @@ export function createSrvxServerEntry<
     middleware: [...(options.middleware ?? []), frameworkMiddleware],
     renderDocument: fetchEntry.renderDocument,
     loadRouteData: fetchEntry.loadRouteData,
+    ...(fetchEntry.loadAction ? { loadAction: fetchEntry.loadAction } : {}),
     renderFragment: fetchEntry.renderFragment,
   }
 }

package/src/static-fragment-artifacts.ts

@@ -12,17 +12,17 @@ function isWithin(directory: string, filePath: string): boolean {
   )
 }
 
-function staticRoutePath(
+export function staticRoutePathForPath(
   clientDirectory: string,
-  route: RouteDefinition,
+  routePath: string,
 ): string {
-  if (/[:*]/.test(route.path)) {
+  if (/[:*]/.test(routePath)) {
     throw new Error(
-      `Cannot prerender parameterized static route ${JSON.stringify(route.path)} without concrete paths.`,
+      `Cannot prerender parameterized static route ${JSON.stringify(routePath)} without concrete paths.`,
     )
   }
 
-  const segments = route.path
+  const segments = routePath
     .split("/")
     .filter(Boolean)
     .map((segment) => decodeURIComponent(segment))
@@ -33,7 +33,7 @@ function staticRoutePath(
     )
   ) {
     throw new Error(
-      `Cannot write unsafe static route path ${JSON.stringify(route.path)}.`,
+      `Cannot write unsafe static route path ${JSON.stringify(routePath)}.`,
     )
   }
 
@@ -41,13 +41,20 @@ function staticRoutePath(
 
   if (!isWithin(clientDirectory, filePath)) {
     throw new Error(
-      `Cannot write static route outside the client build: ${JSON.stringify(route.path)}.`,
+      `Cannot write static route outside the client build: ${JSON.stringify(routePath)}.`,
     )
   }
 
   return filePath
 }
 
+function staticRoutePath(
+  clientDirectory: string,
+  route: RouteDefinition,
+): string {
+  return staticRoutePathForPath(clientDirectory, route.path)
+}
+
 export function staticRouteFile(
   clientDirectory: string,
   route: RouteDefinition,

package/src/virtual-remix-routes.d.ts

@@ -17,6 +17,7 @@ declare module "virtual:flamefront/server-routes" {
   import type { RouteModule } from "./server.ts"
 
   export function importRoute(entry: string): Promise<RouteModule>
+  export function loadActions(): Promise<void>
 }
 
 declare module "virtual:flamefront/server-entry" {

package/src/vite-options.ts

@@ -0,0 +1,29 @@
+import type { PrerenderOptions } from "./prerender.ts"
+
+export interface RegisteredFlamefrontOptions {
+  readonly prerender?: PrerenderOptions
+  readonly markdown?: unknown
+  readonly target?: string
+}
+
+const byRoot = new Map<string, RegisteredFlamefrontOptions>()
+let pending: RegisteredFlamefrontOptions | undefined
+
+export function registerFlamefrontOptions(
+  options: RegisteredFlamefrontOptions,
+): void {
+  pending = options
+}
+
+export function registerFlamefrontRoot(
+  root: string,
+  options: RegisteredFlamefrontOptions,
+): void {
+  byRoot.set(root, options)
+}
+
+export function getFlamefrontOptions(
+  root: string,
+): RegisteredFlamefrontOptions | undefined {
+  return byRoot.get(root) ?? pending
+}

package/src/vite.ts

@@ -15,12 +15,22 @@ import type {
 import { generate, parse, traverse, type Babel } from "./babel.ts"
 import { expandGlob, globDirectory, setGlobRoot } from "./glob.ts"
 import { removeExports } from "./remove-exports.ts"
+import {
+  findActionExports,
+  generateActionProxyModule,
+  transformServerActions,
+} from "./action-transform.ts"
 import { writeRouteImportMap } from "./typegen.ts"
 import {
   resolveFlamefrontOutput,
   type FlamefrontOutputOptions,
   type ResolvedFlamefrontOutput,
 } from "./output.ts"
+import type { PrerenderOptions } from "./prerender.ts"
+import {
+  registerFlamefrontOptions,
+  registerFlamefrontRoot,
+} from "./vite-options.ts"
 
 export type {
   FlamefrontAdapter,
@@ -37,11 +47,13 @@ const resolvedServerRoutesId = `\0${serverRoutesId}`
 
 export const serverEntryId = "virtual:flamefront/server-entry"
 const resolvedServerEntryId = `\0${serverEntryId}`
+const actionProxyId = "\0flamefront/action-proxy"
+const actionProxyPrefix = `${actionProxyId}?module=`
 const hydrationRouteId = "/@flamefront/hydration-route.tsrx"
 const resolvedHydrationRoutePrefix = `${hydrationRouteId}?`
 const markdownRouteId = "/@flamefront/markdown-route.tsrx"
 const resolvedMarkdownRoutePrefix = `${markdownRouteId}?`
-const SERVER_ONLY_ROUTE_EXPORTS = ["loader"] as const
+const SERVER_ONLY_ROUTE_EXPORTS = ["loader", "action"] as const
 const serverFilePattern = /\.server(?:\.[cm]?[jt]sx?|\.tsrx)$/
 const serverDirectoryPattern = /\/\.server\//
 
@@ -50,6 +62,8 @@ export interface FlamefrontOptions extends FlamefrontOutputOptions {
   readonly routes?: string
   /** Built-in Markdown and MDX compiler configuration. */
   readonly markdown?: false | MarkdownOptions
+  /** Configure incremental static rendering and its persistent cache. */
+  readonly prerender?: PrerenderOptions
 }
 
 export interface MarkdownOptions {
@@ -210,21 +224,22 @@ function lazyRoute(
     routeDefinition.render === "client"
       ? `(args) => ${browserLoader}(args, ${JSON.stringify(routing)})`
       : `(args) => ${browserLoader}(args, ${JSON.stringify(routing)}, ${quote(routeDefinition.render)})`
+  const browserActionExpression = `(args) => submitRouteAction(args, ${JSON.stringify(routing)})`
 
   if (routeDefinition.render !== "client") {
     const componentId = browserRouteModuleId(routeDefinition)
 
-    return `async () => { if (import.meta.env.SSR) { const [routeModule, componentModule] = await Promise.all([import(${quote(entry)}), import(${quote(componentId)})]); return { Component: createRouteBoundary(componentModule.default, ${JSON.stringify(metadata)}), loader: routeModule.loader }; } const componentModule = await import(${quote(componentId)}); return { Component: createRouteFragmentRoute({ metadata: ${JSON.stringify(metadata)}, routing: ${JSON.stringify(routing)}, policy: ${quote(routeDefinition.render)}, fallbackComponent: componentModule.default }), loader: ${browserLoaderExpression} }; }`
+    return `async () => { if (import.meta.env.SSR) { const [routeModule, componentModule] = await Promise.all([import(${quote(entry)}), import(${quote(componentId)})]); return { Component: createRouteBoundary(componentModule.default, ${JSON.stringify(metadata)}), loader: routeModule.loader, action: routeModule.action }; } const componentModule = await import(${quote(componentId)}); return { Component: createRouteFragmentRoute({ metadata: ${JSON.stringify(metadata)}, routing: ${JSON.stringify(routing)}, policy: ${quote(routeDefinition.render)}, fallbackComponent: componentModule.default }), loader: ${browserLoaderExpression}, action: ${browserActionExpression} }; }`
   }
 
   if (routeDefinition.render === "client") {
     if (routeDefinition.content === "markdown") {
       const componentId = browserRouteModuleId(routeDefinition)
 
-      return `async () => { if (import.meta.env.SSR) return {}; const componentModule = await import(${quote(componentId)}); return { Component: createRouteBoundary(componentModule.default, ${JSON.stringify(metadata)}), loader: ${browserLoaderExpression} }; }`
+      return `async () => { if (import.meta.env.SSR) return {}; const componentModule = await import(${quote(componentId)}); return { Component: createRouteBoundary(componentModule.default, ${JSON.stringify(metadata)}), loader: ${browserLoaderExpression}, action: ${browserActionExpression} }; }`
     }
 
-    return `async () => { if (import.meta.env.SSR) return {}; const routeModule = await import(${quote(entry)}); return { Component: createRouteBoundary(routeModule.default, ${JSON.stringify(metadata)}), loader: ${browserLoaderExpression} }; }`
+    return `async () => { if (import.meta.env.SSR) return {}; const routeModule = await import(${quote(entry)}); return { Component: createRouteBoundary(routeModule.default, ${JSON.stringify(metadata)}), loader: ${browserLoaderExpression}, action: ${browserActionExpression} }; }`
   }
 
   throw new Error(`Unsupported route render mode ${routeDefinition.render}.`)
@@ -290,6 +305,12 @@ function generateConfigs(
         return `${indent}{\n${childIndent}id: ${quote(metadata.id)},\n${childIndent}lazy: ${lazyLayout(config.entry, metadata)},\n${childIndent}handle: { flamefront: ${JSON.stringify(metadata)} },\n${childIndent}children: [\n${generateConfigs(config.children, routing, depth + 2, metadata.id, location)}\n${childIndent}],\n${indent}}`
       }
 
+      if (/\.(md|mdx)$/.test(cleanModuleId(config.entry))) {
+        const lazy = lazyRoute(config, routing, metadata)
+
+        return `${indent}{\n${childIndent}id: ${quote(metadata.id)},\n${childIndent}path: ${quote(config.path)},\n${childIndent}lazy: async () => { const [routeModule, resolved] = await Promise.all([import(${quote(config.entry)}), (${lazy})()]); return { ...resolved, handle: { flamefront: ${JSON.stringify(metadata)}, frontmatter: routeModule.frontmatter ?? {} } }; },\n${indent}}`
+      }
+
       return `${indent}{\n${childIndent}id: ${quote(metadata.id)},\n${childIndent}path: ${quote(config.path)},\n${childIndent}lazy: ${lazyRoute(config, routing, metadata)},\n${childIndent}handle: { flamefront: ${JSON.stringify(metadata)} },\n${indent}}`
     })
     .join(",\n")
@@ -308,19 +329,31 @@ export function generateRemixRoutes(
     app.shellHydration,
   )
 
-  return `// Generated by Flamefront.\nimport Shell from ${quote(app.shell)};\nimport { RouterDocument } from 'flamefront/octane/router-document';\nimport { createRouteBoundary, createRouteFragmentRoute } from 'flamefront/fragment';\nimport { loadRouteData, loadRouteFragment } from 'flamefront/remix-router/data';\n\nexport { RouterDocument };\nexport const routing = ${JSON.stringify(app.routing)};\nexport const routeMetadata = ${JSON.stringify(routeMetadata)};\n\nexport const routes = [\n\t{\n\t\tid: ${quote(rootId)},\n\t\tComponent: createRouteBoundary(Shell, ${JSON.stringify(routeMetadata[0])}),\n\t\thandle: { flamefront: ${JSON.stringify(routeMetadata[0])} },\n\t\tchildren: [\n${generateConfigs(app.routeTree, app.routing, 3)}\n\t\t],\n\t},\n];\n\n${generateRoutePreloaders(app.routeTree)}`
+  return `// Generated by Flamefront.\nimport Shell from ${quote(app.shell)};\nimport { RouterDocument } from 'flamefront/octane/router-document';\nimport { createRouteBoundary, createRouteFragmentRoute } from 'flamefront/fragment';\nimport { loadRouteData, loadRouteFragment } from 'flamefront/remix-router/data';\nimport { submitRouteAction } from 'flamefront/remix-router/data';\n\nexport { RouterDocument };\nexport const routing = ${JSON.stringify(app.routing)};\nexport const routeMetadata = ${JSON.stringify(routeMetadata)};\n\nexport const routes = [\n\t{\n\t\tid: ${quote(rootId)},\n\t\tComponent: createRouteBoundary(Shell, ${JSON.stringify(routeMetadata[0])}),\n\t\thandle: { flamefront: ${JSON.stringify(routeMetadata[0])} },\n\t\tchildren: [\n${generateConfigs(app.routeTree, app.routing, 3)}\n\t\t],\n\t},\n];\n\n${generateRoutePreloaders(app.routeTree)}`
 }
 
 /** Generate the server-only route-module importer used by loader endpoints. */
 export function generateServerRoutes(
-  app: Pick<AppDefinition, "routes">,
+  app: Pick<AppDefinition, "routes" | "shell" | "routeTree">,
 ): string {
-  const entries = [...new Set(app.routes.map((route) => route.entry))]
-  const imports = entries
+  const entries = new Set<string>([app.shell])
+  const collect = (configs: readonly RouteConfig[]) => {
+    for (const config of configs) {
+      entries.add(config.entry)
+
+      if ("children" in config) {
+        collect(config.children)
+      }
+    }
+  }
+
+  collect(app.routeTree)
+
+  const imports = [...entries]
     .map((entry) => `\t${quote(entry)}: () => import(${quote(entry)})`)
     .join(",\n")
 
-  return `// Generated by Flamefront.\nconst routeModules = {\n${imports}\n};\n\nexport async function importRoute(entry) {\n\tconst importModule = routeModules[entry];\n\tif (!importModule) throw new Error(\`No Vite route module was generated for \${entry}.\`);\n\treturn importModule();\n}\n`
+  return `// Generated by Flamefront.\nconst routeModules = {\n${imports}\n};\n\nlet actionModulesPromise;\nexport function loadActions() {\n\tactionModulesPromise ??= Promise.all(Object.values(routeModules).map((load) => load())).then(() => undefined);\n\treturn actionModulesPromise;\n}\n\nexport async function importRoute(entry) {\n\tconst importModule = routeModules[entry];\n\tif (!importModule) throw new Error(\`No Vite route module was generated for \${entry}.\`);\n\treturn importModule();\n}\n\nimportRoute.loadActions = loadActions;\n`
 }
 
 /** Generate the server-entry import selected by `flamefront({...})`. */
@@ -556,7 +589,7 @@ function isPathWithinDirectory(directory: string, candidate: string): boolean {
 }
 
 function isServerEnvironment(
-  context: PluginContext,
+  context: Pick<PluginContext, "environment">,
   options?: TransformOptions,
 ): boolean {
   return (
@@ -684,6 +717,12 @@ export function removeServerRouteExports(source: string, id = "route.js") {
 
 export function flamefront(options: FlamefrontOptions = {}) {
   const output = resolveFlamefrontOutput(options)
+
+  registerFlamefrontOptions({
+    prerender: options.prerender,
+    markdown: options.markdown,
+    target: options.target,
+  })
   let root = process.cwd()
   let serverBuild = false
   let appPromise: Promise<AppDefinition> | undefined
@@ -723,6 +762,11 @@ export function flamefront(options: FlamefrontOptions = {}) {
     writeRouteImportMap(await loadApp(), { root })
   const configureRoot = (config: { readonly root: string }) => {
     root = config.root
+    registerFlamefrontRoot(root, {
+      prerender: options.prerender,
+      markdown: options.markdown,
+      target: options.target,
+    })
   }
 
   const frameworkModulesPlugin = {
@@ -732,7 +776,44 @@ export function flamefront(options: FlamefrontOptions = {}) {
     async buildStart() {
       await generateTypes()
     },
-    transform(source: string, id: string) {
+    transform(
+      this: object,
+      source: string,
+      id: string,
+      transformOptions?: TransformOptions,
+    ) {
+      const context = this as Pick<PluginContext, "environment">
+
+      if (
+        isServerEnvironment(context, transformOptions) &&
+        !cleanModuleId(id).endsWith(".tsrx") &&
+        source.includes("action") &&
+        /flamefront(?:\/server)?["']/.test(source)
+      ) {
+        const transformedActions = transformServerActions(source, id)
+
+        if (transformedActions) {
+          return {
+            code: transformedActions.code,
+            map: transformedActions.map,
+          }
+        }
+      }
+
+      if (
+        !cleanModuleId(id).endsWith(".tsrx") &&
+        source.includes("action") &&
+        /flamefront(?:\/server)?["']/.test(source)
+      ) {
+        const clientActions = findActionExports(source, id)
+
+        if (clientActions.length > 0) {
+          throw new Error(
+            `Flamefront actions must be declared in a *.server.ts module: ${JSON.stringify(path.relative(root, cleanModuleId(id)) || id)}.`,
+          )
+        }
+      }
+
       if (cleanModuleId(id) !== manifestPath()) {
         return null
       }
@@ -836,6 +917,10 @@ export function flamefront(options: FlamefrontOptions = {}) {
         return id
       }
 
+      if (id.startsWith(actionProxyPrefix)) {
+        return id
+      }
+
       if (
         resolveOptions.scan ||
         isServerEnvironment(this, resolveOptions) ||
@@ -867,10 +952,26 @@ export function flamefront(options: FlamefrontOptions = {}) {
         return null
       }
 
+      let actionSource: string
+
+      try {
+        actionSource = fs.readFileSync(resolvedId, "utf8")
+      } catch {
+        actionSource = ""
+      }
+
+      if (actionSource) {
+        const actions = findActionExports(actionSource, resolvedId)
+
+        if (actions.length > 0) {
+          return `${actionProxyPrefix}${encodeURIComponent(resolvedId)}`
+        }
+      }
+
       const importerId = cleanModuleId(importer)
       const importerLabel = path.relative(root, importerId) || importerId
       const routeHint = (await loadRouteModuleIds()).has(importerId)
-        ? " Flamefront removes server imports used exclusively by `loader`, but this import is still referenced by client code."
+        ? " Flamefront removes server imports used exclusively by `loader` or `action`, but this import is still referenced by client code."
         : ""
 
       throw new Error(
@@ -918,6 +1019,23 @@ export function flamefront(options: FlamefrontOptions = {}) {
         return generateMarkdownRoute(entry)
       }
 
+      if (id.startsWith(actionProxyPrefix)) {
+        const moduleId = new URLSearchParams(
+          id.slice(actionProxyId.length + 1),
+        ).get("module")
+
+        if (!moduleId) {
+          throw new TypeError("Flamefront action proxy is missing its module.")
+        }
+
+        const source = fs.readFileSync(moduleId, "utf8")
+
+        return generateActionProxyModule(
+          findActionExports(source, moduleId),
+          (await loadApp()).routing,
+        )
+      }
+
       return null
     },
   }