Utilize searchParams when querying data

Describe the problem

SvelteKit currently provides access to reactive URL search params in two ways:

• Server side with getRequestEvent
• Client side with page.url.searchParams

Sometimes I build forms to manipulate URL searchParams that invalidate load to query new data. To set initial values, I need to parse search params and ensure the form updates when params change.

For example:

<script>
  import { getUsers } from '$lib/data.remote'
  import { page } from '$app/state'

  const name = $derived(page.url.searchParams.get('name'))
  const lastSignin = $derived(page.url.searchParams.get('lastSignin'))
</script>

<form method="GET">
  <label>
    Name <input name="name" defaultValue={name} />
    Earliest sign in time <input type="date" name="lastSignin" defaultValue={lastSignin} />

    <button>Search users</button>
  </label>
</form>

{const user = $derived(await getUsers(name, lastSignin))}
<p>User is {user.fullName}, last login {user.lastLoginDate}</p>

Describe the proposed solution

This is fine in basic cases where you don't want to write to URL params, and you want your GET form to push history with modified URL search params, and those params trigger new calls to dependent queries on the page. Some considerations include parsing param values into desired types, or to prevent XSS or URL injection attacks.

What if we can remove some of the boilerplate with an enhanced query, or a new remote function urlQuery:

src/lib/date.remote.ts

import { urlQuery } from '$app/server'
import { client } from './db'
import * as v from 'valibot'

export const searchUsers = urlQuery(
  v.object({
    name: v.pipe(v.string(), v.nonEmpty()),
    lastSignin:v.pipe(v.date(), v.optional())
  }),
  async ({ name, lastSignin }) => {
    // fetch from db
    const data = client.query(/* */)

    return data
  }
)

src/routes/+page.svelte

<script>
  import { searchUsers } from '$lib/data.remote'
</script>

<!--
  may be redundant since query can be defined anywhere
  and user should navigate to the current route
-->
<form {...searchUsers.form}>
  <label>
    Name <input {...searchUsers.fields.name.as('text') />
    Earliest sign in time <input {...searchUsers.fields.lastSignin.as('date') />

    <button>Search users</button>
  </label>
</form>

<!-- data is queried using URL search params -->
{const users = $derived(await searchUsers.fromUrlParams())}
<h2>Found users</h2>
{#each users as user}
  <p>User is {user.fullName}, last login {user.lastLoginDate}</p>
{/each}

<!-- plain query-like usage -->
{const usersStartingWithB = $derived(await searchUsers({ name: 'B' })
<h2>Users starting with B</h2>
{#each usersStartingWithB as user}
  <p>{user.fullName}</p>
{/each}

Benefits include:

• URL param values are reactive where consumed
• URL param values are parsed and sanitized for safe usage and types
• URL params can be read where needed, and are already parsed and transformed by your schema

<script>
  import { getUsers } from '$lib/data.remote'

  // reactive urlParam, reactive, and parsed and transformed by your schema
  const lastSigninDate = $derived(getUsers.urlParams.lastSignin)
</script>

Alternatives considered

Glue together page.url.searchParams myself.

Importance

nice to have

Additional Information

No response

Start by reviewing the query and remote-function entry points relevant to the examples in src/lib/date.remote.ts and src/routes/+page.svelte. Define the intended API and its scope before implementation; done should cover schema-backed URL parameter parsing, reactive consumption, form bindings, and direct query calls.