Repository navigation
Conversation
There was a problem hiding this comment.
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.
| extension type UpdateStageOptionsJsImpl._(JSObject _) implements JSObject { | ||
| UpdateStageOptionsJsImpl() : this._(JSObject.new()); | ||
|
|
||
| // ignore: avoid_setters_without_getters | ||
| external set transformedFields(JSAny value); | ||
| } |
There was a problem hiding this comment.
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);
}| /// 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; | ||
| } |
There was a problem hiding this comment.
Update the setter to use expressions instead of transformedFields to match the JS SDK options interface.
| /// 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; | |
| } |
| 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); | ||
| } |
There was a problem hiding this comment.
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);
}| 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)), | ||
| ); | ||
| } | ||
| } |
There was a problem hiding this comment.
Update the property name to 'documentId'.toJS to match the JS SDK options interface.
| 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)), | |
| ); | |
| } | |
| } |
| 'literals' => source.literals( | ||
| converter.toLiteralsDocuments( | ||
| (args as Map<String, dynamic>)['documents']! as List<dynamic>, | ||
| ), | ||
| ), |
There was a problem hiding this comment.
Avoid using the ! operator per the repository style guide. Use flow analysis or a null-coalescing operator instead.
| '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
- 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.
aff73a0 to
e242549
Compare
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.
demolaf
left a comment
There was a problem hiding this comment.
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() { |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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) { |
There was a problem hiding this comment.
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) { |
There was a problem hiding this comment.
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) { |
There was a problem hiding this comment.
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({ |
There was a problem hiding this comment.
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', () { |
There was a problem hiding this comment.
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.
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.atomicis 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.yamland changelogs is not required.///).melos run analyze) does not report any problems on my PR.Breaking Change
Does your PR require plugin users to manually update their apps to accommodate your change?
Test plan
flutter testforpipeline_execute_options_test.dart,pipeline_source_test.dart, andpipeline_stage_test.dart(76 tests passed locally). The execute-options test checks thatatomic: trueis sent only when atomic execution is requested, that a defaultExecuteOptionssends only the index mode, and that omitting options sends null.flutter test --platform=chrome test/pipeline_writes_web_test.dartincloud_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.cloud_firestoreunit tests.pipeline_writes_e2e.dart. Thepipeline-e2e-webjob runs it against the livefirestore-pipeline-testdatabase, not the emulator. It is skipped on Android and iOS because those platforms reject the new stages. It was not run locally.