Skip to content

feat(firestore): support serverTimestamps option on snapshot listeners #993

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
robingenz merged 2 commits into from
Jun 4, 2026
+189 −24
Merged

feat(firestore): support serverTimestamps option on snapshot listeners #993

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d03ec0b
feat(firestore): add serverTimestamps option to snapshot listeners
robingenz May 25, 2026
8bee41b
fix(firestore): address PR review feedback
robingenz May 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/firestore-server-timestamps.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@capacitor-firebase/firestore': minor
---

feat(firestore): support `serverTimestamps` behavior option for `addDocumentSnapshotListener(...)`, `addCollectionSnapshotListener(...)`, and `addCollectionGroupSnapshotListener(...)`
16 changes: 13 additions & 3 deletions ...src/main/java/io/capawesome/capacitorjs/plugins/firebase/firestore/FirebaseFirestore.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
import com.google.firebase.firestore.AggregateSource;
import com.google.firebase.firestore.CollectionReference;
import com.google.firebase.firestore.DocumentReference;
import com.google.firebase.firestore.DocumentSnapshot;
import com.google.firebase.firestore.Filter;
import com.google.firebase.firestore.FirebaseFirestoreSettings;
import com.google.firebase.firestore.ListenerRegistration;
Expand Down Expand Up @@ -269,6 +270,9 @@ public void getCountFromServer(@NonNull GetCountFromServerOptions options, @NonN
public void addDocumentSnapshotListener(@NonNull AddDocumentSnapshotListenerOptions options, @NonNull NonEmptyResultCallback callback) {
String reference = options.getReference();
String callbackId = options.getCallbackId();
DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior = FirebaseFirestoreHelper.createServerTimestampBehavior(
options.getServerTimestampBehavior()
);

ListenerRegistration listenerRegistration = getFirebaseFirestoreInstance()
.document(reference)
Expand All @@ -278,7 +282,7 @@ public void addDocumentSnapshotListener(@NonNull AddDocumentSnapshotListenerOpti
if (exception != null) {
callback.error(exception);
} else {
GetDocumentResult result = new GetDocumentResult(documentSnapshot);
GetDocumentResult result = new GetDocumentResult(documentSnapshot, serverTimestampBehavior);
callback.success(result);
}
}
Expand All @@ -294,6 +298,9 @@ public void addCollectionSnapshotListener(
QueryCompositeFilterConstraint compositeFilter = options.getCompositeFilter();
QueryNonFilterConstraint[] queryConstraints = options.getQueryConstraints();
String callbackId = options.getCallbackId();
DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior = FirebaseFirestoreHelper.createServerTimestampBehavior(
options.getServerTimestampBehavior()
);

Query query = getFirebaseFirestoreInstance().collection(reference);
if (compositeFilter != null) {
Expand All @@ -312,7 +319,7 @@ public void addCollectionSnapshotListener(
if (exception != null) {
callback.error(exception);
} else {
GetCollectionResult result = new GetCollectionResult(querySnapshot);
GetCollectionResult result = new GetCollectionResult(querySnapshot, serverTimestampBehavior);
callback.success(result);
}
}
Expand All @@ -328,6 +335,9 @@ public void addCollectionGroupSnapshotListener(
QueryCompositeFilterConstraint compositeFilter = options.getCompositeFilter();
QueryNonFilterConstraint[] queryConstraints = options.getQueryConstraints();
String callbackId = options.getCallbackId();
DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior = FirebaseFirestoreHelper.createServerTimestampBehavior(
options.getServerTimestampBehavior()
);

Query query = getFirebaseFirestoreInstance().collectionGroup(reference);
if (compositeFilter != null) {
Expand All @@ -346,7 +356,7 @@ public void addCollectionGroupSnapshotListener(
if (exception != null) {
callback.error(exception);
} else {
GetCollectionResult result = new GetCollectionResult(querySnapshot);
GetCollectionResult result = new GetCollectionResult(querySnapshot, serverTimestampBehavior);
callback.success(result);
}
}
Expand Down
15 changes: 15 additions & 0 deletions ...in/java/io/capawesome/capacitorjs/plugins/firebase/firestore/FirebaseFirestoreHelper.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,21 @@

public class FirebaseFirestoreHelper {

@NonNull
public static DocumentSnapshot.ServerTimestampBehavior createServerTimestampBehavior(@Nullable String value) {
if (value == null) {
return DocumentSnapshot.ServerTimestampBehavior.NONE;
}
switch (value) {
case "estimate":
return DocumentSnapshot.ServerTimestampBehavior.ESTIMATE;
case "previous":
return DocumentSnapshot.ServerTimestampBehavior.PREVIOUS;
default:
return DocumentSnapshot.ServerTimestampBehavior.NONE;
}
}

public static HashMap<String, Object> createHashMapFromJSONObject(JSONObject object) throws JSONException {
HashMap<String, Object> map = new HashMap<>();
Iterator<String> keys = object.keys();
Expand Down
6 changes: 6 additions & 0 deletions ...in/java/io/capawesome/capacitorjs/plugins/firebase/firestore/FirebaseFirestorePlugin.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -463,13 +463,15 @@ public void addDocumentSnapshotListener(PluginCall call) {
return;
}
Boolean includeMetadataChanges = call.getBoolean("includeMetadataChanges");
String serverTimestampBehavior = call.getString("serverTimestamps");
String callbackId = call.getCallbackId();

this.pluginCallMap.put(callbackId, call);

AddDocumentSnapshotListenerOptions options = new AddDocumentSnapshotListenerOptions(
reference,
includeMetadataChanges,
serverTimestampBehavior,
callbackId
);
NonEmptyResultCallback callback = new NonEmptyResultCallback() {
Expand Down Expand Up @@ -505,6 +507,7 @@ public void addCollectionSnapshotListener(PluginCall call) {
JSObject compositeFilter = call.getObject("compositeFilter");
JSArray queryConstraints = call.getArray("queryConstraints");
Boolean includeMetadataChanges = call.getBoolean("includeMetadataChanges");
String serverTimestampBehavior = call.getString("serverTimestamps");
String callbackId = call.getCallbackId();

this.pluginCallMap.put(callbackId, call);
Expand All @@ -514,6 +517,7 @@ public void addCollectionSnapshotListener(PluginCall call) {
compositeFilter,
queryConstraints,
includeMetadataChanges,
serverTimestampBehavior,
callbackId
);
NonEmptyResultCallback callback = new NonEmptyResultCallback() {
Expand Down Expand Up @@ -549,6 +553,7 @@ public void addCollectionGroupSnapshotListener(PluginCall call) {
JSObject compositeFilter = call.getObject("compositeFilter");
JSArray queryConstraints = call.getArray("queryConstraints");
Boolean includeMetadataChanges = call.getBoolean("includeMetadataChanges");
String serverTimestampBehavior = call.getString("serverTimestamps");
String callbackId = call.getCallbackId();

this.pluginCallMap.put(callbackId, call);
Expand All @@ -558,6 +563,7 @@ public void addCollectionGroupSnapshotListener(PluginCall call) {
compositeFilter,
queryConstraints,
includeMetadataChanges,
serverTimestampBehavior,
callbackId
);
NonEmptyResultCallback callback = new NonEmptyResultCallback() {
Expand Down
10 changes: 10 additions & 0 deletions ...plugins/firebase/firestore/classes/options/AddCollectionGroupSnapshotListenerOptions.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,17 +24,22 @@ public class AddCollectionGroupSnapshotListenerOptions {

private boolean includeMetadataChanges;

@Nullable
private final String serverTimestampBehavior;

public AddCollectionGroupSnapshotListenerOptions(
String reference,
@Nullable JSObject compositeFilter,
@Nullable JSArray queryConstraints,
@Nullable Boolean includeMetadataChanges,
@Nullable String serverTimestampBehavior,
String callbackId
) throws JSONException {
this.reference = reference;
this.compositeFilter = FirebaseFirestoreHelper.createQueryCompositeFilterConstraintFromJSObject(compositeFilter);
this.queryConstraints = FirebaseFirestoreHelper.createQueryNonFilterConstraintArrayFromJSArray(queryConstraints);
this.includeMetadataChanges = includeMetadataChanges == null ? false : includeMetadataChanges;
this.serverTimestampBehavior = serverTimestampBehavior;
this.callbackId = callbackId;
}

Expand All @@ -56,6 +61,11 @@ public boolean isIncludeMetadataChanges() {
return includeMetadataChanges;
}

@Nullable
public String getServerTimestampBehavior() {
return serverTimestampBehavior;
}

public String getCallbackId() {
return callbackId;
}
Expand Down
10 changes: 10 additions & 0 deletions ...orjs/plugins/firebase/firestore/classes/options/AddCollectionSnapshotListenerOptions.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,17 +25,22 @@ public class AddCollectionSnapshotListenerOptions {

private final boolean includeMetadataChanges;

@Nullable
private final String serverTimestampBehavior;

public AddCollectionSnapshotListenerOptions(
String reference,
@Nullable JSObject compositeFilter,
@Nullable JSArray queryConstraints,
@Nullable Boolean includeMetadataChanges,
@Nullable String serverTimestampBehavior,
String callbackId
) throws JSONException {
this.reference = reference;
this.compositeFilter = FirebaseFirestoreHelper.createQueryCompositeFilterConstraintFromJSObject(compositeFilter);
this.queryConstraints = FirebaseFirestoreHelper.createQueryNonFilterConstraintArrayFromJSArray(queryConstraints);
this.includeMetadataChanges = includeMetadataChanges == null ? false : includeMetadataChanges;
this.serverTimestampBehavior = serverTimestampBehavior;
this.callbackId = callbackId;
}

Expand All @@ -57,6 +62,11 @@ public boolean isIncludeMetadataChanges() {
return includeMetadataChanges;
}

@Nullable
public String getServerTimestampBehavior() {
return serverTimestampBehavior;
}

public String getCallbackId() {
return callbackId;
}
Expand Down
17 changes: 16 additions & 1 deletion ...itorjs/plugins/firebase/firestore/classes/options/AddDocumentSnapshotListenerOptions.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,21 @@ public class AddDocumentSnapshotListenerOptions {

private String reference;
private final boolean includeMetadataChanges;

@Nullable
private final String serverTimestampBehavior;

private String callbackId;

public AddDocumentSnapshotListenerOptions(String reference, @Nullable Boolean includeMetadataChanges, String callbackId) {
public AddDocumentSnapshotListenerOptions(
String reference,
@Nullable Boolean includeMetadataChanges,
@Nullable String serverTimestampBehavior,
String callbackId
) {
this.reference = reference;
this.includeMetadataChanges = includeMetadataChanges == null ? false : includeMetadataChanges;
this.serverTimestampBehavior = serverTimestampBehavior;
this.callbackId = callbackId;
}

Expand All @@ -22,6 +32,11 @@ public boolean isIncludeMetadataChanges() {
return includeMetadataChanges;
}

@Nullable
public String getServerTimestampBehavior() {
return serverTimestampBehavior;
}

public String getCallbackId() {
return callbackId;
}
Expand Down
12 changes: 11 additions & 1 deletion ...apawesome/capacitorjs/plugins/firebase/firestore/classes/results/GetCollectionResult.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,9 @@
package io.capawesome.capacitorjs.plugins.firebase.firestore.classes.results;

import androidx.annotation.NonNull;
import com.getcapacitor.JSArray;
import com.getcapacitor.JSObject;
import com.google.firebase.firestore.DocumentSnapshot;
import com.google.firebase.firestore.QueryDocumentSnapshot;
import com.google.firebase.firestore.QuerySnapshot;
import io.capawesome.capacitorjs.plugins.firebase.firestore.FirebaseFirestoreHelper;
Expand All @@ -12,15 +14,23 @@ public class GetCollectionResult implements Result {

private QuerySnapshot querySnapshot;

@NonNull
private DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior;

public GetCollectionResult(QuerySnapshot querySnapshot) {
this(querySnapshot, DocumentSnapshot.ServerTimestampBehavior.NONE);
}

public GetCollectionResult(QuerySnapshot querySnapshot, @NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior) {
this.querySnapshot = querySnapshot;
this.serverTimestampBehavior = serverTimestampBehavior;
}

@Override
public JSObject toJSObject() {
JSArray snapshotsResult = new JSArray();
for (QueryDocumentSnapshot document : querySnapshot) {
JSObject snapshotDataResult = FirebaseFirestoreHelper.createJSObjectFromMap(document.getData());
JSObject snapshotDataResult = FirebaseFirestoreHelper.createJSObjectFromMap(document.getData(serverTimestampBehavior));

JSObject snapshotResult = new JSObject();
snapshotResult.put("id", document.getId());
Expand Down
11 changes: 10 additions & 1 deletion .../capawesome/capacitorjs/plugins/firebase/firestore/classes/results/GetDocumentResult.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
package io.capawesome.capacitorjs.plugins.firebase.firestore.classes.results;

import androidx.annotation.NonNull;
import com.getcapacitor.JSObject;
import com.google.firebase.firestore.DocumentSnapshot;
import io.capawesome.capacitorjs.plugins.firebase.firestore.FirebaseFirestoreHelper;
Expand All @@ -10,12 +11,20 @@ public class GetDocumentResult implements Result {

private DocumentSnapshot documentSnapshot;

@NonNull
private DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior;

public GetDocumentResult(DocumentSnapshot documentSnapshot) {
this(documentSnapshot, DocumentSnapshot.ServerTimestampBehavior.NONE);
}

public GetDocumentResult(DocumentSnapshot documentSnapshot, @NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior) {
this.documentSnapshot = documentSnapshot;
this.serverTimestampBehavior = serverTimestampBehavior;
}

public JSObject toJSObject() {
Object snapshotDataResult = FirebaseFirestoreHelper.createJSObjectFromMap(documentSnapshot.getData());
Object snapshotDataResult = FirebaseFirestoreHelper.createJSObjectFromMap(documentSnapshot.getData(serverTimestampBehavior));

JSObject snapshotResult = new JSObject();
snapshotResult.put("id", documentSnapshot.getId());
Expand Down
8 changes: 7 additions & 1 deletion ...ages/firestore/ios/Plugin/Classes/Options/AddCollectionGroupSnapshotListenerOptions.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,15 @@ import Capacitor
private var compositeFilter: QueryCompositeFilterConstraint?
private var queryConstraints: [QueryNonFilterConstraint]
private var includeMetadataChanges: Bool
private var serverTimestampBehavior: String?
private var callbackId: String

init(reference: String, compositeFilter: JSObject?, queryConstraints: [JSObject]?, includeMetadataChanges: Bool, callbackId: String) {
init(reference: String, compositeFilter: JSObject?, queryConstraints: [JSObject]?, includeMetadataChanges: Bool, serverTimestampBehavior: String?, callbackId: String) {
self.reference = reference
self.compositeFilter = FirebaseFirestoreHelper.createQueryCompositeFilterConstraintFromJSObject(compositeFilter)
self.queryConstraints = FirebaseFirestoreHelper.createQueryNonFilterConstraintArrayFromJSArray(queryConstraints)
self.includeMetadataChanges = includeMetadataChanges
self.serverTimestampBehavior = serverTimestampBehavior
self.callbackId = callbackId
}

Expand All @@ -32,6 +34,10 @@ import Capacitor
return includeMetadataChanges
}

func getServerTimestampBehavior() -> String? {
return serverTimestampBehavior
}

func getCallbackId() -> String {
return callbackId
}
Expand Down
8 changes: 7 additions & 1 deletion packages/firestore/ios/Plugin/Classes/Options/AddCollectionSnapshotListenerOptions.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,15 @@ import Capacitor
private var compositeFilter: QueryCompositeFilterConstraint?
private var queryConstraints: [QueryNonFilterConstraint]
private var includeMetadataChanges: Bool
private var serverTimestampBehavior: String?
private var callbackId: String

init(reference: String, compositeFilter: JSObject?, queryConstraints: [JSObject]?, includeMetadataChanges: Bool, callbackId: String) {
init(reference: String, compositeFilter: JSObject?, queryConstraints: [JSObject]?, includeMetadataChanges: Bool, serverTimestampBehavior: String?, callbackId: String) {
self.reference = reference
self.compositeFilter = FirebaseFirestoreHelper.createQueryCompositeFilterConstraintFromJSObject(compositeFilter)
self.queryConstraints = FirebaseFirestoreHelper.createQueryNonFilterConstraintArrayFromJSArray(queryConstraints)
self.includeMetadataChanges = includeMetadataChanges
self.serverTimestampBehavior = serverTimestampBehavior
self.callbackId = callbackId
}

Expand All @@ -32,6 +34,10 @@ import Capacitor
return includeMetadataChanges
}

func getServerTimestampBehavior() -> String? {
return serverTimestampBehavior
}

func getCallbackId() -> String {
return callbackId
}
Expand Down
8 changes: 7 additions & 1 deletion packages/firestore/ios/Plugin/Classes/Options/AddDocumentSnapshotListenerOptions.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,13 @@ import Foundation
@objc public class AddDocumentSnapshotListenerOptions: NSObject {
private var reference: String
private var includeMetadataChanges: Bool
private var serverTimestampBehavior: String?
private var callbackId: String

init(reference: String, includeMetadataChanges: Bool, callbackId: String) {
init(reference: String, includeMetadataChanges: Bool, serverTimestampBehavior: String?, callbackId: String) {
self.reference = reference
self.includeMetadataChanges = includeMetadataChanges
self.serverTimestampBehavior = serverTimestampBehavior
self.callbackId = callbackId
}

Expand All @@ -19,6 +21,10 @@ import Foundation
return includeMetadataChanges
}

func getServerTimestampBehavior() -> String? {
return serverTimestampBehavior
}

func getCallbackId() -> String {
return callbackId
}
Expand Down
Loading
Loading