@urbicon-ui/sveltekit-utils 6.22.0 → 6.24.0

package/dist/cron.d.ts

@@ -1,18 +1,96 @@
+/** One scheduled job: an endpoint to hit and how often. */
 export interface CronJob {
+    /** Path (appended to {@link CronRunnerConfig.baseUrl}) to fetch on each tick. */
     path: string;
+    /**
+     * Interval between fires, in seconds. The first fire happens *after* one
+     * interval — there is no leading call at `start()`.
+     */
     intervalSeconds: number;
+    /**
+     * HTTP method for the request.
+     * @default 'POST'
+     */
     method?: 'GET' | 'POST';
 }
+/** Configuration for {@link createCronRunner}. */
 export interface CronRunnerConfig {
+    /**
+     * Shared secret sent on every request in the {@link secretHeader} header, so
+     * the target endpoint can distinguish a scheduled call from a public one.
+     * Keep it in a private env var; the endpoint compares against the same value.
+     */
     secret: string;
+    /**
+     * Header name carrying the {@link secret}.
+     * @default 'x-cron-secret'
+     */
     secretHeader?: string;
+    /**
+     * Origin the job paths are resolved against (e.g. `https://app.example.com`).
+     * @default 'http://localhost:3000'
+     */
     baseUrl?: string;
+    /** Jobs to schedule; each runs on its own independent interval. */
     jobs: CronJob[];
+    /**
+     * Called when a job fails, with the failing {@link CronJob} and an `Error`.
+     * Fires in two cases:
+     * - the job's `fetch` **rejects** (network error, DNS failure, abort) — the
+     *   `Error` is whatever `fetch` threw.
+     * - the endpoint answers with a **non-2xx** status — the runner synthesises
+     *   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.
+     */
     onError?: (job: CronJob, error: Error) => 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).
+     */
     start(): void;
+    /**
+     * Clear every timer so nothing fires again, and flip {@link isRunning} to
+     * `false`. Call this on shutdown / HMR teardown to avoid leaked intervals.
+     */
     stop(): void;
+    /** Whether the runner is currently armed (between `start()` and `stop()`). */
     isRunning(): boolean;
 }
+/**
+ * Create a background runner that fires HTTP requests at SvelteKit server
+ * endpoints on a fixed interval — a minimal in-process cron for scheduled work
+ * (digests, cleanup, cache warming).
+ *
+ * Deliberately simple: one `setInterval` per job, no drift compensation, no
+ * distributed locking, no retry/backoff. Fits a **single-process** deployment;
+ * 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.
+ * @returns A {@link CronRunner} handle (`start` / `stop` / `isRunning`).
+ * @example
+ * ```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 }
+ *   ],
+ *   onError: (job, err) => console.error(`Cron ${job.path} failed`, err)
+ * });
+ *
+ * cron.start();
+ * ```
+ */
 export declare function createCronRunner(config: CronRunnerConfig): CronRunner;

package/dist/cron.js

@@ -1,3 +1,34 @@
+/**
+ * Create a background runner that fires HTTP requests at SvelteKit server
+ * endpoints on a fixed interval — a minimal in-process cron for scheduled work
+ * (digests, cleanup, cache warming).
+ *
+ * Deliberately simple: one `setInterval` per job, no drift compensation, no
+ * distributed locking, no retry/backoff. Fits a **single-process** deployment;
+ * 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.
+ * @returns A {@link CronRunner} handle (`start` / `stop` / `isRunning`).
+ * @example
+ * ```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 }
+ *   ],
+ *   onError: (job, err) => console.error(`Cron ${job.path} failed`, err)
+ * });
+ *
+ * cron.start();
+ * ```
+ */
 export function createCronRunner(config) {
     const timers = [];
     let running = false;
@@ -8,14 +39,26 @@ export function createCronRunner(config) {
             running = true;
             for (const job of config.jobs) {
                 const timer = setInterval(async () => {
+                    const base = config.baseUrl ?? 'http://localhost:3000';
+                    let response;
                     try {
-                        const base = config.baseUrl ?? 'http://localhost:3000';
-                        await fetch(`${base}${job.path}`, {
+                        response = await fetch(`${base}${job.path}`, {
                             method: job.method ?? 'POST',
                             headers: { [config.secretHeader ?? 'x-cron-secret']: config.secret }
                         });
                     }
                     catch (err) {
+                        // Network-level failure (DNS, connection refused, abort): fetch rejected.
+                        config.onError?.(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.
+                    if (!response.ok) {
+                        const err = new Error(`Cron job "${job.path}" returned ${response.status} ${response.statusText}`);
+                        err.status = response.status;
                         config.onError?.(job, err);
                     }
                 }, job.intervalSeconds * 1000);

package/dist/url.svelte.d.ts

@@ -1,19 +1,128 @@
 import { type TableQueryParams, type TableQueryUrlOptions } from './table-query';
+/**
+ * How {@link useUrlArrayParam} maps an array onto the URL:
+ * - `repeat` — one entry per key: `?tag=a&tag=b`
+ * - `csv` — a single delimited value: `?tag=a,b`
+ */
 export type UrlArrayStrategy = 'repeat' | 'csv';
+/** Codec + seed for {@link useUrlParam} / {@link createUrlParam}. */
 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;
+    /**
+     * 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
+     * replaced by this output, leaving every other param untouched. Emit no
+     * entry for a key to remove it from the URL.
+     */
     serialize: (value: T) => URLSearchParams;
+    /** Value the getter returns when {@link parse} yields `null`/`undefined`. */
     initial: T;
+    /**
+     * Replace the current history entry instead of pushing a new one, so rapid
+     * filter/pagination edits don't flood the back button.
+     * @default true
+     */
     replaceState?: boolean;
 };
+/**
+ * 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.
+ *
+ * @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
+ * updateUrlSearchParams({ page: '1', tag: ['a', 'b'], filter: null });
+ * // ?page=1&tag=a&tag=b   (any prior `filter` param is dropped)
+ * ```
+ */
 export declare function updateUrlSearchParams(next: URLSearchParams | Record<string, string | string[]>, opts?: {
     replaceState?: boolean;
 }): void;
+/**
+ * Non-reactive core of {@link useUrlParam}: builds the `get(sp)` / `set(value)`
+ * pair without touching the `page` rune, so `get` can be evaluated against any
+ * `URLSearchParams`. Prefer {@link useUrlParam} in components — this is the
+ * escape hatch when you need to read against a snapshot other than the live
+ * 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`).
+ *
+ * @param _key - Ignored — `options.parse`/`options.serialize` already close
+ *   over the key (see {@link useUrlArrayParam}); kept only for signature parity
+ *   with {@link useUrlParam}.
+ * @param options - Parse/serialize codec, initial value, history behaviour.
+ * @returns `{ get, set }` — `get(sp)` reads a value from the given params
+ *   (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 set: (next: T) => void;
 };
+/**
+ * Bind a typed value to a URL search param, reactively. The returned getter
+ * reads through the `page` rune, so it re-evaluates whenever the URL changes;
+ * the setter writes the value back via `goto` (no full navigation).
+ *
+ * SSR-safe: the getter only reads `page.url` (populated on the server), so the
+ * initial render reflects the incoming URL. The setter calls the client-only
+ * `goto` and is meant to run from event handlers/effects — never during SSR.
+ *
+ * A **getter**, not a store, is returned on purpose: call it lazily inside
+ * `$derived`/`$effect` and the read is tracked there.
+ *
+ * @typeParam T - The decoded value type.
+ * @param key - Param key (forwarded to `createUrlParam` for signature parity;
+ *   the actual key handling lives in `options.parse`/`options.serialize`).
+ * @param options - Parse/serialize codec, initial value, history behaviour.
+ * @returns `[get, set]` — `get()` reads the live value, `set(value)` writes it.
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useUrlParam } from '@urbicon-ui/sveltekit-utils/url.svelte';
+ *
+ *   const [page, setPage] = useUrlParam<number>('page', {
+ *     parse: (sp) => Number(sp.get('page') ?? '1'),
+ *     serialize: (v) => new URLSearchParams({ page: String(v) }),
+ *     initial: 1
+ *   });
+ * </script>
+ *
+ * <button onclick={() => setPage(page() + 1)}>Next — {page()}</button>
+ * ```
+ */
 export declare function useUrlParam<T>(key: string, options: UrlParamOptions<T>): readonly [() => T, (next: T) => void];
+/**
+ * {@link useUrlParam} specialised for a `string[]`, with the encoding handled
+ * for you. Reactive read + `goto`-based write, same as {@link useUrlParam}.
+ *
+ * The `csv` strategy drops empty segments on read (`?tag=` → `[]`) and writes
+ * no param for an empty array, so an empty selection leaves the URL clean.
+ *
+ * @param key - The param key.
+ * @param opts - `initial` seed, `strategy` (default `'repeat'`), and
+ *   `delimiter` for `csv` (default `','`). See {@link UrlArrayStrategy}.
+ * @returns `[get, set]` — `get()` reads the current `string[]`, `set(values)`
+ *   writes it.
+ * @example
+ * ```typescript
+ * const [tags, setTags] = useUrlArrayParam('tag', { initial: [] });            // ?tag=a&tag=b
+ * const [cats, setCats] = useUrlArrayParam('cat', { initial: [], strategy: 'csv' }); // ?cat=a,b
+ * ```
+ */
 export declare function useUrlArrayParam(key: string, opts: {
     initial: string[];
     strategy?: UrlArrayStrategy;

package/dist/url.svelte.js

@@ -1,6 +1,25 @@
 import { goto } from '$app/navigation';
 import { page } from '$app/state';
 import { applyTableQueryToSearchParams, searchParamsToTableQuery } from './table-query';
+/**
+ * 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.
+ *
+ * @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
+ * updateUrlSearchParams({ page: '1', tag: ['a', 'b'], filter: null });
+ * // ?page=1&tag=a&tag=b   (any 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
@@ -33,6 +52,24 @@ export function updateUrlSearchParams(next, opts) {
         keepFocus: true
     });
 }
+/**
+ * Non-reactive core of {@link useUrlParam}: builds the `get(sp)` / `set(value)`
+ * pair without touching the `page` rune, so `get` can be evaluated against any
+ * `URLSearchParams`. Prefer {@link useUrlParam} in components — this is the
+ * escape hatch when you need to read against a snapshot other than the live
+ * 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`).
+ *
+ * @param _key - Ignored — `options.parse`/`options.serialize` already close
+ *   over the key (see {@link useUrlArrayParam}); kept only for signature parity
+ *   with {@link useUrlParam}.
+ * @param options - Parse/serialize codec, initial value, history behaviour.
+ * @returns `{ get, set }` — `get(sp)` reads a value from the given params
+ *   (falling back to `initial`), `set(value)` writes it to the URL.
+ */
 // `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) {
@@ -53,11 +90,61 @@ export function createUrlParam(_key, options) {
     }
     return { get, set: setValue };
 }
+/**
+ * Bind a typed value to a URL search param, reactively. The returned getter
+ * reads through the `page` rune, so it re-evaluates whenever the URL changes;
+ * the setter writes the value back via `goto` (no full navigation).
+ *
+ * SSR-safe: the getter only reads `page.url` (populated on the server), so the
+ * initial render reflects the incoming URL. The setter calls the client-only
+ * `goto` and is meant to run from event handlers/effects — never during SSR.
+ *
+ * A **getter**, not a store, is returned on purpose: call it lazily inside
+ * `$derived`/`$effect` and the read is tracked there.
+ *
+ * @typeParam T - The decoded value type.
+ * @param key - Param key (forwarded to `createUrlParam` for signature parity;
+ *   the actual key handling lives in `options.parse`/`options.serialize`).
+ * @param options - Parse/serialize codec, initial value, history behaviour.
+ * @returns `[get, set]` — `get()` reads the live value, `set(value)` writes it.
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useUrlParam } from '@urbicon-ui/sveltekit-utils/url.svelte';
+ *
+ *   const [page, setPage] = useUrlParam<number>('page', {
+ *     parse: (sp) => Number(sp.get('page') ?? '1'),
+ *     serialize: (v) => new URLSearchParams({ page: String(v) }),
+ *     initial: 1
+ *   });
+ * </script>
+ *
+ * <button onclick={() => setPage(page() + 1)}>Next — {page()}</button>
+ * ```
+ */
 export function useUrlParam(key, options) {
     const { get, set } = createUrlParam(key, options);
     const getBound = () => get(page.url.searchParams);
     return [getBound, set];
 }
+/**
+ * {@link useUrlParam} specialised for a `string[]`, with the encoding handled
+ * for you. Reactive read + `goto`-based write, same as {@link useUrlParam}.
+ *
+ * The `csv` strategy drops empty segments on read (`?tag=` → `[]`) and writes
+ * no param for an empty array, so an empty selection leaves the URL clean.
+ *
+ * @param key - The param key.
+ * @param opts - `initial` seed, `strategy` (default `'repeat'`), and
+ *   `delimiter` for `csv` (default `','`). See {@link UrlArrayStrategy}.
+ * @returns `[get, set]` — `get()` reads the current `string[]`, `set(values)`
+ *   writes it.
+ * @example
+ * ```typescript
+ * const [tags, setTags] = useUrlArrayParam('tag', { initial: [] });            // ?tag=a&tag=b
+ * const [cats, setCats] = useUrlArrayParam('cat', { initial: [], strategy: 'csv' }); // ?cat=a,b
+ * ```
+ */
 export function useUrlArrayParam(key, opts) {
     const strategy = opts.strategy ?? 'repeat';
     const delimiter = opts.delimiter ?? ',';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urbicon-ui/sveltekit-utils",
-  "version": "6.22.0",
+  "version": "6.24.0",
   "description": "SvelteKit helper utilities — createCronRunner and URL-state runes",
   "license": "MIT",
   "repository": {