gorsee 0.2.1 → 0.2.3

package/README.md

@@ -36,7 +36,7 @@ Open [http://localhost:3000](http://localhost:3000).
 ### Islands — partial hydration
 
 ```tsx
-import { island, createSignal } from "gorsee"
+import { island, createSignal } from "gorsee/client"
 
 // Only THIS component gets JavaScript. Rest of the page = zero JS.
 export default island(function LikeButton({ postId }) {
@@ -48,7 +48,7 @@ export default island(function LikeButton({ postId }) {
 ### Reactive WebSocket
 
 ```tsx
-import { createLive } from "gorsee"
+import { createLive } from "gorsee/client"
 
 function StockPrice() {
   const { value: price, connected } = createLive({
@@ -63,7 +63,7 @@ function StockPrice() {
 ### Optimistic Mutations
 
 ```tsx
-import { createSignal, createMutation } from "gorsee"
+import { createSignal, createMutation } from "gorsee/client"
 
 const [todos, setTodos] = createSignal(["Buy milk"])
 const addTodo = createMutation({
@@ -77,7 +77,7 @@ await addTodo.optimistic(todos, setTodos, (list, text) => [...list, text], "New
 ### Built-in Auth
 
 ```tsx
-import { createAuth } from "gorsee/auth"
+import { createAuth } from "gorsee/server"
 
 const auth = createAuth({ secret: process.env.SESSION_SECRET })
 
@@ -130,6 +130,134 @@ export default pipe(
 | `gorsee typegen` | Generate typed routes |
 | `gorsee migrate` | Run DB migrations |
 
+## Recommended Imports
+
+```tsx
+// Route components, islands, navigation, forms, browser-safe reactivity
+import { createSignal, island, Link, Head } from "gorsee/client"
+
+// Middleware, loaders, auth, db, security, logging
+import { createAuth, createDB, cors, log } from "gorsee/server"
+```
+
+- Use `gorsee/client` for route components and anything that must stay browser-safe.
+- Use `gorsee/server` for loaders, middleware, API routes, auth, db, security, env, and logging.
+- Keep root `gorsee` only for backward compatibility. New code should not depend on it.
+- If you need explicit legacy semantics during migration, use `gorsee/compat`.
+
+## Adapter Utilities
+
+```tsx
+import {
+  createAuth,
+  createMemorySessionStore,
+  createNamespacedSessionStore,
+  createRedisSessionStore,
+  createSQLiteSessionStore,
+  createMemoryCacheStore,
+  createNamespacedCacheStore,
+  createRedisCacheStore,
+  createSQLiteCacheStore,
+  createMemoryRPCRegistry,
+  createScopedRPCRegistry,
+} from "gorsee/server"
+
+const sharedSessions = createMemorySessionStore()
+const tenantSessions = createNamespacedSessionStore(sharedSessions, "tenant-a")
+const auth = createAuth({ secret: process.env.SESSION_SECRET!, store: tenantSessions })
+
+const sharedCache = createMemoryCacheStore()
+const tenantCache = createNamespacedCacheStore(sharedCache, "tenant-a")
+
+const sessionStore = createSQLiteSessionStore("./data/auth.sqlite")
+const cacheStore = createSQLiteCacheStore("./data/cache.sqlite")
+
+const redisSessionStore = createRedisSessionStore(redisClient, { prefix: "gorsee:sessions" })
+const redisCacheStore = createRedisCacheStore(redisClient, { prefix: "gorsee:cache" })
+
+const sharedRPC = createMemoryRPCRegistry()
+const tenantRPC = createScopedRPCRegistry(sharedRPC, "tenant-a")
+```
+
+- `createNamespacedSessionStore` isolates auth sessions over one shared backing store.
+- `createNamespacedCacheStore` isolates route cache keys per app, tenant, or test worker.
+- `createSQLiteSessionStore` and `createSQLiteCacheStore` provide persistent local adapters without adding external infrastructure.
+- `createSQLiteSessionStore` prunes expired rows automatically on hot paths and also exposes `deleteExpired()` for explicit maintenance.
+- `createSQLiteCacheStore` supports retention policy via `maxEntryAgeMs` and also exposes `deleteExpired()` for explicit cache pruning.
+- `createRedisSessionStore` and `createRedisCacheStore` work with any client that supports `get/set/del/keys`, so you can plug in `redis` or `ioredis` without framework lock-in.
+- RPC handlers remain intentionally process-local. The stable extension point is injected request-time registry resolution, not pretending closures can live in Redis.
+- `createScopedRPCRegistry` isolates RPC registrations without forking the entire server runtime.
+
+## Redis Recipes
+
+### node-redis
+
+```tsx
+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" }),
+})
+
+export const cache = routeCache({
+  maxAge: 60,
+  staleWhileRevalidate: 300,
+  store: createRedisCacheStore(redisClient, {
+    prefix: "app:cache",
+    maxEntryAgeMs: 360_000,
+  }),
+})
+```
+
+### ioredis
+
+```tsx
+import Redis from "ioredis"
+import {
+  createAuth,
+  createRedisSessionStore,
+  createRedisCacheStore,
+  createIORedisLikeClient,
+  routeCache,
+} from "gorsee/server"
+
+const redis = new Redis(process.env.REDIS_URL!)
+const redisClient = createIORedisLikeClient(redis)
+
+const auth = createAuth({
+  secret: process.env.SESSION_SECRET!,
+  store: createRedisSessionStore(redisClient, { prefix: "app:sessions" }),
+})
+
+export const cache = routeCache({
+  maxAge: 60,
+  staleWhileRevalidate: 300,
+  store: createRedisCacheStore(redisClient, {
+    prefix: "app:cache",
+    maxEntryAgeMs: 360_000,
+  }),
+})
+```
+
+### Notes
+
+- For multi-instance deployments, keep the same Redis prefixes across all app replicas.
+- Session expiry is enforced by store TTL and validated again by `createAuth()`.
+- Cache retention is controlled by `maxEntryAgeMs`; `routeCache()` still decides HIT/STALE/MISS at request time.
+- `createNodeRedisLikeClient()` and `createIORedisLikeClient()` let you pass real Redis SDK clients without writing framework-specific glue.
+
 ## Requirements
 
 - [Bun](https://bun.sh) >= 1.0

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "gorsee",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Full-stack TypeScript framework — islands, reactive WebSocket, optimistic mutations, built-in auth, type-safe routes",
   "type": "module",
   "license": "MIT",
   "author": "Oleg Gorsky",
   "repository": {
     "type": "git",
-    "url": "https://github.com/AYKGorsee/gorsee-js"
+    "url": "git+https://github.com/AYKGorsee/gorsee-js.git"
   },
   "homepage": "https://github.com/AYKGorsee/gorsee-js#readme",
   "keywords": [
@@ -22,12 +22,14 @@
     "web-framework"
   ],
   "bin": {
-    "gorsee": "./bin/gorsee.js"
+    "gorsee": "bin/gorsee.js"
   },
   "exports": {
     ".": "./src/index.ts",
+    "./compat": "./src/index.ts",
+    "./client": "./src/client.ts",
     "./reactive": "./src/reactive/index.ts",
-    "./server": "./src/server/index.ts",
+    "./server": "./src/server-entry.ts",
     "./types": "./src/types/index.ts",
     "./db": "./src/db/index.ts",
     "./router": "./src/router/index.ts",
@@ -63,6 +65,7 @@
     "test": "bun test",
     "check": "tsc --noEmit",
     "dev": "bun run src/dev.ts",
+    "release:check": "node scripts/release-check.mjs",
     "prepublishOnly": "bun run check"
   },
   "engines": {

package/src/auth/index.ts

@@ -1,12 +1,17 @@
 // Built-in session-based auth with HMAC-signed cookies
 
+import { timingSafeEqual } from "node:crypto"
 import type { Context, MiddlewareFn } from "../server/middleware.ts"
+export { createNamespacedSessionStore } from "./store-utils.ts"
+export { createRedisSessionStore } from "./redis-session-store.ts"
+export { createSQLiteSessionStore } from "./sqlite-session-store.ts"
 
 export interface AuthConfig {
   secret: string
   cookieName?: string
   maxAge?: number
   loginPath?: string
+  store?: SessionStore
 }
 
 export interface Session {
@@ -16,7 +21,26 @@ export interface Session {
   expiresAt: number
 }
 
-const sessions = new Map<string, Session>()
+type Awaitable<T> = T | Promise<T>
+
+export interface SessionStore {
+  get(id: string): Awaitable<Session | undefined>
+  set(id: string, session: Session): Awaitable<void>
+  delete(id: string): Awaitable<void>
+  entries(): Awaitable<Iterable<[string, Session]> | AsyncIterable<[string, Session]>>
+}
+
+export function createMemorySessionStore(): SessionStore {
+  const sessions = new Map<string, Session>()
+  return {
+    get: (id) => sessions.get(id),
+    set: (id, session) => { sessions.set(id, session) },
+    delete: (id) => { sessions.delete(id) },
+    entries: () => sessions.entries(),
+  }
+}
+
+const defaultSessionStore = createMemorySessionStore()
 
 let cachedKey: CryptoKey | null = null
 let cachedSecret = ""
@@ -53,15 +77,19 @@ async function verify(
   if (dotIndex === -1) return null
   const value = signed.slice(0, dotIndex)
   const expected = await sign(value, secret)
-  // Constant-time-ish comparison via re-signing
-  if (expected === signed) return value
-  return null
+  // Constant-time comparison to prevent timing attacks
+  if (expected.length !== signed.length) return null
+  const a = Buffer.from(expected)
+  const b = Buffer.from(signed)
+  if (!timingSafeEqual(a, b)) return null
+  return value
 }
 
-function pruneExpired(): void {
+async function pruneExpired(store: SessionStore): Promise<void> {
   const now = Date.now()
-  for (const [id, session] of sessions) {
-    if (session.expiresAt <= now) sessions.delete(id)
+  const entries = await store.entries()
+  for await (const [id, session] of entries) {
+    if (session.expiresAt <= now) await store.delete(id)
   }
 }
 
@@ -71,6 +99,7 @@ function resolveConfig(config: AuthConfig) {
     cookieName: config.cookieName ?? "gorsee_session",
     maxAge: config.maxAge ?? 86400,
     loginPath: config.loginPath ?? "/login",
+    store: config.store ?? defaultSessionStore,
   }
 }
 
@@ -78,21 +107,21 @@ export function createAuth(config: AuthConfig): {
   middleware: MiddlewareFn
   requireAuth: MiddlewareFn
   login: (ctx: Context, userId: string, data?: Record<string, unknown>) => Promise<void>
-  logout: (ctx: Context) => void
+  logout: (ctx: Context) => Promise<void>
   getSession: (ctx: Context) => Session | null
 } {
   const cfg = resolveConfig(config)
 
   const middleware: MiddlewareFn = async (ctx, next) => {
-    const cookie = ctx.cookies.get(cfg.cookieName)
+      const cookie = ctx.cookies.get(cfg.cookieName)
     if (cookie) {
-      const sessionId = await verify(cookie, cfg.secret)
-      if (sessionId) {
-        const session = sessions.get(sessionId)
+        const sessionId = await verify(cookie, cfg.secret)
+        if (sessionId) {
+        const session = await cfg.store.get(sessionId)
         if (session && session.expiresAt > Date.now()) {
           ctx.locals.session = session
         } else if (session) {
-          sessions.delete(sessionId)
+          await cfg.store.delete(sessionId)
         }
       }
     }
@@ -111,7 +140,7 @@ export function createAuth(config: AuthConfig): {
     userId: string,
     data: Record<string, unknown> = {},
   ): Promise<void> {
-    pruneExpired()
+    await pruneExpired(cfg.store)
     const id = crypto.randomUUID()
     const session: Session = {
       id,
@@ -119,21 +148,23 @@ export function createAuth(config: AuthConfig): {
       data,
       expiresAt: Date.now() + cfg.maxAge * 1000,
     }
-    sessions.set(id, session)
+    await cfg.store.set(id, session)
     ctx.locals.session = session
     const signed = await sign(id, cfg.secret)
+    const isProduction = process.env.NODE_ENV === "production"
     ctx.setCookie(cfg.cookieName, signed, {
       maxAge: cfg.maxAge,
       httpOnly: true,
+      secure: isProduction,
       sameSite: "Lax",
       path: "/",
     })
   }
 
-  function logout(ctx: Context): void {
+  async function logout(ctx: Context): Promise<void> {
     const session = ctx.locals.session as Session | undefined
     if (session) {
-      sessions.delete(session.id)
+      await cfg.store.delete(session.id)
       ctx.locals.session = undefined
     }
     ctx.deleteCookie(cfg.cookieName)

package/src/auth/redis-session-store.ts

@@ -0,0 +1,46 @@
+import type { Session, SessionStore } from "./index.ts"
+import { buildRedisKey, stripRedisPrefix, type RedisLikeClient } from "../server/redis-client.ts"
+
+interface RedisSessionStoreOptions {
+  prefix?: string
+}
+
+interface StoredSessionPayload {
+  session: Session
+}
+
+export function createRedisSessionStore(
+  client: RedisLikeClient,
+  options: RedisSessionStoreOptions = {},
+): SessionStore {
+  const prefix = options.prefix ?? "gorsee:session"
+
+  return {
+    async get(id) {
+      const raw = await client.get(buildRedisKey(prefix, id))
+      if (!raw) return undefined
+      const payload = JSON.parse(raw) as StoredSessionPayload
+      return payload.session
+    },
+    async set(id, session) {
+      const key = buildRedisKey(prefix, id)
+      await client.set(key, JSON.stringify({ session } satisfies StoredSessionPayload))
+      const ttlSeconds = Math.max(1, Math.ceil((session.expiresAt - Date.now()) / 1000))
+      if (client.expire) await client.expire(key, ttlSeconds)
+    },
+    async delete(id) {
+      await client.del(buildRedisKey(prefix, id))
+    },
+    async entries() {
+      const keys = await client.keys(`${prefix}:*`)
+      const sessions: Array<[string, Session]> = []
+      for (const key of keys) {
+        const raw = await client.get(key)
+        if (!raw) continue
+        const payload = JSON.parse(raw) as StoredSessionPayload
+        sessions.push([stripRedisPrefix(prefix, key), payload.session])
+      }
+      return sessions
+    },
+  }
+}

package/src/auth/sqlite-session-store.ts

@@ -0,0 +1,98 @@
+import { Database } from "bun:sqlite"
+import type { Session, SessionStore } from "./index.ts"
+
+interface SQLiteSessionStoreOptions {
+  pruneExpiredOnInit?: boolean
+  pruneExpiredOnGet?: boolean
+  pruneExpiredOnSet?: boolean
+  pruneExpiredOnEntries?: boolean
+}
+
+function ensureSessionTable(sqlite: Database): void {
+  sqlite.run(`
+    CREATE TABLE IF NOT EXISTS gorsee_sessions (
+      id TEXT PRIMARY KEY,
+      payload TEXT NOT NULL,
+      expires_at INTEGER NOT NULL
+    )
+  `)
+  sqlite.run("CREATE INDEX IF NOT EXISTS idx_gorsee_sessions_expires_at ON gorsee_sessions (expires_at)")
+}
+
+function pruneExpiredRows(sqlite: Database, now: number = Date.now()): number {
+  const result = sqlite.prepare("DELETE FROM gorsee_sessions WHERE expires_at <= ?1").run(now)
+  return (result as { changes?: number }).changes ?? 0
+}
+
+export function createSQLiteSessionStore(
+  path = ":memory:",
+  options: SQLiteSessionStoreOptions = {},
+): SessionStore & { close(): void; deleteExpired(now?: number): number } {
+  const sqlite = new Database(path)
+  sqlite.run("PRAGMA journal_mode=WAL;")
+  ensureSessionTable(sqlite)
+  const {
+    pruneExpiredOnInit = true,
+    pruneExpiredOnGet = true,
+    pruneExpiredOnSet = true,
+    pruneExpiredOnEntries = true,
+  } = options
+
+  if (pruneExpiredOnInit) pruneExpiredRows(sqlite)
+
+  return {
+    async get(id) {
+      if (pruneExpiredOnGet) pruneExpiredRows(sqlite)
+      const row = sqlite
+        .prepare("SELECT payload, expires_at FROM gorsee_sessions WHERE id = ?1")
+        .get(id) as { payload: string; expires_at: number } | null
+      if (!row) return undefined
+      return {
+        ...(JSON.parse(row.payload) as Omit<Session, "expiresAt">),
+        expiresAt: row.expires_at,
+      }
+    },
+    async set(id, session) {
+      if (pruneExpiredOnSet) pruneExpiredRows(sqlite)
+      sqlite.prepare(`
+        INSERT INTO gorsee_sessions (id, payload, expires_at)
+        VALUES (?1, ?2, ?3)
+        ON CONFLICT(id) DO UPDATE SET
+          payload = excluded.payload,
+          expires_at = excluded.expires_at
+      `).run(
+        id,
+        JSON.stringify({
+          id: session.id,
+          userId: session.userId,
+          data: session.data,
+        }),
+        session.expiresAt,
+      )
+    },
+    async delete(id) {
+      sqlite.prepare("DELETE FROM gorsee_sessions WHERE id = ?1").run(id)
+    },
+    async entries() {
+      if (pruneExpiredOnEntries) pruneExpiredRows(sqlite)
+      const rows = sqlite.prepare("SELECT id, payload, expires_at FROM gorsee_sessions").all() as Array<{
+        id: string
+        payload: string
+        expires_at: number
+      }>
+      return rows.map((row) => [
+        row.id,
+        {
+          ...(JSON.parse(row.payload) as Omit<Session, "expiresAt">),
+          expiresAt: row.expires_at,
+        },
+      ] as [string, Session])
+    },
+    deleteExpired(now = Date.now()) {
+      return pruneExpiredRows(sqlite, now)
+    },
+    close() {
+      sqlite.close()
+    },
+  }
+}

package/src/auth/store-utils.ts

@@ -0,0 +1,21 @@
+import type { Session, SessionStore } from "./index.ts"
+
+export function createNamespacedSessionStore(store: SessionStore, namespace: string): SessionStore {
+  const prefix = `${namespace}:`
+  return {
+    get: (id) => store.get(prefix + id),
+    set: async (id, session) => {
+      await store.set(prefix + id, { ...session, id })
+    },
+    delete: async (id) => {
+      await store.delete(prefix + id)
+    },
+    entries: async function* () {
+      const entries = await store.entries()
+      for await (const [id, session] of entries) {
+        if (!id.startsWith(prefix)) continue
+        yield [id.slice(prefix.length), { ...(session as Session), id: id.slice(prefix.length) }] as [string, Session]
+      }
+    },
+  }
+}

package/src/build/client.ts

@@ -1,6 +1,6 @@
 // Client bundle builder -- uses Bun.build() to create browser-ready JS per route
 
-import { join, resolve, relative } from "node:path"
+import { join, resolve, relative, dirname } from "node:path"
 import { mkdir, rm } from "node:fs/promises"
 import { serverStripPlugin } from "./server-strip.ts"
 import { cssModulesPlugin, getCollectedCSS, resetCollectedCSS } from "./css-modules.ts"
@@ -10,7 +10,8 @@ const FRAMEWORK_ROOT = resolve(import.meta.dir, "..")
 const CLIENT_JSX_RUNTIME = resolve(FRAMEWORK_ROOT, "jsx-runtime-client.ts")
 
 const GORSEE_CLIENT_RESOLVE: Record<string, string> = {
-  "gorsee": resolve(FRAMEWORK_ROOT, "index.ts"),
+  "gorsee": resolve(FRAMEWORK_ROOT, "index-client.ts"),
+  "gorsee/client": resolve(FRAMEWORK_ROOT, "client.ts"),
   "gorsee/reactive": resolve(FRAMEWORK_ROOT, "reactive/index.ts"),
   "gorsee/types": resolve(FRAMEWORK_ROOT, "types/index.ts"),
   "gorsee/runtime": resolve(FRAMEWORK_ROOT, "runtime/index.ts"),
@@ -24,11 +25,19 @@ function routeToEntryName(route: Route, cwd: string): string {
   return rel.replace(/\.(tsx?|jsx?)$/, "").replace(/[\[\]]/g, "_")
 }
 
-function generateEntryCode(routeFile: string, hydrateImport: string, routerImport: string): string {
+function toImportSpecifier(fromFile: string, toFile: string): string {
+  const rel = relative(dirname(fromFile), toFile).replace(/\\/g, "/")
+  return rel.startsWith(".") ? rel : `./${rel}`
+}
+
+function generateEntryCode(routeFile: string, entryPath: string, hydrateImport: string, routerImport: string): string {
+  const hydrateSpecifier = toImportSpecifier(entryPath, hydrateImport)
+  const routerSpecifier = toImportSpecifier(entryPath, routerImport)
+
   return `
-import Component from "${routeFile}";
-import { hydrate } from "${hydrateImport}";
-import { initRouter } from "${routerImport}";
+import Component from "gorsee:route:${routeFile}";
+import { hydrate } from "${hydrateSpecifier}";
+import { initRouter } from "${routerSpecifier}";
 var container = document.getElementById("app");
 var dataEl = document.getElementById("__GORSEE_DATA__");
 var data = dataEl ? JSON.parse(dataEl.textContent) : {};
@@ -74,7 +83,7 @@ export async function buildClientBundles(
     const entryPath = join(entryDir, `${name}.ts`)
     const clientModule = resolve(FRAMEWORK_ROOT, "runtime/client.ts")
     const routerModule = resolve(FRAMEWORK_ROOT, "runtime/router.ts")
-    const code = generateEntryCode(route.filePath, clientModule, routerModule)
+    const code = generateEntryCode(route.filePath, entryPath, clientModule, routerModule)
     await Bun.write(entryPath, code)
     entrypoints.push(entryPath)
     entryMap.set(route.path, `${name}.js`)
@@ -88,10 +97,19 @@ export async function buildClientBundles(
     minify: options?.minify ?? false,
     sourcemap: options?.sourcemap ? "external" : "none",
     splitting: true,
+    jsx: {
+      runtime: "automatic",
+      importSource: "gorsee",
+      development: true,
+    },
     plugins: [
       {
         name: "gorsee-client-resolve",
         setup(build) {
+          build.onResolve({ filter: /^gorsee:route:/ }, (args) => ({
+            path: args.path.slice("gorsee:route:".length),
+          }))
+
           build.onResolve({ filter: /^gorsee(\/.*)?$/ }, (args) => {
             const mapped = GORSEE_CLIENT_RESOLVE[args.path]
             if (mapped) return { path: mapped }

package/src/build/manifest.ts

@@ -0,0 +1,34 @@
+import type { Route } from "../router/scanner.ts"
+import { inspectRouteBuildMetadata } from "./route-metadata.ts"
+import type { BuildManifest } from "../server/manifest.ts"
+
+export async function createBuildManifest(
+  routes: Route[],
+  entryMap: Map<string, string>,
+  hashMap: Map<string, string>,
+  prerenderedPaths: Iterable<string> = [],
+): Promise<BuildManifest> {
+  const prerendered = new Set(prerenderedPaths)
+  const manifest: BuildManifest = {
+    routes: {},
+    chunks: [],
+    prerendered: [...prerendered],
+    buildTime: new Date().toISOString(),
+  }
+
+  for (const route of routes) {
+    const metadata = await inspectRouteBuildMetadata(route)
+    const jsRel = entryMap.get(route.path)
+    manifest.routes[route.path] = {
+      js: jsRel ? hashMap.get(jsRel) : undefined,
+      hasLoader: metadata.hasLoader,
+      prerendered: prerendered.has(route.path) || undefined,
+    }
+  }
+
+  for (const hashed of hashMap.values()) {
+    if (hashed.includes("chunk-")) manifest.chunks.push(hashed)
+  }
+
+  return manifest
+}

package/src/build/route-metadata.ts

@@ -0,0 +1,12 @@
+import type { Route } from "../router/scanner.ts"
+
+export interface RouteBuildMetadata {
+  hasLoader: boolean
+}
+
+export async function inspectRouteBuildMetadata(route: Route): Promise<RouteBuildMetadata> {
+  const source = await Bun.file(route.filePath).text()
+  return {
+    hasLoader: /export\s+(async\s+)?function\s+loader\b/.test(source),
+  }
+}