feat: Flutter SDK update for version 20.3.0

[abnegate]

This PR contains updates to the Flutter SDK for version 20.3.0.

Summary by CodeRabbit

Release Notes - Version 20.3.0

• New Features
  • Added optional parameter to list queries for performance optimization when row counting is not needed
  • Introduced atomic operations for advanced row modifications including arithmetic, array, string, and date operations

[coderabbitai]

Important

Review skipped

More than 25% of the files skipped due to max files limit. The review is being skipped to prevent a low-quality review.

48 files out of 155 files are above the max files limit of 100. Please upgrade to Pro plan to get higher limits.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Walkthrough

This release (20.3.0) introduces two main features and supporting updates: (1) A new total optional parameter added to list query methods across Account, Databases, Functions, Storage, TablesDB, and Teams services to control row counting behavior; (2) A new Operator class providing static factory methods for atomic row modifications including arithmetic operations (increment, decrement, multiply, divide, modulo, power), array operations (append, prepend, insert, remove, unique, intersect, diff, filter), string operations (concat, replace), boolean toggle, and date operations (add/subtract days, set now). Additional changes include query helper methods updated to use explicit timestamp attributes ($createdAt, $updatedAt), version bumps to 20.3.0, and comprehensive test coverage for new and modified functionality.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~40 minutes

• lib/operator.dart: Review the new Operator class for correct validation logic, especially numeric input guards (NaN, Infinity checks), and ensure factory methods properly construct JSON representations
• lib/services/*.dart (account, databases, functions, storage, tables_db, teams): Verify consistency of the total parameter addition across all service files and that parameter propagation to API requests is correct
• lib/query.dart: Confirm attribute name mappings ($createdAt, $updatedAt) and method reassignments (lessThan, greaterThan, between) are semantically accurate
• test/operator_test.dart: Validate test coverage for edge cases in operator methods, especially numeric validation and array/condition handling
• test/query_test.dart: Ensure updated test expectations align with new query method behaviors

Pre-merge checks and finishing touches

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title Check	❓ Inconclusive	The title "feat: Flutter SDK update for version 20.3.0" is related to the changeset in that it correctly identifies a version bump, but it lacks specificity about the actual feature changes being introduced. The PR contains two significant features: the addition of a total parameter to various list methods for performance optimization, and the introduction of a new Operator class for atomic row modifications. The title uses the generic term "update" without conveying what was actually updated or why these changes matter to developers. While the version reference is not misleading, the title is overly broad and doesn't highlight the primary features, making it difficult for someone scanning the commit history to understand what was changed.	Consider revising the title to be more specific about the key features introduced in this release. A more descriptive title would mention at least one of the main changes, such as "feat: Add total parameter to list queries and introduce Operator class for atomic modifications" or split into two focused PRs if the changes are substantial enough to warrant separate reviews. This would help reviewers and future maintainers quickly understand the purpose of the changeset.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

lib/operator.dart (1)

160-164: Consider handling optional value in arrayFilter more explicitly.

Currently, arrayFilter always includes the value parameter in the values array (line 162), even when it's null. This might not be the intended behavior for conditions like isNull or isNotNull that don't require a comparison value.

Consider updating the implementation to conditionally include the value:

  static String arrayFilter(Condition condition, [dynamic value]) {
-   final values = <dynamic>[condition.value, value];
+   final values = <dynamic>[condition.value];
+   if (value != null) {
+     values.add(value);
+   }
    return Operator._('arrayFilter', values).toString();
  }

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 6f43583 and 16de691.

📒 Files selected for processing (24)

• CHANGELOG.md (1 hunks)
• README.md (1 hunks)
• docs/examples/account/list-identities.md (1 hunks)
• docs/examples/account/list-logs.md (1 hunks)
• docs/examples/databases/list-documents.md (1 hunks)
• docs/examples/functions/list-executions.md (1 hunks)
• docs/examples/storage/list-files.md (1 hunks)
• docs/examples/tablesdb/list-rows.md (1 hunks)
• docs/examples/teams/list-memberships.md (1 hunks)
• docs/examples/teams/list.md (1 hunks)
• lib/appwrite.dart (1 hunks)
• lib/operator.dart (1 hunks)
• lib/query.dart (1 hunks)
• lib/services/account.dart (2 hunks)
• lib/services/databases.dart (2 hunks)
• lib/services/functions.dart (1 hunks)
• lib/services/storage.dart (1 hunks)
• lib/services/tables_db.dart (1 hunks)
• lib/services/teams.dart (2 hunks)
• lib/src/client_browser.dart (1 hunks)
• lib/src/client_io.dart (1 hunks)
• pubspec.yaml (1 hunks)
• test/operator_test.dart (1 hunks)
• test/query_test.dart (1 hunks)

🔇 Additional comments (30)

pubspec.yaml (1)

1-2: Version bump correctly aligned with feature release.

Semantic versioning from 20.2.2 to 20.3.0 is appropriate for the new features (total parameter and Operator class). All dependencies remain stable.

lib/src/client_browser.dart (1)

38-45: Version header correctly updated.

The x-sdk-version header is properly aligned with the pubspec.yaml version bump (20.3.0). This ensures correct API versioning telemetry.

lib/src/client_io.dart (1)

56-63: Version header correctly updated to match other implementations.

The x-sdk-version in ClientIO matches the version in ClientBrowser and pubspec.yaml (20.3.0), maintaining consistency across platform implementations.

docs/examples/account/list-identities.md (1)

9-12: Documentation example updated with new total parameter.

The example now demonstrates the optional total parameter for listIdentities. Ensure the corresponding Account.listIdentities() method signature in the service layer includes this parameter and passes it to the API.

[scratchpad_end] -->

docs/examples/account/list-logs.md (1)

9-12: Documentation example consistently updated across Account service.

Parameter placement and documentation style are consistent with other Account service examples (listIdentities). Verify that Account.listLogs() service method includes the total parameter.

docs/examples/functions/list-executions.md (1)

9-13: Documentation example follows consistent pattern across services.

The total parameter is documented consistently in Functions.listExecutions(), matching the pattern established in Account service examples. Verify that Functions.listExecutions() method signature includes this parameter.

docs/examples/storage/list-files.md (1)

9-14: Documentation example appropriately positioned given Storage method signature.

The total parameter is placed after the search parameter, which is contextually appropriate since Storage.listFiles() has additional parameters compared to Account/Functions list methods. Verify Storage.listFiles() includes the total parameter.

CHANGELOG.md (2)

3-6: Changelog entries clearly document new features.

The 20.3.0 section accurately summarizes the two main features: the optional total parameter for list queries (performance optimization) and the new Operator class for atomic row modifications. Entries are concise and follow the established changelog format.

---

1-6: Verify service implementation files are included in PR scope.

The documentation examples and changelog reference updates to service classes (Account, Databases, Functions, Storage, TablesDB, Teams) to add the total parameter, and mention a new lib/operator.dart file. These implementation files are not visible in the current review scope. Confirm that:

1. All service methods documented in examples have corresponding parameter additions
2. The new Operator class is properly exported from lib/appwrite.dart
3. Query helper methods have been updated with explicit timestamp attributes ($createdAt, $updatedAt)
4. Comprehensive tests exist for both new Operator functionality and updated query methods

docs/examples/teams/list-memberships.md (1)

13-13: LGTM! Documentation example updated correctly.

The addition of the total parameter to the example correctly demonstrates the new optional parameter introduced in the Teams service API.

docs/examples/tablesdb/list-rows.md (1)

14-14: LGTM! Documentation example updated correctly.

The addition of the total parameter to the example correctly demonstrates the new optional parameter introduced in the TablesDB service API.

lib/services/functions.dart (1)

11-19: LGTM! Clean implementation of the total parameter.

The listExecutions method correctly adds the optional total parameter to both the method signature and API parameters, maintaining backward compatibility.

lib/services/tables_db.dart (1)

118-132: LGTM! Clean implementation of the total parameter.

The listRows method correctly adds the optional total parameter to both the method signature and API parameters, maintaining backward compatibility.

lib/services/storage.dart (1)

10-22: LGTM! Clean implementation of the total parameter.

The listFiles method correctly adds the optional total parameter to both the method signature and API parameters, maintaining backward compatibility.

lib/services/databases.dart (1)

122-137: LGTM! Consistent update to deprecated method.

The listDocuments method correctly adds the optional total parameter, maintaining consistency with other services even though this method is deprecated since 1.8.0 in favor of TablesDB.listRows.

docs/examples/databases/list-documents.md (1)

14-14: LGTM! Documentation example updated correctly.

The addition of the total parameter to the example correctly demonstrates the new optional parameter introduced in the Databases service API.

lib/services/teams.dart (2)

11-19: LGTM! Clean implementation of the total parameter.

The list method correctly adds the optional total parameter to both the method signature and API parameters, maintaining backward compatibility.

---

107-119: LGTM! Clean implementation of the total parameter.

The listMemberships method correctly adds the optional total parameter to both the method signature and API parameters, maintaining backward compatibility.

docs/examples/teams/list.md (1)

9-13: LGTM! Documentation correctly demonstrates the new total parameter.

The example clearly shows the optional total parameter usage in the teams.list() call, which aligns with the API enhancement for controlling row counting behavior.

lib/services/account.dart (2)

81-87: LGTM! The total parameter is correctly added to listIdentities.

The optional total parameter is properly typed as bool? and correctly propagated to the API parameters, consistent with similar changes across other services.

---

137-142: LGTM! The total parameter is correctly added to listLogs.

The implementation follows the same pattern as listIdentities and other list methods in the SDK.

README.md (1)

24-24: LGTM! Version bump to 20.3.0 is correct.

The installation example correctly reflects the new release version.

lib/appwrite.dart (1)

33-33: LGTM! The operator.dart part directive is correctly added.

The new part directive properly integrates the Operator API into the library surface, following the existing pattern used for other utilities like query.dart and permission.dart.

test/query_test.dart (1)

275-315: LGTM! Test expectations correctly updated for timestamp-based queries.

The tests now properly verify that:

• createdBefore/After/Between use the $createdAt attribute with lessThan/greaterThan/between methods
• updatedBefore/After/Between use the $updatedAt attribute with the same method mappings

This aligns with the implementation changes in lib/query.dart that replaced generic time predicates with explicit attribute-based queries.

test/operator_test.dart (1)

1-156: LGTM! Comprehensive test coverage for the Operator API.

The test suite thoroughly validates all Operator methods:

• Arithmetic operations (increment, decrement, multiply, divide, modulo, power) with and without bounds
• Array operations (append, prepend, insert, remove, unique, intersect, diff, filter)
• String operations (concat, replace)
• Boolean toggle
• Date operations (addDays, subDays, setNow)

Each test correctly verifies the JSON structure (method name and values array) produced by the Operator factory methods.

lib/query.dart (1)

108-126: LGTM! Timestamp query helpers now use explicit system attributes.

The refactored implementation:

• Uses explicit $createdAt and $updatedAt system attributes instead of null attributes
• Delegates to generic comparison methods (lessThan, greaterThan, between)
• Provides clearer, more maintainable code
• Maintains the same public API surface

This change makes the query construction more explicit and aligns with Appwrite's internal timestamp field naming.

lib/operator.dart (4)

1-43: LGTM! Well-structured foundation for the Operator API.

The Condition enum and Operator class provide a clean, type-safe foundation for building atomic operation expressions:

• Enum values are properly defined with string representations
• Private constructor prevents direct instantiation
• toJson() correctly handles both single values and lists
• Consistent with the existing Query class pattern

---

44-131: LGTM! Robust input validation for arithmetic operations.

The arithmetic operations (increment, decrement, multiply, divide, modulo, power) include comprehensive validation:

• NaN and Infinity checks prevent invalid numeric inputs
• Zero divisor checks prevent runtime errors
• Optional max/min bounds provide flexibility
• Error messages are clear and actionable

---

133-164: LGTM! Comprehensive array operation support.

The array operations cover all common use cases (append, prepend, insert, remove, unique, intersect, diff, filter) with a clean API. The integration with the Condition enum for filtering is well-designed.

---

166-186: LGTM! String, boolean, and date operations are well-implemented.

The remaining operations provide useful utilities:

• String operations for concatenation and replacement
• Boolean toggle for flipping values
• Date operations for temporal adjustments

All methods follow the consistent pattern established by the class.