Generated TypeScript README

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

• Overview
• Accessing the connector
  • Connecting to the local Emulator
• Queries
  • ListWellnessActivities
  • ListMyGoals
• Mutations
  • CreateWellnessActivity
  • CreateUserActivityLog

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 example. You can find more information about connectors in the Data Connect documentation.

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

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

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

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 '@dataconnect/generated';

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 example connector's generated functions to execute each query. You can also follow the examples from the Data Connect documentation.

ListWellnessActivities

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

listWellnessActivities(): QueryPromise<ListWellnessActivitiesData, undefined>;

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

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

listWellnessActivities(dc: DataConnect): QueryPromise<ListWellnessActivitiesData, undefined>;

interface ListWellnessActivitiesRef {
  ...
  (dc: DataConnect): QueryRef<ListWellnessActivitiesData, undefined>;
}
export const listWellnessActivitiesRef: ListWellnessActivitiesRef;

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

const name = listWellnessActivitiesRef.operationName;
console.log(name);

Variables

The ListWellnessActivities query has no variables.

Return Type

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

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

export interface ListWellnessActivitiesData {
  wellnessActivities: ({
    id: UUIDString;
    title: string;
    type: string;
    durationMinutes: number;
    description?: string | null;
    imageUrl?: string | null;
    audioUrl?: string | null;
    tags?: string[] | null;
    createdAt: TimestampString;
  } & WellnessActivity_Key)[];
}

Using ListWellnessActivities's action shortcut function

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


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

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

console.log(data.wellnessActivities);

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

Using ListWellnessActivities's QueryRef function

import { getDataConnect, executeQuery } from 'firebase/data-connect';
import { connectorConfig, listWellnessActivitiesRef } from '@dataconnect/generated';


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

// You can also pass in a `DataConnect` instance to the `QueryRef` function.
const dataConnect = getDataConnect(connectorConfig);
const ref = listWellnessActivitiesRef(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.wellnessActivities);

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

ListMyGoals

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

listMyGoals(): QueryPromise<ListMyGoalsData, undefined>;

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

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

listMyGoals(dc: DataConnect): QueryPromise<ListMyGoalsData, undefined>;

interface ListMyGoalsRef {
  ...
  (dc: DataConnect): QueryRef<ListMyGoalsData, undefined>;
}
export const listMyGoalsRef: ListMyGoalsRef;

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

const name = listMyGoalsRef.operationName;
console.log(name);

Variables

The ListMyGoals query has no variables.

Return Type

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

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

export interface ListMyGoalsData {
  goals: ({
    id: UUIDString;
    name: string;
    description?: string | null;
    metricType?: string | null;
    targetValue?: number | null;
    startDate: DateString;
    targetDate: DateString;
    status: string;
    createdAt: TimestampString;
  } & Goal_Key)[];
}

Using ListMyGoals's action shortcut function

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


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

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

console.log(data.goals);

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

Using ListMyGoals's QueryRef function

import { getDataConnect, executeQuery } from 'firebase/data-connect';
import { connectorConfig, listMyGoalsRef } from '@dataconnect/generated';


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

// You can also pass in a `DataConnect` instance to the `QueryRef` function.
const dataConnect = getDataConnect(connectorConfig);
const ref = listMyGoalsRef(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.goals);

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

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 example connector's generated functions to execute each mutation. You can also follow the examples from the Data Connect documentation.

CreateWellnessActivity

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

createWellnessActivity(vars: CreateWellnessActivityVariables): MutationPromise<CreateWellnessActivityData, CreateWellnessActivityVariables>;

interface CreateWellnessActivityRef {
  ...
  /* Allow users to create refs without passing in DataConnect */
  (vars: CreateWellnessActivityVariables): MutationRef<CreateWellnessActivityData, CreateWellnessActivityVariables>;
}
export const createWellnessActivityRef: CreateWellnessActivityRef;

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

createWellnessActivity(dc: DataConnect, vars: CreateWellnessActivityVariables): MutationPromise<CreateWellnessActivityData, CreateWellnessActivityVariables>;

interface CreateWellnessActivityRef {
  ...
  (dc: DataConnect, vars: CreateWellnessActivityVariables): MutationRef<CreateWellnessActivityData, CreateWellnessActivityVariables>;
}
export const createWellnessActivityRef: CreateWellnessActivityRef;

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

const name = createWellnessActivityRef.operationName;
console.log(name);

Variables

The CreateWellnessActivity mutation requires an argument of type CreateWellnessActivityVariables, which is defined in dataconnect-generated/index.d.ts. It has the following fields:

export interface CreateWellnessActivityVariables {
  title: string;
  type: string;
  durationMinutes: number;
  createdAt: TimestampString;
}

Return Type

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

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

export interface CreateWellnessActivityData {
  wellnessActivity_insert: WellnessActivity_Key;
}

Using CreateWellnessActivity's action shortcut function

import { getDataConnect } from 'firebase/data-connect';
import { connectorConfig, createWellnessActivity, CreateWellnessActivityVariables } from '@dataconnect/generated';

// The `CreateWellnessActivity` mutation requires an argument of type `CreateWellnessActivityVariables`:
const createWellnessActivityVars: CreateWellnessActivityVariables = {
  title: ..., 
  type: ..., 
  durationMinutes: ..., 
  createdAt: ..., 
};

// Call the `createWellnessActivity()` function to execute the mutation.
// You can use the `await` keyword to wait for the promise to resolve.
const { data } = await createWellnessActivity(createWellnessActivityVars);
// Variables can be defined inline as well.
const { data } = await createWellnessActivity({ title: ..., type: ..., durationMinutes: ..., createdAt: ..., });

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

console.log(data.wellnessActivity_insert);

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

Using CreateWellnessActivity's MutationRef function

import { getDataConnect, executeMutation } from 'firebase/data-connect';
import { connectorConfig, createWellnessActivityRef, CreateWellnessActivityVariables } from '@dataconnect/generated';

// The `CreateWellnessActivity` mutation requires an argument of type `CreateWellnessActivityVariables`:
const createWellnessActivityVars: CreateWellnessActivityVariables = {
  title: ..., 
  type: ..., 
  durationMinutes: ..., 
  createdAt: ..., 
};

// Call the `createWellnessActivityRef()` function to get a reference to the mutation.
const ref = createWellnessActivityRef(createWellnessActivityVars);
// Variables can be defined inline as well.
const ref = createWellnessActivityRef({ title: ..., type: ..., durationMinutes: ..., createdAt: ..., });

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

// 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.wellnessActivity_insert);

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

CreateUserActivityLog

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

createUserActivityLog(vars: CreateUserActivityLogVariables): MutationPromise<CreateUserActivityLogData, CreateUserActivityLogVariables>;

interface CreateUserActivityLogRef {
  ...
  /* Allow users to create refs without passing in DataConnect */
  (vars: CreateUserActivityLogVariables): MutationRef<CreateUserActivityLogData, CreateUserActivityLogVariables>;
}
export const createUserActivityLogRef: CreateUserActivityLogRef;

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

createUserActivityLog(dc: DataConnect, vars: CreateUserActivityLogVariables): MutationPromise<CreateUserActivityLogData, CreateUserActivityLogVariables>;

interface CreateUserActivityLogRef {
  ...
  (dc: DataConnect, vars: CreateUserActivityLogVariables): MutationRef<CreateUserActivityLogData, CreateUserActivityLogVariables>;
}
export const createUserActivityLogRef: CreateUserActivityLogRef;

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

const name = createUserActivityLogRef.operationName;
console.log(name);

Variables

The CreateUserActivityLog mutation requires an argument of type CreateUserActivityLogVariables, which is defined in dataconnect-generated/index.d.ts. It has the following fields:

export interface CreateUserActivityLogVariables {
  activityType: string;
  timestamp: TimestampString;
  durationMinutesCompleted?: number | null;
  feedback?: string | null;
}

Return Type

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

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

export interface CreateUserActivityLogData {
  userActivityLog_insert: UserActivityLog_Key;
}

Using CreateUserActivityLog's action shortcut function

import { getDataConnect } from 'firebase/data-connect';
import { connectorConfig, createUserActivityLog, CreateUserActivityLogVariables } from '@dataconnect/generated';

// The `CreateUserActivityLog` mutation requires an argument of type `CreateUserActivityLogVariables`:
const createUserActivityLogVars: CreateUserActivityLogVariables = {
  activityType: ..., 
  timestamp: ..., 
  durationMinutesCompleted: ..., // optional
  feedback: ..., // optional
};

// Call the `createUserActivityLog()` function to execute the mutation.
// You can use the `await` keyword to wait for the promise to resolve.
const { data } = await createUserActivityLog(createUserActivityLogVars);
// Variables can be defined inline as well.
const { data } = await createUserActivityLog({ activityType: ..., timestamp: ..., durationMinutesCompleted: ..., feedback: ..., });

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

console.log(data.userActivityLog_insert);

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

Using CreateUserActivityLog's MutationRef function

import { getDataConnect, executeMutation } from 'firebase/data-connect';
import { connectorConfig, createUserActivityLogRef, CreateUserActivityLogVariables } from '@dataconnect/generated';

// The `CreateUserActivityLog` mutation requires an argument of type `CreateUserActivityLogVariables`:
const createUserActivityLogVars: CreateUserActivityLogVariables = {
  activityType: ..., 
  timestamp: ..., 
  durationMinutesCompleted: ..., // optional
  feedback: ..., // optional
};

// Call the `createUserActivityLogRef()` function to get a reference to the mutation.
const ref = createUserActivityLogRef(createUserActivityLogVars);
// Variables can be defined inline as well.
const ref = createUserActivityLogRef({ activityType: ..., timestamp: ..., durationMinutesCompleted: ..., feedback: ..., });

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

// 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.userActivityLog_insert);

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