Skip to content

Commit 53d0756

Browse files
maneeshtcabljacCopilot
authored
chore(docs): Docs Site For Angular (#182)
* Fixed issue where updated variables weren't getting picked up * Completed docs site for angular * Undid changes * Undid package.json changes * Undid package.json changes * Removed unnecessary changes * Removed unnecessary changes * s/functions/Functions * Cleaned up docs a bit more * Removed all hook references * Update docs/angular/data-connect/functions/injectDataConnectMutation.mdx Co-authored-by: Copilot <[email protected]> --------- Co-authored-by: Jacob Cable <[email protected]> Co-authored-by: Copilot <[email protected]>
1 parent 0c12a7f commit 53d0756

File tree

8 files changed

+494
-1
lines changed

8 files changed

+494
-1
lines changed

‎docs.json

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,11 @@
1515
"id": "react",
1616
"title": "React",
1717
"href": "/react"
18+
},
19+
{
20+
"id": "angular",
21+
"title": "Angular",
22+
"href": "/angular"
1823
}
1924
],
2025
"sidebar": [
@@ -42,6 +47,37 @@
4247
}
4348
]
4449
},
50+
{
51+
"tab": "angular",
52+
"group": "Data Connect",
53+
"pages": [
54+
{
55+
"title": "Getting Started",
56+
"href": "/angular/data-connect"
57+
},
58+
{
59+
"title": "Querying",
60+
"href": "/angular/data-connect/querying"
61+
},
62+
{
63+
"title": "Mutations",
64+
"href": "/angular/data-connect/mutations"
65+
},
66+
{
67+
"group": "Functions",
68+
"pages": [
69+
{
70+
"title": "injectDataConnectQuery",
71+
"href": "/angular/data-connect/functions/injectDataConnectQuery"
72+
},
73+
{
74+
"title": "injectDataConnectMutation",
75+
"href": "/angular/data-connect/functions/injectDataConnectMutation"
76+
}
77+
]
78+
}
79+
]
80+
},
4581
{
4682
"tab": "react",
4783
"group": "Authentication",

‎docs/angular/data-connect/functions/injectDataConnectMutation.mdx

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
title: injectDataConnectMutation
3+
---
4+
5+
`injectDataConnectMutation` is an injector designed to simplify handling mutations (creating, updating, deleting) with Firebase Data Connect.
6+
7+
See [mutations](/angular/data-connect/mutations) for more information.
8+
9+
## Features
10+
11+
- Simplifies mutation handling for <b>create</b>, <b>update</b>, and <b>delete</b> operations using Firebase Data Connect.
12+
- Provides <b>type-safe</b> handling of mutations based on your Firebase Data Connect schema.
13+
- Automatically manages <b>pending</b>, <b>success</b>, and <b>error</b> states for mutations.
14+
- Supports <b>optimistic updates</b> and <b>caching</b> to improve user experience and performance.
15+
16+
## Usage
17+
18+
```ts
19+
import { injectDataConnectMutation } from "@tanstack-query-firebase/angular/data-connect";
20+
import { createMovieRef } from "@your-package-name/your-connector";
21+
22+
class AddMovieComponent {
23+
createMovie = injectDataConnectMutation(
24+
createMovieRef
25+
);
26+
addMovie() {
27+
createMovie.mutate({
28+
title: 'John Wick',
29+
genre: "Action",
30+
imageUrl: "https://example.com/image.jpg",
31+
});
32+
}
33+
return (
34+
<button
35+
disabled={createMovie.isPending()}
36+
(click)="addMovie()"
37+
>
38+
{{createMovie.isPending() ? "Creating..." : "Create Movie"}}
39+
</button>
40+
);
41+
}
42+
```

‎docs/angular/data-connect/functions/injectDataConnectQuery.mdx

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
title: injectDataConnectQuery
3+
---
4+
5+
`injectDataConnectQuery` is an injector designed to simplify data fetching and state management with Firebase Data Connect.
6+
7+
See [querying](/angular/data-connect/querying) for more information.
8+
9+
## Features
10+
11+
- Provides <b>type-safe</b> handling of queries based on the Firebase Data Connect schema.
12+
- Simplifies data fetching using Firebase Data Connect.
13+
- Automatically manages <b>loading</b>, <b>success</b>, and <b>error</b> states.
14+
- Supports <b>refetching data</b> with integrated <b>caching</b>.
15+
16+
## Usage
17+
18+
```ts
19+
import { injectDataConnectQuery } from '@tanstack-query-firebase/angular/data-connect';
20+
import { listMoviesRef } from "@your-package-name/your-connector";
21+
22+
// class
23+
export class MovieListComponent {
24+
movies = injectDataConnectQuery(listMoviesRef());
25+
}
26+
27+
// template
28+
@if (movies.isPending()) {
29+
Loading...
30+
}
31+
@if (movies.error()) {
32+
An error has occurred: {{ movies.error() }}
33+
}
34+
@if (movies.data(); as data) {
35+
@for (movie of data.movies; track movie.id) {
36+
<mat-card appearance="outlined">
37+
<mat-card-content>{{movie.description}}</mat-card-content>
38+
</mat-card>
39+
} @empty {
40+
<h2>No items!</h2>
41+
}
42+
}
43+
```

‎docs/angular/data-connect/index.mdx

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
---
2+
title: Firebase Data Connect
3+
---
4+
5+
Firebase Data Connect is a relational database service for mobile and web apps that lets you build and scale using a fully-managed PostgreSQL database powered by Cloud SQL. It provides secure schema, query and mutation management using GraphQL technology that integrates well with Firebase Authentication.
6+
7+
To get started, ensure you have setup your Firebase project and have the Data Connect setup in your project. To learn more,
8+
follow the [Firebase Data Connect documentation](https://firebase.google.com/docs/data-connect/quickstart).
9+
10+
## Setup
11+
12+
Before using the Tanstack Query Firebase injectors for Data Connect, ensure you have configured your application using your chosen connector:
13+
14+
```ts
15+
// app.config.ts
16+
export const appConfig: ApplicationConfig = {
17+
providers: [
18+
...
19+
provideFirebaseApp(() =>
20+
initializeApp(/*Replace with your firebase config*/)
21+
),
22+
provideDataConnect(() => getDataConnect(connectorConfig)),
23+
provideTanStackQuery(new QueryClient()),
24+
],
25+
};
26+
```
27+
28+
## Importing
29+
30+
The package exports are available via the `@tanstack-query-firebase/angular` package under the `data-connect` namespace:
31+
32+
```ts
33+
import { injectDataConnectQuery } from "@tanstack-query-firebase/angular/data-connect";
34+
```
35+
36+
## Basic Usage
37+
38+
To use the Tanstack Query Firebase injectors, you can either use the generated SDKs, or the `injectDataConnectQuery` injector to fetch data from the database:
39+
40+
### Using the Generated SDK
41+
42+
The generated SDK reduces the boilerplate required to use Tanstack Query Firebase's injectors. Instead of having to provide a ref to `injectDataConnectQuery`, you simply need to call the generated
43+
injector function like so:
44+
45+
```ts
46+
import { injectListMyPosts } from '@firebasegen/posts/angular'
47+
48+
@Component({
49+
...
50+
template: `
51+
@if (posts.isPending()) {
52+
Loading...
53+
}
54+
@if (posts.error()) {
55+
An error has occurred: {{ posts.error() }}
56+
}
57+
@if (posts.data(); as data) {
58+
@for (post of data.posts; track post.id) {
59+
<mat-card appearance="outlined">
60+
<mat-card-content>{{post.description}}</mat-card-content>
61+
</mat-card>
62+
} @empty {
63+
<h2>No items!</h2>
64+
}
65+
}
66+
`,
67+
})
68+
export class PostListComponent {
69+
// Calls `injectDataConnectQuery` with the corresponding types.
70+
posts = injectListMyPosts();
71+
}
72+
```
73+
74+
### Using `injectDataConnectQuery`
75+
76+
Alternatively, you can use the `injectDataConnectQuery` injector. To use this, you need to pass the Response and Data generics:
77+
78+
```ts
79+
import { injectDataConnectQuery } from "@tanstack-query-firebase/angular";
80+
import { listMoviesRef } from "@firebasegen/posts";
81+
82+
@Component({
83+
...
84+
template: `
85+
@if (posts.isPending()) {
86+
Loading...
87+
}
88+
@if (posts.error()) {
89+
An error has occurred: {{ posts.error() }}
90+
}
91+
@if (posts.data(); as data) {
92+
@for (post of data.posts; track post.id) {
93+
<mat-card appearance="outlined">
94+
<mat-card-content>{{post.description}}</mat-card-content>
95+
</mat-card>
96+
} @empty {
97+
<h2>No items!</h2>
98+
}
99+
}
100+
`,
101+
})
102+
export class PostListComponent {
103+
// Calls `injectDataConnectQuery` with the corresponding types.
104+
// Alternatively:
105+
// injectDataConnectQuery(queryRef<ListMoviesData, ListMoviesResponse>(dc, 'ListMovies'))
106+
posts = injectDataConnectQuery(listMoviesRef());
107+
}
108+
```
109+
110+
The injectors will automatically infer the data type from the connector and the query and automtically create a [query key](https://tanstack.com/query/latest/docs/framework/angular/guides/query-keys) for the query.
111+
112+
## Learning more
113+
114+
To learn more about the Data Connect functions, check out the following pages:
115+
116+
- [Querying](/angular/data-connect/querying)
117+
- [Mutations](/angular/data-connect/mutations)

‎docs/angular/data-connect/mutations.mdx

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
---
2+
title: Mutations
3+
description: Learn how to mutate data in Firebase Data Connect using the Tanstack Query Firebase injectors.
4+
---
5+
6+
## Mutating Data
7+
8+
To mutate data in Firebase Data Connect, you can either use the generated injectors, or use the `injectDataConnectMutation` injector.
9+
10+
```ts
11+
import { injectCreateMovie } from "@firebasegen/movies/angular";
12+
13+
@Component({
14+
...
15+
template: `
16+
<button
17+
disabled={createMovie.isPending()}
18+
(click)="addMovie()"
19+
>
20+
{{createMovie.isPending() ? "Creating..." : "Create Movie"}}
21+
</button>
22+
`
23+
})
24+
class AddMovieComponent() {
25+
// Calls `injectDataConnectMutation` with the respective types.
26+
// Alternatively:
27+
// import { injectDataConnectMutation } from '@tanstack-query-firebase/angular/data-connect';
28+
// ...
29+
// createMovie = injectDataConnectMutation(createMovieRef);
30+
createMovie = injectCreateMovie();
31+
addMovie() {
32+
createMovie.mutate({
33+
title: 'John Wick',
34+
genre: "Action",
35+
imageUrl: "https://example.com/image.jpg",
36+
});
37+
}
38+
}
39+
```
40+
41+
Additionally, you can provide a factory function to the mutation, which will be called with the mutation variables:
42+
43+
```ts
44+
createMovie = injectDataConnectMutation(undefined, () => ({
45+
mutationFn: (title: string) => createMovieRef({ title, reviewDate: Date.now() })
46+
}));
47+
48+
// ...
49+
createMovie.mutate("John Wick");
50+
```
51+
52+
## Invalidating Queries
53+
54+
The function provides an additional [mutation option](https://tanstack.com/query/latest/docs/framework/angular/reference/functions/injectMutation) called `invalidate`. This option accepts a list of query references which will be automatically invalidated when the mutation is successful.
55+
56+
You can also provide explicit references to the invalidate array, for example:
57+
58+
```ts
59+
const createMovie = injectDataConnectMutation(createMovieRef, {
60+
invalidate: [getMovieRef({ id: "1" })],
61+
});
62+
```
63+
64+
In this case only the query reference `getMovieRef({ id: "1" })` will be invalidated.
65+
66+
## Overriding the mutation key
67+
68+
### Metadata
69+
70+
Along with the data, the function will also return the `ref`, `source`, and `fetchTime` metadata from the mutation.
71+
72+
```ts
73+
const createMovie = injectDataConnectMutation(createMovieRef);
74+
75+
await createMovie.mutateAsync({
76+
title: 'John Wick',
77+
genre: "Action",
78+
imageUrl: "https://example.com/image.jpg",
79+
});
80+
81+
console.log(createMovie.dataConnectResult().ref);
82+
console.log(createMovie.dataConnectResult().source);
83+
console.log(createMovie.dataConnectResult().fetchTime);
84+
```

0 commit comments

Comments
 (0)