@zuzjs/flare 0.2.20 → 0.2.22

package/dist/react.d.cts

@@ -1,5 +1,5 @@
-import { a as CollectionQuery } from './index-CVwSnXPP.cjs';
-import './index-Y0Mq_6P9.cjs';
+import { a as CollectionQuery } from './index-DOaU2Hxo.cjs';
+import './index-18tMqAtM.cjs';
 import '@zuzjs/auth';
 
 declare const useLiveQuery: (data: {
@@ -14,9 +14,47 @@ declare const useLiveQuery: (data: {
         maxDocs: number;
     };
     forceReadyOnFirstEmission?: boolean;
+    /**
+     * Retry the stream when the very first emission is ready=true with zero rows.
+     * Helps recover from transient first-load races on higher-latency networks.
+     * Default 1.
+     */
+    firstReadyEmptyRetryCount?: number;
+    /**
+     * Delay in ms before retrying a first ready+empty emission.
+     * Default 120.
+     */
+    firstReadyEmptyRetryDelayMs?: number;
+    /**
+     * Retry count when the first emission is ready=false with zero rows and
+     * no follow-up emissions arrive within stalledFirstEmissionTimeoutMs.
+     * Default 2.
+     */
+    stalledFirstEmissionRetryCount?: number;
+    /**
+     * Timeout in ms to consider the stream stalled after first ready=false empty emission.
+     * Default 500.
+     */
+    stalledFirstEmissionTimeoutMs?: number;
+    /**
+     * Enable detailed stream trace logs for debugging race conditions.
+     */
+    debugTrace?: boolean;
+    /**
+     * Prefix used in debug logs to identify the caller.
+     */
+    debugLabel?: string;
+    /**
+     * When the stream emits ready=true with zero rows, wait this many ms before
+     * forwarding the empty result. If a non-empty emission arrives within the window
+     * the grace timer is cancelled and data is forwarded immediately.
+     * Default 0 (no grace period — backwards-compatible).
+     */
+    emptyReadyGraceMs?: number;
 }) => {
-    buildStream: (queryOverride?: CollectionQuery<any, {}>) => void;
+    buildStream: (queryOverride?: CollectionQuery<any, {}>, isInternalRetry?: boolean) => void;
     closeStream: () => void;
+    cancelGraceTimer: () => void;
 };
 
 export { useLiveQuery };

package/dist/react.d.ts

@@ -1,5 +1,5 @@
-import { a as CollectionQuery } from './index-OUj3iEUt.js';
-import './index-Y0Mq_6P9.js';
+import { a as CollectionQuery } from './index-CRByt4Qw.js';
+import './index-18tMqAtM.js';
 import '@zuzjs/auth';
 
 declare const useLiveQuery: (data: {
@@ -14,9 +14,47 @@ declare const useLiveQuery: (data: {
         maxDocs: number;
     };
     forceReadyOnFirstEmission?: boolean;
+    /**
+     * Retry the stream when the very first emission is ready=true with zero rows.
+     * Helps recover from transient first-load races on higher-latency networks.
+     * Default 1.
+     */
+    firstReadyEmptyRetryCount?: number;
+    /**
+     * Delay in ms before retrying a first ready+empty emission.
+     * Default 120.
+     */
+    firstReadyEmptyRetryDelayMs?: number;
+    /**
+     * Retry count when the first emission is ready=false with zero rows and
+     * no follow-up emissions arrive within stalledFirstEmissionTimeoutMs.
+     * Default 2.
+     */
+    stalledFirstEmissionRetryCount?: number;
+    /**
+     * Timeout in ms to consider the stream stalled after first ready=false empty emission.
+     * Default 500.
+     */
+    stalledFirstEmissionTimeoutMs?: number;
+    /**
+     * Enable detailed stream trace logs for debugging race conditions.
+     */
+    debugTrace?: boolean;
+    /**
+     * Prefix used in debug logs to identify the caller.
+     */
+    debugLabel?: string;
+    /**
+     * When the stream emits ready=true with zero rows, wait this many ms before
+     * forwarding the empty result. If a non-empty emission arrives within the window
+     * the grace timer is cancelled and data is forwarded immediately.
+     * Default 0 (no grace period — backwards-compatible).
+     */
+    emptyReadyGraceMs?: number;
 }) => {
-    buildStream: (queryOverride?: CollectionQuery<any, {}>) => void;
+    buildStream: (queryOverride?: CollectionQuery<any, {}>, isInternalRetry?: boolean) => void;
     closeStream: () => void;
+    cancelGraceTimer: () => void;
 };
 
 export { useLiveQuery };

package/dist/react.js

@@ -1 +1 @@
-import {useRef,useEffect,useCallback}from'react';var F=E=>{let{query:i,options:l,onData:m,forceReadyOnFirstEmission:d=true}=E,y=useRef(null),f=useRef(null),p=useRef(""),h=useRef(0),S=useRef(false),b=useRef(m),o=useRef(i??null),n=useRef(l),C=useRef(d),s=(...g)=>{};useEffect(()=>{b.current=m;},[m]),useEffect(()=>{o.current=i??null;},[i]),useEffect(()=>{n.current=l;},[l]),useEffect(()=>{C.current=d;},[d]);let a=useCallback(()=>{f.current?.(),y.current?.close(),f.current=null,S.current=false,p.current="";},[]),Q=useCallback(g=>{a(),h.current+=1,g&&(o.current=g),o.current&&(y.current=o.current.stream({flushMs:n.current?.flushMs??20,maxBatchSize:n.current?.maxBatchSize??20,insertAt:n.current?.insertAt??"end",maxDocs:n.current?.maxDocs??50}),f.current=y.current.subscribe((e,t)=>{let $=e.map(c=>`${c?.id??""}:${c?.updatedAt??c?.updated_at??c?.mtime??""}`).join(","),D=`${h.current}:${t?.ready?1:0}:${$}`;if(D===p.current){s("[Sidebar] Skipping duplicate boards stream payload",{size:e.length,meta:t.ready});return}if(p.current=D,!S.current){S.current=true,b.current(e,{ready:C.current?true:!!t?.ready}),s("Stream first payload",{size:e.length,meta:t});return}s("[Sidebar] Boards stream update",{size:e.length,meta:t.ready}),b.current(e,{ready:!!t?.ready});}));},[a]);return useEffect(()=>()=>{a();},[a]),{buildStream:Q,closeStream:a}};export{F as useLiveQuery};
+import {useRef,useEffect,useCallback}from'react';var ce=x=>{let{query:L,options:M,onData:D,forceReadyOnFirstEmission:Q=true,firstReadyEmptyRetryCount:f=1,firstReadyEmptyRetryDelayMs:z=120,stalledFirstEmissionRetryCount:g=2,stalledFirstEmissionTimeoutMs:A=500,debugTrace:I=false,debugLabel:U="useLiveQuery",emptyReadyGraceMs:Z=0}=x,G=useRef(null),$=useRef(null),v=useRef(""),V=useRef(0),o=useRef(false),m=useRef(false),R=useRef(D),b=useRef(L??null),p=useRef(M),H=useRef(Q),J=useRef(f),K=useRef(z),y=useRef(f),P=useRef(g),W=useRef(A),i=useRef(g),d=useRef(null),X=useRef(I),Y=useRef(U),h=useRef(Z),a=useRef(null),T=useRef(null),q=useRef(0),ee=()=>{let l=globalThis,O=l?.__ZUZ_LIVE_QUERY_TRACE,r=false,s=null;try{typeof window<"u"&&window.localStorage&&(r=window.localStorage.getItem("__ZUZ_LIVE_QUERY_TRACE")==="1",s=window.localStorage.getItem("__ZUZ_LIVE_QUERY_TRACE_FILTER"));}catch{}if(!O&&!r)return  false;let S=l?.__ZUZ_LIVE_QUERY_TRACE_FILTER??s;return S?String(Y.current).toLowerCase().includes(String(S).toLowerCase()):true},u=(...l)=>{(X.current||ee())&&console.log(`[${Y.current}]`,...l);};useEffect(()=>{R.current=D;},[D]),useEffect(()=>{b.current=L??null;},[L]),useEffect(()=>{p.current=M;},[M]),useEffect(()=>{H.current=Q;},[Q]),useEffect(()=>{J.current=f,y.current=f;},[f]),useEffect(()=>{K.current=z;},[z]),useEffect(()=>{P.current=g,i.current=g;},[g]),useEffect(()=>{W.current=A;},[A]),useEffect(()=>{X.current=I;},[I]),useEffect(()=>{Y.current=U;},[U]),useEffect(()=>{h.current=Z;},[Z]);let _=useCallback(()=>{a.current!==null&&(clearTimeout(a.current),a.current=null),T.current=null;},[]),B=useCallback(()=>{d.current!==null&&(clearTimeout(d.current),d.current=null);},[]),E=useCallback(()=>{_(),B(),$.current?.(),G.current?.close(),$.current=null,o.current=false,m.current=false,q.current=0,v.current="";},[_,B]),N=useCallback((l,O=false)=>{E(),V.current+=1,O||(y.current=J.current,i.current=P.current),l&&(b.current=l),b.current&&(G.current=b.current.stream({flushMs:p.current?.flushMs??20,maxBatchSize:p.current?.maxBatchSize??20,insertAt:p.current?.insertAt??"end",maxDocs:p.current?.maxDocs??50}),$.current=G.current.subscribe((r,s)=>{d.current!==null&&B();let S=r.map(t=>`${t?.id??""}:${t?.updatedAt??t?.updated_at??t?.mtime??""}`).join(","),w=`${V.current}:${s?.ready?1:0}:${S}`;q.current+=1;let c=q.current;if(u("emission",{emissionNo:c,generation:V.current,ready:!!s?.ready,size:r.length,firstRetryRemaining:y.current,hasNonEmpty:m.current}),w===v.current){u("skip duplicate",{emissionNo:c,size:r.length,metaReady:!!s?.ready});return}v.current=w;let k=!o.current,re=k&&H.current&&r.length>0,C=k&&re?true:!!s?.ready,j=!!s?.ready;if(k&&!j&&r.length===0&&i.current>0){let t=Math.max(0,W.current),te=i.current-1;d.current=setTimeout(()=>{d.current=null,i.current=Math.max(0,i.current-1),u("stalled first emission timeout hit \u2014 rebuilding stream",{stallTimeout:t,retriesLeft:i.current}),N(void 0,true);},t),u("schedule stalled-first-emission retry",{emissionNo:c,stallTimeout:t,retriesLeft:te});return}if(j&&r.length===0&&!m.current&&y.current>0){y.current-=1;let t=Math.max(0,K.current);u("schedule first-ready-empty retry",{emissionNo:c,retryDelay:t,retriesLeft:y.current}),setTimeout(()=>{N(void 0,true);},t);return}if(a.current!==null&&r.length>0){_(),o.current=true,m.current=true,u("emit non-empty after grace wait",{emissionNo:c,ready:C,size:r.length}),R.current(r,{ready:C});return}if(j&&r.length===0&&h.current>0&&a.current===null){T.current={rows:r},o.current=true,a.current=setTimeout(()=>{a.current=null;let t=T.current;T.current=null,t&&(u("emit deferred empty after grace timeout",{size:t.rows.length}),R.current(t.rows,{ready:true}));},h.current),u("start empty-ready grace timer",{emissionNo:c,graceMs:h.current});return}if(!o.current){o.current=true,r.length>0&&(m.current=true),u("emit first payload",{emissionNo:c,ready:C,size:r.length}),R.current(r,{ready:C});return}u("emit update",{emissionNo:c,size:r.length,metaReady:!!s?.ready}),r.length>0&&(m.current=true),R.current(r,{ready:!!s?.ready});}));},[E]);return useEffect(()=>()=>{u("[Sidebar] Cleaning up boards stream"),E();},[E]),{buildStream:N,closeStream:E,cancelGraceTimer:_}};export{ce as useLiveQuery};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zuzjs/flare",
-  "version": "0.2.20",
+  "version": "0.2.22",
   "keywords": [
     "core",
     "zuz",