@alxia/react-router 0.36.1 → 0.38.0

package/docs/troubleshooting.md

@@ -82,6 +82,10 @@ a loader, a message React Router or the browser prints, or an error from
 - [`TypeError: sessionCookies(): the … name "…" already carries a prefix. Pass the base name: the package adds __Host- (session) or __Secure- (challenge) when secure is true.`](#typeerror-sessioncookies-the--name--already-carries-a-prefix-pass-the-base-name-the-package-adds-__host--session-or-__secure--challenge-when-secure-is-true)
 - [`TypeError: sessionCookies(): challengeSeconds must be a positive integer; got ….`](#typeerror-sessioncookies-challengeseconds-must-be-a-positive-integer-got-)
 - [`TypeError: sessionCookies(): challengePath must start with "/" and hold no ";" or control character; got ….`](#typeerror-sessioncookies-challengepath-must-start-with--and-hold-no--or-control-character-got-)
+- [`TypeError: sessionCookies(): sameSite must be "lax", "strict" or "none"; got ….`](#typeerror-sessioncookies-samesite-must-be-lax-strict-or-none-got-)
+- [`TypeError: sessionCookies(): sameSite "none" needs secure: true, since a browser drops a SameSite=None cookie without Secure.`](#typeerror-sessioncookies-samesite-none-needs-secure-true-since-a-browser-drops-a-samesitenone-cookie-without-secure)
+- [`TypeError: signedSession(): secret must be a string of at least 32 characters.`](#typeerror-signedsession-secret-must-be-a-string-of-at-least-32-characters)
+- [`TypeError: signedSession(): the name "…" must be an RFC 6265 token without a __Host- or __Secure- prefix; …` or `maxAge must be a positive integer of seconds; got ….`](#typeerror-signedsession-the-name--must-be-an-rfc-6265-token-without-a-__host--or-__secure--prefix--or-maxage-must-be-a-positive-integer-of-seconds-got-)
 - [`TypeError: signInFlow(): paths.… must be a path of this site with no query or fragment, starting with a single "/"; got ….`](#typeerror-signinflow-paths-must-be-a-path-of-this-site-with-no-query-or-fragment-starting-with-a-single--got-)
 - [`TypeError: signInPath(): options.path must be a path of this site with no query or fragment, starting with a single "/"; got ….`](#typeerror-signinpath-optionspath-must-be-a-path-of-this-site-with-no-query-or-fragment-starting-with-a-single--got-)
 - [`TypeError: signInFlow(): json must come from jsonActions(), which carries the site check every step runs; this object has none (a hand-made double?). Pass the app's jsonActions({ origin }) instance, or a spread copy of it.`](#typeerror-signinflow-json-must-come-from-jsonactions-which-carries-the-site-check-every-step-runs-this-object-has-none-a-hand-made-double-pass-the-apps-jsonactions-origin--instance-or-a-spread-copy-of-it)
@@ -627,6 +631,25 @@ export async function loader({ request }: Route.LoaderArgs) {
 
 The rows stay, `error` is `true`, and `loadMore` retries.
 
+### `useFetcherPromise: a newer call replaced this one before the fetcher answered` (or `… the component unmounted before the fetcher answered`)
+
+**When:** the Promise `run(submit)` returned rejects with a `FetcherPromiseAborted` instead of the action's answer.
+
+**Why:** `'superseded'`: `run` was called again while the first call was still waiting (a double click), so only the newer call gets the answer. `'unmounted'`: the component left before the fetcher answered.
+
+**Fix:** disable the control while the Promise is pending, and tell the two cases from a refusal by the class:
+
+```ts
+import { FetcherPromiseAborted } from '@alxia/react-router/fetcher';
+
+try {
+	await run(() => post({ intent: 'delete', id }));
+} catch (error) {
+	if (error instanceof FetcherPromiseAborted) return;
+	setError((error as Error).message); // the refusal's message
+}
+```
+
 ### A debounced load lands on the route's `ErrorBoundary`
 
 **When:** the resource route behind `useDebouncedFetcher` throws (or throws a `Response`) and the whole page is replaced by its `ErrorBoundary` instead of showing the previous suggestions with a retry.
@@ -1822,6 +1845,42 @@ TypeError: sessionCookies(): challengePath must start with "/" and hold no ";" o
 
 **Fix:** pass the path of the sign-in pages with its leading slash. The default is `'/sign-in'`, which covers `/sign-in` and the pages under it; not `/sign-in/code` alone, since a client navigation fetches `/sign-in/code.data`, which that path would not match.
 
+### `TypeError: sessionCookies(): sameSite must be "lax", "strict" or "none"; got ….`
+
+```
+TypeError: sessionCookies(): sameSite must be "lax", "strict" or "none"; got "sometimes".
+```
+
+**When:** the module that calls `sessionCookies`, `signedSession` or `serializeCookie` is imported (the message starts with that function's name).
+
+**Why:** `sameSite` is one of the three values, in lower case.
+
+**Fix:** pass `'lax'` (the default), `'strict'` or `'none'`.
+
+### `TypeError: sessionCookies(): sameSite "none" needs secure: true, since a browser drops a SameSite=None cookie without Secure.`
+
+**When:** `sameSite: 'none'` with `secure: false` (development over plain HTTP).
+
+**Why:** a browser drops a `SameSite=None` cookie that is not `Secure`.
+
+**Fix:** use `'lax'` or `'strict'` in development, for example `sameSite: import.meta.env.DEV ? 'lax' : 'none'`.
+
+### `TypeError: signedSession(): secret must be a string of at least 32 characters.`
+
+**When:** the module that calls `signedSession` is imported, often because the secret's environment variable is unset and `?? ''` gave an empty string.
+
+**Why:** an HMAC key shorter than 32 characters is guessable.
+
+**Fix:** set the variable to a random value of 32 characters or more (`openssl rand -base64 32`). Changing it later signs every operator out.
+
+### `TypeError: signedSession(): the name "…" must be an RFC 6265 token without a __Host- or __Secure- prefix; …` or `maxAge must be a positive integer of seconds; got ….`
+
+**When:** the module that calls `signedSession` is imported.
+
+**Why:** the name is not a cookie name or already carries a prefix (the package adds `__Host-` when `secure`), or `maxAge` is not a positive whole number of seconds.
+
+**Fix:** pass a base name such as `'my-app_operator'` and `maxAge: 8 * 60 * 60`.
+
 ### `TypeError: signInFlow(): paths.… must be a path of this site with no query or fragment, starting with a single "/"; got ….`
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@alxia/react-router",
-	"version": "0.36.1",
+	"version": "0.38.0",
 	"description": "alxia as the server of a React Router framework app: server rendering behind the app's hooks, loaders reading its typed context, the client's assets served; the code with no UI an installable app shares (`/pwa`), its hooks (`/pwa/react`), `noCache` for the worker's script (`/pwa/server`), the service worker on Workbox (`/pwa/worker`) and its build (`/pwa/build`), an API's refusals worded for the page (`/errors`), the BFF session: cookies, sign-in, step-up and mail links (`/session`), its page hooks (`/session/react`) and what it shares with the page (`/session/model`), a GraphQL subscription relayed to the browser over SSE (`/subscription`), the page's CSP nonce and inline boot scripts (`/document`) and a streaming `entry.server` (`/entry`)",
 	"license": "MIT",
 	"type": "module",