@pylo/react 0.10.1 → 0.11.0

package/dist/{chunk-FKUNSR3E.js → chunk-C3KAJKBM.js}

@@ -1,14 +1,131 @@
 import {
+  usePyloRealtime,
   usePyloTransport
-} from "./chunk-BPRHGSZF.js";
+} from "./chunk-OPMVPQER.js";
+
+// src/hooks.ts
+import { useCallback, useEffect, useRef, useState } from "react";
+
+// src/live.ts
+var IMMUTABLE_SORT_FIELDS = /* @__PURE__ */ new Set(["id", "integer_id", "created_at"]);
+function applyRowEvent(row, event) {
+  if (event.removed) return { data: null, refetch: false };
+  return { data: { ...row, ...event.data }, refetch: false };
+}
+function applyListEvent(list, event, sortby, placement) {
+  const result = applyPagesEvent({ pages: [list], pageParams: [1] }, event, sortby, placement);
+  return { data: result.data.pages[0], refetch: result.refetch };
+}
+function applyPagesEvent(data, event, sortby, placement = { firstPage: true, keepOverflow: true }) {
+  const pageIndex = data.pages.findIndex((page) => page.data.some((row) => row.id === event.id));
+  if (event.removed) {
+    if (pageIndex === -1) return { data, refetch: false };
+    return {
+      data: updatePage(
+        data,
+        pageIndex,
+        (page) => adjustTotal({ ...page, data: page.data.filter((row) => row.id !== event.id) }, pageIndex, -1)
+      ),
+      refetch: "later"
+    };
+  }
+  const incoming = event.data;
+  if (pageIndex !== -1) {
+    const page = data.pages[pageIndex];
+    const current = page.data.find((row) => row.id === event.id);
+    const merged = { ...current, ...incoming };
+    const sort = sortChange(current, merged, sortby);
+    if (sort === "changed") return { data, refetch: "soon" };
+    return {
+      data: updatePage(data, pageIndex, (p) => ({
+        ...p,
+        data: p.data.map((row) => row.id === event.id ? merged : row)
+      })),
+      refetch: sort === "unknown" ? "later" : false
+    };
+  }
+  if (event.kind === "create" && isNewestFirst(sortby) && data.pages.length > 0) {
+    if (!placement.firstPage) return { data, refetch: "later" };
+    const inserted = updatePage(
+      data,
+      0,
+      (page2) => adjustTotal({ ...page2, data: [incoming, ...page2.data] }, 0, 1)
+    );
+    if (placement.keepOverflow) return { data: inserted, refetch: false };
+    const { perPage } = placement;
+    if (perPage === void 0) return { data: inserted, refetch: "later" };
+    const page = inserted.pages[0];
+    if (page.data.length <= perPage) return { data: inserted, refetch: false };
+    const trimmed = recountPages({ ...page, data: page.data.slice(0, perPage) }, perPage);
+    if (!trimmed) return { data: inserted, refetch: "later" };
+    return { data: updatePage(inserted, 0, () => trimmed), refetch: false };
+  }
+  return { data, refetch: "later" };
+}
+function updatePage(data, index, update) {
+  return { ...data, pages: data.pages.map((page, i) => i === index ? update(page) : page) };
+}
+function recountPages(page, perPage) {
+  const pagination = page.pagination;
+  if (!pagination) return page;
+  const total = pagination.total;
+  const dependsOnTotal = "last_page" in pagination || "has_more_pages" in pagination;
+  if (!dependsOnTotal) return page;
+  if (typeof total !== "number") return null;
+  const lastPage = Math.max(1, Math.ceil(total / perPage));
+  return {
+    ...page,
+    pagination: {
+      ...pagination,
+      ..."last_page" in pagination ? { last_page: lastPage } : {},
+      ..."has_more_pages" in pagination ? { has_more_pages: lastPage > 1 } : {}
+    }
+  };
+}
+function adjustTotal(page, pageIndex, delta) {
+  var _a;
+  const total = (_a = page.pagination) == null ? void 0 : _a.total;
+  if (pageIndex !== 0 || typeof total !== "number") return page;
+  return { ...page, pagination: { ...page.pagination, total: Math.max(0, total + delta) } };
+}
+function isNewestFirst(sortby) {
+  const first = sortby == null ? void 0 : sortby[0];
+  if (!first) return true;
+  return (first.field === "integer_id" || first.field === "created_at") && first.order === "desc";
+}
+function sortChange(before, after, sortby) {
+  let unknown = false;
+  for (const { field } of sortby != null ? sortby : []) {
+    if (IMMUTABLE_SORT_FIELDS.has(field)) continue;
+    const previous = readPath(before, field);
+    const next = readPath(after, field);
+    if (next === void 0) {
+      unknown = true;
+      continue;
+    }
+    if (JSON.stringify(previous) !== JSON.stringify(next)) return "changed";
+  }
+  return unknown ? "unknown" : "unchanged";
+}
+function readPath(row, path) {
+  let value = row;
+  for (const key of path.split(".")) {
+    if (value && typeof value === "object" && "data" in value && !(key in value)) {
+      value = value.data;
+    }
+    if (!value || typeof value !== "object") return void 0;
+    value = value[key];
+  }
+  return value;
+}
 
 // src/hooks.ts
-import { useCallback, useRef, useState } from "react";
 import {
   useQuery,
   useInfiniteQuery,
   useMutation,
-  useQueryClient
+  useQueryClient,
+  hashKey
 } from "@tanstack/react-query";
 import {
   buildListQuery,
@@ -38,13 +155,91 @@ import {
   uploadToUrl,
   toUploadPart
 } from "@pylo/core";
+function patchableWith(headers) {
+  return headers === void 0 || Object.keys(headers).length === 0;
+}
+function withId(select) {
+  return { ...select, id: true };
+}
+function dedupeById(rows) {
+  const seen = /* @__PURE__ */ new Set();
+  return rows.filter((row) => {
+    const id = row == null ? void 0 : row.id;
+    if (id === void 0) return true;
+    if (seen.has(id)) return false;
+    seen.add(id);
+    return true;
+  });
+}
+var MAX_PAGES_TO_RESYNC = 5;
+function invalidateEntity(queryClient, realtime, entity) {
+  const live = realtime !== null && realtime.client.isLive(entity);
+  return queryClient.invalidateQueries({
+    queryKey: ["pylo", entity],
+    ...live ? { predicate: (query) => !realtime.liveQueries.has(query.queryHash) } : {}
+  });
+}
 var INFINITE_PAGINATION_SELECT = { current_page: true, has_more_pages: true };
 function createPyloHooks(options) {
-  var _a;
+  var _a, _b;
   const useTransport = (_a = options == null ? void 0 : options.useTransport) != null ? _a : usePyloTransport;
+  const useRealtime = (_b = options == null ? void 0 : options.useRealtime) != null ? _b : usePyloRealtime;
   const globalHeaders = options == null ? void 0 : options.headers;
+  function useLive(entity, queryKey, subscription, apply, beforeResync) {
+    const realtime = useRealtime();
+    const queryClient = useQueryClient();
+    const keyHash = hashKey(queryKey);
+    const latest = useRef({ queryKey, subscription, apply, beforeResync });
+    latest.current = { queryKey, subscription, apply, beforeResync };
+    const enabled = realtime !== null && subscription !== null;
+    useEffect(() => {
+      var _a2;
+      if (!enabled) return;
+      const { queryKey: queryKey2, subscription: subscription2 } = latest.current;
+      let timer;
+      let fireAt = Infinity;
+      const scheduleRefetch = (delayMs) => {
+        const at = Date.now() + delayMs;
+        if (timer !== void 0 && fireAt <= at) return;
+        clearTimeout(timer);
+        fireAt = at;
+        timer = setTimeout(() => {
+          timer = void 0;
+          fireAt = Infinity;
+          void queryClient.invalidateQueries({ queryKey: queryKey2, exact: true });
+        }, delayMs);
+      };
+      const counts = realtime.liveQueries;
+      counts.set(keyHash, ((_a2 = counts.get(keyHash)) != null ? _a2 : 0) + 1);
+      const sub = realtime.client.subscribe(entity, subscription2, {
+        onEvent: (event) => {
+          let refetch = false;
+          queryClient.setQueryData(queryKey2, (old) => {
+            if (old === void 0) return old;
+            const result = latest.current.apply(old, event);
+            refetch = result.refetch;
+            return result.data;
+          });
+          if (refetch) scheduleRefetch(refetch === "soon" ? 250 : 1500);
+        },
+        onResync: () => {
+          var _a3, _b2;
+          (_b2 = (_a3 = latest.current).beforeResync) == null ? void 0 : _b2.call(_a3);
+          void queryClient.invalidateQueries({ queryKey: queryKey2, exact: true });
+        }
+      });
+      return () => {
+        var _a3;
+        clearTimeout(timer);
+        sub.unsubscribe();
+        const left = ((_a3 = counts.get(keyHash)) != null ? _a3 : 1) - 1;
+        if (left > 0) counts.set(keyHash, left);
+        else counts.delete(keyHash);
+      };
+    }, [enabled, realtime, queryClient, entity, keyHash]);
+  }
   function usePyloList(entity, queryOptions) {
-    var _a2, _b, _c;
+    var _a2, _b2, _c;
     const transport = useTransport();
     const merged = mergeHeaders(globalHeaders, queryOptions == null ? void 0 : queryOptions.headers);
     const queryKey = [
@@ -61,17 +256,30 @@ function createPyloHooks(options) {
     const result = useQuery({
       queryKey,
       queryFn: async () => {
-        const { query, variables } = buildListQuery(
-          entity,
-          queryOptions
-        );
+        const { query, variables } = buildListQuery(entity, {
+          ...queryOptions,
+          select: withId(queryOptions.select)
+        });
         const data = await transport(query, variables, merged);
         const listKey = `${entity}List`;
         return data[listKey];
       }
     });
+    const patchable = patchableWith(merged);
+    useLive(
+      entity,
+      queryKey,
+      queryOptions.live ? { select: queryOptions.select, filter: queryOptions.filter } : null,
+      (data, event) => {
+        var _a3, _b3, _c2, _d;
+        return patchable ? applyListEvent(data, event, (_a3 = queryOptions.filter) == null ? void 0 : _a3.sortby, {
+          firstPage: ((_c2 = (_b3 = queryOptions.pagination) == null ? void 0 : _b3.page) != null ? _c2 : 1) === 1,
+          perPage: (_d = queryOptions.pagination) == null ? void 0 : _d.per_page
+        }) : { data, refetch: "later" };
+      }
+    );
     return {
-      data: (_b = (_a2 = result.data) == null ? void 0 : _a2.data) != null ? _b : void 0,
+      data: (_b2 = (_a2 = result.data) == null ? void 0 : _a2.data) != null ? _b2 : void 0,
       ..."_pagination" in queryOptions.select && { pagination: (_c = result.data) == null ? void 0 : _c.pagination },
       isLoading: result.isLoading,
       error: result.error,
@@ -81,25 +289,41 @@ function createPyloHooks(options) {
   function usePyloInfiniteList(entity, infiniteOptions) {
     var _a2;
     const transport = useTransport();
+    const queryClient = useQueryClient();
     const perPage = (_a2 = infiniteOptions == null ? void 0 : infiniteOptions.perPage) != null ? _a2 : 20;
     const merged = mergeHeaders(globalHeaders, infiniteOptions == null ? void 0 : infiniteOptions.headers);
+    const queryKey = [
+      "pylo",
+      entity,
+      "infiniteList",
+      {
+        perPage,
+        filter: infiniteOptions == null ? void 0 : infiniteOptions.filter,
+        select: infiniteOptions == null ? void 0 : infiniteOptions.select,
+        headers: merged
+      }
+    ];
+    const patchable = patchableWith(merged);
+    useLive(
+      entity,
+      queryKey,
+      infiniteOptions.live ? { select: infiniteOptions.select, filter: infiniteOptions.filter } : null,
+      (data, event) => {
+        var _a3;
+        return patchable ? applyPagesEvent(data, event, (_a3 = infiniteOptions.filter) == null ? void 0 : _a3.sortby) : { data, refetch: "later" };
+      },
+      () => queryClient.setQueryData(
+        queryKey,
+        (old) => old && old.pages.length > MAX_PAGES_TO_RESYNC ? { pages: old.pages.slice(0, 1), pageParams: old.pageParams.slice(0, 1) } : old
+      )
+    );
     return useInfiniteQuery({
-      queryKey: [
-        "pylo",
-        entity,
-        "infiniteList",
-        {
-          perPage,
-          filter: infiniteOptions == null ? void 0 : infiniteOptions.filter,
-          select: infiniteOptions == null ? void 0 : infiniteOptions.select,
-          headers: merged
-        }
-      ],
+      queryKey,
       queryFn: async ({ pageParam }) => {
         const select = infiniteOptions.select;
         const runtimeOptions = {
           select: {
-            ...select,
+            ...withId(select),
             _pagination: { ...select._pagination, ...INFINITE_PAGINATION_SELECT }
           },
           filter: infiniteOptions == null ? void 0 : infiniteOptions.filter,
@@ -121,8 +345,8 @@ function createPyloHooks(options) {
         return void 0;
       },
       select: (queryData) => {
-        const allData = queryData.pages.flatMap(
-          (page) => page.data
+        const allData = dedupeById(
+          queryData.pages.flatMap((page) => page.data)
         );
         return {
           ...queryData,
@@ -135,14 +359,24 @@ function createPyloHooks(options) {
   function usePyloById(entity, id, queryOptions) {
     const transport = useTransport();
     const merged = mergeHeaders(globalHeaders, queryOptions == null ? void 0 : queryOptions.headers);
+    const queryKey = ["pylo", entity, "byId", id, { select: queryOptions == null ? void 0 : queryOptions.select, headers: merged }];
+    const patchable = patchableWith(merged);
+    useLive(
+      entity,
+      queryKey,
+      queryOptions.live && id ? {
+        select: queryOptions.select,
+        filter: { query: [{ condition: { field: "id", operator: "equal", value: id } }] }
+      } : null,
+      (data, event) => patchable ? applyRowEvent(data, event) : { data, refetch: "later" }
+    );
     return useQuery({
-      queryKey: ["pylo", entity, "byId", id, { select: queryOptions == null ? void 0 : queryOptions.select, headers: merged }],
+      queryKey,
       queryFn: async () => {
-        const { query, variables } = buildByIdQuery(
-          entity,
-          id,
-          queryOptions
-        );
+        const { query, variables } = buildByIdQuery(entity, id, {
+          ...queryOptions,
+          select: withId(queryOptions.select)
+        });
         const data = await transport(query, variables, merged);
         const byIdKey = `${entity}ById`;
         const result = data[byIdKey];
@@ -231,6 +465,7 @@ function createPyloHooks(options) {
   function usePyloUpsert(entity, mutationOptions) {
     const transport = useTransport();
     const queryClient = useQueryClient();
+    const realtime = useRealtime();
     const merged = mergeHeaders(
       mergeHeaders(globalHeaders, mutationOptions == null ? void 0 : mutationOptions.headers),
       flagsToHeaders(mutationOptions != null ? mutationOptions : {})
@@ -250,11 +485,7 @@ function createPyloHooks(options) {
       },
       onSuccess: (data, variables, onMutateResult, context) => {
         var _a2;
-        if (!isDryRun) {
-          void queryClient.invalidateQueries({
-            queryKey: ["pylo", entity]
-          });
-        }
+        if (!isDryRun) void invalidateEntity(queryClient, realtime, entity);
         (_a2 = mutationOptions == null ? void 0 : mutationOptions.onSuccess) == null ? void 0 : _a2.call(mutationOptions, data, variables, onMutateResult, context);
       }
     });
@@ -262,6 +493,7 @@ function createPyloHooks(options) {
   function usePyloBulkUpsert(entity, mutationOptions) {
     const transport = useTransport();
     const queryClient = useQueryClient();
+    const realtime = useRealtime();
     const merged = mergeHeaders(
       mergeHeaders(globalHeaders, mutationOptions == null ? void 0 : mutationOptions.headers),
       flagsToHeaders(mutationOptions != null ? mutationOptions : {})
@@ -281,11 +513,7 @@ function createPyloHooks(options) {
       },
       onSuccess: (data, variables, onMutateResult, context) => {
         var _a2;
-        if (!isDryRun) {
-          void queryClient.invalidateQueries({
-            queryKey: ["pylo", entity]
-          });
-        }
+        if (!isDryRun) void invalidateEntity(queryClient, realtime, entity);
         (_a2 = mutationOptions == null ? void 0 : mutationOptions.onSuccess) == null ? void 0 : _a2.call(mutationOptions, data, variables, onMutateResult, context);
       }
     });
@@ -293,6 +521,7 @@ function createPyloHooks(options) {
   function usePyloDelete(entity, mutationOptions) {
     const transport = useTransport();
     const queryClient = useQueryClient();
+    const realtime = useRealtime();
     const merged = mergeHeaders(
       mergeHeaders(globalHeaders, mutationOptions == null ? void 0 : mutationOptions.headers),
       flagsToHeaders(mutationOptions != null ? mutationOptions : {})
@@ -313,11 +542,7 @@ function createPyloHooks(options) {
       },
       onSuccess: (data, variables, onMutateResult, context) => {
         var _a2;
-        if (!isDryRun) {
-          void queryClient.invalidateQueries({
-            queryKey: ["pylo", entity]
-          });
-        }
+        if (!isDryRun) void invalidateEntity(queryClient, realtime, entity);
         (_a2 = mutationOptions == null ? void 0 : mutationOptions.onSuccess) == null ? void 0 : _a2.call(mutationOptions, data, variables, onMutateResult, context);
       }
     });
@@ -403,7 +628,7 @@ function createPyloHooks(options) {
     optionsRef.current = hookOptions;
     const startUpload = useCallback(
       async (files, overrides) => {
-        var _a2, _b, _c, _d;
+        var _a2, _b2, _c, _d;
         const opts = { ...optionsRef.current, ...overrides };
         const merged = mergeHeaders(globalHeaders, opts.headers);
         const list = Array.isArray(files) ? files : [files];
@@ -419,13 +644,13 @@ function createPyloHooks(options) {
         const loadedPerFile = new Array(list.length).fill(0);
         const doneFlags = new Array(list.length).fill(false);
         const reportProgress = () => {
-          var _a3, _b2;
+          var _a3, _b3;
           const loaded = loadedPerFile.reduce((sum, bytes) => sum + bytes, 0);
           const percent = grandTotal !== void 0 ? grandTotal > 0 ? Math.round(loaded / grandTotal * 100) : 0 : Math.round(
             doneFlags.filter(Boolean).length / doneFlags.length * 100
           );
           setProgress(percent);
-          (_b2 = (_a3 = optionsRef.current) == null ? void 0 : _a3.onProgress) == null ? void 0 : _b2.call(_a3, {
+          (_b3 = (_a3 = optionsRef.current) == null ? void 0 : _a3.onProgress) == null ? void 0 : _b3.call(_a3, {
             loaded,
             total: grandTotal != null ? grandTotal : loaded,
             percent
@@ -438,7 +663,7 @@ function createPyloHooks(options) {
           const input = buildCreateUploadInput(opts, list.length);
           const results = await Promise.all(
             list.map(async (_source, index) => {
-              var _a3, _b2;
+              var _a3, _b3;
               const part = parts[index];
               const data = await transport(
                 CREATE_UPLOAD_MUTATION,
@@ -460,7 +685,7 @@ function createPyloHooks(options) {
                 id: uploadUrl.id,
                 fileName: part.fileName,
                 mimeType: part.mimeType,
-                size: (_b2 = part.size) != null ? _b2 : 0
+                size: (_b3 = part.size) != null ? _b3 : 0
               };
             })
           );
@@ -476,7 +701,7 @@ function createPyloHooks(options) {
           void queryClient.invalidateQueries({ queryKey: ["pylo", "pyloMedia"] });
           setUploadedFiles(results);
           setProgress(100);
-          (_b = (_a2 = optionsRef.current) == null ? void 0 : _a2.onSuccess) == null ? void 0 : _b.call(_a2, results);
+          (_b2 = (_a2 = optionsRef.current) == null ? void 0 : _a2.onSuccess) == null ? void 0 : _b2.call(_a2, results);
           return results;
         } catch (thrown) {
           controller.abort();
@@ -521,6 +746,37 @@ function createPyloHooks(options) {
       staleTime: (_a2 = queryOptions == null ? void 0 : queryOptions.staleTimeMs) != null ? _a2 : 4 * 60 * 1e3
     });
   }
+  function usePyloSubscription(entity, subscribeOptions, onEvent, handlers) {
+    const realtime = useRealtime();
+    const latest = useRef({ subscribeOptions, onEvent, handlers });
+    latest.current = { subscribeOptions, onEvent, handlers };
+    const enabled = realtime !== null && subscribeOptions.enabled !== false;
+    const key = hashKey([
+      subscribeOptions.select,
+      subscribeOptions.filter,
+      subscribeOptions.on
+    ]);
+    useEffect(() => {
+      if (!enabled) return;
+      const { select, filter, on } = latest.current.subscribeOptions;
+      const sub = realtime.client.subscribe(
+        entity,
+        { select, filter, on },
+        {
+          onEvent: (event) => latest.current.onEvent(event),
+          onResync: () => {
+            var _a2, _b2;
+            return (_b2 = (_a2 = latest.current.handlers) == null ? void 0 : _a2.onResync) == null ? void 0 : _b2.call(_a2);
+          },
+          onError: (error) => {
+            var _a2, _b2;
+            return (_b2 = (_a2 = latest.current.handlers) == null ? void 0 : _a2.onError) == null ? void 0 : _b2.call(_a2, error);
+          }
+        }
+      );
+      return () => sub.unsubscribe();
+    }, [enabled, realtime, entity, key]);
+  }
   return {
     usePyloList,
     usePyloInfiniteList,
@@ -536,7 +792,8 @@ function createPyloHooks(options) {
     usePyloEventPropertyKeys,
     usePyloEventFieldValues,
     usePyloUpload,
-    usePyloFileUrl
+    usePyloFileUrl,
+    usePyloSubscription
   };
 }
 

package/dist/{chunk-BPRHGSZF.js → chunk-OPMVPQER.js}

@@ -8,7 +8,7 @@ import {
   useSyncExternalStore
 } from "react";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
-import { createPyloClient, resolveEndpoint } from "@pylo/core";
+import { createPyloClient, createRealtime, resolveEndpoint } from "@pylo/core";
 import { ME_QUERY } from "@pylo/auth";
 
 // src/session/store.ts
@@ -378,7 +378,7 @@ var LOGGED_OUT = { status: "loggedOut", token: null };
 var NO_OP = () => () => {
 };
 function PyloProvider(props) {
-  var _a, _b;
+  var _a, _b, _c;
   const queryClient = useQueryClient();
   const endpoint = resolveEndpoint(props.endpoint);
   const storeRef = useRef(null);
@@ -421,6 +421,20 @@ function PyloProvider(props) {
   const getTokenRef = useRef(getTokenProp);
   getTokenRef.current = getTokenProp;
   const isEscapeHatch = getTokenProp !== void 0;
+  const transportRef = useRef(null);
+  const realtimeRef = useRef(null);
+  (_c = realtimeRef.current) != null ? _c : realtimeRef.current = {
+    client: createRealtime({
+      request: (query, variables) => transportRef.current(query, variables),
+      auth: async () => {
+        const token = isEscapeHatch ? await getTokenRef.current() : await store.getToken();
+        return { token };
+      }
+    }),
+    liveQueries: /* @__PURE__ */ new Map()
+  };
+  const realtime = realtimeRef.current;
+  useEffect(() => () => realtime.client.close(), [realtime]);
   const value = useMemo(() => {
     const getToken = isEscapeHatch ? () => getTokenRef.current() : () => store.getToken();
     const transport = createDirectTransport({
@@ -428,13 +442,17 @@ function PyloProvider(props) {
       getToken,
       ...store ? { onUnauthorized: () => store.refresh() } : {}
     });
-    return { transport, endpoint, state, store, social, getToken };
-  }, [endpoint, state, store, social, isEscapeHatch]);
+    transportRef.current = transport;
+    return { transport, endpoint, state, store, social, getToken, realtime };
+  }, [endpoint, state, store, social, isEscapeHatch, realtime]);
   return /* @__PURE__ */ jsx(PyloContext.Provider, { value, children: props.children });
 }
 function usePyloTransport() {
   return usePyloContext().transport;
 }
+function usePyloRealtime() {
+  return usePyloContext().realtime;
+}
 function usePyloClient() {
   const { endpoint, getToken } = usePyloContext();
   return useMemo(
@@ -495,6 +513,7 @@ export {
   createDirectTransport,
   PyloProvider,
   usePyloTransport,
+  usePyloRealtime,
   usePyloClient,
   usePyloAuth
 };

package/dist/hooks.d.ts

@@ -1,12 +1,25 @@
-import { T as Transport } from './transport-55cSrvQo.js';
+import { T as Transport, L as LiveRealtime } from './provider-DF_-sV-r.js';
 import { UseQueryResult, UseInfiniteQueryResult, UseMutationOptions, UseMutationResult } from '@tanstack/react-query';
-import { EntityNameWith, ListSelect, FilterInput, RequestOptions, WithPagination, EntityRelationPath, UploadAttachTarget, UploadProgress, PyloUploadedFile, UploadSource, ListSelectConstraint, ListOptions, EntityResult, PaginationData, SelectConstraint, ByIdOptions, EntityName, AggregateMetricInput, AggregateGroupByInput, AggregateOptions, AggregateResult, EventMetricInput, EventGroupByInput, EventAggregateOptions, UpsertInput, MutationRequestOptions, PyloEvent, PyloEventInput, PaginationSelect, EventListOptions, PyloEventListResult, PyloEventPropertyKeysOptions, PyloEventProperty, PyloEventFieldValuesOptions, PyloEventFieldValue } from '@pylo/core';
+import { EntityNameWith, ListSelect, FilterInput, RequestOptions, WithPagination, EntityRelationPath, UploadAttachTarget, UploadProgress, PyloUploadedFile, UploadSource, ListSelectConstraint, ListOptions, EntityResult, PaginationData, SelectConstraint, ByIdOptions, EntityName, AggregateMetricInput, AggregateGroupByInput, AggregateOptions, AggregateResult, EventMetricInput, EventGroupByInput, EventAggregateOptions, UpsertInput, MutationRequestOptions, PyloEvent, PyloEventInput, PaginationSelect, EventListOptions, PyloEventListResult, PyloEventPropertyKeysOptions, PyloEventProperty, PyloEventFieldValuesOptions, PyloEventFieldValue, SubscribeOptions, RealtimeHandlers } from '@pylo/core';
+import 'react/jsx-runtime';
+import 'react';
+import '@pylo/auth';
 
 interface HooksOptions {
     /** Defaults to reading the transport `PyloProvider` supplies. */
     useTransport?: () => Transport;
+    /** Defaults to the connection `PyloProvider` supplies; `null` turns `live` off. */
+    useRealtime?: () => LiveRealtime | null;
     headers?: Record<string, string>;
 }
+interface LiveOption {
+    /**
+     * Keep the result current over the realtime connection: updates and removals
+     * are patched into the cache, anything the cache can't place correctly
+     * triggers a background refetch.
+     */
+    live?: boolean;
+}
 type ListHookResult<T, Sel = unknown> = {
     data: T[] | undefined;
     isLoading: boolean;
@@ -21,7 +34,7 @@ type InfiniteListOptions<S, E extends EntityNameWith<S, "list">, Sel extends Lis
     perPage?: number;
     select: Sel;
     filter?: FilterInput;
-} & RequestOptions;
+} & RequestOptions & LiveOption;
 type InfinitePagination<Sel> = Pick<PaginationData, "current_page" | "has_more_pages" | (Sel extends {
     _pagination: infer PS;
 } ? keyof PS & keyof PaginationData : never)>;
@@ -63,7 +76,7 @@ interface UploadHookResult<S> {
     reset: () => void;
 }
 declare function createPyloHooks<S>(options?: HooksOptions): {
-    usePyloList: <E extends EntityNameWith<S, "list">, const Sel extends ListSelectConstraint<S, E, Sel>>(entity: E, queryOptions: ListOptions<S, E, Sel> & RequestOptions) => ListHookResult<EntityResult<S, E, Sel>, Sel>;
+    usePyloList: <E extends EntityNameWith<S, "list">, const Sel extends ListSelectConstraint<S, E, Sel>>(entity: E, queryOptions: ListOptions<S, E, Sel> & RequestOptions & LiveOption) => ListHookResult<EntityResult<S, E, Sel>, Sel>;
     usePyloInfiniteList: <E extends EntityNameWith<S, "list">, const Sel extends ListSelectConstraint<S, E, Sel>>(entity: E, infiniteOptions: InfiniteListOptions<S, E, Sel>) => UseInfiniteQueryResult<{
         data: Array<EntityResult<S, E, Sel>>;
         pages: Array<{
@@ -71,7 +84,7 @@ declare function createPyloHooks<S>(options?: HooksOptions): {
             pagination: InfinitePagination<Sel>;
         }>;
     }>;
-    usePyloById: <E extends EntityNameWith<S, "byId">, const Sel extends SelectConstraint<S, E, Sel>>(entity: E, id: string | null | undefined, queryOptions: ByIdOptions<S, E, Sel> & RequestOptions) => UseQueryResult<EntityResult<S, E, Sel> | null>;
+    usePyloById: <E extends EntityNameWith<S, "byId">, const Sel extends SelectConstraint<S, E, Sel>>(entity: E, id: string | null | undefined, queryOptions: ByIdOptions<S, E, Sel> & RequestOptions & LiveOption) => UseQueryResult<EntityResult<S, E, Sel> | null>;
     usePyloMe: <const Sel extends SelectConstraint<S, "me" & EntityName<S>, Sel>>(queryOptions: ByIdOptions<S, "me" & EntityName<S>, Sel> & RequestOptions) => UseQueryResult<EntityResult<S, "me" & EntityName<S>, Sel>>;
     usePyloAggregate: <E extends EntityName<S>, const M extends Record<string, AggregateMetricInput<S, E>>, const G extends readonly AggregateGroupByInput<S, E>[] = []>(entity: E, queryOptions: AggregateOptions<S, E, M, G> & RequestOptions) => UseQueryResult<AggregateResult<M, G>>;
     usePyloEventAggregate: <const M extends Record<string, EventMetricInput>, const G extends readonly EventGroupByInput[] = []>(queryOptions: EventAggregateOptions<M, G> & RequestOptions) => UseQueryResult<AggregateResult<M, G>>;
@@ -98,6 +111,9 @@ declare function createPyloHooks<S>(options?: HooksOptions): {
     usePyloFileUrl: (id: string | null | undefined, queryOptions?: {
         staleTimeMs?: number;
     } & RequestOptions) => UseQueryResult<string>;
+    usePyloSubscription: <E extends EntityNameWith<S, "list">, const Sel extends SelectConstraint<S, E, Sel>>(entity: E, subscribeOptions: SubscribeOptions<S, E, Sel> & {
+        enabled?: boolean;
+    }, onEvent: RealtimeHandlers<EntityResult<S, E, Sel>>["onEvent"], handlers?: Omit<RealtimeHandlers<EntityResult<S, E, Sel>>, "onEvent">) => void;
 };
 
-export { type InfiniteListOptions, type ListHookResult, type StartUploadOptions, type UploadHookOptions, type UploadHookResult, createPyloHooks };
+export { type InfiniteListOptions, type ListHookResult, type LiveOption, type StartUploadOptions, type UploadHookOptions, type UploadHookResult, createPyloHooks };

package/dist/hooks.js

@@ -1,8 +1,8 @@
 "use client";
 import {
   createPyloHooks
-} from "./chunk-FKUNSR3E.js";
-import "./chunk-BPRHGSZF.js";
+} from "./chunk-C3KAJKBM.js";
+import "./chunk-OPMVPQER.js";
 export {
   createPyloHooks
 };

package/dist/index.d.ts

@@ -1,11 +1,10 @@
 import { EntityName, EntitySelect, EntityResult } from '@pylo/core';
-export { AggregateFilterInput, AggregateFunction, AggregateGroupByInput, AggregateInput, AggregateInterval, AggregateIntervalUnit, AggregateMetricInput, AggregateOptions, AggregateResult, AggregateRow, AggregateRows, AggregateSortInput, AggregateSortKey, AggregateTotal, ByIdOptions, CallableEntityName, CreateUploadInput, CreateUploadUrlOptions, DimensionInput, DimensionValue, EntityAggregateApi, EntityCapability, EntityFields, EntityMethodName, EntityName, EntityNameWith, EntityRelationPath, EntityRelations, EntityResult, EntitySelect, EventAggregateOptions, EventGroupByInput, EventListFilterInput, EventListOptions, EventMetricInput, FieldName, FilesClient, FilterInput, HasCapability, IngestEvents, ListOptions, ListResult, Me, MetricValue, MutationRequestOptions, NumericFieldName, PaginationData, PaginationInput, PyloError, PyloEvent, PyloEventFieldValue, PyloEventFieldValuesOptions, PyloEventInput, PyloEventListResult, PyloEventProperty, PyloEventPropertyKeysOptions, PyloUploadedFile, QueryInput, QueryInputCondition, QueryOperator, RequestOptions, RowKeyOf, SearchValueInput, SortInput, SortOrder, SystemEntityName, TimeBucketInput, UploadAttachTarget, UploadOptions, UploadProgress, UploadSource, UploadUrl, UpsertInput, VirtualEntityName } from '@pylo/core';
+export { AggregateFilterInput, AggregateFunction, AggregateGroupByInput, AggregateInput, AggregateInterval, AggregateIntervalUnit, AggregateMetricInput, AggregateOptions, AggregateResult, AggregateRow, AggregateRows, AggregateSortInput, AggregateSortKey, AggregateTotal, ByIdOptions, CallableEntityName, CreateUploadInput, CreateUploadUrlOptions, DimensionInput, DimensionValue, EntityAggregateApi, EntityCapability, EntityFields, EntityMethodName, EntityName, EntityNameWith, EntityRelationPath, EntityRelations, EntityResult, EntitySelect, EventAggregateOptions, EventGroupByInput, EventListFilterInput, EventListOptions, EventMetricInput, FieldName, FilesClient, FilterInput, HasCapability, IngestEvents, ListOptions, ListResult, Me, MetricValue, MutationRequestOptions, NumericFieldName, PaginationData, PaginationInput, PyloError, PyloEvent, PyloEventFieldValue, PyloEventFieldValuesOptions, PyloEventInput, PyloEventListResult, PyloEventProperty, PyloEventPropertyKeysOptions, PyloUploadedFile, QueryInput, QueryInputCondition, QueryOperator, RealtimeClient, RealtimeEvent, RealtimeEventKind, RealtimeHandlers, RealtimeStatus, RealtimeSubscription, RequestOptions, RowKeyOf, SearchValueInput, SortInput, SortOrder, SubscribeOptions, SystemEntityName, TimeBucketInput, UploadAttachTarget, UploadOptions, UploadProgress, UploadSource, UploadUrl, UpsertInput, VirtualEntityName } from '@pylo/core';
 import { AuthResult, SocialProvider } from '@pylo/auth';
 export { AuthResult, HandoffCrypto, PyloUser, SocialProvider } from '@pylo/auth';
-import { P as PyloStorage, a as PyloAuth } from './provider-4DBl_6p0.js';
-export { O as OpenAuthSession, b as PyloProvider, c as PyloProviderProps, S as SocialLogin, d as SocialLoginResult, e as createLocalStorageAdapter, f as createMemoryStorage, u as usePyloClient, g as usePyloTransport } from './provider-4DBl_6p0.js';
-export { D as DirectTransportOptions, T as Transport, c as createDirectTransport } from './transport-55cSrvQo.js';
-export { InfiniteListOptions, ListHookResult, StartUploadOptions, UploadHookOptions, UploadHookResult, createPyloHooks } from './hooks.js';
+import { P as PyloStorage, a as PyloAuth } from './provider-DF_-sV-r.js';
+export { D as DirectTransportOptions, L as LiveRealtime, O as OpenAuthSession, b as PyloProvider, c as PyloProviderProps, S as SocialLogin, d as SocialLoginResult, T as Transport, e as createDirectTransport, f as createLocalStorageAdapter, g as createMemoryStorage, u as usePyloClient, h as usePyloRealtime, i as usePyloTransport } from './provider-DF_-sV-r.js';
+export { InfiniteListOptions, ListHookResult, LiveOption, StartUploadOptions, UploadHookOptions, UploadHookResult, createPyloHooks } from './hooks.js';
 import 'react/jsx-runtime';
 import 'react';
 import '@tanstack/react-query';

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   createPyloHooks
-} from "./chunk-FKUNSR3E.js";
+} from "./chunk-C3KAJKBM.js";
 import {
   PyloProvider,
   createDirectTransport,
@@ -9,8 +9,9 @@ import {
   createSessionStore,
   usePyloAuth,
   usePyloClient,
+  usePyloRealtime,
   usePyloTransport
-} from "./chunk-BPRHGSZF.js";
+} from "./chunk-OPMVPQER.js";
 
 // src/index.ts
 import { PyloError } from "@pylo/core";
@@ -25,5 +26,6 @@ export {
   createSessionStore,
   usePyloAuth2 as usePyloAuth,
   usePyloClient,
+  usePyloRealtime,
   usePyloTransport
 };

package/dist/{provider-4DBl_6p0.d.ts → provider-DF_-sV-r.d.ts}

@@ -1,8 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
-import { PyloClient } from '@pylo/core';
+import { RealtimeClient, PyloClient } from '@pylo/core';
 import { SocialProvider, AuthResult, PyloUser, HandoffCrypto } from '@pylo/auth';
-import { T as Transport } from './transport-55cSrvQo.js';
 
 /**
  * The three operations a session needs from a key-value store. Async because
@@ -40,6 +39,23 @@ interface SocialLogin<P extends string = SocialProvider, U extends string = stri
     completeLogin(url?: string): Promise<SocialLoginResult>;
 }
 
+/**
+ * How the hooks reach the API. `@pylo/react` talks to it directly; `@pylo/nextjs`
+ * posts to its route handler so the token can stay in an httpOnly cookie.
+ */
+type Transport = (query: string, variables: Record<string, unknown>, headers?: Record<string, string>) => Promise<unknown>;
+interface DirectTransportOptions {
+    endpoint: string;
+    getToken: () => Promise<string | null>;
+    /** Called once on an unauthorized response; returns the token to retry with. */
+    onUnauthorized?: () => Promise<string | null>;
+}
+declare function createDirectTransport(options: DirectTransportOptions): Transport;
+
+interface LiveRealtime {
+    client: RealtimeClient;
+    liveQueries: Map<string, number>;
+}
 interface PyloProviderProps {
     children: ReactNode;
     endpoint?: string;
@@ -60,6 +76,7 @@ interface PyloProviderProps {
 }
 declare function PyloProvider(props: PyloProviderProps): react_jsx_runtime.JSX.Element;
 declare function usePyloTransport(): Transport;
+declare function usePyloRealtime(): LiveRealtime;
 declare function usePyloClient<S>(): PyloClient<S>;
 interface PyloAuth<P extends string = SocialProvider, U extends string = string> extends SocialLogin<P, U> {
     isLoading: boolean;
@@ -71,4 +88,4 @@ interface PyloAuth<P extends string = SocialProvider, U extends string = string>
 }
 declare function usePyloAuth(): PyloAuth;
 
-export { type OpenAuthSession as O, type PyloStorage as P, type SocialLogin as S, type PyloAuth as a, PyloProvider as b, type PyloProviderProps as c, type SocialLoginResult as d, createLocalStorageAdapter as e, createMemoryStorage as f, usePyloTransport as g, usePyloAuth as h, usePyloClient as u };
+export { type DirectTransportOptions as D, type LiveRealtime as L, type OpenAuthSession as O, type PyloStorage as P, type SocialLogin as S, type Transport as T, type PyloAuth as a, PyloProvider as b, type PyloProviderProps as c, type SocialLoginResult as d, createDirectTransport as e, createLocalStorageAdapter as f, createMemoryStorage as g, usePyloRealtime as h, usePyloTransport as i, usePyloAuth as j, usePyloClient as u };

package/dist/provider.d.ts

@@ -2,5 +2,4 @@ import 'react/jsx-runtime';
 import 'react';
 import '@pylo/core';
 import '@pylo/auth';
-export { a as PyloAuth, b as PyloProvider, c as PyloProviderProps, h as usePyloAuth, u as usePyloClient, g as usePyloTransport } from './provider-4DBl_6p0.js';
-import './transport-55cSrvQo.js';
+export { L as LiveRealtime, a as PyloAuth, b as PyloProvider, c as PyloProviderProps, j as usePyloAuth, u as usePyloClient, h as usePyloRealtime, i as usePyloTransport } from './provider-DF_-sV-r.js';

package/dist/provider.js

@@ -2,11 +2,13 @@ import {
   PyloProvider,
   usePyloAuth,
   usePyloClient,
+  usePyloRealtime,
   usePyloTransport
-} from "./chunk-BPRHGSZF.js";
+} from "./chunk-OPMVPQER.js";
 export {
   PyloProvider,
   usePyloAuth,
   usePyloClient,
+  usePyloRealtime,
   usePyloTransport
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylo/react",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "Type-safe React SDK for Pylo — hooks, session provider, client",
   "type": "module",
   "bin": {
@@ -37,7 +37,7 @@
   ],
   "dependencies": {
     "@pylo/auth": "0.2.0",
-    "@pylo/core": "0.11.0"
+    "@pylo/core": "0.12.0"
   },
   "peerDependencies": {
     "@tanstack/react-query": ">=5.0.0",
@@ -45,9 +45,13 @@
   },
   "devDependencies": {
     "@tanstack/react-query": "^5.0.0",
+    "@testing-library/react": "^16.3.3",
     "@types/node": "^22.15.21",
     "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.3.0",
+    "happy-dom": "^21.0.3",
     "react": "^19.0.0",
+    "react-dom": "^19.2.4",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3"
   },

package/dist/transport-55cSrvQo.d.ts

@@ -1,14 +0,0 @@
-/**
- * How the hooks reach the API. `@pylo/react` talks to it directly; `@pylo/nextjs`
- * posts to its route handler so the token can stay in an httpOnly cookie.
- */
-type Transport = (query: string, variables: Record<string, unknown>, headers?: Record<string, string>) => Promise<unknown>;
-interface DirectTransportOptions {
-    endpoint: string;
-    getToken: () => Promise<string | null>;
-    /** Called once on an unauthorized response; returns the token to retry with. */
-    onUnauthorized?: () => Promise<string | null>;
-}
-declare function createDirectTransport(options: DirectTransportOptions): Transport;
-
-export { type DirectTransportOptions as D, type Transport as T, createDirectTransport as c };