@gadicc/loom 1.28.0 → 1.29.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,28 @@
1
+ import "../../../_dnt.polyfills.js";
2
+ /**
3
+ * Browser-side Better Auth helpers. This module imports nothing, so it adds no
4
+ * dependency and is safe to reach from a consumer's own client module. Read
5
+ * globals through `globalThis`: a bare `window` becomes a build shim that is
6
+ * always defined, and pulls Node polyfills into the browser bundle.
7
+ */
8
+ type PendingSessionState = {
9
+ isPending: boolean;
10
+ };
11
+ /**
12
+ * Wraps Better Auth's `useSession` so a session reports pending only until the
13
+ * page's first answer.
14
+ *
15
+ * Better Auth marks a session with no data as pending again for every refetch,
16
+ * which it runs on focus, on reconnect and on a cross-tab session change. For a
17
+ * signed-out visitor that turns each of those into a pending state, so views
18
+ * waiting for the first answer unmount and re-check identity, and anything
19
+ * keyed on the session runs again. After the first answer this keeps the last
20
+ * settled state, which for a pending refetch is always "no session", until the
21
+ * new answer arrives.
22
+ *
23
+ * Server renders never settle, so hydration still starts from the pending
24
+ * state the server rendered.
25
+ */
26
+ export declare function createSettledSessionHook<TState extends PendingSessionState>(useSession: () => TState): () => TState;
27
+ export {};
28
+ //# sourceMappingURL=client.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../../src/src/next/auth/client.ts"],"names":[],"mappings":"AAAA,OAAO,4BAA4B,CAAC;AAGpC;;;;;GAKG;AAEH,KAAK,mBAAmB,GAAG;IACzB,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,SAAS,mBAAmB,EACzE,UAAU,EAAE,MAAM,MAAM,GACvB,MAAM,MAAM,CAWd"}
@@ -0,0 +1,28 @@
1
+ "use client";
2
+ /**
3
+ * Wraps Better Auth's `useSession` so a session reports pending only until the
4
+ * page's first answer.
5
+ *
6
+ * Better Auth marks a session with no data as pending again for every refetch,
7
+ * which it runs on focus, on reconnect and on a cross-tab session change. For a
8
+ * signed-out visitor that turns each of those into a pending state, so views
9
+ * waiting for the first answer unmount and re-check identity, and anything
10
+ * keyed on the session runs again. After the first answer this keeps the last
11
+ * settled state, which for a pending refetch is always "no session", until the
12
+ * new answer arrives.
13
+ *
14
+ * Server renders never settle, so hydration still starts from the pending
15
+ * state the server rendered.
16
+ */
17
+ export function createSettledSessionHook(useSession) {
18
+ let settled = false;
19
+ return function useSettledSession() {
20
+ const session = useSession();
21
+ if (!session.isPending) {
22
+ if (typeof globalThis.document !== "undefined")
23
+ settled = true;
24
+ return session;
25
+ }
26
+ return settled ? { ...session, isPending: false } : session;
27
+ };
28
+ }
@@ -1,5 +1,6 @@
1
1
  type SessionQuery = {
2
2
  disableCookieCache?: boolean;
3
+ disableRefresh?: boolean;
3
4
  };
4
5
  type GetSessionArgs<THeaders> = {
5
6
  headers: THeaders;
@@ -20,9 +21,24 @@ export type CreateRequestAuthSessionReadersOptions<THeaders, TAuth extends Bette
20
21
  getHeaders: () => THeaders | Promise<THeaders>;
21
22
  profileEnvVar?: string;
22
23
  };
24
+ export type SessionReadOptions = {
25
+ disableCookieCache?: boolean;
26
+ /** Reads the session without extending it, for a check that only decides. */
27
+ disableRefresh?: boolean;
28
+ };
23
29
  export declare function createRequestAuthSessionReaders<THeaders, TAuth extends BetterAuthLike<THeaders, unknown>>(options: CreateRequestAuthSessionReadersOptions<THeaders, TAuth>): {
24
30
  getFreshSession: any;
25
31
  getSession: any;
32
+ /**
33
+ * Reads the session again on every call, unlike the cached readers above.
34
+ * An authorization boundary that re-checks after awaited work needs this:
35
+ * a cached read can still answer from before a revocation. Pass
36
+ * `disableRefresh` for a check that only decides, so deciding does not
37
+ * extend the session.
38
+ */
39
+ readSession: (readOptions?: SessionReadOptions) => Promise<InferAuthSession<TAuth, THeaders>>;
40
+ /** `readSession` with the cookie cache bypassed, and never cached. */
41
+ readFreshSession: (readOptions?: SessionReadOptions) => Promise<InferAuthSession<TAuth, THeaders>>;
26
42
  };
27
43
  export {};
28
44
  //# sourceMappingURL=server.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../../src/src/next/auth/server.ts"],"names":[],"mappings":"AAEA,KAAK,YAAY,GAAG;IAClB,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B,CAAC;AAEF,KAAK,cAAc,CAAC,QAAQ,IAAI;IAC9B,OAAO,EAAE,QAAQ,CAAC;IAClB,KAAK,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;CAClC,CAAC;AAEF,KAAK,cAAc,CAAC,QAAQ,EAAE,QAAQ,IAAI;IACxC,MAAM,EAAE;QACN,OAAO,EAAE,QAAQ,CAAC;KACnB,CAAC;IACF,GAAG,EAAE;QACH,UAAU,CAAC,IAAI,EAAE,cAAc,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;KACtE,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,gBAAgB,CAC1B,KAAK,SAAS,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,EAC/C,QAAQ,IACN,KAAK,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC;AAEtC,MAAM,MAAM,sCAAsC,CAChD,QAAQ,EACR,KAAK,SAAS,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,IAC7C;IACF,IAAI,EAAE,KAAK,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,UAAU,EAAE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC/C,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAMF,wBAAgB,+BAA+B,CAC7C,QAAQ,EACR,KAAK,SAAS,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,EAE/C,OAAO,EAAE,sCAAsC,CAAC,QAAQ,EAAE,KAAK,CAAC;;;EAoCjE"}
1
+ {"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../../src/src/next/auth/server.ts"],"names":[],"mappings":"AAEA,KAAK,YAAY,GAAG;IAClB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF,KAAK,cAAc,CAAC,QAAQ,IAAI;IAC9B,OAAO,EAAE,QAAQ,CAAC;IAClB,KAAK,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;CAClC,CAAC;AAEF,KAAK,cAAc,CAAC,QAAQ,EAAE,QAAQ,IAAI;IACxC,MAAM,EAAE;QACN,OAAO,EAAE,QAAQ,CAAC;KACnB,CAAC;IACF,GAAG,EAAE;QACH,UAAU,CAAC,IAAI,EAAE,cAAc,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;KACtE,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,gBAAgB,CAC1B,KAAK,SAAS,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,EAC/C,QAAQ,IACN,KAAK,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC;AAEtC,MAAM,MAAM,sCAAsC,CAChD,QAAQ,EACR,KAAK,SAAS,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,IAC7C;IACF,IAAI,EAAE,KAAK,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,UAAU,EAAE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC/C,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,6EAA6E;IAC7E,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF,wBAAgB,+BAA+B,CAC7C,QAAQ,EACR,KAAK,SAAS,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,EAE/C,OAAO,EAAE,sCAAsC,CAAC,QAAQ,EAAE,KAAK,CAAC;;;IAqC9D;;;;;;OAMG;gCAtCU,kBAAkB,KAC9B,OAAO,CAAC,gBAAgB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAuC3C,sEAAsE;qCACtC,kBAAkB;EAGrD"}
@@ -4,11 +4,13 @@ export function createRequestAuthSessionReaders(options) {
4
4
  async function readSession(readOptions = {}) {
5
5
  const startedAt = Date.now();
6
6
  const requestHeaders = await options.getHeaders();
7
+ const query = {
8
+ ...(readOptions.disableCookieCache ? { disableCookieCache: true } : {}),
9
+ ...(readOptions.disableRefresh ? { disableRefresh: true } : {}),
10
+ };
7
11
  const session = await options.auth.api.getSession({
8
12
  headers: requestHeaders,
9
- query: readOptions.disableCookieCache
10
- ? { disableCookieCache: true }
11
- : undefined,
13
+ query: Object.keys(query).length ? query : undefined,
12
14
  });
13
15
  if (options.env?.[profileEnvVar] === "1") {
14
16
  console.info(`[perf:authSession] disableCookieCache=${readOptions.disableCookieCache ? 1 : 0} total=${Date.now() - startedAt}ms`);
@@ -20,5 +22,15 @@ export function createRequestAuthSessionReaders(options) {
20
22
  return {
21
23
  getFreshSession,
22
24
  getSession,
25
+ /**
26
+ * Reads the session again on every call, unlike the cached readers above.
27
+ * An authorization boundary that re-checks after awaited work needs this:
28
+ * a cached read can still answer from before a revocation. Pass
29
+ * `disableRefresh` for a check that only decides, so deciding does not
30
+ * extend the session.
31
+ */
32
+ readSession,
33
+ /** `readSession` with the cookie cache bypassed, and never cached. */
34
+ readFreshSession: (readOptions = {}) => readSession({ ...readOptions, disableCookieCache: true }),
23
35
  };
24
36
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gadicc/loom",
3
- "version": "1.28.0",
3
+ "version": "1.29.0",
4
4
  "description": "Deno-first shared helpers for extracting common Next.js app code.",
5
5
  "homepage": "https://github.com/gadicc/loom#readme",
6
6
  "repository": {
@@ -55,6 +55,10 @@
55
55
  "import": "./esm/src/next/apiKeys/mod.js",
56
56
  "require": "./script/src/next/apiKeys/mod.js"
57
57
  },
58
+ "./src/next/auth/client.js": {
59
+ "import": "./esm/src/next/auth/client.js",
60
+ "require": "./script/src/next/auth/client.js"
61
+ },
58
62
  "./src/next/files/mod.js": {
59
63
  "import": "./esm/src/next/files/mod.js",
60
64
  "require": "./script/src/next/files/mod.js"
@@ -231,7 +235,7 @@
231
235
  },
232
236
  "scripts": {},
233
237
  "loom": {
234
- "gitCommit": "e381c057d5eb321d4982119984d98ec292d79c41"
238
+ "gitCommit": "3b37c6ad50a4faaf5ee2e48fa5669dcbdee9b36a"
235
239
  },
236
240
  "bin": {
237
241
  "loom": "script/bin/loom.js"
@@ -0,0 +1,28 @@
1
+ import "../../../_dnt.polyfills.js";
2
+ /**
3
+ * Browser-side Better Auth helpers. This module imports nothing, so it adds no
4
+ * dependency and is safe to reach from a consumer's own client module. Read
5
+ * globals through `globalThis`: a bare `window` becomes a build shim that is
6
+ * always defined, and pulls Node polyfills into the browser bundle.
7
+ */
8
+ type PendingSessionState = {
9
+ isPending: boolean;
10
+ };
11
+ /**
12
+ * Wraps Better Auth's `useSession` so a session reports pending only until the
13
+ * page's first answer.
14
+ *
15
+ * Better Auth marks a session with no data as pending again for every refetch,
16
+ * which it runs on focus, on reconnect and on a cross-tab session change. For a
17
+ * signed-out visitor that turns each of those into a pending state, so views
18
+ * waiting for the first answer unmount and re-check identity, and anything
19
+ * keyed on the session runs again. After the first answer this keeps the last
20
+ * settled state, which for a pending refetch is always "no session", until the
21
+ * new answer arrives.
22
+ *
23
+ * Server renders never settle, so hydration still starts from the pending
24
+ * state the server rendered.
25
+ */
26
+ export declare function createSettledSessionHook<TState extends PendingSessionState>(useSession: () => TState): () => TState;
27
+ export {};
28
+ //# sourceMappingURL=client.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../../src/src/next/auth/client.ts"],"names":[],"mappings":"AAAA,OAAO,4BAA4B,CAAC;AAGpC;;;;;GAKG;AAEH,KAAK,mBAAmB,GAAG;IACzB,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,SAAS,mBAAmB,EACzE,UAAU,EAAE,MAAM,MAAM,GACvB,MAAM,MAAM,CAWd"}
@@ -0,0 +1,32 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.createSettledSessionHook = createSettledSessionHook;
4
+ require("../../../_dnt.polyfills.js");
5
+ "use client";
6
+ /**
7
+ * Wraps Better Auth's `useSession` so a session reports pending only until the
8
+ * page's first answer.
9
+ *
10
+ * Better Auth marks a session with no data as pending again for every refetch,
11
+ * which it runs on focus, on reconnect and on a cross-tab session change. For a
12
+ * signed-out visitor that turns each of those into a pending state, so views
13
+ * waiting for the first answer unmount and re-check identity, and anything
14
+ * keyed on the session runs again. After the first answer this keeps the last
15
+ * settled state, which for a pending refetch is always "no session", until the
16
+ * new answer arrives.
17
+ *
18
+ * Server renders never settle, so hydration still starts from the pending
19
+ * state the server rendered.
20
+ */
21
+ function createSettledSessionHook(useSession) {
22
+ let settled = false;
23
+ return function useSettledSession() {
24
+ const session = useSession();
25
+ if (!session.isPending) {
26
+ if (typeof globalThis.document !== "undefined")
27
+ settled = true;
28
+ return session;
29
+ }
30
+ return settled ? { ...session, isPending: false } : session;
31
+ };
32
+ }
@@ -1,5 +1,6 @@
1
1
  type SessionQuery = {
2
2
  disableCookieCache?: boolean;
3
+ disableRefresh?: boolean;
3
4
  };
4
5
  type GetSessionArgs<THeaders> = {
5
6
  headers: THeaders;
@@ -20,9 +21,24 @@ export type CreateRequestAuthSessionReadersOptions<THeaders, TAuth extends Bette
20
21
  getHeaders: () => THeaders | Promise<THeaders>;
21
22
  profileEnvVar?: string;
22
23
  };
24
+ export type SessionReadOptions = {
25
+ disableCookieCache?: boolean;
26
+ /** Reads the session without extending it, for a check that only decides. */
27
+ disableRefresh?: boolean;
28
+ };
23
29
  export declare function createRequestAuthSessionReaders<THeaders, TAuth extends BetterAuthLike<THeaders, unknown>>(options: CreateRequestAuthSessionReadersOptions<THeaders, TAuth>): {
24
30
  getFreshSession: any;
25
31
  getSession: any;
32
+ /**
33
+ * Reads the session again on every call, unlike the cached readers above.
34
+ * An authorization boundary that re-checks after awaited work needs this:
35
+ * a cached read can still answer from before a revocation. Pass
36
+ * `disableRefresh` for a check that only decides, so deciding does not
37
+ * extend the session.
38
+ */
39
+ readSession: (readOptions?: SessionReadOptions) => Promise<InferAuthSession<TAuth, THeaders>>;
40
+ /** `readSession` with the cookie cache bypassed, and never cached. */
41
+ readFreshSession: (readOptions?: SessionReadOptions) => Promise<InferAuthSession<TAuth, THeaders>>;
26
42
  };
27
43
  export {};
28
44
  //# sourceMappingURL=server.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../../src/src/next/auth/server.ts"],"names":[],"mappings":"AAEA,KAAK,YAAY,GAAG;IAClB,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B,CAAC;AAEF,KAAK,cAAc,CAAC,QAAQ,IAAI;IAC9B,OAAO,EAAE,QAAQ,CAAC;IAClB,KAAK,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;CAClC,CAAC;AAEF,KAAK,cAAc,CAAC,QAAQ,EAAE,QAAQ,IAAI;IACxC,MAAM,EAAE;QACN,OAAO,EAAE,QAAQ,CAAC;KACnB,CAAC;IACF,GAAG,EAAE;QACH,UAAU,CAAC,IAAI,EAAE,cAAc,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;KACtE,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,gBAAgB,CAC1B,KAAK,SAAS,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,EAC/C,QAAQ,IACN,KAAK,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC;AAEtC,MAAM,MAAM,sCAAsC,CAChD,QAAQ,EACR,KAAK,SAAS,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,IAC7C;IACF,IAAI,EAAE,KAAK,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,UAAU,EAAE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC/C,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAMF,wBAAgB,+BAA+B,CAC7C,QAAQ,EACR,KAAK,SAAS,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,EAE/C,OAAO,EAAE,sCAAsC,CAAC,QAAQ,EAAE,KAAK,CAAC;;;EAoCjE"}
1
+ {"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../../src/src/next/auth/server.ts"],"names":[],"mappings":"AAEA,KAAK,YAAY,GAAG;IAClB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF,KAAK,cAAc,CAAC,QAAQ,IAAI;IAC9B,OAAO,EAAE,QAAQ,CAAC;IAClB,KAAK,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;CAClC,CAAC;AAEF,KAAK,cAAc,CAAC,QAAQ,EAAE,QAAQ,IAAI;IACxC,MAAM,EAAE;QACN,OAAO,EAAE,QAAQ,CAAC;KACnB,CAAC;IACF,GAAG,EAAE;QACH,UAAU,CAAC,IAAI,EAAE,cAAc,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;KACtE,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,gBAAgB,CAC1B,KAAK,SAAS,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,EAC/C,QAAQ,IACN,KAAK,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC;AAEtC,MAAM,MAAM,sCAAsC,CAChD,QAAQ,EACR,KAAK,SAAS,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,IAC7C;IACF,IAAI,EAAE,KAAK,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,UAAU,EAAE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC/C,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,6EAA6E;IAC7E,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF,wBAAgB,+BAA+B,CAC7C,QAAQ,EACR,KAAK,SAAS,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,EAE/C,OAAO,EAAE,sCAAsC,CAAC,QAAQ,EAAE,KAAK,CAAC;;;IAqC9D;;;;;;OAMG;gCAtCU,kBAAkB,KAC9B,OAAO,CAAC,gBAAgB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAuC3C,sEAAsE;qCACtC,kBAAkB;EAGrD"}
@@ -7,11 +7,13 @@ function createRequestAuthSessionReaders(options) {
7
7
  async function readSession(readOptions = {}) {
8
8
  const startedAt = Date.now();
9
9
  const requestHeaders = await options.getHeaders();
10
+ const query = {
11
+ ...(readOptions.disableCookieCache ? { disableCookieCache: true } : {}),
12
+ ...(readOptions.disableRefresh ? { disableRefresh: true } : {}),
13
+ };
10
14
  const session = await options.auth.api.getSession({
11
15
  headers: requestHeaders,
12
- query: readOptions.disableCookieCache
13
- ? { disableCookieCache: true }
14
- : undefined,
16
+ query: Object.keys(query).length ? query : undefined,
15
17
  });
16
18
  if (options.env?.[profileEnvVar] === "1") {
17
19
  console.info(`[perf:authSession] disableCookieCache=${readOptions.disableCookieCache ? 1 : 0} total=${Date.now() - startedAt}ms`);
@@ -23,5 +25,15 @@ function createRequestAuthSessionReaders(options) {
23
25
  return {
24
26
  getFreshSession,
25
27
  getSession,
28
+ /**
29
+ * Reads the session again on every call, unlike the cached readers above.
30
+ * An authorization boundary that re-checks after awaited work needs this:
31
+ * a cached read can still answer from before a revocation. Pass
32
+ * `disableRefresh` for a check that only decides, so deciding does not
33
+ * extend the session.
34
+ */
35
+ readSession,
36
+ /** `readSession` with the cookie cache bypassed, and never cached. */
37
+ readFreshSession: (readOptions = {}) => readSession({ ...readOptions, disableCookieCache: true }),
26
38
  };
27
39
  }
@@ -117,12 +117,45 @@ exported `GET` and `POST`.
117
117
 
118
118
  ## Request-scoped sessions
119
119
 
120
- `createRequestAuthSessionReaders` returns request-cached readers, so within one
121
- request `getFreshSession` reads the cookie once. That suits page and layout
122
- reads. An authorization boundary that must re-check after awaited work needs an
123
- uncached read; a cached one can answer from before a revocation. Keep such a
124
- reader app-owned, validate the session where you read it, and record
125
- `requestSessionReaders: "app-owned"` so the check expects it.
120
+ `createRequestAuthSessionReaders` returns four readers. `getSession` and
121
+ `getFreshSession` are request-cached, so within one request each reads the
122
+ cookie once, which suits page and layout reads. `readSession` and
123
+ `readFreshSession` read again on every call.
124
+
125
+ An authorization boundary that re-checks after awaited work needs an uncached
126
+ read: a cached one can still answer from before a revocation. Use
127
+ `readFreshSession` there, and pass `disableRefresh` for a check that only
128
+ decides, so deciding does not extend the session. Validate identity and expiry
129
+ where you read.
130
+
131
+ An app may still own that reader, for example when it takes explicit headers so
132
+ tests and scripts can call it outside a request. Record
133
+ `requestSessionReaders: "app-owned"` then, so the check expects it.
134
+
135
+ ## Browser session state
136
+
137
+ Better Auth marks a session with no data as pending again for every refetch, and
138
+ it refetches on focus, on reconnect and on a cross-tab change. For a signed-out
139
+ visitor each of those becomes a pending state, so views waiting for the first
140
+ answer unmount and re-check identity. Wrap the client's hook once:
141
+
142
+ ```ts
143
+ "use client";
144
+
145
+ import { createSettledSessionHook } from "@gadicc/loom/next/auth/client";
146
+
147
+ export const authClient = createAuthClient({/* app plugins */});
148
+ export const useSession = createSettledSessionHook(authClient.useSession);
149
+ ```
150
+
151
+ The wrapper reports pending only until the page's first answer, then keeps the
152
+ last settled state, which for a pending refetch is always "no session". Server
153
+ renders never settle it, so hydration still starts from the server's state.
154
+
155
+ That module imports nothing and reads globals through `globalThis`. A bare
156
+ `window` in package source becomes a build shim that is always defined, and
157
+ pulls Node polyfills into the browser bundle; `scripts/build_npm.ts` guards the
158
+ emitted browser entrypoints against both.
126
159
 
127
160
  ## Anonymous identity checks
128
161