firstly 0.7.2 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # firstly
 
+## 0.8.0
+
+### Minor Changes
+
+- [#318](https://github.com/jycouet/firstly/pull/318) [`89cb7ee`](https://github.com/jycouet/firstly/commit/89cb7ee93ee783283156c0adeda8b642233f6876) Thanks [@jycouet](https://github.com/jycouet)! - feat: `withShortTermCache` http middleware (dedupes identical read requests within a TTL) and `stackSubscriptionClient` + `withTabSharing` (one shared SSE connection across tabs via `navigator.locks`, with liveQuery resync on leader handoff and reconnect)
+
+- [#322](https://github.com/jycouet/firstly/pull/322) [`fdcc2b7`](https://github.com/jycouet/firstly/commit/fdcc2b7249d737b9bdb08de6feeddc37ca86a952) Thanks [@jycouet](https://github.com/jycouet)! - svelte: add `stackHandleClientError(...middlewares)` and a `withStaleDeployReload()` middleware for `hooks.client.js`, mirroring `stackHttpClient`. Stack your own error handlers alongside stale-deploy recovery: `withStaleDeployReload` hard-reloads once on a chunk-load failure (time-boxed guard, no reload loop), trusting the failure signal instead of `updated.check()` (which lies behind a CDN caching `version.json`).
+
+### Patch Changes
+
+- [#321](https://github.com/jycouet/firstly/pull/321) [`27579a1`](https://github.com/jycouet/firstly/commit/27579a135f970e92b4f491c9c735b8200a49a73e) Thanks [@jycouet](https://github.com/jycouet)! - svelte: re-export `ffTrapFocus` from `firstly/svelte` so custom dialog shells can trap Tab focus without copying the implementation.
+
+- [#325](https://github.com/jycouet/firstly/pull/325) [`0ae3295`](https://github.com/jycouet/firstly/commit/0ae32956dbe3e601e9e194a1275128b7d07612a3) Thanks [@jycouet](https://github.com/jycouet)! - sqlAdmin: run queries read-only by default (Postgres `READ ONLY` transaction, opt out via a UI checkbox), fix the missing row count, add a "copy as markdown" button, and restyle against the semantic theme tokens so it inherits the host app's theme.
+
+## 0.7.3
+
+### Patch Changes
+
+- [#315](https://github.com/jycouet/firstly/pull/315) [`3403d6c`](https://github.com/jycouet/firstly/commit/3403d6cffa657ad04acdac26024bdf6e989df7b4) Thanks [@jycouet](https://github.com/jycouet)! - cron: quieter logs by default - a tick only logs `done in Xms` when it took at least `logs.ended` ms (default 100; `true` = always, `false` = never). `starting` and `result` lines are opt-in, `logs.setup` can silence the registration line. If `onTick` throws, the run is now stored as `failed` (error in `result`), always logged, and no longer leaks the concurrency slot.
+
 ## 0.7.2
 
 ### Patch Changes

package/esm/core/httpClientStack.d.ts

@@ -14,5 +14,26 @@ export type HttpClientMiddleware = (next: HttpClientFetch) => HttpClientFetch;
  * ```
  */
 export declare function stackHttpClient(...middlewares: HttpClientMiddleware[]): HttpClientFetch;
+export type ShortTermCacheOptions = {
+    /** How long a response is served from cache (default 2000ms). */
+    ttlMs?: number;
+    /**
+     * Decide per request if it is cacheable. Default: GET requests, plus remult's
+     * read-only POSTs (`__action=get` / `__action=groupBy`, used when a filter is too
+     * long for a query string).
+     */
+    shouldCache?: (input: RequestInfo | URL, init: RequestInit | undefined, cacheKey: string) => boolean;
+};
+/**
+ * Middleware that dedupes identical read requests within a short TTL - a tiny
+ * client-side cache. Two components mounting and issuing the same query result in
+ * ONE network call; each caller gets its own `Response` clone. Failed requests are
+ * evicted immediately so the next call retries.
+ *
+ * ```ts
+ * remult.apiClient.httpClient = stackHttpClient(withShortTermCache({ ttlMs: 2000 }))
+ * ```
+ */
+export declare function withShortTermCache(opts?: ShortTermCacheOptions): HttpClientMiddleware;
 /** Middleware that sets a request header from `getValue()` when it returns a value. */
 export declare function withHeader(name: string, getValue: () => string | undefined | null): HttpClientMiddleware;

package/esm/core/httpClientStack.js

@@ -14,6 +14,64 @@
 export function stackHttpClient(...middlewares) {
     return middlewares.reduceRight((next, mw) => mw(next), (input, init) => fetch(input, init));
 }
+const defaultShouldCache = (_input, init, key) => {
+    const method = init?.method?.toUpperCase() ?? 'GET';
+    if (method === 'GET')
+        return true;
+    if (method === 'POST')
+        return key.includes('__action=get') || key.includes('__action=groupBy');
+    return false;
+};
+/**
+ * Middleware that dedupes identical read requests within a short TTL - a tiny
+ * client-side cache. Two components mounting and issuing the same query result in
+ * ONE network call; each caller gets its own `Response` clone. Failed requests are
+ * evicted immediately so the next call retries.
+ *
+ * ```ts
+ * remult.apiClient.httpClient = stackHttpClient(withShortTermCache({ ttlMs: 2000 }))
+ * ```
+ */
+export function withShortTermCache(opts = {}) {
+    const ttlMs = opts.ttlMs ?? 2000;
+    const shouldCache = opts.shouldCache ?? defaultShouldCache;
+    const cache = new Map();
+    return (next) => async (input, init) => {
+        let cacheKey = input.toString();
+        if (init?.body) {
+            const body = init.body;
+            const bodyStr = typeof body === 'string'
+                ? body
+                : body instanceof URLSearchParams
+                    ? body.toString()
+                    : JSON.stringify(body);
+            cacheKey = `${cacheKey}:${bodyStr}`;
+        }
+        if (!shouldCache(input, init, cacheKey)) {
+            return next(input, init);
+        }
+        const now = Date.now();
+        const cached = cache.get(cacheKey);
+        if (cached) {
+            if (now - cached.timestamp < ttlMs) {
+                const response = await cached.promise;
+                return response.clone();
+            }
+            cache.delete(cacheKey);
+        }
+        // Keep a pristine copy in cache; every consumer (incl. this one) reads a clone.
+        const promise = next(input, init).then((r) => r.clone());
+        cache.set(cacheKey, { promise, timestamp: now });
+        try {
+            const response = await promise;
+            return response.clone();
+        }
+        catch (e) {
+            cache.delete(cacheKey);
+            throw e;
+        }
+    };
+}
 /** Middleware that sets a request header from `getValue()` when it returns a value. */
 export function withHeader(name, getValue) {
     return (next) => async (input, init) => {

package/esm/core/subscriptionClientStack.d.ts

@@ -0,0 +1,36 @@
+import { type SubscriptionClient } from 'remult';
+export type SubscriptionClientMiddleware = (next: SubscriptionClient) => SubscriptionClient;
+/**
+ * Compose a `SubscriptionClient` from middlewares, with `directSseSubscriptionClient`
+ * at the bottom of the stack. With no middlewares, you get the bare direct SSE client.
+ *
+ * ```ts
+ * remult.apiClient.subscriptionClient = stackSubscriptionClient(withTabSharing())
+ * ```
+ */
+export declare function stackSubscriptionClient(...middlewares: SubscriptionClientMiddleware[]): SubscriptionClient;
+/**
+ * Middleware that shares ONE real SSE connection across all tabs of the same origin.
+ *
+ * Why: the browser's HTTP/1.1 ~6-connections-per-domain limit. With one EventSource
+ * per tab, opening 5+ tabs starves all other HTTP requests on the domain.
+ *
+ * How: `navigator.locks` elects a single leader tab. The leader opens the underlying
+ * (next) `SubscriptionClient` and forwards every channel message over a
+ * `BroadcastChannel` to follower tabs. Followers ask the leader to (un)subscribe
+ * the channels they care about; the leader refcounts interest per tab. On leader
+ * death (close/refresh), the lock is released and the next tab takes over,
+ * re-subscribing every channel any surviving tab still cares about.
+ *
+ * liveQuery support: a leader handoff and a real SSE reconnect both fan out a
+ * `reconnect` signal so EVERY tab fires its own `onReconnect`. Remult's
+ * LiveQueryClient then re-runs each query (refetch + resubscribe), covering
+ * messages lost in the gap. Plain `SubscriptionChannel` fanout works too, with the
+ * usual SSE semantics (no replay of messages missed during a reconnect).
+ */
+export declare function withTabSharing(): SubscriptionClientMiddleware;
+/**
+ * Minimal direct SSE-based `SubscriptionClient` - mirrors Remult's internal
+ * `SseSubscriptionClient`. Inlined because Remult does not publicly export it.
+ */
+export declare function directSseSubscriptionClient(): SubscriptionClient;

package/esm/core/subscriptionClientStack.js

@@ -0,0 +1,333 @@
+import { remult, } from 'remult';
+/**
+ * Compose a `SubscriptionClient` from middlewares, with `directSseSubscriptionClient`
+ * at the bottom of the stack. With no middlewares, you get the bare direct SSE client.
+ *
+ * ```ts
+ * remult.apiClient.subscriptionClient = stackSubscriptionClient(withTabSharing())
+ * ```
+ */
+export function stackSubscriptionClient(...middlewares) {
+    return middlewares.reduceRight((next, mw) => mw(next), directSseSubscriptionClient());
+}
+const BUS_NAME = 'ff-sse-bus';
+const LOCK_NAME = 'ff-sse-leader';
+/**
+ * Middleware that shares ONE real SSE connection across all tabs of the same origin.
+ *
+ * Why: the browser's HTTP/1.1 ~6-connections-per-domain limit. With one EventSource
+ * per tab, opening 5+ tabs starves all other HTTP requests on the domain.
+ *
+ * How: `navigator.locks` elects a single leader tab. The leader opens the underlying
+ * (next) `SubscriptionClient` and forwards every channel message over a
+ * `BroadcastChannel` to follower tabs. Followers ask the leader to (un)subscribe
+ * the channels they care about; the leader refcounts interest per tab. On leader
+ * death (close/refresh), the lock is released and the next tab takes over,
+ * re-subscribing every channel any surviving tab still cares about.
+ *
+ * liveQuery support: a leader handoff and a real SSE reconnect both fan out a
+ * `reconnect` signal so EVERY tab fires its own `onReconnect`. Remult's
+ * LiveQueryClient then re-runs each query (refetch + resubscribe), covering
+ * messages lost in the gap. Plain `SubscriptionChannel` fanout works too, with the
+ * usual SSE semantics (no replay of messages missed during a reconnect).
+ */
+export function withTabSharing() {
+    return (next) => {
+        if (typeof window === 'undefined' ||
+            typeof BroadcastChannel === 'undefined' ||
+            typeof navigator === 'undefined' ||
+            !('locks' in navigator)) {
+            return next;
+        }
+        return {
+            openConnection(onReconnect) {
+                return Promise.resolve(createSharedConnection(next, onReconnect));
+            },
+        };
+    };
+}
+function createSharedConnection(realClient, onReconnect) {
+    const tabId = typeof crypto !== 'undefined' && crypto.randomUUID
+        ? crypto.randomUUID()
+        : Math.random().toString(36).slice(2);
+    const localHandlers = new Map();
+    const bus = new BroadcastChannel(BUS_NAME);
+    let isLeader = false;
+    // True once another tab's leader served us - a later takeover is then a handoff.
+    let sawRemoteLeader = false;
+    let leaderConnection;
+    // Leader state: real subscription per channel + which tabs still want it.
+    const realSubs = new Map();
+    const interest = new Map();
+    let closed = false;
+    let closeResolver;
+    const dispatchLocally = (channel, message) => {
+        const handlers = localHandlers.get(channel);
+        if (handlers)
+            handlers.forEach((h) => h(message));
+    };
+    const addInterest = (channel, forTab) => {
+        let tabs = interest.get(channel);
+        if (!tabs)
+            interest.set(channel, (tabs = new Set()));
+        tabs.add(forTab);
+    };
+    const ensureRealSubscribed = async (channel, forTab) => {
+        if (!isLeader || !leaderConnection)
+            return;
+        addInterest(channel, forTab);
+        if (realSubs.has(channel))
+            return;
+        const promise = leaderConnection.subscribe(channel, (data) => {
+            dispatchLocally(channel, data);
+            bus.postMessage({ type: 'message', channel, data });
+        }, (err) => {
+            console.error('[withTabSharing] channel error', channel, err);
+        });
+        realSubs.set(channel, promise);
+        await promise;
+    };
+    const dropInterest = (channel, forTab) => {
+        if (!isLeader)
+            return;
+        const tabs = interest.get(channel);
+        if (!tabs)
+            return;
+        tabs.delete(forTab);
+        if (tabs.size > 0)
+            return;
+        interest.delete(channel);
+        const sub = realSubs.get(channel);
+        if (sub) {
+            realSubs.delete(channel);
+            sub.then((unsub) => unsub()).catch(() => { });
+        }
+    };
+    const dropTab = (forTab) => {
+        if (!isLeader)
+            return;
+        for (const channel of [...interest.keys()]) {
+            dropInterest(channel, forTab);
+        }
+    };
+    bus.onmessage = async (e) => {
+        const msg = e.data;
+        switch (msg.type) {
+            case 'message':
+                dispatchLocally(msg.channel, msg.data);
+                break;
+            case 'reconnect':
+                if (!isLeader)
+                    onReconnect();
+                break;
+            case 'follower:subscribe':
+                if (isLeader)
+                    await ensureRealSubscribed(msg.channel, msg.tabId);
+                break;
+            case 'follower:unsubscribe':
+                dropInterest(msg.channel, msg.tabId);
+                break;
+            case 'follower:bye':
+                dropTab(msg.tabId);
+                break;
+            case 'follower:channels':
+                if (isLeader) {
+                    for (const ch of msg.channels)
+                        await ensureRealSubscribed(ch, msg.tabId);
+                }
+                break;
+            case 'leader:hello':
+                if (!isLeader) {
+                    const isHandoff = sawRemoteLeader;
+                    sawRemoteLeader = true;
+                    bus.postMessage({
+                        type: 'follower:channels',
+                        tabId,
+                        channels: [...localHandlers.keys()],
+                    });
+                    // New leader means the previous SSE connection died with our
+                    // subscriptions on it - resync liveQueries.
+                    if (isHandoff)
+                        onReconnect();
+                }
+                break;
+        }
+    };
+    navigator.locks
+        .request(LOCK_NAME, { mode: 'exclusive' }, async () => {
+        if (closed)
+            return;
+        try {
+            leaderConnection = await realClient.openConnection(() => {
+                // Real SSE reconnected: resync every tab, not just the leader.
+                onReconnect();
+                bus.postMessage({ type: 'reconnect' });
+            });
+            isLeader = true;
+            for (const ch of localHandlers.keys()) {
+                await ensureRealSubscribed(ch, tabId);
+            }
+            bus.postMessage({ type: 'leader:hello' });
+            // We were riding a dead leader's connection - resync our own queries.
+            if (sawRemoteLeader)
+                onReconnect();
+        }
+        catch (err) {
+            console.error('[withTabSharing] failed to become leader', err);
+            return;
+        }
+        await new Promise((resolve) => {
+            if (closed)
+                resolve();
+            closeResolver = resolve;
+        });
+    })
+        .catch((err) => {
+        console.error('[withTabSharing] lock request failed', err);
+    });
+    return {
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            try {
+                bus.postMessage({ type: 'follower:bye', tabId });
+                bus.close();
+            }
+            catch {
+                // bus may already be gone (tab teardown)
+            }
+            if (leaderConnection) {
+                try {
+                    leaderConnection.close();
+                }
+                catch {
+                    // best effort
+                }
+            }
+            closeResolver?.();
+        },
+        async subscribe(channel, onMessage, _onError) {
+            let handlers = localHandlers.get(channel);
+            if (!handlers) {
+                handlers = new Set();
+                localHandlers.set(channel, handlers);
+            }
+            handlers.add(onMessage);
+            if (isLeader) {
+                await ensureRealSubscribed(channel, tabId);
+            }
+            else {
+                bus.postMessage({ type: 'follower:subscribe', tabId, channel });
+            }
+            return () => {
+                const set = localHandlers.get(channel);
+                if (!set)
+                    return;
+                set.delete(onMessage);
+                if (set.size === 0) {
+                    localHandlers.delete(channel);
+                    if (isLeader) {
+                        dropInterest(channel, tabId);
+                    }
+                    else {
+                        bus.postMessage({
+                            type: 'follower:unsubscribe',
+                            tabId,
+                            channel,
+                        });
+                    }
+                }
+            };
+        },
+    };
+}
+/**
+ * Minimal direct SSE-based `SubscriptionClient` - mirrors Remult's internal
+ * `SseSubscriptionClient`. Inlined because Remult does not publicly export it.
+ */
+export function directSseSubscriptionClient() {
+    return {
+        openConnection(onReconnect) {
+            const channels = new Map();
+            let connectionId;
+            let source;
+            let connected = false;
+            let retryCount = 0;
+            const baseUrl = remult.apiClient.url ?? '/api';
+            const streamUrl = `${baseUrl}/stream`;
+            const post = async (path, body) => {
+                const res = await fetch(`${streamUrl}/${path}`, {
+                    method: 'POST',
+                    credentials: 'include',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify(body),
+                });
+                return res.json().catch(() => null);
+            };
+            const subscribeOnServer = async (channel) => {
+                if (!connectionId)
+                    return;
+                await post('subscribe', { channel, clientId: connectionId });
+            };
+            const open = (resolveOnce) => {
+                if (source)
+                    source.close();
+                source = new EventSource(streamUrl, { withCredentials: true });
+                source.onmessage = (e) => {
+                    try {
+                        const msg = JSON.parse(e.data);
+                        const listeners = channels.get(msg.channel);
+                        if (listeners)
+                            listeners.forEach((l) => l(msg.data));
+                    }
+                    catch (err) {
+                        console.error('[directSseSubscriptionClient] parse error', err);
+                    }
+                };
+                source.onerror = () => {
+                    source?.close();
+                    if (retryCount++ < 10)
+                        setTimeout(open, 500, resolveOnce);
+                };
+                source.addEventListener('connectionId', async (e) => {
+                    connectionId = e.data;
+                    if (connected) {
+                        for (const ch of channels.keys())
+                            await subscribeOnServer(ch);
+                        onReconnect();
+                    }
+                    else {
+                        connected = true;
+                        resolveOnce(connection);
+                    }
+                });
+            };
+            const connection = {
+                close() {
+                    source?.close();
+                },
+                async subscribe(channel, handler, _onError) {
+                    let listeners = channels.get(channel);
+                    if (!listeners) {
+                        channels.set(channel, (listeners = []));
+                        await subscribeOnServer(channel);
+                    }
+                    listeners.push(handler);
+                    return () => {
+                        const idx = listeners.indexOf(handler);
+                        if (idx >= 0)
+                            listeners.splice(idx, 1);
+                        if (listeners.length === 0) {
+                            channels.delete(channel);
+                            if (connectionId) {
+                                post('unsubscribe', { channel, clientId: connectionId }).catch(() => { });
+                            }
+                        }
+                    };
+                },
+            };
+            return new Promise((resolve) => open(resolve));
+        },
+    };
+}

package/esm/cron/Cron.d.ts

@@ -1,4 +1,4 @@
-declare const statuses: readonly ["starting", "ended", "skipped"];
+declare const statuses: readonly ["starting", "ended", "skipped", "failed"];
 type StatusType = (typeof statuses)[number];
 export declare class Cron {
     id?: string;

package/esm/cron/Cron.js

@@ -6,7 +6,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 import { Entity, Fields } from 'remult';
 import { Roles_Cron } from './Roles_Cron';
-const statuses = ['starting', 'ended', 'skipped'];
+const statuses = ['starting', 'ended', 'skipped', 'failed'];
 let Cron = class Cron {
     id;
     topic;

package/esm/cron/server/index.d.ts

@@ -41,9 +41,17 @@ export type CronJobParams = {
     onTick: CronOnTick;
     topic: string;
     concurrent?: number;
+    /**
+     * Defaults: a tick logs `done in Xms` only when it took at least `ended` ms
+     * (default 100, `true` = always, `false` = never) + a `setup done` line at registration.
+     * `starting` & `result` are opt-in (full history incl. results is stored in `_ff_crons`).
+     * Failures and concurrency skips are always logged.
+     */
     logs?: {
+        setup?: boolean;
         starting?: boolean;
-        ended?: boolean;
+        result?: boolean;
+        ended?: boolean | number;
     };
     start?: boolean;
     runOnInit?: boolean;

package/esm/cron/server/index.js

@@ -30,6 +30,8 @@ export const cronTime = {
      */
     every_friday_morning: '11 5 * * 5',
 };
+const DEFAULT_ENDED_MIN_MS = 100;
+const fmtDuration = (ms) => (ms < 1000 ? `${ms}ms` : `${(ms / 1000).toFixed(1)}s`);
 /**
  * usage:
  *
@@ -59,47 +61,55 @@ export const cron = (jobsInfos) => {
         key: 'cron',
         entities: [Cron],
     });
-    const logJobs = (topic, job, message, with_metadata = true, isSuccess = true) => {
-        const l = [];
-        l.push(magenta(`[${topic}]`));
-        l.push(message);
-        if (with_metadata) {
-            // If the job is "stopped", there will still be a next date, but it will not fire it. The job has to start.
-            l.push(`(${job.isActive ? green('running') : red('stopped')}, next at ${yellow(job.nextDate().toISO())})`);
-        }
-        if (isSuccess) {
-            log.success(l.join(' '));
-        }
-        else {
-            log.info(l.join(' '));
-        }
-    };
     m.initApi = async () => {
         jobsInfos.forEach((infos) => {
             const { topic, runOnInit, logs, concurrent, onTick: originalOnTick, ...params } = infos;
             const concurrentToUse = concurrent ?? 1;
+            const prefix = magenta(`[${topic}]`);
+            const endedMinMs = logs?.ended === false
+                ? Infinity
+                : logs?.ended === true
+                    ? 0
+                    : (logs?.ended ?? DEFAULT_ENDED_MIN_MS);
             // Create a wrapper that converts the return type to void for CronJob
             const wrappedOnTick = async () => {
-                if (jobs[topic].concurrentInProgress < concurrentToUse) {
-                    jobs[topic].concurrentInProgress = jobs[topic].concurrentInProgress + 1;
-                    const rCron = await repo(Cron).insert({ topic });
-                    if (logs?.starting === undefined || logs?.starting === true) {
-                        logJobs(topic, job, 'starting...', false, false);
-                    }
+                if (jobs[topic].concurrentInProgress >= concurrentToUse) {
+                    await repo(Cron).insert({ topic, status: 'skipped' });
+                    log.info(`${prefix} skipped because of concurrent limit (${yellow(concurrentToUse.toString())})`);
+                    return;
+                }
+                jobs[topic].concurrentInProgress++;
+                const startedAt = Date.now();
+                const rCron = await repo(Cron).insert({ topic });
+                if (logs?.starting) {
+                    log.info(`${prefix} starting...`);
+                }
+                try {
                     const res = await originalOnTick();
-                    log.info(`[${topic}] result:`, res);
                     rCron.result = res;
                     rCron.endedAt = new Date();
                     rCron.status = 'ended';
                     await repo(Cron).save(rCron);
-                    if (logs?.ended === undefined || logs?.ended === true) {
-                        logJobs(topic, job, 'done');
+                    const ms = Date.now() - startedAt;
+                    if (ms >= endedMinMs) {
+                        const msg = `${prefix} done in ${fmtDuration(ms)}`;
+                        if (logs?.result) {
+                            log.success(msg, res);
+                        }
+                        else {
+                            log.success(msg);
+                        }
                     }
-                    jobs[topic].concurrentInProgress = jobs[topic].concurrentInProgress - 1;
                 }
-                else {
-                    await repo(Cron).insert({ topic, status: 'skipped' });
-                    logJobs(topic, job, `skipped because of concurrent limit (${yellow(concurrentToUse.toString())})`, false, false);
+                catch (error) {
+                    rCron.result = { error: error instanceof Error ? error.message : String(error) };
+                    rCron.endedAt = new Date();
+                    rCron.status = 'failed';
+                    await repo(Cron).save(rCron);
+                    log.error(`${prefix} failed after ${fmtDuration(Date.now() - startedAt)}`, error);
+                }
+                finally {
+                    jobs[topic].concurrentInProgress--;
                 }
             };
             // Use type assertion to bypass complex generic type issues
@@ -108,7 +118,10 @@ export const cron = (jobsInfos) => {
                 onTick: wrappedOnTick,
             });
             jobs[topic] = { job, concurrentInProgress: 0 };
-            logJobs(topic, job, 'setup done');
+            if (logs?.setup !== false) {
+                // A stopped job still reports a next date, it just won't fire it.
+                log.success(`${prefix} setup done (${job.isActive ? green('running') : red('stopped')}, next at ${yellow(job.nextDate().toISO())})`);
+            }
             // If not it will be done too early
             if (runOnInit) {
                 job.fireOnTick();

package/esm/index.d.ts

@@ -15,8 +15,10 @@ export { errorMessage, isError } from './core/helper.js';
 export { tryCatch, tryCatchSync } from './core/tryCatch.js';
 export type { ResolvedType, UnArray, RecursivePartial } from './core/types.js';
 export { tw } from './core/tailwind.js';
-export { stackHttpClient, withHeader } from './core/httpClientStack.js';
-export type { HttpClientFetch, HttpClientMiddleware } from './core/httpClientStack.js';
+export { stackHttpClient, withHeader, withShortTermCache } from './core/httpClientStack.js';
+export type { HttpClientFetch, HttpClientMiddleware, ShortTermCacheOptions, } from './core/httpClientStack.js';
+export { stackSubscriptionClient, withTabSharing, directSseSubscriptionClient, } from './core/subscriptionClientStack.js';
+export type { SubscriptionClientMiddleware } from './core/subscriptionClientStack.js';
 export { FF_LogToConsole } from './SqlDatabase/FF_LogToConsole.js';
 export { FilterEntity } from './virtual/FilterEntity.js';
 export { UIEntity } from './virtual/UIEntity.js';

package/esm/index.js

@@ -15,7 +15,8 @@ export { FF_Validators, createValidators } from './core/FF_Validators.js';
 export { errorMessage, isError } from './core/helper.js';
 export { tryCatch, tryCatchSync } from './core/tryCatch.js';
 export { tw } from './core/tailwind.js';
-export { stackHttpClient, withHeader } from './core/httpClientStack.js';
+export { stackHttpClient, withHeader, withShortTermCache } from './core/httpClientStack.js';
+export { stackSubscriptionClient, withTabSharing, directSseSubscriptionClient, } from './core/subscriptionClientStack.js';
 // Misc primitives still exposed from the root.
 export { FF_LogToConsole } from './SqlDatabase/FF_LogToConsole.js';
 export { FilterEntity } from './virtual/FilterEntity.js';

package/esm/sqlAdmin/SqlAdminController.d.ts

@@ -2,8 +2,16 @@ import { SqlDatabase } from 'remult';
 export declare class SqlAdminController {
     /** Optional override set by the `sqlAdmin()` module's `initApi`. Falls back to `SqlDatabase.getDb()`. */
     static dp?: SqlDatabase;
-    static exec(cmd: string): Promise<{
-        r: import("remult").SqlResult;
+    /**
+     * @param cmd SQL to run.
+     * @param notReadOnly When `false` (default) the query runs inside a
+     *   `READ ONLY` transaction so the database itself rejects any write
+     *   (INSERT/UPDATE/DELETE/DDL). Set `true` only when you deliberately want
+     *   to mutate - the UI gates this behind an explicit checkbox.
+     */
+    static exec(cmd: string, notReadOnly?: boolean): Promise<{
+        rows: any[];
+        rowCount: number;
         took: number;
     }>;
 }

package/esm/sqlAdmin/SqlAdminController.js

@@ -10,12 +10,30 @@ import { Roles_SqlAdmin } from './Roles_SqlAdmin';
 export class SqlAdminController {
     /** Optional override set by the `sqlAdmin()` module's `initApi`. Falls back to `SqlDatabase.getDb()`. */
     static dp;
-    static async exec(cmd) {
+    /**
+     * @param cmd SQL to run.
+     * @param notReadOnly When `false` (default) the query runs inside a
+     *   `READ ONLY` transaction so the database itself rejects any write
+     *   (INSERT/UPDATE/DELETE/DDL). Set `true` only when you deliberately want
+     *   to mutate - the UI gates this behind an explicit checkbox.
+     */
+    static async exec(cmd, notReadOnly = false) {
         const db = SqlAdminController.dp ?? SqlDatabase.getDb();
         const start = performance.now();
-        const r = await db.execute(cmd);
+        let rows = [];
+        if (notReadOnly) {
+            rows = (await db.execute(cmd)).rows;
+        }
+        else {
+            await db.transaction(async (tx) => {
+                const txDb = SqlDatabase.getDb(tx);
+                // Postgres: makes the whole transaction reject writes at the DB level.
+                await txDb.execute('SET TRANSACTION READ ONLY');
+                rows = (await txDb.execute(cmd)).rows;
+            });
+        }
         const took = performance.now() - start;
-        return { r, took };
+        return { rows, rowCount: rows.length, took };
     }
 }
 __decorate([

package/esm/sqlAdmin/ui/SqlAdmin.svelte

@@ -2,9 +2,9 @@
 	/**
 	 * SQL Admin UI.
 	 *
-	 * Dark theme (zinc + indigo accent), styled with raw Tailwind utilities only -
-	 * no plugin (daisyUI, shadcn, etc.) required. Drop into any Tailwind-powered
-	 * project and it just works.
+	 * Styled against the semantic theme tokens (`bg-card`, `text-foreground`,
+	 * `border-border`, `bg-primary`, `bg-destructive`, ...) defined by the host
+	 * app, so it inherits the userland theme instead of a hard-coded palette.
 	 *
 	 * Results are logged to the browser console as `for AI: <json rows>` after
 	 * each successful query - chrome-devtools / AI agents inspecting the page
@@ -18,9 +18,11 @@ FROM "public"."users"
 LIMIT 10`
 
 	let sqlInput = $state(defaultQuery)
-	let result: any = $state()
+	let result: { rows: any[]; rowCount: number; took: number } | undefined = $state()
 	let error = $state('')
 	let isLoading = $state(false)
+	let notReadOnly = $state(false)
+	let copied = $state(false)
 
 	const queries = {
 		default: { label: 'Default', sql: defaultQuery },
@@ -62,8 +64,8 @@ ORDER BY tablename, indexname`,
 		try {
 			error = ''
 			isLoading = true
-			result = { ...(await SqlAdminController.exec(sqlInput)) }
-			log.info('for AI:', JSON.stringify(result.r.rows))
+			result = await SqlAdminController.exec(sqlInput, notReadOnly)
+			log.info('for AI:', JSON.stringify(result.rows))
 			log.info('for humans:', result)
 		} catch (e) {
 			error = JSON.stringify(e, null, 2)
@@ -76,12 +78,42 @@ ORDER BY tablename, indexname`,
 		if (!rows || rows.length === 0) return []
 		return Object.keys(rows[0])
 	}
+
+	function cellToText(cell: unknown): string {
+		if (cell === null || cell === undefined) return ''
+		if (typeof cell === 'object') return JSON.stringify(cell)
+		return String(cell)
+	}
+
+	/** Render the result as a GitHub-flavoured markdown table (paste into a chat). */
+	function toMarkdown(rows: any[]): string {
+		const headers = getHeaders(rows)
+		if (headers.length === 0) return ''
+		const esc = (s: string) => s.replaceAll('|', '\\|').replaceAll('\n', ' ')
+		const head = `| ${headers.map(esc).join(' | ')} |`
+		const sep = `| ${headers.map(() => '---').join(' | ')} |`
+		const body = rows
+			.map((row) => `| ${headers.map((h) => esc(cellToText(row[h]))).join(' | ')} |`)
+			.join('\n')
+		return `${head}\n${sep}\n${body}`
+	}
+
+	async function copyTable() {
+		if (!result?.rows?.length) return
+		try {
+			await navigator.clipboard.writeText(toMarkdown(result.rows))
+			copied = true
+			setTimeout(() => (copied = false), 1500)
+		} catch (e) {
+			log.error('copy failed', e)
+		}
+	}
 </script>
 
-<div class="border border-slate-700 bg-slate-800 text-slate-200">
-	<header class="border-b border-slate-700 px-5 py-4">
-		<h2 class="text-lg font-semibold text-slate-100">SQL Admin</h2>
-		<p class="mt-1 text-sm text-slate-400">
+<div class="border border-border bg-card text-card-foreground">
+	<header class="border-b border-border px-5 py-4">
+		<h2 class="text-lg font-semibold text-foreground">SQL Admin</h2>
+		<p class="mt-1 text-sm text-muted-foreground">
 			Execute SQL queries directly on the database. Results are displayed below and also logged to the
 			browser console.
 		</p>
@@ -92,7 +124,7 @@ ORDER BY tablename, indexname`,
 			{#each Object.entries(queries) as [id, query] (id)}
 				<button
 					type="button"
-					class="border border-slate-600 bg-slate-700 px-3 py-1.5 text-sm font-medium text-slate-100 hover:bg-slate-600 disabled:opacity-50"
+					class="border border-border bg-secondary px-3 py-1.5 text-sm font-medium text-secondary-foreground hover:bg-accent hover:text-accent-foreground disabled:opacity-50"
 					onclick={() => setPresetQuery(id as keyof typeof queries)}>{query.label}</button
 				>
 			{/each}
@@ -100,14 +132,14 @@ ORDER BY tablename, indexname`,
 		<form onsubmit={handleSubmit} class="flex flex-col gap-4">
 			<textarea
 				bind:value={sqlInput}
-				class="h-52 w-full border border-slate-700 bg-slate-900 p-3 font-mono text-sm text-slate-100 placeholder-slate-500 focus:border-indigo-400 focus:outline-none disabled:opacity-50"
+				class="h-52 w-full border border-input bg-background p-3 font-mono text-sm text-foreground placeholder-muted-foreground focus:border-ring focus:outline-none disabled:opacity-50"
 				placeholder="Enter SQL command..."
 				disabled={isLoading}
 			></textarea>
 			<div class="flex flex-wrap items-center gap-4">
 				<button
 					type="submit"
-					class="inline-flex items-center gap-2 bg-indigo-500 px-4 py-2 text-sm font-medium text-white hover:bg-indigo-400 disabled:opacity-50"
+					class="inline-flex items-center gap-2 bg-primary px-4 py-2 text-sm font-medium text-primary-foreground hover:opacity-90 disabled:opacity-50"
 					disabled={isLoading}
 				>
 					{#if isLoading}
@@ -126,55 +158,78 @@ ORDER BY tablename, indexname`,
 					{/if}
 					Execute SQL
 				</button>
+
+				<label
+					class="inline-flex items-center gap-2 text-sm font-medium select-none"
+					class:text-destructive={notReadOnly}
+					class:text-muted-foreground={!notReadOnly}
+					title="Read-only runs your query in a READ ONLY transaction so the database rejects any write. Tick this only when you know what you are doing."
+				>
+					<input type="checkbox" bind:checked={notReadOnly} class="accent-destructive" />
+					{notReadOnly ? 'Writes enabled (I know what I am doing)' : 'Read-only'}
+				</label>
+
 				{#if error}
 					<pre
-						class="flex-1 overflow-auto border border-red-500/40 bg-red-500/10 p-3 text-sm text-red-200">{error.replaceAll(
+						class="flex-1 overflow-auto border border-destructive bg-destructive/10 p-3 text-sm text-destructive">{error.replaceAll(
 							'\\n',
 							'\n',
 						)}</pre>
 				{/if}
 				{#if result}
 					<div
-						class="flex flex-1 justify-between border border-emerald-500/40 bg-emerald-500/10 p-3 text-sm text-emerald-200"
+						class="flex flex-1 items-center justify-between gap-3 border border-border bg-muted p-3 text-sm text-muted-foreground"
 					>
 						<span>{result.took.toFixed(0)} ms</span>
-						<span>{result.r.rowCount} rows</span>
+						<span>{result.rowCount} row{result.rowCount === 1 ? '' : 's'}</span>
 					</div>
 				{/if}
 			</div>
 		</form>
 		{#if result}
+			{#if result.rows && result.rows.length > 0}
+				<div class="flex items-center justify-between">
+					<span class="text-sm text-muted-foreground">
+						{result.rowCount} row{result.rowCount === 1 ? '' : 's'}
+					</span>
+					<button
+						type="button"
+						onclick={copyTable}
+						class="inline-flex items-center gap-2 border border-border bg-secondary px-3 py-1.5 text-sm font-medium text-secondary-foreground hover:bg-accent hover:text-accent-foreground"
+					>
+						{copied ? 'Copied!' : 'Copy as markdown'}
+					</button>
+				</div>
+			{/if}
 			<!-- contain: paint isolates the scroll container's repaint area; without
 				 it, scrolling a wide result table forces the whole page to repaint
 				 every frame, which is what made horizontal scroll feel laggy. -->
-			<div class="max-h-[600px] overflow-auto border border-slate-700 [contain:paint]">
-				{#if result.r.rows && result.r.rows.length > 0}
+			<div class="max-h-[600px] overflow-auto border border-border [contain:paint]">
+				{#if result.rows && result.rows.length > 0}
 					<table class="w-full border-collapse text-sm">
-						<thead class="sticky top-0 z-10 bg-slate-700">
+						<thead class="sticky top-0 z-10 bg-secondary">
 							<tr>
-								{#each getHeaders(result.r.rows) as header, i (i)}
-									<th class="border-b border-slate-600 px-3 py-2 text-left font-semibold text-slate-100"
+								{#each getHeaders(result.rows) as header, i (i)}
+									<th
+										class="border-b border-border px-3 py-2 text-left font-semibold text-secondary-foreground"
 										>{header}</th
 									>
 								{/each}
 							</tr>
 						</thead>
 						<tbody>
-							{#each result.r.rows as row, r (r)}
-								<!-- Solid stripe (no /50 alpha) so the GPU doesn't have to alpha-
-									 composite every cell on every scroll frame. -->
-								<tr class="even:bg-slate-900">
+							{#each result.rows as row, r (r)}
+								<tr class="even:bg-muted/40">
 									{#each Object.values(row) as cell, c (c)}
 										<!-- min-w to keep short cells readable, max-w-xs to cap
 											 wide ones, break-all so long unbroken strings (URLs,
 											 DIDs) wrap inside their cell instead of forcing the
-											 column to ~940px and the table to 2.5kpx (which is
-											 what made horizontal scroll laggy). -->
+											 column too wide and making horizontal scroll laggy. -->
 										<td
-											class="max-w-xs min-w-[8rem] border-b border-slate-700 px-3 py-2 align-top text-sm break-all text-slate-200"
+											class="max-w-xs min-w-[8rem] border-b border-border px-3 py-2 align-top text-sm break-all text-foreground"
 										>
-											{#if typeof cell === 'object'}<pre
-													class="text-xs whitespace-pre-wrap text-slate-400">{JSON.stringify(
+											{#if typeof cell === 'object' && cell !== null}<pre
+													class="text-xs whitespace-pre-wrap text-muted-foreground">{JSON.stringify(
 														cell,
 														null,
 														2,
@@ -187,9 +242,7 @@ ORDER BY tablename, indexname`,
 						</tbody>
 					</table>
 				{:else}
-					<div class="border border-slate-700 bg-slate-800 p-3 text-sm text-slate-300">
-						No rows returned
-					</div>
+					<div class="bg-card p-3 text-sm text-muted-foreground">No rows returned</div>
 				{/if}
 			</div>
 		{/if}

package/esm/svelte/handleError.d.ts

@@ -0,0 +1,31 @@
+import type { HandleClientError } from '@sveltejs/kit';
+export type HandleClientErrorMiddleware = (next: HandleClientError) => HandleClientError;
+/**
+ * Compose `handleError` middlewares into a single `hooks.client.js` handler.
+ * Middlewares run outermost-first (the first argument wraps the rest). A middleware
+ * either short-circuits (return without calling `next` - e.g. a hard reload) or calls
+ * `next(input)`. The base returns `{ message: 'Something went wrong' }`.
+ *
+ * ```js
+ * // src/hooks.client.js
+ * import { stackHandleClientError, withStaleDeployReload } from './'
+ *
+ * export const handleError = stackHandleClientError(
+ *   withStaleDeployReload(),
+ *   (next) => (input) => {
+ *     report(input.error) // your logging
+ *     return next(input) // or return { message: 'Oops' } to stop here
+ *   },
+ * )
+ * ```
+ */
+export declare function stackHandleClientError(...middlewares: HandleClientErrorMiddleware[]): HandleClientError;
+/**
+ * Middleware that recovers stale-deploy chunk failures: after a deploy an open client
+ * (esp. SPA builds) 404s on a lazy chunk. Trusts the failure signal itself, not
+ * `updated.check()` (which lies behind a CDN caching `version.json`), and hard-reloads
+ * once - a time-boxed one-shot guard prevents reload loops. Only chunk-load errors
+ * reload (a blind 404 reload would break client-side not-found routes); anything else
+ * falls through to `next`.
+ */
+export declare function withStaleDeployReload(): HandleClientErrorMiddleware;

package/esm/svelte/handleError.js

@@ -0,0 +1,62 @@
+/**
+ * Compose `handleError` middlewares into a single `hooks.client.js` handler.
+ * Middlewares run outermost-first (the first argument wraps the rest). A middleware
+ * either short-circuits (return without calling `next` - e.g. a hard reload) or calls
+ * `next(input)`. The base returns `{ message: 'Something went wrong' }`.
+ *
+ * ```js
+ * // src/hooks.client.js
+ * import { stackHandleClientError, withStaleDeployReload } from './'
+ *
+ * export const handleError = stackHandleClientError(
+ *   withStaleDeployReload(),
+ *   (next) => (input) => {
+ *     report(input.error) // your logging
+ *     return next(input) // or return { message: 'Oops' } to stop here
+ *   },
+ * )
+ * ```
+ */
+export function stackHandleClientError(...middlewares) {
+    return middlewares.reduceRight((next, mw) => mw(next), () => ({ message: 'Something went wrong' }));
+}
+// Errors SvelteKit/Vite throw when a lazy chunk 404s after a deploy.
+const CHUNK_LOAD_RE = /Failed to fetch dynamically imported module|error loading dynamically imported module|Importing a module script failed/;
+const STORAGE_KEY = 'ff-reload';
+// A URL that failed again within this window is a genuine break, not a stale deploy.
+const RETRY_WINDOW_MS = 10_000;
+/**
+ * Middleware that recovers stale-deploy chunk failures: after a deploy an open client
+ * (esp. SPA builds) 404s on a lazy chunk. Trusts the failure signal itself, not
+ * `updated.check()` (which lies behind a CDN caching `version.json`), and hard-reloads
+ * once - a time-boxed one-shot guard prevents reload loops. Only chunk-load errors
+ * reload (a blind 404 reload would break client-side not-found routes); anything else
+ * falls through to `next`.
+ */
+export function withStaleDeployReload() {
+    return (next) => (input) => {
+        if (CHUNK_LOAD_RE.test(String(input.message)) && reloadOnce(input.event.url.href)) {
+            return; // page is unloading; no error surfaces
+        }
+        return next(input);
+    };
+}
+/** Hard-reload `href` unless it already failed within the guard window. Returns true if reloading. */
+function reloadOnce(href) {
+    try {
+        const prev = sessionStorage.getItem(STORAGE_KEY);
+        if (prev) {
+            const [prevHref, prevAt] = prev.split('\n');
+            if (prevHref === href && Date.now() - Number(prevAt) < RETRY_WINDOW_MS) {
+                sessionStorage.removeItem(STORAGE_KEY); // genuine break -> stop retrying
+                return false;
+            }
+        }
+        sessionStorage.setItem(STORAGE_KEY, `${href}\n${Date.now()}`);
+        location.assign(href); // bypasses SvelteKit's stale version check
+        return true;
+    }
+    catch {
+        return false; // no sessionStorage (private mode) -> don't risk a loop
+    }
+}

package/esm/svelte/index.d.ts

@@ -3,7 +3,9 @@ export { ff } from './ff.svelte.js';
 export type { FF_Many, FF_One, FF_Builder, FF_RepoOptions, FF_OneOptions, FF_RepoLoading, FF_Issue, ManyStrategy, AggregateOptions, QueryOptionsHelper, } from './ff.svelte.js';
 export { infiniteScroll } from './infiniteScroll.js';
 export type { InfiniteScrollOptions } from './infiniteScroll.js';
-export { dialog, ffAutofocus, resolveMessage } from './dialog.svelte.js';
+export { stackHandleClientError, withStaleDeployReload } from './handleError.js';
+export type { HandleClientErrorMiddleware } from './handleError.js';
+export { dialog, ffAutofocus, ffTrapFocus, resolveMessage } from './dialog.svelte.js';
 export type { DialogResult, DialogClose, DialogOptions, DialogItem, DialogRender, ConfirmItem, PromptItem, DialogShellArgs, DialogConfirmArgs, DialogPromptArgs, } from './dialog.svelte.js';
 export type { LocalizedMessage } from '../core/FF_Validators.js';
 export { default as FF_DialogManager } from './FF_DialogManager.svelte';

package/esm/svelte/index.js

@@ -1,7 +1,8 @@
 export { errorMessage, isError } from '../core/helper.js';
 export { ff } from './ff.svelte.js';
 export { infiniteScroll } from './infiniteScroll.js';
-export { dialog, ffAutofocus, resolveMessage } from './dialog.svelte.js';
+export { stackHandleClientError, withStaleDeployReload } from './handleError.js';
+export { dialog, ffAutofocus, ffTrapFocus, resolveMessage } from './dialog.svelte.js';
 export { default as FF_DialogManager } from './FF_DialogManager.svelte';
 export { default as FF_Config } from './FF_Config.svelte';
 export { ffConfig, setFFConfig } from './FF_Config.svelte.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firstly",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "type": "module",
   "description": "Firstly, an opinionated Remult setup!",
   "funding": "https://github.com/sponsors/jycouet",