ContextQMD
Back to Firebase Js Sdk

Generated TypeScript README

e2e/data-connect/dataconnect-generated/js/default-connector/README.md

12.12.112.2 KB
Original Source

Generated TypeScript README

This README will guide you through the process of using the generated JavaScript 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.

Table of Contents

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.

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.

typescript
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.

typescript
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:

typescript
listMovies(): QueryPromise<ListMoviesData, undefined>;

interface ListMoviesRef {
  ...
  /* Allow users to create refs without passing in DataConnect */
  (): QueryRef<ListMoviesData, undefined>;
}
export const listMoviesRef: ListMoviesRef;

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

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

interface ListMoviesRef {
  ...
  (dc: DataConnect): QueryRef<ListMoviesData, undefined>;
}
export const listMoviesRef: ListMoviesRef;

If you need the name of the operation without creating a ref, you can retrieve the operation name by calling the operationName property on the listMoviesRef:

typescript
const name = listMoviesRef.operationName;
console.log(name);

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:

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

Using ListMovies's action shortcut function

typescript
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

typescript
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:

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

interface CreateMovieRef {
  ...
  /* Allow users to create refs without passing in DataConnect */
  (vars: CreateMovieVariables): MutationRef<CreateMovieData, CreateMovieVariables>;
}
export const createMovieRef: CreateMovieRef;

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

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

interface CreateMovieRef {
  ...
  (dc: DataConnect, vars: CreateMovieVariables): MutationRef<CreateMovieData, CreateMovieVariables>;
}
export const createMovieRef: CreateMovieRef;

If you need the name of the operation without creating a ref, you can retrieve the operation name by calling the operationName property on the createMovieRef:

typescript
const name = createMovieRef.operationName;
console.log(name);

Variables

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

typescript
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:

typescript
export interface CreateMovieData {
  movie_insert: Movie_Key;
}

Using CreateMovie's action shortcut function

typescript
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

typescript
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);
});