feat(serve): expose the query string as query in server scripts

File-based routing handed a server script its route parameters as
`params` and then left the query string reachable only through
`__stxServeSearch` - an internal, double-underscored name nobody would
guess from the docs. So the ordinary case of a filtered, paginated list
page had no supported way to read `?state=closed&page=2`.

`query` is always an object, like `params`, so reading a key on a
request with no query string is undefined rather than a crash. Static
and dynamic routes both get it; a repeated key keeps its last value,
matching URLSearchParams.get.

Also pins async work in a component's <script server> across static
routes, dynamic-route views, and dynamic-route components. Those three
look interchangeable, and when one of them stops working the symptom is
not an error - a component whose data never arrives renders its own
empty state, so the page reads as a correct answer rather than a
failure.

Author: chrisbbreuer

packages/bun-plugin/src/serve.ts

@@ -1173,6 +1173,19 @@ export async function serve(options: ServeOptions): Promise<void> {
     // that — stacksjs/stacks#1967).
     context.__stxServeSearch = search
     ;(globalThis as { __stxServeSearch?: string }).__stxServeSearch = search
+
+    // The query string as an object, the counterpart to `params`.
+    //
+    // File-based routing handed a server script its route parameters and then
+    // left the query string reachable only through `__stxServeSearch` — an
+    // internal, double-underscored name nobody would guess. So the ordinary
+    // case of a filtered, paginated list page had no supported way to read
+    // `?state=closed&page=2`.
+    //
+    // Always an object, like `params`, so `query.state` on a request with no
+    // query string is undefined rather than a crash. A repeated key keeps its
+    // last value, matching what `URLSearchParams.get` returns.
+    context.query = Object.fromEntries(new URLSearchParams(search ?? ''))
     if (host)
       context.host = host
     context.cookies = cookies

packages/bun-plugin/test/serve-component-dynamic-route.test.ts

@@ -0,0 +1,118 @@
+/**
+ * A component's `<script server>` doing async work, across route kinds.
+ *
+ * Three shapes that look interchangeable and are easy to assume are:
+ *
+ *   static route  + component + await
+ *   dynamic route + view      + await
+ *   dynamic route + component + await
+ *
+ * All three work. They are pinned because when one of them silently stops
+ * working the symptom is not an error: a component whose data never arrives
+ * renders its own empty-state branch, so the page looks like a correct answer
+ * rather than a failure, and nothing is logged.
+ */
+
+import { afterAll, beforeAll, describe, expect, it, setDefaultTimeout } from 'bun:test'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+
+setDefaultTimeout(60_000)
+
+const PORT = 43_100 + (process.pid % 700)
+const BASE = `http://localhost:${PORT}`
+const SERVE_SRC = path.join(import.meta.dir, '..', 'src', 'serve.ts')
+
+let dir: string
+let proc: ReturnType<typeof Bun.spawn> | null = null
+
+function parseProbe(html: string): Record<string, unknown> {
+  const m = html.match(/PROBE::(.*?)::END/s)
+  if (!m)
+    throw new Error(`no probe marker in response:\n${html.slice(0, 500)}`)
+  return JSON.parse(m[1].replace(/&quot;/g, '"').replace(/&amp;/g, '&'))
+}
+
+beforeAll(async () => {
+  dir = await mkdtemp(path.join(tmpdir(), 'stx-comp-dyn-'))
+
+  // A component that does async work and reports what it got back. Bun.sleep
+  // stands in for the database round trip that first showed this.
+  await Bun.write(path.join(dir, 'components', 'AsyncProbe.stx'), `<script server>
+const label = String(who)
+await Bun.sleep(1)
+const loaded = await Promise.resolve('loaded-' + label)
+const probeJson = JSON.stringify({ label, loaded })
+</script>
+<div>PROBE::{{ probeJson }}::END</div>
+`)
+
+  // Static route rendering that component.
+  await Bun.write(path.join(dir, 'views', 'static-host.stx'), `<AsyncProbe who="alpha" />
+`)
+
+  // Dynamic route rendering the same component.
+  await Bun.write(path.join(dir, 'views', 'dyn', '[slug].stx'), `<AsyncProbe who="{{ params.slug }}" />
+`)
+
+  // Dynamic route doing the same async work in the view itself, as the control.
+  await Bun.write(path.join(dir, 'views', 'inline', '[slug].stx'), `<script server>
+const label = String(params.slug)
+await Bun.sleep(1)
+const loaded = await Promise.resolve('loaded-' + label)
+const probeJson = JSON.stringify({ label, loaded })
+</script>
+<div>PROBE::{{ probeJson }}::END</div>
+`)
+
+  await Bun.write(path.join(dir, 'driver.ts'), `import { serve } from ${JSON.stringify(SERVE_SRC)}
+
+serve({ patterns: ['views'], port: ${PORT} })
+`)
+
+  proc = Bun.spawn(['bun', path.join(dir, 'driver.ts')], { cwd: dir, stdout: 'pipe', stderr: 'pipe' })
+
+  for (let i = 0; i < 100; i++) {
+    try {
+      await fetch(`${BASE}/static-host`)
+      break
+    }
+    catch {
+      await Bun.sleep(100)
+    }
+  }
+})
+
+afterAll(async () => {
+  proc?.kill()
+  await rm(dir, { recursive: true, force: true })
+})
+
+describe('component <script server> across route kinds', () => {
+  it('resolves async work in a component on a static route', async () => {
+    const probe = parseProbe(await (await fetch(`${BASE}/static-host`)).text())
+
+    expect(probe.label).toBe('alpha')
+    expect(probe.loaded).toBe('loaded-alpha')
+  })
+
+  it('resolves async work in the view of a dynamic route', async () => {
+    const probe = parseProbe(await (await fetch(`${BASE}/inline/bravo`)).text())
+
+    expect(probe.label).toBe('bravo')
+    expect(probe.loaded).toBe('loaded-bravo')
+  })
+
+  /**
+   * The combination most likely to be missed: a component, on a dynamic route,
+   * whose value comes from behind an await. Both the prop binding and the
+   * resolved value have to survive.
+   */
+  it('resolves async work in a component on a dynamic route', async () => {
+    const probe = parseProbe(await (await fetch(`${BASE}/dyn/charlie`)).text())
+
+    expect(probe.label).toBe('charlie')
+    expect(probe.loaded).toBe('loaded-charlie')
+  })
+})

packages/bun-plugin/test/serve-request-context.test.ts

@@ -59,6 +59,11 @@ const probe = {
   merged: typeof __stxServeContext !== 'undefined' ? (__stxServeContext.mergedFromHook ?? null) : null,
   routeParamsId: route.params.id ?? null,
   routeQueryX: route.query.x ?? null,
+  // query is the counterpart to params: the query string as an object,
+  // rather than an internal string name nobody would guess.
+  queryX: query?.x ?? null,
+  queryMissing: query?.nope ?? null,
+  queryIsObject: typeof query === 'object' && query !== null,
 }
 const probeJson = JSON.stringify(probe)
 </script>
@@ -71,6 +76,7 @@ const probeJson = JSON.stringify(probe)
 const probe = {
   cookieToken: cookies?.token ?? null,
   search: typeof __stxServeSearch !== 'undefined' ? __stxServeSearch : null,
+  queryX: query?.x ?? null,
 }
 const probeJson = JSON.stringify(probe)
 </script>
@@ -147,6 +153,33 @@ describe('dynamic route params in <script server>', () => {
     expect(probe.routeQueryX).toBe('1')
   })
 
+  /**
+   * `query` is the counterpart to `params`. Without it the query string was
+   * reachable only through `__stxServeSearch` - an internal, double-underscored
+   * name - so the ordinary filtered, paginated list page had no supported way
+   * to read `?state=closed&page=2`.
+   */
+  it('exposes the query string as an object beside params', async () => {
+    const probe = parseProbe(await fetchText(`${BASE}/probe/x?x=1`))
+
+    expect(probe.queryX).toBe('1')
+    expect(probe.queryIsObject).toBe(true)
+  })
+
+  it('is an empty object, not a crash, when there is no query string', async () => {
+    const probe = parseProbe(await fetchText(`${BASE}/probe/x`))
+
+    expect(probe.queryIsObject).toBe(true)
+    expect(probe.queryX).toBeNull()
+    expect(probe.queryMissing).toBeNull()
+  })
+
+  it('reaches static routes too, not only dynamic ones', async () => {
+    const probe = parseProbe(await fetchText(`${BASE}/slow?x=static`))
+
+    expect(probe.queryX).toBe('static')
+  })
+
   it('carries escaped client route params in SPA fragments', async () => {
     const res = await fetch(`${BASE}/probe/%3Cjob-15%3E`, {
       headers: { 'X-STX-Router': 'true' },