@urbicon-ui/sveltekit-utils 8.26.0 → 8.27.0

package/README.md

@@ -15,9 +15,7 @@ Currently shipping:
 bun add @urbicon-ui/sveltekit-utils
 ```
 
-Peer dependencies: `svelte` (^5.57.0), `@sveltejs/kit`.
-
-The declared `@sveltejs/kit` range is 2.x. The package runs under SvelteKit 3 `next` as well; the incorrect-peer warning `bun add` prints there is expected and stays until Kit 3 has a release candidate, when the range widens.
+Peer dependencies: `svelte` (^5.57.1), `@sveltejs/kit` (^3.0.0).
 
 ## URL State (`url.svelte`)
 
@@ -104,7 +102,7 @@ Link or binding: an `href` from `withSearchParams` where the reader picks a dest
 
 **Design notes**
 
-- URL updates use `goto()` with `replaceState: true`, `noScroll: true`, `keepFocus: true` — suited for filter/pagination UIs, not full page transitions.
+- URL updates use `goto()` with `replace: true` and `reset: false` (scroll position and focus stay put) — 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`.
@@ -152,8 +150,8 @@ export const userView = { pageSize: 25, sort: { column: 'joined', direction: 'de
 ```typescript
 // src/routes/users/+page.server.ts
 import { searchParamsToViewSnapshot } from '@urbicon-ui/sveltekit-utils/table-view';
-import { fetchUsers } from '$lib/server/users';
-import { userView } from '$lib/view-defaults';
+import { fetchUsers } from '#lib/server/users.js';
+import { userView } from '#lib/view-defaults.js';
 import type { PageServerLoad } from './$types';
 
 export const load: PageServerLoad = async ({ url }) => ({
@@ -177,22 +175,39 @@ Fire HTTP requests against SvelteKit server endpoints on an interval. Pair with
 
 **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.
 
+The secret and the base URL are environment variables, declared once in `src/env.ts`:
+
+<!-- typecheck -->
+
+```typescript
+// src/env.ts
+import { defineEnvVars } from '@sveltejs/kit/env';
+
+export const variables = defineEnvVars({
+  // Dynamic (Kit's default): a node server reads it at start, not at build.
+  // Rejecting the empty string makes a missing secret a startup failure — not
+  // an unauthenticated cron loop.
+  CRON_SECRET: {
+    schema: (value) => {
+      if (!value) throw new Error('CRON_SECRET is not set');
+      return value;
+    }
+  },
+  // A schema that may return `undefined` makes the variable optional.
+  BASE_URL: { schema: (value) => value }
+});
+```
+
 <!-- typecheck -->
 
 ```typescript
 // src/lib/server/cron.ts
 import { createCronRunner } from '@urbicon-ui/sveltekit-utils/cron';
-import { env } from '$env/dynamic/private';
-
-// Runtime env, not `$env/static/private`: a node server reads its secret at
-// start, not at build. The runner needs a `string`, so a missing one is a
-// startup failure here — not an unauthenticated cron loop.
-const secret = env.CRON_SECRET;
-if (!secret) throw new Error('CRON_SECRET is not set');
+import { BASE_URL, CRON_SECRET } from '$app/env/private';
 
 export const cron = createCronRunner({
-  secret,
-  baseUrl: env.BASE_URL,
+  secret: CRON_SECRET,
+  baseUrl: BASE_URL,
   jobs: [
     { path: '/api/cron/send-digest', intervalSeconds: 3600 },
     { path: '/api/cron/cleanup', intervalSeconds: 900, method: 'POST' }
@@ -214,12 +229,12 @@ Receive the call and verify the secret inside your endpoint:
 
 ```typescript
 // src/routes/api/cron/send-digest/+server.ts
-import { env } from '$env/dynamic/private';
-import { sendDigest } from '$lib/server/digest';
+import { CRON_SECRET } from '$app/env/private';
+import { sendDigest } from '#lib/server/digest.js';
 import type { RequestHandler } from './$types';
 
 export const POST: RequestHandler = async ({ request }) => {
-  if (!env.CRON_SECRET || request.headers.get('x-cron-secret') !== env.CRON_SECRET) {
+  if (request.headers.get('x-cron-secret') !== CRON_SECRET) {
     return new Response('Forbidden', { status: 403 });
   }
   await sendDigest();
@@ -251,8 +266,8 @@ That holds together when the endpoint is idempotent, which means
 
 ```typescript
 // src/routes/api/cron/daily/+server.ts
-import { env } from '$env/dynamic/private';
-import { upsertDailyRollup } from '$lib/server/rollup';
+import { CRON_SECRET } from '$app/env/private';
+import { upsertDailyRollup } from '#lib/server/rollup.js';
 import type { RequestHandler } from './$types';
 
 // Which midnight: the zone your people live in. `en-CA` formats as YYYY-MM-DD.
@@ -260,7 +275,7 @@ 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) {
+  if (request.headers.get('x-cron-secret') !== CRON_SECRET) {
     return new Response('Forbidden', { status: 403 });
   }
   // Keyed on the day and written atomically, so the second call of the day —
@@ -276,6 +291,7 @@ export const POST: RequestHandler = async ({ request }) => {
 
 - 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.
 - Header name defaults to `x-cron-secret`; override via `secretHeader`.
+- A `POST` job sends `{}` as `application/json`. The request carries no `Origin` header, and SvelteKit's CSRF check refuses an Origin-less `POST` with a form content type or none at all — a JSON body is what lets it reach your endpoint in a built app.
 
 ## SSE Stream Reader (`sse`)
 
@@ -310,7 +326,7 @@ Emit the matching frames from the endpoint:
 
 ```typescript
 // src/routes/api/chat/+server.ts
-import { runModel } from '$lib/server/model';
+import { runModel } from '#lib/server/model.js';
 import type { RequestHandler } from './$types';
 
 export const POST: RequestHandler = async ({ request }) => {

package/dist/cron.d.ts

@@ -8,7 +8,8 @@ export interface CronJob {
      */
     intervalSeconds: number;
     /**
-     * HTTP method for the request.
+     * HTTP method for the request. A `POST` carries an empty JSON object (`{}`)
+     * as its body.
      * @default 'POST'
      */
     method?: 'GET' | 'POST';
@@ -88,17 +89,14 @@ export interface CronRunner {
  * @throws TypeError if `onError` is not a function.
  * @example
  * ```typescript
- * // src/lib/server/cron.ts
+ * // src/lib/server/cron.ts — both variables declared in src/env.ts, the
+ * // secret with a schema that rejects the empty string (see the README)
  * import { createCronRunner } from '@urbicon-ui/sveltekit-utils/cron';
- * import { env } from '$env/dynamic/private';
- *
- * // runtime env: `secret` is a `string`, so a missing one fails at startup
- * const secret = env.CRON_SECRET;
- * if (!secret) throw new Error('CRON_SECRET is not set');
+ * import { BASE_URL, CRON_SECRET } from '$app/env/private';
  *
  * export const cron = createCronRunner({
- *   secret,
- *   baseUrl: env.BASE_URL,
+ *   secret: CRON_SECRET,
+ *   baseUrl: BASE_URL,
  *   jobs: [
  *     { path: '/api/cron/send-digest', intervalSeconds: 3600 },
  *     { path: '/api/cron/cleanup', intervalSeconds: 900 }

package/dist/cron.js

@@ -39,6 +39,21 @@ function warnDoubleStart(path, armed) {
 function warnDuplicateJob(path) {
     console.warn(`[createCronRunner] start() armed "${path}" twice from one jobs list; the endpoint gets every tick twice. Remove the duplicate entry.`);
 }
+/**
+ * The request a job fires. A server-side `fetch` sends no `Origin`, and
+ * SvelteKit's CSRF check refuses an Origin-less `POST` whose `Content-Type` is
+ * a form type or absent — in a built app, before any hook runs. A JSON body
+ * passes it.
+ */
+function cronRequestInit(job, config) {
+    const method = job.method ?? 'POST';
+    const headers = {
+        [config.secretHeader ?? 'x-cron-secret']: config.secret
+    };
+    if (method === 'GET')
+        return { method, headers };
+    return { method, headers: { ...headers, 'content-type': 'application/json' }, body: '{}' };
+}
 /**
  * Create a background runner that fires HTTP requests at SvelteKit server
  * endpoints on a fixed interval — a minimal in-process cron for scheduled work
@@ -59,17 +74,14 @@ function warnDuplicateJob(path) {
  * @throws TypeError if `onError` is not a function.
  * @example
  * ```typescript
- * // src/lib/server/cron.ts
+ * // src/lib/server/cron.ts — both variables declared in src/env.ts, the
+ * // secret with a schema that rejects the empty string (see the README)
  * import { createCronRunner } from '@urbicon-ui/sveltekit-utils/cron';
- * import { env } from '$env/dynamic/private';
- *
- * // runtime env: `secret` is a `string`, so a missing one fails at startup
- * const secret = env.CRON_SECRET;
- * if (!secret) throw new Error('CRON_SECRET is not set');
+ * import { BASE_URL, CRON_SECRET } from '$app/env/private';
  *
  * export const cron = createCronRunner({
- *   secret,
- *   baseUrl: env.BASE_URL,
+ *   secret: CRON_SECRET,
+ *   baseUrl: BASE_URL,
  *   jobs: [
  *     { path: '/api/cron/send-digest', intervalSeconds: 3600 },
  *     { path: '/api/cron/cleanup', intervalSeconds: 900 }
@@ -132,10 +144,7 @@ export function createCronRunner(config) {
                     const base = config.baseUrl ?? 'http://localhost:3000';
                     let response;
                     try {
-                        response = await fetch(`${base}${job.path}`, {
-                            method: job.method ?? 'POST',
-                            headers: { [config.secretHeader ?? 'x-cron-secret']: config.secret }
-                        });
+                        response = await fetch(`${base}${job.path}`, cronRequestInit(job, config));
                     }
                     catch (err) {
                         // Network-level failure (DNS, connection refused, abort): fetch rejected.

package/dist/search-params.d.ts

@@ -1,3 +1,13 @@
+/**
+ * The read half of `URLSearchParams`. SvelteKit types `page.url.searchParams`
+ * without the mutators, so a reader that asked for `URLSearchParams` would
+ * refuse it; a real `URLSearchParams` is one of these too.
+ */
+export type ReadableSearchParams = Omit<URLSearchParams, 'append' | 'delete' | 'set' | 'sort'>;
+/** What {@link withSearchParams} reads off a URL: a `URL`, or SvelteKit's read-only `page.url`. */
+export type ReadableUrl = Pick<URL, 'origin' | 'pathname'> & {
+    readonly searchParams: ReadableSearchParams;
+};
 /**
  * What {@link withSearchParams} applies to a URL: a plain record, or a
  * `URLSearchParams` whose repeated keys survive the merge.
@@ -38,4 +48,4 @@ export type SearchParamsPatch = URLSearchParams | Record<string, string | string
  * // '/films?sort=year'
  * ```
  */
-export declare function withSearchParams(url: URL, patch: SearchParamsPatch): string;
+export declare function withSearchParams(url: ReadableUrl, patch: SearchParamsPatch): string;

package/dist/search-params.js

@@ -34,7 +34,7 @@
  * ```
  */
 export function withSearchParams(url, patch) {
-    const next = new URLSearchParams(url.searchParams);
+    const next = new URLSearchParams(url.searchParams.toString());
     if (patch instanceof URLSearchParams) {
         for (const [key] of patch)
             next.delete(key);

package/dist/table-view.d.ts

@@ -14,6 +14,7 @@
  * to `sort=`, so a cleared filter set elides like every other axis (the
  * shipped read side already tolerated it).
  */
+import type { ReadableSearchParams } from './search-params.js';
 /**
  * Filter operators supported by the table. Mirrors `FilterOperator` from
  * `@urbicon-ui/table`. Used as the runtime whitelist when parsing `filter`
@@ -84,7 +85,7 @@ export interface TableViewLike {
 /** The URL keys a set of axes owns, with the configured prefix applied. */
 export declare function viewAxisKeys(axes: readonly TableViewAxis[], prefix?: string): string[];
 /** The axes a URL names — presence only for params it actually carries. */
-export declare function viewAxesNamedBy(sp: URLSearchParams, prefix?: string): TableViewAxis[];
+export declare function viewAxesNamedBy(sp: ReadableSearchParams, prefix?: string): TableViewAxis[];
 /**
  * Parse search params into a **partial** view snapshot — a key per axis the
  * URL actually carries, and nothing else. Read tolerant per key: an
@@ -92,7 +93,7 @@ export declare function viewAxesNamedBy(sp: URLSearchParams, prefix?: string): T
  * for that axis (the key was present, so the axis stays claimed), and
  * malformed filter entries are skipped individually.
  */
-export declare function searchParamsToViewPartial(sp: URLSearchParams, defaults: Pick<TableViewSnapshot, 'page' | 'pageSize'>, prefix?: string): Partial<TableViewSnapshot>;
+export declare function searchParamsToViewPartial(sp: ReadableSearchParams, defaults: Pick<TableViewSnapshot, 'page' | 'pageSize'>, prefix?: string): Partial<TableViewSnapshot>;
 /**
  * Resolve a full view snapshot from search params: every axis the URL names
  * comes from the URL, every other one from `defaults` — the same resolution
@@ -122,7 +123,7 @@ export declare function searchParamsToViewPartial(sp: URLSearchParams, defaults:
  * });
  * ```
  */
-export declare function searchParamsToViewSnapshot(sp: URLSearchParams, defaults?: Partial<TableViewSnapshot>, prefix?: string): TableViewSnapshot;
+export declare function searchParamsToViewSnapshot(sp: ReadableSearchParams, defaults?: Partial<TableViewSnapshot>, prefix?: string): TableViewSnapshot;
 /**
  * Serialize a snapshot, eliding every axis that equals the defaults — the
  * elision baseline *is* the view's defaults, structurally. `axes` restricts
@@ -160,4 +161,4 @@ export declare function assertValidViewSnapshot(snapshot: TableViewSnapshot): vo
  * @returns New `URLSearchParams` with the view applied.
  * @throws TypeError when the snapshot is structurally invalid (write strict).
  */
-export declare function applyViewToSearchParams(existing: URLSearchParams, snapshot: TableViewSnapshot, defaults: TableViewSnapshot, axes?: readonly TableViewAxis[], prefix?: string): URLSearchParams;
+export declare function applyViewToSearchParams(existing: ReadableSearchParams, snapshot: TableViewSnapshot, defaults: TableViewSnapshot, axes?: readonly TableViewAxis[], prefix?: string): URLSearchParams;

package/dist/table-view.js

@@ -301,7 +301,7 @@ export function assertValidViewSnapshot(snapshot) {
 export function applyViewToSearchParams(existing, snapshot, defaults, axes = TABLE_VIEW_AXES, prefix = '') {
     assertValidViewSnapshot(snapshot);
     const serialized = viewSnapshotToSearchParams(snapshot, defaults, axes, prefix);
-    const next = new URLSearchParams(existing);
+    const next = new URLSearchParams(existing.toString());
     for (const key of viewAxisKeys(axes, prefix)) {
         next.delete(key);
     }

package/dist/url.svelte.d.ts

@@ -1,4 +1,4 @@
-import { type SearchParamsPatch } from './search-params.js';
+import { type ReadableSearchParams, type SearchParamsPatch } from './search-params.js';
 export { type SearchParamsPatch, withSearchParams } from './search-params.js';
 export { bindViewToUrl, type UrlViewBindingOptions } from './view-binding.svelte.js';
 /**
@@ -13,7 +13,7 @@ export type UrlParamOptions<T> = {
      * Read the value out of the current search params. Return `null`/`undefined`
      * to signal "absent" — the getter then yields {@link initial}.
      */
-    parse: (sp: URLSearchParams) => T | null | undefined;
+    parse: (sp: ReadableSearchParams) => T | null | undefined;
     /**
      * Encode the value into `URLSearchParams`. The keys it produces are the ones
      * the setter manages: on write they are cleared from the current URL and
@@ -58,7 +58,7 @@ export declare function updateUrlSearchParams(next: SearchParamsPatch, opts?: {
  *
  * `set` rewrites only the keys that `options.serialize` produces (clear +
  * re-append) and preserves the rest, then navigates with `goto` to the address
- * {@link withSearchParams} builds (`replaceState`, `noScroll`, `keepFocus`).
+ * {@link withSearchParams} builds (`replace` per `replaceState`, `reset: false`).
  *
  * @param _key - Ignored — `options.parse`/`options.serialize` already close
  *   over the key (see {@link useUrlArrayParam}); kept only for signature parity
@@ -68,7 +68,7 @@ export declare function updateUrlSearchParams(next: SearchParamsPatch, opts?: {
  *   (falling back to `initial`), `set(value)` writes it to the URL.
  */
 export declare function createUrlParam<T>(_key: string, options: UrlParamOptions<T>): {
-    readonly get: (sp: URLSearchParams) => T;
+    readonly get: (sp: ReadableSearchParams) => T;
     readonly set: (next: T) => void;
 };
 /**

package/dist/url.svelte.js

@@ -1,4 +1,4 @@
-import { building } from '$app/environment';
+import { building } from '$app/env';
 import { goto } from '$app/navigation';
 import { page } from '$app/state';
 import { withSearchParams } from './search-params.js';
@@ -43,9 +43,8 @@ export { bindViewToUrl } from './view-binding.svelte.js';
 // free to call it at their composition point.
 export function updateUrlSearchParams(next, opts) {
     goto(withSearchParams(page.url, next), {
-        replaceState: opts?.replaceState ?? true,
-        noScroll: true,
-        keepFocus: true
+        replace: opts?.replaceState ?? true,
+        reset: false
     });
 }
 /**
@@ -57,7 +56,7 @@ export function updateUrlSearchParams(next, opts) {
  *
  * `set` rewrites only the keys that `options.serialize` produces (clear +
  * re-append) and preserves the rest, then navigates with `goto` to the address
- * {@link withSearchParams} builds (`replaceState`, `noScroll`, `keepFocus`).
+ * {@link withSearchParams} builds (`replace` per `replaceState`, `reset: false`).
  *
  * @param _key - Ignored — `options.parse`/`options.serialize` already close
  *   over the key (see {@link useUrlArrayParam}); kept only for signature parity
@@ -72,9 +71,8 @@ export function createUrlParam(_key, options) {
     const get = (sp) => options.parse(sp) ?? options.initial;
     function setValue(next) {
         goto(withSearchParams(page.url, options.serialize(next)), {
-            replaceState: options.replaceState ?? true,
-            noScroll: true,
-            keepFocus: true
+            replace: options.replaceState ?? true,
+            reset: false
         });
     }
     return { get, set: setValue };

package/dist/view-binding.svelte.js

@@ -27,7 +27,7 @@
  * window of the spike review.
  */
 import { untrack } from 'svelte';
-import { browser, building } from '$app/environment';
+import { browser, building } from '$app/env';
 import { goto } from '$app/navigation';
 import { page } from '$app/state';
 import { searchParamsToViewPartial, TABLE_VIEW_AXES, viewAxesNamedBy, viewAxisKeys, viewSnapshotToSearchParams } from './table-view.js';
@@ -131,9 +131,8 @@ const writer = {
         this.sentPending.add(search);
         this.intendedSearch = search;
         void goto(`${page.url.pathname}${search}${page.url.hash}`, {
-            replaceState,
-            noScroll: true,
-            keepFocus: true
+            replace: replaceState,
+            reset: false
         });
     },
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urbicon-ui/sveltekit-utils",
-  "version": "8.26.0",
+  "version": "8.27.0",
   "description": "SvelteKit helper utilities — createCronRunner, streamSse, and URL-state runes",
   "license": "MIT",
   "repository": {
@@ -19,6 +19,10 @@
     "sse"
   ],
   "type": "module",
+  "imports": {
+    "#lib": "./src/lib/index.js",
+    "#lib/*": "./src/lib/*"
+  },
   "private": false,
   "sideEffects": false,
   "svelte": "./dist/index.js",
@@ -78,20 +82,20 @@
     "test": "vitest run"
   },
   "peerDependencies": {
-    "svelte": "^5.57.0",
-    "@sveltejs/kit": "^2.70.3"
+    "svelte": "^5.57.1",
+    "@sveltejs/kit": "^3.0.0"
   },
   "devDependencies": {
-    "@sveltejs/kit": "^2.70.3",
-    "@sveltejs/package": "^2.5.8",
-    "@sveltejs/vite-plugin-svelte": "^7.3.0",
+    "@sveltejs/kit": "^3.0.0",
+    "@sveltejs/package": "^3.0.0",
+    "@sveltejs/vite-plugin-svelte": "^7.3.1",
     "prettier": "^3.9.6",
     "prettier-plugin-svelte": "^4.1.1",
     "prettier-plugin-tailwindcss": "^0.8.1",
-    "svelte": "^5.57.0",
+    "svelte": "^5.57.1",
     "svelte-check": "^4.7.6",
     "typescript": "^6.0.3",
     "vite": "^8.2.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.3"
   }
 }