deepspace 0.4.4 → 0.5.0

package/dist/index.d.ts

@@ -5489,6 +5489,19 @@ interface RecordProviderProps {
  * Uses external store pattern for React integration.
  */
 
+/**
+ * Immutable snapshot handed to `useSyncExternalStore`. A new object is minted
+ * on every state transition (see `commit`), so a change to `status`/`error` —
+ * not just `records` — flips the snapshot reference and re-renders the hook.
+ * Without `status`/`error` in the snapshot, an error that arrives before the
+ * first result (records reference unchanged) never propagates and the UI is
+ * stuck in "loading" forever.
+ */
+interface QuerySnapshot {
+    status: 'loading' | 'ready' | 'error';
+    records: RecordData[];
+    error?: string;
+}
 declare class RecordStore {
     private queries;
     private listeners;
@@ -5497,9 +5510,12 @@ declare class RecordStore {
     /** Track the single subscriptionId per queryKey (for deduplication) */
     private activeSubscriptions;
     subscribe(queryKey: string, listener: () => void): () => void;
-    getSnapshot(queryKey: string): RecordData[];
-    getStatus(queryKey: string): 'loading' | 'ready' | 'error';
-    getError(queryKey: string): string | undefined;
+    /**
+     * Snapshot for `useSyncExternalStore`. Bundles records + status + error so a
+     * transition in any of them re-renders the hook. Returns a stable reference
+     * until the next `commit()`.
+     */
+    getSnapshot(queryKey: string): QuerySnapshot;
     /**
      * Initialize a query subscription.
      * Returns true if this is the FIRST subscriber (should send SUBSCRIBE).
@@ -5514,6 +5530,12 @@ declare class RecordStore {
     setSubscriptionId(queryKey: string, subscriptionId: string): void;
     /** Get the subscriptionId for a queryKey */
     getSubscriptionId(queryKey: string): string | undefined;
+    /**
+     * Replace the state for a query with a fresh snapshot and bump the version,
+     * then notify listeners. Single write-path so every mutator mints a new
+     * snapshot reference (which is what drives `useSyncExternalStore` re-renders).
+     */
+    private commit;
     setQueryResult(queryKey: string, records: RecordData[]): void;
     /** Check if a record exists in a query's results */
     hasRecord(queryKey: string, recordId: string): boolean;
@@ -5596,8 +5618,13 @@ declare function useRecordContext(): RecordContextValue;
  * </RecordProvider>
  * ```
  */
-declare function RecordProvider({ roomId, schemas, wsUrl, children, allowAnonymous, getAuthToken: getAuthTokenProp, }: {
+declare function RecordProvider({ roomId, wsUrl, children, allowAnonymous, getAuthToken: getAuthTokenProp, }: {
     roomId?: string;
+    /**
+     * Accepted for API compatibility with `RecordScope` and documented usage,
+     * but the single-scope backward-compat provider does no local-first
+     * registration, so it's ignored. Pass schemas to `RecordScope` instead.
+     */
     schemas?: CollectionSchema[];
     wsUrl?: string;
     children: ReactNode;