Give ShapeStream ability to pause

[KyleAMathews]

This could be used manually by people but also a few APIs have come up:

• expose an enabled option in useShape so people could toggle the stream long polling on and off https://tanstack.com/query/latest/docs/framework/react/guides/disabling-queries
• auto-pause long polling from useShape after the user has been inactive for so long and reactivate it when the user is active again

[Alwurts]

This would be so great, it would allow us to create simpler layouts when using the useShape hook

[KyleAMathews]

@Alwurts simpler layouts meaning smaller shapes? Curious to hear more!

[Alwurts]

I meant simpler React components layouts.

The useShape hook starts syncing data right away, so you need separate components if you want to wait before syncing (e.g., until some data that you want to sync is created). Adding an enabled prop would let you pause syncing until you're ready, allowing one component instead of two. This cuts down on repeated code and makes things like animations easier.

Short example

Without enabled prop in useShape

import React, { useState } from 'react';
import { createChat } from './api';
import { useShape } from '@electric-sql/react';

function ChatInitiation({ onChatCreated }) {
  const [message, setMessage] = useState('');

  const handleSubmit = async () => {
    const chatId = await createChat(message);
    onChatCreated(chatId);
  };

  return (
    <div>
      <input value={message} onChange={(e) => setMessage(e.target.value)} />
      <button onClick={handleSubmit}>Start Chat</button>
    </div>
  );
}

function ChatConversation({ chatId }) {
  const { data: messages } = useShape({
    url,
    params: {
    	table: "message",
    	where: `"chatId" = '${chatId}'`,
    },
  });

  return (
    <div>
      {messages.map((msg) => (
        <div key={msg.id}>{msg.content}</div>
      ))}
      {/* Input would be duplicated here for sending messages */}
    </div>
  );
}

function ParentComponent() {
  const [chatId, setChatId] = useState(null);

  return chatId ? (
    <ChatConversation chatId={chatId} />
  ) : (
    <ChatInitiation onChatCreated={setChatId} />
  );
  // Note: Switching components complicates animations and state sharing
}

With enabled prop

import React, { useState } from 'react';
import { useShape } from '@electric-sql/react';
import { createChat } from './api';

function ChatRoom() {
  const [chatId, setChatId] = useState(null);
  const [message, setMessage] = useState('');

  const { data: messages } = useShape({
    url,
    params: {
    	table: "message",
    	where: `"chatId" = '${chatId}'`,
    },
    enabled: !!chatId, // Syncs only when chatId is set
  });

  const handleSubmit = async () => {
    if (!chatId) {
      const newChatId = await createChat(message);
      setChatId(newChatId);
    }
    setMessage('');
  };

  return (
    <div>
      {chatId && messages && messages.map((msg) => (
        <div key={msg.id}>{msg.content}</div>
      ))}
      {/* Single input for both starting and continuing the chat */}
      <input value={message} onChange={(e) => setMessage(e.target.value)} />
      <button onClick={handleSubmit}>Send</button>
      {/* Note: Easier to animate message list appearance */}
    </div>
  );
}

[KyleAMathews]

Ah ok I see. Yeah I generally do more waterfall stuff like this in loaders 🤔

[sudoskys]

This problem has been bothering me for a long time. I don't know how to effectively control the data flow.
I need to carry the token returned by the authentication API, but shape always takes precedence over all processes, and then it reports an error and gets stuck

[KyleAMathews]

@sudoskys not sure what "but shape always takes precedence over all processes" means?

What do you think about the proposed solutions?

[sudoskys]

I've currently achieved a good practice using conditional rendering and react-query in conjunction. I avoid using null fallbacks anywhere.

It can now wait for authentication with the backend to complete before launching the real-time UI.
However, I think it would be convenient if there was a way to control the pause query.

 * function MyPage() {
 *   const { canRenderData, shapeToken, isTokenLoading, tokenError } = useConversationsWithAuth();
 *   
 *   if (isTokenLoading) return <Loading />;
 *   if (tokenError) return <Error error={tokenError} />;
 *   
 *   return (
 *     <div>
 *       {canRenderData && shapeToken && (
 *         <MyDataComponent shapeToken={shapeToken} />
 *       )}
 *     </div>
 *   );
 * }
 * 
 * function MyDataComponent({ shapeToken }: { shapeToken: string }) {
 *   const { data, isLoading, error } = useConversationsShape(shapeToken);
 *   // ...Render
 * }

[sudoskys]

https://electric-sql.com/docs/api/clients/typescript
I found some documentation, sorry, I should have read more