@urbicon-ui/sveltekit-utils 8.19.0 → 8.21.0

package/README.md

@@ -4,7 +4,7 @@ Small, focused SvelteKit helpers that Urbicon apps share. Zero runtime dependenc
 
 Currently shipping:
 
-- **URL-state runes** — reactive `useUrlParam` / `useUrlArrayParam` that keep component state in sync with `?query=` parameters
+- **URL-state runes** — reactive `useUrlParam` / `useUrlArrayParam` that keep component state in sync with `?query=` parameters, and `withSearchParams` for the links that change them
 - **Table view ↔ URL** — `bindViewToUrl`, the URL home for a `@urbicon-ui/table` view object (`?q=…&sort=…&page=…`), plus the pure serializers for the load path
 - **Cron runner** — interval-based background fetcher for scheduled server endpoints
 - **SSE stream reader** — `streamSse`, a spec-correct async-generator client for one-shot POST `text/event-stream` endpoints (LLM relays)
@@ -53,9 +53,57 @@ import { updateUrlSearchParams } from '@urbicon-ui/sveltekit-utils/url.svelte';
 updateUrlSearchParams({ page: '1', tag: ['a', 'b'] }, { replaceState: true });
 ```
 
+A link needs an address, not a setter. `withSearchParams(url, patch)` is the pure core that `updateUrlSearchParams` and `createUrlParam`'s setter navigate to: the address `url` has after `patch` — a scalar `set`s its key, an array `append`s each element, `null` removes the key, every other param stays as it is. An empty string is a value and keeps its key (`?a=`); an empty array appends nothing and so removes it. It reads nothing from the page and navigates nowhere, so the same call builds a link's `href` and a redirect's location.
+
+<!-- typecheck -->
+```typescript
+import { withSearchParams } from '@urbicon-ui/sveltekit-utils/search-params';
+
+const url = new URL('https://films.test/archive?sort=title&page=3');
+
+withSearchParams(url, { sort: 'year' }); // '/archive?page=3&sort=year'
+withSearchParams(url, { tag: ['noir', 'silent'] }); // '/archive?sort=title&page=3&tag=noir&tag=silent'
+withSearchParams(url, { sort: null, page: null }); // '/archive'
+```
+
+`./search-params` is the import path that reaches no `$app/*` module, so a `load`, a form action or a plain test can use it; importing `withSearchParams` from `./url.svelte` (or from the package root) is the same function, but pulls SvelteKit's client runtime along:
+
+<!-- typecheck -->
+```typescript
+// src/routes/archive/+page.server.ts
+import { withSearchParams } from '@urbicon-ui/sveltekit-utils/search-params';
+import type { PageServerLoad } from './$types';
+
+export const load: PageServerLoad = ({ url }) => {
+  const current = Number(url.searchParams.get('page') ?? '1');
+  return {
+    // Page 1 is the default, so its link carries no `page` at all.
+    prevHref: withSearchParams(url, { page: current > 2 ? String(current - 1) : null }),
+    nextHref: withSearchParams(url, { page: String(current + 1) })
+  };
+};
+```
+
+In a component the URL to start from is `page.url`, and the result is the `href`:
+
+```svelte
+<script lang="ts">
+  import { page } from '$app/state';
+  import { withSearchParams } from '@urbicon-ui/sveltekit-utils/url.svelte';
+</script>
+
+<a href={withSearchParams(page.url, { sort: 'year', page: null })}>Sort by year</a>
+```
+
+Not on a prerendered page: SvelteKit makes `url.searchParams` throw there — the emitted HTML must not depend on a query string that will not exist at request time — and `withSearchParams` reads it. `useUrlParam` guards that case for you by yielding its `initial` while `building`; a link on such a page has to be built after hydration, or from a `URL` you construct rather than the page's.
+
+Link or binding: an `href` from `withSearchParams` where the reader picks a destination — a sort header, a pagination step, a filter chip — and the address should exist before the click, so it can be hovered, middle-clicked and crawled; `useUrlParam` where a control owns a value that keeps changing — a search box, a slider — and the URL follows it.
+
 **Design notes**
 
 - URL updates use `goto()` with `replaceState: true`, `noScroll: true`, `keepFocus: true` — suited for filter/pagination UIs, not full page transitions.
+- `updateUrlSearchParams` and `createUrlParam`'s setter hand `goto` the pathname-qualified address `withSearchParams` returns, never a bare `?query`. `goto` resolves a relative target against `document.baseURI`, which equals the page's own URL only while the document carries no `<base href>` — with one, `?page=2` keeps the base's path, not the page's.
+- `bindViewToUrl` is a third URL writer and does **not** go through `withSearchParams`: it merges the view axes itself and carries the URL hash across, where `withSearchParams` drops it. Do not read one policy off the other.
 - `useUrlParam` returns getters (not Svelte stores) so consumers can read the value lazily inside `$derived`/`$effect`.
 
 ## Table View ↔ URL (`url.svelte` + `table-view`)
@@ -123,6 +171,8 @@ The `./table-query` subpath that used to hold a second copy of this codec — sa
 
 Fire HTTP requests against SvelteKit server endpoints on an interval. Pair with a shared-secret header so endpoints can authenticate scheduled calls.
 
+**Import from `@urbicon-ui/sveltekit-utils/cron`**, not from the package root. The runner is wired up in server code — `hooks.server.ts`, or a module it imports — and the root barrel carries `url.svelte` along, whose `$app/navigation` and `$app/state` imports are SvelteKit's client runtime. The subpath reaches no `$app/*` module at all.
+
 <!-- typecheck -->
 ```typescript
 // src/lib/server/cron.ts
@@ -146,8 +196,13 @@ export const cron = createCronRunner({
 });
 
 cron.start();
+// Under `vite dev` this module is re-evaluated on every edit; without the
+// teardown the previous evaluation's timers keep ticking beside the new ones.
+import.meta.hot?.dispose(() => cron.stop());
 ```
 
+The first fire happens **after** one interval: `start()` arms the timers, it does not call anything. A job with `intervalSeconds: 3600` armed at boot first knocks an hour later, so nothing runs at deploy time — if you need work done at startup, do it at startup.
+
 Receive the call and verify the secret inside your endpoint:
 
 <!-- typecheck -->
@@ -166,6 +221,50 @@ export const POST: RequestHandler = async ({ request }) => {
 };
 ```
 
+**`onError` is required**
+
+It is the only channel a failing job has. The runner calls it when the `fetch` rejects and when the endpoint answers non-2xx (with the status on `error.status`), and it reports nothing anywhere else — a nightly job that has been answering 403 since a secret rotation looks exactly like a job that works. A missing handler, or one that is not a function, throws a `TypeError` from `createCronRunner`: at wiring time, where a startup failure is read, rather than on the first failed tick at 3 a.m.
+
+The handler may be `async` — a webhook, a row in a table — and the runner awaits it. One that throws or rejects does not stop the schedule: the runner writes both errors, the handler's and the job's, to `console.error` and keeps ticking. Letting either escape the interval callback would end the process as an unhandled rejection, and one broken log call would take every other job with it.
+
+**Two runners on one path**
+
+In development the runner warns on `console.warn` when `start()` arms a path another runner in the same process is already ticking — the situation a hot reload produces, where both runners fire and the endpoint sees twice the traffic. `import.meta.hot?.dispose(() => cron.stop())` next to the `start()` call is the fix; the warning names it too. Two runners aimed at one path on purpose (different intervals, say) look the same from the inside and will be warned about as well. One runner whose `jobs` array names the same path twice is a different mistake — no second runner to stop — and gets its own warning.
+
+**A daily job on an interval runner**
+
+There are intervals here and no cron expressions — no "at 03:00". A job that should happen once a day therefore ticks hourly and lets the endpoint decide whether there is work: the first tick after midnight does the day's work, the rest of the day's ticks find it done. The phase is the boot time, not the full hour, so that first tick lands up to one interval after midnight and every deploy moves it — in exchange, `setInterval` counts duration rather than wall-clock, so a daylight-saving change neither skips a tick nor fires one twice.
+
+That holds together when the endpoint is idempotent, which means
+
+- the outcome is a **function of the calendar day**, not a counter that advances once per call — and a day needs a zone, so the key below is formatted in one. `toISOString()` would key on UTC, where the day turns at 02:00 local in a Berlin summer and 01:00 in winter;
+- running it twice does nothing twice: the second call writes the same row. Behind a load balancer two instances tick at once, so that write has to be atomic — `INSERT … ON CONFLICT DO UPDATE`, not read-modify-write;
+- a restart loses nothing _within_ a day. Whether it can lose a whole one depends on the shape: a job that computes from state — last activity, say — heals a skipped day on its next tick, while a per-day rollup like the one below only ever writes today and needs a backfill for the day the process was down.
+
+<!-- typecheck -->
+```typescript
+// src/routes/api/cron/daily/+server.ts
+import { env } from '$env/dynamic/private';
+import { upsertDailyRollup } from '$lib/server/rollup';
+import type { RequestHandler } from './$types';
+
+// Which midnight: the zone your people live in. `en-CA` formats as YYYY-MM-DD.
+const TIME_ZONE = 'Europe/Berlin';
+const dayKey = new Intl.DateTimeFormat('en-CA', { timeZone: TIME_ZONE });
+
+export const POST: RequestHandler = async ({ request }) => {
+  if (!env.CRON_SECRET || request.headers.get('x-cron-secret') !== env.CRON_SECRET) {
+    return new Response('Forbidden', { status: 403 });
+  }
+  // Keyed on the day and written atomically, so the second call of the day —
+  // or the second instance behind the load balancer — rewrites the same row
+  // instead of adding one. No "last run" timestamp: that would be scheduler
+  // state in your schema, and it is what turns a missed tick into a missed day.
+  await upsertDailyRollup(dayKey.format(new Date()));
+  return new Response('ok');
+};
+```
+
 **Design notes**
 
 - Simple `setInterval`-based scheduler. No drift compensation, no distributed locking, no exponential backoff — intended for single-process SvelteKit deployments. For scale-out scenarios use a real scheduler (e.g. BullMQ) and point it at the same HTTP endpoints.
@@ -228,15 +327,16 @@ export const POST: RequestHandler = async ({ request }) => {
 
 ## Exports
 
-| Subpath         | Contents                                                                                                                                           |
-| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `.`             | Barrel of all modules                                                                                                                              |
-| `./url.svelte`  | `useUrlParam`, `useUrlArrayParam`, `createUrlParam`, `updateUrlSearchParams`, `bindViewToUrl`, types                                               |
-| `./table-view`  | `searchParamsToViewSnapshot`, `searchParamsToViewPartial`, `viewSnapshotToSearchParams`, `applyViewToSearchParams`, `assertValidViewSnapshot`, `viewAxesNamedBy`, `viewAxisKeys`, `TABLE_VIEW_AXES`, `TABLE_VIEW_FILTER_OPERATORS`, `TableViewLike`, types |
-| `./cron`        | `createCronRunner`, `CronJob`, `CronRunnerConfig`, `CronRunner`                                                                                    |
-| `./sse`         | `streamSse`, `SseEvent`, `StreamSseOptions`, `SseRequestError`                                                                                     |
+| Subpath           | Contents                                                                                                                                         |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.`               | Barrel of all modules                                                                                                                            |
+| `./url.svelte`    | `useUrlParam`, `useUrlArrayParam`, `createUrlParam`, `updateUrlSearchParams`, `bindViewToUrl`, types (re-exports `withSearchParams`)             |
+| `./search-params` | `withSearchParams`, `SearchParamsPatch` — no `$app/*` import                                                                                     |
+| `./table-view`    | `searchParamsToViewSnapshot`, `searchParamsToViewPartial`, `viewSnapshotToSearchParams`, `applyViewToSearchParams`, `assertValidViewSnapshot`, `viewAxesNamedBy`, `viewAxisKeys`, `TABLE_VIEW_AXES`, `TABLE_VIEW_FILTER_OPERATORS`, `TableViewLike`, types |
+| `./cron`          | `createCronRunner`, `CronJob`, `CronRunnerConfig`, `CronRunner`                                                                                  |
+| `./sse`           | `streamSse`, `SseEvent`, `StreamSseOptions`, `SseRequestError`                                                                                   |
 
-`bindViewToUrl` lives in its own module (`view-binding.svelte.ts`) and is re-exported from `./url.svelte`, which is its documented import path — it has no subpath of its own. `./table-view` is SvelteKit-free (it touches no `$app/*`), which is what lets a `load` function and a plain test use it; `./url.svelte` is the half that needs the router.
+`bindViewToUrl` lives in its own module (`view-binding.svelte.ts`) and is re-exported from `./url.svelte`, which is its documented import path — it has no subpath of its own. `./search-params`, `./table-view` and `./cron` are SvelteKit-free (they touch no `$app/*`), which is what lets a `load` function, `hooks.server.ts` and a plain test use them; `./url.svelte` is the half that needs the router — importing it from server code pulls SvelteKit's client runtime in, which is why `withSearchParams` has a subpath of its own as well as the re-export.
 
 ## Development
 

package/dist/cron.d.ts

@@ -42,16 +42,22 @@ export interface CronRunnerConfig {
      *   an `Error` naming the job and status, with the numeric code attached as
      *   `error.status` (e.g. `500`, `403`).
      *
-     * Without a handler both failure modes are swallowed silently — pass one to
-     * observe per-run outcomes.
+     * Required: it is the runner's only outward channel, and nothing else
+     * observes a job that has been answering 403 for weeks. May be `async` — the
+     * runner awaits it; one that throws or rejects is reported on `console.error`
+     * and does not stop the schedule.
      */
-    onError?: (job: CronJob, error: Error) => void;
+    onError: (job: CronJob, error: Error) => void | Promise<void>;
 }
 /** Handle returned by {@link createCronRunner}. */
 export interface CronRunner {
     /**
      * Arm every job's interval timer. Idempotent — calling `start()` while
      * already running is a no-op (does not double-schedule).
+     *
+     * When `import.meta.env.DEV` is set, two wiring mistakes are reported on
+     * `console.warn`: a path another runner in this process already ticks, and
+     * one listed twice in the same `jobs` array.
      */
     start(): void;
     /**
@@ -72,8 +78,14 @@ export interface CronRunner {
  * for scale-out point a real scheduler (BullMQ, a platform cron) at the same
  * endpoints instead. The runner starts idle — call `start()` explicitly.
  *
- * @param config - Secret/header, base URL, and the jobs to schedule.
+ * Import from `@urbicon-ui/sveltekit-utils/cron`, not from the package root:
+ * the root barrel carries `url.svelte`, whose `$app/*` imports have no business
+ * in `hooks.server.ts`.
+ *
+ * @param config - Secret/header, base URL, the jobs to schedule, and the
+ *   required `onError` handler.
  * @returns A {@link CronRunner} handle (`start` / `stop` / `isRunning`).
+ * @throws TypeError if `onError` is not a function.
  * @example
  * ```typescript
  * // src/lib/server/cron.ts
@@ -95,6 +107,7 @@ export interface CronRunner {
  * });
  *
  * cron.start();
+ * import.meta.hot?.dispose(() => cron.stop());
  * ```
  */
 export declare function createCronRunner(config: CronRunnerConfig): CronRunner;

package/dist/cron.js

@@ -1,3 +1,44 @@
+// Which job paths this process currently ticks, and how many runners tick each.
+// The registry hangs off `globalThis` under a `Symbol.for` key rather than
+// living in this module's scope: under `vite dev` a server module is
+// re-evaluated on a hot reload, and the fresh evaluation gets a fresh
+// module scope while the previous evaluation's timers keep firing — the very
+// situation the warning below exists for. `globalThis` survives it, the module
+// scope does not.
+const CRON_REGISTRY = Symbol.for('urbicon-ui.sveltekit-utils.cron');
+function armedPaths() {
+    const host = globalThis;
+    const known = host[CRON_REGISTRY];
+    if (known)
+        return known;
+    const paths = new Map();
+    host[CRON_REGISTRY] = paths;
+    return paths;
+}
+/** Register one armed path; returns how many runners already ticked it. */
+function claimPath(path) {
+    const paths = armedPaths();
+    const armed = paths.get(path) ?? 0;
+    paths.set(path, armed + 1);
+    return armed;
+}
+function releasePath(path) {
+    const paths = armedPaths();
+    const armed = (paths.get(path) ?? 1) - 1;
+    if (armed > 0)
+        paths.set(path, armed);
+    else
+        paths.delete(path);
+}
+function warnDoubleStart(path, armed) {
+    const others = armed === 1 ? 'another runner is' : `${armed} other runners are`;
+    console.warn(`[createCronRunner] start() armed "${path}" while ${others} already ticking it in this process — every one of them fires and the endpoint sees the traffic of all. A hot reload under \`vite dev\` is the usual cause: put \`import.meta.hot?.dispose(() => runner.stop())\` next to the start() call. Otherwise call stop() on the runner you replaced.`);
+}
+// One runner, one path listed twice: neither remedy above applies, so this is
+// its own sentence rather than a plural of the one above.
+function warnDuplicateJob(path) {
+    console.warn(`[createCronRunner] start() armed "${path}" twice from one jobs list; the endpoint gets every tick twice. Remove the duplicate entry.`);
+}
 /**
  * Create a background runner that fires HTTP requests at SvelteKit server
  * endpoints on a fixed interval — a minimal in-process cron for scheduled work
@@ -8,8 +49,14 @@
  * for scale-out point a real scheduler (BullMQ, a platform cron) at the same
  * endpoints instead. The runner starts idle — call `start()` explicitly.
  *
- * @param config - Secret/header, base URL, and the jobs to schedule.
+ * Import from `@urbicon-ui/sveltekit-utils/cron`, not from the package root:
+ * the root barrel carries `url.svelte`, whose `$app/*` imports have no business
+ * in `hooks.server.ts`.
+ *
+ * @param config - Secret/header, base URL, the jobs to schedule, and the
+ *   required `onError` handler.
  * @returns A {@link CronRunner} handle (`start` / `stop` / `isRunning`).
+ * @throws TypeError if `onError` is not a function.
  * @example
  * ```typescript
  * // src/lib/server/cron.ts
@@ -31,16 +78,55 @@
  * });
  *
  * cron.start();
+ * import.meta.hot?.dispose(() => cron.stop());
  * ```
  */
 export function createCronRunner(config) {
+    if (typeof config.onError !== 'function') {
+        throw new TypeError(`[createCronRunner] onError is required and must be a function (received ${typeof config.onError}). It is the only channel a failing job has: without it a 403 or a 500 on every tick is indistinguishable from a job that works. Pass \`onError: (job, err) => console.error(job.path, err)\` if the server log is where you read it.`);
+    }
     const timers = [];
+    // What this runner put into the process-wide registry, so `stop()` returns
+    // exactly that — reading `config.jobs` again would release paths this runner
+    // never claimed, and nothing at all if the consumer has since emptied the
+    // array. Empty unless a `start()` claimed, which is also what makes a second
+    // `stop()` a no-op without a flag to ask.
+    let claimed = [];
     let running = false;
+    // The handler is the consumer's error channel, so when it fails there is no
+    // second one to report on — and letting the failure escape this async
+    // interval callback ends the process: an unhandled rejection exits node
+    // (25.2.1) and bun (1.4.2) with code 1, so one broken log call would take the
+    // app down and stop every other job with it. The `await` is what makes that
+    // hold for an `async` handler too: its rejection reaches no `try` block that
+    // does not await it, and neither does any other thenable's.
+    const report = async (job, error) => {
+        try {
+            await config.onError(job, error);
+        }
+        catch (handlerError) {
+            console.error(`[createCronRunner] the onError handler threw or rejected while reporting a failure of "${job.path}"; the schedule keeps running. Handler error, then the job error:`, handlerError, error);
+        }
+    };
     return {
         start() {
             if (running)
                 return;
             running = true;
+            if (import.meta.env?.DEV) {
+                for (const path of config.jobs.map((job) => job.path)) {
+                    // One claim per path per runner: the registry counts runners, and a
+                    // path listed twice is its own mistake with its own warning.
+                    if (claimed.includes(path)) {
+                        warnDuplicateJob(path);
+                        continue;
+                    }
+                    claimed.push(path);
+                    const armed = claimPath(path);
+                    if (armed > 0)
+                        warnDoubleStart(path, armed);
+                }
+            }
             for (const job of config.jobs) {
                 const timer = setInterval(async () => {
                     const base = config.baseUrl ?? 'http://localhost:3000';
@@ -53,23 +139,23 @@ export function createCronRunner(config) {
                     }
                     catch (err) {
                         // Network-level failure (DNS, connection refused, abort): fetch rejected.
-                        config.onError?.(job, err);
+                        await report(job, err);
                         return;
                     }
-                    // The request completed; a non-2xx status is still a failure. Handle it
-                    // outside the try so a throwing `onError` escapes as an unhandled
-                    // rejection rather than being re-caught and re-invoked here — symmetric
-                    // with the rejection path above.
+                    // The request completed; a non-2xx status is still a failure.
                     if (!response.ok) {
                         const err = new Error(`Cron job "${job.path}" returned ${response.status} ${response.statusText}`);
                         err.status = response.status;
-                        config.onError?.(job, err);
+                        await report(job, err);
                     }
                 }, job.intervalSeconds * 1000);
                 timers.push(timer);
             }
         },
         stop() {
+            for (const path of claimed)
+                releasePath(path);
+            claimed = [];
             running = false;
             timers.forEach(clearInterval);
             timers.length = 0;

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './cron.js';
+export * from './search-params.js';
 export * from './sse.js';
 export * from './table-view.js';
 export * from './url.svelte.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from './cron.js';
+export * from './search-params.js';
 export * from './sse.js';
 export * from './table-view.js';
 export * from './url.svelte.js';

package/dist/search-params.d.ts

@@ -0,0 +1,41 @@
+/**
+ * What {@link withSearchParams} applies to a URL: a plain record, or a
+ * `URLSearchParams` whose repeated keys survive the merge.
+ */
+export type SearchParamsPatch = URLSearchParams | Record<string, string | string[] | null | undefined>;
+/**
+ * The address `url` has after `patch` — the pure core that
+ * `updateUrlSearchParams` and `createUrlParam`'s setter navigate to. Returns
+ * `pathname?query`, or the pathname alone once no param is left, so the result
+ * serves as a link's `href`, a redirect's location, or the argument of `goto`.
+ * Reads nothing from the page, mutates neither argument, navigates nowhere.
+ *
+ * Merge semantics per key in `patch`: the key is first cleared, then
+ * re-applied — a record value `set`s a scalar, `append`s each array element,
+ * and **removes** the key entirely for `null`/`undefined`; a `URLSearchParams`
+ * re-appends all of its entries, so repeated keys survive. An empty string is a
+ * value and keeps its key (`?a=`); an empty array appends nothing and therefore
+ * removes it. A param the patch does not name keeps its value and its position;
+ * a patched key moves behind them. The hash is not carried.
+ *
+ * A `url.pathname` that itself begins with `//` comes back origin-qualified
+ * (`https://host//films?page=2`): left relative, `//films` is a
+ * protocol-relative URL naming `films` as the host.
+ *
+ * @param url - The URL to start from — `page.url` in a component, `url` in a
+ *   `load`. SvelteKit makes `url.searchParams` throw while prerendering
+ *   (`@sveltejs/kit/src/utils/url.js` `disable_search`: the emitted HTML must
+ *   not depend on a query string), and this reads it.
+ * @param patch - Params to apply. A record value of `null`/`undefined` deletes
+ *   that key.
+ * @returns Pathname plus the merged query: `/films?sort=year`.
+ * @example
+ * ```typescript
+ * withSearchParams(new URL('https://x.test/films?sort=title&page=3'), {
+ *   sort: 'year',
+ *   page: null
+ * });
+ * // '/films?sort=year'
+ * ```
+ */
+export declare function withSearchParams(url: URL, patch: SearchParamsPatch): string;

package/dist/search-params.js

@@ -0,0 +1,62 @@
+/**
+ * The address `url` has after `patch` — the pure core that
+ * `updateUrlSearchParams` and `createUrlParam`'s setter navigate to. Returns
+ * `pathname?query`, or the pathname alone once no param is left, so the result
+ * serves as a link's `href`, a redirect's location, or the argument of `goto`.
+ * Reads nothing from the page, mutates neither argument, navigates nowhere.
+ *
+ * Merge semantics per key in `patch`: the key is first cleared, then
+ * re-applied — a record value `set`s a scalar, `append`s each array element,
+ * and **removes** the key entirely for `null`/`undefined`; a `URLSearchParams`
+ * re-appends all of its entries, so repeated keys survive. An empty string is a
+ * value and keeps its key (`?a=`); an empty array appends nothing and therefore
+ * removes it. A param the patch does not name keeps its value and its position;
+ * a patched key moves behind them. The hash is not carried.
+ *
+ * A `url.pathname` that itself begins with `//` comes back origin-qualified
+ * (`https://host//films?page=2`): left relative, `//films` is a
+ * protocol-relative URL naming `films` as the host.
+ *
+ * @param url - The URL to start from — `page.url` in a component, `url` in a
+ *   `load`. SvelteKit makes `url.searchParams` throw while prerendering
+ *   (`@sveltejs/kit/src/utils/url.js` `disable_search`: the emitted HTML must
+ *   not depend on a query string), and this reads it.
+ * @param patch - Params to apply. A record value of `null`/`undefined` deletes
+ *   that key.
+ * @returns Pathname plus the merged query: `/films?sort=year`.
+ * @example
+ * ```typescript
+ * withSearchParams(new URL('https://x.test/films?sort=title&page=3'), {
+ *   sort: 'year',
+ *   page: null
+ * });
+ * // '/films?sort=year'
+ * ```
+ */
+export function withSearchParams(url, patch) {
+    const next = new URLSearchParams(url.searchParams);
+    if (patch instanceof URLSearchParams) {
+        for (const [key] of patch)
+            next.delete(key);
+        for (const [key, value] of patch)
+            next.append(key, value);
+    }
+    else {
+        for (const [key, value] of Object.entries(patch)) {
+            next.delete(key);
+            if (Array.isArray(value)) {
+                for (const v of value)
+                    next.append(key, v);
+            }
+            else if (value != null) {
+                next.set(key, value);
+            }
+        }
+    }
+    const query = next.toString();
+    const address = query ? `${url.pathname}?${query}` : url.pathname;
+    // A leading `//` makes the address protocol-relative: as an `href` or a
+    // `goto` target `//films` names `films` as the host, not a path on this one.
+    // The origin is what disambiguates it; every other pathname stays relative.
+    return url.pathname.startsWith('//') ? `${url.origin}${address}` : address;
+}

package/dist/url.svelte.d.ts

@@ -1,3 +1,5 @@
+import { type SearchParamsPatch } from './search-params.js';
+export { type SearchParamsPatch, withSearchParams } from './search-params.js';
 export { bindViewToUrl, type UrlViewBindingOptions } from './view-binding.svelte.js';
 /**
  * How {@link useUrlArrayParam} maps an array onto the URL:
@@ -30,24 +32,21 @@ export type UrlParamOptions<T> = {
 };
 /**
  * Low-level escape hatch to update several params at once via `goto` (without a
- * full navigation). Starts from the current URL, applies `next`, and keeps
- * every unrelated param.
- *
- * Merge semantics per key in `next`: the key is first cleared, then re-applied
- * — a `URLSearchParams` re-appends all of its entries (repeated keys survive),
- * a record `set`s a scalar, `append`s each array element, and **removes** the
- * key entirely for a `null`/`undefined` value.
+ * full navigation). Navigates to the address {@link withSearchParams} builds
+ * from the current URL and `next`, so every unrelated param is kept; the merge
+ * semantics per key are documented there.
  *
  * @param next - Params to apply, as `URLSearchParams` or a plain record. A
  *   record value of `null`/`undefined` deletes that key.
  * @param opts - `replaceState` (default `true`) — replace vs. push history.
  * @example
  * ```typescript
+ * // on /films?filter=old
  * updateUrlSearchParams({ page: '1', tag: ['a', 'b'], filter: null });
- * // ?page=1&tag=a&tag=b   (any prior `filter` param is dropped)
+ * // navigates to /films?page=1&tag=a&tag=b   (the prior `filter` param is dropped)
  * ```
  */
-export declare function updateUrlSearchParams(next: URLSearchParams | Record<string, string | string[]>, opts?: {
+export declare function updateUrlSearchParams(next: SearchParamsPatch, opts?: {
     replaceState?: boolean;
 }): void;
 /**
@@ -58,8 +57,8 @@ export declare function updateUrlSearchParams(next: URLSearchParams | Record<str
  * page URL (tests, a server `load`).
  *
  * `set` rewrites only the keys that `options.serialize` produces (clear +
- * re-append) and preserves the rest, then navigates with `goto`
- * (`replaceState`, `noScroll`, `keepFocus`).
+ * re-append) and preserves the rest, then navigates with `goto` to the address
+ * {@link withSearchParams} builds (`replaceState`, `noScroll`, `keepFocus`).
  *
  * @param _key - Ignored — `options.parse`/`options.serialize` already close
  *   over the key (see {@link useUrlArrayParam}); kept only for signature parity

package/dist/url.svelte.js

@@ -1,6 +1,12 @@
 import { building } from '$app/environment';
 import { goto } from '$app/navigation';
 import { page } from '$app/state';
+import { withSearchParams } from './search-params.js';
+// The pure core of the two writers below, re-exported so this import path
+// carries it next to them. Its own module — and its own `./search-params`
+// subpath — because it must stay free of `$app`: importing this one pulls
+// SvelteKit's client runtime, which a `load` or a form action must not.
+export { withSearchParams } from './search-params.js';
 // The v8 view-object binding lives in its own module; re-exported here so the
 // documented import path (`@urbicon-ui/sveltekit-utils/url.svelte`) carries it.
 // The mirror types (TableViewLike, TableViewSnapshot, …) are exported from the
@@ -12,50 +18,31 @@ import { page } from '$app/state';
 export { bindViewToUrl } from './view-binding.svelte.js';
 /**
  * Low-level escape hatch to update several params at once via `goto` (without a
- * full navigation). Starts from the current URL, applies `next`, and keeps
- * every unrelated param.
- *
- * Merge semantics per key in `next`: the key is first cleared, then re-applied
- * — a `URLSearchParams` re-appends all of its entries (repeated keys survive),
- * a record `set`s a scalar, `append`s each array element, and **removes** the
- * key entirely for a `null`/`undefined` value.
+ * full navigation). Navigates to the address {@link withSearchParams} builds
+ * from the current URL and `next`, so every unrelated param is kept; the merge
+ * semantics per key are documented there.
  *
  * @param next - Params to apply, as `URLSearchParams` or a plain record. A
  *   record value of `null`/`undefined` deletes that key.
  * @param opts - `replaceState` (default `true`) — replace vs. push history.
  * @example
  * ```typescript
+ * // on /films?filter=old
  * updateUrlSearchParams({ page: '1', tag: ['a', 'b'], filter: null });
- * // ?page=1&tag=a&tag=b   (any prior `filter` param is dropped)
+ * // navigates to /films?page=1&tag=a&tag=b   (the prior `filter` param is dropped)
  * ```
  */
-// Local imperative use of URLSearchParams — not reactive state — so the
-// SvelteURLSearchParams wrapper is unnecessary here. Likewise for `goto`:
-// we pass constructed relative paths, not resolved route ids; callers of
-// this helper are free to call `resolve()` at their composition point.
+// This writer and `createUrlParam`'s setter hand `goto` the pathname-qualified
+// address, never a bare `?query`: `goto` resolves a relative target against
+// `document.baseURI` (`@sveltejs/kit/src/runtime/client/utils.js` `resolve_url`,
+// which falls back to the first `<base>` tag), so with a `<base href>` in the
+// document `?page=2` keeps the base's path, not the page's. No harness can
+// separate the two spellings by outcome — both resolve against `page.url` there
+// — so `url.test.ts` pins the string `goto` was handed instead.
+// The address is not a route id either, so no `resolve()` here; callers are
+// free to call it at their composition point.
 export function updateUrlSearchParams(next, opts) {
-    const base = new URLSearchParams(page.url.searchParams);
-    if (next instanceof URLSearchParams) {
-        for (const [k] of next)
-            base.delete(k);
-        for (const [k, v] of next)
-            base.append(k, v);
-    }
-    else {
-        for (const [key, val] of Object.entries(next)) {
-            base.delete(key);
-            if (Array.isArray(val)) {
-                for (const v of val)
-                    base.append(key, v);
-            }
-            else if (val != null) {
-                base.set(key, String(val));
-            }
-        }
-    }
-    const q = base.toString();
-    const path = page.url.pathname;
-    goto(q ? `${path}?${q}` : path, {
+    goto(withSearchParams(page.url, next), {
         replaceState: opts?.replaceState ?? true,
         noScroll: true,
         keepFocus: true
@@ -69,8 +56,8 @@ export function updateUrlSearchParams(next, opts) {
  * page URL (tests, a server `load`).
  *
  * `set` rewrites only the keys that `options.serialize` produces (clear +
- * re-append) and preserves the rest, then navigates with `goto`
- * (`replaceState`, `noScroll`, `keepFocus`).
+ * re-append) and preserves the rest, then navigates with `goto` to the address
+ * {@link withSearchParams} builds (`replaceState`, `noScroll`, `keepFocus`).
  *
  * @param _key - Ignored — `options.parse`/`options.serialize` already close
  *   over the key (see {@link useUrlArrayParam}); kept only for signature parity
@@ -84,14 +71,7 @@ export function updateUrlSearchParams(next, opts) {
 export function createUrlParam(_key, options) {
     const get = (sp) => options.parse(sp) ?? options.initial;
     function setValue(next) {
-        const current = new URLSearchParams(page.url.searchParams);
-        const nextSp = options.serialize(next);
-        for (const [k] of nextSp)
-            current.delete(k);
-        for (const [k, v] of nextSp)
-            current.append(k, v);
-        const q = current.toString();
-        goto(q ? `?${q}` : page.url.pathname, {
+        goto(withSearchParams(page.url, options.serialize(next)), {
             replaceState: options.replaceState ?? true,
             noScroll: true,
             keepFocus: true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urbicon-ui/sveltekit-utils",
-  "version": "8.19.0",
+  "version": "8.21.0",
   "description": "SvelteKit helper utilities — createCronRunner, streamSse, and URL-state runes",
   "license": "MIT",
   "repository": {
@@ -38,9 +38,15 @@
       "import": "./dist/url.svelte.js",
       "default": "./dist/url.svelte.js"
     },
+    "./search-params": {
+      "types": "./dist/search-params.d.ts",
+      "import": "./dist/search-params.js",
+      "default": "./dist/search-params.js"
+    },
     "./cron": {
       "types": "./dist/cron.d.ts",
-      "import": "./dist/cron.js"
+      "import": "./dist/cron.js",
+      "default": "./dist/cron.js"
     },
     "./sse": {
       "types": "./dist/sse.d.ts",