Skip to content

Latest commit

 

History

History
257 lines (196 loc) · 11.3 KB

README.md

File metadata and controls

257 lines (196 loc) · 11.3 KB

Table of Contents

Generated TypeScript README

This README will guide you through the process of using the generated TypeScript SDK package for the connector default. It will also provide examples on how to use your generated SDK to call your Data Connect queries and mutations.

NOTE: This README is generated alongside the generated SDK. If you make changes to this file, they will be overwritten when the SDK is regenerated.

You can use this generated SDK by importing from the package @firebasegen/default-connector as shown below. Both CommonJS and ESM imports are supported.

You can also follow the instructions from the Data Connect documentation.

Accessing the connector

A connector is a collection of Queries and Mutations. One SDK is generated for each connector - this SDK is generated for the connector default.

You can find more information about connectors in the Data Connect documentation.

import { getDataConnect } from 'firebase/data-connect';
import { connectorConfig } from '@firebasegen/default-connector';

const dataConnect = getDataConnect(connectorConfig);

Connecting to the local Emulator

By default, the connector will connect to the production service.

To connect to the emulator, you can use the following code. You can also follow the emulator instructions from the Data Connect documentation.

import { connectDataConnectEmulator, getDataConnect } from 'firebase/data-connect';
import { connectorConfig } from '@firebasegen/default-connector';

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

After it's initialized, you can call your Data Connect queries and mutations from your generated SDK.

Queries

There are two ways to execute a Data Connect Query using the generated Web SDK:

  • Using a Query Reference function, which returns a QueryRef
    • The QueryRef can be used as an argument to executeQuery(), which will execute the Query and return a QueryPromise
  • Using an action shortcut function, which returns a QueryPromise
    • Calling the action shortcut function will execute the Query and return a QueryPromise

The following is true for both the action shortcut function and the QueryRef function:

  • The QueryPromise returned will resolve to the result of the Query once it has finished executing
  • If the Query accepts arguments, both the action shortcut function and the QueryRef function accept a single argument: an object that contains all the required variables (and the optional variables) for the Query
  • Both functions can be called with or without passing in a DataConnect instance as an argument. If no DataConnect argument is passed in, then the generated SDK will call getDataConnect(connectorConfig) behind the scenes for you.

Below are examples of how to use the default connector's generated functions to execute each query. You can also follow the examples from the Data Connect documentation.

ListMovies

You can execute the ListMovies query using the following action shortcut function, or by calling executeQuery() after calling the following QueryRef function, both of which are defined in default-connector/index.d.ts:

listMovies(): QueryPromise<ListMoviesData, undefined>;

listMoviesRef(): QueryRef<ListMoviesData, undefined>;

You can also pass in a DataConnect instance to the action shortcut function or QueryRef function.

listMovies(dc: DataConnect): QueryPromise<ListMoviesData, undefined>;

listMoviesRef(dc: DataConnect): QueryRef<ListMoviesData, undefined>;

Variables

The ListMovies query has no variables.

Return Type

Recall that executing the ListMovies query returns a QueryPromise that resolves to an object with a data property.

The data property is an object of type ListMoviesData, which is defined in default-connector/index.d.ts. It has the following fields:

export interface ListMoviesData {
  movies: ({
    id: UUIDString;
    title: string;
    imageUrl: string;
    genre?: string | null;
  } & Movie_Key)[];
}

Using ListMovies's action shortcut function

import { getDataConnect } from 'firebase/data-connect';
import { connectorConfig, listMovies } from '@firebasegen/default-connector';


// Call the `listMovies()` function to execute the query.
// You can use the `await` keyword to wait for the promise to resolve.
const { data } = await listMovies();

// You can also pass in a `DataConnect` instance to the action shortcut function.
const dataConnect = getDataConnect(connectorConfig);
const { data } = await listMovies(dataConnect);

console.log(data.movies);

// Or, you can use the `Promise` API.
listMovies().then((response) => {
  const data = response.data;
  console.log(data.movies);
});

Using ListMovies's QueryRef function

import { getDataConnect, executeQuery } from 'firebase/data-connect';
import { connectorConfig, listMoviesRef } from '@firebasegen/default-connector';


// Call the `listMoviesRef()` function to get a reference to the query.
const ref = listMoviesRef();

// You can also pass in a `DataConnect` instance to the `QueryRef` function.
const dataConnect = getDataConnect(connectorConfig);
const ref = listMoviesRef(dataConnect);

// Call `executeQuery()` on the reference to execute the query.
// You can use the `await` keyword to wait for the promise to resolve.
const { data } = await executeQuery(ref);

console.log(data.movies);

// Or, you can use the `Promise` API.
executeQuery(ref).then((response) => {
  const data = response.data;
  console.log(data.movies);
});

Mutations

There are two ways to execute a Data Connect Mutation using the generated Web SDK:

  • Using a Mutation Reference function, which returns a MutationRef
    • The MutationRef can be used as an argument to executeMutation(), which will execute the Mutation and return a MutationPromise
  • Using an action shortcut function, which returns a MutationPromise
    • Calling the action shortcut function will execute the Mutation and return a MutationPromise

The following is true for both the action shortcut function and the MutationRef function:

  • The MutationPromise returned will resolve to the result of the Mutation once it has finished executing
  • If the Mutation accepts arguments, both the action shortcut function and the MutationRef function accept a single argument: an object that contains all the required variables (and the optional variables) for the Mutation
  • Both functions can be called with or without passing in a DataConnect instance as an argument. If no DataConnect argument is passed in, then the generated SDK will call getDataConnect(connectorConfig) behind the scenes for you.

Below are examples of how to use the default connector's generated functions to execute each mutation. You can also follow the examples from the Data Connect documentation.

CreateMovie

You can execute the CreateMovie mutation using the following action shortcut function, or by calling executeMutation() after calling the following MutationRef function, both of which are defined in default-connector/index.d.ts:

createMovie(vars: CreateMovieVariables): MutationPromise<CreateMovieData, CreateMovieVariables>;

createMovieRef(vars: CreateMovieVariables): MutationRef<CreateMovieData, CreateMovieVariables>;

You can also pass in a DataConnect instance to the action shortcut function or MutationRef function.

createMovie(dc: DataConnect, vars: CreateMovieVariables): MutationPromise<CreateMovieData, CreateMovieVariables>;

createMovieRef(dc: DataConnect, vars: CreateMovieVariables): MutationRef<CreateMovieData, CreateMovieVariables>;

Variables

The CreateMovie mutation requires an argument of type CreateMovieVariables, which is defined in default-connector/index.d.ts. It has the following fields:

export interface CreateMovieVariables {
  title: string;
  genre: string;
  imageUrl: string;
}

Return Type

Recall that executing the CreateMovie mutation returns a MutationPromise that resolves to an object with a data property.

The data property is an object of type CreateMovieData, which is defined in default-connector/index.d.ts. It has the following fields:

export interface CreateMovieData {
  movie_insert: Movie_Key;
}

Using CreateMovie's action shortcut function

import { getDataConnect } from 'firebase/data-connect';
import { connectorConfig, createMovie, CreateMovieVariables } from '@firebasegen/default-connector';

// The `CreateMovie` mutation requires an argument of type `CreateMovieVariables`:
const createMovieVars: CreateMovieVariables = {
  title: ..., 
  genre: ..., 
  imageUrl: ..., 
};

// Call the `createMovie()` function to execute the mutation.
// You can use the `await` keyword to wait for the promise to resolve.
const { data } = await createMovie(createMovieVars);
// Variables can be defined inline as well.
const { data } = await createMovie({ title: ..., genre: ..., imageUrl: ..., });

// You can also pass in a `DataConnect` instance to the action shortcut function.
const dataConnect = getDataConnect(connectorConfig);
const { data } = await createMovie(dataConnect, createMovieVars);

console.log(data.movie_insert);

// Or, you can use the `Promise` API.
createMovie(createMovieVars).then((response) => {
  const data = response.data;
  console.log(data.movie_insert);
});

Using CreateMovie's MutationRef function

import { getDataConnect, executeMutation } from 'firebase/data-connect';
import { connectorConfig, createMovieRef, CreateMovieVariables } from '@firebasegen/default-connector';

// The `CreateMovie` mutation requires an argument of type `CreateMovieVariables`:
const createMovieVars: CreateMovieVariables = {
  title: ..., 
  genre: ..., 
  imageUrl: ..., 
};

// Call the `createMovieRef()` function to get a reference to the mutation.
const ref = createMovieRef(createMovieVars);
// Variables can be defined inline as well.
const ref = createMovieRef({ title: ..., genre: ..., imageUrl: ..., });

// You can also pass in a `DataConnect` instance to the `MutationRef` function.
const dataConnect = getDataConnect(connectorConfig);
const ref = createMovieRef(dataConnect, createMovieVars);

// Call `executeMutation()` on the reference to execute the mutation.
// You can use the `await` keyword to wait for the promise to resolve.
const { data } = await executeMutation(ref);

console.log(data.movie_insert);

// Or, you can use the `Promise` API.
executeMutation(ref).then((response) => {
  const data = response.data;
  console.log(data.movie_insert);
});