Krow/Krow-workspace
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

sdk creation in front-web and internal-api-harness

Browse Source
This commit is contained in:
José Salazar
2025-11-19 12:00:02 -05:00
parent a7bbcfe698
commit e8ffa4c5ef
33 changed files with 2210 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
dataconnect/connector/connector.yaml
View File

@@ -6,3 +6,8 @@ generate:
packageJsonDir: ../../frontend-web
react: true
angular: false
- outputDir: ../../internal-api-harness/src/dataconnect-generated
package: "@dataconnect/generated"
packageJsonDir: ../../internal-api-harness
react: true
angular: false

9
frontend-web/src/dataconnect-generated/.guides/config.json Normal file
View File

@@ -0,0 +1,9 @@
{
"description": "A set of guides for interacting with the generated firebase dataconnect sdk",
"mcpServers": {
"firebase": {
"command": "npx",
"args": ["-y", "firebase-tools@latest", "experimental:mcp"]
}
}
}

62
frontend-web/src/dataconnect-generated/.guides/setup.md Normal file
View File

@@ -0,0 +1,62 @@
# Setup
If the user hasn't already installed the SDK, always run the user's node package manager of choice, and install the package in the directory ../package.json.
For more information on where the library is located, look at the connector.yaml file.
```ts
import { initializeApp } from 'firebase/app';
initializeApp({
// fill in your project config here using the values from your Firebase project or from the `firebase_get_sdk_config` tool from the Firebase MCP server.
});
```
Then, you can run the SDK as needed.
```ts
import { ... } from '@dataconnect/generated';
```
## React
### Setup
The user should make sure to install the `@tanstack/react-query` package, along with `@tanstack-query-firebase/react` and `firebase`.
Then, they should initialize Firebase:
```ts
import { initializeApp } from 'firebase/app';
initializeApp(firebaseConfig); /* your config here. To generate this, you can use the `firebase_sdk_config` MCP tool */
```
Then, they should add a `QueryClientProvider` to their root of their application.
Here's an example:
```ts
import { initializeApp } from 'firebase/app';
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
const firebaseConfig = {
/* your config here. To generate this, you can use the `firebase_sdk_config` MCP tool */
};
// Initialize Firebase
const app = initializeApp(firebaseConfig);
// Create a TanStack Query client instance
const queryClient = new QueryClient();
function App() {
return (
// Provide the client to your App
<QueryClientProvider client={queryClient}>
<MyApplication />
</QueryClientProvider>
)
}
render(<App />, document.getElementById('root'));
```

69
frontend-web/src/dataconnect-generated/.guides/usage.md Normal file
View File

@@ -0,0 +1,69 @@
# Basic Usage
Always prioritize using a supported framework over using the generated SDK
directly. Supported frameworks simplify the developer experience and help ensure
best practices are followed.
### React
For each operation, there is a wrapper hook that can be used to call the operation.
Here are all of the hooks that get generated:
```ts
import { useCreateEvent, useListEvents } from '@dataconnect/generated/react';
// The types of these hooks are available in react/index.d.ts
const { data, isPending, isSuccess, isError, error } = useCreateEvent(createEventVars);
const { data, isPending, isSuccess, isError, error } = useListEvents();
```
Here's an example from a different generated SDK:
```ts
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>
}
```
## Advanced Usage
If a user is not using a supported framework, they can use the generated SDK directly.
Here's an example of how to use it with the first 5 operations:
```js
import { createEvent, listEvents } from '@dataconnect/generated';
// Operation CreateEvent: For variables, look at type CreateEventVars in ../index.d.ts
const { data } = await CreateEvent(dataConnect, createEventVars);
// Operation listEvents:
const { data } = await ListEvents(dataConnect);
```

317
frontend-web/src/dataconnect-generated/README.md Normal file
View File

@@ -0,0 +1,317 @@
# Generated TypeScript README
This README will guide you through the process of using the generated JavaScript SDK package for the connector `krow-connector`. It will also provide examples on how to use your generated SDK to call your Data Connect queries and mutations.
**If you're looking for the `React README`, you can find it at [`dataconnect-generated/react/README.md`](./react/README.md)**
***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**](#generated-javascript-readme)
- [**Accessing the connector**](#accessing-the-connector)
- [*Connecting to the local Emulator*](#connecting-to-the-local-emulator)
- [**Queries**](#queries)
- [*listEvents*](#listevents)
- [**Mutations**](#mutations)
- [*CreateEvent*](#createevent)
# 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 `krow-connector`. You can find more information about connectors in the [Data Connect documentation](https://firebase.google.com/docs/data-connect#how-does).
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](https://firebase.google.com/docs/data-connect/web-sdk#set-client).
```typescript
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](https://firebase.google.com/docs/data-connect/web-sdk#instrument-clients).
```typescript
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](#queries) and [mutations](#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 `krow-connector` 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).
## listEvents
You can execute the `listEvents` 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](./index.d.ts):
```typescript
listEvents(): QueryPromise<ListEventsData, undefined>;
interface ListEventsRef {
...
/* Allow users to create refs without passing in DataConnect */
(): QueryRef<ListEventsData, undefined>;
}
export const listEventsRef: ListEventsRef;
```
You can also pass in a `DataConnect` instance to the action shortcut function or `QueryRef` function.
```typescript
listEvents(dc: DataConnect): QueryPromise<ListEventsData, undefined>;
interface ListEventsRef {
...
(dc: DataConnect): QueryRef<ListEventsData, undefined>;
}
export const listEventsRef: ListEventsRef;
```
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 listEventsRef:
```typescript
const name = listEventsRef.operationName;
console.log(name);
```
### Variables
The `listEvents` query has no variables.
### Return Type
Recall that executing the `listEvents` query returns a `QueryPromise` that resolves to an object with a `data` property.
The `data` property is an object of type `ListEventsData`, which is defined in [dataconnect-generated/index.d.ts](./index.d.ts). It has the following fields:
```typescript
export interface ListEventsData {
events: ({
id: UUIDString;
eventName: string;
status: EventStatus;
date: TimestampString;
isRecurring: boolean;
recurrenceType?: RecurrenceType | null;
businessId: UUIDString;
vendorId?: UUIDString | null;
total?: number | null;
requested?: number | null;
} & Event_Key)[];
}
```
### Using `listEvents`'s action shortcut function
```typescript
import { getDataConnect } from 'firebase/data-connect';
import { connectorConfig, listEvents } from '@dataconnect/generated';
// Call the `listEvents()` function to execute the query.
// You can use the `await` keyword to wait for the promise to resolve.
const { data } = await listEvents();
// You can also pass in a `DataConnect` instance to the action shortcut function.
const dataConnect = getDataConnect(connectorConfig);
const { data } = await listEvents(dataConnect);
console.log(data.events);
// Or, you can use the `Promise` API.
listEvents().then((response) => {
const data = response.data;
console.log(data.events);
});
```
### Using `listEvents`'s `QueryRef` function
```typescript
import { getDataConnect, executeQuery } from 'firebase/data-connect';
import { connectorConfig, listEventsRef } from '@dataconnect/generated';
// Call the `listEventsRef()` function to get a reference to the query.
const ref = listEventsRef();
// You can also pass in a `DataConnect` instance to the `QueryRef` function.
const dataConnect = getDataConnect(connectorConfig);
const ref = listEventsRef(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.events);
// Or, you can use the `Promise` API.
executeQuery(ref).then((response) => {
const data = response.data;
console.log(data.events);
});
```
# 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 `krow-connector` 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).
## CreateEvent
You can execute the `CreateEvent` 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](./index.d.ts):
```typescript
createEvent(vars: CreateEventVariables): MutationPromise<CreateEventData, CreateEventVariables>;
interface CreateEventRef {
...
/* Allow users to create refs without passing in DataConnect */
(vars: CreateEventVariables): MutationRef<CreateEventData, CreateEventVariables>;
}
export const createEventRef: CreateEventRef;
```
You can also pass in a `DataConnect` instance to the action shortcut function or `MutationRef` function.
```typescript
createEvent(dc: DataConnect, vars: CreateEventVariables): MutationPromise<CreateEventData, CreateEventVariables>;
interface CreateEventRef {
...
(dc: DataConnect, vars: CreateEventVariables): MutationRef<CreateEventData, CreateEventVariables>;
}
export const createEventRef: CreateEventRef;
```
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 createEventRef:
```typescript
const name = createEventRef.operationName;
console.log(name);
```
### Variables
The `CreateEvent` mutation requires an argument of type `CreateEventVariables`, which is defined in [dataconnect-generated/index.d.ts](./index.d.ts). It has the following fields:
```typescript
export interface CreateEventVariables {
eventName: string;
isRecurring: boolean;
recurrenceType?: RecurrenceType | null;
businessId: UUIDString;
vendorId?: UUIDString | null;
status: EventStatus;
date: TimestampString;
shifts?: string | null;
total?: number | null;
requested?: number | null;
assignedStaff?: string | null;
}
```
### Return Type
Recall that executing the `CreateEvent` mutation returns a `MutationPromise` that resolves to an object with a `data` property.
The `data` property is an object of type `CreateEventData`, which is defined in [dataconnect-generated/index.d.ts](./index.d.ts). It has the following fields:
```typescript
export interface CreateEventData {
event_insert: Event_Key;
}
```
### Using `CreateEvent`'s action shortcut function
```typescript
import { getDataConnect } from 'firebase/data-connect';
import { connectorConfig, createEvent, CreateEventVariables } from '@dataconnect/generated';
// The `CreateEvent` mutation requires an argument of type `CreateEventVariables`:
const createEventVars: CreateEventVariables = {
eventName: ...,
isRecurring: ...,
recurrenceType: ..., // optional
businessId: ...,
vendorId: ..., // optional
status: ...,
date: ...,
shifts: ..., // optional
total: ..., // optional
requested: ..., // optional
assignedStaff: ..., // optional
};
// Call the `createEvent()` function to execute the mutation.
// You can use the `await` keyword to wait for the promise to resolve.
const { data } = await createEvent(createEventVars);
// Variables can be defined inline as well.
const { data } = await createEvent({ eventName: ..., isRecurring: ..., recurrenceType: ..., businessId: ..., vendorId: ..., status: ..., date: ..., shifts: ..., total: ..., requested: ..., assignedStaff: ..., });
// You can also pass in a `DataConnect` instance to the action shortcut function.
const dataConnect = getDataConnect(connectorConfig);
const { data } = await createEvent(dataConnect, createEventVars);
console.log(data.event_insert);
// Or, you can use the `Promise` API.
createEvent(createEventVars).then((response) => {
const data = response.data;
console.log(data.event_insert);
});
```
### Using `CreateEvent`'s `MutationRef` function
```typescript
import { getDataConnect, executeMutation } from 'firebase/data-connect';
import { connectorConfig, createEventRef, CreateEventVariables } from '@dataconnect/generated';
// The `CreateEvent` mutation requires an argument of type `CreateEventVariables`:
const createEventVars: CreateEventVariables = {
eventName: ...,
isRecurring: ...,
recurrenceType: ..., // optional
businessId: ...,
vendorId: ..., // optional
status: ...,
date: ...,
shifts: ..., // optional
total: ..., // optional
requested: ..., // optional
assignedStaff: ..., // optional
};
// Call the `createEventRef()` function to get a reference to the mutation.
const ref = createEventRef(createEventVars);
// Variables can be defined inline as well.
const ref = createEventRef({ eventName: ..., isRecurring: ..., recurrenceType: ..., businessId: ..., vendorId: ..., status: ..., date: ..., shifts: ..., total: ..., requested: ..., assignedStaff: ..., });
// You can also pass in a `DataConnect` instance to the `MutationRef` function.
const dataConnect = getDataConnect(connectorConfig);
const ref = createEventRef(dataConnect, createEventVars);
// 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.event_insert);
// Or, you can use the `Promise` API.
executeMutation(ref).then((response) => {
const data = response.data;
console.log(data.event_insert);
});
```

46
frontend-web/src/dataconnect-generated/esm/index.esm.js Normal file
View File

@@ -0,0 +1,46 @@
import { queryRef, executeQuery, mutationRef, executeMutation, validateArgs } from 'firebase/data-connect';
export const EventStatus = {
DRAFT: "DRAFT",
ACTIVE: "ACTIVE",
PENDING: "PENDING",
ASSIGNED: "ASSIGNED",
CONFIRMED: "CONFIRMED",
COMPLETED: "COMPLETED",
CANCELED: "CANCELED",
}
export const RecurrenceType = {
SINGLE: "SINGLE",
DATE_RANGE: "DATE_RANGE",
SCATTER: "SCATTER",
}
export const connectorConfig = {
connector: 'krow-connector',
service: 'krow-workforce-db',
location: 'us-central1'
};
export const createEventRef = (dcOrVars, vars) => {
const { dc: dcInstance, vars: inputVars} = validateArgs(connectorConfig, dcOrVars, vars, true);
dcInstance._useGeneratedSdk();
return mutationRef(dcInstance, 'CreateEvent', inputVars);
}
createEventRef.operationName = 'CreateEvent';
export function createEvent(dcOrVars, vars) {
return executeMutation(createEventRef(dcOrVars, vars));
}
export const listEventsRef = (dc) => {
const { dc: dcInstance} = validateArgs(connectorConfig, dc, undefined);
dcInstance._useGeneratedSdk();
return queryRef(dcInstance, 'listEvents');
}
listEventsRef.operationName = 'listEvents';
export function listEvents(dc) {
return executeQuery(listEventsRef(dc));
}

1
frontend-web/src/dataconnect-generated/esm/package.json Normal file
View File

@@ -0,0 +1 @@
{"type":"module"}

50
frontend-web/src/dataconnect-generated/index.cjs.js Normal file
View File

@@ -0,0 +1,50 @@
const { queryRef, executeQuery, mutationRef, executeMutation, validateArgs } = require('firebase/data-connect');
const EventStatus = {
DRAFT: "DRAFT",
ACTIVE: "ACTIVE",
PENDING: "PENDING",
ASSIGNED: "ASSIGNED",
CONFIRMED: "CONFIRMED",
COMPLETED: "COMPLETED",
CANCELED: "CANCELED",
}
exports.EventStatus = EventStatus;
const RecurrenceType = {
SINGLE: "SINGLE",
DATE_RANGE: "DATE_RANGE",
SCATTER: "SCATTER",
}
exports.RecurrenceType = RecurrenceType;
const connectorConfig = {
connector: 'krow-connector',
service: 'krow-workforce-db',
location: 'us-central1'
};
exports.connectorConfig = connectorConfig;
const createEventRef = (dcOrVars, vars) => {
const { dc: dcInstance, vars: inputVars} = validateArgs(connectorConfig, dcOrVars, vars, true);
dcInstance._useGeneratedSdk();
return mutationRef(dcInstance, 'CreateEvent', inputVars);
}
createEventRef.operationName = 'CreateEvent';
exports.createEventRef = createEventRef;
exports.createEvent = function createEvent(dcOrVars, vars) {
return executeMutation(createEventRef(dcOrVars, vars));
};
const listEventsRef = (dc) => {
const { dc: dcInstance} = validateArgs(connectorConfig, dc, undefined);
dcInstance._useGeneratedSdk();
return queryRef(dcInstance, 'listEvents');
}
listEventsRef.operationName = 'listEvents';
exports.listEventsRef = listEventsRef;
exports.listEvents = function listEvents(dc) {
return executeQuery(listEventsRef(dc));
};

90
frontend-web/src/dataconnect-generated/index.d.ts vendored Normal file
View File

@@ -0,0 +1,90 @@
import { ConnectorConfig, DataConnect, QueryRef, QueryPromise, MutationRef, MutationPromise } from 'firebase/data-connect';
export const connectorConfig: ConnectorConfig;
export type TimestampString = string;
export type UUIDString = string;
export type Int64String = string;
export type DateString = string;
export enum EventStatus {
DRAFT = "DRAFT",
ACTIVE = "ACTIVE",
PENDING = "PENDING",
ASSIGNED = "ASSIGNED",
CONFIRMED = "CONFIRMED",
COMPLETED = "COMPLETED",
CANCELED = "CANCELED",
};
export enum RecurrenceType {
SINGLE = "SINGLE",
DATE_RANGE = "DATE_RANGE",
SCATTER = "SCATTER",
};
export interface CreateEventData {
event_insert: Event_Key;
}
export interface CreateEventVariables {
eventName: string;
isRecurring: boolean;
recurrenceType?: RecurrenceType | null;
businessId: UUIDString;
vendorId?: UUIDString | null;
status: EventStatus;
date: TimestampString;
shifts?: string | null;
total?: number | null;
requested?: number | null;
assignedStaff?: string | null;
}
export interface Event_Key {
id: UUIDString;
__typename?: 'Event_Key';
}
export interface ListEventsData {
events: ({
id: UUIDString;
eventName: string;
status: EventStatus;
date: TimestampString;
isRecurring: boolean;
recurrenceType?: RecurrenceType | null;
businessId: UUIDString;
vendorId?: UUIDString | null;
total?: number | null;
requested?: number | null;
} & Event_Key)[];
}
interface CreateEventRef {
/* Allow users to create refs without passing in DataConnect */
(vars: CreateEventVariables): MutationRef<CreateEventData, CreateEventVariables>;
/* Allow users to pass in custom DataConnect instances */
(dc: DataConnect, vars: CreateEventVariables): MutationRef<CreateEventData, CreateEventVariables>;
operationName: string;
}
export const createEventRef: CreateEventRef;
export function createEvent(vars: CreateEventVariables): MutationPromise<CreateEventData, CreateEventVariables>;
export function createEvent(dc: DataConnect, vars: CreateEventVariables): MutationPromise<CreateEventData, CreateEventVariables>;
interface ListEventsRef {
/* Allow users to create refs without passing in DataConnect */
(): QueryRef<ListEventsData, undefined>;
/* Allow users to pass in custom DataConnect instances */
(dc: DataConnect): QueryRef<ListEventsData, undefined>;
operationName: string;
}
export const listEventsRef: ListEventsRef;
export function listEvents(): QueryPromise<ListEventsData, undefined>;
export function listEvents(dc: DataConnect): QueryPromise<ListEventsData, undefined>;

32
frontend-web/src/dataconnect-generated/package.json Normal file
View File

@@ -0,0 +1,32 @@
{
"name": "@dataconnect/generated",
"version": "1.0.0",
"author": "Firebase <firebase-support@google.com> (https://firebase.google.com/)",
"description": "Generated SDK For krow-connector",
"license": "Apache-2.0",
"engines": {
"node": " >=18.0"
},
"typings": "index.d.ts",
"module": "esm/index.esm.js",
"main": "index.cjs.js",
"browser": "esm/index.esm.js",
"exports": {
".": {
"types": "./index.d.ts",
"require": "./index.cjs.js",
"default": "./esm/index.esm.js"
},
"./react": {
"types": "./react/index.d.ts",
"require": "./react/index.cjs.js",
"import": "./react/esm/index.esm.js",
"default": "./react/esm/index.esm.js"
},
"./package.json": "./package.json"
},
"peerDependencies": {
"firebase": "^11.3.0 || ^12.0.0",
"@tanstack-query-firebase/react": "^2.0.0"
}
}

332
frontend-web/src/dataconnect-generated/react/README.md Normal file
View File

@@ -0,0 +1,332 @@
# Generated React README
This README will guide you through the process of using the generated React SDK package for the connector `krow-connector`. It will also provide examples on how to use your generated SDK to call your Data Connect queries and mutations.
**If you're looking for the `JavaScript README`, you can find it at [`dataconnect-generated/README.md`](../README.md)**
***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 `@dataconnect/generated/react` as shown below. Both CommonJS and ESM imports are supported.
You can also follow the instructions from the [Data Connect documentation](https://firebase.google.com/docs/data-connect/web-sdk#react).
# Table of Contents
- [**Overview**](#generated-react-readme)
- [**TanStack Query Firebase & TanStack React Query**](#tanstack-query-firebase-tanstack-react-query)
- [*Package Installation*](#installing-tanstack-query-firebase-and-tanstack-react-query-packages)
- [*Configuring TanStack Query*](#configuring-tanstack-query)
- [**Accessing the connector**](#accessing-the-connector)
- [*Connecting to the local Emulator*](#connecting-to-the-local-emulator)
- [**Queries**](#queries)
- [*listEvents*](#listevents)
- [**Mutations**](#mutations)
- [*CreateEvent*](#createevent)
# TanStack Query Firebase & TanStack React Query
This SDK provides [React](https://react.dev/) hooks generated specific to your application, for the operations found in the connector `krow-connector`. These hooks are generated using [TanStack Query Firebase](https://react-query-firebase.invertase.dev/) by our partners at Invertase, a library built on top of [TanStack React Query v5](https://tanstack.com/query/v5/docs/framework/react/overview).
***You do not need to be familiar with Tanstack Query or Tanstack Query Firebase to use this SDK.*** However, you may find it useful to learn more about them, as they will empower you as a user of this Generated React SDK.
## Installing TanStack Query Firebase and TanStack React Query Packages
In order to use the React generated SDK, you must install the `TanStack React Query` and `TanStack Query Firebase` packages.
```bash
npm i --save @tanstack/react-query @tanstack-query-firebase/react
```
```bash
npm i --save firebase@latest # Note: React has a peer dependency on ^11.3.0
```
You can also follow the installation instructions from the [Data Connect documentation](https://firebase.google.com/docs/data-connect/web-sdk#tanstack-install), or the [TanStack Query Firebase documentation](https://react-query-firebase.invertase.dev/react) and [TanStack React Query documentation](https://tanstack.com/query/v5/docs/framework/react/installation).
## Configuring TanStack Query
In order to use the React generated SDK in your application, you must wrap your application's component tree in a `QueryClientProvider` component from TanStack React Query. None of your generated React SDK hooks will work without this provider.
```javascript
import { QueryClientProvider } from '@tanstack/react-query';
// Create a TanStack Query client instance
const queryClient = new QueryClient()
function App() {
return (
// Provide the client to your App
<QueryClientProvider client={queryClient}>
<MyApplication />
</QueryClientProvider>
)
}
```
To learn more about `QueryClientProvider`, see the [TanStack React Query documentation](https://tanstack.com/query/latest/docs/framework/react/quick-start) and the [TanStack Query Firebase documentation](https://invertase.docs.page/tanstack-query-firebase/react#usage).
# 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 `krow-connector`.
You can find more information about connectors in the [Data Connect documentation](https://firebase.google.com/docs/data-connect#how-does).
```javascript
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](https://firebase.google.com/docs/data-connect/web-sdk#emulator-react-angular).
```javascript
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](#queries) and [mutations](#mutations) using the hooks provided from your generated React SDK.
# Queries
The React generated SDK provides Query hook functions that call and return [`useDataConnectQuery`](https://react-query-firebase.invertase.dev/react/data-connect/querying) hooks from TanStack Query Firebase.
Calling these hook functions will return a `UseQueryResult` object. This object holds the state of your Query, including whether the Query is loading, has completed, or has succeeded/failed, and the most recent data returned by the Query, among other things. To learn more about these hooks and how to use them, see the [TanStack Query Firebase documentation](https://react-query-firebase.invertase.dev/react/data-connect/querying).
TanStack React Query caches the results of your Queries, so using the same Query hook function in multiple places in your application allows the entire application to automatically see updates to that Query's data.
Query hooks execute their Queries automatically when called, and periodically refresh, unless you change the `queryOptions` for the Query. To learn how to stop a Query from automatically executing, including how to make a query "lazy", see the [TanStack React Query documentation](https://tanstack.com/query/latest/docs/framework/react/guides/disabling-queries).
To learn more about TanStack React Query's Queries, see the [TanStack React Query documentation](https://tanstack.com/query/v5/docs/framework/react/guides/queries).
## Using Query Hooks
Here's a general overview of how to use the generated Query hooks in your code:
- If the Query has no variables, the Query hook function does not require arguments.
- If the Query has any required variables, the Query hook function will require at least one argument: an object that contains all the required variables for the Query.
- If the Query has some required and some optional variables, only required variables are necessary in the variables argument object, and optional variables may be provided as well.
- If all of the Query's variables are optional, the Query hook function does not require any arguments.
- Query hook 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.
- Query hooks functions can be called with or without passing in an `options` argument of type `useDataConnectQueryOptions`. To learn more about the `options` argument, see the [TanStack React Query documentation](https://tanstack.com/query/v5/docs/framework/react/guides/query-options).
- ***Special case:*** If the Query has all optional variables and you would like to provide an `options` argument to the Query hook function without providing any variables, you must pass `undefined` where you would normally pass the Query's variables, and then may provide the `options` argument.
Below are examples of how to use the `krow-connector` connector's generated Query hook 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#operations-react-angular).
## listEvents
You can execute the `listEvents` Query using the following Query hook function, which is defined in [dataconnect-generated/react/index.d.ts](./index.d.ts):
```javascript
useListEvents(dc: DataConnect, options?: useDataConnectQueryOptions<ListEventsData>): UseDataConnectQueryResult<ListEventsData, undefined>;
```
You can also pass in a `DataConnect` instance to the Query hook function.
```javascript
useListEvents(options?: useDataConnectQueryOptions<ListEventsData>): UseDataConnectQueryResult<ListEventsData, undefined>;
```
### Variables
The `listEvents` Query has no variables.
### Return Type
Recall that calling the `listEvents` Query hook function returns a `UseQueryResult` object. This object holds the state of your Query, including whether the Query is loading, has completed, or has succeeded/failed, and any data returned by the Query, among other things.
To check the status of a Query, use the `UseQueryResult.status` field. You can also check for pending / success / error status using the `UseQueryResult.isPending`, `UseQueryResult.isSuccess`, and `UseQueryResult.isError` fields.
To access the data returned by a Query, use the `UseQueryResult.data` field. The data for the `listEvents` Query is of type `ListEventsData`, which is defined in [dataconnect-generated/index.d.ts](../index.d.ts). It has the following fields:
```javascript
export interface ListEventsData {
events: ({
id: UUIDString;
eventName: string;
status: EventStatus;
date: TimestampString;
isRecurring: boolean;
recurrenceType?: RecurrenceType | null;
businessId: UUIDString;
vendorId?: UUIDString | null;
total?: number | null;
requested?: number | null;
} & Event_Key)[];
}
```
To learn more about the `UseQueryResult` object, see the [TanStack React Query documentation](https://tanstack.com/query/v5/docs/framework/react/reference/useQuery).
### Using `listEvents`'s Query hook function
```javascript
import { getDataConnect } from 'firebase/data-connect';
import { connectorConfig } from '@dataconnect/generated';
import { useListEvents } from '@dataconnect/generated/react'
export default function ListEventsComponent() {
// You don't have to do anything to "execute" the Query.
// Call the Query hook function to get a `UseQueryResult` object which holds the state of your Query.
const query = useListEvents();
// You can also pass in a `DataConnect` instance to the Query hook function.
const dataConnect = getDataConnect(connectorConfig);
const query = useListEvents(dataConnect);
// You can also pass in a `useDataConnectQueryOptions` object to the Query hook function.
const options = { staleTime: 5 * 1000 };
const query = useListEvents(options);
// You can also pass both a `DataConnect` instance and a `useDataConnectQueryOptions` object.
const dataConnect = getDataConnect(connectorConfig);
const options = { staleTime: 5 * 1000 };
const query = useListEvents(dataConnect, options);
// Then, you can render your component dynamically based on the status of the Query.
if (query.isPending) {
return <div>Loading...</div>;
}
if (query.isError) {
return <div>Error: {query.error.message}</div>;
}
// If the Query is successful, you can access the data returned using the `UseQueryResult.data` field.
if (query.isSuccess) {
console.log(query.data.events);
}
return <div>Query execution {query.isSuccess ? 'successful' : 'failed'}!</div>;
}
```
# Mutations
The React generated SDK provides Mutations hook functions that call and return [`useDataConnectMutation`](https://react-query-firebase.invertase.dev/react/data-connect/mutations) hooks from TanStack Query Firebase.
Calling these hook functions will return a `UseMutationResult` object. This object holds the state of your Mutation, including whether the Mutation is loading, has completed, or has succeeded/failed, and the most recent data returned by the Mutation, among other things. To learn more about these hooks and how to use them, see the [TanStack Query Firebase documentation](https://react-query-firebase.invertase.dev/react/data-connect/mutations).
Mutation hooks do not execute their Mutations automatically when called. Rather, after calling the Mutation hook function and getting a `UseMutationResult` object, you must call the `UseMutationResult.mutate()` function to execute the Mutation.
To learn more about TanStack React Query's Mutations, see the [TanStack React Query documentation](https://tanstack.com/query/v5/docs/framework/react/guides/mutations).
## Using Mutation Hooks
Here's a general overview of how to use the generated Mutation hooks in your code:
- Mutation hook functions are not called with the arguments to the Mutation. Instead, arguments are passed to `UseMutationResult.mutate()`.
- If the Mutation has no variables, the `mutate()` function does not require arguments.
- If the Mutation has any required variables, the `mutate()` function will require at least one argument: an object that contains all the required variables for the Mutation.
- If the Mutation has some required and some optional variables, only required variables are necessary in the variables argument object, and optional variables may be provided as well.
- If all of the Mutation's variables are optional, the Mutation hook function does not require any arguments.
- Mutation hook 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.
- Mutation hooks also accept an `options` argument of type `useDataConnectMutationOptions`. To learn more about the `options` argument, see the [TanStack React Query documentation](https://tanstack.com/query/v5/docs/framework/react/guides/mutations#mutation-side-effects).
- `UseMutationResult.mutate()` also accepts an `options` argument of type `useDataConnectMutationOptions`.
- ***Special case:*** If the Mutation has no arguments (or all optional arguments and you wish to provide none), and you want to pass `options` to `UseMutationResult.mutate()`, you must pass `undefined` where you would normally pass the Mutation's arguments, and then may provide the options argument.
Below are examples of how to use the `krow-connector` connector's generated Mutation hook 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#operations-react-angular).
## CreateEvent
You can execute the `CreateEvent` Mutation using the `UseMutationResult` object returned by the following Mutation hook function (which is defined in [dataconnect-generated/react/index.d.ts](./index.d.ts)):
```javascript
useCreateEvent(options?: useDataConnectMutationOptions<CreateEventData, FirebaseError, CreateEventVariables>): UseDataConnectMutationResult<CreateEventData, CreateEventVariables>;
```
You can also pass in a `DataConnect` instance to the Mutation hook function.
```javascript
useCreateEvent(dc: DataConnect, options?: useDataConnectMutationOptions<CreateEventData, FirebaseError, CreateEventVariables>): UseDataConnectMutationResult<CreateEventData, CreateEventVariables>;
```
### Variables
The `CreateEvent` Mutation requires an argument of type `CreateEventVariables`, which is defined in [dataconnect-generated/index.d.ts](../index.d.ts). It has the following fields:
```javascript
export interface CreateEventVariables {
eventName: string;
isRecurring: boolean;
recurrenceType?: RecurrenceType | null;
businessId: UUIDString;
vendorId?: UUIDString | null;
status: EventStatus;
date: TimestampString;
shifts?: string | null;
total?: number | null;
requested?: number | null;
assignedStaff?: string | null;
}
```
### Return Type
Recall that calling the `CreateEvent` Mutation hook function returns a `UseMutationResult` object. This object holds the state of your Mutation, including whether the Mutation is loading, has completed, or has succeeded/failed, among other things.
To check the status of a Mutation, use the `UseMutationResult.status` field. You can also check for pending / success / error status using the `UseMutationResult.isPending`, `UseMutationResult.isSuccess`, and `UseMutationResult.isError` fields.
To execute the Mutation, call `UseMutationResult.mutate()`. This function executes the Mutation, but does not return the data from the Mutation.
To access the data returned by a Mutation, use the `UseMutationResult.data` field. The data for the `CreateEvent` Mutation is of type `CreateEventData`, which is defined in [dataconnect-generated/index.d.ts](../index.d.ts). It has the following fields:
```javascript
export interface CreateEventData {
event_insert: Event_Key;
}
```
To learn more about the `UseMutationResult` object, see the [TanStack React Query documentation](https://tanstack.com/query/v5/docs/framework/react/reference/useMutation).
### Using `CreateEvent`'s Mutation hook function
```javascript
import { getDataConnect } from 'firebase/data-connect';
import { connectorConfig, CreateEventVariables } from '@dataconnect/generated';
import { useCreateEvent } from '@dataconnect/generated/react'
export default function CreateEventComponent() {
// Call the Mutation hook function to get a `UseMutationResult` object which holds the state of your Mutation.
const mutation = useCreateEvent();
// You can also pass in a `DataConnect` instance to the Mutation hook function.
const dataConnect = getDataConnect(connectorConfig);
const mutation = useCreateEvent(dataConnect);
// You can also pass in a `useDataConnectMutationOptions` object to the Mutation hook function.
const options = {
onSuccess: () => { console.log('Mutation succeeded!'); }
};
const mutation = useCreateEvent(options);
// You can also pass both a `DataConnect` instance and a `useDataConnectMutationOptions` object.
const dataConnect = getDataConnect(connectorConfig);
const options = {
onSuccess: () => { console.log('Mutation succeeded!'); }
};
const mutation = useCreateEvent(dataConnect, options);
// After calling the Mutation hook function, you must call `UseMutationResult.mutate()` to execute the Mutation.
// The `useCreateEvent` Mutation requires an argument of type `CreateEventVariables`:
const createEventVars: CreateEventVariables = {
eventName: ...,
isRecurring: ...,
recurrenceType: ..., // optional
businessId: ...,
vendorId: ..., // optional
status: ...,
date: ...,
shifts: ..., // optional
total: ..., // optional
requested: ..., // optional
assignedStaff: ..., // optional
};
mutation.mutate(createEventVars);
// Variables can be defined inline as well.
mutation.mutate({ eventName: ..., isRecurring: ..., recurrenceType: ..., businessId: ..., vendorId: ..., status: ..., date: ..., shifts: ..., total: ..., requested: ..., assignedStaff: ..., });
// You can also pass in a `useDataConnectMutationOptions` object to `UseMutationResult.mutate()`.
const options = {
onSuccess: () => { console.log('Mutation succeeded!'); }
};
mutation.mutate(createEventVars, options);
// Then, you can render your component dynamically based on the status of the Mutation.
if (mutation.isPending) {
return <div>Loading...</div>;
}
if (mutation.isError) {
return <div>Error: {mutation.error.message}</div>;
}
// If the Mutation is successful, you can access the data returned using the `UseMutationResult.data` field.
if (mutation.isSuccess) {
console.log(mutation.data.event_insert);
}
return <div>Mutation execution {mutation.isSuccess ? 'successful' : 'failed'}!</div>;
}
```

18
frontend-web/src/dataconnect-generated/react/esm/index.esm.js Normal file
View File

@@ -0,0 +1,18 @@
import { createEventRef, listEventsRef, connectorConfig } from '../../esm/index.esm.js';
import { validateArgs, CallerSdkTypeEnum } from 'firebase/data-connect';
import { useDataConnectQuery, useDataConnectMutation, validateReactArgs } from '@tanstack-query-firebase/react/data-connect';
export function useCreateEvent(dcOrOptions, options) {
const { dc: dcInstance, vars: inputOpts } = validateArgs(connectorConfig, dcOrOptions, options);
function refFactory(vars) {
return createEventRef(dcInstance, vars);
}
return useDataConnectMutation(refFactory, inputOpts, CallerSdkTypeEnum.GeneratedReact);
}
export function useListEvents(dcOrOptions, options) {
const { dc: dcInstance, options: inputOpts } = validateReactArgs(connectorConfig, dcOrOptions, options);
const ref = listEventsRef(dcInstance);
return useDataConnectQuery(ref, inputOpts, CallerSdkTypeEnum.GeneratedReact);
}

1
frontend-web/src/dataconnect-generated/react/esm/package.json Normal file
View File

@@ -0,0 +1 @@
{"type":"module"}

18
frontend-web/src/dataconnect-generated/react/index.cjs.js Normal file
View File

@@ -0,0 +1,18 @@
const { createEventRef, listEventsRef, connectorConfig } = require('../index.cjs.js');
const { validateArgs, CallerSdkTypeEnum } = require('firebase/data-connect');
const { useDataConnectQuery, useDataConnectMutation, validateReactArgs } = require('@tanstack-query-firebase/react/data-connect');
exports.useCreateEvent = function useCreateEvent(dcOrOptions, options) {
const { dc: dcInstance, vars: inputOpts } = validateArgs(connectorConfig, dcOrOptions, options);
function refFactory(vars) {
return createEventRef(dcInstance, vars);
}
return useDataConnectMutation(refFactory, inputOpts, CallerSdkTypeEnum.GeneratedReact);
}
exports.useListEvents = function useListEvents(dcOrOptions, options) {
const { dc: dcInstance, options: inputOpts } = validateReactArgs(connectorConfig, dcOrOptions, options);
const ref = listEventsRef(dcInstance);
return useDataConnectQuery(ref, inputOpts, CallerSdkTypeEnum.GeneratedReact);
}

12
frontend-web/src/dataconnect-generated/react/index.d.ts vendored Normal file
View File

@@ -0,0 +1,12 @@
import { CreateEventData, CreateEventVariables, ListEventsData } from '../';
import { UseDataConnectQueryResult, useDataConnectQueryOptions, UseDataConnectMutationResult, useDataConnectMutationOptions} from '@tanstack-query-firebase/react/data-connect';
import { UseQueryResult, UseMutationResult} from '@tanstack/react-query';
import { DataConnect } from 'firebase/data-connect';
import { FirebaseError } from 'firebase/app';
export function useCreateEvent(options?: useDataConnectMutationOptions<CreateEventData, FirebaseError, CreateEventVariables>): UseDataConnectMutationResult<CreateEventData, CreateEventVariables>;
export function useCreateEvent(dc: DataConnect, options?: useDataConnectMutationOptions<CreateEventData, FirebaseError, CreateEventVariables>): UseDataConnectMutationResult<CreateEventData, CreateEventVariables>;
export function useListEvents(options?: useDataConnectQueryOptions<ListEventsData>): UseDataConnectQueryResult<ListEventsData, undefined>;
export function useListEvents(dc: DataConnect, options?: useDataConnectQueryOptions<ListEventsData>): UseDataConnectQueryResult<ListEventsData, undefined>;

17
frontend-web/src/dataconnect-generated/react/package.json Normal file
View File

@@ -0,0 +1,17 @@
{
"name": "@dataconnect/generated-react",
"version": "1.0.0",
"author": "Firebase <firebase-support@google.com> (https://firebase.google.com/)",
"description": "Generated SDK For krow-connector",
"license": "Apache-2.0",
"engines": {
"node": " >=18.0"
},
"typings": "index.d.ts",
"main": "index.cjs.js",
"module": "esm/index.esm.js",
"browser": "esm/index.esm.js",
"peerDependencies": {
"@tanstack-query-firebase/react": "^2.0.0"
}
}

56
internal-api-harness/package-lock.json generated
View File

@@ -8,6 +8,7 @@
"name": "internal-api-harness",
"version": "0.0.0",
"dependencies": {
"@dataconnect/generated": "file:src/dataconnect-generated",
"@radix-ui/react-collapsible": "^1.1.12",
"@radix-ui/react-label": "^2.1.8",
"@radix-ui/react-select": "^2.2.6",
@@ -335,6 +336,10 @@
"node": ">=6.9.0"
}
},
"node_modules/@dataconnect/generated": {
"resolved": "src/dataconnect-generated",
"link": true
},
"node_modules/@esbuild/aix-ppc64": {
"version": "0.25.12",
"resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.25.12.tgz",
@@ -3092,6 +3097,45 @@
"win32"
]
},
"node_modules/@tanstack-query-firebase/react": {
"version": "2.1.1",
"resolved": "https://registry.npmjs.org/@tanstack-query-firebase/react/-/react-2.1.1.tgz",
"integrity": "sha512-1hOEcfxLgorg0TwadBJeeEvoD7P4JMCJLhdO1doUQWZRs83WmwTlBJGv8GiO1y2KWaKjQh+JdgsuYCqG2dPXcA==",
"license": "Apache-2.0",
"peer": true,
"peerDependencies": {
"@tanstack/react-query": "^5",
"firebase": "^11.3.0 || ^12.0.0"
}
},
"node_modules/@tanstack/query-core": {
"version": "5.90.10",
"resolved": "https://registry.npmjs.org/@tanstack/query-core/-/query-core-5.90.10.tgz",
"integrity": "sha512-EhZVFu9rl7GfRNuJLJ3Y7wtbTnENsvzp+YpcAV7kCYiXni1v8qZh++lpw4ch4rrwC0u/EZRnBHIehzCGzwXDSQ==",
"license": "MIT",
"peer": true,
"funding": {
"type": "github",
"url": "https://github.com/sponsors/tannerlinsley"
}
},
"node_modules/@tanstack/react-query": {
"version": "5.90.10",
"resolved": "https://registry.npmjs.org/@tanstack/react-query/-/react-query-5.90.10.tgz",
"integrity": "sha512-BKLss9Y8PQ9IUjPYQiv3/Zmlx92uxffUOX8ZZNoQlCIZBJPT5M+GOMQj7xislvVQ6l1BstBjcX0XB/aHfFYVNw==",
"license": "MIT",
"peer": true,
"dependencies": {
"@tanstack/query-core": "5.90.10"
},
"funding": {
"type": "github",
"url": "https://github.com/sponsors/tannerlinsley"
},
"peerDependencies": {
"react": "^18 || ^19"
}
},
"node_modules/@types/babel__core": {
"version": "7.20.5",
"resolved": "https://registry.npmjs.org/@types/babel__core/-/babel__core-7.20.5.tgz",
@@ -6606,6 +6650,18 @@
"peerDependencies": {
"zod": "^3.25.0 || ^4.0.0"
}
},
"src/dataconnect-generated": {
"name": "@dataconnect/generated",
"version": "1.0.0",
"license": "Apache-2.0",
"engines": {
"node": " >=18.0"
},
"peerDependencies": {
"@tanstack-query-firebase/react": "^2.0.0",
"firebase": "^11.3.0 || ^12.0.0"
}
}
}
}

1
internal-api-harness/package.json
View File

@@ -10,6 +10,7 @@
"preview": "vite preview"
},
"dependencies": {
"@dataconnect/generated": "file:src/dataconnect-generated",
"@radix-ui/react-collapsible": "^1.1.12",
"@radix-ui/react-label": "^2.1.8",
"@radix-ui/react-select": "^2.2.6",

9
internal-api-harness/src/dataconnect-generated/.guides/config.json Normal file
View File

@@ -0,0 +1,9 @@
{
"description": "A set of guides for interacting with the generated firebase dataconnect sdk",
"mcpServers": {
"firebase": {
"command": "npx",
"args": ["-y", "firebase-tools@latest", "experimental:mcp"]
}
}
}

62
internal-api-harness/src/dataconnect-generated/.guides/setup.md Normal file
View File

@@ -0,0 +1,62 @@
# Setup
If the user hasn't already installed the SDK, always run the user's node package manager of choice, and install the package in the directory ../package.json.
For more information on where the library is located, look at the connector.yaml file.
```ts
import { initializeApp } from 'firebase/app';
initializeApp({
// fill in your project config here using the values from your Firebase project or from the `firebase_get_sdk_config` tool from the Firebase MCP server.
});
```
Then, you can run the SDK as needed.
```ts
import { ... } from '@dataconnect/generated';
```
## React
### Setup
The user should make sure to install the `@tanstack/react-query` package, along with `@tanstack-query-firebase/react` and `firebase`.
Then, they should initialize Firebase:
```ts
import { initializeApp } from 'firebase/app';
initializeApp(firebaseConfig); /* your config here. To generate this, you can use the `firebase_sdk_config` MCP tool */
```
Then, they should add a `QueryClientProvider` to their root of their application.
Here's an example:
```ts
import { initializeApp } from 'firebase/app';
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
const firebaseConfig = {
/* your config here. To generate this, you can use the `firebase_sdk_config` MCP tool */
};
// Initialize Firebase
const app = initializeApp(firebaseConfig);
// Create a TanStack Query client instance
const queryClient = new QueryClient();
function App() {
return (
// Provide the client to your App
<QueryClientProvider client={queryClient}>
<MyApplication />
</QueryClientProvider>
)
}
render(<App />, document.getElementById('root'));
```

69
internal-api-harness/src/dataconnect-generated/.guides/usage.md Normal file
View File

@@ -0,0 +1,69 @@
# Basic Usage
Always prioritize using a supported framework over using the generated SDK
directly. Supported frameworks simplify the developer experience and help ensure
best practices are followed.
### React
For each operation, there is a wrapper hook that can be used to call the operation.
Here are all of the hooks that get generated:
```ts
import { useCreateEvent, useListEvents } from '@dataconnect/generated/react';
// The types of these hooks are available in react/index.d.ts
const { data, isPending, isSuccess, isError, error } = useCreateEvent(createEventVars);
const { data, isPending, isSuccess, isError, error } = useListEvents();
```
Here's an example from a different generated SDK:
```ts
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>
}
```
## Advanced Usage
If a user is not using a supported framework, they can use the generated SDK directly.
Here's an example of how to use it with the first 5 operations:
```js
import { createEvent, listEvents } from '@dataconnect/generated';
// Operation CreateEvent: For variables, look at type CreateEventVars in ../index.d.ts
const { data } = await CreateEvent(dataConnect, createEventVars);
// Operation listEvents:
const { data } = await ListEvents(dataConnect);
```

317
internal-api-harness/src/dataconnect-generated/README.md Normal file
View File

@@ -0,0 +1,317 @@
# Generated TypeScript README
This README will guide you through the process of using the generated JavaScript SDK package for the connector `krow-connector`. It will also provide examples on how to use your generated SDK to call your Data Connect queries and mutations.
**If you're looking for the `React README`, you can find it at [`dataconnect-generated/react/README.md`](./react/README.md)**
***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**](#generated-javascript-readme)
- [**Accessing the connector**](#accessing-the-connector)
- [*Connecting to the local Emulator*](#connecting-to-the-local-emulator)
- [**Queries**](#queries)
- [*listEvents*](#listevents)
- [**Mutations**](#mutations)
- [*CreateEvent*](#createevent)
# 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 `krow-connector`. You can find more information about connectors in the [Data Connect documentation](https://firebase.google.com/docs/data-connect#how-does).
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](https://firebase.google.com/docs/data-connect/web-sdk#set-client).
```typescript
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](https://firebase.google.com/docs/data-connect/web-sdk#instrument-clients).
```typescript
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](#queries) and [mutations](#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 `krow-connector` 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).
## listEvents
You can execute the `listEvents` 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](./index.d.ts):
```typescript
listEvents(): QueryPromise<ListEventsData, undefined>;
interface ListEventsRef {
...
/* Allow users to create refs without passing in DataConnect */
(): QueryRef<ListEventsData, undefined>;
}
export const listEventsRef: ListEventsRef;
```
You can also pass in a `DataConnect` instance to the action shortcut function or `QueryRef` function.
```typescript
listEvents(dc: DataConnect): QueryPromise<ListEventsData, undefined>;
interface ListEventsRef {
...
(dc: DataConnect): QueryRef<ListEventsData, undefined>;
}
export const listEventsRef: ListEventsRef;
```
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 listEventsRef:
```typescript
const name = listEventsRef.operationName;
console.log(name);
```
### Variables
The `listEvents` query has no variables.
### Return Type
Recall that executing the `listEvents` query returns a `QueryPromise` that resolves to an object with a `data` property.
The `data` property is an object of type `ListEventsData`, which is defined in [dataconnect-generated/index.d.ts](./index.d.ts). It has the following fields:
```typescript
export interface ListEventsData {
events: ({
id: UUIDString;
eventName: string;
status: EventStatus;
date: TimestampString;
isRecurring: boolean;
recurrenceType?: RecurrenceType | null;
businessId: UUIDString;
vendorId?: UUIDString | null;
total?: number | null;
requested?: number | null;
} & Event_Key)[];
}
```
### Using `listEvents`'s action shortcut function
```typescript
import { getDataConnect } from 'firebase/data-connect';
import { connectorConfig, listEvents } from '@dataconnect/generated';
// Call the `listEvents()` function to execute the query.
// You can use the `await` keyword to wait for the promise to resolve.
const { data } = await listEvents();
// You can also pass in a `DataConnect` instance to the action shortcut function.
const dataConnect = getDataConnect(connectorConfig);
const { data } = await listEvents(dataConnect);
console.log(data.events);
// Or, you can use the `Promise` API.
listEvents().then((response) => {
const data = response.data;
console.log(data.events);
});
```
### Using `listEvents`'s `QueryRef` function
```typescript
import { getDataConnect, executeQuery } from 'firebase/data-connect';
import { connectorConfig, listEventsRef } from '@dataconnect/generated';
// Call the `listEventsRef()` function to get a reference to the query.
const ref = listEventsRef();
// You can also pass in a `DataConnect` instance to the `QueryRef` function.
const dataConnect = getDataConnect(connectorConfig);
const ref = listEventsRef(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.events);
// Or, you can use the `Promise` API.
executeQuery(ref).then((response) => {
const data = response.data;
console.log(data.events);
});
```
# 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 `krow-connector` 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).
## CreateEvent
You can execute the `CreateEvent` 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](./index.d.ts):
```typescript
createEvent(vars: CreateEventVariables): MutationPromise<CreateEventData, CreateEventVariables>;
interface CreateEventRef {
...
/* Allow users to create refs without passing in DataConnect */
(vars: CreateEventVariables): MutationRef<CreateEventData, CreateEventVariables>;
}
export const createEventRef: CreateEventRef;
```
You can also pass in a `DataConnect` instance to the action shortcut function or `MutationRef` function.
```typescript
createEvent(dc: DataConnect, vars: CreateEventVariables): MutationPromise<CreateEventData, CreateEventVariables>;
interface CreateEventRef {
...
(dc: DataConnect, vars: CreateEventVariables): MutationRef<CreateEventData, CreateEventVariables>;
}
export const createEventRef: CreateEventRef;
```
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 createEventRef:
```typescript
const name = createEventRef.operationName;
console.log(name);
```
### Variables
The `CreateEvent` mutation requires an argument of type `CreateEventVariables`, which is defined in [dataconnect-generated/index.d.ts](./index.d.ts). It has the following fields:
```typescript
export interface CreateEventVariables {
eventName: string;
isRecurring: boolean;
recurrenceType?: RecurrenceType | null;
businessId: UUIDString;
vendorId?: UUIDString | null;
status: EventStatus;
date: TimestampString;
shifts?: string | null;
total?: number | null;
requested?: number | null;
assignedStaff?: string | null;
}
```
### Return Type
Recall that executing the `CreateEvent` mutation returns a `MutationPromise` that resolves to an object with a `data` property.
The `data` property is an object of type `CreateEventData`, which is defined in [dataconnect-generated/index.d.ts](./index.d.ts). It has the following fields:
```typescript
export interface CreateEventData {
event_insert: Event_Key;
}
```
### Using `CreateEvent`'s action shortcut function
```typescript
import { getDataConnect } from 'firebase/data-connect';
import { connectorConfig, createEvent, CreateEventVariables } from '@dataconnect/generated';
// The `CreateEvent` mutation requires an argument of type `CreateEventVariables`:
const createEventVars: CreateEventVariables = {
eventName: ...,
isRecurring: ...,
recurrenceType: ..., // optional
businessId: ...,
vendorId: ..., // optional
status: ...,
date: ...,
shifts: ..., // optional
total: ..., // optional
requested: ..., // optional
assignedStaff: ..., // optional
};
// Call the `createEvent()` function to execute the mutation.
// You can use the `await` keyword to wait for the promise to resolve.
const { data } = await createEvent(createEventVars);
// Variables can be defined inline as well.
const { data } = await createEvent({ eventName: ..., isRecurring: ..., recurrenceType: ..., businessId: ..., vendorId: ..., status: ..., date: ..., shifts: ..., total: ..., requested: ..., assignedStaff: ..., });
// You can also pass in a `DataConnect` instance to the action shortcut function.
const dataConnect = getDataConnect(connectorConfig);
const { data } = await createEvent(dataConnect, createEventVars);
console.log(data.event_insert);
// Or, you can use the `Promise` API.
createEvent(createEventVars).then((response) => {
const data = response.data;
console.log(data.event_insert);
});
```
### Using `CreateEvent`'s `MutationRef` function
```typescript
import { getDataConnect, executeMutation } from 'firebase/data-connect';
import { connectorConfig, createEventRef, CreateEventVariables } from '@dataconnect/generated';
// The `CreateEvent` mutation requires an argument of type `CreateEventVariables`:
const createEventVars: CreateEventVariables = {
eventName: ...,
isRecurring: ...,
recurrenceType: ..., // optional
businessId: ...,
vendorId: ..., // optional
status: ...,
date: ...,
shifts: ..., // optional
total: ..., // optional
requested: ..., // optional
assignedStaff: ..., // optional
};
// Call the `createEventRef()` function to get a reference to the mutation.
const ref = createEventRef(createEventVars);
// Variables can be defined inline as well.
const ref = createEventRef({ eventName: ..., isRecurring: ..., recurrenceType: ..., businessId: ..., vendorId: ..., status: ..., date: ..., shifts: ..., total: ..., requested: ..., assignedStaff: ..., });
// You can also pass in a `DataConnect` instance to the `MutationRef` function.
const dataConnect = getDataConnect(connectorConfig);
const ref = createEventRef(dataConnect, createEventVars);
// 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.event_insert);
// Or, you can use the `Promise` API.
executeMutation(ref).then((response) => {
const data = response.data;
console.log(data.event_insert);
});
```

46
internal-api-harness/src/dataconnect-generated/esm/index.esm.js Normal file
View File

@@ -0,0 +1,46 @@
import { queryRef, executeQuery, mutationRef, executeMutation, validateArgs } from 'firebase/data-connect';
export const EventStatus = {
DRAFT: "DRAFT",
ACTIVE: "ACTIVE",
PENDING: "PENDING",
ASSIGNED: "ASSIGNED",
CONFIRMED: "CONFIRMED",
COMPLETED: "COMPLETED",
CANCELED: "CANCELED",
}
export const RecurrenceType = {
SINGLE: "SINGLE",
DATE_RANGE: "DATE_RANGE",
SCATTER: "SCATTER",
}
export const connectorConfig = {
connector: 'krow-connector',
service: 'krow-workforce-db',
location: 'us-central1'
};
export const createEventRef = (dcOrVars, vars) => {
const { dc: dcInstance, vars: inputVars} = validateArgs(connectorConfig, dcOrVars, vars, true);
dcInstance._useGeneratedSdk();
return mutationRef(dcInstance, 'CreateEvent', inputVars);
}
createEventRef.operationName = 'CreateEvent';
export function createEvent(dcOrVars, vars) {
return executeMutation(createEventRef(dcOrVars, vars));
}
export const listEventsRef = (dc) => {
const { dc: dcInstance} = validateArgs(connectorConfig, dc, undefined);
dcInstance._useGeneratedSdk();
return queryRef(dcInstance, 'listEvents');
}
listEventsRef.operationName = 'listEvents';
export function listEvents(dc) {
return executeQuery(listEventsRef(dc));
}

1
internal-api-harness/src/dataconnect-generated/esm/package.json Normal file
View File

@@ -0,0 +1 @@
{"type":"module"}

50
internal-api-harness/src/dataconnect-generated/index.cjs.js Normal file
View File

@@ -0,0 +1,50 @@
const { queryRef, executeQuery, mutationRef, executeMutation, validateArgs } = require('firebase/data-connect');
const EventStatus = {
DRAFT: "DRAFT",
ACTIVE: "ACTIVE",
PENDING: "PENDING",
ASSIGNED: "ASSIGNED",
CONFIRMED: "CONFIRMED",
COMPLETED: "COMPLETED",
CANCELED: "CANCELED",
}
exports.EventStatus = EventStatus;
const RecurrenceType = {
SINGLE: "SINGLE",
DATE_RANGE: "DATE_RANGE",
SCATTER: "SCATTER",
}
exports.RecurrenceType = RecurrenceType;
const connectorConfig = {
connector: 'krow-connector',
service: 'krow-workforce-db',
location: 'us-central1'
};
exports.connectorConfig = connectorConfig;
const createEventRef = (dcOrVars, vars) => {
const { dc: dcInstance, vars: inputVars} = validateArgs(connectorConfig, dcOrVars, vars, true);
dcInstance._useGeneratedSdk();
return mutationRef(dcInstance, 'CreateEvent', inputVars);
}
createEventRef.operationName = 'CreateEvent';
exports.createEventRef = createEventRef;
exports.createEvent = function createEvent(dcOrVars, vars) {
return executeMutation(createEventRef(dcOrVars, vars));
};
const listEventsRef = (dc) => {
const { dc: dcInstance} = validateArgs(connectorConfig, dc, undefined);
dcInstance._useGeneratedSdk();
return queryRef(dcInstance, 'listEvents');
}
listEventsRef.operationName = 'listEvents';
exports.listEventsRef = listEventsRef;
exports.listEvents = function listEvents(dc) {
return executeQuery(listEventsRef(dc));
};

90
internal-api-harness/src/dataconnect-generated/index.d.ts vendored Normal file
View File

@@ -0,0 +1,90 @@
import { ConnectorConfig, DataConnect, QueryRef, QueryPromise, MutationRef, MutationPromise } from 'firebase/data-connect';
export const connectorConfig: ConnectorConfig;
export type TimestampString = string;
export type UUIDString = string;
export type Int64String = string;
export type DateString = string;
export enum EventStatus {
DRAFT = "DRAFT",
ACTIVE = "ACTIVE",
PENDING = "PENDING",
ASSIGNED = "ASSIGNED",
CONFIRMED = "CONFIRMED",
COMPLETED = "COMPLETED",
CANCELED = "CANCELED",
};
export enum RecurrenceType {
SINGLE = "SINGLE",
DATE_RANGE = "DATE_RANGE",
SCATTER = "SCATTER",
};
export interface CreateEventData {
event_insert: Event_Key;
}
export interface CreateEventVariables {
eventName: string;
isRecurring: boolean;
recurrenceType?: RecurrenceType | null;
businessId: UUIDString;
vendorId?: UUIDString | null;
status: EventStatus;
date: TimestampString;
shifts?: string | null;
total?: number | null;
requested?: number | null;
assignedStaff?: string | null;
}
export interface Event_Key {
id: UUIDString;
__typename?: 'Event_Key';
}
export interface ListEventsData {
events: ({
id: UUIDString;
eventName: string;
status: EventStatus;
date: TimestampString;
isRecurring: boolean;
recurrenceType?: RecurrenceType | null;
businessId: UUIDString;
vendorId?: UUIDString | null;
total?: number | null;
requested?: number | null;
} & Event_Key)[];
}
interface CreateEventRef {
/* Allow users to create refs without passing in DataConnect */
(vars: CreateEventVariables): MutationRef<CreateEventData, CreateEventVariables>;
/* Allow users to pass in custom DataConnect instances */
(dc: DataConnect, vars: CreateEventVariables): MutationRef<CreateEventData, CreateEventVariables>;
operationName: string;
}
export const createEventRef: CreateEventRef;
export function createEvent(vars: CreateEventVariables): MutationPromise<CreateEventData, CreateEventVariables>;
export function createEvent(dc: DataConnect, vars: CreateEventVariables): MutationPromise<CreateEventData, CreateEventVariables>;
interface ListEventsRef {
/* Allow users to create refs without passing in DataConnect */
(): QueryRef<ListEventsData, undefined>;
/* Allow users to pass in custom DataConnect instances */
(dc: DataConnect): QueryRef<ListEventsData, undefined>;
operationName: string;
}
export const listEventsRef: ListEventsRef;
export function listEvents(): QueryPromise<ListEventsData, undefined>;
export function listEvents(dc: DataConnect): QueryPromise<ListEventsData, undefined>;

32
internal-api-harness/src/dataconnect-generated/package.json Normal file
View File

@@ -0,0 +1,32 @@
{
"name": "@dataconnect/generated",
"version": "1.0.0",
"author": "Firebase <firebase-support@google.com> (https://firebase.google.com/)",
"description": "Generated SDK For krow-connector",
"license": "Apache-2.0",
"engines": {
"node": " >=18.0"
},
"typings": "index.d.ts",
"module": "esm/index.esm.js",
"main": "index.cjs.js",
"browser": "esm/index.esm.js",
"exports": {
".": {
"types": "./index.d.ts",
"require": "./index.cjs.js",
"default": "./esm/index.esm.js"
},
"./react": {
"types": "./react/index.d.ts",
"require": "./react/index.cjs.js",
"import": "./react/esm/index.esm.js",
"default": "./react/esm/index.esm.js"
},
"./package.json": "./package.json"
},
"peerDependencies": {
"firebase": "^11.3.0 || ^12.0.0",
"@tanstack-query-firebase/react": "^2.0.0"
}
}

332
internal-api-harness/src/dataconnect-generated/react/README.md Normal file
View File

@@ -0,0 +1,332 @@
# Generated React README
This README will guide you through the process of using the generated React SDK package for the connector `krow-connector`. It will also provide examples on how to use your generated SDK to call your Data Connect queries and mutations.
**If you're looking for the `JavaScript README`, you can find it at [`dataconnect-generated/README.md`](../README.md)**
***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 `@dataconnect/generated/react` as shown below. Both CommonJS and ESM imports are supported.
You can also follow the instructions from the [Data Connect documentation](https://firebase.google.com/docs/data-connect/web-sdk#react).
# Table of Contents
- [**Overview**](#generated-react-readme)
- [**TanStack Query Firebase & TanStack React Query**](#tanstack-query-firebase-tanstack-react-query)
- [*Package Installation*](#installing-tanstack-query-firebase-and-tanstack-react-query-packages)
- [*Configuring TanStack Query*](#configuring-tanstack-query)
- [**Accessing the connector**](#accessing-the-connector)
- [*Connecting to the local Emulator*](#connecting-to-the-local-emulator)
- [**Queries**](#queries)
- [*listEvents*](#listevents)
- [**Mutations**](#mutations)
- [*CreateEvent*](#createevent)
# TanStack Query Firebase & TanStack React Query
This SDK provides [React](https://react.dev/) hooks generated specific to your application, for the operations found in the connector `krow-connector`. These hooks are generated using [TanStack Query Firebase](https://react-query-firebase.invertase.dev/) by our partners at Invertase, a library built on top of [TanStack React Query v5](https://tanstack.com/query/v5/docs/framework/react/overview).
***You do not need to be familiar with Tanstack Query or Tanstack Query Firebase to use this SDK.*** However, you may find it useful to learn more about them, as they will empower you as a user of this Generated React SDK.
## Installing TanStack Query Firebase and TanStack React Query Packages
In order to use the React generated SDK, you must install the `TanStack React Query` and `TanStack Query Firebase` packages.
```bash
npm i --save @tanstack/react-query @tanstack-query-firebase/react
```
```bash
npm i --save firebase@latest # Note: React has a peer dependency on ^11.3.0
```
You can also follow the installation instructions from the [Data Connect documentation](https://firebase.google.com/docs/data-connect/web-sdk#tanstack-install), or the [TanStack Query Firebase documentation](https://react-query-firebase.invertase.dev/react) and [TanStack React Query documentation](https://tanstack.com/query/v5/docs/framework/react/installation).
## Configuring TanStack Query
In order to use the React generated SDK in your application, you must wrap your application's component tree in a `QueryClientProvider` component from TanStack React Query. None of your generated React SDK hooks will work without this provider.
```javascript
import { QueryClientProvider } from '@tanstack/react-query';
// Create a TanStack Query client instance
const queryClient = new QueryClient()
function App() {
return (
// Provide the client to your App
<QueryClientProvider client={queryClient}>
<MyApplication />
</QueryClientProvider>
)
}
```
To learn more about `QueryClientProvider`, see the [TanStack React Query documentation](https://tanstack.com/query/latest/docs/framework/react/quick-start) and the [TanStack Query Firebase documentation](https://invertase.docs.page/tanstack-query-firebase/react#usage).
# 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 `krow-connector`.
You can find more information about connectors in the [Data Connect documentation](https://firebase.google.com/docs/data-connect#how-does).
```javascript
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](https://firebase.google.com/docs/data-connect/web-sdk#emulator-react-angular).
```javascript
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](#queries) and [mutations](#mutations) using the hooks provided from your generated React SDK.
# Queries
The React generated SDK provides Query hook functions that call and return [`useDataConnectQuery`](https://react-query-firebase.invertase.dev/react/data-connect/querying) hooks from TanStack Query Firebase.
Calling these hook functions will return a `UseQueryResult` object. This object holds the state of your Query, including whether the Query is loading, has completed, or has succeeded/failed, and the most recent data returned by the Query, among other things. To learn more about these hooks and how to use them, see the [TanStack Query Firebase documentation](https://react-query-firebase.invertase.dev/react/data-connect/querying).
TanStack React Query caches the results of your Queries, so using the same Query hook function in multiple places in your application allows the entire application to automatically see updates to that Query's data.
Query hooks execute their Queries automatically when called, and periodically refresh, unless you change the `queryOptions` for the Query. To learn how to stop a Query from automatically executing, including how to make a query "lazy", see the [TanStack React Query documentation](https://tanstack.com/query/latest/docs/framework/react/guides/disabling-queries).
To learn more about TanStack React Query's Queries, see the [TanStack React Query documentation](https://tanstack.com/query/v5/docs/framework/react/guides/queries).
## Using Query Hooks
Here's a general overview of how to use the generated Query hooks in your code:
- If the Query has no variables, the Query hook function does not require arguments.
- If the Query has any required variables, the Query hook function will require at least one argument: an object that contains all the required variables for the Query.
- If the Query has some required and some optional variables, only required variables are necessary in the variables argument object, and optional variables may be provided as well.
- If all of the Query's variables are optional, the Query hook function does not require any arguments.
- Query hook 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.
- Query hooks functions can be called with or without passing in an `options` argument of type `useDataConnectQueryOptions`. To learn more about the `options` argument, see the [TanStack React Query documentation](https://tanstack.com/query/v5/docs/framework/react/guides/query-options).
- ***Special case:*** If the Query has all optional variables and you would like to provide an `options` argument to the Query hook function without providing any variables, you must pass `undefined` where you would normally pass the Query's variables, and then may provide the `options` argument.
Below are examples of how to use the `krow-connector` connector's generated Query hook 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#operations-react-angular).
## listEvents
You can execute the `listEvents` Query using the following Query hook function, which is defined in [dataconnect-generated/react/index.d.ts](./index.d.ts):
```javascript
useListEvents(dc: DataConnect, options?: useDataConnectQueryOptions<ListEventsData>): UseDataConnectQueryResult<ListEventsData, undefined>;
```
You can also pass in a `DataConnect` instance to the Query hook function.
```javascript
useListEvents(options?: useDataConnectQueryOptions<ListEventsData>): UseDataConnectQueryResult<ListEventsData, undefined>;
```
### Variables
The `listEvents` Query has no variables.
### Return Type
Recall that calling the `listEvents` Query hook function returns a `UseQueryResult` object. This object holds the state of your Query, including whether the Query is loading, has completed, or has succeeded/failed, and any data returned by the Query, among other things.
To check the status of a Query, use the `UseQueryResult.status` field. You can also check for pending / success / error status using the `UseQueryResult.isPending`, `UseQueryResult.isSuccess`, and `UseQueryResult.isError` fields.
To access the data returned by a Query, use the `UseQueryResult.data` field. The data for the `listEvents` Query is of type `ListEventsData`, which is defined in [dataconnect-generated/index.d.ts](../index.d.ts). It has the following fields:
```javascript
export interface ListEventsData {
events: ({
id: UUIDString;
eventName: string;
status: EventStatus;
date: TimestampString;
isRecurring: boolean;
recurrenceType?: RecurrenceType | null;
businessId: UUIDString;
vendorId?: UUIDString | null;
total?: number | null;
requested?: number | null;
} & Event_Key)[];
}
```
To learn more about the `UseQueryResult` object, see the [TanStack React Query documentation](https://tanstack.com/query/v5/docs/framework/react/reference/useQuery).
### Using `listEvents`'s Query hook function
```javascript
import { getDataConnect } from 'firebase/data-connect';
import { connectorConfig } from '@dataconnect/generated';
import { useListEvents } from '@dataconnect/generated/react'
export default function ListEventsComponent() {
// You don't have to do anything to "execute" the Query.
// Call the Query hook function to get a `UseQueryResult` object which holds the state of your Query.
const query = useListEvents();
// You can also pass in a `DataConnect` instance to the Query hook function.
const dataConnect = getDataConnect(connectorConfig);
const query = useListEvents(dataConnect);
// You can also pass in a `useDataConnectQueryOptions` object to the Query hook function.
const options = { staleTime: 5 * 1000 };
const query = useListEvents(options);
// You can also pass both a `DataConnect` instance and a `useDataConnectQueryOptions` object.
const dataConnect = getDataConnect(connectorConfig);
const options = { staleTime: 5 * 1000 };
const query = useListEvents(dataConnect, options);
// Then, you can render your component dynamically based on the status of the Query.
if (query.isPending) {
return <div>Loading...</div>;
}
if (query.isError) {
return <div>Error: {query.error.message}</div>;
}
// If the Query is successful, you can access the data returned using the `UseQueryResult.data` field.
if (query.isSuccess) {
console.log(query.data.events);
}
return <div>Query execution {query.isSuccess ? 'successful' : 'failed'}!</div>;
}
```
# Mutations
The React generated SDK provides Mutations hook functions that call and return [`useDataConnectMutation`](https://react-query-firebase.invertase.dev/react/data-connect/mutations) hooks from TanStack Query Firebase.
Calling these hook functions will return a `UseMutationResult` object. This object holds the state of your Mutation, including whether the Mutation is loading, has completed, or has succeeded/failed, and the most recent data returned by the Mutation, among other things. To learn more about these hooks and how to use them, see the [TanStack Query Firebase documentation](https://react-query-firebase.invertase.dev/react/data-connect/mutations).
Mutation hooks do not execute their Mutations automatically when called. Rather, after calling the Mutation hook function and getting a `UseMutationResult` object, you must call the `UseMutationResult.mutate()` function to execute the Mutation.
To learn more about TanStack React Query's Mutations, see the [TanStack React Query documentation](https://tanstack.com/query/v5/docs/framework/react/guides/mutations).
## Using Mutation Hooks
Here's a general overview of how to use the generated Mutation hooks in your code:
- Mutation hook functions are not called with the arguments to the Mutation. Instead, arguments are passed to `UseMutationResult.mutate()`.
- If the Mutation has no variables, the `mutate()` function does not require arguments.
- If the Mutation has any required variables, the `mutate()` function will require at least one argument: an object that contains all the required variables for the Mutation.
- If the Mutation has some required and some optional variables, only required variables are necessary in the variables argument object, and optional variables may be provided as well.
- If all of the Mutation's variables are optional, the Mutation hook function does not require any arguments.
- Mutation hook 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.
- Mutation hooks also accept an `options` argument of type `useDataConnectMutationOptions`. To learn more about the `options` argument, see the [TanStack React Query documentation](https://tanstack.com/query/v5/docs/framework/react/guides/mutations#mutation-side-effects).
- `UseMutationResult.mutate()` also accepts an `options` argument of type `useDataConnectMutationOptions`.
- ***Special case:*** If the Mutation has no arguments (or all optional arguments and you wish to provide none), and you want to pass `options` to `UseMutationResult.mutate()`, you must pass `undefined` where you would normally pass the Mutation's arguments, and then may provide the options argument.
Below are examples of how to use the `krow-connector` connector's generated Mutation hook 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#operations-react-angular).
## CreateEvent
You can execute the `CreateEvent` Mutation using the `UseMutationResult` object returned by the following Mutation hook function (which is defined in [dataconnect-generated/react/index.d.ts](./index.d.ts)):
```javascript
useCreateEvent(options?: useDataConnectMutationOptions<CreateEventData, FirebaseError, CreateEventVariables>): UseDataConnectMutationResult<CreateEventData, CreateEventVariables>;
```
You can also pass in a `DataConnect` instance to the Mutation hook function.
```javascript
useCreateEvent(dc: DataConnect, options?: useDataConnectMutationOptions<CreateEventData, FirebaseError, CreateEventVariables>): UseDataConnectMutationResult<CreateEventData, CreateEventVariables>;
```
### Variables
The `CreateEvent` Mutation requires an argument of type `CreateEventVariables`, which is defined in [dataconnect-generated/index.d.ts](../index.d.ts). It has the following fields:
```javascript
export interface CreateEventVariables {
eventName: string;
isRecurring: boolean;
recurrenceType?: RecurrenceType | null;
businessId: UUIDString;
vendorId?: UUIDString | null;
status: EventStatus;
date: TimestampString;
shifts?: string | null;
total?: number | null;
requested?: number | null;
assignedStaff?: string | null;
}
```
### Return Type
Recall that calling the `CreateEvent` Mutation hook function returns a `UseMutationResult` object. This object holds the state of your Mutation, including whether the Mutation is loading, has completed, or has succeeded/failed, among other things.
To check the status of a Mutation, use the `UseMutationResult.status` field. You can also check for pending / success / error status using the `UseMutationResult.isPending`, `UseMutationResult.isSuccess`, and `UseMutationResult.isError` fields.
To execute the Mutation, call `UseMutationResult.mutate()`. This function executes the Mutation, but does not return the data from the Mutation.
To access the data returned by a Mutation, use the `UseMutationResult.data` field. The data for the `CreateEvent` Mutation is of type `CreateEventData`, which is defined in [dataconnect-generated/index.d.ts](../index.d.ts). It has the following fields:
```javascript
export interface CreateEventData {
event_insert: Event_Key;
}
```
To learn more about the `UseMutationResult` object, see the [TanStack React Query documentation](https://tanstack.com/query/v5/docs/framework/react/reference/useMutation).
### Using `CreateEvent`'s Mutation hook function
```javascript
import { getDataConnect } from 'firebase/data-connect';
import { connectorConfig, CreateEventVariables } from '@dataconnect/generated';
import { useCreateEvent } from '@dataconnect/generated/react'
export default function CreateEventComponent() {
// Call the Mutation hook function to get a `UseMutationResult` object which holds the state of your Mutation.
const mutation = useCreateEvent();
// You can also pass in a `DataConnect` instance to the Mutation hook function.
const dataConnect = getDataConnect(connectorConfig);
const mutation = useCreateEvent(dataConnect);
// You can also pass in a `useDataConnectMutationOptions` object to the Mutation hook function.
const options = {
onSuccess: () => { console.log('Mutation succeeded!'); }
};
const mutation = useCreateEvent(options);
// You can also pass both a `DataConnect` instance and a `useDataConnectMutationOptions` object.
const dataConnect = getDataConnect(connectorConfig);
const options = {
onSuccess: () => { console.log('Mutation succeeded!'); }
};
const mutation = useCreateEvent(dataConnect, options);
// After calling the Mutation hook function, you must call `UseMutationResult.mutate()` to execute the Mutation.
// The `useCreateEvent` Mutation requires an argument of type `CreateEventVariables`:
const createEventVars: CreateEventVariables = {
eventName: ...,
isRecurring: ...,
recurrenceType: ..., // optional
businessId: ...,
vendorId: ..., // optional
status: ...,
date: ...,
shifts: ..., // optional
total: ..., // optional
requested: ..., // optional
assignedStaff: ..., // optional
};
mutation.mutate(createEventVars);
// Variables can be defined inline as well.
mutation.mutate({ eventName: ..., isRecurring: ..., recurrenceType: ..., businessId: ..., vendorId: ..., status: ..., date: ..., shifts: ..., total: ..., requested: ..., assignedStaff: ..., });
// You can also pass in a `useDataConnectMutationOptions` object to `UseMutationResult.mutate()`.
const options = {
onSuccess: () => { console.log('Mutation succeeded!'); }
};
mutation.mutate(createEventVars, options);
// Then, you can render your component dynamically based on the status of the Mutation.
if (mutation.isPending) {
return <div>Loading...</div>;
}
if (mutation.isError) {
return <div>Error: {mutation.error.message}</div>;
}
// If the Mutation is successful, you can access the data returned using the `UseMutationResult.data` field.
if (mutation.isSuccess) {
console.log(mutation.data.event_insert);
}
return <div>Mutation execution {mutation.isSuccess ? 'successful' : 'failed'}!</div>;
}
```

18
internal-api-harness/src/dataconnect-generated/react/esm/index.esm.js Normal file
View File

@@ -0,0 +1,18 @@
import { createEventRef, listEventsRef, connectorConfig } from '../../esm/index.esm.js';
import { validateArgs, CallerSdkTypeEnum } from 'firebase/data-connect';
import { useDataConnectQuery, useDataConnectMutation, validateReactArgs } from '@tanstack-query-firebase/react/data-connect';
export function useCreateEvent(dcOrOptions, options) {
const { dc: dcInstance, vars: inputOpts } = validateArgs(connectorConfig, dcOrOptions, options);
function refFactory(vars) {
return createEventRef(dcInstance, vars);
}
return useDataConnectMutation(refFactory, inputOpts, CallerSdkTypeEnum.GeneratedReact);
}
export function useListEvents(dcOrOptions, options) {
const { dc: dcInstance, options: inputOpts } = validateReactArgs(connectorConfig, dcOrOptions, options);
const ref = listEventsRef(dcInstance);
return useDataConnectQuery(ref, inputOpts, CallerSdkTypeEnum.GeneratedReact);
}

1
internal-api-harness/src/dataconnect-generated/react/esm/package.json Normal file
View File

@@ -0,0 +1 @@
{"type":"module"}

18
internal-api-harness/src/dataconnect-generated/react/index.cjs.js Normal file
View File

@@ -0,0 +1,18 @@
const { createEventRef, listEventsRef, connectorConfig } = require('../index.cjs.js');
const { validateArgs, CallerSdkTypeEnum } = require('firebase/data-connect');
const { useDataConnectQuery, useDataConnectMutation, validateReactArgs } = require('@tanstack-query-firebase/react/data-connect');
exports.useCreateEvent = function useCreateEvent(dcOrOptions, options) {
const { dc: dcInstance, vars: inputOpts } = validateArgs(connectorConfig, dcOrOptions, options);
function refFactory(vars) {
return createEventRef(dcInstance, vars);
}
return useDataConnectMutation(refFactory, inputOpts, CallerSdkTypeEnum.GeneratedReact);
}
exports.useListEvents = function useListEvents(dcOrOptions, options) {
const { dc: dcInstance, options: inputOpts } = validateReactArgs(connectorConfig, dcOrOptions, options);
const ref = listEventsRef(dcInstance);
return useDataConnectQuery(ref, inputOpts, CallerSdkTypeEnum.GeneratedReact);
}

12
internal-api-harness/src/dataconnect-generated/react/index.d.ts vendored Normal file
View File

@@ -0,0 +1,12 @@
import { CreateEventData, CreateEventVariables, ListEventsData } from '../';
import { UseDataConnectQueryResult, useDataConnectQueryOptions, UseDataConnectMutationResult, useDataConnectMutationOptions} from '@tanstack-query-firebase/react/data-connect';
import { UseQueryResult, UseMutationResult} from '@tanstack/react-query';
import { DataConnect } from 'firebase/data-connect';
import { FirebaseError } from 'firebase/app';
export function useCreateEvent(options?: useDataConnectMutationOptions<CreateEventData, FirebaseError, CreateEventVariables>): UseDataConnectMutationResult<CreateEventData, CreateEventVariables>;
export function useCreateEvent(dc: DataConnect, options?: useDataConnectMutationOptions<CreateEventData, FirebaseError, CreateEventVariables>): UseDataConnectMutationResult<CreateEventData, CreateEventVariables>;
export function useListEvents(options?: useDataConnectQueryOptions<ListEventsData>): UseDataConnectQueryResult<ListEventsData, undefined>;
export function useListEvents(dc: DataConnect, options?: useDataConnectQueryOptions<ListEventsData>): UseDataConnectQueryResult<ListEventsData, undefined>;

17
internal-api-harness/src/dataconnect-generated/react/package.json Normal file
View File

@@ -0,0 +1,17 @@
{
"name": "@dataconnect/generated-react",
"version": "1.0.0",
"author": "Firebase <firebase-support@google.com> (https://firebase.google.com/)",
"description": "Generated SDK For krow-connector",
"license": "Apache-2.0",
"engines": {
"node": " >=18.0"
},
"typings": "index.d.ts",
"main": "index.cjs.js",
"module": "esm/index.esm.js",
"browser": "esm/index.esm.js",
"peerDependencies": {
"@tanstack-query-firebase/react": "^2.0.0"
}
}