Skip to content

Commit 6584666

Browse files
dconeybedconeybe
committed
add a simple example, and label the old one an 'advanced' example
1 parent b648ee8 commit 6584666

File tree

4 files changed

+168
-28
lines changed

4 files changed

+168
-28
lines changed

‎docs-devsite/firestore_.firestoredataconverter.md

Lines changed: 41 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,32 @@ toFirestore(modelObject: PartialWithFieldValue<AppModelType>, options: SetOption
9898

9999
### Example
100100

101+
Simple Example
102+
103+
```typescript
104+
const numberConverter = {
105+
toFirestore(value: WithFieldValue<number>) {
106+
return { value };
107+
},
108+
fromFirestore(snapshot: QueryDocumentSnapshot, options: SnapshotOptions) {
109+
return snapshot.data(options).value as number;
110+
}
111+
};
112+
113+
async function simpleDemo(db: Firestore): Promise<void> {
114+
const documentRef = doc(db, 'values/value123').withConverter(numberConverter);
115+
116+
await setDoc(documentRef, 42);
117+
const snapshot1 = await getDoc(documentRef);
118+
assertEqual(snapshot1.data(), 42);
119+
120+
await updateDoc(documentRef, { value: 999 });
121+
const snapshot2 = await getDoc(documentRef);
122+
assertEqual(snapshot2.data(), 999);
123+
}
124+
125+
```
126+
Advanced Example
101127

102128
```typescript
103129
class Post {
@@ -155,7 +181,7 @@ const postConverter = {
155181
}
156182
};
157183
158-
async function demo(db: Firestore): Promise<void> {
184+
async function advancedDemo(db: Firestore): Promise<void> {
159185
// Create a `DocumentReference` with a `FirestoreDataConverter`.
160186
const documentRef = doc(db, 'posts/post123').withConverter(postConverter);
161187
@@ -175,18 +201,19 @@ async function demo(db: Firestore): Promise<void> {
175201
// `setDoc()` is _not_ be compatible with `WithFieldValue<Post>`. This
176202
// type checking prevents the caller from specifying objects with incorrect
177203
// properties or property values.
178-
// @ts-expect-error "Argument of type { ttl: string; } is not assignable to
179-
// parameter of type WithFieldValue<Post>"
204+
// @ts-expect-error "Argument of type { ttl: string; } is not assignable
205+
// to parameter of type WithFieldValue<Post>"
180206
await setDoc(documentRef, { ttl: 'The Title' });
181207
182208
// When retrieving a document with `getDoc()` the `DocumentSnapshot`
183209
// object's `data()` method returns a `Post`, rather than a generic object,
184210
// which is returned if the `DocumentReference` did _not_ have a
185211
// `FirestoreDataConverter` attached to it.
186-
const postSnap: DocumentSnapshot<Post> = await getDoc(documentRef);
187-
const post: Post | undefined = postSnap.data();
188-
if (post) {
189-
console.log(`Post ${documentRef.path} has title=${post.title}`);
212+
const snapshot1: DocumentSnapshot<Post> = await getDoc(documentRef);
213+
const post1: Post = snapshot1.data()!;
214+
if (post1) {
215+
assertEqual(post1.title, 'My Life');
216+
assertEqual(post1.author, 'Foo Bar');
190217
}
191218
192219
// The `data` argument specified to `updateDoc()` is type checked by the
@@ -210,6 +237,13 @@ async function demo(db: Firestore): Promise<void> {
210237
// @ts-expect-error "Argument of type { title: string; } is not assignable
211238
// to parameter of type WithFieldValue<PostDbModel>"
212239
await updateDoc(documentRef, { title: 'New Title' });
240+
241+
const snapshot2: DocumentSnapshot<Post> = await getDoc(documentRef);
242+
const post2: Post = snapshot2.data()!;
243+
if (post2) {
244+
assertEqual(post2.title, 'My Life');
245+
assertEqual(post2.author, 'NewFirstName Bar');
246+
}
213247
}
214248
215249
```

‎docs-devsite/firestore_lite.firestoredataconverter.md

Lines changed: 41 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,32 @@ toFirestore(modelObject: PartialWithFieldValue<AppModelType>, options: SetOption
9797

9898
### Example
9999

100+
Simple Example
101+
102+
```typescript
103+
const numberConverter = {
104+
toFirestore(value: WithFieldValue<number>) {
105+
return { value };
106+
},
107+
fromFirestore(snapshot: QueryDocumentSnapshot, options: SnapshotOptions) {
108+
return snapshot.data(options).value as number;
109+
}
110+
};
111+
112+
async function simpleDemo(db: Firestore): Promise<void> {
113+
const documentRef = doc(db, 'values/value123').withConverter(numberConverter);
114+
115+
await setDoc(documentRef, 42);
116+
const snapshot1 = await getDoc(documentRef);
117+
assertEqual(snapshot1.data(), 42);
118+
119+
await updateDoc(documentRef, { value: 999 });
120+
const snapshot2 = await getDoc(documentRef);
121+
assertEqual(snapshot2.data(), 999);
122+
}
123+
124+
```
125+
Advanced Example
100126

101127
```typescript
102128
class Post {
@@ -154,7 +180,7 @@ const postConverter = {
154180
}
155181
};
156182
157-
async function demo(db: Firestore): Promise<void> {
183+
async function advancedDemo(db: Firestore): Promise<void> {
158184
// Create a `DocumentReference` with a `FirestoreDataConverter`.
159185
const documentRef = doc(db, 'posts/post123').withConverter(postConverter);
160186
@@ -174,18 +200,19 @@ async function demo(db: Firestore): Promise<void> {
174200
// `setDoc()` is _not_ be compatible with `WithFieldValue<Post>`. This
175201
// type checking prevents the caller from specifying objects with incorrect
176202
// properties or property values.
177-
// @ts-expect-error "Argument of type { ttl: string; } is not assignable to
178-
// parameter of type WithFieldValue<Post>"
203+
// @ts-expect-error "Argument of type { ttl: string; } is not assignable
204+
// to parameter of type WithFieldValue<Post>"
179205
await setDoc(documentRef, { ttl: 'The Title' });
180206
181207
// When retrieving a document with `getDoc()` the `DocumentSnapshot`
182208
// object's `data()` method returns a `Post`, rather than a generic object,
183209
// which is returned if the `DocumentReference` did _not_ have a
184210
// `FirestoreDataConverter` attached to it.
185-
const postSnap: DocumentSnapshot<Post> = await getDoc(documentRef);
186-
const post: Post | undefined = postSnap.data();
187-
if (post) {
188-
console.log(`Post ${documentRef.path} has title=${post.title}`);
211+
const snapshot1: DocumentSnapshot<Post> = await getDoc(documentRef);
212+
const post1: Post = snapshot1.data()!;
213+
if (post1) {
214+
assertEqual(post1.title, 'My Life');
215+
assertEqual(post1.author, 'Foo Bar');
189216
}
190217
191218
// The `data` argument specified to `updateDoc()` is type checked by the
@@ -209,6 +236,13 @@ async function demo(db: Firestore): Promise<void> {
209236
// @ts-expect-error "Argument of type { title: string; } is not assignable
210237
// to parameter of type WithFieldValue<PostDbModel>"
211238
await updateDoc(documentRef, { title: 'New Title' });
239+
240+
const snapshot2: DocumentSnapshot<Post> = await getDoc(documentRef);
241+
const post2: Post = snapshot2.data()!;
242+
if (post2) {
243+
assertEqual(post2.title, 'My Life');
244+
assertEqual(post2.author, 'NewFirstName Bar');
245+
}
212246
}
213247
214248
```

‎packages/firestore/src/api/snapshot.ts

Lines changed: 43 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,34 @@ import { SnapshotListenOptions } from './reference_impl';
4949
* storing and retrieving objects from Firestore.
5050
*
5151
* @example
52+
*
53+
* Simple Example
54+
*
55+
* ```typescript
56+
* const numberConverter = {
57+
* toFirestore(value: WithFieldValue<number>) {
58+
* return { value };
59+
* },
60+
* fromFirestore(snapshot: QueryDocumentSnapshot, options: SnapshotOptions) {
61+
* return snapshot.data(options).value as number;
62+
* }
63+
* };
64+
*
65+
* async function simpleDemo(db: Firestore): Promise<void> {
66+
* const documentRef = doc(db, 'values/value123').withConverter(numberConverter);
67+
*
68+
* await setDoc(documentRef, 42);
69+
* const snapshot1 = await getDoc(documentRef);
70+
* assertEqual(snapshot1.data(), 42);
71+
*
72+
* await updateDoc(documentRef, { value: 999 });
73+
* const snapshot2 = await getDoc(documentRef);
74+
* assertEqual(snapshot2.data(), 999);
75+
* }
76+
* ```
77+
*
78+
* Advanced Example
79+
*
5280
* ```typescript
5381
* class Post {
5482
* constructor(
@@ -105,7 +133,7 @@ import { SnapshotListenOptions } from './reference_impl';
105133
* }
106134
* };
107135
*
108-
* async function demo(db: Firestore): Promise<void> {
136+
* async function advancedDemo(db: Firestore): Promise<void> {
109137
* // Create a `DocumentReference` with a `FirestoreDataConverter`.
110138
* const documentRef = doc(db, 'posts/post123').withConverter(postConverter);
111139
*
@@ -125,18 +153,19 @@ import { SnapshotListenOptions } from './reference_impl';
125153
* // `setDoc()` is _not_ be compatible with `WithFieldValue<Post>`. This
126154
* // type checking prevents the caller from specifying objects with incorrect
127155
* // properties or property values.
128-
* // @ts-expect-error "Argument of type { ttl: string; } is not assignable to
129-
* // parameter of type WithFieldValue<Post>"
156+
* // @ts-expect-error "Argument of type { ttl: string; } is not assignable
157+
* // to parameter of type WithFieldValue<Post>"
130158
* await setDoc(documentRef, { ttl: 'The Title' });
131159
*
132160
* // When retrieving a document with `getDoc()` the `DocumentSnapshot`
133161
* // object's `data()` method returns a `Post`, rather than a generic object,
134162
* // which is returned if the `DocumentReference` did _not_ have a
135163
* // `FirestoreDataConverter` attached to it.
136-
* const postSnap: DocumentSnapshot<Post> = await getDoc(documentRef);
137-
* const post: Post | undefined = postSnap.data();
138-
* if (post) {
139-
* console.log(`Post ${documentRef.path} has title=${post.title}`);
164+
* const snapshot1: DocumentSnapshot<Post> = await getDoc(documentRef);
165+
* const post1: Post = snapshot1.data()!;
166+
* if (post1) {
167+
* assertEqual(post1.title, 'My Life');
168+
* assertEqual(post1.author, 'Foo Bar');
140169
* }
141170
*
142171
* // The `data` argument specified to `updateDoc()` is type checked by the
@@ -160,6 +189,13 @@ import { SnapshotListenOptions } from './reference_impl';
160189
* // @ts-expect-error "Argument of type { title: string; } is not assignable
161190
* // to parameter of type WithFieldValue<PostDbModel>"
162191
* await updateDoc(documentRef, { title: 'New Title' });
192+
*
193+
* const snapshot2: DocumentSnapshot<Post> = await getDoc(documentRef);
194+
* const post2: Post = snapshot2.data()!;
195+
* if (post2) {
196+
* assertEqual(post2.title, 'My Life');
197+
* assertEqual(post2.author, 'NewFirstName Bar');
198+
* }
163199
* }
164200
* ```
165201
*/

‎packages/firestore/src/lite-api/snapshot.ts

Lines changed: 43 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,34 @@ import { AbstractUserDataWriter } from './user_data_writer';
4747
* storing and retrieving objects from Firestore.
4848
*
4949
* @example
50+
*
51+
* Simple Example
52+
*
53+
* ```typescript
54+
* const numberConverter = {
55+
* toFirestore(value: WithFieldValue<number>) {
56+
* return { value };
57+
* },
58+
* fromFirestore(snapshot: QueryDocumentSnapshot, options: SnapshotOptions) {
59+
* return snapshot.data(options).value as number;
60+
* }
61+
* };
62+
*
63+
* async function simpleDemo(db: Firestore): Promise<void> {
64+
* const documentRef = doc(db, 'values/value123').withConverter(numberConverter);
65+
*
66+
* await setDoc(documentRef, 42);
67+
* const snapshot1 = await getDoc(documentRef);
68+
* assertEqual(snapshot1.data(), 42);
69+
*
70+
* await updateDoc(documentRef, { value: 999 });
71+
* const snapshot2 = await getDoc(documentRef);
72+
* assertEqual(snapshot2.data(), 999);
73+
* }
74+
* ```
75+
*
76+
* Advanced Example
77+
*
5078
* ```typescript
5179
* class Post {
5280
* constructor(
@@ -103,7 +131,7 @@ import { AbstractUserDataWriter } from './user_data_writer';
103131
* }
104132
* };
105133
*
106-
* async function demo(db: Firestore): Promise<void> {
134+
* async function advancedDemo(db: Firestore): Promise<void> {
107135
* // Create a `DocumentReference` with a `FirestoreDataConverter`.
108136
* const documentRef = doc(db, 'posts/post123').withConverter(postConverter);
109137
*
@@ -123,18 +151,19 @@ import { AbstractUserDataWriter } from './user_data_writer';
123151
* // `setDoc()` is _not_ be compatible with `WithFieldValue<Post>`. This
124152
* // type checking prevents the caller from specifying objects with incorrect
125153
* // properties or property values.
126-
* // @ts-expect-error "Argument of type { ttl: string; } is not assignable to
127-
* // parameter of type WithFieldValue<Post>"
154+
* // @ts-expect-error "Argument of type { ttl: string; } is not assignable
155+
* // to parameter of type WithFieldValue<Post>"
128156
* await setDoc(documentRef, { ttl: 'The Title' });
129157
*
130158
* // When retrieving a document with `getDoc()` the `DocumentSnapshot`
131159
* // object's `data()` method returns a `Post`, rather than a generic object,
132160
* // which is returned if the `DocumentReference` did _not_ have a
133161
* // `FirestoreDataConverter` attached to it.
134-
* const postSnap: DocumentSnapshot<Post> = await getDoc(documentRef);
135-
* const post: Post | undefined = postSnap.data();
136-
* if (post) {
137-
* console.log(`Post ${documentRef.path} has title=${post.title}`);
162+
* const snapshot1: DocumentSnapshot<Post> = await getDoc(documentRef);
163+
* const post1: Post = snapshot1.data()!;
164+
* if (post1) {
165+
* assertEqual(post1.title, 'My Life');
166+
* assertEqual(post1.author, 'Foo Bar');
138167
* }
139168
*
140169
* // The `data` argument specified to `updateDoc()` is type checked by the
@@ -158,6 +187,13 @@ import { AbstractUserDataWriter } from './user_data_writer';
158187
* // @ts-expect-error "Argument of type { title: string; } is not assignable
159188
* // to parameter of type WithFieldValue<PostDbModel>"
160189
* await updateDoc(documentRef, { title: 'New Title' });
190+
*
191+
* const snapshot2: DocumentSnapshot<Post> = await getDoc(documentRef);
192+
* const post2: Post = snapshot2.data()!;
193+
* if (post2) {
194+
* assertEqual(post2.title, 'My Life');
195+
* assertEqual(post2.author, 'NewFirstName Bar');
196+
* }
161197
* }
162198
* ```
163199
*/

0 commit comments

Comments
 (0)