gorsee 0.2.0 → 0.2.2

package/src/cli/framework-md.ts

@@ -35,29 +35,56 @@ app.config.ts    Configuration
 ## Imports
 
 \`\`\`typescript
-// Reactivity
-import { createSignal, createComputed, createEffect, createResource, createStore } from "gorsee/reactive"
+// Browser-safe route code
+import { createSignal, createComputed, createEffect, createResource, createStore } from "gorsee/client"
 
-// Types (compile-time safety)
-import { SafeSQL } from "gorsee/types"           // SQL injection = compile error
-import { SafeHTML, sanitize } from "gorsee/types" // XSS = compile error
-import { SafeURL, validateURL } from "gorsee/types"
-import { validate, type UserInput } from "gorsee/types"
+// Server-only code
+import { server, middleware, type Context, createDB, createAuth, cors, log } from "gorsee/server"
+\`\`\`
 
-// Database
-import { createDB } from "gorsee/db"
+## Import Boundaries
 
-// Server functions
-import { server } from "gorsee/server"
-import { middleware, type Context } from "gorsee/server"
+- \`gorsee/client\` for route components, islands, navigation, forms, and reactive primitives
+- \`gorsee/server\` for middleware, loaders, RPC, auth, db, security, env, and logging
+- Root \`gorsee\` is compatibility-only and should not be used in new code
+- \`gorsee/compat\` is available as an explicit legacy migration entrypoint
+
+## Adapter Recipes
 
-// Logging
-import { log } from "gorsee/log"
+\`\`\`typescript
+import { createClient } from "redis"
+import {
+  createAuth,
+  createRedisSessionStore,
+  createRedisCacheStore,
+  createNodeRedisLikeClient,
+  routeCache,
+} from "gorsee/server"
+
+const redis = createClient({ url: process.env.REDIS_URL })
+await redis.connect()
+const redisClient = createNodeRedisLikeClient(redis)
+
+const auth = createAuth({
+  secret: process.env.SESSION_SECRET!,
+  store: createRedisSessionStore(redisClient, { prefix: "app:sessions" }),
+})
 
-// Escape hatches (DANGER)
-import { unsafeSQL, unsafeHTML } from "gorsee/unsafe"
+export const cache = routeCache({
+  maxAge: 60,
+  staleWhileRevalidate: 300,
+  store: createRedisCacheStore(redisClient, {
+    prefix: "app:cache",
+    maxEntryAgeMs: 360_000,
+  }),
+})
 \`\`\`
 
+- SQLite adapters are the default persistent single-node path
+- Redis adapters are the default multi-instance path
+- \`createNodeRedisLikeClient()\` and \`createIORedisLikeClient()\` normalize real Redis SDK clients to the framework adapter contract
+- RPC handlers remain process-local by design; do not try to distribute closures through Redis
+
 ## Patterns
 
 ### Page Route

package/src/cli/index.ts

@@ -15,6 +15,9 @@ const COMMANDS: Record<string, string> = {
   generate: "Generate CRUD scaffold for entity",
   typegen: "Generate typed route definitions",
   deploy: "Generate deploy config (vercel/fly/cloudflare/netlify/docker)",
+  test: "Run tests (unit/integration/e2e)",
+  docs: "Generate API documentation from routes",
+  upgrade: "Upgrade Gorsee.js to latest version",
   help: "Show this help message",
 }
 
@@ -60,6 +63,21 @@ async function main() {
       const { runDeploy } = await import("./cmd-deploy.ts")
       await runDeploy(args.slice(1))
       break
+    case "test": {
+      const { runTest } = await import("./cmd-test.ts")
+      await runTest(args.slice(1))
+      break
+    }
+    case "docs": {
+      const { runDocs } = await import("./cmd-docs.ts")
+      await runDocs(args.slice(1))
+      break
+    }
+    case "upgrade": {
+      const { runUpgrade } = await import("./cmd-upgrade.ts")
+      await runUpgrade(args.slice(1))
+      break
+    }
     case "help":
     case undefined:
     case "--help":

package/src/client.ts

@@ -0,0 +1,26 @@
+// Explicit browser-safe public entrypoint.
+// Use this in route components and client-facing modules.
+
+export {
+  createSignal,
+  createComputed,
+  createEffect,
+  createResource,
+  createStore,
+  createLive,
+  invalidateResource,
+  invalidateAll,
+  createMutation,
+} from "./reactive/index.ts"
+
+export { Suspense } from "./runtime/suspense.ts"
+export { Link } from "./runtime/link.ts"
+export { Head } from "./runtime/head.ts"
+export { navigate, onNavigate, beforeNavigate, getCurrentPath } from "./runtime/router.ts"
+export { useFormAction } from "./runtime/form.ts"
+export { Image } from "./runtime/image.ts"
+export { ErrorBoundary } from "./runtime/error-boundary.ts"
+export { island } from "./runtime/island.ts"
+export { createEventSource } from "./server/sse.ts"
+export { typedLink, typedNavigate } from "./runtime/typed-routes.ts"
+export { defineForm, validateForm, fieldAttrs } from "./runtime/validated-form.ts"

package/src/dev/partial-handler.ts

@@ -2,8 +2,12 @@
 // Returns JSON with rendered HTML + metadata instead of full page
 
 import { createContext } from "../server/middleware.ts"
-import { renderToString, ssrJsx } from "../runtime/server.ts"
-import { resetServerHead, getServerHead } from "../runtime/head.ts"
+import {
+  buildPartialResponsePayload,
+  createClientScriptPath,
+  renderPageDocument,
+  resolvePageRoute,
+} from "../server/page-render.ts"
 import type { MatchResult } from "../router/matcher.ts"
 import type { BuildResult } from "../build/client.ts"
 
@@ -13,15 +17,6 @@ interface PartialRenderOptions {
   clientBuild: BuildResult
 }
 
-interface PartialResponse {
-  html: string
-  data?: unknown
-  params?: Record<string, string>
-  title?: string
-  css?: string[]
-  script?: string
-}
-
 export async function handlePartialNavigation(opts: PartialRenderOptions): Promise<Response> {
   const { match, request, clientBuild } = opts
   const mod = await import(match.route.filePath)
@@ -32,76 +27,24 @@ export async function handlePartialNavigation(opts: PartialRenderOptions): Promi
     return new Response("Not a page route", { status: 400 })
   }
 
-  const component = mod.default as Function | undefined
-  if (typeof component !== "function") {
+  const resolved = await resolvePageRoute(mod, match, ctx)
+  if (!resolved) {
     return new Response(JSON.stringify({ error: "Route has no default export" }), {
       status: 500,
       headers: { "Content-Type": "application/json" },
     })
   }
 
-  // Parallel loading: import layout modules + run page loader simultaneously
-  const layoutPaths = match.route.layoutPaths ?? []
-  const layoutImportPromises = layoutPaths.map((lp) => import(lp))
-  const pageLoaderPromise = typeof mod.loader === "function" ? mod.loader(ctx) : undefined
-
-  const [layoutMods, loaderData] = await Promise.all([
-    Promise.all(layoutImportPromises),
-    pageLoaderPromise,
-  ])
-
-  // Run layout loaders in parallel
-  const layoutLoaderPromises = layoutMods.map((lm) =>
-    typeof lm.loader === "function" ? lm.loader(ctx) : undefined,
+  const { pageComponent, loaderData, cssFiles } = resolved
+  const rendered = renderPageDocument(pageComponent, ctx, match.params, loaderData)
+  const clientScript = createClientScriptPath(clientBuild.entryMap.get(match.route.path))
+  const result = buildPartialResponsePayload(
+    rendered,
+    loaderData,
+    match.params,
+    cssFiles,
+    clientScript,
   )
-  const layoutLoaderResults = await Promise.all(layoutLoaderPromises)
-
-  // CSS
-  const cssFiles: string[] = []
-  if (typeof mod.css === "string") cssFiles.push(mod.css)
-  if (Array.isArray(mod.css)) cssFiles.push(...(mod.css as string[]))
-
-  // Nested layout wrapping: outermost first, innermost wraps page
-  let pageComponent: Function = component
-  for (let i = layoutMods.length - 1; i >= 0; i--) {
-    const Layout = layoutMods[i]!.default
-    if (typeof Layout === "function") {
-      const inner = pageComponent
-      const layoutData = layoutLoaderResults[i]
-      pageComponent = (props: Record<string, unknown>) =>
-        Layout({ ...props, data: layoutData, children: inner(props) })
-    }
-  }
-
-  // Render
-  resetServerHead()
-  const pageProps = { params: match.params, ctx, data: loaderData }
-  const vnode = ssrJsx(pageComponent as any, pageProps)
-  const html = renderToString(vnode)
-
-  // Extract title from Head component
-  const headElements = getServerHead()
-  let title: string | undefined
-  for (const el of headElements) {
-    const titleMatch = el.match(/<title>(.+?)<\/title>/)
-    if (titleMatch) {
-      title = titleMatch[1]
-      break
-    }
-  }
-
-  // Client JS path
-  const clientJsFile = clientBuild.entryMap.get(match.route.path)
-  const clientScript = clientJsFile ? `/_gorsee/${clientJsFile}` : undefined
-
-  const result: PartialResponse = {
-    html,
-    data: loaderData,
-    params: Object.keys(match.params).length > 0 ? match.params : undefined,
-    title,
-    css: cssFiles.length > 0 ? cssFiles : undefined,
-    script: clientScript,
-  }
 
   return new Response(JSON.stringify(result), {
     headers: { "Content-Type": "application/json" },

package/src/dev/request-handler.ts

@@ -1,10 +1,13 @@
 // Page route request handler — SSR + streaming + layouts + loaders
 
-import { createContext, runMiddlewareChain, RedirectError, type MiddlewareFn } from "../server/middleware.ts"
+import { createContext } from "../server/middleware.ts"
 import { renderToString, ssrJsx } from "../runtime/server.ts"
 import { renderToStream, streamJsx } from "../runtime/stream.ts"
+import { resetServerHead, getServerHead } from "../runtime/head.ts"
 import { handleAction } from "../server/action.ts"
 import { log } from "../log/index.ts"
+import { createClientScriptPath, renderPageDocument, resolvePageRoute } from "../server/page-render.ts"
+import { handleRouteRequest } from "../server/route-request.ts"
 import type { MatchResult } from "../router/matcher.ts"
 import type { BuildResult } from "../build/client.ts"
 
@@ -15,7 +18,7 @@ interface RenderOptions {
   start: number
   clientBuild: BuildResult
   secHeaders: Record<string, string>
-  wrapHTML: (body: string, nonce: string, opts?: { title?: string; clientScript?: string; loaderData?: unknown; params?: Record<string, string>; cssFiles?: string[] }) => string
+  wrapHTML: (body: string, nonce: string, opts?: { title?: string; clientScript?: string; loaderData?: unknown; params?: Record<string, string>; cssFiles?: string[]; headElements?: string[] }) => string
 }
 
 async function renderPageRoute(mod: Record<string, unknown>, opts: RenderOptions): Promise<Response> {
@@ -47,49 +50,24 @@ async function renderPageRoute(mod: Record<string, unknown>, opts: RenderOptions
     return new Response("Route has no default export", { status: 500 })
   }
 
-  // Parallel loading: import layout modules + run page loader simultaneously
-  const layoutPaths = match.route.layoutPaths ?? []
-  const layoutImportPromises = layoutPaths.map((lp) => import(lp))
-  const pageLoaderPromise = typeof mod.loader === "function" ? mod.loader(ctx) : undefined
-
-  const [layoutMods, loaderData] = await Promise.all([
-    Promise.all(layoutImportPromises),
-    pageLoaderPromise,
-  ])
-
-  // Run layout loaders in parallel
-  const layoutLoaderPromises = layoutMods.map((lm) =>
-    typeof lm.loader === "function" ? lm.loader(ctx) : undefined,
-  )
-  const layoutLoaderResults = await Promise.all(layoutLoaderPromises)
-
-  // CSS
-  const cssFiles: string[] = []
-  if (typeof mod.css === "string") cssFiles.push(mod.css)
-  if (Array.isArray(mod.css)) cssFiles.push(...(mod.css as string[]))
-
-  // Nested layout wrapping: outermost first, innermost wraps page
-  let pageComponent: Function = component
-  for (let i = layoutMods.length - 1; i >= 0; i--) {
-    const Layout = layoutMods[i]!.default
-    if (typeof Layout === "function") {
-      const inner = pageComponent
-      const layoutData = layoutLoaderResults[i]
-      pageComponent = (props: Record<string, unknown>) =>
-        Layout({ ...props, data: layoutData, children: inner(props) })
-    }
+  const resolved = await resolvePageRoute(mod, match, ctx)
+  if (!resolved) {
+    return new Response("Route has no default export", { status: 500 })
   }
 
+  const { pageComponent, loaderData, cssFiles, renderMode } = resolved
   const pageProps = { params: match.params, ctx, data: loaderData }
-  const renderMode = (mod.render as string) ?? "async"
-  const clientJsFile = clientBuild.entryMap.get(match.route.path)
-  const clientScript = clientJsFile ? `/_gorsee/${clientJsFile}` : undefined
+  const clientScript = createClientScriptPath(clientBuild.entryMap.get(match.route.path))
   const htmlOpts = { clientScript, loaderData, params: match.params, cssFiles }
 
   if (renderMode === "stream") {
+    resetServerHead()
     const vnode = streamJsx(pageComponent as any, pageProps)
     const stream = renderToStream(vnode, {
-      shell: (body: string) => wrapHTML(body, nonce, htmlOpts),
+      shell: (body: string) => wrapHTML(body, nonce, {
+        ...htmlOpts,
+        headElements: getServerHead(),
+      }),
     })
     const elapsed = (performance.now() - start).toFixed(1)
     log.info("request", { method: request.method, path: match.route.path, status: 200, ms: elapsed, mode: "stream" })
@@ -99,9 +77,11 @@ async function renderPageRoute(mod: Record<string, unknown>, opts: RenderOptions
   }
 
   // Default: async SSR
-  const vnode = ssrJsx(pageComponent as any, pageProps)
-  const body = renderToString(vnode)
-  const html = wrapHTML(body, nonce, htmlOpts)
+  const rendered = renderPageDocument(pageComponent, ctx, match.params, loaderData)
+  const html = wrapHTML(rendered.html, nonce, {
+    ...htmlOpts,
+    headElements: rendered.headElements,
+  })
   const elapsed = (performance.now() - start).toFixed(1)
   log.info("request", { method: request.method, path: match.route.path, status: 200, ms: elapsed })
 
@@ -112,33 +92,22 @@ async function renderPageRoute(mod: Record<string, unknown>, opts: RenderOptions
 
 export async function handlePageRequest(opts: RenderOptions): Promise<Response> {
   const { match, request } = opts
-  const mod = await import(match.route.filePath)
-
-  // Middleware chain (inherited from parent directories)
-  const middlewares: MiddlewareFn[] = []
-  for (const mwPath of match.route.middlewarePaths) {
-    const mwMod = await import(mwPath)
-    if (typeof mwMod.default === "function") middlewares.push(mwMod.default)
-  }
-
-  const ctx = createContext(request, match.params)
-  try {
-    return await runMiddlewareChain(middlewares, ctx, () => renderPageRoute(mod, opts))
-  } catch (err) {
-    // Redirect from loader/action (throw redirect("/path"))
-    if (err instanceof RedirectError) {
-      return new Response(null, {
-        status: err.status,
-        headers: { Location: err.url },
-      })
-    }
-    // Error boundary: render _error.tsx if available
-    if (match.route.errorPath) {
-      const errObj = err instanceof Error ? err : new Error(String(err))
-      return renderErrorBoundary(match.route.errorPath, errObj, opts)
-    }
-    throw err
-  }
+  return handleRouteRequest({
+    match,
+    request,
+    onPartialRequest: async () => {
+      const { handlePartialNavigation } = await import("./partial-handler.ts")
+      return handlePartialNavigation({ match, request, clientBuild: opts.clientBuild })
+    },
+    onPageRequest: async ({ mod }) => renderPageRoute(mod, opts),
+    onRouteError: async (err) => {
+      if (match.route.errorPath) {
+        const errObj = err instanceof Error ? err : new Error(String(err))
+        return renderErrorBoundary(match.route.errorPath, errObj, opts)
+      }
+      throw err
+    },
+  })
 }
 
 async function renderErrorBoundary(errorPath: string, error: Error, opts: RenderOptions): Promise<Response> {