@neetru/sdk 1.1.1 → 2.1.0

package/dist/collection-ref-BBvTTXoG.d.ts

@@ -0,0 +1,423 @@
+/**
+ * Tipos internos da camada offline do @neetru/sdk.
+ *
+ * Estes tipos SÃO internos ao módulo `db/offline/` — não fazem parte da
+ * superfície pública do SDK. A superfície pública é o `DbCollectionRef` e
+ * o `DbSnapshot` de `src/types.ts`.
+ *
+ * Derivados de:
+ *   - I3-sdk-offline.md §3 (store schemas)
+ *   - I3-sdk-offline.md §4 (fila de escritas)
+ *   - I3-sdk-offline.md §5 (query descriptor)
+ *   - I3-sdk-offline.md §7 (conflito LWW)
+ *   - 02-sdk.md §3.2 (DbSnapshot, DbWhereFilter, DbQuery)
+ */
+/** Identificador de um documento (string opaca). */
+type DocId = string;
+/** Identificador de uma mutação (UUID v4 client-generated). */
+type MutationId = string;
+/** Operações possíveis na fila de escritas. */
+type MutationKind = 'add' | 'set' | 'update' | 'remove';
+/**
+ * Uma mutação enfileirada (escrita durável pendente).
+ * Equivalente a `QueuedMutation` do I3 §3.3 (`mutations` store).
+ */
+interface Mutation {
+    /** Número de sequência autoincrement — define a ordem total da fila. */
+    seq: number;
+    /** UUID v4 client-generated — chave de idempotência. */
+    mutationId: MutationId;
+    /** Nome da coleção. */
+    collection: string;
+    /** ID do documento alvo (client-gen para `add`, existente para os demais). */
+    docId: DocId;
+    /** Operação. */
+    op: MutationKind;
+    /** Dados da operação. `null` para `remove`. */
+    payload: Record<string, unknown> | null;
+    /**
+     * `serverVersion` que o cliente viu ao escrever.
+     * `null` para `add` (doc não existia) ou quando o cliente nunca sincronizou.
+     * Usado pelo servidor para detectar conflito (I3 §7.4).
+     */
+    baseVersion: string | null;
+    /** Epoch ms do relógio do CLIENTE — só para diagnóstico e ordenação local. */
+    enqueuedAt: number;
+    /** Número de tentativas de replay. */
+    attempts: number;
+    /** Último erro de replay (string). `null` se nenhuma tentativa ainda. */
+    lastError: string | null;
+    /** Estado de envio desta mutação. */
+    status: 'queued' | 'inflight' | 'failed';
+    /** Agrupa mutações de um `batch()` atômico. `null` se mutação individual. */
+    batchId: string | null;
+}
+/**
+ * Razão pela qual uma escrita foi descartada no LWW (I3 §3.3 `conflict_log`).
+ */
+type ConflictReason = 'lww_server_newer' | 'rejected_permission' | 'rejected_validation';
+/**
+ * Registro de uma escrita perdedora — gravado no `conflict_log` (I3 §3.3).
+ * Entregue ao produto via `onWriteResult` (status: `'superseded'`).
+ */
+interface ConflictRecord {
+    id?: number;
+    collection: string;
+    docId: DocId;
+    mutationId: MutationId;
+    losingData: Record<string, unknown>;
+    winningData: Record<string, unknown>;
+    reason: ConflictReason;
+    detectedAt: number;
+    delivered: boolean;
+}
+/**
+ * Estado de sincronização da camada offline (I3 §10 / 02-sdk §3.4).
+ * Exposto em `client.db.syncState`.
+ *
+ * - `idle`    — online e em repouso (sem sync ativo).
+ * - `syncing` — sync em progresso (push + pull + realtime).
+ * - `offline` — conexão perdida ou inexistente.
+ * - `error`   — erro persistente após retries (reservado para uso futuro).
+ */
+type SyncStatus = 'idle' | 'offline' | 'syncing' | 'error';
+interface SyncState {
+    status: SyncStatus;
+    pendingWrites: number;
+    lastSyncedAt: number | null;
+    isLeaderTab: boolean;
+}
+/** Função para cancelar uma subscrição (onSnapshot, onDoc, onSyncStateChanged). */
+type Unsubscribe = () => void;
+
+/**
+ * SyncEngine — orquestrador da camada offline do @neetru/sdk.
+ *
+ * Implementa as 3 fases de sincronização definidas em I3 §6:
+ *
+ *   FASE 1 — DRENAR A FILA (push)
+ *     Envia mutações pendentes ao Core via SyncTransport.
+ *     Cada mutação é marcada inflight, enviada e depois:
+ *       - CONFIRMADA    → removida da fila (markApplied)
+ *       - SUPERADA (LWW)→ ConflictRecord gravado, cache atualizado
+ *       - REJEITADA     → resolveRejected + ConflictRecord + removida
+ *       - FALHA TRANSIENTE → markRetry + PARA a drenagem (ordem preservada)
+ *
+ *   FASE 2 — RECONCILIAR O CACHE (pull)
+ *     Busca mudanças do servidor desde o watermark ou resume token.
+ *     Cada documento passa pelo ConflictResolver (LWW) e é gravado no LocalStore.
+ *     Changes são emitidos pelo ChangeBus.
+ *     Se `resyncRequired` → aciona full resync em vez de pull incremental.
+ *
+ *   FASE 3 — REABRIR LISTENERS (realtime)
+ *     Atualiza SyncState para refletir que o cache está reconciliado.
+ *     O ChangeBus já foi alimentado nas fases anteriores — os listeners
+ *     ativos na camada superior (onSnapshot/onDoc) recebem snapshots frescos.
+ *
+ * Garantias:
+ *   - SOMENTE a aba LÍDER executa o sync (TabCoordinator.isLeader()).
+ *   - Re-entrante-safe: um sync em progresso bloqueia novos disparos.
+ *   - Fail-closed: falha transiente retém a mutação; falha de pull não
+ *     corrompe o cache nem o watermark.
+ *   - Idempotente: o SyncTransport usa mutationId como chave de idempotência.
+ *
+ * O SyncTransport é INJETADO — a ligação real com o Core acontece na camada
+ * de adaptação, não aqui. Isso torna o SyncEngine 100% testável com fake.
+ */
+
+/**
+ * Documento retornado pelo servidor em push/pull/resync.
+ */
+interface ServerDoc {
+    collection: string;
+    id: string;
+    data: Record<string, unknown>;
+    serverVersion: string;
+    serverTimestamp: number;
+    /** `true` se o doc foi deletado no servidor. */
+    deleted: boolean;
+}
+/**
+ * Resultado individual de uma mutação enviada ao Core (FASE 1).
+ */
+type MutationResult = {
+    mutationId: string;
+    outcome: 'confirmed';
+    serverVersion: string;
+    serverTimestamp: number;
+} | {
+    mutationId: string;
+    outcome: 'superseded';
+    serverVersion: string;
+    serverTimestamp: number;
+    serverData: Record<string, unknown>;
+} | {
+    mutationId: string;
+    outcome: 'rejected';
+    reason: 'rejected_permission' | 'rejected_validation';
+    serverVersion: string | null;
+    serverData: Record<string, unknown> | null;
+};
+/** Retorno de pushMutations. */
+interface PushMutationsResult {
+    results: MutationResult[];
+}
+/** Retorno de pullChanges. */
+interface PullChangesResult {
+    docs: ServerDoc[];
+    newWatermark: number | null;
+    /** `true` quando o resume token / watermark ficou inválido (gap grande). */
+    resyncRequired: boolean;
+}
+/** Retorno de fullResync. */
+interface FullResyncResult {
+    docs: ServerDoc[];
+    newWatermark: number | null;
+}
+/**
+ * Contrato do transporte de sync — injetado no SyncEngine.
+ *
+ * A implementação real usa os endpoints `/api/sdk/v1/db/*` do Core.
+ * Em testes, usa-se um FakeSyncTransport.
+ *
+ * Per I3 §6:
+ *   - `pushMutations`  → FASE 1: envia mutações em ordem de seq.
+ *   - `pullChanges`    → FASE 2: busca delta desde o watermark/resumeToken.
+ *   - `fullResync`     → FASE 2 (fallback): lista completa das coleções ativas.
+ */
+interface SyncTransport {
+    /**
+     * Envia um lote de mutações ao Core.
+     * O Core aplica, verifica conflito LWW e retorna um resultado por mutação.
+     * A ordem do array deve ser preservada (seq crescente).
+     */
+    pushMutations(mutations: Mutation[]): Promise<PushMutationsResult>;
+    /**
+     * Busca documentos modificados no servidor desde `sinceWatermark`.
+     * `sinceWatermark === null` indica primeiro sync (sem base conhecida).
+     * `resumeToken` é o token de change stream (nosql-vm); pode ser null.
+     *
+     * Retorna `resyncRequired: true` se o gap é grande demais para pull incremental.
+     */
+    pullChanges(sinceWatermark: number | null, resumeToken: string | null): Promise<PullChangesResult>;
+    /**
+     * Faz um full resync das coleções informadas.
+     * Retorna TODOS os documentos atuais (paginado internamente pelo transporte).
+     * Docs ausentes na resposta foram deletados durante o gap.
+     */
+    fullResync(collections: string[]): Promise<FullResyncResult>;
+    /**
+     * (Opcional) Registra uma subscription realtime para uma coleção específica.
+     *
+     * Implementado pelo WebSocket transport (nosql-vm): chama
+     * `NeetruRealtimeClient.subscribe()` e alimenta os frames delta/resync
+     * no `ChangeBus` da camada offline.
+     *
+     * Transportes REST e Firestore não implementam este método (undefined).
+     * O chamador (`DbCollectionRefImpl.onSnapshot`) verifica antes de invocar.
+     *
+     * @param collection - Nome da coleção a subscrever.
+     * @param onChange   - Callback que recebe changes quando um delta/resync chega.
+     *                     `null` payload = resync full necessário.
+     * @returns Função de unsubscribe.
+     */
+    subscribeCollection?: (collection: string, onChange: (changes: Array<{
+        type: 'added' | 'modified' | 'removed';
+        docId: string;
+        data: Record<string, unknown> | null;
+    }>, needsResync: boolean) => void) => () => void;
+}
+
+/**
+ * DbCollectionRef — superfície de Documentos offline-first do @neetru/sdk (M2).
+ *
+ * Implementa a API pública conforme especificada em:
+ *   - 02-sdk.md §3.2 (contrato TypeScript DbCollectionRef)
+ *   - I2-mundo-documentos.md §3.2 (superfície dupla CRUD + realtime)
+ *   - I3-sdk-offline.md §10 (camada offline, lifecycle, SyncState)
+ *
+ * ### Semântica de Promise de escrita (02-sdk.md §3.2 nota negrito)
+ * `add/set/update/remove` resolvem quando a escrita está **durável localmente**
+ * (cache + fila), NÃO quando o servidor confirma. Isso é offline-first por design:
+ * sem rede, `add()` resolve imediatamente. Para saber quando sincronizou, o produto
+ * observa `onWriteResult` (future / SyncEngine). A Promise só rejeita por:
+ * - validação síncrona (nome de coleção inválido, id vazio)
+ * - `offline_quota_exceeded` (IndexedDB cheio)
+ *
+ * ### Injeção do transporte realtime
+ * O `RealtimeTransport` é injetado via `createOfflineDocumentsNamespace({ transport })`.
+ * A implementação atual usa o `SyncEngine` para push/pull (sync offline ↔ servidor).
+ * Transportes futuros (Firestore Web SDK / WebSocket gateway) são injetados aqui —
+ * sem alterar a superfície pública.
+ */
+
+interface DbWhereFilter {
+    field: string;
+    op: '==' | '!=' | '<' | '<=' | '>' | '>=' | 'array-contains' | 'in' | 'not-in';
+    value: unknown;
+}
+interface DbQuery {
+    where?: DbWhereFilter[];
+    orderBy?: {
+        field: string;
+        direction?: 'asc' | 'desc';
+    };
+    /** Máximo de documentos. Default 20, max 500. */
+    limit?: number;
+    /** Cursor opaco — devolvido em `DbListResult.nextCursor`. */
+    cursor?: string;
+}
+interface DbDoc<T = Record<string, unknown>> {
+    id: string;
+    data: T;
+}
+interface DbListResult<T = Record<string, unknown>> {
+    docs: DbDoc<T>[];
+    nextCursor: string | null;
+    fromCache: boolean;
+    stale: boolean;
+    hasPendingWrites: boolean;
+    changes: Array<{
+        type: 'added' | 'modified' | 'removed';
+        doc: DbDoc<T>;
+    }>;
+}
+interface DbGetResult<T = Record<string, unknown>> {
+    docs: Array<DbDoc<T>>;
+    fromCache: boolean;
+    stale: boolean;
+    hasPendingWrites: boolean;
+    changes: Array<{
+        type: 'added' | 'modified' | 'removed';
+        doc: DbDoc<T>;
+    }>;
+}
+type DbChangeType = 'added' | 'modified' | 'removed';
+interface DbBatchOp {
+    op: 'add' | 'set' | 'update' | 'remove';
+    collection: string;
+    id?: string;
+    data?: Record<string, unknown>;
+}
+/**
+ * Contrato do transporte de realtime — injetado no namespace.
+ *
+ * A implementação real usa os endpoints `/api/sdk/v1/db/*` do Core.
+ * Em testes, usa-se um fake in-memory.
+ *
+ * Este é o **seam de injeção** que conecta a camada offline ao servidor real.
+ * Transportes futuros (Firestore Web SDK direto / WebSocket gateway) são
+ * implementados aqui, sem modificar a superfície pública `DbCollectionRef`.
+ */
+type RealtimeTransport = SyncTransport;
+/**
+ * Referência a um documento específico.
+ * Parte da superfície `DbCollectionRef.doc(id)`.
+ */
+interface DbDocRef<T = Record<string, unknown>> {
+    get(): Promise<DbGetResult<T> | null>;
+    set(data: Omit<T, 'id'>): Promise<{
+        ok: true;
+    }>;
+    update(data: Partial<Omit<T, 'id'>>): Promise<{
+        ok: true;
+    }>;
+    remove(): Promise<{
+        ok: true;
+    }>;
+    onSnapshot(cb: (snap: DbGetResult<T> | null) => void): Unsubscribe;
+}
+/**
+ * Referência a uma coleção — superfície dupla CRUD + realtime.
+ *
+ * Conforme 02-sdk.md §3.2 / I2 §3.2.
+ */
+interface DbCollectionRef<T = Record<string, unknown>> {
+    /** Retorna snapshot de um documento. `null` se não existir (nem no cache). */
+    get(id: string): Promise<DbGetResult<T> | null>;
+    /** Lista documentos com query opcional. */
+    list(q?: DbQuery): Promise<DbListResult<T>>;
+    /** Adiciona doc com id gerado pelo cliente (UUID v4). Durável localmente. */
+    add(data: Omit<T, 'id'>): Promise<{
+        ok: true;
+        id: string;
+    }>;
+    /** Cria ou sobrescreve um doc pelo id. Durável localmente. */
+    set(id: string, data: Omit<T, 'id'>): Promise<{
+        ok: true;
+    }>;
+    /** Atualiza campos de um doc (merge). Durável localmente. */
+    update(id: string, data: Partial<Omit<T, 'id'>>): Promise<{
+        ok: true;
+    }>;
+    /** Remove um doc (tombstone local). Durável localmente. */
+    remove(id: string): Promise<{
+        ok: true;
+    }>;
+    /** Aplica múltiplas operações atomicamente na fila. */
+    batch(ops: DbBatchOp[]): Promise<{
+        ok: true;
+    }>;
+    /** Escuta um documento específico. */
+    onDoc(id: string, cb: (doc: T | null) => void): Unsubscribe;
+    /** Escuta a coleção inteira (ou subconjunto via query). */
+    onSnapshot(q: DbQuery | undefined, cb: (snap: DbListResult<T>) => void): Unsubscribe;
+    /** Retorna uma referência ao documento `id`. */
+    doc(id: string): DbDocRef<T>;
+}
+/**
+ * Namespace `db.documents` — ponto de entrada para coleções de documentos.
+ *
+ * Analogia a `NeetruDb` de 02-sdk.md §3.1 mas escoped para o Mundo Documentos.
+ */
+interface NeetruDbDocuments {
+    collection<T = Record<string, unknown>>(name: string): DbCollectionRef<T>;
+    /** Estado atual de sincronização (offline/online/syncing). */
+    readonly syncState: SyncState;
+    onSyncStateChanged(cb: (s: SyncState) => void): Unsubscribe;
+    /** Força flush da fila de mutações pendentes. */
+    flush(): Promise<void>;
+    /** Limpa o cache local (IndexedDB) — operação destrutiva. */
+    clearCache(): Promise<void>;
+    /**
+     * Retorna os registros do log de conflitos LWW gravados pelo SyncEngine.
+     * Um conflito ocorre quando a mutação local é descartada porque o servidor
+     * já avançou a versão do documento (Last-Write-Wins).
+     */
+    getConflicts(): Promise<ConflictRecord[]>;
+}
+interface CreateOfflineDocumentsOptions {
+    /**
+     * Nome do banco IndexedDB — deve ser único por produto × dbId × env.
+     * Convenção: `neetru-db__{productSlug}__{dbId}__{env}`.
+     */
+    dbName: string;
+    /**
+     * Transporte de sync — implementa `SyncTransport` do SyncEngine.
+     * Este é o **seam de injeção** do transporte real.
+     *
+     * Implementações possíveis:
+     *   - `RestSyncTransport`      — REST → Core (padrão em staging/prod)
+     *   - `FirestoreRealtimeTransport` — Firestore Web SDK direto (engine=firestore)
+     *   - `WebSocketTransport`     — WebSocket → gateway (engine=nosql-vm)
+     *   - `FakeRealtimeTransport`  — in-memory (testes)
+     */
+    transport: RealtimeTransport;
+    /**
+     * Estado inicial de conectividade.
+     * Default: `navigator.onLine` se disponível, senão `true`.
+     */
+    startOnline?: boolean;
+    /**
+     * `true` = sem contenção multi-aba (sempre líder).
+     * Padrão em testes; em produção usa Web Locks.
+     */
+    singleTab?: boolean;
+    /**
+     * Intervalo do sync periódico em ms. `0` desativa.
+     * Default: 5 * 60 * 1000 (5min).
+     */
+    periodicSyncIntervalMs?: number;
+}
+
+export type { ConflictRecord as C, DbBatchOp as D, NeetruDbDocuments as N, RealtimeTransport as R, SyncState as S, Unsubscribe as U, CreateOfflineDocumentsOptions as a, DbChangeType as b, DbCollectionRef as c, DbDoc as d, DbDocRef as e, DbGetResult as f, DbListResult as g, DbQuery as h, DbWhereFilter as i };

package/dist/db-react.cjs

@@ -0,0 +1,136 @@
+'use strict';
+
+var React = require('react');
+
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+
+var React__namespace = /*#__PURE__*/_interopNamespace(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__namespace.useState({
+    data: null,
+    loading: true,
+    fromCache: true,
+    stale: false
+  });
+  const mountedRef = React__namespace.useRef(true);
+  React__namespace.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__namespace.useState({
+    docs: [],
+    loading: true,
+    fromCache: true,
+    stale: false,
+    hasPendingWrites: false
+  });
+  const mountedRef = React__namespace.useRef(true);
+  const queryKey = serializeQuery(query);
+  React__namespace.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__namespace.useState(() => ns.syncState);
+  const mountedRef = React__namespace.useRef(true);
+  React__namespace.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;
+}
+
+exports.useCollection = useCollection;
+exports.useDocument = useDocument;
+exports.useSyncState = useSyncState;
+//# sourceMappingURL=db-react.cjs.map
+//# sourceMappingURL=db-react.cjs.map

package/dist/db-react.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/db/react.ts"],"names":["React"],"mappings":"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","file":"db-react.cjs","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"]}

package/dist/db-react.d.cts

@@ -0,0 +1,99 @@
+import { S as SyncState, U as Unsubscribe, d as DbDoc, c as DbCollectionRef, h as DbQuery } from './collection-ref-BBvTTXoG.cjs';
+
+/**
+ * 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 };