@urbicon-ui/sveltekit-utils 8.20.0 → 8.22.0

package/README.md

@@ -15,7 +15,7 @@ Currently shipping:
 bun add @urbicon-ui/sveltekit-utils
 ```
 
-Peer dependencies: `svelte` (^5), `@sveltejs/kit`.
+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.
 
@@ -47,6 +47,7 @@ Bind a typed, reactive value to a URL search param. When the value changes, the
 Low-level escape hatch if you prefer to update multiple params at once:
 
 <!-- typecheck -->
+
 ```typescript
 import { updateUrlSearchParams } from '@urbicon-ui/sveltekit-utils/url.svelte';
 
@@ -56,6 +57,7 @@ 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';
 
@@ -69,6 +71,7 @@ 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';
@@ -136,7 +139,7 @@ The second argument is optional; every option has a default:
 
 Because the binding re-reads the URL rather than capturing it, the browser's back button works: navigating back to a URL that no longer names `?sort` returns the table to its default sort.
 
-The pure serializers work without SvelteKit — e.g. to parse the incoming query in a server `load` and fetch the first page during SSR. Use `searchParamsToViewSnapshot` from `./table-view`: it takes the *same* defaults object the component hands `createTableView`, so the server cannot resolve an absent param differently from the client, and it hands back the very shape a managed `source.query` receives.
+The pure serializers work without SvelteKit — e.g. to parse the incoming query in a server `load` and fetch the first page during SSR. Use `searchParamsToViewSnapshot` from `./table-view`: it takes the _same_ defaults object the component hands `createTableView`, so the server cannot resolve an absent param differently from the client, and it hands back the very shape a managed `source.query` receives.
 
 ```typescript
 // src/lib/view-defaults.ts — imported by the component and by the load function.
@@ -145,6 +148,7 @@ export const userView = { pageSize: 25, sort: { column: 'joined', direction: 'de
 ```
 
 <!-- typecheck -->
+
 ```typescript
 // src/routes/users/+page.server.ts
 import { searchParamsToViewSnapshot } from '@urbicon-ui/sveltekit-utils/table-view';
@@ -161,7 +165,7 @@ The `./table-query` subpath that used to hold a second copy of this codec — sa
 
 **Design notes**
 
-- **Default elision** — an axis whose value equals its default is not written; a table in its default state leaves the URL clean. The baseline *is* `view.defaults`, read off the object the binding decorates, so there is no second copy of the defaults to keep in step with the table's own.
+- **Default elision** — an axis whose value equals its default is not written; a table in its default state leaves the URL clean. The baseline _is_ `view.defaults`, read off the object the binding decorates, so there is no second copy of the defaults to keep in step with the table's own.
 - **Read tolerant, write strict** — an unparsable value on a param the URL actually carries falls back to that axis' default, and malformed `filter` entries are skipped individually. `assertValidViewSnapshot` is the strict half: it throws on a structurally invalid view (non-positive page, unknown operator) instead of writing corrupt state, and `applyViewToSearchParams` calls it. `viewSnapshotToSearchParams` deliberately does not — it runs inside the binding on every view change, where a throw would cost the page rather than the URL.
 - **Namespacing** — `prefix: 't_'` scopes all keys (`?t_q=…`) for multiple bound tables on one page; unrelated params are always preserved. Two prefixless bindings would manage the same keys, so that throws at registration instead of producing a link that loads the wrong table.
 - **One writer per page** — every binding submits into one coalescing URL writer, so two tables land in a single navigation, each replacing only its own keys. A landing URL the writer itself sent is not applied back onto the view: an edit made while that navigation was in flight survives instead of being overwritten by the URL it raced.
@@ -171,7 +175,10 @@ 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
 import { createCronRunner } from '@urbicon-ui/sveltekit-utils/cron';
@@ -194,11 +201,17 @@ 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 -->
+
 ```typescript
 // src/routes/api/cron/send-digest/+server.ts
 import { env } from '$env/dynamic/private';
@@ -214,6 +227,51 @@ 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.
@@ -237,7 +295,8 @@ try {
     else if (ev.event === 'error') throw new Error(JSON.parse(ev.data).message);
   }
 } catch (err) {
-  if (err instanceof SseRequestError) showError(err.body); // raw response body
+  if (err instanceof SseRequestError)
+    showError(err.body); // raw response body
   else if ((err as Error).name !== 'AbortError') throw err;
 }
 
@@ -248,6 +307,7 @@ controller.abort();
 Emit the matching frames from the endpoint:
 
 <!-- typecheck -->
+
 ```typescript
 // src/routes/api/chat/+server.ts
 import { runModel } from '$lib/server/model';
@@ -276,16 +336,16 @@ export const POST: RequestHandler = async ({ request }) => {
 
 ## Exports
 
-| Subpath           | Contents                                                                                                                                         |
-| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `.`               | Barrel of all modules                                                                                                                            |
-| `./url.svelte`    | `useUrlParam`, `useUrlArrayParam`, `createUrlParam`, `updateUrlSearchParams`, `bindViewToUrl`, types (re-exports `withSearchParams`)             |
-| `./search-params` | `withSearchParams`, `SearchParamsPatch` — no `$app/*` import                                                                                     |
+| 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`                                                                                   |
+| `./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. `./search-params` and `./table-view` are SvelteKit-free (they touch no `$app/*`), which is what lets a `load` function 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.
+`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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urbicon-ui/sveltekit-utils",
-  "version": "8.20.0",
+  "version": "8.22.0",
   "description": "SvelteKit helper utilities — createCronRunner, streamSse, and URL-state runes",
   "license": "MIT",
   "repository": {
@@ -45,7 +45,8 @@
     },
     "./cron": {
       "types": "./dist/cron.d.ts",
-      "import": "./dist/cron.js"
+      "import": "./dist/cron.js",
+      "default": "./dist/cron.js"
     },
     "./sse": {
       "types": "./dist/sse.d.ts",