@gusnips/react 0.4.5 → 0.4.6

package/README.md

@@ -136,6 +136,22 @@ where there is no window. A session bootstrap can only be in flight in a browser
 during a build is a wait that never ends: it once shipped a spinner as the indexable body of a
 page whose whole job was to be found.
 
+When your store needs more than those flags, `authSlice` in the same place gives you them as a
+plain object to spread, so `create` stays yours — and with it `persist`, your own actions, and
+fields of your own:
+
+```ts
+const useAuthStore = create<AuthState<User> & { isAnonymous: boolean }>((set) => ({
+  ...authSlice<User, { isAnonymous: boolean }>(set, (user) => ({
+    isAnonymous: !!user?.isAnonymous,
+  })),
+}));
+```
+
+The second argument is what makes this more than spreading extra keys in yourself: a field read
+off the user has to be rewritten whenever the user changes, and `setUser` and `clear` are the two
+writes you no longer own.
+
 `hydrateOrMount` is at `@gusnips/react/hydrate`, and the guards are at `@gusnips/react/guards`.
 
 ## On a phone
@@ -169,13 +185,13 @@ something.
 `@gusnips/react` itself needs `react`, `react-dom` and nothing else. Anything that needs more
 lives behind a subpath, so you install a dependency only if you import the thing that uses it:
 
-| Import from               | What is in it       | What you must have |
-| ------------------------- | ------------------- | ------------------ |
-| `@gusnips/react`          | the client and rest | react, react-dom   |
-| `@gusnips/react/store`    | `createAuthStore`   | zustand            |
-| `@gusnips/react/guards`   | the route guards    | react-router-dom   |
-| `@gusnips/react/ui`       | the seven wrappers  | @base-ui/react     |
-| `@gusnips/react/contract` | two prerender names | nothing            |
+| Import from               | What is in it                  | What you must have |
+| ------------------------- | ------------------------------ | ------------------ |
+| `@gusnips/react`          | the client and rest            | react, react-dom   |
+| `@gusnips/react/store`    | `createAuthStore`, `authSlice` | zustand            |
+| `@gusnips/react/guards`   | the route guards               | react-router-dom   |
+| `@gusnips/react/ui`       | the seven wrappers             | @base-ui/react     |
+| `@gusnips/react/contract` | two prerender names            | nothing            |
 
 The rule behind that table: **a peer marked optional must not be reachable from the main entry
 point.** An optional peer the barrel imports anyway is not optional — it is a required one whose

package/dist/auth-store.d.ts

@@ -46,4 +46,35 @@ export interface AuthState<TUser> {
  * Only one of the three donors knew this. It is invariant 7.
  */
 export declare function createAuthStore<TUser>(): UseBoundStore<StoreApi<AuthState<TUser>>>;
+/**
+ * zustand's `set`, narrowed to the two writes this slice makes.
+ *
+ * Not `Partial<AuthState<TUser> & TExtra>`, which is what it means and what a caller passes:
+ * inside a generic function TypeScript cannot check `{ isLoading }` against a partial of an
+ * unresolved type parameter, because `TExtra` might yet declare an `isLoading` of its own. The
+ * union says the same thing in terms it can check at both ends. Any real store's setter
+ * satisfies it, where `TExtra` is a concrete type.
+ */
+type AuthSet<TUser, TExtra> = (partial: (TExtra & Partial<AuthState<TUser>>) | Pick<AuthState<TUser>, "isLoading">) => void;
+/**
+ * The session flags as a plain object, for a product whose store needs more than them.
+ *
+ * `createAuthStore` owns its `create()` call, which means it owns the whole store: a product
+ * cannot wrap it in `persist`, cannot add an action, and cannot add a field. Both adopters that
+ * met it had a superset and neither could use it. One holds a remember-me choice, a profile row
+ * and the sign-in methods themselves, under `persist`. The other adds `isAnonymous` — and that
+ * one is the reason this takes a `derive` function rather than just letting the caller spread
+ * extra keys in: `isAnonymous` is read off the user, so it has to be rewritten by `setUser` and
+ * `clear`, which are exactly the two writes the product does not own.
+ *
+ * The caller keeps `create`, so middleware, extra actions and the store's own name stay theirs:
+ *
+ * ```ts
+ * const useAuthStore = create<AuthState<User> & { isAnonymous: boolean }>((set) => ({
+ *   ...authSlice<User, { isAnonymous: boolean }>(set, (user) => ({ isAnonymous: !!user?.isAnonymous })),
+ * }));
+ * ```
+ */
+export declare function authSlice<TUser, TExtra extends object>(set: AuthSet<TUser, TExtra>, derive: (user: TUser | null) => TExtra): AuthState<TUser> & TExtra;
+export {};
 //# sourceMappingURL=auth-store.d.ts.map

package/dist/auth-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-store.d.ts","sourceRoot":"","sources":["../src/auth-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AAEpE;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,SAAS,CAAC,KAAK;IAC9B,IAAI,EAAE,KAAK,GAAG,IAAI,CAAC;IACnB,eAAe,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB;;;;;OAKG;IACH,OAAO,EAAE,CAAC,IAAI,EAAE,KAAK,GAAG,IAAI,KAAK,IAAI,CAAC;IACtC,UAAU,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI,CAAC;IACzC,yEAAyE;IACzE,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,KAAK,KAAK,aAAa,CAAC,QAAQ,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CASlF"}
+{"version":3,"file":"auth-store.d.ts","sourceRoot":"","sources":["../src/auth-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AAEpE;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,SAAS,CAAC,KAAK;IAC9B,IAAI,EAAE,KAAK,GAAG,IAAI,CAAC;IACnB,eAAe,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB;;;;;OAKG;IACH,OAAO,EAAE,CAAC,IAAI,EAAE,KAAK,GAAG,IAAI,KAAK,IAAI,CAAC;IACtC,UAAU,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI,CAAC;IACzC,yEAAyE;IACzE,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,KAAK,KAAK,aAAa,CAAC,QAAQ,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAElF;AAKD;;;;;;;;GAQG;AACH,KAAK,OAAO,CAAC,KAAK,EAAE,MAAM,IAAI,CAC5B,OAAO,EAAE,CAAC,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC,KAChF,IAAI,CAAC;AAEV;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,SAAS,MAAM,EACpD,GAAG,EAAE,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,EAC3B,MAAM,EAAE,CAAC,IAAI,EAAE,KAAK,GAAG,IAAI,KAAK,MAAM,GACrC,SAAS,CAAC,KAAK,CAAC,GAAG,MAAM,CAW3B"}

package/dist/auth-store.js

@@ -15,13 +15,36 @@ import { create } from "zustand";
  * Only one of the three donors knew this. It is invariant 7.
  */
 export function createAuthStore() {
-    return create((set) => ({
+    return create((set) => authSlice(set, () => ({})));
+}
+/**
+ * The session flags as a plain object, for a product whose store needs more than them.
+ *
+ * `createAuthStore` owns its `create()` call, which means it owns the whole store: a product
+ * cannot wrap it in `persist`, cannot add an action, and cannot add a field. Both adopters that
+ * met it had a superset and neither could use it. One holds a remember-me choice, a profile row
+ * and the sign-in methods themselves, under `persist`. The other adds `isAnonymous` — and that
+ * one is the reason this takes a `derive` function rather than just letting the caller spread
+ * extra keys in: `isAnonymous` is read off the user, so it has to be rewritten by `setUser` and
+ * `clear`, which are exactly the two writes the product does not own.
+ *
+ * The caller keeps `create`, so middleware, extra actions and the store's own name stay theirs:
+ *
+ * ```ts
+ * const useAuthStore = create<AuthState<User> & { isAnonymous: boolean }>((set) => ({
+ *   ...authSlice<User, { isAnonymous: boolean }>(set, (user) => ({ isAnonymous: !!user?.isAnonymous })),
+ * }));
+ * ```
+ */
+export function authSlice(set, derive) {
+    return {
+        ...derive(null),
         user: null,
         isAuthenticated: false,
         isLoading: typeof window !== "undefined",
-        setUser: (user) => set({ user, isAuthenticated: Boolean(user), isLoading: false }),
+        setUser: (user) => set({ ...derive(user), user, isAuthenticated: Boolean(user), isLoading: false }),
         setLoading: (isLoading) => set({ isLoading }),
-        clear: () => set({ user: null, isAuthenticated: false, isLoading: false }),
-    }));
+        clear: () => set({ ...derive(null), user: null, isAuthenticated: false, isLoading: false }),
+    };
 }
 //# sourceMappingURL=auth-store.js.map

package/dist/auth-store.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth-store.js","sourceRoot":"","sources":["../src/auth-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAqC,MAAM,SAAS,CAAC;AAkCpE;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,MAAM,CAAmB,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACxC,IAAI,EAAE,IAAI;QACV,eAAe,EAAE,KAAK;QACtB,SAAS,EAAE,OAAO,MAAM,KAAK,WAAW;QACxC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;QAClF,UAAU,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,CAAC;QAC7C,KAAK,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;KAC3E,CAAC,CAAC,CAAC;AACN,CAAC"}
+{"version":3,"file":"auth-store.js","sourceRoot":"","sources":["../src/auth-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAqC,MAAM,SAAS,CAAC;AAkCpE;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,MAAM,CAAmB,CAAC,GAAG,EAAE,EAAE,CAAC,SAAS,CAAoB,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAC1F,CAAC;AAkBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,SAAS,CACvB,GAA2B,EAC3B,MAAsC;IAEtC,OAAO;QACL,GAAG,MAAM,CAAC,IAAI,CAAC;QACf,IAAI,EAAE,IAAI;QACV,eAAe,EAAE,KAAK;QACtB,SAAS,EAAE,OAAO,MAAM,KAAK,WAAW;QACxC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAChB,GAAG,CAAC,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;QAClF,UAAU,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,CAAC;QAC7C,KAAK,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;KAC5F,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gusnips/react",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "The headless runtime under a Vite + React SPA: typed fetch client with single-flight refresh, auth store, query defaults, route guards, error boundary, chunk-reload recovery, i18n bootstrap.",
   "type": "module",
   "license": "MIT",

package/src/auth-store.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import { create } from "zustand";
+import { authSlice, createAuthStore, type AuthState } from "./auth-store.ts";
+
+interface User {
+  id: string;
+  email: string;
+  isAnonymous?: boolean;
+}
+
+describe("createAuthStore", () => {
+  it("ends the loading state when it learns who the user is", () => {
+    const store = createAuthStore<User>();
+
+    store.getState().setUser({ id: "1", email: "a@b.c" });
+
+    expect(store.getState().isAuthenticated).toBe(true);
+    expect(store.getState().isLoading).toBe(false);
+  });
+});
+
+/**
+ * The shape an adopter actually has: an anonymous flag read off the user, plus state and an
+ * action of its own. Both halves have to survive `setUser` and `clear`, which is the whole
+ * reason `authSlice` exists — a store built on `createAuthStore` could hold neither.
+ */
+type Extra = { isAnonymous: boolean };
+
+const useAuthStore = create<AuthState<User> & Extra & { restored: boolean; restore: () => void }>(
+  (set) => ({
+    ...authSlice<User, Extra>(set, (user) => ({ isAnonymous: Boolean(user?.isAnonymous) })),
+    restored: false,
+    restore: () => set({ restored: true }),
+  }),
+);
+
+describe("authSlice", () => {
+  it("keeps a derived field in step with the user it is read from", () => {
+    useAuthStore.getState().setUser({ id: "1", email: "a@b.c", isAnonymous: true });
+    expect(useAuthStore.getState().isAnonymous).toBe(true);
+
+    useAuthStore.getState().setUser({ id: "2", email: "d@e.f" });
+    expect(useAuthStore.getState().isAnonymous).toBe(false);
+
+    useAuthStore.getState().setUser({ id: "3", email: "g@h.i", isAnonymous: true });
+    // Signing out must not leave the flag behind: the next visitor is not anonymous, they are
+    // nobody, and a stale `true` here reads as "signed in anonymously" to every guard.
+    useAuthStore.getState().clear();
+    expect(useAuthStore.getState().isAnonymous).toBe(false);
+    expect(useAuthStore.getState().isAuthenticated).toBe(false);
+  });
+
+  it("leaves the product's own state alone", () => {
+    useAuthStore.getState().restore();
+    useAuthStore.getState().setUser({ id: "1", email: "a@b.c" });
+    useAuthStore.getState().clear();
+
+    expect(useAuthStore.getState().restored).toBe(true);
+  });
+});

package/src/auth-store.ts

@@ -48,12 +48,56 @@ export interface AuthState<TUser> {
  * Only one of the three donors knew this. It is invariant 7.
  */
 export function createAuthStore<TUser>(): UseBoundStore<StoreApi<AuthState<TUser>>> {
-  return create<AuthState<TUser>>((set) => ({
+  return create<AuthState<TUser>>((set) => authSlice<TUser, EmptyExtra>(set, () => ({})));
+}
+
+/** What `authSlice` derives when a product adds nothing of its own. */
+type EmptyExtra = Record<never, never>;
+
+/**
+ * zustand's `set`, narrowed to the two writes this slice makes.
+ *
+ * Not `Partial<AuthState<TUser> & TExtra>`, which is what it means and what a caller passes:
+ * inside a generic function TypeScript cannot check `{ isLoading }` against a partial of an
+ * unresolved type parameter, because `TExtra` might yet declare an `isLoading` of its own. The
+ * union says the same thing in terms it can check at both ends. Any real store's setter
+ * satisfies it, where `TExtra` is a concrete type.
+ */
+type AuthSet<TUser, TExtra> = (
+  partial: (TExtra & Partial<AuthState<TUser>>) | Pick<AuthState<TUser>, "isLoading">,
+) => void;
+
+/**
+ * The session flags as a plain object, for a product whose store needs more than them.
+ *
+ * `createAuthStore` owns its `create()` call, which means it owns the whole store: a product
+ * cannot wrap it in `persist`, cannot add an action, and cannot add a field. Both adopters that
+ * met it had a superset and neither could use it. One holds a remember-me choice, a profile row
+ * and the sign-in methods themselves, under `persist`. The other adds `isAnonymous` — and that
+ * one is the reason this takes a `derive` function rather than just letting the caller spread
+ * extra keys in: `isAnonymous` is read off the user, so it has to be rewritten by `setUser` and
+ * `clear`, which are exactly the two writes the product does not own.
+ *
+ * The caller keeps `create`, so middleware, extra actions and the store's own name stay theirs:
+ *
+ * ```ts
+ * const useAuthStore = create<AuthState<User> & { isAnonymous: boolean }>((set) => ({
+ *   ...authSlice<User, { isAnonymous: boolean }>(set, (user) => ({ isAnonymous: !!user?.isAnonymous })),
+ * }));
+ * ```
+ */
+export function authSlice<TUser, TExtra extends object>(
+  set: AuthSet<TUser, TExtra>,
+  derive: (user: TUser | null) => TExtra,
+): AuthState<TUser> & TExtra {
+  return {
+    ...derive(null),
     user: null,
     isAuthenticated: false,
     isLoading: typeof window !== "undefined",
-    setUser: (user) => set({ user, isAuthenticated: Boolean(user), isLoading: false }),
+    setUser: (user) =>
+      set({ ...derive(user), user, isAuthenticated: Boolean(user), isLoading: false }),
     setLoading: (isLoading) => set({ isLoading }),
-    clear: () => set({ user: null, isAuthenticated: false, isLoading: false }),
-  }));
+    clear: () => set({ ...derive(null), user: null, isAuthenticated: false, isLoading: false }),
+  };
 }