@neetru/sdk 1.2.0 → 2.1.0

package/dist/db-react.d.ts

@@ -0,0 +1,99 @@
+import { S as SyncState, U as Unsubscribe, d as DbDoc, c as DbCollectionRef, h as DbQuery } from './collection-ref-BBvTTXoG.js';
+
+/**
+ * Resultado de `useDocument`.
+ *
+ * - `data` — dados do documento, ou `null` se não existe / ainda carregando.
+ * - `loading` — `true` enquanto o primeiro snapshot não foi entregue.
+ * - `fromCache` — o snapshot veio do cache local, não do servidor.
+ * - `stale` — conexão caída ou sincronizando; pode haver dados mais novos.
+ */
+interface UseDocumentResult<T> {
+    data: T | null;
+    loading: boolean;
+    fromCache: boolean;
+    stale: boolean;
+}
+/**
+ * Resultado de `useCollection`.
+ *
+ * - `docs` — documentos da coleção (ou subconjunto via query).
+ * - `loading` — `true` enquanto o primeiro snapshot não foi entregue.
+ * - `fromCache` — o snapshot veio do cache local.
+ * - `stale` — conexão caída ou sincronizando.
+ * - `hasPendingWrites` — ao menos um doc tem escrita local não confirmada.
+ */
+interface UseCollectionResult<T> {
+    docs: DbDoc<T>[];
+    loading: boolean;
+    fromCache: boolean;
+    stale: boolean;
+    hasPendingWrites: boolean;
+}
+/**
+ * Subconjunto mínimo do namespace offline que `useSyncState` precisa.
+ * Compatível com `NeetruDbDocuments` de `collection-ref.ts`.
+ *
+ * Passado explicitamente (sem Context) para alinhar com o padrão do SDK.
+ * Tipicamente: o namespace retornado por `createOfflineDocumentsNamespace`.
+ */
+interface SyncStateSource {
+    readonly syncState: SyncState;
+    onSyncStateChanged(cb: (s: SyncState) => void): Unsubscribe;
+}
+/**
+ * Hook de tempo real para um documento específico.
+ *
+ * Subscreve a `ref.doc(id).onSnapshot` no mount. Re-subscreve quando `ref`
+ * ou `id` mudam. Cancela a subscrição no unmount.
+ *
+ * ```tsx
+ * const { data, loading, fromCache, stale } = useDocument(ordersRef, orderId);
+ * if (loading) return <Spinner />;
+ * if (!data) return <NotFound />;
+ * return <OrderCard order={data} fromCache={fromCache} />;
+ * ```
+ *
+ * Seguro em React 18/19 StrictMode: a cleanup function do useEffect cancela
+ * o listener no unmount, e o double-mount do StrictMode não vaza estado.
+ */
+declare function useDocument<T>(ref: DbCollectionRef<T>, id: string): UseDocumentResult<T>;
+/**
+ * Hook de tempo real para uma coleção (ou subconjunto filtrado).
+ *
+ * Subscreve a `ref.onSnapshot(query, cb)` no mount. Re-subscreve quando `ref`
+ * ou a serialização de `query` muda — NÃO por identidade de objeto, o que
+ * evita re-subscribe desnecessário em inline objects.
+ *
+ * ```tsx
+ * const { docs, loading, hasPendingWrites } = useCollection(ordersRef, {
+ *   where: [{ field: 'status', op: '==', value: 'open' }],
+ * });
+ * ```
+ *
+ * Seguro em React 18/19 StrictMode.
+ */
+declare function useCollection<T>(ref: DbCollectionRef<T>, query?: DbQuery): UseCollectionResult<T>;
+/**
+ * Hook para observar o SyncState do namespace offline.
+ *
+ * Retorna o `SyncState` atual e re-renderiza quando ele muda.
+ * Usado para renderizar indicadores "sincronizando…" ou "offline" na UI.
+ *
+ * ```tsx
+ * const state = useSyncState(ns);
+ * if (state.status === 'offline') return <OfflineBanner pending={state.pendingWrites} />;
+ * ```
+ *
+ * `ns` deve ser o namespace retornado por `createOfflineDocumentsNamespace` (ou
+ * qualquer objeto com `syncState` + `onSyncStateChanged`).
+ *
+ * Alinhado com 02-sdk.md §3.6: `useSyncState(client: NeetruClient): NeetruSyncState`.
+ * Na camada M2, aceita diretamente o namespace de documentos (`SyncStateSource`)
+ * pois o `NeetruClient.db` completo está fora do escopo do M2.
+ *
+ * Seguro em React 18/19 StrictMode.
+ */
+declare function useSyncState(ns: SyncStateSource): SyncState;
+
+export { type SyncStateSource, type UseCollectionResult, type UseDocumentResult, useCollection, useDocument, useSyncState };

package/dist/db-react.mjs

@@ -0,0 +1,112 @@
+import * as React from 'react';
+
+// src/db/react.ts
+function serializeQuery(query) {
+  if (!query) return "";
+  try {
+    return JSON.stringify(query, Object.keys(query).sort());
+  } catch {
+    return String(query);
+  }
+}
+function useDocument(ref, id) {
+  const [state, setState] = React.useState({
+    data: null,
+    loading: true,
+    fromCache: true,
+    stale: false
+  });
+  const mountedRef = React.useRef(true);
+  React.useEffect(() => {
+    mountedRef.current = true;
+    setState({ data: null, loading: true, fromCache: true, stale: false });
+    const docRef = ref.doc(id);
+    const unsubscribe = docRef.onSnapshot(
+      (snap) => {
+        if (!mountedRef.current) return;
+        if (snap === null || snap.docs.length === 0) {
+          setState({
+            data: null,
+            loading: false,
+            fromCache: snap?.fromCache ?? true,
+            stale: snap?.stale ?? false
+          });
+        } else {
+          setState({
+            data: snap.docs[0]?.data ?? null,
+            loading: false,
+            fromCache: snap.fromCache,
+            stale: snap.stale
+          });
+        }
+      }
+    );
+    return () => {
+      mountedRef.current = false;
+      unsubscribe();
+    };
+  }, [ref, id]);
+  return state;
+}
+function useCollection(ref, query) {
+  const [state, setState] = React.useState({
+    docs: [],
+    loading: true,
+    fromCache: true,
+    stale: false,
+    hasPendingWrites: false
+  });
+  const mountedRef = React.useRef(true);
+  const queryKey = serializeQuery(query);
+  React.useEffect(() => {
+    mountedRef.current = true;
+    setState({
+      docs: [],
+      loading: true,
+      fromCache: true,
+      stale: false,
+      hasPendingWrites: false
+    });
+    const unsubscribe = ref.onSnapshot(
+      query,
+      (snap) => {
+        if (!mountedRef.current) return;
+        setState({
+          docs: snap.docs,
+          loading: false,
+          fromCache: snap.fromCache,
+          stale: snap.stale,
+          hasPendingWrites: snap.hasPendingWrites
+        });
+      }
+    );
+    return () => {
+      mountedRef.current = false;
+      unsubscribe();
+    };
+  }, [ref, queryKey]);
+  return state;
+}
+function useSyncState(ns) {
+  const [state, setState] = React.useState(() => ns.syncState);
+  const mountedRef = React.useRef(true);
+  React.useEffect(() => {
+    mountedRef.current = true;
+    if (mountedRef.current) {
+      setState(ns.syncState);
+    }
+    const unsubscribe = ns.onSyncStateChanged((s) => {
+      if (!mountedRef.current) return;
+      setState(s);
+    });
+    return () => {
+      mountedRef.current = false;
+      unsubscribe();
+    };
+  }, [ns]);
+  return state;
+}
+
+export { useCollection, useDocument, useSyncState };
+//# sourceMappingURL=db-react.mjs.map
+//# sourceMappingURL=db-react.mjs.map

package/dist/db-react.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/db/react.ts"],"names":[],"mappings":";;;AAiFA,SAAS,eAAe,KAAA,EAAoC;AAC1D,EAAA,IAAI,CAAC,OAAO,OAAO,EAAA;AACnB,EAAA,IAAI;AACF,IAAA,OAAO,IAAA,CAAK,UAAU,KAAA,EAAO,MAAA,CAAO,KAAK,KAAK,CAAA,CAAE,MAAM,CAAA;AAAA,EACxD,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,OAAO,KAAK,CAAA;AAAA,EACrB;AACF;AAoBO,SAAS,WAAA,CACd,KACA,EAAA,EACsB;AACtB,EAAA,MAAM,CAAC,KAAA,EAAO,QAAQ,CAAA,GAAU,KAAA,CAAA,QAAA,CAA+B;AAAA,IAC7D,IAAA,EAAM,IAAA;AAAA,IACN,OAAA,EAAS,IAAA;AAAA,IACT,SAAA,EAAW,IAAA;AAAA,IACX,KAAA,EAAO;AAAA,GACR,CAAA;AAGD,EAAA,MAAM,UAAA,GAAmB,aAAO,IAAI,CAAA;AAEpC,EAAM,gBAAU,MAAM;AACpB,IAAA,UAAA,CAAW,OAAA,GAAU,IAAA;AAErB,IAAA,QAAA,CAAS,EAAE,MAAM,IAAA,EAAM,OAAA,EAAS,MAAM,SAAA,EAAW,IAAA,EAAM,KAAA,EAAO,KAAA,EAAO,CAAA;AAErE,IAAA,MAAM,MAAA,GAAS,GAAA,CAAI,GAAA,CAAI,EAAE,CAAA;AAEzB,IAAA,MAAM,cAA2B,MAAA,CAAO,UAAA;AAAA,MACtC,CAAC,IAAA,KAAgC;AAC/B,QAAA,IAAI,CAAC,WAAW,OAAA,EAAS;AACzB,QAAA,IAAI,IAAA,KAAS,IAAA,IAAQ,IAAA,CAAK,IAAA,CAAK,WAAW,CAAA,EAAG;AAC3C,UAAA,QAAA,CAAS;AAAA,YACP,IAAA,EAAM,IAAA;AAAA,YACN,OAAA,EAAS,KAAA;AAAA,YACT,SAAA,EAAW,MAAM,SAAA,IAAa,IAAA;AAAA,YAC9B,KAAA,EAAO,MAAM,KAAA,IAAS;AAAA,WACvB,CAAA;AAAA,QACH,CAAA,MAAO;AACL,UAAA,QAAA,CAAS;AAAA,YACP,IAAA,EAAM,IAAA,CAAK,IAAA,CAAK,CAAC,GAAG,IAAA,IAAQ,IAAA;AAAA,YAC5B,OAAA,EAAS,KAAA;AAAA,YACT,WAAW,IAAA,CAAK,SAAA;AAAA,YAChB,OAAO,IAAA,CAAK;AAAA,WACb,CAAA;AAAA,QACH;AAAA,MACF;AAAA,KACF;AAEA,IAAA,OAAO,MAAM;AACX,MAAA,UAAA,CAAW,OAAA,GAAU,KAAA;AACrB,MAAA,WAAA,EAAY;AAAA,IACd,CAAA;AAAA,EAEF,CAAA,EAAG,CAAC,GAAA,EAAK,EAAE,CAAC,CAAA;AAEZ,EAAA,OAAO,KAAA;AACT;AAmBO,SAAS,aAAA,CACd,KACA,KAAA,EACwB;AACxB,EAAA,MAAM,CAAC,KAAA,EAAO,QAAQ,CAAA,GAAU,KAAA,CAAA,QAAA,CAAiC;AAAA,IAC/D,MAAM,EAAC;AAAA,IACP,OAAA,EAAS,IAAA;AAAA,IACT,SAAA,EAAW,IAAA;AAAA,IACX,KAAA,EAAO,KAAA;AAAA,IACP,gBAAA,EAAkB;AAAA,GACnB,CAAA;AAED,EAAA,MAAM,UAAA,GAAmB,aAAO,IAAI,CAAA;AAIpC,EAAA,MAAM,QAAA,GAAW,eAAe,KAAK,CAAA;AAErC,EAAM,gBAAU,MAAM;AACpB,IAAA,UAAA,CAAW,OAAA,GAAU,IAAA;AAErB,IAAA,QAAA,CAAS;AAAA,MACP,MAAM,EAAC;AAAA,MACP,OAAA,EAAS,IAAA;AAAA,MACT,SAAA,EAAW,IAAA;AAAA,MACX,KAAA,EAAO,KAAA;AAAA,MACP,gBAAA,EAAkB;AAAA,KACnB,CAAA;AAED,IAAA,MAAM,cAA2B,GAAA,CAAI,UAAA;AAAA,MACnC,KAAA;AAAA,MACA,CAAC,IAAA,KAA0B;AACzB,QAAA,IAAI,CAAC,WAAW,OAAA,EAAS;AACzB,QAAA,QAAA,CAAS;AAAA,UACP,MAAM,IAAA,CAAK,IAAA;AAAA,UACX,OAAA,EAAS,KAAA;AAAA,UACT,WAAW,IAAA,CAAK,SAAA;AAAA,UAChB,OAAO,IAAA,CAAK,KAAA;AAAA,UACZ,kBAAkB,IAAA,CAAK;AAAA,SACxB,CAAA;AAAA,MACH;AAAA,KACF;AAEA,IAAA,OAAO,MAAM;AACX,MAAA,UAAA,CAAW,OAAA,GAAU,KAAA;AACrB,MAAA,WAAA,EAAY;AAAA,IACd,CAAA;AAAA,EAEF,CAAA,EAAG,CAAC,GAAA,EAAK,QAAQ,CAAC,CAAA;AAElB,EAAA,OAAO,KAAA;AACT;AAwBO,SAAS,aAAa,EAAA,EAAgC;AAC3D,EAAA,MAAM,CAAC,KAAA,EAAO,QAAQ,IAAU,KAAA,CAAA,QAAA,CAAoB,MAAM,GAAG,SAAS,CAAA;AAEtE,EAAA,MAAM,UAAA,GAAmB,aAAO,IAAI,CAAA;AAEpC,EAAM,gBAAU,MAAM;AACpB,IAAA,UAAA,CAAW,OAAA,GAAU,IAAA;AAGrB,IAAA,IAAI,WAAW,OAAA,EAAS;AACtB,MAAA,QAAA,CAAS,GAAG,SAAS,CAAA;AAAA,IACvB;AAEA,IAAA,MAAM,WAAA,GAA2B,EAAA,CAAG,kBAAA,CAAmB,CAAC,CAAA,KAAiB;AACvE,MAAA,IAAI,CAAC,WAAW,OAAA,EAAS;AACzB,MAAA,QAAA,CAAS,CAAC,CAAA;AAAA,IACZ,CAAC,CAAA;AAED,IAAA,OAAO,MAAM;AACX,MAAA,UAAA,CAAW,OAAA,GAAU,KAAA;AACrB,MAAA,WAAA,EAAY;AAAA,IACd,CAAA;AAAA,EAEF,CAAA,EAAG,CAAC,EAAE,CAAC,CAAA;AAEP,EAAA,OAAO,KAAA;AACT","file":"db-react.mjs","sourcesContent":["/**\r\n * Bindings React do módulo db (M2) — `@neetru/sdk/react`.\r\n *\r\n * Exporta três hooks de tempo real que se integram com a camada offline do\r\n * `@neetru/sdk/db`:\r\n *\r\n *   - `useDocument(ref, id)` — subscreve ao onSnapshot de um documento.\r\n *   - `useCollection(ref, query?)` — subscreve ao onSnapshot de uma coleção.\r\n *   - `useSyncState(ns)` — observa o SyncState do namespace offline.\r\n *\r\n * ### Design\r\n * Segue o padrão do subpath `/react` existente (cliente/ref passados\r\n * explicitamente, sem Context Provider obrigatório). Alinhado com 02-sdk.md §3.6.\r\n *\r\n * ### React 18/19 StrictMode\r\n * Cada hook usa um ref interno para rastrear se o componente foi desmontado,\r\n * e a função `useEffect` retorna sempre a função de unsubscribe. Em StrictMode,\r\n * o duplo-mount/unmount do React 18 chama cleanup corretamente — não há leak.\r\n *\r\n * ### Dependências\r\n * `react` é peer dependency — não importada como dep direta.\r\n */\r\nimport * as React from 'react';\r\nimport type { DbCollectionRef, DbDoc, DbQuery, DbListResult, DbGetResult } from './collection-ref';\r\nimport type { SyncState, Unsubscribe } from './offline/types';\r\n\r\n// ─── Tipos públicos dos hooks ─────────────────────────────────────────────────\r\n\r\n/**\r\n * Resultado de `useDocument`.\r\n *\r\n * - `data` — dados do documento, ou `null` se não existe / ainda carregando.\r\n * - `loading` — `true` enquanto o primeiro snapshot não foi entregue.\r\n * - `fromCache` — o snapshot veio do cache local, não do servidor.\r\n * - `stale` — conexão caída ou sincronizando; pode haver dados mais novos.\r\n */\r\nexport interface UseDocumentResult<T> {\r\n  data: T | null;\r\n  loading: boolean;\r\n  fromCache: boolean;\r\n  stale: boolean;\r\n}\r\n\r\n/**\r\n * Resultado de `useCollection`.\r\n *\r\n * - `docs` — documentos da coleção (ou subconjunto via query).\r\n * - `loading` — `true` enquanto o primeiro snapshot não foi entregue.\r\n * - `fromCache` — o snapshot veio do cache local.\r\n * - `stale` — conexão caída ou sincronizando.\r\n * - `hasPendingWrites` — ao menos um doc tem escrita local não confirmada.\r\n */\r\nexport interface UseCollectionResult<T> {\r\n  docs: DbDoc<T>[];\r\n  loading: boolean;\r\n  fromCache: boolean;\r\n  stale: boolean;\r\n  hasPendingWrites: boolean;\r\n}\r\n\r\n/**\r\n * Subconjunto mínimo do namespace offline que `useSyncState` precisa.\r\n * Compatível com `NeetruDbDocuments` de `collection-ref.ts`.\r\n *\r\n * Passado explicitamente (sem Context) para alinhar com o padrão do SDK.\r\n * Tipicamente: o namespace retornado por `createOfflineDocumentsNamespace`.\r\n */\r\nexport interface SyncStateSource {\r\n  readonly syncState: SyncState;\r\n  onSyncStateChanged(cb: (s: SyncState) => void): Unsubscribe;\r\n}\r\n\r\n// ─── Serialização estável de query ────────────────────────────────────────────\r\n\r\n/**\r\n * Serializa uma DbQuery para string estável, usada como chave de efeito.\r\n *\r\n * `useCollection` re-subscreve somente quando a serialização muda, NÃO por\r\n * identidade de objeto. Isso evita a armadilha clássica de inline-object em\r\n * JSX que causaria re-subscribe em todo render.\r\n */\r\nfunction serializeQuery(query: DbQuery | undefined): string {\r\n  if (!query) return '';\r\n  try {\r\n    return JSON.stringify(query, Object.keys(query).sort());\r\n  } catch {\r\n    return String(query);\r\n  }\r\n}\r\n\r\n// ─── useDocument ─────────────────────────────────────────────────────────────\r\n\r\n/**\r\n * Hook de tempo real para um documento específico.\r\n *\r\n * Subscreve a `ref.doc(id).onSnapshot` no mount. Re-subscreve quando `ref`\r\n * ou `id` mudam. Cancela a subscrição no unmount.\r\n *\r\n * ```tsx\r\n * const { data, loading, fromCache, stale } = useDocument(ordersRef, orderId);\r\n * if (loading) return <Spinner />;\r\n * if (!data) return <NotFound />;\r\n * return <OrderCard order={data} fromCache={fromCache} />;\r\n * ```\r\n *\r\n * Seguro em React 18/19 StrictMode: a cleanup function do useEffect cancela\r\n * o listener no unmount, e o double-mount do StrictMode não vaza estado.\r\n */\r\nexport function useDocument<T>(\r\n  ref: DbCollectionRef<T>,\r\n  id: string,\r\n): UseDocumentResult<T> {\r\n  const [state, setState] = React.useState<UseDocumentResult<T>>({\r\n    data: null,\r\n    loading: true,\r\n    fromCache: true,\r\n    stale: false,\r\n  });\r\n\r\n  // Ref para detectar unmount e evitar setState após cleanup.\r\n  const mountedRef = React.useRef(true);\r\n\r\n  React.useEffect(() => {\r\n    mountedRef.current = true;\r\n    // Reset para loading quando ref/id muda\r\n    setState({ data: null, loading: true, fromCache: true, stale: false });\r\n\r\n    const docRef = ref.doc(id);\r\n\r\n    const unsubscribe: Unsubscribe = docRef.onSnapshot(\r\n      (snap: DbGetResult<T> | null) => {\r\n        if (!mountedRef.current) return;\r\n        if (snap === null || snap.docs.length === 0) {\r\n          setState({\r\n            data: null,\r\n            loading: false,\r\n            fromCache: snap?.fromCache ?? true,\r\n            stale: snap?.stale ?? false,\r\n          });\r\n        } else {\r\n          setState({\r\n            data: snap.docs[0]?.data ?? null,\r\n            loading: false,\r\n            fromCache: snap.fromCache,\r\n            stale: snap.stale,\r\n          });\r\n        }\r\n      },\r\n    );\r\n\r\n    return () => {\r\n      mountedRef.current = false;\r\n      unsubscribe();\r\n    };\r\n    // eslint-disable-next-line react-hooks/exhaustive-deps\r\n  }, [ref, id]);\r\n\r\n  return state;\r\n}\r\n\r\n// ─── useCollection ────────────────────────────────────────────────────────────\r\n\r\n/**\r\n * Hook de tempo real para uma coleção (ou subconjunto filtrado).\r\n *\r\n * Subscreve a `ref.onSnapshot(query, cb)` no mount. Re-subscreve quando `ref`\r\n * ou a serialização de `query` muda — NÃO por identidade de objeto, o que\r\n * evita re-subscribe desnecessário em inline objects.\r\n *\r\n * ```tsx\r\n * const { docs, loading, hasPendingWrites } = useCollection(ordersRef, {\r\n *   where: [{ field: 'status', op: '==', value: 'open' }],\r\n * });\r\n * ```\r\n *\r\n * Seguro em React 18/19 StrictMode.\r\n */\r\nexport function useCollection<T>(\r\n  ref: DbCollectionRef<T>,\r\n  query?: DbQuery,\r\n): UseCollectionResult<T> {\r\n  const [state, setState] = React.useState<UseCollectionResult<T>>({\r\n    docs: [],\r\n    loading: true,\r\n    fromCache: true,\r\n    stale: false,\r\n    hasPendingWrites: false,\r\n  });\r\n\r\n  const mountedRef = React.useRef(true);\r\n\r\n  // Serializamos a query para garantir que mudanças de valor (não de referência)\r\n  // triggam o re-subscribe, mas que objetos iguais não causem loop.\r\n  const queryKey = serializeQuery(query);\r\n\r\n  React.useEffect(() => {\r\n    mountedRef.current = true;\r\n    // Reset loading ao trocar de query/ref\r\n    setState({\r\n      docs: [],\r\n      loading: true,\r\n      fromCache: true,\r\n      stale: false,\r\n      hasPendingWrites: false,\r\n    });\r\n\r\n    const unsubscribe: Unsubscribe = ref.onSnapshot(\r\n      query,\r\n      (snap: DbListResult<T>) => {\r\n        if (!mountedRef.current) return;\r\n        setState({\r\n          docs: snap.docs,\r\n          loading: false,\r\n          fromCache: snap.fromCache,\r\n          stale: snap.stale,\r\n          hasPendingWrites: snap.hasPendingWrites,\r\n        });\r\n      },\r\n    );\r\n\r\n    return () => {\r\n      mountedRef.current = false;\r\n      unsubscribe();\r\n    };\r\n    // eslint-disable-next-line react-hooks/exhaustive-deps\r\n  }, [ref, queryKey]);\r\n\r\n  return state;\r\n}\r\n\r\n// ─── useSyncState ─────────────────────────────────────────────────────────────\r\n\r\n/**\r\n * Hook para observar o SyncState do namespace offline.\r\n *\r\n * Retorna o `SyncState` atual e re-renderiza quando ele muda.\r\n * Usado para renderizar indicadores \"sincronizando…\" ou \"offline\" na UI.\r\n *\r\n * ```tsx\r\n * const state = useSyncState(ns);\r\n * if (state.status === 'offline') return <OfflineBanner pending={state.pendingWrites} />;\r\n * ```\r\n *\r\n * `ns` deve ser o namespace retornado por `createOfflineDocumentsNamespace` (ou\r\n * qualquer objeto com `syncState` + `onSyncStateChanged`).\r\n *\r\n * Alinhado com 02-sdk.md §3.6: `useSyncState(client: NeetruClient): NeetruSyncState`.\r\n * Na camada M2, aceita diretamente o namespace de documentos (`SyncStateSource`)\r\n * pois o `NeetruClient.db` completo está fora do escopo do M2.\r\n *\r\n * Seguro em React 18/19 StrictMode.\r\n */\r\nexport function useSyncState(ns: SyncStateSource): SyncState {\r\n  const [state, setState] = React.useState<SyncState>(() => ns.syncState);\r\n\r\n  const mountedRef = React.useRef(true);\r\n\r\n  React.useEffect(() => {\r\n    mountedRef.current = true;\r\n\r\n    // Snapshot inicial imediato ao montar (pode ter mudado entre render e effect)\r\n    if (mountedRef.current) {\r\n      setState(ns.syncState);\r\n    }\r\n\r\n    const unsubscribe: Unsubscribe = ns.onSyncStateChanged((s: SyncState) => {\r\n      if (!mountedRef.current) return;\r\n      setState(s);\r\n    });\r\n\r\n    return () => {\r\n      mountedRef.current = false;\r\n      unsubscribe();\r\n    };\r\n    // eslint-disable-next-line react-hooks/exhaustive-deps\r\n  }, [ns]);\r\n\r\n  return state;\r\n}\r\n"]}