@urbicon-ui/sveltekit-utils 6.1.4

package/README.md

@@ -0,0 +1,117 @@
+# @urbicon-ui/sveltekit-utils
+
+Small, focused SvelteKit helpers that Urbicon apps share. Zero runtime dependencies.
+
+Currently shipping:
+
+- **URL-state runes** — reactive `useUrlParam` / `useUrlArrayParam` that keep component state in sync with `?query=` parameters
+- **Cron runner** — interval-based background fetcher for scheduled server endpoints
+
+## Installation
+
+This package ships inside the Urbicon UI monorepo. Install from repo root:
+
+```bash
+bun install
+```
+
+Peer dependencies: `svelte` (^5), `@sveltejs/kit`.
+
+## URL State (`url.svelte`)
+
+Bind a typed, reactive value to a URL search param. When the value changes, the URL is updated (and vice versa) without a full navigation.
+
+```svelte
+<script lang="ts">
+  import { useUrlParam, useUrlArrayParam } from '@urbicon-ui/sveltekit-utils/url.svelte';
+
+  // Single string param, typed
+  const [page, setPage] = useUrlParam<number>('page', {
+    parse: (sp) => Number(sp.get('page') ?? '1'),
+    serialize: (v) => new URLSearchParams({ page: String(v) }),
+    initial: 1
+  });
+
+  // Repeated-key array param: ?tag=a&tag=b
+  const [tags, setTags] = useUrlArrayParam('tag', { initial: [], strategy: 'repeat' });
+
+  // CSV array param: ?tag=a,b
+  const [categories, setCategories] = useUrlArrayParam('cat', { initial: [], strategy: 'csv' });
+</script>
+
+<button onclick={() => setPage(page() + 1)}>Next — current: {page()}</button>
+```
+
+Low-level escape hatch if you prefer to update multiple params at once:
+
+```typescript
+import { updateUrlSearchParams } from '@urbicon-ui/sveltekit-utils/url.svelte';
+
+updateUrlSearchParams({ page: '1', tag: ['a', 'b'] }, { replaceState: true });
+```
+
+**Design notes**
+
+- URL updates use `goto()` with `replaceState: true`, `noScroll: true`, `keepFocus: true` — suited for filter/pagination UIs, not full page transitions.
+- `useUrlParam` returns getters (not Svelte stores) so consumers can read the value lazily inside `$derived`/`$effect`.
+
+## Cron Runner (`cron`)
+
+Fire HTTP requests against SvelteKit server endpoints on an interval. Pair with a shared-secret header so endpoints can authenticate scheduled calls.
+
+```typescript
+// src/lib/server/cron.ts
+import { createCronRunner } from '@urbicon-ui/sveltekit-utils/cron';
+import { env } from '$env/dynamic/private';
+
+export const cron = createCronRunner({
+  secret: env.CRON_SECRET,
+  baseUrl: env.BASE_URL,
+  jobs: [
+    { path: '/api/cron/send-digest', intervalSeconds: 3600 },
+    { path: '/api/cron/cleanup', intervalSeconds: 900, method: 'POST' }
+  ],
+  onError: (job, err) => console.error(`Cron ${job.path} failed`, err)
+});
+
+cron.start();
+```
+
+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';
+
+export const POST = async ({ request }) => {
+  if (request.headers.get('x-cron-secret') !== env.CRON_SECRET) {
+    return new Response('Forbidden', { status: 403 });
+  }
+  await sendDigest();
+  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.
+- Header name defaults to `x-cron-secret`; override via `secretHeader`.
+
+## Exports
+
+| Subpath        | Contents                                                                            |
+| -------------- | ----------------------------------------------------------------------------------- |
+| `.`            | Barrel of both modules                                                              |
+| `./url.svelte` | `useUrlParam`, `useUrlArrayParam`, `createUrlParam`, `updateUrlSearchParams`, types |
+| `./cron`       | `createCronRunner`, `CronJob`, `CronRunnerConfig`, `CronRunner`                     |
+
+## Development
+
+```bash
+bun --filter='@urbicon-ui/sveltekit-utils' run build    # svelte-package
+bun --filter='@urbicon-ui/sveltekit-utils' run check    # svelte-check
+```
+
+## Scope & Roadmap
+
+Candidate additions under consideration: form-helper runes, layout-runes, shared load-helpers.

package/dist/cron.d.ts

@@ -0,0 +1,18 @@
+export interface CronJob {
+    path: string;
+    intervalSeconds: number;
+    method?: 'GET' | 'POST';
+}
+export interface CronRunnerConfig {
+    secret: string;
+    secretHeader?: string;
+    baseUrl?: string;
+    jobs: CronJob[];
+    onError?: (job: CronJob, error: Error) => void;
+}
+export interface CronRunner {
+    start(): void;
+    stop(): void;
+    isRunning(): boolean;
+}
+export declare function createCronRunner(config: CronRunnerConfig): CronRunner;

package/dist/cron.js

@@ -0,0 +1,34 @@
+export function createCronRunner(config) {
+    const timers = [];
+    let running = false;
+    return {
+        start() {
+            if (running)
+                return;
+            running = true;
+            for (const job of config.jobs) {
+                const timer = setInterval(async () => {
+                    try {
+                        const base = config.baseUrl ?? 'http://localhost:3000';
+                        await fetch(`${base}${job.path}`, {
+                            method: job.method ?? 'POST',
+                            headers: { [config.secretHeader ?? 'x-cron-secret']: config.secret }
+                        });
+                    }
+                    catch (err) {
+                        config.onError?.(job, err);
+                    }
+                }, job.intervalSeconds * 1000);
+                timers.push(timer);
+            }
+        },
+        stop() {
+            running = false;
+            timers.forEach(clearInterval);
+            timers.length = 0;
+        },
+        isRunning() {
+            return running;
+        }
+    };
+}

package/dist/cron.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cron.test.js

@@ -0,0 +1,137 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createCronRunner } from './cron';
+describe('createCronRunner', () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(null, { status: 200 })));
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+        vi.restoreAllMocks();
+    });
+    it('should not be running initially', () => {
+        const runner = createCronRunner({
+            secret: 'test-secret',
+            jobs: [{ path: '/api/test', intervalSeconds: 60 }]
+        });
+        expect(runner.isRunning()).toBe(false);
+    });
+    it('should be running after start()', () => {
+        const runner = createCronRunner({
+            secret: 'test-secret',
+            jobs: [{ path: '/api/test', intervalSeconds: 60 }]
+        });
+        runner.start();
+        expect(runner.isRunning()).toBe(true);
+        runner.stop();
+    });
+    it('should not be running after stop()', () => {
+        const runner = createCronRunner({
+            secret: 'test-secret',
+            jobs: [{ path: '/api/test', intervalSeconds: 60 }]
+        });
+        runner.start();
+        runner.stop();
+        expect(runner.isRunning()).toBe(false);
+    });
+    it('should not start twice', () => {
+        const runner = createCronRunner({
+            secret: 'test-secret',
+            jobs: [{ path: '/api/test', intervalSeconds: 10 }]
+        });
+        runner.start();
+        runner.start();
+        vi.advanceTimersByTime(10_000);
+        expect(fetch).toHaveBeenCalledTimes(1);
+        runner.stop();
+    });
+    it('should call fetch for each job at the correct interval', async () => {
+        const runner = createCronRunner({
+            secret: 'my-secret',
+            baseUrl: 'http://localhost:5000',
+            jobs: [
+                { path: '/api/job-a', intervalSeconds: 10 },
+                { path: '/api/job-b', intervalSeconds: 20, method: 'GET' }
+            ]
+        });
+        runner.start();
+        // At 10s: job-a fires
+        await vi.advanceTimersByTimeAsync(10_000);
+        expect(fetch).toHaveBeenCalledTimes(1);
+        expect(fetch).toHaveBeenCalledWith('http://localhost:5000/api/job-a', {
+            method: 'POST',
+            headers: { 'x-cron-secret': 'my-secret' }
+        });
+        // At 20s: job-a fires again + job-b fires for the first time
+        await vi.advanceTimersByTimeAsync(10_000);
+        expect(fetch).toHaveBeenCalledTimes(3);
+        expect(fetch).toHaveBeenCalledWith('http://localhost:5000/api/job-b', {
+            method: 'GET',
+            headers: { 'x-cron-secret': 'my-secret' }
+        });
+        runner.stop();
+    });
+    it('should use default baseUrl when not provided', async () => {
+        const runner = createCronRunner({
+            secret: 's',
+            jobs: [{ path: '/api/ping', intervalSeconds: 5 }]
+        });
+        runner.start();
+        await vi.advanceTimersByTimeAsync(5_000);
+        expect(fetch).toHaveBeenCalledWith('http://localhost:3000/api/ping', expect.any(Object));
+        runner.stop();
+    });
+    it('should use custom secretHeader', async () => {
+        const runner = createCronRunner({
+            secret: 'abc',
+            secretHeader: 'x-internal-key',
+            jobs: [{ path: '/api/test', intervalSeconds: 5 }]
+        });
+        runner.start();
+        await vi.advanceTimersByTimeAsync(5_000);
+        expect(fetch).toHaveBeenCalledWith(expect.any(String), {
+            method: 'POST',
+            headers: { 'x-internal-key': 'abc' }
+        });
+        runner.stop();
+    });
+    it('should call onError when fetch throws', async () => {
+        const error = new Error('Network error');
+        vi.mocked(fetch).mockRejectedValueOnce(error);
+        const onError = vi.fn();
+        const job = { path: '/api/fail', intervalSeconds: 5 };
+        const runner = createCronRunner({
+            secret: 's',
+            jobs: [job],
+            onError
+        });
+        runner.start();
+        await vi.advanceTimersByTimeAsync(5_000);
+        expect(onError).toHaveBeenCalledWith(job, error);
+        runner.stop();
+    });
+    it('should not call onError when fetch succeeds', async () => {
+        const onError = vi.fn();
+        const runner = createCronRunner({
+            secret: 's',
+            jobs: [{ path: '/api/ok', intervalSeconds: 5 }],
+            onError
+        });
+        runner.start();
+        await vi.advanceTimersByTimeAsync(5_000);
+        expect(onError).not.toHaveBeenCalled();
+        runner.stop();
+    });
+    it('should stop all timers and not fire after stop()', async () => {
+        const runner = createCronRunner({
+            secret: 's',
+            jobs: [{ path: '/api/test', intervalSeconds: 5 }]
+        });
+        runner.start();
+        await vi.advanceTimersByTimeAsync(5_000);
+        expect(fetch).toHaveBeenCalledTimes(1);
+        runner.stop();
+        await vi.advanceTimersByTimeAsync(15_000);
+        expect(fetch).toHaveBeenCalledTimes(1);
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './cron';
+export * from './url.svelte';

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './cron';
+export * from './url.svelte';

package/dist/url.svelte.d.ts

@@ -0,0 +1,21 @@
+export type UrlArrayStrategy = 'repeat' | 'csv';
+export type UrlParamOptions<T> = {
+    parse: (sp: URLSearchParams) => T | null | undefined;
+    serialize: (value: T) => URLSearchParams;
+    initial: T;
+    replaceState?: boolean;
+};
+export declare function updateUrlSearchParams(next: URLSearchParams | Record<string, string | string[]>, opts?: {
+    replaceState?: boolean;
+    keepPath?: boolean;
+}): void;
+export declare function createUrlParam<T>(_key: string, options: UrlParamOptions<T>): {
+    readonly get: (sp: URLSearchParams) => T;
+    readonly set: (next: T) => void;
+};
+export declare function useUrlParam<T>(key: string, options: UrlParamOptions<T>): readonly [() => T, (next: T) => void];
+export declare function useUrlArrayParam(key: string, opts: {
+    initial: string[];
+    strategy?: UrlArrayStrategy;
+    delimiter?: string;
+}): readonly [() => string[], (next: string[]) => void];

package/dist/url.svelte.js

@@ -0,0 +1,84 @@
+import { goto } from '$app/navigation';
+import { page } from '$app/state';
+// 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.
+/* eslint-disable svelte/prefer-svelte-reactivity, svelte/no-navigation-without-resolve */
+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 = opts?.keepPath ? page.url.pathname : '/';
+    goto(q ? `${path}?${q}` : path, {
+        replaceState: opts?.replaceState ?? true,
+        noScroll: true,
+        keepFocus: true
+    });
+}
+// `key` is unused here — `options.parse`/`options.serialize` already close over
+// it (see useUrlArrayParam) — but kept for signature parity with useUrlParam.
+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}` : '/', {
+            replaceState: options.replaceState ?? true,
+            noScroll: true,
+            keepFocus: true
+        });
+    }
+    return { get, set: setValue };
+}
+export function useUrlParam(key, options) {
+    const { get, set } = createUrlParam(key, options);
+    const getBound = () => get(page.url.searchParams);
+    return [getBound, set];
+}
+export function useUrlArrayParam(key, opts) {
+    const strategy = opts.strategy ?? 'repeat';
+    const delimiter = opts.delimiter ?? ',';
+    const parse = (sp) => {
+        if (strategy === 'repeat')
+            return sp.getAll(key);
+        const raw = sp.get(key);
+        return raw ? raw.split(delimiter).filter(Boolean) : [];
+    };
+    const serialize = (values) => {
+        const sp = new URLSearchParams();
+        if (strategy === 'repeat') {
+            for (const v of values)
+                sp.append(key, v);
+        }
+        else {
+            if (values.length)
+                sp.set(key, values.join(delimiter));
+        }
+        return sp;
+    };
+    return useUrlParam(key, { parse, serialize, initial: opts.initial });
+}
+/* eslint-enable svelte/prefer-svelte-reactivity, svelte/no-navigation-without-resolve */

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@urbicon-ui/sveltekit-utils",
+  "version": "6.1.4",
+  "description": "SvelteKit helper utilities — createCronRunner and URL-state runes",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://codeberg.org/urbicon/ui.git",
+    "directory": "packages/sveltekit-utils"
+  },
+  "homepage": "https://ui.urbicon.de",
+  "bugs": "https://codeberg.org/urbicon/ui/issues",
+  "keywords": [
+    "svelte",
+    "sveltekit",
+    "utilities",
+    "cron",
+    "url-state"
+  ],
+  "type": "module",
+  "private": false,
+  "sideEffects": false,
+  "svelte": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "svelte": "./dist/index.js",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./url.svelte": {
+      "types": "./dist/url.svelte.d.ts",
+      "svelte": "./dist/url.svelte.js",
+      "import": "./dist/url.svelte.js",
+      "default": "./dist/url.svelte.js"
+    },
+    "./cron": {
+      "types": "./dist/cron.d.ts",
+      "import": "./dist/cron.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "svelte-package --watch",
+    "build": "svelte-kit sync && svelte-package",
+    "clean": "rm -rf dist .svelte-kit",
+    "clean-all": "bun --bun run clean && rm -rf node_modules",
+    "package": "svelte-kit sync && svelte-package",
+    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+    "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
+    "format": "biome format --write . && prettier --write \"**/*.svelte\"",
+    "lint": "biome check . && svelte-check --tsconfig ./tsconfig.json",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "svelte": "^5.56.3",
+    "@sveltejs/kit": "^2.65.2"
+  },
+  "devDependencies": {
+    "@sveltejs/kit": "^2.65.2",
+    "@sveltejs/package": "^2.5.8",
+    "@sveltejs/vite-plugin-svelte": "^7.0.0",
+    "prettier": "^3.8.4",
+    "prettier-plugin-svelte": "^4.1.1",
+    "prettier-plugin-tailwindcss": "^0.8.0",
+    "svelte": "^5.56.3",
+    "svelte-check": "^4.6.0",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.16",
+    "vitest": "^4.1.9"
+  }
+}