Skip to content

feat(firestore): add web pipeline writes and atomic execute - #18954

Open
SelaseKay wants to merge 4 commits into
mainfrom
feat/firestore-web-pipeline-dml
Open

SelaseKay wants to merge 4 commits into
mainfrom
feat/firestore-web-pipeline-dml

Conversation

@SelaseKay

@SelaseKay SelaseKay commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Description

Cloud Firestore pipelines on the web JS SDK can delete, update, insert, and upsert documents, including a literals source and an atomic execute option. The Dart API could not express those stages.

This adds them to the shared Dart pipeline API and binds them in the web implementation. Android, iOS, macOS, and Windows are unchanged. On those platforms, executing a pipeline that uses one of the new stages fails before any write is sent. ExecuteOptions.atomic is included in the execute options only when it is true. Android and Apple ignore that flag, which only matters for read pipelines today because the new write stages are rejected first. Windows does not implement pipelines.

Related Issues

None.

Checklist

Before you create this PR confirm that it meets all requirements listed below by checking the relevant checkboxes ([x]).
This will ensure a smooth and quick review process. Updating the pubspec.yaml and changelogs is not required.

  • I read the Contributor Guide and followed the process outlined there for submitting PRs.
  • My PR includes unit or integration tests for all changed/updated/fixed behaviors (See Contributor Guide).
  • All existing and new tests are passing.
  • I updated/added relevant documentation (doc comments with ///).
  • The analyzer (melos run analyze) does not report any problems on my PR.
  • I read and followed the Flutter Style Guide.
  • I signed the CLA.
  • I am willing to follow-up on review comments in a timely manner.

Breaking Change

Does your PR require plugin users to manually update their apps to accommodate your change?

  • Yes, this is a breaking change.
  • No, this is not a breaking change.

Test plan

  • flutter test for pipeline_execute_options_test.dart, pipeline_source_test.dart, and pipeline_stage_test.dart (76 tests passed locally). The execute-options test checks that atomic: true is sent only when atomic execution is requested, that a default ExecuteOptions sends only the index mode, and that omitting options sends null.
  • flutter test --platform=chrome test/pipeline_writes_web_test.dart in cloud_firestore_web (2 tests passed locally). It builds literals, upsert, insert, update, and delete through the web pipeline builder and checks the JS property names.
  • CI format, analyze, and the cloud_firestore unit tests.
  • Web live round-trip in pipeline_writes_e2e.dart. The pipeline-e2e-web job runs it against the live firestore-pipeline-test database, not the emulator. It is skipped on Android and iOS because those platforms reject the new stages. It was not run locally.

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request adds data manipulation stages (delete, update, insert, upsert) and a literals source stage to the Firestore Pipeline API, along with an atomic execution option. The review feedback highlights critical JS interop mapping issues on the web platform where property names (such as transformedFields and documentIdExpression) do not match the Firebase JS SDK. Additionally, a style guide violation regarding the use of the non-null assertion operator (!) was identified.

Comment on lines +1423 to +1428
extension type UpdateStageOptionsJsImpl._(JSObject _) implements JSObject {
UpdateStageOptionsJsImpl() : this._(JSObject.new());

// ignore: avoid_setters_without_getters
external set transformedFields(JSAny value);
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

The Firebase JS SDK UpdateStageOptions interface expects the property name to be expressions, not transformedFields. Using transformedFields will cause the JS SDK to ignore the update expressions entirely.

extension type UpdateStageOptionsJsImpl._(JSObject _) implements JSObject {
  UpdateStageOptionsJsImpl() : this._(JSObject.new());

  // ignore: avoid_setters_without_getters
  external set expressions(JSAny value);
}

Comment on lines +703 to +711
/// Converts an update stage into JS UpdateStageOptions.
JSAny toUpdateOptions(Map<String, dynamic> map) {
final options = interop.UpdateStageOptionsJsImpl();
final expressions = map['expressions'] as List<dynamic>?;
if (expressions != null && expressions.isNotEmpty) {
options.transformedFields = _toSelectableList(expressions).toJS;
}
return options;
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

Update the setter to use expressions instead of transformedFields to match the JS SDK options interface.

Suggested change
/// Converts an update stage into JS UpdateStageOptions.
JSAny toUpdateOptions(Map<String, dynamic> map) {
final options = interop.UpdateStageOptionsJsImpl();
final expressions = map['expressions'] as List<dynamic>?;
if (expressions != null && expressions.isNotEmpty) {
options.transformedFields = _toSelectableList(expressions).toJS;
}
return options;
}
/// Converts an update stage into JS UpdateStageOptions.
JSAny toUpdateOptions(Map<String, dynamic> map) {
final options = interop.UpdateStageOptionsJsImpl();
final expressions = map['expressions'] as List<dynamic>?;
if (expressions != null && expressions.isNotEmpty) {
options.expressions = _toSelectableList(expressions).toJS;
}
return options;
}

Comment on lines +1430 to +1448
extension type InsertStageOptionsJsImpl._(JSObject _) implements JSObject {
InsertStageOptionsJsImpl() : this._(JSObject.new());

// ignore: avoid_setters_without_getters
external set collection(JSString value);
// ignore: avoid_setters_without_getters
external set documentIdExpression(JSAny value);
}

extension type UpsertStageOptionsJsImpl._(JSObject _) implements JSObject {
UpsertStageOptionsJsImpl() : this._(JSObject.new());

// ignore: avoid_setters_without_getters
external set collection(JSString value);
// ignore: avoid_setters_without_getters
external set documentIdExpression(JSAny value);
// ignore: avoid_setters_without_getters
external set additionalFields(JSAny value);
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

The Firebase JS SDK InsertStageOptions and UpsertStageOptions interfaces expect the property name to be documentId, not documentIdExpression. Using documentIdExpression will cause the JS SDK to ignore the custom document ID expression.

extension type InsertStageOptionsJsImpl._(JSObject _) implements JSObject {
  InsertStageOptionsJsImpl() : this._(JSObject.new());

  // ignore: avoid_setters_without_getters
  external set collection(JSString value);
  // ignore: avoid_setters_without_getters
  external set documentId(JSAny value);
}

extension type UpsertStageOptionsJsImpl._(JSObject _) implements JSObject {
  UpsertStageOptionsJsImpl() : this._(JSObject.new());

  // ignore: avoid_setters_without_getters
  external set collection(JSString value);
  // ignore: avoid_setters_without_getters
  external set documentId(JSAny value);
  // ignore: avoid_setters_without_getters
  external set additionalFields(JSAny value);
}

Comment on lines +731 to +743
void _applyWriteTarget(JSObject options, Map<String, dynamic> map) {
final collection = map['collection'] as String?;
if (collection != null) {
options.setProperty('collection'.toJS, collection.toJS);
}
final documentId = map['document_id'];
if (documentId is Map) {
options.setProperty(
'documentIdExpression'.toJS,
toExpression(Map<String, dynamic>.from(documentId)),
);
}
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

Update the property name to 'documentId'.toJS to match the JS SDK options interface.

Suggested change
void _applyWriteTarget(JSObject options, Map<String, dynamic> map) {
final collection = map['collection'] as String?;
if (collection != null) {
options.setProperty('collection'.toJS, collection.toJS);
}
final documentId = map['document_id'];
if (documentId is Map) {
options.setProperty(
'documentIdExpression'.toJS,
toExpression(Map<String, dynamic>.from(documentId)),
);
}
}
void _applyWriteTarget(JSObject options, Map<String, dynamic> map) {
final collection = map['collection'] as String?;
if (collection != null) {
options.setProperty('collection'.toJS, collection.toJS);
}
final documentId = map['document_id'];
if (documentId is Map) {
options.setProperty(
'documentId'.toJS,
toExpression(Map<String, dynamic>.from(documentId)),
);
}
}

Comment on lines +63 to +67
'literals' => source.literals(
converter.toLiteralsDocuments(
(args as Map<String, dynamic>)['documents']! as List<dynamic>,
),
),

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

low

Avoid using the ! operator per the repository style guide. Use flow analysis or a null-coalescing operator instead.

Suggested change
'literals' => source.literals(
converter.toLiteralsDocuments(
(args as Map<String, dynamic>)['documents']! as List<dynamic>,
),
),
'literals' => source.literals(
converter.toLiteralsDocuments(
((args as Map<String, dynamic>)['documents'] ?? const []) as List<dynamic>,
),
),
References
  1. Null Safety: NO ! operator. Use ? and flow analysis (e.g. if (x != null)). (link)

The JS SDK can delete, update, insert, and upsert through a pipeline, including a literals source and an atomic execute option. Expose those stages on the shared Dart API and bind them on web.
@SelaseKay
SelaseKay force-pushed the feat/firestore-web-pipeline-dml branch from aff73a0 to e242549 Compare November 13, 2026 07:15
The web write stages were bound, but nothing built the JS options or
round-tripped a write. Lock the property names and add a web-only live path.
@SelaseKay
SelaseKay marked this pull request as ready for review November 19, 2026 12:35

@demolaf demolaf left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A few blocking issues on the write stages: the update/upsert field types, web-only behavior on mobile, and upsert's target-path docs. The rest are non-blocking.

/// .where(Expression.field('genre').equal('Science Fiction'))
/// .delete();
/// ```
Pipeline delete() {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mark delete, update, insert, upsert and literals as web-only in their docs, or throw UnsupportedError on other platforms. Right now Android and Apple fail at execute with a generic "Unknown pipeline stage" error.

///
/// An existing document is replaced entirely. Fields that are not in the
/// written document are removed. [additionalFields] are aliased expressions
/// merged onto each input document before the write. See [insert] for how

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Document upsert's own target rules here instead of pointing to insert. The JS UpsertStageOptions doesn't define the documentId-only case, so either reject documentId without collectionPath or confirm the backend supports it.

}

Map<String, dynamic> _encodeLiteralField(Object? value) {
if (value is Expression) {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this reject AliasedExpression? A top-level .as() value passes this check, then toExpression on web throws unsupported-expression at execute.

///
/// Lists become JS arrays. Nested maps stay maps. [List<int>] is an array
/// of numbers here; byte values are [Blob].
JSAny? _literalValueToJs(Object? value) {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider mapping Uint8List to Bytes here. A bare bytes literal currently becomes an int array, while the same value wrapped in Expression.constant is stored as bytes.

}
}

void _checkCollectionPath(String? collectionPath) {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Worth also rejecting even segment counts and leading or trailing slashes here. 'books/dune' currently passes and only fails on the backend.

/// written document are removed. [additionalFields] are aliased expressions
/// merged onto each input document before the write. See [insert] for how
/// [collectionPath] and [documentId] choose the target path.
Pipeline upsert({

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we document that write stages must be the final stage? .delete().limit(1) compiles, and the backend error doesn't explain the ordering rule.

},
);

test('a literals stage with no documents list still builds', () {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Make the builder throw on missing or empty documents and flip this test to expect it. literals() already rejects an empty list, so the silent const [] fallback contradicts the public API.

Match the JS SDK field and target rules, and fail web-only stages on other platforms with UnsupportedError instead of an unknown-stage error.
Check every write stage on the method channel, and check that a byte literal stays bytes on web.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants