firstly 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # firstly
 
+## 0.9.0
+
+### Minor Changes
+
+- [#341](https://github.com/jycouet/firstly/pull/341) [`ea9b4b6`](https://github.com/jycouet/firstly/commit/ea9b4b67544dc755374b3178c22082dac986472e) Thanks [@jycouet](https://github.com/jycouet)! - svelte: added `repoFetch(fetch)` and `loadRepo(loadFn)` - bind a repo to a load's `event.fetch` so API rules apply on SSR, hydration reuses the SSR response (one query), and parallel `+layout.ts`/`+page.ts` loads can't leak into each other. Removed `remultApiUniversalLoad`, `remultApiServerLoad`, `withRemultFetch`; migrate to `loadRepo` (works for universal AND server loads) or the `repoFetch(event.fetch)` primitive.
+
+## 0.8.1
+
+### Patch Changes
+
+- [#335](https://github.com/jycouet/firstly/pull/335) [`c551a73`](https://github.com/jycouet/firstly/commit/c551a730969252e89b0a1d1a59a54580a380237b) Thanks [@jycouet](https://github.com/jycouet)! - Add `handleCaching` (`firstly/svelte/server`): a `hooks.server.js` handle setting deploy-safe `Cache-Control` headers - immutable for `/_app/immutable/*` 200s, no-store for HTML/API and all non-200s (a cached 404 chunk would brick the client until "disable cache").
+
 ## 0.8.0
 
 ### Minor Changes

package/esm/svelte/index.d.ts

@@ -18,7 +18,7 @@ export { default as FF_ToastManager } from './FF_ToastManager.svelte';
 export { SP } from './class/SP.svelte';
 export type { ParamDefinition } from './class/SP.svelte';
 export { initRemultSvelteReactivity } from './initRemultSvelteReactivity';
-export { remultApiUniversalLoad } from './remultApiLoad.js';
+export { loadRepo, repoFetch, type Repo } from './remultApiLoad.js';
 export { FF_Cell, FF_CellValue, FF_Grid, GroupFields, DefaultInput, buildCells, displayCell, resolveCellComponent, getFieldMetaType, getInputType, getStyle, getCellElementConfig, defaultConfig, } from './grid/index.js';
 export type { Cell, CellInput, CellComponent, CellUI, MetaKind, CellConfig, CellElementConfig, CellProps, CellContentProps, CellElementProps, CellMode, HubConfig, ActionConfig, } from './grid/index.js';
 export { default as Icon } from './ui/Icon.svelte';

package/esm/svelte/index.js

@@ -10,7 +10,7 @@ export { toast } from './toast.js';
 export { default as FF_ToastManager } from './FF_ToastManager.svelte';
 export { SP } from './class/SP.svelte';
 export { initRemultSvelteReactivity } from './initRemultSvelteReactivity';
-export { remultApiUniversalLoad } from './remultApiLoad.js';
+export { loadRepo, repoFetch } from './remultApiLoad.js';
 // Headless cell primitives (FF_Grid / FF_Group are boutique-only — copy from src/boutique/grid).
 export { FF_Cell, FF_CellValue, FF_Grid, GroupFields, DefaultInput, buildCells, displayCell, resolveCellComponent, getFieldMetaType, getInputType, getStyle, getCellElementConfig, defaultConfig, } from './grid/index.js';
 export { default as Icon } from './ui/Icon.svelte';

package/esm/svelte/remultApiLoad.d.ts

@@ -1,25 +1,41 @@
-import type { LoadEvent } from '@sveltejs/kit';
+import type { LoadEvent, ServerLoadEvent } from '@sveltejs/kit';
+import { repo as globalRepo } from 'remult';
+export type Repo = typeof globalRepo;
 /**
- * Run `body` in a scoped `withRemult` whose reads go through the API via `fetch`
- * (`allowApiRead` / `apiPrefilter` apply); a concurrent load keeps its own
- * provider. `remult.user` is carried in so the body can read it.
+ * A `repo` whose data access goes through the API via the given fetch:
+ * API rules apply on SSR (as the current user), hydration replays the SSR
+ * responses in the browser (one single query), nothing global is mutated
+ * (safe when `+layout.ts` and `+page.ts` run in parallel), and the ambient
+ * remult (user, context) stays in charge. Inherits `remult.apiClient` config.
+ *
+ * Name the result so the intent shows at every query:
+ * ```ts
+ * const repoClient = repoFetch(event.fetch)
+ * await repoClient(Task).find()
+ * ```
  *
  * TODO(remult): framework-agnostic (only needs a fetch) - candidate to live in
  * remult directly.
  */
-export declare function withRemultFetch<T>(fetch: typeof globalThis.fetch, body: () => Promise<T>): Promise<T>;
+export declare function repoFetch(fetch: typeof globalThis.fetch, options?: {
+    url?: string;
+}): Repo;
 /**
- * Wrap a SvelteKit UNIVERSAL load (`+page.ts` / `+layout.ts`) so plain global
- * `repo()` / `ff()` reads through the API (so `allowApiRead` / `apiPrefilter`
- * apply), on both SSR and CSR.
+ * Wrap a load: the callback receives a repo bound to `event.fetch`, then the event.
+ * Works for universal (`+page.ts`) AND server (`+page.server.ts`) loads.
+ *
+ * ```ts
+ * export const load = loadRepo(async (repoClient, { params }) => ({
+ * 	task: await repoClient(Task).findFirst({ id: params.id }),
+ * })) satisfies PageLoad // or PageServerLoad
+ * ```
  *
- * - SSR: runs the body in a scoped `withRemult` bound to `event.fetch` - gated,
- *   and a concurrent `+page.server.ts` keeps its own provider. SvelteKit inlines
- *   the response.
- * - CSR / hydration: points the client `remult` at this page's `event.fetch` so the
- *   inlined SSR response is reused, then runs the body.
+ * For server-only event members (`cookies`, `locals`, ...) annotate the event:
+ * `loadRepo(async (repoClient, event: ServerLoadEvent) => ...)`.
  *
- * (A universal load runs on the client too, so it must use `event.fetch`. For a
- * server-only load see `remultApiServerLoad` from `firstly/svelte/server`.)
+ * TODO(remult): candidate to live in remult - only the event default is
+ * SvelteKit-specific, the constraint itself is structural (`{ fetch }`).
  */
-export declare function remultApiUniversalLoad<T>(body: (event: LoadEvent) => Promise<T>): (event: LoadEvent) => Promise<T>;
+export declare function loadRepo<R, Ev extends {
+    fetch: typeof globalThis.fetch;
+} = LoadEvent | ServerLoadEvent>(loadFn: (repoClient: Repo, event: Ev) => R): (event: Ev) => R;

package/esm/svelte/remultApiLoad.js

@@ -1,39 +1,44 @@
-import { isBackend, remult, RestDataProvider, withRemult } from 'remult';
+import { repo as globalRepo, remult, RestDataProvider } from 'remult';
 /**
- * Run `body` in a scoped `withRemult` whose reads go through the API via `fetch`
- * (`allowApiRead` / `apiPrefilter` apply); a concurrent load keeps its own
- * provider. `remult.user` is carried in so the body can read it.
+ * A `repo` whose data access goes through the API via the given fetch:
+ * API rules apply on SSR (as the current user), hydration replays the SSR
+ * responses in the browser (one single query), nothing global is mutated
+ * (safe when `+layout.ts` and `+page.ts` run in parallel), and the ambient
+ * remult (user, context) stays in charge. Inherits `remult.apiClient` config.
+ *
+ * Name the result so the intent shows at every query:
+ * ```ts
+ * const repoClient = repoFetch(event.fetch)
+ * await repoClient(Task).find()
+ * ```
  *
  * TODO(remult): framework-agnostic (only needs a fetch) - candidate to live in
  * remult directly.
  */
-export function withRemultFetch(fetch, body) {
-    const user = remult.user;
-    return withRemult(async () => {
-        remult.user = user;
-        return body();
-    }, { dataProvider: new RestDataProvider(() => ({ httpClient: fetch })) });
+export function repoFetch(fetch, options) {
+    const dp = new RestDataProvider(() => ({
+        ...remult.apiClient,
+        httpClient: fetch,
+        ...(options?.url ? { url: options.url } : {}),
+    }));
+    return (entity, dataProvider) => globalRepo(entity, dataProvider ?? dp);
 }
 /**
- * Wrap a SvelteKit UNIVERSAL load (`+page.ts` / `+layout.ts`) so plain global
- * `repo()` / `ff()` reads through the API (so `allowApiRead` / `apiPrefilter`
- * apply), on both SSR and CSR.
+ * Wrap a load: the callback receives a repo bound to `event.fetch`, then the event.
+ * Works for universal (`+page.ts`) AND server (`+page.server.ts`) loads.
+ *
+ * ```ts
+ * export const load = loadRepo(async (repoClient, { params }) => ({
+ * 	task: await repoClient(Task).findFirst({ id: params.id }),
+ * })) satisfies PageLoad // or PageServerLoad
+ * ```
  *
- * - SSR: runs the body in a scoped `withRemult` bound to `event.fetch` - gated,
- *   and a concurrent `+page.server.ts` keeps its own provider. SvelteKit inlines
- *   the response.
- * - CSR / hydration: points the client `remult` at this page's `event.fetch` so the
- *   inlined SSR response is reused, then runs the body.
+ * For server-only event members (`cookies`, `locals`, ...) annotate the event:
+ * `loadRepo(async (repoClient, event: ServerLoadEvent) => ...)`.
  *
- * (A universal load runs on the client too, so it must use `event.fetch`. For a
- * server-only load see `remultApiServerLoad` from `firstly/svelte/server`.)
+ * TODO(remult): candidate to live in remult - only the event default is
+ * SvelteKit-specific, the constraint itself is structural (`{ fetch }`).
  */
-export function remultApiUniversalLoad(body) {
-    return (event) => {
-        if (!isBackend()) {
-            remult.apiClient.httpClient = event.fetch;
-            return body(event);
-        }
-        return withRemultFetch(event.fetch, () => body(event));
-    };
+export function loadRepo(loadFn) {
+    return (event) => loadFn(repoFetch(event.fetch), event);
 }

package/esm/svelte/server/handleCaching.d.ts

@@ -0,0 +1,24 @@
+import type { Handle } from '@sveltejs/kit';
+/**
+ * `hooks.server.js` handle that sets `Cache-Control` so browsers and CDNs cache
+ * correctly across deploys - the server-side twin of `withStaleDeployReload`.
+ *
+ * - `/_app/immutable/*` (200 only) → `public, max-age=31536000, immutable`.
+ *   Only this subtree is content-hashed; `/_app/version.json` and `/_app/env.js`
+ *   are not, and MUST stay revalidatable or clients never see a new deploy.
+ * - Everything else non-asset (HTML, API) and every non-200 → `no-cache, no-store,
+ *   must-revalidate`. Never let a 404 carry a long max-age: a chunk 404 during a
+ *   deploy window cached for a year bricks that client until devtools "disable cache".
+ * - Other static assets (200, by extension) are left untouched for you to tune.
+ *
+ * Replaces purge-everything-on-deploy CDN strategies.
+ *
+ * ```js
+ * // src/hooks.server.js
+ * import { sequence } from '@sveltejs/kit/hooks'
+ * import { handleCaching } from './'
+ *
+ * export const handle = sequence(handleCaching, ...rest)
+ * ```
+ */
+export declare const handleCaching: Handle;

package/esm/svelte/server/handleCaching.js

@@ -0,0 +1,35 @@
+// Cacheable static assets by extension (used to skip the no-cache header).
+const STATIC_ASSET_RE = /\.(js|css|ico|png|jpg|jpeg|gif|svg|webp|avif|woff2?|ttf|eot)$/;
+/**
+ * `hooks.server.js` handle that sets `Cache-Control` so browsers and CDNs cache
+ * correctly across deploys - the server-side twin of `withStaleDeployReload`.
+ *
+ * - `/_app/immutable/*` (200 only) → `public, max-age=31536000, immutable`.
+ *   Only this subtree is content-hashed; `/_app/version.json` and `/_app/env.js`
+ *   are not, and MUST stay revalidatable or clients never see a new deploy.
+ * - Everything else non-asset (HTML, API) and every non-200 → `no-cache, no-store,
+ *   must-revalidate`. Never let a 404 carry a long max-age: a chunk 404 during a
+ *   deploy window cached for a year bricks that client until devtools "disable cache".
+ * - Other static assets (200, by extension) are left untouched for you to tune.
+ *
+ * Replaces purge-everything-on-deploy CDN strategies.
+ *
+ * ```js
+ * // src/hooks.server.js
+ * import { sequence } from '@sveltejs/kit/hooks'
+ * import { handleCaching } from './'
+ *
+ * export const handle = sequence(handleCaching, ...rest)
+ * ```
+ */
+export const handleCaching = async ({ event, resolve }) => {
+    const response = await resolve(event);
+    const { pathname } = event.url;
+    if (pathname.startsWith('/_app/immutable/') && response.status === 200) {
+        response.headers.set('Cache-Control', 'public, max-age=31536000, immutable');
+    }
+    else if (response.status !== 200 || !STATIC_ASSET_RE.test(pathname)) {
+        response.headers.set('Cache-Control', 'no-cache, no-store, must-revalidate');
+    }
+    return response;
+};

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

@@ -1,13 +1 @@
-import type { ServerLoadEvent } from '@sveltejs/kit';
-/**
- * Wrap a SvelteKit SERVER load (`+page.server.ts`) so plain global `repo()` reads
- * apply the API gate (as the current user) instead of the privileged DB provider.
- *
- * Reads go through `event.fetch`: SvelteKit dispatches same-origin server fetch
- * in-process (no network) and forwards cookies, so the app's real auth/hooks run
- * for each read. Use it only when a server load should see exactly what the API
- * exposes; otherwise a server load keeps the DB provider (gate rows with
- * `backendPrefilter`). Gates direct `repo()` reads; BackendMethods keep their own
- * `allowed` gate.
- */
-export declare function remultApiServerLoad<T>(body: (event: ServerLoadEvent) => Promise<T>): (event: ServerLoadEvent) => Promise<T>;
+export { handleCaching } from './handleCaching.js';

package/esm/svelte/server/index.js

@@ -1,15 +1 @@
-import { withRemultFetch } from '../remultApiLoad.js';
-/**
- * Wrap a SvelteKit SERVER load (`+page.server.ts`) so plain global `repo()` reads
- * apply the API gate (as the current user) instead of the privileged DB provider.
- *
- * Reads go through `event.fetch`: SvelteKit dispatches same-origin server fetch
- * in-process (no network) and forwards cookies, so the app's real auth/hooks run
- * for each read. Use it only when a server load should see exactly what the API
- * exposes; otherwise a server load keeps the DB provider (gate rows with
- * `backendPrefilter`). Gates direct `repo()` reads; BackendMethods keep their own
- * `allowed` gate.
- */
-export function remultApiServerLoad(body) {
-    return (event) => withRemultFetch(event.fetch, () => body(event));
-}
+export { handleCaching } from './handleCaching.js';

package/package.json

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