メインコンテンツまでスキップ

React SDK

Squid を React と統合するためのライブラリです。

SDK Version

最新の安定版

機能​

  • Squid Client の collection、document、query にアクセスするための hooks。
  • React コンポーネント内のどこからでも Squid Client にアクセスできる provider。

はじめに​

要件​

この SDK には、React 16.11 以上が必要です。

インストール​

NPM を使用して Squid React SDK をインストールします:

npm install @squidcloud/react

Squid の設定​

  1. Squid Console に移動して Create application をクリックし、Application を作成します。

  2. 新しい Application の overview タブから Application ID をコピーします。

  3. 次の provider を React アプリケーションに追加します:

// main.tsx

import { SquidContextProvider } from '@squidcloud/react';
import ReactDOM from 'react-dom/client';
import App from './App';

const root = ReactDOM.createRoot(document.getElementById('root'));

root.render(
  <SquidContextProvider
    options={{
      appId: '<SQUID_CLOUD_APP_ID>',
      region: '<SQUID_CLOUD_REGION>',
    }}
  >
    <App />
  </SquidContextProvider>
);

注: 環境管理に .env ファイルを使用している場合は、appId と region を任意の envars（環境変数）に設定してください:

// main.tsx

<SquidContextProvider
  options={{
    appId: process.env.SQUID_CLOUD_APP_ID,
    region: process.env.SQUID_CLOUD_REGION,
  }}
>

Hooks​

アプリケーションを SquidContextProvider でラップすると、アプリは Squid インスタンスにアクセスできるようになります。このインスタンスを直接参照するには、useSquid hook を使用します。

function App() {
  const squid = useSquid();

  const foo = () => {
    squid.executeFunction('foo');
  };

  return <button onClick={foo}>Foo</button>;
}

ただし、collection、query、document へアクセスするための追加の hooks も用意されています。

useCollection​

useCollection hook は squid.collection(...) のラッパーです。squid の参照がなくても collection にアクセスできます。collection を取得したら、それを使って query を作成したり、document を管理したりできます。

const collection = useCollection<User>('users');

const query = collection.query().eq('name', 'John Doe');
const doc = collection.doc('user-id');

useQuery​

query を作成したら、useQuery hook を使ってそれを実行し、必要に応じて結果を subscribe できます。

この hook は、次のプロパティを含む object を返します:

  • loading: query からデータが返されたかどうか。
  • data: 配列としての query 結果。hook に渡す query の種類に応じて、document reference、document data、join query の結果などになります。
  • error: query 実行中にエラーが発生した場合の error object。
function App() {
  const collection = useCollection<User>('users');

  /**
   * docs のリストはクライアントにストリーミングされ、
   * 最新の状態に保たれます。
   */
  const { data } = useQuery(collection.query().gt('age', 18), {
    subscribe: true,
    initialData: [],
  });

  return (
    <ul>
      {docs.map((d) => (
        <li key={d.refId}>{d.data.age}</li>
      ))}
    </ul>
  );
}

subscribe オプションが true に設定されている場合、データはクライアントにストリーミングされ、新しい更新を受信するとコンポーネントは自動的に再レンダリングされます。subscribe が false の場合、query の初期データは取得されますが、変更はストリーミングされません。

また、必要に応じて initialData オプションも指定でき、最初の結果が読み込まれるまでそれが返されます。

usePagination​

usePagination hook は、query 結果をページネーションするために使用します。ページネーションを扱うためのインターフェースを提供し、変更に合わせてデータを最新の状態に保ちます。Squid におけるページネーションの詳細は、pagination documentation を参照してください。

この hook は、次のプロパティを含む object を返します:

  • loading: 現在データを読み込んでいる、またはページネーション中かどうか。
  • data: 配列としてのページネーション結果。hook に渡す query の種類に応じて、document reference、document data、join query の結果などになります。
  • hasNext: 現在のページの後にさらに結果があるかどうかを示す boolean。
  • hasPrev: 現在のページの前にさらに結果があるかどうかを示す boolean。
  • next: 次のページの結果を読み込む関数（hasNext が true のときのみ有効）。
  • prev: 前のページの結果を読み込む関数（hasPrev が true のときのみ有効）。
function App() {
  const collection = useCollection<User>('users');

  /**
   * users のリストをページネーションします。
   * docs のリストはクライアントにストリーミングされ、最新の状態に保たれます。
   */
  const { docs, loading, hasNext, hasPrev, next, prev } = usePagination(
    collection.query().eq('age', 30).sortBy('name'),
    { subscribe: true, pageSize: 10 } /* PaginationOptions */,
    [30] // deps
  );

  if (loading) {
    return <div>Loading...</div>;
  }

  return (
    <div>
      <ul>
        {docs.map((d) => (
          <li key={d.refId}>{d.data.name}</li>
        ))}
      </ul>
      <button onClick={prev} disabled={!hasPrev}>
        Previous
      </button>
      <button onClick={next} disabled={!hasNext}>
        Next
      </button>
    </div>
  );
}

subscribe オプションが true に設定されている場合、データはクライアントにストリーミングされ、新しい更新を受信するとコンポーネントは自動的に再レンダリングされます。ページ上の最初の item と最後の item の間に新しいデータが追加された場合、ページは自動的に更新されて新しいデータが表示され、pageSize 個の item だけが表示されることが保証されます。

ページネーションを使用するには、query で sortBy を指定する必要があります。

また、必要に応じて deps 配列も指定できます。deps 配列が変更されると、新しいページネーション query が作成されます。

useDoc​

useDoc hook は類似の機能を提供しますが、query に subscribe する代わりに、特定の document の更新に subscribe します。

この hook は、次のプロパティを含む object を返します:

  • loading: document query からデータが返されたかどうか。
  • data: document data。データをまだ受信していない場合や document が削除された場合は undefined になり得ます。
  • error: document の query 中にエラーが発生した場合の error object。
// App.tsx

function App() {
  const collection = useCollection<User>('users');
  const doc = collection.doc('user-id');

  /**
   * doc の変更はクライアントにストリーミングされ、
   * 最新の状態に保たれます。
   */
  const { data } = useDoc(doc);

  return <span>{data.foo}</span>;
}

useDocs​

useDocs hook は、複数の document reference に対する更新を提供します。

この hook は、次のプロパティを含む object を返します:

  • loading: すべて の document query からデータが返されたかどうか。
  • data: document data の配列。配列の要素は、データをまだ受信していない場合や document が削除された場合に undefined になり得ます。
  • error: いずれか の document の query 中にエラーが発生した場合の error object。
// App.tsx

function App() {
  const collection = useCollection<User>('users');
  const docs = [collection.doc('my-id-1'), collection.doc('my-id-2')];

  /**
   * document の変更はクライアントにストリーミングされ、
   * 最新の状態に保たれます。
   */
  const { data } = useDocs(docs);

  return (
    <ul>
      <li>{data[0].foo}</li>
      <li>{data[1].foo}</li>
    </ul>
  );
}

Async Hooks​

Squid Client SDK は Promises と Observables を使用しますが、React コンポーネントでこうした非同期更新をサポートするには、いくつか作業が必要です。

Squid Client SDK のすべての機能を React に簡単に統合できるように、Squid は usePromise と useObservable hooks を公開しています。これらの hooks により、squid インスタンス上の非同期関数を React コンポーネント内で直接利用できます。

useObservable​

useObservable hook は Observable<T> を返す関数を受け取り、observable に subscribe してコンポーネント内で更新を受け取れるようにします。次のプロパティを含む object を返します:

  • loading: observable から値を受け取ったかどうか。
  • data: observable から受け取った最新のデータ。
  • error: observable がエラーに遭遇した場合の error object。
  • complete: observable が完了したかどうか。
function App() {
  const [bar, setBar] = useState('bar');
  const squid = useSquid();

  const { loading, data, error, complete } = useObservable(
    () => {
      return squid.collection<User>('users').query().gt('foo', bar).snapshots();
    },
    { initialData: [] },
    [bar] // deps
  );
}

必要に応じて、この hook は initialData オプション（デフォルトは null）と deps 配列も受け取れます。deps 配列が変更されると、現在の observable は unsubscribe され、新しい subscription が作成されます。上の例では、query の where 条件が bar 変数に依存していることが分かります。bar が変更されたときに query が適切に更新されるよう、依存関係として渡す必要があります。

deps が変更されるたびに、新しく作成された observable から値が emit されるまで loading は true にリセットされます。

usePromise​

usePromise hook は useObservable に似ていますが、Promise<T> を返す関数を受け取ります。この hook が promise そのものではなく関数を取る理由は、コンポーネントが mount されるまで promise の実行が開始されないようにするためです。

  • loading: promise が resolve または reject されたかどうか。
  • data: promise によって resolve されたデータ。
  • error: promise が reject された場合の error object。
function App() {
  const [bar, setBar] = useState('bar');
  const squid = useSquid();

  const { loading, data, error } = usePromise(
    () => {
      return squid.collection<User>('users').query().gt('foo', bar).snapshot();
    },
    { initialData: [] },
    [bar] // deps
  );
}

この hook は initialData オプション（デフォルトは null）と deps 配列も受け取れます。deps が変更されるたびに、進行中の promise の結果は無視され、新しい promise が作成されます。上の例では、bar 変数が変更されるたびに新しい promise が作成されます。

Feature Hooks​

上記の hooks に加えて、Squid React SDK は一般的な Squid のユースケースを簡略化するために設計された hooks も提供します。

useAiChat​

useAiChat hook は Squid AI Agents をラップし、質問の送信や chat history へのアクセスを容易にします。hook は次のように使用できます:

const { chat, history, data, loading, complete, error } = useAiChat('agent-id');

そして次を返します:

  • chat: AI agent への prompt（string）を受け取る関数。
  • history: message の配列。message は id、message、type（ai または user）を持ち、AI agent からのアクティブな応答も含みます。
  • data: 現在の応答（chat が進行中の場合）。
  • loading: 現在の prompt に対する応答を待っているかどうか。
  • complete: 現在の応答が完了したかどうか。
  • error -> 現在の prompt に対してエラーが返された場合に設定されます。
const Chat = () => {
  const [value, setValue] = useState('');
  const { history, chat, complete } = useAiChat('agent-id');

  const handleClick = () => {
    chat(value);
  };

  return (
    <>
      <input onChange={(e) => setValue(e.target.value)} value={value} />
      <button onClick={handleClick} disabled={!complete}>
        Chat
      </button>
      {history.map(({ id, message, type }) => (
        <span key={id}>
          {type}: {message}
        </span>
      ))}
    </>
  );
};