galbe 0.15.5 → 0.16.0

package/README.md

@@ -9,6 +9,9 @@
 
 Galbe is a fast, lightweight and highly customizable JavaScript web framework based on [Bun](https://bun.sh).
 
+> [!NOTE]
+> Galbe is Bun-only (Bun v1.2.21+): it relies on Bun-native APIs and ships TypeScript sources directly. Node.js and Deno are not supported.
+
 > [!IMPORTANT]  
 > Galbe is currently under active development and not guaranteed to be stable. Future releases may potentially introduce breaking changes.
 

package/bin/commands/build.ts

@@ -7,7 +7,7 @@ import { mkdir, rm } from 'fs/promises'
 
 import { CWD, fmtVal, silentExec } from '../util'
 import { Galbe } from '../../src'
-import { defineRoutes, GalbeProxy } from '../../src/routes'
+import { defineRoutes } from '../../src/routes'
 import type { BuildConfig } from 'bun'
 import { cpSync, existsSync } from 'fs'
 import { softMerge } from '../../src/util'
@@ -16,45 +16,54 @@ const createBuildIndex = async (indexPath: string, g: Galbe, buildId: string, ou
   const buildPath = resolve(tmpdir(), buildId)
   const indexDir = dirname(indexPath)
 
+  // Locate galbe's own modules from the CLI's install location rather than
+  // assuming `<app>/node_modules/galbe/src`, which breaks under pnpm,
+  // hoisted or global CLI installs.
+  const galbeUtilPath = resolve(import.meta.dir, '..', '..', 'src', 'util')
+  const galbeIndexPath = resolve(import.meta.dir, '..', '..', 'src', 'index')
+
   let configPath = ''
   if (existsSync(`${indexDir}/galbe.config.ts`)) configPath = `${indexDir}/galbe.config.ts`
   else if (existsSync(`${indexDir}/galbe.config.js`)) configPath = `${indexDir}/galbe.config.js`
 
-  const routes = new Map<string, { filepath: string; static?: { path: string; root: string } }>()
   let errors: any[] = []
-  // Create GalbeProxy here
-  // use it to define routes
-  const proxy = new GalbeProxy(g, ({ type, error, filepath, route }) => {
-    if (!filepath) return
-    routes.set(filepath, { filepath, static: route?.static })
-    if (type === 'error') errors.push(error)
-  })
-  await defineRoutes({ routes: g?.config?.routes }, proxy)
-  // call init on it for plugin initialization
-  await proxy.init()
+  const { routeFiles, middlewareFiles } = await defineRoutes(
+    { routes: g?.config?.routes, middleware: g?.config?.middleware },
+    g,
+    ({ type, error }) => {
+      if (type === 'error') errors.push(error)
+    }
+  )
+  // plugin initialization
+  await g.init()
 
   if (errors.length) throw errors
 
   // Copy static assets next to the bundle so the runtime can resolve them
   // via static-${BUILD_ID}/<target> at request time.
-  for (const { target } of proxy._staticTargets) {
+  for (const { target } of g.staticTargets) {
     cpSync(target, `${outPath}/static-${buildId}/${target}`, { recursive: true, dereference: true })
   }
 
   await mkdir(buildPath, { recursive: true })
 
+  const usesGroup = routeFiles.some(r => r.prefix)
   let buildIndex =
     `import galbe from '${relative(buildPath, indexPath)}';\n` +
+    (usesGroup ? `import {GalbeGroup} from '${relative(buildPath, galbeIndexPath)}';\n` : '') +
     (configPath ? `import config from '${relative(buildPath, configPath)}';\n` : '') +
-    (configPath
-      ? `import {softMerge} from '${relative(buildPath, `${indexDir}/node_modules/galbe/src/util`)}';\n`
-      : '') +
+    (configPath ? `import {softMerge} from '${relative(buildPath, galbeUtilPath)}';\n` : '') +
     (configPath ? `let conf = galbe.config;\ngalbe.config = softMerge(config, conf)\n` : '') +
-    `${[...routes.values()].map((r, idx) => `import _${idx} from '${relative(buildPath, r.filepath)}'`).join(';\n')}\n` +
+    `${middlewareFiles.map((m, idx) => `import mw_${idx} from '${relative(buildPath, m.file)}'`).join(';\n')}\n` +
+    `${routeFiles.map((r, idx) => `import _${idx} from '${relative(buildPath, r.file)}'`).join(';\n')}\n` +
     `Bun.env.BUN_ENV = 'production';\n` +
     `Bun.env.GALBE_BUILD = '${buildId}';\n` +
     `galbe.meta = ${JSON.stringify(g.meta)};\n` +
-    `${[...routes].map((_, idx) => `_${idx}(galbe)`).join(';\n')};\n` +
+    `galbe.metaMiddleware = ${JSON.stringify(g.metaMiddleware)};\n` +
+    `${middlewareFiles.map((m, idx) => `galbe.middleware(${JSON.stringify(m.scope)}, mw_${idx})`).join(';\n')};\n` +
+    `${routeFiles
+      .map((r, idx) => `_${idx}(${r.prefix ? `new GalbeGroup(galbe, ${JSON.stringify(r.prefix)})` : 'galbe'})`)
+      .join(';\n')};\n` +
     `galbe.listen();\n` +
     `process.on('SIGTERM', () => galbe.stop());\n` +
     `process.on('SIGINT', () => galbe.stop());\n`
@@ -114,7 +123,9 @@ export default (cmd: Command) => {
         buildIndex = await createBuildIndex(index, g, buildID, outPath)
       } catch (errors) {
         console.log(`\nerror: build errors`)
-        for (let error of errors as any[]) console.log(error)
+        // route-file errors come as an array; anything else (a boot error, a
+        // failed import) throws a single value — don't lose it
+        for (let error of [errors].flat()) console.log(error)
         return process.exit(1)
       }
       if (!buildIndex) {

package/bin/commands/dev.ts

@@ -2,7 +2,7 @@ import { $ } from 'bun'
 import { Command, Option } from 'commander'
 import { resolve, dirname } from 'path'
 
-import { CWD, fmtInterval, fmtVal, instanciateRoutes, watchDir } from '../util'
+import { CWD, fmtInterval, fmtVal, instanciateRoutes, resolveReloadStrategy, watchDir } from '../util'
 import { Galbe } from '../../src'
 import { softMerge } from '../../src/util'
 import { existsSync } from 'fs'
@@ -42,22 +42,70 @@ export default (cmd: Command) => {
 
       if (!Bun.env.BUN_ENV) Bun.env.BUN_ENV = 'development'
 
+      if (!!watch_dir && resolveReloadStrategy() === 'respawn') {
+        // Reload by respawning the app process: a syntax error in an edited file
+        // kills the child, not the watcher — the next save reloads.
+        const spawnApp = () =>
+          Bun.spawn([process.execPath, process.argv[1], 'dev', index, '-p', `${port || DEFAULT_PORT}`], {
+            stdio: ['inherit', 'inherit', 'inherit'],
+            cwd: CWD,
+          })
+        const killChild = () => {
+          try {
+            child?.kill()
+          } catch {}
+        }
+        process.on('SIGINT', () => {
+          killChild()
+          process.exit(0)
+        })
+        process.on('SIGTERM', () => {
+          killChild()
+          process.exit(0)
+        })
+        if (clear) await $`clear`.nothrow()
+        let child = spawnApp()
+        let reloading: Promise<void> = Promise.resolve()
+        await watchDir(
+          watch_dir,
+          () => {
+            reloading = reloading.then(async () => {
+              killChild()
+              await child.exited
+              if (clear) await $`clear`.nothrow()
+              child = spawnApp()
+            })
+          },
+          { ignore: watchignore ? new RegExp(watchignore) : undefined }
+        )
+        // The watcher is non-persistent and a pending promise alone does not
+        // keep the event loop alive — hold it open with an interval.
+        setInterval(() => {}, 2 ** 31 - 1)
+        return
+      }
+
       if (!!watch_dir) {
         await watchDir(
           watch_dir,
           async () => {
             g.stop()
-            if (clear) await $`clear`
+            if (clear) await $`clear`.nothrow()
             Loader.registry.clear()
-            g = (await import(indexPath)).default
+            try {
+              g = (await import(indexPath)).default
+            } catch (e) {
+              console.error('\x1b[0;31mReload failed:\x1b[0m', e)
+              return
+            }
+            g.config = softMerge(galbeConfig, g.config)
             await instanciateRoutes(g)
             await g.listen(port)
           },
-          { ignore: watchignore ? new RegExp(watchignore) : /node_modules/ }
+          { ignore: watchignore ? new RegExp(watchignore) : undefined }
         )
       }
 
-      if (!!watch_dir && clear) await $`clear`
+      if (!!watch_dir && clear) await $`clear`.nothrow()
       g = (await import(indexPath)).default
       let conf = g.config
       g.config = softMerge(galbeConfig, conf)

package/bin/commands/generate/cli/index.ts

@@ -63,8 +63,11 @@ export default (cmd: Command) => {
 
       let commands: GalbeCLICommand[] = []
 
+      // meta keys are relative to basePath; route paths carry it
+      const prefix = g.router.prefix || ''
       walkRoutes(g.router.routes, r => {
-        let meta = metaRoutes?.[r.path]?.[r.method]
+        const rPath = prefix && r.path.startsWith(prefix) ? r.path.slice(prefix.length) || '/' : r.path
+        let meta = metaRoutes?.[rPath]?.[r.method]
         let [_, summary, description] = meta?.head?.match(/^([^\n]*)\n\n(.*)/) || []
         if (!summary) description = meta?.head
 

package/bin/commands/generate/client.ts

@@ -1,6 +1,6 @@
 import { Command, Option } from 'commander'
 import { resolve } from 'path'
-import { transformSync } from '@swc/core'
+import { transformSync } from '@swc/wasm'
 import { CWD, fmtList, instanciateRoutes, silentExec } from '../../util'
 import { Galbe, type GalbeClientRoute, type GalbeClientOptions } from '../../../src'
 import { walkRoutes } from '../../../src/util'
@@ -32,12 +32,7 @@ const mimeToShort = (mime: string) => MIME_SHORT[mime] ?? (mime.startsWith('text
 // ─── Operaion-id derivation ───────────────────────────────────────────────────
 
 const deriveOperationId = (method: string, path: string): string =>
-  `${method}-${path
-    .replace(/\//g, '-')
-    .replace(/:/g, '')
-    .replace(/^-/, '')
-    .replace(/-+/g, '-')
-    .replace(/-$/, '')}`
+  `${method}-${path.replace(/\//g, '-').replace(/:/g, '').replace(/^-/, '').replace(/-+/g, '-').replace(/-$/, '')}`
 
 // ─── Response-entry helpers ───────────────────────────────────────────────────
 
@@ -64,7 +59,10 @@ const responseBodyInfo = (entry: STResponseEntry): BodyInfo => {
   for (const [mime, s] of Object.entries(content)) {
     if (!mime.includes('/') || !s) continue
     const schema = s as STSchema
-    if (Stream in schema && (schema as any)[Stream]) { methods.push('stream'); continue }
+    if (Stream in schema && (schema as any)[Stream]) {
+      methods.push('stream')
+      continue
+    }
     const short = mimeToShort(mime)
     methods.push(short === 'byteArray' ? 'byteArray' : short === 'text' ? 'text' : 'json')
     typeStr = schemaToTypeStr(schema)
@@ -77,7 +75,9 @@ const responseHeadersType = (entry: STResponseEntry): string => {
     ? (entry as any).responseHeaders
     : (entry as STResponseContent).responseHeaders
   if (!rh || !Object.keys(rh).length) return 'Headers'
-  const keys = Object.keys(rh).map(k => `'${k}'`).join('|')
+  const keys = Object.keys(rh)
+    .map(k => `'${k}'`)
+    .join('|')
   return `{get<K extends string>(name:K):K extends ${keys}?string:string|null}&Omit<Headers,'get'>`
 }
 
@@ -94,10 +94,32 @@ type _OKStatus = ${[...OKS].join('|')}
 type _HttpStatus = ${HTTP_CODES.join('|')}
 `.trim()
 
+/**
+ * Expand `1XX`…`5XX` range keys into the concrete statuses they cover, so the
+ * generated types stay per-status. An exact declaration always wins over the
+ * range containing it; `default` is left alone as the fallback arm.
+ */
+const expandRanges = (response: STResponse): Array<[string, STResponseEntry]> => {
+  const exact = new Set(Object.keys(response).filter(k => /^\d+$/.test(k)))
+  const out: Array<[string, STResponseEntry]> = []
+  for (const [key, entry] of Object.entries(response)) {
+    if (!entry) continue
+    const range = key.match(/^([1-5])XX$/)
+    if (!range) {
+      out.push([key, entry])
+      continue
+    }
+    const hundred = Number(range[1]) * 100
+    for (const code of HTTP_CODES)
+      if (code >= hundred && code < hundred + 100 && !exact.has(String(code))) out.push([String(code), entry])
+  }
+  return out
+}
+
 // Convert operationId to a safe TypeScript identifier (for type names)
 const safeTypeId = (id: string) => id.replace(/[^a-zA-Z0-9_$]/g, '_')
 // Quote a property key if it is not a valid bare identifier
-const safePropKey = (id: string) => /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(id) ? id : `'${id}'`
+const safePropKey = (id: string) => (/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(id) ? id : `'${id}'`)
 
 const buildBodyObjType = (methods: string[], typeStr: string): string => {
   const parts: string[] = []
@@ -121,7 +143,7 @@ const buildRawResponseType = (operationId: string, response: STResponse | null):
   const declared: string[] = []
   const arms: string[] = []
 
-  for (const [rawKey, entry] of Object.entries(response)) {
+  for (const [rawKey, entry] of expandRanges(response)) {
     if (!entry) continue
     const status = rawKey === 'default' ? null : Number(rawKey)
     if (status === null) continue // handled as fallback
@@ -129,14 +151,14 @@ const buildRawResponseType = (operationId: string, response: STResponse | null):
     const ok = OKS.has(status)
     const { methods, typeStr } = responseBodyInfo(entry)
     const headersT = responseHeadersType(entry)
-    arms.push(
-      `{status:${status};ok:${ok};headers:${headersT};body:${buildBodyObjType(methods, typeStr)}}`
-    )
+    arms.push(`{status:${status};ok:${ok};headers:${headersT};body:${buildBodyObjType(methods, typeStr)}}`)
   }
 
   // fallback arm
   const defaultEntry = (response as any)['default'] as STResponseEntry | undefined
-  const fallbackBody = defaultEntry ? buildBodyObjType(...Object.values(responseBodyInfo(defaultEntry)) as [string[], string]) : FALLBACK_BODY
+  const fallbackBody = defaultEntry
+    ? buildBodyObjType(...(Object.values(responseBodyInfo(defaultEntry)) as [string[], string]))
+    : FALLBACK_BODY
   const excludeStr = declared.length ? `Exclude<_HttpStatus,${declared.join('|')}>` : '_HttpStatus'
   arms.push(`{status:${excludeStr};ok:boolean;headers:Headers;body:${fallbackBody}}`)
 
@@ -147,7 +169,7 @@ const buildRawResponseType = (operationId: string, response: STResponse | null):
 const buildSuccessType = (response: STResponse | null): string => {
   if (!response) return 'unknown'
   const types: string[] = []
-  for (const [rawKey, entry] of Object.entries(response)) {
+  for (const [rawKey, entry] of expandRanges(response)) {
     if (!entry) continue
     const status = rawKey === 'default' ? null : Number(rawKey)
     if (status === null || !OKS.has(status)) continue
@@ -167,7 +189,7 @@ const buildErrorType = (operationId: string, response: STResponse | null): strin
   const declared: string[] = []
   const arms: string[] = []
 
-  for (const [rawKey, entry] of Object.entries(response)) {
+  for (const [rawKey, entry] of expandRanges(response)) {
     if (!entry) continue
     const status = rawKey === 'default' ? null : Number(rawKey)
     if (status === null || OKS.has(status)) continue
@@ -180,9 +202,9 @@ const buildErrorType = (operationId: string, response: STResponse | null): strin
   const defaultEntry = (response as any)['default'] as STResponseEntry | undefined
   const fallbackBody = defaultEntry ? responseBodyInfo(defaultEntry).typeStr : 'any'
   // also exclude all declared 2xx
-  const declared2xx = Object.keys(response)
+  const declared2xx = expandRanges(response)
+    .map(([k]) => k)
     .filter(k => k !== 'default' && OKS.has(Number(k)))
-    .map(String)
   const allDeclared = [...declared, ...declared2xx]
   const errExcludeStr = allDeclared.length ? `Exclude<_HttpStatus,${allDeclared.join('|')}>` : '_HttpStatus'
   arms.push(`{status:${errExcludeStr};headers:Headers;body:${fallbackBody}}`)
@@ -217,7 +239,10 @@ const expandRoute = (r: GalbeClientRoute): RouteVariant[] => {
     Object.entries(r.query).map(([k, v]) => [k, { typeStr: v.type, optional: v.optional, description: v.description }])
   )
   const reqHeaders = Object.fromEntries(
-    Object.entries(r.headers).map(([k, v]) => [k, { typeStr: v.type, optional: v.optional, description: v.description }])
+    Object.entries(r.headers).map(([k, v]) => [
+      k,
+      { typeStr: v.type, optional: v.optional, description: v.description },
+    ])
   )
 
   const bodyEntries = r.body ? Object.entries(r.body) : []
@@ -289,9 +314,7 @@ const buildParamList = (v: RouteVariant): string => {
 const buildFetchCall = (v: RouteVariant, fnName: string): string => {
   const pathExpr = v.params.length ? `\`${v.pathTemplate}\`` : `'${v.path}'`
   const bodyArg = v.bodyShortName !== null ? 'body' : 'undefined'
-  const optionsArg = v.bodyShortName !== null
-    ? `{...(options??{}),contentType:'${v.bodyShortName}'}`
-    : 'options'
+  const optionsArg = v.bodyShortName !== null ? `{...(options??{}),contentType:'${v.bodyShortName}'}` : 'options'
   return `${fnName}(this.#config,'${v.method.toUpperCase()}',${pathExpr},${bodyArg},${optionsArg})`
 }
 
@@ -413,7 +436,9 @@ export default (cmd: Command) => {
       if (!out) out = { ts: 'dist/client.ts', js: 'dist/client.js' }[target as 'ts' | 'js']
 
       let pckg: any = {}
-      try { pckg = await Bun.file(resolve(CWD, 'package.json')).json() } catch {}
+      try {
+        pckg = await Bun.file(resolve(CWD, 'package.json')).json()
+      } catch {}
 
       let error: any = null
       Bun.write(Bun.stdout, '💻 \x1b[1;30mBuilding \x1b[36mGalbe\x1b[0m\x1b[1;30m client\x1b[0m')
@@ -424,7 +449,9 @@ export default (cmd: Command) => {
           await instanciateRoutes(mod)
           await mod.init()
           return mod
-        } catch (err) { error = err }
+        } catch (err) {
+          error = err
+        }
       })
 
       if (error) {
@@ -444,8 +471,11 @@ export default (cmd: Command) => {
       const routes: GalbeClientRoute[] = []
       const autoDerivedIds: string[] = []
 
+      // meta keys are relative to basePath; route paths carry it
+      const prefix = g.router.prefix || ''
       walkRoutes(g.router.routes, r => {
-        const meta = metaRoutes?.[r.path]?.[r.method]
+        const rPath = prefix && r.path.startsWith(prefix) ? r.path.slice(prefix.length) || '/' : r.path
+        const meta = metaRoutes?.[rPath]?.[r.method]
         const [, summary, description] = meta?.head?.match(/^([^\n]*)\n\n(.*)/) ?? []
         const explicitId: string | undefined = meta?.operationId
         const autoDerived = !explicitId
@@ -455,7 +485,7 @@ export default (cmd: Command) => {
         // Collect named types
         Object.values(r.schema.response ?? {}).forEach(entry => {
           if (!entry) return
-          const s = isResponseValue(entry as STResponseEntry) ? entry as STSchema : null
+          const s = isResponseValue(entry as STResponseEntry) ? (entry as STSchema) : null
           if (s?.id) namedTypes[s.id] = schemaToTypeStr(s)
         })
 
@@ -533,8 +563,8 @@ export default (cmd: Command) => {
       const allVariants = finalRoutes.flatMap(expandRoute)
       Bun.write(Bun.stdout, '\n')
       for (const v of allVariants) {
-        const sourceRoute = finalRoutes.find(r =>
-          r.operationId === v.operationId || v.operationId.startsWith(r.operationId)
+        const sourceRoute = finalRoutes.find(
+          r => r.operationId === v.operationId || v.operationId.startsWith(r.operationId)
         )
         const isAuto = sourceRoute?.autoDerived
         Bun.write(
@@ -561,7 +591,8 @@ export default (cmd: Command) => {
 
       if (target === 'js') {
         code = transformSync(code, {
-          jsc: { parser: { syntax: 'typescript' }, preserveAllComments: true, target: 'esnext' },
+          // @swc/wasm's JscTarget typing lags @swc/core's; 'esnext' is supported at runtime
+          jsc: { parser: { syntax: 'typescript' }, preserveAllComments: true, target: 'esnext' as any },
         }).code
       }