Add firestore-exp/firestore-lite docs #3843

schmidt-sebastian · 2020-09-24T23:19:51Z

This is a diff against #3792, which copy pastes the existing docs. This PR modifies them for the Lite and firestore-exp SDK.

changeset-bot · 2020-09-24T23:19:54Z

⚠️ No Changeset found

Latest commit: 84e69c4

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

googlebot · 2020-09-24T23:20:11Z

We found a Contributor License Agreement for you (the sender of this pull request), but were unable to find agreements for all the commit author(s) or Co-authors. If you authored these, maybe you used a different email address in the git commits than was used to sign the CLA (login here to double check)? If these were authored by someone else, then they will need to sign a CLA as well, and confirm that they're okay with these being contributed to Google.
In order to pass this check, please resolve this problem and then comment @googlebot I fixed it.. If the bot doesn't comment, it means it doesn't think anything has changed.

ℹ️ Googlers: Go here for more info.

google-oss-bot · 2020-09-24T23:34:40Z

Binary Size Report

Affected SDKs

@firebase/firestore/exp

Type Base (a6af7c2) Head (d63b572) Diff

main 477 kB 477 kB +4 B (+0.0%)
@firebase/firestore/lite

Type Base (a6af7c2) Head (d63b572) Diff

main 140 kB 140 kB +6 B (+0.0%)

Test Logs

Base (a6af7c27): https://github.com/firebase/firebase-js-sdk/actions/runs/272725135
Head (d63b572d): https://github.com/firebase/firebase-js-sdk/actions/runs/277394282

egilmorez

LG! There are some places where I think we need backticks for literals, or need to un-capitalize generic terms. Also, any place we can use present tense instead of "will," it is preferred.

Thanks!

egilmorez · 2020-09-25T17:13:21Z

packages/firestore/lite/src/api/transaction.ts

 * @param updateFunction The function to execute within the transaction context.
- * @return If the transaction completed successfully or was explicitly aborted
+ * @return  If the transaction completed successfully or was explicitly aborted
 * (the `updateFunction` returned a failed promise), the promise returned by the
 * updateFunction is returned here. Else, if the transaction failed, a rejected


Is this a literal?

egilmorez · 2020-09-25T17:13:54Z

packages/firestore/lite/src/api/transaction.ts

 * @param updateFunction The function to execute within the transaction context.
- * @return If the transaction completed successfully or was explicitly aborted
+ * @return  If the transaction completed successfully or was explicitly aborted
 * (the `updateFunction` returned a failed promise), the promise returned by the
 * updateFunction is returned here. Else, if the transaction failed, a rejected
 * promise with the corresponding failure error will be returned.


Suggest "is returned."

egilmorez · 2020-09-25T17:14:28Z

packages/firestore/lite/src/api/transaction.ts

 * @param updateFunction The function to execute within the transaction context.
- * @return If the transaction completed successfully or was explicitly aborted
+ * @return  If the transaction completed successfully or was explicitly aborted
 * (the `updateFunction` returned a failed promise), the promise returned by the
 * updateFunction is returned here. Else, if the transaction failed, a rejected


Suggest "Otherwise,"

egilmorez · 2020-09-25T17:15:51Z

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

+  /**
+   * Called by the Firestore SDK to convert a custom model object of type T
+   * into a plain Javascript object (suitable for writing directly to the
+   * Firestore database). Used with {@link setData()}, {@link WriteBatch#set()}


Do you think we need the parens?

I am hoping it looks nice in the final output, but I am not sure. A lot of the old code did this instead:

{@link setDoc setDoc()}

I hope this is the same as {@link setDoc()}.

Oh -- I meant "(suitable for....). Not a big deal though.

Okay, got it. I do kind of prefer to leave the parenthesis as is. Otherwise, we have to add a conjunction of some sort which will make this part harder to parse.

egilmorez · 2020-09-25T17:19:29Z

packages/firestore/lite/src/api/reference.ts

-   * set(), get(), etc. on the returned DocumentReference instance, the
-   * provided converter will convert between Firestore data and your custom
-   * type U.
+   * Applies a custom data converter to this DocumentReference, allowing you to


Literal? Here and below.

egilmorez · 2020-09-25T17:29:38Z

packages/firestore/lite/src/api/field_value.ts

 *
 * @param elements The elements to remove from the array.
- * @return The FieldValue sentinel for use in a call to `set()` or `update()`.
+ * @return The FieldValue sentinel for use in a call to `setDoc()` or


Literal? Here and below.

egilmorez · 2020-09-25T17:52:31Z

packages/firestore/lite/src/api/bytes.ts

@@ -29,7 +29,7 @@ export class Bytes {
  }

  /**
-   * Creates a new Blob from the given Base64 string, converting it to
+   * Creates a new Bytes object from the given Base64 string, converting it to


Literal? Here and below.

egilmorez · 2020-09-25T18:08:23Z

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

- * @param other The `DocumentSnapshot` to compare against.
- * @return true if this `DocumentSnapshot` is equal to the provided one.
+ * @param left A snapshot to compare.
+ * @param right A snapshot` to compare.


Typo backtick.

egilmorez · 2020-09-25T18:10:40Z

packages/firestore/exp/src/api/reference.ts

- * by waiting for data from the server, but it may return cached data or fail
- * if you are offline and the server cannot be reached. This behavior can be
- * altered via the `GetOptions` parameter.
+ * Note: getDoc() attempts to provide up-to-date data when possible by waiting


egilmorez · 2020-09-25T18:11:01Z

packages/firestore/exp/src/api/reference.ts

- * if you are offline and the server cannot be reached. This behavior can be
- * altered via the `GetOptions` parameter.
+ * Reads the document referred to by this `DocumentReference` from cache.
+ * Returns an error of the document is not currently cached.


Think this should be "if"

googlebot · 2020-09-25T19:36:17Z

CLAs look good, thanks!

ℹ️ Googlers: Go here for more info.

schmidt-sebastian

Thanks for looking at this so quickly! Feedback addressed.

schmidt-sebastian · 2020-09-25T19:13:51Z

packages/firestore/exp/src/api/reference.ts

- * by waiting for data from the server, but it may return cached data or fail
- * if you are offline and the server cannot be reached. This behavior can be
- * altered via the `GetOptions` parameter.
+ * Note: getDoc() attempts to provide up-to-date data when possible by waiting


schmidt-sebastian · 2020-09-25T19:14:12Z

packages/firestore/exp/src/api/reference.ts

- * if you are offline and the server cannot be reached. This behavior can be
- * altered via the `GetOptions` parameter.
+ * Reads the document referred to by this `DocumentReference` from cache.
+ * Returns an error of the document is not currently cached.


schmidt-sebastian · 2020-09-25T19:16:45Z

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

- * @param other The `DocumentSnapshot` to compare against.
- * @return true if this `DocumentSnapshot` is equal to the provided one.
+ * @param left A snapshot to compare.
+ * @param right A snapshot` to compare.


schmidt-sebastian · 2020-09-25T19:17:33Z

packages/firestore/lite/src/api/bytes.ts

@@ -29,7 +29,7 @@ export class Bytes {
  }

  /**
-   * Creates a new Blob from the given Base64 string, converting it to
+   * Creates a new Bytes object from the given Base64 string, converting it to


schmidt-sebastian · 2020-09-25T19:17:59Z

packages/firestore/lite/src/api/field_value.ts

 *
 * @param elements The elements to remove from the array.
- * @return The FieldValue sentinel for use in a call to `set()` or `update()`.
+ * @return The FieldValue sentinel for use in a call to `setDoc()` or


schmidt-sebastian · 2020-09-25T19:33:16Z

packages/firestore/lite/src/api/reference.ts

@@ -1114,10 +1197,13 @@ export function refEqual<T>(
 }

 /**
- * Returns true if this `Query` is equal to the provided one.
+ * Returns true if the provided Queries point to the same collection and apply


schmidt-sebastian · 2020-09-25T19:34:21Z

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

+  /**
+   * Called by the Firestore SDK to convert a custom model object of type T
+   * into a plain Javascript object (suitable for writing directly to the
+   * Firestore database). Used with {@link setData()}, {@link WriteBatch#set()}


I am hoping it looks nice in the final output, but I am not sure. A lot of the old code did this instead:

{@link setDoc setDoc()}

I hope this is the same as {@link setDoc()}.

schmidt-sebastian · 2020-09-25T19:35:07Z

packages/firestore/lite/src/api/transaction.ts

 * @param updateFunction The function to execute within the transaction context.
- * @return If the transaction completed successfully or was explicitly aborted
+ * @return  If the transaction completed successfully or was explicitly aborted
 * (the `updateFunction` returned a failed promise), the promise returned by the
 * updateFunction is returned here. Else, if the transaction failed, a rejected


schmidt-sebastian · 2020-09-25T19:35:11Z

packages/firestore/lite/src/api/transaction.ts

 * @param updateFunction The function to execute within the transaction context.
- * @return If the transaction completed successfully or was explicitly aborted
+ * @return  If the transaction completed successfully or was explicitly aborted
 * (the `updateFunction` returned a failed promise), the promise returned by the
 * updateFunction is returned here. Else, if the transaction failed, a rejected


schmidt-sebastian · 2020-09-25T19:35:28Z

packages/firestore/lite/src/api/transaction.ts

 * @param updateFunction The function to execute within the transaction context.
- * @return If the transaction completed successfully or was explicitly aborted
+ * @return  If the transaction completed successfully or was explicitly aborted
 * (the `updateFunction` returned a failed promise), the promise returned by the
 * updateFunction is returned here. Else, if the transaction failed, a rejected
 * promise with the corresponding failure error will be returned.


schmidt-sebastian · 2020-09-25T22:03:56Z

@wilhuff - Eric looked at this PR when it was a diff against #3792 and says it looks good. I rebased the PR against master and need a rubberstamp from our team.

wilhuff · 2020-09-25T22:10:23Z

packages/firestore/exp/src/api/database.ts

@@ -173,6 +174,17 @@ export class FirebaseFirestore
  }
 }

+/**
+ * Initializes a new instance of Cloud Firestore with the provided settings.
+ * Can only be called before any other methods, including


This seems no longer to be a method. Isn't it a function?

This comment applies throughout.

Very nice catch. Fixed here and everywhere.

wilhuff · 2020-09-25T22:11:12Z

packages/firestore/exp/src/api/database.ts

+ * {@link getFirestore()}. If the custom settings are empty, this method is
+ * equivalent to calling {@link getFirestore()}.
+ *
+ * @param app The {@link FirebaseApp} that the Firestore instance will be


Do we care about prepositions at the end of sentences? If so: The app with which the Firestore instance will be associated.

I have no preference here. Fixed.

wilhuff · 2020-09-25T22:12:32Z

packages/firestore/exp/src/api/database.ts

+ * {@link initializeFirestore()}, {@link getFirestore()} or
+ * {@link clearIndexedDbPersistence()}.
+ *
+ * If this fails, enableIndexedDbPersistence() will reject the promise it


Should enableIndexedDbPersistence be in backticks?

Same concern in the other methods of this type.

Fixed (three times)

wilhuff · 2020-09-25T22:14:13Z

packages/firestore/exp/src/api/database.ts

+ * documents.
+ *
+ * Must be called while the firestore instance is not started (after the app is
+ * shutdown or when the app is first initialized). On startup, this method must


"shutdown" should be two words or should possibly be "terminated" since terminate is the function, not shutdown.

wilhuff · 2020-09-25T22:16:04Z

packages/firestore/exp/src/api/database.ts

+/**
+ * Disables network usage for this instance. It can be re-enabled via {@link
+ * enableNetwork()}. While the network is disabled, any snapshot listeners,
+ * getDoc() or getDocs() calls will return results from cache, and any write


Should getDoc and getDocs be in backticks?

wilhuff · 2020-09-25T23:02:12Z

packages/firestore/src/api/geo_point.ts

@@ -54,19 +63,25 @@ export class GeoPoint {
  }

  /**
-   * Returns the latitude of this geo point, a number between -90 and 90.
+   * The latitude of this GeoPoint instance.


GeoPoint in backticks?

wilhuff · 2020-09-25T23:02:51Z

packages/firestore/src/api/timestamp.ts

+ * calendar, represented as seconds and fractions of seconds at nanosecond
+ * resolution in UTC Epoch time.
+ *
+ * It is encoded using the Proleptic Gregorian


Reflow text?

wilhuff · 2020-09-25T23:04:16Z

packages/firestore/src/api/timestamp.ts

@@ -64,10 +108,24 @@ export class Timestamp {
    }
  }

+  /**
+   * Convert a Timestamp to a JavaScript `Date` object. This conversion causes


Should start with "Converts", not "Convert". Timestamp in backticks or make it lowercase like below.

wilhuff · 2020-09-25T23:05:26Z

packages/firestore/src/api/timestamp.ts

  toDate(): Date {
    return new Date(this.toMillis());
  }

+  /**
+   * Convert a timestamp to a numeric timestamp (in milliseconds since epoch).


"Converts"

Also, the first "timestamp" should probably be Timestamp since we're talking about both this type and "numeric timestamp" in the same sentence.

wilhuff · 2020-09-25T23:06:46Z

packages/firestore/src/util/log.ts

+ *   the following values:
+ *
+ *   <ul>
+ *     <li><code>debug</code> for the most verbose logging level, primarily for


Should these <code> spans just be backticks?

schmidt-sebastian

Thanks for the thorough review! Feedback addressed.

schmidt-sebastian · 2020-09-28T17:13:40Z

packages/firestore/exp/src/api/database.ts

@@ -173,6 +174,17 @@ export class FirebaseFirestore
  }
 }

+/**
+ * Initializes a new instance of Cloud Firestore with the provided settings.
+ * Can only be called before any other methods, including


Very nice catch. Fixed here and everywhere.

schmidt-sebastian · 2020-09-28T17:14:27Z

packages/firestore/exp/src/api/database.ts

+ * {@link getFirestore()}. If the custom settings are empty, this method is
+ * equivalent to calling {@link getFirestore()}.
+ *
+ * @param app The {@link FirebaseApp} that the Firestore instance will be


I have no preference here. Fixed.

schmidt-sebastian · 2020-09-28T17:15:43Z

packages/firestore/exp/src/api/database.ts

+ * {@link initializeFirestore()}, {@link getFirestore()} or
+ * {@link clearIndexedDbPersistence()}.
+ *
+ * If this fails, enableIndexedDbPersistence() will reject the promise it


Fixed (three times)

schmidt-sebastian · 2020-09-28T17:16:08Z

packages/firestore/exp/src/api/database.ts

+ * documents.
+ *
+ * Must be called while the firestore instance is not started (after the app is
+ * shutdown or when the app is first initialized). On startup, this method must


schmidt-sebastian · 2020-09-28T17:17:02Z

packages/firestore/exp/src/api/database.ts

+/**
+ * Disables network usage for this instance. It can be re-enabled via {@link
+ * enableNetwork()}. While the network is disabled, any snapshot listeners,
+ * getDoc() or getDocs() calls will return results from cache, and any write


schmidt-sebastian · 2020-09-28T18:48:44Z

packages/firestore/src/api/geo_point.ts

@@ -23,15 +23,24 @@ import {
 import { primitiveComparator } from '../util/misc';

 /**
- * Immutable class representing a geo point as latitude-longitude pair.
- * This class is directly exposed in the public API, including its constructor.
+ * An immutable object representing a geo point in Firestore. The geo point


schmidt-sebastian · 2020-09-28T18:49:07Z

packages/firestore/src/api/geo_point.ts

@@ -54,19 +63,25 @@ export class GeoPoint {
  }

  /**
-   * Returns the latitude of this geo point, a number between -90 and 90.
+   * The latitude of this GeoPoint instance.


schmidt-sebastian · 2020-09-28T18:50:11Z

packages/firestore/src/api/timestamp.ts

@@ -64,10 +108,24 @@ export class Timestamp {
    }
  }

+  /**
+   * Convert a Timestamp to a JavaScript `Date` object. This conversion causes


schmidt-sebastian · 2020-09-28T18:50:24Z

packages/firestore/src/api/timestamp.ts

  toDate(): Date {
    return new Date(this.toMillis());
  }

+  /**
+   * Convert a timestamp to a numeric timestamp (in milliseconds since epoch).


schmidt-sebastian · 2020-09-28T18:51:27Z

packages/firestore/src/util/log.ts

+ *   the following values:
+ *
+ *   <ul>
+ *     <li><code>debug</code> for the most verbose logging level, primarily for


google-oss-bot · 2020-09-28T19:17:50Z

Size Analysis Report

Affected Products

No changes between base commit (a6af7c2) and head commit (d63b572).

Test Logs

Base (a6af7c27): https://github.com/firebase/firebase-js-sdk/actions/runs/272725135
Head (d63b572d): https://github.com/firebase/firebase-js-sdk/actions/runs/277394282

wilhuff

LGTM

wilhuff · 2020-09-28T20:47:17Z

packages/firestore/lite/src/api/reference.ts

+ * caching or see local modifications, please use the full Firestore SDK.
+ *
+ * @param reference The reference of the document to fetch.
+ * @return A Promise resolved with a  DocumentSnapshot   containing the


Something is wrong with the DocumentSnapshot here. Too many spaces surrounding it and no backticks.

wilhuff · 2020-09-28T21:00:20Z

packages/firestore/lite/src/api/reference.ts

@@ -903,11 +903,11 @@ export function doc<T>(
 * All documents are directly fetched from the server, even if the document was
 * previously read or modified. Recent modifications are only reflected in the
 * retrieved `DocumentSnapshot` if they have already been applied by the
- * backend. If you like to use caching or see local modifications, please use
- * the full Firestore SDK.
+ * backend.  If the client is offline, the read fails. If you like to use


Extra space after period.

schmidt-sebastian added 4 commits September 16, 2020 10:13

Copy & Paste existing docs

b68b20e

Merge

f1d4745

Reduce diff

9a66285

Add firestore-exp/firestore-lite docs

40ec00a

schmidt-sebastian requested review from alikn, andirayo, avolkovi, bojeil-google, ChaoqunCHEN, davideast, erikeldridge, Feiyang1, hiranya911, hsubox76, jamesdaniels, jsdt, sam-gc, scottcrossen, yuchenshi, zijianjoy and zwu52 as code owners September 24, 2020 23:19

schmidt-sebastian changed the base branch from mrschmidt/docs to master September 24, 2020 23:20

schmidt-sebastian changed the base branch from master to mrschmidt/docs September 24, 2020 23:20

schmidt-sebastian changed the title ~~Mrschmidt/docsupdate~~ Add firestore-exp/firestore-lite docs Sep 24, 2020

schmidt-sebastian assigned erikeldridge Sep 24, 2020

schmidt-sebastian added the api: firestore label Sep 24, 2020

schmidt-sebastian assigned egilmorez and unassigned erikeldridge Sep 24, 2020

egilmorez reviewed Sep 25, 2020

View reviewed changes

Feedback

41b26c5

schmidt-sebastian commented Sep 25, 2020

View reviewed changes

schmidt-sebastian changed the base branch from mrschmidt/docs to master September 25, 2020 22:01

schmidt-sebastian assigned wilhuff Sep 25, 2020

schmidt-sebastian requested review from wilhuff and removed request for yuchenshi, zwu52 and zijianjoy September 25, 2020 22:02

wilhuff reviewed Sep 25, 2020

View reviewed changes

wilhuff assigned schmidt-sebastian and unassigned wilhuff Sep 25, 2020

Address Gil's feedback

e0adfc9

schmidt-sebastian commented Sep 28, 2020

View reviewed changes

schmidt-sebastian assigned wilhuff and unassigned egilmorez and schmidt-sebastian Sep 28, 2020

wilhuff approved these changes Sep 28, 2020

View reviewed changes

wilhuff assigned schmidt-sebastian and unassigned wilhuff Sep 28, 2020

Fix

84e69c4

schmidt-sebastian merged commit 7c1c7f1 into master Sep 28, 2020

schmidt-sebastian mentioned this pull request Sep 29, 2020

Remove cyclic references in RemoteDocumentCache #3857

Merged

firebase locked and limited conversation to collaborators Oct 29, 2020

schmidt-sebastian deleted the mrschmidt/docsupdate branch November 9, 2020 22:38

Add firestore-exp/firestore-lite docs #3843

Add firestore-exp/firestore-lite docs #3843

Uh oh!

Conversation

schmidt-sebastian commented Sep 24, 2020

Uh oh!

changeset-bot bot commented Sep 24, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

googlebot commented Sep 24, 2020

Uh oh!

google-oss-bot commented Sep 24, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Binary Size Report

Affected SDKs

@firebase/firestore/exp

@firebase/firestore/lite

Test Logs

Uh oh!

egilmorez left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

googlebot commented Sep 25, 2020

Uh oh!

schmidt-sebastian left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

changeset-bot bot commented Sep 24, 2020 •

edited

Loading

google-oss-bot commented Sep 24, 2020 •

edited

Loading

`@firebase/firestore/exp`

`@firebase/firestore/lite`