@weirdscience/based-client 0.1.1 → 0.2.0

package/README.md

@@ -124,7 +124,40 @@ Methods on `client.auth`:
 - `signOut()` → invalidates the session
 - `refreshSession()` → manually refresh (happens automatically on 401)
 
-Access tokens auto-refresh on `401`. Sessions are stored in memory.
+Access tokens auto-refresh on `401`.
+
+## Session persistence
+
+Sessions persist across page reloads via `localStorage` by default. On mount, the client restores the saved session and validates it by calling `/auth/me`.
+
+Use `client.ready()` or `useUser().isLoading` to avoid flashing a logged-out UI during hydration:
+
+```tsx
+const { user, isLoading } = useUser();
+if (isLoading) return <Spinner />;
+if (!user) return <LoginForm />;
+return <Dashboard user={user} />;
+```
+
+Opt out or use a custom storage adapter:
+
+```tsx
+// Disable entirely (in-memory only)
+createClient({ url, anonKey, storage: false });
+
+// Custom storage (cookies, IndexedDB, React Native AsyncStorage, etc.)
+createClient({
+  url,
+  anonKey,
+  storage: {
+    getItem: (k) => AsyncStorage.getItem(k),
+    setItem: (k, v) => AsyncStorage.setItem(k, v),
+    removeItem: (k) => AsyncStorage.removeItem(k),
+  },
+});
+```
+
+Storage adapters can return promises — the client awaits them.
 
 ## Type safety
 

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAuB,WAAW,EAAE,MAAM,SAAS,CAAC;AAEpF,wBAAgB,YAAY,CAAC,OAAO,EAAE,kBAAkB,GAAG,WAAW,CAsJrE"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAGlB,WAAW,EAEZ,MAAM,SAAS,CAAC;AAqBjB,wBAAgB,YAAY,CAAC,OAAO,EAAE,kBAAkB,GAAG,WAAW,CAyPrE"}

package/dist/index.js

@@ -1,11 +1,27 @@
 // src/client.ts
+var DEFAULT_STORAGE_KEY = "based.session";
+function defaultStorage() {
+  if (typeof globalThis === "undefined")
+    return null;
+  const ls = globalThis.localStorage;
+  if (!ls || typeof ls.getItem !== "function")
+    return null;
+  return {
+    getItem: (k) => ls.getItem(k),
+    setItem: (k, v) => ls.setItem(k, v),
+    removeItem: (k) => ls.removeItem(k)
+  };
+}
 function createClient(options) {
   const { url, anonKey } = options;
   const baseUrl = url.replace(/\/$/, "");
+  const storage = options.storage === false ? null : options.storage ?? defaultStorage();
+  const storageKey = options.storageKey ?? DEFAULT_STORAGE_KEY;
   let state = {
     user: null,
     accessToken: null,
-    refreshToken: null
+    refreshToken: null,
+    isLoading: !!storage
   };
   const listeners = new Set;
   function notify() {
@@ -19,6 +35,66 @@ function createClient(options) {
   function getState() {
     return state;
   }
+  async function persist() {
+    if (!storage)
+      return;
+    const snapshot = {
+      user: state.user,
+      accessToken: state.accessToken,
+      refreshToken: state.refreshToken
+    };
+    if (!snapshot.refreshToken) {
+      await storage.removeItem(storageKey);
+      return;
+    }
+    await storage.setItem(storageKey, JSON.stringify(snapshot));
+  }
+  function setState(next) {
+    state = { ...state, ...next };
+    notify();
+    persist().catch(() => {});
+  }
+  const readyPromise = (async () => {
+    if (!storage) {
+      setState({ isLoading: false });
+      return;
+    }
+    try {
+      const raw = await storage.getItem(storageKey);
+      if (!raw) {
+        setState({ isLoading: false });
+        return;
+      }
+      const stored = JSON.parse(raw);
+      if (!stored.refreshToken) {
+        setState({ isLoading: false });
+        return;
+      }
+      state = {
+        user: stored.user,
+        accessToken: stored.accessToken,
+        refreshToken: stored.refreshToken,
+        isLoading: true
+      };
+      notify();
+      const user = await getUser();
+      if (!user) {
+        const refreshed = await refreshSession();
+        if (refreshed) {
+          await getUser();
+        }
+      }
+    } catch {
+      try {
+        await storage.removeItem(storageKey);
+      } catch {}
+    } finally {
+      setState({ isLoading: false });
+    }
+  })();
+  function ready() {
+    return readyPromise;
+  }
   async function fetchWithAuth(path, init = {}) {
     const headers = new Headers(init.headers);
     if (state.accessToken) {
@@ -46,16 +122,16 @@ function createClient(options) {
       body: JSON.stringify({ email, password })
     });
     if (!res.ok) {
-      const json = await res.json();
-      throw new Error(json.error?.message || "Sign up failed");
+      const json = await res.json().catch(() => null);
+      throw new Error(json?.error?.message || "Sign up failed");
     }
     const { data } = await res.json();
-    state = {
+    setState({
       user: data.user,
       accessToken: data.accessToken,
-      refreshToken: data.refreshToken
-    };
-    notify();
+      refreshToken: data.refreshToken,
+      isLoading: false
+    });
     return data.user;
   }
   async function signIn(email, password) {
@@ -65,16 +141,16 @@ function createClient(options) {
       body: JSON.stringify({ email, password })
     });
     if (!res.ok) {
-      const json = await res.json();
-      throw new Error(json.error?.message || "Sign in failed");
+      const json = await res.json().catch(() => null);
+      throw new Error(json?.error?.message || "Sign in failed");
     }
     const { data } = await res.json();
-    state = {
+    setState({
       user: data.user,
       accessToken: data.accessToken,
-      refreshToken: data.refreshToken
-    };
-    notify();
+      refreshToken: data.refreshToken,
+      isLoading: false
+    });
     return data.user;
   }
   async function signOut() {
@@ -86,8 +162,7 @@ function createClient(options) {
         });
       } catch {}
     }
-    state = { user: null, accessToken: null, refreshToken: null };
-    notify();
+    setState({ user: null, accessToken: null, refreshToken: null, isLoading: false });
   }
   async function refreshSession() {
     if (!state.refreshToken)
@@ -99,27 +174,46 @@ function createClient(options) {
         body: JSON.stringify({ refreshToken: state.refreshToken })
       });
       if (!res.ok) {
-        state = { user: null, accessToken: null, refreshToken: null };
-        notify();
+        setState({ user: null, accessToken: null, refreshToken: null, isLoading: false });
         return false;
       }
       const { data } = await res.json();
-      state = {
-        ...state,
+      setState({
         accessToken: data.accessToken,
         refreshToken: data.refreshToken
-      };
-      notify();
+      });
       return true;
     } catch {
       return false;
     }
   }
+  async function getUser() {
+    if (!state.accessToken)
+      return null;
+    try {
+      const res = await fetch(`${baseUrl}/auth/me`, {
+        headers: { Authorization: `Bearer ${state.accessToken}` }
+      });
+      if (!res.ok) {
+        if (res.status === 401) {
+          setState({ user: null });
+        }
+        return null;
+      }
+      const { data } = await res.json();
+      const user = { id: data.id, email: data.email };
+      setState({ user });
+      return user;
+    } catch {
+      return null;
+    }
+  }
   return {
-    auth: { signUp, signIn, signOut, refreshSession },
+    auth: { signUp, signIn, signOut, refreshSession, getUser },
     fetch: fetchWithAuth,
     subscribe,
-    getState
+    getState,
+    ready
   };
 }
 // src/provider.tsx
@@ -149,18 +243,18 @@ function useUser() {
   const state = useSyncExternalStore(client.subscribe, () => client.getState(), () => client.getState());
   return {
     user: state.user,
-    isLoading: false,
+    isLoading: state.isLoading,
     error: null
   };
 }
 // src/hooks/use-query.ts
-import { useState as useState2, useEffect as useEffect2, useCallback } from "react";
+import { useState, useEffect, useCallback } from "react";
 function useQuery(table, options) {
   const client = useBasedClient();
-  const [data, setData] = useState2(null);
-  const [total, setTotal] = useState2(0);
-  const [isLoading, setIsLoading] = useState2(true);
-  const [error, setError] = useState2(null);
+  const [data, setData] = useState(null);
+  const [total, setTotal] = useState(0);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState(null);
   const fetchData = useCallback(async () => {
     setIsLoading(true);
     setError(null);
@@ -196,17 +290,17 @@ function useQuery(table, options) {
       setIsLoading(false);
     }
   }, [client, table, JSON.stringify(options)]);
-  useEffect2(() => {
+  useEffect(() => {
     fetchData();
   }, [fetchData]);
   return { data, total, isLoading, error, refetch: fetchData };
 }
 // src/hooks/use-mutation.ts
-import { useState as useState3, useCallback as useCallback2 } from "react";
+import { useState as useState2, useCallback as useCallback2 } from "react";
 function useMutation(table, operation) {
   const client = useBasedClient();
-  const [isLoading, setIsLoading] = useState3(false);
-  const [error, setError] = useState3(null);
+  const [isLoading, setIsLoading] = useState2(false);
+  const [error, setError] = useState2(null);
   const mutate = useCallback2(async (data) => {
     setIsLoading(true);
     setError(null);

package/dist/types.d.ts

@@ -1,6 +1,20 @@
+export interface StorageAdapter {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem(key: string): void | Promise<void>;
+}
 export interface BasedClientOptions {
     url: string;
     anonKey: string;
+    /**
+     * Where to persist the session. Defaults to `localStorage` in browsers,
+     * in-memory elsewhere. Pass `false` to disable persistence entirely.
+     */
+    storage?: StorageAdapter | false;
+    /**
+     * Key used for storage. Defaults to `based.session`.
+     */
+    storageKey?: string;
 }
 export interface AuthUser {
     id: string;
@@ -10,6 +24,11 @@ export interface AuthState {
     user: AuthUser | null;
     accessToken: string | null;
     refreshToken: string | null;
+    /**
+     * True during the initial session rehydration. Use this to avoid flashing
+     * a "logged out" UI before the stored session has been validated.
+     */
+    isLoading: boolean;
 }
 export interface BasedClient {
     auth: {
@@ -17,10 +36,19 @@ export interface BasedClient {
         signIn(email: string, password: string): Promise<AuthUser>;
         signOut(): Promise<void>;
         refreshSession(): Promise<boolean>;
+        /**
+         * Returns the current authenticated user by calling `/auth/me`.
+         */
+        getUser(): Promise<AuthUser | null>;
     };
     fetch(path: string, init?: RequestInit): Promise<Response>;
     subscribe(listener: () => void): () => void;
     getState(): AuthState;
+    /**
+     * Resolves when the client finishes restoring a stored session (if any).
+     * Safe to await multiple times.
+     */
+    ready(): Promise<void>;
 }
 export interface QueryOptions<T = Record<string, unknown>> {
     filter?: Partial<Record<keyof T, string | number | boolean>>;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC;IACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE;QACJ,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC3D,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC3D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;QACzB,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;KACpC,CAAC;IACF,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC3D,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IAC5C,QAAQ,IAAI,SAAS,CAAC;CACvB;AAED,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACvD,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,OAAO;IACtC,IAAI,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAChD,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,OAAO;IACzC,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACnE,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACjD;AAID,MAAM,WAAW,aAAa;IAC5B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weirdscience/based-client",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "React SDK for Based — a minimal self-hosted BaaS",
   "license": "MIT",
   "repository": {