gorsee 0.1.0

package/src/server/middleware.ts

@@ -0,0 +1,143 @@
+// Server context, middleware chain, and cookie management
+
+export interface CookieOptions {
+  maxAge?: number
+  expires?: Date
+  path?: string
+  domain?: string
+  secure?: boolean
+  httpOnly?: boolean
+  sameSite?: "Strict" | "Lax" | "None"
+}
+
+export interface Context {
+  request: Request
+  url: URL
+  params: Record<string, string>
+  cookies: Map<string, string>
+  locals: Record<string, unknown>
+  /** Response headers to be merged into the final response */
+  responseHeaders: Headers
+  redirect(url: string, status?: number): Response
+  setCookie(name: string, value: string, options?: CookieOptions): void
+  deleteCookie(name: string, options?: Pick<CookieOptions, "path" | "domain">): void
+  setHeader(name: string, value: string): void
+}
+
+export type NextFn = () => Promise<Response>
+export type MiddlewareFn = (ctx: Context, next: NextFn) => Promise<Response>
+
+/** Throwable redirect — use in loaders to interrupt and redirect */
+export class RedirectError {
+  constructor(public url: string, public status: number = 302) {}
+}
+
+export function redirect(url: string, status = 302): never {
+  throw new RedirectError(url, status)
+}
+
+export function middleware(fn: MiddlewareFn): MiddlewareFn {
+  return fn
+}
+
+function serializeCookie(name: string, value: string, options: CookieOptions = {}): string {
+  let cookie = `${name}=${value}`
+  if (options.maxAge !== undefined) cookie += `; Max-Age=${options.maxAge}`
+  if (options.expires) cookie += `; Expires=${options.expires.toUTCString()}`
+  cookie += `; Path=${options.path ?? "/"}`
+  if (options.domain) cookie += `; Domain=${options.domain}`
+  if (options.secure) cookie += "; Secure"
+  if (options.httpOnly) cookie += "; HttpOnly"
+  if (options.sameSite) cookie += `; SameSite=${options.sameSite}`
+  return cookie
+}
+
+function parseCookies(request: Request): Map<string, string> {
+  const cookieHeader = request.headers.get("cookie") ?? ""
+  const cookies = new Map<string, string>()
+  for (const pair of cookieHeader.split(";")) {
+    const [key, ...rest] = pair.trim().split("=")
+    if (key) cookies.set(key, rest.join("="))
+  }
+  return cookies
+}
+
+export function createContext(request: Request, params: Record<string, string> = {}): Context {
+  const url = new URL(request.url)
+  const cookies = parseCookies(request)
+  const responseHeaders = new Headers()
+  const pendingCookies: string[] = []
+
+  return {
+    request,
+    url,
+    params,
+    cookies,
+    locals: {},
+    responseHeaders,
+
+    redirect(target: string, status = 302) {
+      const res = new Response(null, {
+        status,
+        headers: { Location: target },
+      })
+      // Apply pending cookies to redirect response
+      for (const cookie of pendingCookies) {
+        res.headers.append("Set-Cookie", cookie)
+      }
+      return res
+    },
+
+    setCookie(name: string, value: string, options?: CookieOptions) {
+      const cookie = serializeCookie(name, value, options)
+      pendingCookies.push(cookie)
+      responseHeaders.append("Set-Cookie", cookie)
+      cookies.set(name, value)
+    },
+
+    deleteCookie(name: string, options?: Pick<CookieOptions, "path" | "domain">) {
+      const cookie = serializeCookie(name, "", {
+        ...options,
+        maxAge: 0,
+        expires: new Date(0),
+      })
+      pendingCookies.push(cookie)
+      responseHeaders.append("Set-Cookie", cookie)
+      cookies.delete(name)
+    },
+
+    setHeader(name: string, value: string) {
+      responseHeaders.set(name, value)
+    },
+  }
+}
+
+export async function runMiddlewareChain(
+  middlewares: MiddlewareFn[],
+  ctx: Context,
+  handler: () => Promise<Response>
+): Promise<Response> {
+  let index = 0
+
+  const next = async (): Promise<Response> => {
+    if (index < middlewares.length) {
+      const mw = middlewares[index]!
+      index++
+      return mw(ctx, next)
+    }
+    return handler()
+  }
+
+  const response = await next()
+
+  // Merge ctx.responseHeaders into response
+  for (const [key, value] of ctx.responseHeaders.entries()) {
+    if (key.toLowerCase() === "set-cookie") {
+      response.headers.append(key, value)
+    } else {
+      response.headers.set(key, value)
+    }
+  }
+
+  return response
+}

package/src/server/mime.ts

@@ -0,0 +1,48 @@
+// MIME type detection for static file serving
+
+const MIME_TYPES: Record<string, string> = {
+  ".html": "text/html; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".js": "application/javascript; charset=utf-8",
+  ".mjs": "application/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".xml": "application/xml; charset=utf-8",
+  ".txt": "text/plain; charset=utf-8",
+  ".md": "text/markdown; charset=utf-8",
+  ".csv": "text/csv; charset=utf-8",
+
+  // Images
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".avif": "image/avif",
+  ".svg": "image/svg+xml",
+  ".ico": "image/x-icon",
+
+  // Fonts
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".otf": "font/otf",
+  ".eot": "application/vnd.ms-fontobject",
+
+  // Media
+  ".mp4": "video/mp4",
+  ".webm": "video/webm",
+  ".mp3": "audio/mpeg",
+  ".ogg": "audio/ogg",
+  ".wav": "audio/wav",
+
+  // Other
+  ".pdf": "application/pdf",
+  ".zip": "application/zip",
+  ".wasm": "application/wasm",
+  ".map": "application/json",
+}
+
+export function getMimeType(path: string): string {
+  const ext = path.slice(path.lastIndexOf(".")).toLowerCase()
+  return MIME_TYPES[ext] ?? "application/octet-stream"
+}

package/src/server/pipe.ts

@@ -0,0 +1,46 @@
+// Middleware pipe — compose middleware functions into a pipeline
+// Usage: pipe(cors(), compress(), rateLimit(), auth())
+// Killer DX: declarative route-level middleware composition
+
+import type { MiddlewareFn } from "./middleware.ts"
+
+/** Compose multiple middleware into a single middleware function */
+export function pipe(...middlewares: MiddlewareFn[]): MiddlewareFn {
+  if (middlewares.length === 0) return async (_ctx, next) => next()
+  if (middlewares.length === 1) return middlewares[0]!
+
+  return async (ctx, next) => {
+    let index = 0
+    const run = async (): Promise<Response> => {
+      if (index < middlewares.length) {
+        const mw = middlewares[index]!
+        index++
+        return mw(ctx, run)
+      }
+      return next()
+    }
+    return run()
+  }
+}
+
+/** Create a conditional middleware — runs inner only if predicate passes */
+export function when(
+  predicate: (ctx: import("./middleware.ts").Context) => boolean,
+  middleware: MiddlewareFn,
+): MiddlewareFn {
+  return async (ctx, next) => {
+    if (predicate(ctx)) return middleware(ctx, next)
+    return next()
+  }
+}
+
+/** Create a middleware that runs only for specific HTTP methods */
+export function forMethods(methods: string[], middleware: MiddlewareFn): MiddlewareFn {
+  const methodSet = new Set(methods.map((m) => m.toUpperCase()))
+  return when((ctx) => methodSet.has(ctx.request.method), middleware)
+}
+
+/** Create a middleware that runs only for specific path prefixes */
+export function forPaths(prefixes: string[], middleware: MiddlewareFn): MiddlewareFn {
+  return when((ctx) => prefixes.some((p) => ctx.url.pathname.startsWith(p)), middleware)
+}

package/src/server/rpc-hash.ts

@@ -0,0 +1,17 @@
+// Shared RPC hash function -- must produce identical IDs on server and client
+// ID = sha256(filePath + ":" + callIndex).slice(0, 12)
+
+import { createHash } from "node:crypto"
+
+export function hashRPC(filePath: string, index: number): string {
+  return createHash("sha256")
+    .update(`${filePath}:${index}`)
+    .digest("hex")
+    .slice(0, 12)
+}
+
+// Scan source for server() call positions and return their hashes
+export function scanServerCalls(source: string, filePath: string): string[] {
+  const matches = [...source.matchAll(/\bserver\s*\(\s*(?=async\s|function\s)/g)]
+  return matches.map((_, i) => hashRPC(filePath, i))
+}

package/src/server/rpc.ts

@@ -0,0 +1,125 @@
+// server() function + RPC registry
+// On server: registers function for RPC with hash(filePath:index)
+// On client: replaced by build plugin with fetch() stub
+
+import { stringify } from "devalue"
+import { hashRPC } from "./rpc-hash.ts"
+
+export interface ServerOptions {
+  middleware?: unknown[]
+}
+
+// RPC registry
+const rpcHandlers = new Map<string, (...args: unknown[]) => Promise<unknown>>()
+
+// Track per-file call counters for hash synchronization
+const fileCallCounters = new Map<string, number>()
+
+export function __registerRPC(id: string, fn: (...args: unknown[]) => Promise<unknown>): void {
+  rpcHandlers.set(id, fn)
+}
+
+export function __resetRPCState(): void {
+  fileCallCounters.clear()
+  rpcHandlers.clear()
+}
+
+export function getRPCHandler(id: string): ((...args: unknown[]) => Promise<unknown>) | undefined {
+  return rpcHandlers.get(id)
+}
+
+function getCallerFile(): string | null {
+  const orig = Error.prepareStackTrace
+  Error.prepareStackTrace = (_err, stack) => stack
+  const err = new Error()
+  const stack = err.stack as unknown as NodeJS.CallSite[]
+  Error.prepareStackTrace = orig
+
+  // Walk up stack: 0=getCallerFile, 1=server(), 2=caller (route file)
+  for (let i = 2; i < stack.length; i++) {
+    const file = stack[i]?.getFileName()
+    if (file && !file.includes("/server/rpc.ts") && !file.includes("node_modules")) {
+      return file
+    }
+  }
+  return null
+}
+
+// server() wrapper -- registers with hash-based ID matching client transform
+export function server<TArgs extends unknown[], TReturn>(
+  fn: (...args: TArgs) => Promise<TReturn>,
+  _options?: ServerOptions
+): (...args: TArgs) => Promise<TReturn> {
+  const callerFile = getCallerFile()
+  if (callerFile) {
+    const counter = fileCallCounters.get(callerFile) ?? 0
+    fileCallCounters.set(callerFile, counter + 1)
+    const id = hashRPC(callerFile, counter)
+    rpcHandlers.set(id, fn as (...args: unknown[]) => Promise<unknown>)
+  }
+  return fn
+}
+
+// RPC HTTP handler
+export async function handleRPCRequest(request: Request): Promise<Response | null> {
+  const url = new URL(request.url)
+  const match = url.pathname.match(/^\/api\/_rpc\/([a-zA-Z0-9]+)$/)
+  if (!match) return null
+
+  const id = match[1]!
+  const handler = rpcHandlers.get(id)
+
+  if (!handler) {
+    return new Response(JSON.stringify({ error: `RPC handler not found: ${id}` }), {
+      status: 404,
+      headers: { "Content-Type": "application/json" },
+    })
+  }
+
+  try {
+    const MAX_RPC_BODY = 1024 * 1024 // 1MB
+    let args: unknown[] = []
+    if (request.method === "POST") {
+      const contentLength = Number(request.headers.get("content-length") ?? "0")
+      if (contentLength > MAX_RPC_BODY) {
+        return new Response(JSON.stringify({ error: "Request body too large" }), {
+          status: 413,
+          headers: { "Content-Type": "application/json" },
+        })
+      }
+      const body = await request.text()
+      if (body) {
+        let parsed: unknown
+        try {
+          parsed = JSON.parse(body)
+        } catch {
+          return new Response(JSON.stringify({ error: "Invalid JSON in request body" }), {
+            status: 400,
+            headers: { "Content-Type": "application/json" },
+          })
+        }
+        if (!Array.isArray(parsed)) {
+          return new Response(JSON.stringify({ error: "RPC args must be an array" }), {
+            status: 400,
+            headers: { "Content-Type": "application/json" },
+          })
+        }
+        args = parsed
+      }
+    }
+
+    const result = await handler(...args)
+    const serialized = stringify(result)
+
+    return new Response(serialized, {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    })
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    return new Response(JSON.stringify({ error: message }), {
+      status: 500,
+      headers: { "Content-Type": "application/json" },
+    })
+  }
+}

package/src/server/sse.ts

@@ -0,0 +1,96 @@
+import { createSignal, type SignalGetter } from "../reactive/signal.ts"
+
+export interface SSEOptions {
+  headers?: Record<string, string>
+}
+
+export interface SSEStream {
+  response: Response
+  send: (event: string, data: unknown) => void
+  close: () => void
+}
+
+export function createSSEStream(options?: SSEOptions): SSEStream {
+  let controller: ReadableStreamDefaultController<Uint8Array> | null = null
+  const encoder = new TextEncoder()
+
+  const stream = new ReadableStream<Uint8Array>({
+    start(ctrl) {
+      controller = ctrl
+    },
+    cancel() {
+      controller = null
+    },
+  })
+
+  const response = new Response(stream, {
+    headers: {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      Connection: "keep-alive",
+      ...options?.headers,
+    },
+  })
+
+  function send(event: string, data: unknown): void {
+    if (!controller) return
+    const payload = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`
+    controller.enqueue(encoder.encode(payload))
+  }
+
+  function close(): void {
+    if (controller) {
+      controller.close()
+      controller = null
+    }
+  }
+
+  return { response, send, close }
+}
+
+// --- Client-side: reactive EventSource signal ---
+
+export interface EventSourceSignal<T> {
+  readonly value: SignalGetter<T>
+  readonly connected: SignalGetter<boolean>
+  close: () => void
+}
+
+export function createEventSource<T>(
+  url: string,
+  event: string,
+  initialValue: T,
+): EventSourceSignal<T> {
+  const [value, setValue] = createSignal<T>(initialValue)
+  const [connected, setConnected] = createSignal(false)
+
+  if (typeof globalThis.EventSource === "undefined") {
+    return { value, connected, close: () => {} }
+  }
+
+  const source = new EventSource(url)
+
+  source.addEventListener("open", () => {
+    setConnected(true)
+  })
+
+  source.addEventListener(event, (e: MessageEvent) => {
+    try {
+      const parsed = JSON.parse(String(e.data)) as T
+      setValue(parsed)
+    } catch {
+      // ignore malformed messages
+    }
+  })
+
+  source.addEventListener("error", () => {
+    setConnected(false)
+  })
+
+  function close(): void {
+    source.close()
+    setConnected(false)
+  }
+
+  return { value, connected, close }
+}

package/src/server/ws.ts

@@ -0,0 +1,56 @@
+// WebSocket support for real-time features
+// Routes can export a `ws` handler for WebSocket connections
+
+export interface WSContext {
+  send(data: string | ArrayBuffer): void
+  close(code?: number, reason?: string): void
+  id: string
+}
+
+export type WSHandler = {
+  open?: (ws: WSContext) => void
+  message?: (ws: WSContext, data: string | ArrayBuffer) => void
+  close?: (ws: WSContext) => void
+}
+
+// Room-based pub/sub for common real-time patterns
+const rooms = new Map<string, Set<WSContext>>()
+
+export function joinRoom(room: string, ws: WSContext): void {
+  let members = rooms.get(room)
+  if (!members) {
+    members = new Set()
+    rooms.set(room, members)
+  }
+  members.add(ws)
+}
+
+export function leaveRoom(room: string, ws: WSContext): void {
+  const members = rooms.get(room)
+  if (!members) return
+  members.delete(ws)
+  if (members.size === 0) rooms.delete(room)
+}
+
+export function broadcastToRoom(room: string, data: string, exclude?: WSContext): void {
+  const members = rooms.get(room)
+  if (!members) return
+  for (const ws of members) {
+    if (ws === exclude) continue
+    try { ws.send(data) } catch {}
+  }
+}
+
+export function getRoomSize(room: string): number {
+  return rooms.get(room)?.size ?? 0
+}
+
+let wsIdCounter = 0
+
+export function createWSContext(ws: { send(data: string | ArrayBuffer): void; close(code?: number, reason?: string): void }): WSContext {
+  return {
+    send: (data) => ws.send(data),
+    close: (code, reason) => ws.close(code, reason),
+    id: `ws_${++wsIdCounter}`,
+  }
+}

package/src/testing/index.ts

@@ -0,0 +1,74 @@
+// Testing utilities for Gorsee.js applications
+
+import { createContext, type Context, type MiddlewareFn, runMiddlewareChain } from "../server/middleware.ts"
+import { renderToString, ssrJsx } from "../runtime/server.ts"
+
+/** Create a mock request for testing */
+export function createTestRequest(
+  path: string,
+  options: {
+    method?: string
+    headers?: Record<string, string>
+    body?: string | Record<string, unknown>
+  } = {},
+): Request {
+  const { method = "GET", headers = {}, body } = options
+  const url = `http://localhost${path}`
+  const init: RequestInit = { method, headers }
+  if (body) {
+    if (typeof body === "object") {
+      init.body = JSON.stringify(body)
+      ;(init.headers as Record<string, string>)["Content-Type"] = "application/json"
+    } else {
+      init.body = body
+    }
+  }
+  return new Request(url, init)
+}
+
+/** Create a test context for middleware/loader testing */
+export function createTestContext(
+  path: string,
+  options: {
+    method?: string
+    headers?: Record<string, string>
+    params?: Record<string, string>
+    body?: string | Record<string, unknown>
+  } = {},
+): Context {
+  const { params = {}, ...reqOpts } = options
+  const request = createTestRequest(path, reqOpts)
+  return createContext(request, params)
+}
+
+/** Run a middleware function with a test context and handler */
+export async function runTestMiddleware(
+  middleware: MiddlewareFn,
+  ctx: Context,
+  handler?: () => Promise<Response>,
+): Promise<Response> {
+  const defaultHandler = async () => new Response("OK")
+  return runMiddlewareChain([middleware], ctx, handler ?? defaultHandler)
+}
+
+/** Render a component to HTML string for snapshot/assertion testing */
+export function renderComponent(
+  component: Function,
+  props: Record<string, unknown> = {},
+): string {
+  const vnode = ssrJsx(component as any, props)
+  return renderToString(vnode)
+}
+
+/** Test a loader function directly */
+export async function testLoader<T>(
+  loader: (ctx: Context) => Promise<T>,
+  path: string,
+  options: {
+    params?: Record<string, string>
+    headers?: Record<string, string>
+  } = {},
+): Promise<T> {
+  const ctx = createTestContext(path, options)
+  return loader(ctx)
+}

package/src/types/index.ts

@@ -0,0 +1,4 @@
+export { SafeSQL, type SafeSQLValue } from "./safe-sql.ts"
+export { SafeHTML, sanitize } from "./safe-html.ts"
+export { SafeURL, validateURL } from "./safe-url.ts"
+export { type UserInput, validate } from "./user-input.ts"

package/src/types/safe-html.ts

@@ -0,0 +1,32 @@
+declare const __safeHTMLBrand: unique symbol
+
+export type SafeHTMLValue = string & { readonly [__safeHTMLBrand]: true }
+
+const ESCAPE_MAP: Record<string, string> = {
+  "&": "&amp;",
+  "<": "&lt;",
+  ">": "&gt;",
+  '"': "&quot;",
+  "'": "&#x27;",
+}
+
+const ESCAPE_RE = /[&<>"']/g
+
+export function sanitize(raw: string): SafeHTMLValue {
+  const escaped = raw.replace(ESCAPE_RE, (ch) => ESCAPE_MAP[ch] ?? ch)
+  return escaped as SafeHTMLValue
+}
+
+export function SafeHTML(
+  strings: TemplateStringsArray,
+  ...values: unknown[]
+): SafeHTMLValue {
+  const parts: string[] = []
+  for (let i = 0; i < strings.length; i++) {
+    parts.push(strings[i]!)
+    if (i < values.length) {
+      parts.push(sanitize(String(values[i])) as string)
+    }
+  }
+  return parts.join("") as SafeHTMLValue
+}

package/src/types/safe-sql.ts

@@ -0,0 +1,28 @@
+declare const __safeSQLBrand: unique symbol
+
+export interface SafeSQLValue {
+  readonly text: string
+  readonly params: readonly unknown[]
+  readonly [__safeSQLBrand]: true
+}
+
+export function SafeSQL(
+  strings: TemplateStringsArray,
+  ...values: unknown[]
+): SafeSQLValue {
+  const parts: string[] = []
+  const params: unknown[] = []
+
+  for (let i = 0; i < strings.length; i++) {
+    parts.push(strings[i]!)
+    if (i < values.length) {
+      params.push(values[i])
+      parts.push("?")
+    }
+  }
+
+  return {
+    text: parts.join(""),
+    params,
+  } as unknown as SafeSQLValue
+}