|
| 1 | +# Table of Contents |
| 2 | +- [**Overview**](#generated-typescript-readme) |
| 3 | +- [**Accessing the connector**](#accessing-the-connector) |
| 4 | + - [*Connecting to the local Emulator*](#connecting-to-the-local-emulator) |
| 5 | +- [**Queries**](#queries) |
| 6 | + - [*ListMovies*](#listmovies) |
| 7 | +- [**Mutations**](#mutations) |
| 8 | + - [*CreateMovie*](#createmovie) |
| 9 | + |
| 10 | +# Generated TypeScript README |
| 11 | +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. |
| 12 | + |
| 13 | +***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.* |
| 14 | + |
| 15 | +You can use this generated SDK by importing from the package `@firebasegen/default-connector` as shown below. Both CommonJS and ESM imports are supported. |
| 16 | + |
| 17 | +You can also follow the instructions from the [Data Connect documentation](https://firebase.google.com/docs/data-connect/web-sdk#set-client). |
| 18 | + |
| 19 | +# Accessing the connector |
| 20 | +A connector is a collection of Queries and Mutations. One SDK is generated for each connector - this SDK is generated for the connector `default`. |
| 21 | + |
| 22 | +You can find more information about connectors in the [Data Connect documentation](https://firebase.google.com/docs/data-connect#how-does). |
| 23 | + |
| 24 | +```javascript |
| 25 | +import { getDataConnect } from 'firebase/data-connect'; |
| 26 | +import { connectorConfig } from '@firebasegen/default-connector'; |
| 27 | + |
| 28 | +const dataConnect = getDataConnect(connectorConfig); |
| 29 | +``` |
| 30 | + |
| 31 | +## Connecting to the local Emulator |
| 32 | +By default, the connector will connect to the production service. |
| 33 | + |
| 34 | +To connect to the emulator, you can use the following code. |
| 35 | +You can also follow the emulator instructions from the [Data Connect documentation](https://firebase.google.com/docs/data-connect/web-sdk#instrument-clients). |
| 36 | + |
| 37 | +```javascript |
| 38 | +import { connectDataConnectEmulator, getDataConnect } from 'firebase/data-connect'; |
| 39 | +import { connectorConfig } from '@firebasegen/default-connector'; |
| 40 | + |
| 41 | +const dataConnect = getDataConnect(connectorConfig); |
| 42 | +connectDataConnectEmulator(dataConnect, 'localhost', 9399); |
| 43 | +``` |
| 44 | + |
| 45 | +After it's initialized, you can call your Data Connect [queries](#queries) and [mutations](#mutations) from your generated SDK. |
| 46 | + |
| 47 | +# Queries |
| 48 | + |
| 49 | +There are two ways to execute a Data Connect Query using the generated Web SDK: |
| 50 | +- Using a Query Reference function, which returns a `QueryRef` |
| 51 | + - The `QueryRef` can be used as an argument to `executeQuery()`, which will execute the Query and return a `QueryPromise` |
| 52 | +- Using an action shortcut function, which returns a `QueryPromise` |
| 53 | + - Calling the action shortcut function will execute the Query and return a `QueryPromise` |
| 54 | + |
| 55 | +The following is true for both the action shortcut function and the `QueryRef` function: |
| 56 | +- The `QueryPromise` returned will resolve to the result of the Query once it has finished executing |
| 57 | +- 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 |
| 58 | +- 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. |
| 59 | + |
| 60 | +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](https://firebase.google.com/docs/data-connect/web-sdk#using-queries). |
| 61 | + |
| 62 | +## ListMovies |
| 63 | +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](./index.d.ts): |
| 64 | +```javascript |
| 65 | +listMovies(): QueryPromise<ListMoviesData, undefined>; |
| 66 | + |
| 67 | +listMoviesRef(): QueryRef<ListMoviesData, undefined>; |
| 68 | +``` |
| 69 | +You can also pass in a `DataConnect` instance to the action shortcut function or `QueryRef` function. |
| 70 | +```javascript |
| 71 | +listMovies(dc: DataConnect): QueryPromise<ListMoviesData, undefined>; |
| 72 | + |
| 73 | +listMoviesRef(dc: DataConnect): QueryRef<ListMoviesData, undefined>; |
| 74 | +``` |
| 75 | + |
| 76 | +### Variables |
| 77 | +The `ListMovies` query has no variables. |
| 78 | +### Return Type |
| 79 | +Recall that executing the `ListMovies` query returns a `QueryPromise` that resolves to an object with a `data` property. |
| 80 | + |
| 81 | +The `data` property is an object of type `ListMoviesData`, which is defined in [default-connector/index.d.ts](./index.d.ts). It has the following fields: |
| 82 | +```javascript |
| 83 | +export interface ListMoviesData { |
| 84 | + movies: ({ |
| 85 | + id: UUIDString; |
| 86 | + title: string; |
| 87 | + imageUrl: string; |
| 88 | + genre?: string | null; |
| 89 | + } & Movie_Key)[]; |
| 90 | +} |
| 91 | +``` |
| 92 | +### Using `ListMovies`'s action shortcut function |
| 93 | + |
| 94 | +```javascript |
| 95 | +import { getDataConnect } from 'firebase/data-connect'; |
| 96 | +import { connectorConfig, listMovies } from '@firebasegen/default-connector'; |
| 97 | + |
| 98 | + |
| 99 | +// Call the `listMovies()` function to execute the query. |
| 100 | +// You can use the `await` keyword to wait for the promise to resolve. |
| 101 | +const { data } = await listMovies(); |
| 102 | + |
| 103 | +// You can also pass in a `DataConnect` instance to the action shortcut function. |
| 104 | +const dataConnect = getDataConnect(connectorConfig); |
| 105 | +const { data } = await listMovies(dataConnect); |
| 106 | + |
| 107 | +console.log(data.movies); |
| 108 | + |
| 109 | +// Or, you can use the `Promise` API. |
| 110 | +listMovies().then((response) => { |
| 111 | + const data = response.data; |
| 112 | + console.log(data.movies); |
| 113 | +}); |
| 114 | +``` |
| 115 | + |
| 116 | +### Using `ListMovies`'s `QueryRef` function |
| 117 | + |
| 118 | +```javascript |
| 119 | +import { getDataConnect, executeQuery } from 'firebase/data-connect'; |
| 120 | +import { connectorConfig, listMoviesRef } from '@firebasegen/default-connector'; |
| 121 | + |
| 122 | + |
| 123 | +// Call the `listMoviesRef()` function to get a reference to the query. |
| 124 | +const ref = listMoviesRef(); |
| 125 | + |
| 126 | +// You can also pass in a `DataConnect` instance to the `QueryRef` function. |
| 127 | +const dataConnect = getDataConnect(connectorConfig); |
| 128 | +const ref = listMoviesRef(dataConnect); |
| 129 | + |
| 130 | +// Call `executeQuery()` on the reference to execute the query. |
| 131 | +// You can use the `await` keyword to wait for the promise to resolve. |
| 132 | +const { data } = await executeQuery(ref); |
| 133 | + |
| 134 | +console.log(data.movies); |
| 135 | + |
| 136 | +// Or, you can use the `Promise` API. |
| 137 | +executeQuery(ref).then((response) => { |
| 138 | + const data = response.data; |
| 139 | + console.log(data.movies); |
| 140 | +}); |
| 141 | +``` |
| 142 | + |
| 143 | +# Mutations |
| 144 | + |
| 145 | +There are two ways to execute a Data Connect Mutation using the generated Web SDK: |
| 146 | +- Using a Mutation Reference function, which returns a `MutationRef` |
| 147 | + - The `MutationRef` can be used as an argument to `executeMutation()`, which will execute the Mutation and return a `MutationPromise` |
| 148 | +- Using an action shortcut function, which returns a `MutationPromise` |
| 149 | + - Calling the action shortcut function will execute the Mutation and return a `MutationPromise` |
| 150 | + |
| 151 | +The following is true for both the action shortcut function and the `MutationRef` function: |
| 152 | +- The `MutationPromise` returned will resolve to the result of the Mutation once it has finished executing |
| 153 | +- 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 |
| 154 | +- 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. |
| 155 | + |
| 156 | +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](https://firebase.google.com/docs/data-connect/web-sdk#using-mutations). |
| 157 | + |
| 158 | +## CreateMovie |
| 159 | +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](./index.d.ts): |
| 160 | +```javascript |
| 161 | +createMovie(vars: CreateMovieVariables): MutationPromise<CreateMovieData, CreateMovieVariables>; |
| 162 | + |
| 163 | +createMovieRef(vars: CreateMovieVariables): MutationRef<CreateMovieData, CreateMovieVariables>; |
| 164 | +``` |
| 165 | +You can also pass in a `DataConnect` instance to the action shortcut function or `MutationRef` function. |
| 166 | +```javascript |
| 167 | +createMovie(dc: DataConnect, vars: CreateMovieVariables): MutationPromise<CreateMovieData, CreateMovieVariables>; |
| 168 | + |
| 169 | +createMovieRef(dc: DataConnect, vars: CreateMovieVariables): MutationRef<CreateMovieData, CreateMovieVariables>; |
| 170 | +``` |
| 171 | + |
| 172 | +### Variables |
| 173 | +The `CreateMovie` mutation requires an argument of type `CreateMovieVariables`, which is defined in [default-connector/index.d.ts](./index.d.ts). It has the following fields: |
| 174 | + |
| 175 | +```javascript |
| 176 | +export interface CreateMovieVariables { |
| 177 | + title: string; |
| 178 | + genre: string; |
| 179 | + imageUrl: string; |
| 180 | +} |
| 181 | +``` |
| 182 | +### Return Type |
| 183 | +Recall that executing the `CreateMovie` mutation returns a `MutationPromise` that resolves to an object with a `data` property. |
| 184 | + |
| 185 | +The `data` property is an object of type `CreateMovieData`, which is defined in [default-connector/index.d.ts](./index.d.ts). It has the following fields: |
| 186 | +```javascript |
| 187 | +export interface CreateMovieData { |
| 188 | + movie_insert: Movie_Key; |
| 189 | +} |
| 190 | +``` |
| 191 | +### Using `CreateMovie`'s action shortcut function |
| 192 | + |
| 193 | +```javascript |
| 194 | +import { getDataConnect } from 'firebase/data-connect'; |
| 195 | +import { connectorConfig, createMovie, CreateMovieVariables } from '@firebasegen/default-connector'; |
| 196 | + |
| 197 | +// The `CreateMovie` mutation requires an argument of type `CreateMovieVariables`: |
| 198 | +const createMovieVars: CreateMovieVariables = { |
| 199 | + title: ..., |
| 200 | + genre: ..., |
| 201 | + imageUrl: ..., |
| 202 | +}; |
| 203 | + |
| 204 | +// Call the `createMovie()` function to execute the mutation. |
| 205 | +// You can use the `await` keyword to wait for the promise to resolve. |
| 206 | +const { data } = await createMovie(createMovieVars); |
| 207 | +// Variables can be defined inline as well. |
| 208 | +const { data } = await createMovie({ title: ..., genre: ..., imageUrl: ..., }); |
| 209 | + |
| 210 | +// You can also pass in a `DataConnect` instance to the action shortcut function. |
| 211 | +const dataConnect = getDataConnect(connectorConfig); |
| 212 | +const { data } = await createMovie(dataConnect, createMovieVars); |
| 213 | + |
| 214 | +console.log(data.movie_insert); |
| 215 | + |
| 216 | +// Or, you can use the `Promise` API. |
| 217 | +createMovie(createMovieVars).then((response) => { |
| 218 | + const data = response.data; |
| 219 | + console.log(data.movie_insert); |
| 220 | +}); |
| 221 | +``` |
| 222 | + |
| 223 | +### Using `CreateMovie`'s `MutationRef` function |
| 224 | + |
| 225 | +```javascript |
| 226 | +import { getDataConnect, executeMutation } from 'firebase/data-connect'; |
| 227 | +import { connectorConfig, createMovieRef, CreateMovieVariables } from '@firebasegen/default-connector'; |
| 228 | + |
| 229 | +// The `CreateMovie` mutation requires an argument of type `CreateMovieVariables`: |
| 230 | +const createMovieVars: CreateMovieVariables = { |
| 231 | + title: ..., |
| 232 | + genre: ..., |
| 233 | + imageUrl: ..., |
| 234 | +}; |
| 235 | + |
| 236 | +// Call the `createMovieRef()` function to get a reference to the mutation. |
| 237 | +const ref = createMovieRef(createMovieVars); |
| 238 | +// Variables can be defined inline as well. |
| 239 | +const ref = createMovieRef({ title: ..., genre: ..., imageUrl: ..., }); |
| 240 | + |
| 241 | +// You can also pass in a `DataConnect` instance to the `MutationRef` function. |
| 242 | +const dataConnect = getDataConnect(connectorConfig); |
| 243 | +const ref = createMovieRef(dataConnect, createMovieVars); |
| 244 | + |
| 245 | +// Call `executeMutation()` on the reference to execute the mutation. |
| 246 | +// You can use the `await` keyword to wait for the promise to resolve. |
| 247 | +const { data } = await executeMutation(ref); |
| 248 | + |
| 249 | +console.log(data.movie_insert); |
| 250 | + |
| 251 | +// Or, you can use the `Promise` API. |
| 252 | +executeMutation(ref).then((response) => { |
| 253 | + const data = response.data; |
| 254 | + console.log(data.movie_insert); |
| 255 | +}); |
| 256 | +``` |
| 257 | + |
0 commit comments