@lunora/client 1.0.0-alpha.18 → 1.0.0-alpha.181

package/README.md

@@ -34,7 +34,7 @@
 
 ---
 
-The framework-agnostic browser/edge SDK for Lunora. It runs RPC over HTTP and real-time deltas over a single multiplexed WebSocket, with optimistic updates, an offline mutation queue, and decorrelated-jitter reconnect built in. It is the lowest-level user-facing entry point that every framework adapter (React, Vue, Svelte, Solid) layers on top of.
+The framework-agnostic browser/edge SDK for Lunora. It runs RPC over HTTP and real-time deltas over a single multiplexed WebSocket, with optimistic updates, an offline mutation queue, and exponential-backoff-with-jitter reconnect built in. It is the lowest-level user-facing entry point that every framework adapter (React, Vue, Svelte, Solid) layers on top of.
 
 Part of the [Lunora](https://github.com/anolilab/lunora) framework — a type-safe, real-time backend on Cloudflare Workers + Durable Objects with a Vite-first DX.
 
@@ -63,8 +63,21 @@ const client = new LunoraClient({ url: "https://app.acme.test" });
 // One-shot query (HTTP, carries the D1 bookmark for read-your-writes).
 const messages = await client.query(api.messages.list, { room: "general" });
 
-// Mutation with an optimistic update applied to matching subscribers.
-await client.mutation(api.messages.send, { body: "hi" }, { optimistic: (current = []) => [...current, { body: "hi", pending: true }] });
+// Mutation with an optimistic update. `optimisticUpdate` names the query it
+// patches — a write and the queries it affects are different functions, and only
+// you know which. (The per-call `optimistic` shortcut patches the subscription
+// registered under the mutation's OWN reference and args, nothing else.)
+await client.mutation(
+    api.messages.send,
+    { room: "general", body: "hi" },
+    {
+        optimisticUpdate: (store, args) => {
+            const current = store.getQuery(api.messages.list, { room: args.room }) ?? [];
+
+            store.setQuery(api.messages.list, { room: args.room }, [...current, { body: args.body, pending: true }]);
+        },
+    },
+);
 
 // Live subscription over WS — returns an unsubscribe function.
 const unsubscribe = client.subscribe(api.messages.list, { room: "general" }, (next) => {

package/dist/auth/index.d.mts

@@ -1,20 +1,51 @@
-import { U as User, L as LunoraClient } from "../packem_shared/lunora-client.d-Dy4neKF6.mjs";
+import { U as User, L as LunoraClient } from "../packem_shared/lunora-client.d-gPd6tie1.mjs";
+import '@lunora/errors';
+import "../packem_shared/function-reference.d-Br_hsKje.mjs";
 import '@lunora/runtime';
+/**
+ * Every {@link AuthStatus}, as a value — the contract table in this module's
+ * header, and the `@lunora/client` docs table that restates it for consumers,
+ * are both asserted against this list (`auth-status-docs.test.ts`), so a new
+ * state cannot ship undocumented.
+ */
+declare const AUTH_STATUSES: readonly ["authenticated", "loading", "unauthenticated", "unreachable"];
+/**
+ * Resolved authentication state. See the contract table in this module's header
+ * — the states are not interchangeable, and `unreachable` is the one that exists
+ * only so "the server said no session" and "we could not ask" stop colliding.
+ */
+type AuthStatus = (typeof AUTH_STATUSES)[number];
+/**
+ * Whether a gate should render its authenticated branch.
+ *
+ * Both `authenticated` and `unreachable` qualify: the credential is held in
+ * either case, and only the identity round-trip differs.
+ */
+declare const isAuthenticatedStatus: (status: AuthStatus) => boolean;
+/** Whether a gate should render its loading branch — the first resolve only. */
+declare const isLoadingStatus: (status: AuthStatus) => boolean;
 interface IdentityStore {
-  /** Read the current resolved user, or `null` when signed out / not yet resolved. */
+  /** The current {@link AuthStatus} — what a gate branches on. */
+  getStatus: () => AuthStatus;
+  /**
+   * The last resolved user, or `null`. `null` does NOT mean signed out on its
+   * own: read `getStatus` for that. A user resolved before the endpoint
+   * went unreachable is retained, so the UI keeps rendering the identity it
+   * last knew instead of blanking.
+   */
   getUser: () => User | null;
   /**
-  * Subscribe to identity changes. `onChange` is called whenever the user or
-  * token changes. Returns an unsubscribe handle.
-  */
+   * Subscribe to identity changes. `onChange` is called whenever the user or
+   * the status changes. Returns an unsubscribe handle.
+   */
   subscribe: (onChange: () => void) => () => void;
 }
 /**
-* Return the per-client identity store, creating it on first access.
-*
-* The store is cached via a `WeakMap` so it is GC'd when the client is dropped,
-* and creation is idempotent — calling this multiple times with the same client
-* returns the same store, keeping the single-fetch / fan-out invariant.
-*/
+ * Return the per-client identity store, creating it on first access.
+ *
+ * The store is cached via a `WeakMap` so it is GC'd when the client is dropped,
+ * and creation is idempotent — calling this multiple times with the same client
+ * returns the same store, keeping the single-fetch / fan-out invariant.
+ */
 declare const getIdentityStore: (client: LunoraClient) => IdentityStore;
-export { type IdentityStore, getIdentityStore };
+export { AUTH_STATUSES, type AuthStatus, type IdentityStore, getIdentityStore, isAuthenticatedStatus, isLoadingStatus };

package/dist/auth/index.d.ts

@@ -1,20 +1,51 @@
-import { U as User, L as LunoraClient } from "../packem_shared/lunora-client.d-Dy4neKF6.js";
+import { U as User, L as LunoraClient } from "../packem_shared/lunora-client.d-CUpV_t_w.js";
+import '@lunora/errors';
+import "../packem_shared/function-reference.d-Br_hsKje.js";
 import '@lunora/runtime';
+/**
+ * Every {@link AuthStatus}, as a value — the contract table in this module's
+ * header, and the `@lunora/client` docs table that restates it for consumers,
+ * are both asserted against this list (`auth-status-docs.test.ts`), so a new
+ * state cannot ship undocumented.
+ */
+declare const AUTH_STATUSES: readonly ["authenticated", "loading", "unauthenticated", "unreachable"];
+/**
+ * Resolved authentication state. See the contract table in this module's header
+ * — the states are not interchangeable, and `unreachable` is the one that exists
+ * only so "the server said no session" and "we could not ask" stop colliding.
+ */
+type AuthStatus = (typeof AUTH_STATUSES)[number];
+/**
+ * Whether a gate should render its authenticated branch.
+ *
+ * Both `authenticated` and `unreachable` qualify: the credential is held in
+ * either case, and only the identity round-trip differs.
+ */
+declare const isAuthenticatedStatus: (status: AuthStatus) => boolean;
+/** Whether a gate should render its loading branch — the first resolve only. */
+declare const isLoadingStatus: (status: AuthStatus) => boolean;
 interface IdentityStore {
-  /** Read the current resolved user, or `null` when signed out / not yet resolved. */
+  /** The current {@link AuthStatus} — what a gate branches on. */
+  getStatus: () => AuthStatus;
+  /**
+   * The last resolved user, or `null`. `null` does NOT mean signed out on its
+   * own: read `getStatus` for that. A user resolved before the endpoint
+   * went unreachable is retained, so the UI keeps rendering the identity it
+   * last knew instead of blanking.
+   */
   getUser: () => User | null;
   /**
-  * Subscribe to identity changes. `onChange` is called whenever the user or
-  * token changes. Returns an unsubscribe handle.
-  */
+   * Subscribe to identity changes. `onChange` is called whenever the user or
+   * the status changes. Returns an unsubscribe handle.
+   */
   subscribe: (onChange: () => void) => () => void;
 }
 /**
-* Return the per-client identity store, creating it on first access.
-*
-* The store is cached via a `WeakMap` so it is GC'd when the client is dropped,
-* and creation is idempotent — calling this multiple times with the same client
-* returns the same store, keeping the single-fetch / fan-out invariant.
-*/
+ * Return the per-client identity store, creating it on first access.
+ *
+ * The store is cached via a `WeakMap` so it is GC'd when the client is dropped,
+ * and creation is idempotent — calling this multiple times with the same client
+ * returns the same store, keeping the single-fetch / fan-out invariant.
+ */
 declare const getIdentityStore: (client: LunoraClient) => IdentityStore;
-export { type IdentityStore, getIdentityStore };
+export { AUTH_STATUSES, type AuthStatus, type IdentityStore, getIdentityStore, isAuthenticatedStatus, isLoadingStatus };

package/dist/auth/index.mjs

@@ -1,60 +1 @@
-const stores = /* @__PURE__ */ new WeakMap();
-const createIdentityStore = (client) => {
-  const listeners = /* @__PURE__ */ new Set();
-  let user = null;
-  let started = false;
-  const notify = () => {
-    for (const listener of listeners) {
-      listener();
-    }
-  };
-  let generation = 0;
-  const setUser = (next) => {
-    if (user !== next) {
-      user = next;
-      notify();
-    }
-  };
-  const refresh = () => {
-    generation += 1;
-    const current = generation;
-    if (client.getAuthToken() === null) {
-      setUser(null);
-      return;
-    }
-    client.getCurrentUser().then((next) => {
-      if (current === generation) {
-        setUser(next);
-      }
-      return void 0;
-    }).catch(() => {
-      if (current === generation) {
-        setUser(null);
-      }
-    });
-  };
-  client.onAuthTokenChange(refresh);
-  return {
-    getUser: () => user,
-    subscribe: (onChange) => {
-      listeners.add(onChange);
-      if (!started) {
-        started = true;
-        refresh();
-      }
-      return () => {
-        listeners.delete(onChange);
-      };
-    }
-  };
-};
-const getIdentityStore = (client) => {
-  let store = stores.get(client);
-  if (!store) {
-    store = createIdentityStore(client);
-    stores.set(client, store);
-  }
-  return store;
-};
-
-export { getIdentityStore };
+const b=["authenticated","loading","unauthenticated","unreachable"],y=t=>t==="authenticated"||t==="unreachable",A=t=>t==="loading",f=new WeakMap,S=t=>{const n=new Set;let u=null,s="loading",c=!1,h=!1,a;const g=()=>{for(const e of n)e()};let i=0;const r=(e,o)=>{(s!==e||u!==o)&&(s=e,u=o,g())},l=(e=!1)=>{i+=1;const o=i;if(!e&&t.getAuthToken()===null&&h){r("unauthenticated",null);return}r(u===null?"loading":"authenticated",u),t.getCurrentUser().then(d=>{o===i&&(h=!0,r(d===null?"unauthenticated":"authenticated",d),d!==null&&a===`subj:${d.id}`&&(a=void 0))}).catch(()=>{a=void 0,o===i&&r("unreachable",u)})};return t.expectIdentityResolution(),t.onAuthTokenChange(()=>{l()}),t.onIdentityChange(()=>{if(!c||t.getAuthToken()!==null)return;const e=t.currentIdentity();e===null?r("unauthenticated",null):e!==a&&(a=e,l(!0))}),t.onConnectionStatus(e=>{e==="connected"&&s==="unreachable"&&l(!0)}),{getStatus:()=>s,getUser:()=>u,subscribe:e=>(n.add(e),c||(c=!0,l()),()=>{n.delete(e)})}},T=t=>{let n=f.get(t);return n||(n=S(t),f.set(t,n)),n};export{b as AUTH_STATUSES,T as getIdentityStore,y as isAuthenticatedStatus,A as isLoadingStatus};