Usar SDKs da Web gerados

Com os SDKs do cliente do Firebase SQL Connect, é possível chamar consultas e mutações do lado do servidor diretamente de um app do Firebase. Você gera um SDK do cliente personalizado em paralelo ao projetar os esquemas, as consultas e as mutações que implanta no seu serviço SQL Connect. Em seguida, integre os métodos desse SDK à lógica do cliente.

Como já mencionamos, é importante observar que SQL Connect consultas e mutações não são enviadas pelo código do cliente e executadas no servidor. Em vez disso, quando implantadas, as operações SQL Connect são armazenadas no servidor, como o Cloud Functions. Isso significa que você precisa implantar as mudanças correspondentes do lado do cliente para evitar falhas nos usuários atuais (por exemplo, em versões mais antigas do app).

Por isso, o SQL Connect oferece um ambiente de desenvolvimento e ferramentas que permitem prototipar seus esquemas, consultas e mutações implantados no servidor. Ele também gera SDKs do lado do cliente automaticamente enquanto você cria protótipos.

Depois de iterar as atualizações nos apps de serviço e cliente, as atualizações do lado do servidor e do cliente estarão prontas para implantação.

Qual é o fluxo de trabalho de desenvolvimento do cliente?

Se você seguiu o Guia de início rápido, conheceu o fluxo geral de desenvolvimento do SQL Connect. Neste guia, você encontra informações mais detalhadas sobre como gerar SDKs da Web com base no seu esquema e trabalhar com consultas e mutações do cliente.

Em resumo, para usar os SDKs da Web gerados nos apps cliente, siga estas etapas de pré-requisito:

1. Adicione o Firebase ao seu app da Web.

Depois, siga estas instruções:

1. Desenvolva o esquema do app.
2. Inicialize o código do cliente com o SDK para JavaScript.
3. Configure a geração de SDKs:
   • Com o botão Adicionar SDK ao app na extensão SQL Connect do VS Code.
   • Atualizando seu connector.yaml para o SDK para JavaScript.
4. Importe bibliotecas e código gerado com o SDK para JavaScript.
5. Implemente chamadas para consultas e mutações com o SDK para JavaScript.
6. Teste configurando o emulador SQL Connect com o SDK para JavaScript.

Implementar código do cliente com o SDK Firebase JavaScript

Esta seção mostra como implementar clientes usando o SDK Firebase JavaScript.

Se você estiver usando React ou Angular, consulte instruções de configuração alternativas e links para documentação adicional sobre geração de SDKs SQL Connect para frameworks.

Inicializar o aplicativo

Primeiro, inicialize o app usando a sequência padrão do Firebase.

initializeApp({...});

Instalar o SDK para JavaScript gerado

Use a CLI Firebase para configurar os SDKs gerados pelo SQL Connect nos seus apps. O comando init detecta todos os apps na pasta atual e instala automaticamente os SDKs gerados.

firebase init dataconnect:sdk

Conecte o app ao serviço SQL Connect.

import { connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@dataconnect/generated';

const dataConnect = getDataConnect(connectorConfig);
// [Optionally] Configure the SDK to use Data Connect local emulator.
connectDataConnectEmulator(dataConnect, 'localhost', 9399);

Atualizar SDKs durante a criação de protótipos

Se você tiver a extensão do SQL Connect VS Code instalada, ela sempre manterá os SDKs gerados atualizados.

Se você não usa a extensão SQL Connect do VS Code, pode usar a CLI do Firebase para manter os SDKs gerados atualizados.

firebase dataconnect:sdk:generate --watch

Gerar SDKs em pipelines de build

Use a CLI do Firebase para gerar SDKs SQL Connect em processos de build de CI/CD.

firebase dataconnect:sdk:generate

Importar bibliotecas

Há dois conjuntos de importações necessários para inicializar o código do cliente: importações gerais de SQL Connect e importações específicas e geradas do SDK.

Observe o objeto ConnectorConfig incluído nas importações gerais.

// general imports
import { ConnectorConfig, DataConnect, getDataConnect, QueryRef, MutationRef, QueryPromise, MutationPromise } from 'firebase/data-connect';

// generated queries and mutations from SDK
import { listMovies, ListMoviesResponse, createMovie, connectorConfig } from '@dataconnect/generated';

Usar consultas do SDK para JavaScript

O código gerado já vem com referências de consulta predefinidas. Basta importar e chamar a execução neles.

import { executeQuery } from 'firebase/data-connect';
import { listMoviesRef } from '@dataconnect/generated';

const ref = listMoviesRef();
const { data } = await executeQuery(ref);
console.log(data.movies);

Chamar métodos de consulta do SDK

Confira um exemplo usando essas funções de atalho de ação:

import { listMovies } from '@dataconnect/generated';
function onBtnClick() {
// This will call the generated JS from the CLI and then make an HTTP request out
// to the server.
  listMovies().then(data => showInUI(data)); // == executeQuery(listMoviesRef);
}

Inscrever-se para receber notificações sobre mudanças

Consulte Receber atualizações em tempo real do SQL Connect.

Processar mudanças em campos de enumeração

O esquema de um app pode conter enumerações, que podem ser acessadas pelas suas consultas GraphQL.

À medida que o design de um app muda, você pode adicionar novos valores compatíveis com enumeração. Por exemplo, imagine que, mais tarde no ciclo de vida do aplicativo, você decida adicionar um valor FULLSCREEN à enumeração AspectRatio.

No fluxo de trabalho do SQL Connect, você pode usar ferramentas de desenvolvimento local para atualizar suas consultas e SDKs.

No entanto, antes de lançar uma versão atualizada dos clientes, os clientes implantados mais antigos podem falhar.

Exemplo de implementação resiliente

Sempre adicione uma ramificação default a uma instrução switch nos valores de enumeração ou uma ramificação else a um bloco if/else if comparando com os valores de enumeração. Isso não é aplicado pela linguagem JavaScript/TypeScript, mas é a maneira de tornar o código do cliente robusto caso novos valores de enumeração sejam adicionados.

const queryResult = await getOldestMovie();

if (queryResult.data) {
  // we can use a switch statement's "default" case to check for unexpected values
  const oldestMovieAspectRatio = queryResult.data.originalAspectRatio;
  switch (oldestMovieAspectRatio) {
      case AspectRatio.ACADEMY:
      case AspectRatio.WIDESCREEN:
      case AspectRatio.ANAMORPHIC:
        console.log('This movie was filmed in Academy, widescreen or anamorphic aspect ratio!');
        break;
      default:
        // the default case will catch FULLSCREEN, UNAVAILABLE or _UNKNOWN
        // it will also catch unexpected values the SDK isn't aware of, such as CINEMASCOPE
        console.log('This movie was was NOT filmed in Academy, widescreen or anamorphic.');
        break;
  }

  // alternatively, we can check to see if the returned enum value is a known value
  if (!Object.values(AspectRatio).includes(oldestMovieAspectRatio)) {
    console.log(`Unrecognized aspect ratio: ${oldestAspectRatio}`);
  }
} else {
  console.log("no movies found!");
}

Usar mutações do SDK para JavaScript

As mutações são acessíveis da mesma forma que as consultas.

import { executeMutation } from 'firebase/data-connect';
import { createMovieRef } from '@dataconnect/generated';

const { data } = await executeMutation(createMovieRef({ movie: 'Empire Strikes Back' }));

Conectar-se ao emulador SQL Connect

Se quiser, conecte-se ao emulador chamando connectDataConnectEmulator e transmitindo a instância SQL Connect, assim:

import { connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@dataconnect/generated';

const dataConnect = getDataConnect(connectorConfig);
connectDataConnectEmulator(dataConnect, 'localhost', 9399);`

// Make calls from your app

Para mudar para recursos de produção, adicione um comentário às linhas de conexão com o emulador.

Ativar o armazenamento em cache no lado do cliente

O SQL Connect tem um recurso opcional de cache do lado do cliente, que você pode ativar editando o arquivo connector.yaml. Quando esse recurso está ativado, os SDKs de cliente gerados armazenam em cache localmente as respostas de consulta, o que pode reduzir o número de solicitações de banco de dados feitas pelo app e permitir que as partes dependentes do banco de dados funcionem quando a disponibilidade da rede é interrompida.

Para ativar o cache do lado do cliente, adicione uma configuração de cache do cliente à configuração do conector:

generate:
  javascriptSdk:
    outputDir: ../web/
    package: "@dataconnect/generated"
    clientCache:
      maxAge: 5s
      storage: memory

Essa configuração tem dois parâmetros opcionais:

• maxAge: a idade máxima que uma resposta em cache pode ter antes que o SDK do cliente busque valores atualizados. Exemplos: "0", "30s", "1h30m".

  O valor padrão de maxAge é 0, o que significa que as respostas são armazenadas em cache, mas o SDK do cliente sempre vai buscar valores atualizados. Os valores em cache só serão usados quando CACHE_ONLY for especificado como executeQuery() e o resultado inicial retornado de subscribe().

• storage: o SDK do cliente pode ser configurado para armazenar respostas em cache no armazenamento persistent ou em memory. Os resultados armazenados em cache no armazenamento persistent serão mantidos entre as reinicializações do app. Nos SDKs da Web, apenas o armazenamento memory é compatível.

Depois de atualizar a configuração de cache do conector, gere novamente os SDKs do cliente e reconstrua o app. Depois disso, executeQuery() e subscribe() vão armazenar em cache respostas e usar valores armazenados em cache de acordo com a política configurada. Isso geralmente acontece de forma automática, sem que você precise seguir etapas adicionais. No entanto, observe o seguinte:

• O comportamento padrão de executeQuery() é o descrito acima: se um resultado for armazenado em cache para uma consulta e o valor armazenado em cache não for mais antigo que maxAge, use o valor armazenado em cache. Esse comportamento padrão é chamado de política de PREFER_CACHE.

  Também é possível especificar invocações individuais de executeQuery() para disponibilizar apenas valores em cache (CACHE_ONLY) ou buscar incondicionalmente valores atualizados do servidor (SERVER_ONLY).

  await executeQuery(queryRef, QueryFetchPolicy.CACHE_ONLY);
  

  await executeQuery(queryRef, QueryFetchPolicy.SERVER_ONLY);
  

• Quando você chama subscribe(), ele sempre retorna imediatamente o conteúdo em cache, se existir, independente da configuração maxAge. As chamadas subsequentes para executeQuery() vão notificar os listeners de acordo com o maxAge configurado.

Tipos de dados no SDK

O servidor SQL Connect representa tipos de dados comuns do GraphQL. Elas são representadas no SDK da seguinte maneira.

Gerar SDKs do React e do Angular com o TanStack

O Firebase SQL Connect fornece um SDK gerado com hooks para React e Angular usando bibliotecas disponíveis dos nossos parceiros da Invertase, TanStack Query Firebase.

Essa biblioteca oferece um conjunto de hooks que facilitam muito o processamento de tarefas assíncronas com o Firebase nos seus aplicativos.

O TanStack vem com a própria implementação de cache do lado do cliente e assinaturas em tempo real, que podem funcionar com o suporte em tempo real integrado do SQL Connect, mas com alguma dificuldade. Recomendamos usar as vinculações baseadas em TanStack ou o suporte em tempo real integrado do SQL Connect, mas não os dois.

A implementação em tempo real do próprio SQL Connect tem algumas vantagens em relação às vinculações do TanStack:

• Armazenamento em cache normalizado: o SQL Connect implementa o armazenamento em cache normalizado, que melhora a consistência dos dados e a eficiência da memória e da rede em comparação com o armazenamento em cache no nível da consulta. Com o armazenamento em cache normalizado, se uma entidade for atualizada em uma área do app, ela também será atualizada em outras áreas que usam essa entidade.
• Invalidação remota: o SQL Connect pode invalidar remotamente entidades em cache em todos os dispositivos inscritos.

Inicializar o aplicativo

Primeiro, como em qualquer app da Web do Firebase, inicialize o app usando a sequência padrão do Firebase.

initializeApp({...});

Instalar pacotes do Firebase do TanStack Query

instale pacotes para TanStack Query no seu projeto.

npm i --save @tanstack/react-query @tanstack-query-firebase/react
npm i --save firebase@latest # Note: React has a peer dependency on ^11.3.0

ng add @angular/fire

Gerar seu SDK do React ou do Angular

Assim como no SDK da Web padrão, conforme descrito anteriormente, as ferramentas do Firebase processam a geração automática de SDKs com base no seu esquema e nas suas operações.

Se você acabou de adicionar o React ou o Angular ao seu projeto, execute firebase init dataconnect:sdk de novo para reconfigurar os SDKs gerados e incluir as vinculações extras do framework.

Importar bibliotecas

Há quatro conjuntos de importações necessárias para inicializar o código do cliente React ou Angular: importações gerais de SQL Connect, importações gerais do TanStack e importações específicas para seus SDKs gerados em JS e React.

Observe o tipo ConnectorConfig incluído nas importações gerais.

// general imports
import { ConnectorConfig, DataConnect, getDataConnect, QueryRef, MutationRef, QueryPromise, MutationPromise } from 'firebase/data-connect';

// TanStack Query-related functions
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

// generated queries and mutations from SDK
import { ListMoviesResponse, connectorConfig } from '@dataconnect/generated';

// generated React hooks from SDK
import { useListAllMovies, useCreateMovie } from "@dataconnect/generated/react";

// general imports
import { ConnectorConfig, DataConnect, getDataConnect, QueryRef, MutationRef, QueryPromise, MutationPromise } from 'firebase/data-connect';

// TanStack Query-related functions
import { provideTanStackQuery, QueryClient } from "@tanstack/angular-query-experimental";

// generated queries and mutations from SDK
import { ListMoviesResponse, connectorConfig } from '@dataconnect/generated';

// generated React hooks from SDK
import { injectListAllMovies, injectCreateMovie } from "@dataconnect/generated/angular";

Usar consultas e mutações no cliente React ou Angular

Com a configuração concluída, você pode incorporar métodos do SDK gerado.

No snippet a seguir, observe o método useListAllMovies com prefixo use para React e o método injectListAllMovies com prefixo inject para Angular, ambos do SDK gerado.

import { useListAllMovies } from '@dataconnect/generated/react';

function MyComponent() {
  const { isLoading, data, error } = useListAllMovies();
  if(isLoading) {
    return <div>Loading...</div>
  }
  if(error) {
    return <div> An Error Occurred: {error} </div>
  }
}

// App.tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import MyComponent from './my-component';

function App() {
  const queryClient = new QueryClient();
  return <QueryClientProvider client={queryClient}>
    <MyComponent />
  </QueryClientProvider>
}

import { injectAllMovies, connectorConfig } from '@dataconnect/generated/angular';
import { provideDataConnect, getDataConnect } from '@angular/fire/data-connect';
import { provideTanStackQuery, QueryClient } from "@tanstack/angular-query-experimental";
const queryClient = new QueryClient();
...
providers: [
  ...
  provideTanStackQuery(queryClient),
  provideDataConnect(() => {
    const dc = getDataConnect(connectorConfig);
    return dc;
  })
]

Usar consultas de recarregamento automático com React e Angular

É possível configurar as consultas para serem recarregadas automaticamente quando os dados mudarem.

export class MovieListComponent {
  movies = useListAllMovies();
}

export class AddPostComponent {
  const mutation = useCreateMovie({ invalidate: [listAllMoviesRef()] });
  addMovie() {
    // The following will automatically cause TanStack to reload its listAllMovies query
    mutation.mutate({ title: 'The Matrix });
  }
}

// class
export class MovieListComponent {
  movies = injectListAllMovies();
}

// template
@if (movies.isPending()) {
    Loading...
}
@if (movies.error()) {
    An error has occurred: {{  movies.error() }}
}
@if (movies.data(); as data) {
    @for (movie of data.movies; track movie.id) {
    <mat-card appearance="outlined">
        <mat-card-content>{{movie.description}}</mat-card-content>
    </mat-card>
    } @empty {
        <h2>No items!</h2>
    }
}

Conectar-se ao emulador SQL Connect

Se quiser, conecte-se ao emulador chamando connectDataConnectEmulator e transmitindo a instância SQL Connect ao hook gerado, assim:

import { getDataConnect, connectDataConnectEmulator } from 'firebase/data-connect';
import { connectorConfig } from '@dataconnect/generated';
import { useListAllMovies } from '@dataconnect/generated/react';

const dc = getDataConnect(connectorConfig);
connectDataConnectEmulator(dc, 'localhost', 9399);

class AppComponent() {
  ...
  const { isLoading, data, error } = useListAllMovies(dc);
  ...
}

// app.config.ts
import { provideDataConnect } from '@angular/fire/data-connect';
import { getDataConnect, connectDataConnectEmulator } from 'firebase/data-connect';
provideDataConnect(() => {
  const dc = getDataConnect(connectorConfig);
  connectDataConnectEmulator(dc, 'localhost', 9399);
  return dc;
}),

Para mudar para recursos de produção, adicione um comentário às linhas de conexão com o emulador.

Atualizar SDKs durante a criação de protótipos

Se você tiver a extensão do SQL Connect VS Code instalada, ela sempre manterá os SDKs gerados atualizados.

Se você não usa a extensão SQL Connect do VS Code, pode usar a CLI do Firebase para manter os SDKs gerados atualizados.

firebase dataconnect:sdk:generate --watch

Gerar SDKs em pipelines de build

Use a CLI do Firebase para gerar SDKs SQL Connect em processos de build de CI/CD.

firebase dataconnect:sdk:generate